panelui-native 0.40.0 → 0.43.0

package/src/components/tabs/index.tsx

@@ -33,18 +33,62 @@ import {
   type LayoutChangeEvent,
   type ViewProps,
 } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
   FadeIn,
+  runOnJS,
   useAnimatedStyle,
   useSharedValue,
   withSpring,
+  type SharedValue,
 } from 'react-native-reanimated';
 import { tv } from 'tailwind-variants';
+import { useDirectionSign } from '../../hooks/use-direction';
 import { Text, textChildren } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 
 const SPRING = { damping: 24, stiffness: 300, mass: 0.7 } as const;
 
+/**
+ * How far sideways a finger must travel before the panel takes the gesture
+ * from whatever is scrolling above it, and how far up or down before it gives
+ * up on it. The window between them is what lets a swipe start inside a
+ * vertically scrolling panel without either gesture stealing the other.
+ */
+const SWIPE_ACTIVATE_X = 12;
+const SWIPE_FAIL_Y = 8;
+
+/** A swipe past this share of the panel's width changes tab on release. */
+const SWIPE_DISTANCE_RATIO = 0.25;
+/** …or past this speed, however short it was. */
+const SWIPE_VELOCITY = 500;
+
+/**
+ * How much of the finger's travel the panel actually follows.
+ *
+ * Not all of it: a panel that tracked one-to-one would look like a pager that
+ * is about to reveal the next panel, and there is nothing behind it to reveal
+ * — the panels are separate views, only one of which is mounted. A third of
+ * the distance is enough to say the gesture was received.
+ */
+const SWIPE_FOLLOW = 0.32;
+/** …and a fraction of that again at the ends, where there is nowhere to go. */
+const SWIPE_FOLLOW_AT_END = 0.1;
+
+/**
+ * How far off its resting place the arriving panel starts, as a share of the
+ * panel's width.
+ *
+ * A swipe that commits should not look like a swipe that was cancelled. Both
+ * end with a panel settling at rest, and the only thing that distinguishes
+ * them is which side it settled *from* — so the incoming panel picks up
+ * roughly where the outgoing one was let go, on the far side, and travels in.
+ */
+const SWIPE_ENTER = 0.3;
+
+/** The arriving panel is springier than the one being dragged back into place. */
+const ENTER_SPRING = { damping: 22, stiffness: 240, mass: 0.6 } as const;
+
 export type TabsVariant = 'segmented' | 'underline' | 'pill';
 
 const tabsVariants = tv({
@@ -109,10 +153,33 @@ interface TabsContextValue {
   setValue: (value: string) => void;
   registerLayout: (value: string, layout: TabLayout) => void;
   layouts: Record<string, TabLayout>;
+  /**
+   * Every tab in the order it was declared, which is the order a swipe moves
+   * through them. Kept separately from `layouts` because that is a map keyed
+   * by value and its order is whatever the layout pass happened to produce —
+   * and because under RTL the leftmost trigger is the last one, so a position
+   * cannot stand in for a place in the sequence either.
+   */
+  tabs: string[];
+  registerTab: (value: string) => void;
+  unregisterTab: (value: string) => void;
   variant: TabsVariant;
   scrollable: boolean;
   setScrollable: (scrollable: boolean) => void;
   keepMounted: boolean;
+  swipeable: boolean;
+  /**
+   * How far the visible panel is displaced from its resting place, in points.
+   *
+   * It lives on the root rather than on a panel because the outgoing and
+   * incoming panels are different views, and a value that belonged to either
+   * of them would be destroyed at the moment of the handover. Shared, the
+   * displacement survives it: the panel being let go and the panel arriving
+   * are one continuous movement, drawn by two views in turn.
+   */
+  swipeOffset: SharedValue<number>;
+  /** The visible panel's measured width, which the throw above is a share of. */
+  panelWidth: SharedValue<number>;
 }
 
 const TabsContext = createContext<TabsContextValue | null>(null);
@@ -141,6 +208,16 @@ export interface TabsProps extends ViewProps {
    * Costs the render of every panel up front.
    */
   keepMounted?: boolean;
+  /**
+   * Move between tabs by dragging sideways on the panel, as well as by
+   * pressing the triggers.
+   *
+   * Off by default, because a panel is allowed to contain something that
+   * already wants a horizontal drag — a carousel, a slider, a row that swipes
+   * open — and the two cannot both have it. Turn it on for panels of ordinary
+   * scrolling content, where it is the gesture people try first.
+   */
+  swipeable?: boolean;
   children: ReactNode;
 }
 
@@ -151,11 +228,16 @@ function TabsRoot({
   defaultValue,
   variant = 'segmented',
   keepMounted = false,
+  swipeable = false,
   children,
   ...props
 }: TabsProps) {
   const [internalValue, setInternalValue] = useState(defaultValue);
   const [layouts, setLayouts] = useState<Record<string, TabLayout>>({});
+  const [tabs, setTabs] = useState<string[]>([]);
+  const swipeOffset = useSharedValue(0);
+  const panelWidth = useSharedValue(0);
+  const sign = useDirectionSign();
   // 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);
@@ -164,10 +246,37 @@ function TabsRoot({
 
   const setValue = useCallback(
     (next: string) => {
+      /*
+       * The arriving panel starts on the side it is arriving from, and travels
+       * in. Done here rather than in the panel because only the root knows
+       * both the tab being left and the tab being gone to — a panel knows
+       * which one it is, not which one it replaced — and because a tab changed
+       * by pressing a trigger deserves the same movement as one changed by
+       * swiping to it. Without it the two read as different features.
+       */
+      if (swipeable) {
+        const from = tabs.indexOf(resolvedValue);
+        const to = tabs.indexOf(next);
+        if (from !== -1 && to !== -1 && from !== to) {
+          swipeOffset.value =
+            (to > from ? 1 : -1) * sign * panelWidth.value * SWIPE_ENTER;
+          swipeOffset.value = withSpring(0, ENTER_SPRING);
+        }
+      }
+
       if (!isControlled) setInternalValue(next);
       onValueChange?.(next);
     },
-    [isControlled, onValueChange]
+    [
+      isControlled,
+      onValueChange,
+      swipeable,
+      tabs,
+      resolvedValue,
+      sign,
+      swipeOffset,
+      panelWidth,
+    ]
   );
 
   const registerLayout = useCallback((tab: string, layout: TabLayout) => {
@@ -180,18 +289,50 @@ function TabsRoot({
     });
   }, []);
 
+  /*
+   * Triggers add themselves on mount, so the order is React's child order —
+   * the order they are written in, which is the order they are read in.
+   */
+  const registerTab = useCallback((tab: string) => {
+    setTabs((current) => (current.includes(tab) ? current : [...current, tab]));
+  }, []);
+
+  const unregisterTab = useCallback((tab: string) => {
+    setTabs((current) => current.filter((entry) => entry !== tab));
+  }, []);
+
   const context = useMemo(
     () => ({
       value: resolvedValue,
       setValue,
       registerLayout,
       layouts,
+      tabs,
+      registerTab,
+      unregisterTab,
       variant,
       scrollable,
       setScrollable,
       keepMounted,
+      swipeable,
+      swipeOffset,
+      panelWidth,
     }),
-    [resolvedValue, setValue, registerLayout, layouts, variant, scrollable, keepMounted]
+    [
+      resolvedValue,
+      setValue,
+      registerLayout,
+      layouts,
+      tabs,
+      registerTab,
+      unregisterTab,
+      variant,
+      scrollable,
+      keepMounted,
+      swipeable,
+      swipeOffset,
+      panelWidth,
+    ]
   );
 
   return (
@@ -331,6 +472,15 @@ function TabsTrigger({
     [context, value]
   );
 
+  // Separate from the layout registration above, and earlier than it: a swipe
+  // needs to know the sequence, which is known at mount, not the positions,
+  // which are not known until the row has been laid out.
+  const { registerTab, unregisterTab } = context;
+  useEffect(() => {
+    registerTab(value);
+    return () => unregisterTab(value);
+  }, [value, registerTab, unregisterTab]);
+
   return (
     <Pressable
       accessibilityRole="tab"
@@ -360,6 +510,86 @@ export interface TabsContentProps extends ViewProps {
 function TabsContent({ className, value, children, style, ...props }: TabsContentProps) {
   const context = useTabs('Tabs.Content');
   const active = context.value === value;
+  const {
+    tabs,
+    setValue,
+    swipeable,
+    swipeOffset: offset,
+    panelWidth: width,
+  } = context;
+  const sign = useDirectionSign();
+  // Read on the UI thread while the finger is down, so the resistance at the
+  // ends is known without a round trip to JavaScript.
+  const index = useSharedValue(0);
+  const count = useSharedValue(0);
+
+  const position = tabs.indexOf(value);
+  useEffect(() => {
+    index.value = position;
+    count.value = tabs.length;
+  }, [position, tabs.length, index, count]);
+
+  const step = useCallback(
+    (delta: number) => {
+      const from = tabs.indexOf(value);
+      const next = tabs[from + delta];
+      if (next) setValue(next);
+    },
+    [tabs, value, setValue]
+  );
+
+  const pan = useMemo(
+    () =>
+      Gesture.Pan()
+        // Sideways past the threshold takes the gesture; any real vertical
+        // travel hands it back, so a panel that scrolls still scrolls.
+        .activeOffsetX([-SWIPE_ACTIVATE_X, SWIPE_ACTIVATE_X])
+        .failOffsetY([-SWIPE_FAIL_Y, SWIPE_FAIL_Y])
+        .onUpdate((event) => {
+          // Positive is "towards the previous tab" in reading order, which is
+          // rightwards under LTR and leftwards under RTL.
+          const travel = event.translationX * sign;
+          const atEnd =
+            (travel > 0 && index.value === 0) ||
+            (travel < 0 && index.value >= count.value - 1);
+          offset.value =
+            event.translationX * (atEnd ? SWIPE_FOLLOW_AT_END : SWIPE_FOLLOW);
+        })
+        .onEnd((event) => {
+          const travel = event.translationX * sign;
+          const speed = event.velocityX * sign;
+          const far = Math.abs(travel) > width.value * SWIPE_DISTANCE_RATIO;
+          const fast = Math.abs(speed) > SWIPE_VELOCITY;
+          const atEnd =
+            (travel > 0 && index.value === 0) ||
+            (travel < 0 && index.value >= count.value - 1);
+
+          if ((far || fast) && !atEnd) {
+            // Distance and speed can disagree — a flick back the way it came
+            // reads as a cancel — so the direction comes from whichever of the
+            // two crossed its threshold, speed first.
+            //
+            // No spring back to zero here: `setValue` on the root throws the
+            // displacement across to the side the next panel arrives from, and
+            // springing to rest first would undo it a frame before it happens.
+            runOnJS(step)(fast ? (speed < 0 ? 1 : -1) : travel < 0 ? 1 : -1);
+            return;
+          }
+
+          // Nothing changed hands, so this panel simply comes back.
+          offset.value = withSpring(0, SPRING);
+        })
+        .onFinalize((_event, success) => {
+          // A cancelled gesture never reaches `onEnd`, and would otherwise
+          // leave the panel wherever the finger abandoned it.
+          if (!success) offset.value = withSpring(0, SPRING);
+        }),
+    [sign, step, offset, width, index, count]
+  );
+
+  const followStyle = useAnimatedStyle(() => ({
+    transform: [{ translateX: offset.value }],
+  }));
 
   if (!active && !context.keepMounted) return null;
 
@@ -369,13 +599,31 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
    * 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 (
+  const panel = (
     <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]}
+      /*
+       * 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.
+       *
+       * And never alongside the swipe: an entering layout animation owns the
+       * view's style for the length of it and will overwrite an animated style
+       * touching the same view, so the fade would eat the slide. When panels
+       * move, the movement is the entrance.
+       */
+      entering={context.keepMounted || swipeable ? undefined : FadeIn.duration(150)}
+      onLayout={(event: LayoutChangeEvent) => {
+        // The thresholds are a share of the panel, not of the screen: a tab
+        // set inside a card is narrower than the window, and a quarter of the
+        // window would be most of the way across it.
+        //
+        // Zero is ignored. Every panel reports into the same value, and a
+        // kept-mounted one is `display: none` — it measures as nothing, and
+        // letting it say so would leave the visible panel with no width.
+        const measured = event.nativeEvent.layout.width;
+        if (measured > 0) width.value = measured;
+      }}
+      style={[!active && { display: 'none' }, swipeable && followStyle, style]}
       pointerEvents={active ? 'auto' : 'none'}
       accessibilityElementsHidden={!active}
       importantForAccessibility={active ? 'auto' : 'no-hide-descendants'}
@@ -385,6 +633,13 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
       {textChildren(children)}
     </Animated.View>
   );
+
+  // Only the visible panel carries the gesture. A kept-mounted panel is
+  // `display: none` and takes no touches anyway, but attaching a detector to
+  // each of them would put several competing recognisers in the same tree.
+  if (!swipeable || !active) return panel;
+
+  return <GestureDetector gesture={pan}>{panel}</GestureDetector>;
 }
 
 export const Tabs = Object.assign(TabsRoot, {