# Contract: Controls + Selection

Version: 1.0

## Shared Base

- This pattern inherits the shared `table-management` contract:
  `kit/patterns/table-management/contract.md`.
- Reuse shared toolbar/table/icon geometry from the base contract first, then define only
  controls-specific additions below.

## Buttons

- Use a small stable button taxonomy: `primary`, `secondary`, `ghost`, `danger`, `disabled`.
- The canonical visual baseline for demo/scaffold examples is the active dual baseline used in the
  demo/scaffold (`Vapor Soft` / `Vapor Night`, system-selected). A frozen Aqua snapshot bundle may
  be kept for archival reference, but examples should follow the active baseline.
- Destructive actions (`archive`, `delete`, `remove`) must use danger styling and explicit labels.
- Button text should describe the action outcome, not implementation detail.
- Buttons are text-first; icons are optional and must not replace labels on primary/danger actions.
- Base examples must show both `disabled` and `loading` states.

## Checkbox Selection

- Row checkboxes support bulk actions from a shared action bar.
- Header checkbox semantics must be explicit:
  - select visible rows only, or
  - select all rows in query scope (must be clearly labeled)
- Selection summary must show count (`N selected`) near bulk actions.
- In paginated views, the UI should distinguish selection on the current page from selection across the filtered/query scope.
- Selection state should survive pagination/filter navigation via explicit state (query params, server session, or another deterministic mechanism).
- Same-page interactions should preserve reading position (module anchor pattern is preferred in canonical server-rendered flows).

## Segmented Filters

- Segment/toggle filters are allowed for small enumerations (status, active/archived).
- Segmented controls are grouped joined-buttons:
  - one shared outer shell,
  - rounded corners only on the first/last segment,
  - straight internal separators between middle segments.
- Active segment color may vary by context (for example blue preset selector vs dark status scope tabs), but geometry must remain consistent.
- Segment changes should preserve other active filters where possible.

## Bulk Action Safety

- Bulk action click should preview count and target scope before execution.
- Destructive bulk actions require confirmation.
- Dense bulk action bars may move rare actions into an explicit overflow menu (`More actions`) while keeping primary actions visible.