@cdx-ui/primitives 0.0.1-beta.13 → 0.0.1-beta.130

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,93 @@
+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;
+  /**
+   * If true, the tab will be in hovered state.
+   * @internal
+   */
+  isHovered?: boolean;
+  /**
+   * If true, the tab will be in pressed state.
+   * @internal
+   */
+  isActive?: boolean;
+  /**
+   * If true, the tab will be focused.
+   * @internal
+   */
+  isFocused?: boolean;
+  /**
+   * If true, the tab focus ring will be visible.
+   * @internal
+   */
+  isFocusVisible?: boolean;
+  /**
+   * If true, the tab will be disabled.
+   * @internal
+   */
+  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 };
+}

package/src/tile/TileGroup.tsx

@@ -0,0 +1,137 @@
+import { forwardRef, useCallback, useMemo, type ComponentRef } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { useControllableState } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { TileGroupContextProvider } from './context';
+import type { ITileGroupProps, TileGroupType } from './types';
+
+/**
+ * Internal widening of the public discriminated union: the runtime accepts any value
+ * shape and reads `type` to decide branch behavior. The public API stays narrow.
+ */
+type WidenedTileGroupProps = ViewProps & {
+  asChild?: boolean;
+  type: TileGroupType;
+  value?: string | string[];
+  defaultValue?: string | string[];
+  onValueChange?: (value: string | string[]) => void;
+  max?: number;
+  isDisabled?: boolean;
+  'aria-label'?: string;
+};
+
+export type TileGroupProps = ITileGroupProps;
+
+export const TileGroup = forwardRef<ComponentRef<typeof View>, TileGroupProps>((props, ref) => {
+  const {
+    asChild = false,
+    children,
+    type,
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    max: maxProp,
+    isDisabled = false,
+    'aria-label': ariaLabel,
+    ...rest
+  } = props as WidenedTileGroupProps;
+
+  const max = maxProp ?? Number.POSITIVE_INFINITY;
+
+  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 isSelected = useCallback(
+    (tileValue: string) => {
+      if (type === 'single') {
+        return state === tileValue;
+      }
+      return Array.isArray(state) && state.includes(tileValue);
+    },
+    [type, state],
+  );
+
+  const isTileDisabledByGroup = useCallback(
+    (tileValue: string) => {
+      if (isDisabled) {
+        return true;
+      }
+      if (type !== 'multiple') {
+        return false;
+      }
+      const arr = Array.isArray(state) ? state : [];
+      if (arr.length < max) {
+        return false;
+      }
+      return !arr.includes(tileValue);
+    },
+    [isDisabled, type, state, max],
+  );
+
+  const toggleValue = useCallback(
+    (tileValue: string) => {
+      if (isDisabled) {
+        return;
+      }
+      if (type === 'single') {
+        if (state === tileValue) {
+          return;
+        }
+        setState(tileValue);
+        return;
+      }
+      const arr = Array.isArray(state) ? [...state] : [];
+      const idx = arr.indexOf(tileValue);
+      if (idx >= 0) {
+        arr.splice(idx, 1);
+        setState(arr);
+      } else if (arr.length < max) {
+        arr.push(tileValue);
+        setState(arr);
+      }
+    },
+    [isDisabled, type, state, setState, max],
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      type,
+      value: state,
+      toggleValue,
+      isSelected,
+      isTileDisabledByGroup,
+      isGroupDisabled: isDisabled,
+      max,
+    }),
+    [type, state, toggleValue, isSelected, isTileDisabledByGroup, isDisabled, max],
+  );
+
+  const role = type === 'single' ? 'radiogroup' : 'group';
+  const Comp = asChild ? Slot : View;
+
+  return (
+    <TileGroupContextProvider value={contextValue}>
+      <Comp
+        ref={ref}
+        role={role}
+        {...(type === 'single' ? { accessibilityRole: 'radiogroup' as const } : {})}
+        {...(ariaLabel ? { 'aria-label': ariaLabel, accessibilityLabel: ariaLabel } : {})}
+        {...(rest as ViewProps)}
+      >
+        {children}
+      </Comp>
+    </TileGroupContextProvider>
+  );
+});
+
+TileGroup.displayName = 'TileGroup';

package/src/tile/TileRoot.tsx

@@ -0,0 +1,137 @@
+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 { TileProvider, useOptionalTileGroupContext } from './context';
+import type { ITileProps, ITilePressablePassthrough } from './types';
+
+const rowStyle = {
+  flexDirection: 'row' as const,
+  alignSelf: 'stretch' as const,
+  alignItems: 'center' as const,
+};
+
+export interface TileRootProps extends ITileProps {}
+
+export const TileRoot = forwardRef<ComponentRef<typeof Pressable>, TileRootProps>(
+  (
+    {
+      asChild = false,
+      value,
+      disabled: disabledProp = false,
+      isSelected: controlledSelected,
+      defaultSelected,
+      onSelectedChange,
+      children,
+      onPress,
+      onFocus,
+      onBlur,
+      style,
+      ...rest
+    },
+    ref,
+  ) => {
+    const group = useOptionalTileGroupContext();
+
+    const [standaloneSelected = false, setStandaloneSelected] = useControllableState<boolean>({
+      prop: controlledSelected,
+      defaultProp: defaultSelected ?? false,
+      onChange: (next) => {
+        onSelectedChange?.(next);
+      },
+    });
+
+    const isSelected = group ? group.isSelected(value) : standaloneSelected;
+    const disabledByGroup = group ? group.isTileDisabledByGroup(value) : false;
+    const isDisabled = disabledByGroup || disabledProp;
+    const cannotToggle = isDisabled;
+
+    const { focusProps, isFocused } = useFocus();
+    const { isFocusVisible, focusProps: focusRingProps } = useFocusRing() as {
+      isFocusVisible: boolean;
+      focusProps: typeof focusProps;
+    };
+    const { pressProps, isPressed } = usePress({ isDisabled: cannotToggle });
+    const { hoverProps, isHovered } = useHover();
+
+    // Standalone tiles use checkbox semantics (independent on/off toggle).
+    const selectionType = group ? group.type : 'multiple';
+
+    const accessibilityState = useMemo(
+      () => ({
+        disabled: isDisabled,
+        ...(selectionType === 'single' ? { selected: isSelected } : { checked: isSelected }),
+      }),
+      [isDisabled, isSelected, selectionType],
+    );
+
+    const tileContext = useMemo(
+      () => ({ value, isSelected, isDisabled, selectionType }),
+      [value, isSelected, isDisabled, selectionType],
+    );
+
+    const passthrough = rest as ITilePressablePassthrough;
+
+    const composedOnPress = composeEventHandlers(onPress, () => {
+      if (cannotToggle) {
+        return;
+      }
+      if (group) {
+        group.toggleValue(value);
+      } else {
+        setStandaloneSelected(!standaloneSelected);
+      }
+    });
+
+    const role = selectionType === 'single' ? 'radio' : 'checkbox';
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <TileProvider value={tileContext}>
+        <Comp
+          ref={ref}
+          accessibilityRole={role}
+          role={role}
+          accessibilityState={accessibilityState}
+          aria-checked={isSelected}
+          {...(isDisabled ? { 'aria-disabled': true as const } : {})}
+          disabled={isDisabled}
+          {...(rest as PressableProps)}
+          {...mergeDataAttributes(
+            rest,
+            dataAttributes({
+              state: isSelected ? 'selected' : 'unselected',
+              disabled: isDisabled,
+              active: isPressed,
+              hover: isHovered,
+              focus: isFocused,
+              focusVisible: isFocusVisible,
+            }),
+          )}
+          style={[rowStyle, style]}
+          onPress={isDisabled ? undefined : composedOnPress}
+          onPressIn={composeEventHandlers(passthrough.onPressIn, pressProps.onPressIn)}
+          onPressOut={composeEventHandlers(passthrough.onPressOut, pressProps.onPressOut)}
+          onHoverIn={composeEventHandlers(passthrough.onHoverIn, hoverProps.onHoverIn)}
+          onHoverOut={composeEventHandlers(passthrough.onHoverOut, hoverProps.onHoverOut)}
+          onFocus={composeEventHandlers(
+            composeEventHandlers(onFocus, focusProps.onFocus),
+            focusRingProps.onFocus,
+          )}
+          onBlur={composeEventHandlers(
+            composeEventHandlers(onBlur, focusProps.onBlur),
+            focusRingProps.onBlur,
+          )}
+        >
+          {children}
+        </Comp>
+      </TileProvider>
+    );
+  },
+);
+
+TileRoot.displayName = 'TileRoot';

package/src/tile/index.ts

@@ -1,19 +1,5 @@
-import type React from 'react';
-import { createTileContent } from './createTileContent';
-import { createTileDescription } from './createTileDescription';
-import { createTileGroup } from './createTileGroup';
-import { createTileIndicator } from './createTileIndicator';
-import { createTileLeadingSlot } from './createTileLeadingSlot';
-import { createTileRoot } from './createTileRoot';
-import { createTileTitle } from './createTileTitle';
-import { createTileTrailingSlot } from './createTileTrailingSlot';
-import type { ITileComponentType } from './types';
-
 export type {
-  ITileComponentType,
-  ITileContentProps,
   ITileContextValue,
-  ITileDescriptionProps,
   ITileGroupMultipleProps,
   ITileGroupProps,
   ITileGroupSingleProps,
@@ -22,67 +8,11 @@ export type {
   ITileLeadingSlotProps,
   ITilePressablePassthrough,
   ITileProps,
-  ITileTitleProps,
   ITileTrailingSlotProps,
   TileGroupType,
   TileGroupValue,
 } from './types';
 
 export { TileProvider, useTileContext } from './context';
-
-export function createTile<
-  Pressable,
-  Leading,
-  Content,
-  Title,
-  Description,
-  Indicator,
-  TrailingSlot,
-  Group,
->(BaseComponents: {
-  Pressable: React.ComponentType<Pressable>;
-  LeadingSlot: React.ComponentType<Leading>;
-  Content: React.ComponentType<Content>;
-  Title: React.ComponentType<Title>;
-  Description: React.ComponentType<Description>;
-  Indicator: React.ComponentType<Indicator>;
-  TrailingSlot: React.ComponentType<TrailingSlot>;
-  Group: React.ComponentType<Group>;
-}) {
-  const Tile = createTileRoot(BaseComponents.Pressable);
-  const Group = createTileGroup(BaseComponents.Group);
-  const LeadingSlot = createTileLeadingSlot(BaseComponents.LeadingSlot);
-  const Content = createTileContent(BaseComponents.Content);
-  const Title = createTileTitle(BaseComponents.Title);
-  const Description = createTileDescription(BaseComponents.Description);
-  const Indicator = createTileIndicator(BaseComponents.Indicator);
-  const TrailingSlot = createTileTrailingSlot(BaseComponents.TrailingSlot);
-
-  Tile.displayName = 'TilePrimitive';
-  Group.displayName = 'TilePrimitive.Group';
-  LeadingSlot.displayName = 'TilePrimitive.LeadingSlot';
-  Content.displayName = 'TilePrimitive.Content';
-  Title.displayName = 'TilePrimitive.Title';
-  Description.displayName = 'TilePrimitive.Description';
-  Indicator.displayName = 'TilePrimitive.Indicator';
-  TrailingSlot.displayName = 'TilePrimitive.TrailingSlot';
-
-  return Object.assign(Tile, {
-    Group,
-    LeadingSlot,
-    Content,
-    Title,
-    Description,
-    Indicator,
-    TrailingSlot,
-  }) as ITileComponentType<
-    Pressable,
-    Leading,
-    Content,
-    Title,
-    Description,
-    Indicator,
-    TrailingSlot,
-    Group
-  >;
-}
+export { TileRoot, type TileRootProps } from './TileRoot';
+export { TileGroup, type TileGroupProps } from './TileGroup';