@oxyhq/bloom 1.13.0 → 1.14.1

package/src/tab-bar/TabBarBase.tsx

@@ -22,13 +22,21 @@ import {
   useMemo,
   type ComponentType,
 } from 'react';
-import { Pressable, StyleSheet, useWindowDimensions, View, type ViewStyle } from 'react-native';
+import {
+  Platform,
+  Pressable,
+  StyleSheet,
+  useWindowDimensions,
+  View,
+  type ViewStyle,
+} from 'react-native';
 import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
   Extrapolation,
   interpolate,
   interpolateColor,
   runOnJS,
+  useAnimatedReaction,
   useAnimatedStyle,
   useSharedValue,
   withSpring,
@@ -83,6 +91,13 @@ type BarContextValue = {
   theme: TabBarTheme;
   /** Set only on the CONTROLLED path (see `TabBarProps.activeIndex`). */
   activeIndex: number | undefined;
+  /**
+   * True while a driver owns the highlight's POSITION (see
+   * `TabBarProps.activeProgress`). Buttons read it to stand down: their focus
+   * effect and their press must not spring `slideIndex` out from under a pager
+   * mid-gesture. It says nothing about visibility, which stays where it was.
+   */
+  driven: boolean;
   /** Report a selection made by a button press. */
   selectIndex: (index: number) => void;
 };
@@ -103,6 +118,7 @@ function TabBarBody({
   Blur,
   children,
   activeIndex,
+  activeProgress,
   onIndexChange,
   onIndexLongPress,
   theme: themeOverrides,
@@ -189,6 +205,33 @@ function TabBarBody({
   // a legitimate effect (external-system sync), the same shape `Tabs` uses for
   // its underline. The focus-driven path is handled per-button instead — see
   // `TabBarButtonBody`.
+  // DRIVEN path: a pager owns the highlight's position and writes it every
+  // frame, so the position is COPIED rather than sprung — a spring chasing a
+  // per-frame value lags behind the finger, which is the whole thing this path
+  // exists to avoid.
+  //
+  // `useAnimatedReaction` cannot be called conditionally, so an unsupplied
+  // `activeProgress` is stood in for by a shared value nothing ever writes and
+  // the reaction returns early. `driven` changing flips the identity of `source`
+  // too, and both are in the deps array, so the reaction re-registers either
+  // way.
+  //
+  // Scrubbing still wins: a finger on the BAR is a direct manipulation of the
+  // bar and must not be fought by the pager's settle animation.
+  // (Deps: see the CRITICAL note below.)
+  const idleProgress = useSharedValue(0);
+  const driven = activeProgress !== undefined;
+  const source = activeProgress ?? idleProgress;
+  useAnimatedReaction(
+    () => source.value,
+    (value) => {
+      if (!driven) return;
+      if (isDragging.value) return;
+      slideIndex.value = value;
+    },
+    [source, driven, isDragging, slideIndex],
+  );
+
   useEffect(() => {
     if (activeIndex === undefined) return;
     // While scrubbing the finger owns the highlight; never fight it.
@@ -209,16 +252,29 @@ function TabBarBody({
     // stale index would animate out of a position the user never saw, and would
     // light up every tab in between on the way. Interrupted mid-fade it is
     // still on screen, so from there it slides as it always does.
-    slideIndex.value =
-      highlightOpacity.value === 0 ? activeIndex : withSpring(activeIndex, SLIDE_SPRING);
+    //
+    // On the DRIVEN path this effect keeps owning visibility and gives up the
+    // position: the driver is already writing `slideIndex` every frame, and a
+    // spring started here would drag the capsule across the bar between two of
+    // its writes.
+    if (!driven) {
+      slideIndex.value =
+        highlightOpacity.value === 0 ? activeIndex : withSpring(activeIndex, SLIDE_SPRING);
+    }
     highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
-  }, [activeIndex, hasSelection, slideIndex, highlightOpacity, isDragging]);
+  }, [activeIndex, hasSelection, driven, slideIndex, highlightOpacity, isDragging]);
 
   // Scrubbing: the highlight tracks the finger 1:1 while dragging (no spring —
   // it must feel attached), haptic ticks fire on boundary crossings, and
   // navigation happens only on release. Taps are handled by a Tap gesture
-  // racing the pan — the detector consumes the bar's touches, so the inner
-  // Pressables never receive them.
+  // racing the pan.
+  //
+  // THE DETECTOR DOES NOT CONSUME THE PRESS, which this file assumed for a long
+  // time. A `Tap` gesture activates on RELEASE, by which point the inner
+  // `Pressable` has already fired `onPress`, and RNGH's cancellation of the RN
+  // responder comes too late to stop it. Measured on a Pixel 10 Pro: ONE tap
+  // produced both, ~600ms apart on a busy JS thread, so every consumer got two
+  // selections per tap. `TabBarButtonBody` is where that is resolved.
   const gesture = useMemo(() => {
     const indexAtX = (x: number, minimizedValue: number) => {
       'worklet';
@@ -292,8 +348,15 @@ function TabBarBody({
         const index = Math.round(indexAtX(event.x, progress.value));
         // Same rule as the controlled path above: appear at the tapped tab when
         // hidden, slide to it when already on screen.
-        slideIndex.value =
-          highlightOpacity.value === 0 ? index : withSpring(index, SLIDE_SPRING);
+        //
+        // A tap is a discrete writer, so on the DRIVEN path it stands down like
+        // the others and the driver carries the highlight to the tapped tab.
+        // The scrub is the one gesture that does not: a finger dragging the
+        // pill is manipulating the bar itself, not asking for a page.
+        if (!driven) {
+          slideIndex.value =
+            highlightOpacity.value === 0 ? index : withSpring(index, SLIDE_SPRING);
+        }
         highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
         setMinimized(minimized, 0);
         runOnJS(selectIndex)(index);
@@ -324,6 +387,7 @@ function TabBarBody({
     hasLongPress,
     longPressIndex,
     tick,
+    driven,
     isDragging,
     lastTicked,
     slideIndex,
@@ -444,8 +508,8 @@ function TabBarBody({
   const constrainedWrapStyle: ViewStyle | null =
     maxWidth === undefined ? null : { width: barOuterWidth, alignSelf: 'center' };
   const barContext = useMemo(
-    () => ({ slideIndex, highlightOpacity, isDragging, theme, activeIndex, selectIndex }),
-    [slideIndex, highlightOpacity, isDragging, theme, activeIndex, selectIndex],
+    () => ({ slideIndex, highlightOpacity, isDragging, theme, activeIndex, driven, selectIndex }),
+    [slideIndex, highlightOpacity, isDragging, theme, activeIndex, driven, selectIndex],
   );
 
   return (
@@ -493,6 +557,9 @@ interface TabBarButtonBodyProps extends TabBarButtonProps {
 }
 
 /** One tab trigger: icon + label that fades out when the bar minimizes. */
+/** Stable identity: a new array each render would re-send the actions to the OS. */
+const ACTIVATE_ACTIONS = [{ name: 'activate' as const }];
+
 function TabBarButtonBody({
   Glyph,
   item,
@@ -522,6 +589,10 @@ function TabBarButtonBody({
   useEffect(() => {
     if (isFocused === undefined || !isFocused || !bar) return;
     if (bar.isDragging.value) return;
+    // A driver owns the position — see `TabBarProps.activeProgress`. It is
+    // already tracking this same focus change; springing from here as well would
+    // be a second writer on one shared value.
+    if (bar.driven) return;
     bar.slideIndex.value = withSpring(index, SLIDE_SPRING);
   }, [isFocused, index, bar]);
 
@@ -584,21 +655,43 @@ function TabBarButtonBody({
       aria-selected={focused}
       accessibilityLabel={item.label}
       {...pressableProps}
+      // ASSISTIVE TECHNOLOGY, on native, is the one activation the bar's gesture
+      // cannot see: TalkBack and VoiceOver activate a view without ever
+      // producing a touch, so the `Tap` gesture never runs and the selection has
+      // to come from here.
+      accessibilityActions={ACTIVATE_ACTIONS}
+      onAccessibilityAction={(event) => {
+        if (event.nativeEvent.actionName !== 'activate') return;
+        if (isFocused === undefined) bar?.selectIndex(index);
+      }}
       onPress={(event) => {
         // The bar's GestureDetector normally consumes touches; this still fires
         // for assistive-technology activation (VoiceOver) and keyboard focus.
         if (bar) {
           // Appear at the tab when hidden, slide to it when visible — the same
-          // rule the tap gesture and the controlled path follow.
-          bar.slideIndex.value =
-            bar.highlightOpacity.value === 0 ? index : withSpring(index, SLIDE_SPRING);
+          // rule the tap gesture and the controlled path follow. Skipped on the
+          // driven path, where the position belongs to the driver and this
+          // press will reach it as an ordinary selection.
+          if (!bar.driven) {
+            bar.slideIndex.value =
+              bar.highlightOpacity.value === 0 ? index : withSpring(index, SLIDE_SPRING);
+          }
           bar.highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
         }
         setMinimized(minimized, 0);
-        // Controlled path only. On the focus-driven path the trigger's own
-        // `onPress` below performs the navigation, so reporting the selection
-        // here as well would navigate twice.
-        if (isFocused === undefined) bar?.selectIndex(index);
+        // Controlled path only, and NOT on Android. On the focus-driven path the
+        // trigger's own `onPress` below performs the navigation, so reporting
+        // the selection here as well would navigate twice.
+        //
+        // ANDROID IS THE ONE PLATFORM THAT DOUBLES. RNGH sets
+        // `cancelsTouchesInView` on iOS, so a recognised tap cancels this press
+        // and the gesture above is the only reporter there; react-native-web
+        // likewise routes a keyboard Enter or Space through this press and
+        // nothing else. Android cancels nothing — measured on a Pixel 10 Pro,
+        // one tap produced `PRESSABLE selectIndex(1)` AND `GESTURE tap
+        // selectIndex(1)` ~600ms apart on a busy JS thread — so there, and only
+        // there, this press stands down.
+        if (isFocused === undefined && Platform.OS !== 'android') bar?.selectIndex(index);
         onPress?.(event);
       }}
       // `Pressable`'s `style` also accepts a function of the press state; both

package/src/tab-bar/expo-router/RouterTabBar.tsx

@@ -19,6 +19,11 @@ import type { TabBarItem, TabBarProps } from '../types';
  * by each trigger's own focus (see `RouterTabBarButton`), which is what keeps it
  * correct through deep links, back gestures and any other programmatic
  * navigation. Setting both would put two writers on one shared value.
+ *
+ * `activeProgress` is NOT omitted, and that is not an oversight. It answers a
+ * different question — where the highlight is, not whether there is one — so a
+ * router-focused bar whose screens are PAGED can pass it and keep the focus
+ * path for selection. See `TabBarProps.activeProgress`.
  */
 export type RouterTabBarProps = TabListProps & Omit<TabBarProps, 'activeIndex'>;
 

package/src/tab-bar/types.ts

@@ -4,14 +4,21 @@
  *
  * Public API types for `@oxyhq/bloom/tab-bar`.
  *
- * This module imports from `react` and `react-native` ONLY. It is resolved by a
- * consumer's `tsc`, by Metro, and by every web bundler alike, so a platform
- * import here (expo-glass-effect / expo-symbols / expo-router) would break all
- * three at once. Platform behaviour lives in `surface.native.tsx` /
- * `glyph.native.tsx` / `surface.web.tsx` and the `expo-router/` adapter.
+ * This module names no PLATFORM package. It is resolved by a consumer's `tsc`,
+ * by Metro, and by every web bundler alike, so an import here of
+ * expo-glass-effect / expo-symbols / expo-router / react-native-screens would
+ * break all three at once. Platform behaviour lives in `surface.native.tsx` /
+ * `glyph.native.tsx` / `surface.web.tsx` and the `expo-router/` adapter; the
+ * gate is `src/__tests__/TabBarWebFork.test.ts`.
+ *
+ * `react-native-reanimated` is exempt and always was: it is a REQUIRED peer that
+ * every neutral module in this family already imports at runtime
+ * (`TabBarBase.tsx`), and the one reference below is `import type`, erased
+ * before any bundler sees it.
  */
 import type { ReactNode } from 'react';
 import type { PressableProps, ViewProps } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
 
 export type TabBarItem = {
   /** Stable identity for the tab (a route name in router-driven usage). */
@@ -92,6 +99,30 @@ export type TabBarProps = ViewProps & {
    * highlight from its own `isFocused`.
    */
   activeIndex?: number;
+  /**
+   * DRIVEN path — the highlight's live position, in TAB UNITS, on the UI thread.
+   * A pager writes its own page position here (`1.4` is 40% of the way from the
+   * second tab to the third) and the highlight tracks the finger 1:1 instead of
+   * springing to a settled index after the navigation commits.
+   *
+   * It says WHERE the highlight is, never WHETHER there is one. Selection stays
+   * with the path already in play: `activeIndex` when the bar is controlled (an
+   * index naming no tab still fades the highlight out — see above), each
+   * button's `isFocused` when it is not. Passing this alone, with neither, is a
+   * bar that is always selected, which is what the focus-driven path already
+   * means.
+   *
+   * PRECEDENCE, because a shared value with two writers is a race: the SCRUB
+   * always wins — a finger on the bar is a direct manipulation of the bar, and
+   * releasing it reports through `onIndexChange` like any other selection. Below
+   * that, this value wins over every discrete writer: while it is supplied, the
+   * controlled effect, the focus effect and a `TabBarButton`'s own press all
+   * stop writing the position and leave it to the driver. So a consumer that
+   * passes this must keep it truthful — spring it to the settled index after a
+   * commit, and after any navigation it did not cause (a deep link, a back
+   * gesture), or the highlight stays where the last gesture left it.
+   */
+  activeProgress?: SharedValue<number>;
   /**
    * Called with the chosen index when a tab is picked by tap, by scrub release,
    * or by keyboard/assistive-technology activation of a `TabBarButton`.

package/src/theme/color-scope/ColorScope.tsx

@@ -6,10 +6,25 @@ import { buildTheme } from '../build-theme';
 import type { AppColorName } from '../color-presets';
 import { buildNativePresetStyle, buildScopeVars, getVariableContextProvider } from './style-builder';
 
+/**
+ * The variables a scope publishes when it carries no preset of its own.
+ *
+ * Empty and shared at module scope, both deliberately: react-native-css's
+ * `VariableContextProvider` MERGES its value over the inherited one, so an empty
+ * record leaves the parent scope's variables exactly as they were, and one
+ * shared identity keeps that provider's `useMemo` from recomputing every render.
+ */
+const NO_VARS: Record<string, string> = Object.freeze({});
+
 export interface BloomColorScopeProps {
   /**
-   * Preset to apply within this subtree. When `undefined`, the scope is a
-   * no-op and children inherit the parent scope's preset unchanged.
+   * Preset to apply within this subtree. When `undefined`, the scope publishes
+   * nothing of its own and children inherit the parent scope's preset unchanged.
+   *
+   * It is a no-op in what it PUBLISHES, never in what it RENDERS — see the
+   * component's own comment: the element tree this returns is identical whether
+   * or not a preset is set, because a preset that arrives late must not remount
+   * the subtree.
    */
   colorPreset: AppColorName | undefined;
   /**
@@ -26,6 +41,35 @@ interface StyleableProps {
   style?: StyleProp<ViewStyle>;
 }
 
+/**
+ * A subtree themed by one color preset.
+ *
+ * THE SHAPE OF WHAT THIS RETURNS DOES NOT DEPEND ON `colorPreset`. Both
+ * providers are mounted unconditionally, and an absent preset is expressed as
+ * pass-through VALUES ({@link NO_VARS}, the parent's own theme) rather than as a
+ * shorter tree. That is a correctness requirement, not a tidiness one, and it
+ * cost a real bug to learn:
+ *
+ * The no-preset path used to be `return <>{children}</>` — two provider levels
+ * shallower than the preset path. React reconciles by POSITION, so the first
+ * render after a preset arrives finds different element types at that position
+ * and unmounts the whole subtree to mount a new one. Every consumer that resolves
+ * its preset asynchronously — a profile screen learning the account's color a
+ * few hundred milliseconds after it opens — therefore remounted everything below
+ * the scope, including its own navigator.
+ *
+ * In Mention that scope sits above the app's route stack: the remount rebuilt
+ * the `[username]` navigator from scratch, which dropped the pushed child route
+ * AND its `username` param, and the profile a reader had just tapped rendered
+ * itself as "Profile not found" (mention#…, reproduced from the reel on a Pixel
+ * 10 Pro; the A/B was pinning `colorPreset` and watching the collapse stop).
+ * Remounting also throws away scroll positions, video players and in-flight
+ * state, so the same bug was costing far more than the one visible symptom.
+ *
+ * If a future change wants the no-preset case to render less, it has to keep the
+ * element types at this position identical across a preset change, or the
+ * remount comes back.
+ */
 export function BloomColorScope({
   colorPreset,
   asChild = false,
@@ -33,10 +77,9 @@ export function BloomColorScope({
   children,
 }: BloomColorScopeProps) {
   // All hooks are called UNCONDITIONALLY, in the same order on every render —
-  // never gate a hook behind an early return (rules of hooks). The conditional
-  // no-op/throw behavior is applied AFTER every hook has run, using the values
-  // the hooks produced. `resolvedMode` falls back harmlessly when the provider
-  // is absent (that render path throws below anyway).
+  // never gate a hook behind an early return (rules of hooks). The throw below
+  // happens AFTER every hook has run. `resolvedMode` falls back harmlessly when
+  // the provider is absent (that render path throws anyway).
   const parent = useContext(BloomThemeContext);
   const resolvedMode = parent?.theme.mode ?? 'light';
 
@@ -58,10 +101,6 @@ export function BloomColorScope({
   if (!parent) {
     throw new Error('BloomColorScope must be used within a <BloomThemeProvider>');
   }
-  // `colorPreset` undefined => the scope is a no-op; children inherit the
-  // parent scope. With `parent` present, `contextValue`/`nativeVars` are null
-  // iff `colorPreset` is absent, so this guard also narrows them to non-null.
-  if (!contextValue || !nativeVars) return <>{children}</>;
 
   const VariableProvider = getVariableContextProvider();
 
@@ -85,12 +124,14 @@ export function BloomColorScope({
   // Wrap the subtree in the variable provider when NativeWind is available;
   // otherwise render as-is so we never crash on web/non-NativeWind hosts.
   const scoped = VariableProvider ? (
-    <VariableProvider value={nativeVars}>{content}</VariableProvider>
+    <VariableProvider value={nativeVars ?? NO_VARS}>{content}</VariableProvider>
   ) : (
     content
   );
 
-  return <BloomThemeContext.Provider value={contextValue}>{scoped}</BloomThemeContext.Provider>;
+  return (
+    <BloomThemeContext.Provider value={contextValue ?? parent}>{scoped}</BloomThemeContext.Provider>
+  );
 }
 
 /**

package/src/theme/color-scope/ColorScope.web.tsx

@@ -20,8 +20,12 @@ function buildWebScopeVars(
 
 export interface BloomColorScopeProps {
   /**
-   * Preset to apply within this subtree. When `undefined`, the scope is a
-   * no-op and children inherit the parent scope's preset unchanged.
+   * Preset to apply within this subtree. When `undefined`, the scope publishes
+   * nothing of its own and children inherit the parent scope's preset unchanged.
+   *
+   * It is a no-op in what it PUBLISHES, never in what it RENDERS — the element
+   * tree is identical either way, so a preset that arrives late cannot remount
+   * the subtree. `ColorScope.tsx` carries the full account.
    */
   colorPreset: AppColorName | undefined;
   /**
@@ -91,10 +95,6 @@ export function BloomColorScope({
   if (!parent) {
     throw new Error('BloomColorScope must be used within a <BloomThemeProvider>');
   }
-  // `colorPreset` undefined => the scope is a no-op; children inherit the
-  // parent scope. With `parent` present, `contextValue`/`varsStyle` are null
-  // iff `colorPreset` is absent, so this guard also narrows them to non-null.
-  if (!contextValue || !varsStyle) return <>{children}</>;
 
   let content: React.ReactNode;
   if (asChild) {
@@ -111,7 +111,7 @@ export function BloomColorScope({
     const childStyle = child.props.style;
     const childIsRnStyled = Array.isArray(childStyle) || typeof childStyle === 'number';
     const mergedStyle: WebStyle = childIsRnStyled
-      ? [varsStyle, style, childStyle]
+      ? [varsStyle ?? undefined, style, childStyle]
       : { ...varsStyle, ...style, ...(childStyle || undefined) };
     content = cloneElement(child, { style: mergedStyle });
   } else {
@@ -121,7 +121,9 @@ export function BloomColorScope({
     content = <div style={mergedStyle}>{children}</div>;
   }
 
-  return <BloomThemeContext.Provider value={contextValue}>{content}</BloomThemeContext.Provider>;
+  return (
+    <BloomThemeContext.Provider value={contextValue ?? parent}>{content}</BloomThemeContext.Provider>
+  );
 }
 
 /**