Reference headless

combobox

import { … } from '@kumiki/headless/combobox'

interface 4 type 6 function 1

interface Interfaces 4

interface

# ComboboxContext

Type Parameters

T

Members

error: error: Error | null
Most recent fetcher error, if any.
filtered: filtered: readonly T[]
Filtered subset shown in the listbox.
highlightedId: highlightedId: string | null
Id of the currently highlighted option, or null.
options: options: readonly T[]
Source list of options (sync mode). For async, mirrors the latest fetch.
pageSize: pageSize: number
Page step for PageUp / PageDown navigation.
query: query: string
Current input string.
status: status: ComboboxStatus
Async fetch lifecycle. Always 'idle' in sync mode.
token: token: number
Monotonic token incremented on every INPUT.CHANGE; used to drop stale fetches.
value: value: T | null
Currently selected option, or null.

interface combobox/index.ts · L32

# ComboboxController

Type Parameters

T

Members

context: readonly context: Readonly<ComboboxContext<T>>
disabled: readonly disabled: boolean
filtered: readonly filtered: readonly T[]
highlightedId: readonly highlightedId: string | null
id: readonly id: string
input: readonly input: Attachment
inputId: readonly inputId: string
isOpen: readonly isOpen: boolean
listbox: readonly listbox: Attachment
listboxId: readonly listboxId: string
machine: readonly machine: ComboboxMachine<T>
query: readonly query: string
root: readonly root: Attachment
state: readonly state: ComboboxState
status: readonly status: ComboboxStatus
trigger: readonly trigger: Attachment
value: readonly value: T | null
close(): close(): void
###### Returns

void
navigate(): navigate(direction): void
###### Parameters

###### direction

NavigateDirection

###### Returns

void
open(): open(): void
###### Returns

void
option(): option(option): Attachment
###### Parameters

###### option

T

###### Returns

Attachment
optionElementId(): optionElementId(optionId): string
###### Parameters

###### optionId

string

###### Returns

string
reset(): reset(): void
###### Returns

void
select(): select(option): void
User-action selection — fires onValueChange and closes the listbox.

###### Parameters

###### option

T

###### Returns

void
setDisabled(): setDisabled(disabled): void
###### Parameters

###### disabled

boolean

###### Returns

void
setValue(): setValue(value): void
Programmatic value update — works in any state, does not transition.

###### Parameters

###### value

T | null

###### Returns

void
subscribe(): subscribe(listener): () => void
###### Parameters

###### listener

(snapshot) => void

###### Returns

() => void

interface

# ComboboxOption

Structural shape an option must satisfy. Most consumers pass typed domain objects (User, Product, …) — id and label are the floor; everything else propagates as T.

Members

disabled?: readonly optional disabled?: boolean
id: readonly id: string
label: readonly label: string

interface combobox/index.ts · L72

# CreateComboboxOptions

Type Parameters

T

Members

defaultQuery?: optional defaultQuery?: string
###### Inherited from

CreateComboboxInput.defaultQuery
defaultValue?: optional defaultValue?: T | null
###### Inherited from

CreateComboboxInput.defaultValue
disabled?: optional disabled?: boolean
###### Inherited from

CreateComboboxInput.disabled
filter?: optional filter?: (options, query) => readonly T[]
Optional sync filter. Receives (options, query) and returns a subset. Default: case-insensitive label substring match.

###### Parameters

###### options

readonly T[]

###### query

string

###### Returns

readonly T[]

###### Inherited from

CreateComboboxInput.filter
id?: optional id?: string
onOpenChange?: optional onOpenChange?: (open) => void
Called when the open state changes.

###### Parameters

###### open

boolean

###### Returns

void
onQueryChange?: optional onQueryChange?: (query) => void
Called on every input change.

###### Parameters

###### query

string

###### Returns

void
onValueChange?: optional onValueChange?: (value) => void
Called when the selected value changes (user-initiated).

###### Parameters

###### value

T | null

###### Returns

void
options?: optional options?: readonly T[]
###### Inherited from

CreateComboboxInput.options
pageSize?: optional pageSize?: number
Page step for PageUp/PageDown. Defaults to 10.

###### Inherited from

CreateComboboxInput.pageSize

type Type Aliases 6

type combobox/index.ts · L30

# Attachment

Attachment = (node) => void | (() => void)

Parameters

node: HTMLElement

Returns

void | (() => void)

type

# ComboboxEvent

ComboboxEvent<T> = { type: "INPUT.FOCUS"; } | { type: "INPUT.BLUR"; } | { type: "INPUT.CHANGE"; value: string; } | { type: "INPUT.ESCAPE"; } | { type: "INPUT.ENTER"; } | { direction: NavigateDirection; type: "INPUT.NAVIGATE"; } | { id: string; type: "OPTION.HIGHLIGHT"; } | { option: T; type: "OPTION.SELECT"; } | { type: "TRIGGER.CLICK"; } | { type: "OPEN"; } | { type: "CLOSE"; } | { options: ReadonlyArray<T>; token: number; type: "FETCH.RESOLVE"; } | { error: Error; token: number; type: "FETCH.REJECT"; } | { token: number; type: "FETCH.LOADING"; } | { type: "SET.VALUE"; value: T | null; } | { type: "RESET"; } | { type: "DISABLE"; } | { type: "ENABLE"; }

All events the Combobox machine can receive.

Type Parameters

T

type

# ComboboxMachine

ComboboxMachine<T> = Machine<ComboboxContext<T>, ComboboxEvent<T>, ComboboxState>

Type Parameters

T

type

# ComboboxState

ComboboxState = "idle" | "open" | "disabled"

type

# ComboboxStatus

ComboboxStatus = "idle" | "loading" | "error"

Async fetch lifecycle.

type

# NavigateDirection

Keyboard navigation directions.

function Functions 1

function combobox/index.ts · L94

# createCombobox ( )

createCombobox<T>(options?): ComboboxController<T>

Create a Combobox controller plus its {@attach}-compatible attachments.

Type Parameters

T

Parameters

options?: CreateComboboxOptions<T> = {}

Returns

ComboboxController<T>