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