vireuikit 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,5 +1,388 @@
-export { A as A11Y_NONE, a as A11yMode, b as A11yOverride, P as Presentation, S as Surface, p as presentationFor, r as resolveA11y, s as sameA11y } from './a11y-D3SS74I3.js';
-import { VireGlassMaterial, VireGlassGeometry, VireGlassMorph } from 'vireglass';
+import { S as Size, R as Rect, A as AdaptiveContext, I as InputLayers } from './context-DQaAcRq-.js';
+export { a as A11Y_NONE, b as A11yMode, c as A11yOverride, F as Fold, H as HalfOpenOptions, d as INPUT_MIXED, e as INPUT_POINTER, f as INPUT_TABLET_KEYBOARD, g as INPUT_TOUCH, P as POSTURE_FLAT, h as Posture, i as Presentation, j as Surface, k as adaptiveContext, l as halfOpen, m as intersectRect, p as postureFromSegments, n as presentationFor, r as rectContains, o as resolveA11y, s as sameA11y, q as segmentOf, t as surfaceRegion, w as windowSegments } from './context-DQaAcRq-.js';
+import { VireGlassGeometry, VireGlassMorph, VireGlassMaterial } from 'vireglass';
+
+type WidthClass = 'compact' | 'medium' | 'expanded' | 'large' | 'xlarge';
+type HeightClass = 'compact' | 'medium' | 'expanded';
+declare const WIDTH_CLASSES: readonly WidthClass[];
+declare const HEIGHT_CLASSES: readonly HeightClass[];
+/** The lower bound of each class in dp; compact starts at 0. */
+declare const WIDTH_BREAKPOINTS: {
+    readonly medium: 600;
+    readonly expanded: 840;
+    readonly large: 1200;
+    readonly xlarge: 1600;
+};
+declare const HEIGHT_BREAKPOINTS: {
+    readonly medium: 480;
+    readonly expanded: 900;
+};
+type WindowClass = {
+    width: WidthClass;
+    height: HeightClass;
+};
+declare function widthClass(width: number): WidthClass;
+declare function heightClass(height: number): HeightClass;
+declare function classifyWindow(size: Size): WindowClass;
+declare function widthAtLeast(value: WidthClass, minimum: WidthClass): boolean;
+
+/** A spring with `response`-second settle time; `damping` < 1 overshoots. `instant` skips
+ *  integration entirely, for reduced motion. */
+type Spring = {
+    x: number;
+    v: number;
+    target: number;
+};
+declare function stepSpring(s: Spring, dt: number, response: number, damping: number, instant?: boolean): boolean;
+declare const smoothstep: (e0: number, e1: number, x: number) => number;
+type GrowthPoint = {
+    x: number;
+    y: number;
+};
+/** A shape and its position — it has no role of its own; `growthFrame` assigns the role (body, or
+ *  what the body is merging into). */
+type GrowthShape = {
+    geometry: VireGlassGeometry;
+    center: GrowthPoint;
+};
+/** `shrink` — capsule → drop, no overshoot. `grow` — drop → target; may exceed 1 for the
+ *  overshoot. Both are read as-is; `stepGrowth` owns the bounds and the handoff between them. */
+type GrowthPhase = {
+    shrink: number;
+    grow: number;
+};
+type GrowthInk = {
+    /** 0…1: how much of the source's ink is still visible (1) vs. already defocused into the drop (0). */
+    outgoing: number;
+    /** 0…1: how much of the target's ink has come into focus (0 = not yet, 1 = fully). */
+    incoming: number;
+};
+type GrowthFrame = {
+    /** The shape worth drawing as glass right now: the larger of the two, which supplies the
+     *  thickness and the bevel. */
+    body: GrowthShape;
+    /** The target shape as-is, regardless of role — it drives the response to finger/light while
+     *  the glass hasn't become it yet (while `body` is still the drop). */
+    grown: GrowthShape;
+    /** The second merge shape, ready for `toLensProps`/`toSurfaceUniforms`; `undefined` while the
+     *  neck hasn't grown yet or has already retracted. */
+    merge: VireGlassMorph | undefined;
+    ink: GrowthInk;
+};
+declare function growthInk(phase: GrowthPhase): GrowthInk;
+/** `anchor` is the corner shared by source and target: the body pins to it, otherwise the target
+ *  would grow out of the drop's center instead of the button's corner. */
+declare function growthFrame(source: GrowthShape, target: GrowthShape, anchor: GrowthPoint, phase: GrowthPhase): GrowthFrame;
+type GrowthState = {
+    shrink: Spring;
+    grow: Spring;
+};
+declare const createGrowthState: () => GrowthState;
+declare const growthPhase: (state: GrowthState) => GrowthPhase;
+/** Durations are client-specific: the default is fitted to the menu growing out of its toolbar at
+ *  M 5:11 (docs/acceptance.md, N9), and an atom at a different scale (an icon opening into a sheet)
+ *  isn't obligated to match it. The shape of the transition is shared regardless. */
+type GrowthTiming = {
+    shrinkOpen: number;
+    shrinkClose: number;
+    growOpen: number;
+    growClose: number;
+    /** < 1 gives the target a slight overshoot on open; closing never overshoots. */
+    growDampingOpen: number;
+};
+declare const DEFAULT_GROWTH_TIMING: GrowthTiming;
+/** Growth starts once the drop has gathered, and the reverse on close. `reduceMotion` turns off
+ *  the spring entirely: both phases jump straight to their target in one step, with no overshoot
+ *  and no defocus phase. */
+declare function stepGrowth(state: GrowthState, dt: number, open: boolean, reduceMotion?: boolean, timing?: GrowthTiming): boolean;
+
+type MorphBody = 'navigation' | 'surface' | 'panes' | 'supporting' | 'accessory' | 'toolbar';
+type FormChange = {
+    body: MorphBody;
+    from: string;
+    to: string;
+};
+type FormMorphDescriptor = FormChange & {
+    /**
+     * `reshape`: the one body changes its box and its content refocuses. `appear` and `disappear`: the body comes and goes by
+     * modulating its lens, never by fading. `retract`: its anchor is gone, so it runs back into the anchor's new owner and
+     * closes. `none`: nothing moves.
+     */
+    mode: 'none' | 'reshape' | 'appear' | 'disappear' | 'retract';
+    /** An open surface stays open through a change of form. */
+    staysOpen: boolean;
+    instant: boolean;
+};
+declare function formMorph(change: FormChange, ctx: Pick<AdaptiveContext, 'reduceMotion'>, options?: {
+    anchorGone?: boolean;
+}): FormMorphDescriptor;
+/** The menu's opening response, so a class change moves at the pace of the growth; critically damped, because a
+ *  layout that overshoots would bounce off the window's edge. */
+declare const FORM_MORPH_TIMING: {
+    readonly response: number;
+    readonly damping: 1;
+};
+/** 0 is the form it comes from, 1 the form it goes to. */
+type FormMorphState = {
+    t: Spring;
+    fromInk?: number;
+};
+declare const createFormMorph: () => FormMorphState;
+/** Steps toward a form; true while still moving. Called with the other end mid-way, it turns back from where it is. */
+declare function stepFormMorph(state: FormMorphState, dt: number, toward: 0 | 1, instant?: boolean): boolean;
+type MorphBox = Rect & {
+    radius: number;
+};
+type FormMorphFrame = {
+    box: MorphBox;
+    /** The content defocuses out of the old form and into the new one; both are 0 around the middle. */
+    ink: {
+        outgoing: number;
+        incoming: number;
+    };
+    /** Which form's content shows. */
+    showing: 'from' | 'to';
+};
+declare function formMorphFrame(from: MorphBox, to: MorphBox, state: FormMorphState): FormMorphFrame;
+/**
+ * A third form while a morph is under way: the box it is in now becomes the new start and the content showing now
+ * leaves from the ink it has, so nothing jumps. A rebased start is a moment, not a form; the morph only goes on from it.
+ */
+declare function rebaseFormMorph(state: FormMorphState): void;
+
+type ControlSize = 'touch' | 'small' | 'medium' | 'large' | 'xlarge';
+declare const CONTROL_SIZES: readonly ControlSize[];
+type SizeSpec = {
+    /** Body height; an icon button is a square of this side. */
+    height: number;
+    paddingX: number;
+    icon: number;
+    radius: number;
+    shape: 'capsule' | 'rounded';
+};
+declare const MIN_TOUCH_TARGET_DP = 44;
+declare const MIN_POINTER_TARGET_DP = 24;
+declare const BUTTON_SIZES: Readonly<Record<ControlSize, SizeSpec>>;
+declare function iconButtonSize(size: ControlSize): SizeSpec & {
+    width: number;
+};
+type MenuSizeSpec = {
+    /** Row height; the glyph sits centred in a square of it. */
+    row: number;
+    padding: number;
+    /** The active item's highlight. */
+    itemRadius: number;
+    /** Concentric with the highlight: its radius plus the padding. */
+    radius: number;
+    icon: number;
+    /** The label's inset in an item without a glyph. */
+    labelPad: number;
+};
+declare function menuSize(size: ControlSize): MenuSizeSpec;
+declare function nestedRadius(outerRadius: number, inset: number, minimum?: number): number;
+declare function defaultSize(input: {
+    touch: boolean;
+}): ControlSize;
+declare function hitSlop(bodyDp: number, minTargetDp: number): number;
+declare function minTarget(input: {
+    touch: boolean;
+}): number;
+
+/** Layout density, for the whole window: the primary pointer. */
+declare function sizeTier(input: Pick<InputLayers, 'primary'>): ControlSize;
+/** The hit area's floor in dp: any coarse input present. The body keeps its size. */
+declare function hitTarget(input: Pick<InputLayers, 'anyCoarse'>): number;
+/** Hover is the event's: a mouse or a pen over the control hovers, a finger never does. */
+declare function hoversWith(pointerType: string): boolean;
+
+type NavigationSpec = {
+    /** Destinations shown on every form. */
+    primary: number;
+    /** Destinations shown only in the sidebar and in a rail expanded over the content. */
+    secondary?: number;
+    search?: boolean;
+    /** The person collapsed the sidebar into a rail; the choice is remembered. */
+    sidebarCollapsed?: boolean;
+    /** Panes the content shows; two panes on a medium window take the bar. */
+    panes?: number;
+};
+type NavigationFormKind = 'bar' | 'rail' | 'sidebar';
+type SearchForm = {
+    /** A button at the bar's trailing end, an item of the rail, or a persistent field. */
+    form: 'button' | 'item' | 'field';
+    place: 'bar' | 'rail' | 'sidebar' | 'toolbar';
+    /** A keyboard shortcut focuses it. */
+    shortcut: boolean;
+};
+type NavigationForm = {
+    form: NavigationFormKind;
+    edge: 'bottom' | 'leading';
+    /** The same primary destinations on every form, so the body that changes form keeps its items. */
+    primary: number;
+    /** The secondary destinations plus those the bar has no slot for. */
+    secondary: number;
+    secondaryVisible: boolean;
+    search: SearchForm | null;
+    /** A rail that opens wider: over the content on an expanded window, beside it when the person collapsed the sidebar. */
+    expandable: 'over' | 'beside' | null;
+    /** A sidebar the person can collapse into a rail. */
+    collapsible: boolean;
+};
+/** Slots on the bar, the search button included. There is no "More" slot. */
+declare const BAR_SLOTS = 5;
+declare function navigationForm(ctx: AdaptiveContext, spec: NavigationSpec): NavigationForm;
+type BottomAccessoryForm = {
+    /** Above the bar; in the bar's row once it has minimised; along the bottom of the content beside a rail or sidebar. */
+    placement: 'above-bar' | 'in-bar' | 'content-bottom';
+    /** In the bar's row only the transport fits. */
+    compact: boolean;
+};
+declare function bottomAccessory(nav: Pick<NavigationForm, 'form'>, state?: {
+    barMinimized?: boolean;
+}): BottomAccessoryForm;
+
+/** The fixed list pane beside the detail (Material 3 list-detail). */
+declare const LIST_PANE_WIDTH: {
+    readonly expanded: 360;
+    readonly large: 412;
+};
+declare const SUPPORTING_PANE_MAX_WIDTH = 400;
+type ListDetailState = {
+    selected: boolean;
+    /** The pane the person is on while one pane shows; the detail needs a selection. Set it to `detail` on a selection. */
+    showing: 'list' | 'detail';
+    /** Sparse content may split a medium window in half. */
+    sparse?: boolean;
+};
+type PaneSplit = {
+    kind: 'fixed';
+    list: number;
+} | {
+    kind: 'half';
+}
+/** Book posture: the fold is the spacer between the panes. */
+ | {
+    kind: 'fold';
+    gap: Rect;
+};
+type PaneLayout = {
+    panes: 1 | 2;
+    visible: readonly ('list' | 'detail')[];
+    split: PaneSplit | null;
+    /** Two panes and nothing selected: the detail shows its empty state. */
+    placeholder: boolean;
+    /** Back exists only where the detail replaces the list. */
+    back: boolean;
+    /** The selection is drawn in the list only while both panes show. */
+    selectionShown: boolean;
+};
+declare function paneLayout(ctx: AdaptiveContext, state: ListDetailState): PaneLayout;
+type SupportingPaneState = {
+    /** The person keeps it beside the content; remembered across classes, so it returns when the window widens again. */
+    pinned: boolean;
+    /** Shown on demand; over the content on an expanded window. */
+    open: boolean;
+};
+type SupportingPaneForm = {
+    form: 'beside' | 'over' | 'hidden';
+    edge: 'trailing';
+    maxWidth: number;
+    /** Over the content it dims what it covers, like a modal side sheet. */
+    scrim: boolean;
+    remembered: boolean;
+};
+declare function supportingPane(ctx: AdaptiveContext, state: SupportingPaneState): SupportingPaneForm;
+type PostureSplit = {
+    kind: 'single';
+}
+/** Tabletop: what is watched above the fold, its controls below. Book: the leading half and the trailing one. */
+ | {
+    kind: 'split';
+    axis: 'horizontal' | 'vertical';
+    primary: Rect;
+    secondary: Rect;
+};
+declare function postureSplit(ctx: AdaptiveContext): PostureSplit;
+
+/**
+ * `menu`: closes after one choice and grows out of its trigger on every class. `picker`: a long choice with a search,
+ * which is not a menu but a sheet. `popover`: several picks, stays open. `sheet`: supplementary content beside a
+ * parallel task. `modal-sheet`: a modal task with a form. `alert`: a dialog without fields. `dialog`: one with fields.
+ */
+type SurfaceKind = 'menu' | 'picker' | 'popover' | 'sheet' | 'modal-sheet' | 'alert' | 'dialog';
+declare const SURFACE_KINDS: readonly SurfaceKind[];
+type PresentationFormKind = 'grown' | 'popover' | 'bottom-sheet' | 'centered-sheet' | 'side-sheet' | 'side-pane' | 'full-screen' | 'basic-dialog' | 'alert';
+type PresentationForm = {
+    form: PresentationFormKind;
+    /** It grows out of its source (and runs back into it). */
+    fromSource: boolean;
+    /** What lies behind is dimmed and inert. */
+    scrim: boolean;
+    /** It narrows the main area instead of covering it. */
+    compresses: boolean;
+    /** Its widest extent in dp; null where it fills its region. */
+    maxWidth: number | null;
+    /** Where it lives: its source's segment, or the largest; side sheets in book posture take the trailing one. */
+    region: Rect;
+};
+/** A bottom sheet on a medium window stops growing here and centres (Material 3 bottom sheets). */
+declare const BOTTOM_SHEET_MAX_WIDTH = 640;
+/** A side sheet, and the third pane it becomes on an xlarge window. */
+declare const SIDE_SHEET_MAX_WIDTH = 400;
+/** A centred sheet and a basic dialog (Material 3 dialogs). */
+declare const DIALOG_MAX_WIDTH = 560;
+declare function presentationForm(kind: SurfaceKind, ctx: AdaptiveContext, source?: Rect): PresentationForm;
+
+type ToolbarItem = {
+    id: string;
+    kind: 'icon' | 'text';
+    /** Higher stays visible longer; 0 by default. */
+    priority?: number;
+    /** A status on the item: it stays visible at any width. */
+    badge?: boolean;
+    /** The one tinted main action. It goes to the trailing end and never overflows. */
+    primary?: boolean;
+    /** Items of one group merge into one capsule; without it, neighbours of a kind share a group. */
+    group?: string;
+    /** A text item's width in dp, measured by the target; three tier heights by default. An icon is the tier's square. */
+    width?: number;
+};
+type ToolbarOrientation = 'horizontal' | 'vertical';
+type ToolbarOptions = {
+    /** The container's extent along the toolbar, dp. */
+    available: number;
+    tier: ControlSize;
+    orientation?: ToolbarOrientation;
+    maxGroups?: number;
+    gap?: number;
+};
+type ToolbarCapsule = {
+    kind: 'icon' | 'text' | 'more' | 'primary';
+    items: readonly string[];
+    extent: number;
+};
+type ToolbarLayout = {
+    orientation: ToolbarOrientation;
+    stage: 'separate' | 'merged' | 'overflow';
+    capsules: readonly ToolbarCapsule[];
+    /** In "…", in their order. "…" exists only when this is not empty. */
+    overflow: readonly string[];
+    /** Text items of a vertical toolbar: text does not stand vertical, so they stay in a horizontal row. */
+    aside: readonly string[];
+    extent: number;
+    /** False only when what may not overflow (status, the main action) is wider than the container. */
+    fits: boolean;
+};
+declare const TOOLBAR_GAP = 8;
+declare const MORE_ID = "\u2026";
+type ToolbarPlacement = {
+    edge: 'bottom' | 'top' | 'trailing';
+    orientation: ToolbarOrientation;
+    maxGroups: number;
+};
+/** The window decides where a toolbar sits; its layout then follows its own container. */
+declare function toolbarPlacement(ctx: AdaptiveContext): ToolbarPlacement;
+declare function toolbarLayout(items: readonly ToolbarItem[], options: ToolbarOptions): ToolbarLayout;
 
 type VireUIKitAtomKind = 'button' | 'iconButton' | 'switch' | 'slider' | 'segment' | 'chip' | 'field' | 'menu';
 /** Hover and focus don't exist everywhere: touch has neither. The atom accepts them, but has to
@@ -103,76 +486,6 @@ type ControlTargets = {
 };
 declare function controlTargets(state: ControlState): ControlTargets;
 
-/** A spring with `response`-second settle time; `damping` < 1 overshoots. `instant` skips
- *  integration entirely, for reduced motion. */
-type Spring = {
-    x: number;
-    v: number;
-    target: number;
-};
-declare function stepSpring(s: Spring, dt: number, response: number, damping: number, instant?: boolean): boolean;
-declare const smoothstep: (e0: number, e1: number, x: number) => number;
-type GrowthPoint = {
-    x: number;
-    y: number;
-};
-/** A shape and its position — it has no role of its own; `growthFrame` assigns the role (body, or
- *  what the body is merging into). */
-type GrowthShape = {
-    geometry: VireGlassGeometry;
-    center: GrowthPoint;
-};
-/** `shrink` — capsule → drop, no overshoot. `grow` — drop → target; may exceed 1 for the
- *  overshoot. Both are read as-is; `stepGrowth` owns the bounds and the handoff between them. */
-type GrowthPhase = {
-    shrink: number;
-    grow: number;
-};
-type GrowthInk = {
-    /** 0…1: how much of the source's ink is still visible (1) vs. already defocused into the drop (0). */
-    outgoing: number;
-    /** 0…1: how much of the target's ink has come into focus (0 = not yet, 1 = fully). */
-    incoming: number;
-};
-type GrowthFrame = {
-    /** The shape worth drawing as glass right now: the larger of the two, which supplies the
-     *  thickness and the bevel. */
-    body: GrowthShape;
-    /** The target shape as-is, regardless of role — it drives the response to finger/light while
-     *  the glass hasn't become it yet (while `body` is still the drop). */
-    grown: GrowthShape;
-    /** The second merge shape, ready for `toLensProps`/`toSurfaceUniforms`; `undefined` while the
-     *  neck hasn't grown yet or has already retracted. */
-    merge: VireGlassMorph | undefined;
-    ink: GrowthInk;
-};
-declare function growthInk(phase: GrowthPhase): GrowthInk;
-/** `anchor` is the corner shared by source and target: the body pins to it, otherwise the target
- *  would grow out of the drop's center instead of the button's corner. */
-declare function growthFrame(source: GrowthShape, target: GrowthShape, anchor: GrowthPoint, phase: GrowthPhase): GrowthFrame;
-type GrowthState = {
-    shrink: Spring;
-    grow: Spring;
-};
-declare const createGrowthState: () => GrowthState;
-declare const growthPhase: (state: GrowthState) => GrowthPhase;
-/** Durations are client-specific: the default is fitted to the menu growing out of its toolbar at
- *  M 5:11 (docs/acceptance.md, N9), and an atom at a different scale (an icon opening into a sheet)
- *  isn't obligated to match it. The shape of the transition is shared regardless. */
-type GrowthTiming = {
-    shrinkOpen: number;
-    shrinkClose: number;
-    growOpen: number;
-    growClose: number;
-    /** < 1 gives the target a slight overshoot on open; closing never overshoots. */
-    growDampingOpen: number;
-};
-declare const DEFAULT_GROWTH_TIMING: GrowthTiming;
-/** Growth starts once the drop has gathered, and the reverse on close. `reduceMotion` turns off
- *  the spring entirely: both phases jump straight to their target in one step, with no overshoot
- *  and no defocus phase. */
-declare function stepGrowth(state: GrowthState, dt: number, open: boolean, reduceMotion?: boolean, timing?: GrowthTiming): boolean;
-
 type ControlVisual = {
     pressed: Spring;
     hovered: Spring;
@@ -242,16 +555,6 @@ type MenuStep = {
 };
 declare const TYPEAHEAD_SECONDS = 0.5;
 declare function stepMenu(state: MenuState, event: MenuEvent, items: readonly MenuItem[]): MenuStep;
-type Rect = {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
-type Size = {
-    width: number;
-    height: number;
-};
 /** -1 is left or top, 1 is right or bottom. */
 type MenuCorner = {
     x: -1 | 1;
@@ -281,13 +584,20 @@ type MenuPlacement = {
     /** The menu's corner on the pinned side: where its growth ends. */
     anchor: GrowthPoint;
 };
-/** The trigger's corner nearest the viewport corner it sits in: the open space lies away from it. */
-declare function menuCorner(trigger: Rect, viewport: Size): MenuCorner;
+/** Where a menu must stay: its trigger's segment of the window, the whole viewport when nothing folds it. A size
+ *  alone is a region at the origin. */
+type MenuRegion = Size & {
+    x?: number;
+    y?: number;
+};
+/** The trigger's corner nearest the corner of its region it sits in: the open space lies away from it. */
+declare function menuCorner(trigger: Rect, region: MenuRegion): MenuCorner;
 /**
- * The menu shares a corner with its trigger and covers it. An automatic corner flips on an axis
- * where the menu would leave the viewport and the other side fits; then it slides in.
+ * The menu shares a corner with its trigger and covers it. An automatic corner flips on an axis where the menu would
+ * leave its region and the other side fits; then it slides in. The region is the trigger's segment, so a menu never
+ * crosses a fold.
  */
-declare function menuPlacement(trigger: Rect, menu: Size, viewport: Size, options?: {
+declare function menuPlacement(trigger: Rect, menu: Size, region: MenuRegion, options?: {
     corner?: MenuCorner | undefined;
     margin?: number;
 }): MenuPlacement;
@@ -309,7 +619,9 @@ type MenuSurfaceFrame = {
     activity: number;
 };
 declare function menuActivity(phase: GrowthPhase): number;
-declare function menuSurfaceFrame(trigger: RoundedRect, menu: RoundedRect, anchor: GrowthPoint, phase: GrowthPhase): MenuSurfaceFrame;
+/** `bounds`, the menu's region, holds every frame inside it: the overshoot runs away from the anchor and could
+ *  otherwise reach over a fold for a few frames. */
+declare function menuSurfaceFrame(trigger: RoundedRect, menu: RoundedRect, anchor: GrowthPoint, phase: GrowthPhase, bounds?: Rect): MenuSurfaceFrame;
 /** A menu is a larger piece of the same glass, and a larger piece scatters light more softly (M 7:19): it
  *  takes the core's sheet scattering, which turns text under it into soft spots without turning it to mush. */
 declare function menuGlass(base: VireGlassMaterial): VireGlassMaterial;
@@ -331,6 +643,190 @@ declare const MENU_ITEM_FILL: {
 };
 declare function menuItemFill(state: MenuItemState): number;
 
+declare const NAV_SIZES: {
+    readonly bar: {
+        readonly height: 56;
+        readonly item: 74;
+        readonly minItem: 44;
+        readonly inset: 3;
+        readonly margin: 16;
+        readonly searchGap: 8;
+        readonly minimized: 44;
+    };
+    readonly rail: {
+        readonly width: 80;
+        readonly item: 56;
+        readonly gap: 4;
+        readonly padding: 8;
+        readonly margin: 8;
+        readonly head: 48;
+    };
+    readonly sidebar: {
+        readonly width: 280;
+        readonly row: {
+            readonly touch: 44;
+            readonly pointer: 36;
+        };
+        readonly padding: 8;
+        readonly margin: 8;
+        readonly head: 48;
+        readonly separator: 12;
+    };
+    readonly accessory: {
+        readonly height: 48;
+        readonly gap: 8;
+        readonly inline: 44;
+        readonly content: 56;
+        readonly margin: 8;
+    };
+    readonly lens: {
+        readonly inflate: 6;
+    };
+    readonly toggle: 44;
+};
+type NavLayoutInput = {
+    form: NavigationFormKind;
+    /** The bar as a circle with the search circle; ignored on the other forms. */
+    minimized?: boolean;
+    window: Size;
+    /** Primary destinations shown. */
+    items: number;
+    /** Rows shown only in the sidebar. */
+    secondary: number;
+    search: SearchForm | null;
+    /** Index into the primary destinations, then the secondary; -1 for none. */
+    selected: number;
+    tier: 'touch' | 'pointer';
+    /** The rail's or sidebar's head holds a toggle. */
+    toggle: boolean;
+    accessory?: boolean;
+    /** The safe area at the bottom. */
+    bottomInset?: number;
+};
+type NavLayout = {
+    form: NavigationFormKind;
+    minimized: boolean;
+    body: MorphBox;
+    /** Primary, then secondary; the bar has only primary. A minimised bar's items all lie on its circle. */
+    items: MorphBox[];
+    pill: MorphBox | null;
+    /** The bar's separate circle, or the search item (rail) or field (sidebar) inside the body. */
+    search: MorphBox | null;
+    accessory: MorphBox | null;
+    /** The toggle in the head of the rail or sidebar; null where the head holds none. */
+    toggle: MorphBox | null;
+    accessoryPlacement: BottomAccessoryForm['placement'] | null;
+    /** What the content must clear. */
+    insets: {
+        bottom: number;
+        start: number;
+    };
+};
+declare function navLayout(input: NavLayoutInput): NavLayout;
+
+type NavDragState = {
+    active: boolean;
+    /** The lens's centre. */
+    x: Spring;
+    lift: Spring;
+    /** 0..MAX_STRETCH: how much wider (and half as much lower) the lens is for the pointer's speed. */
+    stretch: number;
+    /** The item under the lens. */
+    index: number;
+    lastX: number;
+};
+declare const createNavDrag: () => NavDragState;
+/** Bar form only; elsewhere a press is just a press. */
+declare function pressNavDrag(state: NavDragState, layout: NavLayout, pointerX: number): void;
+declare function moveNavDrag(state: NavDragState, layout: NavLayout, pointerX: number, dt: number): void;
+/** The nearest item; the lens springs to it and its lift falls to 0. Where the layout is not a bar the press just ends. */
+declare function releaseNavDrag(state: NavDragState, layout: NavLayout): number;
+/** A cancelled press settles back where it was. */
+declare function cancelNavDrag(state: NavDragState, layout: NavLayout, selected: number): void;
+/** True while the lens is held or still moving. */
+declare function stepNavDrag(state: NavDragState, dt: number, reduceMotion?: boolean): boolean;
+declare function navDragFrame(state: NavDragState, layout: NavLayout): {
+    lens: MorphBox;
+    lift: number;
+    hover: number;
+} | null;
+
+/**
+ * The model's answer held to one form, for a host that knows its layout or opens the sidebar over the content: the
+ * destinations stay the same, the search takes the form's own shape and the toggle follows the form.
+ */
+declare function fixedNavigationForm(nav: NavigationForm, form: NavigationFormKind): NavigationForm;
+
+declare const MINIMIZE_THRESHOLD = 24;
+/** A step against the run shorter than this is counted into it, not taken for a reversal. */
+declare const MINIMIZE_JITTER = 4;
+type MinimizeState = {
+    minimized: boolean;
+    run: number;
+    last: number;
+};
+declare const createMinimize: (scrollTop?: number) => MinimizeState;
+/** Feeds the scroller's position; returns whether the bar is minimised. */
+declare function stepMinimize(state: MinimizeState, scrollTop: number): boolean;
+/** The scroller's position as the bar should see it: a bounce past either end is the end. */
+declare const clampScrollTop: (scrollTop: number, scrollHeight: number, clientHeight: number) => number;
+/** A tap or focus expands the bar and starts the run over. */
+declare function expandMinimize(state: MinimizeState): void;
+
+/** Critically damped, fitted so the spring passes 95 % at about 0.8 s (M 8:36.2-8:37.0). */
+declare const NAV_MORPH_TIMING: {
+    readonly response: 1.06;
+    readonly damping: 1;
+};
+/** The bar contracting to its minimised circle and back moves at the pace of any other form change. */
+declare const NAV_MINIMIZE_TIMING: {
+    readonly response: number;
+    readonly damping: 1;
+};
+type NavMorphPhase = 'rest' | 'lift' | 'contract' | 'travel' | 'grow' | 'settle';
+type NavMorphFrame = {
+    phase: NavMorphPhase;
+    body: MorphBox;
+    /** The bar's search circle as the body's second shape; smoothing 0 once separate. */
+    second: {
+        box: MorphBox;
+        smoothing: number;
+    } | null;
+    /** The selection's lens; null at rest. `lift` 0..1 is its glass presence and magnification. */
+    lens: {
+        box: MorphBox;
+        lift: number;
+    } | null;
+    ink: {
+        outgoing: number;
+        incoming: number;
+    };
+    showing: 'from' | 'to';
+};
+declare function navMorphFrame(from: NavLayout, to: NavLayout, t: number, via?: 'lens' | 'contract'): NavMorphFrame;
+type NavMorphState = {
+    /** 0 is the form it comes from, 1 the form it goes to. */
+    t: Spring;
+    from: NavLayout;
+    to: NavLayout;
+    via: 'lens' | 'contract';
+    /** A frozen frame the morph goes on from; see `pivotAt`. */
+    pivot: NavMorphFrame | null;
+    /** Where `t` stood when a third form froze the lens mid-travel; 0 when the pivot is a new start (t was reset). */
+    pivotAt: number;
+};
+/** Resting at `at`. */
+declare const createNavMorph: (at: NavLayout) => NavMorphState;
+declare function currentNavFrame(state: NavMorphState): NavMorphFrame;
+/**
+ * Aims the morph at a layout. At rest it starts a new morph. Aimed back at the layout it came from it turns back.
+ * A third form before the lens reaches its place swaps the target (freezing the lens if it is already travelling);
+ * once the body grows, the frame it is in becomes the start of a new morph that contracts again.
+ */
+declare function aimNavMorph(state: NavMorphState, next: NavLayout, via?: 'lens' | 'contract'): void;
+/** True while moving. Reduced motion lands in one step. */
+declare function stepNavMorph(state: NavMorphState, dt: number, reduceMotion?: boolean): boolean;
+
 type PressResponse = {
     /** Fraction of its own size the body adds at full press. */
     grow: number;
@@ -339,42 +835,4 @@ type PressResponse = {
 };
 declare function pressResponse(kind: VireUIKitAtomKind): PressResponse;
 
-type ControlSize = 'touch' | 'small' | 'medium' | 'large' | 'xlarge';
-declare const CONTROL_SIZES: readonly ControlSize[];
-type SizeSpec = {
-    /** Body height; an icon button is a square of this side. */
-    height: number;
-    paddingX: number;
-    icon: number;
-    radius: number;
-    shape: 'capsule' | 'rounded';
-};
-declare const MIN_TOUCH_TARGET_DP = 44;
-declare const MIN_POINTER_TARGET_DP = 24;
-declare const BUTTON_SIZES: Readonly<Record<ControlSize, SizeSpec>>;
-declare function iconButtonSize(size: ControlSize): SizeSpec & {
-    width: number;
-};
-type MenuSizeSpec = {
-    /** Row height; the glyph sits centred in a square of it. */
-    row: number;
-    padding: number;
-    /** The active item's highlight. */
-    itemRadius: number;
-    /** Concentric with the highlight: its radius plus the padding. */
-    radius: number;
-    icon: number;
-    /** The label's inset in an item without a glyph. */
-    labelPad: number;
-};
-declare function menuSize(size: ControlSize): MenuSizeSpec;
-declare function nestedRadius(outerRadius: number, inset: number, minimum?: number): number;
-declare function defaultSize(input: {
-    touch: boolean;
-}): ControlSize;
-declare function hitSlop(bodyDp: number, minTargetDp: number): number;
-declare function minTarget(input: {
-    touch: boolean;
-}): number;
-
-export { ATOM_AT_REST, type AtomBody, BUTTON_SIZES, CONTROL_IDLE, CONTROL_SIZES, type ControlEvent, type ControlSize, type ControlState, type ControlStep, type ControlTargets, type ControlVisual, DEFAULT_GROWTH_TIMING, type FocusChange, type GrowthFrame, type GrowthInk, type GrowthPhase, type GrowthPoint, type GrowthShape, type GrowthState, type GrowthTiming, type HoverChange, type InputCaps, MENU_CLOSED, MENU_CORNERS, MENU_DROP_BODY, MENU_ITEM_FILL, MIN_POINTER_TARGET_DP, MIN_TOUCH_TARGET_DP, type MenuCorner, type MenuDismissal, type MenuEvent, type MenuFocus, type MenuItem, type MenuItemState, type MenuPlacement, type MenuSizeSpec, type MenuState, type MenuStep, type MenuSurfaceFrame, POINTER_INPUT, PRESS_IDLE, type PressEvent, type PressResponse, type PressSource, type PressState, type PressStep, type Rect, type RoundedRect, type Size, type SizeSpec, type Spring, TOUCH_INPUT, TYPEAHEAD_SECONDS, type VireUIKitAtomKind, type VireUIKitAtomState, atomAtRest, atomBody, atomLift, atomMaterial, controlTargets, createControlVisual, createGrowthState, defaultSize, growthFrame, growthInk, growthPhase, hitSlop, iconButtonSize, menuActivity, menuBody, menuCorner, menuGlass, menuItemFill, menuMaterial, menuPlacement, menuSize, menuSurfaceFrame, minTarget, nestedRadius, pressResponse, settleControlVisual, smoothstep, stepControl, stepControlVisual, stepFocus, stepGrowth, stepHover, stepMenu, stepPress, stepSpring, visualAtomState };
+export { ATOM_AT_REST, AdaptiveContext, type AtomBody, BAR_SLOTS, BOTTOM_SHEET_MAX_WIDTH, BUTTON_SIZES, type BottomAccessoryForm, CONTROL_IDLE, CONTROL_SIZES, type ControlEvent, type ControlSize, type ControlState, type ControlStep, type ControlTargets, type ControlVisual, DEFAULT_GROWTH_TIMING, DIALOG_MAX_WIDTH, FORM_MORPH_TIMING, type FocusChange, type FormChange, type FormMorphDescriptor, type FormMorphFrame, type FormMorphState, type GrowthFrame, type GrowthInk, type GrowthPhase, type GrowthPoint, type GrowthShape, type GrowthState, type GrowthTiming, HEIGHT_BREAKPOINTS, HEIGHT_CLASSES, type HeightClass, type HoverChange, type InputCaps, InputLayers, LIST_PANE_WIDTH, type ListDetailState, MENU_CLOSED, MENU_CORNERS, MENU_DROP_BODY, MENU_ITEM_FILL, MINIMIZE_JITTER, MINIMIZE_THRESHOLD, MIN_POINTER_TARGET_DP, MIN_TOUCH_TARGET_DP, MORE_ID, type MenuCorner, type MenuDismissal, type MenuEvent, type MenuFocus, type MenuItem, type MenuItemState, type MenuPlacement, type MenuRegion, type MenuSizeSpec, type MenuState, type MenuStep, type MenuSurfaceFrame, type MinimizeState, type MorphBody, type MorphBox, NAV_MINIMIZE_TIMING, NAV_MORPH_TIMING, NAV_SIZES, type NavDragState, type NavLayout, type NavLayoutInput, type NavMorphFrame, type NavMorphPhase, type NavMorphState, type NavigationForm, type NavigationFormKind, type NavigationSpec, POINTER_INPUT, PRESS_IDLE, type PaneLayout, type PaneSplit, type PostureSplit, type PresentationForm, type PresentationFormKind, type PressEvent, type PressResponse, type PressSource, type PressState, type PressStep, Rect, type RoundedRect, SIDE_SHEET_MAX_WIDTH, SUPPORTING_PANE_MAX_WIDTH, SURFACE_KINDS, type SearchForm, Size, type SizeSpec, type Spring, type SupportingPaneForm, type SupportingPaneState, type SurfaceKind, TOOLBAR_GAP, TOUCH_INPUT, TYPEAHEAD_SECONDS, type ToolbarCapsule, type ToolbarItem, type ToolbarLayout, type ToolbarOptions, type ToolbarOrientation, type ToolbarPlacement, type VireUIKitAtomKind, type VireUIKitAtomState, WIDTH_BREAKPOINTS, WIDTH_CLASSES, type WidthClass, type WindowClass, aimNavMorph, atomAtRest, atomBody, atomLift, atomMaterial, bottomAccessory, cancelNavDrag, clampScrollTop, classifyWindow, controlTargets, createControlVisual, createFormMorph, createGrowthState, createMinimize, createNavDrag, createNavMorph, currentNavFrame, defaultSize, expandMinimize, fixedNavigationForm, formMorph, formMorphFrame, growthFrame, growthInk, growthPhase, heightClass, hitSlop, hitTarget, hoversWith, iconButtonSize, menuActivity, menuBody, menuCorner, menuGlass, menuItemFill, menuMaterial, menuPlacement, menuSize, menuSurfaceFrame, minTarget, moveNavDrag, navDragFrame, navLayout, navMorphFrame, navigationForm, nestedRadius, paneLayout, postureSplit, presentationForm, pressNavDrag, pressResponse, rebaseFormMorph, releaseNavDrag, settleControlVisual, sizeTier, smoothstep, stepControl, stepControlVisual, stepFocus, stepFormMorph, stepGrowth, stepHover, stepMenu, stepMinimize, stepNavDrag, stepNavMorph, stepPress, stepSpring, supportingPane, toolbarLayout, toolbarPlacement, visualAtomState, widthAtLeast, widthClass };