altitude-design 0.4.0 → 0.4.2

package/dist/types/chart-brush.d.ts

@@ -24,6 +24,12 @@ interface BrushWiring {
  * opening, the whole series drawn as a flat line in a trench, because it's a track you slide along; the window is a raised lens
  * over it (level 1, accent rim, clear face) whose two grips are a range Slider's thumbs. Outside the window the overview
  * recedes. Drag the lens to pan, a grip to resize, or press outside it to centre the window there.
+ * @example
+ * ```tsx
+ * import { ChartBrush } from 'altitude-design';
+ *
+ * <ChartBrush />
+ * ```
  */
 export declare function ChartBrush({ __brush, ...props }: ChartBrushProps & {
     __brush?: BrushWiring;

package/dist/types/chart.d.ts

@@ -340,6 +340,12 @@ export declare function ChartTooltipContent({ indicator, labelFormat, hideLabel,
 /**
  * Puts your own content in a chart's readout. The readout is on for every chart by default; this only changes what it
  * shows. Place it inside the chart type or the container: `<ChartTooltip content={<ChartTooltipContent indicator="dot" />} />`.
+ * @example
+ * ```tsx
+ * import { ChartTooltip, ChartTooltipContent } from 'altitude-design';
+ *
+ * <ChartTooltip content={<ChartTooltipContent indicator="dot" labelFormat={(w) => 'Week of ' + long.format(new Date(w + 'T00:00:00Z'))} />} />
+ * ```
  */
 export declare function ChartTooltip(_: {
     content?: React.ReactElement<ChartTooltipContentProps>;
@@ -383,7 +389,14 @@ export interface ChartLegendContentProps {
  * stop; ←/→ between keys), each an aria-pressed button; the last shown series can't be hidden.
  */
 export declare function ChartLegendContent({ toggle, label, items, swatch, onToggle }: ChartLegendContentProps): React.JSX.Element;
-/** A legend for the chart: place it inside the chart type or the container, with its content. */
+/** A legend for the chart: place it inside the chart type or the container, with its content.
+ * @example
+ * ```tsx
+ * import { ChartLegend, ChartLegendContent } from 'altitude-design';
+ *
+ * <ChartLegend content={<ChartLegendContent />} />
+ * ```
+ */
 export declare function ChartLegend(_: {
     content?: React.ReactElement<ChartLegendContentProps>;
 }): null;
@@ -426,6 +439,12 @@ export interface ChartReferenceProps {
  * solid (dashes mean "projected"), labelled at its right end; a band is a flat line-coloured fill, labelled inside.
  * Place it inside the chart type or the container. The container draws it, so labels stay clear of each other and of
  * the marks.
+ * @example
+ * ```tsx
+ * import { ChartReference } from 'altitude-design';
+ *
+ * <ChartReference y={[0.995, 1]} label="Normal range" />
+ * ```
  */
 export declare function ChartReference(_: ChartReferenceProps): null;
 export declare namespace ChartReference {
@@ -566,5 +585,14 @@ export interface ChartEmpty {
  * would lift bars off the ground line and misstate every value. `null` or `[]`: an EmptyState in the plot. A new
  * promise (or `refreshing`) while data shows: the old chart stays, at half strength after dur-grace. A rejected
  * promise goes to your error boundary.
+ * @example
+ * ```tsx
+ * import { ChartContainer } from 'altitude-design';
+ *
+ * <ChartContainer aria-labelledby="rc" data={months} x="month" aspect={1.7} summary="Revenue rose 44% while costs held flat."
+ *   config={{ revenue: { label: 'Revenue', format: usd.format }, costs: { label: 'Costs', format: usd.format } }}>
+ *   <Lines />
+ * </ChartContainer>
+ * ```
  */
 export declare function ChartContainer(props: ChartContainerProps): React.JSX.Element;

package/dist/types/checklist.d.ts

@@ -67,5 +67,11 @@ export interface ChecklistProps<T> {
  * A list you write into, one line per item. Each line is the editor (no Save, no read mode): it commits when you
  * leave it. Items lie flush; the empty line at the end is an opening; the checkbox is a choice built like the Switch,
  * and a done item is pressed into the record: muted and struck through, kept in place.
+ * @example
+ * ```tsx
+ * import { Checklist } from 'altitude-design';
+ *
+ * <Checklist aria-labelledby="cl-launch" nested {...props} {...launch} />
+ * ```
  */
 export declare function Checklist<T>({ items, getKey, getText, isDone, getChildren, nested, sortDone, onChange, onUndo, createId, placeholder, disabled, className, ...aria }: ChecklistProps<T>): React.JSX.Element;

package/dist/types/code-block.d.ts

@@ -28,5 +28,11 @@ export interface CodeBlockProps extends Omit<React.HTMLAttributes<HTMLElement>,
 /**
  * Code shown to read and copy is the record: it lies flush on the ground with a line rim, in mono, with no shadow.
  * Several forms of the same thing switch with segmented Tabs; copy is a CopyButton; code still arriving has a dashed rule.
+ * @example
+ * ```tsx
+ * import { CodeBlock } from 'altitude-design';
+ *
+ * <CodeBlock title="Install" tabs={[{ label: 'npm', language: 'sh', code: 'npm install altitude-design' }, { label: 'pnpm', language: 'sh', code: 'pnpm add altitude-design' }, { label: 'yarn', language: 'sh', code: 'yarn add altitude-design' }]} />
+ * ```
  */
 export declare function CodeBlock({ code, language, title, tabs, highlight, syntax, lineNumbers, streaming, maxHeight, copyable, className, ...rest }: CodeBlockProps): React.JSX.Element;

package/dist/types/collections.d.ts

@@ -188,6 +188,21 @@ export interface BoardProps extends React.HTMLAttributes<HTMLDivElement> {
 /**
  * Columns of cards. Columns are receptacles: flush at rest, they open into wells while a card is carried, and the one
  * under it deepens. Cards are raised; one picked up floats at level 3, tilted, follows the pointer, and lands with a settle.
+ * @example
+ * ```tsx
+ * import { Board, BoardCard, BoardColumn, Field, Input } from 'altitude-design';
+ *
+ * <Board onMove={move} aria-label="Launch board">
+ *   {Object.keys(titles).map(k => <BoardColumn key={k} id={k} title={titles[k]} collapsible={k === "done"} defaultCollapsed={k === "done"} onCreate={k === "done" ? undefined : create(k)}>
+ *     {cols[k].map(c => <BoardCard key={c.id} id={c.id} label={c.t} heldBy={c.held} onRename={rename(k, c.id)}
+ *       {...(k === "review" ? { value: { title: c.t, meta: c.m }, onValueChange: update(k, c.id),
+ *         renderEditor: field => <><Field label="Title"><Input {...field("title")} size="sm" /></Field><Field label="Details"><Input {...field("meta")} size="sm" /></Field></>,
+ *         onSave: async draft => { await wait(200); return refuse(draft.title) || { ok: true, value: draft }; } } : {})}>
+ *       {c.t}<small>{c.m}</small>
+ *     </BoardCard>)}
+ *   </BoardColumn>)}
+ * </Board>
+ * ```
  */
 export declare const Board: React.ForwardRefExoticComponent<BoardProps & React.RefAttributes<HTMLDivElement>>;
 export interface BoardColumnProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {

package/dist/types/color-picker.d.ts

@@ -34,5 +34,11 @@ export interface ColorPickerProps {
  * A brand or label colour: swatches as choices (trenches the colour pours into, one travelling mark), and, if allowed,
  * a hex field that fills when it holds a whole colour and a full picker in a Popover. A contrast check says in words
  * whether text on the colour passes, because the accent carries text.
+ * @example
+ * ```tsx
+ * import { ColorPicker } from 'altitude-design';
+ *
+ * <ColorPicker label="Brand colour" value={color} onValueChange={setColor} swatches={brand} allowCustom checkContrast />
+ * ```
  */
 export declare function ColorPicker({ label, value, defaultValue, onValueChange, swatches, allowCustom, checkContrast, className }: ColorPickerProps): React.JSX.Element;

package/dist/types/command.d.ts

@@ -62,5 +62,18 @@ export declare function commandScore(text: string, query: string): number;
  * The summit: a level-5 search over everything you can do, opened with ⌘K or Ctrl+K. The page recedes behind it
  * as it does for Dialog. The query field is an opening built like Input; one highlight glides between results;
  * when results change, surviving rows travel to their new places and new ones rise in, a few at a time.
+ * @example
+ * ```tsx
+ * import { CommandPalette } from 'altitude-design';
+ *
+ * <CommandPalette
+ *   open={open}
+ *   onOpenChange={onOpenChange}
+ *   query={text}
+ *   onQueryChange={setText}
+ *   items={groups}
+ *   onSelect={(item) => setLast(item.label)}
+ * />
+ * ```
  */
 export declare function CommandPalette({ items, open, defaultOpen, onOpenChange, onSelect, placeholder, filter, empty, shortcut, query: queryProp, defaultQuery, onQueryChange, closeOnSelect, hints: hintsProp, className, ...rest }: CommandPaletteProps): React.JSX.Element | null;

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

@@ -44,5 +44,16 @@ export interface CommentThreadProps {
  * Comments on a record. Posted comments are the record, flush on the ground; the composer is an opening that fills; a
  * comment being posted hovers until it lands, or drops to a trench keeping its text. A resolved thread is stamped like a
  * done Checklist item: muted, collapsed to one line, kept in place. Mentions are a listbox at level 3.
+ * @example
+ * ```tsx
+ * import { CommentThread } from 'altitude-design';
+ *
+ * <CommentThread comments={comments} resolved={resolved ? { by: 'You' } : false} onPost={post}
+ *   onResolve={() => setResolved(true)} onReopen={() => setResolved(false)}
+ *   onRetry={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, status: undefined } : x)))}
+ *   onDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: true } : x)))}
+ *   onUndoDelete={(id) => setComments((xs) => xs.map((x) => (x.id === id ? { ...x, deleted: false } : x)))}
+ *   mentionable={(q) => people.filter((p) => p.name.toLowerCase().includes(q.toLowerCase()))} typing={resolved ? [] : ['Ada Obi']} />
+ * ```
  */
 export declare function CommentThread({ comments, resolved, onPost, onResolve, onReopen, onRetry, onDelete, onUndoDelete, mentionable, typing, 'aria-label': label, className }: CommentThreadProps): React.JSX.Element;

package/dist/types/confirmation.d.ts

@@ -56,5 +56,13 @@ export interface ConfirmationProps {
  * (Alert's raised rule), naming the consequence, with Approve and Reject. Nothing has been dispatched, so it mustn't
  * hover. Once approved it becomes a pending write (hovers), then lands or drops to a trench. Rejected and expired are
  * flush and muted, kept in the record.
+ * @example
+ * ```tsx
+ * import { Confirmation } from 'altitude-design';
+ *
+ * <Confirmation state={state} title={title} consequence={consequence} escalate={escalate} approveLabel={approveLabel} rejectLabel={rejectLabel}
+ * runningLabel={runningLabel} doneLabel={doneLabel} failedLabel={failedLabel} resolvedBy="you" resolvedAt={at} scopes={scopes} resolvedScope={scope}
+ * onApprove={approve} onReject={() => { setState('rejected'); setAt(new Date()); }} onRetry={() => { setState('running'); setTimeout(() => { setState('done'); setAt(new Date()); }, 1000); }} />
+ * ```
  */
 export declare function Confirmation({ state, title, consequence, details, approveLabel, rejectLabel, runningLabel, doneLabel, failedLabel, escalate, resolvedBy, resolvedAt, requestedBy, scopes, resolvedScope, edit, edited, onEditCancel, onApprove, onReject, onRetry, className }: ConfirmationProps): React.JSX.Element;

package/dist/types/context-menu.d.ts

@@ -13,5 +13,16 @@ export interface ContextMenuProps {
  * Actions on a thing, opened where you right-click or long-press it, or at it with Shift+F10 or the Menu key. The menu
  * is DropdownMenu's, at level 3; the thing shows it's the subject with a 2px accent-ink outline, never a height, so a
  * flush row doesn't lift out of its table. Every action here must also be reachable another way.
+ * @example
+ * ```tsx
+ * import { Button, ContextMenu, DropdownMenu, Icons } from 'altitude-design';
+ *
+ * <ContextMenu key={f} items={() => actions(f)}>
+ *   <div className="file" role="listitem" tabIndex={0}>
+ *     <span className="name">{f}</span><span className="meta">Edited 2 days ago</span>
+ *     <DropdownMenu align="end" items={actions(f)} trigger={<Button variant="ghost" size="sm" square aria-label={`Actions for ${f}`}><Icons.More /></Button>} />
+ *   </div>
+ * </ContextMenu>
+ * ```
  */
 export declare function ContextMenu({ items, children, 'aria-label': label, onOpenChange }: ContextMenuProps): React.JSX.Element;

package/dist/types/controls.d.ts

@@ -10,6 +10,14 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
     leading?: React.ReactNode;
     trailing?: React.ReactNode;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Button } from 'altitude-design';
+ *
+ * <Button variant="primary">Publish changes</Button>
+ * ```
+ */
 export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
 export interface CardProps extends React.HTMLAttributes<HTMLDivElement>, DepthProps {
     /** Lifts on hover and presses on click. Only set it when the whole card does something. */
@@ -21,6 +29,17 @@ export interface CardProps extends React.HTMLAttributes<HTMLDivElement>, DepthPr
      */
     skeleton?: SkeletonOption;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Card, CardContent, CardDescription, CardHeader, CardTitle } from 'altitude-design';
+ *
+ * <Card>
+ *   <CardHeader><CardTitle>Usage this month</CardTitle><CardDescription>Static: a grouping surface, it never lifts.</CardDescription></CardHeader>
+ *   <CardContent>18,240 requests · 62% of plan</CardContent>
+ * </Card>
+ * ```
+ */
 export declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;
 export declare const CardHeader: ({ className, ...p }: React.HTMLAttributes<HTMLDivElement>) => React.JSX.Element;
 /**
@@ -59,6 +78,14 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
     trailing?: React.ReactNode;
     size?: 'sm' | 'md';
 }
+/**
+ * @example
+ * ```tsx
+ * import { Input } from 'altitude-design';
+ *
+ * <Input type="email" placeholder="name@company.com" value={email} onChange={(e) => setEmail(e.target.value)} />
+ * ```
+ */
 export declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
 export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement>, SuggestionProps {
     invalid?: boolean;
@@ -76,6 +103,16 @@ export interface FieldProps {
     className?: string;
     children: React.ReactElement<any>;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Field, Input } from 'altitude-design';
+ *
+ * <Field label="Workspace name" hint="Shown to everyone you invite.">
+ *   <Input defaultValue="Northwind Studio" />
+ * </Field>
+ * ```
+ */
 export declare function Field({ label, hint, error, required, className, children }: FieldProps): React.JSX.Element;
 export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange'> {
     label?: React.ReactNode;
@@ -84,7 +121,14 @@ export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputE
     onCheckedChange?: (checked: boolean) => void;
     onChange?: React.ChangeEventHandler<HTMLInputElement>;
 }
-/** Built like the Switch and RadioGroup: an empty trench when off; checking pours the accent in and sets a raised white check on it. */
+/** Built like the Switch and RadioGroup: an empty trench when off; checking pours the accent in and sets a raised white check on it.
+ * @example
+ * ```tsx
+ * import { Checkbox } from 'altitude-design';
+ *
+ * <Checkbox label="Select all" checked={a && b} indeterminate={a !== b} onCheckedChange={(c) => { setA(c); setB(c); }} />
+ * ```
+ */
 export declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
 export interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
     value?: string;
@@ -94,7 +138,18 @@ export interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElemen
     disabled?: boolean;
     orientation?: 'vertical' | 'horizontal';
 }
-/** A switch with several positions: one raised thumb slides to the chosen option and the accent pours in behind it. */
+/** A switch with several positions: one raised thumb slides to the chosen option and the accent pours in behind it.
+ * @example
+ * ```tsx
+ * import { Radio, RadioGroup } from 'altitude-design';
+ *
+ * <RadioGroup defaultValue="team" aria-label="Plan">
+ *   <Radio value="solo" label="Solo" description="One seat, unlimited projects." />
+ *   <Radio value="team" label="Team" description="Up to 20 seats and shared libraries." />
+ *   <Radio value="org" label="Organization" disabled description="Talk to us." />
+ * </RadioGroup>
+ * ```
+ */
 export declare function RadioGroup({ value, defaultValue, onValueChange, name, disabled, orientation, className, children, ...rest }: RadioGroupProps): React.JSX.Element;
 export interface RadioProps {
     value: string;
@@ -110,6 +165,14 @@ export interface SwitchProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonE
     onCheckedChange?: (v: boolean) => void;
     label?: React.ReactNode;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Switch } from 'altitude-design';
+ *
+ * <Switch label="Sync across devices" defaultChecked />
+ * ```
+ */
 export declare function Switch({ checked, defaultChecked, onCheckedChange, label, className, disabled, ...rest }: SwitchProps): React.JSX.Element;
 export interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'defaultValue'> {
     value?: string;
@@ -121,6 +184,25 @@ export interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'd
      */
     variant?: 'folder' | 'segmented';
 }
+/**
+ * @example
+ * ```tsx
+ * import { Tabs, TabsContent, TabsList, TabsTrigger } from 'altitude-design';
+ *
+ * <Tabs defaultValue="overview">
+ *   <TabsList aria-label="Project">
+ *     <TabsTrigger value="overview">Overview</TabsTrigger>
+ *     <TabsTrigger value="activity">Activity</TabsTrigger>
+ *     <TabsTrigger value="settings">Settings</TabsTrigger>
+ *     <TabsTrigger value="members">Members</TabsTrigger>
+ *   </TabsList>
+ *   <TabsContent value="overview"><p className="body">Three deployments this week. Everything is healthy.</p></TabsContent>
+ *   <TabsContent value="activity"><p className="body">Mara merged “Faster cold starts” 2 hours ago.</p></TabsContent>
+ *   <TabsContent value="settings"><p className="body">Region, domains and environment variables.</p></TabsContent>
+ *   <TabsContent value="members"><p className="body">Six people have access to this project.</p></TabsContent>
+ * </Tabs>
+ * ```
+ */
 export declare function Tabs({ value, defaultValue, onValueChange, variant, className, children, ...rest }: TabsProps): React.JSX.Element;
 export declare function TabsList({ className, children, ...rest }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 export declare function TabsTrigger({ value, className, children, ...rest }: React.ButtonHTMLAttributes<HTMLButtonElement> & {
@@ -152,6 +234,14 @@ export interface SliderRangeProps extends Omit<SliderProps, 'value' | 'defaultVa
     /** A name per thumb, or one name for the pair (each thumb is then "<name>, minimum" and "<name>, maximum"). */
     'aria-label'?: string | [string, string];
 }
+/**
+ * @example
+ * ```tsx
+ * import { Slider } from 'altitude-design';
+ *
+ * <Slider value={v} onValueChange={setV} aria-label="Volume" format={(n) => n + '%'} />
+ * ```
+ */
 export declare function Slider(props: SliderProps): React.ReactElement;
 export declare function Slider(props: SliderRangeProps): React.ReactElement;
 /** Two values on one track: what the range Slider and ChartBrush share. A thumb can't cross the other or come within
@@ -185,6 +275,14 @@ export interface ProgressProps extends React.HTMLAttributes<HTMLDivElement> {
     max?: number;
     'aria-label'?: string;
 }
+/**
+ * @example
+ * ```tsx
+ * import { Progress } from 'altitude-design';
+ *
+ * <Progress value={v} aria-label="Upload" />
+ * ```
+ */
 export declare function Progress({ value, max, className, ...rest }: ProgressProps): React.JSX.Element;
 export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'> {
     tone?: 'neutral' | 'accent' | 'positive' | 'caution' | 'critical';
@@ -203,7 +301,14 @@ export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>,
     /** While the label is on its way: the imprint's `width` (default 64px; a count is round). `false`: render what you pass as it is, and let promises suspend to your own boundary. */
     skeleton?: SkeletonOption;
 }
-/** A label stamped into the record. Status carries a lamp that relights when it changes; a changed label is re-stamped. */
+/** A label stamped into the record. Status carries a lamp that relights when it changes; a changed label is re-stamped.
+ * @example
+ * ```tsx
+ * import { Badge } from 'altitude-design';
+ *
+ * <Badge lamp>Draft</Badge>
+ * ```
+ */
 export declare function Badge({ children, skeleton, ...props }: BadgeProps): React.JSX.Element;
 export interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
     /** The accessible label. Undefined while your data loads (`user?.name`), or a promise: until it arrives the avatar is an imprint of its size and shape. */
@@ -225,7 +330,14 @@ export interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
     /** `false`: no imprint. An undefined `name` renders an empty face; a promised one suspends to your own boundary. */
     skeleton?: boolean;
 }
-/** A disc resting on the page while the person is here, flush in it when they're not; live, it lifts off its shadow. */
+/** A disc resting on the page while the person is here, flush in it when they're not; live, it lifts off its shadow.
+ * @example
+ * ```tsx
+ * import { Avatar } from 'altitude-design';
+ *
+ * <Avatar name="Mara Quist" size={44} status="active" live presence={1} />
+ * ```
+ */
 export declare function Avatar({ skeleton, ...props }: AvatarProps): React.JSX.Element;
 export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Show at most this many faces; the rest become a "+N" plate that names them. */
@@ -245,7 +357,14 @@ export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
     height?: number | string;
     radius?: string;
 }
-/** An imprint of the content to come, pressed into the page; when the content arrives it rises out of its imprint. */
+/** An imprint of the content to come, pressed into the page; when the content arrives it rises out of its imprint.
+ * @example
+ * ```tsx
+ * import { Avatar, Skeleton } from 'altitude-design';
+ *
+ * <Skeleton loaded={loaded} shape="circle" width={44}><Avatar name="Mara Quist" size={44} status="active" /></Skeleton>
+ * ```
+ */
 export declare function Skeleton({ loaded, shape, lines, width, height, radius, className, style, children, ...rest }: SkeletonProps): React.JSX.Element;
 export interface AlertProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'>, Pick<DepthProps, 'settle'> {
     tone?: 'neutral' | 'accent' | 'positive' | 'caution' | 'critical';
@@ -263,7 +382,15 @@ export interface AlertProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     /** With placement="page": stays at the top while the page scrolls. */
     sticky?: boolean;
 }
-/** Status as a sheet laid on the page: it rests on the ground (you can see its edge and its contact shadow) and never floats. When it asks the person to act it becomes a raised card. */
+/** Status as a sheet laid on the page: it rests on the ground (you can see its edge and its contact shadow) and never floats. When it asks the person to act it becomes a raised card.
+ * @example
+ * ```tsx
+ * import { Alert, Button } from 'altitude-design';
+ *
+ * <Alert placement="page" tone="caution" variant="raised" title="Your trial ends in 3 days" action={<Button variant="primary" size="sm">Choose a plan</Button>}
+ * onDismiss={() => setTrial(false)} dismissLabel="Remind me tomorrow" />
+ * ```
+ */
 export declare function Alert({ tone, variant, title, action, icon, onDismiss, dismissLabel, placement, sticky, settle, className, style, children, ...rest }: AlertProps): React.JSX.Element;
 export interface AlertStackProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Alert elements, most important first. Give each a key. */
@@ -293,6 +420,14 @@ export interface AccordionProps extends Omit<React.HTMLAttributes<HTMLDivElement
     type?: 'single' | 'multiple';
     defaultValue?: string[];
 }
+/**
+ * @example
+ * ```tsx
+ * import { Accordion } from 'altitude-design';
+ *
+ * <Accordion items={items} defaultValue={['b']} />
+ * ```
+ */
 export declare function Accordion({ items, type, defaultValue, className, ...rest }: AccordionProps): React.JSX.Element;
 export interface HoldButtonProps extends Omit<ButtonProps, 'loading'> {
     /** Called once the button has been held for `duration`. */
@@ -307,7 +442,14 @@ export interface HoldButtonProps extends Omit<ButtonProps, 'loading'> {
      */
     repeatable?: boolean;
 }
-/** Commitment as depth: holding pushes the button down through the ground into a trench. Let go early and it springs back. */
+/** Commitment as depth: holding pushes the button down through the ground into a trench. Let go early and it springs back.
+ * @example
+ * ```tsx
+ * import { HoldButton } from 'altitude-design';
+ *
+ * <HoldButton onConfirm={() => {}} holdingLabel="Keep holding…" doneLabel="Project deleted">Hold to delete</HoldButton>
+ * ```
+ */
 export declare function HoldButton({ onConfirm, duration, variant, holdingLabel, doneLabel, repeatable, className, children, style, disabled, onClick, ...rest }: HoldButtonProps): React.JSX.Element;
 export interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
     /** A header that sits flush at the top and rises once content scrolls beneath it. */
@@ -315,7 +457,14 @@ export interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
     maxHeight?: number | string;
     'aria-label'?: string;
 }
-/** Overflow as depth: where content continues past an edge, the edge curves away (an inner lip); content passing under the header lifts it. */
+/** Overflow as depth: where content continues past an edge, the edge curves away (an inner lip); content passing under the header lifts it.
+ * @example
+ * ```tsx
+ * import { ScrollArea } from 'altitude-design';
+ *
+ * <ScrollArea maxHeight={240} aria-label="Invoices">{rows.map(([a, b]) => <div className="item" key={a}>{a}<span>{b}</span></div>)}</ScrollArea>
+ * ```
+ */
 export declare function ScrollArea({ header, maxHeight, className, children, ...rest }: ScrollAreaProps): React.JSX.Element;
 export interface DropZoneProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onDrop'> {
     onFiles?: (files: File[]) => void;
@@ -340,7 +489,14 @@ export interface UploadItem {
     /** Why it failed, in words. */
     error?: string;
 }
-/** Receptacles open when they're needed: a drop zone is flush until a file is dragged anywhere on the page, then sinks open; over it, it deepens. */
+/** Receptacles open when they're needed: a drop zone is flush until a file is dragged anywhere on the page, then sinks open; over it, it deepens.
+ * @example
+ * ```tsx
+ * import { DropZone } from 'altitude-design';
+ *
+ * <DropZone state="idle"><Body /></DropZone>
+ * ```
+ */
 export declare function DropZone({ onFiles, accept, multiple, state, queue, onRetry, onCancel, onRemove, className, children, ...rest }: DropZoneProps): React.JSX.Element;
 export interface SortableListProps<T> {
     items: T[];
@@ -355,6 +511,14 @@ export interface SortableListProps<T> {
     className?: string;
     'aria-label'?: string;
 }
-/** Possession as depth: the item you pick up comes into your hand (level 3), the slot it will land in opens as a well, and it lands with a settle. */
+/** Possession as depth: the item you pick up comes into your hand (level 3), the slot it will land in opens as a well, and it lands with a settle.
+ * @example
+ * ```tsx
+ * import { Badge, SortableList } from 'altitude-design';
+ *
+ * <SortableList aria-label="Priorities" items={items} getKey={(i) => i.id} getLabel={(i) => i.t} onReorder={setItems}
+ *   renderItem={(i) => <div className="it">{i.t}<Badge tone={i.p === 'High' ? 'critical' : i.p === 'Med' ? 'caution' : 'neutral'}>{i.p}</Badge></div>} />
+ * ```
+ */
 export declare function SortableList<T>({ items, getKey, onReorder, renderItem, getLabel, gap, className, ...rest }: SortableListProps<T>): React.JSX.Element;
 export {};

package/dist/types/conversation.d.ts

@@ -6,6 +6,27 @@ export interface ConversationProps extends React.HTMLAttributes<HTMLDivElement>
  * The thread between a person and an assistant. Settled messages are the record. It follows new text to the bottom
  * until the person scrolls up, then offers "Jump to latest". A streamed answer is announced once, when it completes,
  * never token by token.
+ * @example
+ * ```tsx
+ * import { Conversation, ConversationCheckpoint, ConversationContent, ConversationScrollButton, Message, MessageActions, MessageAttachments, MessageContent } from 'altitude-design';
+ *
+ * <Conversation aria-label="Assistant">
+ *   <ConversationContent>
+ *     {msgs.map((m) => m.kind === 'checkpoint' ? (
+ *       <ConversationCheckpoint key={m.id} label={m.label} at={m.at} onRestore={() => restore(m.id)} onReturn={giveBack}
+ *         consequence="The messages after this will be set aside. You can return to them." />
+ *     ) : (
+ *       <Message key={m.id} from={m.from} status={m.status} edited={m.v > 0} onRetry={m.status === 'stopped' ? () => { setStatus('streaming'); stream(m.id); } : undefined}>
+ *         {m.files && <MessageAttachments items={m.files} />}
+ *         <MessageContent>{m.text}</MessageContent>
+ *         {m.from === 'assistant' ? <MessageActions onCopy onRegenerate={() => {}} onFeedback={() => {}} />
+ *           : <MessageActions onEdit={(t) => edit(m.id, t)} versions={m.versions && { index: m.v + 1, total: m.versions.length, onChange: (k) => showVersion(m.id, k - 1) }} />}
+ *       </Message>
+ *     ))}
+ *   </ConversationContent>
+ *   <ConversationScrollButton />
+ * </Conversation>
+ * ```
  */
 export declare function Conversation({ className, children, 'aria-label': label, ...rest }: ConversationProps): React.JSX.Element;
 /** The messages, in order. */

package/dist/types/copy-button.d.ts

@@ -15,5 +15,11 @@ export interface CopyButtonProps extends Omit<ButtonProps, 'value' | 'onCopy' |
 /**
  * Copies a value and says so in words: pressed to the ground with a check and "Copied" for dur-linger, announced
  * politely while the button keeps its name. No rise and no afterglow: nothing new arrived on the page.
+ * @example
+ * ```tsx
+ * import { CopyButton } from 'altitude-design';
+ *
+ * <CopyButton size="sm" value="sk_live_51Hc8x2Lw9Qe7TfR4mNpZa" label="Copy API key" />
+ * ```
  */
 export declare const CopyButton: React.ForwardRefExoticComponent<CopyButtonProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/types/core.d.ts

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

@@ -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;