Rename kit/ to rules/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

rules/patterns/table-management/contract.md

@@ -0,0 +1,108 @@
+# 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.
+
+## 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.