Docs API reference UI machinescommand

command machine

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

@grassroot/ui-machines/command

Package

18 exports

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

Install npm i @grassroot/ui-machines

Service example

command.tsts

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

Exports

CommandBindingMode

type

CommandBindingModets

type CommandBindingMode = "controlled" | "uncontrolled";

CommandChangeReason

type

CommandChangeReasonts

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

CommandCommand

type

CommandCommandts

type CommandCommand = CommandObject & ({
  readonly type: "VALUE_CHANGE_REQUEST";
  readonly value: string;
  readonly reason: CommandSelectionReason;
} | {
  readonly type: "OPEN_CHANGE_REQUEST";
  readonly open: boolean;
  readonly reason: Exclude<CommandChangeReason, "input">;
} | {
  readonly type: "QUERY_CHANGE_REQUEST";
  readonly query: string;
  readonly reason: "input" | "programmatic";
} | {
  readonly type: "FOCUS_PART";
  readonly part: "input" | "panel";
} | {
  readonly type: "ANNOUNCE";
  readonly key: "selection-changed" | "results-available";
  readonly params: {
    readonly label: string | null;
    readonly count: number | null;
  };
  readonly politeness: "polite" | "assertive";
});

CommandContext

interface

CommandContextts

interface CommandContext<Item extends CommandItem = CommandItem> {
  readonly value: string | undefined;
  readonly open: boolean;
  readonly query: string;
  /** Index into the current flattened item list; filtering never creates a second index model. */
  readonly highlightedIndex: number;
  readonly filteredGroups: readonly CommandGroup<Item>[];
  readonly flatItems: readonly Item[];
  readonly modes: CommandModes;
}

Name

Kind

Type

Requirement

Description

filteredGroups

property

readonly CommandGroup<Item>[]

required

—

flatItems

property

readonly Item[]

required

—

highlightedIndex

property

number

required

Index into the current flattened item list; filtering never creates a second index model.

modes

property

CommandModes

required

—

open

property

boolean

required

—

query

property

string

required

—

value

property

string | undefined

required

—

Name: filteredGroups
Kind: property
Type: readonly CommandGroup<Item>[]
Requirement: required
Description: —

Name: flatItems
Kind: property
Type: readonly Item[]
Requirement: required
Description: —

Name: highlightedIndex
Kind: property
Type: number
Requirement: required
Description: Index into the current flattened item list; filtering never creates a second index model.

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

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

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

Name: value
Kind: property
Type: string | undefined
Requirement: required
Description: —

CommandDiagnosticCodes

value

CommandDiagnosticCodests

export declare const CommandDiagnosticCodes: readonly DiagnosticCatalogueEntry[];

CommandEvent

type

CommandEventts

type CommandEvent = {
  readonly type: "OPEN";
  readonly reason: Exclude<CommandChangeReason, "input">;
} | {
  readonly type: "CLOSE";
  readonly reason: Exclude<CommandChangeReason, "input">;
} | {
  readonly type: "TOGGLE";
  readonly reason: Exclude<CommandChangeReason, "input">;
} | {
  readonly type: "SET_QUERY";
  readonly query: string;
  readonly reason: "input" | "programmatic";
} | {
  readonly type: "MOVE";
  readonly direction: -1 | 1;
} | {
  readonly type: "HIGHLIGHT";
  readonly index: number;
} | {
  readonly type: "SELECT";
  readonly value: string;
  readonly reason: CommandSelectionReason;
} | {
  readonly type: "RESET";
};

CommandFilter

type

CommandFilterts

type CommandFilter<Item extends CommandItem = CommandItem> = (item: Item, normalizedQuery: string) => boolean;

CommandGroup

type

CommandGroupts

type CommandGroup<Item extends CommandItem = CommandItem> = CommandGroup$1<Item>;

CommandInput

interface

CommandInputts

interface CommandInput<Item extends CommandItem = CommandItem> {
  readonly groups: readonly CommandGroup<Item>[];
  readonly value?: string;
  readonly defaultValue?: string;
  readonly open?: boolean;
  readonly defaultOpen?: boolean;
  readonly query?: string;
  readonly defaultQuery?: string;
  /** Replaces the default oracle predicate; the machine still owns grouping. */
  readonly filter?: CommandFilter<Item>;
}

Name

Kind

Type

Requirement

Description

defaultOpen

property

boolean

optional

—

defaultQuery

property

string

optional

—

defaultValue

property

string

optional

—

filter

property

CommandFilter<Item>

optional

Replaces the default oracle predicate; the machine still owns grouping.

groups

property

readonly CommandGroup<Item>[]

required

—

open

property

boolean

optional

—

query

property

string

optional

—

value

property

string

optional

—

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

Name: defaultQuery
Kind: property
Type: string
Requirement: optional
Description: —

Name: defaultValue
Kind: property
Type: string
Requirement: optional
Description: —

Name: filter
Kind: property
Type: CommandFilter<Item>
Requirement: optional
Description: Replaces the default oracle predicate; the machine still owns grouping.

Name: groups
Kind: property
Type: readonly CommandGroup<Item>[]
Requirement: required
Description: —

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

Name: query
Kind: property
Type: string
Requirement: optional
Description: —

Name: value
Kind: property
Type: string
Requirement: optional
Description: —

CommandItem

type

CommandItemts

type CommandItem = CommandItem$1;

commandMachine

value

commandMachinets

export declare const commandMachine: CommandMachine;

CommandMachine

type

CommandMachinets

type CommandMachine<Item extends CommandItem = CommandItem> = Machine<CommandInput<Item>, CommandStateValue, CommandContext<Item>, CommandEvent, CommandCommand>;

CommandModes

interface

CommandModests

interface CommandModes {
  readonly value: CommandBindingMode;
  readonly open: CommandBindingMode;
  readonly query: CommandBindingMode;
}

Name

Kind

Type

Requirement

open

property

CommandBindingMode

required

query

property

CommandBindingMode

required

value

property

CommandBindingMode

required

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

Name: query
Kind: property
Type: CommandBindingMode
Requirement: required

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

commandReplaySequence

value

commandReplaySequencets

export declare const commandReplaySequence: readonly CommandEvent[];

CommandSelectionReason

type

CommandSelectionReasonts

type CommandSelectionReason = "pointer" | "keyboard" | "programmatic";

commandSelectors

value

commandSelectorsts

export declare const commandSelectors: {
  value: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => string | undefined;
  open: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => boolean;
  query: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => string;
  highlightedIndex: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => number;
  filteredGroups: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => readonly CommandGroup<Item>[];
  flatItems: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => readonly Item[];
};

Name

Kind

Type

Requirement

filteredGroups

property

<Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => readonly CommandGroup<Item>[]

required

flatItems

property

<Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => readonly Item[]

required

highlightedIndex

property

<Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => number

required

open

property

<Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => boolean

required

query

property

<Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => string

required

value

property

<Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => string | undefined

required

Name: filteredGroups
Kind: property
Type: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => readonly CommandGroup<Item>[]
Requirement: required

Name: flatItems
Kind: property
Type: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => readonly Item[]
Requirement: required

Name: highlightedIndex
Kind: property
Type: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => number
Requirement: required

Name: open
Kind: property
Type: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => boolean
Requirement: required

Name: query
Kind: property
Type: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => string
Requirement: required

Name: value
Kind: property
Type: <Item extends CommandItem>(snapshot: CommandSnapshot<Item>) => string | undefined
Requirement: required

CommandSnapshot

type

CommandSnapshotts

type CommandSnapshot<Item extends CommandItem = CommandItem> = Snapshot<CommandStateValue, CommandContext<Item>>;

CommandStateValue

type

CommandStateValuets

type CommandStateValue = "open" | "closed";

Service example

Exports

Related references