ui-audit-log-viewer

Component contract

• scope: AuditScope — { kind: "tenant" | "event" | "entity" | "actor"; id: string }; constrains rows to this scope
• fetchRows: (filters, page) => Promise<AuditRowsPage> — paginated; returns rows in reverse-chronological order
• actions: ActionDef[] — closed enum of action types (e.g., "registration_created", "refund_issued", "collaborator_added") with display labels + icons; populates filter dropdown
• actorKinds?: ActorKindDef[] — distinguishes user / system / api-token / scheduled-job actors; affects row presentation
• onRowClick?: (row) => void — row drill-in; when omitted, drill-in is the default modal display
• permissions: { canExport, canViewSensitive } — gates export CTA + sensitive-field redaction
• onExport?: (filters) => Promise<ExportJobRef> — async export with same filters; returns job ref for tracker

Composition

• ui-search-with-filters — header row: actor filter, action-kind filter, free-text search, date range
• ui-date-range-picker — filter; default = last 7 days
• ui-data-table — rows: timestamp, actor, action (with status pill), context label, drill-in icon
• ui-status-pill — per-row action category (success / failure / partial / cancelled)
• ui-pagination — bottom; cold-tier rows show a "loaded from archive" indicator
• ui-modal — drill-in; full row JSON + before/after diff (where applicable)
• ui-async-job-tracker — when onExport is invoked, the export job's status is tracked

Interaction surface

1. Default view: last 7 days, all actions, all actors.

   Reverse-chronological. URL state syncs (?from=...&to=...&action=...&actor=...). Refresh-safe. Empty state distinct from filtered-empty.

2. Per-row click drills in.

   Modal shows: full timestamp (with timezone), actor (kind + identity), action label, full payload (before/after JSON for state changes), request_id (for API-actor rows), audit row ID (for support). Esc closes; focus returns to row.

3. Filtering produces visible URL changes.

   Each filter change updates URL state immediately (debounced 300ms via ui-search-with-filters). Bookmarkable, shareable. Refreshing on a filtered URL restores the same filtered view.

4. Cold-tier rows annotated.

   Filter beyond 90 days fetches from compliance-archived storage; rows display a small "archived" indicator. Slower (banner: "Loading archive — may take a few seconds"). Fully transparent — same row format.

5. Export CTA opens async-job-tracker.

   When canExport, "Export filtered rows" CTA. Submits an export job with current filter set. Tracker shows pending/running/ready with download URL. Inherits ui-async-job-tracker contract.

Failure modes

Accessibility

• Inherits ui-data-table, ui-pagination, ui-search-with-filters, ui-modal a11y contracts.
• Drill-in modal title is the row's action label + timestamp.
• Cold-tier banner + archived pill announced via aria-live=polite.
• Redaction markers have aria-label="redacted (insufficient permission)" so screen readers know it's not missing data.
• axe-clean ≥ serious across default, filtered, drill-in-open, empty, cold-tier-loading states.

Stable test attributes

Agent test plan

- default-view-last-7-days: filter date range = last 7 days
- url-state-syncs: filter changes update URL within 300ms
- url-refresh-restores-filters: filter + refresh, same view
- drill-in-on-row-click: click row, ui-audit-log-drill-in visible
- drill-in-esc-closes: open + Esc, modal closes, row focus restored
- drill-in-update-row-shows-diff: UPDATE action row, two-column diff
- drill-in-create-row-shows-payload: CREATE action row, single payload column
- drill-in-api-row-shows-request-id: api-token actor, request_id visible + copy button
- drill-in-read-only: drill-in has no mutating buttons
- redaction-without-canViewSensitive: stub no-permission, redacted markers visible in drill-in
- cold-tier-indicator: filter > 90d, banner + archived pills visible
- empty-state-no-rows: scope has 0 rows, ui-audit-log-empty-no-rows visible
- empty-state-filtered: filter to 0 rows, ui-audit-log-empty-filtered visible with clear-link
- column-headers-not-sortable: no sort affordance on any column header
- export-uses-current-filters: filter + export, job params match UI
- export-permission-gated: stub no canExport, ui-audit-log-export-cta hidden
- scope-permission-gated-403: stub low-role + high-scope, 403 on direct API
- aria-live-cold-tier: cold-tier banner has aria-live=polite
- axe-clean-across-states: default + filtered + drill-in + empty pass axe ≥ serious

Current consumers