From 3a4a1c7f39313472f51935957c74db8c7368f2c4 Mon Sep 17 00:00:00 2001 From: ZDDC Date: Sat, 9 May 2026 11:09:31 -0500 Subject: [PATCH] feat(mdl): default columns mirror tracking-number components + customizable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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//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[]. 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) --- AGENTS.md | 2 + tables/template.html | 86 +++++++++++++++---- zddc/internal/handler/default-mdl.form.yaml | 80 ++++++++++++++---- zddc/internal/handler/default-mdl.table.yaml | 71 ++++++++++++---- zddc/internal/handler/tables.html | 88 ++++++++++++++++---- 5 files changed, 268 insertions(+), 59 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bd37ccc..639aa5e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -376,6 +376,8 @@ Read/aggregate counterpart to the form system. Renders a directory of YAML row f **Default-MDL fallback at `archive//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//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//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 `/` and drop `table.yaml` (and optionally `form.yaml` for row editing) into it. No code change required. Visit `/table.html`. ## Implementation-vs-dependency policy diff --git a/tables/template.html b/tables/template.html index 4904b2f..6a40043 100644 --- a/tables/template.html +++ b/tables/template.html @@ -73,27 +73,85 @@

What is this table?

-

Each row in this table is one YAML file in the source directory. - Tables are declared in .zddc via a - tables: map. The columns and row schema come from - a *.table.yaml spec file.

+

The directory you opened — say archive/Acme/mdl/ — + is the table. table.yaml describes the + columns; form.yaml describes the row-edit form + schema; every other .yaml file in the directory + is one row. Copying the directory anywhere takes the whole + table (spec + form + every row) with it.

+ +

Editing cells

+

Click a cell to select it. Then:

+
+
↑ / ↓ / ← / →
+
Move selection. Hold Shift to extend a range.
+
Tab / Shift+Tab
+
Move right / left, wrap to next / previous row.
+
Enter / F2 / double-click / typing
+
Enter edit mode. Typing replaces the cell value; the + others keep it.
+
Enter in edit mode
+
Commit and move down.
+
Tab in edit mode
+
Commit and move right.
+
Esc
+
Cancel the edit; restore the prior value.
+
Delete / Backspace
+
Clear every cell in the current selection.
+
Ctrl+D / Ctrl+R
+
Fill the top row down / left column right through the + selected range.
+
Ctrl+C / Ctrl+V
+
Copy / paste — interoperates with Excel and Google + Sheets via tab-separated values.
+
Ctrl+Z
+
Undo the last edit (one history per session).
+
+

Edits save automatically when you move to a different row. + A small left-edge swatch on the row indicates state: + blue = unsaved, amber = the + server flagged a validation error, orange = + someone else changed this row since you loaded it (you'll + get a prompt with Use mine / Reload).

Sorting

Click a column header to sort by that column. Click again to - toggle direction. Shift-click another header to add a secondary - sort key.

+ toggle direction. Shift-click another header to + add a secondary sort key.

Filtering

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.

+ value contains your text (case-insensitive). Same filter UI + for every column.

-

Editing a row

-

Click a row to open its YAML in the form editor. Whether the - row is editable depends on the cascading .zddc - permissions for the row's path. Rows in Issued or - Received archives are read-only by design (WORM).

+

Customizing the columns

+

The default Master Deliverables List has columns for every + component of a tracking number + (originator, phase, + project, area, + discipline, type, + sequence, suffix) plus deliverable + metadata. To customize, drop your own + table.yaml (and matching + form.yaml) into this directory:

+ 
archive/<party>/mdl/
+  table.yaml          ← columns + sort/filter defaults
+  form.yaml           ← per-row schema (JSON Schema)
+  <id>.yaml ...     ← rows
+

Operator-supplied files override the embedded defaults. + Hide a column by omitting it from columns:; + add a column by appending one (and adding the matching + property in form.yaml's + schema.properties). The same pattern works + for any directory — <dir>/table.html + is automatically a table whenever + <dir>/table.yaml exists.

+ +

Permissions

+

Whether a row is editable depends on the cascading + .zddc permissions for the directory. Rows + in Issued or Received archives + are read-only by design (WORM).

Header buttons

diff --git a/zddc/internal/handler/default-mdl.form.yaml b/zddc/internal/handler/default-mdl.form.yaml index 4bd855e..9d8bcd2 100644 --- a/zddc/internal/handler/default-mdl.form.yaml +++ b/zddc/internal/handler/default-mdl.form.yaml @@ -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//. 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//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//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 diff --git a/zddc/internal/handler/default-mdl.table.yaml b/zddc/internal/handler/default-mdl.table.yaml index 2bbec18..e039d60 100644 --- a/zddc/internal/handler/default-mdl.table.yaml +++ b/zddc/internal/handler/default-mdl.table.yaml @@ -1,40 +1,83 @@ # Default Master Deliverables List spec, served by zddc-server when no -# operator-supplied mdl.table.yaml exists at archive//. Operators -# can override per-party by writing their own file at -# archive//mdl.table.yaml plus a tables: { mdl: ./mdl.table.yaml } -# entry in the party's .zddc. +# operator-supplied table.yaml exists at archive//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//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[] = "". +# +# 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: diff --git a/zddc/internal/handler/tables.html b/zddc/internal/handler/tables.html index d66c3fb..8ce2a82 100644 --- a/zddc/internal/handler/tables.html +++ b/zddc/internal/handler/tables.html @@ -939,7 +939,7 @@ body.help-open .app-header {
ZDDC Table - v0.0.17-alpha · 2026-05-09 15:38:03 · 8e703dc-dirty + v0.0.17-alpha · 2026-05-09 16:07:14 · d3cd662-dirty
@@ -990,27 +990,85 @@ body.help-open .app-header {

What is this table?

-

Each row in this table is one YAML file in the source directory. - Tables are declared in .zddc via a - tables: map. The columns and row schema come from - a *.table.yaml spec file.

+

The directory you opened — say archive/Acme/mdl/ — + is the table. table.yaml describes the + columns; form.yaml describes the row-edit form + schema; every other .yaml file in the directory + is one row. Copying the directory anywhere takes the whole + table (spec + form + every row) with it.

+ +

Editing cells

+

Click a cell to select it. Then:

+
+
↑ / ↓ / ← / →
+
Move selection. Hold Shift to extend a range.
+
Tab / Shift+Tab
+
Move right / left, wrap to next / previous row.
+
Enter / F2 / double-click / typing
+
Enter edit mode. Typing replaces the cell value; the + others keep it.
+
Enter in edit mode
+
Commit and move down.
+
Tab in edit mode
+
Commit and move right.
+
Esc
+
Cancel the edit; restore the prior value.
+
Delete / Backspace
+
Clear every cell in the current selection.
+
Ctrl+D / Ctrl+R
+
Fill the top row down / left column right through the + selected range.
+
Ctrl+C / Ctrl+V
+
Copy / paste — interoperates with Excel and Google + Sheets via tab-separated values.
+
Ctrl+Z
+
Undo the last edit (one history per session).
+
+

Edits save automatically when you move to a different row. + A small left-edge swatch on the row indicates state: + blue = unsaved, amber = the + server flagged a validation error, orange = + someone else changed this row since you loaded it (you'll + get a prompt with Use mine / Reload).

Sorting

Click a column header to sort by that column. Click again to - toggle direction. Shift-click another header to add a secondary - sort key.

+ toggle direction. Shift-click another header to + add a secondary sort key.

Filtering

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.

+ value contains your text (case-insensitive). Same filter UI + for every column.

-

Editing a row

-

Click a row to open its YAML in the form editor. Whether the - row is editable depends on the cascading .zddc - permissions for the row's path. Rows in Issued or - Received archives are read-only by design (WORM).

+

Customizing the columns

+

The default Master Deliverables List has columns for every + component of a tracking number + (originator, phase, + project, area, + discipline, type, + sequence, suffix) plus deliverable + metadata. To customize, drop your own + table.yaml (and matching + form.yaml) into this directory:

+ 
archive/<party>/mdl/
+  table.yaml          ← columns + sort/filter defaults
+  form.yaml           ← per-row schema (JSON Schema)
+  <id>.yaml ...     ← rows
+

Operator-supplied files override the embedded defaults. + Hide a column by omitting it from columns:; + add a column by appending one (and adding the matching + property in form.yaml's + schema.properties). The same pattern works + for any directory — <dir>/table.html + is automatically a table whenever + <dir>/table.yaml exists.

+ +

Permissions

+

Whether a row is editable depends on the cascading + .zddc permissions for the directory. Rows + in Issued or Received archives + are read-only by design (WORM).

Header buttons