On this pageFunctions
Ui/Listbox
/** Creates an initial single-select listbox model from a config. Defaults to closed with no active item and no selection. */
(config: InitConfig): Listbox.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 listbox items container loses focus. */
type BlurredItems = CallableTaggedStruct<"BlurredItems", {}>/** Sent when the listbox 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 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). */
type InitConfig = BaseInitConfig & Readonly<{
selectedItem: string
}>/** Configuration for an individual listbox item's appearance. */
type ItemConfig = Readonly<{
className: string
content: Html
}>/** Sent when the pointer moves over a listbox item, carrying screen coordinates for tracked-pointer comparison. */
type MovedPointerOverItem = CallableTaggedStruct<"MovedPointerOverItem", {
index: Number
screenX: Number
screenY: Number
}>/** Sent when the listbox 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 who create the listbox
* via `Ui.Listbox.create<MyUnion>()` receive `value: MyUnion` in the
* `Selected` OutMessage from the factory's `update`, instead of
* `value: string`. Defaults to `string`.
*/
type OutMessage = Selected<Value>/** Sent when the user presses a pointer device on the listbox button. Records pointer type for click handling. */
type PressedPointerOnButton = CallableTaggedStruct<"PressedPointerOnButton", {
button: Number
pointerType: String
}>/** 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 when a single-select listbox commits a selection, or when a multi-select listbox toggles an item. Generic over `Value extends string`: the runtime schema stores `value: string`, but the type-level OutMessage exposes `value: Value` so consumers who supply `items: ReadonlyArray<MyUnion>` receive `value: MyUnion` from `update<MyUnion>` without casting. The cast is fenced inside this module's `update` return, sound because the value was extracted from the items array the consumer supplied. */
type Selected = Readonly<{
_tag: "Selected"
value: Value
wasAdded: boolean
}>/** Sent when a Space key-up is captured to prevent page scrolling. */
type SuppressedSpaceScroll = CallableTaggedStruct<"SuppressedSpaceScroll", {}>/** Per-render view inputs passed to the view via `h.submodel`'s `viewInputs` field. */
type ViewInputs = BaseViewInputs<Item, Value>/**
* The anchor-positioning Mount this Listbox renders when an anchor is
* configured. Exposed so Scene tests can call
* `Scene.Mount.resolve(AnchorListbox, CompletedAnchorListbox())`.
*/
const AnchorListbox: MountDefinitionWithArgs<"AnchorListbox", {
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: "CompletedAnchorListbox"
}>/** Sent after the search debounce period to clear the accumulated query. */
const ClearedSearch: CallableTaggedStruct<"ClearedSearch", {
version: Number
}>/** Programmatically clicks the active listbox item's DOM element. */
const ClickItem: CommandDefinitionWithArgs<"ClickItem", {
id: String
index: Number
}, Effect<{
_tag: "CompletedClickItem"
}, never, never>>/** Sent when the listbox items panel mounts and Floating UI has positioned it. Update no-ops; surfaces the positioning side effect for DevTools. */
const CompletedAnchorListbox: CallableTaggedStruct<"CompletedAnchorListbox", {}>/** Sent when the programmatic item click command completes. */
const CompletedClickItem: CallableTaggedStruct<"CompletedClickItem", {}>/** Sent when the focus-button command completes after closing. */
const CompletedFocusButton: CallableTaggedStruct<"CompletedFocusButton", {}>/** Sent when the focus-items command completes after opening. */
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 listbox backdrop mounts and is portaled to the document body. Update no-ops; surfaces the portal side effect for DevTools. */
const CompletedPortalListboxBackdrop: CallableTaggedStruct<"CompletedPortalListboxBackdrop", {}>/** 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 listbox 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 listbox button after closing. */
const FocusButton: CommandDefinitionWithArgs<"FocusButton", {
id: String
}, Effect<{
_tag: "CompletedFocusButton"
}, never, never>>/** Moves focus to the listbox 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 listbox as inert for modal behavior. */
const InertOthers: CommandDefinitionWithArgs<"InertOthers", {
id: String
}, Effect<{
_tag: "CompletedInertOthers"
}, never, never>>/** Prevents page scrolling while the listbox is open in modal mode. */
const LockScroll: CommandDefinitionNoArgs<"LockScroll", Effect<{
_tag: "CompletedLockScroll"
}, never, never>>/** Union of all messages the listbox 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 CompletedLockScroll, typeof CompletedUnlockScroll, typeof CompletedInertOthers, typeof CompletedRestoreInert, typeof CompletedFocusButton, typeof CompletedFocusItems, typeof CompletedScrollIntoView, typeof CompletedClickItem, typeof IgnoredMouseClick, typeof SuppressedSpaceScroll, typeof CompletedAnchorListbox, typeof CompletedPortalListboxBackdrop, typeof GotAnimationMessage, typeof PressedPointerOnButton]>/** Schema for the listbox component's state, tracking open/closed status, active item, selected 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
}>>
maybeSelectedItem: Option<String>
orientation: Literals<readonly ["Vertical", "Horizontal"]>
searchQuery: String
searchVersion: Number
}>/** Schema for the listbox orientation: whether items flow vertically or horizontally. */
const Orientation: Literals<readonly ["Vertical", "Horizontal"]>/** Union of out-messages the listbox component can produce. Single-select listboxes always emit `wasAdded: true`. Multi-select listboxes emit `wasAdded: true` when adding to the selection and `wasAdded: false` when toggling off. */
const OutMessage: Union<readonly [
CallableTaggedStruct<"Selected", {
value: String
wasAdded: Boolean
}>
]>/**
* The backdrop-portaling Mount this Listbox renders. Exposed so Scene tests can
* call `Scene.Mount.resolve(PortalListboxBackdrop, CompletedPortalListboxBackdrop())` to
* acknowledge the mount produced by the rendered backdrop.
*/
const PortalListboxBackdrop: MountDefinitionNoArgs<"PortalListboxBackdrop", {
_tag: "CompletedPortalListboxBackdrop"
}>/** Removes the inert attribute from elements outside the listbox. */
const RestoreInert: CommandDefinitionWithArgs<"RestoreInert", {
id: String
}, Effect<{
_tag: "CompletedRestoreInert"
}, never, never>>/** Scrolls the active listbox item into view after keyboard navigation. */
const ScrollIntoView: CommandDefinitionWithArgs<"ScrollIntoView", {
id: String
index: Number
}, Effect<{
_tag: "CompletedScrollIntoView"
}, never, never>>/** Sent when a single-select listbox commits a selection, or when a multi-select listbox toggles an item. Generic over `Value extends string`: the runtime schema stores `value: string`, but the type-level OutMessage exposes `value: Value` so consumers who supply `items: ReadonlyArray<MyUnion>` receive `value: MyUnion` from `update<MyUnion>` without casting. The cast is fenced inside this module's `update` return, sound because the value was extracted from the items array the consumer supplied. */
const Selected: CallableTaggedStruct<"Selected", {
value: String
wasAdded: Boolean
}>/** Sent when an item is selected via Enter, Space, or click. Contains the item's string value. */
const SelectedItem: CallableTaggedStruct<"SelectedItem", {
item: String
}>