altitude-design 0.2.1 → 0.3.0

package/dist/types/overlays.d.ts

@@ -1,7 +1,12 @@
 import * as React from 'react';
+import { type Presentation } from './core.js';
+/** The shared warm-up, for floating readouts outside this module (a chart's readout): warm if one closed within 400ms. */
+export declare const tipIsWarm: () => boolean;
+export declare const markTipClosed: () => void;
 export interface TooltipProps {
     content: React.ReactNode;
-    side?: 'top' | 'bottom';
+    /** Default 'top'. 'right' is for a rail of icons, where above would cover the next one. */
+    side?: 'top' | 'bottom' | 'right';
     delay?: number;
     defaultOpen?: boolean;
     children: React.ReactElement<any>;
@@ -29,6 +34,8 @@ export interface MenuItem {
     disabled?: boolean;
     /** Ephemeral adaptation: predicted items appear at once, the rest fade in over dur-onset. Only worth it when predictions are right most of the time. */
     predicted?: boolean;
+    /** A checkable item (role="menuitemcheckbox"), shown with a check when true: a toggle moved into a menu. */
+    checked?: boolean;
 }
 export type MenuEntry = MenuItem | {
     type: 'separator';
@@ -43,8 +50,34 @@ export interface DropdownMenuProps {
     side?: 'top' | 'bottom';
     defaultOpen?: boolean;
     className?: string;
+    /**
+     * 'auto' (default): anchored to the trigger, or on a narrow touch screen a sheet at the bottom edge, with a title and
+     * Close, where the thumb is (#249). 'anchored' or 'sheet' forces one.
+     */
+    presentation?: Presentation;
+    /** The sheet's title. Default: the trigger's aria-label or text. */
+    title?: string;
 }
-export declare function DropdownMenu({ trigger, items, align, side, defaultOpen, className }: DropdownMenuProps): React.JSX.Element;
+/**
+ * The menu itself, shared by DropdownMenu and ContextMenu: its items, the highlight that glides between them, the
+ * keyboard, and choosing. `onClose(true)` asks the owner to close and give focus back.
+ */
+export declare function MenuPanel({ items, id, state, side, align, className, style, startFirst, onClose, sheet, title }: {
+    items: MenuEntry[];
+    id: string;
+    state: string;
+    side?: 'top' | 'bottom';
+    align?: 'start' | 'end';
+    className?: string;
+    style?: React.CSSProperties;
+    /** Opened from the keyboard: the first item is active at once. */
+    startFirst?: boolean;
+    onClose: () => void;
+    /** Presented as a bottom sheet (#249), with this title. */
+    sheet?: boolean;
+    title?: React.ReactNode;
+}): React.JSX.Element;
+export declare function DropdownMenu({ trigger, items, align, side, defaultOpen, className, presentation, title }: DropdownMenuProps): React.JSX.Element;
 export interface HoverCardProps {
     /** What you hover or focus: usually a link or an avatar. It must do its own job (navigate, open) without the card. */
     trigger: React.ReactElement<any>;
@@ -67,33 +100,28 @@ export interface HoverCardProps {
  * warm-up: once one has shown, a neighbour opens at once. Its content is supplementary, never the only way to reach anything.
  */
 export declare function HoverCard({ trigger, children, side, align, openDelay, closeDelay, open, defaultOpen, onOpenChange, className }: HoverCardProps): React.JSX.Element;
-export declare const summitTaken: () => boolean;
+/** The summit is shared by every provider in the same document. */
+export declare const summitTaken: (doc?: Document) => boolean;
 export interface ModalOptions {
     open: boolean;
     onDismiss: () => void;
-    /** How long the closed pose stays mounted (the exit runs at 70% of the entry). */
     exitMs: number;
     panel: React.RefObject<HTMLElement | null>;
-    /** Blocks the page: the stage recedes, scroll locks and Tab is trapped. Default true. */
     modal?: boolean;
-    /** Escape closes. Default true. */
     dismissible?: boolean;
-    /** Takes level 5 (Dialog, CommandPalette). Default false. */
     summit?: boolean;
-    /** Move focus into the panel once it has risen. Default true. */
     autoFocus?: boolean;
     focusSelector?: string;
-    /** Put focus back where it was on close. Default: autoFocus. */
     restoreFocus?: boolean;
+    background?: 'recede' | 'stationary';
+    returnFocus?: () => HTMLElement | null;
 }
-/**
- * The machinery every layer above the page shares: presence (mount, rise, exit), the receding page,
- * scroll lock, focus in and back out, Escape and the Tab trap. Dialog, Sheet and CommandPalette use it.
- */
 export declare const MODAL_FOCUS = "[data-autofocus], input, textarea, select";
-export declare function useModal({ open, onDismiss, exitMs, panel, modal, dismissible, summit, autoFocus, focusSelector, restoreFocus }: ModalOptions): {
-    onKeyDown: (e: React.KeyboardEvent) => void;
+export declare function useModal({ open, onDismiss, exitMs, panel, modal, dismissible, summit, autoFocus, focusSelector, restoreFocus, background, returnFocus }: ModalOptions): {
     mounted: boolean;
+    onKeyDown: (e: React.KeyboardEvent) => void;
+    rootRef: (root: HTMLDivElement | null) => void;
+    captureInvoker: (el: HTMLElement) => void;
     state: "open" | "closed";
 };
 export interface DialogProps {
@@ -109,13 +137,17 @@ export interface DialogProps {
     size?: 'sm' | 'md' | 'lg';
     /** Set false for decisions that must be answered: the scrim and Escape won't close it. */
     dismissible?: boolean;
-    /** Where focus goes once it has risen: the first field (the default), the title (for a read surface), or nowhere (you move it yourself). */
+    /** Initial focus: the first field (default), the title, or false for a safe panel fallback until the application moves focus inside. */
     initialFocus?: 'first-field' | 'title' | false;
     /** What 'first-field' looks for. Default '[data-autofocus], input, textarea, select'; the panel itself if nothing matches. */
     focusSelector?: string;
+    /** Keep the background in place and remove scrim blur; default 'recede'. Modality is unchanged. */
+    background?: 'recede' | 'stationary';
+    /** Lazy fallback when the captured invoker can no longer receive focus. */
+    returnFocus?: () => HTMLElement | null;
     className?: string;
 }
-export declare function Dialog({ open, defaultOpen, onOpenChange, trigger, title, description, children, footer, size, dismissible, initialFocus, focusSelector, className }: DialogProps): React.JSX.Element;
+export declare function Dialog({ open, defaultOpen, onOpenChange, trigger, title, description, children, footer, size, dismissible, initialFocus, focusSelector, background, returnFocus, className }: DialogProps): React.JSX.Element;
 export type ToastTone = 'neutral' | 'positive' | 'caution' | 'critical';
 export interface ToastOptions {
     title: React.ReactNode;
@@ -126,6 +158,8 @@ export interface ToastOptions {
         label: string;
         onClick: () => void;
     };
+    /** false: shown but not announced, because what it says was already announced where it happened. Default true. */
+    announce?: boolean;
 }
 export declare function toast(input: ToastOptions | string): number;
 export declare namespace toast {

package/dist/types/page-header.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import { MenuEntry } from './overlays.js';
+export interface PageHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+    /** A Breadcrumb above the title. */
+    breadcrumb?: React.ReactNode;
+    /** The page's one primary action: a single Button variant="primary". There's one slot, so there's one primary. */
+    primary?: React.ReactElement;
+    /** Secondary and ghost actions, before the primary. */
+    actions?: React.ReactNode;
+    /** Actions that don't need to be seen, in a "More actions" menu. */
+    overflow?: MenuEntry[];
+    /** Tabs under the title, for the page's sections. */
+    tabs?: React.ReactNode;
+    /** Stays at the top while the page scrolls, and rises one level when content passes under it. */
+    sticky?: boolean;
+    /** PageHeaderTitle and PageHeaderDescription. */
+    children?: React.ReactNode;
+}
+/**
+ * The block every page opens with: breadcrumb, title, description, actions and tabs. The page's name is the record, so
+ * the block lies on the ground; only its actions are live, and it has one slot for the primary action (law 1).
+ */
+export declare function PageHeader({ breadcrumb, primary, actions, overflow, tabs, sticky, className, children, ...rest }: PageHeaderProps): React.JSX.Element;
+/** The page's h1. */
+export declare function PageHeaderTitle({ className, ...rest }: React.HTMLAttributes<HTMLHeadingElement>): React.JSX.Element;
+/** One line saying what the page is for. */
+export declare function PageHeaderDescription({ className, ...rest }: React.HTMLAttributes<HTMLParagraphElement>): React.JSX.Element;

package/dist/types/pagination.d.ts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+/** The pages shown: the first, the last, the current one and `siblings` either side, with a gap where pages are skipped. */
+export declare function pageRange(page: number, count: number, siblings?: number): (number | 'gap')[];
+export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange'> {
+    /** The current page, from 1. */
+    page: number;
+    /** How many pages. Leave it out for cursor paging: Previous and Next, and "Page 3". */
+    pageCount?: number;
+    onPageChange?: (page: number) => void;
+    /** With pageSize: the summary "21–40 of 214". */
+    total?: number;
+    pageSize?: number;
+    /** Pages have URLs: they're links. Without it they're buttons. */
+    hrefFor?: (page: number) => string;
+    /** For cursor paging: whether there's a next page. Default true. */
+    hasNext?: boolean;
+    /** Pages either side of the current one. Default 1. */
+    siblings?: number;
+    /** The next page is loading: the thumb is held pressed until it lands. */
+    loading?: boolean;
+    /** What's being paged, plural, for the summary ("invoices"). */
+    noun?: string;
+    locale?: string;
+}
+/**
+ * Move through pages of a collection. The page numbers sit in a trench and the current page is one raised thumb that
+ * travels to it, as RadioGroup's does: "you are here, among these". They stay links (or buttons) in plain Tab order.
+ */
+export declare function Pagination({ page, pageCount, onPageChange, total, pageSize, hrefFor, hasNext, siblings, loading, noun, locale, className, 'aria-label': label, ...rest }: PaginationProps): React.JSX.Element;

package/dist/types/palette.d.ts

@@ -0,0 +1,64 @@
+type Vec = [number, number, number];
+/** [lightness 0–1, chroma, hue in degrees] */
+export declare function oklch(hex: string): Vec;
+/** OKLCH → hex, or null when the colour is outside sRGB. */
+export declare function fromOklch(L: number, C: number, h: number): string | null;
+/** The most chroma (to 0.001) that hue h holds at lightness L inside sRGB. */
+export declare function maxChroma(L: number, h: number): number;
+export type Vision = 'normal' | 'protan' | 'deutan';
+/** OKLab ΔE × 100 between two hex colours, as seen with normal vision or simulated protanopia or deuteranopia. */
+export declare function deltaE(a: string, b: string, kind?: Vision): number;
+/** The smaller of the protan and deutan ΔE. */
+export declare const cvdDeltaE: (a: string, b: string) => number;
+export declare function contrastRatio(a: string, b: string): number;
+export declare const hueGap: (a: number, b: number) => number;
+/** A scheme is dark when its ground is, by the same test deriveAccent uses. */
+export declare const isDarkGround: (ground: string) => boolean;
+export declare const DATA_GATES: {
+    reserved: number;
+    normal: number;
+    hue: number;
+    cvd: number;
+    cvdAny: number;
+    contrast: number;
+    chroma: number;
+    band: Record<"light" | "dark", [number, number]>;
+    rampStep: number;
+    pole: number;
+    context: {
+        chroma: number;
+        line: number;
+        other: number;
+    };
+};
+export declare const DATA_SLOTS: readonly ["data-1", "data-2", "data-3", "data-4", "data-5", "data-6"];
+export declare const DATA_RESERVED: readonly ["accent", "positive", "caution", "critical", "presence-1", "presence-2", "presence-3"];
+export declare const DATA_SEQ: readonly ["data-seq-1", "data-seq-2", "data-seq-3", "data-seq-4", "data-seq-5", "data-seq-6", "data-seq-7"];
+export declare const DATA_DIV_NEG: readonly ["data-div-mid", "data-div-neg-1", "data-div-neg-2", "data-div-neg-3"];
+export declare const DATA_DIV_POS: readonly ["data-div-mid", "data-div-pos-1", "data-div-pos-2", "data-div-pos-3"];
+/** Every data-* token, in tokens.json order. */
+export declare const DATA_TOKENS: readonly ["data-1", "data-2", "data-3", "data-4", "data-5", "data-6", "data-other", "data-context", "data-seq-1", "data-seq-2", "data-seq-3", "data-seq-4", "data-seq-5", "data-seq-6", "data-seq-7", "data-div-neg-3", "data-div-neg-2", "data-div-neg-1", "data-div-mid", "data-div-pos-1", "data-div-pos-2", "data-div-pos-3"];
+/** Magnitude, low to high, in one hue: light schemes darken from near-white; dark schemes start near their ground and climb. */
+export declare function sequentialRamp(h: number, dark: boolean): string[];
+/**
+ * Measure the data-* tokens against every gate. `get` returns a token's value by name (without `--`); every value
+ * must already be a hex colour. Returns one sentence per problem.
+ */
+export declare function checkDataPalette(get: (name: string) => string): string[];
+/**
+ * Colours that could be data-1 for a brand accent, best first: the accent's hue (then hues up to 30° either side), at
+ * lightnesses nearest the accent's, each clearing the band, chroma, 3:1 on ground and raised, and the reserved hues.
+ */
+export declare function accentCandidates(accent: string, get: (name: string) => string): string[];
+/**
+ * A scheme's six slots, led by a brand accent. The slot nearest the accent makes way: the first candidate (see
+ * accentCandidates) that keeps every pairwise gate with the other five takes its place, or, if none does, that nearest
+ * slot leads unchanged. The other five are re-ordered behind data-1: every order is tried and the greatest minimum
+ * adjacent CVD ΔE wins, ties keeping the scheme's order; if none clears the adjacent gate, the slot closest to data-1
+ * is dropped and the rest tried again. Dropped slots leave the end of the palette to data-other. Deterministic.
+ */
+export declare function leadSlots(accent: string, candidates: string[], slots: string[]): {
+    slots: string[];
+    dropped: string[];
+};
+export {};

package/dist/types/password-input.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { InputProps } from './controls.js';
+export interface PasswordRequirement {
+    label: string;
+    test: (value: string) => boolean;
+}
+export interface PasswordInputProps extends Omit<InputProps, 'type' | 'trailing'> {
+    /** Scores a password from 0 (weakest) to 4 (strongest); your app supplies the scoring (zxcvbn, your rules). Shown as a Meter. */
+    strength?: (value: string) => number;
+    /** The word for each score, 0 to 4. Default "Very weak", "Weak", "Fair", "Good", "Strong". */
+    strengthLabels?: [string, string, string, string, string];
+    /** Rules shown under the field, each stamped as met or not as the password changes. */
+    requirements?: PasswordRequirement[];
+    /** The reveal toggle's name. It never changes with its state. Default "Show password". */
+    revealLabel?: string;
+}
+/**
+ * A password field: an Input with a reveal Toggle in its end cap, a caps-lock notice, and, when creating one, its
+ * strength as a reading (a Meter, never a Progress) and its requirements stamped as met. Strength and requirements
+ * describe the field and are announced politely once typing pauses.
+ */
+export declare const PasswordInput: React.ForwardRefExoticComponent<PasswordInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/types/pattern-assistant-conversation.d.ts

@@ -0,0 +1,55 @@
+/** What a turn is doing. 'interrupted' is an unfinished answer found after a reload; 'awaiting-input' is a Confirmation or Question open. */
+export type AssistantTurnState = 'ready' | 'submitted' | 'streaming' | 'complete' | 'stopped' | 'failed' | 'interrupted' | 'awaiting-input';
+export type AssistantErrorKind = 'offline' | 'rate-limited' | 'context-full' | 'refused' | 'outage' | 'unknown';
+/** Throw this from `stream` to say what went wrong; anything else is 'unknown' (or 'offline' when the browser is offline). */
+export declare class AssistantError extends Error {
+    kind: AssistantErrorKind;
+    /** For 'rate-limited': when it can be tried again. */
+    retryAt?: Date | number;
+    constructor(kind: AssistantErrorKind, message?: string, retryAt?: Date | number);
+}
+export interface AssistantTurnError {
+    kind: AssistantErrorKind;
+    retryAt?: Date | number;
+    message?: string;
+}
+export interface AssistantTurnOptions<I> {
+    /** Starts the answer: yield text as it arrives; resolve when the stream says it's complete. Abort on `signal`. */
+    stream: (input: I, signal: AbortSignal) => AsyncIterable<string>;
+    /** An answer restored after a reload. If it wasn't complete it's 'interrupted', never shown as complete. */
+    restored?: {
+        input: I;
+        text: string;
+        complete: boolean;
+    };
+    locale?: string;
+}
+export interface AssistantTurn<I> {
+    state: AssistantTurnState;
+    /** The answer so far: kept when stopped, failed or interrupted. */
+    text: string;
+    /** What was sent, kept until it's answered: put it back in the composer when sending fails. */
+    input: I | undefined;
+    error: AssistantTurnError | null;
+    /** The error in words, with what to do: "You've reached this hour's limit. Try again at 3:40 PM." */
+    errorText: string;
+    /** Map onto the components. */
+    promptStatus: 'ready' | 'submitted' | 'streaming' | 'error';
+    messageStatus: 'streaming' | 'complete' | 'stopped' | 'error' | undefined;
+    /** Sends unless a turn is already in flight (a double Enter sends once). Returns whether it started. */
+    submit: (input: I) => boolean;
+    stop: () => void;
+    /** Sends the last input again (after a failure, a stop or an interruption). */
+    retry: () => boolean;
+    /** A Confirmation or Question is open (true) or answered (false): the turn waits for the person. */
+    awaitInput: (waiting: boolean) => void;
+}
+/** Each error kind in words, with what to do. */
+export declare function assistantErrorText(error: AssistantTurnError | null, locale?: string): string;
+/**
+ * The assistant-conversation contract's turn (project/framework/patterns/assistant-conversation.md, #285): a send that
+ * can't happen twice, a stream whose late events from a superseded turn are ignored, Stop that keeps the partial
+ * answer, completion only when the stream says so, an unfinished answer after a reload shown as interrupted, and each
+ * error kind in words. Map `promptStatus` to PromptInput and `messageStatus` to the answer's Message.
+ */
+export declare function useAssistantTurn<I>({ stream, restored, locale }: AssistantTurnOptions<I>): AssistantTurn<I>;

package/dist/types/pattern-async-collection.d.ts

@@ -0,0 +1,34 @@
+export type CollectionPhase = 'loading' | 'refreshing' | 'populated' | 'empty' | 'no-results' | 'failed';
+export interface AsyncCollectionOptions<T, Q> {
+    initialQuery: Q;
+    /** Own query semantics, permissions, pagination and URL/history in the application. Abort is advisory. */
+    load: (query: Q, context: {
+        signal: AbortSignal;
+    }) => readonly T[] | Promise<readonly T[]>;
+    getKey: (item: T) => string;
+    isFiltered: (query: Q) => boolean;
+    /** preserve deliberately retains keys absent from the current page/filter; reconcile deleted identities in the app. */
+    selection: 'clear-on-query' | 'preserve';
+    messages?: Partial<{
+        loading: string;
+        refreshing: string;
+        empty: string;
+        noResults: string;
+        failed: string;
+        results: (count: number) => string;
+    }>;
+}
+/** Stale-response-safe collection, with explicit selection policy. See altitude-design/guidance/patterns/async-collection.md. */
+export declare function useAsyncCollection<T, Q>(options: AsyncCollectionOptions<T, Q>): {
+    setQuery: (query: Q) => void;
+    refresh: () => void;
+    reset: () => void;
+    clearSelection: () => void;
+    toggleSelection: (key: string) => void;
+    query: Q;
+    items: readonly T[];
+    phase: CollectionPhase;
+    error: string;
+    status: string;
+    selectedKeys: ReadonlySet<string>;
+};

package/dist/types/pattern-consequential-action.d.ts

@@ -0,0 +1,53 @@
+export type ActionResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+export type UndoResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export type ConsequentialPhase = 'idle' | 'confirming' | 'pending' | 'failed' | 'succeeded' | 'undoing' | 'undone';
+interface ActionBase<T> {
+    /** Render target and consequence alongside the trigger and in any confirmation. */
+    target: string;
+    consequence: string;
+    execute: () => ActionResult<T> | Promise<ActionResult<T>>;
+    /** Connected, visible next logical destination when the original trigger disappears. */
+    focusFallback?: () => HTMLElement | null;
+    messages?: Partial<{
+        pending: string;
+        succeeded: string;
+        failed: string;
+        undoing: string;
+        undone: string;
+    }>;
+}
+export type ConsequentialActionOptions<T> = ActionBase<T> & ({
+    requiresConfirmation: true;
+    undo?: (result: T) => UndoResult | Promise<UndoResult>;
+} | {
+    requiresConfirmation: false;
+    undo: (result: T) => UndoResult | Promise<UndoResult>;
+});
+/** Confirmation records intent; only execute success records completion. Undo is offered only with an application-supplied inverse.
+ * Compose Dialog/Alert/Button with the returned content and states. See altitude-design/guidance/patterns/consequential-action.md. */
+export declare function useConsequentialAction<T>(options: ConsequentialActionOptions<T>): {
+    target: string;
+    consequence: string;
+    canUndo: boolean;
+    request: () => void;
+    confirm: () => void;
+    cancel: () => void;
+    retry: () => Promise<void> | undefined;
+    undo: (() => Promise<void>) | undefined;
+    phase: ConsequentialPhase;
+    error: string;
+    status: string;
+    result: T | undefined;
+};
+export {};

package/dist/types/pattern-edit-record.d.ts

@@ -0,0 +1,72 @@
+import * as React from 'react';
+export type FieldErrors<T> = Partial<Record<keyof T, string>>;
+export type EditRecordResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+    errors?: FieldErrors<T>;
+};
+export type EditRecordPhase = 'editing' | 'invalid' | 'submitting' | 'saved' | 'failed';
+export type LeaveReason = 'cancel' | 'back' | 'navigation';
+export interface EditRecordOptions<T extends object> {
+    /** Initial snapshot only. Use reset to deliberately adopt another record; keep snapshots immutable. */
+    initialValue: T;
+    validate: (draft: T) => FieldErrors<T>;
+    /** Submit validates every field; blur additionally validates the blurred field. Corrections revalidate visible errors. */
+    validationMode: 'submit' | 'blur';
+    save: (draft: T, context: {
+        previousValue: T;
+    }) => EditRecordResult<T> | Promise<EditRecordResult<T>>;
+    /** Supply semantic equality for nested values. The default compares top-level fields with Object.is. */
+    isEqual?: (a: T, b: T) => boolean;
+    messages?: Partial<{
+        saving: string;
+        saved: string;
+        failed: string;
+        invalid: string;
+        newerEdits: string;
+    }>;
+}
+/** Small record workflow. Persistence, concurrency/version checks, authorization and route interception belong to the app.
+ * See altitude-design/guidance/patterns/edit-record.md. A response never replaces edits made after dispatch.
+ */
+export declare function useEditRecord<T extends object>(options: EditRecordOptions<T>): {
+    dirty: boolean;
+    setDraft: (draft: T) => void;
+    setField: <K extends keyof T>(key: K, value: T[K]) => void;
+    validateField: (key: keyof T) => void;
+    validateAll: () => boolean;
+    submit: () => Promise<EditRecordResult<T> | undefined>;
+    reset: (value?: T) => boolean;
+    requestLeave: (reason: LeaveReason, confirmDiscard: (context: {
+        reason: LeaveReason;
+        draft: T;
+    }) => boolean | Promise<boolean>) => Promise<boolean>;
+    draft: T;
+    baseline: T;
+    errors: FieldErrors<T>;
+    error: string;
+    phase: EditRecordPhase;
+    status: string;
+    submitCount: number;
+};
+export interface ErrorSummaryProps {
+    errors: readonly {
+        id: string;
+        label: string;
+        message: string;
+    }[];
+    title?: string;
+    /** Change after an unsuccessful submit to focus the summary. Omit to keep focus where it is. */
+    focusKey?: number;
+    className?: string;
+}
+/** Render from the same errors passed to Field; use each input's actual id. Inline Field owns alert announcements. */
+export declare function ErrorSummary({ errors, title, focusKey, className }: ErrorSummaryProps): React.JSX.Element | null;
+/** Place outside any aria-busy region so pending and completion remain announced. */
+export declare function WorkflowStatus({ children, className }: {
+    children?: React.ReactNode;
+    className?: string;
+}): React.JSX.Element;

package/dist/types/pattern-review-submit.d.ts

@@ -0,0 +1,43 @@
+import type { FieldErrors } from './pattern-edit-record.js';
+export type ReviewSubmitResult<T, R> = {
+    ok: true;
+    receipt: R;
+} | {
+    ok: false;
+    error: string;
+    errors?: FieldErrors<T>;
+};
+export interface ReviewSubmitOptions<T extends object, R> {
+    /** Supply any recovered draft here. Durable storage, step dependencies and cross-session resume are application responsibilities. */
+    initialValue: T;
+    validate: (draft: T) => FieldErrors<T>;
+    submit: (draft: T) => ReviewSubmitResult<T, R> | Promise<ReviewSubmitResult<T, R>>;
+    isEqual?: (a: T, b: T) => boolean;
+    messages?: Partial<{
+        submitting: string;
+        complete: string;
+        failed: string;
+        invalid: string;
+    }>;
+}
+/** Review/correct/submit composition with a persistent application-provided receipt. No automatic persistence or fabricated resume.
+ * See altitude-design/guidance/patterns/review-submit.md. Mount a new workflow to start a distinct transaction after completion. */
+export declare function useReviewSubmit<T extends object, R>(options: ReviewSubmitOptions<T, R>): {
+    draft: T;
+    errors: Partial<Record<keyof T, string>>;
+    error: string;
+    status: string;
+    submitCount: number;
+    dirty: boolean;
+    phase: "review" | "editing" | "complete" | "submitting";
+    receipt: R | undefined;
+    setDraft: (value: T) => void;
+    setField: <K extends keyof T>(key: K, value: T[K]) => void;
+    review: () => void;
+    correct: () => void;
+    submit: () => Promise<void>;
+    requestLeave: (reason: import("./pattern-edit-record.js").LeaveReason, confirmDiscard: (context: {
+        reason: import("./pattern-edit-record.js").LeaveReason;
+        draft: T;
+    }) => boolean | Promise<boolean>) => Promise<boolean>;
+};

package/dist/types/permission-matrix.d.ts

@@ -0,0 +1,34 @@
+import * as React from 'react';
+export interface MatrixRole {
+    id: string;
+    name: string; /** Every permission is always granted (an owner). */
+    locked?: boolean;
+}
+export interface MatrixPermission {
+    id: string;
+    name: string; /** Rows with the same group sit under its heading. */
+    group?: string;
+}
+export interface MatrixInherited {
+    granted: boolean; /** Where it comes from ("Admin"). */
+    from: string;
+}
+export interface PermissionMatrixProps {
+    roles: MatrixRole[];
+    permissions: MatrixPermission[];
+    /** Grants you can change: value[roleId][permissionId]. */
+    value: Record<string, Record<string, boolean>>;
+    /** A grant decided elsewhere (a parent role, a group): shown as a stamped mark, not a choice. */
+    inherited?: (roleId: string, permissionId: string) => MatrixInherited | undefined;
+    /** Called when a choice is toggled. Return a promise and the cell hovers as pending until it settles; a rejection reverts it. */
+    onChange?: (roleId: string, permissionId: string, granted: boolean) => void | Promise<unknown>;
+    /** Names the grid ("Role permissions"). */
+    'aria-label'?: string;
+    className?: string;
+}
+/**
+ * Roles against permissions. The grid is settled (the record of who can do what). An editable grant is a choice, built
+ * like a Checkbox (a trench the accent pours into); an inherited or fixed grant is already decided, so it's a flush
+ * stamped check, not a disabled box. The active cell is a ring, never a height. A grid: arrows move, Space toggles.
+ */
+export declare function PermissionMatrix({ roles, permissions, value, inherited, onChange, 'aria-label': label, className }: PermissionMatrixProps): React.JSX.Element;

package/dist/types/plan-picker.d.ts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+export interface Plan {
+    id: string;
+    name: string;
+    description?: React.ReactNode;
+    /** In minor units (cents), per period; a single number is the same for both. Null: no price (Contact sales). */
+    price: {
+        month: number;
+        year: number;
+    } | number | null;
+    /** ISO 4217. Default 'USD'. */
+    currency?: string;
+    /** What the price is for ("per seat"). */
+    unit?: string;
+    features?: string[];
+    /** Why it can't be chosen ("Contact sales for more than 500 seats"). */
+    unavailable?: string;
+}
+export interface PlanPickerProps {
+    plans: Plan[];
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (id: string) => void;
+    /** The plan they're on now: a "Current plan" plate. */
+    current?: string;
+    /** A plan you suggest: a "Recommended" plate, never extra height. */
+    recommended?: string;
+    /** The billing period, with a Monthly / Annually switch when onPeriodChange is given. Annual prices are per month, billed yearly. */
+    period?: 'month' | 'year';
+    onPeriodChange?: (period: 'month' | 'year') => void;
+    locale?: string;
+    'aria-label'?: string;
+    className?: string;
+}
+/**
+ * Choose a plan. The plans are positions in one choice, so the cards lie flush and one raised mark travels to the chosen
+ * one, as RadioGroup's thumb does. "Current plan" and "Recommended" are plates, not height: marketing emphasis isn't
+ * importance. The only level-2 slab is your Continue button, outside it.
+ */
+export declare function PlanPicker({ plans, value, defaultValue, onValueChange, current, recommended, period, onPeriodChange, locale, 'aria-label': label, className }: PlanPickerProps): React.JSX.Element;