@foldkit/ui 0.112.0

package/dist/listbox/single.d.ts

@@ -0,0 +1,207 @@
+import { Option, Schema as S } from 'effect';
+import type * as Command from 'foldkit/command';
+import type { Reflect, View as SubmodelView } from 'foldkit/submodel';
+import { type BaseInitConfig, type BaseViewInputs, type Message, type OutMessage } from './shared.js';
+/** Schema for the listbox component's state, tracking open/closed status, active item, selected item, activation trigger, and typeahead search. */
+export declare const Model: S.Struct<{
+    readonly maybeSelectedItem: S.Option<S.String>;
+    readonly id: S.String;
+    readonly isOpen: S.Boolean;
+    readonly isAnimated: S.Boolean;
+    readonly isModal: S.Boolean;
+    readonly orientation: S.Literals<readonly ["Vertical", "Horizontal"]>;
+    readonly animation: S.Struct<{
+        readonly id: S.String;
+        readonly isShowing: S.Boolean;
+        readonly transitionState: S.Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>;
+    }>;
+    readonly maybeActiveItemIndex: S.Option<S.Number>;
+    readonly activationTrigger: S.Literals<readonly ["Pointer", "Keyboard"]>;
+    readonly searchQuery: S.String;
+    readonly searchVersion: S.Number;
+    readonly maybeLastPointerPosition: S.Option<S.Struct<{
+        readonly screenX: S.Number;
+        readonly screenY: S.Number;
+    }>>;
+    readonly maybeLastButtonPointerType: S.Option<S.String>;
+}>;
+export type Model = typeof Model.Type;
+/** Configuration for creating a single-select listbox model with `init`. `isAnimated` enables CSS transition coordination (default `false`). `isModal` locks page scroll and inerts other elements when open (default `false`). `selectedItem` sets the initial selection (default none). */
+export type InitConfig = BaseInitConfig & Readonly<{
+    selectedItem?: string;
+}>;
+/** Creates an initial single-select listbox model from a config. Defaults to closed with no active item and no selection. */
+export declare const init: (config: InitConfig) => Model;
+/** Processes a listbox message and returns the next model, commands, and optional OutMessage. Closes the listbox on selection (single-select behavior); emits a `Selected({ value, wasAdded: true })` OutMessage. */
+export declare const update: (model: {
+    readonly maybeSelectedItem: Option.Option<string>;
+    readonly id: string;
+    readonly isOpen: boolean;
+    readonly isAnimated: boolean;
+    readonly isModal: boolean;
+    readonly orientation: "Horizontal" | "Vertical";
+    readonly animation: {
+        readonly id: string;
+        readonly isShowing: boolean;
+        readonly transitionState: "Idle" | "EnterStart" | "EnterAnimating" | "LeaveStart" | "LeaveAnimating";
+    };
+    readonly maybeActiveItemIndex: Option.Option<number>;
+    readonly activationTrigger: "Pointer" | "Keyboard";
+    readonly searchQuery: string;
+    readonly searchVersion: number;
+    readonly maybeLastPointerPosition: Option.Option<{
+        readonly screenX: number;
+        readonly screenY: number;
+    }>;
+    readonly maybeLastButtonPointerType: Option.Option<string>;
+}, message: Message) => readonly [{
+    readonly maybeSelectedItem: Option.Option<string>;
+    readonly id: string;
+    readonly isOpen: boolean;
+    readonly isAnimated: boolean;
+    readonly isModal: boolean;
+    readonly orientation: "Horizontal" | "Vertical";
+    readonly animation: {
+        readonly id: string;
+        readonly isShowing: boolean;
+        readonly transitionState: "Idle" | "EnterStart" | "EnterAnimating" | "LeaveStart" | "LeaveAnimating";
+    };
+    readonly maybeActiveItemIndex: Option.Option<number>;
+    readonly activationTrigger: "Pointer" | "Keyboard";
+    readonly searchQuery: string;
+    readonly searchVersion: number;
+    readonly maybeLastPointerPosition: Option.Option<{
+        readonly screenX: number;
+        readonly screenY: number;
+    }>;
+    readonly maybeLastButtonPointerType: Option.Option<string>;
+}, readonly Readonly<{
+    name: string;
+    args?: Record<string, unknown>;
+    effect: import("effect/Effect").Effect<{
+        readonly _tag: "CompletedFocusButton";
+    } | {
+        readonly _tag: "CompletedLockScroll";
+    } | {
+        readonly _tag: "CompletedUnlockScroll";
+    } | {
+        readonly _tag: "CompletedInertOthers";
+    } | {
+        readonly _tag: "CompletedRestoreInert";
+    } | {
+        readonly _tag: "IgnoredMouseClick";
+    } | {
+        readonly _tag: "SuppressedSpaceScroll";
+    } | {
+        readonly _tag: "Closed";
+    } | {
+        readonly _tag: "DeactivatedItem";
+    } | {
+        readonly _tag: "CompletedScrollIntoView";
+    } | {
+        readonly _tag: "CompletedClickItem";
+    } | {
+        readonly _tag: "Opened";
+        readonly maybeActiveItemIndex: Option.Option<number>;
+    } | {
+        readonly _tag: "BlurredItems";
+    } | {
+        readonly _tag: "ActivatedItem";
+        readonly index: number;
+        readonly activationTrigger: "Pointer" | "Keyboard";
+    } | {
+        readonly _tag: "SelectedItem";
+        readonly item: string;
+    } | {
+        readonly _tag: "RequestedItemClick";
+        readonly index: number;
+    } | {
+        readonly _tag: "Searched";
+        readonly key: string;
+        readonly maybeTargetIndex: Option.Option<number>;
+    } | {
+        readonly _tag: "ClearedSearch";
+        readonly version: number;
+    } | {
+        readonly _tag: "MovedPointerOverItem";
+        readonly index: number;
+        readonly screenX: number;
+        readonly screenY: number;
+    } | {
+        readonly _tag: "CompletedFocusItems";
+    } | {
+        readonly _tag: "CompletedAnchorListbox";
+    } | {
+        readonly _tag: "CompletedPortalListboxBackdrop";
+    } | {
+        readonly _tag: "GotAnimationMessage";
+        readonly message: {
+            readonly _tag: "Showed";
+        } | {
+            readonly _tag: "Hid";
+        } | {
+            readonly _tag: "AdvancedAnimationFrame";
+        } | {
+            readonly _tag: "EndedAnimation";
+        };
+    } | {
+        readonly _tag: "PressedPointerOnButton";
+        readonly pointerType: string;
+        readonly button: number;
+    }, never, never>;
+}>[], Option.Option<Readonly<{
+    readonly _tag: "Selected";
+    readonly value: string;
+    readonly wasAdded: boolean;
+}>>];
+type UpdateReturn = ReturnType<typeof update>;
+/** Programmatically opens the listbox, updating the model and returning
+ *  focus and modal commands. Use this in domain-event handlers to open the listbox. */
+export declare const open: (model: Model) => UpdateReturn;
+/** Programmatically closes the listbox, updating the model and returning
+ *  focus and modal commands. Use this in domain-event handlers to close the listbox. */
+export declare const close: (model: Model) => UpdateReturn;
+/** Programmatically selects an item in the single-select listbox, closing the listbox and emitting a `Selected({ value, wasAdded: true })` OutMessage. */
+export declare const selectItem: (model: Model, item: string) => UpdateReturn;
+/** Reflects an externally-sourced selection onto the model without
+ *  emitting an OutMessage or running the user-selection side effects (no
+ *  close, no focus). Use this to mirror external truth (a URL parameter,
+ *  restored storage, a server push) onto the listbox's selection.
+ *  Contrast with `selectItem`, which represents a user or programmatic
+ *  *choice*: it closes the listbox, restores focus, and emits `Selected`.
+ *  `reflect` returns the model directly because it produces no commands and
+ *  no OutMessage, so a parent reflecting external state cannot
+ *  accidentally echo it back out. */
+export declare const reflectSelectedItem: Reflect<Model, Option.Option<string>>;
+/** Per-render view inputs passed to the view via `h.submodel`'s `viewInputs` field. */
+export type ViewInputs<Item, Value extends string = string> = BaseViewInputs<Item, Value>;
+/** Pairs the single-select listbox's `view` and `update` (and programmatic
+ *  helpers) behind a single Item-typed entry point. Declaring the listbox
+ *  once at module scope ensures the view's `Item` type and the update's
+ *  OutMessage `item` type can't drift:
+ *
+ *  ```ts
+ *  const ColorListbox = Listbox.create<Color>()
+ *
+ *  // In view:
+ *  h.submodel({ view: ColorListbox.view, ... })
+ *
+ *  // In update:
+ *  const [next, commands, maybeOutMessage] = ColorListbox.update(model, message)
+ *  // maybeOutMessage: Option<Listbox.OutMessage<Color>>
+ *  ```
+ *
+ *  Two type params support object-typed items with an `itemToValue`
+ *  extractor: pass `<Person, string>` when items are objects whose
+ *  extracted value is a plain string. `Value` defaults to `Item` when
+ *  `Item extends string`, else defaults to `string`. */
+export declare const create: <Item = string, Value extends string = Item extends string ? Item : string>() => Readonly<{
+    view: SubmodelView<Model, Message, BaseViewInputs<Item, Value>>;
+    update: (model: Model, message: Message) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Value>>];
+    selectItem: (model: Model, item: Value) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Value>>];
+    open: (model: Model) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Value>>];
+    close: (model: Model) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Value>>];
+    reflectSelectedItem: Reflect<Model, Option.Option<Value>>;
+}>;
+export {};
+//# sourceMappingURL=single.d.ts.map

package/dist/listbox/single.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single.d.ts","sourceRoot":"","sources":["../../src/listbox/single.ts"],"names":[],"mappings":"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"}

package/dist/listbox/single.js

@@ -0,0 +1,73 @@
+import { Array, Function, Option, Schema as S } from 'effect';
+import { evo } from 'foldkit/struct';
+import { BaseModel, Closed, Opened, SelectedItem, Selected as SharedSelected, baseInit, makeUpdate, makeView, } from './shared.js';
+// MODEL
+/** Schema for the listbox component's state, tracking open/closed status, active item, selected item, activation trigger, and typeahead search. */
+export const Model = S.Struct({
+    ...BaseModel.fields,
+    maybeSelectedItem: S.Option(S.String),
+});
+/** Creates an initial single-select listbox model from a config. Defaults to closed with no active item and no selection. */
+export const init = (config) => ({
+    ...baseInit(config),
+    maybeSelectedItem: Option.fromNullishOr(config.selectedItem),
+});
+// UPDATE
+/** Processes a listbox message and returns the next model, commands, and optional OutMessage. Closes the listbox on selection (single-select behavior); emits a `Selected({ value, wasAdded: true })` OutMessage. */
+export const update = makeUpdate((model, item, context) => context.closeWithFocus(evo(model, { maybeSelectedItem: () => Option.some(item) }), Option.some(SharedSelected({ value: item, wasAdded: true }))));
+/** Programmatically opens the listbox, updating the model and returning
+ *  focus and modal commands. Use this in domain-event handlers to open the listbox. */
+export const open = (model) => update(model, Opened({ maybeActiveItemIndex: Option.none() }));
+/** Programmatically closes the listbox, updating the model and returning
+ *  focus and modal commands. Use this in domain-event handlers to close the listbox. */
+export const close = (model) => update(model, Closed());
+/** Programmatically selects an item in the single-select listbox, closing the listbox and emitting a `Selected({ value, wasAdded: true })` OutMessage. */
+export const selectItem = (model, item) => update(model, SelectedItem({ item }));
+/** Reflects an externally-sourced selection onto the model without
+ *  emitting an OutMessage or running the user-selection side effects (no
+ *  close, no focus). Use this to mirror external truth (a URL parameter,
+ *  restored storage, a server push) onto the listbox's selection.
+ *  Contrast with `selectItem`, which represents a user or programmatic
+ *  *choice*: it closes the listbox, restores focus, and emits `Selected`.
+ *  `reflect` returns the model directly because it produces no commands and
+ *  no OutMessage, so a parent reflecting external state cannot
+ *  accidentally echo it back out. */
+export const reflectSelectedItem = Function.dual(2, (model, maybeItem) => evo(model, { maybeSelectedItem: () => maybeItem }));
+const internalView = makeView({
+    isItemSelected: (model, itemValue) => Option.exists(model.maybeSelectedItem, selectedItem => selectedItem === itemValue),
+    selectedItemIndex: (model, items, itemToValue) => Option.flatMap(model.maybeSelectedItem, selectedItem => Array.findFirstIndex(items, item => itemToValue(item) === selectedItem)),
+    ariaMultiSelectable: false,
+});
+/** Pairs the single-select listbox's `view` and `update` (and programmatic
+ *  helpers) behind a single Item-typed entry point. Declaring the listbox
+ *  once at module scope ensures the view's `Item` type and the update's
+ *  OutMessage `item` type can't drift:
+ *
+ *  ```ts
+ *  const ColorListbox = Listbox.create<Color>()
+ *
+ *  // In view:
+ *  h.submodel({ view: ColorListbox.view, ... })
+ *
+ *  // In update:
+ *  const [next, commands, maybeOutMessage] = ColorListbox.update(model, message)
+ *  // maybeOutMessage: Option<Listbox.OutMessage<Color>>
+ *  ```
+ *
+ *  Two type params support object-typed items with an `itemToValue`
+ *  extractor: pass `<Person, string>` when items are objects whose
+ *  extracted value is a plain string. `Value` defaults to `Item` when
+ *  `Item extends string`, else defaults to `string`. */
+export const create = () => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const typedUpdate = update;
+    return {
+        view: internalView(),
+        update: typedUpdate,
+        selectItem: (model, item) => typedUpdate(model, SelectedItem({ item })),
+        open: model => typedUpdate(model, Opened({ maybeActiveItemIndex: Option.none() })),
+        close: model => typedUpdate(model, Closed()),
+        /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */
+        reflectSelectedItem: reflectSelectedItem,
+    };
+};

package/dist/menu/index.d.ts

@@ -0,0 +1,368 @@
+import { Effect, Option, Schema as S } from 'effect';
+import * as Command from 'foldkit/command';
+import { type ChildAttribute, type Html } from 'foldkit/html';
+import * as Mount from 'foldkit/mount';
+import { type View as SubmodelView } from 'foldkit/submodel';
+import { AnchorConfig } from '../anchor.js';
+import { groupContiguous } from '../group.js';
+import { resolveTypeaheadMatch } from '../typeahead.js';
+/** Schema for the activation trigger: whether the user interacted via mouse or keyboard. */
+export declare const ActivationTrigger: S.Literals<readonly ["Pointer", "Keyboard"]>;
+export type ActivationTrigger = typeof ActivationTrigger.Type;
+/** Schema for the menu component's state, tracking open/closed status, active item, activation trigger, and typeahead search. */
+export declare const Model: S.Struct<{
+    readonly id: S.String;
+    readonly isOpen: S.Boolean;
+    readonly isAnimated: S.Boolean;
+    readonly isModal: S.Boolean;
+    readonly animation: S.Struct<{
+        readonly id: S.String;
+        readonly isShowing: S.Boolean;
+        readonly transitionState: S.Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>;
+    }>;
+    readonly maybeActiveItemIndex: S.Option<S.Number>;
+    readonly activationTrigger: S.Literals<readonly ["Pointer", "Keyboard"]>;
+    readonly searchQuery: S.String;
+    readonly searchVersion: S.Number;
+    readonly maybeLastPointerPosition: S.Option<S.Struct<{
+        readonly screenX: S.Number;
+        readonly screenY: S.Number;
+    }>>;
+    readonly maybeLastButtonPointerType: S.Option<S.String>;
+    readonly maybePointerOrigin: S.Option<S.Struct<{
+        readonly screenX: S.Number;
+        readonly screenY: S.Number;
+        readonly timeStamp: S.Number;
+    }>>;
+}>;
+export type Model = typeof Model.Type;
+/** Sent when the menu opens via button click or keyboard. Contains an optional initial active item index: None for pointer, Some for keyboard. */
+export declare const Opened: import("foldkit/schema").CallableTaggedStruct<"Opened", {
+    maybeActiveItemIndex: S.Option<S.Number>;
+}>;
+/** Sent when the menu closes via Escape key or backdrop click. */
+export declare const Closed: import("foldkit/schema").CallableTaggedStruct<"Closed", {}>;
+/** Sent when the menu items container loses focus. */
+export declare const BlurredItems: import("foldkit/schema").CallableTaggedStruct<"BlurredItems", {}>;
+/** Sent when an item is highlighted via arrow keys or mouse hover. Includes activation trigger. */
+export declare const ActivatedItem: import("foldkit/schema").CallableTaggedStruct<"ActivatedItem", {
+    index: S.Number;
+    activationTrigger: S.Literals<readonly ["Pointer", "Keyboard"]>;
+}>;
+/** Sent when the mouse leaves an enabled item. */
+export declare const DeactivatedItem: import("foldkit/schema").CallableTaggedStruct<"DeactivatedItem", {}>;
+/** Sent when an item is selected via Enter, Space, or click. */
+export declare const SelectedItem: import("foldkit/schema").CallableTaggedStruct<"SelectedItem", {
+    index: S.Number;
+    item: S.String;
+}>;
+/** Sent when Enter or Space is pressed on the active item, triggering a programmatic click on the DOM element. */
+export declare const RequestedItemClick: import("foldkit/schema").CallableTaggedStruct<"RequestedItemClick", {
+    index: S.Number;
+}>;
+/** Sent when a printable character is typed for typeahead search. */
+export declare const Searched: import("foldkit/schema").CallableTaggedStruct<"Searched", {
+    key: S.String;
+    maybeTargetIndex: S.Option<S.Number>;
+}>;
+/** Sent after the search debounce period to clear the accumulated query. */
+export declare const ClearedSearch: import("foldkit/schema").CallableTaggedStruct<"ClearedSearch", {
+    version: S.Number;
+}>;
+/** Sent when the pointer moves over a menu item, carrying screen coordinates for tracked-pointer comparison. */
+export declare const MovedPointerOverItem: import("foldkit/schema").CallableTaggedStruct<"MovedPointerOverItem", {
+    index: S.Number;
+    screenX: S.Number;
+    screenY: S.Number;
+}>;
+/** Sent when the focus-items command completes after opening the menu. */
+export declare const CompletedFocusItems: import("foldkit/schema").CallableTaggedStruct<"CompletedFocusItems", {}>;
+/** Sent when the focus-button command completes after closing or selecting. */
+export declare const CompletedFocusButton: import("foldkit/schema").CallableTaggedStruct<"CompletedFocusButton", {}>;
+/** Sent when the scroll lock command completes. */
+export declare const CompletedLockScroll: import("foldkit/schema").CallableTaggedStruct<"CompletedLockScroll", {}>;
+/** Sent when the scroll unlock command completes. */
+export declare const CompletedUnlockScroll: import("foldkit/schema").CallableTaggedStruct<"CompletedUnlockScroll", {}>;
+/** Sent when the inert-others command completes. */
+export declare const CompletedInertOthers: import("foldkit/schema").CallableTaggedStruct<"CompletedInertOthers", {}>;
+/** Sent when the restore-inert command completes. */
+export declare const CompletedRestoreInert: import("foldkit/schema").CallableTaggedStruct<"CompletedRestoreInert", {}>;
+/** Sent when the scroll-into-view command completes after keyboard activation. */
+export declare const CompletedScrollIntoView: import("foldkit/schema").CallableTaggedStruct<"CompletedScrollIntoView", {}>;
+/** Sent when the programmatic click command completes. */
+export declare const CompletedClickItem: import("foldkit/schema").CallableTaggedStruct<"CompletedClickItem", {}>;
+/** Sent when a mouse click on the button is ignored because pointer-down already handled the toggle. */
+export declare const IgnoredMouseClick: import("foldkit/schema").CallableTaggedStruct<"IgnoredMouseClick", {}>;
+/** Sent when a Space key-up is captured to prevent page scrolling. */
+export declare const SuppressedSpaceScroll: import("foldkit/schema").CallableTaggedStruct<"SuppressedSpaceScroll", {}>;
+/** Sent when the menu items panel mounts and Floating UI has positioned it. Update no-ops; the side effect is the act of positioning, surfaced for DevTools observability. */
+export declare const CompletedAnchorMenu: import("foldkit/schema").CallableTaggedStruct<"CompletedAnchorMenu", {}>;
+/** Sent when the menu backdrop mounts and is portaled to the document body. Update no-ops; surfaces the portal side effect for DevTools. */
+export declare const CompletedPortalMenuBackdrop: import("foldkit/schema").CallableTaggedStruct<"CompletedPortalMenuBackdrop", {}>;
+/** Wraps an Animation submodel message for delegation. */
+export declare const GotAnimationMessage: import("foldkit/schema").CallableTaggedStruct<"GotAnimationMessage", {
+    message: S.Union<[import("foldkit/schema").CallableTaggedStruct<"Showed", {}>, import("foldkit/schema").CallableTaggedStruct<"Hid", {}>, import("foldkit/schema").CallableTaggedStruct<"AdvancedAnimationFrame", {}>, import("foldkit/schema").CallableTaggedStruct<"EndedAnimation", {}>]>;
+}>;
+/** Sent when the user presses a pointer device on the menu button. Records pointer type and toggles for mouse. */
+export declare const PressedPointerOnButton: import("foldkit/schema").CallableTaggedStruct<"PressedPointerOnButton", {
+    pointerType: S.String;
+    button: S.Number;
+    screenX: S.Number;
+    screenY: S.Number;
+    timeStamp: S.Number;
+}>;
+/** Sent when the user releases a pointer on the items container, enabling drag-to-select for mouse. */
+export declare const ReleasedPointerOnItems: import("foldkit/schema").CallableTaggedStruct<"ReleasedPointerOnItems", {
+    screenX: S.Number;
+    screenY: S.Number;
+    timeStamp: S.Number;
+}>;
+/** Union of all messages the menu component can produce. */
+export declare const Message: S.Union<[
+    typeof Opened,
+    typeof Closed,
+    typeof BlurredItems,
+    typeof ActivatedItem,
+    typeof DeactivatedItem,
+    typeof SelectedItem,
+    typeof MovedPointerOverItem,
+    typeof RequestedItemClick,
+    typeof Searched,
+    typeof ClearedSearch,
+    typeof CompletedFocusItems,
+    typeof CompletedFocusButton,
+    typeof CompletedLockScroll,
+    typeof CompletedUnlockScroll,
+    typeof CompletedInertOthers,
+    typeof CompletedRestoreInert,
+    typeof CompletedScrollIntoView,
+    typeof CompletedClickItem,
+    typeof IgnoredMouseClick,
+    typeof SuppressedSpaceScroll,
+    typeof CompletedAnchorMenu,
+    typeof CompletedPortalMenuBackdrop,
+    typeof GotAnimationMessage,
+    typeof PressedPointerOnButton,
+    typeof ReleasedPointerOnItems
+]>;
+export type Message = typeof Message.Type;
+/** Sent to the parent when a menu item is selected. Carries both the selected value (from the `viewInputs.items` array supplied at view time) and its index. The menu has already closed when this fires; the parent does not need to dispatch `Menu.close`. */
+export declare const Selected: import("foldkit/schema").CallableTaggedStruct<"Selected", {
+    value: S.String;
+    index: S.Number;
+}>;
+export type Selected<Value extends string = string> = Readonly<{
+    readonly _tag: 'Selected';
+    readonly value: Value;
+    readonly index: number;
+}>;
+/** Union of out-messages the menu component can produce. Surfaced as the third element of `update`'s return tuple and pattern-matched by the parent. */
+export declare const OutMessage: S.Union<readonly [import("foldkit/schema").CallableTaggedStruct<"Selected", {
+    value: S.String;
+    index: S.Number;
+}>]>;
+/** Generic over `Value extends string` so consumers using the typed
+ *  `Menu.create<MyUnion>()` factory receive `value: MyUnion` in the
+ *  `Selected` OutMessage. Defaults to `string`. */
+export type OutMessage<Value extends string = string> = Selected<Value>;
+export type Opened = typeof Opened.Type;
+export type Closed = typeof Closed.Type;
+export type BlurredItems = typeof BlurredItems.Type;
+export type ActivatedItem = typeof ActivatedItem.Type;
+export type DeactivatedItem = typeof DeactivatedItem.Type;
+export type SelectedItem = typeof SelectedItem.Type;
+export type MovedPointerOverItem = typeof MovedPointerOverItem.Type;
+export type RequestedItemClick = typeof RequestedItemClick.Type;
+export type Searched = typeof Searched.Type;
+export type ClearedSearch = typeof ClearedSearch.Type;
+export type IgnoredMouseClick = typeof IgnoredMouseClick.Type;
+export type SuppressedSpaceScroll = typeof SuppressedSpaceScroll.Type;
+export type PressedPointerOnButton = typeof PressedPointerOnButton.Type;
+export type ReleasedPointerOnItems = typeof ReleasedPointerOnItems.Type;
+/** Configuration for creating a menu model with `init`. `isAnimated` enables animation coordination (default `false`). `isModal` locks page scroll and inerts other elements when open (default `false`). */
+export type InitConfig = Readonly<{
+    id: string;
+    isAnimated?: boolean;
+    isModal?: boolean;
+}>;
+/** Creates an initial menu model from a config. Defaults to closed with no active item. */
+export declare const init: (config: InitConfig) => Model;
+type UpdateReturn = readonly [
+    Model,
+    ReadonlyArray<Command.Command<Message>>,
+    Option.Option<OutMessage>
+];
+/** Prevents page scrolling while the menu is open. */
+export declare const LockScroll: Command.CommandDefinitionNoArgs<"LockScroll", Effect.Effect<{
+    readonly _tag: "CompletedLockScroll";
+}, never, never>>;
+/** Re-enables page scrolling after the menu closes. */
+export declare const UnlockScroll: Command.CommandDefinitionNoArgs<"UnlockScroll", Effect.Effect<{
+    readonly _tag: "CompletedUnlockScroll";
+}, never, never>>;
+/** Marks all elements outside the menu as inert for modal behavior. */
+export declare const InertOthers: Command.CommandDefinitionWithArgs<"InertOthers", {
+    id: S.String;
+}, Effect.Effect<{
+    readonly _tag: "CompletedInertOthers";
+}, never, never>>;
+/** Removes the inert attribute from elements outside the menu. */
+export declare const RestoreInert: Command.CommandDefinitionWithArgs<"RestoreInert", {
+    id: S.String;
+}, Effect.Effect<{
+    readonly _tag: "CompletedRestoreInert";
+}, never, never>>;
+/** Moves focus to the menu items container after opening. */
+export declare const FocusItems: Command.CommandDefinitionWithArgs<"FocusItems", {
+    id: S.String;
+}, Effect.Effect<{
+    readonly _tag: "CompletedFocusItems";
+}, never, never>>;
+/** Moves focus back to the menu button after closing. */
+export declare const FocusButton: Command.CommandDefinitionWithArgs<"FocusButton", {
+    id: S.String;
+}, Effect.Effect<{
+    readonly _tag: "CompletedFocusButton";
+}, never, never>>;
+/** Scrolls the active menu item into view after keyboard navigation. */
+export declare const ScrollIntoView: Command.CommandDefinitionWithArgs<"ScrollIntoView", {
+    id: S.String;
+    index: S.Number;
+}, Effect.Effect<{
+    readonly _tag: "CompletedScrollIntoView";
+}, never, never>>;
+/** Programmatically clicks the active menu item's DOM element. */
+export declare const ClickItem: Command.CommandDefinitionWithArgs<"ClickItem", {
+    id: S.String;
+    index: S.Number;
+}, Effect.Effect<{
+    readonly _tag: "CompletedClickItem";
+}, never, never>>;
+/** Waits for the typeahead search debounce period before clearing the query. */
+export declare const DelayClearSearch: Command.CommandDefinitionWithArgs<"DelayClearSearch", {
+    version: S.Number;
+}, Effect.Effect<{
+    readonly _tag: "ClearedSearch";
+    readonly version: number;
+}, never, never>>;
+/** Detects whether the menu button moved or the leave animation ended. Whichever comes first; both outcomes signal the Animation submodel that leave is complete. */
+export declare const DetectMovementOrAnimationEnd: Command.CommandDefinitionWithArgs<"DetectMovementOrAnimationEnd", {
+    id: S.String;
+}, Effect.Effect<{
+    readonly _tag: "GotAnimationMessage";
+    readonly message: {
+        readonly _tag: "Showed";
+    } | {
+        readonly _tag: "Hid";
+    } | {
+        readonly _tag: "AdvancedAnimationFrame";
+    } | {
+        readonly _tag: "EndedAnimation";
+    };
+}, never, never>>;
+/** Processes a menu message and returns the next model and commands. */
+export declare const update: (model: Model, message: Message) => UpdateReturn;
+/** The anchor-positioning Mount this Menu renders on its panel. The panel is
+ *  always anchored to the button via Floating UI and portaled to the document
+ *  body (opt out of portaling with `anchor.portal: false`), so it escapes
+ *  ancestor stacking contexts and overflow clipping. Exposed so Scene tests
+ *  can call `Scene.Mount.resolve(AnchorMenu, CompletedAnchorMenu())`. */
+export declare const AnchorMenu: Mount.MountDefinitionWithArgs<"AnchorMenu", {
+    buttonId: S.String;
+    anchor: S.Struct<{
+        readonly placement: S.optional<S.Literals<readonly ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"]>>;
+        readonly gap: S.optional<S.Number>;
+        readonly offset: S.optional<S.Number>;
+        readonly padding: S.optional<S.Number>;
+        readonly portal: S.optional<S.Boolean>;
+    }>;
+}, {
+    readonly _tag: "CompletedAnchorMenu";
+}>;
+/** The backdrop-portaling Mount this Menu renders. Exposed so Scene tests can
+ *  call `Scene.Mount.resolve(PortalMenuBackdrop, CompletedPortalMenuBackdrop())` to
+ *  acknowledge the mount produced by the rendered backdrop. */
+export declare const PortalMenuBackdrop: Mount.MountDefinitionNoArgs<"PortalMenuBackdrop", {
+    readonly _tag: "CompletedPortalMenuBackdrop";
+}>;
+/** Programmatically opens the menu, updating the model and returning
+ *  focus and modal commands. Use this in domain-event handlers to open the menu. */
+export declare const open: (model: Model) => UpdateReturn;
+/** Programmatically closes the menu, updating the model and returning
+ *  focus and modal commands. Use this in domain-event handlers to close the menu. */
+export declare const close: (model: Model) => UpdateReturn;
+/** Programmatically selects a menu item, closing the menu and returning
+ *  focus commands plus a `Selected` OutMessage. Use this in domain-event handlers. */
+export declare const selectItem: (model: Model, item: string, index: number) => UpdateReturn;
+/** Configuration for an individual menu item's appearance. */
+export type ItemConfig = Readonly<{
+    className?: string;
+    content: Html;
+}>;
+/** Configuration for a group heading rendered above a group of items. */
+export type GroupHeading = Readonly<{
+    content: Html;
+    className?: string;
+}>;
+/** Per-render view inputs passed to `view` via `h.submodel`'s `viewInputs` field.
+ *
+ *  The Menu emits a `Selected({ value, index })` OutMessage on commit.
+ *  The menu has already closed by the time this fires; consumers
+ *  pattern-match it in their `GotMenuMessage` handler to react. */
+export type ViewInputs<Item extends string> = Readonly<{
+    items: ReadonlyArray<Item>;
+    itemToConfig: (item: Item, context: Readonly<{
+        isActive: boolean;
+        isDisabled: boolean;
+    }>) => ItemConfig;
+    isItemDisabled?: (item: Item, index: number) => boolean;
+    itemToSearchText?: (item: Item, index: number) => string;
+    isButtonDisabled?: boolean;
+    buttonContent: Html;
+    buttonClassName?: string;
+    buttonAttributes?: ReadonlyArray<ChildAttribute>;
+    itemsClassName?: string;
+    itemsAttributes?: ReadonlyArray<ChildAttribute>;
+    itemsScrollClassName?: string;
+    itemsScrollAttributes?: ReadonlyArray<ChildAttribute>;
+    backdropClassName?: string;
+    backdropAttributes?: ReadonlyArray<ChildAttribute>;
+    className?: string;
+    attributes?: ReadonlyArray<ChildAttribute>;
+    itemGroupKey?: (item: Item, index: number) => string;
+    groupToHeading?: (groupKey: string) => GroupHeading | undefined;
+    groupClassName?: string;
+    groupAttributes?: ReadonlyArray<ChildAttribute>;
+    separatorClassName?: string;
+    separatorAttributes?: ReadonlyArray<ChildAttribute>;
+    anchor?: AnchorConfig;
+}>;
+export { groupContiguous, resolveTypeaheadMatch };
+/** Headless menu view with typeahead search, keyboard navigation,
+ *  and aria-activedescendant focus management. Obtained from
+ *  `Menu.create<MyItem>().view`; not exported directly. */
+type ViewForItem<Item extends string> = SubmodelView<Model, Message, ViewInputs<Item>>;
+/** Pairs the menu's `view` and `update` (and programmatic helpers)
+ *  behind a single Item-typed entry point. Declaring the menu once at
+ *  module scope ensures the view's `Item` type and the OutMessage's
+ *  `item` type can't drift:
+ *
+ *  ```ts
+ *  const ActionMenu = Menu.create<Action>()
+ *
+ *  // In view:
+ *  h.submodel({ view: ActionMenu.view, ... })
+ *
+ *  // In update:
+ *  const [next, commands, maybeOutMessage] = ActionMenu.update(model.menu, message)
+ *  // maybeOutMessage: Option<Menu.OutMessage<Action>>
+ *  ```
+ */
+export declare const create: <Item extends string = string>() => Readonly<{
+    view: ViewForItem<Item>;
+    update: (model: Model, message: Message) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
+    selectItem: (model: Model, item: Item, index: number) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
+    open: (model: Model) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
+    close: (model: Model) => readonly [Model, ReadonlyArray<Command.Command<Message>>, Option.Option<OutMessage<Item>>];
+}>;
+//# sourceMappingURL=index.d.ts.map