# 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.