94 lines
5 KiB
Markdown
94 lines
5 KiB
Markdown
# ZDDC Tables
|
|
|
|
[← Back to ZDDC](../README.md)
|
|
|
|
Render a directory of YAML files as a sortable, filterable table — read-only, with click-row → edit-in-form integration. Backed by `zddc-server`'s form handler so the table view and the form editor are two sides of the same data.
|
|
|
|
**Anchor use case.** A Master Deliverables List (MDL) under `Archive/<Party>/MDL/`, where each `.yaml` file is one expected deliverable. Multiple parties keep their own MDLs side by side; the table aggregates within a single party's directory.
|
|
|
|
## How it works
|
|
|
|
- **Storage** is file-per-row YAML — one `*.yaml` file in a directory per table row. Concurrent edits don't collide on a shared blob, every row has independent git history, and per-row ACL inherits from the cascading `.zddc` chain.
|
|
- **Discovery** is `.zddc`-declarative. Drop a `tables:` entry in the directory's `.zddc` to register the table; no file-presence auto-mount, no phantom tables from rogue YAML drops.
|
|
- **Rendering** is server-side: `zddc-server` reads every `*.yaml` under the rows directory, normalizes them into a JSON list, and inlines the list into the page on render. The browser does sorting, filtering, and click-row navigation locally — no further server round-trips for those.
|
|
- **Editing** is delegated to the existing form tool. Each row's click target is the form's re-edit URL (`<dir>/<name>/<basename>.yaml.html`), which `zddc-server` already serves via the form handler. The table itself never writes.
|
|
|
|
## Setup (for an MDL at `Archive/Acme/MDL/`)
|
|
|
|
```
|
|
Archive/Acme/
|
|
├── .zddc # declares: tables: { MDL: ./MDL.table.yaml }
|
|
├── MDL.table.yaml # column spec + rows path + row schema reference
|
|
├── MDL.form.yaml # JSON Schema for one row (used by both the table and the form editor)
|
|
└── MDL/
|
|
├── D-001.yaml # one row
|
|
├── D-002.yaml # one row
|
|
└── ...
|
|
```
|
|
|
|
Visit `Archive/Acme/MDL.table.html` and the table renders. Visit `Archive/Acme/MDL.form.html` to add a new row (the form handler creates a YAML in `MDL/`).
|
|
|
|
### `.zddc` declaration
|
|
|
|
```yaml
|
|
tables:
|
|
MDL: ./MDL.table.yaml
|
|
```
|
|
|
|
The map key (`MDL`) becomes the URL stem and must match both the rows directory name and the form spec name. v1 enforces this with a load-time spec-validation error.
|
|
|
|
### Table spec (`MDL.table.yaml`)
|
|
|
|
```yaml
|
|
title: Master Deliverables List
|
|
description: Optional description shown above the table.
|
|
rowSchema: ./MDL.form.yaml # path to the row's JSON Schema (form-spec format)
|
|
rows: ./MDL # directory of *.yaml row files (non-recursive in v1)
|
|
columns:
|
|
- field: id # top-level key OR JSON Pointer (e.g. /nested/path)
|
|
title: ID
|
|
width: 7em
|
|
sort: asc # default sort key (overridden by defaults.sort below)
|
|
- field: title
|
|
title: Deliverable
|
|
- field: dueDate
|
|
title: Due
|
|
format: date # date | datetime | number | bool
|
|
- field: status
|
|
title: Status
|
|
enum: [pending, submitted, accepted, rejected] # constrains values + enables enum filter
|
|
defaults:
|
|
sort:
|
|
- { field: dueDate, dir: asc }
|
|
filter:
|
|
status: [pending, submitted] # initial filter state; clear with the toolbar button
|
|
```
|
|
|
|
Columns are explicit — the renderer does not auto-derive from the row schema. Pick the subset you want to display.
|
|
|
|
## ACL behavior
|
|
|
|
- The page-level read check uses the cascade at the spec directory; a caller without `r` gets a 403.
|
|
- Per-row "edit" affordance is recomputed against the row's own parent dir. If the user has `w` there, the row is clickable; otherwise it's plain text. Hard enforcement remains on the form-handler side (the form's POST will refuse a write the cascade denies).
|
|
- `Issued`/`Received` archive folders are server-enforced WORM. The decider strips `w/d/a` from non-admin grants under those subtrees, so an MDL placed inside `Issued/` shows every row as read-only with no special-casing in the table tool.
|
|
|
|
## v1 limits
|
|
|
|
- Read-only grid; click-row opens the form editor. Inline cell editing is a v2 candidate (would PUT each edit through the new file API in `zddc/internal/handler/fileapi.go`).
|
|
- One directory of `*.yaml` per table; cross-directory aggregation (`Archive/*/MDL/*.yaml` as one combined view) is not yet supported.
|
|
- No virtualization — large tables (>1000 rows) will be slow.
|
|
- No multi-row bulk operations, no add-row UI inside the table (use the form editor at `<name>.form.html`).
|
|
- `.zddc tables:` declarations are direct-lookup only; no upward cascade. Each directory hosting a table needs its own declaration.
|
|
|
|
## Build & develop
|
|
|
|
```bash
|
|
sh tables/build.sh # build (writes tables/dist/tables.html)
|
|
sh tables/build.sh --release alpha # cut alpha
|
|
sh ./build # full lockstep build (all tools + zddc-server)
|
|
|
|
(cd zddc && go test ./internal/handler/... ./internal/zddc/...)
|
|
npx playwright test --project=tables
|
|
```
|
|
|
|
Authoritative architecture and build docs are in [`../AGENTS.md`](../AGENTS.md) and [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
|