Docs API reference UI machinescombobox

combobox machine

The public state machine contract for @grassroot/ui-machines/combobox. The machine owns behaviour; the matching headless layer owns composition.

@grassroot/ui-machines/combobox

Package

21 exports

View source packages/ui-machines/src/combobox/index.ts

Install npm i @grassroot/ui-machines

Service example

combobox.tsts

import { createService } from "@grassroot/statechart";
import { comboboxMachine } from "@grassroot/ui-machines/combobox";
 
const service = createService(comboboxMachine, { input: {} });
service.start();
service.send({ type: "…" });
service.stop();

Exports

ComboboxBindingMode

type

ComboboxBindingModets

type ComboboxBindingMode = "controlled" | "uncontrolled";

ComboboxChangeReason

type

ComboboxChangeReasonts

type ComboboxChangeReason = "pointer" | "keyboard" | "input" | "trigger" | "programmatic" | "escape" | "outside-click";

ComboboxCommand

type

ComboboxCommandts

type ComboboxCommand = CommandObject & ({
  readonly type: "VALUE_CHANGE_REQUEST";
  readonly value: ComboboxCommandValue;
  readonly reason: Exclude<ComboboxChangeReason, "input">;
} | {
  readonly type: "OPEN_CHANGE_REQUEST";
  readonly open: boolean;
  readonly reason: ComboboxChangeReason;
} | {
  readonly type: "INPUT_VALUE_CHANGE_REQUEST";
  readonly inputValue: string;
  readonly reason: "input" | "programmatic";
} | {
  readonly type: "FOCUS_PART";
  readonly part: "input" | "trigger";
} | {
  readonly type: "ANNOUNCE";
  readonly key: string;
  readonly params?: Record<string, string | number | boolean>;
} | {
  readonly type: "statechart.schedule";
  readonly key: "combobox.debounce";
  readonly event: {
    readonly type: "OPTIONS_REQUEST_FIRE";
  };
  readonly delayMs: number;
} | {
  readonly type: "statechart.cancel";
  readonly key: "combobox.debounce";
} | {
  readonly type: "OPTIONS_REQUEST";
  readonly key: "combobox.options";
  readonly request: {
    readonly query: string;
  };
  readonly onSettled: {
    readonly type: "OPTIONS_LOADED";
    readonly payloadKey: "options";
  };
  readonly onFailed: {
    readonly type: "OPTIONS_LOAD_FAILED";
    readonly payloadKey: "error";
  };
});

ComboboxContext

interface

ComboboxContextts

interface ComboboxContext {
  /** Caller-facing selection representation: strings or option records. */
  readonly value: ComboboxValue;
  /** Normalized identity used by the machine for all selection operations. */
  readonly selectedIds: readonly string[];
  readonly valueKind: SelectionKind;
  readonly open: boolean;
  readonly inputValue: string;
  /** Original options-list index; filtered and disabled options are skipped while moving. */
  readonly highlightedIndex: number;
  /** Normalized option ids, in filtered option order. */
  readonly filteredValues: readonly string[];
  readonly loading: boolean;
  readonly loadError: unknown;
  readonly modes: ComboboxModes;
}

Name

Kind

Type

Requirement

Description

filteredValues

property

readonly string[]

required

Normalized option ids, in filtered option order.

highlightedIndex

property

number

required

Original options-list index; filtered and disabled options are skipped while moving.

inputValue

property

string

required

—

loadError

property

unknown

required

—

loading

property

boolean

required

—

modes

property

ComboboxModes

required

—

open

property

boolean

required

—

selectedIds

property

readonly string[]

required

Normalized identity used by the machine for all selection operations.

value

property

ComboboxValue

required

Caller-facing selection representation: strings or option records.

valueKind

property

SelectionKind

required

—

Name: filteredValues
Kind: property
Type: readonly string[]
Requirement: required
Description: Normalized option ids, in filtered option order.

Name: highlightedIndex
Kind: property
Type: number
Requirement: required
Description: Original options-list index; filtered and disabled options are skipped while moving.

Name: inputValue
Kind: property
Type: string
Requirement: required
Description: —

Name: loadError
Kind: property
Type: unknown
Requirement: required
Description: —

Name: loading
Kind: property
Type: boolean
Requirement: required
Description: —

Name: modes
Kind: property
Type: ComboboxModes
Requirement: required
Description: —

Name: open
Kind: property
Type: boolean
Requirement: required
Description: —

Name: selectedIds
Kind: property
Type: readonly string[]
Requirement: required
Description: Normalized identity used by the machine for all selection operations.

Name: value
Kind: property
Type: ComboboxValue
Requirement: required
Description: Caller-facing selection representation: strings or option records.

Name: valueKind
Kind: property
Type: SelectionKind
Requirement: required
Description: —

ComboboxDiagnosticCodes

value

ComboboxDiagnosticCodests

export declare const ComboboxDiagnosticCodes: readonly DiagnosticCatalogueEntry[];

ComboboxEvent

type

ComboboxEventts

type ComboboxEvent = {
  readonly type: "OPEN";
  readonly reason: ComboboxChangeReason;
  readonly value?: string;
} | {
  readonly type: "CLOSE";
  readonly reason: ComboboxChangeReason;
} | {
  readonly type: "TOGGLE";
  readonly reason: ComboboxChangeReason;
  readonly value?: string;
} | {
  readonly type: "SET_INPUT_VALUE";
  readonly value: string;
  readonly reason: "input" | "programmatic";
} | {
  readonly type: "MOVE";
  readonly direction: -1 | 1;
} | {
  readonly type: "HOME";
} | {
  readonly type: "END";
} | {
  readonly type: "HIGHLIGHT";
  readonly id: string;
} | {
  readonly type: "SELECT";
  readonly id: string;
  readonly reason: Exclude<ComboboxChangeReason, "input">;
} | {
  readonly type: "OPTIONS_REQUEST_FIRE";
} | {
  readonly type: "OPTIONS_LOADED";
  readonly options: readonly ComboboxOptionInput[];
} | {
  readonly type: "OPTIONS_LOAD_FAILED";
  readonly error: unknown;
} | {
  readonly type: "RESET";
};

ComboboxInput

interface

ComboboxInputts

interface ComboboxInput {
  readonly options: readonly ComboboxOptionInput[];
  readonly loadOptions?: boolean;
  readonly selectionMode?: ComboboxSelectionMode;
  readonly value?: ComboboxValue;
  readonly defaultValue?: ComboboxValue;
  readonly open?: boolean;
  readonly defaultOpen?: boolean;
  readonly inputValue?: string;
  readonly defaultInputValue?: string;
}

Name

Kind

Type

Requirement

defaultInputValue

property

string

optional

defaultOpen

property

boolean

optional

defaultValue

property

ComboboxValue

optional

inputValue

property

string

optional

loadOptions

property

boolean

optional

open

property

boolean

optional

options

property

readonly ComboboxOptionInput[]

required

selectionMode

property

ComboboxSelectionMode

optional

value

property

ComboboxValue

optional

Name: defaultInputValue
Kind: property
Type: string
Requirement: optional

Name: defaultOpen
Kind: property
Type: boolean
Requirement: optional

Name: defaultValue
Kind: property
Type: ComboboxValue
Requirement: optional

Name: inputValue
Kind: property
Type: string
Requirement: optional

Name: loadOptions
Kind: property
Type: boolean
Requirement: optional

Name: open
Kind: property
Type: boolean
Requirement: optional

Name: options
Kind: property
Type: readonly ComboboxOptionInput[]
Requirement: required

Name: selectionMode
Kind: property
Type: ComboboxSelectionMode
Requirement: optional

Name: value
Kind: property
Type: ComboboxValue
Requirement: optional

comboboxMachine

value

comboboxMachinets

export declare const comboboxMachine: ComboboxMachine;

ComboboxMachine

type

ComboboxMachinets

type ComboboxMachine = Machine<ComboboxInput, ComboboxStateValue, ComboboxContext, ComboboxEvent, ComboboxCommand>;

ComboboxModes

interface

ComboboxModests

interface ComboboxModes {
  readonly value: ComboboxBindingMode;
  readonly open: ComboboxBindingMode;
  readonly inputValue: ComboboxBindingMode;
}

Name

Kind

Type

Requirement

inputValue

property

ComboboxBindingMode

required

open

property

ComboboxBindingMode

required

value

property

ComboboxBindingMode

required

Name: inputValue
Kind: property
Type: ComboboxBindingMode
Requirement: required

Name: open
Kind: property
Type: ComboboxBindingMode
Requirement: required

Name: value
Kind: property
Type: ComboboxBindingMode
Requirement: required

ComboboxOption

interface

ComboboxOptionts

interface ComboboxOption {
  readonly id?: string;
  readonly value: string;
  readonly label: string;
  readonly disabled?: boolean;
}

Name

Kind

Type

Requirement

disabled

property

boolean

optional

id

property

string

optional

label

property

string

required

value

property

string

required

Name: disabled
Kind: property
Type: boolean
Requirement: optional

Name: id
Kind: property
Type: string
Requirement: optional

Name: label
Kind: property
Type: string
Requirement: required

Name: value
Kind: property
Type: string
Requirement: required

ComboboxOptionInput

type

ComboboxOptionInputts

type ComboboxOptionInput = string | ComboboxOption;

comboboxReplaySequence

value

comboboxReplaySequencets

export declare const comboboxReplaySequence: readonly ComboboxEvent[];

ComboboxSelection

type

ComboboxSelectionts

type ComboboxSelection = string | ComboboxOption;

ComboboxSelectionMode

type

ComboboxSelectionModets

type ComboboxSelectionMode = "single" | "multiple";

comboboxSelectors

value

comboboxSelectorsts

export declare const comboboxSelectors: {
  open: (snapshot: ComboboxSnapshot) => boolean;
  value: (snapshot: ComboboxSnapshot) => ComboboxValue;
  selectedIds: (snapshot: ComboboxSnapshot) => readonly string[];
  inputValue: (snapshot: ComboboxSnapshot) => string;
  highlightedIndex: (snapshot: ComboboxSnapshot) => number;
  filteredValues: (snapshot: ComboboxSnapshot) => readonly string[];
};

Name

Kind

Type

Requirement

filteredValues

property

(snapshot: ComboboxSnapshot) => readonly string[]

required

highlightedIndex

property

(snapshot: ComboboxSnapshot) => number

required

inputValue

property

(snapshot: ComboboxSnapshot) => string

required

open

property

(snapshot: ComboboxSnapshot) => boolean

required

selectedIds

property

(snapshot: ComboboxSnapshot) => readonly string[]

required

value

property

(snapshot: ComboboxSnapshot) => ComboboxValue

required

Name: filteredValues
Kind: property
Type: (snapshot: ComboboxSnapshot) => readonly string[]
Requirement: required

Name: highlightedIndex
Kind: property
Type: (snapshot: ComboboxSnapshot) => number
Requirement: required

Name: inputValue
Kind: property
Type: (snapshot: ComboboxSnapshot) => string
Requirement: required

Name: open
Kind: property
Type: (snapshot: ComboboxSnapshot) => boolean
Requirement: required

Name: selectedIds
Kind: property
Type: (snapshot: ComboboxSnapshot) => readonly string[]
Requirement: required

Name: value
Kind: property
Type: (snapshot: ComboboxSnapshot) => ComboboxValue
Requirement: required

ComboboxSnapshot

type

ComboboxSnapshotts

type ComboboxSnapshot = Snapshot<ComboboxStateValue, ComboboxContext>;

ComboboxStateValue

type

ComboboxStateValuets

type ComboboxStateValue = "open" | "closed";

ComboboxValue

type

ComboboxValuets

type ComboboxValue = readonly ComboboxSelection[];

normalizedOptions

function

normalizedOptionsts

declare function normalizedOptions(options: readonly OptionInput[]): readonly NormalizedOption[];

Name

Kind

Type

Requirement

options

parameter

readonly OptionInput[]

required

return

return value

readonly NormalizedOption[]

n/a

Name: options
Kind: parameter
Type: readonly OptionInput[]
Requirement: required

Name: return
Kind: return value
Type: readonly NormalizedOption[]
Requirement: n/a

normalizeOption

function

normalizeOptionts

declare function normalizeOption(option: OptionInput): NormalizedOption;

Name

Kind

Type

Requirement

option

parameter

OptionInput

required

return

return value

NormalizedOption

n/a

Name: option
Kind: parameter
Type: OptionInput
Requirement: required

Name: return
Kind: return value
Type: NormalizedOption
Requirement: n/a

Service example

Exports

Related references