On this pageFunctions
Ui/Menu
/** Creates an initial menu model from a config. Defaults to closed with no active item. */
(config: InitConfig): Menu.Model/** Sent when an item is highlighted via arrow keys or mouse hover. Includes activation trigger. */
type ActivatedItem = CallableTaggedStruct<"ActivatedItem", {
activationTrigger: Literals<readonly ["Pointer", "Keyboard"]>
index: Number
}>/** Schema for the activation trigger: whether the user interacted via mouse or keyboard. */
type ActivationTrigger = Literals<readonly ["Pointer", "Keyboard"]>/** Sent when the menu items container loses focus. */
type BlurredItems = CallableTaggedStruct<"BlurredItems", {}>/** Sent when the menu closes via Escape key or backdrop click. */
type Closed = CallableTaggedStruct<"Closed", {}>/** Sent when the mouse leaves an enabled item. */
type DeactivatedItem = CallableTaggedStruct<"DeactivatedItem", {}>/** Configuration for a group heading rendered above a group of items. */
type GroupHeading = Readonly<{
className: string
content: Html
}>/** Sent when a mouse click on the button is ignored because pointer-down already handled the toggle. */
type IgnoredMouseClick = CallableTaggedStruct<"IgnoredMouseClick", {}>/** 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`). */
type InitConfig = Readonly<{
id: string
isAnimated: boolean
isModal: boolean
}>/** Configuration for an individual menu item's appearance. */
type ItemConfig = Readonly<{
className: string
content: Html
}>/** Sent when the pointer moves over a menu item, carrying screen coordinates for tracked-pointer comparison. */
type MovedPointerOverItem = CallableTaggedStruct<"MovedPointerOverItem", {
index: Number
screenX: Number
screenY: Number
}>/** Sent when the menu opens via button click or keyboard. Contains an optional initial active item index: None for pointer, Some for keyboard. */
type Opened = CallableTaggedStruct<"Opened", {
maybeActiveItemIndex: Option<Number>
}>/**
* Generic over `Value extends string` so consumers using the typed
* `Ui.Menu.create<MyUnion>()` factory receive `value: MyUnion` in the
* `Selected` OutMessage. Defaults to `string`.
*/
type OutMessage = Selected<Value>/** Sent when the user presses a pointer device on the menu button. Records pointer type and toggles for mouse. */
type PressedPointerOnButton = CallableTaggedStruct<"PressedPointerOnButton", {
button: Number
pointerType: String
screenX: Number
screenY: Number
timeStamp: Number
}>/** Sent when the user releases a pointer on the items container, enabling drag-to-select for mouse. */
type ReleasedPointerOnItems = CallableTaggedStruct<"ReleasedPointerOnItems", {
screenX: Number
screenY: Number
timeStamp: Number
}>/** Sent when Enter or Space is pressed on the active item, triggering a programmatic click on the DOM element. */
type RequestedItemClick = CallableTaggedStruct<"RequestedItemClick", {
index: Number
}>/** Sent when a printable character is typed for typeahead search. */
type Searched = CallableTaggedStruct<"Searched", {
key: String
maybeTargetIndex: Option<Number>
}>/** 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 `Ui.Menu.close`. */
type Selected = Readonly<{
_tag: "Selected"
index: number
value: Value
}>/** Sent when a Space key-up is captured to prevent page scrolling. */
type SuppressedSpaceScroll = CallableTaggedStruct<"SuppressedSpaceScroll", {}>/**
* 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.
*/
type ViewInputs = Readonly<{
anchor: AnchorConfig
attributes: ReadonlyArray<ChildAttribute>
backdropAttributes: ReadonlyArray<ChildAttribute>
backdropClassName: string
buttonAttributes: ReadonlyArray<ChildAttribute>
buttonClassName: string
buttonContent: Html
className: string
groupAttributes: ReadonlyArray<ChildAttribute>
groupClassName: string
groupToHeading: (groupKey: string) => GroupHeading | undefined
isButtonDisabled: boolean
isItemDisabled: (item: Item, index: number) => boolean
itemGroupKey: (item: Item, index: number) => string
items: ReadonlyArray<Item>
itemsAttributes: ReadonlyArray<ChildAttribute>
itemsClassName: string
itemsScrollAttributes: ReadonlyArray<ChildAttribute>
itemsScrollClassName: string
itemToConfig: (item: Item, context: Readonly<{
isActive: boolean
isDisabled: boolean
}>) => ItemConfig
itemToSearchText: (item: Item, index: number) => string
separatorAttributes: ReadonlyArray<ChildAttribute>
separatorClassName: string
}>/**
* The anchor-positioning Mount this Menu renders on its panel. Exposed so
* Scene tests can call `Scene.Mount.resolve(AnchorMenu, CompletedAnchorMenu())`
* to acknowledge the mount produced by the rendered panel.
*/
const AnchorMenu: MountDefinitionWithArgs<"AnchorMenu", {
anchor: Struct<{
gap: optional<Number>
offset: optional<Number>
padding: optional<Number>
placement: optional<Literals<readonly ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"]>>
portal: optional<Boolean>
}>
buttonId: String
}, {
_tag: "CompletedAnchorMenu"
}>/** Sent after the search debounce period to clear the accumulated query. */
const ClearedSearch: CallableTaggedStruct<"ClearedSearch", {
version: Number
}>/** Programmatically clicks the active menu item's DOM element. */
const ClickItem: CommandDefinitionWithArgs<"ClickItem", {
id: String
index: Number
}, Effect<{
_tag: "CompletedClickItem"
}, never, never>>/** 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. */
const CompletedAnchorMenu: CallableTaggedStruct<"CompletedAnchorMenu", {}>/** Sent when the programmatic click command completes. */
const CompletedClickItem: CallableTaggedStruct<"CompletedClickItem", {}>/** Sent when the focus-button command completes after closing or selecting. */
const CompletedFocusButton: CallableTaggedStruct<"CompletedFocusButton", {}>/** Sent when the focus-items command completes after opening the menu. */
const CompletedFocusItems: CallableTaggedStruct<"CompletedFocusItems", {}>/** Sent when the inert-others command completes. */
const CompletedInertOthers: CallableTaggedStruct<"CompletedInertOthers", {}>/** Sent when the scroll lock command completes. */
const CompletedLockScroll: CallableTaggedStruct<"CompletedLockScroll", {}>/** Sent when the menu backdrop mounts and is portaled to the document body. Update no-ops; surfaces the portal side effect for DevTools. */
const CompletedPortalMenuBackdrop: CallableTaggedStruct<"CompletedPortalMenuBackdrop", {}>/** Sent when the restore-inert command completes. */
const CompletedRestoreInert: CallableTaggedStruct<"CompletedRestoreInert", {}>/** Sent when the scroll-into-view command completes after keyboard activation. */
const CompletedScrollIntoView: CallableTaggedStruct<"CompletedScrollIntoView", {}>/** Sent when the scroll unlock command completes. */
const CompletedUnlockScroll: CallableTaggedStruct<"CompletedUnlockScroll", {}>/** Waits for the typeahead search debounce period before clearing the query. */
const DelayClearSearch: CommandDefinitionWithArgs<"DelayClearSearch", {
version: Number
}, Effect<{
_tag: "ClearedSearch"
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. */
const DetectMovementOrAnimationEnd: CommandDefinitionWithArgs<"DetectMovementOrAnimationEnd", {
id: String
}, Effect<{
_tag: "GotAnimationMessage"
message: {
_tag: "Showed"
} | {
_tag: "Hid"
} | {
_tag: "AdvancedAnimationFrame"
} | {
_tag: "EndedAnimation"
}
}, never, never>>/** Moves focus back to the menu button after closing. */
const FocusButton: CommandDefinitionWithArgs<"FocusButton", {
id: String
}, Effect<{
_tag: "CompletedFocusButton"
}, never, never>>/** Moves focus to the menu items container after opening. */
const FocusItems: CommandDefinitionWithArgs<"FocusItems", {
id: String
}, Effect<{
_tag: "CompletedFocusItems"
}, never, never>>/** Wraps an Animation submodel message for delegation. */
const GotAnimationMessage: CallableTaggedStruct<"GotAnimationMessage", {
message: Union<[CallableTaggedStruct<"Showed", {}>, CallableTaggedStruct<"Hid", {}>, CallableTaggedStruct<"AdvancedAnimationFrame", {}>, CallableTaggedStruct<"EndedAnimation", {}>]>
}>/** Marks all elements outside the menu as inert for modal behavior. */
const InertOthers: CommandDefinitionWithArgs<"InertOthers", {
id: String
}, Effect<{
_tag: "CompletedInertOthers"
}, never, never>>/** Prevents page scrolling while the menu is open. */
const LockScroll: CommandDefinitionNoArgs<"LockScroll", Effect<{
_tag: "CompletedLockScroll"
}, never, never>>/** Union of all messages the menu component can produce. */
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]>/** Schema for the menu component's state, tracking open/closed status, active item, activation trigger, and typeahead search. */
const Model: Struct<{
activationTrigger: Literals<readonly ["Pointer", "Keyboard"]>
animation: Struct<{
id: String
isShowing: Boolean
transitionState: Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>
}>
id: String
isAnimated: Boolean
isModal: Boolean
isOpen: Boolean
maybeActiveItemIndex: Option<Number>
maybeLastButtonPointerType: Option<String>
maybeLastPointerPosition: Option<Struct<{
screenX: Number
screenY: Number
}>>
maybePointerOrigin: Option<Struct<{
screenX: Number
screenY: Number
timeStamp: Number
}>>
searchQuery: String
searchVersion: 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. */
const OutMessage: Union<readonly [
CallableTaggedStruct<"Selected", {
index: Number
value: String
}>
]>/**
* 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.
*/
const PortalMenuBackdrop: MountDefinitionNoArgs<"PortalMenuBackdrop", {
_tag: "CompletedPortalMenuBackdrop"
}>/** Removes the inert attribute from elements outside the menu. */
const RestoreInert: CommandDefinitionWithArgs<"RestoreInert", {
id: String
}, Effect<{
_tag: "CompletedRestoreInert"
}, never, never>>/** Scrolls the active menu item into view after keyboard navigation. */
const ScrollIntoView: CommandDefinitionWithArgs<"ScrollIntoView", {
id: String
index: Number
}, Effect<{
_tag: "CompletedScrollIntoView"
}, never, never>>/** 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 `Ui.Menu.close`. */
const Selected: CallableTaggedStruct<"Selected", {
index: Number
value: String
}>/** Sent when an item is selected via Enter, Space, or click. */
const SelectedItem: CallableTaggedStruct<"SelectedItem", {
index: Number
item: String
}>