altitude-design 0.4.0 → 0.4.2

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

@@ -160,6 +160,21 @@ export declare const LoadingStyleContext: React.Context<"sweep" | "breath">;
 export declare const ModeContext: React.Context<AppMode | null>;
 /** The mode's name as a plate, for headers of things that float above the page (Dialog, Sheet). */
 export declare function ModePlate(): React.JSX.Element | null;
+/**
+ * @example
+ * ```tsx
+ * import { AltitudeProvider, Badge, Button, Input, Switch } from 'altitude-design';
+ *
+ * <AltitudeProvider key={i} scheme={s} accent={accent} className="shell"><div className="scheme">
+ *   <h4>{typeof s === 'string' ? s[0].toUpperCase() + s.slice(1) : 'Custom'}</h4>
+ *   <small>{accent ? 'accent="' + accent + '"' : typeof s === 'string' ? 'scheme="' + s + '"' : 'scheme={paper}'}</small>
+ *   <Button variant="primary" size="sm">Publish</Button>
+ *   <Input size="sm" placeholder="Search" aria-label="Search" />
+ *   <div style={{ display: 'flex', gap: 10, alignItems: 'center' }}><Switch defaultChecked aria-label="Enabled" /><Badge tone="accent">Beta</Badge></div>
+ *   <div className="series">{[1, 2, 3, 4, 5, 6].map((n) => <span key={n} style={{ background: `var(--data-${n})` }} />)}<small>{accent ? 'data-1…6, led by the accent' : 'data-1…6'}</small></div>
+ * </div></AltitudeProvider>
+ * ```
+ */
 export declare function AltitudeProvider({ scheme, accent, motion, contrast, density, recede, approach, loading, mode, devChecks, className, style, children, ...rest }: AltitudeProviderProps): React.JSX.Element;
 /** Renders into the provider's layer host (inside the theme, outside the receding stage), else document.body. */
 export declare function Layer({ children }: {
@@ -207,6 +222,14 @@ export interface SurfaceProps extends React.HTMLAttributes<HTMLElement>, DepthPr
     href?: string;
     as?: keyof React.JSX.IntrinsicElements;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Surface } from 'altitude-design';
+ *
+ * <Surface level={-1} className="s"><b>level={'{-1}'}</b><span>A well. Holds things; never lifts.</span></Surface>
+ * ```
+ */
 export declare const Surface: React.ForwardRefExoticComponent<SurfaceProps & React.RefAttributes<HTMLElement>>;
 /**
  * Keep an anchored floating panel (a tooltip, popover, menu, hover card, list) inside the viewport (#248): when it
@@ -252,5 +275,13 @@ export interface KbdProps extends React.HTMLAttributes<HTMLElement> {
      */
     hideOnTouch?: boolean;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Kbd } from 'altitude-design';
+ *
+ * <Kbd listen="Meta">⌘</Kbd>
+ * ```
+ */
 export declare function Kbd({ listen, hideOnTouch, className, children, ...rest }: KbdProps): React.JSX.Element | null;
 export {};

package/dist/types-cjs/data-grid.d.cts

@@ -72,5 +72,30 @@ export interface DataGridProps<T> {
  * edited opens into a well clipped to the cell; an invalid value deepens to a trench; when a value lands the floor
  * rises flush and the cell settles. A pending cell holds a small raised plate; a failed one drops to a trench. Range
  * selection is a tint, not a height: choosing a target isn't live content.
+ * @example
+ * ```tsx
+ * import { Badge, DataGrid, Select } from 'altitude-design';
+ *
+ * <DataGrid aria-label="Inventory" rows={rows} getRowId={r => r.id} getRowLabel={r => r.name}
+ *   columns={[
+ *     { key: 'name', header: 'Name', editable: true, validate: v => String(v).trim() ? undefined : 'Enter a name.' },
+ *     { key: 'sku', header: 'SKU' },
+ *     { key: 'price', header: 'Price', align: 'end', editable: true, parse: t => t.trim() === '' ? '' : Number(t), format: dgMoney,
+ *       validate: v => v === '' || !Number.isFinite(v) || v < 0 ? 'Use a price of 0 or more.' : undefined, cell: r => `$${r.price}` },
+ *     { key: 'stock', header: 'Stock', align: 'end', editable: true, parse: t => t.trim() === '' ? 0 : Number(t), format: dgMoney,
+ *       validate: v => Number.isInteger(v) && v >= 0 ? undefined : 'Use a whole number, 0 or more.' },
+ *     { key: 'status', header: 'Status', editable: true, format: v => DG_STATUS.find(s => s.value === v)?.label ?? '',
+ *       cell: r => <Badge tone={r.status === 'active' ? 'positive' : r.status === 'paused' ? 'caution' : 'neutral'}>{DG_STATUS.find(s => s.value === r.status).label}</Badge>,
+ *       editor: control => <Select {...control} items={DG_STATUS} size="sm" defaultOpen /> },
+ *   ]}
+ *   onCellSave={async change => {
+ *     await dgWait(250);
+ *     // The demo service locks the lamp's price during a sale.
+ *     if (change.rowId === 'p1' && change.key === 'price') return { ok: false, error: 'The Desk lamp price is locked during the sale.' };
+ *     apply([change]); return { ok: true };
+ *   }}
+ *   onCellsSave={async changes => { await dgWait(300); apply(changes); return { ok: true }; }}
+ *   onUndo={last => apply(last.map(c => ({ ...c, draft: c.previousValue })))} />
+ * ```
  */
 export declare function DataGrid<T>({ rows, columns, getRowId, getRowLabel, onCellSave, onCellsSave, onUndo, showInvalid, maxHeight, className, ...aria }: DataGridProps<T>): React.JSX.Element;

package/dist/types-cjs/date-picker.d.cts

@@ -89,6 +89,12 @@ export interface DateRangePickerProps extends PickerBase {
 /**
  * A date in a field, typed or picked. The field is an opening built like Select; its floor rises flush once it holds a
  * date. The calendar floats at level 3; days are flush and the chosen one carries the raised accent mark.
+ * @example
+ * ```tsx
+ * import { DatePicker } from 'altitude-design';
+ *
+ * <DatePicker value={due} onValueChange={setDue} min={DP_TODAY} isUnavailable={weekend} locale="en-GB" defaultOpen />
+ * ```
  */
 export declare function DatePicker({ value, defaultValue, onValueChange, min, max, isUnavailable, locale, weekStartsOn, id, name, disabled, required, invalid, size, className, defaultOpen, ...aria }: DatePickerProps): React.JSX.Element;
 /** Two dates as one span. In the calendar the span is a sunk track between two raised ends, the Slider's build. */

package/dist/types-cjs/diff-view.d.cts

@@ -49,6 +49,14 @@ export declare function diffChanges(ops: Op[]): Change[];
  * What changed between two versions, in signs and words. Both versions are the record, so it lies flush. Additions are
  * positive-soft with a + sign and "Added", removals critical-soft, struck through, with − and "Removed"; a changed
  * property shows the old value struck through beside the new. Long unchanged runs fold behind lids. Never colour alone.
+ * @example
+ * ```tsx
+ * import { DiffView, diffChanges, diffLines } from 'altitude-design';
+ *
+ * <DiffView caption="src/pricing.ts · proposed by the assistant" before={pricingBefore} after={pricingAfter} review decisions={decisions}
+ * onDecide={(id, d) => setDecisions({ ...decisions, [id]: d })}
+ * onDecideAll={(d) => setDecisions(Object.fromEntries(diffChanges(diffLines(pricingBefore, pricingAfter)).map((c) => [c.id, decisions[c.id] ?? d])))} />
+ * ```
  */
 export declare function DiffView({ mode, before, after, fields, context, caption, hunks, review, decisions, onDecide, onDecideAll, className }: DiffViewProps): React.JSX.Element;
 export {};

package/dist/types-cjs/dot-plot.d.cts

@@ -47,6 +47,12 @@ export interface DotPlotProps {
  * the ground, as a ScatterChart's do: at least 8px, a marker shape per series, ringed 2px in the plot's colour. With no
  * zero there's no ground line. A spread is a flat band behind its dot, never error bars; a dumbbell joins a hollow
  * "from" dot to a filled "to" dot with a 2px ink-muted link.
+ * @example
+ * ```tsx
+ * import { DotPlot } from 'altitude-design';
+ *
+ * <DotPlot data={services} x="service" range={['p10', 'p90']} rangeLabel="10th–90th percentile" sort="desc" />
+ * ```
  */
 export declare function DotPlot(props: DotPlotProps): React.JSX.Element | null;
 export declare namespace DotPlot {

package/dist/types-cjs/edit-region.d.cts

@@ -83,6 +83,29 @@ export interface EditRegionBinder<T> {
  * record on the ground; Edit lifts it into a static raised editor holding the fields. The editor's padding is there in
  * both modes (with a negative margin), so lifting changes colour and shadow, never position. The session follows
  * InlineEdit: no save on blur, one write in flight, a known failure keeps the draft, and an outside change blocks Save.
+ * @example
+ * ```tsx
+ * import { EditRegion, EditRegionForm, EditRegionValue, EditRegionView, Field, Input, Select, Switch } from 'altitude-design';
+ *
+ * <EditRegion layout="in-place" label={person.name} editLabel={`Edit ${person.name}`} value={erFields(person)} validate={validate}
+ *   onValueChange={canonical => setPeople(people => people.map(p => p.id === person.id ? { ...server.current.get(person.id), ...canonical } : p))}
+ *   onSave={save(person)}>
+ *   <EditRegionView>
+ *     <span className="er-name"><EditRegionValue field="name">{person.name}</EditRegionValue></span>
+ *     <span className="er-meta"><EditRegionValue field="email">{person.email}</EditRegionValue> · <EditRegionValue field="role">{ER_ROLES.find(r => r.value === person.role).label}</EditRegionValue>{person.notify ? <> · <EditRegionValue field="notify">Gets updates</EditRegionValue></> : ''}</span>
+ *   </EditRegionView>
+ *   <EditRegionForm>
+ *     {field => <>
+ *       <div className="er-name-edit"><Field label="Name" required error={field.error('name')}><Input {...field('name')} autoComplete="off" /></Field></div>
+ *       <div className="er-meta-edit">
+ *         <Field label="Email" required error={field.error('email')}><Input {...field('email')} type="email" autoComplete="off" /></Field>
+ *         <Field label="Role"><Select {...field.value('role')} items={ER_ROLES} /></Field>
+ *         <Switch {...field.checked('notify')} label="Gets updates" />
+ *       </div>
+ *     </>}
+ *   </EditRegionForm>
+ * </EditRegion>
+ * ```
  */
 export declare function EditRegion<T extends Record<string, unknown>>({ label, value, onValueChange, onSave, validate, open: openProp, defaultOpen, onOpenChange, disabled, initialFocus, focusFallback, isEqual, editLabel, saveLabel, cancelLabel, settleDuration, layout, className, children }: EditRegionProps<T>): React.JSX.Element;
 /** Read mode: the record as text. Shows an Edit button after it unless `trigger={false}` (then place EditRegionTrigger yourself). */

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

@@ -20,5 +20,14 @@ export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLElement>,
 /**
  * An opening the first record will fill. Nothing here yet is a well cut into the page (not a raised card, not an
  * alert), with a dashed rim, a title that names what's empty and one next action standing in it.
+ * @example
+ * ```tsx
+ * import { Button, EmptyState } from 'altitude-design';
+ *
+ * <EmptyState icon={<Gift />} title="No gift ideas yet" headingLevel={2}
+ *   description="Ideas you save stay private to you until you share them."
+ *   action={<Button variant="primary">Add idea</Button>}
+ *   secondary={<Button variant="ghost">Import a list</Button>} />
+ * ```
  */
 export declare function EmptyState({ icon, title, description, action, secondary, size, headingLevel, announce, className, children, ...rest }: EmptyStateProps): React.JSX.Element;

package/dist/types-cjs/feature-gate.d.cts

@@ -18,5 +18,13 @@ export interface FeatureGateProps {
  * A feature that needs another plan, shown as locked rather than disabled. Disabled means nothing happens; a locked
  * control does something (it explains the plan and offers the upgrade), so it stays live: normal ink, it lifts when
  * pointed at, it's reachable, and it carries a lock and a plan plate. Pressing it opens a Popover.
+ * @example
+ * ```tsx
+ * import { Button, FeatureGate } from 'altitude-design';
+ *
+ * <FeatureGate requires="Business" description="Export any view to CSV, and schedule exports by email." onUpgrade={() => setSaid('Opening plans…')} compareHref="#/billing/plans">
+ *   <Button variant="secondary">Export to CSV</Button>
+ * </FeatureGate>
+ * ```
  */
 export declare function FeatureGate({ requires, description, onUpgrade, compareHref, canUpgrade, children, className }: FeatureGateProps): React.JSX.Element;

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

@@ -62,4 +62,12 @@ export declare const filterValueText: (f: FilterField, v: FilterValue) => string
  */
 /** The whole expression in words: "Plan is Pro and any of: Country is Germany, Seats > 50". */
 export declare function filterSentence(fields: FilterField[], value: Filter[] | FilterTree, match?: 'all' | 'any'): string;
+/**
+ * @example
+ * ```tsx
+ * import { FilterBar } from 'altitude-design';
+ *
+ * <FilterBar aria-label="Filter issues" fields={FB_FIELDS} value={filters} onValueChange={setFilters} match={match} onMatchChange={setMatch} resultCount={count} />
+ * ```
+ */
 export declare function FilterBar(props: FilterBarProps): React.JSX.Element;

package/dist/types-cjs/formatted-number.d.cts

@@ -34,5 +34,11 @@ export interface FormattedNumberProps extends FormatNumberOptions {
 /**
  * A number is the record, so it lies flush: tabular figures, the exact value on hand when it's rounded or abbreviated,
  * and units spoken in words. A changed value cross-fades and settles with the afterglow; it never counts.
+ * @example
+ * ```tsx
+ * import { FormattedNumber } from 'altitude-design';
+ *
+ * <FormattedNumber value={4900} format="currency" currency="EUR" locale="en-IE" />
+ * ```
  */
 export declare function FormattedNumber({ value, className, style, id, title, ...options }: FormattedNumberProps): React.JSX.Element;

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

@@ -50,6 +50,12 @@ export interface HeatmapProps {
  * record, so they lie flat on the plot: a data-seq step (or data-div around a midpoint), parted by 2px of the plot's
  * own colour, never raised, never shaded. Each step also has a pattern density for forced colours and print, and its
  * range in words in the legend, the cell's name and the table.
+ * @example
+ * ```tsx
+ * import { Heatmap } from 'altitude-design';
+ *
+ * <Heatmap variant="calendar" data={commits} date="day" value="count" bins={[0, 1, 4, 10]} />
+ * ```
  */
 export declare function Heatmap(props: HeatmapProps): React.JSX.Element | null;
 export declare namespace Heatmap {

package/dist/types-cjs/inline-citation.d.cts

@@ -21,6 +21,12 @@ export interface InlineCitationProps {
  * A numbered source marker in generated text. A citation is part of the record, so it's a small flush plate (the
  * ChartAnnotation build) in the text; it acts, so it lifts one level when pointed at, and a HoverCard previews the
  * source on hover and on focus. Named "Source 2: Billing FAQ", never "[2]".
+ * @example
+ * ```tsx
+ * import { InlineCitation } from 'altitude-design';
+ *
+ * <InlineCitation index={1} source={sources[0]} />
+ * ```
  */
 export declare function InlineCitation({ index, source, href, idPrefix, className }: InlineCitationProps): React.JSX.Element;
 export interface SourcesProps {

package/dist/types-cjs/inline-edit.d.cts

@@ -67,5 +67,12 @@ export interface InlineEditProps<V = string> {
  * One local editing session. The application remains the sole owner of the committed value and write. Editing happens
  * in place: the value's text sits in a slot with the control's own inset and font, so when the control opens there, the
  * text doesn't move; only the well (floor, walls, border) fades in around it. Whatever still changes size glides.
+ * @example
+ * ```tsx
+ * import { InlineEdit } from 'altitude-design';
+ *
+ * <InlineEdit label="Description" value={task.description} onValueChange={publish('description')} onSave={save('description')}
+ *   multiline rows={3} maxRows={8} maxLength={500} />
+ * ```
  */
 export declare function InlineEdit<V = string>({ value, onValueChange, onSave, label, validate, required, maxLength, disabled, editLabel, saveLabel, cancelLabel, focusFallback, className, renderValue, editor, commit, isEqual, multiline, rows, maxRows, trigger: triggerMode, hint, emptyLabel, shortcut, settleDuration }: InlineEditProps<V>): React.ReactElement;

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

@@ -22,6 +22,17 @@ export interface InputOTPProps extends Omit<React.InputHTMLAttributes<HTMLInputE
  * A one-time code as a row of openings that fill. One real input (inputmode numeric, autocomplete one-time-code) drives
  * the slots, so autofill, paste and screen readers see one field; each slot is a well whose floor rises flush as its
  * character lands, and a rejected code drops the whole row to a trench.
+ * @example
+ * ```tsx
+ * import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from 'altitude-design';
+ *
+ * <InputOTP maxLength={6} value={code} verifying={state === 'verifying'}
+ *   onChange={(c) => { setCode(c); if (state === 'wrong') setState('idle'); }} onComplete={verify}>
+ *   <InputOTPGroup>{[0, 1, 2].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
+ *   <InputOTPSeparator />
+ *   <InputOTPGroup>{[3, 4, 5].map((i) => <InputOTPSlot key={i} index={i} />)}</InputOTPGroup>
+ * </InputOTP>
+ * ```
  */
 export declare const InputOTP: React.ForwardRefExoticComponent<InputOTPProps & React.RefAttributes<HTMLInputElement>>;
 /** Slots that sit together, parted from the next group by an InputOTPSeparator. */

package/dist/types-cjs/item-group.d.cts

@@ -80,6 +80,35 @@ export interface ItemGroupProps<T extends Record<string, unknown>> {
  * A list of slats changed in the list itself. Slats are the record, flush on the ground with line dividers. One slat
  * at a time lifts into its editor (EditRegion), its neighbours flush and readable; the add slat is an opening; a slat
  * picked up to reorder floats at level 3 over its slot. Removal follows the application's stated policy.
+ * @example
+ * ```tsx
+ * import { Button, Field, Input, Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle } from 'altitude-design';
+ *
+ * <ItemGroup aria-labelledby="ig-hooks" items={hooks} getKey={h => h.id} getLabel={h => h.name}
+ *   renderItem={(h, { editProps, removeProps }) => <Item>
+ *     <ItemMedia><HookIcon /></ItemMedia>
+ *     <ItemContent><ItemTitle>{h.name}</ItemTitle><ItemDescription className="ig-url">{h.url}</ItemDescription></ItemContent>
+ *     <ItemActions><Button size="sm" variant="ghost" {...editProps}>Edit</Button><Button size="sm" variant="ghost" {...removeProps}>Remove</Button></ItemActions>
+ *   </Item>}
+ *   renderEditor={field => <>
+ *     <Field label="Name" required error={field.error('name')}><Input {...field('name')} /></Field>
+ *     <Field label="Endpoint URL" required error={field.error('url')}><Input {...field('url')} type="url" /></Field>
+ *   </>}
+ *   onSave={async (draft, { previousValue }) => {
+ *     const errors = validate(draft); if (Object.keys(errors).length) return { ok: false, error: 'Check the highlighted fields.', fieldErrors: errors };
+ *     await igWait(300); return { ok: true, value: { ...draft, name: draft.name.trim(), revision: previousValue.revision + 1 } };
+ *   }}
+ *   onItemChange={h => setHooks(list => list.map(x => x.id === h.id ? h : x))}
+ *   newItem={() => ({ id: '', name: '', url: 'https://', revision: 0 })}
+ *   onCreate={async draft => {
+ *     const errors = validate(draft); if (Object.keys(errors).length) return { ok: false, error: 'Check the highlighted fields.', fieldErrors: errors };
+ *     await igWait(300); const hook = { ...draft, id: 'n' + ++seq.current, name: draft.name.trim(), revision: 1 }; setHooks(list => [...list, hook]); return { ok: true, value: hook };
+ *   }}
+ *   addLabel="Add webhook"
+ *   onReorder={async next => { await igWait(200); setHooks(next); }}
+ *   onRemove={async h => { await igWait(200); trash.current.set(h.id, hooks.indexOf(h)); setHooks(list => list.filter(x => x.id !== h.id)); }}
+ *   removal={{ kind: 'recoverable', undo: h => setHooks(list => { const next = [...list]; next.splice(trash.current.get(h.id) ?? next.length, 0, h); return next; }) }} />
+ * ```
  */
 export declare function ItemGroup<T extends Record<string, unknown>>({ items, getKey, getLabel, renderItem, renderEditor, onSave, onItemChange, newItem, onCreate, addLabel, onReorder, onRemove, removal, empty, className, ...aria }: ItemGroupProps<T>): React.JSX.Element;
 export declare function Item({ className, ...rest }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;

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

@@ -109,6 +109,12 @@ export declare function linePath(points: Array<[number, number] | null>, curve?:
  * Change over time for one to four series. Lines are the record: 2px strokes in their series' colours, round joins,
  * no fill, no glow. A missing value breaks the line. The last point carries a marker and each line is named at its
  * end, so the legend is the lines themselves.
+ * @example
+ * ```tsx
+ * import { LineChart } from 'altitude-design';
+ *
+ * <LineChart data={latency} x="t" y={{ format: (ms) => `${ms} ms` }} />
+ * ```
  */
 export declare function LineChart({ curve, endLabels, band, compare }: LineChartProps): React.JSX.Element;
 export declare namespace LineChart {

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

@@ -7,5 +7,12 @@ export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement>
     /** Mark links already followed: their underline turns ink-muted. Off by default; use it in long lists of documents. */
     visited?: boolean;
 }
-/** Navigation in accent-ink with an underline. A link is text in the record, so it never lifts: hover thickens the underline. */
+/** Navigation in accent-ink with an underline. A link is text in the record, so it never lifts: hover thickens the underline.
+ * @example
+ * ```tsx
+ * import { Link } from 'altitude-design';
+ *
+ * <Link href="#webhooks">Read about webhooks</Link>
+ * ```
+ */
 export declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;

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

@@ -83,6 +83,12 @@ export declare function parseMarkdown(source: string, { streaming, allowHtml }?:
  * An answer's Markdown, set as Altitude prose: the record's typography, adding no height. Code is CodeBlock, links are
  * Link, `[n]` markers are InlineCitation, tables use Table's flush rows, images rise from an imprint. While
  * `streaming`, unfinished constructs render as unfinished rather than as raw text.
+ * @example
+ * ```tsx
+ * import { Markdown } from 'altitude-design';
+ *
+ * <Markdown citations={sources}>{done}</Markdown>
+ * ```
  */
 export declare const Markdown: React.ForwardRefExoticComponent<MarkdownProps & React.RefAttributes<HTMLDivElement>>;
 export {};

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

@@ -39,5 +39,11 @@ export interface MeterProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
  * rises out of a trench because a task under way is live). Thresholds are 1px notches at the track's rim; past them
  * the fill turns caution or critical and the state is said in words, with a lamp that relights when it changes.
  * Segments show parts of a whole, the honest replacement for a donut.
+ * @example
+ * ```tsx
+ * import { Meter } from 'altitude-design';
+ *
+ * <Meter label="Storage" value={used} max={100} high={80} format={gb} />
+ * ```
  */
 export declare function Meter(props: MeterProps): React.JSX.Element;

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

@@ -21,5 +21,11 @@ export interface DrilldownProps extends React.HTMLAttributes<HTMLDivElement> {
  * Hierarchy as a stack. Each place you go into is laid on top of the one before: the breadcrumb
  * builds a staircase — every step stands on the same ground line and each deeper place is a taller
  * step — and the view sits on a pile whose thickness is how deep you are. Going back lifts sheets off the top.
+ * @example
+ * ```tsx
+ * import { Drilldown } from 'altitude-design';
+ *
+ * <Drilldown root={tree} />
+ * ```
  */
 export declare function Drilldown({ root, className, ...rest }: DrilldownProps): React.JSX.Element;

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

@@ -38,5 +38,11 @@ export interface NotificationCenterProps extends NotificationListProps {
  * A bell with a count that opens the list. The bell is live (a ghost button), the count floats (only a count wants
  * you), the panel floats at level 3 (a Sheet at level 4 on narrow screens), and the list in it lies on the ground.
  * New notifications are announced, batched, whether or not the panel is open.
+ * @example
+ * ```tsx
+ * import { NotificationCenter } from 'altitude-design';
+ *
+ * <NotificationCenter items={items} onMarkRead={markRead} onMarkAllRead={() => setItems((xs) => xs.map((x) => ({ ...x, read: true })))} preferencesHref="#/settings/notifications" />
+ * ```
  */
 export declare function NotificationCenter({ mobileBreakpoint, className, ...list }: NotificationCenterProps): React.JSX.Element;

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

@@ -26,5 +26,11 @@ export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInp
  * A number field: an opening that fills, with two small raised steppers in its end cap (push up, fill down). It reads
  * what's typed in the locale's own way, clamps to min and max when committed, and is a spinbutton with its unit in
  * aria-valuetext. The steppers aren't tab stops: the arrow keys step.
+ * @example
+ * ```tsx
+ * import { NumberInput } from 'altitude-design';
+ *
+ * <NumberInput value={seats} onValueChange={setSeats} min={1} max={500} incrementLabel="Increase seats" decrementLabel="Decrease seats" />
+ * ```
  */
 export declare const NumberInput: React.ForwardRefExoticComponent<NumberInputProps & React.RefAttributes<HTMLInputElement>>;

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

@@ -11,6 +11,14 @@ export interface TooltipProps {
     defaultOpen?: boolean;
     children: React.ReactElement<any>;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Button, Tooltip } from 'altitude-design';
+ *
+ * <Tooltip content="Bold  ⌘B" defaultOpen><Button square variant="ghost" aria-label="Bold"><b>B</b></Button></Tooltip>
+ * ```
+ */
 export declare function Tooltip({ content, side, delay, defaultOpen, children }: TooltipProps): React.JSX.Element;
 export interface PopoverProps {
     trigger: React.ReactElement<any>;
@@ -23,6 +31,20 @@ export interface PopoverProps {
     className?: string;
     'aria-label'?: string;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Button, Field, Input, Popover } from 'altitude-design';
+ *
+ * <Popover defaultOpen aria-label="Share" trigger={<Button>Share</Button>}>
+ *   <div className="col" style={{ width: 280, gap: 12 }}>
+ *     <b style={{ font: '600 14px/20px var(--font-sans)' }}>Invite to project</b>
+ *     <Field label="Email address"><Input size="sm" type="email" placeholder="name@company.com" /></Field>
+ *     <div className="row" style={{ justifyContent: 'flex-end', gap: 8 }}><Button size="sm" variant="primary">Send invite</Button></div>
+ *   </div>
+ * </Popover>
+ * ```
+ */
 export declare function Popover({ trigger, children, open, defaultOpen, onOpenChange, side, align, className, ...rest }: PopoverProps): React.JSX.Element;
 export interface MenuItem {
     type?: 'item';
@@ -77,6 +99,14 @@ export declare function MenuPanel({ items, id, state, side, align, className, st
     sheet?: boolean;
     title?: React.ReactNode;
 }): React.JSX.Element;
+/**
+ * @example
+ * ```tsx
+ * import { Button, DropdownMenu, Icons } from 'altitude-design';
+ *
+ * <DropdownMenu defaultOpen items={items} trigger={<Button trailing={<Icons.ChevronDown />}>Actions</Button>} />
+ * ```
+ */
 export declare function DropdownMenu({ trigger, items, align, side, defaultOpen, className, presentation, title }: DropdownMenuProps): React.JSX.Element;
 export interface HoverCardProps {
     /** What you hover or focus: usually a link or an avatar. It must do its own job (navigate, open) without the card. */
@@ -98,6 +128,14 @@ export interface HoverCardProps {
 /**
  * A richer preview that rises from its trigger at level 3, after hover intent or on keyboard focus. It shares Tooltip's
  * warm-up: once one has shown, a neighbour opens at once. Its content is supplementary, never the only way to reach anything.
+ * @example
+ * ```tsx
+ * import { HoverCard } from 'altitude-design';
+ *
+ * <HoverCard defaultOpen={true} trigger={<a href="#mara">Mara Quist</a>}>
+ *   <Card p={people.mara} />
+ * </HoverCard>
+ * ```
  */
 export declare function HoverCard({ trigger, children, side, align, openDelay, closeDelay, open, defaultOpen, onOpenChange, className }: HoverCardProps): React.JSX.Element;
 /** The summit is shared by every provider in the same document. */
@@ -147,6 +185,21 @@ export interface DialogProps {
     returnFocus?: () => HTMLElement | null;
     className?: string;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Alert, Button, Dialog } from 'altitude-design';
+ *
+ * <Dialog open={open} onOpenChange={setOpen} background={background} size="sm" title="Delete this file permanently?"
+ *   description={`“${target?.name || ''}” will be removed. You won’t be able to restore it.`} focusSelector="[data-cancel]" returnFocus={() => heading.current}
+ *   footer={<><Button data-cancel variant="ghost" onClick={() => setOpen(false)}>{busy ? 'Close' : 'Cancel'}</Button>
+ *     <Button data-confirm variant="danger" disabled={busy || operation?.state === 'conflict'} onClick={confirm}>{busy ? operation?.state === 'checking' ? 'Checking deletion…' : 'Deleting…' : failed ? 'Try deleting again' : 'Delete permanently'}</Button></>}>
+ *   <p className="body dialog-target">{target?.name}<br /><span className="cap">{target?.folder}</span></p>
+ *   {busy && <p role="status">Deletion is in progress. Closing this dialog won’t cancel it.</p>}
+ *   {failed && <Alert tone="critical" title="File not deleted">{operation.message}{operation.state === 'conflict' && <p>Latest file: {operation.current?.name || 'No longer available'}</p>}</Alert>}
+ * </Dialog>
+ * ```
+ */
 export declare function Dialog({ open, defaultOpen, onOpenChange, trigger, title, description, children, footer, size, dismissible, initialFocus, focusSelector, background, returnFocus, className }: DialogProps): React.JSX.Element;
 export type ToastTone = 'neutral' | 'positive' | 'caution' | 'critical';
 export interface ToastOptions {
@@ -165,6 +218,14 @@ export declare function toast(input: ToastOptions | string): number;
 export declare namespace toast {
     var dismiss: (id: number) => void;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Toaster } from 'altitude-design';
+ *
+ * <Toaster />
+ * ```
+ */
 export declare function Toaster({ className }: {
     className?: string;
 }): React.JSX.Element;

package/dist/types-cjs/page-header.d.cts

@@ -19,6 +19,20 @@ export interface PageHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>,
 /**
  * The block every page opens with: breadcrumb, title, description, actions and tabs. The page's name is the record, so
  * the block lies on the ground; only its actions are live, and it has one slot for the primary action (law 1).
+ * @example
+ * ```tsx
+ * import { Breadcrumb, Button, PageHeader, PageHeaderDescription, PageHeaderTitle, Tabs, TabsList, TabsTrigger } from 'altitude-design';
+ *
+ * <PageHeader sticky
+ *   breadcrumb={<Breadcrumb items={[{ label: 'Settings', href: '#/settings' }, { label: 'Members' }]} />}
+ *   primary={<Button variant="primary">Invite members</Button>}
+ *   actions={<Button variant="secondary">Export list</Button>}
+ *   overflow={[{ label: 'Download audit log' }, { label: 'Members settings' }]}
+ *   tabs={<Tabs variant="segmented" value={tab} onValueChange={setTab}><TabsList aria-label="Members sections"><TabsTrigger value="members">Members</TabsTrigger><TabsTrigger value="invites">Invitations</TabsTrigger><TabsTrigger value="roles">Roles</TabsTrigger></TabsList></Tabs>}>
+ *   <PageHeaderTitle>Members</PageHeaderTitle>
+ *   <PageHeaderDescription>People who can see and edit this workspace.</PageHeaderDescription>
+ * </PageHeader>
+ * ```
  */
 export declare function PageHeader({ breadcrumb, primary, actions, overflow, tabs, sticky, className, children, ...rest }: PageHeaderProps): React.JSX.Element;
 /** The page's h1. */

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

@@ -25,5 +25,11 @@ export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>,
 /**
  * Move through pages of a collection. The page numbers sit in a trench and the current page is one raised thumb that
  * travels to it, as RadioGroup's does: "you are here, among these". They stay links (or buttons) in plain Tab order.
+ * @example
+ * ```tsx
+ * import { Pagination } from 'altitude-design';
+ *
+ * <Pagination page={page} pageCount={11} onPageChange={go} total={214} pageSize={20} noun="invoices" loading={loading} />
+ * ```
  */
 export declare function Pagination({ page, pageCount, onPageChange, total, pageSize, hrefFor, hasNext, siblings, loading, noun, locale, className, 'aria-label': label, ...rest }: PaginationProps): React.JSX.Element;

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

@@ -18,5 +18,11 @@ export interface PasswordInputProps extends Omit<InputProps, 'type' | 'trailing'
  * A password field: an Input with a reveal Toggle in its end cap, a caps-lock notice, and, when creating one, its
  * strength as a reading (a Meter, never a Progress) and its requirements stamped as met. Strength and requirements
  * describe the field and are announced politely once typing pauses.
+ * @example
+ * ```tsx
+ * import { PasswordInput } from 'altitude-design';
+ *
+ * <PasswordInput defaultValue="correct horse" />
+ * ```
  */
 export declare const PasswordInput: React.ForwardRefExoticComponent<PasswordInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/types-cjs/permission-matrix.d.cts

@@ -30,5 +30,12 @@ export interface PermissionMatrixProps {
  * Roles against permissions. The grid is settled (the record of who can do what). An editable grant is a choice, built
  * like a Checkbox (a trench the accent pours into); an inherited or fixed grant is already decided, so it's a flush
  * stamped check, not a disabled box. The active cell is a ring, never a height. A grid: arrows move, Space toggles.
+ * @example
+ * ```tsx
+ * import { PermissionMatrix } from 'altitude-design';
+ *
+ * <PermissionMatrix aria-label="Role permissions" roles={roles} permissions={perms} value={grants} inherited={inherited}
+ *   onChange={(role, perm, on) => new Promise((r) => setTimeout(() => { setGrants((g) => ({ ...g, [role]: { ...g[role], [perm]: on } })); r(); }, 600))} />
+ * ```
  */
 export declare function PermissionMatrix({ roles, permissions, value, inherited, onChange, 'aria-label': label, className }: PermissionMatrixProps): React.JSX.Element;

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

@@ -23,5 +23,11 @@ export interface PileProps<T = unknown> extends Omit<React.HTMLAttributes<HTMLDi
  * (the badge says exactly); reaching for it fans them a little. Click it and the items slide out from under
  * the top card over the page below it, each casting its own shadow; click one to choose it; click the top,
  * press Escape or click away and they slide back.
+ * @example
+ * ```tsx
+ * import { Pile } from 'altitude-design';
+ *
+ * <Pile count={1} className="p"><div className="face"><b>Drafts</b><span>1 document</span></div></Pile>
+ * ```
  */
 export declare function Pile<T>({ count, interactive, items, renderItem, getKey, onSelect, open, defaultOpen, onOpenChange, maxHeight, className, children, ...rest }: PileProps<T>): React.JSX.Element;

package/dist/types-cjs/plan-picker.d.cts

@@ -36,5 +36,11 @@ export interface PlanPickerProps {
  * Choose a plan. The plans are positions in one choice, so the cards lie flush and one raised mark travels to the chosen
  * one, as RadioGroup's thumb does. "Current plan" and "Recommended" are plates, not height: marketing emphasis isn't
  * importance. The only level-2 slab is your Continue button, outside it.
+ * @example
+ * ```tsx
+ * import { PlanPicker } from 'altitude-design';
+ *
+ * <PlanPicker plans={plans} value={plan} onValueChange={setPlan} current="free" recommended="pro" period={period} onPeriodChange={setPeriod} locale="en-IE" aria-label="Choose a plan" />
+ * ```
  */
 export declare function PlanPicker({ plans, value, defaultValue, onValueChange, current, recommended, period, onPeriodChange, locale, 'aria-label': label, className }: PlanPickerProps): React.JSX.Element;

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

@@ -57,6 +57,17 @@ export interface PromptInputProps extends Omit<React.FormHTMLAttributes<HTMLForm
  * deepens as the pointer nears, and once it holds text the floor rises flush. Send is the level-2 primary; while a
  * response is generating it becomes Stop in the same slot and size, so nothing moves. Enter sends, Shift+Enter adds a
  * line, and Enter during IME composition never sends.
+ * @example
+ * ```tsx
+ * import { PromptInput, PromptInputSubmit, PromptInputTextarea, PromptInputToolbar } from 'altitude-design';
+ *
+ * <PromptInput onSubmit={({ text, mentions, command }) => setSent(`${command ? `/${command} · ` : ''}${text}${mentions ? ` · context: ${mentions.map((m) => m.label).join(', ')}` : ''}`)}
+ *   mentionable={(q) => new Promise((r) => setTimeout(() => r(context.filter((c) => c.label.toLowerCase().includes(q.toLowerCase()))), 250))}
+ *   commands={[{ name: 'review', description: 'Review the current changes' }, { name: 'compact', description: 'Summarise the conversation so far' }, { name: 'clear', description: 'Start a new conversation' }]}>
+ *   <PromptInputTextarea placeholder="@ to add context, / for commands" />
+ *   <PromptInputToolbar><PromptInputSubmit /></PromptInputToolbar>
+ * </PromptInput>
+ * ```
  */
 export declare function PromptInput({ onSubmit, status, onStop, onQueue, mentionable, commands, value, onValueChange, onAttach, accept, className, children, ...rest }: PromptInputProps): React.JSX.Element;
 export interface PromptInputTextareaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange'> {