# V1-AWEB-095 — Canonical Dense-Table Behaviour Spec

Implementation spec for the Phase 17.10 canonical dense-table component. Goal:
**scan speed, row emphasis, selection, bulk actions, and keyboard-first
operation** behave consistently across every admin queue / list surface.

## Reference: as-is

Today the admin app has 18+ list surfaces, each implementing its own tabular
layout (per V1-AWEB-092 inventory). Examples: `AppealQueueList`,
`ModerationContentList`, `UserReportsList`, `ClonedVoiceReviewList`,
`AvatarDeceptionReviewList`, `ImageModerationReviewList`, `OffenderHistoryList`,
`SupportCaseInboxPanel`, `PrivacyRequestQueuePanel`,
`ResearchIntegrityQueuePanel`, `CitationValidationWorkspacePanel`,
`ReviewPackageList`, `RightsProvenancePanel`, `PolicyBundleGovernancePanel`,
`ConfigurationCenterPanel`, `ReadinessDashboardPanel` rows,
`RetentionManagementPanel` sections, `ProviderOperationsPanel`. Each defines its
own row height, padding, header, row-emphasis rules, and keyboard shortcuts.

### As-is pain points

1. **Inconsistent row heights.** Operators scanning across queues in the same
   shift cannot use peripheral pattern-matching; every queue feels visually
   different.
2. **No standardised selection model.** A few panels expose per-row checkboxes
   (`UnifiedInboxPanel`); most do not. Selection state lives per-panel with no
   canonical hook.
3. **Bulk actions inconsistently surfaced.** Inbox bulk actions live above the
   list; trust-safety bulk actions live in a modal; review bulk actions don't
   exist.
4. **Keyboard navigation is panel-by-panel.** `j/k` works in
   `KeyboardTriageReviewPanel` but not in `AppealQueueList`.
5. **Row emphasis rules are local.** Critical / overdue / SLA- breached rows are
   emphasised differently per panel: some red stripe, some red text, some red
   badge.

## Design principles

1. **One row spec, every list.** Single canonical row component shared across
   all admin lists.
2. **Selection is opt-in but identical.** Lists declare whether they support
   selection; when they do, the checkbox column renders identically.
3. **Bulk action bar is a sticky surface, not a modal.** Bulk actions appear in
   a sticky bar above the list when ≥1 row is selected.
4. **Keyboard navigation is built in.** `j/k` always row- navigates; `x` always
   toggles selection on the focused row; `Enter` always opens the row; `?`
   always opens the keyboard shortcut help.
5. **Emphasis comes from data, not styling decisions.** Row emphasis (critical,
   overdue, SLA breach) is driven by a declared `severity` prop on the row spec.

## Canonical row spec

```tsx
interface AdminTableRow<TData> {
  id: string;
  data: TData;
  severity: 'normal' | 'attention' | 'urgent' | 'critical';
  href?: string; // optional permalink for the row
  selectable?: boolean; // override panel default
}

interface AdminTableColumn<TData> {
  key: string;
  header: string;
  cell: (row: AdminTableRow<TData>) => ReactNode;
  width?: string; // CSS grid width fragment
  align?: 'start' | 'end' | 'center';
  scanRank?: 1 | 2 | 3; // 1 = primary scan, 3 = supporting
}

interface AdminTableProps<TData> {
  rows: ReadonlyArray<AdminTableRow<TData>>;
  columns: ReadonlyArray<AdminTableColumn<TData>>;
  selectionState?: AdminTableSelectionState; // opt-in
  bulkActions?: ReadonlyArray<AdminTableBulkAction>;
  keyboardShortcuts?: 'standard' | 'extended';
  emptyState?: ReactNode;
}
```

The row component renders as a CSS grid row with `grid-template-columns` derived
from `columns[].width`. Severity is mapped to a left-edge stripe (4px) via
`data-severity` and a CSS rule:

```css
[data-severity='attention'] {
  border-left: 4px solid #fbbf24;
}
[data-severity='urgent'] {
  border-left: 4px solid #fb923c;
}
[data-severity='critical'] {
  border-left: 4px solid #ef4444;
}
```

Row text is the same density at all severities (no bolding, italicising, or
colour shifts on the text itself — emphasis lives entirely in the stripe).

## Selection model

`AdminTableSelectionState` exposes:

- `selectedIds: Set<string>`
- `toggle(id): void`
- `selectAll(): void`
- `clear(): void`
- `count: number`

Selection state is opt-in per panel. When provided, the table renders a leading
checkbox column. The bulk action bar (`<AdminTableBulkActionBar />`) appears as
a sticky surface above the list when `count > 0` and lists each declared bulk
action with a button. Bulk actions take an array of selected ids and either emit
an inline confirmation drawer or fire directly.

## Keyboard shortcuts

Standard set (always on):

- `j` / `↓` — move focus to next row
- `k` / `↑` — move focus to previous row
- `Enter` — open the focused row's `href` (no-op if not set)
- `x` — toggle selection on the focused row (no-op if selection not enabled)
- `?` — open `KeyboardShortcutsHelp` modal scoped to the table

Extended set (lists with an `extended` opt-in):

- `g g` — jump to first row
- `G` — jump to last row
- `/` — focus the search box (if the list ships one)
- `Ctrl-a` — select all (when selection enabled)

## Implementation deliverables

1. `apps/oshun/admin/src/components/AdminTable.tsx` + `.module.css` — canonical
   table component.
2. `apps/oshun/admin/src/components/AdminTableBulkActionBar.tsx` +
   `.module.css`.
3. `apps/oshun/admin/src/lib/use-admin-table-selection.ts` —
   `useAdminTableSelection()` hook.
4. Migration: 18 named list components migrate to `AdminTable`, one per PR.
   Migration order keyed to operator volume: `UnifiedInboxPanel` first, then
   `ReviewPackageList`, `ResearchIntegrityQueuePanel`,
   `CitationValidationWorkspacePanel`, `SupportCaseInboxPanel`,
   `PrivacyRequestQueuePanel`, then trust-safety + the long tail.
5. Tests: `AdminTable` component test (severity stripe, empty state, column
   widths), bulk action bar test, selection hook unit test, Playwright
   `admin-table-keyboard.spec.ts` (`j/k/Enter/x` round-trips).

## Out of scope

- Drag-to-reorder columns (deferred).
- Column visibility chooser (deferred).
- Server-side pagination changes (existing panels keep client-side rendering).

## Acceptance criteria

- Every admin list surface uses `AdminTable` with a declared column spec and row
  severity mapping.
- Severity emphasis renders as the canonical 4px left stripe at all four
  severity levels.
- Selection state, when enabled, drives a sticky bulk action bar with all
  declared actions.
- Standard keyboard shortcut set works on every list.
- `useAdminTableSelection` hook unit test passes; `AdminTable` component test
  passes; Playwright keyboard spec passes.
- Existing per-panel tests remain green after migration.
