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#
- Inconsistent row heights. Operators scanning across queues in the same shift cannot use peripheral pattern-matching; every queue feels visually different.
- No standardised selection model. A few panels expose per-row checkboxes
(
UnifiedInboxPanel); most do not. Selection state lives per-panel with no canonical hook. - 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.
- Keyboard navigation is panel-by-panel.
j/kworks inKeyboardTriageReviewPanelbut not inAppealQueueList. - 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#
- One row spec, every list. Single canonical row component shared across all admin lists.
- Selection is opt-in but identical. Lists declare whether they support selection; when they do, the checkbox column renders identically.
- 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.
- Keyboard navigation is built in.
j/kalways row- navigates;xalways toggles selection on the focused row;Enteralways opens the row;?always opens the keyboard shortcut help. - Emphasis comes from data, not styling decisions. Row emphasis (critical,
overdue, SLA breach) is driven by a declared
severityprop on the row spec.
Canonical row spec#
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:
[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): voidselectAll(): voidclear(): voidcount: 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 rowk/↑— move focus to previous rowEnter— open the focused row'shref(no-op if not set)x— toggle selection on the focused row (no-op if selection not enabled)?— openKeyboardShortcutsHelpmodal scoped to the table
Extended set (lists with an extended opt-in):
g g— jump to first rowG— jump to last row/— focus the search box (if the list ships one)Ctrl-a— select all (when selection enabled)
Implementation deliverables#
apps/oshun/admin/src/components/AdminTable.tsx+.module.css— canonical table component.apps/oshun/admin/src/components/AdminTableBulkActionBar.tsx+.module.css.apps/oshun/admin/src/lib/use-admin-table-selection.ts—useAdminTableSelection()hook.- Migration: 18 named list components migrate to
AdminTable, one per PR. Migration order keyed to operator volume:UnifiedInboxPanelfirst, thenReviewPackageList,ResearchIntegrityQueuePanel,CitationValidationWorkspacePanel,SupportCaseInboxPanel,PrivacyRequestQueuePanel, then trust-safety + the long tail. - Tests:
AdminTablecomponent test (severity stripe, empty state, column widths), bulk action bar test, selection hook unit test, Playwrightadmin-table-keyboard.spec.ts(j/k/Enter/xround-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
AdminTablewith 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.
useAdminTableSelectionhook unit test passes;AdminTablecomponent test passes; Playwright keyboard spec passes.- Existing per-panel tests remain green after migration.