Split shared UI knowledge into atomic topic directories
This commit is contained in:
1 parent
08ff987edb
commit
b0e6402d66
37 files changed
+600
-516
No files matched your search
@@ -9,131 +9,6 @@ All patterns that expose table selection + bulk actions must inherit this contra
|
||||
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:
|
||||
@@ -141,3 +16,14 @@ 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.
|
||||
|
||||
## Topic Contracts
|
||||
|
||||
Geometry and icon semantics are the shared base. Read the other topics when that behavior is present.
|
||||
|
||||
- [Table Geometry](geometry/contract.md)
|
||||
- [Table Action Icons](icons/contract.md)
|
||||
- [Table Filtering](filtering/contract.md)
|
||||
- [Dense and Hierarchical Tables](density/contract.md)
|
||||
- [Change History Tables](history/contract.md)
|
||||
- [Table Pagination](pagination/contract.md)
|
||||
Reference in new issue
Block a user