vireuikit 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -156,9 +156,9 @@ type GrowthState = {
 };
 declare const createGrowthState: () => GrowthState;
 declare const growthPhase: (state: GrowthState) => GrowthPhase;
-/** Durations are client-specific: this set is tuned for the capsule-to-menu transition, 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. */
+/** 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;
@@ -183,6 +183,154 @@ declare function stepControlVisual(visual: ControlVisual, dt: number, state: Con
 declare function visualAtomState(visual: ControlVisual, state: ControlState): VireUIKitAtomState;
 declare function settleControlVisual(visual: ControlVisual, state: ControlState): void;
 
+/**
+ * `disabled`: cannot be chosen. `focusable` (default: not disabled): whether focus can land on it. A native
+ * disabled button cannot take focus, so the keyboard passes over it; an aria-disabled one can (WAI-ARIA APG).
+ */
+type MenuItem = {
+    label: string;
+    disabled: boolean;
+    focusable?: boolean;
+};
+type MenuState = {
+    open: boolean;
+    /** The active item, or -1 while the menu itself holds focus. */
+    active: number;
+    typed: string;
+    /** Seconds, on whatever clock the events carry. */
+    typedAt: number;
+};
+declare const MENU_CLOSED: MenuState;
+type MenuDismissal = 'escape' | 'outside' | 'tab' | 'trigger';
+type MenuEvent = {
+    type: 'open';
+    focus: 'menu' | 'first' | 'last';
+} | {
+    type: 'move';
+    to: 'next' | 'previous' | 'first' | 'last';
+} | {
+    type: 'point';
+    index: number;
+} | {
+    type: 'type';
+    key: string;
+    at: number;
+} | {
+    type: 'choose';
+    index: number;
+} | {
+    type: 'dismiss';
+    reason: MenuDismissal;
+};
+/** Where focus goes after a step. `none` leaves it where the person put it (a press outside). */
+type MenuFocus = {
+    to: 'item';
+    index: number;
+} | {
+    to: 'menu';
+} | {
+    to: 'trigger';
+} | {
+    to: 'none';
+} | {
+    to: 'stay';
+};
+type MenuStep = {
+    state: MenuState;
+    focus: MenuFocus;
+    chosen: number | null;
+};
+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;
+    y: -1 | 1;
+};
+declare const MENU_CORNERS: {
+    readonly 'top-left': {
+        readonly x: -1;
+        readonly y: -1;
+    };
+    readonly 'top-right': {
+        readonly x: 1;
+        readonly y: -1;
+    };
+    readonly 'bottom-left': {
+        readonly x: -1;
+        readonly y: 1;
+    };
+    readonly 'bottom-right': {
+        readonly x: 1;
+        readonly y: 1;
+    };
+};
+type MenuPlacement = {
+    rect: Rect;
+    corner: MenuCorner;
+    /** 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;
+/**
+ * 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.
+ */
+declare function menuPlacement(trigger: Rect, menu: Size, viewport: Size, options?: {
+    corner?: MenuCorner | undefined;
+    margin?: number;
+}): MenuPlacement;
+type RoundedRect = Rect & {
+    radius: number;
+};
+type MenuSurfaceFrame = {
+    /** The surface's box this frame: the growth frame's body. */
+    box: RoundedRect;
+    /** The second shape for the lens's `setMorph`, offset from the box's centre; undefined once there is one body. */
+    morph: VireGlassMorph | undefined;
+    /** Where the content's origin sits relative to the box's: it keeps its final place while the box moves. */
+    content: {
+        x: number;
+        y: number;
+    };
+    ink: GrowthInk;
+    /** How much of a drop the surface is: 0 as the trigger and as the menu, highest in between. */
+    activity: number;
+};
+declare function menuActivity(phase: GrowthPhase): number;
+declare function menuSurfaceFrame(trigger: RoundedRect, menu: RoundedRect, anchor: GrowthPoint, phase: GrowthPhase): 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;
+/** The drop is the medium at its active end, the menu at rest is the resting glass. */
+declare function menuMaterial(base: VireGlassMaterial, activity: number): VireGlassMaterial;
+/** The gathered medium lit by a concentrate of its surroundings: about 0.2 lighter than what it covers at
+ *  M 5:11, so white over a light backdrop, and only brighter over a dark one. */
+declare const MENU_DROP_BODY: AtomBody;
+declare function menuBody(base: VireGlassMaterial, activity: number, frost?: boolean): AtomBody;
+type MenuItemState = {
+    active: boolean;
+    pressed: boolean;
+    disabled: boolean;
+};
+/** Ink laid on the glass under an item, as a fraction of the ink colour. */
+declare const MENU_ITEM_FILL: {
+    readonly active: 0.1;
+    readonly pressed: 0.18;
+};
+declare function menuItemFill(state: MenuItemState): number;
+
 type PressResponse = {
     /** Fraction of its own size the body adds at full press. */
     grow: number;
@@ -207,6 +355,19 @@ 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;
@@ -216,4 +377,4 @@ 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, MIN_POINTER_TARGET_DP, MIN_TOUCH_TARGET_DP, POINTER_INPUT, PRESS_IDLE, type PressEvent, type PressResponse, type PressSource, type PressState, type PressStep, type SizeSpec, type Spring, TOUCH_INPUT, type VireUIKitAtomKind, type VireUIKitAtomState, atomAtRest, atomBody, atomLift, atomMaterial, controlTargets, createControlVisual, createGrowthState, defaultSize, growthFrame, growthInk, growthPhase, hitSlop, iconButtonSize, minTarget, nestedRadius, pressResponse, settleControlVisual, smoothstep, stepControl, stepControlVisual, stepFocus, stepGrowth, stepHover, stepPress, stepSpring, visualAtomState };
+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 };

package/dist/index.d.ts

@@ -156,9 +156,9 @@ type GrowthState = {
 };
 declare const createGrowthState: () => GrowthState;
 declare const growthPhase: (state: GrowthState) => GrowthPhase;
-/** Durations are client-specific: this set is tuned for the capsule-to-menu transition, 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. */
+/** 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;
@@ -183,6 +183,154 @@ declare function stepControlVisual(visual: ControlVisual, dt: number, state: Con
 declare function visualAtomState(visual: ControlVisual, state: ControlState): VireUIKitAtomState;
 declare function settleControlVisual(visual: ControlVisual, state: ControlState): void;
 
+/**
+ * `disabled`: cannot be chosen. `focusable` (default: not disabled): whether focus can land on it. A native
+ * disabled button cannot take focus, so the keyboard passes over it; an aria-disabled one can (WAI-ARIA APG).
+ */
+type MenuItem = {
+    label: string;
+    disabled: boolean;
+    focusable?: boolean;
+};
+type MenuState = {
+    open: boolean;
+    /** The active item, or -1 while the menu itself holds focus. */
+    active: number;
+    typed: string;
+    /** Seconds, on whatever clock the events carry. */
+    typedAt: number;
+};
+declare const MENU_CLOSED: MenuState;
+type MenuDismissal = 'escape' | 'outside' | 'tab' | 'trigger';
+type MenuEvent = {
+    type: 'open';
+    focus: 'menu' | 'first' | 'last';
+} | {
+    type: 'move';
+    to: 'next' | 'previous' | 'first' | 'last';
+} | {
+    type: 'point';
+    index: number;
+} | {
+    type: 'type';
+    key: string;
+    at: number;
+} | {
+    type: 'choose';
+    index: number;
+} | {
+    type: 'dismiss';
+    reason: MenuDismissal;
+};
+/** Where focus goes after a step. `none` leaves it where the person put it (a press outside). */
+type MenuFocus = {
+    to: 'item';
+    index: number;
+} | {
+    to: 'menu';
+} | {
+    to: 'trigger';
+} | {
+    to: 'none';
+} | {
+    to: 'stay';
+};
+type MenuStep = {
+    state: MenuState;
+    focus: MenuFocus;
+    chosen: number | null;
+};
+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;
+    y: -1 | 1;
+};
+declare const MENU_CORNERS: {
+    readonly 'top-left': {
+        readonly x: -1;
+        readonly y: -1;
+    };
+    readonly 'top-right': {
+        readonly x: 1;
+        readonly y: -1;
+    };
+    readonly 'bottom-left': {
+        readonly x: -1;
+        readonly y: 1;
+    };
+    readonly 'bottom-right': {
+        readonly x: 1;
+        readonly y: 1;
+    };
+};
+type MenuPlacement = {
+    rect: Rect;
+    corner: MenuCorner;
+    /** 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;
+/**
+ * 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.
+ */
+declare function menuPlacement(trigger: Rect, menu: Size, viewport: Size, options?: {
+    corner?: MenuCorner | undefined;
+    margin?: number;
+}): MenuPlacement;
+type RoundedRect = Rect & {
+    radius: number;
+};
+type MenuSurfaceFrame = {
+    /** The surface's box this frame: the growth frame's body. */
+    box: RoundedRect;
+    /** The second shape for the lens's `setMorph`, offset from the box's centre; undefined once there is one body. */
+    morph: VireGlassMorph | undefined;
+    /** Where the content's origin sits relative to the box's: it keeps its final place while the box moves. */
+    content: {
+        x: number;
+        y: number;
+    };
+    ink: GrowthInk;
+    /** How much of a drop the surface is: 0 as the trigger and as the menu, highest in between. */
+    activity: number;
+};
+declare function menuActivity(phase: GrowthPhase): number;
+declare function menuSurfaceFrame(trigger: RoundedRect, menu: RoundedRect, anchor: GrowthPoint, phase: GrowthPhase): 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;
+/** The drop is the medium at its active end, the menu at rest is the resting glass. */
+declare function menuMaterial(base: VireGlassMaterial, activity: number): VireGlassMaterial;
+/** The gathered medium lit by a concentrate of its surroundings: about 0.2 lighter than what it covers at
+ *  M 5:11, so white over a light backdrop, and only brighter over a dark one. */
+declare const MENU_DROP_BODY: AtomBody;
+declare function menuBody(base: VireGlassMaterial, activity: number, frost?: boolean): AtomBody;
+type MenuItemState = {
+    active: boolean;
+    pressed: boolean;
+    disabled: boolean;
+};
+/** Ink laid on the glass under an item, as a fraction of the ink colour. */
+declare const MENU_ITEM_FILL: {
+    readonly active: 0.1;
+    readonly pressed: 0.18;
+};
+declare function menuItemFill(state: MenuItemState): number;
+
 type PressResponse = {
     /** Fraction of its own size the body adds at full press. */
     grow: number;
@@ -207,6 +355,19 @@ 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;
@@ -216,4 +377,4 @@ 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, MIN_POINTER_TARGET_DP, MIN_TOUCH_TARGET_DP, POINTER_INPUT, PRESS_IDLE, type PressEvent, type PressResponse, type PressSource, type PressState, type PressStep, type SizeSpec, type Spring, TOUCH_INPUT, type VireUIKitAtomKind, type VireUIKitAtomState, atomAtRest, atomBody, atomLift, atomMaterial, controlTargets, createControlVisual, createGrowthState, defaultSize, growthFrame, growthInk, growthPhase, hitSlop, iconButtonSize, minTarget, nestedRadius, pressResponse, settleControlVisual, smoothstep, stepControl, stepControlVisual, stepFocus, stepGrowth, stepHover, stepPress, stepSpring, visualAtomState };
+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 };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { A11Y_NONE, ATOM_AT_REST, BUTTON_SIZES, CONTROL_IDLE, CONTROL_SIZES, DEFAULT_GROWTH_TIMING, MIN_POINTER_TARGET_DP, MIN_TOUCH_TARGET_DP, POINTER_INPUT, PRESS_IDLE, TOUCH_INPUT, atomAtRest, atomBody, atomLift, atomMaterial, controlTargets, createControlVisual, createGrowthState, defaultSize, growthFrame, growthInk, growthPhase, hitSlop, iconButtonSize, minTarget, nestedRadius, presentationFor, pressResponse, resolveA11y, sameA11y, settleControlVisual, smoothstep, stepControl, stepControlVisual, stepFocus, stepGrowth, stepHover, stepPress, stepSpring, visualAtomState } from './chunk-I3BD3XGC.js';
+export { A11Y_NONE, ATOM_AT_REST, BUTTON_SIZES, CONTROL_IDLE, CONTROL_SIZES, DEFAULT_GROWTH_TIMING, MENU_CLOSED, MENU_CORNERS, MENU_DROP_BODY, MENU_ITEM_FILL, MIN_POINTER_TARGET_DP, MIN_TOUCH_TARGET_DP, POINTER_INPUT, PRESS_IDLE, TOUCH_INPUT, TYPEAHEAD_SECONDS, atomAtRest, atomBody, atomLift, atomMaterial, controlTargets, createControlVisual, createGrowthState, defaultSize, growthFrame, growthInk, growthPhase, hitSlop, iconButtonSize, menuActivity, menuBody, menuCorner, menuGlass, menuItemFill, menuMaterial, menuPlacement, menuSize, menuSurfaceFrame, minTarget, nestedRadius, presentationFor, pressResponse, resolveA11y, sameA11y, settleControlVisual, smoothstep, stepControl, stepControlVisual, stepFocus, stepGrowth, stepHover, stepMenu, stepPress, stepSpring, visualAtomState } from './chunk-AR2AM3BR.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map