altitude-design 0.4.0 → 0.4.2

package/dist/types-cjs/property-list.d.cts

@@ -61,6 +61,23 @@ export interface PropertyListItemProps<V> {
  * One record's properties as label–value pairs. The properties are the record, on the ground; an unset value is a
  * small opening; an editable value is one plate that lifts when pointed at, because clicking it opens its editor
  * (InlineEdit, with any control). “Edit all” lifts the whole list into one EditRegion for cross-field rules.
+ * @example
+ * ```tsx
+ * import { Badge, Combobox, Input, PropertyList, PropertyListItem, Select } from 'altitude-design';
+ *
+ * <PropertyList aria-labelledby="pl-issue" shortcuts>
+ *   <PropertyListItem label="Status" value={issue.status} shortcut="s" commit="on-choose" onSave={save('status')} onValueChange={set('status')}
+ *     renderValue={s => <Badge tone={PL_TONE[s]}>{plLabel(PL_STATUS, s)}</Badge>} editor={c => <Select {...c} items={PL_STATUS} size="sm" />} />
+ *   <PropertyListItem label="Assignee" value={issue.assignee} shortcut="a" commit="on-choose" onSave={save('assignee')} onValueChange={set('assignee')}
+ *     renderValue={p => plLabel(PL_PEOPLE, p)} editor={c => <Combobox {...c} items={PL_PEOPLE} size="sm" />} />
+ *   <PropertyListItem label="Priority" value={issue.priority} emptyLabel="Add priority" commit="on-choose" onSave={save('priority')} onValueChange={set('priority')}
+ *     renderValue={p => plLabel(PL_PRIORITY, p)} editor={c => <Select {...c} items={PL_PRIORITY} size="sm" />} />
+ *   <PropertyListItem label="Estimate" value={issue.estimate} onSave={save('estimate')} onValueChange={set('estimate')} required
+ *     validate={n => Number.isInteger(n) && n >= 0 ? undefined : 'Use a whole number, 0 or more.'} renderValue={n => `${n} points`}
+ *     editor={({ value, onValueChange, ...c }) => <Input {...c} type="number" size="sm" value={value ?? ''} onChange={e => onValueChange(e.target.value === '' ? null : Number(e.target.value))} />} />
+ *   <PropertyListItem label="Created" value={issue.created} />
+ * </PropertyList>
+ * ```
  */
 export declare function PropertyList<T extends Record<string, unknown> = Record<string, unknown>>({ layout, shortcuts, editAll, proposedBy, className, children, ...aria }: PropertyListProps<T>): React.JSX.Element;
 /** One property. With onSave its value is an editable plate (InlineEdit); without, read-only text. */

package/dist/types-cjs/question.d.cts

@@ -44,6 +44,17 @@ export interface QuestionProps {
  * has been dispatched, so it's raised like a requested Confirmation, not pending. Options are a radio group (or
  * checkboxes), "Your own answer" is a field, and Answer is the one primary; there's no default and nothing is focused
  * for you. Answered, it presses to the ground as one line: "You chose: Staging · now".
+ * @example
+ * ```tsx
+ * import { Question, QuestionOption } from 'altitude-design';
+ *
+ * <Question title="Which environment should I deploy to?" state={q.state} answer={q.answer} answeredAt={q.at} allowOther
+ *   answerLabel="Deploy" skipLabel="Let the assistant decide" onSkip={() => setQ({ state: 'expired' })}
+ *   onAnswer={(answer) => setQ({ state: 'answered', answer, at: Date.now() })}>
+ *   <QuestionOption value="staging" label="Staging" description="Resets nightly. Safe to try things." />
+ *   <QuestionOption value="production" label="Production" description="Customers will see it immediately." />
+ * </Question>
+ * ```
  */
 export declare function Question({ title, state: own, multiple, allowOther, otherLabel, answerLabel, skipLabel, onSkip, onAnswer, answer, answeredAt, requestedBy, name, children, className }: QuestionProps): React.JSX.Element;
 export interface QuestionSetProps {

package/dist/types-cjs/relative-time.d.cts

@@ -17,5 +17,12 @@ export interface RelativeTimeProps extends RelativeTimeOptions, Omit<React.TimeH
     /** Show the exact date, time and zone in a Tooltip on hover and focus (the element becomes focusable). Default true. */
     tooltip?: boolean;
 }
-/** A moment as "3 minutes ago" in a <time>, refreshed on one shared timer, with its exact time on hand. Ticking isn't a change. */
+/** A moment as "3 minutes ago" in a <time>, refreshed on one shared timer, with its exact time on hand. Ticking isn't a change.
+ * @example
+ * ```tsx
+ * import { RelativeTime } from 'altitude-design';
+ *
+ * <RelativeTime date={when} format="auto" />
+ * ```
+ */
 export declare function RelativeTime({ date, format, threshold, tense, locale, tooltip, className, title, style, ...rest }: RelativeTimeProps): React.JSX.Element;

package/dist/types-cjs/removal-receipt.d.cts

@@ -28,7 +28,24 @@ export interface RemovalReceiptProps extends Omit<React.HTMLAttributes<HTMLEleme
     /** When mounted, the slot glides open from nothing (an item brought back from elsewhere), then settles. */
     arrive?: boolean;
 }
-/** An item's slot that keeps its place when the item leaves: the result shows where the item was, then the gap closes. */
+/** An item's slot that keeps its place when the item leaves: the result shows where the item was, then the gap closes.
+ * @example
+ * ```tsx
+ * import { Button, RemovalReceipt, toast } from 'altitude-design';
+ *
+ * <RemovalReceipt as="li" key={hook.id} removed={!!receipt} pending={receipt?.pending} arrive={back === hook.id}
+ *   title={receipt?.undoing ? `Restoring ${hook.name}…` : receipt?.pending ? `Removing ${hook.name}…` : `${hook.name} removed.`}
+ *   action={receipt && (!receipt.pending || receipt.undoing) &&
+ *     <Button size="sm" loading={!!receipt.undoing} aria-label={`Undo removing ${hook.name}`} onClick={() => undo(hook)}>Undo</Button>}
+ *   onClosed={() => {
+ *     put(hook.id, null); setHooks((list) => list.filter((h) => h.id !== hook.id));
+ *     toast({ title: `${hook.name} removed.`, action: { label: 'Undo', onClick: () => restore(hook) } });
+ *   }}>
+ *   <div className="rr-body"><div className="rr-name">{hook.name}</div><div className="rr-url">{hook.url}</div></div>
+ *   <Button size="sm" variant="ghost" aria-label={`Remove ${hook.name}`} onClick={() => remove(hook)}>Remove</Button>
+ * </RemovalReceipt>
+ * ```
+ */
 export declare function RemovalReceipt({ as, removed, pending, title, action, tone, icon, hold, onClosed, focusFallback, arrive, settle, className, style, children, ...rest }: RemovalReceiptProps): React.DetailedReactHTMLElement<{
     style: {
         accentColor?: import("csstype").Property.AccentColor | undefined;

package/dist/types-cjs/save-bar.d.cts

@@ -33,6 +33,12 @@ export interface SaveBarProps {
  * Unsaved changes on a page, held above it until saved or discarded. A draft is something in your hand, so the bar
  * floats at level 3, docked to the bottom edge (below Sheets and Dialogs). Saving hovers as a pending write; a saved
  * draft lowers away while the fields settle; a failed save drops the bar to a trench and keeps the draft.
+ * @example
+ * ```tsx
+ * import { SaveBar } from 'altitude-design';
+ *
+ * <SaveBar record={record} />
+ * ```
  */
 export declare function SaveBar({ record, dirty: dirtyProp, saving: savingProp, error: errorProp, invalidCount: invalidProp, changedCount, onSave, onDiscard, delay, saveLabel, discardLabel, className }: SaveBarProps): React.JSX.Element;
 export {};

package/dist/types-cjs/saved-views.d.cts

@@ -68,5 +68,17 @@ export interface SavedViewsProps {
 /**
  * Saved views as folder Tabs: the active tab and the table beneath it are one raised sheet. A view you've changed is a
  * draft: its tab carries a dot and "modified", and Save view, Save as new view and Reset appear beside the tabs.
+ * @example
+ * ```tsx
+ * import { DataTable, FilterBar, FormattedNumber, SavedViews } from 'altitude-design';
+ *
+ * <SavedViews views={views} aria-label="Deal views">
+ *   <FilterBar fields={fields} {...views.filterBarProps} aria-label="Filter deals" />
+ *   <DataTable aria-label="Deals" rows={deals} getRowId={(r) => r.id} {...views.tableProps} columnsMenu density="compact"
+ *     relevance={(r) => (value.some((f) => f.value !== undefined) ? (matches(r, value, match) ? 'match' : 'miss') : undefined)}
+ *     columns={[{ key: 'name', header: 'Deal', sortValue: (r) => r.name }, { key: 'stage', header: 'Stage', sortValue: (r) => r.stage }, { key: 'owner', header: 'Owner', sortValue: (r) => r.owner },
+ *       { key: 'value', header: 'Value', align: 'end', sortValue: (r) => r.value, cell: (r) => <FormattedNumber value={r.value} format="currency" currency="USD" minorUnits={false} maximumFractionDigits={0} /> }]} />
+ * </SavedViews>
+ * ```
  */
 export declare function SavedViews({ views: v, children, 'aria-label': label, className }: SavedViewsProps): React.JSX.Element;

package/dist/types-cjs/scatter-chart.d.cts

@@ -47,6 +47,14 @@ export interface ScatterChartProps {
  * customer. Dots are the record, so they lie on the plot: at least 8px, a data-* fill and a marker shape per group, a
  * 2px ring of the plot's own colour so overlapping dots stay apart. Never raised, never shaded. A few can be labelled
  * in ink with a 1px leader, and a least-squares trend drawn as a 1px ink-muted line.
+ * @example
+ * ```tsx
+ * import { ChartLegend, ChartLegendContent, ScatterChart } from 'altitude-design';
+ *
+ * <ScatterChart data={endpoints} x="kb" y="ms" group="service" id="name" name="name" label={(d) => (d.ms > 250 && d.kb < 300 ? d.name : null)} trend>
+ *   <ChartLegend content={<ChartLegendContent toggle label="Services" />} />
+ * </ScatterChart>
+ * ```
  */
 export declare function ScatterChart(props: ScatterChartProps): React.JSX.Element;
 export declare namespace ScatterChart {

package/dist/types-cjs/schedule.d.cts

@@ -76,5 +76,26 @@ export interface ScheduleProps<T> {
  * A day or week of time whose events you handle directly. The grid is ground; events are live work items raised one
  * level, like BoardCards. Time opens into wells only while something could land in it (carrying or drawing), and the
  * slot under a carried event deepens to a trench the length of the event. A carried event floats at level 3, tilted.
+ * @example
+ * ```tsx
+ * import { Schedule } from 'altitude-design';
+ *
+ * <Schedule aria-label="Room bookings" view="workweek" date={date} onDateChange={setDate} now="2026-10-27T10:20"
+ *   events={events} getKey={e => e.id} getStart={e => e.start} getEnd={e => e.end} getLabel={e => e.title}
+ *   dayStart="08:00" dayEnd="18:00"
+ *   renderEvent={e => <><strong>{e.title}</strong><small className="sch-room">{e.start.slice(11)}–{e.end.slice(11)} · {e.room}</small></>}
+ *   heldBy={e => e.id === 'e6' ? { name: 'Ana', presence: 2 } : null}
+ *   // Rooms close at 17:00 on Fridays.
+ *   isUnavailable={({ start, end }) => start.slice(0, 10) === '2026-10-30' && end.slice(11) > '17:00'}
+ *   onChange={async ({ id, start, end }) => {
+ *     await schWait(300);
+ *     // The demo service refuses Wednesday mornings: the rooms are being cleaned.
+ *     if (start.slice(0, 10) === '2026-10-28' && start.slice(11) < '12:00') return { ok: false, error: 'Both rooms are being cleaned on Wednesday morning.' };
+ *     setEvents(list => list.map(e => e.id === id ? { ...e, start, end } : e)); return { ok: true };
+ *   }}
+ *   onCreate={async ({ start, end, title }) => { await schWait(300); const event = { id: 'n' + ++seq.current, title, start, end, room: 'Room A' }; setEvents(list => [...list, event]); return { ok: true, value: event }; }}
+ *   onRename={async (e, title) => { await schWait(200); setEvents(list => list.map(x => x.id === e.id ? { ...x, title } : x)); return { ok: true }; }}
+ *   onRemove={e => setEvents(list => list.filter(x => x.id !== e.id))} />
+ * ```
  */
 export declare function Schedule<T>({ view: viewProp, narrowView, date, onDateChange, events, getKey, getStart, getEnd, getLabel, step, dayStart, dayEnd, hourHeight: hourHeightProp, weekStartsOn, defaultDuration, renderEvent, onCreate, onChange, onRename, onOpen, onRemove, heldBy, isUnavailable, now, locale, className, ...aria }: ScheduleProps<T>): React.JSX.Element;

package/dist/types-cjs/secret-field.d.cts

@@ -29,5 +29,11 @@ export interface SecretFieldProps {
  * A key or token: shown once when created, masked afterwards. A new secret is an opening, something to take away: a
  * sunk well with copy beside it and a warning, until you say you've saved it; then it fills flush and masks. A stored
  * secret is settled: flush, masked to its tail, with reveal (if allowed), rotate and a held revoke.
+ * @example
+ * ```tsx
+ * import { SecretField } from 'altitude-design';
+ *
+ * <SecretField label="Secret key" value="ak_live_EXAMPLE0000demo4f2a" once onAcknowledge={() => setSaved(true)} />
+ * ```
  */
 export declare function SecretField({ label, noun, value, once, onAcknowledge, acknowledgeLabel, warning, prefix, maskedTail, onReveal, onRotate, onRevoke, className }: SecretFieldProps): React.JSX.Element;

package/dist/types-cjs/select.d.cts

@@ -84,6 +84,12 @@ export interface SelectProps extends FieldLike {
  * Choosing a value is filling a field, so the trigger is an opening built like Input: its back wall shows while it's
  * empty, its floor rises flush once a value is chosen, and it drops to trench depth when invalid. The list rises from
  * the field's edge at level 3 with one gliding highlight; the chosen option wears the Checkbox family's tick.
+ * @example
+ * ```tsx
+ * import { Select } from 'altitude-design';
+ *
+ * <Select items={regions} placeholder="Choose a region" name="region" />
+ * ```
  */
 export declare function Select({ value, defaultValue, onValueChange, items, children, id, name, required, disabled, invalid, size, placeholder, requiredMessage, defaultOpen, className, presentation, ...aria }: SelectProps): React.JSX.Element;
 export interface ComboboxProps extends FieldLike {
@@ -104,6 +110,12 @@ export interface ComboboxProps extends FieldLike {
 /**
  * An editable Select: type to filter, choose to fill. What you type is a query, not yet a value, so the field stays an
  * opening (its back wall showing) until an option is chosen; then its floor rises flush.
+ * @example
+ * ```tsx
+ * import { Combobox } from 'altitude-design';
+ *
+ * <Combobox items={people} value={who} onValueChange={setWho} placeholder="Search people" />
+ * ```
  */
 export declare function Combobox({ items, value, defaultValue, onValueChange, filter, empty, id, name, required, disabled, invalid, size, placeholder, defaultOpen, className, presentation, ...aria }: ComboboxProps): React.JSX.Element;
 export {};

package/dist/types-cjs/separator.d.cts

@@ -7,5 +7,12 @@ export interface SeparatorProps extends Omit<React.HTMLAttributes<HTMLDivElement
     /** A word between two lines ("or"). It's read in the flow, so it's never decorative. */
     label?: React.ReactNode;
 }
-/** A divider on the ground: 1px of `line`, never `line-control` and never a shadow. role="separator" unless decorative. */
+/** A divider on the ground: 1px of `line`, never `line-control` and never a shadow. role="separator" unless decorative.
+ * @example
+ * ```tsx
+ * import { Separator } from 'altitude-design';
+ *
+ * <Separator />
+ * ```
+ */
 export declare const Separator: React.ForwardRefExoticComponent<SeparatorProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types-cjs/sheet.d.cts

@@ -17,6 +17,25 @@ export interface SheetProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
 /**
  * A large sheet laid over the page at level 4, anchored to an edge. It rises at that edge (16px of travel at most,
  * a fade, its shadow growing from elev-1 to elev-4) while the page recedes behind it; closing lifts it off.
+ * @example
+ * ```tsx
+ * import { Button, Input, Sheet, SheetDescription, SheetFooter, SheetHeader, SheetTitle } from 'altitude-design';
+ *
+ * <Sheet side="bottom" size="sm" trigger={<Button>Share</Button>}>
+ *   <SheetHeader>
+ *     <SheetTitle>Share Northwind</SheetTitle>
+ *     <SheetDescription>
+ *       Anyone with the link can view the latest deployment.
+ *     </SheetDescription>
+ *   </SheetHeader>
+ *   <Input
+ *     defaultValue="https://acme.dev/n/8dc01b2"
+ *     readOnly={true}
+ *     aria-label="Share link"
+ *   />
+ *   <SheetFooter><Button variant="primary">Copy link</Button></SheetFooter>
+ * </Sheet>
+ * ```
  */
 export declare function Sheet({ open, defaultOpen, onOpenChange, trigger, side, size, modal, dismissible, className, style, children, ...rest }: SheetProps): React.JSX.Element;
 /** The title block. It stays at the top while the sheet scrolls, and rises once content passes under it. */

package/dist/types-cjs/sparkline.d.cts

@@ -41,6 +41,12 @@ export declare function describeTrend(vals: Array<number | null>, opts: {
  * record in the row it sits in, so it lies flush on the ground like everything a chart draws: a 1.5px stroke (or flat
  * bars), no axes, no gridlines, no readout, no fill under the line. Its height is the line height of the text beside
  * it. The last point wears a 4px marker. Colour is context (ink-muted) unless you say it's the series or a status.
+ * @example
+ * ```tsx
+ * import { Sparkline } from 'altitude-design';
+ *
+ * <Sparkline data={signups} x="day" y="signups" tone="data" width={120} aria-label="Signups, last 30 days" />
+ * ```
  */
 export declare function Sparkline({ data, ...props }: SparklineProps): React.JSX.Element;
 export {};

package/dist/types-cjs/split-button.d.cts

@@ -17,5 +17,12 @@ export interface SplitButtonProps extends Omit<ButtonProps, 'variant' | 'childre
  * One action with its alternatives: two faces on one slab, sharing one wall and parted by a line notch. The slab lifts
  * and presses as one whichever face is pointed at; the face under the pointer is tinted, so you can tell which action a
  * click takes without the faces splitting into two heights. Alt+Down on the action opens the menu.
+ * @example
+ * ```tsx
+ * import { SplitButton } from 'altitude-design';
+ *
+ * <SplitButton label="Save changes" menuLabel="More save options" onClick={() => setSaid('Saved.')}
+ *   items={[{ label: 'Save as draft', onSelect: () => setSaid('Saved as a draft.') }, { label: 'Save and close', onSelect: () => setSaid('Saved and closed.') }]} />
+ * ```
  */
 export declare const SplitButton: React.ForwardRefExoticComponent<SplitButtonProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/types-cjs/stat.d.cts

@@ -41,6 +41,13 @@ export interface StatProps extends Omit<React.HTMLAttributes<HTMLElement>, 'chil
  * it sits on (a Card, or the page): no level of its own. A changed value cross-fades and the stat gets the afterglow,
  * within the attention budget; it never counts up. The change says its direction in words and with an arrow, and only
  * takes a status colour when you say which direction is good.
+ * @example
+ * ```tsx
+ * import { Stat } from 'altitude-design';
+ *
+ * <Stat label="Monthly recurring revenue" size="hero" value={mrr} format={usd.format} good="up"
+ *   change={{ value: 0.042, vs: 'September', previous: 176800 }} help="Paid plans only, before refunds." />
+ * ```
  */
 export declare function Stat({ value, ...props }: StatProps): React.JSX.Element;
 export interface StatGroupProps extends React.HTMLAttributes<HTMLDivElement> {

package/dist/types-cjs/stepper.d.cts

@@ -22,5 +22,17 @@ export interface StepperProps extends Omit<React.OlHTMLAttributes<HTMLOListEleme
  * the record: flush plates with a stamped check. The current step is a raised slab with a wall. Steps to come are imprints
  * 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.
+ * @example
+ * ```tsx
+ * import { Stepper } from 'altitude-design';
+ *
+ * <Stepper
+ *   steps={steps}
+ *   current={at}
+ *   onStepChange={setAt}
+ *   orientation="auto"
+ *   aria-label="Workspace setup"
+ * />
+ * ```
  */
 export declare function Stepper({ steps, current, onStepChange, orientation: orientationProp, className, ...rest }: StepperProps): React.JSX.Element;

package/dist/types-cjs/suggestions.d.cts

@@ -23,6 +23,16 @@ export interface SuggestionItemProps extends Omit<React.ButtonHTMLAttributes<HTM
  * 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).
+ * @example
+ * ```tsx
+ * import { Suggestion, Suggestions } from 'altitude-design';
+ *
+ * <Suggestions aria-label="Start with" onChoose={setDraft}>
+ *   <Suggestion>Summarise last week's incidents</Suggestion>
+ *   <Suggestion>Draft a release note</Suggestion>
+ *   <Suggestion value="Which of my open pull requests are blocked, and by whom?">What's blocked?</Suggestion>
+ * </Suggestions>
+ * ```
  */
 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. */

package/dist/types-cjs/sync-indicator.d.cts

@@ -20,5 +20,13 @@ export interface SyncIndicatorProps {
  * 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).
+ * @example
+ * ```tsx
+ * import { Surface, SyncIndicator } from 'altitude-design';
+ *
+ * <SyncIndicator state={state} pending={waiting.length} lastSyncedAt={at} conflicts={1} onRetry={() => { setState('saving'); setTimeout(() => { setState('saved'); setAt(new Date()); }, 700); }}
+ *   onOpenConflicts={() => setState('saved')}
+ *   queue={waiting.length ? waiting.map((w, i) => <Surface key={i} status="pending" className="change">{w}</Surface>) : undefined} />
+ * ```
  */
 export declare function SyncIndicator({ state, pending, conflicts, lastSyncedAt, onRetry, onOpenConflicts, queue, announceEvery, className }: SyncIndicatorProps): React.JSX.Element;

package/dist/types-cjs/tag-input.d.cts

@@ -52,6 +52,14 @@ export interface TagInputProps {
  * 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.
+ * @example
+ * ```tsx
+ * import { TagInput } from 'altitude-design';
+ *
+ * <TagInput value={labels} onValueChange={setLabels} suggestions={TAG_LABELS} max={6} noun={['label', 'labels']}
+ *   placeholder="Add a label" normalize={tag => tag.trim().toLowerCase()} validate={tag => tag.length <= 24 ? undefined : 'Use 24 characters or fewer.'}
+ *   renderTag={tag => <>{TAG_DOTS[tag] && <span className="tags-dot" style={{ '--dot': TAG_DOTS[tag] }} aria-hidden="true" />}{tag}</>} />
+ * ```
  */
 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'> {

package/dist/types-cjs/terminal.d.cts

@@ -29,5 +29,11 @@ export interface TerminalProps extends Omit<React.HTMLAttributes<HTMLElement>, '
  * 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".
+ * @example
+ * ```tsx
+ * import { Terminal } from 'altitude-design';
+ *
+ * <Terminal command="npm test" output={testRun} status="exited" exitCode={1} duration={4200} />
+ * ```
  */
 export declare function Terminal({ command, output, status, exitCode, duration, onStop, stopOnEscape, maxLines, ansi, copyable, className, ...rest }: TerminalProps): React.JSX.Element;

package/dist/types-cjs/thread-list.d.cts

@@ -14,6 +14,22 @@ export interface ThreadListProps extends Omit<React.HTMLAttributes<HTMLDivElemen
  * 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.
+ * @example
+ * ```tsx
+ * import { ThreadList, ThreadListGroup, ThreadListItem, groupByDate } from 'altitude-design';
+ *
+ * <ThreadList searchable onSearch={setQ}>
+ *   {groupByDate(shown, (t) => t.at, now).map((g) => (
+ *     <ThreadListGroup key={g.label} label={g.label}>
+ *       {g.threads.map((t) => (
+ *         <ThreadListItem key={t.id} href={'#/c/' + t.id} title={t.title} updatedAt={t.at} status={t.status} needs={t.needs} unread={t.unread} current={t.id === at}
+ *           onSelect={(e) => { e.preventDefault(); setAt(t.id); set(t.id, { unread: false }); }}
+ *           onRename={(title) => set(t.id, { title })} onDelete={() => {}} onUndoDelete={() => {}} onDeleted={() => setThreads((ts) => ts.filter((x) => x.id !== t.id))} />
+ *       ))}
+ *     </ThreadListGroup>
+ *   ))}
+ * </ThreadList>
+ * ```
  */
 export declare function ThreadList({ searchable, onSearch, searchLabel, className, children, ...rest }: ThreadListProps): React.JSX.Element;
 export interface ThreadListGroupProps {

package/dist/types-cjs/time-input.d.cts

@@ -29,5 +29,11 @@ export interface TimeInputProps {
 /**
  * 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.
+ * @example
+ * ```tsx
+ * import { TimeInput } from 'altitude-design';
+ *
+ * <TimeInput value={report} onValueChange={setReport} step={15} hourCycle="h12" locale="en-US" timeZone="Europe/Berlin" />
+ * ```
  */
 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-cjs/timeline.d.cts

@@ -14,6 +14,15 @@ export interface TimelineProps extends React.HTMLAttributes<HTMLElement> {
  * 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.
+ * @example
+ * ```tsx
+ * import { Timeline, TimelineItem } from 'altitude-design';
+ *
+ * <Timeline aria-label="Activity">
+ *   {events.map((e) => <TimelineItem key={e.id} time={e.at} icon={<I d={icons[e.icon]} />} status={e.status} href={e.href} detail={e.detail}
+ *     onRetry={() => setEvents((xs) => xs.map((x) => (x.id === e.id ? { ...x, status: 'committed' } : x)))}>{e.text}</TimelineItem>)}
+ * </Timeline>
+ * ```
  */
 export declare function Timeline({ groupBy, headingLevel, locale, className, children, 'aria-label': label, ...rest }: TimelineProps): React.JSX.Element;
 export interface TimelineItemProps {

package/dist/types-cjs/toggle.d.cts

@@ -10,6 +10,12 @@ export interface ToggleProps extends Omit<ButtonProps, 'variant' | 'onChange'> {
 /**
  * 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.
+ * @example
+ * ```tsx
+ * import { Toggle } from 'altitude-design';
+ *
+ * <Toggle variant="secondary" pressed={archived} onPressedChange={setArchived}>Show archived</Toggle>
+ * ```
  */
 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. */

package/dist/types-cjs/toolbar.d.cts

@@ -16,6 +16,26 @@ export interface ToolbarProps extends React.HTMLAttributes<HTMLDivElement> {
 /**
  * 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.
+ * @example
+ * ```tsx
+ * import { ToggleGroup, ToggleGroupItem, Toolbar, ToolbarButton, ToolbarGroup, ToolbarSeparator, ToolbarToggle } from 'altitude-design';
+ *
+ * <Toolbar aria-label="Formatting" overflow="menu" bordered className={className}>
+ *   <ToggleGroup type="multiple" value={marks} onValueChange={setMarks} aria-label="Text style">
+ *     <ToggleGroupItem value="bold" aria-label="Bold" square><b>B</b></ToggleGroupItem>
+ *     <ToggleGroupItem value="italic" aria-label="Italic" square><i>I</i></ToggleGroupItem>
+ *     <ToggleGroupItem value="underline" aria-label="Underline" square><u>U</u></ToggleGroupItem>
+ *   </ToggleGroup>
+ *   <ToolbarSeparator />
+ *   <ToolbarGroup aria-label="Blocks">
+ *     <ToolbarButton aria-label="Bulleted list" square><I d={list} /></ToolbarButton>
+ *     <ToolbarToggle aria-label="Quote" square pressed={quoted} onPressedChange={setQuoted}><I d={quote} /></ToolbarToggle>
+ *     <ToolbarButton aria-label="Code" square><I d={code} /></ToolbarButton>
+ *   </ToolbarGroup>
+ *   <ToolbarSeparator />
+ *   <ToolbarButton aria-label="Insert link" square><I d={link} /></ToolbarButton>
+ * </Toolbar>
+ * ```
  */
 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. */

package/dist/types-cjs/tour.d.cts

@@ -19,5 +19,15 @@ export interface TourProps {
  * 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.
+ * @example
+ * ```tsx
+ * import { Tour } from 'altitude-design';
+ *
+ * <Tour open={open} onOpenChange={setOpen} onFinish={(how) => setSaid(how === 'done' ? 'Tour finished.' : 'Tour skipped.')} steps={[
+ *   { target: '#tour-projects', title: 'Projects moved here', body: 'All your projects now live in one place.' },
+ *   { target: '[data-tour="owner"]', title: 'Filter by owner', body: 'Type a name to see only their projects.' },
+ *   { target: '[data-tour="new"]', title: 'Start something new', body: 'Projects can start from a template.' },
+ * ]} />
+ * ```
  */
 export declare function Tour({ steps, open, defaultOpen, onOpenChange, onFinish, onStepChange }: TourProps): React.JSX.Element | null;

package/dist/types-cjs/trace.d.cts

@@ -7,6 +7,22 @@ export interface TraceProps extends React.OlHTMLAttributes<HTMLOListElement> {
  * 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.
+ * @example
+ * ```tsx
+ * import { Confirmation, Trace, TraceReasoning, TraceStep, TraceToolCall } from 'altitude-design';
+ *
+ * <Trace aria-label="Agent run: answer refund question">
+ *   {plan.map((s, i) => (
+ *     <TraceStep key={s.id} title={s.title} status={status(i)} duration={i < at ? s.ms : undefined}
+ *       error={failed && i === at ? 'The billing service timed out.' : undefined} onRetry={failed && i === at ? () => { setRetried(true); setFailed(false); } : undefined}>
+ *       {s.tool && <TraceToolCall name={s.tool.name} input={s.tool.input} output={i < at ? s.tool.output ?? { plan: 'annual', startedDaysAgo: 20 } : undefined} />}
+ *       {s.reasoning && i < at && <TraceReasoning duration={s.ms}>{s.reasoning}</TraceReasoning>}
+ *       {s.approval && <Confirmation state={approval} title="Send reply to Jamie Lee" consequence="Jamie will get an email confirming a full refund of €240." approveLabel="Send reply" rejectLabel="Don't send" runningLabel="Sending…" doneLabel="Sent"
+ *         onApprove={() => { setApproval('running'); setTimeout(() => setApproval('done'), 1000); }} onReject={() => setApproval('rejected')} />}
+ *     </TraceStep>
+ *   ))}
+ * </Trace>
+ * ```
  */
 export declare function Trace(props: TraceProps): React.JSX.Element;
 export interface TraceParallelProps {

package/dist/types-cjs/tree.d.cts

@@ -66,6 +66,27 @@ export interface TreeProps<T> {
     onRemove?: (item: T) => void;
     className?: string;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Tree } from 'altitude-design';
+ *
+ * <Tree ref={tree} aria-label="Pages" items={pages} getKey={p => p.id} getLabel={p => p.title} getChildren={p => p.children} hasChildren={p => !!p.children}
+ *   expanded={expanded} onExpandedChange={setExpanded} selected={selected} onSelectedChange={setSelected}
+ *   renderItem={p => <><span className="tree-demo-icon" aria-hidden="true">{p.children ? <FolderIcon /> : <PageIcon />}</span>{p.title}</>}
+ *   onRename={async (page, title) => { await treeWait(250); if (title.length > 40) return { ok: false, error: 'Use 40 characters or fewer.' }; setPages(list => treeRename(list, page.id, title.trim())); return { ok: true }; }}
+ *   canDrop={({ to }) => to.parentId === null || !!treeFind(pages, to.parentId).page.children}
+ *   onMove={async ({ id, to }) => {
+ *     await treeWait(250);
+ *     // The demo service refuses to move anything out of Archive.
+ *     if (treeFind(pages, id).parent === 'archive' && to.parentId !== 'archive') return { ok: false, error: 'Archived pages can’t be moved out of Archive.' };
+ *     setPages(list => { const page = treeFind(list, id).page; return treeInsert(treeRemove(list, id), to.parentId, to.index, page); });
+ *     return { ok: true };
+ *   }}
+ *   onCreate={async ({ parentId, index, name }) => { await treeWait(250); const page = { id: 'new-' + ++seq.current, title: name }; setPages(list => treeInsert(list, parentId, index, page)); return { ok: true, value: page }; }}
+ *   onRemove={page => setPages(list => treeRemove(list, page.id))} />
+ * ```
+ */
 export declare const Tree: <T>(props: TreeProps<T> & {
     ref?: React.Ref<TreeHandle>;
 }) => React.ReactElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altitude-design",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "A design and HCI framework for agent-built React web applications, where height is the interface.",
   "keywords": [
     "react",