ui-async-job-admin-page

Component contract

One React component renders the entire job-admin surface. Job kind is parameterized — same component shape covers reports, mailings, imports, syncs, exports, bulk-resends. Branch stories declare which kind via prop.

• jobKind: JobKind — discriminator: "report" | "mailing" | "import" | "sync" | "export" | "bulk-resend"
• fetchJobs: (filters, page) => Promise<JobsPage> — returns paginated job rows
• fetchJobStatus: (jobId) => Promise<JobStatus> — per-row tracker uses this
• jobTypes: JobTypeDef[] — types creatable from this surface (e.g., "guest-list-summary", "activity-log" for reports)
• onCreateJob?: (type, params) => Promise<Job> — when omitted, "Create new" is hidden
• onCancelJob?: (jobId) => Promise — per-row cancel button visible when provided
• onRetryJob?: (jobId) => Promise — per-row retry button visible when provided
• filterFields?: FilterField[] — passed to the embedded ui-search-with-filters
• permissions: { canCreate, canCancel, canRetry, canDelete } — gates UI affordances
• idempotencyKeyPrefix: string — for create + retry idempotency

Composition

Internally constructs:

• ui-search-with-filters — search + filter chips at the top; debounced 300ms
• ui-date-range-picker — embedded in the filter row when filterFields includes a date-range
• ui-data-table — the job list itself; columns: name, type, status (ui-status-pill), created-by, created-at, duration, actions
• ui-pagination — bottom of the list; page-size + total + status text
• ui-async-job-tracker — embedded per-row when a row is in {queued, running} state, AND optionally as the primary surface in a drill-in modal
• ui-status-pill — per row's status column
• ui-destructive-confirmation — for cancel + delete (when provided)
• ui-toast — for action confirmations (job created, job cancelled)

The composition is a single React component but is testable both as a unit (fixture page with mock data) and via consumer branches (which exercise it with real data flows).

Interaction surface

1. Page renders the job list.

   Header: page title + "Create new [jobKind]" button (visible when canCreate). Filter row underneath. Job list paginated below.

2. Filter changes re-fetch.

   Inherits ui-search-with-filters's debounce + URL-sync mandate. Page resets to 1 on filter change.

3. Per-row tracker updates live.

   Rows in queued/running state poll every 2s (per ui-async-job-tracker contract). Terminal-state rows don't poll.

4. Click row opens drill-in modal.

   Larger ui-async-job-tracker view with full lifecycle history, errorReason, requestId, download URL. Modal closes on Esc / outside click.

5. Create new opens form modal.

   Form fields per JobTypeDef (e.g., for reports: type selector, date range, output format). Submit creates job + appears in list at the top.

6. Cancel + retry per row.

   Cancel uses ui-destructive-confirmation. Retry creates a new job with the same params (audit log row references original).

Failure modes

Accessibility

• Inherits all tier-1 component a11y contracts.
• Page heading hierarchy: H1 = page title, H2 = filter region, H2 = job list, H3 = per-row job name (when expanded inline). headings-no-skip enforced.
• Live region announces job state transitions via aria-live=polite (ui-async-job-tracker contract).
• Drill-in modal inherits ui-modal focus-trap.
• axe-clean at severity ≥ serious across all states.

Stable test attributes

Agent test plan

- jobkind-renders-distinct-title: jobKind=report → title contains "Reports"; jobKind=mailing → "Mailings"
- create-cta-permission-gated: canCreate=false → ui-async-job-admin-create-cta hidden
- empty-state-no-jobs: 0 jobs ever → ui-async-job-admin-empty-no-jobs visible with create-first CTA
- empty-state-filtered: 5 jobs all filtered out → ui-async-job-admin-empty-filtered with clear-filters link
- loading-state-aria-busy: initial load → ui-async-job-admin-loading + aria-busy=true
- list-paginated-correctly: 50 jobs / pageSize=25 → page 1 shows 25, footer "Showing 1–25 of 50"
- per-row-tracker-polls: row in running state → fetchJobStatus called every 2s
- terminal-row-stops-polling: row in ready state → no further polls
- drill-in-on-row-click: click row → drill-in-modal visible
- drill-in-esc-closes: open + Esc → modal closes, row focus restored
- create-form-validates: submit incomplete form → validation errors per ui-form
- create-creates-job: submit valid → fetchJobs returns +1 row at top of list
- cancel-uses-destructive-confirmation: click cancel → ui-destructive-confirmation visible
- cancel-success-toast: confirm cancel → ui-toast "Cancelled"
- retry-uses-idempotency-key: click retry 2x within 100ms → 2 POSTs with same Idempotency-Key
- bulk-cancel-cascades: select 5 + bulk cancel → 5 cancel POSTs each with distinct keys
- list-refresh-30s: stub server-side new job, wait 30s → appears in list
- manual-refresh-cta: click refresh → fetchJobs called immediately
- jobkind-mismatch-404: navigate to mismatched URL → 404-equivalent rendered
- cross-tenant-404: forged URL → 404
- color-contrast-status-pills: every status × every tone ≥ 4.5:1 (inherits ui-status-pill)
- axe-clean-serious: across loading/empty/filtered/normal states

Current consumers (will tighten via this compound)

Once branches adopt this tier-3 component, their usesComponents declarations simplify. Each branch goes from listing 7 tier-1 components to listing 1 tier-3 component (plus any branch-specific additions).