@zag-js/combobox 0.82.2 → 1.0.1

package/dist/index.d.mts

@@ -3,10 +3,10 @@ export { FocusOutsideEvent, InteractOutsideEvent, PointerDownOutsideEvent } from
 import * as _zag_js_anatomy from '@zag-js/anatomy';
 import { CollectionOptions, ListCollection, CollectionItem } from '@zag-js/collection';
 export { CollectionItem, CollectionOptions } from '@zag-js/collection';
-import { RequiredBy, PropTypes, DirectionProperty, CommonProperties, NormalizeProps } from '@zag-js/types';
+import { DirectionProperty, CommonProperties, PropTypes, RequiredBy, NormalizeProps } from '@zag-js/types';
 import * as _zag_js_core from '@zag-js/core';
-import { Machine, StateMachine } from '@zag-js/core';
-import { PositioningOptions } from '@zag-js/popper';
+import { Service, Machine, EventObject } from '@zag-js/core';
+import { PositioningOptions, Placement } from '@zag-js/popper';
 export { Placement, PositioningOptions } from '@zag-js/popper';
 
 declare const anatomy: _zag_js_anatomy.AnatomyInstance<"content" | "list" | "label" | "input" | "root" | "item" | "clearTrigger" | "control" | "itemGroup" | "itemGroupLabel" | "itemIndicator" | "itemText" | "positioner" | "trigger">;
@@ -55,23 +55,30 @@ type ElementIds = Partial<{
     itemGroup(id: string | number): string;
     itemGroupLabel(id: string | number): string;
 }>;
-interface PublicContext<T extends CollectionItem = CollectionItem> extends DirectionProperty, CommonProperties, InteractOutsideHandlers {
+interface ComboboxProps<T extends CollectionItem = CollectionItem> extends DirectionProperty, CommonProperties, InteractOutsideHandlers {
     /**
-     * Whether the combobox is open
+     * The controlled open state of the combobox
      */
     open?: boolean | undefined;
     /**
-     * Whether the combobox open state is controlled by the user
+     * The initial open state of the combobox when rendered.
+     * Use when you don't need to control the open state of the combobox.
      */
-    "open.controlled"?: boolean | undefined;
+    defaultOpen?: boolean | undefined;
     /**
      * The ids of the elements in the combobox. Useful for composition.
      */
     ids?: ElementIds | undefined;
     /**
-     * The current value of the combobox's input
+     * The controlled value of the combobox's input
      */
-    inputValue: string;
+    inputValue?: string | undefined;
+    /**
+     * The initial value of the combobox's input when rendered.
+     * Use when you don't need to control the value of the combobox's input.
+     * @default ""
+     */
+    defaultInputValue?: string | undefined;
     /**
      * The `name` attribute of the combobox's input. Useful for form submission
      */
@@ -102,13 +109,24 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      */
     placeholder?: string | undefined;
     /**
-     * The active item's id. Used to set the `aria-activedescendant` attribute
+     * The initial highlighted value of the combobox when rendered.
+     * Use when you don't need to control the highlighted value of the combobox.
      */
-    highlightedValue: string | null;
+    defaultHighlightedValue?: string | null | undefined;
     /**
-     * The keys of the selected items
+     * The controlled highlighted value of the combobox
      */
-    value: string[];
+    highlightedValue?: string | null | undefined;
+    /**
+     * The controlled value of the combobox's selected items
+     */
+    value?: string[] | undefined;
+    /**
+     * The initial value of the combobox's selected items when rendered.
+     * Use when you don't need to control the value of the combobox's selected items.
+     * @default []
+     */
+    defaultValue?: string[] | undefined;
     /**
      * Defines the auto-completion behavior of the combobox.
      *
@@ -117,7 +135,7 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      *
      * @default "none"
      */
-    inputBehavior: "autohighlight" | "autocomplete" | "none";
+    inputBehavior?: "autohighlight" | "autocomplete" | "none" | undefined;
     /**
      * The behavior of the combobox input when an item is selected
      *
@@ -127,7 +145,7 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      *
      * @default "replace"
      */
-    selectionBehavior: "clear" | "replace" | "preserve";
+    selectionBehavior?: "clear" | "replace" | "preserve" | undefined;
     /**
      * Whether to autofocus the input on mount
      */
@@ -153,8 +171,9 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
     loopFocus?: boolean | undefined;
     /**
      * The positioning options to dynamically position the menu
+     * @default { placement: "bottom-start" }
      */
-    positioning: PositioningOptions;
+    positioning?: PositioningOptions | undefined;
     /**
      * Function called when the input's value changes
      */
@@ -175,11 +194,11 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
     /**
      * Specifies the localized strings that identifies the accessibility elements and their states
      */
-    translations: IntlTranslations;
+    translations?: IntlTranslations | undefined;
     /**
      * The collection of items
      */
-    collection: ListCollection<any>;
+    collection?: ListCollection<T> | undefined;
     /**
      * Whether to allow multiple selection.
      *
@@ -195,7 +214,7 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      * Whether to open the combobox on arrow key press
      * @default true
      */
-    openOnKeyPress: boolean;
+    openOnKeyPress?: boolean | undefined;
     /**
      * Function to scroll to a specific index
      */
@@ -204,7 +223,7 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      * Whether the combobox is a composed with other composite widgets like tabs
      * @default true
      */
-    composite: boolean;
+    composite?: boolean | undefined;
     /**
      * Whether to disable registering this a dismissable layer
      */
@@ -212,49 +231,36 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
     /**
      * Function to navigate to the selected item
      */
-    navigate: (details: NavigateDetails) => void;
+    navigate?: ((details: NavigateDetails) => void) | undefined;
 }
-type UserDefinedContext<T extends CollectionItem = CollectionItem> = RequiredBy<PublicContext<T>, "id" | "collection">;
-type ComputedContext = Readonly<{
-    /**
-     * @computed
-     * Whether the input's value is empty
-     */
-    isInputValueEmpty: boolean;
-    /**
-     * @computed
-     * Whether the combobox is interactive
-     */
-    isInteractive: boolean;
-    /**
-     * @computed
-     */
-    autoComplete: boolean;
-    /**
-     * @computed
-     */
-    autoHighlight: boolean;
-    /**
-     * @computed
-     * Whether there's a selected option
-     */
-    hasSelectedItems: boolean;
-}>;
-interface PrivateContext<T extends CollectionItem = CollectionItem> {
-    /**
-     * The highlighted item
-     */
-    highlightedItem: T | null;
-}
-interface MachineContext extends PublicContext, PrivateContext, ComputedContext {
-}
-interface MachineState {
-    value: "idle" | "focused" | "suggesting" | "interacting";
-    tags: "open" | "focused" | "idle" | "closed";
+type PropsWithDefault = "openOnChange" | "openOnKeyPress" | "composite" | "navigate" | "loopFocus" | "positioning" | "openOnClick" | "openOnChange" | "inputBehavior" | "collection" | "selectionBehavior" | "closeOnSelect" | "translations" | "positioning";
+interface ComboboxSchema<T extends CollectionItem = CollectionItem> {
+    props: RequiredBy<ComboboxProps<T>, PropsWithDefault>;
+    state: "idle" | "focused" | "suggesting" | "interacting";
+    tag: "open" | "focused" | "idle" | "closed";
+    context: {
+        value: string[];
+        inputValue: string;
+        highlightedValue: string | null;
+        currentPlacement?: Placement | undefined;
+        highlightedItem: T | null;
+        selectedItems: T[];
+        valueAsString: string;
+    };
+    computed: {
+        isInputValueEmpty: boolean;
+        isInteractive: boolean;
+        autoComplete: boolean;
+        autoHighlight: boolean;
+        hasSelectedItems: boolean;
+    };
+    event: EventObject;
+    action: string;
+    effect: string;
+    guard: string;
 }
-type State = StateMachine.State<MachineContext, MachineState>;
-type Send = StateMachine.Send<StateMachine.AnyEventObject>;
-type Service = Machine<MachineContext, MachineState, StateMachine.AnyEventObject>;
+type ComboboxService<T extends CollectionItem = CollectionItem> = Service<ComboboxSchema<T>>;
+type ComboboxMachine<T extends CollectionItem = CollectionItem> = Machine<ComboboxSchema<T>>;
 interface TriggerProps {
     /**
      * Whether the trigger is focusable
@@ -295,7 +301,7 @@ interface ItemGroupProps {
 interface ItemGroupLabelProps {
     htmlFor: string;
 }
-interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem = CollectionItem> {
+interface ComboboxApi<T extends PropTypes = PropTypes, V extends CollectionItem = CollectionItem> {
     /**
      * Whether the combobox is focused
      */
@@ -373,10 +379,6 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
      * Function to toggle the combobox
      */
     collection: ListCollection<V>;
-    /**
-     * Function to set the collection of items
-     */
-    setCollection(collection: ListCollection<V>): void;
     /**
      * Function to set the positioning options
      */
@@ -405,8 +407,17 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
     getItemGroupLabelProps(props: ItemGroupLabelProps): T["element"];
 }
 
-declare function connect<T extends PropTypes, V extends CollectionItem>(state: State, send: Send, normalize: NormalizeProps<T>): MachineApi<T, V>;
+declare function connect<T extends PropTypes, V extends CollectionItem>(service: ComboboxService<V>, normalize: NormalizeProps<T>): ComboboxApi<T, V>;
+
+declare const machine: _zag_js_core.Machine<ComboboxSchema<any>>;
 
-declare function machine<T extends CollectionItem>(userContext: UserDefinedContext<T>): _zag_js_core.Machine<MachineContext, MachineState, _zag_js_core.StateMachine.AnyEventObject>;
+declare const props: (keyof ComboboxProps<any>)[];
+declare const splitProps: <Props extends Partial<ComboboxProps<any>>>(props: Props) => [Partial<ComboboxProps<any>>, Omit<Props, keyof ComboboxProps<any>>];
+declare const itemGroupLabelProps: "htmlFor"[];
+declare const splitItemGroupLabelProps: <Props extends ItemGroupLabelProps>(props: Props) => [ItemGroupLabelProps, Omit<Props, "htmlFor">];
+declare const itemGroupProps: "id"[];
+declare const splitItemGroupProps: <Props extends ItemGroupProps>(props: Props) => [ItemGroupProps, Omit<Props, "id">];
+declare const itemProps: (keyof ItemProps)[];
+declare const splitItemProps: <Props extends ItemProps>(props: Props) => [ItemProps, Omit<Props, keyof ItemProps>];
 
-export { type MachineApi as Api, type UserDefinedContext as Context, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type NavigateDetails, type OpenChangeDetails, type ScrollToIndexDetails, type Service, type TriggerProps, type ValueChangeDetails, anatomy, collection, connect, machine };
+export { type ComboboxApi as Api, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type ComboboxMachine as Machine, type NavigateDetails, type OpenChangeDetails, type ComboboxProps as Props, type ScrollToIndexDetails, type ComboboxService as Service, type TriggerProps, type ValueChangeDetails, anatomy, collection, connect, itemGroupLabelProps, itemGroupProps, itemProps, machine, props, splitItemGroupLabelProps, splitItemGroupProps, splitItemProps, splitProps };

package/dist/index.d.ts

@@ -3,10 +3,10 @@ export { FocusOutsideEvent, InteractOutsideEvent, PointerDownOutsideEvent } from
 import * as _zag_js_anatomy from '@zag-js/anatomy';
 import { CollectionOptions, ListCollection, CollectionItem } from '@zag-js/collection';
 export { CollectionItem, CollectionOptions } from '@zag-js/collection';
-import { RequiredBy, PropTypes, DirectionProperty, CommonProperties, NormalizeProps } from '@zag-js/types';
+import { DirectionProperty, CommonProperties, PropTypes, RequiredBy, NormalizeProps } from '@zag-js/types';
 import * as _zag_js_core from '@zag-js/core';
-import { Machine, StateMachine } from '@zag-js/core';
-import { PositioningOptions } from '@zag-js/popper';
+import { Service, Machine, EventObject } from '@zag-js/core';
+import { PositioningOptions, Placement } from '@zag-js/popper';
 export { Placement, PositioningOptions } from '@zag-js/popper';
 
 declare const anatomy: _zag_js_anatomy.AnatomyInstance<"content" | "list" | "label" | "input" | "root" | "item" | "clearTrigger" | "control" | "itemGroup" | "itemGroupLabel" | "itemIndicator" | "itemText" | "positioner" | "trigger">;
@@ -55,23 +55,30 @@ type ElementIds = Partial<{
     itemGroup(id: string | number): string;
     itemGroupLabel(id: string | number): string;
 }>;
-interface PublicContext<T extends CollectionItem = CollectionItem> extends DirectionProperty, CommonProperties, InteractOutsideHandlers {
+interface ComboboxProps<T extends CollectionItem = CollectionItem> extends DirectionProperty, CommonProperties, InteractOutsideHandlers {
     /**
-     * Whether the combobox is open
+     * The controlled open state of the combobox
      */
     open?: boolean | undefined;
     /**
-     * Whether the combobox open state is controlled by the user
+     * The initial open state of the combobox when rendered.
+     * Use when you don't need to control the open state of the combobox.
      */
-    "open.controlled"?: boolean | undefined;
+    defaultOpen?: boolean | undefined;
     /**
      * The ids of the elements in the combobox. Useful for composition.
      */
     ids?: ElementIds | undefined;
     /**
-     * The current value of the combobox's input
+     * The controlled value of the combobox's input
      */
-    inputValue: string;
+    inputValue?: string | undefined;
+    /**
+     * The initial value of the combobox's input when rendered.
+     * Use when you don't need to control the value of the combobox's input.
+     * @default ""
+     */
+    defaultInputValue?: string | undefined;
     /**
      * The `name` attribute of the combobox's input. Useful for form submission
      */
@@ -102,13 +109,24 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      */
     placeholder?: string | undefined;
     /**
-     * The active item's id. Used to set the `aria-activedescendant` attribute
+     * The initial highlighted value of the combobox when rendered.
+     * Use when you don't need to control the highlighted value of the combobox.
      */
-    highlightedValue: string | null;
+    defaultHighlightedValue?: string | null | undefined;
     /**
-     * The keys of the selected items
+     * The controlled highlighted value of the combobox
      */
-    value: string[];
+    highlightedValue?: string | null | undefined;
+    /**
+     * The controlled value of the combobox's selected items
+     */
+    value?: string[] | undefined;
+    /**
+     * The initial value of the combobox's selected items when rendered.
+     * Use when you don't need to control the value of the combobox's selected items.
+     * @default []
+     */
+    defaultValue?: string[] | undefined;
     /**
      * Defines the auto-completion behavior of the combobox.
      *
@@ -117,7 +135,7 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      *
      * @default "none"
      */
-    inputBehavior: "autohighlight" | "autocomplete" | "none";
+    inputBehavior?: "autohighlight" | "autocomplete" | "none" | undefined;
     /**
      * The behavior of the combobox input when an item is selected
      *
@@ -127,7 +145,7 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      *
      * @default "replace"
      */
-    selectionBehavior: "clear" | "replace" | "preserve";
+    selectionBehavior?: "clear" | "replace" | "preserve" | undefined;
     /**
      * Whether to autofocus the input on mount
      */
@@ -153,8 +171,9 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
     loopFocus?: boolean | undefined;
     /**
      * The positioning options to dynamically position the menu
+     * @default { placement: "bottom-start" }
      */
-    positioning: PositioningOptions;
+    positioning?: PositioningOptions | undefined;
     /**
      * Function called when the input's value changes
      */
@@ -175,11 +194,11 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
     /**
      * Specifies the localized strings that identifies the accessibility elements and their states
      */
-    translations: IntlTranslations;
+    translations?: IntlTranslations | undefined;
     /**
      * The collection of items
      */
-    collection: ListCollection<any>;
+    collection?: ListCollection<T> | undefined;
     /**
      * Whether to allow multiple selection.
      *
@@ -195,7 +214,7 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      * Whether to open the combobox on arrow key press
      * @default true
      */
-    openOnKeyPress: boolean;
+    openOnKeyPress?: boolean | undefined;
     /**
      * Function to scroll to a specific index
      */
@@ -204,7 +223,7 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
      * Whether the combobox is a composed with other composite widgets like tabs
      * @default true
      */
-    composite: boolean;
+    composite?: boolean | undefined;
     /**
      * Whether to disable registering this a dismissable layer
      */
@@ -212,49 +231,36 @@ interface PublicContext<T extends CollectionItem = CollectionItem> extends Direc
     /**
      * Function to navigate to the selected item
      */
-    navigate: (details: NavigateDetails) => void;
+    navigate?: ((details: NavigateDetails) => void) | undefined;
 }
-type UserDefinedContext<T extends CollectionItem = CollectionItem> = RequiredBy<PublicContext<T>, "id" | "collection">;
-type ComputedContext = Readonly<{
-    /**
-     * @computed
-     * Whether the input's value is empty
-     */
-    isInputValueEmpty: boolean;
-    /**
-     * @computed
-     * Whether the combobox is interactive
-     */
-    isInteractive: boolean;
-    /**
-     * @computed
-     */
-    autoComplete: boolean;
-    /**
-     * @computed
-     */
-    autoHighlight: boolean;
-    /**
-     * @computed
-     * Whether there's a selected option
-     */
-    hasSelectedItems: boolean;
-}>;
-interface PrivateContext<T extends CollectionItem = CollectionItem> {
-    /**
-     * The highlighted item
-     */
-    highlightedItem: T | null;
-}
-interface MachineContext extends PublicContext, PrivateContext, ComputedContext {
-}
-interface MachineState {
-    value: "idle" | "focused" | "suggesting" | "interacting";
-    tags: "open" | "focused" | "idle" | "closed";
+type PropsWithDefault = "openOnChange" | "openOnKeyPress" | "composite" | "navigate" | "loopFocus" | "positioning" | "openOnClick" | "openOnChange" | "inputBehavior" | "collection" | "selectionBehavior" | "closeOnSelect" | "translations" | "positioning";
+interface ComboboxSchema<T extends CollectionItem = CollectionItem> {
+    props: RequiredBy<ComboboxProps<T>, PropsWithDefault>;
+    state: "idle" | "focused" | "suggesting" | "interacting";
+    tag: "open" | "focused" | "idle" | "closed";
+    context: {
+        value: string[];
+        inputValue: string;
+        highlightedValue: string | null;
+        currentPlacement?: Placement | undefined;
+        highlightedItem: T | null;
+        selectedItems: T[];
+        valueAsString: string;
+    };
+    computed: {
+        isInputValueEmpty: boolean;
+        isInteractive: boolean;
+        autoComplete: boolean;
+        autoHighlight: boolean;
+        hasSelectedItems: boolean;
+    };
+    event: EventObject;
+    action: string;
+    effect: string;
+    guard: string;
 }
-type State = StateMachine.State<MachineContext, MachineState>;
-type Send = StateMachine.Send<StateMachine.AnyEventObject>;
-type Service = Machine<MachineContext, MachineState, StateMachine.AnyEventObject>;
+type ComboboxService<T extends CollectionItem = CollectionItem> = Service<ComboboxSchema<T>>;
+type ComboboxMachine<T extends CollectionItem = CollectionItem> = Machine<ComboboxSchema<T>>;
 interface TriggerProps {
     /**
      * Whether the trigger is focusable
@@ -295,7 +301,7 @@ interface ItemGroupProps {
 interface ItemGroupLabelProps {
     htmlFor: string;
 }
-interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem = CollectionItem> {
+interface ComboboxApi<T extends PropTypes = PropTypes, V extends CollectionItem = CollectionItem> {
     /**
      * Whether the combobox is focused
      */
@@ -373,10 +379,6 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
      * Function to toggle the combobox
      */
     collection: ListCollection<V>;
-    /**
-     * Function to set the collection of items
-     */
-    setCollection(collection: ListCollection<V>): void;
     /**
      * Function to set the positioning options
      */
@@ -405,8 +407,17 @@ interface MachineApi<T extends PropTypes = PropTypes, V extends CollectionItem =
     getItemGroupLabelProps(props: ItemGroupLabelProps): T["element"];
 }
 
-declare function connect<T extends PropTypes, V extends CollectionItem>(state: State, send: Send, normalize: NormalizeProps<T>): MachineApi<T, V>;
+declare function connect<T extends PropTypes, V extends CollectionItem>(service: ComboboxService<V>, normalize: NormalizeProps<T>): ComboboxApi<T, V>;
+
+declare const machine: _zag_js_core.Machine<ComboboxSchema<any>>;
 
-declare function machine<T extends CollectionItem>(userContext: UserDefinedContext<T>): _zag_js_core.Machine<MachineContext, MachineState, _zag_js_core.StateMachine.AnyEventObject>;
+declare const props: (keyof ComboboxProps<any>)[];
+declare const splitProps: <Props extends Partial<ComboboxProps<any>>>(props: Props) => [Partial<ComboboxProps<any>>, Omit<Props, keyof ComboboxProps<any>>];
+declare const itemGroupLabelProps: "htmlFor"[];
+declare const splitItemGroupLabelProps: <Props extends ItemGroupLabelProps>(props: Props) => [ItemGroupLabelProps, Omit<Props, "htmlFor">];
+declare const itemGroupProps: "id"[];
+declare const splitItemGroupProps: <Props extends ItemGroupProps>(props: Props) => [ItemGroupProps, Omit<Props, "id">];
+declare const itemProps: (keyof ItemProps)[];
+declare const splitItemProps: <Props extends ItemProps>(props: Props) => [ItemProps, Omit<Props, keyof ItemProps>];
 
-export { type MachineApi as Api, type UserDefinedContext as Context, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type NavigateDetails, type OpenChangeDetails, type ScrollToIndexDetails, type Service, type TriggerProps, type ValueChangeDetails, anatomy, collection, connect, machine };
+export { type ComboboxApi as Api, type ElementIds, type HighlightChangeDetails, type InputValueChangeDetails, type IntlTranslations, type ItemGroupLabelProps, type ItemGroupProps, type ItemProps, type ItemState, type ComboboxMachine as Machine, type NavigateDetails, type OpenChangeDetails, type ComboboxProps as Props, type ScrollToIndexDetails, type ComboboxService as Service, type TriggerProps, type ValueChangeDetails, anatomy, collection, connect, itemGroupLabelProps, itemGroupProps, itemProps, machine, props, splitItemGroupLabelProps, splitItemGroupProps, splitItemProps, splitProps };