# 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 tokens and icon rendering are inherited from the global Aqua theme module:
`kit/patterns/theme-aqua-legacy`.

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