@cdx-ui/primitives 0.0.1-beta.121 → 0.0.1-beta.123

package/lib/typescript/tabs/useTabsNavigation.d.ts

@@ -0,0 +1,14 @@
+import type { RegisteredTab, TabsActivationMode, TabsOrientation } from './types';
+export interface UseTabsNavigationOptions {
+    getTabs: () => [string, RegisteredTab][];
+    focusedValue: string | undefined;
+    setFocusedValue: (value: string | undefined) => void;
+    value: string | undefined;
+    onValueChange: (value: string) => void;
+    activationMode: TabsActivationMode;
+    orientation: TabsOrientation;
+}
+export declare function useTabsNavigation({ getTabs, focusedValue, setFocusedValue, value, onValueChange, activationMode, orientation, }: UseTabsNavigationOptions): {
+    handleKeyDown: (e: any) => void;
+};
+//# sourceMappingURL=useTabsNavigation.d.ts.map

package/lib/typescript/tabs/useTabsNavigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTabsNavigation.d.ts","sourceRoot":"","sources":["../../../src/tabs/useTabsNavigation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAKlF,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,CAAC;IACzC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACrD,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,cAAc,EAAE,kBAAkB,CAAC;IACnC,WAAW,EAAE,eAAe,CAAC;CAC9B;AAED,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,YAAY,EACZ,eAAe,EACf,KAAK,EACL,aAAa,EACb,cAAc,EACd,WAAW,GACZ,EAAE,wBAAwB;uBAqBnB,GAAG;EAmDV"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdx-ui/primitives",
-  "version": "0.0.1-beta.121",
+  "version": "0.0.1-beta.123",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "react-native": "src/index.ts",
@@ -60,7 +60,7 @@
     "@react-stately/checkbox": "3.7.4",
     "@react-stately/radio": "3.12.0",
     "@react-stately/toggle": "3.9.4",
-    "@cdx-ui/utils": "0.0.1-beta.121"
+    "@cdx-ui/utils": "0.0.1-beta.123"
   },
   "devDependencies": {
     "@types/react": "19.1.17",

package/src/index.ts

@@ -14,6 +14,7 @@ export { type EdgeInsets, OverlayInsetsProvider } from './overlay';
 export { useAnchorPosition, type AnchorLayout } from './overlay';
 export * from './select';
 export * from './switch';
+export * from './tabs';
 export * from './tile';
 export * from './toast';
 export * from './portal';

package/src/tabs/Tab.tsx

@@ -0,0 +1,158 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type ComponentRef,
+  type ReactNode,
+} from 'react';
+import { Platform, Pressable } from 'react-native';
+import { composeEventHandlers, mergeRefs } 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 { TabProvider, useTabsContext } from './context';
+import type { ITabProps } from './types';
+
+export interface TabProps extends Omit<ITabProps, 'children'> {
+  asChild?: boolean;
+  children?: ReactNode;
+}
+
+export const Tab = forwardRef<ComponentRef<typeof Pressable>, TabProps>(
+  (
+    {
+      asChild,
+      children,
+      value: tabValue,
+      disabled: disabledProp = false,
+      isHovered: isHoveredProp,
+      isActive: isActiveProp,
+      isFocused: isFocusedProp,
+      isFocusVisible: isFocusVisibleProp,
+      isDisabled: isDisabledProp,
+      ...props
+    },
+    ref,
+  ) => {
+    const {
+      value: selectedValue,
+      onValueChange,
+      disabled: contextDisabled,
+      listId,
+      registerTab,
+      unregisterTab,
+      focusedValue,
+      setFocusedValue,
+    } = useTabsContext();
+
+    const disabled = contextDisabled || !!disabledProp || !!isDisabledProp;
+    const selected = selectedValue === tabValue;
+
+    const nodeRef = useRef<ComponentRef<typeof Pressable> | null>(null);
+    const mergedRef = mergeRefs(ref, nodeRef);
+
+    useEffect(() => {
+      registerTab(tabValue, {
+        disabled,
+        node: nodeRef.current as { focus?: () => void } | null,
+      });
+      return () => unregisterTab(tabValue);
+    }, [tabValue, disabled, registerTab, unregisterTab]);
+
+    const { isFocusVisible, focusProps: focusRingProps } = useFocusRing() as {
+      isFocusVisible: boolean;
+      focusProps: {
+        onFocus?: (...args: unknown[]) => unknown;
+        onBlur?: (...args: unknown[]) => unknown;
+      };
+    };
+    const { pressProps, isPressed: isActive } = usePress({ isDisabled: disabled });
+    const { isFocused, focusProps } = useFocus();
+    const { isHovered, hoverProps } = useHover();
+
+    const handlePress = useCallback(() => {
+      if (!disabled) {
+        setFocusedValue(tabValue);
+        onValueChange(tabValue);
+      }
+    }, [disabled, tabValue, onValueChange, setFocusedValue]);
+
+    const interactionState = useMemo(
+      () => ({
+        hover: !!(isHoveredProp || isHovered),
+        focus: !!(isFocusedProp || isFocused),
+        active: !!(isActiveProp || isActive),
+        disabled: !!disabled,
+        focusVisible: !!(isFocusVisibleProp || isFocusVisible),
+        selected,
+      }),
+      [
+        isHoveredProp,
+        isHovered,
+        isFocusedProp,
+        isFocused,
+        isActiveProp,
+        isActive,
+        disabled,
+        isFocusVisibleProp,
+        isFocusVisible,
+        selected,
+      ],
+    );
+
+    const isRovingTabStop = (focusedValue ?? selectedValue) === tabValue;
+    const webProps = Platform.OS === 'web' ? { tabIndex: isRovingTabStop ? 0 : -1 } : {};
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <TabProvider value={interactionState}>
+        <Comp
+          ref={mergedRef}
+          role="tab"
+          id={`${listId}-tab-${tabValue}`}
+          aria-selected={selected}
+          aria-controls={`${listId}-panel-${tabValue}`}
+          aria-disabled={disabled}
+          disabled={disabled}
+          accessibilityState={{ selected, disabled }}
+          {...webProps}
+          {...props}
+          {...mergeDataAttributes(
+            props,
+            dataAttributes({
+              hover: interactionState.hover,
+              focus: interactionState.focus,
+              active: interactionState.active,
+              disabled: interactionState.disabled,
+              focusVisible: interactionState.focusVisible,
+              state: selected ? 'active' : 'inactive',
+            }),
+          )}
+          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(
+            props?.onFocus as (...args: unknown[]) => unknown,
+            focusProps.onFocus,
+            focusRingProps.onFocus,
+          )}
+          onBlur={composeEventHandlers(
+            props?.onBlur as (...args: unknown[]) => unknown,
+            focusProps.onBlur,
+            focusRingProps.onBlur,
+          )}
+        >
+          {children}
+        </Comp>
+      </TabProvider>
+    );
+  },
+);
+
+Tab.displayName = 'Tab';

package/src/tabs/TabPanel.tsx

@@ -0,0 +1,52 @@
+import { forwardRef, type ComponentRef, type ReactNode } from 'react';
+import { View } from 'react-native';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useTabsContext } from './context';
+import type { ITabPanelProps } from './types';
+
+export interface TabPanelProps extends Omit<ITabPanelProps, 'children'> {
+  asChild?: boolean;
+  children?: ReactNode;
+}
+
+export const TabPanel = forwardRef<ComponentRef<typeof View>, TabPanelProps>(
+  ({ asChild, children, value: panelValue, unmountWhenInactive = false, style, ...props }, ref) => {
+    const { value: selectedValue, listId } = useTabsContext();
+    const selected = selectedValue === panelValue;
+
+    if (!selected && unmountWhenInactive) {
+      return null;
+    }
+
+    const Comp = asChild ? Slot : View;
+
+    const hideFromAccessibility = selected
+      ? null
+      : {
+          accessibilityElementsHidden: true as const,
+          importantForAccessibility: 'no-hide-descendants' as const,
+          'aria-hidden': true as const,
+        };
+
+    return (
+      <Comp
+        ref={ref}
+        role="tabpanel"
+        id={`${listId}-panel-${panelValue}`}
+        aria-labelledby={`${listId}-tab-${panelValue}`}
+        style={[!selected ? { display: 'none' } : null, style]}
+        {...props}
+        {...hideFromAccessibility}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({ slot: 'tabs-panel', state: selected ? 'active' : 'inactive' }),
+        )}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+TabPanel.displayName = 'TabPanel';

package/src/tabs/TabsList.tsx

@@ -0,0 +1,64 @@
+import { forwardRef, type ComponentRef } from 'react';
+import { Platform, View } from 'react-native';
+import { composeEventHandlers } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useTabsContext } from './context';
+import type { ITabsListProps } from './types';
+import { useTabsNavigation } from './useTabsNavigation';
+
+export interface TabsListProps extends ITabsListProps {
+  asChild?: boolean;
+  className?: string;
+}
+
+export const TabsList = forwardRef<ComponentRef<typeof View>, TabsListProps>(
+  ({ asChild, children, ...props }, ref) => {
+    const {
+      value,
+      onValueChange,
+      activationMode,
+      orientation,
+      getTabs,
+      focusedValue,
+      setFocusedValue,
+    } = useTabsContext();
+
+    const { handleKeyDown } = useTabsNavigation({
+      getTabs,
+      focusedValue,
+      setFocusedValue,
+      value,
+      onValueChange,
+      activationMode,
+      orientation,
+    });
+
+    const webProps =
+      Platform.OS === 'web'
+        ? {
+            onKeyDown: composeEventHandlers(
+              (props as { onKeyDown?: (e: KeyboardEvent) => void }).onKeyDown,
+              handleKeyDown,
+            ),
+          }
+        : {};
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <Comp
+        ref={ref}
+        role="tablist"
+        aria-orientation={orientation}
+        {...props}
+        {...webProps}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'tabs-list', orientation }))}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+TabsList.displayName = 'TabsList';

package/src/tabs/TabsRoot.tsx

@@ -0,0 +1,115 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentRef,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+import { useControllableState } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { TabsProvider } from './context';
+import type { ITabsProps, RegisteredTab } from './types';
+
+export interface TabsRootProps extends ITabsProps, Omit<ViewProps, 'children'> {
+  asChild?: boolean;
+  className?: string;
+}
+
+export const TabsRoot = forwardRef<ComponentRef<typeof View>, TabsRootProps>(
+  (
+    {
+      asChild,
+      children,
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      activationMode = 'automatic',
+      orientation = 'horizontal',
+      disabled = false,
+      ...props
+    },
+    ref,
+  ) => {
+    const [value, setValue] = useControllableState<string | undefined>({
+      prop: valueProp,
+      defaultProp: defaultValue,
+      onChange: (newValue) => {
+        if (newValue !== undefined) {
+          onValueChange?.(newValue);
+        }
+      },
+    });
+
+    const [focusedValue, setFocusedValue] = useState<string | undefined>(undefined);
+
+    // When the parent updates the controlled selection, drop stale roving-focus state so
+    // tabIndex and arrow-key navigation follow `value` instead of a previously focused tab.
+    useEffect(() => {
+      setFocusedValue((prev) => (prev !== undefined && prev !== value ? undefined : prev));
+    }, [value]);
+
+    const tabsRef = useRef<Map<string, RegisteredTab>>(new Map());
+
+    const registerTab = useCallback((tabValue: string, entry: RegisteredTab) => {
+      tabsRef.current.set(tabValue, entry);
+    }, []);
+
+    const unregisterTab = useCallback((tabValue: string) => {
+      tabsRef.current.delete(tabValue);
+    }, []);
+
+    const getTabs = useCallback(() => Array.from(tabsRef.current.entries()), []);
+
+    const reactId = useId();
+    const listId = `tabs-${reactId}`;
+
+    const contextValue = useMemo(
+      () => ({
+        value,
+        onValueChange: setValue,
+        disabled,
+        activationMode,
+        orientation,
+        listId,
+        registerTab,
+        unregisterTab,
+        getTabs,
+        focusedValue,
+        setFocusedValue,
+      }),
+      [
+        value,
+        setValue,
+        disabled,
+        activationMode,
+        orientation,
+        listId,
+        registerTab,
+        unregisterTab,
+        getTabs,
+        focusedValue,
+      ],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <TabsProvider value={contextValue}>
+        <Comp
+          ref={ref}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ disabled, orientation }))}
+        >
+          {children}
+        </Comp>
+      </TabsProvider>
+    );
+  },
+);
+
+TabsRoot.displayName = 'TabsRoot';

package/src/tabs/context.tsx

@@ -0,0 +1,10 @@
+import { createContext } from '@cdx-ui/utils';
+import type { TabInteractionState, TabsContextValue } from './types';
+
+export const [TabsProvider, useTabsContext] = createContext<TabsContextValue>('TabsContext');
+
+/**
+ * Propagates a tab's interaction and selection state (hover, focus, active, selected, etc.)
+ * to child slots like a styled `Tabs.Tab`'s label/icon.
+ */
+export const [TabProvider, useTabContext] = createContext<TabInteractionState>('TabContext');

package/src/tabs/index.ts

@@ -0,0 +1,17 @@
+export type {
+  ITabPanelProps,
+  ITabProps,
+  ITabsListProps,
+  ITabsProps,
+  RegisteredTab,
+  TabInteractionState,
+  TabsActivationMode,
+  TabsContextValue,
+  TabsOrientation,
+} from './types';
+
+export { useTabContext, useTabsContext } from './context';
+export { TabsRoot, type TabsRootProps } from './TabsRoot';
+export { TabsList, type TabsListProps } from './TabsList';
+export { Tab, type TabProps } from './Tab';
+export { TabPanel, type TabPanelProps } from './TabPanel';

package/src/tabs/types.ts

@@ -0,0 +1,73 @@
+import type { ReactNode } from 'react';
+import type { PressableProps, ViewProps } from 'react-native';
+import type { InteractionState } from '../types';
+
+export type TabsActivationMode = 'automatic' | 'manual';
+export type TabsOrientation = 'horizontal' | 'vertical';
+
+export interface ITabsProps {
+  /** Controlled selected tab value. */
+  value?: string;
+  /** Default selected tab value for uncontrolled usage. */
+  defaultValue?: string;
+  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.
+   */
+  activationMode?: TabsActivationMode;
+  /**
+   * Layout axis and roving-focus key set. `horizontal` (default) uses ArrowLeft/ArrowRight;
+   * `vertical` uses ArrowUp/ArrowDown, per the ARIA APG tabs pattern.
+   */
+  orientation?: TabsOrientation;
+  disabled?: boolean;
+  children?: ReactNode;
+}
+
+export interface ITabsListProps extends ViewProps {
+  children?: ReactNode;
+}
+
+export interface ITabProps extends PressableProps {
+  /** Required — correlates this tab with its `Tabs.Panel` counterpart. */
+  value: string;
+  disabled?: boolean;
+  isHovered?: boolean;
+  isActive?: boolean;
+  isFocused?: boolean;
+  isFocusVisible?: boolean;
+  isDisabled?: boolean;
+}
+
+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. */
+  unmountWhenInactive?: boolean;
+  children?: ReactNode;
+}
+
+export interface TabInteractionState extends InteractionState {
+  selected: boolean;
+}
+
+export interface RegisteredTab {
+  disabled: boolean;
+  node: { focus?: () => void } | null;
+}
+
+export interface TabsContextValue {
+  value: string | undefined;
+  onValueChange: (value: string) => void;
+  disabled: boolean;
+  activationMode: TabsActivationMode;
+  orientation: TabsOrientation;
+  listId: string;
+  registerTab: (value: string, entry: RegisteredTab) => void;
+  unregisterTab: (value: string) => void;
+  getTabs: () => [string, RegisteredTab][];
+  /** Currently roving-focused tab value (keyboard navigation), distinct from committed `value`. */
+  focusedValue: string | undefined;
+  setFocusedValue: (value: string | undefined) => void;
+}

package/src/tabs/useTabsNavigation.ts

@@ -0,0 +1,97 @@
+import { useCallback, useRef } from 'react';
+import type { RegisteredTab, TabsActivationMode, TabsOrientation } from './types';
+
+// Web-only — native platforms rely on OS-managed sequential focus (VoiceOver/TalkBack),
+// same restriction documented on `useListboxNavigation` in `../select/`.
+
+export interface UseTabsNavigationOptions {
+  getTabs: () => [string, RegisteredTab][];
+  focusedValue: string | undefined;
+  setFocusedValue: (value: string | undefined) => void;
+  value: string | undefined;
+  onValueChange: (value: string) => void;
+  activationMode: TabsActivationMode;
+  orientation: TabsOrientation;
+}
+
+export function useTabsNavigation({
+  getTabs,
+  focusedValue,
+  setFocusedValue,
+  value,
+  onValueChange,
+  activationMode,
+  orientation,
+}: UseTabsNavigationOptions) {
+  const onValueChangeRef = useRef(onValueChange);
+  onValueChangeRef.current = onValueChange;
+
+  const getEnabledTabs = useCallback(
+    () => getTabs().filter(([, entry]) => !entry.disabled),
+    [getTabs],
+  );
+
+  const moveFocus = useCallback(
+    ([targetValue, targetEntry]: [string, RegisteredTab]) => {
+      setFocusedValue(targetValue);
+      targetEntry.node?.focus?.();
+      if (activationMode === 'automatic') {
+        onValueChangeRef.current(targetValue);
+      }
+    },
+    [setFocusedValue, activationMode],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: any) => {
+      const enabledTabs = getEnabledTabs();
+      if (enabledTabs.length === 0) {
+        return;
+      }
+
+      const currentValue = focusedValue ?? value;
+      const idx = enabledTabs.findIndex(([tabValue]) => tabValue === currentValue);
+
+      // ARIA APG tabs pattern: horizontal lists respond to Left/Right, vertical lists to Up/Down.
+      const nextKey = orientation === 'vertical' ? 'ArrowDown' : 'ArrowRight';
+      const prevKey = orientation === 'vertical' ? 'ArrowUp' : 'ArrowLeft';
+
+      switch (e.key) {
+        case nextKey: {
+          e.preventDefault();
+          moveFocus(enabledTabs[idx < enabledTabs.length - 1 ? idx + 1 : 0]);
+          break;
+        }
+        case prevKey: {
+          e.preventDefault();
+          moveFocus(enabledTabs[idx > 0 ? idx - 1 : enabledTabs.length - 1]);
+          break;
+        }
+        case 'Home': {
+          e.preventDefault();
+          moveFocus(enabledTabs[0]);
+          break;
+        }
+        case 'End': {
+          e.preventDefault();
+          const last = enabledTabs.at(-1);
+          if (last) {
+            moveFocus(last);
+          }
+          break;
+        }
+        case 'Enter':
+        case ' ': {
+          if (activationMode === 'manual' && focusedValue) {
+            e.preventDefault();
+            onValueChangeRef.current(focusedValue);
+          }
+          break;
+        }
+      }
+    },
+    [focusedValue, value, getEnabledTabs, moveFocus, activationMode, orientation],
+  );
+
+  return { handleKeyDown };
+}