@dungle-scrubs/admin-ui-soft 0.0.0-stage → 0.1.0

package/dist/compositions/decision-queue/decision-queue.js

@@ -0,0 +1,478 @@
+import { Alert, AlertAction, AlertDescription, AlertTitle } from "../../components/ui/alert.js";
+import { Spinner } from "../../components/ui/spinner.js";
+import { Button } from "../../components/ui/button.js";
+import { Badge } from "../../components/ui/badge.js";
+import { ButtonGroup } from "../../components/ui/button-group.js";
+import { Card, CardContent, CardHeader } from "../../components/ui/card.js";
+import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from "../../components/ui/empty.js";
+import { Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from "../../components/ui/item.js";
+import { Skeleton } from "../../components/ui/skeleton.js";
+import { ConfirmAction } from "../confirm-action/confirm-action.js";
+import { TRIAGE_TARGET_ATTRIBUTE, TriageKbd, TriageKeyHints, triageShortcuts, useTriageKeyboard } from "../../lib/triage-keys.js";
+import * as React from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "cn";
+import { AlertCircleIcon, ChevronRightIcon } from "lucide-react";
+import { useControllableValue, useLatest, useMap } from "ahooks";
+//#region src/compositions/decision-queue/decision-queue.tsx
+const groupKey = (groupId) => `group:${groupId}`;
+const itemKey = (itemId) => `item:${itemId}`;
+function plural(count, noun, localized = false) {
+	return `${localized ? count.toLocaleString() : count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function defaultConsequence(label, { count, group }) {
+	return `"${label}" will apply to ${plural(count, "item")} in ${group.title}.`;
+}
+/**
+* The items a target should fall back to when the one the cursor was on is
+* gone (decided and refetched, or its group collapsed): the first item at or
+* after the old position, else the last item, else any target there.
+*/
+function fallbackIndex(targets, previousIndex) {
+	if (targets.length === 0) return -1;
+	const start = Math.min(Math.max(previousIndex, 0), targets.length - 1);
+	for (let index = start; index < targets.length; index += 1) if (targets[index]?.kind === "item") return index;
+	for (let index = start - 1; index >= 0; index -= 1) if (targets[index]?.kind === "item") return index;
+	return start;
+}
+/**
+* Grouped items for per-item or bulk decisions, operable entirely from the
+* keyboard: `j`/`k` or the arrow keys move the cursor across group headers and
+* items, Enter on a group header expands or collapses it, and `keymap` keys
+* decide. Keys are ignored while focus is in a text field. Destructive and
+* bulk decisions go through ConfirmAction first. A failed decision shows its
+* error in the queue until the owner dismisses it. In a queue narrower than
+* 32rem (a phone) each item stacks, its decisions span its width at touch
+* size, and the key hints are hidden; on a touch screen they are hidden at
+* any width.
+*/
+function DecisionQueue(props) {
+	const { groups, decisions, onDecide, bulk = false, defaultCollapsed = false, keymap, isPending, decisionError, onDismissDecisionError, label = "Decision queue", isLoading = false, error, emptyLabel = "Nothing to decide", className } = props;
+	const baseId = React.useId();
+	const lastIndex = React.useRef(0);
+	const [focusedItemId, setFocusedItemId] = useControllableValue(props, {
+		valuePropName: "focusedId",
+		defaultValuePropName: "defaultFocusedId",
+		trigger: "onFocusChange",
+		defaultValue: null
+	});
+	const [headerFocus, setHeaderFocus] = React.useState(null);
+	const [collapseRule] = React.useState(() => defaultCollapsed === true ? true : new Set(defaultCollapsed || []));
+	const [toggled, { set: setToggled }] = useMap();
+	const isCollapsed = React.useCallback((groupId) => toggled.get(groupId) ?? (collapseRule === true || collapseRule.has(groupId)), [toggled, collapseRule]);
+	const [confirmation, setConfirmation] = React.useState(null);
+	const [confirmOpen, setConfirmOpen] = React.useState(false);
+	const pending = React.useCallback((itemId) => isPending?.(itemId) ?? false, [isPending]);
+	const decisionsByKey = React.useMemo(() => new Map(decisions.map((decision) => [decision.key, decision])), [decisions]);
+	const bulkDecisions = React.useMemo(() => decisions.filter((decision) => decision.bulk !== false), [decisions]);
+	const shortcutsByDecision = React.useMemo(() => triageShortcuts(keymap, (decision) => decisionsByKey.has(decision)), [keymap, decisionsByKey]);
+	const targets = React.useMemo(() => {
+		const list = [];
+		for (const group of groups) {
+			list.push({
+				kind: "group",
+				key: groupKey(group.id),
+				group
+			});
+			if (isCollapsed(group.id)) continue;
+			group.items.forEach((item, index) => {
+				list.push({
+					kind: "item",
+					key: itemKey(item.id),
+					group,
+					item,
+					position: index + 1
+				});
+			});
+		}
+		return list;
+	}, [groups, isCollapsed]);
+	const intendedKey = headerFocus && headerFocus.itemId === focusedItemId ? groupKey(headerFocus.groupId) : focusedItemId != null ? itemKey(focusedItemId) : null;
+	let activeIndex = intendedKey ? targets.findIndex((target) => target.key === intendedKey) : -1;
+	const intendedMissing = intendedKey !== null && activeIndex === -1;
+	if (intendedMissing) activeIndex = fallbackIndex(targets, lastIndex.current);
+	else if (activeIndex === -1) {
+		activeIndex = targets.findIndex((target) => target.kind === "item");
+		if (activeIndex === -1) activeIndex = targets.length > 0 ? 0 : -1;
+	}
+	const active = activeIndex >= 0 ? targets[activeIndex] : void 0;
+	const activeKey = useLatest(active?.key);
+	const failedIds = React.useMemo(() => new Set(decisionError?.itemIds ?? []), [decisionError]);
+	const failedGroupId = decisionError ? groups.find((group) => group.items.some((item) => failedIds.has(item.id)))?.id ?? null : null;
+	const failureId = `${baseId}-decision-error`;
+	const describe = React.useCallback((target) => {
+		if (target.kind === "item") return `${target.position} of ${target.group.items.length} in ${target.group.title}`;
+		return `${target.group.title}, ${plural(target.group.items.length, "item")}`;
+	}, []);
+	const activate = React.useCallback((target) => {
+		if (target.kind === "group") {
+			setHeaderFocus({
+				groupId: target.group.id,
+				itemId: focusedItemId
+			});
+			return;
+		}
+		setHeaderFocus(null);
+		if (focusedItemId !== target.item.id) setFocusedItemId(target.item.id);
+	}, [focusedItemId, setFocusedItemId]);
+	const findTarget = (key) => key === null ? void 0 : targets.find((target) => target.key === key);
+	const { containerRef, registerTarget, targetElement, targetKeyOf, focusLost, cursorVisible, announcement, announce, handlers } = useTriageKeyboard({
+		keymap,
+		hasAction: (decision) => decisionsByKey.has(decision),
+		activeKey: active?.key ?? null,
+		modalOpen: confirmOpen,
+		onAction: (key, targetKey) => {
+			const decision = decisionsByKey.get(key);
+			const target = findTarget(targetKey);
+			if (!decision || !target) return;
+			if (target.kind === "item") decide([target.item.id], decision, target.group, false);
+			else if (bulk && target.group.bulk !== false && decision.bulk !== false) decide(target.group.items.map((item) => item.id), decision, target.group, true);
+		},
+		onStep: (fromKey, step) => {
+			const current = findTarget(fromKey);
+			const index = current ? targets.indexOf(current) : -1;
+			const next = targets[Math.min(Math.max(index + step, 0), targets.length - 1)];
+			if (next) focusTarget(next);
+		},
+		onOtherKey: (event, element) => {
+			if (event.key !== "Enter") return false;
+			const target = findTarget(targetKeyOf(element));
+			if (target?.kind === "group" && element.getAttribute("data-queue-target") === target.key) {
+				toggleGroup(target.group);
+				return true;
+			}
+			return false;
+		},
+		onFocusTarget: (key, entered) => {
+			const target = findTarget(key);
+			if (!target) return;
+			activate(target);
+			if (entered) announce(describe(target));
+		}
+	});
+	React.useEffect(() => {
+		lastIndex.current = Math.max(activeIndex, 0);
+		if (!active) return;
+		if (intendedMissing) {
+			activate(active);
+			announce(describe(active));
+		}
+		const element = targetElement(active.key);
+		if (element && focusLost()) {
+			activate(active);
+			announce(describe(active));
+			element.focus();
+		}
+	}, [
+		activeIndex,
+		intendedMissing,
+		active,
+		activate,
+		describe,
+		announce,
+		targetElement,
+		focusLost
+	]);
+	const focusTarget = (target) => {
+		activate(target);
+		announce(describe(target));
+		targetElement(target.key)?.focus();
+	};
+	const toggleGroup = (group) => {
+		const collapse = !isCollapsed(group.id);
+		setToggled(group.id, collapse);
+		announce(`${group.title} ${collapse ? "collapsed" : "expanded"}`);
+	};
+	const decide = (itemIds, decision, group, isBulk) => {
+		if (itemIds.length === 0 || itemIds.some(pending)) return;
+		if (decision.destructive || isBulk) {
+			setConfirmation({
+				itemIds,
+				decision,
+				group,
+				bulk: isBulk
+			});
+			setConfirmOpen(true);
+			return;
+		}
+		onDecide(itemIds, decision.key);
+	};
+	const dismissFailure = () => {
+		if (activeKey.current) targetElement(activeKey.current)?.focus();
+		onDismissDecisionError?.();
+	};
+	const failureAlert = (failure) => /* @__PURE__ */ jsxs(Alert, {
+		variant: "destructive",
+		"data-slot": "decision-queue-decision-error",
+		children: [
+			/* @__PURE__ */ jsx(AlertCircleIcon, { "aria-hidden": "true" }),
+			/* @__PURE__ */ jsxs(AlertTitle, { children: ["Decision failed for ", plural(failure.itemIds.length, "item")] }),
+			/* @__PURE__ */ jsx(AlertDescription, {
+				id: failureId,
+				children: failure.message
+			}),
+			onDismissDecisionError ? /* @__PURE__ */ jsx(AlertAction, { children: /* @__PURE__ */ jsx(Button, {
+				type: "button",
+				size: "xs",
+				variant: "outline",
+				className: "text-foreground",
+				onClick: dismissFailure,
+				children: "Dismiss"
+			}) }) : null
+		]
+	});
+	const decisionButtons = (group, itemIds, isBulk, disabled, tabbable) => (isBulk ? bulkDecisions : decisions).map((decision) => {
+		const shortcuts = shortcutsByDecision.get(decision.key) ?? [];
+		return /* @__PURE__ */ jsxs(Button, {
+			type: "button",
+			size: "sm",
+			variant: decision.tone ?? "outline",
+			className: cn("pointer-coarse:h-8 @max-lg/decision-queue:h-8", !isBulk && "@max-lg/decision-queue:flex-1", decision.tone === void 0 && decision.destructive && "text-destructive hover:bg-destructive/10 hover:text-destructive dark:hover:bg-destructive/20"),
+			disabled,
+			tabIndex: tabbable ? 0 : -1,
+			"aria-keyshortcuts": shortcuts.length > 0 ? shortcuts.join(" ") : void 0,
+			onClick: () => decide(itemIds, decision, group, isBulk),
+			children: [isBulk ? `${decision.label} all` : decision.label, !isBulk && shortcuts[0] ? /* @__PURE__ */ jsx(TriageKbd, {
+				shortcut: shortcuts[0],
+				className: "@max-lg/decision-queue:hidden"
+			}) : null]
+		}, decision.key);
+	});
+	const totalItems = groups.reduce((sum, group) => sum + group.items.length, 0);
+	const hintId = `${baseId}-hint`;
+	const confirmCount = confirmation?.itemIds.length ?? 0;
+	const confirmLabel = confirmation?.decision.label ?? "";
+	return /* @__PURE__ */ jsxs("section", {
+		ref: containerRef,
+		"aria-label": label,
+		"aria-describedby": hintId,
+		"aria-busy": isLoading || void 0,
+		"data-slot": "decision-queue",
+		className: cn("@container/decision-queue flex w-full flex-col gap-3 text-xs/relaxed", className),
+		...handlers,
+		children: [
+			/* @__PURE__ */ jsx(TriageKeyHints, {
+				id: hintId,
+				hidden: totalItems === 0,
+				"data-slot": "decision-queue-hint",
+				keymap,
+				className: "@max-lg/decision-queue:hidden",
+				hints: [{
+					key: "Enter",
+					label: "expand or collapse a group"
+				}, ...decisions.flatMap((decision) => {
+					const shortcut = shortcutsByDecision.get(decision.key)?.[0];
+					return shortcut ? [{
+						key: shortcut,
+						label: decision.label.toLowerCase()
+					}] : [];
+				})]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				"aria-live": "polite",
+				"aria-atomic": "true",
+				className: "sr-only",
+				children: announcement
+			}),
+			error ? /* @__PURE__ */ jsxs(Alert, {
+				variant: "destructive",
+				"data-slot": "decision-queue-error",
+				children: [/* @__PURE__ */ jsx(AlertCircleIcon, { "aria-hidden": "true" }), /* @__PURE__ */ jsx(AlertTitle, { children: error })]
+			}) : null,
+			decisionError && failedGroupId === null ? failureAlert(decisionError) : null,
+			isLoading && groups.length === 0 ? /* @__PURE__ */ jsx(Card, {
+				size: "sm",
+				"data-slot": "decision-queue-loading",
+				children: /* @__PURE__ */ jsxs(CardContent, {
+					className: "flex flex-col gap-2",
+					children: [
+						/* @__PURE__ */ jsx("span", {
+							className: "sr-only",
+							children: "Loading"
+						}),
+						/* @__PURE__ */ jsx(Skeleton, { className: "h-4 w-32" }),
+						[
+							0,
+							1,
+							2
+						].map((row) => /* @__PURE__ */ jsx(Skeleton, { className: "h-10 w-full" }, row))
+					]
+				})
+			}) : null,
+			!isLoading && totalItems === 0 && !error ? /* @__PURE__ */ jsx(Empty, {
+				"data-slot": "decision-queue-empty",
+				className: "border",
+				children: /* @__PURE__ */ jsxs(EmptyHeader, { children: [/* @__PURE__ */ jsx(EmptyTitle, { children: emptyLabel }), /* @__PURE__ */ jsx(EmptyDescription, { children: "New items appear here as they arrive." })] })
+			}) : null,
+			totalItems > 0 ? groups.map((group) => {
+				const collapsed = isCollapsed(group.id);
+				const headerKey = groupKey(group.id);
+				const headerActive = active?.key === headerKey;
+				const listId = `${baseId}-${group.id}-items`;
+				const titleId = `${baseId}-${group.id}-title`;
+				const descriptionId = `${baseId}-${group.id}-description`;
+				const groupPending = group.items.some((item) => pending(item.id));
+				const countOverride = typeof group.count === "number" && Number.isInteger(group.count) && group.count >= 0 ? group.count : void 0;
+				const count = countOverride ?? group.items.length;
+				const titleRow = /* @__PURE__ */ jsxs(Fragment$1, { children: [
+					/* @__PURE__ */ jsx(ChevronRightIcon, {
+						"aria-hidden": "true",
+						className: cn("size-3.5 shrink-0 text-muted-foreground transition-transform", !collapsed && "rotate-90")
+					}),
+					/* @__PURE__ */ jsx("span", {
+						id: titleId,
+						className: cn("truncate font-heading text-sm font-medium", (group.badges || group.headerAction) && "min-w-12"),
+						children: group.title
+					}),
+					/* @__PURE__ */ jsx(Badge, {
+						variant: "secondary",
+						children: countOverride !== void 0 ? count.toLocaleString() : count
+					})
+				] });
+				return /* @__PURE__ */ jsxs(Card, {
+					size: "sm",
+					"data-slot": "decision-queue-group",
+					role: "group",
+					"aria-labelledby": titleId,
+					className: "gap-2",
+					children: [
+						/* @__PURE__ */ jsxs(CardHeader, {
+							"data-slot": "decision-queue-group-header",
+							"data-cursor": headerActive && cursorVisible || void 0,
+							className: "mx-2 -my-1 flex flex-wrap items-center gap-2 rounded-md px-1 py-1 transition-colors duration-100 data-cursor:bg-muted/50",
+							children: [
+								/* @__PURE__ */ jsxs("button", {
+									ref: registerTarget(headerKey),
+									type: "button",
+									[TRIAGE_TARGET_ATTRIBUTE]: headerKey,
+									"data-active": headerActive || void 0,
+									tabIndex: headerActive ? 0 : -1,
+									"aria-label": `${group.title}, ${plural(count, "item", countOverride !== void 0)}`,
+									"aria-describedby": group.description ? descriptionId : void 0,
+									"aria-expanded": !collapsed,
+									"aria-controls": collapsed ? void 0 : listId,
+									onClick: () => toggleGroup(group),
+									className: cn("flex min-w-0 grow basis-40 flex-wrap items-center gap-x-1.5 gap-y-0.5 rounded-md px-1 py-0.5 text-left outline-none", !group.badges && "@lg/decision-queue:flex-nowrap", group.headerAction && "@max-lg/decision-queue:basis-0"),
+									children: [
+										group.badges ? /* @__PURE__ */ jsx("span", {
+											className: "flex min-w-0 basis-full items-center gap-x-1.5",
+											children: titleRow
+										}) : titleRow,
+										group.badges ? /* @__PURE__ */ jsx("span", {
+											className: "flex min-w-0 basis-full flex-wrap items-center gap-1 pl-5 [&_[data-slot=badge]]:h-auto [&_[data-slot=badge]]:min-h-5 [&_[data-slot=badge]]:max-w-full [&_[data-slot=badge]]:wrap-anywhere [&_[data-slot=badge]]:whitespace-normal",
+											children: group.badges
+										}) : null,
+										group.description ? /* @__PURE__ */ jsx("span", {
+											id: descriptionId,
+											className: "basis-full pl-5 text-muted-foreground @lg/decision-queue:basis-auto @lg/decision-queue:truncate @lg/decision-queue:pl-0",
+											children: group.description
+										}) : null
+									]
+								}),
+								group.headerAction ? /* @__PURE__ */ jsx("div", {
+									[TRIAGE_TARGET_ATTRIBUTE]: headerKey,
+									className: "min-w-0 max-w-full shrink-0 @max-lg/decision-queue:self-start @max-lg/decision-queue:py-0.5",
+									children: group.headerAction
+								}) : null,
+								bulk && group.bulk !== false && bulkDecisions.length > 0 && group.items.length > 0 ? /* @__PURE__ */ jsx(ButtonGroup, {
+									"aria-label": `Decide all in ${group.title}`,
+									className: cn(group.headerAction && "@max-lg/decision-queue:basis-full"),
+									children: decisionButtons(group, group.items.map((item) => item.id), true, groupPending, headerActive)
+								}) : null
+							]
+						}),
+						decisionError && failedGroupId === group.id ? /* @__PURE__ */ jsx("div", {
+							className: "px-(--card-spacing)",
+							children: failureAlert(decisionError)
+						}) : null,
+						collapsed ? null : /* @__PURE__ */ jsx(CardContent, {
+							id: listId,
+							children: group.items.length === 0 ? /* @__PURE__ */ jsx("p", {
+								className: "pl-6 text-muted-foreground",
+								children: "No items"
+							}) : /* @__PURE__ */ jsx("ul", {
+								"aria-labelledby": titleId,
+								className: "flex flex-col gap-1",
+								children: group.items.map((item) => {
+									const key = itemKey(item.id);
+									const isActive = active?.key === key;
+									const isItemPending = pending(item.id);
+									const isFailed = failedIds.has(item.id);
+									const primaryId = `${baseId}-${item.id}-primary`;
+									const secondaryId = `${baseId}-${item.id}-secondary`;
+									const describedBy = [item.secondary ? secondaryId : null, isFailed ? failureId : null].filter(Boolean);
+									return /* @__PURE__ */ jsxs(Item, {
+										ref: registerTarget(key),
+										size: "sm",
+										variant: "outline",
+										render: /* @__PURE__ */ jsx("li", {}),
+										[TRIAGE_TARGET_ATTRIBUTE]: key,
+										"data-active": isActive || void 0,
+										"data-cursor": isActive && cursorVisible || void 0,
+										"data-pending": isItemPending || void 0,
+										"data-failed": isFailed || void 0,
+										tabIndex: isActive ? 0 : -1,
+										"aria-labelledby": primaryId,
+										"aria-describedby": describedBy.length > 0 ? describedBy.join(" ") : void 0,
+										"aria-busy": isItemPending || void 0,
+										className: "focus-visible:ring-0 data-cursor:transition-none data-cursor:border-ring data-cursor:bg-muted/50 data-failed:not-data-cursor:border-destructive/60",
+										children: [
+											/* @__PURE__ */ jsxs(ItemContent, {
+												className: "min-w-40 basis-48",
+												children: [/* @__PURE__ */ jsx(ItemTitle, {
+													id: primaryId,
+													children: item.primary
+												}), item.secondary ? /* @__PURE__ */ jsx(ItemDescription, {
+													id: secondaryId,
+													children: item.secondary
+												}) : null]
+											}),
+											item.meta || isItemPending ? /* @__PURE__ */ jsx("div", {
+												className: "shrink-0 basis-full text-muted-foreground @max-lg/decision-queue:-mt-1.5 @lg/decision-queue:basis-auto",
+												children: isItemPending ? /* @__PURE__ */ jsx(Spinner, {
+													"aria-label": "Pending",
+													className: "size-3.5"
+												}) : item.meta
+											}) : null,
+											/* @__PURE__ */ jsx(ItemActions, {
+												className: "basis-full @lg/decision-queue:basis-auto",
+												children: /* @__PURE__ */ jsx(ButtonGroup, {
+													"aria-label": "Decide",
+													className: "w-full @lg/decision-queue:w-fit",
+													children: decisionButtons(group, [item.id], false, isItemPending, isActive)
+												})
+											})
+										]
+									}, item.id);
+								})
+							})
+						})
+					]
+				}, group.id);
+			}) : null,
+			/* @__PURE__ */ jsx(ConfirmAction, {
+				open: confirmOpen,
+				onOpenChange: setConfirmOpen,
+				tone: confirmation?.decision.destructive ? "destructive" : "default",
+				title: confirmation?.bulk ? `${confirmLabel} all ${plural(confirmCount, "item")} in ${confirmation.group.title}?` : `${confirmLabel} ${plural(confirmCount, "item")}?`,
+				consequence: confirmation ? confirmation.decision.consequence?.({
+					count: confirmCount,
+					group: confirmation.group
+				}) ?? defaultConsequence(confirmLabel, {
+					count: confirmCount,
+					group: confirmation.group
+				}) : "",
+				confirmLabel: confirmCount > 1 ? `${confirmLabel} ${confirmCount}` : confirmLabel,
+				isPending: confirmation?.itemIds.some(pending) ?? false,
+				finalFocus: () => activeKey.current && targetElement(activeKey.current) || true,
+				onConfirm: () => {
+					if (!confirmation) return;
+					setConfirmOpen(false);
+					onDecide(confirmation.itemIds, confirmation.decision.key);
+				}
+			})
+		]
+	});
+}
+//#endregion
+export { DecisionQueue };

package/dist/compositions/event-feed/event-feed.d.ts

@@ -0,0 +1,59 @@
+import { StatusTone } from "../../lib/status-tone.js";
+import * as React from "react";
+//#region src/compositions/event-feed/event-feed.d.ts
+export type EventFeedTone = StatusTone;
+export interface EventFeedAction {
+  /** The button's label, for example "Retry" or "Open". */
+  label: string;
+  /** While true, the button is disabled and shows a spinner. */
+  isPending?: boolean;
+}
+export interface EventFeedEvent {
+  id: string;
+  /** When it happened, as the app wants it shown, for example "09:12" or "Yesterday". */
+  time: string;
+  /** The same moment, machine-readable (ISO 8601), for the `<time>` element. */
+  dateTime?: string;
+  /** What kind of event it is, shown as a badge, for example "approve" or "gate". */
+  kind: string;
+  /** One line saying what happened. */
+  summary: React.ReactNode;
+  /** How the event reads at a glance. Defaults to `neutral`. */
+  tone?: EventFeedTone;
+  /** Supporting text under the summary. */
+  detail?: React.ReactNode;
+  /** A follow-up the owner can take from the event. Shown only with `onAction`. */
+  action?: EventFeedAction;
+}
+export interface EventFeedProps {
+  /** The events, in the order to show them (usually newest first). */
+  events: readonly EventFeedEvent[];
+  /** Runs an event's `action`. */
+  onAction?: (eventId: string) => void;
+  /** Text shown when there are no events. */
+  emptyLabel?: string;
+  /** Accessible name of the feed. */
+  label?: string;
+  /** Show placeholder rows while the first load is in flight. */
+  isLoading?: boolean;
+  /**
+   * Plain-text load error. With events on screen they stay visible below it,
+   * as the last good data.
+   */
+  error?: string;
+  /** Offer a retry next to `error`. Retrying is the owner's action. */
+  onRetry?: () => void;
+  /**
+   * Classes for the root. Give it a height or a maximum height (for example
+   * `h-96` or `max-h-96`, or a flex parent that sets one) and the events
+   * scroll inside it.
+   */
+  className?: string;
+}
+/**
+ * A timeline of events (activity, gate events, alerts): each shows its time,
+ * kind, summary and tone, with optional detail and a follow-up action. It
+ * scrolls inside whatever height the app gives it.
+ */
+export declare function EventFeed({ events, onAction, emptyLabel, label, isLoading, error, onRetry, className }: EventFeedProps): React.JSX.Element;
+//#endregion

package/dist/compositions/event-feed/event-feed.js

@@ -0,0 +1,105 @@
+import { Spinner } from "../../components/ui/spinner.js";
+import { Button } from "../../components/ui/button.js";
+import { Badge } from "../../components/ui/badge.js";
+import { Item, ItemActions, ItemContent, ItemDescription, ItemMedia, ItemTitle } from "../../components/ui/item.js";
+import { ScrollArea } from "../../components/ui/scroll-area.js";
+import { ToneIcon } from "../../lib/status-tone.js";
+import { EmptyState, ErrorState, Loading } from "../state-blocks/state-blocks.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "cn";
+//#region src/compositions/event-feed/event-feed.tsx
+/**
+* A timeline of events (activity, gate events, alerts): each shows its time,
+* kind, summary and tone, with optional detail and a follow-up action. It
+* scrolls inside whatever height the app gives it.
+*/
+function EventFeed({ events, onAction, emptyLabel = "No events yet", label = "Events", isLoading = false, error, onRetry, className }) {
+	const baseId = React.useId();
+	const hasEvents = events.length > 0;
+	return /* @__PURE__ */ jsxs("section", {
+		"aria-label": label,
+		"aria-busy": isLoading || void 0,
+		"data-slot": "event-feed",
+		className: cn("@container/event-feed flex min-h-0 w-full flex-col gap-3 text-xs/relaxed", className),
+		children: [
+			error ? /* @__PURE__ */ jsx(ErrorState, {
+				title: error,
+				description: hasEvents ? "Showing the last events loaded." : void 0,
+				onRetry
+			}) : null,
+			isLoading && !hasEvents ? /* @__PURE__ */ jsx(Loading, { label: `Loading ${label.toLowerCase()}` }) : null,
+			!isLoading && !hasEvents && !error ? /* @__PURE__ */ jsx(EmptyState, { title: emptyLabel }) : null,
+			hasEvents ? /* @__PURE__ */ jsx(ScrollArea, {
+				"data-slot": "event-feed-scroll",
+				className: "group/event-feed-scroll flex min-h-0 flex-1 flex-col rounded-md *:data-[slot=scroll-area-viewport]:min-h-0 *:data-[slot=scroll-area-viewport]:flex-1 *:data-[slot=scroll-area-viewport]:focus-visible:ring-2 *:data-[slot=scroll-area-viewport]:focus-visible:ring-ring/30",
+				children: /* @__PURE__ */ jsx("ol", {
+					"aria-label": label,
+					className: "flex flex-col group-data-[has-overflow-y]/event-feed-scroll:pr-3",
+					children: events.map((event) => {
+						const tone = event.tone ?? "neutral";
+						const summaryId = `${baseId}-${event.id}-summary`;
+						const action = onAction ? event.action : void 0;
+						return /* @__PURE__ */ jsx("li", {
+							"data-slot": "event-feed-event",
+							"data-tone": tone,
+							className: "border-b last:border-b-0",
+							children: /* @__PURE__ */ jsxs(Item, {
+								size: "sm",
+								className: "items-start rounded-none px-1",
+								children: [
+									/* @__PURE__ */ jsx(ItemMedia, {
+										className: "pt-0.5",
+										children: /* @__PURE__ */ jsx(ToneIcon, {
+											tone,
+											className: "size-3.5"
+										})
+									}),
+									/* @__PURE__ */ jsxs(ItemContent, {
+										className: "min-w-0 gap-1",
+										children: [/* @__PURE__ */ jsx(ItemTitle, {
+											id: summaryId,
+											className: "line-clamp-none w-auto",
+											children: event.summary
+										}), /* @__PURE__ */ jsxs("div", {
+											className: "flex min-w-0 items-start gap-2",
+											children: [/* @__PURE__ */ jsx(Badge, {
+												variant: tone === "critical" ? "destructive" : "outline",
+												children: event.kind
+											}), event.detail ? /* @__PURE__ */ jsx(ItemDescription, {
+												className: "line-clamp-none min-w-0 flex-1",
+												children: event.detail
+											}) : null]
+										})]
+									}),
+									/* @__PURE__ */ jsxs(ItemActions, {
+										className: "flex-col items-end gap-1 @lg/event-feed:flex-row-reverse @lg/event-feed:items-center @lg/event-feed:gap-2",
+										children: [/* @__PURE__ */ jsx("time", {
+											dateTime: event.dateTime,
+											className: "text-muted-foreground tabular-nums",
+											children: event.time
+										}), action ? /* @__PURE__ */ jsxs(Button, {
+											type: "button",
+											size: "sm",
+											variant: "outline",
+											className: "@lg/event-feed:-my-0.5",
+											disabled: action.isPending,
+											"aria-describedby": summaryId,
+											onClick: () => onAction?.(event.id),
+											children: [action.isPending ? /* @__PURE__ */ jsx(Spinner, {
+												"data-icon": "inline-start",
+												"aria-hidden": "true"
+											}) : null, action.label]
+										}) : null]
+									})
+								]
+							})
+						}, event.id);
+					})
+				})
+			}) : null
+		]
+	});
+}
+//#endregion
+export { EventFeed };

package/dist/compositions/feedback.d.ts

@@ -0,0 +1,20 @@
+import { Dialog } from "../components/ui/dialog.js";
+import { Badge, Tone } from "../components/ui/badge.js";
+import { ComponentProps, ReactElement, ReactNode } from "react";
+//#region src/compositions/feedback.d.ts
+export interface BannerProps extends Omit<ComponentProps<"div">, "title"> {
+  readonly dismissLabel?: string;
+  readonly onDismiss?: () => void;
+  readonly title: ReactNode;
+  readonly tone?: Tone;
+}
+export declare function Banner({ children, className, dismissLabel, onDismiss, title, tone, ...props }: BannerProps): ReactElement;
+export interface ModalProps extends Pick<ComponentProps<typeof Dialog>, "open" | "onOpenChange" | "defaultOpen"> {
+  readonly actions?: ReactNode;
+  readonly children: ReactNode;
+  readonly description: ReactNode;
+  readonly title: ReactNode;
+  readonly trigger?: ReactNode;
+}
+export declare function Modal({ actions, children, description, title, trigger, ...props }: ModalProps): ReactElement;
+//#endregion