panelui-native 0.9.0 → 0.13.0

package/src/components/tabs/index.tsx

@@ -1,24 +1,104 @@
+/**
+ * Tabs — segmented navigation between panels.
+ *
+ * The active tab is marked by one indicator that slides between measured
+ * trigger positions rather than by a style on each trigger. That is what makes
+ * the movement continuous: there is a single thing travelling, so a switch two
+ * tabs away reads as one gesture instead of two states swapping.
+ *
+ * ```tsx
+ * <Tabs defaultValue="account">
+ *   <Tabs.List>
+ *     <Tabs.Trigger value="account">Account</Tabs.Trigger>
+ *     <Tabs.Trigger value="team" badge={<Badge>3</Badge>}>Team</Tabs.Trigger>
+ *   </Tabs.List>
+ *   <Tabs.Content value="account">…</Tabs.Content>
+ * </Tabs>
+ * ```
+ */
 import {
   createContext,
   useCallback,
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
   type ReactNode,
 } from 'react';
-import { Pressable, View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import {
+  Pressable,
+  ScrollView,
+  View,
+  type LayoutChangeEvent,
+  type ViewProps,
+} from 'react-native';
 import Animated, {
   FadeIn,
   useAnimatedStyle,
   useSharedValue,
   withSpring,
 } from 'react-native-reanimated';
+import { tv } from 'tailwind-variants';
 import { Text } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 
 const SPRING = { damping: 24, stiffness: 300, mass: 0.7 } as const;
 
+export type TabsVariant = 'segmented' | 'underline' | 'pill';
+
+const tabsVariants = tv({
+  slots: {
+    list: 'flex-row',
+    indicator: 'absolute left-0',
+    trigger: 'items-center justify-center',
+    label: '',
+  },
+  variants: {
+    variant: {
+      // A raised chip travelling inside a recessed track.
+      segmented: {
+        list: 'rounded-lg bg-muted p-1',
+        indicator: 'bottom-1 top-1 rounded-md bg-popover shadow-sm',
+        trigger: 'rounded-md py-1.5',
+      },
+      // No track at all — the indicator is a rule under the active tab, and
+      // the row sits on a hairline so inactive tabs still have a baseline.
+      underline: {
+        list: 'gap-1 border-b border-border',
+        indicator: '-bottom-px h-0.5 rounded-full bg-foreground',
+        trigger: 'py-2.5',
+      },
+      // Filled chip on the page rather than in a track; the active label
+      // inverts against it.
+      pill: {
+        list: 'gap-1',
+        indicator: 'bottom-0 top-0 rounded-full bg-primary',
+        trigger: 'rounded-full py-2',
+      },
+    },
+    active: {
+      true: { label: 'text-foreground' },
+      false: { label: 'text-muted-foreground' },
+    },
+    disabled: {
+      true: { trigger: 'opacity-[0.44]' },
+    },
+    /** Intrinsic width in a scroller, equal shares when the row is fixed. */
+    scrollable: {
+      true: { trigger: 'px-4' },
+      false: { trigger: 'flex-1' },
+    },
+  },
+  compoundVariants: [
+    { variant: 'pill', active: true, class: { label: 'text-primary-foreground' } },
+  ],
+  defaultVariants: {
+    variant: 'segmented',
+    scrollable: false,
+  },
+});
+
 interface TabLayout {
   x: number;
   width: number;
@@ -29,6 +109,10 @@ interface TabsContextValue {
   setValue: (value: string) => void;
   registerLayout: (value: string, layout: TabLayout) => void;
   layouts: Record<string, TabLayout>;
+  variant: TabsVariant;
+  scrollable: boolean;
+  setScrollable: (scrollable: boolean) => void;
+  keepMounted: boolean;
 }
 
 const TabsContext = createContext<TabsContextValue | null>(null);
@@ -46,6 +130,17 @@ export interface TabsProps extends ViewProps {
   value?: string;
   onValueChange?: (value: string) => void;
   defaultValue: string;
+  /**
+   * `segmented` is a chip travelling inside a recessed track, `underline` is a
+   * rule under the active tab, `pill` is a filled chip on the page.
+   */
+  variant?: TabsVariant;
+  /**
+   * Keep inactive panels mounted and hidden instead of unmounting them, so a
+   * scroll position or a half-filled form survives a switch away and back.
+   * Costs the render of every panel up front.
+   */
+  keepMounted?: boolean;
   children: ReactNode;
 }
 
@@ -54,11 +149,16 @@ function TabsRoot({
   value,
   onValueChange,
   defaultValue,
+  variant = 'segmented',
+  keepMounted = false,
   children,
   ...props
 }: TabsProps) {
   const [internalValue, setInternalValue] = useState(defaultValue);
   const [layouts, setLayouts] = useState<Record<string, TabLayout>>({});
+  // Published by the List rather than the root, because it is the List that
+  // decides whether it scrolls — but the Triggers below it need to know.
+  const [scrollable, setScrollable] = useState(false);
   const isControlled = value !== undefined;
   const resolvedValue = isControlled ? value : internalValue;
 
@@ -81,8 +181,17 @@ function TabsRoot({
   }, []);
 
   const context = useMemo(
-    () => ({ value: resolvedValue, setValue, registerLayout, layouts }),
-    [resolvedValue, setValue, registerLayout, layouts]
+    () => ({
+      value: resolvedValue,
+      setValue,
+      registerLayout,
+      layouts,
+      variant,
+      scrollable,
+      setScrollable,
+      keepMounted,
+    }),
+    [resolvedValue, setValue, registerLayout, layouts, variant, scrollable, keepMounted]
   );
 
   return (
@@ -95,12 +204,13 @@ function TabsRoot({
 }
 
 function TabsIndicator() {
-  const { value, layouts } = useTabs('Tabs.List');
+  const { value, layouts, variant } = useTabs('Tabs.List');
   const x = useSharedValue(0);
   const width = useSharedValue(0);
   const initialized = useSharedValue(0);
 
   const layout = layouts[value];
+  const { indicator } = tabsVariants({ variant });
 
   // In an effect, not the render body: touching a shared value during render
   // is a Reanimated strict-mode violation, and the write can be lost or
@@ -125,41 +235,93 @@ function TabsIndicator() {
     width: width.value,
   }));
 
-  return (
-    <Animated.View
-      style={style}
-      className="absolute bottom-1 top-1 left-0 rounded-md bg-popover shadow-sm"
-    />
-  );
+  return <Animated.View style={style} className={indicator()} />;
 }
 
 export interface TabsListProps extends ViewProps {
   className?: string;
+  /**
+   * Lay the triggers out at their natural widths inside a horizontal scroller
+   * instead of splitting the row between them. For more tabs than fit — which
+   * a fixed row answers by crushing every label.
+   */
+  scrollable?: boolean;
   children: ReactNode;
 }
 
-function TabsList({ className, children, ...props }: TabsListProps) {
-  return (
-    <View
-      accessibilityRole="tablist"
-      className={cn('flex-row rounded-lg bg-muted p-1', className)}
-      {...props}
-    >
+function TabsList({ className, scrollable = false, children, ...props }: TabsListProps) {
+  const { variant, setScrollable, value, layouts } = useTabs('Tabs.List');
+  const { list } = tabsVariants({ variant });
+  const scroller = useRef<ScrollView>(null);
+
+  useEffect(() => {
+    setScrollable(scrollable);
+  }, [scrollable, setScrollable]);
+
+  // Bring the active tab into view when it changes from elsewhere — a
+  // controlled switch, or a swipe on the panel below.
+  const activeLayout = layouts[value];
+  useEffect(() => {
+    if (!scrollable || !activeLayout) return;
+    scroller.current?.scrollTo({
+      // Land the tab a little in from the edge rather than flush against it,
+      // so it does not read as the last one in the row.
+      x: Math.max(activeLayout.x - 24, 0),
+      animated: true,
+    });
+  }, [scrollable, activeLayout?.x, activeLayout]);
+
+  const row = (
+    <View accessibilityRole="tablist" className={cn(list(), className)} {...props}>
       <TabsIndicator />
       {children}
     </View>
   );
+
+  if (!scrollable) return row;
+
+  return (
+    <ScrollView
+      ref={scroller}
+      horizontal
+      showsHorizontalScrollIndicator={false}
+      // The row measures itself, and the indicator is positioned against it,
+      // so the scroller must not stretch it to the viewport width.
+      contentContainerStyle={{ flexGrow: 0 }}
+    >
+      {row}
+    </ScrollView>
+  );
 }
 
 export interface TabsTriggerProps {
   className?: string;
   value: string;
+  /** Rendered before the label. */
+  icon?: ReactNode;
+  /** Rendered after the label — a count, a dot, a status. */
+  badge?: ReactNode;
+  /** Unselectable, dimmed, and announced as disabled. */
+  disabled?: boolean;
   children: ReactNode;
 }
 
-function TabsTrigger({ className, value, children }: TabsTriggerProps) {
+function TabsTrigger({
+  className,
+  value,
+  icon,
+  badge,
+  disabled = false,
+  children,
+}: TabsTriggerProps) {
   const context = useTabs('Tabs.Trigger');
   const active = context.value === value;
+  const slots = tabsVariants({
+    variant: context.variant,
+    active,
+    disabled,
+    scrollable: context.scrollable,
+  });
 
   const handleLayout = useCallback(
     (event: LayoutChangeEvent) => {
@@ -172,22 +334,21 @@ function TabsTrigger({ className, value, children }: TabsTriggerProps) {
   return (
     <Pressable
       accessibilityRole="tab"
-      accessibilityState={{ selected: active }}
+      accessibilityState={{ selected: active, disabled }}
+      disabled={disabled}
       onPress={() => context.setValue(value)}
       onLayout={handleLayout}
-      className={cn('flex-1 items-center justify-center rounded-md py-1.5', className)}
+      className={cn(slots.trigger(), (icon || badge) && 'flex-row gap-1.5', className)}
     >
+      {icon}
       {typeof children === 'string' ? (
-        <Text
-          size="sm"
-          weight="medium"
-          className={active ? 'text-foreground' : 'text-muted-foreground'}
-        >
+        <Text size="sm" weight="medium" className={slots.label()}>
           {children}
         </Text>
       ) : (
         children
       )}
+      {badge}
     </Pressable>
   );
 }
@@ -198,12 +359,31 @@ export interface TabsContentProps extends ViewProps {
   children: ReactNode;
 }
 
-function TabsContent({ className, value, children, ...props }: TabsContentProps) {
+function TabsContent({ className, value, children, style, ...props }: TabsContentProps) {
   const context = useTabs('Tabs.Content');
-  if (context.value !== value) return null;
+  const active = context.value === value;
 
+  if (!active && !context.keepMounted) return null;
+
+  /*
+   * Hidden rather than unmounted under `keepMounted`, and hidden thoroughly:
+   * `display: none` takes it out of layout, and the accessibility props take
+   * it out of the reading order too. A screen reader walking through three
+   * panels of a tab set it cannot see is worse than no tabs at all.
+   */
   return (
-    <Animated.View entering={FadeIn.duration(150)} className={className} {...props}>
+    <Animated.View
+      // Only worth animating when the panel is genuinely arriving. A kept
+      // panel is already there; fading it in every time it is revealed would
+      // undo the point of keeping it.
+      entering={context.keepMounted ? undefined : FadeIn.duration(150)}
+      style={[!active && { display: 'none' }, style]}
+      pointerEvents={active ? 'auto' : 'none'}
+      accessibilityElementsHidden={!active}
+      importantForAccessibility={active ? 'auto' : 'no-hide-descendants'}
+      className={className}
+      {...props}
+    >
       {children}
     </Animated.View>
   );