@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/components/InlineEdit.d.ts

@@ -0,0 +1,183 @@
+import { type Ref } from "react";
+import { useRender } from "@base-ui/react/use-render";
+import { type EditActivation } from "./edit/activation";
+import { type EditCommit } from "./edit/outcome";
+import { type CommitMode } from "./edit/use-edit-session";
+interface InlineEditFieldProps {
+    /**
+     * The committed value. Controlled — this component never holds the truth,
+     * only the draft while somebody is typing one.
+     */
+    value: string;
+    /**
+     * Commit a new value. Called ONLY when the live text differs both from
+     * `value` and from the value editing began from — text the reader did not
+     * change is never written back, even if `value` moved underneath the open
+     * field (with `autosaveMs`, "unchanged" is measured against the last value
+     * this edit committed instead — see "AUTOSAVE").
+     *
+     * `base` is the `value` this control saw at the moment editing BEGAN —
+     * captured once and handed back unchanged regardless of how long the edit or
+     * the save takes. Compare it against whatever you currently believe is
+     * authoritative to tell "this would overwrite a change that landed while I
+     * was editing" from "nothing has moved". See the module comment
+     * ("THE OVERWRITE-PROTECTION CONTRACT") for the DX-2907 problem this closes.
+     *
+     * May return a promise, in which case the field stays open and pending until
+     * it settles. Resolve/return `{ refusal }` to reject the value with a
+     * reason; throw or reject to report that the save itself failed.
+     */
+    onCommit: EditCommit;
+    /**
+     * The refusals that are knowable WITHOUT a request. Return the reason, or
+     * `null` to accept. Runs after the unchanged check and before `onCommit`.
+     */
+    validate?: (value: string) => string | null;
+    /**
+     * The same shape as `validate`, but checked on EVERY keystroke instead of
+     * only at commit (SG-909) — an email/URL field flagging a typo while the
+     * reviewer is still typing, not only once they leave the box. Shares the
+     * one message slot `validate`'s refusal already draws from, so a live
+     * warning and a commit-time refusal never show two different sentences at
+     * once — whichever is current simply replaces the other. Purely advisory:
+     * it never freezes the field or drops a keystroke (R-12) the way a refused
+     * COMMIT does; it only decides what the message area says while typing.
+     * Pass the identical function as `validate` too if an invalid value should
+     * also be refused at commit — `liveValidate` on its own only ever warns.
+     *
+     * ALSO RUNS THE INSTANT EDITING OPENS (`begin()`), not only on the first
+     * keystroke — so a field that already holds an invalid stored value (e.g.
+     * a bad address that predates this check) shows the warning as soon as the
+     * reviewer clicks in, before they have typed anything at all, rather than
+     * waiting for them to disturb the text first.
+     */
+    liveValidate?: (value: string) => string | null;
+    /**
+     * The virtual keyboard a touch device shows for this field — `"email"` /
+     * `"tel"` / `"url"` bring up the matching layout. `InlineEdit` is a
+     * `contentEditable` box, not an `<input>`, so this is the only lever it has
+     * for that; unlike a real `<input type="email">`, the attribute alone does
+     * not also change parsing or validation, both of which stay entirely
+     * `validate`/`liveValidate`'s job.
+     */
+    inputMode?: "text" | "email" | "tel" | "url" | "numeric" | "decimal" | "search" | "none";
+    /**
+     * The accessible name AND accessible value's label, in both states —
+     * `role="textbox"` computes its accessible value from its own text content,
+     * so this is the one thing that has to be said separately. REQUIRED.
+     */
+    label: string;
+    /**
+     * What the control shows in place of a blank value, and its
+     * `aria-placeholder`.
+     *
+     * Omit for the built-in empty text.
+     */
+    placeholder?: string;
+    /** Box ramp. Matches `Input`'s names. */
+    size?: "sm" | "md" | "lg";
+    /**
+     * How the field wraps and how Enter behaves. Three shapes, not a boolean,
+     * because "wraps visually" and "Enter inserts a newline" are independent
+     * axes — DX-3388 needed a line that wraps but never contains "\n", which a
+     * single `multiline` flag could not express without a second bolted-on
+     * prop.
+     *
+     * - `"single"` (default) — no wrap; scrolls horizontally while editing,
+     *   truncates at rest. Enter commits (Shift+Enter is a no-op — there is
+     *   nowhere for a second line to go).
+     * - `"wrap"` — wraps visually like `"multiline"`, but Enter still commits
+     *   exactly as `"single"` does. Every typed or pasted newline is normalised
+     *   to a single space by the same `beforeinput` interception that
+     *   `"single"` uses to strip them — the committed value can never contain
+     *   "\n". For a title or summary: readable while long, never a literal
+     *   line break in something that flows into a list row, Trello, or a
+     *   commit message.
+     * - `"multiline"` — grows as a multi-line block. THE COMMIT KEY MOVES,
+     *   because Enter has to insert a newline instead: Enter inserts "\n",
+     *   Cmd/Ctrl+Enter commits, Escape still cancels, blur still commits.
+     */
+    lineMode?: "single" | "wrap" | "multiline";
+    /**
+     * Save WHILE the reader types: commit this many milliseconds after the last
+     * keystroke, with the field still open. Enter (Shift+Enter is the newline in
+     * `multiline`), blur, and Cmd/Ctrl+Enter commit and exit; Escape cancels the
+     * pending debounce and reverts to the last committed value. Saves are
+     * serialised — see the module comment ("AUTOSAVE") for the full contract.
+     *
+     * Omit for the commit-on-blur/Enter behaviour. Must be a positive number.
+     */
+    autosaveMs?: number;
+    /**
+     * `"close"` closes the field the moment a commit that returns a promise is
+     * sent, instead of freezing it until the promise settles - for a screen that
+     * already shows the new value. A refusal or failure that lands afterwards
+     * reopens the field with the text that was sent and the message under it,
+     * unless the field was opened again meanwhile (a later commit wins). Not
+     * combinable with `autosaveMs`. Default `"wait"`.
+     */
+    commitMode?: CommitMode;
+    /**
+     * This value cannot be edited at all, AND WHY. `{ reason }`, matching
+     * `SettingRow.readOnly` — a control that refuses in silence is
+     * indistinguishable from one that is broken. Under controlled activation a
+     * request to open (`editing` true) is declined by handing the closed state
+     * straight back through `onEditingChange(false)`, so a pencil driving it
+     * returns instead of waiting on a field that will never open (DX-3372 H3).
+     */
+    readOnly?: {
+        reason: string;
+    };
+    /**
+     * What is shown when the commit REJECTS (a thrown error or a rejected
+     * promise — never a `{ refusal }`, which renders its own text).
+     *
+     * Omit for the built-in sentence, which names the key that commits in this
+     * configuration: Enter, or Ctrl+Enter for a `multiline` field without
+     * `autosaveMs` (blur never re-attempts a failed value, DX-3372 review L1).
+     */
+    failureMessage?: string;
+    /** The rejected error, handed on so it can be logged or reported. */
+    onError?: (error: unknown) => void;
+    /** Render as a different element — see `Button`'s own `render` for the shape. */
+    render?: useRender.RenderProp;
+    /**
+     * Applied in both states, and there is only one of these on purpose — see
+     * `box` above: anything that changes the box's geometry has to reach both
+     * states or the control shifts on click, and a control cannot shift on click
+     * when both states are the same element unless a class only reaches one of
+     * them.
+     */
+    className?: string;
+    /** The refusal/failure message only — NOT the box. See 5.2.1's own doc for why it is a separate prop. */
+    messageClassName?: string;
+    ref?: Ref<HTMLElement>;
+}
+/**
+ * SELF-ACTIVATED: omit `editing` and the control opens itself on click, Enter
+ * or F2. `onEditingChange` then only observes — it fires when the control
+ * starts editing and when it stops, so a caller can suspend its own
+ * re-render-from-server logic for exactly as long as someone is typing.
+ */
+interface InlineEditSelfActivated {
+    editing?: undefined;
+    onEditingChange?: (editing: boolean) => void;
+}
+/**
+ * The props. `editing` + `onEditingChange` are a discriminated pair
+ * (DX-3372 review P0): either omit `editing` (self-activated, above) or pass
+ * BOTH (`EditActivation` — controlled). Controlled, the control never opens
+ * itself; `true` opens it focused with the caret at the end; it hands the
+ * closed state back through `onEditingChange(false)` after a landed commit,
+ * Escape, or a refused opening (read-only). Setting `editing` false yourself
+ * ends the edit exactly as Escape does — nothing more is written. A save that
+ * is already out when you do cannot be recalled: it still reaches your
+ * `onCommit` promise, but its outcome no longer touches the field — no
+ * message, no focus move, no second `onEditingChange(false)` — and a commit
+ * from the next opening waits for it before starting (see
+ * `edit/use-edit-session.ts`). At rest a controlled control leaves the tab
+ * order and drops its hover affordance, so the trigger is the one stop.
+ */
+export type InlineEditProps = InlineEditFieldProps & (InlineEditSelfActivated | EditActivation);
+export declare function InlineEdit(props: InlineEditProps): import("react").JSX.Element;
+export {};

package/dist/types/components/InlineMarkdownEdit.d.ts

@@ -0,0 +1,100 @@
+import { type ReactNode } from "react";
+import type { ImageUploader } from "../lib/markdown/image-pipeline";
+import { type EditActivation } from "./edit/activation";
+import { type EditCommit } from "./edit/outcome";
+import { type CommitMode } from "./edit/use-edit-session";
+export interface InlineMarkdownEditProps extends EditActivation {
+    /** The committed markdown. Controlled — the field only ever holds a draft. */
+    value: string;
+    /**
+     * Commit a new value — the same contract as `InlineEdit.onCommit`: called
+     * only when the draft differs from `value`, with `base` = the value editing
+     * began from; return/resolve `{ refusal }` to refuse with a reason, throw or
+     * reject to report a failed save.
+     */
+    onCommit: EditCommit;
+    /**
+     * Whether the editor is open — REQUIRED, see the module comment. The field
+     * hands the closed state back through `onEditingChange(false)` once a commit
+     * lands, on Escape, and when asked to open while `readOnly`. Setting it
+     * `false` yourself drops the draft exactly as Escape does. A save already
+     * out when you do cannot be recalled: your `onCommit` promise still settles,
+     * but its outcome no longer touches the field — no message, no focus move,
+     * no `onEditingChange(false)` — and a commit from the next opening waits for
+     * it before starting.
+     */
+    editing: boolean;
+    /**
+     * What each opening starts from instead of `value` — a draft the caller kept
+     * from an earlier, unfinished edit (DX-5229). `value` stays the committed text
+     * and `onCommit`'s `base`, so "unchanged" and conflict checks still measure
+     * against the record, not the draft. Read once per opening.
+     */
+    initialDraft?: string;
+    /**
+     * Fires with the whole draft after each change the reader makes in the open
+     * editor (not on opening, not on a commit). It is how a caller keeps an
+     * unsent edit somewhere durable; cancelling is the caller's own
+     * `onEditingChange(false)`.
+     */
+    onDraftChange?: (draft: string) => void;
+    /** The accessible name of the field and of its editor. */
+    label: string;
+    /** Shown at rest and in the editor when the value is empty. Omit for the built-in text. */
+    placeholder?: string;
+    /** Collapse the rendered view to this many lines behind a `ReadMore`. */
+    collapsedLines?: number;
+    /**
+     * Shown at rest after the rendered value, never in the editor. With
+     * `collapsedLines` it sits inside the same `ReadMore`, under the fold: a
+     * card's description lists its decisions there (DX-6416).
+     */
+    restingFooter?: ReactNode;
+    /** Extra toolbar content for the editor, after its built-in groups. */
+    toolbar?: ReactNode;
+    /** Stores a pasted/dropped/picked image — see `MarkdownEditorProps.uploadImage`. */
+    uploadImage?: ImageUploader;
+    /** DXUI-74: stores any other file as a link — see `MarkdownEditorProps.uploadFile`. */
+    uploadFile?: ImageUploader;
+    /** DXUI-74: the picture types `uploadImage` stores — see `MarkdownEditorProps.imageTypes`. */
+    imageTypes?: readonly string[];
+    /** DXUI-74: whether a link's destination is a stored file, so it gets a tile — see `MarkdownEditorProps.isFileUrl`. */
+    isFileUrl?: (url: string) => boolean;
+    /**
+     * Fires whenever the open draft's image-upload state changes: `true` while
+     * any image in it is uploading, failed, or otherwise unstored; `false` once
+     * none are — INCLUDING when the field closes or unmounts with an upload
+     * still pending, so a caller wiring this straight into its own navigation
+     * guard can never get stuck armed after the field that armed it is gone.
+     * See the module comment ("NAVIGATION HOLD WHILE AN UPLOAD IS PENDING") for
+     * why this is a callback rather than a router hook.
+     */
+    onUploadStateChange?: (uploading: boolean) => void;
+    /**
+     * This value cannot be edited at all, AND WHY — `InlineEdit.readOnly`'s
+     * shape and rule: asked to open, the field hands `onEditingChange(false)`
+     * straight back, and the reason is the rest view's accessible description.
+     */
+    readOnly?: {
+        reason: string;
+    };
+    /**
+     * What is shown when the commit REJECTS (never a `{ refusal }`, which
+     * renders its own text).
+     *
+     * Omit for the built-in sentence, which names Ctrl+Enter as the retry key.
+     */
+    failureMessage?: string;
+    /** The rejected error, handed on so it can be logged or reported. */
+    onError?: (error: unknown) => void;
+    /**
+     * `"close"` closes the field (`onEditingChange(false)`) the moment a commit
+     * that returns a promise is sent, instead of freezing it until the promise
+     * settles. A refusal or failure that lands afterwards reopens it
+     * (`onEditingChange(true)`) with the text that was sent and the message under
+     * it, unless the field was opened again meanwhile. Default `"wait"`.
+     */
+    commitMode?: CommitMode;
+    className?: string;
+}
+export declare function InlineMarkdownEdit(props: InlineMarkdownEditProps): import("react").JSX.Element;

package/dist/types/components/Input.d.ts

@@ -0,0 +1,128 @@
+import type { ReactNode, Ref, TextareaHTMLAttributes } from "react";
+import { Input as BaseInput } from "@base-ui/react/input";
+import { type VariantProps } from "tailwind-variants";
+import { type SubmitAction } from "../lib/submit-shortcut";
+declare const control: import("tailwind-variants").TVReturnType<{
+    size: {
+        sm: "h-control-sm rounded-md px-3 text-xs";
+        md: "h-control-md rounded-md px-3.5 text-sm";
+        lg: "h-control-lg rounded-lg px-4 text-md";
+    };
+    hasLeading: {
+        true: "";
+        false: "";
+    };
+    hasTrailing: {
+        true: "";
+        false: "";
+    };
+}, undefined, string[], {
+    size: {
+        sm: "h-control-sm rounded-md px-3 text-xs";
+        md: "h-control-md rounded-md px-3.5 text-sm";
+        lg: "h-control-lg rounded-lg px-4 text-md";
+    };
+    hasLeading: {
+        true: "";
+        false: "";
+    };
+    hasTrailing: {
+        true: "";
+        false: "";
+    };
+}, undefined, import("tailwind-variants").TVReturnTypeLike<{
+    size: {
+        sm: "h-control-sm rounded-md px-3 text-xs";
+        md: "h-control-md rounded-md px-3.5 text-sm";
+        lg: "h-control-lg rounded-lg px-4 text-md";
+    };
+    hasLeading: {
+        true: "";
+        false: "";
+    };
+    hasTrailing: {
+        true: "";
+        false: "";
+    };
+}, undefined>>;
+export interface InputProps extends Omit<BaseInput.Props, "className" | "render" | "size">, VariantProps<typeof control> {
+    className?: string;
+    /** Icon or text shown inside the field's leading edge. */
+    leading?: ReactNode;
+    /** Icon, unit or action shown inside the field's trailing edge. */
+    trailing?: ReactNode;
+    /**
+     * Replaces the trailing adornment with a spinner — for a field doing its own
+     * async work (an availability check, a lookup) rather than a form-wide submit.
+     */
+    loading?: boolean;
+    ref?: Ref<HTMLInputElement>;
+}
+export declare function Input(allProps: InputProps): import("react").JSX.Element;
+declare const textarea: import("tailwind-variants").TVReturnType<{
+    size: {
+        sm: "rounded-md px-3 py-2 text-xs";
+        md: "rounded-md px-3.5 py-2.5 text-sm";
+        lg: "rounded-lg px-4 py-3 text-md";
+    };
+    /**
+     * `auto` uses field-sizing, which grows the box with its content with no
+     * JS, no hidden mirror element and no scroll-height measuring — the three
+     * things every auto-resize textarea implementation has needed until now.
+     * Engines without it simply keep the fixed height and a scrollbar, which
+     * is the correct graceful degradation.
+     */
+    resize: {
+        none: "resize-none";
+        vertical: "resize-y";
+        auto: "resize-none field-sizing-content";
+    };
+}, undefined, string[], {
+    size: {
+        sm: "rounded-md px-3 py-2 text-xs";
+        md: "rounded-md px-3.5 py-2.5 text-sm";
+        lg: "rounded-lg px-4 py-3 text-md";
+    };
+    /**
+     * `auto` uses field-sizing, which grows the box with its content with no
+     * JS, no hidden mirror element and no scroll-height measuring — the three
+     * things every auto-resize textarea implementation has needed until now.
+     * Engines without it simply keep the fixed height and a scrollbar, which
+     * is the correct graceful degradation.
+     */
+    resize: {
+        none: "resize-none";
+        vertical: "resize-y";
+        auto: "resize-none field-sizing-content";
+    };
+}, undefined, import("tailwind-variants").TVReturnTypeLike<{
+    size: {
+        sm: "rounded-md px-3 py-2 text-xs";
+        md: "rounded-md px-3.5 py-2.5 text-sm";
+        lg: "rounded-lg px-4 py-3 text-md";
+    };
+    /**
+     * `auto` uses field-sizing, which grows the box with its content with no
+     * JS, no hidden mirror element and no scroll-height measuring — the three
+     * things every auto-resize textarea implementation has needed until now.
+     * Engines without it simply keep the fixed height and a scrollbar, which
+     * is the correct graceful degradation.
+     */
+    resize: {
+        none: "resize-none";
+        vertical: "resize-y";
+        auto: "resize-none field-sizing-content";
+    };
+}, undefined>>;
+export interface TextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "size">, VariantProps<typeof textarea> {
+    ref?: Ref<HTMLTextAreaElement>;
+    /**
+     * DX-5596: Ctrl+Enter (Cmd+Enter on a Mac) runs `onSubmit` and a hint line under the box names it
+     * ("Ctrl+Enter to post"). Same contract as `MarkdownEditor`'s `submit`: `disabled` is the caller's
+     * own can't-submit rule, the chord is swallowed while it is true. Without it the box has no
+     * submit shortcut and no hint line.
+     */
+    submit?: SubmitAction;
+}
+export declare function Textarea({ className, size, resize, rows, ref, submit, onKeyDown, ...props }: TextareaProps): import("react").JSX.Element;
+export {};

package/dist/types/components/LegalDocument.d.ts

@@ -0,0 +1,23 @@
+import { type MouseEvent } from "react";
+import { type LegalDocumentValue } from "../lib/legal-document";
+export interface LegalDocumentProps {
+    document: LegalDocumentValue;
+    /**
+     * The element the title line is. `h1` when the document is the page's own
+     * heading, `p` when something else (an app shell's top bar) already owns the
+     * page's one `h1`.
+     */
+    titleAs?: "h1" | "p";
+    /** Names the contents list, and is the collapsed control's text until a section is current. */
+    contentsLabel?: string;
+    /**
+     * Runs when a contents link is clicked, with the section's anchor id and the
+     * click. The links are real `<a href="#section-N">`, which a path-based
+     * router leaves to the browser. A router that owns the fragment itself (a
+     * hash router) suppresses the browser's jump here, as `SectionNav` documents
+     * for its own rows, and scrolls the section into view instead.
+     */
+    onNavigate?: (anchor: string, event: MouseEvent<HTMLAnchorElement>) => void;
+    className?: string;
+}
+export declare function LegalDocument({ document: legal, titleAs: Title, contentsLabel, onNavigate, className, }: LegalDocumentProps): import("react").JSX.Element;

package/dist/types/components/LineDiff.d.ts

@@ -0,0 +1,53 @@
+/** Shared with `PatchDiff` (DX-5271): one row look for every line diff the library draws. */
+export declare const lineDiffRow: import("tailwind-variants").TVReturnType<{
+    kind: {
+        unchanged: "text-secondary";
+        removed: "bg-danger-subtle text-danger-text";
+        added: "bg-success-subtle text-success-text";
+        gap: "bg-surface-inset text-tertiary italic";
+    };
+}, undefined, "flex min-w-0 gap-2 rounded-sm px-2 py-0.5 font-mono text-xs whitespace-pre-wrap [overflow-wrap:anywhere]", {
+    kind: {
+        unchanged: "text-secondary";
+        removed: "bg-danger-subtle text-danger-text";
+        added: "bg-success-subtle text-success-text";
+        gap: "bg-surface-inset text-tertiary italic";
+    };
+}, undefined, import("tailwind-variants").TVReturnTypeLike<{
+    kind: {
+        unchanged: "text-secondary";
+        removed: "bg-danger-subtle text-danger-text";
+        added: "bg-success-subtle text-success-text";
+        gap: "bg-surface-inset text-tertiary italic";
+    };
+}, undefined>>;
+export interface LineDiffProps {
+    /** The baseline/default text this compares `after` against. */
+    before: string;
+    /** The current text being compared against `before`. */
+    after: string;
+    /** The accessible name for the diff region. */
+    label: string;
+    /**
+     * Show only this many unchanged lines either side of a change, folding each
+     * longer unchanged run into a "N unchanged lines" row (`git diff -U<n>`).
+     * Omitted: every line is shown. `0` shows the changed lines alone. DX-4041.
+     */
+    context?: number;
+    /**
+     * Fold each unchanged run longer than `context` (default 2) into a row a
+     * person can open: a few lines at a time under the change above or over the
+     * change below, or the whole run. Off: the fixed `context` mode. DXUI-38.
+     */
+    expandable?: boolean;
+    className?: string;
+}
+/**
+ * Renders a line-based diff of `after` against `before`: lines common to both
+ * are shown once, plain; a line only in `before` is shown once, styled as a
+ * removal; a line only in `after` is shown once, styled as an addition. A
+ * line edited in place shows as its old form removed immediately followed by
+ * its new form added. Identical `before`/`after` renders every line
+ * unchanged, with no added/removed markers at all.
+ */
+export declare function LineDiff({ before, after, label, context, expandable, className }: LineDiffProps): import("react").JSX.Element;

package/dist/types/components/ListHeader.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from "react";
+import { type FilterField } from "./FilterMenu";
+import { type IconName } from "./Icon";
+/** A list's filters as `FilterMenu` and `FilterChips` draw them: the fields, the one step that turns them all off, and the control's name. */
+export interface ListFilters {
+    fields: readonly FilterField[];
+    onClearAll: () => void;
+    /** Names the filter button for assistive technology, e.g. "Filter feedback". */
+    label: string;
+    /** The button's icon when the list filters by one kind of thing (a comment thread's tags); the funnel otherwise. */
+    icon?: IconName;
+}
+export interface ListHeaderProps {
+    /**
+     * DXUI-97: the keyword search is optional. `searchLabel` (the box's accessible name), `searchPlaceholder`, `query` and `onQueryChange` are passed
+     * together or not at all; a list with no keyword search (API keys, sessions Recent) passes none and the header draws no search box, button or chip.
+     */
+    searchLabel?: string;
+    searchPlaceholder?: string;
+    query?: string;
+    onQueryChange?: (query: string) => void;
+    /**
+     * Told the box's text on Enter, when the box loses focus and when it is emptied (typed empty or cleared with its x button), for a list that
+     * reads once per search and not once per keystroke.
+     */
+    onQueryCommit?: (query: string) => void;
+    /**
+     * DXUI-47: how the keyword search is drawn. `"box"` (the default) is the open search box. `"button"` is a search icon button, named by
+     * `searchLabel`, that opens a popover holding the box; the applied search then shows as a short removable chip beside the filter
+     * chips, and the button shows it is active. For a search that sits beside something else you type into (a comment thread), where an
+     * open box reads as the place to write. The `query` / `onQueryChange` / `onQueryCommit` contract is the same in both.
+     */
+    search?: "box" | "button";
+    /** The list's filters: ONE filter icon button right after the search box (before the sort), the applied ones as chips under the row. Never a row of `Select`s. */
+    filters?: ListFilters;
+    /** The controls at the row's end: the sort, and the caller's own. */
+    children?: ReactNode;
+    /**
+     * DXUI-94: where the controls row (the search, the filter button, the caller's own controls and the sort) is drawn. Passed, the row goes into that
+     * element, which a caller puts elsewhere (an overlay's title row) while the applied filters' chips stay under the header where it is; `null` is an
+     * element that has not mounted yet and draws no controls for now. Omitted (the default), the row sits in the header as always.
+     */
+    controlsHost?: HTMLElement | null;
+}
+export declare function ListHeader({ searchLabel, searchPlaceholder, query, onQueryChange, onQueryCommit, search, filters, children, controlsHost }: ListHeaderProps): import("react").JSX.Element;

package/dist/types/components/Loading.d.ts

@@ -0,0 +1,131 @@
+import type { CSSProperties, ReactNode, Ref } from "react";
+import { type VariantProps } from "tailwind-variants";
+declare const skeleton: import("tailwind-variants").TVReturnType<{
+    shape: {
+        text: "h-[1em] rounded-sm";
+        block: "rounded-md";
+        circle: "aspect-square rounded-full";
+        pill: "rounded-full";
+    };
+    sweep: {
+        true: "dx-sweep animate-none";
+        false: "";
+    };
+}, undefined, string[], {
+    shape: {
+        text: "h-[1em] rounded-sm";
+        block: "rounded-md";
+        circle: "aspect-square rounded-full";
+        pill: "rounded-full";
+    };
+    sweep: {
+        true: "dx-sweep animate-none";
+        false: "";
+    };
+}, undefined, import("tailwind-variants").TVReturnTypeLike<{
+    shape: {
+        text: "h-[1em] rounded-sm";
+        block: "rounded-md";
+        circle: "aspect-square rounded-full";
+        pill: "rounded-full";
+    };
+    sweep: {
+        true: "dx-sweep animate-none";
+        false: "";
+    };
+}, undefined>>;
+export interface SkeletonProps extends VariantProps<typeof skeleton> {
+    className?: string;
+    width?: string | number;
+    height?: string | number;
+    style?: CSSProperties;
+    ref?: Ref<HTMLSpanElement>;
+    /**
+     * Stack this many bars in a column instead of rendering one (SG-833
+     * slice 7) — for a loading LIST (a table's rows, a feed's cards), where the
+     * shape being previewed is "several of these", not one field.
+     *
+     * Extracted because every consumer needing this had written the same three
+     * lines by hand: `Array.from({ length: n }, (_, i) => <Skeleton key={i}
+     * .../>)` inside a `flex flex-col gap-3` wrapper carrying `aria-busy`/
+     * `aria-label="Loading"` — gpt-manager's Demand Desk had exactly this as its
+     * own `LoadingRows` component. `shape`/`sweep`/`className`/`width`/`height`
+     * apply to EACH bar; `repeat` only changes how many render and how they are
+     * laid out.
+     *
+     * 1 or omitted renders the plain single bar, unchanged from before this
+     * prop existed — including staying `aria-hidden` rather than gaining the
+     * wrapper's live-region treatment, so a lone field's skeleton doesn't start
+     * announcing itself.
+     */
+    repeat?: number;
+}
+export declare function Skeleton({ shape, sweep, className, width, height, style, ref, repeat, }: SkeletonProps): import("react").JSX.Element;
+export interface SkeletonTextProps {
+    /** How many lines to draw. */
+    lines?: number;
+    className?: string;
+}
+/**
+ * A paragraph-shaped skeleton.
+ *
+ * The last line is short. That single detail is what makes it read as text
+ * rather than as a stack of bars — every real paragraph ends mid-line, and a
+ * block of equal-length bars reads as a table.
+ */
+export declare function SkeletonText({ lines, className }: SkeletonTextProps): import("react").JSX.Element;
+export interface LoadingOverlayProps {
+    /** Whether the overlay is showing. */
+    active: boolean;
+    /** Text inside the card. Keep it short — it sits over content being read. */
+    message?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * Dims existing content and floats a card over it while that content is being
+ * replaced.
+ *
+ * TWO DETAILS DO THE REAL WORK.
+ *
+ * The veil is `inert`, not `pointer-events: none`. Blocking the mouse alone
+ * leaves every control underneath reachable by Tab and clickable by Enter, so
+ * a keyboard user can act on data that is mid-replacement — which is exactly
+ * the race the overlay exists to prevent. `inert` removes the subtree from the
+ * tab order and the accessibility tree together.
+ *
+ * The card is OPAQUE while the veil is translucent. A translucent card over
+ * translucent content produces text over text, which is unreadable at
+ * precisely the moment someone is trying to work out what is happening.
+ */
+export declare function LoadingOverlay({ active, message, children, className }: LoadingOverlayProps): import("react").JSX.Element;
+export interface LoadRegionProps {
+    /** True while the region's data is loading: the first load, or any later one (a filter, search, sort or page change, a refetch). */
+    loading: boolean;
+    /**
+     * Whether the region has ever had content to show. This is the caller's fact, never inferred from `loading`: a region that mounts
+     * idle and starts loading with nothing to show (a panel waiting on a choice, a load that failed) must still draw the skeleton.
+     */
+    hasContent: boolean;
+    /** Drawn only while `loading` and there is no content. */
+    skeleton: ReactNode;
+    /** Accessible name of the region while it loads. Defaults to the library's "Loading". */
+    label?: string;
+    /** Text inside the overlay card, when `loading` over content. */
+    message?: ReactNode;
+    /** The content. It must keep rendering its last data while `loading`, so the overlay has something to sit on. */
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * The one decision between the two treatments above, for a list or panel that loads its own data: `loading && !hasContent` is the
+ * skeleton, `loading && hasContent` is the content kept on screen under the refresh overlay, and anything else is the content.
+ *
+ * The content sits in one tree for the overlay and the idle states, so a reload starting remounts nothing and keeps focus and
+ * scroll inside it. A region is `aria-busy` and named (`role="group"`) exactly while it loads.
+ *
+ * NOT FOR A `DataTable`: it already takes `loading` (first load) and `refreshing` (a reload over rows) and draws both itself.
+ * Wrapping one in this would stack a second overlay on its own.
+ */
+export declare function LoadRegion({ loading, hasContent, skeleton, label, message, children, className }: LoadRegionProps): import("react").JSX.Element;
+export {};