@lar-works/design-system 0.2.1 → 0.3.0

package/src/display/RichText.tsx

@@ -0,0 +1,114 @@
+// Renders a GitHub or Azure DevOps description or comment the way the provider shows it. Markdown is
+// GitHub-flavoured and may hold raw HTML; an Azure DevOps field may be HTML. Both go through the same
+// sanitizer, then images become links (the page never loads a remote image) and links open in a new tab. The output
+// never makes its container scroll sideways.
+import type { Element, ElementContent, Root } from 'hast';
+import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
+import type { ReactNode } from 'react';
+import Markdown from 'react-markdown';
+import { Fragment, jsx, jsxs } from 'react/jsx-runtime';
+import rehypeParse from 'rehype-parse';
+import rehypeRaw from 'rehype-raw';
+import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
+import remarkGfm from 'remark-gfm';
+import { unified } from 'unified';
+import type { PluggableList } from 'unified';
+
+export type RichTextFormat = 'markdown' | 'html';
+
+const link = (properties: Element['properties'], children: ElementContent[]): Element => ({
+    type: 'element',
+    tagName: 'a',
+    properties: { ...properties, target: '_blank', rel: ['noopener', 'noreferrer'] },
+    children,
+});
+
+/** Turns every image into a link to it and gives every link a new tab. An image inside a link, or without a
+ *  usable source, becomes its text, since a link cannot hold a link. */
+function rehypeImagesAsLinks() {
+    const walk = (node: Root | Element, inLink: boolean): void => {
+        node.children = node.children.map((child) => {
+            if (child.type !== 'element') return child;
+
+            if (child.tagName === 'img') {
+                const src = typeof child.properties.src === 'string' ? child.properties.src : '';
+                const text: ElementContent = { type: 'text', value: String(child.properties.alt || src) };
+
+                return src && !inLink ? link({ href: src }, [text]) : text;
+            }
+
+            walk(child, inLink || child.tagName === 'a');
+
+            return child.tagName === 'a' ? link(child.properties, child.children) : child;
+        });
+    };
+
+    return (tree: Root) => walk(tree, false);
+}
+
+// The default schema is GitHub's: it keeps <details>, tables and task-list checkboxes and drops scripts,
+// handlers, javascript: URLs, iframes and styles. It keeps a dropped <style>'s text, so strip that element whole.
+const schema = { ...defaultSchema, strip: [...(defaultSchema.strip ?? []), 'style'] };
+const rehypePlugins: PluggableList = [rehypeRaw, [rehypeSanitize, schema], rehypeImagesAsLinks];
+const htmlProcessor = unified()
+    .use(rehypeParse, { fragment: true })
+    .use(rehypeSanitize, schema)
+    .use(rehypeImagesAsLinks);
+
+// Tailwind has no typography plugin and its preflight resets headings, lists and tables, so the elements a
+// provider's text holds are styled here.
+const body = [
+    'min-w-0 max-w-full text-sm leading-relaxed break-words [overflow-wrap:anywhere]',
+    '[&>:first-child]:mt-0 [&>:last-child]:mb-0 [&_p]:my-2 [&_ul]:my-2 [&_ol]:my-2 [&_blockquote]:my-2',
+    '[&_h1]:mt-4 [&_h1]:mb-2 [&_h1]:text-lg [&_h1]:font-semibold [&_h2]:mt-4 [&_h2]:mb-2 [&_h2]:text-base [&_h2]:font-semibold',
+    '[&_h3]:mt-3 [&_h3]:mb-1.5 [&_h3]:font-semibold [&_h4]:mt-3 [&_h4]:mb-1.5 [&_h4]:font-semibold [&_h5]:font-semibold [&_h6]:font-semibold',
+    '[&_ul]:list-disc [&_ul]:ps-6 [&_ol]:list-decimal [&_ol]:ps-6 [&_li]:my-0.5 [&_.task-list-item]:list-none [&_.task-list-item]:ms-[-1.5rem] [&_input]:me-1.5',
+    '[&_a]:text-(--lar-info-text) [&_a]:underline [&_a]:underline-offset-2',
+    '[&_blockquote]:border-s-2 [&_blockquote]:ps-3 [&_blockquote]:text-base-700',
+    '[&_hr]:my-4',
+    '[&_pre]:my-2 [&_pre]:max-w-full [&_pre]:overflow-x-hidden [&_pre]:whitespace-pre-wrap [&_pre]:rounded-md [&_pre]:bg-base-200 [&_pre]:p-3 [&_pre]:font-mono [&_pre]:text-xs',
+    '[&_:not(pre)>code]:rounded [&_:not(pre)>code]:bg-base-200 [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:py-0.5 [&_:not(pre)>code]:font-mono [&_:not(pre)>code]:text-xs',
+    '[&_table]:my-2 [&_table]:w-full [&_table]:max-w-full [&_table]:table-fixed [&_th]:border [&_th]:px-2 [&_th]:py-1 [&_th]:text-start [&_td]:border [&_td]:px-2 [&_td]:py-1',
+    '[&_details]:my-2 [&_summary]:cursor-pointer [&_summary]:font-medium',
+].join(' ');
+
+interface RichTextProps {
+    text: string;
+    format: RichTextFormat;
+    /** Draws each fenced ```mermaid block of Markdown, such as with `Diagram`, between the text around it. */
+    renderDiagram?: (source: string) => ReactNode;
+}
+
+/** A provider's text, sanitized and styled; with `renderDiagram`, Markdown's Mermaid blocks draw as diagrams. */
+export function RichText({ text, format, renderDiagram }: RichTextProps) {
+    if (text === '') return null;
+
+    if (renderDiagram && format === 'markdown') {
+        const parts = text.split(/```mermaid[^\S\r\n]*\r?\n([\s\S]*?)```/g);
+
+        if (parts.length > 1)
+            return (
+                <div className="grid min-w-0 gap-3" data-slot="rich-text-with-diagrams">
+                    {parts.map((part, index) =>
+                        index % 2 === 1 ? (
+                            <Fragment key={index}>{renderDiagram(part.trim())}</Fragment>
+                        ) : part.trim() ? (
+                            <RichText key={index} text={part} format="markdown" />
+                        ) : null,
+                    )}
+                </div>
+            );
+    }
+
+    return (
+        <div className={body} data-slot="rich-text">
+            {format === 'markdown' ? (
+                <Markdown rehypePlugins={rehypePlugins} remarkPlugins={[remarkGfm]}>
+                    {text}
+                </Markdown>
+            ) : (
+                toJsxRuntime(htmlProcessor.runSync(htmlProcessor.parse(text)), { Fragment, jsx, jsxs })
+            )}
+        </div>
+    );
+}

package/src/display/index.ts

@@ -7,11 +7,13 @@ export { BrandLink, BrandMark } from './BrandMark';
 export { ChangeList, type ChangeListItem } from './ChangeList';
 export { CheckList, type CheckListItem } from './CheckList';
 export { CodeBlock } from './CodeBlock';
+export { Comment, CommentList } from './Comment';
 export { CopyButton } from './CopyButton';
 export { DataTable, type DataTableCell, type DataTableRow } from './DataTable';
 export { DetailHero, DetailHeroDetail, DetailHeroDetails, DetailHeroTags } from './DetailHero';
 export { DetailList } from './DetailList';
 export { DeviceCard } from './DeviceCard';
+export { Diagram } from './Diagram';
 export { Identity } from './Identity';
 export { ImageCard } from './ImageCard';
 export { ImagePicker, ImagePickerGrid, ImagePickerOption, ImageUpload } from './ImagePicker';
@@ -20,15 +22,18 @@ export { InsetPanel } from './InsetPanel';
 export { ItemAction } from './ItemAction';
 export { Kbd } from './Kbd';
 export { KindIcon } from './KindIcon';
+export { LabelChip } from './LabelChip';
 export { NoticeCard } from './NoticeCard';
 export { PairingList, type PairingListItem } from './PairingList';
 export { PathList } from './PathList';
 export { PeoplePreview } from './PeoplePreview';
+export { Person } from './Person';
 export { PropertySheet, type PropertySheetRow, type PropertySheetTag } from './PropertySheet';
 export { QrCode } from './QrCode';
 export { RadioChoice } from './RadioChoice';
 export { RatingLink } from './RatingLink';
 export { ResourceCard, ResourceCardSkeleton } from './ResourceCard';
+export { RichText, type RichTextFormat } from './RichText';
 export { RowList, RowListItem } from './RowList';
 export { MeterLegend, type MeterSegment, type MeterTone, StackedMeter } from './StackedMeter';
 export { StatTile } from './StatTile';

package/src/feedback/DismissButton.tsx

@@ -0,0 +1,28 @@
+import { XIcon } from 'lucide-react';
+import type { MouseEvent } from 'react';
+
+import { IconButton } from '../actions/IconButton';
+
+/**
+ * The close button every failure, warning and notification carries; `label` names what it closes, such as
+ * "Dismiss: Moved #61". In the `corner` it floats to the top right of the text it closes; `inline` sits in a line of
+ * text, after an error message.
+ */
+export function DismissButton({
+    label,
+    onClick,
+    placement = 'corner',
+}: {
+    label: string;
+    onClick: (event: MouseEvent<HTMLButtonElement>) => void;
+    placement?: 'corner' | 'inline';
+}) {
+    return (
+        <IconButton
+            className={`dismiss ${placement === 'inline' ? 'float-none -my-1 ml-0.5 align-middle' : 'float-right -mt-0.75 -mr-1.5 ml-2'}`}
+            aria-label={label}
+            icon={<XIcon />}
+            onClick={onClick}
+        />
+    );
+}

package/src/feedback/ErrorNotification.ts

@@ -1,5 +1,7 @@
 import { toast } from '@ninna-ui/feedback';
 
+import { forgetNotificationSlots } from './Notifications';
+
 export interface ErrorNotification {
     description: string;
     title: string;
@@ -7,6 +9,7 @@ export interface ErrorNotification {
 
 export function dismissAllNotifications(): void {
     toast.dismissAll();
+    forgetNotificationSlots();
 }
 
 export function showErrorNotification(notification: ErrorNotification): void {

package/src/feedback/FormResult.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react';
+
+import { Alert } from './Alert';
+
+/**
+ * A form's result, such as a dialog's validation message or what its submit did. It stays mounted as a live region,
+ * so screen readers hear each new message; empty, it has no border, padding or icon. With no tone it is a warning, as
+ * a validation message is. Line breaks in `text` show.
+ */
+export function FormResult({
+    id,
+    text,
+    tone = 'warning',
+    children,
+    list,
+}: {
+    id: string;
+    text: string;
+    tone?: 'success' | 'warning' | 'error' | undefined;
+    /** Shown under the text. */
+    children?: ReactNode;
+    /** A list under the text, such as the paths a call touched, indented and wrapping normally. */
+    list?: readonly ReactNode[] | undefined;
+}) {
+    return (
+        <Alert
+            id={id}
+            tone={tone === 'error' ? 'danger' : tone}
+            data-tone={tone}
+            role="status"
+            aria-atomic="true"
+            showIcon={Boolean(text)}
+            className={text ? 'wrap-anywhere whitespace-pre-line' : 'border-0 p-0'}
+        >
+            {text && (
+                <>
+                    {text}
+                    {children}
+                    {list && list.length > 0 && (
+                        <ul className="pl-4.5 whitespace-normal">
+                            {list.map((entry, index) => (
+                                <li key={index}>{entry}</li>
+                            ))}
+                        </ul>
+                    )}
+                </>
+            )}
+        </Alert>
+    );
+}

package/src/feedback/LiveRegion.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+
+/** An out-of-sight polite live region: screen readers read what it says each time that changes, such as "Copied". */
+export function LiveRegion({ id, children }: { id?: string; children?: ReactNode }) {
+    return (
+        <div id={id} className="sr-only" role="status" aria-live="polite">
+            {children}
+        </div>
+    );
+}

package/src/feedback/Loading.tsx

@@ -0,0 +1,75 @@
+import { Loading as NinnaLoading, type LoadingProps as NinnaLoadingProps } from '@ninna-ui/feedback';
+import { LoaderCircleIcon, type LucideProps } from 'lucide-react';
+import { forwardRef } from 'react';
+
+import { ambientMotion } from '../foundations/AmbientMotion';
+
+const motions = {
+    spin: 'motion-safe:animate-spin',
+    always: 'animate-spin',
+    status: 'status-spin',
+    still: '',
+} as const;
+
+type SpinnerIconProps = LucideProps & {
+    /** The spin: `spin` turns unless the user prefers reduced motion, `always` turns regardless, as a pending action's
+     *  does, `status` is a status glyph's own spin (its page defines `status-spin`), and `still` doesn't turn. */
+    motion?: keyof typeof motions;
+};
+
+/**
+ * The loader icon, spinning on a box around it: above a device scale of 1 Chromium can't run a root svg's transform on
+ * the compositor, so the page would render every frame. It pauses while out of view or in a hidden window.
+ */
+export function SpinnerIcon({ motion = 'spin', ...icon }: SpinnerIconProps) {
+    const spin = motions[motion];
+
+    return (
+        <span ref={spin ? ambientMotion : undefined} className={`flex w-fit shrink-0 ${spin}`}>
+            <LoaderCircleIcon {...icon} />
+        </span>
+    );
+}
+
+type LoadingProps = Omit<NinnaLoadingProps, 'title'> & {
+    /** What loads. Without a `presentation` it names ninna-ui's spinner for screen readers only; with one it shows
+     *  beside the spinner. */
+    label?: string;
+    /** With no label, names the spinner alone, as a cue beside values already shown. */
+    title?: string | undefined;
+    /** Stops it spinning. */
+    still?: boolean;
+    /** Without it, ninna-ui's announced spinner. `inline` is a small spinner and what loads in a line of 12px text;
+     *  `line` stands on its own line of body text; `status` is a step's own loading line, announced, muted body text
+     *  with room above and below that keeps turning as a pending action's spinner does. */
+    presentation?: 'inline' | 'line' | 'status';
+};
+
+/** What shows in place of something still loading: ninna-ui's announced spinner, or with a `presentation`, a small
+ *  spinner, still under reduced motion, and what loads. */
+export const Loading = forwardRef<HTMLDivElement, LoadingProps>(
+    ({ presentation, label, title, still = false, ...props }, ref) => {
+        if (!presentation) return <NinnaLoading ref={ref} label={label} title={title} {...props} />;
+
+        if (presentation === 'status')
+            return (
+                <p role="status" className="text-base-700 m-0 flex items-center gap-2 py-4 text-sm">
+                    <SpinnerIcon motion={still ? 'still' : 'always'} aria-hidden="true" className="size-4" />
+                    {label}
+                </p>
+            );
+
+        return (
+            <span data-loader className="inline-flex min-w-0 items-center gap-1.5" title={title}>
+                <SpinnerIcon
+                    motion={still ? 'still' : 'spin'}
+                    aria-hidden="true"
+                    className={presentation === 'line' ? 'size-4' : 'size-3'}
+                />
+                {label ? <span className="truncate">{label}</span> : title && <span className="sr-only">{title}</span>}
+            </span>
+        );
+    },
+);
+
+Loading.displayName = 'Loading';

package/src/feedback/Notifications.tsx

@@ -1,5 +1,270 @@
-import { Toaster } from '@ninna-ui/feedback';
+/* oxlint-disable react/only-export-components -- The slot functions and the body's controls belong to the toaster. */
+
+import { toast, Toaster } from '@ninna-ui/feedback';
+import {
+    createContext,
+    type ReactNode,
+    type RefObject,
+    useContext,
+    useEffect,
+    useLayoutEffect,
+    useRef,
+    useState,
+} from 'react';
+import { flushSync } from 'react-dom';
+
+import { DismissButton } from './DismissButton';
+
+/** How long a success stays once the pointer and the focus have left it. */
+const SUCCESS_MS = 5_000;
+
+/** Each notification's fade, as wide as a Modal body's: notifications scrolled past fade out at the stack's edges. */
+const FADE_PX = 24;
+
+/**
+ * The page's notifications. `corner` shows a few at a time in the bottom right corner. `stack` keeps every one, oldest
+ * above the newest, above every dialog: when they don't fit, the stack scrolls, follows the newest while you are at the
+ * bottom, and fades those scrolled past at its edges, as a Modal's body does. Mount one, once, outside the page's root.
+ */
+export function Notifications({ presentation = 'corner' }: { presentation?: 'corner' | 'stack' }) {
+    if (presentation === 'stack')
+        return (
+            <Toaster
+                ref={followNewest}
+                position="bottom-right"
+                max={Infinity}
+                className="notification-stack"
+                offset="calc(var(--spacing) * 1)"
+            />
+        );
 
-export function Notifications() {
     return <Toaster position="bottom-right" />;
 }
+
+/**
+ * Follows the newest notification while the user is at the bottom: a new entry, a narrower or shorter window and a
+ * notification growing all keep it in view. Once the user scrolls away the stack stays where they left it, until they
+ * scroll back. Each notification carries its own slice of the edge fade: a mask on the stack would make it the
+ * notifications' backdrop root and cut their blur off from the page behind.
+ */
+function followNewest(viewport: HTMLDivElement | null) {
+    if (!viewport) return;
+
+    let following = true;
+    const entries = () => Array.from(viewport.children).filter((el): el is HTMLElement => el instanceof HTMLElement);
+    const fade = () => {
+        const { scrollTop, scrollHeight, clientHeight } = viewport;
+        const stack = viewport.getBoundingClientRect();
+        const top = Math.min(FADE_PX, Math.max(0, scrollTop));
+        const bottom = Math.min(FADE_PX, Math.max(0, scrollHeight - clientHeight - scrollTop));
+
+        for (const entry of entries()) {
+            const y = entry.getBoundingClientRect().top - stack.top;
+
+            entry.style.setProperty('--fade-from', `${-y}px`);
+            entry.style.setProperty('--fade-top', `${top - y}px`);
+            entry.style.setProperty('--fade-bottom', `${stack.height - bottom - y}px`);
+            entry.style.setProperty('--fade-to', `${stack.height - y}px`);
+        }
+    };
+    const toNewest = () => {
+        if (following) viewport.scrollTop = viewport.scrollHeight;
+
+        fade();
+    };
+    const scrolled = () => {
+        following = viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop <= 1;
+        fade();
+    };
+    const resizes = new ResizeObserver(toNewest);
+    const observe = () => {
+        resizes.disconnect();
+        resizes.observe(viewport);
+        entries().forEach((entry) => resizes.observe(entry));
+    };
+    const arrivals = new MutationObserver((changes) => {
+        observe();
+
+        const newest = viewport.lastElementChild;
+        const arrived = changes.some(({ addedNodes }) => Array.from(addedNodes).includes(newest as Node));
+
+        // Only a new entry moves the stack; one closing or changing above leaves the user where they are.
+        if (arrived) toNewest();
+        else fade();
+    });
+
+    arrivals.observe(viewport, { childList: true });
+    viewport.addEventListener('scroll', scrolled, { passive: true });
+    // Entering notifications slide in; measure them where they land.
+    viewport.addEventListener('animationend', fade);
+    viewport.addEventListener('transitionend', fade);
+    observe();
+    toNewest();
+
+    return () => {
+        arrivals.disconnect();
+        resizes.disconnect();
+        viewport.removeEventListener('scroll', scrolled);
+        viewport.removeEventListener('animationend', fade);
+        viewport.removeEventListener('transitionend', fade);
+    };
+}
+
+export interface Notification {
+    /** One notification per slot: a new one replaces the last. */
+    slot: string;
+    /** A failure is red and stays until it's closed; a success is green and clears itself five seconds after the
+     *  pointer and the keyboard focus leave it. */
+    tone?: 'success' | 'danger';
+    /** Names the close button, such as "Dismiss: Moved #61". */
+    dismissLabel: string;
+    /** What it says: text, links and buttons. */
+    body: ReactNode;
+    /** Called after it closes while the keyboard focus was inside it, to put the focus somewhere useful. */
+    onFocusLost?: () => void;
+}
+
+interface NotificationControls {
+    /** Keeps a success from clearing itself while `held`, such as while an action it offers is under way. */
+    hold: (held: boolean) => void;
+    /** Shows a success as a failure while `failed`, such as when an action it offers failed. */
+    fail: (failed: boolean) => void;
+}
+
+const Controls = createContext<NotificationControls>({ hold: () => {}, fail: () => {} });
+
+/** For a notification's body: what it can change about the notification it sits in. */
+export function useNotificationControls(): NotificationControls {
+    return useContext(Controls);
+}
+
+/** The id of the notification in each slot, in the toast manager. */
+const slots = new Map<string, string>();
+
+/** Forgets every slot, as the toasts they named are gone. */
+export function forgetNotificationSlots(): void {
+    slots.clear();
+}
+
+/** Closes the notification `id` in `slot`; if the focus was in it, `onFocusLost` puts it somewhere else. */
+function close(slot: string, id: string, onFocusLost?: () => void): void {
+    const hadFocus = Boolean(document.querySelector(`[data-toast-id="${id}"]`)?.contains(document.activeElement));
+
+    flushSync(() => {
+        if (slots.get(slot) === id) slots.delete(slot);
+
+        toast.dismiss(id);
+    });
+
+    if (hadFocus) onFocusLost?.();
+}
+
+/** Shows `notification` in its slot, replacing the one there. */
+export function showNotification(notification: Notification): void {
+    clearNotification(notification.slot);
+
+    const id: string = toast.create({
+        color: notification.tone === 'danger' ? 'danger' : 'success',
+        // The body's own clock closes successes and its own button closes every notification, so the manager never does.
+        duration: 0,
+        closable: false,
+        description: (
+            <NotificationBody
+                {...notification}
+                onClose={() => close(notification.slot, id, notification.onFocusLost)}
+            />
+        ),
+    });
+
+    slots.set(notification.slot, id);
+}
+
+/** Closes whatever notification holds this slot. */
+export function clearNotification(slot: string): void {
+    const id = slots.get(slot);
+
+    if (id) close(slot, id);
+}
+
+/** Gives a success five seconds after hover and keyboard focus leave it. */
+function useSuccessClose(ref: RefObject<Element | null>, enabled: boolean, onClose: () => void): void {
+    const latest = useRef(onClose);
+
+    useLayoutEffect(() => {
+        latest.current = onClose;
+    });
+    useEffect(() => {
+        if (!enabled) return;
+
+        const entry = ref.current?.closest<HTMLElement>('[data-slot="toast"]');
+
+        if (!entry) return;
+
+        const held = {
+            hovered: entry.matches(':hover'),
+            focused: entry.contains(document.activeElement),
+            timer: undefined as ReturnType<typeof setTimeout> | undefined,
+        };
+        const restart = () => {
+            clearTimeout(held.timer);
+
+            if (!held.hovered && !held.focused) held.timer = setTimeout(() => latest.current(), SUCCESS_MS);
+        };
+        const enter = () => {
+            held.hovered = true;
+            restart();
+        };
+        const leave = () => {
+            held.hovered = false;
+            restart();
+        };
+        const focus = () => {
+            held.focused = true;
+            restart();
+        };
+        const blur = (event: FocusEvent) => {
+            held.focused = event.relatedTarget instanceof Node && entry.contains(event.relatedTarget);
+            restart();
+        };
+
+        entry.addEventListener('mouseenter', enter);
+        entry.addEventListener('mouseleave', leave);
+        entry.addEventListener('focusin', focus);
+        entry.addEventListener('focusout', blur);
+        restart();
+
+        return () => {
+            clearTimeout(held.timer);
+            entry.removeEventListener('mouseenter', enter);
+            entry.removeEventListener('mouseleave', leave);
+            entry.removeEventListener('focusin', focus);
+            entry.removeEventListener('focusout', blur);
+        };
+    }, [enabled, ref]);
+}
+
+/** One notification's content. `onClose` runs when its close button is clicked or, for a success, when its time is up. */
+function NotificationBody({
+    slot,
+    dismissLabel,
+    tone = 'success',
+    body,
+    onClose,
+}: Notification & { onClose: () => void }) {
+    const ref = useRef<HTMLSpanElement>(null);
+    const [held, setHeld] = useState(false);
+    const [bodyFailed, setBodyFailed] = useState(false);
+    const failed = tone === 'danger' || bodyFailed;
+
+    useEffect(() => {
+        ref.current?.closest('[data-slot="toast"]')?.setAttribute('data-toast-color', failed ? 'danger' : 'success');
+    }, [failed]);
+    useSuccessClose(ref, !failed && !held, onClose);
+
+    return (
+        <span ref={ref} data-toast={slot}>
+            <DismissButton label={dismissLabel} onClick={onClose} />
+            <Controls.Provider value={{ hold: setHeld, fail: setBodyFailed }}>{body}</Controls.Provider>
+        </span>
+    );
+}

package/src/feedback/Progress.tsx

@@ -0,0 +1,44 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { Text } from '../typography/Typography';
+
+type ProgressProps = Omit<ComponentProps<'div'>, 'children' | 'className' | 'style'> & {
+    value: number;
+    max?: number;
+    /** Muted text after the bar, such as "Step 2 of 4". */
+    caption?: ReactNode;
+};
+
+/**
+ * A determinate progress bar: a rounded track filled to value / max, then an optional caption. Its props (an
+ * `aria-label`, say) go on the progressbar. Use ProgressStatusRow for a task's status row and StackedMeter for shares
+ * of a whole.
+ */
+export function Progress({ caption, value, max = 100, ...props }: ProgressProps) {
+    const share = max > 0 ? Math.min(Math.max(value / max, 0), 1) : 0;
+
+    return (
+        <div className="flex items-center gap-2" data-slot="progress">
+            <div
+                role="progressbar"
+                aria-valuemin={0}
+                aria-valuemax={max}
+                aria-valuenow={value}
+                className="bg-base-200 h-2 max-w-65 flex-1 overflow-hidden rounded-full"
+                data-slot="progress-bar"
+                {...props}
+            >
+                <div
+                    className="bg-primary h-full rounded-[inherit]"
+                    style={{ width: `${share * 100}%` }}
+                    data-slot="progress-indicator"
+                />
+            </div>
+            {caption && (
+                <Text as="span" variant="caption" tone="muted" data-slot="progress-caption">
+                    {caption}
+                </Text>
+            )}
+        </div>
+    );
+}