command headless API

declare function activateCommandLayer<Item extends CommandItem>(service: CommandService<Item>, scope: PartScope, document: Document): () => void;

type CommandActionableItem = CommandItem & {
  readonly disabled?: boolean;
};

export declare const commandAnatomy: {
  readonly scope: "command";
  readonly parts: readonly ["root", "trigger", "input", "positioner", "content", "group", "group-label", "item", "item-text", "empty"];
};

interface CommandApi<Item extends CommandItem = CommandItem> {
  rootProps(): PartProps;
  triggerProps(): PartProps;
  inputProps(): PartProps;
  positionerProps(): PartProps;
  contentProps(): PartProps;
  groupProps(group: CommandGroup<Item>, index: number): PartProps;
  groupLabelProps(group: CommandGroup<Item>, index: number): PartProps;
  itemProps(item: Item, index?: number): PartProps;
  itemTextProps(item: Item): PartProps;
  emptyProps(): PartProps;
  readonly open: boolean;
  readonly value: string | undefined;
  readonly query: string;
  readonly activeIndex: number;
  readonly filteredGroups: readonly CommandGroup<Item>[];
  readonly flatItems: readonly Item[];
}

type CommandBindingMode = "controlled" | "uncontrolled";

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

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";
});

interface CommandConnectOptions {
  readonly onValueChange?: (detail: {
    value: string;
    reason: CommandSelectionReason;
  }) => void;
  readonly onOpenChange?: (detail: {
    open: boolean;
    reason: Exclude<CommandChangeReason, "input">;
  }) => void;
  readonly onQueryChange?: (detail: {
    query: string;
    reason: "input" | "programmatic";
  }) => void;
  readonly announce?: (key: "selection-changed" | "results-available", params: {
    readonly label: string | null;
    readonly count: number | null;
  }, politeness: "polite" | "assertive") => void;
}

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;
}

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";
};

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

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

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>;
}

type CommandItem = CommandItem$1;

export declare const commandMachine: CommandMachine;

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

interface CommandMount<Item extends CommandItem = CommandItem> {
  readonly service: CommandService<Item>;
  readonly connector: CommandApi<Item>;
  readonly root: HTMLElement;
  destroy(): void;
}

interface CommandOpenChangeDetail {
  readonly open: boolean;
  readonly reason: string;
}

type CommandPart = (typeof parts)[number];

interface CommandQueryChangeDetail {
  readonly query: string;
  readonly reason: "input" | "programmatic";
}

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

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[];
};

type CommandService<Item extends CommandItem = CommandItem> = Service<CommandInput<Item>, CommandStateValue, CommandContext<Item>, CommandEvent, CommandCommand>;

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

type CommandStateValue = "open" | "closed";

interface CommandValueChangeDetail {
  readonly value: string;
  readonly reason: string;
}

declare function connectCommand<Item extends CommandItem = CommandItem>(service: CommandService<Item>, scope: PartScope, _options?: CommandConnectOptions): CommandApi<Item>;

declare function mountCommand<Item extends CommandItem = CommandItem>(container: HTMLElement, options: MountCommandOptions<Item>): CommandMount<Item>;

interface MountCommandOptions<Item extends CommandItem = CommandItem> extends CommandInput<Item> {
  readonly onValueChange?: (detail: CommandValueChangeDetail) => void;
  readonly onOpenChange?: (detail: CommandOpenChangeDetail) => void;
  readonly onQueryChange?: (detail: CommandQueryChangeDetail) => void;
  readonly announce?: (key: string, params: Record<string, string | number | null>, politeness: string) => void;
  readonly triggerText?: string;
  readonly emptyText?: string;
  readonly renderTrigger?: (element: HTMLButtonElement) => void;
  readonly renderItem?: (element: HTMLElement, item: Item) => void;
  readonly renderItemText?: (element: HTMLElement, item: Item) => void;
}

declare function runCommandCommand(command: CommandCommand, scope: PartScope, options?: CommandConnectOptions): void;