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

Contract: Table Management (Shared)

Version: 1.0

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 active repository baseline (currently Vapor Soft / Vapor Night in demo/scaffold). 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.

Pagination Rules

• Pagination is server-side. Never load all rows and paginate client-side.
• URL query parameters carry page state: ?page=2&per_page=50.
  • page is 1-based.
  • per_page defaults to a fixed project constant (e.g. 50); user may change it from a fixed set (25 / 50 / 100).
• The server response includes: total_count, page, per_page, total_pages.
• 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.