panelui-native 0.46.0 → 0.51.1

package/src/components/swipe/index.tsx

@@ -27,6 +27,11 @@
  *
  * Everything that moves runs on the UI thread. A row being dragged does not
  * re-render — the only React work in a swipe is the callback at the end of it.
+ *
+ * Rows in a `Swipe.Group` close each other, so only one of them is ever open.
+ * That is the behaviour of every list on the phone that has this gesture, and
+ * a row cannot arrange it alone: it knows when it opens and has no way to hear
+ * that a sibling did.
  */
 import {
   Children,
@@ -36,6 +41,7 @@ import {
   isValidElement,
   useCallback,
   useContext,
+  useEffect,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -96,6 +102,131 @@ interface SwipeContextValue {
 
 const SwipeContext = createContext<SwipeContextValue | null>(null);
 
+/* -------------------------------------------------------------------------- */
+/* Group                                                                      */
+/* -------------------------------------------------------------------------- */
+
+interface SwipeGroupContextValue {
+  /** Take a slot in the group. Returns the function that gives it back. */
+  join: (row: SwipeGroupMember) => () => void;
+  /** Say that this row has opened, so every other one can put itself away. */
+  opened: (row: SwipeGroupMember) => void;
+  /** Shut every row in the group. */
+  closeAll: () => void;
+}
+
+interface SwipeGroupMember {
+  close: () => void;
+}
+
+const SwipeGroupContext = createContext<SwipeGroupContextValue | null>(null);
+
+export interface SwipeGroupProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+  /**
+   * Close the other rows when one opens. On by default — that is the whole
+   * reason to reach for a group. Turning it off keeps the container and the
+   * `useSwipeGroup` handle while letting several rows stand open at once.
+   */
+  exclusive?: boolean;
+}
+
+/**
+ * Several rows that agree only one of them is open at a time.
+ *
+ * Every list of swipeable rows wants this, and every list has to be told: a
+ * row knows when it opens but has no way to learn that a sibling did, so
+ * without something above them a list ends up with three rows standing open
+ * and a screen that reads as broken. The mail, message and reminder lists on
+ * a phone all behave this way, and a list that does not is the odd one out.
+ *
+ * ```tsx
+ * <Swipe.Group>
+ *   {rows.map((row) => (
+ *     <Swipe key={row.id}>
+ *       <Swipe.End>
+ *         <Swipe.Action label="Delete" color="destructive" onPress={…} />
+ *       </Swipe.End>
+ *       <Item>…</Item>
+ *     </Swipe>
+ *   ))}
+ * </Swipe.Group>
+ * ```
+ *
+ * The rows register themselves rather than being found by inspecting children,
+ * so a row nested inside anything at all still belongs — wrapped in an
+ * `Item.Group`, produced by a `map`, rendered by a component of your own. The
+ * alternative, walking the tree for `Swipe` elements, only ever works for the
+ * one arrangement it was written against.
+ *
+ * Nothing here re-renders. The registry is a ref and closing a sibling writes
+ * to that row's shared value, so opening a row costs the springs it starts and
+ * no React work at all.
+ */
+const SwipeGroup = forwardRef<View, SwipeGroupProps>(
+  ({ className, children, exclusive = true, ...props }, ref) => {
+    /*
+     * A ref rather than state: membership changes as rows mount and unmount,
+     * and rendering the whole list again because one row arrived would undo
+     * the point of a component that never re-renders while it is dragged.
+     */
+    const members = useRef(new Set<SwipeGroupMember>());
+
+    const context = useMemo<SwipeGroupContextValue>(
+      () => ({
+        join: (row) => {
+          members.current.add(row);
+          return () => {
+            members.current.delete(row);
+          };
+        },
+        opened: (row) => {
+          if (!exclusive) return;
+          for (const other of members.current) {
+            if (other !== row) other.close();
+          }
+        },
+        closeAll: () => {
+          for (const row of members.current) row.close();
+        },
+      }),
+      [exclusive]
+    );
+
+    return (
+      <SwipeGroupContext.Provider value={context}>
+        <View ref={ref} className={className} {...props}>
+          {children}
+        </View>
+      </SwipeGroupContext.Provider>
+    );
+  }
+);
+SwipeGroup.displayName = 'Swipe.Group';
+
+/**
+ * Shut every row in the enclosing `Swipe.Group`.
+ *
+ * The one thing a group knows that a single row cannot: a list that scrolls,
+ * navigates away, or has just deleted the row that was open wants all of them
+ * put back, and holding a ref to each row to do it by hand is bookkeeping the
+ * group is already doing.
+ *
+ * ```tsx
+ * const { closeAll } = useSwipeGroup();
+ * <ScrollView onScrollBeginDrag={closeAll}>…</ScrollView>
+ * ```
+ *
+ * Outside a group it is inert rather than an error, so a row that is sometimes
+ * grouped and sometimes not does not need two versions of its parent.
+ */
+export function useSwipeGroup(): { closeAll: () => void } {
+  const group = useContext(SwipeGroupContext);
+  const closeAll = useCallback(() => group?.closeAll(), [group]);
+  return { closeAll };
+}
+
 /* -------------------------------------------------------------------------- */
 /* Action                                                                     */
 /* -------------------------------------------------------------------------- */
@@ -440,6 +571,35 @@ const SwipeRoot = forwardRef<SwipeHandle, SwipeProps>(
       reportOpen(null);
     }, [offset, reportOpen]);
 
+    /*
+     * Membership in a `Swipe.Group`, if there is one above this row.
+     *
+     * The registered member is a stable object rather than the `close`
+     * function itself, because `close` changes identity whenever
+     * `onOpenChange` does and the group would then be holding a stale entry
+     * alongside a live one. The object never changes; what it closes is read
+     * off a ref at the moment it is asked.
+     */
+    const group = useContext(SwipeGroupContext);
+    const closeRef = useRef(close);
+    closeRef.current = close;
+    const member = useRef<SwipeGroupMember>({ close: () => closeRef.current() }).current;
+
+    useEffect(() => group?.join(member), [group, member]);
+
+    /**
+     * Told when this row settles open, so the group can put its siblings away.
+     * A row closing says nothing — the others are already closed, and telling
+     * them so would be a round of work per settle for no change.
+     */
+    const announce = useCallback(
+      (side: SwipeOpenSide) => {
+        reportOpen(side);
+        if (side !== null) group?.opened(member);
+      },
+      [reportOpen, group, member]
+    );
+
     useImperativeHandle(
       ref,
       () => ({
@@ -447,11 +607,11 @@ const SwipeRoot = forwardRef<SwipeHandle, SwipeProps>(
           const width = side === 'start' ? startWidth.value : endWidth.value;
           if (width === 0) return;
           offset.value = withSpring(side === 'start' ? width : -width, SPRING);
-          reportOpen(side);
+          announce(side);
         },
         close,
       }),
-      [offset, startWidth, endWidth, reportOpen, close]
+      [offset, startWidth, endWidth, announce, close]
     );
 
     /**
@@ -541,7 +701,7 @@ const SwipeRoot = forwardRef<SwipeHandle, SwipeProps>(
 
             if (projected > limit * OPEN_RATIO) {
               offset.value = withSpring(toStart ? limit : -limit, SPRING);
-              runOnJS(reportOpen)(side);
+              runOnJS(announce)(side);
             } else {
               offset.value = withSpring(0, SPRING);
               runOnJS(reportOpen)(null);
@@ -562,6 +722,7 @@ const SwipeRoot = forwardRef<SwipeHandle, SwipeProps>(
         fire,
         tick,
         reportOpen,
+        announce,
       ]
     );
 
@@ -681,6 +842,7 @@ const SwipeRoot = forwardRef<SwipeHandle, SwipeProps>(
 SwipeRoot.displayName = 'Swipe';
 
 export const Swipe = Object.assign(SwipeRoot, {
+  Group: SwipeGroup,
   Start: SwipeStart,
   End: SwipeEnd,
   Action: SwipeAction,

package/src/components/tabs/index.tsx

@@ -36,6 +36,7 @@ import {
   type ReactNode,
 } from 'react';
 import {
+  Platform,
   Pressable,
   ScrollView,
   View,
@@ -92,8 +93,18 @@ const SWIPE_RESISTANCE_AT_END = 0.16;
  * card: a panel on its way out is on its way out, and the one arriving comes
  * back up through the same fade. The two together read as a dissolve carried
  * by the movement, rather than as a gap between two slides.
+ *
+ * **iOS only, and that is not a compromise.** A transform is a property of the
+ * layer the panel is drawn into, so moving it costs nothing per frame however
+ * much is inside it. An opacity that changes every frame is not: on Android the
+ * panel's view group has no offscreen buffer to fade, so the alpha is pushed
+ * down into its children and the whole visible subtree is re-drawn on every
+ * frame of the drag. Behind a list that is thirty rows of text and images,
+ * which is what a tab panel usually is, that is the difference between a swipe
+ * that tracks the finger and one that stutters. iOS fades the layer itself and
+ * is unaffected.
  */
-const SWIPE_FADE = 0.75;
+const SWIPE_FADE = Platform.OS === 'ios' ? 0.75 : 0;
 
 /**
  * How far off its resting place a panel arriving by a *press* starts, as a
@@ -101,7 +112,7 @@ const SWIPE_FADE = 0.75;
  *
  * A press has no finger travel to continue from, so it is given a throw of its
  * own. A swipe does not use this: the panel it hands over to picks up exactly
- * where the outgoing one was let go — see `setValue`.
+ * one width from wherever the outgoing one has travelled to — see `setValue`.
  */
 const SWIPE_ENTER = 0.3;
 
@@ -291,6 +302,15 @@ export interface TabsProps extends ViewProps {
    * 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.
+   *
+   * **It does not change what is mounted.** Only `keepMounted` decides that,
+   * with or without this — a swipe animates between two panels of which one is
+   * being unmounted and the other mounted for the first time, exactly as a
+   * press does. What it does change is that the mount now happens *while
+   * something is moving*, so a panel that is slow to build stops being a pause
+   * before it appears and starts being a stutter in the movement. If a swipe
+   * feels heavier than a press on the same tab set, the panel is expensive to
+   * mount; `keepMounted` is the answer, not turning this off.
    */
   swipeable?: boolean;
   children: ReactNode;
@@ -319,8 +339,26 @@ function TabsRoot({
   const isControlled = value !== undefined;
   const resolvedValue = isControlled ? value : internalValue;
 
+  /*
+   * The two things `setValue` reads that change on every switch, held where
+   * reading them does not make it a new function.
+   *
+   * With them in the dependency list, changing tab produced a new `setValue`,
+   * therefore a new context, therefore a new `step`, therefore a new pan
+   * gesture — which detaches and re-attaches the native recogniser on the same
+   * commit that mounts the arriving panel's contents. The busiest frame of the
+   * interaction was doing the one piece of work that had no reason to be there.
+   */
+  const tabsRef = useRef(tabs);
+  tabsRef.current = tabs;
+  const valueRef = useRef(resolvedValue);
+  valueRef.current = resolvedValue;
+
   const setValue = useCallback(
     (next: string, handover?: SwipeHandover) => {
+      const tabs = tabsRef.current;
+      const resolvedValue = valueRef.current;
+
       /*
        * 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
@@ -338,11 +376,13 @@ function TabsRoot({
           if (handover) {
             /*
              * A swipe hands over mid-movement, so the arriving panel starts a
-             * whole panel's width from wherever the outgoing one was let go —
+             * whole panel's width from wherever the outgoing one has got to —
              * which is where it *would* have been all along, had both been
-             * mounted. Adding to the displacement rather than replacing it is
-             * the entire difference between one continuous movement and a jump
-             * at the moment the finger lifts.
+             * mounted. Read live rather than captured, because the outgoing
+             * panel is still travelling while this runs: adding to the current
+             * displacement rather than replacing it is the whole difference
+             * between one continuous movement and a jump at the moment the
+             * arriving panel finishes mounting.
              */
             swipeOffset.value += direction * sign * panelWidth.value;
             swipeOffset.value = withSpring(0, {
@@ -361,16 +401,7 @@ function TabsRoot({
       if (!isControlled) setInternalValue(next);
       onValueChange?.(next);
     },
-    [
-      isControlled,
-      onValueChange,
-      swipeable,
-      tabs,
-      resolvedValue,
-      sign,
-      swipeOffset,
-      panelWidth,
-    ]
+    [isControlled, onValueChange, swipeable, sign, swipeOffset, panelWidth]
   );
 
   const registerLayout = useCallback((tab: string, layout: TabLayout) => {
@@ -781,13 +812,25 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
     count.value = tabs.length;
   }, [position, tabs.length, index, count]);
 
+  /*
+   * Same reason as `setValue` on the root: `step` is reached through the pan
+   * gesture, and a `step` that changes identity on every switch rebuilds the
+   * gesture on every switch. The two facts it needs are read at call time
+   * instead, which is when they are wanted anyway.
+   */
+  const tabsRef = useRef(tabs);
+  tabsRef.current = tabs;
+  const valueRef = useRef(value);
+  valueRef.current = value;
+
   const step = useCallback(
     (delta: number, velocity: number) => {
-      const from = tabs.indexOf(value);
-      const next = tabs[from + delta];
+      const list = tabsRef.current;
+      const from = list.indexOf(valueRef.current);
+      const next = list[from + delta];
       if (next) setValue(next, { velocity });
     },
-    [tabs, value, setValue]
+    [setValue]
   );
 
   const pan = useMemo(
@@ -828,14 +871,31 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
             // 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 carries the
-            // displacement across to the arriving panel, and springing to rest
-            // first would undo it a frame before it happens.
-            runOnJS(step)(
-              fast ? (speed < 0 ? 1 : -1) : travel < 0 ? 1 : -1,
-              event.velocityX
-            );
+            const delta = fast ? (speed < 0 ? 1 : -1) : travel < 0 ? 1 : -1;
+
+            /*
+             * The outgoing panel carries on off the edge on the UI thread,
+             * immediately, rather than waiting to be told what happened.
+             *
+             * It used to hold wherever the finger left it until `setValue`
+             * landed — which is fine when React commits in a frame, and is a
+             * visible freeze when the arriving panel is expensive to mount, a
+             * list of any size being the usual case. The panel appeared to
+             * stick to the screen for exactly as long as the JS thread was
+             * busy, which reads as the swipe having dropped the gesture.
+             *
+             * `setValue` still places the arriving panel *relative* to this
+             * one, reading the offset live at commit time, so continuing the
+             * movement here does not desynchronise the handover: the panel
+             * that arrives is one width from wherever this one has got to,
+             * whenever that turns out to be.
+             */
+            offset.value = withSpring(-delta * sign * width.value, {
+              ...ENTER_SPRING,
+              velocity: event.velocityX,
+            });
+
+            runOnJS(step)(delta, event.velocityX);
             return;
           }
 
@@ -853,6 +913,11 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
   );
 
   const followStyle = useAnimatedStyle(() => {
+    // No `opacity` key at all when there is no fade, rather than a constant 1.
+    // Declaring it would still mark the property as animated and hand the view
+    // an alpha to composite every frame — the cost this is avoiding.
+    if (!SWIPE_FADE) return { transform: [{ translateX: offset.value }] };
+
     const span = width.value || 1;
     const travelled = Math.min(1, Math.abs(offset.value) / span);
     return {
@@ -893,7 +958,14 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
         const measured = event.nativeEvent.layout.width;
         if (measured > 0) width.value = measured;
       }}
-      style={[!active && { display: 'none' }, swipeable && followStyle, style]}
+      /*
+       * The follow style goes on the panel that is moving, and only that one.
+       * Under `keepMounted` every other panel is `display: none` and cannot be
+       * seen to move — but an animated style still subscribes them all to the
+       * offset, so a five-tab set ran five mappers per frame to reposition four
+       * views nobody was looking at.
+       */
+      style={[!active && { display: 'none' }, swipeable && active && followStyle, style]}
       pointerEvents={active ? 'auto' : 'none'}
       accessibilityElementsHidden={!active}
       importantForAccessibility={active ? 'auto' : 'no-hide-descendants'}

package/src/components/time-picker/index.tsx

@@ -116,6 +116,15 @@ const TICK_SPACING = 12;
 /** Settles the clock hands after a pick. Slow enough to be followed by eye. */
 const HAND_SPRING = { damping: 16, stiffness: 140, mass: 0.7 } as const;
 
+/**
+ * How loudly the ruler face states the time it is on.
+ *
+ * `default` is the big centred number, right when the scale is the only thing
+ * on the panel. `compact` steps it down to sit under something that outranks
+ * it, and `none` drops it for a caller that writes the time itself.
+ */
+export type TimePickerReadout = 'default' | 'compact' | 'none';
+
 const timePickerVariants = tv({
   slots: {
     panel: 'gap-3',
@@ -128,10 +137,20 @@ const timePickerVariants = tv({
     row: 'items-center justify-center',
     rowLabel: 'text-lg tabular-nums text-foreground',
     rowLabelSelected: 'font-semibold text-primary',
-    readout: 'text-center text-4xl font-semibold tabular-nums text-foreground',
+    readout: 'text-center font-semibold tabular-nums text-foreground',
     clock: 'flex-row items-center gap-4',
     footer: 'flex-row justify-end gap-2',
   },
+  variants: {
+    readout: {
+      default: { readout: 'text-4xl' },
+      compact: { readout: 'text-xl' },
+      none: {},
+    },
+  },
+  defaultVariants: {
+    readout: 'default',
+  },
 });
 
 /* -------------------------------------------------------------------------- */
@@ -296,6 +315,8 @@ interface FaceProps {
   minuteStep: number;
   locale?: string;
   disabled?: boolean;
+  /** Ruler face only — the other two never draw a number of their own. */
+  readout?: TimePickerReadout;
 }
 
 function WheelFace({
@@ -573,8 +594,9 @@ function RulerFace({
   minuteStep,
   locale,
   disabled,
+  readout = 'default',
 }: FaceProps) {
-  const slots = timePickerVariants();
+  const slots = timePickerVariants({ readout });
   const ref = useRef<ScrollView>(null);
   const times = useMemo(() => timesOfDay(minuteStep), [minuteStep]);
   const index = Math.min(
@@ -638,10 +660,12 @@ function RulerFace({
   );
 
   return (
-    <View className="gap-4">
-      <Text className={slots.readout()}>
-        {formatTime(value, { hourCycle, locale })}
-      </Text>
+    <View className={readout === 'none' ? undefined : 'gap-4'}>
+      {readout === 'none' ? null : (
+        <Text className={slots.readout()}>
+          {formatTime(value, { hourCycle, locale })}
+        </Text>
+      )}
 
       <View className="relative h-14 justify-center" onLayout={onLayout}>
         <ScrollView
@@ -768,6 +792,16 @@ export interface TimePickerProps {
   format?: (value: TimeValue) => string;
   /** BCP 47 tag for the time's text and the meridiem labels. */
   locale?: string;
+  /**
+   * How loudly the `ruler` face states the time it is on. The other two faces
+   * spell the time out in their own columns and hands, and ignore this.
+   *
+   * The big centred number is right when the scale is the only thing on the
+   * panel. Under something that outranks it — a calendar, a form row — it is
+   * the largest text on screen for the smaller half of the answer, so step it
+   * down with `compact` or take it over yourself with `none`.
+   */
+  readout?: TimePickerReadout;
   /** Stop the trigger opening it, and the faces from being scrolled. */
   disabled?: boolean;
   className?: string;
@@ -803,6 +837,7 @@ function TimePickerRoot({
   placeholder = DEFAULT_PLACEHOLDER,
   format,
   locale,
+  readout = 'default',
   disabled = false,
   className,
   children,
@@ -867,6 +902,7 @@ function TimePickerRoot({
     minuteStep: step,
     locale,
     disabled,
+    readout,
   };
 
   if (presentation === 'inline') {