Files
bible/rules/patterns/table-management/contract.md
T

144 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Contract: Table Management (Shared)
Version: 1.2
## Scope
Defines one canonical, reusable interaction model for table-driven operator/admin screens.
All patterns that expose table selection + bulk actions must inherit this contract.
Visual styling is inherited from the `web-visual-baseline` contract.
This contract remains theme-agnostic and defines geometry/semantics only.
## Canonical Regions
1. Selection summary line (visible/selected counts).
2. Unified table toolbar (single module container).
3. Data table body.
4. Pagination.
Toolbar and table must read as one continuous module:
- toolbar directly above table,
- no double borders/rounded-corner seams at the join,
- table horizontal overflow remains enabled when needed.
## Toolbar Geometry
- One outer toolbar container for all groups.
- Groups are separated with vertical separators.
- Group title + icon buttons are inline and compact.
- Group order is fixed:
1. `Selection`
2. `Actions`
3. `Import/Export`
4. `Task Actions`
5. `Misc`
## Button Model
- Buttons are icon-first inside toolbar groups.
- Each button must expose deterministic semantics via `title` and `aria-label`.
- Keep primary and destructive variants explicit via style tokens, not by icon ambiguity alone.
## Icon Semantics (One Action = One Icon)
Do not reuse the same icon for semantically different actions in this module.
Canonical mapping:
- `select visible` -> checked square
- `select filtered` -> filter + plus
- `clear visible` -> square + minus
- `clear filtered` -> filter + close
- `clear selection` -> clear selection icon (distinct from remove/cancel/archive)
- `run` -> play/execute
- `edit` -> pencil
- `remove` -> remove/delete row
- `cancel` -> cancel task (distinct from remove/archive)
- `archive` -> archive box/tray
- `import` -> arrow into container
- `export` -> arrow out of container
- `export filtered` -> export + filter marker
- `export selected` -> export + checkbox marker
- `retry/sync` -> circular refresh (two arrows along path)
- `review` -> info/review marker
- `confirm` -> confirm/check marker
- `inspect` -> inspect/zoom marker
## Table Columns
- Left `select` column:
- no text header label,
- minimal fixed width,
- centered checkbox control.
- Right `actions` column:
- no text header label,
- minimal width,
- right-aligned action icons.
- Row action icons in `actions` column are intentionally smaller than toolbar icons.
## Filtering Rules
- Filters live above the table, in a dedicated filter bar or inline in the toolbar.
- Every active filter must be visually indicated (highlighted field, chip, or badge count).
- Applying a filter always resets pagination to page 1.
- Filter state must be reflected in the URL as query parameters so the page is bookmarkable/shareable.
- "Reset filters" clears all filter fields and reloads with no filter params.
- Server-side filtering only — do not filter an already-loaded JS array client-side unless the full
dataset is guaranteed small (< 500 rows) and never grows.
- Filter inputs debounce text input (300–500 ms) before triggering a server request.
- A shared collapsible filter panel may show the active-filter count and result count while
closed. Mark active fields inside it; collapsing it does not clear filters. Own URL state,
debounce and reset behavior in one shared module, with page-specific field declarations.
- Filter popups follow `controls-selection` placement rules, including in Gantt views;
raising z-index alone does not solve ancestor clipping or viewport overflow.
## Dense and Hierarchical Tables
- An operator-table density override may use `3px 14px` cell padding and middle alignment;
subordinate rows may use `1px` vertical padding and `18px` line height. Scope the override
to dense tables rather than changing key-value detail tables.
- Keep parents visually stronger than children. Indent children and align their columns;
omit redundant repeated parent fields. Expand only when there is meaningful detail.
- Expansion and editing are different actions. Use a keyboard-operable expand button with
`aria-expanded`; clicking a row action must not also toggle expansion.
- Sticky headers may use `border-collapse: separate; border-spacing: 0` to avoid collapsed
border rendering artifacts. Choose the scrolling owner explicitly. For a bounded table,
stick headers inside its scroll container and preserve horizontal scrolling.
Do not substitute `overflow-x: clip` for access to wide columns.
- Sorting uses one shared state cycle: ascending, descending, original order. Show the
direction and expose `aria-sort` on the header; use a button for keyboard activation.
Keep child groups attached to their parents. With server pagination, sort the query on
the server rather than just the loaded page.
## Change History Tables
- Use a dense event row with timestamp, actor, object and action, and expand multi-field
changes into labeled Before/After columns. Show a single meaningful change inline.
- A creation has an after value; a deletion has a before value. Do not render a misleading
empty-to-value arrow when there is no comparison.
- Combine a line item's name and quantity when they describe one change. Exclude technical
bookkeeping from the presentation, without deleting it from the underlying audit record.
- Event timestamps retain date/time precision. Formatting business dates as weeks must not
erase exact-date changes from the source audit data.
## Pagination Rules
- Pagination is server-side. Never load all rows and paginate client-side.
- Query parameters carry page state (`?page=2&per_page=50`); the response includes
`total_count`, `page`, `per_page`, `total_pages` (shape per the `go-api` contract).
- `page` is 1-based; `per_page` defaults to a fixed project constant (e.g. 50) and may be
changed from a fixed set (25 / 50 / 100).
- Display: "Showing 51–100 of 342" — always show the range and total.
- Prev/Next buttons are disabled (not hidden) at the boundary pages.
- Direct page-number input is optional; if present it clamps to `[1, total_pages]` on blur.
- Changing `per_page` resets to page 1.
## Reuse Rule
If a pattern needs table selection + bulk actions, it must:
1. Reuse this module unchanged by default.
2. Document only additive overrides in the pattern-specific contract.
3. Avoid redefining shared geometry/icon semantics locally.