panelui-native 0.49.0 → 0.53.0

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

@@ -140,6 +140,16 @@ const MEASURE_WIDTH = 400;
 
 export type TabsVariant = 'segmented' | 'underline' | 'pill' | 'expanding';
 
+/**
+ * How much of an inactive panel survives a switch away from it.
+ *
+ * `false` unmounts it. `true` keeps it mounted but takes it out of layout, so
+ * it costs nothing to have around. `'measured'` keeps it laid out at full size
+ * as well — the expensive option, and the only one a child that sizes itself
+ * from its parent can be built inside while it is hidden.
+ */
+export type TabsKeepMounted = boolean | 'measured';
+
 const tabsVariants = tv({
   slots: {
     list: 'flex-row',
@@ -246,7 +256,7 @@ interface TabsContextValue {
   variant: TabsVariant;
   scrollable: boolean;
   setScrollable: (scrollable: boolean) => void;
-  keepMounted: boolean;
+  keepMounted: TabsKeepMounted;
   swipeable: boolean;
   /**
    * How far the visible panel is displaced from its resting place, in points.
@@ -292,8 +302,29 @@ export interface TabsProps extends ViewProps {
    * 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.
+   *
+   * `true` hides a kept panel with `display: none`, which also takes it out of
+   * layout: it is mounted, but it has no size. That is what makes it cheap, and
+   * it is enough for a panel whose content sizes itself — a column of views, a
+   * form, a `ScrollView` of known children.
+   *
+   * It is *not* enough for a child that decides what to render by measuring the
+   * space it has been given. A virtualised list asks its parent how tall it is
+   * and fills that many rows; asked inside a panel of zero height it answers
+   * zero rows, and the whole first render still lands on the frame the tab
+   * becomes visible — the stall this flag looks like it should have avoided.
+   *
+   * `'measured'` is for that case. A kept panel stays laid out at the full size
+   * of the tab set, and is hidden by not being drawn rather than by being
+   * removed from layout: a list inside it measures, renders its rows and
+   * settles while it is still hidden, so becoming visible costs nothing.
+   *
+   * The trade is real and is why it is not the default — every kept panel lays
+   * out and draws, up front and on every size change, so a five-tab set builds
+   * five panels' worth of rows to show one. Reach for it when a panel is slow
+   * to appear and its content is virtualised; leave it at `true` otherwise.
    */
-  keepMounted?: boolean;
+  keepMounted?: TabsKeepMounted;
   /**
    * Move between tabs by dragging sideways on the panel, as well as by
    * pressing the triggers.
@@ -310,7 +341,9 @@ export interface TabsProps extends ViewProps {
    * 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.
+   * mount — and the answer is whichever `keepMounted` actually keeps its
+   * content built, which for a virtualised list is `'measured'` rather than
+   * `true`. Turning this off hides the cost rather than removing it.
    */
   swipeable?: boolean;
   children: ReactNode;
@@ -928,11 +961,41 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
 
   if (!active && !context.keepMounted) return null;
 
+  /*
+   * Under `keepMounted='measured'` a hidden panel keeps its size instead of
+   * losing it. It is taken out of the flow and stretched over the tab set, so
+   * it is laid out at the same size as the visible panel without contributing
+   * its height to the parent, and it is hidden by being transparent rather
+   * than by `display: none`.
+   *
+   * That distinction is the whole point: `display: none` lays a panel out at
+   * zero size, and a child that sizes itself from its parent — a virtualised
+   * list deciding how many rows to render — renders nothing at all inside one.
+   * Given a real size while still hidden, it builds its rows now rather than on
+   * the frame the tab is switched to.
+   *
+   * `opacity: 0` is set once and never animated, so it costs a composite and
+   * not a per-frame redraw; the negative `zIndex` keeps it behind the visible
+   * panel rather than over it, whatever order the panels are written in.
+   */
+  const measured = context.keepMounted === 'measured';
+  const hiddenStyle = measured
+    ? ({
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        opacity: 0,
+        zIndex: -1,
+      } as const)
+    : ({ display: 'none' } as const);
+
   /*
    * 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.
+   * it is not drawn, it takes no touches, 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.
    */
   const panel = (
     <Animated.View
@@ -953,19 +1016,21 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
         // 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.
+        // panel kept with `display: none` measures as nothing — letting it say
+        // so would leave the visible panel with no width. A `'measured'` one
+        // is stretched over the tab set and reports the same width as the
+        // visible panel, so it is agreeing rather than overwriting.
         const measured = event.nativeEvent.layout.width;
         if (measured > 0) width.value = measured;
       }}
       /*
        * 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.
+       * Under `keepMounted` every other panel is hidden 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]}
+      style={[!active && hiddenStyle, swipeable && active && followStyle, style]}
       pointerEvents={active ? 'auto' : 'none'}
       accessibilityElementsHidden={!active}
       importantForAccessibility={active ? 'auto' : 'no-hide-descendants'}
@@ -976,9 +1041,10 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
     </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.
+  // Only the visible panel carries the gesture. A kept-mounted panel takes no
+  // touches anyway — `pointerEvents` is off on it whichever way it is hidden —
+  // 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>;