altitude-design 0.2.0 → 0.3.0

package/dist/types/stepper.d.ts

@@ -11,8 +11,11 @@ export interface StepperProps extends Omit<React.OlHTMLAttributes<HTMLOListEleme
     current: number;
     /** Makes completed steps buttons that go back to them. */
     onStepChange?: (index: number) => void;
-    /** Default 'horizontal'. */
-    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Default 'horizontal'. 'auto' (#264): horizontal when every step fits on one line in its container, vertical when
+     * not, so a phone never shows connectors that lead to the next line.
+     */
+    orientation?: 'horizontal' | 'vertical' | 'auto';
 }
 /**
  * A process as a staircase of plates on one ground line, in the breadcrumb's vocabulary. Completed steps are settled into
@@ -20,4 +23,4 @@ export interface StepperProps extends Omit<React.OlHTMLAttributes<HTMLOListEleme
  * pressed into the page. Advancing presses the current step down into the record, stamps its check in, then raises the
  * next one out of its imprint.
  */
-export declare function Stepper({ steps, current, onStepChange, orientation, className, ...rest }: StepperProps): React.JSX.Element;
+export declare function Stepper({ steps, current, onStepChange, orientation: orientationProp, className, ...rest }: StepperProps): React.JSX.Element;

package/dist/types/suggestions.d.ts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+export interface SuggestionsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChoose'> {
+    /** Names the group: "Suggested follow-ups", "Start with". */
+    'aria-label': string;
+    /** 'fill' (default) puts the text in the composer to edit; 'send' sends it at once. */
+    mode?: 'fill' | 'send';
+    /** Called with the chosen suggestion's value (or its text). Fill or send it from here. */
+    onChoose: (value: string) => void;
+    /**
+     * Follow-ups that became available after an answer: they cross-fade in over dur-onset, never rising. Default true
+     * inside a Message, false elsewhere (starters in an empty conversation are simply there).
+     */
+    arrive?: boolean;
+    children: React.ReactNode;
+}
+export interface SuggestionItemProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'value'> {
+    /** What's filled or sent, when it's longer than the label. Default the label's text. */
+    value?: string;
+    children: React.ReactNode;
+}
+/**
+ * Prompts to start from or follow up with (#272): small secondary buttons, raised at level 1 like any affordance and
+ * never level 2, since the view's one primary is the composer's Send. Starters sit in an EmptyState; follow-ups sit
+ * under an answer and cross-fade in once it's complete. More than four become one toolbar tab stop with arrow keys.
+ * After choosing, focus goes to the composer (with the caret at the end, to edit what was filled).
+ */
+export declare function Suggestions({ mode, onChoose, arrive, className, children, ...rest }: SuggestionsProps): React.JSX.Element;
+/** One suggestion: named by its text, plus "sends now" when choosing it sends. */
+export declare function Suggestion({ value, className, children, onClick, ...rest }: SuggestionItemProps): React.JSX.Element;

package/dist/types/suspense.d.ts

@@ -0,0 +1,85 @@
+import * as React from 'react';
+/** A value, or a promise of one. A component that takes one shows its own imprint until it lands. */
+export type Promised<T> = T | PromiseLike<T>;
+/** Hints for a component's imprint, or `false` to let it suspend to your own boundary instead. */
+export type SkeletonOption = boolean | {
+    lines?: number;
+    width?: number | string;
+};
+export declare const isPromise: (v: unknown) => v is PromiseLike<unknown>;
+/** Content that may still be on its way: `undefined` while your data loads, or a promise. `null` means there is nothing. */
+export type Pending<T> = T | PromiseLike<T> | undefined;
+/** Children that hold a promise, at the top level or one level down (`Welcome back, {name}`). */
+export declare const hasPromise: (children: unknown) => boolean;
+/**
+ * Reads a promised value, suspending until it lands. React 19's `use()` when it's there; on React 18, the same contract
+ * by hand (the promise is thrown to the nearest Suspense boundary and its result remembered).
+ */
+export declare function readPromised<T>(v: Promised<T>): T;
+/** Reads promised children, at the top level or one level down. */
+export declare function readChildren(children: unknown): React.ReactNode;
+/**
+ * Turns "not here yet" into a suspension: while `waiting`, returns a promise that resolves once it stops, for the
+ * component's inner part to read (see Arrive), so its own boundary shows the imprint. Call it in the outer part, which
+ * stays mounted and re-renders when your data arrives.
+ */
+export declare function useArrival(waiting: boolean): PromiseLike<void> | null;
+/** Suspends while `when` is pending; renders its children once it isn't. */
+export declare function Arrive({ when, children }: {
+    when: PromiseLike<void> | null;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** True from the first render that waited onwards, so the boundary stays mounted and the content can rise out of it. */
+export declare function useHasWaited(waiting: boolean): boolean;
+export declare function LoadingScope({ children }: {
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** For required content (an avatar's name, a title, a badge's label, a table's rows): says whether it's still on its way. */
+export declare function useReportWaiting(waiting: boolean): void;
+/** For optional content: is the card it's in still waiting for its required parts? */
+export declare const useScopeWaiting: () => boolean;
+/**
+ * Imprints inside a RevealGroup land together: each one that finishes waits, still an imprint, until the slowest has
+ * landed, then they all rise at once (four at a time, as always). Group things that load from the same place.
+ */
+export declare function RevealGroup({ children }: {
+    children?: React.ReactNode;
+}): React.JSX.Element;
+export interface AwaitProps {
+    /** The imprint: the fallback while the children suspend. */
+    imprint: React.ReactNode;
+    /** The shape left behind as content rises out of it. `none` for containers: their content just rises. */
+    shape?: 'circle' | 'text' | 'block' | 'none';
+    /** Sits in a line of text or a row of controls (an avatar, a badge) rather than as a block. */
+    inline?: boolean;
+    /** `false`: no boundary; the children suspend to yours. */
+    enabled?: boolean;
+    /**
+     * Where the content rests once it lands, for `loading="breath"`. 'flush' (default): on the ground (text, a badge, a
+     * row); it fills past the ground and settles. 'raised': on its own surface at level 1 (a card); it rises a level past
+     * its rest and settles over dur-arrive.
+     */
+    settle?: 'flush' | 'raised';
+    /**
+     * Content arriving into a view that's already showing (Load more), for `loading="breath"`: flush content gets a
+     * plate that dissolves over dur-plate. A boundary that suspends again after it has landed is late without this.
+     */
+    late?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * A Suspense boundary whose fallback is an imprint, and whose content rises out of it. Every Suspense-native Altitude
+ * component holds one; use it in your own components to give them the same behaviour.
+ */
+export declare function Await({ imprint, shape, inline, enabled, settle, late, className, children }: AwaitProps): React.JSX.Element;
+/** Lines of text, as tall as the text they stand for (each line is one line-height of the surrounding type). */
+export declare function TextImprint({ lines, width, className }: {
+    lines?: number;
+    width?: number | string;
+    className?: string;
+}): React.JSX.Element;
+export declare const hint: (s: SkeletonOption | undefined) => {
+    lines?: number;
+    width?: number | string;
+};

package/dist/types/sync-indicator.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+export type SyncState = 'saved' | 'saving' | 'offline' | 'failed' | 'conflict';
+export interface SyncIndicatorProps {
+    state: SyncState;
+    /** Changes not yet on the server. */
+    pending?: number;
+    /** Conflicts waiting to be resolved, with state="conflict". */
+    conflicts?: number;
+    /** When the work last reached the server ("Saved 2 min ago"). */
+    lastSyncedAt?: Date | string | number;
+    onRetry?: () => void;
+    onOpenConflicts?: () => void;
+    /** The waiting changes, shown in a Popover when the plate is pressed. Without it the plate doesn't open anything. */
+    queue?: React.ReactNode;
+    /** Announces "Saved" at most this often, in milliseconds; going offline and failures are announced at once. Default 5000. */
+    announceEvery?: number;
+    className?: string;
+}
+/**
+ * Whether your work has reached the server, said in words on a flush Badge plate whose lamp relights when the state
+ * changes: labels never lift, and a state change cross-fades rather than rises. The items it covers hover as pending
+ * until they land, so the global and per-item signals agree. With a queue, the plate opens it (and lifts, because it acts).
+ */
+export declare function SyncIndicator({ state, pending, conflicts, lastSyncedAt, onRetry, onOpenConflicts, queue, announceEvery, className }: SyncIndicatorProps): React.JSX.Element;

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

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import { SelectOption } from './select.js';
+export type TagResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface TagInputProps {
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    /** Offered as you type, ranked as the Combobox ranks. Free entry is still allowed unless `restrict`. */
+    suggestions?: (string | SelectOption)[];
+    /** Only suggestions can be added. Default false. */
+    restrict?: boolean;
+    /** Keys that add what's typed: Enter and any single characters (also used to split a paste). Default [',', 'Enter']. */
+    separators?: string[];
+    /** The most tags allowed; then the field is read-only with “Limit reached”. */
+    max?: number;
+    /** Return an error to refuse a tag. Runs after `normalize`. */
+    validate?: (tag: string) => string | undefined;
+    /** Applied before validating and before comparing for duplicates. Default: trim. */
+    normalize?: (tag: string) => string;
+    /** Persist one added tag. Return its canonical text, or an error; the tag waits, pending, until then. */
+    onAdd?: (tag: string) => TagResult | Promise<TagResult>;
+    /** Persist one removal. The tag stays, pending, until the result. */
+    onRemove?: (tag: string) => TagResult | Promise<TagResult> | {
+        ok: true;
+    } | Promise<{
+        ok: true;
+    } | TagResult>;
+    /** Draw a tag's contents. Default: its text. */
+    renderTag?: (tag: string) => React.ReactNode;
+    /** Words for the count and the messages. Default ['tag', 'tags']. */
+    noun?: [singular: string, plural: string];
+    placeholder?: string;
+    id?: string;
+    name?: string;
+    disabled?: boolean;
+    required?: boolean;
+    /** Field sets it for you when it has an error. */
+    invalid?: boolean;
+    size?: 'sm' | 'md';
+    className?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+}
+/**
+ * A field that holds a set of short values. The field is an opening; each tag is a label stamped flush into its floor
+ * like a Badge plate, and once it holds a tag the floor rises flush (filled). The last tag, armed by a first Backspace,
+ * lifts one level on a critical tint before a second Backspace takes it off. Suggestions are the Combobox's list.
+ */
+export declare function TagInput({ value, defaultValue, onValueChange, suggestions, restrict, separators, max, validate, normalize, onAdd, onRemove, renderTag, noun, placeholder, id, name, disabled, required, invalid, size, className, ...aria }: TagInputProps): React.JSX.Element;
+export interface TagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'> {
+    children: React.ReactNode;
+    /** Adds a ghost remove button named “Remove <label>”. */
+    onRemove?: () => void;
+    /** Names the remove button when the children aren't plain text. */
+    label?: string;
+}
+/** A tag on its own: the TagInput's plate, stamped flush into the page, for showing a set outside a field. */
+export declare function Tag({ children, onRemove, label, className, ...rest }: TagProps): React.JSX.Element;

package/dist/types/terminal.d.ts

@@ -0,0 +1,33 @@
+import * as React from 'react';
+export type TerminalChunk = {
+    text: string;
+    stream?: 'stdout' | 'stderr';
+};
+export interface TerminalProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+    /** The command that ran: "npm test". It names the figure. */
+    command: string;
+    /** Everything it has printed so far: a string, or chunks marked stdout or stderr as they arrived. */
+    output: string | TerminalChunk[];
+    /** Default 'running'. */
+    status?: 'running' | 'exited' | 'stopped';
+    exitCode?: number;
+    /** Milliseconds it ran (said once it's finished). */
+    duration?: number;
+    /** Shows Stop while it runs. */
+    onStop?: () => void;
+    /** Escape inside the output stops a running command. Default false. */
+    stopOnEscape?: boolean;
+    /** Lines kept on screen; earlier ones are behind "Show 1,204 earlier lines". Default 400. */
+    maxLines?: number;
+    /** Map ANSI colours to Altitude's inks (red, yellow and green to the status inks, blue and cyan to accent-ink, dim to ink-muted). Default true; off, escapes are stripped. */
+    ansi?: boolean;
+    /** Shows Copy for the whole output. Default true. */
+    copyable?: boolean;
+}
+/**
+ * A command's output as it runs (#273), in CodeBlock's frame: flush on the ground with a 1px rim, mono. While it runs
+ * it isn't the record yet: a dashed rule down the left, "Running", and the output follows its end until you scroll up
+ * (then "Jump to latest output" rises). It finishes with one afterglow and its exit in words: "Exited with 0 · 4.2s",
+ * with a critical mark when non-zero (the edge stays neutral: #374), or "Stopped by you". stderr lines carry a critical mark and say "stderr".
+ */
+export declare function Terminal({ command, output, status, exitCode, duration, onStop, stopOnEscape, maxLines, ansi, copyable, className, ...rest }: TerminalProps): React.JSX.Element;

package/dist/types/thread-list.d.ts

@@ -0,0 +1,58 @@
+import * as React from 'react';
+export type ThreadStatus = 'idle' | 'working' | 'needs-input' | 'failed' | 'stopped';
+export interface ThreadListProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    /** A search field above the list; ⌘K / Ctrl+K focuses it. */
+    searchable?: boolean;
+    onSearch?: (query: string) => void;
+    /** Default "Search conversations". */
+    searchLabel?: string;
+    /** ThreadListGroups. */
+    children: React.ReactNode;
+}
+/**
+ * Conversations with an assistant (#269), in a Sidebar: rows are destinations (flush, the current one on the raised
+ * pill), and each says its state in words. A working thread isn't pending (nothing you sent is in flight), so it
+ * doesn't hover: a plate with a steady lamp says "Working". One that needs you says so on a caution plate, and is
+ * announced once; finishing isn't announced. Rename in place, delete with a receipt and Undo.
+ */
+export declare function ThreadList({ searchable, onSearch, searchLabel, className, children, ...rest }: ThreadListProps): React.JSX.Element;
+export interface ThreadListGroupProps {
+    label: string;
+    children: React.ReactNode;
+    className?: string;
+}
+/** A run of threads under a heading: "Today", "Yesterday", "Previous 7 days". */
+export declare function ThreadListGroup({ label, children, className }: ThreadListGroupProps): React.JSX.Element;
+export interface ThreadListItemProps {
+    href: string;
+    title: string;
+    updatedAt: Date | string | number;
+    /** Default 'idle'. */
+    status?: ThreadStatus;
+    /** For 'needs-input': what it needs. Default 'approval'. */
+    needs?: 'approval' | 'question';
+    /** Finished while you were away: a dot, the title in 600, and "Unread" in its name. */
+    unread?: boolean;
+    current?: boolean;
+    onSelect?: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+    /** Rename in place (F2, or the row menu). */
+    onRename?: (title: string) => void;
+    /** Delete (Delete key, or the row menu): the row becomes a receipt with Undo. Remove it from your data in onDeleted. */
+    onDelete?: () => void;
+    onUndoDelete?: () => void;
+    /** The receipt has closed: drop the thread now. */
+    onDeleted?: () => void;
+    onArchive?: () => void;
+    className?: string;
+}
+/** One conversation: a destination row with its state in words, a row menu, rename in place and delete with Undo. */
+export declare function ThreadListItem({ href, title, updatedAt, status, needs, unread, current, onSelect, onRename, onDelete, onUndoDelete, onDeleted, onArchive, className }: ThreadListItemProps): React.JSX.Element | null;
+/** "New conversation": secondary, so the composer's Send keeps the view's one primary. */
+export declare function ThreadListNew({ children, className, ...rest }: React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** Groups threads by when they were last updated: Today, Yesterday, Previous 7 days, Previous 30 days, then by month. */
+export declare function groupByDate<T>(threads: T[], getDate: (t: T) => Date | string | number, now?: Date | number, locale?: string): {
+    label: string;
+    threads: T[];
+}[];

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

@@ -0,0 +1,33 @@
+import * as React from 'react';
+export interface TimeInputProps {
+    /** A time of day, "HH:mm" on a 24-hour clock, or null. It's only set once every segment holds a value. */
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string | null) => void;
+    /** The arrow keys move the minutes by this much. Default 1. */
+    step?: number;
+    /** "auto" (default) follows the locale; "h12" shows AM/PM; "h23" a 24-hour clock. */
+    hourCycle?: 'auto' | 'h12' | 'h23';
+    /** Earliest and latest allowed times ("09:00", "17:30"). A time outside them is invalid. */
+    min?: string;
+    max?: string;
+    /** An IANA time zone ("Europe/Berlin"). Its short name is shown after the time and spoken with it. The value isn't converted. */
+    timeZone?: string;
+    locale?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    size?: 'sm' | 'md';
+    /** Submits the value with a form, in a hidden input. */
+    name?: string;
+    id?: string;
+    className?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+}
+/**
+ * A time of day, typed by segment like DatePicker's dates. It's an opening that fills only when every segment holds a
+ * value: a partial time ("09:__") is still a hole. Hours, minutes and AM/PM are spinbuttons in a labelled group.
+ */
+export declare function TimeInput({ value, defaultValue, onValueChange, step, hourCycle, min, max, timeZone, locale, invalid, disabled, required, size, name, id, className, 'aria-describedby': describedBy, ...aria }: TimeInputProps): React.JSX.Element;

package/dist/types/timeline.d.ts

@@ -0,0 +1,38 @@
+import * as React from 'react';
+export interface TimelineProps extends React.HTMLAttributes<HTMLElement> {
+    /** 'day' (default) puts a heading before each day's events ("Today", "Yesterday", "March 4"). */
+    groupBy?: 'day' | 'none';
+    /** The level of the day headings. Default 3. */
+    headingLevel?: 2 | 3 | 4;
+    locale?: string;
+    /** Names the history ("Activity"). */
+    'aria-label'?: string;
+    /** TimelineItem elements, newest first or oldest first, as you like; give each a key. */
+    children: React.ReactNode;
+}
+/**
+ * Events in order on one ground line: the 1px ink-muted rule Stepper and the chart baseline stand on, turned upright.
+ * Events are flush entries stamped onto it. A new event arrives lifted and settles; one you caused hovers until it
+ * lands, or drops to a trench with Retry.
+ */
+export declare function Timeline({ groupBy, headingLevel, locale, className, children, 'aria-label': label, ...rest }: TimelineProps): React.JSX.Element;
+export interface TimelineItemProps {
+    /** The event's own icon; it sits on the line as a flush plate. Default a dot. */
+    icon?: React.ReactNode;
+    /** When it happened. */
+    time: Date | string | number;
+    /** An event you caused: pending hovers ("Sending…") until it lands; failed drops to a trench with Retry. */
+    status?: 'pending' | 'committed' | 'failed';
+    onRetry?: () => void;
+    /** More about it (a DiffView, a payload), behind a Details disclosure. */
+    detail?: React.ReactNode;
+    /** The event links somewhere: it lifts when pointed at. */
+    href?: string;
+    locale?: string;
+    /** The sentence: who did what to what. */
+    children: React.ReactNode;
+    /** Set by Timeline: arrived since the last render. */
+    isNew?: boolean;
+}
+/** One event: a sentence with its time, flush on the line. */
+export declare function TimelineItem({ icon, time, status, onRetry, detail, href, locale, children, isNew }: TimelineItemProps): React.JSX.Element;

package/dist/types/toggle.d.ts

@@ -0,0 +1,46 @@
+import * as React from 'react';
+import { ButtonProps } from './controls.js';
+export interface ToggleProps extends Omit<ButtonProps, 'variant' | 'onChange'> {
+    pressed?: boolean;
+    defaultPressed?: boolean;
+    onPressedChange?: (pressed: boolean) => void;
+    /** ghost (default): flush at rest, as in a toolbar. secondary: a raised slab at rest. */
+    variant?: 'ghost' | 'secondary';
+}
+/**
+ * A button that stays on. On is a choice, so it's built like the Switch, not like a held press: the face is cut into a
+ * shallow well with accent-soft poured in and the label in accent-ink. Its name never changes; aria-pressed says it.
+ */
+export declare const Toggle: React.ForwardRefExoticComponent<ToggleProps & React.RefAttributes<HTMLButtonElement>>;
+/** Set by Toolbar: a ToggleGroup inside one leaves the arrow keys to it, so the whole bar is one tab stop. */
+export declare const InToolbar: React.Context<boolean>;
+interface ToggleGroupBase extends Omit<React.HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
+    /** For type="multiple": ghost (default) or secondary toggles. type="single" is always the segmented build. */
+    variant?: 'ghost' | 'secondary';
+    size?: ButtonProps['size'];
+    orientation?: 'horizontal' | 'vertical';
+    disabled?: boolean;
+}
+export interface ToggleGroupSingleProps extends ToggleGroupBase {
+    /** One choice: the options sit in a well and one raised pill glides between them, as segmented Tabs. A radio group. */
+    type: 'single';
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+}
+export interface ToggleGroupMultipleProps extends ToggleGroupBase {
+    /** Any number on: a row of Toggles, each with aria-pressed. */
+    type: 'multiple';
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+}
+export type ToggleGroupProps = ToggleGroupSingleProps | ToggleGroupMultipleProps;
+export declare function ToggleGroup(props: ToggleGroupProps): React.JSX.Element;
+export interface ToggleGroupItemProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'value'> {
+    value: string;
+    /** type="multiple" only: an icon-only square toggle. */
+    square?: boolean;
+}
+export declare const ToggleGroupItem: React.ForwardRefExoticComponent<ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/types/toolbar.d.ts

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import { ButtonProps } from './controls.js';
+import { ToggleProps } from './toggle.js';
+export interface ToolbarProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Names the toolbar ("Formatting"). Required: a toolbar is a landmark-like group. */
+    'aria-label': string;
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * When the tools don't fit: 'wrap' (default) onto another row; 'menu' moves the ones that don't fit, from the end,
+     * into a "More tools" menu, where toggles keep their state as checkable items.
+     */
+    overflow?: 'wrap' | 'menu';
+    /** A line rim around the bar. Default false. */
+    bordered?: boolean;
+}
+/**
+ * A row of tools with one tab stop. The bar lies on the ground; its tools are ghosts that lift when pointed at, and
+ * latched tools are Toggles. Arrow keys move between tools, Home and End jump, and returning lands where you left.
+ */
+export declare function Toolbar({ orientation, overflow, bordered, className, children, ...rest }: ToolbarProps): React.JSX.Element;
+/** Tools that belong together, parted from the next group by a ToolbarSeparator. */
+export declare function ToolbarGroup({ className, ...rest }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+/** A decorative 1px line between groups: the toolbar already says what's grouped. */
+export declare function ToolbarSeparator({ className }: {
+    className?: string;
+}): React.JSX.Element;
+export interface ToolbarButtonProps extends Omit<ButtonProps, 'variant'> {
+}
+/** A ghost tool. Icon-only tools need an aria-label (a development warning says so). */
+export declare const ToolbarButton: React.ForwardRefExoticComponent<ToolbarButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export interface ToolbarToggleProps extends Omit<ToggleProps, 'variant'> {
+}
+/** A latched tool: a ghost Toggle. */
+export declare const ToolbarToggle: React.ForwardRefExoticComponent<ToolbarToggleProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/types/tour.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+export interface TourStep {
+    /** What it points at: a CSS selector or an element. */
+    target: string | HTMLElement | null;
+    title: string;
+    body?: React.ReactNode;
+}
+export interface TourProps {
+    steps: TourStep[];
+    /** Whether it's showing. Start it by setting this (or defaultOpen); it ends with onFinish. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Called once, when the last step's Done is pressed ('done') or the tour is skipped or dismissed ('skipped'). */
+    onFinish?: (how: 'done' | 'skipped') => void;
+    onStepChange?: (index: number) => void;
+}
+/**
+ * A few steps pointing at parts of the interface, without taking it over. One step at a time floats at level 3 beside
+ * its target, which is marked with a 2px accent-ink ring (a ring, not a lift: it may not be something you press). It
+ * never dims the page (receding is the summit's privilege) and isn't modal: the target stays usable.
+ */
+export declare function Tour({ steps, open, defaultOpen, onOpenChange, onFinish, onStepChange }: TourProps): React.JSX.Element | null;

package/dist/types/trace.d.ts

@@ -0,0 +1,65 @@
+import * as React from 'react';
+export type TraceStepStatus = 'planned' | 'running' | 'done' | 'failed' | 'awaiting-approval';
+export interface TraceProps extends React.OlHTMLAttributes<HTMLOListElement> {
+    'aria-label': string;
+}
+/**
+ * The steps an agent takes, drawn as a vertical Stepper: done steps are flush in the record with a stamped check, the
+ * running step stands raised on its wall, planned steps are imprints. No spinners. A failed step drops to a trench with
+ * Retry; one waiting for approval holds a Confirmation. Steps that start without a plan arrive with the afterglow.
+ */
+export declare function Trace(props: TraceProps): React.JSX.Element;
+export interface TraceParallelProps {
+    /** What runs at once: "Subagents". */
+    label: string;
+    /** TraceSteps that run at the same time. */
+    children: React.ReactNode;
+    className?: string;
+}
+/**
+ * Steps that run at once (#278), in a labelled group with a 1px bracket: "Subagents · 3 in parallel · 2 of 3 done".
+ * Several steps can be raised at once here, each because it's in play; the words carry the count.
+ */
+export declare function TraceParallel({ label, children, className }: TraceParallelProps): React.JSX.Element;
+export declare const formatDuration: (ms: number) => string;
+export interface TraceStepProps {
+    title: string;
+    /** 'auto': derived from the steps inside it (a nested Trace or TraceParallel): done only when they all are. */
+    status: TraceStepStatus | 'auto';
+    /** Milliseconds it took (done or failed) or has taken so far. */
+    duration?: number;
+    /** Why it failed. */
+    error?: React.ReactNode;
+    onRetry?: () => void;
+    /** Tool calls, reasoning, a Confirmation. */
+    children?: React.ReactNode;
+    className?: string;
+}
+export declare function TraceStep({ title, status: given, duration, error, onRetry, children, className }: TraceStepProps): React.JSX.Element;
+export interface TraceToolCallProps {
+    /** The tool's name ("search_documents"). */
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    /** Open to begin with. Default false. */
+    defaultOpen?: boolean;
+}
+/** A tool call's input and output, behind an Accordion lid named by the tool. */
+export declare function TraceToolCall({ name, input, output, defaultOpen }: TraceToolCallProps): React.JSX.Element;
+export interface TraceReasoningProps {
+    /** How long it thought, in milliseconds: "Thought for 12s". Said once, when it's known; never a ticking counter. */
+    duration?: number;
+    /**
+     * 'streaming': the lid says "Thinking…" and, opened, the text follows its end as it arrives; 'complete' (default):
+     * "Thought for 12s"; 'redacted': "Reasoning hidden by the provider", with nothing to open.
+     */
+    status?: 'streaming' | 'complete' | 'redacted';
+    /** While streaming and open, keep the newest text in view (until the person scrolls up). Default true. */
+    followWhileOpen?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * The model's reasoning, closed by default. While it streams it isn't the record yet: "Thinking…" on the lid and a
+ * dashed rule down the open compartment, never a shimmer or pulsing dots. Done, it's "Thought for 12s".
+ */
+export declare function TraceReasoning({ duration, status, followWhileOpen, children }: TraceReasoningProps): React.JSX.Element;

package/dist/types/tree.d.ts

@@ -0,0 +1,71 @@
+import * as React from 'react';
+export type TreeResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export type TreeCreateResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** Where a node goes: under `parentId` (null for the top level), at `index` among the children once it has left its old place. */
+export interface TreeTarget {
+    parentId: string | null;
+    index: number;
+}
+export interface TreeMove {
+    id: string;
+    from: TreeTarget;
+    to: TreeTarget;
+}
+export interface TreeHandle {
+    /** Open a naming well for a new node under `parentId` (null: the top level) at `index` (default: the end). */
+    startCreate: (parentId: string | null, index?: number) => void;
+    /** Rename a node, as F2 does. */
+    startRename: (id: string) => void;
+}
+export interface TreeProps<T> {
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    items: T[];
+    getKey: (item: T) => string;
+    getLabel: (item: T) => string;
+    /** Children, or undefined when there are none or they aren't loaded yet. */
+    getChildren?: (item: T) => T[] | undefined;
+    /** Whether a node can have children (and so shows a chevron) before they're loaded. Default: it has children. */
+    hasChildren?: (item: T) => boolean;
+    /** Called the first time a node with no loaded children is expanded; an imprint shows until `items` includes them. */
+    loadChildren?: (item: T) => void | Promise<void>;
+    expanded?: string[];
+    defaultExpanded?: string[];
+    onExpandedChange?: (expanded: string[]) => void;
+    /** Default 'single'. */
+    selectionMode?: 'single' | 'none';
+    selected?: string | null;
+    defaultSelected?: string | null;
+    onSelectedChange?: (id: string | null) => void;
+    /** Enter's default action (open the page). */
+    onAction?: (item: T) => void;
+    /** Draw a node's label. Default: getLabel. */
+    renderItem?: (item: T) => React.ReactNode;
+    /** F2. Resolve after `items` carries the new name. */
+    onRename?: (item: T, draft: string) => TreeResult | Promise<TreeResult>;
+    /** Space to carry, or drag. Resolve after `items` reflects the move. */
+    onMove?: (move: TreeMove) => TreeResult | Promise<TreeResult>;
+    /** Refuse a target: a node can never go into its own subtree, whatever this says. */
+    canDrop?: (move: TreeMove) => boolean;
+    /** Ctrl/Cmd+Enter (sibling after) and Ctrl/Cmd+Shift+Enter (child). Resolve after `items` includes the new node. */
+    onCreate?: (request: TreeTarget & {
+        name: string;
+    }) => TreeCreateResult<T> | Promise<TreeCreateResult<T>>;
+    /** Delete. Your removal policy (recovery or confirmation) applies; the tree only asks. */
+    onRemove?: (item: T) => void;
+    className?: string;
+}
+export declare const Tree: <T>(props: TreeProps<T> & {
+    ref?: React.Ref<TreeHandle>;
+}) => React.ReactElement;