rcf-lite 0.20.0 → 0.22.0

package/blueprints/application-datatable/README.md

@@ -0,0 +1,43 @@
+# Datatable blueprint (v1.0.0)
+
+Vendor-neutral datatable contract for a rcf-lite application. Ships the ARIA APG table / grid pattern choice (per interactivity), the sort / filter / paginate discipline, the selection model with a bulk-action confirmation dialog, the four-state region contract (empty / loading / error / no-results), and a non-drag keyboard path for column visibility / reorder / resize. Ships a Playwright probe pack under `probe-packs/application-datatable.pack.mjs` whose six checks are the runtime gate the delivery-ci-workflows runner drives (visual round spec 2026-09-04). No new global topics; suggests the `logging` and `errorHandling` companions.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-datatable
+```
+
+Applies namespaced contributions into the project tree and records `manifest.blueprints[]`. Consumes the `logging` and `errorHandling` companions when they resolve to an applied provider or a registered library; falls back to the shelf providers otherwise.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `suggestedCompanions: [{ logging }, { errorHandling }]`, 22 contributions in the 17xx band |
+| Doc set | `contributions/` | 6 REQs, 9 USs (27 runtime-observable ACs), 3 TACs, 4 ADRs, schema-valid and namespaced |
+| Probe pack | `probe-packs/application-datatable.pack.mjs` | Six browser-verify checks anchored to AC-17101-1, AC-17102-1, AC-17103-2, AC-17104-3, AC-17105-1, AC-17106-1 |
+| Guide | `guide/application-datatable.md` | Operator-facing: when to reach, when not, mechanism-reach gaps |
+| Coordination vocabulary | `docs/topics.md` | Shelf id band registry update; no new global topics claimed |
+
+## What it contributes, and what it deliberately does not
+
+Contributed: REQ, US (with inline ACs), TAC, ADR, plus one shipped probe pack. Adherence is expressed as ACs; the blueprint ships no framework source and no test files (the probe pack drives the real browser against the applying project's own runtime).
+
+Deliberately not contributed: a choice of data-table library (TanStack Table, MUI DataGrid, AG Grid, or a hand-rolled `<table>`); a wire endpoint for the data source (the query adapter targets whatever the applied `application-api-rest` or GraphQL contract shapes); an authentication or authorisation contract for row-level visibility (the applied auth blueprint owns that decision); a caching or optimistic-update policy (client-state is the applied `application-spa` blueprint's ADR-203 territory).
+
+## The one runtime gate
+
+`probe-packs/application-datatable.pack.mjs` ships six checks the `rcf verify browser` runner invokes on any FBS whose surface matches the pack's `appliesTo` predicate (an FBS that binds `TAC-1801-application-datatable-shell` or whose nav model routes name a datatable path). Each check drives the real Playwright browser the runner provisions (through the pinned Playwright MCP or the consuming project's own `playwright` installation), reads the accessibility tree and the DOM, and returns a verdict. A failing block-severity check refuses ship through the existing `browserVerification` aggregate verdict.
+
+The pack fires ONLY when its `appliesTo` returns true; a project whose FBS does not bind the shell TAC or a datatable route sees the pack recorded as `applicable: false` and no browser check runs.
+
+## Quality bar
+
+Table or grid ARIA APG pattern per interactivity (ADR-1801); sortable columns keyboard-reachable with `aria-sort` announcing direction; text filter carrying `q` into the query adapter with per-column dropdowns composing deterministically; pagination controls with an `aria-live=\"polite\"` region reading `Page N of M`; selection model with per-row toggles and a page-level toggle; bulk actions opening a dialog under ARIA APG dialog-modal (`role=\"dialog\"`, `aria-modal=\"true\"`, `aria-labelledby`, `aria-describedby`, focus return to the originating row on close); four distinct states in `role=\"region\"` with `aria-live=\"polite\"`; non-colour distinction on every state (WCAG 1.4.1); URL-state serialisation of sort, filter and page as the recommended default (ADR-1802); default page size 25 elicitable at apply (ADR-1803); selection persistence elicited (ADR-1804); non-drag keyboard alternative for column visibility, reorder and resize (WCAG 2.5.7). Every bar is carried by ACs in the doc set and probed by the shipped pack.
+
+## Known mechanism-reach gaps
+
+- **Framework-agnostic focus containment.** The pack asserts focus return to the originating row on dialog close, but cannot prove a given framework's focus trap never leaks into the browser chrome; a project-side keyboard smoke supplement per applied framework closes the class.
+- **Chart-adjacent chart integration.** A datatable that renders a per-row sparkline (`application-charts` chart-style) is not covered by the datatable pack; the `application-charts` blueprint's own probe pack (visual round T-2) reaches those surfaces.
+- **Live-region debouncing on rapid filter typing.** Per-keystroke pagination announcements can flood assistive tech; the pack asserts the announcement fires, not the debounce. A v1.1 minor bump candidate adds a check for a bounded announcement rate.

package/blueprints/application-datatable/blueprint.json

@@ -0,0 +1,33 @@
+{
+  "slug": "application-datatable",
+  "version": "1.0.0",
+  "category": "application",
+  "suggestedCompanions": [
+    { "role": "logging", "reason": "Every server-side query pass writes a request-scoped log line; a logging companion supplies the factory the pipeline calls." },
+    { "role": "errorHandling", "reason": "A partial-load failure or a bulk-action refusal constructs an internal error record; an error-handling companion supplies the factory and the boundary." }
+  ],
+  "contributions": [
+    { "id": "application-datatable-REQ-001", "kind": "req", "path": "requirements/application-datatable-req-001.json" },
+    { "id": "application-datatable-REQ-002", "kind": "req", "path": "requirements/application-datatable-req-002.json" },
+    { "id": "application-datatable-REQ-003", "kind": "req", "path": "requirements/application-datatable-req-003.json" },
+    { "id": "application-datatable-REQ-004", "kind": "req", "path": "requirements/application-datatable-req-004.json" },
+    { "id": "application-datatable-REQ-005", "kind": "req", "path": "requirements/application-datatable-req-005.json" },
+    { "id": "application-datatable-REQ-006", "kind": "req", "path": "requirements/application-datatable-req-006.json" },
+    { "id": "application-datatable-US-17101", "kind": "us", "path": "user-stories/application-datatable-us-17101.json" },
+    { "id": "application-datatable-US-17102", "kind": "us", "path": "user-stories/application-datatable-us-17102.json" },
+    { "id": "application-datatable-US-17103", "kind": "us", "path": "user-stories/application-datatable-us-17103.json" },
+    { "id": "application-datatable-US-17104", "kind": "us", "path": "user-stories/application-datatable-us-17104.json" },
+    { "id": "application-datatable-US-17105", "kind": "us", "path": "user-stories/application-datatable-us-17105.json" },
+    { "id": "application-datatable-US-17106", "kind": "us", "path": "user-stories/application-datatable-us-17106.json" },
+    { "id": "application-datatable-US-17107", "kind": "us", "path": "user-stories/application-datatable-us-17107.json" },
+    { "id": "application-datatable-US-17108", "kind": "us", "path": "user-stories/application-datatable-us-17108.json" },
+    { "id": "application-datatable-US-17109", "kind": "us", "path": "user-stories/application-datatable-us-17109.json" },
+    { "id": "TAC-1801-application-datatable-shell", "kind": "tac", "path": "tacs/tac-1801-application-datatable-shell.json" },
+    { "id": "TAC-1802-application-datatable-query-adapter", "kind": "tac", "path": "tacs/tac-1802-application-datatable-query-adapter.json" },
+    { "id": "TAC-1803-application-datatable-selection-model", "kind": "tac", "path": "tacs/tac-1803-application-datatable-selection-model.json" },
+    { "id": "ADR-1801-application-datatable-pattern-choice", "kind": "adr", "path": "adrs/adr-1801-application-datatable-pattern-choice.json", "standardsTraceClause": "ARIA APG table pattern / ARIA APG grid pattern" },
+    { "id": "ADR-1802-application-datatable-url-state", "kind": "adr", "path": "adrs/adr-1802-application-datatable-url-state.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "generic enterprise practice" },
+    { "id": "ADR-1803-application-datatable-page-size", "kind": "adr", "path": "adrs/adr-1803-application-datatable-page-size.json", "recommendedDefault": true, "elicited": true, "standardsTraceClause": "generic enterprise practice" },
+    { "id": "ADR-1804-application-datatable-selection-persistence", "kind": "adr", "path": "adrs/adr-1804-application-datatable-selection-persistence.json", "recommendedDefault": false, "elicited": true, "standardsTraceClause": "generic enterprise practice" }
+  ]
+}

package/blueprints/application-datatable/contributions/adrs/adr-1801-application-datatable-pattern-choice.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1801-application-datatable-pattern-choice",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Choose ARIA APG table for read-only rows and ARIA APG grid once any cell becomes an interactive control",
+  "context": "The ARIA APG names two distinct patterns for tabular surfaces: `table` for a read-only presentation of tabular data, and `grid` for a two-dimensional widget where cells can hold interactive controls (buttons, links, editable fields). Assistive-tech behaviour differs between the two: a grid announces row and column position on focus, supports two-dimensional keyboard navigation, and expects `role=\"gridcell\"` on data cells; a table announces cell contents in reading order and does not expect grid navigation. Picking one pattern per the interactivity of the surface prevents the shipped datatable from advertising grid affordances the surface does not implement (a common defect).",
+  "decision": "The blueprint's shell picks the `table` pattern when the rows carry no interactive controls, and the `grid` pattern once any per-row control ships (sort activation on header, selection checkboxes, inline row actions). The decision is per-shell (a project can ship a read-only detail table and an interactive datatable in the same app); the choice is exposed on the shell factory input.",
+  "consequences": "Assistive tech reads the intended pattern; the sort control on a header always renders as an interactive control regardless of pattern; the grid pattern's two-dimensional keyboard navigation is only expected when the shell renders `role=\"grid\"`. A project that wants the grid pattern for a read-only surface (a stock listing with per-row cell focus) elects it explicitly on the shell factory input.",
+  "alternativesConsidered": [
+    {
+      "name": "Always render `role=\"grid\"`",
+      "summary": "The shell always renders the grid pattern, regardless of interactivity.",
+      "reasonNotChosen": "Read-only surfaces that render the grid pattern advertise two-dimensional keyboard navigation and cell focus their surface does not implement, so assistive-tech users hit dead ends."
+    },
+    {
+      "name": "Always render plain `<table>`",
+      "summary": "The shell never renders the grid pattern.",
+      "reasonNotChosen": "Interactive datatables reads worse on assistive tech than they should because the grid pattern's cell announcements are not fired."
+    }
+  ],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/adrs/adr-1802-application-datatable-url-state.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-1802-application-datatable-url-state",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Serialise sort, filter and page state into the URL by recommended default; elicited overrides for a session-scoped alternative",
+  "context": "Deep-linkable, reload-stable views are the tabular surface's expected posture in production. A datatable that resets sort, filter and page on reload forces operators to recreate their view every session and prevents them from sharing a specific view with a colleague. Some surfaces (an internal admin panel where a session-scoped view is preferable for auditability) elect the alternative.",
+  "decision": "The recommended default is to serialise `sort`, `q` and `page` into the URL query parameters as `sort=<column>:<asc|desc>`, `q=<string>`, `page=<int>`. The URL is written back on every state change via `history.replaceState` (no navigation entry per micro-change). The elicited alternative is a session-scoped state kept in memory; the operator elicits this at apply time and the shell suppresses URL writes.",
+  "consequences": "Reload rerenders the same view; a shared link reproduces the same view for another operator (subject to any RBAC filter on the underlying data). The client-side sort alternative (used on small in-memory collections) still writes the sort direction to the URL so reload stability is preserved. A project that elects the session-scoped alternative pays the reload-loss cost knowingly.",
+  "alternativesConsidered": [
+    {
+      "name": "Serialise state to sessionStorage",
+      "summary": "State reads and writes from sessionStorage; the URL stays clean.",
+      "reasonNotChosen": "Loses the shareability the URL contract provides; a shared link no longer reproduces the same view."
+    }
+  ],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/adrs/adr-1803-application-datatable-page-size.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-1803-application-datatable-page-size",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Default page size 25; elicited overrides on apply",
+  "context": "Page size shapes the pagination behaviour and the initial fetch cost. Too small a default forces excessive pagination; too large a default renders a slow first paint on a large dataset. The middle ground for most tabular surfaces (users, orders, records) sits between 20 and 50 rows; the shelf picks a stable default the guide names.",
+  "decision": "The default page size is 25 when the applying project does not elicit a value. The operator overrides at apply time (`--elicit pageSize=<int>` or the interactive equivalent); the elicited value replaces the default without changing the URL contract (a `pageSize` in the URL still overrides for one view).",
+  "consequences": "New projects render 25 rows on the first page without any operator decision. Projects with large rows (dense records) elicit a smaller value; projects with small rows (order summaries) elicit a larger one. The URL contract still permits an operator to view an ad-hoc page size for one session.",
+  "alternativesConsidered": [
+    {
+      "name": "No default; elicit on every apply",
+      "summary": "The blueprint refuses to apply without an elicited pageSize.",
+      "reasonNotChosen": "Adds friction on the common case; a working default costs nothing and every operator that cares overrides."
+    }
+  ],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/adrs/adr-1804-application-datatable-selection-persistence.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-1804-application-datatable-selection-persistence",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Selection persistence is elicited: per-page reset by default, cross-page persistence when the operator opts in",
+  "context": "Cross-page selection persistence is a powerful primitive for bulk operations across a large dataset; it also increases the surface area for confusing behaviour (an unexpected bulk operation on rows the operator forgot they selected two pages ago). The default preserves predictability; the operator opts into persistence when the surface's task shape warrants it.",
+  "decision": "Selection persistence is elicited at apply time. The default is `perPage`: selection resets on pagination advance and the shell surfaces this in the accessible copy near the bulk action controls. The elicited alternative is `crossPage`: selection persists across pagination for the shell mount's lifetime.",
+  "consequences": "Datatables on high-cardinality surfaces (records to be exported, notifications to be marked read across days) elicit `crossPage`. Datatables on transactional per-page workflows keep the default. The shell's accessible copy names the mode so operators are never surprised by the behaviour.",
+  "alternativesConsidered": [
+    {
+      "name": "Cross-page persistence as the recommended default",
+      "summary": "The blueprint recommends cross-page persistence for every applied surface.",
+      "reasonNotChosen": "Increases the surprise footprint on the common per-page workflow; a per-page default is safer to inherit and the elicited override is fast to change."
+    }
+  ],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/requirements/application-datatable-req-001.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-datatable-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The application ships a datatable shell with rows, columns, header cells and per-page navigation",
+  "description": "The application realises a datatable surface honouring the ARIA APG table pattern for read-only rows and the ARIA APG grid pattern once any cell becomes an interactive control (per ADR-1801). Header cells associate with column data through `<th scope=\"col\">` or an equivalent grid `role=\"columnheader\"` binding; per-page navigation renders a pagination control that fetches subsequent pages against the query adapter (TAC-1802). The shell is the base surface the other five REQs elaborate on.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "The shell decision closes two families of failure at once: the accessibility mode picked (table vs grid), and the pagination contract the query adapter feeds. Without this, projects reinvent both per surface and every downstream discipline (state contract, selection, sort) rides on ad-hoc assumptions.",
+  "tags": ["blueprint:application-datatable", "category:01-shell"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/requirements/application-datatable-req-002.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-datatable-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Sort activates the query adapter and renders in the announced direction",
+  "description": "Column headers advertise sortability via a keyboard-reachable sort control; activation flips direction (asc / desc), announces the new direction through `aria-sort`, and reorders rendered rows to match the server-side sort (TAC-1802) when the project chose the server-side default. The client-side sort alternative applies to small in-memory collections when the operator elicited it (ADR-1802's elicited alternative).",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Sort is the single-most-used interaction on a datatable and the most common source of hidden accessibility regressions. Anchoring the direction announcement and the keyboard reach at the surface level closes both.",
+  "tags": ["blueprint:application-datatable", "category:02-sort"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/requirements/application-datatable-req-003.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-datatable-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Filter chrome ships a text search and per-column dropdowns that read into the query adapter",
+  "description": "The chrome exposes a text search input (WCAG 2.4.6 labelled) that issues the query adapter's search request (`q=<value>` on the server-side default, or an equivalent in-memory filter under the elicited client-side alternative) and per-column dropdown filters where the column exposes a bounded value set. Filter changes reset the pagination cursor and rerender through the same path a sort change takes. Combined filter and sort compose deterministically at the query adapter (TAC-1802).",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Filter and sort share the same query surface. Naming them together stops projects from realising two divergent request shapes that then desync on the composition case.",
+  "tags": ["blueprint:application-datatable", "category:03-filter"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/requirements/application-datatable-req-004.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-datatable-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Selection and bulk actions carry a per-row, per-page and cross-page selection model with a confirmation dialog per bulk operation",
+  "description": "The selection model (TAC-1803) exposes per-row toggles, a page-level toggle that flips the visible page, and (elicited per ADR-1804) an optional cross-page persistence that stays across pagination. Every bulk operation opens a confirmation dialog under the ARIA APG dialog-modal pattern (`role=\"dialog\"`, `aria-modal=\"true\"`, `aria-labelledby`, `aria-describedby`, focus trap, focus return on close). The dialog returns focus to the control that opened it, per WCAG 2.4.3 and ARIA APG.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Bulk actions on a datatable are where destructive operations sit. The confirmation dialog's focus return is the single biggest keyboard-usability defect the surface produces if the project scaffolds one from scratch. Anchoring the dialog and the focus-return contract makes both testable at ship.",
+  "tags": ["blueprint:application-datatable", "category:04-selection"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/requirements/application-datatable-req-005.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-datatable-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Empty, loading, error and no-results states each render a distinct region with a status announcement",
+  "description": "Each of the four states renders inside its own `role=\"region\"` element carrying `aria-live=\"polite\"`, with a distinct visual and a status announcement per WCAG 4.1.3. No state relies on colour alone (WCAG 1.4.1). The no-results state is distinguished from empty by the presence of an active filter (`q`) that yielded no rows.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "State ambiguity is the second-biggest datatable defect after focus return: showing a spinner over the last-good rows (stale-content ambiguity), or an empty state that reads the same as no-results. Distinct regions plus polite live announcements close both classes.",
+  "tags": ["blueprint:application-datatable", "category:05-states"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/requirements/application-datatable-req-006.json

@@ -0,0 +1,15 @@
+{
+  "reqId": "application-datatable-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Column visibility, reorder and resize each expose a keyboard-reachable alternative to any drag pointer path",
+  "description": "Column visibility toggles are keyboard-reachable controls (checkboxes or menu items) that hide or show columns; column reorder exposes a non-drag path (paired move-left / move-right controls or a menu ordering); column resize exposes a keyboard-alternative to any pointer drag, per WCAG 2.5.7 Dragging Movements. A drag-only reorder or resize is refused at author-side review.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "WCAG 2.5.7 makes drag-only interactions non-conformant. Naming the keyboard alternative for each of the three column controls prevents the shipped surface from failing the standard at the last moment.",
+  "tags": ["blueprint:application-datatable", "category:06-columns"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/tacs/tac-1801-application-datatable-shell.json

@@ -0,0 +1,50 @@
+{
+  "tacId": "TAC-1801-application-datatable-shell",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Datatable shell",
+  "purpose": "Owns the rendered datatable surface: the ARIA APG pattern choice (table vs grid per interactivity, ADR-1801), the header cell binding, the pagination controls with the polite live status region, the four-state distinction (empty, loading, error, no-results), the sort control per column with the aria-sort attribute, the filter chrome, the selection column, the bulk action controls, and the non-drag column reorder / visibility / resize path. The shell is the substitutable interface every AC in this blueprint anchors on.",
+  "responsibilities": [
+    "Render the ARIA APG pattern matching the surface's interactivity (AC-17107-1, AC-17107-3): plain table for read-only rows, grid once cells become interactive controls (ADR-1801).",
+    "Expose a keyboard-reachable sort control per sortable column and update `aria-sort` on activation (AC-17101-1, AC-17101-2, AC-17101-3).",
+    "Expose a text filter input and per-column dropdown filters that read into the query adapter with `q` and column filter values (AC-17102-1, AC-17102-3) and reset pagination on change (AC-17102-2).",
+    "Render pagination controls with an `aria-live=\"polite\"` region reading `Page N of M` and updating on advance (AC-17103-2, AC-17103-3), and drive the query adapter with `page` and `pageSize` on next / previous (AC-17103-1).",
+    "Render each of the four states (empty, loading, error, no-results) inside its own `role=\"region\"` element with `aria-live=\"polite\"` and non-colour distinction (AC-17105-1, AC-17105-2, AC-17105-3).",
+    "Render a bulk-action confirmation dialog under ARIA APG dialog-modal with `role=\"dialog\"`, `aria-modal=\"true\"`, `aria-labelledby`, `aria-describedby`, initial focus on confirm and focus return to the originating row on close (AC-17104-2, AC-17104-3).",
+    "Expose non-drag keyboard paths for column reorder, column visibility and column resize (WCAG 2.5.7, AC-17106-1, AC-17106-2, AC-17106-3).",
+    "Preserve sort, filter and page state in the URL per ADR-1802 and honour the applied default page size per ADR-1803 (AC-17108-1, AC-17108-2, AC-17108-3)."
+  ],
+  "internalStructure": "One shell module that mounts the surface, plus small internal helpers per interaction family (sort binder, filter binder, pagination binder, selection binder, column reorder binder). Every family reads from the same state container and writes back through the query adapter (TAC-1802) or the selection model (TAC-1803). The framework is not prescribed; the shell interfaces are what the project realises against React, Vue, Svelte or vanilla DOM.",
+  "interfaces": [
+    {
+      "name": "renderShell",
+      "kind": "factory",
+      "description": "renderShell({ queryAdapter, selectionModel, columns, initialState }) -> { mount(rootElement), unmount() }. The project supplies the queryAdapter (TAC-1802) and the selectionModel (TAC-1803); the shell owns the DOM plumbing, the accessibility patterns, and the four-state render."
+    },
+    {
+      "name": "columnsSpec",
+      "kind": "shape",
+      "description": "Every column declares `{ key, headerLabel, sortable?, filterable?, filterKind?, visibilityToggleable?, reorderable?, resizable? }`; the shell reads the spec to decide which controls render per column."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Query adapter",
+      "kind": "tac",
+      "tacId": "TAC-1802-application-datatable-query-adapter",
+      "description": "The shell reads sort, filter and pagination through the adapter."
+    },
+    {
+      "name": "Selection model",
+      "kind": "tac",
+      "tacId": "TAC-1803-application-datatable-selection-model",
+      "description": "The shell reads and writes selection state through the model; bulk actions read the selected set."
+    }
+  ],
+  "tradeoffs": "The shell is framework-agnostic; a project that wants a specific framework's data-table component (MUI DataGrid, TanStack Table) supplies an implementation that satisfies the shell contract rather than replacing it. The four-state contract is opinionated; a project that ships only three (no distinct loading region) fails the AC and the probe pack refuses. The shell owns the accessibility patterns; a project that ships a custom-role table (`role=\"treegrid\"` for a hierarchical data set) supersedes the shell TAC in its own realisation and names the residual as a known gap.",
+  "notes": "Known mechanism-reach gap: the shell contract cannot prove keyboard focus does not escape the surface in every framework's rendering; project-side smoke tests supplement the pack. See README `Known mechanism-reach gaps`.",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/tacs/tac-1802-application-datatable-query-adapter.json

@@ -0,0 +1,39 @@
+{
+  "tacId": "TAC-1802-application-datatable-query-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Datatable query adapter",
+  "purpose": "Owns the sort, filter and pagination wire contract between the shell (TAC-1801) and the project's data source (a REST endpoint on application-api-rest, a GraphQL query, or an in-memory collection). Ships two shapes: a server-side default (elicited endpoint, receives `q`, `sort`, `page`, `pageSize`, returns `{ rows, total, page, pageSize, sort, q }`) and a client-side in-memory adapter for small collections (elicited ADR-1802 alternative).",
+  "responsibilities": [
+    "Serialise sort, filter and pagination into the request the data source reads (AC-17101-1, AC-17102-1, AC-17103-1) with a documented parameter grammar (`sort=<column>:<asc|desc>`, `q=<string>`, `page=<int>`, `pageSize=<int>`).",
+    "Return a page envelope the shell can render without knowing whether the source is server-side or client-side (AC-17102-1, AC-17103-2).",
+    "Preserve sort, filter and page state in the URL per ADR-1802 recommended default (AC-17108-1, AC-17108-2).",
+    "Read the applied default page size from ADR-1803 when no `pageSize` is present in the URL (AC-17108-3)."
+  ],
+  "internalStructure": "One factory `createQueryAdapter({ mode, endpoint, initialState })` returning an object with `query({ sort, q, page, pageSize })` returning `Promise<{ rows, total, page, pageSize, sort, q }>`. Mode `serverSide` issues `fetch(endpoint + '?' + params)`; mode `clientSide` runs the sort and filter against the in-memory collection the operator supplied at construction time. Both modes expose the same page envelope.",
+  "interfaces": [
+    {
+      "name": "createQueryAdapter",
+      "kind": "factory",
+      "description": "createQueryAdapter({ mode: 'serverSide' | 'clientSide', endpoint?, rows?, initialState? }) -> { query({ sort?, q?, page, pageSize }): Promise<{ rows, total, page, pageSize, sort, q }> }"
+    },
+    {
+      "name": "queryEnvelope",
+      "kind": "shape",
+      "description": "The response envelope the shell renders: `{ rows: Row[], total: number, page: number, pageSize: number, sort: string | null, q: string | null }`."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "application-api-rest",
+      "kind": "external",
+      "description": "The server-side default targets a REST endpoint the api-rest blueprint's contract shapes; the adapter carries no api-rest dependency at runtime and does not require the api-rest blueprint to be applied."
+    }
+  ],
+  "tradeoffs": "The wire grammar is opinionated (`sort=<col>:<dir>` rather than `orderBy=<col>&direction=<dir>`); a project with an existing endpoint that reads a different grammar supplies its own adapter satisfying the shell interface, and the shell reads through it unchanged. GraphQL projects supply an adapter that maps the same envelope through the GraphQL query and mutation as the server-side default reads.",
+  "notes": "Known mechanism-reach gap: request-cancellation on rapid filter typing is a project-side concern; the adapter names debouncing as an operator-owned decision in the guide and does not ship debouncing in v1.0.0.",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/tacs/tac-1803-application-datatable-selection-model.json

@@ -0,0 +1,28 @@
+{
+  "tacId": "TAC-1803-application-datatable-selection-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Datatable selection model",
+  "purpose": "Owns the per-row, per-page and (elicited) cross-page selection state, plus the accessible count the shell renders adjacent to the bulk action controls. Substitutable interface so tests can drive selection without mounting the shell.",
+  "responsibilities": [
+    "Track the selected row-id set across shell mount / unmount cycles (AC-17109-1, AC-17109-2).",
+    "Expose a keyboard-reachable per-row toggle and a page-level toggle that flips the visible page (AC-17104-1).",
+    "Expose the running count the shell renders adjacent to the bulk-action controls (AC-17109-2).",
+    "Reset selection on advance when the operator did not elicit cross-page persistence (AC-17109-3)."
+  ],
+  "internalStructure": "One factory `createSelectionModel({ persistence: 'perPage' | 'crossPage' })` returning `{ toggle(rowId), togglePage(rowIds), selectedIds(), size(), reset(), onChange(listener) }`. The shell (TAC-1801) reads selectedIds() to render checkbox state and size() to render the running count.",
+  "interfaces": [
+    {
+      "name": "createSelectionModel",
+      "kind": "factory",
+      "description": "createSelectionModel({ persistence: 'perPage' | 'crossPage' }) -> { toggle(rowId), togglePage(rowIds), selectedIds(): number[]|string[], size(): number, reset(), onChange((event) => void) }"
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "A project on cross-page persistence pays the cost of a growing selection state; the recommendedDefault (per-page reset) keeps the surface predictable for large datasets. Elicited cross-page persistence names the operator's choice; the shell surfaces the choice in the accessible copy near the bulk action so operators know which mode applies.",
+  "notes": "Known mechanism-reach gap: selection state does not survive a full page reload in v1.0.0; a project that wants that persistence writes through the URL contract (ADR-1802) or supplies its own model. Named in the guide.",
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17101.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17101",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Sort activation reorders rendered rows to match the query adapter and announces the direction",
+  "asA": "operator scanning a table for a top or bottom row",
+  "iWant": "the sort control on a column header to reorder the rendered rows to match the query adapter's response and announce the sort direction to assistive tech",
+  "soThat": "keyboard-only users and screen-reader users perceive the same sort result sighted users see",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17101-1",
+      "description": "Given a rendered datatable route with a sortable column, when the operator activates the column's sort control, the DOM rendered row order matches the server-side sort response for that column and direction. The check drives the browser to the shell route, records the initial row order, clicks the sort control, and compares the rerendered row order to the /api/rows response for the same sort key. Probed by the `application-datatable` pack under check id AC-17101-1.",
+      "given": "a rendered datatable route and a sortable column with an accessible sort control",
+      "when": "the operator activates the sort control (mouse or keyboard)",
+      "then": "the rendered row order matches the server-side sort response for the same column and direction",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17101-2",
+      "description": "Given a rendered datatable route, when the operator focuses a sortable column header, the header carries a keyboard-reachable sort control (a `<button>` or `role=\"button\"` element) reachable in tab order without a pointer.",
+      "given": "a rendered datatable route",
+      "when": "the operator tabs into the table header",
+      "then": "each sortable column exposes a focusable sort control",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17101-3",
+      "description": "Given a sort activation on a column, the surface updates the column header's `aria-sort` attribute to `ascending` or `descending` matching the applied direction; subsequent activations flip the direction and the attribute together (ARIA APG table + grid patterns).",
+      "given": "a rendered datatable with an initial `aria-sort` of `none` on every column",
+      "when": "the operator activates the sort control on a column",
+      "then": "the activated column's `aria-sort` reads `ascending` or `descending` matching the new direction and every other column stays at `none`",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1801-application-datatable-shell", "TAC-1802-application-datatable-query-adapter"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17102.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17102",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Filter chrome text search issues a q request and narrows rendered rows to the response",
+  "asA": "operator looking for a subset of rows by keyword",
+  "iWant": "the text filter to issue a request the query adapter reads as `q` and rerender the rows the response returned",
+  "soThat": "the sighted, keyboard and screen-reader paths all see the same filtered set",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17102-1",
+      "description": "Given a rendered datatable route with a text filter input, when the operator types a value, the client issues a request to the query adapter carrying `q=<value>`; the server (server-side default) or the in-memory adapter (elicited client-side alternative) reads `q` and returns rows matching the filter; the rendered rows equal the returned rows. The check types into the filter, awaits the fetch, reads the rendered names, and compares against a direct `/api/rows?q=<value>` fetch. Probed by pack check AC-17102-1.",
+      "given": "a rendered datatable route with a filter input",
+      "when": "the operator types a value into the filter",
+      "then": "the query adapter receives a `q` value equal to the typed string and the rendered rows equal the returned rows",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17102-2",
+      "description": "Given a filter change, the pagination cursor resets to page 1 so the operator does not see an out-of-range empty page after narrowing. The check reads the pagination status region before and after typing into the filter and asserts the current page reads 1.",
+      "given": "a rendered datatable route where the operator advanced past page 1",
+      "when": "the operator types a filter value",
+      "then": "the pagination status region reads `Page 1 of M` for the filtered result set",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17102-3",
+      "description": "Given a per-column filter dropdown on a bounded-value column, when the operator selects a value, the query adapter receives a filter on that column and the rendered rows narrow to the matching subset; combined with a text search on `q`, both filters compose deterministically at the adapter.",
+      "given": "a rendered datatable route with at least one per-column dropdown filter",
+      "when": "the operator selects a value and (independently) types a `q`",
+      "then": "the query adapter receives both filters and the rendered rows are the intersection",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1801-application-datatable-shell", "TAC-1802-application-datatable-query-adapter"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17103.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17103",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Pagination advances the page and announces the current position through an aria-live region",
+  "asA": "operator paging through a long result set",
+  "iWant": "the pagination control to advance the page, refetch the correct page from the query adapter, and announce the new position to assistive tech",
+  "soThat": "screen-reader users know which page they are on without having to scan the whole surface",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17103-1",
+      "description": "Given a rendered datatable with server-side pagination, when the operator activates the next-page control, the client issues a request carrying `page` and `pageSize` and rerenders the returned rows. Probed indirectly through AC-17103-2 which asserts the announced position; direct request assertions carry via the `application-api-rest` contract.",
+      "given": "a rendered datatable with a next-page control",
+      "when": "the operator activates the next-page control",
+      "then": "the query adapter receives `page` and `pageSize` and the rendered rows equal the returned rows",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17103-2",
+      "description": "Given a rendered datatable, an `aria-live=\"polite\"` region renders the current position as `Page N of M`; when the operator advances the pagination, the region text updates to the new N. The check reads the region before and after clicking the next-page control, asserts the initial text matches `Page N of M`, and asserts the next click updates N. Probed by pack check AC-17103-2.",
+      "given": "a rendered datatable with a pagination control and an aria-live status region",
+      "when": "the operator activates the pagination control",
+      "then": "the aria-live region text updates from `Page N of M` to `Page N+1 of M`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17103-3",
+      "description": "Given a rendered datatable, the pagination controls (previous, next, page number links where present) are reachable in tab order and activate on `Enter` or `Space` without pointer input.",
+      "given": "a rendered datatable with a pagination control",
+      "when": "the operator tabs into the pagination region",
+      "then": "each pagination control receives focus and activates on `Enter` or `Space`",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1801-application-datatable-shell", "TAC-1802-application-datatable-query-adapter"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}

package/blueprints/application-datatable/contributions/user-stories/application-datatable-us-17104.json

@@ -0,0 +1,44 @@
+{
+  "usId": "application-datatable-US-17104",
+  "prdId": "PRD-001",
+  "reqId": "application-datatable-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Bulk actions on selected rows open a confirmation dialog and return focus to the originating row on close",
+  "asA": "operator applying an action to multiple rows",
+  "iWant": "each bulk action to open a confirmation dialog under the ARIA APG dialog-modal pattern and return focus to the row that opened it when the dialog closes",
+  "soThat": "the destructive step never runs by accident and keyboard-only users are not stranded at the top of the surface",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-17104-1",
+      "description": "Given a rendered datatable with row-level checkboxes and a bulk action, when the operator toggles a row checkbox, the selection model records the row id and the bulk-action control reflects the new selection count in its accessible label or an adjacent status element.",
+      "given": "a rendered datatable with row-selection checkboxes",
+      "when": "the operator toggles a row checkbox",
+      "then": "the accessible selection count updates by one",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17104-2",
+      "description": "Given selected rows and a bulk-action control, when the operator activates the bulk action, a dialog opens with `role=\"dialog\"`, `aria-modal=\"true\"`, `aria-labelledby` naming the action, and `aria-describedby` naming the affected count; the confirm control receives initial focus.",
+      "given": "one or more rows selected in a rendered datatable",
+      "when": "the operator activates the bulk action",
+      "then": "the dialog opens with `role=\"dialog\"`, `aria-modal=\"true\"`, `aria-labelledby` and `aria-describedby` set, and the confirm control receives initial focus",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-17104-3",
+      "description": "Given an open bulk-action confirmation dialog, when the operator closes it (confirm or cancel), focus returns to the row control (the row's selection checkbox or an equivalent row-scoped focus target) that originated the bulk action, per WCAG 2.4.3 and ARIA APG dialog-modal. The check selects a row, opens the dialog, cancels, and asserts the focused element is the originating row's checkbox. Probed by pack check AC-17104-3.",
+      "given": "an open bulk-action confirmation dialog that originated on a specific row",
+      "when": "the operator closes the dialog (confirm or cancel)",
+      "then": "focus returns to the originating row's control (the row-scoped focus target), not to the document body or an unrelated element",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": ["TAC-1801-application-datatable-shell", "TAC-1803-application-datatable-selection-model"],
+  "tags": ["blueprint:application-datatable"],
+  "createdAt": "2026-09-04T19:45:00Z",
+  "updatedAt": "2026-09-04T19:45:00Z"
+}