altitude-design 0.2.0 → 0.3.0

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

@@ -0,0 +1,256 @@
+import * as React from 'react';
+/** useLayoutEffect in the browser, useEffect on the server, where layout effects can't run (React 18 warns about them). */
+export declare const useIsoLayoutEffect: typeof React.useEffect;
+export declare const cx: (...parts: Array<string | false | null | undefined>) => string;
+/** A duration token in milliseconds. Minifiers rewrite `220ms` as `.22s`, so the unit is read, not assumed. */
+export declare const cssMs: (cs: CSSStyleDeclaration | null | undefined, name: string, fallback: number) => number;
+/**
+ * Mount/unmount with an exit animation. Returns `mounted` (render or not) and
+ * `state` ("open" | "closed") for the data-state attribute. The element first
+ * renders in its closed pose, then flips to open two frames later so CSS
+ * transitions run; on close it stays mounted for `exitMs`.
+ */
+export declare function usePresence(open: boolean, exitMs: number): {
+    mounted: boolean;
+    state: "open" | "closed";
+};
+export declare function useControllable<T>(value: T | undefined, defaultValue: T, onChange?: (v: T) => void): readonly [T, (v: T) => void];
+export declare function useOutside(ref: React.RefObject<HTMLElement | null>, active: boolean, onOutside: () => void): void;
+/** Spread on an element to make it inert. React 18 passes unknown attributes through as strings and needs ''; React 19
+ * knows `inert` as a boolean and treats '' as false. */
+export declare const inert: React.HTMLAttributes<HTMLElement>;
+export declare function useKeyFocus(): void;
+/** Keeps the shared approach tracker running while any component that reacts to it is mounted. */
+export declare function useApproach(enabled?: boolean): void;
+type IconProps = React.SVGProps<SVGSVGElement> & {
+    size?: number;
+};
+export declare const Icons: {
+    Check: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    ChevronDown: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    X: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Info: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Pencil: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    CircleCheck: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    AlertCircle: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Copy: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    ArrowUp: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Stop: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Paperclip: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    ThumbsUp: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    ThumbsDown: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Refresh: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    ArrowDown: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Spark: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Lock: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Pin: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Bell: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Eye: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    EyeOff: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    Clock: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    PanelLeft: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    More: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    ExternalLink: ({ size, ...rest }: IconProps) => React.JSX.Element;
+    AlertTriangle: ({ size, ...rest }: IconProps) => React.JSX.Element;
+};
+export declare function Spinner({ size }: {
+    size?: number;
+}): React.JSX.Element;
+export declare const contrast: (a: string, b: string) => number;
+/**
+ * Derive the four accent tokens from one brand colour, against the surfaces of
+ * the active scheme: `accent` (as given), `on-accent` (white or ink, whichever
+ * reads at 4.5:1), `accent-ink` (nudged toward ink until it reads at 4.5:1 on
+ * every surface passed) and `accent-soft` (a tint of the ground).
+ */
+export declare function deriveAccent(accent: string, surfaces: string[]): React.CSSProperties;
+declare const SURFACES: readonly ["surface-trench", "surface-well", "surface-ground", "surface-raised", "surface-lifted", "surface-floating", "surface-overlay", "surface-modal"];
+export type SchemeColorToken = typeof SURFACES[number] | 'ink' | 'ink-muted' | 'ink-faint' | 'line' | 'line-control' | 'accent' | 'on-accent' | 'accent-ink' | 'accent-soft' | 'positive' | 'positive-soft' | 'caution' | 'caution-soft' | 'critical' | 'critical-soft' | 'on-critical' | 'presence-1' | 'presence-2' | 'presence-3' | 'on-presence' | 'scrim' | DataColorToken;
+/** The data palette (charts only): categorical slots, the fold, the magnitude ramp and the diverging ramp. */
+export type DataColorToken = `data-${1 | 2 | 3 | 4 | 5 | 6}` | 'data-other' | `data-seq-${1 | 2 | 3 | 4 | 5 | 6 | 7}` | `data-div-${'neg' | 'pos'}-${1 | 2 | 3}` | 'data-div-mid';
+export type SchemeShadowToken = 'trench' | 'well' | 'elev-0' | 'elev-1' | 'elev-2' | 'elev-3' | 'elev-4' | 'elev-5' | 'lip-top' | 'lip-bottom';
+/** Which invariants checkScheme measures: `core` is the surface ladder and contrast, `data` the data palette's gates. */
+export type SchemeCheck = 'core' | 'data';
+/**
+ * Check a scheme against the invariants every scheme keeps: the surfaces climb in lightness (trench < well < ground
+ * < raised ≤ … ≤ modal) and text, control edges and presence colours hold their contrast on every surface. Pass the
+ * colour tokens by name (without `--`), or an element to read them from. Returns one sentence per problem; [] passes.
+ * Only hex values can be measured; any other value of a checked token is reported.
+ *
+ * `include` picks the checks; it defaults to `['core']`. Add `'data'` for the data palette's gates (Theming.md, "The
+ * data palette"): lightness band and chroma, colour-blind and normal-vision separation, 3:1 on ground and raised,
+ * distance from the accent, status and presence hues, and monotone ramps.
+ */
+export declare function checkScheme(colors: Partial<Record<SchemeColorToken, string>> | Element, options?: {
+    include?: SchemeCheck[];
+}): string[];
+export interface CustomScheme {
+    /** Stamped as data-scheme on the provider's root. */
+    name: string;
+    /** The built-in scheme your tokens are laid over: any token you leave out comes from it, and so does light or dark
+     *  handling (casts, rims, walls). Use nightfall for a dark scheme. Default 'daylight'. */
+    base?: BuiltInScheme | RetiredScheme;
+    /** Colour and shadow tokens by name, without `--`. */
+    tokens: Partial<Record<SchemeColorToken | SchemeShadowToken, string>>;
+}
+export type BuiltInScheme = 'daylight' | 'nightfall';
+/** @deprecated Mesa and Alpine were retired because they matched generated-UI palette defaults (#324). They resolve
+ *  to daylight and nightfall, with a warning in development. */
+export type RetiredScheme = 'mesa' | 'alpine';
+/** A built-in scheme, the name of your own [data-theme="…"] block, or a CustomScheme. */
+export type Scheme = BuiltInScheme | (string & {});
+/** The nearest theme's portal host. Modal ownership stays private. */
+export declare const useAltitude: () => {
+    host: HTMLElement | null;
+    /** @deprecated Internal visual-only compatibility helper; use Dialog or Sheet for modal behavior. */
+    pushLayer: () => () => void;
+} | null;
+export interface AltitudeProviderProps extends React.HTMLAttributes<HTMLDivElement> {
+    scheme?: Scheme | CustomScheme;
+    accent?: string;
+    motion?: 'system' | 'full' | 'reduced';
+    /** 'more' renders elevation as hard, high-contrast slabs (offset = height). 'system' follows prefers-contrast. */
+    contrast?: 'system' | 'more';
+    /**
+     * How large controls are (#245). 'auto' (default): today's sizes for a mouse, a step up under a coarse pointer (a
+     * finger), so they're big enough to hit. 'comfortable': the larger sizes everywhere (a kiosk, an accessibility
+     * setting). 'compact': today's sizes even on touch. Hit areas reach 44px under a coarse pointer either way.
+     */
+    density?: 'auto' | 'compact' | 'comfortable';
+    recede?: boolean;
+    /** Openings deepen as the pointer approaches (empty fields, a sheet's finger pull). Default true; reduced motion turns it off regardless. */
+    approach?: boolean;
+    /**
+     * How content that's still on its way waits (#343). 'sweep' (default): light passes over each imprint. 'breath'
+     * (experimental): imprints breathe in depth on one page clock, a swell crossing the view top to bottom; content that
+     * rests raised (`Await settle="raised"`) rises a level past its rest and settles, flush content fills past the ground,
+     * and a card's parts land together. Set it on the outer provider: nested providers inherit it and can't turn it off.
+     */
+    loading?: 'sweep' | 'breath';
+    /**
+     * The whole app is in a mode people must never mistake for the normal app: test mode, viewing as a customer,
+     * read-only, a preview. Height can't say "this whole ground is different", so it's said in words and a border: a
+     * flush strip naming the mode at the top, a 2px frame around the viewport, and a plate in every Dialog and Sheet.
+     */
+    mode?: AppMode;
+    /**
+     * Development checks: warns when more than one primary Button is visible in one view (law 1). Each Dialog, Sheet and
+     * Popover is its own view, and <PrimaryScope> makes another. Default: on when process.env.NODE_ENV isn't 'production'.
+     */
+    devChecks?: boolean;
+}
+export interface AppMode {
+    label: string;
+    description?: React.ReactNode;
+    /** Default 'caution'. */
+    tone?: 'caution' | 'accent' | 'critical' | 'neutral';
+    /** A way out ("Leave test mode"). The strip can't be dismissed. */
+    action?: React.ReactNode;
+}
+/** Opens a scope of its own for the one-primary check: an independent card on a dashboard, a dialog. */
+export declare function PrimaryScope({ name, children }: {
+    name?: string;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Button variant="primary" registers itself with the nearest scope while it's mounted. */
+export declare function usePrimaryRegistration(el: React.RefObject<HTMLElement | null>, primary: boolean): void;
+/** The provider's loading style, for the parts of loading that aren't only CSS (RevealGroup's budget, Card's grouping). */
+export declare const LoadingStyleContext: React.Context<"sweep" | "breath">;
+/** The app's mode, for Dialog and Sheet to name it in their headers. */
+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;
+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 }: {
+    children: React.ReactNode;
+}): React.ReactPortal | null;
+export declare function riseDelay(): number;
+/**
+ * Breath (loading="breath"): an imprint takes its phase from one page clock, lagged by how far down the view it sits,
+ * so imprints change in step (one moving thing, not many) and a slow swell of depth crosses the view. Ten seconds in,
+ * it calms. Returns a ref for the element whose imprints breathe; does nothing under the sweep.
+ */
+export declare function useBreath<T extends HTMLElement>(): (el: T | null) => void;
+export type Presence = 1 | 2 | 3;
+export interface DepthProps {
+    /** Afterglow. Any value: when it changes the surface lifts, tints and settles back over dur-settle. `true` settles once on mount. */
+    settle?: unknown;
+    /** Commit state of an optimistic write. pending hovers above the ground (after dur-grace), committed lands, failed drops into a trench. */
+    status?: 'pending' | 'committed' | 'failed';
+    /** Someone is holding this: lifted to level 3 with their presence colour and name. */
+    heldBy?: {
+        name: string;
+        presence?: Presence;
+    } | null;
+    /** Focus+context. match rises one level, miss sinks into a well; nothing is removed. */
+    relevance?: 'match' | 'miss';
+}
+/** Turns depth signals into the data attributes bundle.css reads. Spread the result onto any surface. */
+export declare function useDepth({ settle, status, heldBy, relevance }: DepthProps): {
+    'data-settle': "a" | "b" | undefined;
+    'data-land': "a" | "b" | undefined;
+    'data-status': "pending" | "committed" | "failed" | undefined;
+    'data-held': string | undefined;
+    'data-held-by': string | undefined;
+    'data-presence': string | undefined;
+    'data-relevance': "match" | "miss" | undefined;
+    'aria-busy': true | undefined;
+    style: React.CSSProperties | undefined;
+};
+export type Level = -2 | -1 | 0 | 1 | 2 | 3 | 4 | 5;
+export interface SurfaceProps extends React.HTMLAttributes<HTMLElement>, DepthProps {
+    level?: Level;
+    interactive?: boolean;
+    disabled?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    href?: string;
+    as?: keyof React.JSX.IntrinsicElements;
+}
+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
+ * opens, and when the window resizes, it's measured and shifted sideways so it stays 8px clear of the screen's edges,
+ * on top of whatever translate its own placement uses. Its CSS caps its width at the viewport's.
+ */
+export declare function useFitFloating(ref: React.RefObject<HTMLElement | null>, open: boolean): void;
+/** How a menu or list presents itself (#249): anchored to its trigger, or as a sheet at the bottom edge. */
+export type Presentation = 'auto' | 'anchored' | 'sheet';
+/**
+ * Whether a menu or list opens as a bottom sheet: always for 'sheet', never for 'anchored', and for 'auto' on a narrow
+ * touch screen (under breakpoint-compact, with a coarse pointer), where the thumb is at the bottom of the screen.
+ */
+export declare function useSheetPresentation(presentation?: Presentation): boolean;
+/** A sheet-presented menu's head: its title, and a way to close it that doesn't need a tap outside. */
+export declare function SheetHead({ title, onClose }: {
+    title?: React.ReactNode;
+    onClose: () => void;
+}): React.JSX.Element;
+/**
+ * Touch drags start on press-and-hold, so a swipe still scrolls (#254–#256). Call on a touch pointerdown: after
+ * HOLD_MS without moving more than 8px it calls onHold, and from then until the finger lifts the browser isn't
+ * allowed to pan (the first touchmove is cancelled) or open a long-press menu. Moving first gives the gesture to the
+ * browser. Returns a function that abandons the hold.
+ */
+export declare const HOLD_MS = 400;
+export declare function touchHold(e: {
+    clientX: number;
+    clientY: number;
+    pointerId: number;
+}, onHold: () => void): () => void;
+/**
+ * Whether the person likely has a keyboard: false on a touch-only device (no hover, a coarse pointer) until a key is
+ * pressed in the session, true otherwise. Components hide shortcut hints when it's false; the shortcuts still work.
+ */
+export declare function useKeyboardLikely(): boolean;
+export interface KbdProps extends React.HTMLAttributes<HTMLElement> {
+    /** A KeyboardEvent.key (case-insensitive) — the key presses down while it is held. */
+    listen?: string;
+    /**
+     * Hide it on a touch-only device until a key is pressed (#262): for a hint that only makes sense with a keyboard.
+     * Off by default, since an app may be documenting its shortcuts on purpose. Components' own hints do this already.
+     */
+    hideOnTouch?: boolean;
+}
+export declare function Kbd({ listen, hideOnTouch, className, children, ...rest }: KbdProps): React.JSX.Element | null;
+export {};

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

@@ -0,0 +1,76 @@
+import * as React from 'react';
+export type DataGridResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export interface DataGridChange<T> {
+    rowId: string;
+    key: string;
+    draft: unknown;
+    previousValue: unknown;
+    row: T;
+}
+/** What a column's custom editor receives. Spread it onto a Select or Combobox. */
+export interface DataGridEditorControl {
+    value: any;
+    onValueChange: (value: any) => void;
+    id: string;
+    'aria-label': string;
+    invalid: boolean;
+    autoFocus: true;
+}
+export interface DataGridColumn<T> {
+    key: string;
+    header: React.ReactNode;
+    /** The header as words, for cell names. Default: the header when it's a string, else the key. */
+    label?: string;
+    align?: 'start' | 'end';
+    editable?: boolean;
+    /** Text typed into the cell → the value. Default: the text. */
+    parse?: (text: string) => unknown;
+    /** The value → text in the editing field and in copies. Default: String(value ?? ''). */
+    format?: (value: unknown) => string;
+    /** Return an error to refuse a value. */
+    validate?: (value: any, row: T) => string | undefined;
+    /** Draw the cell at rest. Default: format(value). */
+    cell?: (row: T) => React.ReactNode;
+    /** A custom editor (a Select): it commits as soon as a value is chosen. */
+    editor?: (control: DataGridEditorControl) => React.ReactNode;
+    width?: number | string;
+    /**
+     * The narrowest the column gets (#260): on a phone the table scrolls inside its frame rather than squeezing a column
+     * below this. Default: the header's width, and at least 6rem when the table is narrow.
+     */
+    minWidth?: number | string;
+    /** Keep this column in view while the table scrolls sideways, over a flush 1px edge (no shadow: it isn't live). */
+    sticky?: boolean;
+}
+export interface DataGridProps<T> {
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    rows: T[];
+    columns: DataGridColumn<T>[];
+    getRowId: (row: T) => string;
+    /** Names a row in each cell's name (“Price, Desk lamp”). */
+    getRowLabel: (row: T) => string;
+    /** One cell. Resolve after `rows` carries the canonical value. */
+    onCellSave: (change: DataGridChange<T>) => DataGridResult | Promise<DataGridResult>;
+    /** A paste or a cleared range, as one batch. Default: each cell through onCellSave. */
+    onCellsSave?: (changes: DataGridChange<T>[]) => DataGridResult | Promise<DataGridResult>;
+    /** Ctrl/Cmd+Z: reverse the last committed change (or batch). Omit and Ctrl+Z does nothing. */
+    onUndo?: (last: DataGridChange<T>[]) => void;
+    /** Check every cell against its column's `validate` at rest, not only while it's edited: an invalid value lies in a
+     * trench on critical-soft, with its problem in the cell's description. For data that arrived from elsewhere (an import). */
+    showInvalid?: boolean;
+    maxHeight?: number | string;
+    className?: string;
+}
+/**
+ * A table you edit cell by cell, with spreadsheet keys. Cells are the record, flush in their rows. The cell being
+ * 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.
+ */
+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

@@ -0,0 +1,96 @@
+import * as React from 'react';
+export type ISODate = string;
+export interface DateRange {
+    start: ISODate | null;
+    end: ISODate | null;
+}
+/**
+ * A named span for DateRangePicker: a fixed range, or a function of today, so "Last 7 days" stays relative and
+ * re-resolves when today changes. `key` defaults to the label.
+ */
+export interface DatePreset {
+    key?: string;
+    label: string;
+    range: DateRange | ((today: ISODate) => DateRange);
+}
+/** Ready-made relative presets. Each is a function, so labels and spans can be adjusted: `datePresets.lastDays(14)`. */
+export declare const datePresets: {
+    today: () => DatePreset;
+    yesterday: () => DatePreset;
+    /** The last n days, today included: lastDays(7) on 27 Oct is 21–27 Oct. */
+    lastDays: (n: number) => DatePreset;
+    thisMonth: () => DatePreset;
+    lastMonth: () => DatePreset;
+    thisQuarter: () => DatePreset;
+    lastQuarter: () => DatePreset;
+    thisYear: () => DatePreset;
+};
+export interface CalendarProps {
+    value?: ISODate | null;
+    defaultValue?: ISODate | null;
+    onValueChange?: (value: ISODate) => void;
+    /** Earliest and latest days that can be chosen. */
+    min?: ISODate;
+    max?: ISODate;
+    isUnavailable?: (date: ISODate) => boolean;
+    /** Default: the browser's. */
+    locale?: string;
+    /** 0 Sunday … 6 Saturday. Default: the locale's. */
+    weekStartsOn?: number;
+    'aria-label'?: string;
+    className?: string;
+}
+/** A month calendar laid on the page (level 0): no field, no panel. */
+export declare function Calendar({ value, defaultValue, onValueChange, min, max, isUnavailable, locale, weekStartsOn, className, ...aria }: CalendarProps): React.JSX.Element;
+interface PickerBase {
+    min?: ISODate;
+    max?: ISODate;
+    isUnavailable?: (date: ISODate) => boolean;
+    locale?: string;
+    weekStartsOn?: number;
+    /** Goes on the first segment; Field sets it so its label points here. */
+    id?: string;
+    name?: string;
+    disabled?: boolean;
+    required?: boolean;
+    /** Field sets it for you when it has an error. */
+    invalid?: boolean;
+    size?: 'sm' | 'md';
+    className?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+    /** Start with the calendar open (for documentation). */
+    defaultOpen?: boolean;
+}
+export interface DatePickerProps extends PickerBase {
+    value?: ISODate | null;
+    defaultValue?: ISODate | null;
+    /** Called with a complete, real, allowed date, or null when the field is cleared. */
+    onValueChange?: (value: ISODate | null) => void;
+}
+export interface DateRangePickerProps extends PickerBase {
+    value?: DateRange;
+    defaultValue?: DateRange;
+    onValueChange?: (value: DateRange) => void;
+    /**
+     * Named spans offered beside the calendar ("Last 7 days", "This quarter"): build them with `datePresets`, or pass
+     * `{ label, range }`. Choosing one fills the field with its name and dates; typing or picking days clears it.
+     */
+    presets?: DatePreset[];
+    /** The chosen preset's key, controlled; null when the range is custom. */
+    preset?: string | null;
+    /** The preset to start with, uncontrolled. Without a `defaultValue`, the range starts as this preset's. */
+    defaultPreset?: string | null;
+    onPresetChange?: (preset: string | null) => void;
+    /** Today, as an ISO date: relative presets resolve against it, and re-resolve when it changes. Default: the local date. */
+    today?: ISODate;
+}
+/**
+ * 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.
+ */
+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. */
+export declare function DateRangePicker({ value, defaultValue, onValueChange, min, max, isUnavailable, locale, weekStartsOn, id, name, disabled, required, invalid, size, className, defaultOpen, presets, preset: presetProp, defaultPreset, onPresetChange, today: todayProp, ...aria }: DateRangePickerProps): React.JSX.Element;
+export {};

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

@@ -0,0 +1,54 @@
+import * as React from 'react';
+type Op = {
+    kind: 'same' | 'add' | 'del';
+    text: string;
+};
+/** Line operations for two texts. */
+export declare function diffLines(before: string, after: string): Op[];
+export interface DiffField {
+    key: string;
+    label: string;
+    format?: (value: unknown) => React.ReactNode;
+}
+export interface DiffViewProps {
+    /** 'text' (default): lines of two texts. 'properties': fields of two records. */
+    mode?: 'text' | 'properties';
+    before: string | Record<string, unknown>;
+    after: string | Record<string, unknown>;
+    /** For mode="properties": which fields, labelled. Default every key that changed. */
+    fields?: DiffField[];
+    /** Unchanged lines kept around each change; longer runs fold behind a lid. Default 3. */
+    context?: number;
+    /** What's being compared ("Version 4 → 5"). */
+    caption?: React.ReactNode;
+    /** Precomputed line operations, for large inputs. */
+    hunks?: Op[];
+    /**
+     * Review each change (#282, text mode): a change awaiting a decision is a proposal, so it's raised, with Accept and
+     * Reject; once decided it's the record again (accepted flush with one afterglow, rejected collapsed to a line). The
+     * header gets Accept all, Reject all and "3 of 7 changes reviewed"; n and p (or ] and [) move between undecided ones.
+     */
+    review?: boolean;
+    /** Decisions so far, by change id ("change-1", in order). Your app owns applying them. */
+    decisions?: Record<string, DiffDecision>;
+    onDecide?: (changeId: string, decision: DiffDecision) => void;
+    onDecideAll?: (decision: DiffDecision) => void;
+    className?: string;
+}
+export type DiffDecision = 'accept' | 'reject';
+type Change = {
+    id: string;
+    n: number;
+    from: number;
+    to: number;
+    label: string;
+};
+/** The changes in a list of line operations: each maximal run of removals and additions, with its lines named. */
+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.
+ */
+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

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { type ChartConfig, type ChartDatum, type ChartInfo } from './chart.cjs';
+export interface DotPlotProps {
+    /** The records: one per category. undefined or a promise while they load; null or [] when there are none. */
+    data: ChartDatum[] | null | undefined | PromiseLike<ChartDatum[] | null>;
+    /** What the plot says when there's no data. */
+    empty?: import('./chart.cjs').ChartEmpty;
+    /** The key of each record's category, down the side. */
+    x: string;
+    /** Order the categories by value ('desc': the largest first): the first series', or `to`'s. Default: the data's order. */
+    sort?: 'asc' | 'desc';
+    /**
+     * A spread around each value, as the keys of its low and high ("p10", "p90"): a flat band of the series colour at 16%
+     * behind the dot. It joins the axis, the readout, each point's name and the table. Never error bars.
+     */
+    range?: [string, string];
+    /** What the spread is, in words. Default "Range". */
+    rangeLabel?: string;
+    /** The series the spread belongs to. Default the first. */
+    rangeSeries?: string;
+    /**
+     * Before and after per category (a dumbbell): the keys of the earlier and later values. The earlier dot is hollow, the
+     * later filled, joined by a 2px ink-muted link, and the change is said in words ("Up 14% from Q2").
+     */
+    from?: string;
+    to?: string;
+    /** Force zero onto the axis. Default false: a dot plot is for values where zero isn't part of the story. */
+    zero?: boolean;
+    /** Filter in place: which records match. Misses recede to 35%, keeping their place and colour. */
+    relevance?: (d: ChartDatum) => 'match' | 'miss' | undefined;
+    /** Fit the axis to the matches rather than holding it. */
+    rescale?: boolean;
+    /** Marks you can select: the selected record's category, and what to do when one is chosen (null clears). */
+    selected?: unknown;
+    onSelect?: (d: ChartDatum | null) => void;
+    /** Marks you drill into: the id of the current Drilldown node's child that a record opens. */
+    drill?: (d: ChartDatum) => string | null | undefined;
+    /** The crosshair and readout. Default true. */
+    tooltip?: boolean;
+    /** Series keys that keep their colours while the rest take data-context (#188). */
+    focus?: string[];
+    children?: React.ReactNode;
+}
+/**
+ * Values compared across categories where zero isn't part of the story (ten services' p95, all between 180 and 240ms),
+ * or averages with their spread, or before and after per category. The values are the record, so the dots lie flat on
+ * 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.
+ */
+export declare function DotPlot(props: DotPlotProps): React.JSX.Element | null;
+export declare namespace DotPlot {
+    var chartInfo: (props: Record<string, unknown>, config: ChartConfig) => ChartInfo;
+}

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

@@ -0,0 +1,121 @@
+import * as React from 'react';
+type Fields<T> = Partial<Record<keyof T, string>>;
+export type EditRegionSaveResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+    fieldErrors?: Fields<T>;
+};
+export interface EditRegionProps<T extends Record<string, unknown>> {
+    /** Names the region: “Edit <label>”. */
+    label: string;
+    /** The committed record. */
+    value: T;
+    /** Publishes the accepted canonical record, synchronously and without a network write. */
+    onValueChange: (canonical: T) => void;
+    /** The sole write. `changed` lists only the fields that differ, so you can send a patch. */
+    onSave: (draft: T, context: {
+        previousValue: T;
+        changed: (keyof T)[];
+    }) => EditRegionSaveResult<T> | Promise<EditRegionSaveResult<T>>;
+    /** Runs on Save. Return an error per field, or undefined. */
+    validate?: (draft: T) => Fields<T> | undefined | Promise<Fields<T> | undefined>;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    disabled?: boolean;
+    /** The field focused on opening. Default: the first control in the form. */
+    initialFocus?: keyof T;
+    /** Used only when completion still owns focus and the Edit button cannot receive it. */
+    focusFallback?: () => HTMLElement | null;
+    /** Compares one field's values. Default Object.is. */
+    isEqual?: (a: unknown, b: unknown) => boolean;
+    editLabel?: string;
+    saveLabel?: string;
+    cancelLabel?: string;
+    /** How long the region's afterglow takes to fade after a save, in ms. Default 5000. */
+    settleDuration?: number;
+    /**
+     * 'form' (default): editing opens a form laid out your way. 'in-place': each value's well opens where its text is: mark
+     * read values with EditRegionValue, and lay the fields out where the values were. Controls take the value's font and
+     * reach 13px past their column on each side (the inset their text sits at), so leave 26px between columns.
+     */
+    layout?: 'form' | 'in-place';
+    className?: string;
+    /** EditRegionView and EditRegionForm. */
+    children: React.ReactNode;
+}
+/** Binds one field of the draft to a control. Spread the result onto it. */
+export interface EditRegionBinder<T> {
+    /** Text controls (Input, Textarea): value + onChange. */
+    <K extends keyof T>(key: K): {
+        name: string;
+        value: T[K];
+        onChange: (event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+        readOnly: boolean;
+        disabled?: boolean;
+        'data-field': string;
+    };
+    /** Value controls (Select, Combobox, Slider): value + onValueChange. */
+    value<K extends keyof T>(key: K): {
+        name: string;
+        value: T[K];
+        onValueChange: (value: T[K]) => void;
+        disabled?: boolean;
+        'data-field': string;
+    };
+    /** Toggles (Switch, Checkbox): checked + onCheckedChange. */
+    checked<K extends keyof T>(key: K): {
+        checked: boolean;
+        onCheckedChange: (checked: boolean) => void;
+        disabled?: boolean;
+        'data-field': string;
+    };
+    /** The field's error, for its Field. */
+    error(key: keyof T): string | undefined;
+    /** The current draft. */
+    draft: T;
+}
+/**
+ * Several fields of one record, edited where the record is shown and saved together as one write. Read mode is the
+ * 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.
+ */
+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). */
+export declare function EditRegionView({ children, trigger, className }: {
+    children?: React.ReactNode;
+    trigger?: boolean;
+    className?: string;
+}): React.JSX.Element | null;
+/**
+ * One value in read mode, named by the field that edits it. With layout 'in-place', a field whose text opens where its
+ * value was simply appears; one that opens elsewhere fades in. `reserve` gives the value its control's height and inset
+ * now, so in a list of labelled rows nothing moves at all when Edit opens.
+ */
+export declare function EditRegionValue({ field, reserve, children, className }: {
+    field: string;
+    reserve?: boolean;
+    children?: React.ReactNode;
+    className?: string;
+}): React.JSX.Element;
+/** The visible Edit button. Rendered by EditRegionView by default. */
+export declare function EditRegionTrigger({ children, className }: {
+    children?: React.ReactNode;
+    className?: string;
+}): React.JSX.Element | null;
+/**
+ * Edit mode: a form (or a group, inside another form) named “Edit <label>”, holding your fields, then any error and
+ * Save/Cancel. Children may be a function of the draft binder: `{(field) => <Input {...field('name')} />}`.
+ */
+export declare function EditRegionForm<T extends Record<string, unknown> = Record<string, unknown>>({ children, actions, className }: {
+    children: React.ReactNode | ((field: EditRegionBinder<T>) => React.ReactNode);
+    actions?: boolean;
+    className?: string;
+}): React.JSX.Element | null;
+/** Any error, the conflict notice and Save/Cancel. EditRegionForm renders them after the fields unless `actions={false}`. */
+export declare function EditRegionActions(): React.ReactNode;
+export {};