spec(ActivityTray): spec and prototype for background task progress

[Stephen Watkins (stephenjwatkins)]

📝 Changes

https://63f50c7c86f6514d2e0ef4be-mxsjvrjewf.chromatic.com/?path=/docs/prototypes-activitytray--docs

A spec and working prototype for a corner-docked, non-blocking surface that reports on background work — bulk label purchases, report generation, CSV imports — while the user keeps working.

• Spec: documentation/specs/ActivityTray.md
• Prototype: easy-ui-react/src/ActivityTray/, in Storybook under Prototypes/ActivityTray

Not a toast. A toast is a message with a 4-second life and nothing to track. Notification's singleton queue, mandatory timeout, and role="status" all work against a task list, so this doesn't build on it — they compose instead. The pattern has no settled industry name; the spec records the prior art and the naming trade-off.

The API

Minimal case — one task is one row, with no header above it:

import { ActivityTray } from "@easypost/easy-ui/ActivityTray";

<ActivityTray>
  <ActivityTray.Task
    title="Buying labels"
    status="running"
    completed={127}
    total={250}
    unit="labels"
  />
</ActivityTray>;

Real usage — mounted above the router so navigation can't unmount it, fed from whatever already tracks the work:

function BackgroundActivity() {
  const { tasks, cancel, retry, dismiss } = useBackgroundJobs();

  return (
    <ActivityTray placement="bottom-end" offset={{ bottom: "72px" }}>
      {tasks.map((task) => (
        <ActivityTray.Task
          key={task.id}
          title={task.title}
          status={task.status}
          completed={task.completed}
          total={task.total}
          unit="labels"
          description={task.description}
          onDismiss={() => dismiss(task.id)}
        >
          {task.status === "running" && (
            <ActivityTray.Action onPress={() => cancel(task.id)}>
              Cancel
            </ActivityTray.Action>
          )}
          {task.status === "failed" && (
            <ActivityTray.Action onPress={() => retry(task.id)}>
              Retry
            </ActivityTray.Action>
          )}
          {task.status === "partial" && (
            <ActivityTray.Action href={`/shipments?batch=${task.id}`}>
              Review
            </ActivityTray.Action>
          )}
        </ActivityTray.Task>
      ))}
    </ActivityTray>
  );
}

<ActivityTray />

Prop	Type	Default
children	ReactNode	—	<ActivityTray.Task /> elements
placement	"bottom-end" | "bottom-start" | "top-end" | "top-start"	"bottom-end"	Corner it docks to
offset	{ top?, right?, bottom?, left? }	space.4	Clears app chrome — a sticky footer, a support widget
maxVisibleTasks	number	4	Height cap in rows, then it scrolls. Applies from the second task on
autoDismissDelay	number | null	6000	Held while the pointer or focus is in the tray; null disables
renderSummary	(running: number, total: number) => ReactNode	"2 of 5 tasks running"	Header text. Never called with one task
isExpanded / defaultExpanded / onExpandedChange	boolean / boolean / (isExpanded) => void	— / true / —	Inert with a single task, where there's nothing to collapse
aria-label	string	"Background tasks"	Names the landmark
getContainer	() => HTMLElement | null	() => document.body	Portal target. Nothing renders until it returns an element

<ActivityTray.Task /> — title, status (pending running succeeded partial failed canceled), completed + total + unit for a determinate bar (omit total for indeterminate), description, onDismiss, a per-task autoDismissDelay override, and up to two <ActivityTray.Action /> children.

<ActivityTray.Action /> — children plus either onPress or href. Running rows get no dismiss button; a Cancel action with a real handler is the honest version of that.

Decisions

• ActivityTray, not TaskTray. "Task" is the riskier word to claim at the component level, so it moves down a level: the surface is an activity tray, each row in it is a task. The cost is that "activity" can read as an audit log — what keeps them apart is that the header counts what is running, finished rows retire themselves, and there is no scrollback.
• The app owns the task list. The tray is controlled and presentational, so Easy UI holds no opinions about polling, auth, or dedupe.
• Surviving navigation is a mounting concern, not a feature — mounted above the router, a route change can't unmount it. Crossing a full page load is the server's problem.
• Composition over a data prop, matching the rest of the package.
• A single task is the whole tray. No header, no disclosure: the row already names the work, shows its progress, and carries its actions.

Accessibility: progress is polled, outcomes are pushed. Named landmark rather than a live region; progress reaches AT through role="progressbar" with real unit counts; only terminal transitions write into one polite live region, coalescing same-tick finishes into a single sentence.

Two gaps this surfaced, both written up under Dependencies:

1. No linear ProgressBar exists. The bar is private to ActivityTray for now; extract it before this ships publicly.
2. Spinner can't be used decoratively — indeterminate mode is a role="status" live region, and its only label channel renders visible text, so an unlabeled one warned on every render. A private CSS ring stands in.

No index.ts, so the prototype is not an entry point of the published package and nothing can import it yet.

Worth discussing: the spec's 7 open questions, particularly stacking against Modal, mobile, and whether cancel needs confirmation.

✅ Checklist

• Visuals match Design Specs in Figma — no Figma yet; this is the proposal
• Stories accompany any component changes
• Code is in accordance with our style guide
• Design tokens are utilized — except z-index, which needs a new z_index.activity_tray token and is a literal for now
• Unit tests accompany any component changes
• TSDoc is written for any API surface area
• Specs are up-to-date
• Console is free from warnings
• No accessibility violations are reported — not yet run against the stories; needed before this is promoted
• Cross-browser check is performed (Chrome, Safari, Firefox) — not yet done
• Changeset is added — nothing published; no index.ts means no entry point

🤖 Generated with Claude Code