@oxyhq/bloom 1.12.0 → 1.14.0

package/src/tab-bar/TabBarBase.tsx

@@ -20,7 +20,6 @@ import {
   useContext,
   useEffect,
   useMemo,
-  useState,
   type ComponentType,
 } from 'react';
 import { Pressable, StyleSheet, useWindowDimensions, View, type ViewStyle } from 'react-native';
@@ -85,6 +84,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;
 };
@@ -105,6 +111,7 @@ function TabBarBody({
   Blur,
   children,
   activeIndex,
+  activeProgress,
   onIndexChange,
   onIndexLongPress,
   theme: themeOverrides,
@@ -191,6 +198,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.
@@ -211,10 +245,17 @@ 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
@@ -294,8 +335,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);
@@ -326,6 +374,7 @@ function TabBarBody({
     hasLongPress,
     longPressIndex,
     tick,
+    driven,
     isDragging,
     lastTicked,
     slideIndex,
@@ -424,33 +473,13 @@ 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 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);
+  // 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);
 
   // 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
@@ -466,8 +495,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 (
@@ -544,6 +573,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]);
 
@@ -611,9 +644,13 @@ function TabBarButtonBody({
         // 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);

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/__tests__/support/collision-fixture-barrel.ts

@@ -1,20 +0,0 @@
-/**
- * A barrel that DELIBERATELY offers one name from two declarations, so that
- * `barrel-name-collisions.test.ts` can prove its detector fires. It reproduces
- * the shipped `Item` shape: a star export carrying `Item` from `item/`, and an
- * explicit re-export binding that same name to a different component.
- *
- * Nothing imports this at runtime. bob's `exclude` keeps it out of `lib/`, and
- * `files: ["src", …]` does ship it inside the tarball's `src/` like the other
- * test files there — but no entry point reaches it, so no bundler links it, and
- * `package.json#exports` never names it.
- *
- * The `Card` lines below are the other half of the
- * control: one name offered twice from ONE declaration, which the detector must
- * stay quiet about — otherwise its cheapest fix would be deleting a legitimate
- * redundant re-export.
- */
-export * from '../../item';
-export { Card as Item } from '../../card';
-export { Card } from '../../card';
-export * from '../../card';

package/src/__tests__/support/constructed-style-sheets.ts

@@ -1,68 +0,0 @@
-/**
- * A spec-shaped stand-in for constructed stylesheets, for the jsdom suites.
- *
- * jsdom 26 ships the `CSSStyleSheet` CONSTRUCTOR but neither `replaceSync` nor
- * `document.adoptedStyleSheets`, so every jsdom test takes Bloom's `<style>`
- * fallback. That makes the whole CSP-safe path — the reason
- * `styles/adopt-style-sheet.ts` exists — invisible to jest unless a test
- * installs the API itself. Without this, a mutation that deleted the adoption
- * branch entirely would leave the suite green.
- *
- * Not collected as a suite: jest's `testMatch` wants `*.test.ts` / `*.spec.ts`.
- */
-
-export interface FakeStyleSheet {
-  /** The CSS most recently handed to `replaceSync`. */
-  cssText: string;
-  /** How many times the sheet has been re-parsed, so a test can prove it wasn't. */
-  replaceSyncCalls: number;
-  replaceSync(css: string): void;
-}
-
-export interface ConstructedStyleSheetsHarness {
-  /** The document's adopted sheets, read live (the code reassigns the array). */
-  adopted(): readonly FakeStyleSheet[];
-  /** Drop the API again, restoring jsdom's own `CSSStyleSheet`. */
-  uninstall(): void;
-}
-
-export function installConstructedStyleSheets(): ConstructedStyleSheetsHarness {
-  class FakeCSSStyleSheet implements FakeStyleSheet {
-    cssText = '';
-    replaceSyncCalls = 0;
-
-    replaceSync(css: string): void {
-      this.cssText = css;
-      this.replaceSyncCalls += 1;
-    }
-  }
-
-  const previousConstructor = Object.getOwnPropertyDescriptor(
-    globalThis,
-    'CSSStyleSheet',
-  );
-
-  Object.defineProperty(globalThis, 'CSSStyleSheet', {
-    value: FakeCSSStyleSheet,
-    writable: true,
-    configurable: true,
-  });
-  Object.defineProperty(document, 'adoptedStyleSheets', {
-    value: [],
-    writable: true,
-    configurable: true,
-  });
-
-  return {
-    adopted: () =>
-      document.adoptedStyleSheets as unknown as readonly FakeStyleSheet[],
-    uninstall: () => {
-      Reflect.deleteProperty(document, 'adoptedStyleSheets');
-      if (previousConstructor) {
-        Object.defineProperty(globalThis, 'CSSStyleSheet', previousConstructor);
-      } else {
-        Reflect.deleteProperty(globalThis, 'CSSStyleSheet');
-      }
-    },
-  };
-}

package/src/__tests__/support/press-host.ts

@@ -1,30 +0,0 @@
-/**
- * Pressing a component's OWN host node, and proving the component is what
- * installed the handler being measured.
- *
- * `fireEvent.press` walks UP from the element it is handed to the nearest
- * ancestor carrying an `onPress` prop, and it does not stop at host nodes — a
- * COMPOSITE counts, because `getEventHandler` only reads `element.props`. So
- * `<Thing onPress={fn}>` written in a test's own JSX catches the press itself.
- * Measured on `ProfileCard`: with the handler deleted from the component the
- * card rendered as an inert `View`, and the test still reported exactly one
- * call. Green, and measuring nothing. Nine suites had the same shape.
- *
- * Asserting the host node's own `onPress` FIRST closes both halves:
- *
- *  - a component that installs no handler at all fails here, and
- *  - a component that installs one which drops the caller's fails on the call
- *    count, because `fireEvent` now finds a handler AT the node and never walks
- *    past it to the test's own JSX.
- *
- * `host` must therefore be the node the component itself made pressable — the
- * one carrying its `testID` / `accessibilityLabel` — not a `Text` deep inside
- * it, or the walk-up is back and so is the hole.
- */
-import { fireEvent } from '@testing-library/react-native';
-import type { ReactTestInstance } from 'react-test-renderer';
-
-export function pressHost(host: ReactTestInstance): void {
-  expect(typeof host.props.onPress).toBe('function');
-  fireEvent.press(host);
-}

package/src/__tests__/support/rendered-style.ts

@@ -1,99 +0,0 @@
-/**
- * Reading what actually landed on a rendered node — shared by every suite that
- * asserts the "className lands on the node the parent lays out" rule.
- *
- * Three components had the same two-node defect (`Button`, then `Fab` and
- * `FrostedIconButton`), and asserting it needs the same two things each time:
- * the HOST tree (composites do not appear in `toJSON()`, so a wrapper is only
- * visible there) and a deep flatten of the `style` prop, because react-native-css
- * merges a caller's class in as a `{ $$css: true, className }` descriptor
- * ALONGSIDE the style objects rather than in a prop of its own.
- */
-import type { ReactTestRendererJSON } from 'react-test-renderer';
-
-export type StyleEntry = Record<string, unknown>;
-
-export interface HostNode {
-  type: string;
-  props: Record<string, unknown>;
-  children: Array<HostNode | string> | null;
-}
-
-/**
- * Deep-flatten an RN `style` prop (nested arrays, `false`/`null` holes) into the
- * list of style objects that actually reached the node.
- */
-export function styleEntries(style: unknown, out: StyleEntry[] = []): StyleEntry[] {
-  if (!style || typeof style !== 'object') return out;
-  if (Array.isArray(style)) {
-    for (const entry of style) styleEntries(entry, out);
-    return out;
-  }
-  out.push(style as StyleEntry);
-  return out;
-}
-
-/** Every style key/value that landed on a node, later entries winning. */
-export function resolvedStyle(style: unknown): StyleEntry {
-  return Object.assign({}, ...styleEntries(style)) as StyleEntry;
-}
-
-/** The class tokens react-native-css accepted for a node, in arrival order. */
-export function classNamesOn(style: unknown): string[] {
-  return styleEntries(style)
-    .filter((entry) => entry.$$css === true && typeof entry.className === 'string')
-    .map((entry) => String(entry.className));
-}
-
-export function isHostNode(value: unknown): value is HostNode {
-  return (
-    typeof value === 'object' && value !== null && typeof (value as HostNode).type === 'string'
-  );
-}
-
-/** Walk the HOST tree (composites are absent from `toJSON()`) for a testID. */
-export function findHost(
-  node: ReactTestRendererJSON | ReactTestRendererJSON[] | unknown,
-  testID: string,
-): HostNode | null {
-  if (Array.isArray(node)) {
-    for (const child of node) {
-      const hit = findHost(child, testID);
-      if (hit) return hit;
-    }
-    return null;
-  }
-  if (!isHostNode(node)) return null;
-  if (node.props.testID === testID) return node;
-  return findHost(node.children, testID);
-}
-
-/**
- * Every host node in a rendered tree, in document order.
- *
- * The reason to walk `toJSON()` rather than `UNSAFE_root.findAll` is that the
- * latter yields COMPOSITE instances too, so a `memo(fn)` component contributes
- * two matches for one rendered element and every count is silently doubled —
- * which reads as "the component rendered the thing twice", not as an artefact
- * of the query.
- */
-export function hostNodes(tree: unknown, out: HostNode[] = []): HostNode[] {
-  if (Array.isArray(tree)) {
-    for (const child of tree) hostNodes(child, out);
-    return out;
-  }
-  if (!isHostNode(tree)) return out;
-  out.push(tree);
-  return hostNodes(tree.children, out);
-}
-
-/**
- * The host nodes a parent laid out. Callers assert the LENGTH themselves —
- * "exactly one" is the property, and a helper that returned only the first would
- * hide the second.
- */
-export function renderedChildren(tree: unknown, hostTestID: string): HostNode[] {
-  const host = findHost(tree, hostTestID);
-  if (host === null) throw new Error(`no host rendered for testID "${hostTestID}"`);
-  return (host.children ?? []).filter(isHostNode);
-}

package/src/__tests__/support/unread-hook-fixture.ts

@@ -1,33 +0,0 @@
-/**
- * A module that DELIBERATELY throws away one of the values a hook hands back, so
- * `hook-subscriptions-are-read.test.ts` can prove its detector fires. It carries
- * both halves of the control: `unreadFlag` is bound and never read, which the
- * detector must report, and `readFlag` is bound and read, which it must stay
- * quiet about — otherwise the cheapest way to green the gate would be deleting a
- * binding that is doing its job.
- *
- * Nothing imports this at runtime. bob's `exclude` keeps it out of `lib/`, and
- * `files: ["src", …]` does ship it inside the tarball's `src/` like the other
- * 137 test files there — but no entry point reaches it, so no bundler links it.
- * It is a plain `.ts` with no React import because the
- * detector reads source, never types: a call named `use…` bound to a name is all
- * the shape there is.
- *
- * The destructuring RENAMES, which is not decoration — it reproduces the shipped
- * shape (`const { state: pressed, onIn: onPressIn } = useInteractionState()`) and
- * it is what keeps the control honest. A hook declared in the same file as its
- * caller mentions its own property names in its return type and its return
- * object, and the detector counts every occurrence of a spelling as a possible
- * read, so an unrenamed fixture would be silently unreportable for a reason no
- * real call site has.
- */
-
-/** Stands in for a real subscription — a hook by name, with two return values. */
-function useFixtureInteractionState(): { first: boolean; second: boolean } {
-  return { first: false, second: false };
-}
-
-export function fixtureComponentBody(): boolean {
-  const { first: readFlag, second: unreadFlag } = useFixtureInteractionState();
-  return readFlag;
-}