@cdx-ui/primitives 0.0.1-alpha.1

package/src/overlay/useAnchorPosition.ts

@@ -0,0 +1,72 @@
+import type { RefObject } from 'react';
+import { useEffect, useLayoutEffect, useState } from 'react';
+import { Platform } from 'react-native';
+
+const useIsomorphicLayoutEffect = Platform.OS === 'web' ? useLayoutEffect : useEffect;
+
+export interface AnchorLayout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+function measureWeb(element: any): AnchorLayout {
+  const rect = (element as unknown as HTMLElement).getBoundingClientRect();
+  return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+}
+
+/**
+ * Measures an anchor element's position and size, re-measuring on scroll/resize
+ * (web) so a positioned overlay can track its anchor across layout changes.
+ *
+ * Returns `null` until the first measurement completes.
+ */
+export function useAnchorPosition(anchorRef: RefObject<any>, open: boolean): AnchorLayout | null {
+  const [layout, setLayout] = useState<AnchorLayout | null>(null);
+
+  useIsomorphicLayoutEffect(() => {
+    if (!open) {
+      setLayout(null);
+      return;
+    }
+
+    const anchor = anchorRef.current;
+    if (!anchor) return;
+
+    let cancelled = false;
+
+    if (Platform.OS === 'web') {
+      setLayout(measureWeb(anchor));
+    } else {
+      anchor.measureInWindow((x: number, y: number, width: number, height: number) => {
+        if (!cancelled) {
+          setLayout({ x, y, width, height });
+        }
+      });
+    }
+
+    return () => {
+      cancelled = true;
+    };
+  }, [open, anchorRef]);
+
+  useEffect(() => {
+    if (!open || Platform.OS !== 'web') return;
+
+    const anchor = anchorRef.current;
+    if (!anchor) return;
+
+    const update = () => setLayout(measureWeb(anchor));
+
+    window.addEventListener('scroll', update, true);
+    window.addEventListener('resize', update);
+
+    return () => {
+      window.removeEventListener('scroll', update, true);
+      window.removeEventListener('resize', update);
+    };
+  }, [open, anchorRef]);
+
+  return layout;
+}

package/src/overlay/useDismissOverlay.ts

@@ -0,0 +1,14 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import type { RefObject } from 'react';
+
+/**
+ * No-op on native — overlay dismissal is handled by backdrop press
+ * or the system back gesture / hardware button via Modal.
+ */
+export function useDismissOverlay(
+  _open: boolean,
+  _contentRef: RefObject<any>,
+  _excludeRefs: RefObject<any>[],
+  _onDismiss: () => void,
+) {}

package/src/overlay/useDismissOverlay.web.ts

@@ -0,0 +1,51 @@
+import type { RefObject } from 'react';
+import { useEffect, useRef } from 'react';
+
+/**
+ * Dismisses an overlay when the user clicks/presses outside of it or when
+ * focus moves to an element outside the overlay via keyboard.
+ * Events targeting `contentRef` or any of `excludeRefs` are ignored.
+ */
+export function useDismissOverlay(
+  open: boolean,
+  contentRef: RefObject<any>,
+  excludeRefs: RefObject<any>[],
+  onDismiss: () => void,
+) {
+  const onDismissRef = useRef(onDismiss);
+  onDismissRef.current = onDismiss;
+
+  const excludeRefsRef = useRef(excludeRefs);
+  excludeRefsRef.current = excludeRefs;
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    const isInsideOverlay = (target: Node) => {
+      if (contentRef.current?.contains?.(target)) {
+        return true;
+      }
+      for (const ref of excludeRefsRef.current) {
+        if (ref.current?.contains?.(target)) {
+          return true;
+        }
+      }
+      return false;
+    };
+
+    const dismissIfOutside = (e: Event) => {
+      if (!isInsideOverlay(e.target as Node)) {
+        onDismissRef.current();
+      }
+    };
+
+    document.addEventListener('pointerdown', dismissIfOutside);
+    document.addEventListener('focusin', dismissIfOutside);
+    return () => {
+      document.removeEventListener('pointerdown', dismissIfOutside);
+      document.removeEventListener('focusin', dismissIfOutside);
+    };
+  }, [open, contentRef]);
+}

package/src/overlay/useOverlayPosition.ts

@@ -0,0 +1,96 @@
+import { createContext, useContext, useMemo } from 'react';
+import { useWindowDimensions, type ViewStyle } from 'react-native';
+import type { AnchorLayout } from './useAnchorPosition';
+
+export interface EdgeInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+const DEFAULT_INSETS: EdgeInsets = { top: 0, right: 0, bottom: 0, left: 0 };
+
+/**
+ * Provides safe-area insets to overlay positioning hooks. Wrap your app
+ * root with this provider and pass values from `useSafeAreaInsets()` to
+ * enable safe-area-aware overlay placement.
+ *
+ * @example
+ * ```tsx
+ * import { useSafeAreaInsets } from 'react-native-safe-area-context';
+ * import { OverlayInsetsProvider } from '@cdx-ui/primitives';
+ *
+ * function App() {
+ *   const insets = useSafeAreaInsets();
+ *   return (
+ *     <OverlayInsetsProvider value={insets}>
+ *       {children}
+ *     </OverlayInsetsProvider>
+ *   );
+ * }
+ * ```
+ */
+export const OverlayInsetsContext = createContext<EdgeInsets>(DEFAULT_INSETS);
+export const OverlayInsetsProvider = OverlayInsetsContext.Provider;
+
+/** Minimum gap (px) between the overlay edge and the viewport/safe-area boundary. */
+const SCREEN_EDGE_PADDING = 8;
+
+/** Minimum usable space (px) below the anchor before the overlay flips above. */
+const MIN_CONTENT_HEIGHT = 200;
+
+export interface OverlayPosition {
+  style: ViewStyle;
+  maxHeight: number;
+  placement: 'top' | 'bottom';
+}
+
+/**
+ * Computes viewport-aware overlay positioning relative to an anchor element.
+ * Automatically flips placement from bottom to top when insufficient space
+ * exists below the anchor. Constrains `maxHeight` to available space so
+ * content never extends beyond the screen edge.
+ *
+ * Respects safe-area insets provided via `OverlayInsetsProvider`.
+ */
+export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPosition | null {
+  const { height: viewportHeight } = useWindowDimensions();
+  const { top: insetTop, bottom: insetBottom } = useContext(OverlayInsetsContext);
+
+  return useMemo(() => {
+    if (!anchorLayout) return null;
+
+    const anchorBottom = anchorLayout.y + anchorLayout.height;
+    const spaceBelow = viewportHeight - anchorBottom - insetBottom - SCREEN_EDGE_PADDING;
+    const spaceAbove = anchorLayout.y - insetTop - SCREEN_EDGE_PADDING;
+
+    const preferBelow = spaceBelow >= MIN_CONTENT_HEIGHT || spaceBelow >= spaceAbove;
+
+    if (preferBelow) {
+      const maxHeight = Math.max(0, spaceBelow);
+      return {
+        style: {
+          top: anchorBottom,
+          left: anchorLayout.x,
+          width: anchorLayout.width,
+          maxHeight,
+        },
+        maxHeight,
+        placement: 'bottom' as const,
+      };
+    }
+
+    const maxHeight = Math.max(0, spaceAbove);
+    return {
+      style: {
+        bottom: viewportHeight - anchorLayout.y,
+        left: anchorLayout.x,
+        width: anchorLayout.width,
+        maxHeight,
+      },
+      maxHeight,
+      placement: 'top' as const,
+    };
+  }, [anchorLayout, viewportHeight, insetTop, insetBottom]);
+}

package/src/select/context.tsx

@@ -0,0 +1,56 @@
+import { createContext, useContext } from 'react';
+import type { InteractionState, SelectContextValue, SelectItemInteractionState } from './types';
+
+const defaultContextValue: SelectContextValue = {
+  open: false,
+  items: [],
+  setOpen: () => {},
+  value: undefined,
+  onValueChange: () => {},
+  disabled: false,
+  required: false,
+  invalid: false,
+  readOnly: false,
+  native: false,
+  triggerRef: { current: null },
+  contentId: '',
+  triggerId: '',
+  activeValue: undefined,
+  setActiveValue: () => {}, // TODO: Is this needed? At the very least it could be moved to SelectContent
+  accessibilityLabel: undefined,
+};
+
+export const SelectContext = createContext<SelectContextValue>(defaultContextValue);
+
+export const useSelectContext = () => useContext(SelectContext);
+
+/**
+ * Propagates the trigger's interaction state (hover, focus, active, etc.) to
+ * child components like SelectValue and SelectIcon so they can apply matching
+ * data-attribute styles.
+ */
+export const SelectTriggerContext = createContext<InteractionState>({
+  hover: false,
+  focus: false,
+  active: false,
+  disabled: false,
+  focusVisible: false,
+});
+
+export const useSelectTriggerContext = () => useContext(SelectTriggerContext);
+
+/**
+ * Propagates the item's interaction and selection state (hover, focus, active,
+ * highlighted, checked, etc.) to child components like SelectItemLabel.
+ */
+export const SelectItemContext = createContext<SelectItemInteractionState>({
+  hover: false,
+  focus: false,
+  active: false,
+  disabled: false,
+  focusVisible: false,
+  highlighted: false,
+  checked: false,
+});
+
+export const useSelectItemContext = () => useContext(SelectItemContext);

package/src/select/createSelectContent.tsx

@@ -0,0 +1,115 @@
+import type React from 'react';
+import { forwardRef, useCallback, useRef } from 'react';
+import { Platform, ScrollView } from 'react-native';
+import { FadeIn, FadeOut } from 'react-native-reanimated';
+import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
+import {
+  OverlayContainer,
+  useAnchorPosition,
+  useDismissOverlay,
+  useOverlayPosition,
+} from '../overlay';
+import { dataAttributes } from '../utils/dataAttributes';
+import { useSelectContext } from './context';
+import type { ISelectContentProps } from './types';
+import { useContentFocus } from './useContentFocus';
+import { useListboxNavigation } from './useListboxNavigation';
+
+export const createSelectContent = <T,>(BaseContent: React.ComponentType<T>) =>
+  forwardRef(
+    (
+      { children, enteringAnimation, exitingAnimation, ...props }: ISelectContentProps,
+      ref?: any,
+    ) => {
+      const {
+        open,
+        setOpen,
+        contentId,
+        triggerId,
+        activeValue,
+        setActiveValue,
+        value,
+        onValueChange,
+        native,
+        triggerRef,
+        items,
+      } = useSelectContext();
+
+      const contentRef = useRef<HTMLElement | null>(null);
+
+      const focusOnMount = useCallback((node: HTMLElement) => {
+        contentRef.current = node;
+        if (node && Platform.OS === 'web') {
+          requestAnimationFrame(() => {
+            setTimeout(() => {
+              node.focus?.();
+            }, 100);
+          });
+        }
+      }, []);
+
+      const mergedRef = mergeRefs(ref, focusOnMount);
+
+      const dismiss = () => setOpen(false);
+
+      const anchorLayout = useAnchorPosition(triggerRef, open);
+      const position = useOverlayPosition(anchorLayout);
+
+      useDismissOverlay(open, contentRef, [triggerRef], dismiss);
+
+      const { handleKeyDown } = useListboxNavigation({
+        items,
+        activeValue,
+        setActiveValue,
+        onSelect: (val) => {
+          onValueChange(val);
+          setOpen(false);
+        },
+        onDismiss: dismiss,
+      });
+
+      useContentFocus({
+        open,
+        triggerRef,
+        items,
+        value,
+        setActiveValue,
+      });
+
+      if (native || !open || !position) {
+        return null;
+      }
+
+      const webProps =
+        Platform.OS === 'web'
+          ? {
+              onKeyDown: composeEventHandlers((props as any).onKeyDown, handleKeyDown),
+              tabIndex: -1,
+            }
+          : {};
+
+      return (
+        <OverlayContainer
+          onDismiss={dismiss}
+          entering={enteringAnimation ?? FadeIn.duration(150)}
+          exiting={exitingAnimation ?? FadeOut.duration(100)}
+          style={position.style}
+        >
+          <BaseContent
+            ref={mergedRef}
+            role="listbox"
+            id={contentId}
+            aria-labelledby={triggerId}
+            {...dataAttributes({
+              state: 'open',
+              slot: 'select-content',
+            })}
+            {...(props as T)}
+            {...webProps}
+          >
+            <ScrollView scrollEventThrottle={16}>{children}</ScrollView>
+          </BaseContent>
+        </OverlayContainer>
+      );
+    },
+  );

package/src/select/createSelectIcon.tsx

@@ -0,0 +1,27 @@
+import { forwardRef } from 'react';
+import { dataAttributes } from '../utils/dataAttributes';
+import { useSelectContext, useSelectTriggerContext } from './context';
+
+export const createSelectIcon = <T,>(BaseIcon: React.ComponentType<T>) =>
+  forwardRef((props: any, ref?: any) => {
+    const { hover, focus, active, disabled, focusVisible } = useSelectTriggerContext();
+    const { required, invalid, readOnly } = useSelectContext();
+
+    return (
+      <BaseIcon
+        ref={ref}
+        {...dataAttributes({
+          hover,
+          focus,
+          active,
+          disabled,
+          focusVisible,
+          required,
+          invalid,
+          readonly: readOnly,
+          slot: 'select-icon',
+        })}
+        {...(props as T)}
+      />
+    );
+  });

package/src/select/createSelectItem.tsx

@@ -0,0 +1,121 @@
+import type React from 'react';
+import { forwardRef, useCallback, useMemo } from 'react';
+import { composeEventHandlers } from '@cdx-ui/utils';
+import { useFocus, useFocusRing } from '@react-native-aria/focus';
+import { useHover, usePress } from '@react-native-aria/interactions';
+import { dataAttributes } from '../utils/dataAttributes';
+import { SelectItemContext, useSelectContext } from './context';
+import type { ISelectItemProps } from './types';
+
+export const createSelectItem = <T,>(BaseItem: React.ComponentType<T>) =>
+  forwardRef(
+    (
+      {
+        children,
+        value: itemValue,
+        disabled: disabledProp = false,
+        isHovered: isHoveredProp,
+        isActive: isActiveProp,
+        isFocused: isFocusedProp,
+        isFocusVisible: isFocusVisibleProp,
+        isDisabled: isDisabledProp,
+        ...props
+      }: Omit<ISelectItemProps, 'children'> & { children?: React.ReactNode },
+      ref?: any,
+    ) => {
+      const {
+        value: selectedValue,
+        onValueChange,
+        setOpen,
+        activeValue,
+        contentId,
+        disabled: contextDisabled,
+      } = useSelectContext();
+
+      const disabled = contextDisabled || !!disabledProp || !!isDisabledProp;
+      const checked = selectedValue === itemValue;
+      const highlighted = activeValue === itemValue;
+
+      const { isFocusVisible, focusProps: focusRingProps }: any = useFocusRing();
+      const { pressProps, isPressed: isActive } = usePress({ isDisabled: disabled });
+      const { isFocused, focusProps } = useFocus();
+      const { isHovered, hoverProps }: any = useHover();
+
+      const handlePress = useCallback(() => {
+        if (!disabled) {
+          onValueChange(itemValue);
+          setOpen(false);
+        }
+      }, [disabled, itemValue, onValueChange, setOpen]);
+
+      const interactionState = useMemo(
+        () => ({
+          hover: isHoveredProp || isHovered,
+          focus: isFocusedProp || isFocused,
+          active: isActiveProp || isActive,
+          disabled: !!disabled,
+          focusVisible: isFocusVisibleProp || isFocusVisible,
+          highlighted,
+          checked,
+        }),
+        [
+          isHoveredProp,
+          isHovered,
+          isFocusedProp,
+          isFocused,
+          isActiveProp,
+          isActive,
+          disabled,
+          isFocusVisibleProp,
+          isFocusVisible,
+          highlighted,
+          checked,
+        ],
+      );
+
+      return (
+        <SelectItemContext.Provider value={interactionState}>
+          <BaseItem
+            ref={ref}
+            role="option"
+            id={`${contentId}-option-${itemValue}`}
+            aria-selected={checked}
+            aria-disabled={disabled}
+            {...dataAttributes({
+              hover: interactionState.hover,
+              focus: interactionState.focus,
+              active: interactionState.active,
+              disabled: interactionState.disabled,
+              focusVisible: interactionState.focusVisible,
+              highlighted: interactionState.highlighted,
+              state: checked ? 'checked' : 'unchecked',
+              slot: 'select-item',
+            })}
+            disabled={disabled}
+            {...(props as T)}
+            onPress={composeEventHandlers(props?.onPress, handlePress)}
+            onPressIn={composeEventHandlers(props?.onPressIn, pressProps.onPressIn)}
+            onPressOut={composeEventHandlers(props?.onPressOut, pressProps.onPressOut)}
+            onHoverIn={composeEventHandlers(props?.onHoverIn, hoverProps.onHoverIn)}
+            onHoverOut={composeEventHandlers(props?.onHoverOut, hoverProps.onHoverOut)}
+            onFocus={composeEventHandlers(
+              composeEventHandlers(
+                props?.onFocus as (...args: unknown[]) => unknown,
+                focusProps.onFocus,
+              ),
+              focusRingProps.onFocus,
+            )}
+            onBlur={composeEventHandlers(
+              composeEventHandlers(
+                props?.onBlur as (...args: unknown[]) => unknown,
+                focusProps.onBlur,
+              ),
+              focusRingProps.onBlur,
+            )}
+          >
+            {children}
+          </BaseItem>
+        </SelectItemContext.Provider>
+      );
+    },
+  );

package/src/select/createSelectItemLabel.tsx

@@ -0,0 +1,30 @@
+import type React from 'react';
+import { forwardRef } from 'react';
+import { dataAttributes } from '../utils/dataAttributes';
+import { useSelectItemContext } from './context';
+import type { ISelectItemLabelProps } from './types';
+
+export const createSelectItemLabel = <T,>(BaseItemLabel: React.ComponentType<T>) =>
+  forwardRef(({ children, ...props }: ISelectItemLabelProps, ref?: any) => {
+    const { hover, focus, active, disabled, focusVisible, highlighted, checked } =
+      useSelectItemContext();
+
+    return (
+      <BaseItemLabel
+        ref={ref}
+        {...(props as T)}
+        {...dataAttributes({
+          hover,
+          focus,
+          active,
+          disabled,
+          focusVisible,
+          highlighted,
+          state: checked ? 'checked' : 'unchecked',
+          slot: 'select-item-label',
+        })}
+      >
+        {children}
+      </BaseItemLabel>
+    );
+  });