@oxyhq/bloom 0.53.0 → 0.54.1

package/src/tab-bar/TabBarBase.tsx

@@ -22,7 +22,7 @@ import {
   useMemo,
   type ComponentType,
 } from 'react';
-import { Pressable, StyleSheet, useWindowDimensions, View } from 'react-native';
+import { Pressable, StyleSheet, useWindowDimensions, View, type ViewStyle } from 'react-native';
 import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
   Extrapolation,
@@ -32,6 +32,7 @@ import Animated, {
   useAnimatedStyle,
   useSharedValue,
   withSpring,
+  withTiming,
   type SharedValue,
 } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
@@ -44,6 +45,7 @@ import {
   BLUR_BLEED,
   EXPANDED_HEIGHT,
   HIGHLIGHT_EXPANDED,
+  HIGHLIGHT_FADE,
   HIGHLIGHT_MINIMIZED,
   ICON_SIZE,
   ITEM_GAP,
@@ -69,6 +71,12 @@ import type { TabBarButtonProps, TabBarProps, TabBarTheme } from './types';
 type BarContextValue = {
   /** Live highlight position, in tab units. Fractional while scrubbing. */
   slideIndex: SharedValue<number>;
+  /**
+   * Highlight visibility, 0–1. Below 1 only when the bar has NO selection (an
+   * `activeIndex` that names no tab). Buttons fold it into their own active
+   * tint so a faded-out capsule leaves no glyph and no label lit.
+   */
+  highlightOpacity: SharedValue<number>;
   /** True while a scrub is in progress — the finger owns the highlight. */
   isDragging: SharedValue<boolean>;
   theme: TabBarTheme;
@@ -98,6 +106,8 @@ function TabBarBody({
   onIndexLongPress,
   theme: themeOverrides,
   haptics = true,
+  blur = true,
+  maxWidth,
   style,
   ...viewProps
 }: TabBarBodyProps) {
@@ -105,13 +115,53 @@ function TabBarBody({
   const { width: windowWidth } = useWindowDimensions();
   const minimized = useMinimizeState();
   const progress = minimized.progress;
+  const tabCount = Math.max(Children.count(children), 1);
+
+  // Is a tab selected at all?
+  //
+  // The two states this distinguishes are NOT the same thing, and collapsing
+  // them would silently kill the highlight for every router consumer:
+  //
+  //   - `activeIndex === undefined` is the FOCUS-DRIVEN path. The bar is not
+  //     the writer at all — each `TabBarButton` supplies `isFocused` and drives
+  //     the highlight itself (that is how the adapter keeps it correct through
+  //     deep links and back gestures), so from the bar's side there is always a
+  //     selection and the highlight is always visible.
+  //   - NO SELECTION is `activeIndex` being a number that names no tab:
+  //     negative, past the last tab, or fractional. Every consumer whose route
+  //     set is larger than its tab set produces one — a `usePathname()`-derived
+  //     index is -1 on every screen that is not a tab — and the highlight must
+  //     then be gone rather than parked outside the pill.
+  const hasSelection =
+    activeIndex === undefined ||
+    (Number.isInteger(activeIndex) && activeIndex >= 0 && activeIndex < tabCount);
+
   const slideIndex = useSharedValue(0);
+  // Seeded from the CURRENT state, not from 0: a bar that mounts with a
+  // selection must show its highlight on the first frame exactly as it always
+  // has, and one that mounts without a selection must never flash it.
+  const highlightOpacity = useSharedValue(hasSelection ? 1 : 0);
   const isDragging = useSharedValue(false);
   const lastTicked = useSharedValue(-1);
-  const tabCount = Math.max(Children.count(children), 1);
   const theme = useTabBarTheme(themeOverrides);
   const impact = useHaptics();
 
+  // The pill's OUTER width (the box the animated minimize inset is applied
+  // inside), and the single source of truth for it: the wrap's own layout, the
+  // highlight geometry and the `indexAtX` scrub worklet all derive from this one
+  // number. They have to, or a tap lands on a tab the highlight is not under —
+  // the exact failure `maxWidth` exists to prevent, since narrowing the bar from
+  // the outside with a `style` override moves only the pixels.
+  //
+  // Unconstrained it is what the stretched wrap already measures
+  // (`windowWidth - BAR_MARGIN * 2`), so an existing consumer's geometry is
+  // unchanged to the pixel. `maxWidth` is a ceiling, never a floor: on a window
+  // narrower than it, the bar stays full-bleed.
+  const barOuterWidth =
+    maxWidth === undefined
+      ? windowWidth - BAR_MARGIN * 2
+      : Math.min(windowWidth - BAR_MARGIN * 2, maxWidth);
+
   // Picker-style tick while the highlight crosses tab boundaries mid-drag.
   // `useHaptics` already no-ops on web, when the optional `expo-haptics` peer
   // is absent, and when a `BloomHapticsProvider` has haptics turned off — so
@@ -142,8 +192,26 @@ function TabBarBody({
     if (activeIndex === undefined) return;
     // While scrubbing the finger owns the highlight; never fight it.
     if (isDragging.value) return;
-    slideIndex.value = withSpring(activeIndex, SLIDE_SPRING);
-  }, [activeIndex, slideIndex, isDragging]);
+    if (!hasSelection) {
+      // Fade out where it stands. `slideIndex` is deliberately left alone: it
+      // is the highlight's POSITION, and there is no position that means
+      // "nowhere" — springing it to a sentinel would drag the capsule across
+      // the bar on its way out, dragging the active tint over every tab it
+      // passed. Visibility is the thing that changed, so visibility is the only
+      // thing that animates.
+      highlightOpacity.value = withTiming(0, HIGHLIGHT_FADE);
+      return;
+    }
+    // Coming back from fully hidden the capsule APPEARS at the new tab instead
+    // of travelling to it: a slide says "the selection moved from here to
+    // there", and while it was invisible there was no "here" — sliding from the
+    // 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);
+    highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
+  }, [activeIndex, hasSelection, 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
@@ -159,7 +227,13 @@ function TabBarBody({
         [0, MINIMIZED_INSET],
         Extrapolation.CLAMP,
       );
-      const barWidth = windowWidth - BAR_MARGIN * 2 - sideInset * 2;
+      // `event.x` is measured from the left edge of the view the detector is
+      // attached to — the animated pill itself, NOT the window and not the wrap
+      // around it. Its width is therefore the outer width minus the two
+      // animated margins, which is exactly what this computes, constrained or
+      // not. (Margins sit outside a view's own box, so x = 0 is the pill's left
+      // border edge either way.)
+      const barWidth = barOuterWidth - sideInset * 2;
       const itemWidth = (barWidth - ROW_PAD_H * 2) / tabCount;
       const raw = (x - ROW_PAD_H) / itemWidth - 0.5;
       return Math.min(Math.max(raw, 0), tabCount - 1);
@@ -168,8 +242,17 @@ function TabBarBody({
     const pan = Gesture.Pan()
       .activeOffsetX([-6, 6])
       .failOffsetY([-14, 14])
-      .onStart(() => {
+      .onStart((event) => {
         isDragging.value = true;
+        // Arming from the no-selection state: a hidden capsule has no position
+        // the finger can pick up, so it starts under the finger rather than at
+        // the index it faded out on — which would also make the first boundary
+        // tick fire against a phantom position. Mid-fade it is still visible,
+        // so it keeps the position it is at, exactly as it always has.
+        if (highlightOpacity.value === 0) {
+          slideIndex.value = indexAtX(event.x, progress.value);
+        }
+        highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
         lastTicked.value = Math.round(slideIndex.value);
         // Scrubbing is a deliberate bar interaction — surface the labels.
         setMinimized(minimized, 0);
@@ -206,7 +289,11 @@ function TabBarBody({
           return;
         }
         const index = Math.round(indexAtX(event.x, progress.value));
-        slideIndex.value = withSpring(index, SLIDE_SPRING);
+        // 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);
+        highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
         setMinimized(minimized, 0);
         runOnJS(selectIndex)(index);
       });
@@ -230,7 +317,7 @@ function TabBarBody({
 
     return Gesture.Race(pan, tap, longPress);
   }, [
-    windowWidth,
+    barOuterWidth,
     tabCount,
     selectIndex,
     hasLongPress,
@@ -239,6 +326,7 @@ function TabBarBody({
     isDragging,
     lastTicked,
     slideIndex,
+    highlightOpacity,
     minimized,
     progress,
   ]);
@@ -311,39 +399,70 @@ function TabBarBody({
       [0, MINIMIZED_INSET],
       Extrapolation.CLAMP,
     );
-    const barWidth = windowWidth - BAR_MARGIN * 2 - sideInset * 2;
+    // Same `barOuterWidth` the scrub worklet resolves an index from — see the
+    // note where it is computed.
+    const barWidth = barOuterWidth - sideInset * 2;
     const itemWidth = (barWidth - ROW_PAD_H * 2) / tabCount;
     return {
       height,
       width: itemWidth,
       borderRadius: height / 2,
       top: (barHeight - height) / 2,
+      // With no selection there is nothing to highlight, and the capsule has to
+      // stop being drawn: `slideIndex` is a position in tab units, so an
+      // out-of-range one is a real place — one item-width to the LEFT of the
+      // first tab, i.e. half outside the pill — not an absence.
+      opacity: highlightOpacity.value,
       transform: [{ translateX: ROW_PAD_H + itemWidth * slideIndex.value }],
     };
-  }, [progress, slideIndex, windowWidth, tabCount]);
+  }, [progress, slideIndex, highlightOpacity, barOuterWidth, tabCount]);
 
   // Shared with `useTabBarFootprint`, so a consumer accounting for the bar in
   // its own layout can never drift from where the bar actually sits.
   const bottomOffset = tabBarBottomGap(insets.bottom);
+
+  // 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
+  // centred once by layout at a definite width, and the pill's two equal
+  // margins keep it centred within that wrap at every point of the minimize
+  // animation — neither has to know about the other. Centring the animated view
+  // itself would instead mean `alignSelf: 'center'` on a node with no width of
+  // its own (its width comes from those margins), which Yoga then sizes from its
+  // CONTENT rather than from the constraint.
+  //
+  // Applied only when `maxWidth` is set: with no width and no `alignSelf` the
+  // wrap stretches, which is the original full-bleed behaviour.
+  const constrainedWrapStyle: ViewStyle | null =
+    maxWidth === undefined ? null : { width: barOuterWidth, alignSelf: 'center' };
   const barContext = useMemo(
-    () => ({ slideIndex, isDragging, theme, activeIndex, selectIndex }),
-    [slideIndex, isDragging, theme, activeIndex, selectIndex],
+    () => ({ slideIndex, highlightOpacity, isDragging, theme, activeIndex, selectIndex }),
+    [slideIndex, highlightOpacity, isDragging, theme, activeIndex, selectIndex],
   );
 
   return (
     <View {...viewProps} style={[styles.root, style]}>
-      {/* Progressive blur rising from the screen's bottom edge behind the pill. */}
-      <Blur
-        direction="bottom"
-        style={{
-          position: 'absolute',
-          left: 0,
-          right: 0,
-          bottom: 0,
-          height: bottomOffset + EXPANDED_HEIGHT + BLUR_BLEED,
-        }}
-      />
-      <View style={[styles.barWrap, { marginBottom: bottomOffset }]}>
+      {/* Progressive blur rising from the screen's bottom edge behind the pill.
+          Rendered CONDITIONALLY, and as nothing at all when off: the band is
+          full-bleed and 114pt tall at a zero bottom inset, so it blurs whatever
+          a screen floats near the bottom edge (a scrubber, a FAB), and leaving
+          an empty absolutely-positioned view behind would keep a node — and a
+          rect — that exists to do nothing. Stays full-bleed under `maxWidth`:
+          it is the screen-edge scrim content dissolves into, not part of the
+          pill. */}
+      {blur !== false && (
+        <Blur
+          direction="bottom"
+          intensity={typeof blur === 'object' ? blur.intensity : undefined}
+          style={{
+            position: 'absolute',
+            left: 0,
+            right: 0,
+            bottom: 0,
+            height: bottomOffset + EXPANDED_HEIGHT + BLUR_BLEED,
+          }}
+        />
+      )}
+      <View style={[styles.barWrap, { marginBottom: bottomOffset }, constrainedWrapStyle]}>
         <GestureDetector gesture={gesture}>
           <Animated.View style={barStyle}>
             <Surface theme={theme} style={shapeStyle} />
@@ -381,6 +500,7 @@ function TabBarButtonBody({
   const standaloneTheme = useTabBarTheme();
   const theme = bar?.theme ?? standaloneTheme;
   const slideIndex = bar?.slideIndex;
+  const highlightOpacity = bar?.highlightOpacity;
   // The two paths meet here: an explicit `isFocused` (router adapter) wins;
   // otherwise focus comes from the bar's controlled `activeIndex`.
   const focused = isFocused ?? (bar?.activeIndex === index);
@@ -399,29 +519,35 @@ function TabBarButtonBody({
   // Tint follows the sliding highlight, not navigation focus: whatever the pill
   // is over lights up — live while scrubbing, traveling on taps. Without a bar
   // there is nothing to follow, so it falls back to plain focus.
+  //
+  // Scaled by the highlight's own visibility, so a bar with NO selection leaves
+  // nothing lit: distance alone would keep the tab the capsule faded out on
+  // fully tinted, which is the same bug as a stray capsule wearing a different
+  // hat — a tab that looks selected while nothing is.
   // (Deps: see the CRITICAL note in `TabBarBody`.)
-  const activeGlyphStyle = useAnimatedStyle(
-    () => ({
-      opacity: slideIndex ? 1 - Math.min(Math.abs(slideIndex.value - index), 1) : focused ? 1 : 0,
-    }),
-    [slideIndex, index, focused],
-  );
+  const activeGlyphStyle = useAnimatedStyle(() => {
+    if (!slideIndex || !highlightOpacity) return { opacity: focused ? 1 : 0 };
+    const proximity = 1 - Math.min(Math.abs(slideIndex.value - index), 1);
+    return { opacity: highlightOpacity.value * proximity };
+  }, [slideIndex, highlightOpacity, index, focused]);
 
-  const labelStyle = useAnimatedStyle(
-    () => ({
-      opacity: interpolate(progress.value, [0, 0.4], [1, 0], Extrapolation.CLAMP),
-      color: slideIndex
-        ? interpolateColor(
-            Math.min(Math.abs(slideIndex.value - index), 1),
-            [0, 1],
-            [theme.activeTint, theme.inactiveTint],
-          )
-        : focused
-          ? theme.activeTint
-          : theme.inactiveTint,
-    }),
-    [progress, slideIndex, index, focused, theme],
-  );
+  const labelStyle = useAnimatedStyle(() => {
+    const opacity = interpolate(progress.value, [0, 0.4], [1, 0], Extrapolation.CLAMP);
+    if (!slideIndex || !highlightOpacity) {
+      return { opacity, color: focused ? theme.activeTint : theme.inactiveTint };
+    }
+    // Same quantity as the glyph crossfade above, so a label can never disagree
+    // with the icon it sits under.
+    const proximity = 1 - Math.min(Math.abs(slideIndex.value - index), 1);
+    return {
+      opacity,
+      color: interpolateColor(
+        highlightOpacity.value * proximity,
+        [0, 1],
+        [theme.inactiveTint, theme.activeTint],
+      ),
+    };
+  }, [progress, slideIndex, highlightOpacity, index, focused, theme]);
 
   // Height is animated EXPLICITLY (not derived from children) so the icon stays
   // perfectly centered every frame — layout-driven sizing lags a frame behind
@@ -449,7 +575,13 @@ function TabBarButtonBody({
       onPress={(event) => {
         // The bar's GestureDetector normally consumes touches; this still fires
         // for assistive-technology activation (VoiceOver) and keyboard focus.
-        if (bar) bar.slideIndex.value = withSpring(index, SLIDE_SPRING);
+        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);
+          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

package/src/tab-bar/shared.ts

@@ -79,6 +79,18 @@ export function tabBarBottomGap(bottomInset: number): number {
  */
 export const SLIDE_SPRING = { duration: 420, dampingRatio: 0.82 };
 
+/**
+ * Fade for the highlight coming and going when the selection does — an
+ * `activeIndex` that names no tab (see `TabBarProps.activeIndex`).
+ *
+ * A timing, not a spring, and deliberately shorter than {@link SLIDE_SPRING}:
+ * appearing and disappearing is a change of STATE, not a movement, so it must
+ * not read as a second animation racing the slide. The capsule fades where it
+ * stands — moving it out of view instead would drag it the length of the bar on
+ * its way out and sweep the active tint across every tab it passed.
+ */
+export const HIGHLIGHT_FADE = { duration: 160 };
+
 /**
  * How long a press must be held before `onIndexLongPress` fires.
  *

package/src/tab-bar/types.ts

@@ -78,6 +78,18 @@ export type TabBarProps = ViewProps & {
    * highlight and springs it here whenever this changes. Use this when there is
    * no router in play; the router adapter uses the per-button `isFocused` path
    * instead (see {@link TabBarButtonProps.isFocused}) and must NOT pass this.
+   *
+   * An index that names NO tab — negative, past the last tab, or fractional —
+   * means no selection: the highlight fades out where it stands and no tab is
+   * left tinted. Pass one whenever the current screen is not a tab; an index
+   * derived from the route (`TABS.findIndex(…)`) is `-1` on every such screen
+   * and is correct as-is. Returning to a real index fades the highlight back in
+   * AT that tab rather than sliding to it — while it was invisible there was no
+   * position to travel from — and scrubbing still arms it under the finger.
+   *
+   * OMITTING this prop is a different thing entirely and does not hide
+   * anything: that is the focus-driven path, where each button drives the
+   * highlight from its own `isFocused`.
    */
   activeIndex?: number;
   /**
@@ -107,6 +119,44 @@ export type TabBarProps = ViewProps & {
    * optional `expo-haptics` peer is absent.
    */
   haptics?: boolean;
+  /**
+   * The progressive blur rising from the bottom edge of the screen behind the
+   * pill. Defaults to `true`; `{ intensity }` tunes its strength.
+   *
+   * Pass `false` to remove it entirely — no blur, and no node left behind. The
+   * band is tall (the bar's own bottom gap plus its expanded height plus the
+   * bleed above it, 114pt at a zero bottom inset) and full-bleed, so anything a
+   * screen floats near the bottom edge — a video scrubber, a FAB — sits INSIDE
+   * it and is blurred. That cannot be undone from the outside: `zIndex` only
+   * orders siblings within one stacking context, and a screen's FAB is inside
+   * an earlier sibling of the bar's host, so no z-order a consumer can write
+   * lifts it above this band. Turning the blur off is the only fix that does
+   * not also change where the FAB paints relative to everything else.
+   *
+   * On native the band is ten stacked `expo-blur` layers plus a tail gradient;
+   * on web it is one masked `backdrop-filter`. `false` skips both.
+   */
+  blur?: boolean | { intensity?: number };
+  /**
+   * Maximum width of the pill, in points. No default — omit it and the bar
+   * spans the window exactly as it always has.
+   *
+   * A CEILING, never a floor: on a window narrower than this the bar keeps its
+   * full-bleed width, so a phone layout is untouched by any value big enough to
+   * matter on a tablet. When it binds, the pill is constrained to this width and
+   * CENTRED, and the ITEM geometry follows it — the item width, the sliding
+   * highlight's position and the tap/scrub hit-testing all derive from the same
+   * constrained width, so a tap still lands on the tab it is visibly over.
+   *
+   * That last part is why this cannot be done from the outside. Narrowing the
+   * bar with a `style` override moves the pixels only: the highlight and the
+   * scrub worklet would still divide the WINDOW width by the tab count, leaving
+   * the highlight sized and positioned for a bar that is no longer there. On an
+   * iPad the unconstrained bar is the reason to reach for this at all — 810pt at
+   * 11" portrait, 1342pt in landscape, leaving 21pt glyphs adrift in cells
+   * hundreds of points wide.
+   */
+  maxWidth?: number;
 };
 
 export type TabBarButtonProps = PressableProps & {