@cdx-ui/primitives 0.3.2 → 0.3.4

package/src/select/types.ts

@@ -1,5 +1,5 @@
 import type { ReactNode, RefObject } from 'react';
-import type { PressableProps, ViewProps } from 'react-native';
+import type { PressableProps, TextInputProps, ViewProps } from 'react-native';
 import type { EntryOrExitLayoutType } from 'react-native-reanimated';
 import type { OverlayPlacement } from '../overlay';
 import type { InteractionState } from '../types';
@@ -9,15 +9,21 @@ export interface SelectItemInteractionState extends InteractionState {
   checked: boolean;
 }
 
-export interface ISelectProps {
+/** Selection mode for `Select`. */
+export type SelectType = 'single' | 'multiple';
+
+/**
+ * Decides whether an option stays visible for the current search query. Receives the option's
+ * `label` from `items` and the query.
+ */
+export type SelectFilter = (textValue: string, inputValue: string) => boolean;
+
+interface ISelectBaseProps {
   /**
    * Options used to resolve `Select.Value` labels and drive keyboard navigation.
    * Render matching `Select.Item` elements inside `Select.Content`.
    */
   items: SelectItemData[];
-  value?: string;
-  defaultValue?: string;
-  onValueChange?: (value: string) => void;
   /** Controlled open state. Use `defaultOpen` for the uncontrolled variant. */
   isOpen?: boolean;
   defaultOpen?: boolean;
@@ -29,9 +35,58 @@ export interface ISelectProps {
   /** Prevents `Select.Content` from rendering. Reserved for native picker integration. */
   native?: boolean;
   accessibilityLabel?: string;
+  /** Controlled search query typed into `Select.Search`. */
+  inputValue?: string;
+  /** Uncontrolled initial search query. */
+  defaultInputValue?: string;
+  /**
+   * Called when the search query changes, including the reset to `''` when the popup closes.
+   * Pair with `inputValue` to replace `items` with server results.
+   */
+  onInputChange?: (inputValue: string) => void;
+  /**
+   * Decides which options stay visible for a non-empty query. Every option is visible while the
+   * query is empty.
+   * @default case- and accent-insensitive `contains`
+   */
+  filter?: SelectFilter;
   children?: ReactNode;
 }
 
+export interface ISelectSingleProps extends ISelectBaseProps {
+  /**
+   * Selection mode. `single` selects one option and closes the popup.
+   * @default 'single'
+   */
+  type?: 'single';
+  /** Controlled selected value. */
+  value?: string;
+  /** Uncontrolled initial value. */
+  defaultValue?: string;
+  /** Called with the newly selected value. */
+  onValueChange?: (value: string) => void;
+}
+
+export interface ISelectMultipleProps extends ISelectBaseProps {
+  /**
+   * Selection mode. `multiple` toggles options on press and keeps the popup open.
+   * Each toggle commits immediately.
+   */
+  type: 'multiple';
+  /** Controlled selected values. An empty array means no selection. */
+  value?: string[];
+  /** Uncontrolled initial values. */
+  defaultValue?: string[];
+  /** Called with the full array of selected values after each toggle. */
+  onValueChange?: (value: string[]) => void;
+}
+
+/**
+ * Discriminated union: `type` narrows `value` / `defaultValue` / `onValueChange` to `string`
+ * (single, the default) or `string[]` (multiple).
+ */
+export type ISelectProps = ISelectSingleProps | ISelectMultipleProps;
+
 export interface ISelectTriggerProps extends PressableProps {
   isHovered?: boolean;
   isActive?: boolean;
@@ -42,9 +97,23 @@ export interface ISelectTriggerProps extends PressableProps {
   'aria-describedby'?: string;
 }
 
+/** State passed to a `Select.Value` function child. */
+export interface SelectValueRenderProps {
+  /** `true` when nothing is selected. */
+  isPlaceholder: boolean;
+  /** Selected options, in `items` order. Values missing from `items` are omitted. */
+  selectedItems: SelectItemData[];
+  /** Labels of `selectedItems` joined with `', '`. Empty when nothing is selected. */
+  selectedText: string;
+}
+
 export interface ISelectValueProps {
   placeholder?: string;
-  children?: ReactNode;
+  /**
+   * Replaces the default display. A function child receives the selection state; return
+   * `null` or `undefined` to fall back to the default (placeholder or `selectedText`).
+   */
+  children?: ReactNode | ((state: SelectValueRenderProps) => ReactNode);
 }
 
 export interface ISelectContentProps extends ViewProps {
@@ -58,6 +127,38 @@ export interface ISelectContentProps extends ViewProps {
   enteringAnimation?: EntryOrExitLayoutType;
   /** Exit animation for the dropdown. Defaults to a 100ms fade. */
   exitingAnimation?: EntryOrExitLayoutType;
+  /**
+   * Accessible name of the visually hidden button that lets screen-reader users close the
+   * popup on web.
+   * @default 'Dismiss'
+   */
+  dismissAccessibilityLabel?: string;
+  children?: ReactNode;
+}
+
+export interface ISelectSheetContentProps extends ViewProps {
+  children?: ReactNode;
+}
+
+export interface ISelectSearchProps extends Omit<
+  TextInputProps,
+  'value' | 'defaultValue' | 'onChangeText' | 'children'
+> {
+  /** Accessible name of the search input. Recommended, because a placeholder is not a label. */
+  accessibilityLabel?: string;
+  /**
+   * Text the polite live region announces when the result count changes, such as
+   * `"3 results"` (the English default). When nothing matches, the `Select.Empty` text is
+   * announced instead.
+   */
+  getResultCountLabel?: (count: number) => string;
+}
+
+export interface ISelectListboxProps extends ViewProps {
+  children?: ReactNode;
+}
+
+export interface ISelectEmptyProps extends ViewProps {
   children?: ReactNode;
 }
 
@@ -78,7 +179,8 @@ export interface ISelectItemLabelProps {
 export interface SelectItemData {
   value: string;
   label: string;
-  disabled?: boolean; // TODO: This isn't working
+  /** Prevents the option from being selected or highlighted by keyboard. */
+  disabled?: boolean;
 }
 
 export interface SelectItemCollectionContextValue {
@@ -91,8 +193,22 @@ export interface SelectContextValue {
   open: boolean;
   items: SelectItemData[];
   setOpen: (open: boolean) => void;
-  value: string | undefined;
-  onValueChange: (value: string) => void;
+  type: SelectType;
+  /** Raw selection: `string` in single mode, `string[]` in multiple mode. */
+  value: string | string[] | undefined;
+  /** Selection normalized to an array for both modes. */
+  selectedValues: string[];
+  isSelected: (value: string) => boolean;
+  /** Adds or removes `value` from the selection without closing. */
+  toggleValue: (value: string) => void;
+  /** Replaces the selection with `value` and closes the popup. */
+  selectValueAndClose: (value: string) => void;
+  /** Commits an option press: `toggleValue` in multiple mode, `selectValueAndClose` in single. */
+  commitValue: (value: string) => void;
+  /** Disabled via the root, `SelectItemData.disabled`, or a mounted `Select.Item disabled`. */
+  isItemDisabled: (value: string) => boolean;
+  /** Called by `Select.Item` so item-level `disabled` reaches keyboard navigation. */
+  registerDisabledItem: (value: string) => () => void;
   disabled: boolean;
   required: boolean;
   invalid: boolean;
@@ -101,6 +217,23 @@ export interface SelectContextValue {
   triggerRef: RefObject<any>;
   contentId: string;
   triggerId: string;
+  /** Current search query. Reset to `''` when the popup closes. */
+  inputValue: string;
+  setInputValue: (inputValue: string) => void;
+  /** `items` that pass `filter` for the current query, in `items` order. */
+  visibleItems: SelectItemData[];
+  isItemVisible: (value: string) => boolean;
+  /** `true` while a `Select.Search` is mounted: the popup becomes a dialog around the listbox. */
+  hasSearch: boolean;
+  /** Called by `Select.Search` on mount. Returns the unregister function. */
+  registerSearch: () => () => void;
+  /** Plain text of `Select.Empty`, announced when nothing matches. */
+  emptyText: string | undefined;
+  setEmptyText: (text: string | undefined) => void;
+  /** Id of the listbox inside the dialog when `hasSearch` is `true`. */
+  listboxId: string;
+  /** `Field.Label` id when the select is inside a `Field`. */
+  labelId?: string;
   /** Currently highlighted value during keyboard navigation */
   activeValue: string | undefined;
   setActiveValue: (value: string | undefined) => void;

package/src/select/useContentFocus.ts

@@ -1,54 +1,35 @@
 import type { RefObject } from 'react';
-import { useCallback, useEffect, useRef } from 'react';
+import { useEffect, useRef } from 'react';
 import { Platform } from 'react-native';
-import type { SelectItemData } from './types';
 
 // TODO: Split into web and native versions?
 
 export interface UseContentFocusOptions {
   open: boolean;
   triggerRef: RefObject<any>;
-  items: SelectItemData[];
-  value: string | undefined;
   setActiveValue: (value: string | undefined) => void;
 }
 
 /**
  * Manages focus lifecycle for overlay content:
+ * - Clears `activeValue` when the overlay closes
  * - Restores focus to the trigger when the overlay closes (web)
- * - Initializes `activeValue` to the current value or first enabled item
  *
- * Initial focus on open is handled via a ref callback in SelectContent
- * to avoid timing issues with deferred portal rendering.
+ * Initial focus on open is handled by `FocusScope autoFocus` in SelectContent, and the
+ * highlight while open by `useQueryHighlight`.
  */
-export function useContentFocus({
-  open,
-  triggerRef,
-  items,
-  value,
-  setActiveValue,
-}: UseContentFocusOptions) {
-  const prevOpenRef = useRef(open);
-
-  const getEnabledItems = useCallback(() => items.filter((item) => !item.disabled), [items]);
+export function useContentFocus({ open, triggerRef, setActiveValue }: UseContentFocusOptions) {
+  const prevOpenRef = useRef(false);
 
   useEffect(() => {
-    if (prevOpenRef.current && !open && Platform.OS === 'web') {
-      triggerRef.current?.focus?.();
-    }
+    const wasOpen = prevOpenRef.current;
     prevOpenRef.current = open;
-  }, [open, triggerRef]);
 
-  useEffect(() => {
-    if (open) {
-      const enabled = getEnabledItems();
-      if (value && enabled.some((i) => i.value === value)) {
-        setActiveValue(value);
-      } else if (enabled.length > 0) {
-        setActiveValue(enabled[0].value);
-      }
-    } else {
+    if (!open) {
       setActiveValue(undefined);
+      if (wasOpen && Platform.OS === 'web') {
+        triggerRef.current?.focus?.();
+      }
     }
-  }, [open, getEnabledItems, setActiveValue, value]);
+  }, [open, setActiveValue, triggerRef]);
 }

package/src/select/useListboxNavigation.ts

@@ -1,30 +1,53 @@
 import { useCallback, useRef } from 'react';
-import type { SelectItemData } from './types';
+import type { SelectItemData, SelectType } from './types';
 
 // TODO: Split into web and native versions?
 
 export interface UseListboxNavigationOptions {
+  /** Options to navigate, in display order. Pass the filtered list when a search is present. */
   items: SelectItemData[];
   activeValue: string | undefined;
   setActiveValue: (value: string | undefined) => void;
-  onSelect: (value: string) => void;
+  type: SelectType;
+  /** Commit for `type="multiple"`: toggles the highlighted option and keeps the listbox open. */
+  onToggle: (value: string) => void;
+  /** Commit for `type="single"`: selects the highlighted option and closes the listbox. */
+  onSelectAndClose: (value: string) => void;
+  /** Excludes options from keyboard highlight and commit. */
+  isItemDisabled: (value: string) => boolean;
   onDismiss: () => void;
+  /**
+   * Keys arrive from the `Select.Search` input (virtual focus). Space types instead of
+   * committing, Home/End move the caret, and Enter is always consumed so the input neither
+   * blurs nor submits an enclosing form.
+   */
+  isSearch?: boolean;
 }
 
+/** Keys the search input keeps for text editing: Space types, Home/End move the caret. */
+const SEARCH_INPUT_KEYS = new Set([' ', 'Home', 'End']);
+
 export function useListboxNavigation({
   items,
   activeValue,
   setActiveValue,
-  onSelect,
+  type,
+  onToggle,
+  onSelectAndClose,
+  isItemDisabled,
   onDismiss,
+  isSearch = false,
 }: UseListboxNavigationOptions) {
-  const onSelectRef = useRef(onSelect);
-  onSelectRef.current = onSelect;
+  const commitRef = useRef(onSelectAndClose);
+  commitRef.current = type === 'multiple' ? onToggle : onSelectAndClose;
 
   const onDismissRef = useRef(onDismiss);
   onDismissRef.current = onDismiss;
 
-  const getEnabledItems = useCallback(() => items.filter((item) => !item.disabled), [items]);
+  const getEnabledItems = useCallback(
+    () => items.filter((item) => !isItemDisabled(item.value)),
+    [items, isItemDisabled],
+  );
 
   const handleKeyDown = useCallback(
     (e: any) => {
@@ -40,6 +63,15 @@ export function useListboxNavigation({
         return;
       }
 
+      if (isSearch && SEARCH_INPUT_KEYS.has(e.key)) {
+        return;
+      }
+
+      if (isSearch && e.key === 'Enter') {
+        // Keeps the input from blurring or submitting an enclosing form, even with no match.
+        e.preventDefault();
+      }
+
       const enabledItems = getEnabledItems();
       if (enabledItems.length === 0) {
         return;
@@ -74,14 +106,14 @@ export function useListboxNavigation({
         case 'Enter':
         case ' ': {
           e.preventDefault();
-          if (activeValue) {
-            onSelectRef.current(activeValue);
+          if (activeValue !== undefined && idx !== -1) {
+            commitRef.current(activeValue);
           }
           break;
         }
       }
     },
-    [activeValue, getEnabledItems, setActiveValue],
+    [activeValue, getEnabledItems, isSearch, setActiveValue],
   );
 
   return { handleKeyDown, getEnabledItems };

package/src/select/useQueryHighlight.ts

@@ -0,0 +1,61 @@
+import { useEffect, useRef } from 'react';
+import type { SelectItemData } from './types';
+
+export interface UseQueryHighlightOptions {
+  open: boolean;
+  inputValue: string;
+  visibleItems: SelectItemData[];
+  selectedValues: string[];
+  isItemDisabled: (value: string) => boolean;
+  activeValue: string | undefined;
+  setActiveValue: (value: string | undefined) => void;
+}
+
+/**
+ * Owns the highlight while open:
+ * - Unset (on open, or once async `items` arrive): the first enabled selected item, or the
+ *   first enabled item.
+ * - Query change: the first enabled match.
+ * - Hidden by the filter or a swapped `items` list: the first enabled item.
+ *
+ * Otherwise the highlight stays put, so a multiple-mode toggle does not move it.
+ */
+export function useQueryHighlight({
+  open,
+  inputValue,
+  visibleItems,
+  selectedValues,
+  isItemDisabled,
+  activeValue,
+  setActiveValue,
+}: UseQueryHighlightOptions) {
+  const prevInputValueRef = useRef(inputValue);
+  const selectedRef = useRef(selectedValues);
+  selectedRef.current = selectedValues;
+
+  useEffect(() => {
+    const queryChanged = prevInputValueRef.current !== inputValue;
+    prevInputValueRef.current = inputValue;
+
+    if (!open) {
+      return;
+    }
+
+    const enabled = visibleItems.filter((item) => !isItemDisabled(item.value));
+
+    if (activeValue === undefined) {
+      const selected = selectedRef.current;
+      const initial = enabled.find((item) => selected.includes(item.value)) ?? enabled.at(0);
+      if (initial) {
+        setActiveValue(initial.value);
+      }
+      return;
+    }
+
+    const activeHidden = !enabled.some((item) => item.value === activeValue);
+
+    if (queryChanged || activeHidden) {
+      setActiveValue(enabled.at(0)?.value);
+    }
+  }, [open, inputValue, visibleItems, isItemDisabled, activeValue, setActiveValue]);
+}

package/src/select/useSelectTrigger.ts

@@ -142,6 +142,7 @@ export function useSelectTrigger(
     contentId,
     triggerRef,
     activeValue,
+    hasSearch,
     accessibilityLabel,
     ariaDescribedBy: ariaDescribedByFromField,
   } = useSelectContext();
@@ -278,10 +279,13 @@ export function useSelectTrigger(
   const ariaProps: SelectTriggerAriaProps = {
     role: 'combobox',
     'aria-label': accessibilityLabel,
+    // Kept as `listbox` with search too (RAC's choice), pending the a11y spike (DEVEX-8289).
     'aria-haspopup': 'listbox',
     'aria-expanded': open,
     'aria-controls': contentId,
-    'aria-activedescendant': open && activeValue ? `${contentId}-option-${activeValue}` : undefined,
+    // With search, the input owns the active descendant.
+    'aria-activedescendant':
+      open && activeValue && !hasSearch ? `${contentId}-option-${activeValue}` : undefined,
     'aria-required': contextRequired || undefined,
     'aria-invalid': contextInvalid || undefined,
     'aria-readonly': contextReadOnly || undefined,

package/src/select/useSelectTrigger.web.ts

@@ -78,6 +78,7 @@ export function useSelectTrigger(
     contentId,
     triggerRef,
     activeValue,
+    hasSearch,
     accessibilityLabel,
     ariaDescribedBy: ariaDescribedByFromField,
   } = useSelectContext();
@@ -207,10 +208,13 @@ export function useSelectTrigger(
   const ariaProps: SelectTriggerAriaProps = {
     role: 'combobox',
     'aria-label': accessibilityLabel,
+    // Kept as `listbox` with search too (RAC's choice), pending the a11y spike (DEVEX-8289).
     'aria-haspopup': 'listbox',
     'aria-expanded': open,
     'aria-controls': contentId,
-    'aria-activedescendant': open && activeValue ? `${contentId}-option-${activeValue}` : undefined,
+    // With search, the input owns the active descendant.
+    'aria-activedescendant':
+      open && activeValue && !hasSearch ? `${contentId}-option-${activeValue}` : undefined,
     'aria-required': contextRequired || undefined,
     'aria-invalid': contextInvalid || undefined,
     'aria-readonly': contextReadOnly || undefined,

package/src/utils/splitContainerProps.ts

@@ -0,0 +1,16 @@
+/**
+ * Splits the props a split root's container keeps (`className`, data attributes) from the ones
+ * its press region receives.
+ */
+export function splitContainerProps(props: Record<string, unknown>) {
+  const container: Record<string, unknown> = {};
+  const region: Record<string, unknown> = {};
+  for (const key in props) {
+    if (key === 'className' || key === 'dataSet' || key.startsWith('data-')) {
+      container[key] = props[key];
+    } else {
+      region[key] = props[key];
+    }
+  }
+  return { container, region };
+}