altitude-design 0.3.2 → 0.4.1

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

@@ -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/removal-receipt.d.ts

@@ -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/save-bar.d.ts

@@ -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/saved-views.d.ts

@@ -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/scatter-chart.d.ts

@@ -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/schedule.d.ts

@@ -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/secret-field.d.ts

@@ -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/select.d.ts

@@ -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/separator.d.ts

@@ -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/sheet.d.ts

@@ -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/sparkline.d.ts

@@ -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/split-button.d.ts

@@ -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/stat.d.ts

@@ -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/stepper.d.ts

@@ -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/suggestions.d.ts

@@ -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/sync-indicator.d.ts

@@ -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/tag-input.d.ts

@@ -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/terminal.d.ts

@@ -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/thread-list.d.ts

@@ -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/time-input.d.ts

@@ -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/timeline.d.ts

@@ -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/toggle.d.ts

@@ -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/toolbar.d.ts

@@ -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/tour.d.ts

@@ -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/trace.d.ts

@@ -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/tree.d.ts

@@ -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/dist/types-cjs/agent-fleet.d.cts

@@ -26,6 +26,16 @@ export interface AgentFleetProps extends React.HTMLAttributes<HTMLDivElement> {
  * longest wait at the top, then the ones working, then the finished ones folded away. Rows are the record, flush, each
  * saying its state in words with a lamp that only repeats it; the one open beside the fleet is selected (tinted and
  * raised a level, as a table's selected row). An agent that starts needing you is announced once.
+ * @example
+ * ```tsx
+ * import { AgentFleet, AgentFleetGroup, summarizeFleet } from 'altitude-design';
+ *
+ * <AgentFleet now={now} summary={summarizeFleet(seed.map((a) => a.state))}>
+ *   <AgentFleetGroup label="Needs you" empty="Nothing needs you.">{g.needsYou.map(row)}</AgentFleetGroup>
+ *   <AgentFleetGroup label="Working">{g.working.map(row)}</AgentFleetGroup>
+ *   <AgentFleetGroup label="Done" collapsible>{g.finished.map(row)}</AgentFleetGroup>
+ * </AgentFleet>
+ * ```
  */
 export declare function AgentFleet({ 'aria-label': label, now, summary, className, children, ...rest }: AgentFleetProps): React.JSX.Element;
 export interface AgentFleetGroupProps {
@@ -111,6 +121,18 @@ export interface AgentRequestsProps extends React.HTMLAttributes<HTMLElement> {
  * Every decision your agents are waiting on, in one queue, so you can answer them without opening
  * each agent: oldest first, because a wait costs the most the longer it runs. Each request asks for action, so it's a
  * raised card that arrives lifted and settles; nothing in it has been dispatched. A new one is announced once.
+ * @example
+ * ```tsx
+ * import { AgentRequest, AgentRequests, Button } from 'altitude-design';
+ *
+ * <AgentRequests now={now}>
+ *   {left.map((r) => (
+ *     <AgentRequest key={r.id} agent={r.agent} kind={r.kind} since={r.since} title={r.title} detail={r.detail} onOpen={() => {}}
+ *       actions={<>{r.answers.map((a) => <Button key={a} size="sm" variant="secondary" onClick={() => done(r.id)}>{a}</Button>)}
+ *         {r.decline && <Button size="sm" variant="ghost" onClick={() => done(r.id)}>{r.decline}</Button>}</>} />
+ *   ))}
+ * </AgentRequests>
+ * ```
  */
 export declare function AgentRequests({ title, now, empty, className, children, ...rest }: AgentRequestsProps): React.JSX.Element;
 export interface AgentRequestProps {
@@ -161,6 +183,12 @@ export interface AgentLanesProps extends Omit<React.HTMLAttributes<HTMLElement>,
  * you is the bottleneck a fleet hides, so the takeaway says it first. A chart, so its marks are flat (Charts): the
  * stretches are equal-height bars on each lane's ground line, told apart by fill and pattern (waiting is hatched,
  * blocked an outline) and named in a legend in words; a 1px "Now" rule ends the record. A table says the same.
+ * @example
+ * ```tsx
+ * import { AgentLanes } from 'altitude-design';
+ *
+ * <AgentLanes lanes={lanes} start={t0} now={m(31)} selected={sel} onSelect={setSel} />
+ * ```
  */
 export declare function AgentLanes({ lanes, start, now, takeaway, 'aria-label': label, selected, onSelect, className, ...rest }: AgentLanesProps): React.JSX.Element;
 export {};

package/dist/types-cjs/ai-label.d.cts

@@ -26,5 +26,12 @@ export interface AILabelProps {
  * "Drafted with AI" once a person has reviewed it), with no gradient and no glow: the light never moves. It acts, so it
  * lifts one level when pointed at and opens a Popover saying how the content was produced. Provenance stays on the
  * accepted record.
+ * @example
+ * ```tsx
+ * import { AILabel } from 'altitude-design';
+ *
+ * <AILabel subject="Summary" model="Opus 5.5" generatedAt={new Date(Date.now() - 4 * 60000)} confidence="Medium: two sources disagreed about the renewal date"
+ * sources={[{ title: 'Call with Jamie Lee, 28 Oct', url: '#/calls/28' }, { title: 'Contract v3.pdf', url: '#/files/contract' }]} />
+ * ```
  */
 export declare function AILabel({ subject, model, generatedAt, sources, confidence, reviewedBy, editedBy, children, className }: AILabelProps): React.JSX.Element;

package/dist/types-cjs/app-shell.d.cts

@@ -78,6 +78,29 @@ export interface AppShellProps extends Omit<SidebarProviderProps, 'children'> {
 /**
  * The frame of an app: a sidebar of destinations, a top bar and the page, all on the ground and divided by lines.
  * The top bar rises when content passes under it. A skip link jumps to the page.
+ * @example
+ * ```tsx
+ * import { AppShell, Avatar, Button, DropdownMenu, Kbd, PageHeader, PageHeaderDescription, PageHeaderTitle, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarHeader, SidebarMenu, SidebarMenuButton, SidebarMenuItem } from 'altitude-design';
+ *
+ * <AppShell
+ *   sidebar={
+ *     <Sidebar>
+ *       <SidebarHeader>
+ *         <DropdownMenu items={[{ label: 'Acme Inc.' }, { label: 'Northwind' }, { type: 'separator' }, { label: 'Create workspace' }]}
+ *           trigger={<button className="as-ws"><Avatar name="Acme Inc." size={24} /><span className="alt-sidebar-text">Acme Inc.</span></button>} />
+ *       </SidebarHeader>
+ *       <SidebarContent>
+ *         <SidebarGroup label="Workspace"><SidebarMenu>{item('inbox', 'Inbox', 4)}{item('projects', 'Projects')}{item('reports', 'Reports')}</SidebarMenu></SidebarGroup>
+ *         <SidebarGroup label="Admin" collapsible><SidebarMenu>{item('members', 'Members')}{item('billing', 'Billing')}{item('settings', 'Settings')}</SidebarMenu></SidebarGroup>
+ *       </SidebarContent>
+ *       <SidebarFooter><SidebarMenu><SidebarMenuItem><SidebarMenuButton href="#/me" icon={<Avatar name="Maya Chen" size={20} />}>Maya Chen</SidebarMenuButton></SidebarMenuItem></SidebarMenu></SidebarFooter>
+ *     </Sidebar>
+ *   }
+ *   topBar={<Button variant="secondary" size="sm" className="search">Search… <Kbd>⌘K</Kbd></Button>}>
+ *   <PageHeader primary={<Button variant="primary">New message</Button>}><PageHeaderTitle>{at[0].toUpperCase() + at.slice(1)}</PageHeaderTitle><PageHeaderDescription>The sidebar's current destination sits on a raised pill that glides as you move. ⌘B collapses it to a rail.</PageHeaderDescription></PageHeader>
+ *   <div className="rows">{Array.from({ length: 8 }, (_, i) => <div key={i} />)}</div>
+ * </AppShell>
+ * ```
  */
 export declare function AppShell({ sidebar, topBar, children, className, ...provider }: AppShellProps): React.JSX.Element;
 export {};

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

@@ -72,6 +72,14 @@ export interface AreaChartProps {
  * order (the order never changes, so a band never jumps), each parted from the one above by a 2px line in the plot's
  * own colour, with a 2px top line on the topmost. A single area is a flat data-1 fill at reduced opacity under a 2px
  * line. No gradient fill: the only face gradient in Altitude is the sheen, and it means "press it".
+ * @example
+ * ```tsx
+ * import { AreaChart, ChartLegend, ChartLegendContent } from 'altitude-design';
+ *
+ * <AreaChart data={week ? reqB : reqA} x="day" stack curve="monotone">
+ *   <ChartLegend content={<ChartLegendContent toggle />} />
+ * </AreaChart>
+ * ```
  */
 export declare function AreaChart({ stack, curve, labels }: AreaChartProps): React.JSX.Element;
 export declare namespace AreaChart {