@cdx-ui/components 0.0.1-beta.121 → 0.0.1-beta.122

package/src/components/Tabs/index.tsx

@@ -0,0 +1,694 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ComponentProps,
+  type ComponentRef,
+  type ReactNode,
+} from 'react';
+import {
+  Platform,
+  Pressable,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+  type LayoutChangeEvent,
+  type TextProps,
+  type ViewProps,
+} from 'react-native';
+import Animated, { useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated';
+import { ChevronLeft, ChevronRight } from '@cdx-ui/icons';
+import {
+  Tab as TabPrimitive,
+  TabPanel as TabPanelPrimitive,
+  TabsList as TabsListPrimitive,
+  TabsRoot as TabsRootPrimitive,
+  Slot,
+  dataAttributes,
+  mergeDataAttributes,
+  useTabContext,
+  useTabsContext,
+  type ITabPanelProps,
+  type ITabProps,
+  type ITabsListProps,
+  type ITabsProps,
+} from '@cdx-ui/primitives';
+import { cn, createContext } from '@cdx-ui/utils';
+import { Icon } from '../Icon';
+import { ScrollShadow } from '../ScrollShadow';
+import {
+  tabsIndicatorVariants,
+  tabsListSolidShellBgVariants,
+  tabsListSolidShellVariants,
+  tabsListSolidScrollButtonSlotVariants,
+  tabsListSolidScrollButtonVariants,
+  tabsListScrollButtonVariants,
+  tabsListScrollContainerVariants,
+  tabsListScrollViewVariants,
+  tabsListTrackVariants,
+  tabsListVariants,
+  tabsOutlineTrackVariants,
+  tabsPanelVariants,
+  tabsRootVariants,
+  tabsStyles,
+  tabsTabLabelVariants,
+  tabsTabVariants,
+  TABS_INDICATOR_TRANSITION_MS,
+  TABS_SOLID_SCROLL_FADE_SIZE,
+  TABS_SCROLL_FADE_SIZE,
+  OUTLINE_INDICATOR_THICKNESS,
+  type TabsVariant,
+} from './styles';
+
+export type { TabsVariant };
+
+interface TabLayout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Minimum horizontal scroll offset so `layout` is fully inside the viewport. */
+function scrollXToRevealTab(
+  layout: TabLayout,
+  viewportWidth: number,
+  currentScrollX: number,
+): number {
+  const tabStart = layout.x;
+  const tabEnd = layout.x + layout.width;
+  const viewEnd = currentScrollX + viewportWidth;
+
+  if (tabStart < currentScrollX) {
+    return tabStart;
+  }
+  if (tabEnd > viewEnd) {
+    return tabEnd - viewportWidth;
+  }
+  return currentScrollX;
+}
+
+function clampScrollX(scrollX: number, viewportWidth: number, contentWidth: number): number {
+  const maxScrollX = Math.max(0, contentWidth - viewportWidth);
+  return Math.min(Math.max(0, scrollX), maxScrollX);
+}
+
+interface TabsIndicatorContextValue {
+  reportLayout: (value: string, layout: TabLayout) => void;
+  clearLayout: (value: string) => void;
+  variant: TabsVariant;
+}
+
+const [TabsIndicatorProvider, useTabsIndicatorContext] =
+  createContext<TabsIndicatorContextValue>('TabsIndicatorContext');
+
+interface TabsVariantContextValue {
+  variant: TabsVariant;
+}
+
+const [TabsVariantProvider, useTabsVariantContext] =
+  createContext<TabsVariantContextValue>('TabsVariantContext');
+
+// =============================================================================
+// STYLED ROOT
+// =============================================================================
+
+export interface TabsProps extends Omit<ViewProps, 'children'>, ITabsProps {
+  /** `solid` (default) slides a filled indicator behind the active tab; `outline` draws a sliding line indicator. Styled per Forge DS SegmentedControl (solid). */
+  variant?: TabsVariant;
+  className?: string;
+}
+
+const TabsRoot = forwardRef<ComponentRef<typeof View>, TabsProps>(
+  (
+    { className, style, children, variant = 'solid', orientation = 'horizontal', ...props },
+    ref,
+  ) => (
+    <TabsVariantProvider value={{ variant }}>
+      <TabsRootPrimitive
+        ref={ref}
+        orientation={orientation}
+        className={cn(tabsRootVariants({ orientation }), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'tabs' }))}
+      >
+        {children}
+      </TabsRootPrimitive>
+    </TabsVariantProvider>
+  ),
+);
+
+TabsRoot.displayName = 'Tabs';
+
+// =============================================================================
+// STYLED LIST — hosts the animated selection indicator
+// =============================================================================
+
+export interface TabsListProps extends ITabsListProps {
+  asChild?: boolean;
+  className?: string;
+  /**
+   * When `orientation="horizontal"`, scroll tab triggers if they overflow the list width.
+   * Vertical lists do not scroll — tabs stack in a column (matches HeroUI / ARIA scrollable
+   * tablist patterns, which are horizontal-only).
+   * @default true
+   */
+  scrollable?: boolean;
+  showsHorizontalScrollIndicator?: boolean;
+}
+
+const TabsList = forwardRef<ComponentRef<typeof View>, TabsListProps>(
+  (
+    {
+      asChild,
+      className,
+      style,
+      children,
+      scrollable = true,
+      showsHorizontalScrollIndicator = false,
+      ...props
+    },
+    ref,
+  ) => {
+    const { value, orientation, getTabs } = useTabsContext();
+    const { variant } = useTabsVariantContext();
+    const isHorizontalScroll = orientation === 'horizontal' && scrollable;
+    const isWebHorizontalScroll = isHorizontalScroll && Platform.OS === 'web';
+    const shouldAutoScrollActiveTab = isHorizontalScroll && Platform.OS !== 'web';
+
+    const layoutsRef = useRef<Map<string, TabLayout>>(new Map());
+    const hasMeasuredRef = useRef(false);
+    const scrollRef = useRef<ScrollView>(null);
+    const scrollViewWidthRef = useRef(0);
+    const scrollContentWidthRef = useRef(0);
+    const scrollXRef = useRef(0);
+    const [scrollCapability, setScrollCapability] = useState({
+      canScrollBefore: false,
+      canScrollAfter: false,
+    });
+    const translateX = useSharedValue(0);
+    const translateY = useSharedValue(0);
+    // Both variants animate measured width/height. Measured size + translate is reliable
+    // and keeps `rounded-full` looking like a capsule for the solid variant.
+    const width = useSharedValue(0);
+    const height = useSharedValue(0);
+
+    const scrollActiveTabIntoView = useCallback(
+      (layout: TabLayout | undefined, activeTabValue: string | undefined = value) => {
+        if (
+          !shouldAutoScrollActiveTab ||
+          !layout ||
+          !scrollRef.current ||
+          activeTabValue === undefined
+        ) {
+          return;
+        }
+
+        const viewportWidth = scrollViewWidthRef.current;
+        if (viewportWidth <= 0) {
+          return;
+        }
+
+        let nextScrollX = scrollXToRevealTab(layout, viewportWidth, scrollXRef.current);
+
+        const tabOrder = getTabs().map(([tabValue]) => tabValue);
+        const activeIndex = tabOrder.indexOf(activeTabValue);
+
+        // Active tab fully visible at the right edge — peek the next sibling in.
+        if (activeIndex >= 0 && activeIndex < tabOrder.length - 1) {
+          const nextLayout = layoutsRef.current.get(tabOrder[activeIndex + 1]);
+          if (nextLayout) {
+            const viewEnd = nextScrollX + viewportWidth;
+            const nextTabEnd = nextLayout.x + nextLayout.width;
+            if (nextTabEnd > viewEnd) {
+              nextScrollX = Math.max(nextScrollX, nextTabEnd - viewportWidth);
+            }
+          }
+        }
+
+        // Active tab fully visible at the left edge — peek the previous sibling in.
+        if (activeIndex > 0) {
+          const prevLayout = layoutsRef.current.get(tabOrder[activeIndex - 1]);
+          if (prevLayout && prevLayout.x < nextScrollX) {
+            nextScrollX = Math.min(nextScrollX, prevLayout.x);
+          }
+        }
+
+        nextScrollX = clampScrollX(nextScrollX, viewportWidth, scrollContentWidthRef.current);
+
+        scrollXRef.current = nextScrollX;
+        scrollRef.current.scrollTo({ x: nextScrollX, animated: true });
+      },
+      [getTabs, shouldAutoScrollActiveTab, value],
+    );
+
+    const retryScrollActiveTabIntoView = useCallback(() => {
+      if (value === undefined) {
+        return;
+      }
+
+      if (scrollViewWidthRef.current <= 0 || scrollContentWidthRef.current <= 0) {
+        return;
+      }
+
+      scrollActiveTabIntoView(layoutsRef.current.get(value), value);
+    }, [value, scrollActiveTabIntoView]);
+
+    const scrollTabsByPage = useCallback((direction: -1 | 1) => {
+      if (!scrollRef.current) {
+        return;
+      }
+
+      const viewportWidth = scrollViewWidthRef.current;
+      if (viewportWidth <= 0) {
+        return;
+      }
+
+      const nextScrollX = clampScrollX(
+        scrollXRef.current + direction * viewportWidth * 0.8,
+        viewportWidth,
+        scrollContentWidthRef.current,
+      );
+
+      scrollXRef.current = nextScrollX;
+      scrollRef.current.scrollTo({ x: nextScrollX, animated: true });
+    }, []);
+
+    const applyLayout = useCallback(
+      (layout: TabLayout | undefined) => {
+        if (!layout) {
+          return;
+        }
+
+        let nextX = layout.x;
+        let nextY = layout.y;
+        let nextW = layout.width;
+        let nextH = layout.height;
+
+        if (variant === 'outline') {
+          if (orientation === 'vertical') {
+            // X offset comes from `style.left = TRACK` (indicator to the right of the rail).
+            nextX = 0;
+            nextW = OUTLINE_INDICATOR_THICKNESS;
+          } else {
+            // Y offset comes from `style.bottom = TRACK` (indicator above the rail).
+            nextY = 0;
+            nextH = OUTLINE_INDICATOR_THICKNESS;
+          }
+        }
+
+        if (hasMeasuredRef.current) {
+          // Explicit duration — kept in sync with `TABS_INDICATOR_TRANSITION_MS`, the web focus
+          // ring's `transition` duration, so the ring doesn't visually outrun the sliding indicator.
+          const config = { duration: TABS_INDICATOR_TRANSITION_MS };
+          translateX.set(withTiming(nextX, config));
+          translateY.set(withTiming(nextY, config));
+          width.set(withTiming(nextW, config));
+          height.set(withTiming(nextH, config));
+        } else {
+          translateX.set(nextX);
+          translateY.set(nextY);
+          width.set(nextW);
+          height.set(nextH);
+          hasMeasuredRef.current = true;
+        }
+      },
+      [translateX, translateY, width, height, variant, orientation],
+    );
+
+    const reportLayout = useCallback(
+      (tabValue: string, layout: TabLayout) => {
+        layoutsRef.current.set(tabValue, layout);
+        if (tabValue === value) {
+          applyLayout(layout);
+          scrollActiveTabIntoView(layout, tabValue);
+        }
+      },
+      [value, applyLayout, scrollActiveTabIntoView],
+    );
+
+    const clearLayout = useCallback((tabValue: string) => {
+      layoutsRef.current.delete(tabValue);
+    }, []);
+
+    // `useLayoutEffect` (not `useEffect`) — the web focus ring's CSS transition starts
+    // synchronously as part of the same commit that flips `data-focus-visible` on the newly
+    // selected tab. A deferred `useEffect` would schedule the indicator's `withTiming` glide a
+    // frame later than that, so the ring's own transition would finish first even though both
+    // share `TABS_INDICATOR_TRANSITION_MS` — running this synchronously keeps both starting in
+    // the same frame.
+    useLayoutEffect(() => {
+      if (value !== undefined) {
+        const layout = layoutsRef.current.get(value);
+        applyLayout(layout);
+        scrollActiveTabIntoView(layout, value);
+      }
+    }, [value, applyLayout, scrollActiveTabIntoView]);
+
+    const indicatorAnimatedStyle = useAnimatedStyle(() => ({
+      width: width.get(),
+      height: height.get(),
+      transform: [{ translateX: translateX.get() }, { translateY: translateY.get() }],
+    }));
+
+    const isSolidHorizontalScroll = isHorizontalScroll && variant === 'solid';
+    const trackClassName = cn(
+      tabsListTrackVariants({ orientation, variant, scrollable: isHorizontalScroll }),
+    );
+    const trackStyle =
+      variant === 'solid' && !isSolidHorizontalScroll
+        ? orientation === 'vertical'
+          ? tabsStyles.solidTrackVertical
+          : tabsStyles.solidTrack
+        : null;
+
+    const handleScrollViewLayout = useCallback(
+      (event: LayoutChangeEvent) => {
+        scrollViewWidthRef.current = event.nativeEvent.layout.width;
+        retryScrollActiveTabIntoView();
+      },
+      [retryScrollActiveTabIntoView],
+    );
+
+    const handleScrollViewContentSizeChange = useCallback(
+      (contentWidth: number) => {
+        scrollContentWidthRef.current = contentWidth;
+        retryScrollActiveTabIntoView();
+      },
+      [retryScrollActiveTabIntoView],
+    );
+
+    const handleScrollViewScroll = useCallback(
+      (event: Parameters<NonNullable<ComponentProps<typeof ScrollView>['onScroll']>>[0]) => {
+        scrollXRef.current = event.nativeEvent.contentOffset.x;
+      },
+      [],
+    );
+
+    const listTrack = (
+      <View className={trackClassName} style={trackStyle}>
+        {variant === 'outline' ? (
+          <View pointerEvents="none" className={cn(tabsOutlineTrackVariants({ orientation }))} />
+        ) : null}
+        <Animated.View
+          pointerEvents="none"
+          className={cn(tabsIndicatorVariants({ orientation, variant }))}
+          style={[
+            variant === 'outline'
+              ? [
+                  tabsStyles.outlineIndicator,
+                  orientation === 'vertical'
+                    ? tabsStyles.outlineIndicatorVertical
+                    : tabsStyles.outlineIndicatorHorizontal,
+                ]
+              : tabsStyles.solidIndicator,
+            indicatorAnimatedStyle,
+          ]}
+        />
+        {children}
+      </View>
+    );
+
+    const horizontalScrollView = (
+      <ScrollView
+        ref={scrollRef}
+        horizontal
+        showsHorizontalScrollIndicator={showsHorizontalScrollIndicator}
+        keyboardShouldPersistTaps="handled"
+        className={cn(tabsListScrollViewVariants())}
+        style={isHorizontalScroll ? tabsStyles.horizontalScrollViewBleed : null}
+        contentContainerStyle={isHorizontalScroll ? tabsStyles.horizontalScrollContent : undefined}
+        onLayout={handleScrollViewLayout}
+        onContentSizeChange={handleScrollViewContentSizeChange}
+        onScroll={handleScrollViewScroll}
+        scrollEventThrottle={16}
+      >
+        {listTrack}
+      </ScrollView>
+    );
+
+    const wrapSolidScrollShell = (scrollArea: ReactNode) =>
+      isSolidHorizontalScroll ? (
+        <View className={cn(tabsListSolidShellVariants())} style={tabsStyles.solidShell}>
+          <View
+            pointerEvents="none"
+            className={cn(tabsListSolidShellBgVariants())}
+            style={tabsStyles.solidTrack}
+          />
+          <View className="relative z-10 min-w-0">{scrollArea}</View>
+        </View>
+      ) : (
+        scrollArea
+      );
+
+    const renderSolidScrollChevron = (position: 'start' | 'end', direction: -1 | 1) => {
+      const canScroll =
+        position === 'start' ? scrollCapability.canScrollBefore : scrollCapability.canScrollAfter;
+      if (!canScroll) {
+        return null;
+      }
+
+      const IconComponent = position === 'start' ? ChevronLeft : ChevronRight;
+      const label = position === 'start' ? 'Scroll tabs left' : 'Scroll tabs right';
+
+      return (
+        <View
+          pointerEvents="box-none"
+          className={cn(tabsListSolidScrollButtonSlotVariants({ position }))}
+        >
+          <Pressable
+            accessibilityLabel={label}
+            accessibilityRole="button"
+            className={cn(tabsListSolidScrollButtonVariants())}
+            tabIndex={-1}
+            onPress={() => scrollTabsByPage(direction)}
+          >
+            <Icon as={IconComponent} className="size-5 text-content-secondary" />
+          </Pressable>
+        </View>
+      );
+    };
+
+    const solidWebHorizontalScroll = (
+      <View className="relative min-w-0 w-full">
+        <ScrollShadow
+          hideScrollBar
+          orientation="horizontal"
+          size={TABS_SOLID_SCROLL_FADE_SIZE}
+          fadeFromClassName="from-surface-secondary"
+          onCapabilityChange={setScrollCapability}
+        >
+          {horizontalScrollView}
+        </ScrollShadow>
+        {renderSolidScrollChevron('start', -1)}
+        {renderSolidScrollChevron('end', 1)}
+      </View>
+    );
+
+    const outlineWebHorizontalScroll = (
+      <View className="w-full min-w-0 flex-row items-stretch">
+        {scrollCapability.canScrollBefore ? (
+          <Pressable
+            accessibilityLabel="Scroll tabs left"
+            accessibilityRole="button"
+            className={cn(tabsListScrollButtonVariants())}
+            tabIndex={-1}
+            onPress={() => scrollTabsByPage(-1)}
+          >
+            <Icon as={ChevronLeft} className="size-4 text-content-secondary" />
+          </Pressable>
+        ) : null}
+        <View className="min-w-0 flex-1">
+          <ScrollShadow
+            hideScrollBar
+            orientation="horizontal"
+            size={TABS_SCROLL_FADE_SIZE}
+            fadeFromClassName="from-background/85"
+            onCapabilityChange={setScrollCapability}
+          >
+            {horizontalScrollView}
+          </ScrollShadow>
+        </View>
+        {scrollCapability.canScrollAfter ? (
+          <Pressable
+            accessibilityLabel="Scroll tabs right"
+            accessibilityRole="button"
+            className={cn(tabsListScrollButtonVariants())}
+            tabIndex={-1}
+            onPress={() => scrollTabsByPage(1)}
+          >
+            <Icon as={ChevronRight} className="size-4 text-content-secondary" />
+          </Pressable>
+        ) : null}
+      </View>
+    );
+
+    return (
+      <TabsIndicatorProvider value={{ reportLayout, clearLayout, variant }}>
+        <TabsListPrimitive
+          ref={ref}
+          asChild={asChild}
+          className={cn(tabsListVariants(), className)}
+          style={style}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ slot: 'tabs-list' }))}
+        >
+          {isWebHorizontalScroll ? (
+            <View className={cn(tabsListScrollContainerVariants())}>
+              {wrapSolidScrollShell(
+                isSolidHorizontalScroll ? solidWebHorizontalScroll : outlineWebHorizontalScroll,
+              )}
+            </View>
+          ) : isHorizontalScroll ? (
+            wrapSolidScrollShell(horizontalScrollView)
+          ) : (
+            listTrack
+          )}
+        </TabsListPrimitive>
+      </TabsIndicatorProvider>
+    );
+  },
+);
+
+TabsList.displayName = 'Tabs.List';
+
+// =============================================================================
+// STYLED TAB
+// =============================================================================
+
+export interface TabsTabProps extends Omit<ITabProps, 'children'> {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+const TabsTab = forwardRef<ComponentRef<typeof Pressable>, TabsTabProps>(
+  ({ asChild, className, style, children, value: tabValue, onLayout, ...props }, ref) => {
+    const { reportLayout, clearLayout, variant } = useTabsIndicatorContext();
+    const { orientation } = useTabsContext();
+
+    useEffect(() => {
+      return () => clearLayout(tabValue);
+    }, [tabValue, clearLayout]);
+
+    const handleLayout = useCallback(
+      (e: LayoutChangeEvent) => {
+        onLayout?.(e);
+        const { x, y, width, height } = e.nativeEvent.layout;
+        reportLayout(tabValue, { x, y, width, height });
+      },
+      [onLayout, reportLayout, tabValue],
+    );
+
+    return (
+      <TabPrimitive
+        ref={ref}
+        asChild={asChild}
+        value={tabValue}
+        className={cn(tabsTabVariants({ orientation, variant }), className)}
+        style={
+          variant === 'solid'
+            ? (state) =>
+                StyleSheet.flatten([
+                  tabsStyles.solidTabPressable,
+                  typeof style === 'function' ? style(state) : style,
+                ])
+            : style
+        }
+        onLayout={handleLayout}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'tabs-tab' }))}
+      >
+        {children}
+      </TabPrimitive>
+    );
+  },
+);
+
+TabsTab.displayName = 'Tabs.Tab';
+
+// =============================================================================
+// STYLED TAB LABEL (styled-only, reads tab context for selected state)
+// =============================================================================
+
+export interface TabsTabLabelProps extends TextProps {
+  asChild?: boolean;
+  className?: string;
+}
+
+const TabsTabLabel = forwardRef<ComponentRef<typeof Text>, TabsTabLabelProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { selected } = useTabContext();
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(tabsTabLabelVariants({ state: selected ? 'active' : 'inactive' }), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({ slot: 'tabs-tab-label', state: selected ? 'active' : 'inactive' }),
+        )}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+TabsTabLabel.displayName = 'Tabs.TabLabel';
+
+// =============================================================================
+// STYLED PANEL
+// =============================================================================
+
+export interface TabsPanelProps extends ITabPanelProps {
+  asChild?: boolean;
+  className?: string;
+}
+
+const TabsPanel = forwardRef<ComponentRef<typeof View>, TabsPanelProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { orientation } = useTabsContext();
+
+    return (
+      <TabPanelPrimitive
+        ref={ref}
+        asChild={asChild}
+        className={cn(tabsPanelVariants({ orientation }), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'tabs-panel' }))}
+      >
+        {children}
+      </TabPanelPrimitive>
+    );
+  },
+);
+
+TabsPanel.displayName = 'Tabs.Panel';
+
+// =============================================================================
+// COMPOUND COMPONENT
+// =============================================================================
+
+type TabsCompoundComponent = typeof TabsRoot & {
+  List: typeof TabsList;
+  Tab: typeof TabsTab;
+  TabLabel: typeof TabsTabLabel;
+  Panel: typeof TabsPanel;
+};
+
+export const Tabs = Object.assign(TabsRoot, {
+  List: TabsList,
+  Tab: TabsTab,
+  TabLabel: TabsTabLabel,
+  Panel: TabsPanel,
+}) as TabsCompoundComponent;