PriceForge/bible-local/kit/patterns/table-management/contract.md

Contract: Table Management (Shared)

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.

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.