6.3 KiB
6.3 KiB
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
- Selection summary line (visible/selected counts).
- Unified table toolbar (single module container).
- Data table body.
- 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:
SelectionActionsImport/ExportTask ActionsMisc
Button Model
- Buttons are icon-first inside toolbar groups.
- Each button must expose deterministic semantics via
titleandaria-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 squareselect filtered-> filter + plusclear visible-> square + minusclear filtered-> filter + closeclear selection-> clear selection icon (distinct from remove/cancel/archive)run-> play/executeedit-> pencilremove-> remove/delete rowcancel-> cancel task (distinct from remove/archive)archive-> archive box/trayimport-> arrow into containerexport-> arrow out of containerexport filtered-> export + filter markerexport selected-> export + checkbox markerretry/sync-> circular refresh (two arrows along path)review-> info/review markerconfirm-> confirm/check markerinspect-> inspect/zoom marker
Table Columns
- Left
selectcolumn:- no text header label,
- minimal fixed width,
- centered checkbox control.
- Right
actionscolumn:- no text header label,
- minimal width,
- right-aligned action icons.
- Row action icons in
actionscolumn 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-selectionplacement 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 14pxcell padding and middle alignment; subordinate rows may use1pxvertical padding and18pxline 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: 0to 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 substituteoverflow-x: clipfor access to wide columns. - Sorting uses one shared state cycle: ascending, descending, original order. Show the
direction and expose
aria-sorton 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 includestotal_count,page,per_page,total_pages(shape per thego-apicontract). pageis 1-based;per_pagedefaults 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_pageresets to page 1.
Reuse Rule
If a pattern needs table selection + bulk actions, it must:
- Reuse this module unchanged by default.
- Document only additive overrides in the pattern-specific contract.
- Avoid redefining shared geometry/icon semantics locally.