Eve library

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

Spec

Revision 1

On this page

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.