On this pageFunctions
Ui/Combobox
/** Creates an initial single-select combobox model from a config. Defaults to closed with no active item, empty input, and no selection. */
(config: InitConfig): Combobox.Model/** Sent when an item is highlighted via arrow keys or mouse hover. Includes activation trigger and optional immediate selection info. */
type ActivatedItem = CallableTaggedStruct<"ActivatedItem", {
activationTrigger: Literals<readonly ["Pointer", "Keyboard"]>
index: Number
maybeImmediateSelection: Option<Struct<{
displayText: String
item: String
}>>
}>/** Schema for the activation trigger: whether the user interacted via mouse or keyboard. */
type ActivationTrigger = Literals<readonly ["Pointer", "Keyboard"]>/** Static configuration for anchor-based positioning of a floating element relative to a button. */
type AnchorConfig = 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>
}>/** Sent when the combobox input loses focus. */
type BlurredInput = CallableTaggedStruct<"BlurredInput", {}>/** Sent when the combobox 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
}>/** Configuration for creating a single-select combobox 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<{
selectedDisplayText: string
selectedItem: string
}>/** Configuration for an individual combobox item's appearance. */
type ItemConfig = Readonly<{
className: string
content: Html
}>/** Sent when the pointer moves over a combobox item. */
type MovedPointerOverItem = CallableTaggedStruct<"MovedPointerOverItem", {
index: Number
screenX: Number
screenY: Number
}>/** Sent when the combobox popup opens. Contains an optional initial active item index. */
type Opened = CallableTaggedStruct<"Opened", {
maybeActiveItemIndex: Option<Number>
}>/**
* Generic over `Value extends string` so consumers who create the combobox
* via `Ui.Combobox.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 optional toggle button is clicked. */
type PressedToggleButton = CallableTaggedStruct<"PressedToggleButton", {}>/** Sent when Enter or Space is pressed on the active item, triggering a programmatic click. */
type RequestedItemClick = CallableTaggedStruct<"RequestedItemClick", {
index: Number
}>/** Sent when a single-select combobox commits a selection, or when a multi-select combobox toggles an item on. The `value` is the string key; consumers that need a richer domain type should look it up from their own state or, in the multi case, branch on `wasAdded` to distinguish add vs remove. */
type Selected = Readonly<{
_tag: "Selected"
value: Value
wasAdded: boolean
}>/** Sent when the user types in the input. */
type UpdatedInputValue = CallableTaggedStruct<"UpdatedInputValue", {
value: String
}>/** Per-render view inputs passed to the view via `h.submodel`'s `viewInputs` field. */
type ViewInputs = BaseViewInputs<Item>/**
* The anchor-positioning Mount this Combobox renders on its items panel.
* The panel is always anchored to the input wrapper 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. The Mount also installs the `pointerdown`-cancelling
* capture listener that prevents input blur on item presses. Exposed so
* Scene tests can call
* `Scene.Mount.resolve(AnchorCombobox, CompletedAnchorCombobox())`.
*/
const AnchorCombobox: MountDefinitionWithArgs<"AnchorCombobox", {
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: "CompletedAnchorCombobox"
}>/**
* The Mount this Combobox renders to install a `pointerdown`-cancelling
* capture listener that prevents blur on item presses. Exposed so Scene
* tests can call
* `Scene.Mount.resolve(AttachComboboxPreventBlur, CompletedAttachComboboxPreventBlur())`.
*/
const AttachComboboxPreventBlur: MountDefinitionNoArgs<"AttachComboboxPreventBlur", {
_tag: "CompletedAttachComboboxPreventBlur"
}>/**
* The Mount this Combobox renders to install the input's select-on-focus
* behavior. Exposed so Scene tests can call
* `Scene.Mount.resolve(AttachComboboxSelectOnFocus, CompletedAttachComboboxSelectOnFocus())`.
*/
const AttachComboboxSelectOnFocus: MountDefinitionNoArgs<"AttachComboboxSelectOnFocus", {
_tag: "CompletedAttachComboboxSelectOnFocus"
}>/** Programmatically clicks the active combobox item's DOM element. */
const ClickItem: CommandDefinitionWithArgs<"ClickItem", {
id: String
index: Number
}, Effect<{
_tag: "CompletedClickItem"
}, never, never>>/** Sent when the items panel mounts and Floating UI has positioned it. Update no-ops; surfaces the positioning side effect for DevTools. */
const CompletedAnchorCombobox: CallableTaggedStruct<"CompletedAnchorCombobox", {}>/** Sent when the items panel mounts and the capture-phase pointerdown listener is attached (with or without anchor). Update no-ops; surfaces the listener-attach side effect for DevTools. */
const CompletedAttachComboboxPreventBlur: CallableTaggedStruct<"CompletedAttachComboboxPreventBlur", {}>/** Sent when the input mounts and the focus listener that auto-selects on focus is attached. Update no-ops; surfaces the listener-attach side effect for DevTools. */
const CompletedAttachComboboxSelectOnFocus: CallableTaggedStruct<"CompletedAttachComboboxSelectOnFocus", {}>/** Sent when the programmatic item click command completes. */
const CompletedClickItem: CallableTaggedStruct<"CompletedClickItem", {}>/** Sent when the focus-input command completes. */
const CompletedFocusInput: CallableTaggedStruct<"CompletedFocusInput", {}>/** 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 combobox backdrop mounts and is portaled to the document body. Update no-ops; surfaces the portal side effect for DevTools. */
const CompletedPortalComboboxBackdrop: CallableTaggedStruct<"CompletedPortalComboboxBackdrop", {}>/** 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", {}>/** Detects whether the combobox input wrapper 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 to the combobox input after selection or close. */
const FocusInput: CommandDefinitionWithArgs<"FocusInput", {
id: String
}, Effect<{
_tag: "CompletedFocusInput"
}, 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 combobox as inert for modal behavior. */
const InertOthers: CommandDefinitionWithArgs<"InertOthers", {
id: String
}, Effect<{
_tag: "CompletedInertOthers"
}, never, never>>/** Prevents page scrolling while the combobox popup is open in modal mode. */
const LockScroll: CommandDefinitionNoArgs<"LockScroll", Effect<{
_tag: "CompletedLockScroll"
}, never, never>>/** Union of all messages the combobox component can produce. */
const Message: S.Union<[typeof Opened, typeof Closed, typeof BlurredInput, typeof ActivatedItem, typeof DeactivatedItem, typeof SelectedItem, typeof MovedPointerOverItem, typeof RequestedItemClick, typeof CompletedLockScroll, typeof CompletedUnlockScroll, typeof CompletedInertOthers, typeof CompletedRestoreInert, typeof CompletedFocusInput, typeof CompletedScrollIntoView, typeof CompletedClickItem, typeof CompletedAnchorCombobox, typeof CompletedAttachComboboxPreventBlur, typeof CompletedAttachComboboxSelectOnFocus, typeof CompletedPortalComboboxBackdrop, typeof GotAnimationMessage, typeof UpdatedInputValue, typeof PressedToggleButton]>/** Schema for the single-select combobox component's state, tracking open/closed status, active item, input value, selected item, and display text. */
const Model: Struct<{
activationTrigger: Literals<readonly ["Pointer", "Keyboard"]>
animation: Struct<{
id: String
isShowing: Boolean
transitionState: Literals<readonly ["Idle", "EnterStart", "EnterAnimating", "LeaveStart", "LeaveAnimating"]>
}>
id: String
immediate: Boolean
inputValue: String
isAnimated: Boolean
isModal: Boolean
isOpen: Boolean
maybeActiveItemIndex: Option<Number>
maybeLastPointerPosition: Option<Struct<{
screenX: Number
screenY: Number
}>>
maybeSelectedDisplayText: Option<String>
maybeSelectedItem: Option<String>
nullable: Boolean
selectInputOnFocus: Boolean
}>/** Union of out-messages the combobox component can produce. Single-select comboboxes always emit `wasAdded: true`. Multi-select comboboxes 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 Combobox renders. Exposed so Scene tests can
* call `Scene.Mount.resolve(PortalComboboxBackdrop, CompletedPortalComboboxBackdrop())` to
* acknowledge the mount produced by the rendered backdrop.
*/
const PortalComboboxBackdrop: MountDefinitionNoArgs<"PortalComboboxBackdrop", {
_tag: "CompletedPortalComboboxBackdrop"
}>/** Removes the inert attribute from elements outside the combobox. */
const RestoreInert: CommandDefinitionWithArgs<"RestoreInert", {
id: String
}, Effect<{
_tag: "CompletedRestoreInert"
}, never, never>>/** Scrolls the active combobox item into view after keyboard navigation. */
const ScrollIntoView: CommandDefinitionWithArgs<"ScrollIntoView", {
id: String
index: Number
}, Effect<{
_tag: "CompletedScrollIntoView"
}, never, never>>/** Sent when a single-select combobox commits a selection, or when a multi-select combobox toggles an item on. The `value` is the string key; consumers that need a richer domain type should look it up from their own state or, in the multi case, branch on `wasAdded` to distinguish add vs remove. */
const Selected: CallableTaggedStruct<"Selected", {
value: String
wasAdded: Boolean
}>/** Sent when an item is selected via Enter or click. Includes display text for restoring input value on close. */
const SelectedItem: CallableTaggedStruct<"SelectedItem", {
displayText: String
item: String
}>