@oxyhq/bloom 1.10.1 → 1.12.0

package/src/layout/bottom-edge.tsx

@@ -27,6 +27,33 @@
  * edge, so two surfaces at that edge overlap rather than stack; the tallest is
  * what a new surface has to clear. Summing would strand it at twice the height.
  *
+ * ## A size and a state, because they travel differently
+ *
+ * A surface that collapses — the tab bar minimizes 58 -> 44 on scroll — publishes
+ * two things, and only one of them is a measurement:
+ *
+ *   - RESERVED (`useBottomEdgeInset`) never shrinks while the claimant is
+ *     mounted. It is what must be kept permanently free: a list's bottom
+ *     padding, a toast stack's offset. Shrinking it on collapse would jitter a
+ *     list's content size on every scroll and jump a toast 14px mid-display,
+ *     because the bar re-expands the instant the user scrolls back up.
+ *   - COLLAPSED (`useBottomEdgeCollapsed`) is a boolean, deliberately, and this
+ *     is the part that was learned the hard way. It first shipped as a live
+ *     PIXEL height so a FAB could ride down with the bar — and it felt broken on
+ *     a device. The bar animates on the UI thread; a React consumer learns about
+ *     the change through `runOnJS` plus two render passes, so its motion STARTS
+ *     one to three frames late, worst exactly while scrolling because that is
+ *     when the JS thread is busiest. No spring config fixes a variable start
+ *     delay.
+ *
+ * Two things moving together betray that lag; a state change does not. A reader
+ * that FADES on this boolean has no spatial relationship to violate, so the same
+ * few frames of latency are imperceptible. That is why the channel is a state and
+ * not a geometry: it is the shape of signal that survives the trip to the JS
+ * thread. Anything that genuinely must track the collapse per-frame has to read
+ * the tab bar's own shared value on the UI thread instead — React state is the
+ * wrong transport for it, at any width.
+ *
  * ## Why an external store
  *
  * The claim set is mutable state living outside React. Reading it in a memoized
@@ -45,33 +72,50 @@ import {
   type PropsWithChildren,
 } from 'react';
 
+interface Claim {
+  /** What the surface keeps permanently free, collapsed or not. */
+  reserved: number;
+  /** Whether it is currently in its collapsed state. */
+  collapsed: boolean;
+}
+
 interface BottomEdgeStore {
   subscribe: (onChange: () => void) => () => void;
   /**
-   * The cached total. Returns the SAME number until a claim actually changes it
-   * — `useSyncExternalStore` re-renders forever if the snapshot is recomputed
-   * per call.
+   * The cached totals. Each returns the SAME number until a claim actually
+   * changes it — `useSyncExternalStore` re-renders forever if the snapshot is
+   * recomputed per call, and a reader of one channel must not re-render when
+   * only the other moved.
    */
-  getInset: () => number;
-  claim: (id: string, height: number) => void;
+  getReserved: () => number;
+  getCollapsed: () => boolean;
+  claim: (id: string, reserved: number, collapsed: boolean) => void;
   release: (id: string) => void;
 }
 
 function createBottomEdgeStore(): BottomEdgeStore {
-  const claims = new Map<string, number>();
+  const claims = new Map<string, Claim>();
   const listeners = new Set<() => void>();
-  let inset = 0;
+  let reserved = 0;
+  let collapsed = false;
 
   const recompute = () => {
-    let next = 0;
-    for (const height of claims.values()) {
-      if (height > next) next = height;
+    let nextReserved = 0;
+    // ANY claimant collapsing collapses the edge. With the one floating bar this
+    // is written for the two readings coincide; where they would not, "something
+    // at this edge just retracted" is still the signal a reader wants, and it is
+    // the safe direction — a FAB that fades when it did not strictly have to
+    // beats one that stays put over a bar that left.
+    let nextCollapsed = false;
+    for (const claim of claims.values()) {
+      if (claim.reserved > nextReserved) nextReserved = claim.reserved;
+      if (claim.collapsed) nextCollapsed = true;
     }
-    // Bail before notifying: a re-registration at an unchanged height (every
-    // render of a claimant whose footprint did not move) must not re-render
-    // every reader.
-    if (next === inset) return;
-    inset = next;
+    // Bail before notifying: a re-registration at an unchanged footprint (every
+    // render of a claimant that did not move) must not re-render every reader.
+    if (nextReserved === reserved && nextCollapsed === collapsed) return;
+    reserved = nextReserved;
+    collapsed = nextCollapsed;
     for (const listener of listeners) listener();
   };
 
@@ -82,10 +126,12 @@ function createBottomEdgeStore(): BottomEdgeStore {
         listeners.delete(onChange);
       };
     },
-    getInset: () => inset,
-    claim(id, height) {
-      if (claims.get(id) === height) return;
-      claims.set(id, height);
+    getReserved: () => reserved,
+    getCollapsed: () => collapsed,
+    claim(id, nextReserved, nextCollapsed) {
+      const existing = claims.get(id);
+      if (existing?.reserved === nextReserved && existing.collapsed === nextCollapsed) return;
+      claims.set(id, { reserved: nextReserved, collapsed: nextCollapsed });
       recompute();
     },
     release(id) {
@@ -114,15 +160,18 @@ BottomEdgeProvider.displayName = 'BottomEdgeProvider';
 // would resubscribe `useSyncExternalStore` on every render.
 const NO_SUBSCRIPTION = () => () => {};
 const NO_INSET = () => 0;
+const NO_COLLAPSE = () => false;
 
 /**
- * How much of the bottom edge is already occupied, in px.
+ * How much of the bottom edge is permanently RESERVED, in px.
  *
- * Add it to whatever offset the surface would otherwise use:
+ * Never shrinks while its claimant is mounted, so it is the number for anything
+ * that must not move as the user scrolls — a list's bottom padding, a toast
+ * stack's offset:
  *
  * ```tsx
- * const occupied = useBottomEdgeInset();
- * <View style={{ position: 'absolute', bottom: windowEdgeGap(insets.bottom) + occupied }} />
+ * const reserved = useBottomEdgeInset();
+ * <FlatList contentContainerStyle={{ paddingBottom: reserved + 12 }} />
  * ```
  *
  * `0` outside a provider, and `0` on the first commit even inside one — a claim
@@ -134,29 +183,56 @@ export function useBottomEdgeInset(): number {
   const store = useContext(BottomEdgeContext);
   return useSyncExternalStore(
     store?.subscribe ?? NO_SUBSCRIPTION,
-    store?.getInset ?? NO_INSET,
-    store?.getInset ?? NO_INSET,
+    store?.getReserved ?? NO_INSET,
+    store?.getReserved ?? NO_INSET,
+  );
+}
+
+/**
+ * Whether the surface owning the bottom edge is currently COLLAPSED — the tab
+ * bar minimized on scroll.
+ *
+ * A boolean rather than a live height, on purpose: see the note at the top of
+ * this file. A reader should FADE or otherwise change state on it, never try to
+ * stay geometrically locked to the collapsing surface — that lock is what a
+ * React-state channel cannot deliver, because the surface animates on the UI
+ * thread and this arrives one to three frames later.
+ *
+ * ```tsx
+ * const collapsed = useBottomEdgeCollapsed();
+ * // fade out; do not chase the bar's new top edge
+ * ```
+ *
+ * `false` outside a provider.
+ */
+export function useBottomEdgeCollapsed(): boolean {
+  const store = useContext(BottomEdgeContext);
+  return useSyncExternalStore(
+    store?.subscribe ?? NO_SUBSCRIPTION,
+    store?.getCollapsed ?? NO_COLLAPSE,
+    store?.getCollapsed ?? NO_COLLAPSE,
   );
 }
 
 /**
- * Claim `height` px of the bottom edge for as long as the caller is mounted.
+ * Claim the bottom edge for as long as the caller is mounted.
  *
  * The claimant owns its own placement — claiming does not move it. It declares
- * the space it occupies so that everything reading `useBottomEdgeInset()` stays
- * off it. Pass the FULL footprint (the surface's height plus the gap it holds
- * off the window edge), which is the same number the surface positions itself
- * with.
+ * the space it occupies so that everything reading the edge stays off it. Pass
+ * the FULL footprint (the surface's height plus the gap it holds off the window
+ * edge), which is the same number the surface positions itself with, and keep it
+ * at the surface's FULL size even while collapsed: `reserved` is what must stay
+ * permanently free, and the collapse is reported separately by `collapsed`.
  *
  * A no-op outside a provider, so a surface stays usable standalone.
  */
-export function useClaimBottomEdge(height: number): void {
+export function useClaimBottomEdge(reserved: number, collapsed = false): void {
   const store = useContext(BottomEdgeContext);
   const id = useId();
 
   useEffect(() => {
     if (!store) return;
-    store.claim(id, height);
+    store.claim(id, reserved, collapsed);
     return () => store.release(id);
-  }, [store, id, height]);
+  }, [store, id, reserved, collapsed]);
 }

package/src/layout/index.ts

@@ -5,4 +5,9 @@
  * parked there". A surface that floats at the bottom needs both.
  */
 export { EDGE_GAP, windowEdgeGap } from './edge';
-export { BottomEdgeProvider, useBottomEdgeInset, useClaimBottomEdge } from './bottom-edge';
+export {
+  BottomEdgeProvider,
+  useBottomEdgeInset,
+  useBottomEdgeCollapsed,
+  useClaimBottomEdge,
+} from './bottom-edge';

package/src/tab-bar/TabBarBase.tsx

@@ -20,6 +20,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useState,
   type ComponentType,
 } from 'react';
 import { Pressable, StyleSheet, useWindowDimensions, View, type ViewStyle } from 'react-native';
@@ -29,6 +30,7 @@ import Animated, {
   interpolate,
   interpolateColor,
   runOnJS,
+  useAnimatedReaction,
   useAnimatedStyle,
   useSharedValue,
   withSpring,
@@ -422,13 +424,33 @@ function TabBarBody({
   // its own layout can never drift from where the bar actually sits.
   const bottomOffset = windowEdgeGap(insets.bottom);
 
+  // Whether the bar has settled into its minimized size, as REACT state.
+  //
+  // Reacting on `target` rather than on `progress` is what keeps this cheap:
+  // `target` is the binary 0/1 the minimize spring is heading for, so this fires
+  // twice per scroll gesture instead of once per frame. Crossing `progress > 0.5`
+  // would work too and would cost the same, but it would report the change
+  // halfway through the animation rather than when it was decided.
+  const [isMinimized, setIsMinimized] = useState(false);
+  useAnimatedReaction(
+    () => minimized.target.value,
+    (target, previous) => {
+      if (target !== previous) runOnJS(setIsMinimized)(target === 1);
+    },
+    [minimized],
+  );
+
   // Publish what the bar occupies so anything else at this edge stacks above it
-  // rather than behind it. Same number `useTabBarFootprint` reports, derived from
-  // the same two values, so a consumer reading either can never disagree with
-  // where the bar actually sits. The EXPANDED height on purpose: the bar
-  // minimizes on scroll and re-expands, so claiming the minimized height would
-  // drop a FAB onto the pill the moment the user scrolled back up.
-  useClaimBottomEdge(bottomOffset + EXPANDED_HEIGHT);
+  // rather than behind it. Same numbers `useTabBarFootprint` reports, derived
+  // from the same geometry, so a consumer reading either can never disagree with
+  // where the bar actually sits.
+  //
+  // RESERVED stays the EXPANDED height even while minimized: the bar re-expands
+  // the moment the user scrolls back up, so anything that permanently reserves
+  // space (a list's bottom padding, a toast) must keep room for the full pill or
+  // it would jitter on every scroll. The collapse travels as its own STATE — see
+  // `layout/bottom-edge` for why it is a boolean and not the live height.
+  useClaimBottomEdge(bottomOffset + EXPANDED_HEIGHT, isMinimized);
 
   // How centring and the animated inset compose: centring is STATIC and belongs
   // to the wrap, the inset stays ANIMATED on the pill inside it. The wrap is