@limonify/zest-ui 0.3.1 → 0.4.0

package/src/combobox/backdrop/ComboboxBackdrop.tsx

@@ -2,6 +2,8 @@
 import { Pressable, StyleSheet, type GestureResponderEvent } from 'react-native';
 import { useComboboxRootContext } from '../root/ComboboxRootContext';
 import { useRenderElement } from '../../use-render/useRenderElement';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
 import type { ZestUIComponentProps } from '../../types';
 
 /**
@@ -11,7 +13,8 @@ import type { ZestUIComponentProps } from '../../types';
 export function ComboboxBackdrop(componentProps: ComboboxBackdrop.Props) {
   const { render, className, style, ref, ...elementProps } = componentProps;
 
-  const { open, setOpen } = useComboboxRootContext();
+  const store = useComboboxRootContext();
+  const open = store.useState('open');
 
   const state: ComboboxBackdropState = { open };
 
@@ -22,7 +25,12 @@ export function ComboboxBackdrop(componentProps: ComboboxBackdrop.Props) {
       {
         style: StyleSheet.absoluteFill,
         onPress(event: GestureResponderEvent) {
-          setOpen(false, event);
+          if (store.select('disablePointerDismissal')) {
+            return;
+          }
+
+          store.setOpen(false, createChangeEventDetails(REASONS.outsidePress, event));
+          store.select('inputRef')?.current?.blur();
         },
       },
       elementProps,

package/src/combobox/empty/ComboboxEmpty.tsx

@@ -1,6 +1,7 @@
 'use client';
 import { View } from 'react-native';
 import { useComboboxRootContext } from '../root/ComboboxRootContext';
+import { useComboboxItemsContext } from '../root/ComboboxItemsContext';
 import { useRenderElement } from '../../use-render/useRenderElement';
 import type { ZestUIComponentProps } from '../../types';
 
@@ -11,7 +12,10 @@ import type { ZestUIComponentProps } from '../../types';
 export function ComboboxEmpty(componentProps: ComboboxEmpty.Props) {
   const { render, className, style, ref, ...elementProps } = componentProps;
 
-  const { filteredItems, open } = useComboboxRootContext();
+  const store = useComboboxRootContext();
+  const { filteredItems } = useComboboxItemsContext();
+
+  const open = store.useState('open');
 
   const state: ComboboxEmptyState = { open };
 

package/src/combobox/index.parts.ts

@@ -1,4 +1,5 @@
 export { ComboboxRoot as Root } from './root/ComboboxRoot';
+export { createComboboxHandle as createHandle, ComboboxHandle as Handle } from './store/ComboboxHandle';
 export { ComboboxInput as Input } from './input/ComboboxInput';
 export { ComboboxPortal as Portal } from './portal/ComboboxPortal';
 export { ComboboxBackdrop as Backdrop } from './backdrop/ComboboxBackdrop';

package/src/combobox/index.ts

@@ -14,3 +14,5 @@ export {
   useComboboxRootContext,
   type ComboboxItem as ComboboxItemData,
 } from './root/ComboboxRootContext';
+export { ComboboxHandle } from './store/ComboboxHandle';
+export type { ComboboxItems } from './store/ComboboxStore';

package/src/combobox/input/ComboboxInput.tsx

@@ -1,36 +1,88 @@
 'use client';
 import * as React from 'react';
-import { TextInput } from 'react-native';
-import { useComboboxRootContext } from '../root/ComboboxRootContext';
+import { TextInput, type LayoutChangeEvent } from 'react-native';
+import { ComboboxRootContext } from '../root/ComboboxRootContext';
 import { useRenderElement } from '../../use-render/useRenderElement';
+import { useId } from '../../hooks/useId';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
 import { useMergedRefs } from '../../hooks/useMergedRefs';
+import { usePopupHandleStore } from '../../utils/popups/usePopupHandleStore';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import type { ComboboxHandle } from '../store/ComboboxHandle';
+import type { ComboboxStore } from '../store/ComboboxStore';
 import type { ZestUIComponentProps } from '../../types';
 
 /**
  * The text input that filters the list, and the element the popup is anchored to.
  * Renders a `<TextInput>`.
+ *
+ * Pass a `handle` to render the input outside of its `Combobox.Root`: there is
+ * no context reaching across, so the handle is what connects the two.
  */
-export function ComboboxInput(componentProps: ComboboxInput.Props) {
-  const { render, className, style, ref, ...elementProps } = componentProps;
-
+export function ComboboxInput<Payload = unknown>(componentProps: ComboboxInput.Props<Payload>) {
   const {
-    open,
-    setOpen,
-    inputValue,
-    setInputValue,
-    disabled,
-    openOnFocus,
-    setTriggerNode,
-    update,
-  } = useComboboxRootContext();
+    render,
+    className,
+    style,
+    handle,
+    nativeID: idProp,
+    payload,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const rootStore = React.useContext(ComboboxRootContext);
+  const handleStore = usePopupHandleStore(handle);
+
+  // An input inside a root uses that root; a detached one follows its handle,
+  // which resolves to the attached root's store or to an inert fallback.
+  const store = (handleStore ?? rootStore) as ComboboxStore | undefined;
+
+  if (store === undefined) {
+    throw new Error(
+      'Zest: Combobox.Input must be placed within <Combobox.Root> or <Autocomplete.Root>, or given a `handle` it shares with one.',
+    );
+  }
+
+  const id = useId(idProp ?? undefined);
 
+  const open = store.useState('open');
+  const disabled = store.useState('disabled');
+  const inputValue = store.useState('inputValue');
+  const openOnFocus = store.useState('openOnFocus');
+  const update = store.useState('update');
+
+  const internalRef = React.useRef<TextInput>(null);
+
+  useIsoLayoutEffect(() => {
+    store.set('inputRef', internalRef);
+  }, [store]);
+
+  const triggerRef = React.useRef<unknown>(null);
   const anchorRef = React.useCallback(
     (node: unknown) => {
-      setTriggerNode(node);
+      triggerRef.current = node;
+      store.set('triggerNode', node);
     },
-    [setTriggerNode],
+    [store],
   );
-  const mergedRef = useMergedRefs(ref, anchorRef);
+  const mergedRef = useMergedRefs(ref, anchorRef, internalRef);
+
+  // Registering into whichever store is current is what lets a handle resolve
+  // `open(id)`. The effect re-runs when the handle swaps stores, migrating the
+  // registration to the root that just attached.
+  useIsoLayoutEffect(() => {
+    if (id === undefined) {
+      return undefined;
+    }
+
+    store.context.triggerNodes.add(id, triggerRef.current);
+
+    return () => {
+      store.context.triggerNodes.delete(id);
+    };
+  }, [store, id]);
 
   const state: ComboboxInputState = { open, disabled };
 
@@ -39,20 +91,45 @@ export function ComboboxInput(componentProps: ComboboxInput.Props) {
     ref: mergedRef,
     props: [
       {
+        nativeID: id,
         value: inputValue,
         editable: !disabled,
         onChangeText(text: string) {
-          setInputValue(text);
+          // One event details object is shared, so canceling the text change
+          // also stops the list from opening.
+          const eventDetails = createChangeEventDetails(REASONS.inputChange);
+
+          store.setInputValue(text, eventDetails);
+
+          if (eventDetails.isCanceled) {
+            return;
+          }
+
+          // Typing reopens the list so suggestions follow the query.
+          if (!store.select('open') && text.length > 0) {
+            store.setOpen(true, eventDetails);
+          }
         },
         onFocus() {
+          if (payload !== undefined) {
+            store.set('payload', payload);
+          }
+          if (id !== undefined) {
+            store.set('triggerId', id);
+          }
+
           if (openOnFocus) {
-            setOpen(true);
+            store.setOpen(true, createChangeEventDetails(REASONS.triggerFocus));
           }
         },
-        onLayout() {
+        onLayout(event: LayoutChangeEvent) {
+          const { width, height } = event.nativeEvent.layout;
+          store.set('triggerWidth', width);
+          store.set('triggerHeight', height);
           update?.();
         },
         accessibilityRole: 'search' as const,
+        accessibilityState: { expanded: open, disabled: disabled || undefined },
         'aria-expanded': open,
         'aria-autocomplete': 'list' as const,
       },
@@ -62,14 +139,32 @@ export function ComboboxInput(componentProps: ComboboxInput.Props) {
 }
 
 export interface ComboboxInputState {
+  /**
+   * Whether the list is currently open.
+   */
   open: boolean;
+  /**
+   * Whether the component should ignore user interaction.
+   */
   disabled: boolean;
 }
 
-export interface ComboboxInputProps
-  extends Omit<ZestUIComponentProps<typeof TextInput, ComboboxInputState>, 'value'> {}
+export interface ComboboxInputProps<Payload = unknown>
+  extends Omit<ZestUIComponentProps<typeof TextInput, ComboboxInputState>, 'value'> {
+  /**
+   * A handle shared with a `Combobox.Root`, which is what lets this input live
+   * outside of it. Create one with `Combobox.createHandle()`.
+   *
+   * The input's `nativeID` is the id a handle's `open(triggerId)` resolves.
+   */
+  handle?: ComboboxHandle | undefined;
+  /**
+   * A payload handed to the root's children when they are a function.
+   */
+  payload?: Payload | undefined;
+}
 
 export namespace ComboboxInput {
   export type State = ComboboxInputState;
-  export type Props = ComboboxInputProps;
+  export type Props<Payload = unknown> = ComboboxInputProps<Payload>;
 }

package/src/combobox/item/ComboboxItem.tsx

@@ -1,9 +1,12 @@
 'use client';
 import * as React from 'react';
 import { Pressable, type GestureResponderEvent } from 'react-native';
-import { useComboboxRootContext, type ComboboxItem as ComboboxItemData } from '../root/ComboboxRootContext';
+import { useComboboxRootContext } from '../root/ComboboxRootContext';
 import { useRenderElement } from '../../use-render/useRenderElement';
 import { useCompositeListItem } from '../../internals/composite/list/useCompositeListItem';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import type { ComboboxItem as ComboboxItemData } from '../store/ComboboxStore';
 import type { ZestUIComponentProps } from '../../types';
 
 /**
@@ -13,13 +16,18 @@ import type { ZestUIComponentProps } from '../../types';
 export function ComboboxItem(componentProps: ComboboxItem.Props) {
   const { render, className, style, item, ref, ...elementProps } = componentProps;
 
-  const { selectedValue, selectItem } = useComboboxRootContext();
-  const { onLayout } = useCompositeListItem();
+  const store = useComboboxRootContext();
+  const selectedValue = store.useState('value');
+
+  const { index, onLayout } = useCompositeListItem();
 
   const [pressed, setPressed] = React.useState(false);
   const selected = selectedValue === item.value;
 
-  const state: ComboboxItemState = { selected, pressed };
+  const state: ComboboxItemState = React.useMemo(
+    () => ({ selected, pressed, index }),
+    [selected, pressed, index],
+  );
 
   return useRenderElement(Pressable, componentProps, {
     state,
@@ -28,7 +36,8 @@ export function ComboboxItem(componentProps: ComboboxItem.Props) {
       {
         onLayout,
         onPress(event: GestureResponderEvent) {
-          selectItem(item, event);
+          store.selectItem(item, createChangeEventDetails(REASONS.itemPress, event));
+          store.select('inputRef')?.current?.blur();
         },
         onPressIn: () => setPressed(true),
         onPressOut: () => setPressed(false),
@@ -43,8 +52,18 @@ export function ComboboxItem(componentProps: ComboboxItem.Props) {
 }
 
 export interface ComboboxItemState {
+  /**
+   * Whether this item is the selected one.
+   */
   selected: boolean;
+  /**
+   * Whether the item is currently pressed.
+   */
   pressed: boolean;
+  /**
+   * The item's index in the list, in visual order.
+   */
+  index: number;
 }
 
 export interface ComboboxItemProps extends ZestUIComponentProps<typeof Pressable, ComboboxItemState> {

package/src/combobox/list/ComboboxList.tsx

@@ -1,8 +1,10 @@
 'use client';
 import * as React from 'react';
 import { View } from 'react-native';
-import { useComboboxRootContext, type ComboboxItem } from '../root/ComboboxRootContext';
+import { useComboboxRootContext } from '../root/ComboboxRootContext';
+import { useComboboxItemsContext } from '../root/ComboboxItemsContext';
 import { useRenderElement } from '../../use-render/useRenderElement';
+import type { ComboboxItem } from '../store/ComboboxStore';
 import type { ZestUIComponentProps } from '../../types';
 
 /**
@@ -16,7 +18,10 @@ import type { ZestUIComponentProps } from '../../types';
 export function ComboboxList(componentProps: ComboboxList.Props) {
   const { render, className, style, children, ref, ...elementProps } = componentProps;
 
-  const { filteredItems, open } = useComboboxRootContext();
+  const store = useComboboxRootContext();
+  const { filteredItems } = useComboboxItemsContext();
+
+  const open = store.useState('open');
 
   const state: ComboboxListState = { open, empty: filteredItems.length === 0 };
 

package/src/combobox/popup/ComboboxPopup.tsx

@@ -1,8 +1,12 @@
 'use client';
 import { View } from 'react-native';
 import { useComboboxRootContext } from '../root/ComboboxRootContext';
+import { useComboboxPositionerContext } from '../positioner/ComboboxPositionerContext';
+import { useComboboxTransitionContext } from '../root/ComboboxTransitionContext';
 import { useRenderElement } from '../../use-render/useRenderElement';
 import { CompositeList } from '../../internals/composite/list/CompositeList';
+import type { Align, Side } from '../../utils/useAnchorPositioning';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
 import type { ZestUIComponentProps } from '../../types';
 
 /**
@@ -12,9 +16,22 @@ import type { ZestUIComponentProps } from '../../types';
 export function ComboboxPopup(componentProps: ComboboxPopup.Props) {
   const { render, className, style, ref, ...elementProps } = componentProps;
 
-  const { open } = useComboboxRootContext();
+  const store = useComboboxRootContext();
+  const { side, align } = useComboboxPositionerContext();
+  const { transitionStatus } = useComboboxTransitionContext() ?? { transitionStatus: undefined };
 
-  const state: ComboboxPopupState = { open };
+  const open = store.useState('open');
+  const triggerWidth = store.useState('triggerWidth');
+  const triggerHeight = store.useState('triggerHeight');
+
+  const state: ComboboxPopupState = {
+    open,
+    transitionStatus,
+    side,
+    align,
+    triggerWidth,
+    triggerHeight,
+  };
 
   const element = useRenderElement(View, componentProps, {
     state,
@@ -29,11 +46,36 @@ export function ComboboxPopup(componentProps: ComboboxPopup.Props) {
     ],
   });
 
+  // Items register here so they can be indexed in visual order.
   return <CompositeList>{element}</CompositeList>;
 }
 
 export interface ComboboxPopupState {
+  /**
+   * Whether the list is currently open.
+   */
   open: boolean;
+  /**
+   * The transition status of the list: `'starting'` as it opens (auto-clears to
+   * `undefined` after one frame), `'ending'` once it is closing.
+   */
+  transitionStatus: TransitionStatus;
+  /**
+   * The side the popup was actually placed on, after collision handling.
+   */
+  side: Side;
+  /**
+   * The alignment the popup was actually placed with.
+   */
+  align: Align;
+  /**
+   * The input's measured width, available for consumers to apply to the popup.
+   */
+  triggerWidth: number | undefined;
+  /**
+   * The input's measured height.
+   */
+  triggerHeight: number | undefined;
 }
 
 export interface ComboboxPopupProps extends ZestUIComponentProps<typeof View, ComboboxPopupState> {}

package/src/combobox/portal/ComboboxPortal.tsx

@@ -2,6 +2,9 @@
 import * as React from 'react';
 import { Modal, type NativeSyntheticEvent } from 'react-native';
 import { useComboboxRootContext } from '../root/ComboboxRootContext';
+import { ComboboxPortalContext } from './ComboboxPortalContext';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
 
 /**
  * Moves the popup to the top of the app, as an RN `Modal` like the rest of the
@@ -10,7 +13,8 @@ import { useComboboxRootContext } from '../root/ComboboxRootContext';
 export function ComboboxPortal(props: ComboboxPortal.Props) {
   const { children, keepMounted = false } = props;
 
-  const { open, setOpen } = useComboboxRootContext();
+  const store = useComboboxRootContext();
+  const open = store.useState('open');
 
   const shouldRender = open || keepMounted;
   if (!shouldRender) {
@@ -18,18 +22,20 @@ export function ComboboxPortal(props: ComboboxPortal.Props) {
   }
 
   return (
-    <Modal
-      transparent
-      visible={open}
-      animationType="fade"
-      statusBarTranslucent
-      navigationBarTranslucent
-      onRequestClose={(event: NativeSyntheticEvent<unknown>) => {
-        setOpen(false, event);
-      }}
-    >
-      {children}
-    </Modal>
+    <ComboboxPortalContext.Provider value={keepMounted}>
+      <Modal
+        transparent
+        visible={open}
+        animationType="fade"
+        statusBarTranslucent
+        navigationBarTranslucent
+        onRequestClose={(event: NativeSyntheticEvent<unknown>) => {
+          store.setOpen(false, createChangeEventDetails(REASONS.escapeKey, event));
+        }}
+      >
+        {children}
+      </Modal>
+    </ComboboxPortalContext.Provider>
   );
 }
 

package/src/combobox/portal/ComboboxPortalContext.ts

@@ -0,0 +1,15 @@
+'use client';
+import * as React from 'react';
+
+export const ComboboxPortalContext = React.createContext<boolean | undefined>(undefined);
+
+export function useComboboxPortalContext() {
+  const context = React.useContext(ComboboxPortalContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: ComboboxPortalContext is missing. <Combobox.Positioner> must be placed within <Combobox.Portal>.',
+    );
+  }
+
+  return context;
+}

package/src/combobox/positioner/ComboboxPositioner.tsx

@@ -1,6 +1,9 @@
 'use client';
+import * as React from 'react';
 import { View } from 'react-native';
 import { useComboboxRootContext } from '../root/ComboboxRootContext';
+import { useComboboxPortalContext } from '../portal/ComboboxPortalContext';
+import { ComboboxPositionerContext } from './ComboboxPositionerContext';
 import { useRenderElement } from '../../use-render/useRenderElement';
 import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
 import { useMergedRefs } from '../../hooks/useMergedRefs';
@@ -32,7 +35,13 @@ export function ComboboxPositioner(componentProps: ComboboxPositioner.Props) {
     ...elementProps
   } = componentProps;
 
-  const { open, triggerNode, setUpdate } = useComboboxRootContext();
+  useComboboxPortalContext();
+  const store = useComboboxRootContext();
+
+  const open = store.useState('open');
+  const triggerNode = store.useState('triggerNode');
+  const triggerWidth = store.useState('triggerWidth');
+  const triggerHeight = store.useState('triggerHeight');
 
   const positioning = useAnchorPositioning({
     align,
@@ -51,25 +60,61 @@ export function ComboboxPositioner(componentProps: ComboboxPositioner.Props) {
   }, [refs, triggerNode]);
 
   useIsoLayoutEffect(() => {
-    setUpdate(update);
-    return () => setUpdate(undefined);
-  }, [setUpdate, update]);
+    store.set('update', update);
+    return () => {
+      store.set('update', undefined);
+    };
+  }, [store, update]);
 
   const mergedRef = useMergedRefs(ref, refs.setFloating);
 
-  const state: ComboboxPositionerState = { open, side: positioning.side, align: positioning.align };
+  const state: ComboboxPositionerState = {
+    open,
+    side: positioning.side,
+    align: positioning.align,
+    triggerWidth,
+    triggerHeight,
+  };
+
+  const contextValue: ComboboxPositionerContext = React.useMemo(
+    () => ({ side: positioning.side, align: positioning.align }),
+    [positioning.side, positioning.align],
+  );
 
-  return useRenderElement(View, componentProps, {
+  const element = useRenderElement(View, componentProps, {
     state,
     ref: mergedRef,
-    props: [{ style: positionerStyles, onLayout: () => update() }, elementProps],
+    props: [
+      {
+        style: positionerStyles,
+        onLayout() {
+          update();
+        },
+      },
+      elementProps,
+    ],
   });
+
+  return (
+    <ComboboxPositionerContext.Provider value={contextValue}>
+      {element}
+    </ComboboxPositionerContext.Provider>
+  );
 }
 
 export interface ComboboxPositionerState {
   open: boolean;
   side: Side;
   align: Align;
+  /**
+   * The input's measured width, available for consumers to apply to the popup.
+   * This is the React Native equivalent of the web's `--anchor-width` CSS variable.
+   */
+  triggerWidth: number | undefined;
+  /**
+   * The input's measured height.
+   */
+  triggerHeight: number | undefined;
 }
 
 export interface ComboboxPositionerProps

package/src/combobox/positioner/ComboboxPositionerContext.ts

@@ -0,0 +1,23 @@
+'use client';
+import * as React from 'react';
+import type { Align, Side } from '../../utils/useAnchorPositioning';
+
+export interface ComboboxPositionerContext {
+  side: Side;
+  align: Align;
+}
+
+export const ComboboxPositionerContext = React.createContext<
+  ComboboxPositionerContext | undefined
+>(undefined);
+
+export function useComboboxPositionerContext() {
+  const context = React.useContext(ComboboxPositionerContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: ComboboxPositionerContext is missing. <Combobox.Popup> must be placed within <Combobox.Positioner>.',
+    );
+  }
+
+  return context;
+}

package/src/combobox/root/ComboboxItemsContext.ts

@@ -0,0 +1,32 @@
+'use client';
+import * as React from 'react';
+import type { ComboboxItem } from '../store/ComboboxStore';
+
+export interface ComboboxItemsContext {
+  /**
+   * The items left after filtering by the current query.
+   */
+  filteredItems: ComboboxItem[];
+}
+
+/**
+ * The filtered view of the items.
+ *
+ * This is derived from the store rather than stored in it: a synced store value
+ * only lands in a layout effect, which would leave the list one commit behind
+ * the text the user just typed.
+ */
+export const ComboboxItemsContext = React.createContext<ComboboxItemsContext | undefined>(
+  undefined,
+);
+
+export function useComboboxItemsContext() {
+  const context = React.useContext(ComboboxItemsContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: ComboboxItemsContext is missing. Combobox parts must be placed within <Combobox.Root> or <Autocomplete.Root>.',
+    );
+  }
+
+  return context;
+}