@cdx-ui/primitives 0.1.5 → 0.1.7

package/src/portal/portal.tsx

@@ -130,7 +130,21 @@ export function PortalProvider({ children }: Readonly<{ children: React.ReactNod
 
 // --------------------------------------------------
 
-export function PortalHost({ name = DEFAULT_PORTAL_HOST }: { name?: string }) {
+export interface PortalHostProps {
+  /** Host name that `Portal` targets through `hostName`. @default the shared default host */
+  name?: string;
+  /**
+   * Web only. Element that receives the portal content instead of `document.body`.
+   *
+   * Use it to keep overlays inside an embedded surface, such as a device preview. Fixed
+   * overlays stay inside the container only when an ancestor of it creates a containing
+   * block for fixed descendants, for example through a `transform`. While `null`, such as
+   * before a callback ref attaches, the host renders nothing. Ignored on native.
+   */
+  container?: Element | null;
+}
+
+export function PortalHost({ name = DEFAULT_PORTAL_HOST, container }: PortalHostProps) {
   const registry = React.useContext(PortalRegistryContext) ?? fallbackPortalRegistry;
   const hostId = React.useRef(Symbol()).current;
 
@@ -167,7 +181,8 @@ export function PortalHost({ name = DEFAULT_PORTAL_HOST }: { name?: string }) {
   );
 
   if (Platform.OS === 'web' && createPortalFn && typeof document !== 'undefined') {
-    return createPortalFn(content, document.body);
+    if (container === null) return null;
+    return createPortalFn(content, container ?? document.body);
   }
 
   return content;

package/src/progress-bar/types.ts

@@ -5,17 +5,22 @@ export type ProgressDataState = 'complete' | 'indeterminate' | 'loading';
 
 export interface InterfaceProgressProps extends Omit<ViewProps, 'children'> {
   /**
-   * Current value in the range [0, max], or `null` for indeterminate progress.
-   * Omit or use a number for determinate progress; default is `0`.
+   * Current value in the range `[0, max]`, or `null` for indeterminate progress.
+   * Values below `0` clamp to `0`; values above `max` clamp to `max`.
+   * Non-finite values (such as `NaN`) are treated as `0`.
+   * @default 0
    */
   readonly value?: number | null;
   /**
-   * Maximum value (minimum is always 0).
+   * Maximum value. The minimum is always `0`.
+   * A `max` of `0` or less is treated as complete.
    * @default 100
    */
   readonly max?: number;
   /**
-   * Optional label for `accessibilityValue.text` when determinate.
+   * Screen-reader text for determinate progress (`accessibilityValue.text`).
+   * Defaults to a rounded percentage of `max`, such as `"45%"`.
+   * No effect when `value` is `null`, or when `accessibilityValue` is set.
    */
   readonly getValueLabel?: (value: number, max: number) => string;
   readonly children?: ReactNode;

package/src/radio/types.ts

@@ -3,8 +3,10 @@ import type { PressableProps } from 'react-native';
 export interface IRadioProps extends PressableProps {
   /** Required — identifies this item's value within a Radio.Group. */
   value: string;
+  /** Disables this item without disabling the rest of the group. */
   isDisabled?: boolean;
   isInvalid?: boolean;
+  /** Focusable, but the selection cannot be changed. */
   isReadOnly?: boolean;
   isHovered?: boolean;
   isFocused?: boolean;

package/src/select/SelectContent.tsx

@@ -2,7 +2,7 @@ import React, { forwardRef, useCallback, useRef, type ComponentRef } from 'react
 import { Platform, View } from 'react-native';
 import { FadeIn, FadeOut } from 'react-native-reanimated';
 import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
-import { OverlayContainer, useAnchoredOverlay, useDismissOverlay } from '../overlay';
+import { OverlayContainer, useAnchoredOverlay, useDismissOverlay, useEscapeKey } from '../overlay';
 import { Slot } from '../slot';
 import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
 import { useSelectContext } from './context';
@@ -76,6 +76,7 @@ export const SelectContent = forwardRef<ComponentRef<typeof View>, SelectContent
     const mergedRef = mergeRefs(ref, focusOnMount as unknown as React.Ref<View>, floatingRef);
 
     useDismissOverlay(overlayOpen, contentRef, [triggerRef], dismiss);
+    useEscapeKey(overlayOpen, dismiss);
 
     const { handleKeyDown } = useListboxNavigation({
       items,

package/src/switch/types.ts

@@ -7,11 +7,11 @@ export interface IInterfaceSwitchProps {
    */
   onValueChange?: (value: boolean) => void;
   /**
-   * If true, set the Switch to the checked state.
+   * Alias for `value`. `value` takes precedence when both are set.
    */
   isChecked?: boolean;
   /**
-   * The current value of the switch.
+   * Controlled on/off state. Takes precedence over `isChecked`.
    */
   value?: boolean;
   /**
@@ -19,11 +19,11 @@ export interface IInterfaceSwitchProps {
    */
   isDisabled?: boolean;
   /**
-   * If true, the switch will be disabled.
+   * Alias for `isDisabled`. Either prop disables the switch.
    */
   disabled?: boolean;
   /**
-   * If true, the switch will be initially checked.
+   * Initial state when uncontrolled. No effect when `value` or `isChecked` is set.
    */
   defaultValue?: boolean;
   /**

package/src/tabs/types.ts

@@ -13,7 +13,8 @@ export interface ITabsProps {
   onValueChange?: (value: string) => void;
   /**
    * `automatic` (default) selects a tab as soon as it receives focus via arrow keys.
-   * `manual` only moves focus on arrow keys — the consumer must press Enter/Space to select.
+   * `manual` only moves focus — press Enter or Space to select. Web only; native
+   * selection follows press. Use `manual` when rendering the next panel is expensive.
    */
   activationMode?: TabsActivationMode;
   /**
@@ -21,6 +22,7 @@ export interface ITabsProps {
    * `vertical` uses ArrowUp/ArrowDown, per the ARIA APG tabs pattern.
    */
   orientation?: TabsOrientation;
+  /** Disables every tab. Disable a single tab with `disabled` on that `Tabs.Tab`. */
   disabled?: boolean;
   children?: ReactNode;
 }
@@ -63,7 +65,10 @@ export interface ITabProps extends PressableProps {
 export interface ITabPanelProps extends ViewProps {
   /** Required — correlates this panel with its `Tabs.Tab` counterpart. */
   value: string;
-  /** Unmount when inactive instead of keeping the panel hidden in the DOM. */
+  /**
+   * Unmount when inactive instead of keeping the panel mounted and hidden.
+   * The default keeps it mounted so the tab's `aria-controls` target stays in the tree.
+   */
   unmountWhenInactive?: boolean;
   children?: ReactNode;
 }

package/src/toggle-button/ToggleButtonGroup.tsx

@@ -0,0 +1,260 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentRef,
+} from 'react';
+import { Platform, View, type ViewProps } from 'react-native';
+import { composeEventHandlers, useControllableState } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { ToggleButtonGroupContextProvider } from './context';
+import type {
+  IToggleButtonGroupProps,
+  RegisteredToggleButton,
+  ToggleButtonGroupType,
+} from './types';
+import { useToggleButtonGroupNavigation } from './useToggleButtonGroupNavigation';
+
+type WidenedToggleButtonGroupProps = ViewProps & {
+  asChild?: boolean;
+  type?: ToggleButtonGroupType;
+  value?: string | string[];
+  defaultValue?: string | string[];
+  onValueChange?: (value: string | string[]) => void;
+  isDisabled?: boolean;
+  orientation?: 'horizontal' | 'vertical';
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+};
+
+export type ToggleButtonGroupProps = IToggleButtonGroupProps;
+
+// Map insertion order drifts when an item re-registers (e.g. its disabled state changes)
+// or mounts conditionally, so navigation order is derived from document position instead.
+function getItemsInRenderedOrder(
+  items: Map<string, RegisteredToggleButton>,
+): [string, RegisteredToggleButton][] {
+  const entries = Array.from(items.entries());
+  if (Platform.OS !== 'web' || typeof Node === 'undefined') {
+    return entries;
+  }
+
+  return entries.sort(([, first], [, second]) => {
+    const firstNode = first.node as Node | null;
+    const secondNode = second.node as Node | null;
+    if (!firstNode?.compareDocumentPosition || !secondNode) {
+      return 0;
+    }
+
+    const position = firstNode.compareDocumentPosition(secondNode);
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING) {
+      return -1;
+    }
+    if (position & Node.DOCUMENT_POSITION_PRECEDING) {
+      return 1;
+    }
+    return 0;
+  });
+}
+
+function getAnchorValue(
+  type: ToggleButtonGroupType,
+  state: string | string[] | undefined,
+): string | undefined {
+  if (type === 'single') {
+    return typeof state === 'string' ? state : undefined;
+  }
+  if (Array.isArray(state) && state.length > 0) {
+    return state[0];
+  }
+  return undefined;
+}
+
+export const ToggleButtonGroup = forwardRef<ComponentRef<typeof View>, ToggleButtonGroupProps>(
+  (props, ref) => {
+    const {
+      asChild = false,
+      children,
+      className,
+      style,
+      type: typeProp = 'single',
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      isDisabled = false,
+      orientation = 'horizontal',
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      ...rest
+    } = props as WidenedToggleButtonGroupProps & {
+      className?: string;
+      style?: ViewProps['style'];
+    };
+
+    const type: ToggleButtonGroupType = typeProp;
+
+    const defaultProp =
+      defaultValue !== undefined ? defaultValue : type === 'multiple' ? [] : undefined;
+
+    const [state, setState] = useControllableState<string | string[] | undefined>({
+      prop: valueProp,
+      defaultProp,
+      onChange: (next) => {
+        if (next !== undefined) {
+          onValueChange?.(next);
+        }
+      },
+    });
+
+    const [focusedValue, setFocusedValue] = useState<string | undefined>(undefined);
+    const [registrationEpoch, setRegistrationEpoch] = useState(0);
+    const itemsRef = useRef<Map<string, RegisteredToggleButton>>(new Map());
+
+    // Single-select: if the parent changes `value`, drop a stale roving tab stop so
+    // arrow keys follow the selected item. Multiple-select keeps focus on the last
+    // pressed/focused item even when it is no longer selected.
+    useEffect(() => {
+      if (type !== 'single') {
+        return;
+      }
+      const selectedId = typeof state === 'string' ? state : undefined;
+      setFocusedValue((prev) => (prev !== undefined && prev !== selectedId ? undefined : prev));
+    }, [type, state]);
+
+    const getItems = useCallback(
+      () => getItemsInRenderedOrder(itemsRef.current),
+      [registrationEpoch],
+    );
+
+    const registerItem = useCallback((itemValue: string, entry: RegisteredToggleButton) => {
+      itemsRef.current.set(itemValue, entry);
+      setRegistrationEpoch((epoch) => epoch + 1);
+    }, []);
+
+    const unregisterItem = useCallback((itemValue: string) => {
+      itemsRef.current.delete(itemValue);
+      setRegistrationEpoch((epoch) => epoch + 1);
+    }, []);
+
+    const isSelected = useCallback(
+      (buttonValue: string) => {
+        if (type === 'single') {
+          return state === buttonValue;
+        }
+        return Array.isArray(state) && state.includes(buttonValue);
+      },
+      [type, state],
+    );
+
+    const toggleValue = useCallback(
+      (buttonValue: string) => {
+        if (isDisabled) {
+          return;
+        }
+        if (type === 'single') {
+          if (state === buttonValue) {
+            return;
+          }
+          setState(buttonValue);
+          return;
+        }
+        const arr = Array.isArray(state) ? [...state] : [];
+        const idx = arr.indexOf(buttonValue);
+        if (idx >= 0) {
+          arr.splice(idx, 1);
+          setState(arr);
+        } else {
+          arr.push(buttonValue);
+          setState(arr);
+        }
+      },
+      [isDisabled, type, state, setState],
+    );
+
+    const anchorValue = getAnchorValue(type, state);
+
+    const { handleKeyDown } = useToggleButtonGroupNavigation({
+      type,
+      orientation,
+      getItems,
+      focusedValue,
+      setFocusedValue,
+      anchorValue,
+      selectOnFocus: type === 'single' ? toggleValue : undefined,
+    });
+
+    const webProps =
+      Platform.OS === 'web'
+        ? {
+            onKeyDown: composeEventHandlers(
+              (rest as { onKeyDown?: (e: KeyboardEvent) => void }).onKeyDown,
+              handleKeyDown,
+            ),
+          }
+        : {};
+
+    const contextValue = useMemo(
+      () => ({
+        type,
+        orientation,
+        value: state,
+        toggleValue,
+        isSelected,
+        isGroupDisabled: isDisabled,
+        focusedValue,
+        setFocusedValue,
+        registerItem,
+        unregisterItem,
+        getItems,
+      }),
+      [
+        type,
+        orientation,
+        state,
+        toggleValue,
+        isSelected,
+        isDisabled,
+        focusedValue,
+        registerItem,
+        unregisterItem,
+        getItems,
+      ],
+    );
+
+    // `AccessibilityRole` has no `group` member, so multiple-select relies on the `role` prop,
+    // which RN resolves natively and ranks above `accessibilityRole`.
+    const role = rest.role ?? (type === 'single' ? 'radiogroup' : 'group');
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <ToggleButtonGroupContextProvider value={contextValue}>
+        <Comp
+          ref={ref}
+          {...rest}
+          role={role}
+          {...(type === 'single' ? { accessibilityRole: 'radiogroup' as const } : {})}
+          {...(ariaLabel ? { 'aria-label': ariaLabel, accessibilityLabel: ariaLabel } : {})}
+          {...(ariaLabelledBy ? { 'aria-labelledby': ariaLabelledBy } : {})}
+          className={className}
+          style={style}
+          {...mergeDataAttributes(
+            rest,
+            dataAttributes({
+              orientation,
+              disabled: isDisabled,
+            }),
+          )}
+          {...webProps}
+        >
+          {children}
+        </Comp>
+      </ToggleButtonGroupContextProvider>
+    );
+  },
+);
+
+ToggleButtonGroup.displayName = 'ToggleButtonGroup';

package/src/toggle-button/ToggleButtonRoot.tsx

@@ -0,0 +1,151 @@
+import { forwardRef, useMemo, type ComponentRef } from 'react';
+import { Pressable, type PressableProps } from 'react-native';
+import { composeEventHandlers, useControllableState } from '@cdx-ui/utils';
+import { useFocus, useFocusRing } from '@react-native-aria/focus';
+import { useHover, usePress } from '@react-native-aria/interactions';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { ToggleButtonProvider, useOptionalToggleButtonGroupContext } from './context';
+import { getToggleState } from './toggleState';
+import type { IToggleButtonProps } from './types';
+
+export interface ToggleButtonRootProps extends IToggleButtonProps {}
+
+export const ToggleButtonRoot = forwardRef<ComponentRef<typeof Pressable>, ToggleButtonRootProps>(
+  (
+    {
+      asChild = false,
+      value,
+      isSelected: controlledSelected,
+      defaultSelected,
+      onSelectedChange,
+      isDisabled: isDisabledProp = false,
+      children,
+      onPress,
+      onFocus,
+      onBlur,
+      style,
+      ...rest
+    },
+    ref,
+  ) => {
+    const group = useOptionalToggleButtonGroupContext();
+
+    const [standaloneSelected = false, setStandaloneSelected] = useControllableState<boolean>({
+      prop: controlledSelected,
+      defaultProp: defaultSelected ?? false,
+      onChange: (next) => {
+        onSelectedChange?.(next);
+      },
+    });
+
+    const isSelected = group ? group.isSelected(value) : standaloneSelected;
+    const isDisabled = (group?.isGroupDisabled ?? false) || isDisabledProp;
+
+    const { focusProps, isFocused } = useFocus();
+    const { isFocusVisible, focusProps: focusRingProps } = useFocusRing() as {
+      isFocusVisible: boolean;
+      focusProps: typeof focusProps;
+    };
+    const { pressProps, isPressed } = usePress({ isDisabled });
+    const { hoverProps, isHovered } = useHover();
+
+    const selectionType: 'single' | 'multiple' | 'standalone' = group ? group.type : 'standalone';
+
+    const role = selectionType === 'single' ? ('radio' as const) : ('button' as const);
+
+    const accessibilityState = useMemo(
+      () => ({
+        disabled: isDisabled,
+        ...(selectionType === 'single'
+          ? { checked: isSelected, selected: isSelected }
+          : { selected: isSelected }),
+      }),
+      [isDisabled, isSelected, selectionType],
+    );
+
+    const ariaProps =
+      selectionType === 'single' ? { 'aria-checked': isSelected } : { 'aria-pressed': isSelected };
+
+    const toggleButtonContext = useMemo(
+      () => ({
+        value,
+        isSelected,
+        isDisabled,
+        selectionType,
+        hover: isHovered,
+        active: isPressed,
+        focus: isFocused,
+        focusVisible: isFocusVisible,
+      }),
+      [
+        value,
+        isSelected,
+        isDisabled,
+        selectionType,
+        isHovered,
+        isPressed,
+        isFocused,
+        isFocusVisible,
+      ],
+    );
+
+    const composedOnPress = composeEventHandlers(onPress, () => {
+      if (isDisabled) {
+        return;
+      }
+      if (group) {
+        group.toggleValue(value);
+      } else {
+        setStandaloneSelected(!standaloneSelected);
+      }
+    });
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <ToggleButtonProvider value={toggleButtonContext}>
+        <Comp
+          ref={ref}
+          accessibilityRole={role}
+          role={role}
+          accessibilityState={accessibilityState}
+          {...ariaProps}
+          {...(isDisabled ? { 'aria-disabled': true as const } : {})}
+          disabled={isDisabled}
+          {...(rest as PressableProps)}
+          {...mergeDataAttributes(
+            rest,
+            dataAttributes({
+              selected: isSelected,
+              disabled: isDisabled,
+              active: isPressed,
+              hover: isHovered,
+              focus: isFocused,
+              focusVisible: isFocusVisible,
+              toggleState: getToggleState(isSelected, isPressed, isHovered),
+            }),
+          )}
+          style={style}
+          onPress={isDisabled ? undefined : composedOnPress}
+          onPressIn={composeEventHandlers(rest.onPressIn, pressProps.onPressIn)}
+          onPressOut={composeEventHandlers(rest.onPressOut, pressProps.onPressOut)}
+          onHoverIn={composeEventHandlers(rest.onHoverIn, hoverProps.onHoverIn)}
+          onHoverOut={composeEventHandlers(rest.onHoverOut, hoverProps.onHoverOut)}
+          onFocus={composeEventHandlers(
+            composeEventHandlers(onFocus, focusProps.onFocus),
+            focusRingProps.onFocus,
+          )}
+          onBlur={composeEventHandlers(
+            composeEventHandlers(onBlur, focusProps.onBlur),
+            focusRingProps.onBlur,
+          )}
+        >
+          {children}
+        </Comp>
+      </ToggleButtonProvider>
+    );
+  },
+);
+
+ToggleButtonRoot.displayName = 'ToggleButtonRoot';