@mithrl/design-system 0.3.0 → 0.4.0

package/dist/components/approval-card/ApprovalCard.d.ts

@@ -0,0 +1,70 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+/** One selectable answer on an approval question. */
+export interface ApprovalOption {
+    id: string;
+    label: string;
+    /** Short clarifier shown under the label. Keep it to one plain sentence. */
+    description?: string;
+}
+/** A single question the agent asks before it acts. */
+export interface ApprovalQuestion {
+    id: string;
+    /** The question itself, phrased the way a colleague would ask it. */
+    prompt: string;
+    /** Optional context sentence shown under the prompt. */
+    helpText?: ReactNode;
+    options: ApprovalOption[];
+    /** Allow more than one option. Defaults to single choice. */
+    multiSelect?: boolean;
+}
+/** Selected option ids keyed by question id. */
+export type ApprovalAnswers = Record<string, string[]>;
+type RestrictedApprovalCardAttribute = "children" | "onSubmit" | "role";
+export type ApprovalCardProps = Omit<HTMLAttributes<HTMLElement>, RestrictedApprovalCardAttribute> & {
+    /** Ordered questions. The card pages through them one at a time. */
+    questions: ApprovalQuestion[];
+    /** Optional heading above the question, e.g. the run the agent is planning. */
+    eyebrow?: ReactNode;
+    /** Controlled answers. Pair with `onAnswersChange`. */
+    answers?: ApprovalAnswers;
+    /** Initial answers when the card owns its own state. */
+    defaultAnswers?: ApprovalAnswers;
+    onAnswersChange?: (answers: ApprovalAnswers) => void;
+    /** Fired once the last question is confirmed. */
+    onComplete?: (answers: ApprovalAnswers) => void;
+    /** Fired when the scientist declines to answer and lets the agent decide. */
+    onSkip?: (answers: ApprovalAnswers) => void;
+    skipLabel?: string;
+    continueLabel?: string;
+    /** Label for the final page's primary action. */
+    completeLabel?: string;
+    /** Require a selection before the primary action enables. @default true */
+    requireAnswer?: boolean;
+};
+/**
+ * Human-in-the-loop approval. The agent pauses, asks what it should do, and
+ * waits: one question per page, a clear way out, and no hidden defaults.
+ */
+export declare const ApprovalCard: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, RestrictedApprovalCardAttribute> & {
+    /** Ordered questions. The card pages through them one at a time. */
+    questions: ApprovalQuestion[];
+    /** Optional heading above the question, e.g. the run the agent is planning. */
+    eyebrow?: ReactNode;
+    /** Controlled answers. Pair with `onAnswersChange`. */
+    answers?: ApprovalAnswers;
+    /** Initial answers when the card owns its own state. */
+    defaultAnswers?: ApprovalAnswers;
+    onAnswersChange?: (answers: ApprovalAnswers) => void;
+    /** Fired once the last question is confirmed. */
+    onComplete?: (answers: ApprovalAnswers) => void;
+    /** Fired when the scientist declines to answer and lets the agent decide. */
+    onSkip?: (answers: ApprovalAnswers) => void;
+    skipLabel?: string;
+    continueLabel?: string;
+    /** Label for the final page's primary action. */
+    completeLabel?: string;
+    /** Require a selection before the primary action enables. @default true */
+    requireAnswer?: boolean;
+} & import("react").RefAttributes<HTMLElement>>;
+export {};

package/dist/components/code-block/CodeBlock.d.ts

@@ -0,0 +1,64 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export type CodeBlockVariant = "code" | "diff";
+export type CodeLineKind = "context" | "added" | "removed";
+export type CodeLine = {
+    /** Raw line text. Rendered verbatim in the mono column. */
+    content: string;
+    /** Diff classification. Ignored by the `code` variant. */
+    kind?: CodeLineKind;
+};
+export type CodeBlockRenderLineArgs = {
+    /** Raw line text. */
+    content: string;
+    /** Resolved diff classification. */
+    kind: CodeLineKind;
+    /** One-based line number as shown in the gutter. */
+    number: number;
+    /** Variant the line is being rendered for. */
+    variant: CodeBlockVariant;
+};
+export type CodeBlockLabels = {
+    copy: string;
+    copied: string;
+    copyFailed: string;
+    codeTab: string;
+    diffTab: string;
+    listing: string;
+};
+type CodeBlockOwnProps = {
+    /** Source text. Split on newlines into the listing. */
+    code?: string;
+    /** Pre-split lines, required for diff rendering. Wins over `code`. */
+    lines?: readonly CodeLine[];
+    /** Language label rendered as a Tag in the header. */
+    language?: string;
+    /** File path or name rendered as the header title. */
+    fileName?: string;
+    /** Listing mode. Ignored when `tabs` is enabled. */
+    variant?: CodeBlockVariant;
+    /** Renders a Code/Diff segmented control. Requires `code` and `lines`. */
+    tabs?: boolean;
+    /** Controlled tab value when `tabs` is enabled. */
+    activeTab?: CodeBlockVariant;
+    /** Called when the Code/Diff segmented control changes. */
+    onTabChange?: (variant: CodeBlockVariant) => void;
+    /** Hides the line-number column. */
+    hideLineNumbers?: boolean;
+    /** Called with the text placed on the clipboard. */
+    onCopy?: (text: string) => void;
+    /** Injects highlighted nodes for a line. Defaults to plain mono text. */
+    renderLine?: (line: CodeBlockRenderLineArgs) => ReactNode;
+    labels?: Partial<CodeBlockLabels>;
+    className?: string;
+};
+export type CodeBlockProps = Omit<HTMLAttributes<HTMLDivElement>, keyof CodeBlockOwnProps | "children"> & CodeBlockOwnProps;
+/**
+ * A notebook-tier code surface: a titled header rail with an optional
+ * language Tag and copy action, and a line-numbered, horizontally scrolling
+ * listing. The `diff` variant renders unified diff lines with semantic
+ * tinting. CodeBlock ships no syntax highlighting engine — pass `renderLine`
+ * to inject already-highlighted nodes.
+ */
+export declare const CodeBlock: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | keyof CodeBlockOwnProps> & CodeBlockOwnProps & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/command-search/CommandSearch.d.ts

@@ -0,0 +1,57 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export type CommandSearchItem = {
+    /** Stable identity used for keys and active-descendant wiring. */
+    id: string;
+    /** Visible command label; match highlighting applies to this text. */
+    label: string;
+    /** Optional group heading the item is filed under. */
+    group?: string;
+    /** Optional trailing hint such as a shortcut or destination. */
+    hint?: string;
+    /** Invoked on Enter or click. */
+    onSelect?: (item: CommandSearchItem) => void;
+    /** Removes the item from keyboard navigation and selection. */
+    disabled?: boolean;
+};
+export type CommandSearchProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onSelect"> & {
+    items: readonly CommandSearchItem[];
+    /** Required accessible name for the search field. */
+    label: string;
+    placeholder?: string;
+    /** Controlled query. Omit for uncontrolled use. */
+    query?: string;
+    defaultQuery?: string;
+    onQueryChange?: (query: string) => void;
+    /** Called after any item is chosen, in addition to the item's own handler. */
+    onSelect?: (item: CommandSearchItem) => void;
+    /** Called when Escape is pressed on a field that is already empty. */
+    onEscape?: () => void;
+    /** Renders group headings when items carry a `group`. */
+    grouped?: boolean;
+    /** Secondary line shown under the empty-state title. */
+    emptyHint?: ReactNode;
+};
+/**
+ * A command palette search surface. CommandSearch renders inline as an
+ * embedded panel and can be composed inside a Dialog by the consumer; it owns
+ * filtering, match highlighting, and roving keyboard selection only.
+ */
+export declare const CommandSearch: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onSelect"> & {
+    items: readonly CommandSearchItem[];
+    /** Required accessible name for the search field. */
+    label: string;
+    placeholder?: string;
+    /** Controlled query. Omit for uncontrolled use. */
+    query?: string;
+    defaultQuery?: string;
+    onQueryChange?: (query: string) => void;
+    /** Called after any item is chosen, in addition to the item's own handler. */
+    onSelect?: (item: CommandSearchItem) => void;
+    /** Called when Escape is pressed on a field that is already empty. */
+    onEscape?: () => void;
+    /** Renders group headings when items carry a `group`. */
+    grouped?: boolean;
+    /** Secondary line shown under the empty-state title. */
+    emptyHint?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/context-cards/ContextCards.d.ts

@@ -0,0 +1,53 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+/** File types a retrieved chunk can come from. */
+export type ContextFileType = "PDF" | "CSV" | "XLSX" | "TXT";
+export interface FileTypeChipProps {
+    /** The chunk's source file type. */
+    fileType: ContextFileType;
+}
+/**
+ * A tinted three-or-four letter file-type marker. Each type gets a distinct
+ * semantic tint so a mixed list is scannable at a glance without reading
+ * filenames.
+ */
+export declare function FileTypeChip({ fileType }: FileTypeChipProps): import("react/jsx-runtime").JSX.Element;
+export interface ContextCardProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Chunk heading — usually the section or table it was taken from. */
+    title: ReactNode;
+    /** Retrieved text. Clamped to three lines and faded, never truncated mid-word with an ellipsis. */
+    excerpt: ReactNode;
+    /** Character count of the full chunk, shown as retrieval metadata. */
+    characterCount?: number;
+    /** File the chunk came from. */
+    fileName: string;
+    /** File type of `fileName`. */
+    fileType: ContextFileType;
+    /**
+     * Optional page or row provenance, e.g. `"p. 4"` or `"rows 120–184"`.
+     */
+    locator?: string;
+}
+/**
+ * One retrieved knowledge chunk. Presentational: the card is not a control, so
+ * it carries no role or tab stop. Wrap it in a button or link at the call site
+ * if opening the source is supported there.
+ */
+export declare const ContextCard: import("react").ForwardRefExoticComponent<ContextCardProps & import("react").RefAttributes<HTMLElement>>;
+export interface ContextCardListProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Group heading. @default "All chunks" */
+    title?: ReactNode;
+    /**
+     * Number shown in the count Tag. Defaults to the number of rendered cards,
+     * so pass it explicitly only when the list is paged or virtualised.
+     */
+    count?: number;
+    /** `ContextCard` children. */
+    children: ReactNode;
+}
+/**
+ * A labelled group of retrieved chunks. Rendered as a `<section>` with its
+ * heading wired through `aria-labelledby`, and the cards themselves in a
+ * `<ul>` so assistive technology announces the group size.
+ */
+export declare const ContextCardList: import("react").ForwardRefExoticComponent<ContextCardListProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/disclosure/Disclosure.d.ts

@@ -0,0 +1,38 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export type DisclosureProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Whether the region is expanded. Disclosure is always controlled. */
+    open: boolean;
+    /** Region content. Padding belongs on the content, never on Disclosure. */
+    children?: ReactNode;
+};
+/**
+ * An animated, controlled disclosure region.
+ *
+ * Disclosure animates its own height between collapsed and expanded using the
+ * `grid-template-rows: 0fr -> 1fr` technique, so content of any size animates
+ * without JavaScript measurement. Open animates over
+ * `--motion-duration-moderate` on `--motion-easing-enter`; close animates over
+ * the shorter `--motion-duration-standard` on `--motion-easing-exit`, matching
+ * the foundations asymmetry rule and the Dialog precedent.
+ *
+ * Boundary — Disclosure is presentational and owns the region only. It does
+ * **not** own the trigger, the chevron, focus management, `aria-expanded`, or
+ * `aria-controls`; the caller already owns those and keeps them on its own
+ * trigger. Pass `id` here and reference it from the trigger's `aria-controls`.
+ *
+ * While closed the content is hidden from the accessibility tree and from the
+ * tab order twice over: `visibility: hidden` is deferred behind the collapse
+ * transition (the pattern already used by `secondary-panel.css` and
+ * `workspace-app-shell.css`), and `inert` is applied immediately so nothing
+ * inside can be focused during the closing transition.
+ *
+ * Under `prefers-reduced-motion: reduce` the height animation is dropped
+ * entirely and the region crossfades at `--motion-duration-fast`.
+ */
+export declare const Disclosure: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Whether the region is expanded. Disclosure is always controlled. */
+    open: boolean;
+    /** Region content. Padding belongs on the content, never on Disclosure. */
+    children?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/field-message/FieldMessage.d.ts

@@ -13,6 +13,18 @@ export type FieldMessageProps = Omit<HTMLAttributes<HTMLParagraphElement>, "chil
 /**
  * Supporting or validation text for one form control. The consumer owns the
  * ID, ARIA relationship, live-region policy, and validation behavior.
+ *
+ * The message reveals itself on mount rather than popping in: an outer grid
+ * wrapper animates `grid-template-rows: 0fr -> 1fr` from a CSS
+ * `@starting-style` rule, so surrounding layout eases open instead of jumping.
+ * The wrapper is purely presentational — every prop, the `className`, the
+ * forwarded ref, `role="alert"`, and the ARIA relationship stay on the same
+ * `<p>` element they were on before, so nothing about the announcement is
+ * delayed, duplicated, or moved. Browsers without `@starting-style` simply
+ * show the message immediately.
+ *
+ * Exit is owned by the consumer, because the consumer owns the unmount. Wrap
+ * FieldMessage in `Disclosure` and keep it mounted to animate it away.
  */
 export declare const FieldMessage: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLParagraphElement>, "children" | "className"> & VariantProps<(props?: ({
     tone?: "error" | "helper" | "warning" | null | undefined;

package/dist/components/filter-table/FilterTable.d.ts

@@ -0,0 +1,61 @@
+import { type HTMLAttributes } from "react";
+
+export declare const filterTableStatuses: readonly ["to-do", "in-progress", "completed"];
+export type FilterTableStatus = (typeof filterTableStatuses)[number];
+export type FilterTableRow = {
+    /** Stable row identity. */
+    id: string;
+    /** Primary task name. */
+    name: string;
+    /** Preformatted date string; rendered with tabular figures. */
+    date: string;
+    status: FilterTableStatus;
+    /** Person or team accountable for the task. */
+    owner: string;
+    /** Optional secondary line under the task name. */
+    detail?: string;
+};
+export type FilterTableProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
+    rows: readonly FilterTableRow[];
+    /** Required accessible name for the table. */
+    caption: string;
+    /** Controlled filter. `null` shows every row. */
+    filter?: FilterTableStatus | null;
+    /** Initial filter for uncontrolled use. */
+    defaultFilter?: FilterTableStatus | null;
+    onFilterChange?: (filter: FilterTableStatus | null) => void;
+    /** Label used on the "show everything" chip. */
+    allLabel?: string;
+    /** Column headers, in render order. */
+    headers?: {
+        name: string;
+        date: string;
+        status: string;
+        owner: string;
+    };
+};
+/**
+ * A light task table whose status chips reorganize the visible rows in place.
+ * Row movement is animated with a FLIP pass that only touches `transform`.
+ */
+export declare const FilterTable: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
+    rows: readonly FilterTableRow[];
+    /** Required accessible name for the table. */
+    caption: string;
+    /** Controlled filter. `null` shows every row. */
+    filter?: FilterTableStatus | null;
+    /** Initial filter for uncontrolled use. */
+    defaultFilter?: FilterTableStatus | null;
+    onFilterChange?: (filter: FilterTableStatus | null) => void;
+    /** Label used on the "show everything" chip. */
+    allLabel?: string;
+    /** Column headers, in render order. */
+    headers?: {
+        name: string;
+        date: string;
+        status: string;
+        owner: string;
+    };
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FilterTableStatusLabelMap = Record<FilterTableStatus, string>;
+export declare const filterTableStatusLabels: FilterTableStatusLabelMap;

package/dist/components/flap-text/FlapText.d.ts

@@ -0,0 +1,68 @@
+import { type CSSProperties } from "react";
+
+/**
+ * Milliseconds one cell spends flipping. Mirrors `--motion-duration-moderate`;
+ * the CSS reads the token directly and only falls back to this number when the
+ * caller overrides `flapDuration`.
+ */
+export declare const FLAP_TEXT_DEFAULT_DURATION_MS = 220;
+/** Milliseconds each successive cell waits before it starts flipping. */
+export declare const FLAP_TEXT_DEFAULT_STAGGER_MS = 18;
+export type FlapTextElement = "span" | "div" | "p" | "strong" | "em";
+export type FlapTextAlign = "start" | "center" | "end";
+export interface FlapTextProps {
+    /** The string to display. Changing it flips the characters that differ. */
+    text: string;
+    /** Host element. @default "span" */
+    as?: FlapTextElement;
+    /** Per-character delay, in milliseconds. @default 18 */
+    stagger?: number;
+    /** Flip duration, in milliseconds. @default `--motion-duration-moderate` */
+    flapDuration?: number;
+    /** Horizontal alignment of the rendered line. @default "start" */
+    align?: FlapTextAlign;
+    className?: string;
+    style?: CSSProperties;
+}
+export type FlapCell = {
+    /** Glyph shown once the cell settles. */
+    char: string;
+    /** Glyph rotating out, or `null` when the cell is new or settled. */
+    previous: string | null;
+    /** Whether this cell is mid-flip. */
+    flap: boolean;
+    /** Trailing cell that disappears when the text got shorter. */
+    exiting: boolean;
+};
+/**
+ * A Solari board only moves the cells whose glyph actually changed. Identical
+ * characters at the same index stay perfectly still, which is both faithful and
+ * far calmer to read.
+ */
+export declare function flapTextCells(previous: string, next: string): FlapCell[];
+/**
+ * Split-flap text.
+ *
+ * Each character is its own cell. When `text` changes, only the cells whose
+ * glyph differs flip: the old glyph rotates away around the horizontal midline
+ * while the new one rotates in behind it, staggered left to right.
+ *
+ * Sharpness: cells are inline-block with `preserve-3d` and hidden backfaces,
+ * `will-change: transform` is present only while a cell is actually flipping,
+ * and settled cells carry `transform: none` exactly — never an identity matrix
+ * — so the browser re-rasterises the glyph at full fidelity. No scale is ever
+ * applied, and the component sets no font property, so text metrics are the
+ * caller's.
+ *
+ * Accessibility: cells are `aria-hidden`, the host carries `aria-label={text}`,
+ * and a visually hidden polite live region announces one clean string.
+ *
+ * Reduced motion: no 3D at all — a fast opacity crossfade swaps the glyph.
+ */
+export declare function FlapText({ text, as, stagger, flapDuration, align, className, style, }: FlapTextProps): import("react").DetailedReactHTMLElement<{
+    className: string;
+    style: CSSProperties | undefined;
+    "aria-label": string;
+    "data-align": FlapTextAlign;
+    "data-flapping": string;
+}, HTMLElement>;

package/dist/components/flowchart/Flowchart.d.ts

@@ -0,0 +1,140 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import { type IconGlyphComponent } from "../icon/Icon";
+
+export type FlowchartCanvasProps = HTMLAttributes<HTMLDivElement> & {
+    /** Flow nodes and connectors, composed top to bottom. */
+    children: ReactNode;
+    /** Hides the dotted grid when the flow sits inside an already-textured surface. */
+    grid?: boolean;
+    /** Horizontal alignment of the node column. @default "center" */
+    align?: "center" | "start";
+};
+/**
+ * A static presentation surface for a vertically-connected workflow.
+ * Flowchart never owns drag, drop, or node editing: it renders an already
+ * decided pipeline so a reader can follow it top to bottom.
+ */
+export declare const FlowchartCanvas: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    /** Flow nodes and connectors, composed top to bottom. */
+    children: ReactNode;
+    /** Hides the dotted grid when the flow sits inside an already-textured surface. */
+    grid?: boolean;
+    /** Horizontal alignment of the node column. @default "center" */
+    align?: "center" | "start";
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FlowchartConnectorVariant = "line" | "elbow-left" | "elbow-right";
+export type FlowchartConnectorProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Straight run, or an elbow that steps the flow into a branch column. */
+    variant?: FlowchartConnectorVariant;
+    /** Short branch caption such as `Yes`, `No`, or `On failure`. */
+    label?: string;
+    /** Draws the run dashed to signal a conditional or deferred path. */
+    dashed?: boolean;
+};
+/**
+ * The visual run between two flow nodes. Decorative by default; the label,
+ * when present, is the only readable content and is exposed to assistive tech.
+ */
+export declare const FlowchartConnector: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Straight run, or an elbow that steps the flow into a branch column. */
+    variant?: FlowchartConnectorVariant;
+    /** Short branch caption such as `Yes`, `No`, or `On failure`. */
+    label?: string;
+    /** Draws the run dashed to signal a conditional or deferred path. */
+    dashed?: boolean;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FlowchartTriggerProps = Omit<HTMLAttributes<HTMLDivElement>, "title" | "children"> & {
+    /** Approved Lucide glyph naming the event source. */
+    icon?: IconGlyphComponent;
+    /** What starts the flow, phrased as an event. */
+    title: ReactNode;
+    /** One sentence of supporting detail about the event. */
+    description?: ReactNode;
+    /** Overrides the default `Trigger` eyebrow. */
+    eyebrow?: string;
+    /** Optional metadata slot, typically a `Tag`. */
+    trailing?: ReactNode;
+};
+/** The entry node of a flow. Carries an accent left treatment. */
+export declare const FlowchartTrigger: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "title"> & {
+    /** Approved Lucide glyph naming the event source. */
+    icon?: IconGlyphComponent;
+    /** What starts the flow, phrased as an event. */
+    title: ReactNode;
+    /** One sentence of supporting detail about the event. */
+    description?: ReactNode;
+    /** Overrides the default `Trigger` eyebrow. */
+    eyebrow?: string;
+    /** Optional metadata slot, typically a `Tag`. */
+    trailing?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FlowchartActionProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    icon?: IconGlyphComponent;
+    /** What the step does. */
+    title: ReactNode;
+    description?: ReactNode;
+    /** Overrides the default `Action` eyebrow, e.g. `Step 2`. */
+    eyebrow?: string;
+    /** Optional metadata slot, typically a `Tag` or a duration. */
+    trailing?: ReactNode;
+    /** Extra detail rendered beneath the header. */
+    children?: ReactNode;
+};
+/** A generic executed step in the flow. */
+export declare const FlowchartAction: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    icon?: IconGlyphComponent;
+    /** What the step does. */
+    title: ReactNode;
+    description?: ReactNode;
+    /** Overrides the default `Action` eyebrow, e.g. `Step 2`. */
+    eyebrow?: string;
+    /** Optional metadata slot, typically a `Tag` or a duration. */
+    trailing?: ReactNode;
+    /** Extra detail rendered beneath the header. */
+    children?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FlowchartClauseJoin = "and" | "or";
+export type FlowchartConditionClause = {
+    /** The measured entity, e.g. `run QC score`. */
+    entity: string;
+    /** The comparison, e.g. `is below`. */
+    operator: string;
+    /** The compared value, e.g. `0.8`. */
+    value: string;
+    /**
+     * How this clause joins the previous one. Ignored on the first clause.
+     * @default "and"
+     */
+    join?: FlowchartClauseJoin;
+};
+export type FlowchartConditionProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    icon?: IconGlyphComponent;
+    /** Short name for the decision, e.g. `Route low-quality runs`. */
+    title: ReactNode;
+    /** The clauses evaluated together, rendered as entity / operator / value chips. */
+    clauses: readonly FlowchartConditionClause[];
+    /** Overrides the default `If / Else` eyebrow. */
+    eyebrow?: string;
+    /** Caption for the true outcome. */
+    thenLabel?: string;
+    /** Caption for the false outcome. Omit for an if-only condition. */
+    elseLabel?: string;
+    /** Optional metadata slot, typically a `Tag`. */
+    trailing?: ReactNode;
+};
+/** A branching If/Else node whose clauses read as inline chips. */
+export declare const FlowchartCondition: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    icon?: IconGlyphComponent;
+    /** Short name for the decision, e.g. `Route low-quality runs`. */
+    title: ReactNode;
+    /** The clauses evaluated together, rendered as entity / operator / value chips. */
+    clauses: readonly FlowchartConditionClause[];
+    /** Overrides the default `If / Else` eyebrow. */
+    eyebrow?: string;
+    /** Caption for the true outcome. */
+    thenLabel?: string;
+    /** Caption for the false outcome. Omit for an if-only condition. */
+    elseLabel?: string;
+    /** Optional metadata slot, typically a `Tag`. */
+    trailing?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/global-app-bar/GlobalAppBar.d.ts

@@ -1,4 +1,4 @@
-import { type AnchorHTMLAttributes, type ButtonHTMLAttributes, type HTMLAttributes, type MouseEventHandler, type ReactElement } from "react";
+import { type AnchorHTMLAttributes, type ButtonHTMLAttributes, type HTMLAttributes, type MouseEventHandler, type ReactElement, type ReactNode } from "react";
 import { type AccountMenuProps } from "../account-menu/AccountMenu";
 import { type DropdownMenuProps } from "../dropdown-menu/DropdownMenu";
 import { type ThemeMode } from "../switch/Switch";
@@ -59,6 +59,11 @@ export type GlobalAppBarProps = Omit<HTMLAttributes<HTMLElement>, "children"> &
     onAccountMenuOpenChange?: DropdownMenuProps["onOpenChange"];
     /** Additional native attributes for the account-menu button. */
     accountButtonProps?: AccountButtonProps;
+    /**
+     * Product-wide utility controls rendered before Theme Switch. Use for
+     * persistent utilities such as Notifications, never page-specific actions.
+     */
+    utilityActions?: ReactNode;
     /**
      * Workspace-only App Shell controls. Each control keeps its own semantics;
      * Global App Bar owns only their approved order and alignment.
@@ -70,9 +75,9 @@ export type GlobalAppBarProps = Omit<HTMLAttributes<HTMLElement>, "children"> &
     };
 };
 /**
- * Persistent application anchor. Home keeps the minimal brand, theme, and
- * account contract; Workspace adds structural panel controls and project
- * context without introducing a second App Bar component.
+ * Persistent application anchor. Home keeps brand, optional product-wide
+ * utilities, theme, and account; Workspace adds structural panel controls and
+ * project context without introducing a second App Bar component.
  */
 export declare const GlobalAppBar: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, "children"> & {
     /** Home destination used by the official Mithrl brand action. */
@@ -105,6 +110,11 @@ export declare const GlobalAppBar: import("react").ForwardRefExoticComponent<Omi
     onAccountMenuOpenChange?: DropdownMenuProps["onOpenChange"];
     /** Additional native attributes for the account-menu button. */
     accountButtonProps?: AccountButtonProps;
+    /**
+     * Product-wide utility controls rendered before Theme Switch. Use for
+     * persistent utilities such as Notifications, never page-specific actions.
+     */
+    utilityActions?: ReactNode;
     /**
      * Workspace-only App Shell controls. Each control keeps its own semantics;
      * Global App Bar owns only their approved order and alignment.

package/dist/components/icon-swap/IconSwap.d.ts

@@ -0,0 +1,30 @@
+import { type HTMLAttributes } from "react";
+import { type IconGlyphComponent, type IconSize } from "../icon/Icon";
+
+export type IconSwapProps = Omit<HTMLAttributes<HTMLSpanElement>, "aria-label" | "aria-hidden" | "children" | "role"> & {
+    /**
+     * Approved glyph to display. Changing the component identity swaps the
+     * glyph in place; the caller never manages two children.
+     */
+    icon: IconGlyphComponent;
+    /** Icon Foundation size token. Matches the `Icon` contract exactly. */
+    size?: IconSize;
+};
+/**
+ * Cross-fades two glyphs through one slot.
+ *
+ * IconSwap is a single-slot component: pass one `icon`, and whenever that
+ * component identity changes the outgoing glyph fades out while the incoming
+ * glyph fades in over it. Both share one grid cell so the slot never reflows.
+ *
+ * Motion — `--motion-duration-standard` on `--motion-easing-standard`, with
+ * the incoming glyph rising from `--motion-scale-enter` and
+ * `--motion-blur-soft` to rest. Under `prefers-reduced-motion: reduce` the
+ * scale and blur are dropped and the two glyphs cross-fade on opacity alone at
+ * `--motion-duration-fast`.
+ *
+ * Boundary — the swap is decorative. IconSwap announces nothing: the root and
+ * every glyph are hidden from assistive technology, exactly as a bare `Icon`
+ * without a `label` is. The accessible name belongs to the owning control.
+ */
+export declare function IconSwap({ icon, size, className, ...props }: IconSwapProps): import("react/jsx-runtime").JSX.Element;