feat(mdl): default columns mirror tracking-number components + customizable

Per the reference doc at zddc.varasys.io/reference.html#tracking-numbers,
a tracking number is composed of: originator, [phase], project,
[area], discipline, type, sequence, [suffix]. The default Master
Deliverables List now surfaces every component as its own column,
plus the standard MDL metadata (title, plannedRevision,
plannedDate, status, owner). Columns appear in the canonical
filename order so the table reads left-to-right like the tracking
number itself.

Optional components ([phase], [area], [suffix]) render in the
table even when blank — keeps the layout consistent across rows.
Projects on a schema that doesn't use them hide the columns by
overriding (see customization).

Form schema (default-mdl.form.yaml):

- One JSON Schema property per tracking-number component, plus
  the deliverable metadata. originator / project / discipline /
  type / sequence are required; phase / area / suffix are
  optional. The schema is intentionally permissive — free-text
  strings on every component, no enums or regex constraints.
  Projects pick their own conventions for originator codes,
  discipline vocabularies, etc.; a default that imposed a
  fixed set would just get in the way.

- Phase 2's editable-cell widget factory derives the right
  per-cell editor from this schema: text inputs for the
  components, the existing select for `status` (which keeps
  its enum), date input for `plannedDate`, textarea for
  `notes`.

Customization (the "way for end users to customize"):

- Drop your own table.yaml and / or form.yaml into the rows
  directory (archive/<party>/mdl/, or any directory hosting a
  table). Operator-supplied files override the embedded defaults
  ATOMICALLY — there's no field-level merge, the operator file
  wins entirely. This matches every other "spec on disk wins"
  convention in zddc-server.

- Hide a column: omit it from the columns: list.
- Rename a column header: change `title:`.
- Add a column: append a {field, title} entry AND add a
  matching property in form.yaml's schema.properties.
- Tighten constraints: use `enum:`, `pattern:`, `minLength:`
  etc. on form.yaml properties.
- Pre-filter rows on load: defaults.filter[<field>].

The whole rows-directory is self-contained — copying mdl/ to a
new project takes the spec, the form, and every row YAML
together.

Documentation:

- AGENTS.md "Tables system" gains a paragraph on the default-MDL
  column set + the customization mechanism + a pointer to the
  embedded source files.

- tables/template.html help panel rewrites the body to cover:
    * What the directory IS (spec + form + row YAMLs together).
    * Editable-cell keyboard shortcuts (the Phase 1-5 sequence
      we just shipped — arrows, Tab, Enter, F2, Delete, Ctrl+D /
      R / C / V / Z, Shift+arrow / Shift+click for ranges).
    * The auto-save model + per-row state swatch colors.
    * The customization model with a worked file-tree example.
  Replaces the obsolete pre-Phase-1 wording that referenced
  `*.table.yaml` parent files and click-to-navigate-row UX.

Tests: no schema test changes — the default YAMLs are loaded
through the same RecognizeTableRequest / RecognizeFormRequest
paths that already cover the fallback. Full Playwright + Go
suites green (44 + 13).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
ZDDC 2026-05-09 11:09:31 -05:00
parent d3cd662740
commit 3a4a1c7f39
5 changed files with 268 additions and 59 deletions

View file

@ -376,6 +376,8 @@ Read/aggregate counterpart to the form system. Renders a directory of YAML row f
**Default-MDL fallback at `archive/<party>/mdl/`**: when no `table.yaml` (or `form.yaml`) exists on disk in this exact location, the server serves embedded default bytes. The `mdl/` directory itself doesn't even need to exist — the URL renders the default MDL view fully virtually so a fresh archive surfaces the master document list without operator setup. Outside `archive/<party>/mdl/`, presence-based discovery is the rule.
**Default-MDL columns mirror the tracking-number components** documented at `zddc.varasys.io/reference.html#tracking-numbers`: `originator`, `phase`, `project`, `area`, `discipline`, `type`, `sequence`, `suffix` — each one a slot of the deliverable's permanent identifier — plus `title`, `plannedRevision`, `plannedDate`, `status`, `owner`. The form schema accepts free-text on every component (no enums or regex constraints) so projects pick their own conventions. Operators customize by dropping their own `table.yaml` + `form.yaml` into `archive/<party>/mdl/`; both files override the embedded defaults atomically (no merge — operator-supplied wins entirely). Source: `zddc/internal/handler/default-mdl.{table,form}.yaml`.
**Adding a new table**: create a directory `<dir>/` and drop `table.yaml` (and optionally `form.yaml` for row editing) into it. No code change required. Visit `<dir>/table.html`.
## Implementation-vs-dependency policy

View file

@ -73,27 +73,85 @@
</div>
<div class="help-panel__body">
<h3>What is this table?</h3>
<p>Each row in this table is one YAML file in the source directory.
Tables are declared in <code>.zddc</code> via a
<code>tables:</code> map. The columns and row schema come from
a <code>*.table.yaml</code> spec file.</p>
<p>The directory you opened — say <code>archive/Acme/mdl/</code>
<em>is</em> the table. <code>table.yaml</code> describes the
columns; <code>form.yaml</code> describes the row-edit form
schema; every other <code>.yaml</code> file in the directory
is one row. Copying the directory anywhere takes the whole
table (spec + form + every row) with it.</p>
<h3>Editing cells</h3>
<p>Click a cell to select it. Then:</p>
<dl>
<dt><kbd></kbd> / <kbd></kbd> / <kbd></kbd> / <kbd></kbd></dt>
<dd>Move selection. Hold <kbd>Shift</kbd> to extend a range.</dd>
<dt><kbd>Tab</kbd> / <kbd>Shift+Tab</kbd></dt>
<dd>Move right / left, wrap to next / previous row.</dd>
<dt><kbd>Enter</kbd> / <kbd>F2</kbd> / double-click / typing</dt>
<dd>Enter edit mode. Typing replaces the cell value; the
others keep it.</dd>
<dt><kbd>Enter</kbd> in edit mode</dt>
<dd>Commit and move down.</dd>
<dt><kbd>Tab</kbd> in edit mode</dt>
<dd>Commit and move right.</dd>
<dt><kbd>Esc</kbd></dt>
<dd>Cancel the edit; restore the prior value.</dd>
<dt><kbd>Delete</kbd> / <kbd>Backspace</kbd></dt>
<dd>Clear every cell in the current selection.</dd>
<dt><kbd>Ctrl+D</kbd> / <kbd>Ctrl+R</kbd></dt>
<dd>Fill the top row down / left column right through the
selected range.</dd>
<dt><kbd>Ctrl+C</kbd> / <kbd>Ctrl+V</kbd></dt>
<dd>Copy / paste — interoperates with Excel and Google
Sheets via tab-separated values.</dd>
<dt><kbd>Ctrl+Z</kbd></dt>
<dd>Undo the last edit (one history per session).</dd>
</dl>
<p>Edits save automatically when you move to a different row.
A small left-edge swatch on the row indicates state:
<strong>blue</strong> = unsaved, <strong>amber</strong> = the
server flagged a validation error, <strong>orange</strong> =
someone else changed this row since you loaded it (you'll
get a prompt with <em>Use mine</em> / <em>Reload</em>).</p>
<h3>Sorting</h3>
<p>Click a column header to sort by that column. Click again to
toggle direction. Shift-click another header to add a secondary
sort key.</p>
toggle direction. <kbd>Shift</kbd>-click another header to
add a secondary sort key.</p>
<h3>Filtering</h3>
<p>Type in the box under a column header to filter rows whose
value contains your text (case-insensitive). For columns with a
fixed enum, the box becomes a multi-select — leave it empty to
show every value.</p>
value contains your text (case-insensitive). Same filter UI
for every column.</p>
<h3>Editing a row</h3>
<p>Click a row to open its YAML in the form editor. Whether the
row is editable depends on the cascading <code>.zddc</code>
permissions for the row's path. Rows in <code>Issued</code> or
<code>Received</code> archives are read-only by design (WORM).</p>
<h3>Customizing the columns</h3>
<p>The default Master Deliverables List has columns for every
component of a tracking number
(<code>originator</code>, <code>phase</code>,
<code>project</code>, <code>area</code>,
<code>discipline</code>, <code>type</code>,
<code>sequence</code>, <code>suffix</code>) plus deliverable
metadata. To customize, drop your own
<code>table.yaml</code> (and matching
<code>form.yaml</code>) into this directory:</p>
<pre><code>archive/&lt;party&gt;/mdl/
table.yaml ← columns + sort/filter defaults
form.yaml ← per-row schema (JSON Schema)
&lt;id&gt;.yaml ... ← rows</code></pre>
<p>Operator-supplied files override the embedded defaults.
Hide a column by omitting it from <code>columns:</code>;
add a column by appending one (and adding the matching
property in <code>form.yaml</code>'s
<code>schema.properties</code>). The same pattern works
for any directory — <code>&lt;dir&gt;/table.html</code>
is automatically a table whenever
<code>&lt;dir&gt;/table.yaml</code> exists.</p>
<h3>Permissions</h3>
<p>Whether a row is editable depends on the cascading
<code>.zddc</code> permissions for the directory. Rows
in <code>Issued</code> or <code>Received</code> archives
are read-only by design (WORM).</p>
<h3>Header buttons</h3>
<dl>

View file

@ -1,32 +1,77 @@
# Default row schema for a Master Deliverables List entry. Served by
# zddc-server when no operator-supplied mdl.form.yaml exists at
# archive/<party>/. Operators can override per-party.
# Default row schema for a Master Deliverables List entry, served by
# zddc-server when no operator-supplied form.yaml exists at
# archive/<party>/mdl/.
#
# Properties cover every component of the ZDDC tracking-number model
# (zddc.varasys.io/reference.html#tracking-numbers) plus the standard
# MDL metadata (title, planned revision, planned date, status, owner,
# notes). The schema is intentionally permissive on the components
# (free-text strings, no regex / enum constraints) — projects choose
# their own conventions for originator codes, discipline vocabularies,
# etc., and a default that imposed a fixed set would just get in the
# way.
#
# To customize: drop your own form.yaml into archive/<party>/mdl/
# (the same directory as table.yaml). Tighten constraints with
# `enum:`, `pattern:`, `minLength:`, etc. Add fields and they'll
# appear in the row-edit form; add a matching column to table.yaml
# to surface the field in the table view too.
title: Deliverable
description: One planned or in-flight deliverable for this party.
description: One planned or in-flight deliverable. The first eight fields are components of this row's tracking number; the rest are deliverable metadata.
schema:
type: object
required: [tracking, title]
required: [originator, project, discipline, type, sequence, title]
additionalProperties: false
properties:
tracking:
# --- Tracking-number components (matches the reference doc's
# field definitions, in order). originator / project / discipline
# / type / sequence are the structural minimum; phase / area /
# suffix are optional and project-dependent.
originator:
type: string
title: Tracking number
description: ZDDC tracking identifier (e.g. proj-EM-SPC-0001).
title: Originator
description: Organizational unit responsible for this deliverable (e.g. ACME).
minLength: 1
phase:
type: string
title: Phase
description: Optional project phase code (e.g. ECI, EPC). Leave blank if your tracking-number schema doesn't use phases.
project:
type: string
title: Project
description: Project identifier, or your corporate placeholder (e.g. 000000) for non-project deliverables.
minLength: 1
area:
type: string
title: Area
description: Optional area / budget code (e.g. B02). Leave blank if unused.
discipline:
type: string
title: Discipline
description: Engineering or functional group code (EL, ME, CV, PM, ...).
minLength: 1
type:
type: string
title: Document type
description: Document category code within the discipline (SPC, DWG, RPT, ...).
minLength: 1
sequence:
type: string
title: Sequence
description: Zero-padded integer (0001, 0042, 2623). Stored as a string so leading zeros survive YAML.
minLength: 1
suffix:
type: string
title: Suffix
description: Optional structural-part suffix (-A for Appendix A, -01 for Sheet 1). Use only for parts of the SAME deliverable; separate documents get their own tracking number.
# --- Deliverable metadata.
title:
type: string
title: Deliverable title
minLength: 1
discipline:
type: string
title: Discipline
description: Engineering discipline code (EM, EL, MC, ST, ...).
type:
type: string
title: Document type
description: Code for document class (SPC, DWG, RPT, ...).
plannedRevision:
type: string
title: Planned revision
@ -46,3 +91,6 @@ schema:
notes:
type: string
title: Notes
ui:
notes:
ui:widget: textarea

View file

@ -1,40 +1,83 @@
# Default Master Deliverables List spec, served by zddc-server when no
# operator-supplied mdl.table.yaml exists at archive/<party>/. Operators
# can override per-party by writing their own file at
# archive/<party>/mdl.table.yaml plus a tables: { mdl: ./mdl.table.yaml }
# entry in the party's .zddc.
# operator-supplied table.yaml exists at archive/<party>/mdl/.
#
# Columns mirror the tracking-number component model documented at
# zddc.varasys.io/reference.html#tracking-numbers — every column from
# `originator` through `suffix` is one slot of a deliverable's
# permanent identifier. Optional components ([phase], [area], [suffix])
# render in the table even when blank so the layout stays consistent
# across rows; users on schemas that don't use them can hide the
# columns by overriding this spec (see customization note below).
#
# Beyond the tracking-number fields, the table tracks the deliverable's
# title, planned revision and date, current status, owner, and notes —
# the standard MDL columns operators expect for planning and status
# tracking.
#
# To customize: drop your own table.yaml + form.yaml into the same
# directory (archive/<party>/mdl/). The whole directory IS the table —
# spec, row-edit form, and rows are siblings. Override examples:
# - Hide a column: omit it from the columns: list here.
# - Rename a column header: change `title:`.
# - Add a custom column: append a {field, title} entry AND add a
# matching property in form.yaml's schema.properties so the row
# form lets users fill it in.
# - Tighten column widths: set `width:` (CSS length, e.g. "8em").
# - Pre-filter rows on load: defaults.filter[<field>] = "<text>".
#
# The whole directory is self-contained — copying mdl/ to a new
# project takes the spec, the form, and every row YAML with it.
title: Master Deliverables List
description: Planned and actual deliverables for this party.
rowSchema: ./mdl.form.yaml
rows: ./mdl
description: Planned and actual deliverables for this party. Columns mirror the tracking-number components plus standard MDL metadata.
columns:
- field: tracking
title: Tracking
width: 11em
sort: asc
- field: title
title: Deliverable
# --- Tracking-number components (in the order they appear in the
# canonical filename: originator-[phase-]project-[area-]discipline-
# type-sequence[-suffix]). Optional components are kept narrow so
# they don't clutter the layout when unused.
- field: originator
title: Originator
width: 8em
- field: phase
title: Phase
width: 5em
- field: project
title: Project
width: 8em
- field: area
title: Area
width: 5em
- field: discipline
title: Disc.
width: 5em
- field: type
title: Type
width: 6em
- field: sequence
title: Seq.
width: 5em
- field: suffix
title: Suffix
width: 5em
# --- Deliverable metadata.
- field: title
title: Deliverable
- field: plannedRevision
title: Rev.
width: 5em
- field: plannedDate
title: Planned
format: date
width: 8em
- field: status
title: Status
width: 6em
enum: [DFT, IFR, IFA, IFC, AFC, AB]
- field: owner
title: Owner
width: 12em
defaults:
sort:

View file

@ -939,7 +939,7 @@ body.help-open .app-header {
</svg>
<div class="header-title-group">
<span class="app-header__title" id="table-title">ZDDC Table</span>
<span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.17-alpha · 2026-05-09 15:38:03 · 8e703dc-dirty</span></span>
<span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.17-alpha · 2026-05-09 16:07:14 · d3cd662-dirty</span></span>
</div>
</div>
<div class="header-right">
@ -990,27 +990,85 @@ body.help-open .app-header {
</div>
<div class="help-panel__body">
<h3>What is this table?</h3>
<p>Each row in this table is one YAML file in the source directory.
Tables are declared in <code>.zddc</code> via a
<code>tables:</code> map. The columns and row schema come from
a <code>*.table.yaml</code> spec file.</p>
<p>The directory you opened — say <code>archive/Acme/mdl/</code>
<em>is</em> the table. <code>table.yaml</code> describes the
columns; <code>form.yaml</code> describes the row-edit form
schema; every other <code>.yaml</code> file in the directory
is one row. Copying the directory anywhere takes the whole
table (spec + form + every row) with it.</p>
<h3>Editing cells</h3>
<p>Click a cell to select it. Then:</p>
<dl>
<dt><kbd></kbd> / <kbd></kbd> / <kbd></kbd> / <kbd></kbd></dt>
<dd>Move selection. Hold <kbd>Shift</kbd> to extend a range.</dd>
<dt><kbd>Tab</kbd> / <kbd>Shift+Tab</kbd></dt>
<dd>Move right / left, wrap to next / previous row.</dd>
<dt><kbd>Enter</kbd> / <kbd>F2</kbd> / double-click / typing</dt>
<dd>Enter edit mode. Typing replaces the cell value; the
others keep it.</dd>
<dt><kbd>Enter</kbd> in edit mode</dt>
<dd>Commit and move down.</dd>
<dt><kbd>Tab</kbd> in edit mode</dt>
<dd>Commit and move right.</dd>
<dt><kbd>Esc</kbd></dt>
<dd>Cancel the edit; restore the prior value.</dd>
<dt><kbd>Delete</kbd> / <kbd>Backspace</kbd></dt>
<dd>Clear every cell in the current selection.</dd>
<dt><kbd>Ctrl+D</kbd> / <kbd>Ctrl+R</kbd></dt>
<dd>Fill the top row down / left column right through the
selected range.</dd>
<dt><kbd>Ctrl+C</kbd> / <kbd>Ctrl+V</kbd></dt>
<dd>Copy / paste — interoperates with Excel and Google
Sheets via tab-separated values.</dd>
<dt><kbd>Ctrl+Z</kbd></dt>
<dd>Undo the last edit (one history per session).</dd>
</dl>
<p>Edits save automatically when you move to a different row.
A small left-edge swatch on the row indicates state:
<strong>blue</strong> = unsaved, <strong>amber</strong> = the
server flagged a validation error, <strong>orange</strong> =
someone else changed this row since you loaded it (you'll
get a prompt with <em>Use mine</em> / <em>Reload</em>).</p>
<h3>Sorting</h3>
<p>Click a column header to sort by that column. Click again to
toggle direction. Shift-click another header to add a secondary
sort key.</p>
toggle direction. <kbd>Shift</kbd>-click another header to
add a secondary sort key.</p>
<h3>Filtering</h3>
<p>Type in the box under a column header to filter rows whose
value contains your text (case-insensitive). For columns with a
fixed enum, the box becomes a multi-select — leave it empty to
show every value.</p>
value contains your text (case-insensitive). Same filter UI
for every column.</p>
<h3>Editing a row</h3>
<p>Click a row to open its YAML in the form editor. Whether the
row is editable depends on the cascading <code>.zddc</code>
permissions for the row's path. Rows in <code>Issued</code> or
<code>Received</code> archives are read-only by design (WORM).</p>
<h3>Customizing the columns</h3>
<p>The default Master Deliverables List has columns for every
component of a tracking number
(<code>originator</code>, <code>phase</code>,
<code>project</code>, <code>area</code>,
<code>discipline</code>, <code>type</code>,
<code>sequence</code>, <code>suffix</code>) plus deliverable
metadata. To customize, drop your own
<code>table.yaml</code> (and matching
<code>form.yaml</code>) into this directory:</p>
<pre><code>archive/&lt;party&gt;/mdl/
table.yaml ← columns + sort/filter defaults
form.yaml ← per-row schema (JSON Schema)
&lt;id&gt;.yaml ... ← rows</code></pre>
<p>Operator-supplied files override the embedded defaults.
Hide a column by omitting it from <code>columns:</code>;
add a column by appending one (and adding the matching
property in <code>form.yaml</code>'s
<code>schema.properties</code>). The same pattern works
for any directory — <code>&lt;dir&gt;/table.html</code>
is automatically a table whenever
<code>&lt;dir&gt;/table.yaml</code> exists.</p>
<h3>Permissions</h3>
<p>Whether a row is editable depends on the cascading
<code>.zddc</code> permissions for the directory. Rows
in <code>Issued</code> or <code>Received</code> archives
are read-only by design (WORM).</p>
<h3>Header buttons</h3>
<dl>