@podoba/react 0.0.6 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@podoba/react",
-	"version": "0.0.6",
+	"version": "0.0.8",
 	"type": "module",
 	"description": "podoba React components — React Aria Components + Tailwind primitives + layout, built with uic.",
 	"repository": {
@@ -25,8 +25,8 @@
 		"typecheck": "tsc --build"
 	},
 	"dependencies": {
-		"@podoba/tokens": "^0.0.6",
-		"@podoba/tailwind": "^0.0.6",
+		"@podoba/tokens": "^0.0.8",
+		"@podoba/tailwind": "^0.0.8",
 		"react-aria-components": "1.18.0",
 		"class-variance-authority": "0.7.1",
 		"clsx": "2.1.1",

package/src/components/brand-page-header.tsx

@@ -0,0 +1,189 @@
+import { type ReactNode, useState } from 'react'
+import { Button } from './button'
+
+/**
+ * BrandPageHeader — the brand-workspace page header (port of gs-platform
+ * `GSPageHeader` + `ExpandableCTA`).
+ *
+ * gs-platform's header is a two-column grid: a left "welcome" section
+ * (optional breadcrumbs + a large greeting line) and a right section holding an
+ * `ExpandableCTA` — a collapsed teal pill that expands into an inline
+ * create-hub panel. We port that interaction to React Aria + Tailwind + the
+ * teal accent token (`brand-secondary`), dropping gs-platform's mobile
+ * fixed-sheet behaviour for a simpler inline disclosure.
+ *
+ * The expandable CTA is a controlled disclosure: the collapsed teal pill is a
+ * React Aria `Button` (keyboard + focus ring + press handling) wired to a
+ * `region` with `aria-expanded`/`aria-controls`, so it follows the WAI-ARIA
+ * disclosure pattern without pulling in extra markup.
+ *
+ * Presentational only (hard rule #1): every string (greeting, breadcrumb
+ * labels, CTA label) arrives via props — no API, no i18n.
+ */
+
+export type BrandPageHeaderCrumb = {
+	label: ReactNode
+	/** Optional click handler — when set the crumb renders as a button. */
+	onPress?: () => void
+}
+
+export type BrandPageHeaderProps = {
+	/** The large greeting / page-title slot (e.g. "Good morning Jonas 👋"). */
+	greeting: ReactNode
+	/**
+	 * gs-style "title to go back": a muted, clickable PARENT link rendered as the
+	 * line ABOVE the title (so the title reads "Parent ⏎ Current"). Pass a real
+	 * router `<Link>` so it's an anchor (cmd/middle-click, deep-link-safe), exactly
+	 * like gs's `parentLink`. The header styles it muted with a hover→fg affordance.
+	 */
+	parentLink?: ReactNode
+	/** Optional breadcrumb trail rendered above the greeting. */
+	breadcrumbs?: BrandPageHeaderCrumb[]
+	/**
+	 * Arbitrary right-column CTA node (e.g. the gs hero `CtaPill` banner). When
+	 * set it REPLACES the collapsed-pill ExpandableCTA — use this for the
+	 * gs-faithful "Let's create something" hero. `ctaLabel`/`createHub` are ignored.
+	 */
+	cta?: ReactNode
+	/** Label on the collapsed teal "Create" pill. Required to render the CTA. */
+	ctaLabel?: ReactNode
+	/** Inline content revealed when the CTA expands (the create hub). */
+	createHub?: ReactNode
+	/** Controlled expansion (optional — uncontrolled by default). */
+	expanded?: boolean
+	onExpandedChange?: (expanded: boolean) => void
+	/** Accessible label for the close control when expanded. Defaults to "Close". */
+	closeLabel?: string
+	/** Sticky header on scroll. */
+	sticky?: boolean
+	className?: string
+}
+
+const PANEL_ID = 'brand-page-header-create-hub'
+
+export function BrandPageHeader({
+	greeting,
+	parentLink,
+	breadcrumbs,
+	cta,
+	ctaLabel,
+	createHub,
+	expanded: expandedProp,
+	onExpandedChange,
+	closeLabel = 'Close',
+	sticky = false,
+	className,
+}: BrandPageHeaderProps) {
+	const [internalExpanded, setInternalExpanded] = useState(false)
+	const isControlled = expandedProp !== undefined
+	const expanded = isControlled ? expandedProp : internalExpanded
+	const hasExpandable = Boolean(createHub)
+
+	const setExpanded = (next: boolean) => {
+		if (!isControlled) setInternalExpanded(next)
+		onExpandedChange?.(next)
+	}
+
+	return (
+		<div
+			className={[
+				'mb-6 w-full',
+				sticky ? 'sticky top-0 z-30 bg-surface' : '',
+				className,
+			]
+				.filter(Boolean)
+				.join(' ')}
+		>
+			<div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between sm:gap-4">
+				<div className="flex min-w-0 flex-col gap-1">
+					{breadcrumbs && breadcrumbs.length > 0 ? (
+						<nav aria-label="Breadcrumb" className="flex flex-wrap items-center gap-1 text-compact text-fg-muted">
+							{breadcrumbs.map((crumb, i) => (
+								<span key={i} className="inline-flex items-center gap-1">
+									{i > 0 ? <span aria-hidden="true">/</span> : null}
+									{crumb.onPress ? (
+										<Button
+											variant="ghost"
+											onPress={crumb.onPress}
+											className="h-auto rounded-sm p-0 text-compact font-normal text-fg-muted data-[hovered]:bg-transparent data-[hovered]:text-fg data-[hovered]:underline"
+										>
+											{crumb.label}
+										</Button>
+									) : (
+										<span>{crumb.label}</span>
+									)}
+								</span>
+							))}
+						</nav>
+					) : null}
+					<h1 className="text-display font-medium leading-[1.12] tracking-[-0.56px] text-fg">
+						{parentLink ? (
+							// gs "title to go back": muted clickable parent line above the title.
+							// `[&_a]` styles the nested router <Link> (anchor) without @app/ui
+							// importing the router.
+							<>
+								<span className="text-fg-muted transition-colors [&_a:hover]:text-fg [&_a]:text-fg-muted [&_a]:no-underline [&_a]:outline-none [&_a:focus-visible]:underline">
+									{parentLink}
+								</span>
+								<br />
+							</>
+						) : null}
+						{greeting}
+					</h1>
+				</div>
+
+				{cta ? (
+					<div className="w-full shrink-0 sm:w-auto sm:min-w-[360px]">{cta}</div>
+				) : ctaLabel ? (
+					<div className="shrink-0">
+						{hasExpandable ? (
+							<Button
+								onPress={() => setExpanded(!expanded)}
+								aria-expanded={expanded}
+								aria-controls={PANEL_ID}
+								className="h-10 rounded-full bg-brand-secondary px-5 text-sm font-medium text-fg data-[hovered]:opacity-90 data-[pressed]:opacity-80"
+							>
+								{ctaLabel}
+							</Button>
+						) : (
+							<Button className="h-10 rounded-full bg-brand-secondary px-5 text-sm font-medium text-fg data-[hovered]:opacity-90 data-[pressed]:opacity-80">
+								{ctaLabel}
+							</Button>
+						)}
+					</div>
+				) : null}
+			</div>
+
+			{hasExpandable ? (
+				<div
+					id={PANEL_ID}
+					role="region"
+					aria-label={typeof ctaLabel === 'string' ? ctaLabel : undefined}
+					hidden={!expanded}
+					className="mt-4"
+				>
+					{expanded ? (
+						<div className="relative rounded-lg border border-border bg-surface-card p-4 animate-expand-cta motion-reduce:animate-none">
+							<Button
+								variant="ghost"
+								aria-label={closeLabel}
+								onPress={() => setExpanded(false)}
+								className="absolute right-2 top-2 h-7 w-7 rounded-full p-0 text-fg-muted data-[hovered]:bg-surface-muted data-[hovered]:text-fg"
+							>
+								<svg width="16" height="16" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+									<path
+										d="M6 6l12 12M18 6L6 18"
+										stroke="currentColor"
+										strokeWidth="2"
+										strokeLinecap="round"
+									/>
+								</svg>
+							</Button>
+							{createHub}
+						</div>
+					) : null}
+				</div>
+			) : null}
+		</div>
+	)
+}

package/src/components/combobox.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react'
 import {
+	Autocomplete,
 	Button as RACButton,
 	ComboBox as RACComboBox,
 	type ComboBoxProps as RACComboBoxProps,
@@ -10,9 +11,12 @@ import {
 	ListBoxItem,
 	type ListBoxItemProps,
 	Popover,
+	SearchField,
 	Text,
+	useFilter,
 } from 'react-aria-components'
 import { uic } from '../utils/uic'
+import { useInFocusOverlay } from './focus-context'
 
 /**
  * ComboBox — a filterable single-select: a text input that narrows a listbox as
@@ -65,32 +69,78 @@ export const ComboBox = <T extends object>({
 	errorMessage,
 	placeholder,
 	children,
+	selectedKey,
+	onSelectionChange,
 	...props
-}: ComboBoxProps<T>) => (
-	// `menuTrigger="focus"` opens the list on focus/click (not only on typing), so
-	// the options are always one interaction away. Consumers can override via props.
-	<RACComboBox menuTrigger="focus" {...props} className="group flex flex-col gap-2">
-		<Label className="text-heading5 font-medium text-fg">{label}</Label>
-		<div className="relative">
-			<ComboBoxInput placeholder={placeholder} />
-			{/* RAC uses this Button to toggle the listbox open/closed. */}
-			<RACButton className="absolute inset-y-0 right-0 flex w-11 items-center justify-center rounded-r-lg outline-none data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring">
-				<Chevron />
-			</RACButton>
-		</div>
-		{description ? (
-			<Text slot="description" className="text-xs text-fg-muted">
-				{description}
-			</Text>
-		) : null}
-		<FieldError className="text-xs text-danger">{errorMessage}</FieldError>
-		<Popover className="min-w-[var(--trigger-width)] overflow-hidden rounded-lg bg-surface-card shadow-lg">
-			<ListBox
-				className="flex max-h-64 flex-col gap-0.5 overflow-auto overscroll-contain p-1 outline-none"
-				renderEmptyState={() => <div className="px-3 py-2 text-sm text-fg-muted">No results</div>}
-			>
-				{children}
-			</ListBox>
-		</Popover>
-	</RACComboBox>
-)
+}: ComboBoxProps<T>) => {
+	const inFocus = useInFocusOverlay()
+	const { contains } = useFilter({ sensitivity: 'base' })
+	const desc = description ? (
+		<Text slot="description" className="text-xs text-fg-muted">
+			{description}
+		</Text>
+	) : null
+
+	// Focus overlay: a bare search input + an inline filtered list (RAC ComboBox
+	// only fills its listbox while open, so compose Autocomplete + ListBox here).
+	if (inFocus) {
+		return (
+			<div className="flex flex-col gap-2">
+				<span className="text-heading5 font-medium text-fg">{label}</span>
+				<Autocomplete filter={contains}>
+					<SearchField aria-label={typeof label === 'string' ? label : 'Search'}>
+						<RACInput
+							placeholder={placeholder}
+							className="w-full border-0 bg-transparent p-0 text-3xl font-medium text-fg outline-none placeholder:text-fg-subtle"
+						/>
+					</SearchField>
+					<ListBox
+						selectionMode="single"
+						selectedKeys={selectedKey != null ? new Set([selectedKey]) : new Set()}
+						onSelectionChange={(keys) => {
+							const k = keys === 'all' ? undefined : [...keys][0]
+							onSelectionChange?.(k ?? null)
+						}}
+						renderEmptyState={() => <div className="px-3 py-2 text-sm text-fg-muted">No results</div>}
+						className="mt-2 flex max-h-72 flex-col gap-0.5 overflow-auto overscroll-contain p-1 outline-none"
+					>
+						{children}
+					</ListBox>
+				</Autocomplete>
+				{desc}
+				{errorMessage ? <span className="text-xs text-danger">{errorMessage}</span> : null}
+			</div>
+		)
+	}
+
+	return (
+		// `menuTrigger="focus"` opens the list on focus/click (not only on typing), so
+		// the options are always one interaction away. Consumers can override via props.
+		<RACComboBox
+			menuTrigger="focus"
+			selectedKey={selectedKey}
+			onSelectionChange={onSelectionChange}
+			{...props}
+			className="group flex flex-col gap-2"
+		>
+			<Label className="text-heading5 font-medium text-fg">{label}</Label>
+			<div className="relative">
+				<ComboBoxInput placeholder={placeholder} />
+				{/* RAC uses this Button to toggle the listbox open/closed. */}
+				<RACButton className="absolute inset-y-0 right-0 flex w-11 items-center justify-center rounded-r-lg outline-none data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring">
+					<Chevron />
+				</RACButton>
+			</div>
+			{desc}
+			<FieldError className="text-xs text-danger">{errorMessage}</FieldError>
+			<Popover className="min-w-[var(--trigger-width)] overflow-hidden rounded-lg bg-surface-card shadow-lg">
+				<ListBox
+					className="flex max-h-72 flex-col gap-0.5 overflow-auto overscroll-contain p-1 outline-none"
+					renderEmptyState={() => <div className="px-3 py-2 text-sm text-fg-muted">No results</div>}
+				>
+					{children}
+				</ListBox>
+			</Popover>
+		</RACComboBox>
+	)
+}

package/src/components/dashboard-grid.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react'
+
+/**
+ * DashboardGrid + DashboardTile — responsive 12-column dashboard grid
+ * (port of gs-platform `DashboardGrid`).
+ *
+ * gs-platform's grid is a 12-col CSS grid where each item declares a `width`
+ * (3/4/6/12) and tiles collapse to full width on mobile. We reproduce that with
+ * Tailwind responsive column spans — no SCSS, no external grid lib.
+ *
+ * **Drag-to-reorder is DEFERRED** for this issue: gs-platform implements it with
+ * `@dnd-kit/core` + `@dnd-kit/sortable`, which are not dependencies of this repo
+ * and adding them is out of scope (no dependency bumps). A static responsive grid
+ * is acceptable per the issue spec; the `DashboardTile` API is shaped so a future
+ * sortable wrapper can slot in without changing call sites.
+ *
+ * Presentational only (hard rule #1).
+ */
+
+export type DashboardTileSpan = 3 | 4 | 6 | 12
+
+const SPAN_CLASS: Record<DashboardTileSpan, string> = {
+	// Mobile: always full width. ≥sm: take the requested fraction of 12 cols.
+	3: 'col-span-12 sm:col-span-6 lg:col-span-3',
+	4: 'col-span-12 sm:col-span-6 lg:col-span-4',
+	6: 'col-span-12 sm:col-span-6',
+	12: 'col-span-12',
+}
+
+export type DashboardGridProps = {
+	children: ReactNode
+	className?: string
+}
+
+export function DashboardGrid({ children, className }: DashboardGridProps) {
+	return (
+		<div className={['grid grid-cols-12 gap-4', className].filter(Boolean).join(' ')}>{children}</div>
+	)
+}
+
+export type DashboardTileProps = {
+	/** Column span out of 12 (collapses to full width below `lg`). Default 3. */
+	span?: DashboardTileSpan
+	children: ReactNode
+	className?: string
+}
+
+export function DashboardTile({ span = 3, children, className }: DashboardTileProps) {
+	return <div className={[SPAN_CLASS[span], className].filter(Boolean).join(' ')}>{children}</div>
+}

package/src/components/date-picker.tsx

@@ -20,7 +20,9 @@ import {
 	Popover,
 	Text,
 } from 'react-aria-components'
+import { clsx } from 'clsx'
 import { dateInputClass, segmentClass } from './date-field'
+import { useInFocusOverlay } from './focus-context'
 
 /**
  * DatePicker — a `DateField` with a calendar popover. Built on React Aria
@@ -38,74 +40,86 @@ const Chevron = ({ dir }: { dir: 'left' | 'right' }) => (
 	</svg>
 )
 
+const calendarCellClass =
+	'flex h-9 w-9 cursor-pointer items-center justify-center rounded-md text-sm text-fg outline-none transition-colors ' +
+	'data-[outside-month]:text-fg-subtle data-[hovered]:bg-surface-muted ' +
+	'data-[selected]:bg-fg data-[selected]:text-fg-inverted data-[selected]:font-medium ' +
+	'data-[unavailable]:text-fg-subtle data-[unavailable]:line-through ' +
+	'data-[disabled]:opacity-40 data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring'
+
+function CalendarBody() {
+	return (
+		<Calendar className="w-[17.5rem]">
+			<header className="flex items-center justify-between pb-3">
+				<RACButton slot="previous" className={navButton}>
+					<Chevron dir="left" />
+				</RACButton>
+				<Heading className="text-sm font-medium text-fg" />
+				<RACButton slot="next" className={navButton}>
+					<Chevron dir="right" />
+				</RACButton>
+			</header>
+			<CalendarGrid className="w-full border-collapse">
+				<CalendarGridHeader>
+					{(day) => (
+						<CalendarHeaderCell className="pb-1 text-micro font-medium uppercase tracking-wide text-fg-subtle">
+							{day}
+						</CalendarHeaderCell>
+					)}
+				</CalendarGridHeader>
+				<CalendarGridBody>{(date) => <CalendarCell date={date} className={calendarCellClass} />}</CalendarGridBody>
+			</CalendarGrid>
+		</Calendar>
+	)
+}
+
 export type DatePickerProps<T extends DateValue> = RACDatePickerProps<T> & {
 	label: ReactNode
 	description?: ReactNode
 	errorMessage?: string
 }
 
-export const DatePicker = <T extends DateValue>({ label, description, errorMessage, ...props }: DatePickerProps<T>) => (
-	<RACDatePicker {...props} className="group flex flex-col gap-2">
-		<Label className="text-heading5 font-medium text-fg">{label}</Label>
-		<Group className={`${dateInputClass} pr-2`}>
-			<DateInput className="flex flex-1 items-center gap-0.5">
-				{(segment) => <DateSegment segment={segment} className={segmentClass} />}
-			</DateInput>
-			<RACButton
-				aria-label="Open calendar"
-				className="flex h-8 w-8 shrink-0 items-center justify-center rounded-md text-fg-muted outline-none transition-colors hover:bg-surface-muted hover:text-fg data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring"
-			>
-				<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
-					<rect x="3" y="4" width="18" height="18" rx="2" />
-					<path d="M16 2v4M8 2v4M3 10h18" />
-				</svg>
-			</RACButton>
-		</Group>
-		{description ? (
-			<Text slot="description" className="text-xs text-fg-muted">
-				{description}
-			</Text>
-		) : null}
-		<FieldError className="text-xs text-danger">{errorMessage}</FieldError>
-		<Popover className="rounded-lg border border-border bg-surface p-4 shadow-lg outline-none">
-			<Dialog className="outline-none">
-				<Calendar className="w-[17.5rem]">
-					<header className="flex items-center justify-between pb-3">
-						<RACButton slot="previous" className={navButton}>
-							<Chevron dir="left" />
-						</RACButton>
-						<Heading className="text-sm font-medium text-fg" />
-						<RACButton slot="next" className={navButton}>
-							<Chevron dir="right" />
-						</RACButton>
-					</header>
-					<CalendarGrid className="w-full border-collapse">
-						<CalendarGridHeader>
-							{(day) => (
-								<CalendarHeaderCell className="pb-1 text-micro font-medium uppercase tracking-wide text-fg-subtle">
-									{day}
-								</CalendarHeaderCell>
-							)}
-						</CalendarGridHeader>
-						<CalendarGridBody>
-							{(date) => (
-								<CalendarCell
-									date={date}
-									className={
-										'flex h-9 w-9 cursor-pointer items-center justify-center rounded-md text-sm text-fg outline-none transition-colors ' +
-										'data-[outside-month]:text-fg-subtle ' +
-										'data-[hovered]:bg-surface-muted ' +
-										'data-[selected]:bg-fg data-[selected]:text-fg-inverted data-[selected]:font-medium ' +
-										'data-[unavailable]:text-fg-subtle data-[unavailable]:line-through ' +
-										'data-[disabled]:opacity-40 ' +
-										'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring'
-									}
-								/>
-							)}
-						</CalendarGridBody>
-					</CalendarGrid>
-				</Calendar>
-			</Dialog>
-		</Popover>
-	</RACDatePicker>
-)
+export const DatePicker = <T extends DateValue>({ label, description, errorMessage, ...props }: DatePickerProps<T>) => {
+	// In a focus overlay, show the calendar inline (open) instead of a popover.
+	const inFocus = useInFocusOverlay()
+	return (
+		<RACDatePicker {...props} className="group flex flex-col gap-2">
+			<Label className="text-heading5 font-medium text-fg">{label}</Label>
+			{/* In focus mode the field is bare + large and the calendar is borderless,
+			    so field + calendar read as one seamless editor rather than boxes. */}
+			<Group className={inFocus ? 'flex w-full items-center' : `${dateInputClass} pr-2`}>
+				<DateInput className={clsx('flex flex-1 items-center gap-0.5', inFocus && 'text-3xl font-medium')}>
+					{(segment) => <DateSegment segment={segment} className={segmentClass} />}
+				</DateInput>
+				{inFocus ? null : (
+					<RACButton
+						aria-label="Open calendar"
+						className="flex h-8 w-8 shrink-0 items-center justify-center rounded-md text-fg-muted outline-none transition-colors hover:bg-surface-muted hover:text-fg data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring"
+					>
+						<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+							<rect x="3" y="4" width="18" height="18" rx="2" />
+							<path d="M16 2v4M8 2v4M3 10h18" />
+						</svg>
+					</RACButton>
+				)}
+			</Group>
+			{description ? (
+				<Text slot="description" className="text-xs text-fg-muted">
+					{description}
+				</Text>
+			) : null}
+			<FieldError className="text-xs text-danger">{errorMessage}</FieldError>
+			{inFocus ? (
+				<div className="mt-2 -ml-2">
+					<CalendarBody />
+				</div>
+			) : (
+				<Popover className="rounded-lg border border-border bg-surface p-4 shadow-lg outline-none">
+					<Dialog className="outline-none">
+						<CalendarBody />
+					</Dialog>
+				</Popover>
+			)}
+		</RACDatePicker>
+	)
+}

package/src/components/delivery/delivery-status-module.tsx

@@ -0,0 +1,113 @@
+// @app/ui — delivery status module (issue 17).
+//
+// PRESENTATIONAL "black status module" — the signature delivery-UI surface ported
+// from the gs-platform `FinalOutputsHandoffPanel` (`.statusModule`): a dark
+// inverted surface (white-on-#242423) carrying a status header row, muted status
+// text, an optional progress track with a GREEN progress bar, and optional
+// trailing "ready" pills. Used by BOTH the final-outputs handoff panel and the
+// live delivery-status cards so the two read as one visual language.
+//
+// APP-AGNOSTIC (hard rule #1): no apps/web imports, no API hooks, no i18n. Every
+// string is passed in; the owning surface in apps/web supplies the i18n copy and
+// wires behaviour. Pure markup + Tailwind classes bound to @app/tokens CSS vars.
+//
+// ── Styling (hard rule #3) ────────────────────────────────────────────────────
+// Tailwind + @app/tokens only — NO SCSS, NO raw hex.
+//   gs-platform `--color-text-primary` (#000 module surface) → our `surface-inverted`
+//   gs-platform `--color-background` (white text)            → our `fg-inverted`
+//   gs-platform `--color-brand-green` (#22c55e progress)     → our `success`
+//   gs-platform `--radius-full` (track / pills)              → `rounded-full`
+//   gs-platform `--radius-panel-sm` (module)                 → `rounded-md`
+//
+// ── a11y ──────────────────────────────────────────────────────────────────────
+// White (#fff) on the dark surface (#242423) ≈ 14.9:1 — passes WCAG AA. The muted
+// status text uses `text-white/70` (white at 70% over the dark surface) ≈ 8.6:1 —
+// still AA. (We use the stock `white`/opacity utilities for the muted tints rather
+// than `fg-inverted/NN`: Tailwind cannot inject an alpha channel into an arbitrary
+// `var(--color-…)`, so an opacity modifier on `fg-inverted` would be a no-op; the
+// `fg-inverted` token IS white, so `text-white` is the same colour, alpha-capable.)
+// The green bar (#22c55e on #242423) is a NON-TEXT graphical indicator (~5.6:1,
+// above the 3:1 non-text minimum). The progress track is `aria-hidden`; when a
+// numeric value matters, expose it in the header (text), not the bar.
+
+import type { ReactNode } from 'react'
+import { uic } from '../../utils/uic'
+
+/** The dark status-module shell (inverted surface + white text). */
+export const DeliveryStatusModuleRoot = uic('div', {
+	displayName: 'DeliveryStatusModule',
+	baseClass:
+		'grid gap-3 rounded-md bg-surface-inverted p-4 text-fg-inverted',
+})
+
+export interface DeliveryStatusModuleProps {
+	/** Status header — left-aligned headline (e.g. "Files ready"). */
+	heading: ReactNode
+	/** Optional right-aligned header annotation (e.g. "50 %", "3 ready"). */
+	headingMeta?: ReactNode
+	/** Muted status sentence under the header. */
+	statusText?: ReactNode
+	/**
+	 * Optional progress fraction in [0, 1]. When provided, renders the green
+	 * progress track. Clamped; the track itself is decorative (`aria-hidden`).
+	 */
+	progress?: number
+	/** Optional trailing pills / actions row (e.g. "ready" chips). */
+	children?: ReactNode
+	/** Forwarded test id. */
+	'data-testid'?: string
+}
+
+/**
+ * Black status module with an optional green progress bar. The visual heart of the
+ * delivery UI — stack it under a white output card or use it as a job-status card.
+ */
+export function DeliveryStatusModule({
+	heading,
+	headingMeta,
+	statusText,
+	progress,
+	children,
+	'data-testid': testId,
+}: DeliveryStatusModuleProps): React.ReactNode {
+	const hasProgress = progress != null
+	const pct = hasProgress ? Math.max(0, Math.min(1, progress)) * 100 : 0
+
+	return (
+		<DeliveryStatusModuleRoot data-testid={testId}>
+			<div className="flex items-center justify-between gap-4 text-sm font-medium">
+				<span>{heading}</span>
+				{headingMeta != null ? <span>{headingMeta}</span> : null}
+			</div>
+
+			{statusText != null ? (
+				<p className="m-0 text-xs text-white/70">{statusText}</p>
+			) : null}
+
+			{hasProgress ? (
+				<div
+					className="h-2 overflow-hidden rounded-full bg-white/25"
+					aria-hidden="true"
+				>
+					<span
+						className="block h-full rounded-full bg-success transition-[width]"
+						style={{ width: `${pct}%` }}
+					/>
+				</div>
+			) : null}
+
+			{children != null ? (
+				<div className="flex flex-wrap items-center gap-2 text-xs text-white/80">
+					{children}
+				</div>
+			) : null}
+		</DeliveryStatusModuleRoot>
+	)
+}
+
+/** A hairline "ready" pill for the trailing actions row (inverted palette). */
+export const DeliveryStatusPill = uic('span', {
+	displayName: 'DeliveryStatusPill',
+	baseClass:
+		'inline-flex min-h-5 items-center rounded-full border border-white/30 px-3',
+})