@cdx-ui/primitives 0.0.1-beta.99 → 0.1.1

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/tooltip/TooltipContent.tsx

@@ -0,0 +1,117 @@
+import { forwardRef, useCallback, useLayoutEffect, type ComponentRef } from 'react';
+import { Platform, StyleSheet, View } from 'react-native';
+import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
+import { Portal } from '../portal';
+import { useAnchoredOverlay, useDismissOverlay, useEscapeKey } from '../overlay';
+import { createPortalFn } from '../utils/createPortal';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { TooltipProvider, useTooltipContext } from './context';
+import { TOOLTIP_Z_INDEX } from './getTooltipPosition';
+import type { ITooltipContentProps } from './types';
+
+export interface TooltipContentProps extends ITooltipContentProps {}
+
+export const TooltipContent = forwardRef<ComponentRef<typeof View>, TooltipContentProps>(
+  ({ asChild, children, onLayout, ...props }, ref) => {
+    const contextValue = useTooltipContext();
+    const {
+      open,
+      setOpen,
+      isDisabled,
+      placement,
+      offset,
+      trigger,
+      triggerRef,
+      contentId,
+      resolvedPlacement,
+      setResolvedPlacement,
+    } = contextValue;
+
+    const {
+      floatingRef,
+      onFloatingLayout,
+      style: overlayStyle,
+      position,
+    } = useAnchoredOverlay(triggerRef, open && !isDisabled, {
+      placement,
+      offset,
+      collisionBehavior: 'none',
+      width: 'content',
+    });
+    const mergedRef = mergeRefs(ref, floatingRef);
+
+    const handleDismiss = useCallback(() => {
+      setOpen(false);
+    }, [setOpen]);
+
+    const shouldDismissOnInteraction =
+      trigger === 'click' && Platform.OS === 'web' && open && !isDisabled;
+
+    useDismissOverlay(shouldDismissOnInteraction, floatingRef, [triggerRef], handleDismiss);
+    useEscapeKey(shouldDismissOnInteraction, handleDismiss);
+
+    useLayoutEffect(() => {
+      if (
+        position &&
+        (resolvedPlacement?.side !== position.resolvedPlacement.side ||
+          resolvedPlacement.align !== position.resolvedPlacement.align)
+      ) {
+        setResolvedPlacement(position.resolvedPlacement);
+      }
+    }, [position, resolvedPlacement, setResolvedPlacement]);
+
+    if (!open || isDisabled) {
+      return null;
+    }
+
+    const Comp = asChild ? Slot : View;
+    const webProps =
+      Platform.OS === 'web'
+        ? ({
+            id: contentId,
+            role: 'tooltip',
+          } as const)
+        : ({
+            accessibilityRole: 'text' as const,
+            accessibilityLiveRegion: 'polite' as const,
+          } as const);
+
+    const popup = (
+      <TooltipProvider value={contextValue}>
+        <View pointerEvents="none" style={[overlayStyle, { zIndex: TOOLTIP_Z_INDEX }]}>
+          <Comp
+            ref={mergedRef}
+            onLayout={composeEventHandlers(onLayout, onFloatingLayout)}
+            {...props}
+            {...webProps}
+            {...mergeDataAttributes(
+              props,
+              dataAttributes({
+                side: position?.resolvedPlacement.side,
+                align: position?.resolvedPlacement.align,
+                state: 'open',
+              }),
+            )}
+          >
+            {children}
+          </Comp>
+        </View>
+      </TooltipProvider>
+    );
+
+    if (Platform.OS === 'web' && createPortalFn && typeof document !== 'undefined') {
+      return createPortalFn(popup, document.body);
+    }
+
+    return (
+      <Portal name={contentId}>
+        <View pointerEvents="box-none" style={[StyleSheet.absoluteFill, { zIndex: 9999 }]}>
+          {popup}
+        </View>
+      </Portal>
+    );
+  },
+);
+
+TooltipContent.displayName = 'TooltipContent';

package/src/tooltip/TooltipRoot.tsx

@@ -0,0 +1,187 @@
+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 { TooltipProvider } from './context';
+import type { ResolvedTooltipPlacement } from './getTooltipPosition';
+import type { ITooltipProps } from './types';
+
+export interface TooltipRootProps extends ITooltipProps {
+  asChild?: boolean;
+}
+
+export const TooltipRoot = forwardRef<ComponentRef<typeof View>, TooltipRootProps>(
+  (
+    {
+      asChild,
+      children,
+      isDisabled = false,
+      enterDelay = 0,
+      leaveDelay = 0,
+      isOpen: isOpenProp,
+      defaultOpen = false,
+      onOpen,
+      onClose,
+      placement = 'top',
+      offset = 8,
+      trigger = 'hover',
+      ...props
+    },
+    ref,
+  ) => {
+    const [open, setOpenState] = useControllableState<boolean>({
+      prop: isOpenProp,
+      defaultProp: defaultOpen,
+      onChange: (next) => {
+        if (next) {
+          onOpen?.();
+        } else {
+          onClose?.();
+        }
+      },
+    });
+
+    const enterTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const leaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const triggerRef = useRef<ComponentRef<typeof View> | null>(null);
+    const [resolvedPlacement, setResolvedPlacement] = useState<ResolvedTooltipPlacement | null>(
+      null,
+    );
+
+    const clearTimers = useCallback(() => {
+      if (enterTimerRef.current) {
+        clearTimeout(enterTimerRef.current);
+        enterTimerRef.current = null;
+      }
+      if (leaveTimerRef.current) {
+        clearTimeout(leaveTimerRef.current);
+        leaveTimerRef.current = null;
+      }
+    }, []);
+
+    const setOpen = useCallback(
+      (nextOpen: boolean) => {
+        if (isDisabled && nextOpen) {
+          return;
+        }
+        setOpenState(nextOpen);
+      },
+      [isDisabled, setOpenState],
+    );
+
+    const requestOpen = useCallback(() => {
+      if (isDisabled) {
+        return;
+      }
+
+      clearTimers();
+
+      if (leaveTimerRef.current) {
+        clearTimeout(leaveTimerRef.current);
+        leaveTimerRef.current = null;
+      }
+
+      if (enterDelay <= 0) {
+        setOpen(true);
+        return;
+      }
+
+      enterTimerRef.current = setTimeout(() => {
+        setOpen(true);
+      }, enterDelay);
+    }, [clearTimers, enterDelay, isDisabled, setOpen]);
+
+    const requestClose = useCallback(() => {
+      clearTimers();
+
+      if (enterTimerRef.current) {
+        clearTimeout(enterTimerRef.current);
+        enterTimerRef.current = null;
+      }
+
+      if (leaveDelay <= 0) {
+        setOpen(false);
+        return;
+      }
+
+      leaveTimerRef.current = setTimeout(() => {
+        setOpen(false);
+      }, leaveDelay);
+    }, [clearTimers, leaveDelay, setOpen]);
+
+    useEffect(() => clearTimers, [clearTimers]);
+
+    const reactId = useId();
+    const triggerId = `tooltip-trigger-${reactId}`;
+    const contentId = `tooltip-content-${reactId}`;
+
+    const contextValue = useMemo(
+      () => ({
+        open: open ?? false,
+        setOpen,
+        requestOpen,
+        requestClose,
+        clearTimers,
+        isDisabled,
+        enterDelay,
+        leaveDelay,
+        placement,
+        offset,
+        trigger,
+        triggerRef,
+        contentId,
+        triggerId,
+        resolvedPlacement,
+        setResolvedPlacement,
+      }),
+      [
+        clearTimers,
+        contentId,
+        enterDelay,
+        isDisabled,
+        leaveDelay,
+        offset,
+        open,
+        placement,
+        requestClose,
+        requestOpen,
+        resolvedPlacement,
+        setOpen,
+        trigger,
+        triggerId,
+      ],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <TooltipProvider value={contextValue}>
+        <Comp
+          ref={ref}
+          {...(props as ViewProps)}
+          {...mergeDataAttributes(
+            props,
+            dataAttributes({
+              state: open ? 'open' : 'closed',
+              disabled: isDisabled,
+            }),
+          )}
+        >
+          {children}
+        </Comp>
+      </TooltipProvider>
+    );
+  },
+);
+
+TooltipRoot.displayName = 'TooltipRoot';