@limonify/zest-ui 0.3.1 → 0.4.0

package/src/combobox/root/ComboboxRoot.tsx

@@ -1,8 +1,10 @@
 'use client';
-import * as React from 'react';
-import type { ZestNativeEvent } from '../../utils/createChangeEventDetails';
-import { ComboboxRootContext, type ComboboxItem } from './ComboboxRootContext';
-import { useComboboxRoot, type ComboboxItems } from './useComboboxRoot';
+import type * as React from 'react';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import type { REASONS } from '../../utils/reasons';
+import type { ComboboxHandle } from '../store/ComboboxHandle';
+import type { ComboboxItem, ComboboxItems } from '../store/ComboboxStore';
+import { useRenderComboboxRoot } from './useRenderComboboxRoot';
 
 /**
  * Groups all parts of the combobox: a text input that filters a list of items,
@@ -12,50 +14,28 @@ import { useComboboxRoot, type ComboboxItems } from './useComboboxRoot';
  * **Adapted from upstream.** Base UI's Combobox is a large component built on a
  * shared collection/filter core with chips, groups, rows and virtualization.
  * This is a focused React Native port: an input, a filtered list, and single
- * selection. Filtering is a case-insensitive label match by default; pass
- * `filter` to change it.
+ * selection. Filtering is a locale-aware label match by default (see
+ * `useFilter`); pass `filter` to change it.
  */
-export function ComboboxRoot(props: ComboboxRoot.Props) {
-  const {
-    items,
-    value,
-    defaultValue,
-    onValueChange,
-    inputValue,
-    defaultInputValue,
-    onInputValueChange,
-    open,
-    defaultOpen,
-    onOpenChange,
-    openOnFocus,
-    filter,
-    disabled = false,
-    children,
-  } = props;
-
-  const contextValue = useComboboxRoot({
-    mode: 'combobox',
-    items,
-    value,
-    defaultValue,
-    onValueChange,
-    inputValue,
-    defaultInputValue,
-    onInputValueChange,
-    open,
-    defaultOpen,
-    onOpenChange,
-    openOnFocus,
-    filter,
-    disabled,
-  });
-
-  return <ComboboxRootContext.Provider value={contextValue}>{children}</ComboboxRootContext.Provider>;
+export function ComboboxRoot<Payload = unknown>(props: ComboboxRoot.Props<Payload>) {
+  return useRenderComboboxRoot(props, 'combobox');
 }
 
 export interface ComboboxRootState {}
 
-export interface ComboboxRootProps {
+export interface ComboboxRootActions {
+  /**
+   * Unmounts the list without firing `onOpenChange`. Call it after an
+   * externally controlled closing animation finishes.
+   */
+  unmount: () => void;
+  /**
+   * Closes the list, reporting the `imperative-action` reason.
+   */
+  close: () => void;
+}
+
+export interface ComboboxRootProps<Payload = unknown> {
   /**
    * The items to filter and choose from. Strings, or `{ value, label }` records
    * for non-string values.
@@ -63,16 +43,20 @@ export interface ComboboxRootProps {
   items?: ComboboxItems | undefined;
   /**
    * The selected value.
+   *
+   * To render an uncontrolled combobox, use the `defaultValue` prop instead.
    */
   value?: unknown;
   /**
-   * The initially selected value when uncontrolled.
+   * The initially selected value.
+   *
+   * To render a controlled combobox, use the `value` prop instead.
    */
   defaultValue?: unknown;
   /**
-   * Called when the selection changes.
+   * Event handler called when the selection changes.
    */
-  onValueChange?: ((value: unknown) => void) | undefined;
+  onValueChange?: ((value: any, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
   /**
    * The controlled input text.
    */
@@ -82,39 +66,93 @@ export interface ComboboxRootProps {
    */
   defaultInputValue?: string | undefined;
   /**
-   * Called as the input text changes.
+   * Event handler called as the input text changes.
    */
-  onInputValueChange?: ((value: string) => void) | undefined;
+  onInputValueChange?:
+    | ((value: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void)
+    | undefined;
   /**
-   * Whether the list is open.
+   * Whether the list is currently open.
    */
   open?: boolean | undefined;
   /**
-   * Whether the list is initially open when uncontrolled.
+   * Whether the list is initially open.
+   *
+   * To render a controlled combobox, use the `open` prop instead.
+   * @default false
    */
   defaultOpen?: boolean | undefined;
   /**
-   * Called when the list opens or closes.
+   * Event handler called when the list is opened or closed.
    */
-  onOpenChange?: ((open: boolean, event?: ZestNativeEvent) => void) | undefined;
+  onOpenChange?:
+    | ((open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void)
+    | undefined;
   /**
    * Whether focusing the input opens the list.
    * @default true
    */
   openOnFocus?: boolean | undefined;
   /**
-   * A custom filter predicate. Defaults to a case-insensitive label match.
+   * A custom filter predicate. Defaults to a locale-aware label match, so
+   * "resume" finds "Résumé" — see `useFilter` to build your own.
    */
   filter?: ((item: ComboboxItem, query: string) => boolean) | undefined;
   /**
-   * Whether the combobox is disabled.
+   * Whether the component should ignore user interaction.
    * @default false
    */
   disabled?: boolean | undefined;
-  children?: React.ReactNode;
+  /**
+   * Whether to prevent the list from closing on presses outside the popup.
+   * @default false
+   */
+  disablePointerDismissal?: boolean | undefined;
+  /**
+   * A ref to imperative actions.
+   */
+  actionsRef?: React.RefObject<ComboboxRoot.Actions | null> | undefined;
+  /**
+   * A handle associating this combobox with an input rendered outside it, and
+   * letting it be opened and closed imperatively. Create one with
+   * `Combobox.createHandle()`.
+   */
+  handle?: ComboboxHandle | undefined;
+  /**
+   * The id of the input the list is anchored to. Useful together with the `open`
+   * prop, to control which input a controlled list belongs to.
+   */
+  triggerId?: string | null | undefined;
+  /**
+   * The id of the input the list is initially anchored to. Useful together with
+   * `defaultOpen`.
+   */
+  defaultTriggerId?: string | null | undefined;
+  /**
+   * The content of the combobox.
+   *
+   * Pass a function to receive the payload the list was opened with, via a
+   * detached input's `payload` prop.
+   */
+  children?: React.ReactNode | ((payload: Payload) => React.ReactNode);
 }
 
+export type ComboboxRootChangeEventReason =
+  | typeof REASONS.inputPress
+  | typeof REASONS.inputChange
+  | typeof REASONS.triggerFocus
+  | typeof REASONS.itemPress
+  | typeof REASONS.outsidePress
+  | typeof REASONS.escapeKey
+  | typeof REASONS.imperativeAction
+  | typeof REASONS.none;
+
+export type ComboboxRootChangeEventDetails = ZestChangeEventDetails<ComboboxRootChangeEventReason>;
+
 export namespace ComboboxRoot {
   export type State = ComboboxRootState;
-  export type Props = ComboboxRootProps;
+  export type Props<Payload = unknown> = ComboboxRootProps<Payload>;
+  export type Actions = ComboboxRootActions;
+  export type ChangeEventReason = ComboboxRootChangeEventReason;
+  export type ChangeEventDetails = ComboboxRootChangeEventDetails;
 }

package/src/combobox/root/ComboboxRootContext.ts

@@ -1,50 +1,10 @@
 'use client';
 import * as React from 'react';
-import type { ZestNativeEvent } from '../../utils/createChangeEventDetails';
+import type { ComboboxStore } from '../store/ComboboxStore';
 
-export interface ComboboxItem {
-  value: unknown;
-  label: string;
-}
-
-export interface ComboboxRootContext {
-  /**
-   * `'combobox'` selects a value and shows its label; `'autocomplete'` is free
-   * text with suggestions, where the typed string is the value.
-   */
-  mode: 'combobox' | 'autocomplete';
-  open: boolean;
-  setOpen: (open: boolean, event?: ZestNativeEvent) => void;
-  inputValue: string;
-  setInputValue: (value: string) => void;
-  /**
-   * The selected value (combobox mode only). `null` when nothing is selected.
-   */
-  selectedValue: unknown;
-  /**
-   * Selects an item: records the value, fills the input with its label, and
-   * closes the popup.
-   */
-  selectItem: (item: ComboboxItem, event?: ZestNativeEvent) => void;
-  /**
-   * The items after filtering by the current input value.
-   */
-  filteredItems: ComboboxItem[];
-  disabled: boolean;
-  /**
-   * Whether focusing the input opens the list.
-   */
-  openOnFocus: boolean;
-  /**
-   * The anchor's native node, carried across the portal boundary.
-   */
-  triggerNode: unknown;
-  setTriggerNode: (node: unknown) => void;
-  update: (() => void) | undefined;
-  setUpdate: (fn: (() => void) | undefined) => void;
-}
+export type { ComboboxItem, ComboboxItems } from '../store/ComboboxStore';
 
-export const ComboboxRootContext = React.createContext<ComboboxRootContext | undefined>(undefined);
+export const ComboboxRootContext = React.createContext<ComboboxStore | undefined>(undefined);
 
 export function useComboboxRootContext() {
   const context = React.useContext(ComboboxRootContext);

package/src/combobox/root/ComboboxTransitionContext.ts

@@ -0,0 +1,15 @@
+'use client';
+import * as React from 'react';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
+
+export interface ComboboxTransitionContext {
+  transitionStatus: TransitionStatus;
+}
+
+export const ComboboxTransitionContext = React.createContext<
+  ComboboxTransitionContext | undefined
+>(undefined);
+
+export function useComboboxTransitionContext() {
+  return React.useContext(ComboboxTransitionContext);
+}

package/src/combobox/root/useRenderComboboxRoot.tsx

@@ -0,0 +1,189 @@
+'use client';
+import * as React from 'react';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import { useRefWithInit } from '../../hooks/useRefWithInit';
+import { useTransitionStatus } from '../../internals/useTransitionStatus';
+import { usePopupRootHandle } from '../../utils/popups/usePopupRootHandle';
+import { useFilter } from '../../filter/useFilter';
+import type { ComboboxHandle } from '../store/ComboboxHandle';
+import {
+  ComboboxStore,
+  normalizeComboboxItems,
+  type ComboboxItem,
+  type ComboboxItems,
+} from '../store/ComboboxStore';
+import type { ComboboxRoot } from './ComboboxRoot';
+import { ComboboxItemsContext } from './ComboboxItemsContext';
+import { ComboboxRootContext } from './ComboboxRootContext';
+import { ComboboxTransitionContext } from './ComboboxTransitionContext';
+
+export type ComboboxMode = 'combobox' | 'autocomplete';
+
+/**
+ * The props both `Combobox.Root` and `Autocomplete.Root` accept. An
+ * autocomplete's value *is* its input text, so it omits the selection props.
+ */
+export interface UseRenderComboboxRootProps<Payload = unknown> {
+  items?: ComboboxItems | undefined;
+  value?: unknown;
+  defaultValue?: unknown;
+  onValueChange?: ((value: any, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
+  inputValue?: string | undefined;
+  defaultInputValue?: string | undefined;
+  onInputValueChange?:
+    | ((value: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void)
+    | undefined;
+  open?: boolean | undefined;
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
+  openOnFocus?: boolean | undefined;
+  filter?: ((item: ComboboxItem, query: string) => boolean) | undefined;
+  disabled?: boolean | undefined;
+  disablePointerDismissal?: boolean | undefined;
+  actionsRef?: React.RefObject<ComboboxRoot.Actions | null> | undefined;
+  handle?: ComboboxHandle | undefined;
+  triggerId?: string | null | undefined;
+  defaultTriggerId?: string | null | undefined;
+  children?: React.ReactNode | ((payload: Payload) => React.ReactNode);
+}
+
+/**
+ * The shared Root implementation behind `Combobox.Root` and `Autocomplete.Root`.
+ *
+ * The two differ only in whether choosing an item records a separate value:
+ * a combobox selects `item.value` and shows its label, an autocomplete puts the
+ * typed text itself forward and treats the list as suggestions.
+ */
+export function useRenderComboboxRoot<Payload = unknown>(
+  props: UseRenderComboboxRootProps<Payload>,
+  mode: ComboboxMode,
+) {
+  const {
+    actionsRef,
+    children,
+    defaultInputValue,
+    defaultOpen = false,
+    defaultTriggerId = null,
+    defaultValue,
+    disablePointerDismissal = false,
+    disabled = false,
+    filter,
+    handle,
+    inputValue,
+    items,
+    onInputValueChange,
+    onOpenChange,
+    onValueChange,
+    open,
+    openOnFocus = true,
+    triggerId,
+    value,
+  } = props;
+
+  const normalizedItems = React.useMemo(() => normalizeComboboxItems(items), [items]);
+
+  const { contains } = useFilter();
+  const filterItem = React.useMemo(
+    () => filter ?? ((item: ComboboxItem, query: string) => contains(item.label, query)),
+    [filter, contains],
+  );
+
+  // The initial input text is only read on the first render; compute it once so
+  // it stays stable, or a later selection changing the controlled `value` (and
+  // with it the derived label) would look like a controlled/uncontrolled switch.
+  const initialInputRef = React.useRef<string | undefined>(undefined);
+  if (initialInputRef.current === undefined) {
+    initialInputRef.current =
+      defaultInputValue ??
+      (mode === 'combobox'
+        ? (normalizedItems.find((item) => item.value === (value ?? defaultValue))?.label ?? '')
+        : '');
+  }
+
+  const store = useRefWithInit(
+    () =>
+      new ComboboxStore({
+        open: defaultOpen,
+        openProp: open,
+        value: defaultValue ?? null,
+        valueProp: value,
+        inputValue: initialInputRef.current!,
+        inputValueProp: inputValue,
+        items: normalizedItems,
+        mode,
+        disabled,
+        disablePointerDismissal,
+        openOnFocus,
+        triggerId: defaultTriggerId,
+        triggerIdProp: triggerId,
+      }),
+  ).current;
+
+  store.useControlledProp('openProp', open);
+  store.useControlledProp('valueProp', value);
+  store.useControlledProp('inputValueProp', inputValue);
+  store.useControlledProp('triggerIdProp', triggerId);
+  store.useContextCallback('onOpenChange', onOpenChange);
+  store.useContextCallback('onValueChange', onValueChange);
+  store.useContextCallback('onInputValueChange', onInputValueChange);
+  store.useSyncedValues({
+    mode,
+    disabled,
+    disablePointerDismissal,
+    openOnFocus,
+    items: normalizedItems,
+  });
+
+  usePopupRootHandle({ store, handle, actionsRef });
+
+  const resolvedOpen = store.useState('open');
+  const selectedValue = store.useState('value');
+  const currentInputValue = store.useState('inputValue');
+
+  // The label of the currently selected value (combobox mode only).
+  const selectedLabel =
+    mode === 'combobox'
+      ? (normalizedItems.find((item) => item.value === selectedValue)?.label ?? '')
+      : '';
+
+  // Reflect a controlled `value` that changed from outside into the input text.
+  // `selectItem` already sets both, so the ref guard makes that a no-op and stops
+  // this from fighting the user's typing (typing never changes the selection).
+  const lastReflectedValueRef = React.useRef(selectedValue);
+  useIsoLayoutEffect(() => {
+    if (mode !== 'combobox' || selectedValue === lastReflectedValueRef.current) {
+      return;
+    }
+    lastReflectedValueRef.current = selectedValue;
+    store.reflectInputValue(selectedLabel);
+  }, [mode, selectedValue, selectedLabel, store]);
+
+  const filteredItems = React.useMemo(() => {
+    // When the input still shows the current selection, the user has not started
+    // filtering — show every item so a fresh focus reveals the whole list rather
+    // than the single selected row.
+    const query =
+      mode === 'combobox' && currentInputValue === selectedLabel ? '' : currentInputValue.trim();
+    if (query.length === 0) {
+      return normalizedItems;
+    }
+    return normalizedItems.filter((item) => filterItem(item, query));
+  }, [normalizedItems, currentInputValue, selectedLabel, mode, filterItem]);
+
+  const { transitionStatus } = useTransitionStatus(resolvedOpen, false, true);
+
+  const itemsContextValue = React.useMemo(() => ({ filteredItems }), [filteredItems]);
+  const transitionContextValue = React.useMemo(() => ({ transitionStatus }), [transitionStatus]);
+
+  const payload = store.useState('payload') as Payload;
+
+  return (
+    <ComboboxRootContext.Provider value={store}>
+      <ComboboxItemsContext.Provider value={itemsContextValue}>
+        <ComboboxTransitionContext.Provider value={transitionContextValue}>
+          {typeof children === 'function' ? children(payload) : children}
+        </ComboboxTransitionContext.Provider>
+      </ComboboxItemsContext.Provider>
+    </ComboboxRootContext.Provider>
+  );
+}

package/src/combobox/store/ComboboxHandle.ts

@@ -0,0 +1,64 @@
+import { ComboboxStore } from './ComboboxStore';
+import { BasePopupHandle } from '../../utils/popups/BasePopupHandle';
+
+/**
+ * Controls a combobox imperatively, and associates a `Combobox.Input` rendered
+ * outside the root with it. Create one with `Combobox.createHandle()` and pass
+ * it to the root's and the input's `handle` prop.
+ *
+ * The imperative methods only take effect while a root using this handle is
+ * mounted; calls made before one attaches (or after it unmounts) are ignored.
+ */
+export class ComboboxHandle extends BasePopupHandle<ComboboxStore, ComboboxStore> {
+  constructor(componentName: string = 'Combobox') {
+    // `true`: the list is anchored to the input, so opening it by an unknown
+    // trigger id is an error rather than a warning — there would be nothing to
+    // anchor to.
+    super(new ComboboxStore(), componentName, true);
+  }
+
+  /**
+   * Points the positioner at the input the list was opened from. Without this an
+   * imperative open would anchor to whatever was last measured.
+   */
+  protected override associateTrigger(store: ComboboxStore, triggerNode: unknown) {
+    if (triggerNode !== undefined) {
+      store.set('triggerNode', triggerNode);
+    }
+  }
+
+  /**
+   * Opens the list, anchored to the input with the given id.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   *
+   * @param triggerId The `nativeID` of a mounted `Combobox.Input` carrying this handle.
+   */
+  open(triggerId: string) {
+    this.openByTrigger(triggerId);
+  }
+
+  /**
+   * Closes the list.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   */
+  close() {
+    this.closePopup();
+  }
+
+  /**
+   * Whether the list is open. `false` while no root is attached.
+   */
+  get isOpen() {
+    return this.attachedStore?.select('open') ?? false;
+  }
+}
+
+/**
+ * Creates a handle that connects a `Combobox.Root` to a `Combobox.Input`
+ * rendered outside it, and controls it imperatively.
+ */
+export function createComboboxHandle(): ComboboxHandle {
+  return new ComboboxHandle();
+}