@oxyhq/bloom 1.9.2 → 1.10.0

package/src/index.web.ts

@@ -158,6 +158,13 @@ export type {
   SurfacePromptOptions,
 } from './surfaces/index.web';
 export * from './button/index.web';
+export {
+  EDGE_GAP,
+  windowEdgeGap,
+  BottomEdgeProvider,
+  useBottomEdgeInset,
+  useClaimBottomEdge,
+} from './layout';
 export { Fab } from './fab/index.web';
 export type { FabProps, FabVariant, FabSize, FabPlacement } from './fab/index.web';
 export { FrostedIconButton } from './frosted-icon-button/index.web';

package/src/layout/bottom-edge.tsx

@@ -0,0 +1,162 @@
+/**
+ * The bottom edge's OCCUPANCY — how much of it is already claimed by a floating
+ * surface, so the next surface can stack above it instead of underneath it.
+ *
+ * ## The problem
+ *
+ * `windowEdgeGap` tells a surface where the window edge is. It cannot tell it
+ * that a tab bar is already parked there. Nothing could, so nothing did: Bloom's
+ * `Fab` anchored itself 16px off the edge and landed squarely behind the
+ * floating tab bar, and every app that hit it patched around Bloom instead —
+ * Mention grew a `BottomBarAwareFab` that read `useTabBarFootprint()` and lifted
+ * the FAB by hand, on web only, leaving native broken across seven screens.
+ *
+ * A z-index cannot rescue that placement either. The tab bar host is the last
+ * sibling of the app shell, so it paints above every descendant regardless of
+ * what they claim; the FAB has to be somewhere ELSE, not merely on top.
+ *
+ * ## The model
+ *
+ * A surface that parks at the bottom edge CLAIMS its footprint. A surface that
+ * wants to avoid it READS the total and offsets itself. Neither one imports the
+ * other, so a consumer composes them in any combination — a tab bar with no FAB,
+ * a FAB with no tab bar, both, or a third surface written later — and the
+ * geometry still resolves.
+ *
+ * Claims combine with MAX, not sum. Every claim is measured from the same window
+ * 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.
+ *
+ * ## Why an external store
+ *
+ * The claim set is mutable state living outside React. Reading it in a memoized
+ * position is exactly the stale-read the React Compiler produces, so it is read
+ * through `useSyncExternalStore` and never touched directly. The store is
+ * created per provider (not at module scope) so tests, and any app mounting two
+ * roots, stay isolated from each other.
+ */
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useState,
+  useSyncExternalStore,
+  type PropsWithChildren,
+} from 'react';
+
+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.
+   */
+  getInset: () => number;
+  claim: (id: string, height: number) => void;
+  release: (id: string) => void;
+}
+
+function createBottomEdgeStore(): BottomEdgeStore {
+  const claims = new Map<string, number>();
+  const listeners = new Set<() => void>();
+  let inset = 0;
+
+  const recompute = () => {
+    let next = 0;
+    for (const height of claims.values()) {
+      if (height > next) next = height;
+    }
+    // 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;
+    for (const listener of listeners) listener();
+  };
+
+  return {
+    subscribe(onChange) {
+      listeners.add(onChange);
+      return () => {
+        listeners.delete(onChange);
+      };
+    },
+    getInset: () => inset,
+    claim(id, height) {
+      if (claims.get(id) === height) return;
+      claims.set(id, height);
+      recompute();
+    },
+    release(id) {
+      if (!claims.delete(id)) return;
+      recompute();
+    },
+  };
+}
+
+const BottomEdgeContext = createContext<BottomEdgeStore | null>(null);
+
+/**
+ * Wrap the app once — `BloomProvider` already does. Rendering a second one
+ * scopes a nested subtree to its own claims, which is a real (if rare) thing to
+ * want: a bottom-edge surface inside a full-screen modal should not be offset by
+ * the tab bar the modal is covering.
+ */
+export function BottomEdgeProvider({ children }: PropsWithChildren) {
+  const [store] = useState(createBottomEdgeStore);
+  return <BottomEdgeContext.Provider value={store}>{children}</BottomEdgeContext.Provider>;
+}
+
+BottomEdgeProvider.displayName = 'BottomEdgeProvider';
+
+// Stable module-scope identities for the no-provider path. Fresh closures here
+// would resubscribe `useSyncExternalStore` on every render.
+const NO_SUBSCRIPTION = () => () => {};
+const NO_INSET = () => 0;
+
+/**
+ * How much of the bottom edge is already occupied, in px.
+ *
+ * Add it to whatever offset the surface would otherwise use:
+ *
+ * ```tsx
+ * const occupied = useBottomEdgeInset();
+ * <View style={{ position: 'absolute', bottom: windowEdgeGap(insets.bottom) + occupied }} />
+ * ```
+ *
+ * `0` outside a provider, and `0` on the first commit even inside one — a claim
+ * registers in an effect, so a reader mounted in the same commit as its claimant
+ * settles one frame later. That is a layout offset rather than a measurement, so
+ * the settle is invisible in practice; nothing here waits on a real layout pass.
+ */
+export function useBottomEdgeInset(): number {
+  const store = useContext(BottomEdgeContext);
+  return useSyncExternalStore(
+    store?.subscribe ?? NO_SUBSCRIPTION,
+    store?.getInset ?? NO_INSET,
+    store?.getInset ?? NO_INSET,
+  );
+}
+
+/**
+ * Claim `height` px of 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.
+ *
+ * A no-op outside a provider, so a surface stays usable standalone.
+ */
+export function useClaimBottomEdge(height: number): void {
+  const store = useContext(BottomEdgeContext);
+  const id = useId();
+
+  useEffect(() => {
+    if (!store) return;
+    store.claim(id, height);
+    return () => store.release(id);
+  }, [store, id, height]);
+}

package/src/layout/edge.ts

@@ -0,0 +1,59 @@
+/**
+ * How far a floating surface sits from a window edge.
+ *
+ * ## The rule this file encodes
+ *
+ * A floating surface CLEARS THE OS'S RESERVED BAND IN FULL. The safe-area inset
+ * is the space the platform has reserved for its own affordance — the iOS home
+ * indicator, the Android gesture handle — and a surface that sits inside it is
+ * sitting on top of a system control.
+ *
+ * Bloom used to answer this question three times, differently:
+ *
+ *   - a detached `BottomSheet`  `insets.bottom + 16`
+ *   - the toast stack           `bottom > 0 ? bottom + 8 : 16`
+ *   - the floating tab bar      `max(bottom - 16, 12)`
+ *
+ * The tab bar was the only one that SUBTRACTED, and subtracting is what put it
+ * on the Android gesture handle: a gesture-navigation device reserves ~24dp, the
+ * bar absorbed 16 of it, hit its own 12dp floor, and landed inside the band with
+ * the handle drawn through it. The other two were never reachable by that bug
+ * because they add.
+ *
+ * One function now answers it for all three, and the additive `gap` reproduces
+ * the sheet and the toast exactly — only the tab bar moves.
+ */
+
+/**
+ * Breathing room from a window edge where the platform reserves nothing at all
+ * (web, a browser with no visual viewport inset, an Android device with the
+ * gesture bar hidden).
+ *
+ * It is also the FLOOR for every surface: a small-but-nonzero inset must never
+ * pull a surface closer to the edge than a device reporting no inset would.
+ */
+export const EDGE_GAP = 16;
+
+/**
+ * The distance a floating surface holds off a window edge, given that edge's
+ * safe-area inset.
+ *
+ * `gap` is the surface's own breathing room ON TOP of the reserved band, not an
+ * allowance to spend inside it — a bigger `gap` floats the surface further from
+ * the affordance, never closer. Pass `0` for a surface that should hug the safe
+ * area (the tab bar), a positive number for one that should stand clear of it (a
+ * detached sheet, a toast stack).
+ *
+ * ```ts
+ * windowEdgeGap(insets.bottom)      // 34pt iOS · 24dp Android · 16 web
+ * windowEdgeGap(insets.bottom, 16)  // 50pt iOS · 40dp Android · 16 web
+ * ```
+ *
+ * Anything laying out AROUND such a surface wants its total footprint (this gap
+ * plus the surface's own height) and must get it from the surface — never by
+ * adding `insets.bottom` to a hardcoded height, which double-counts the inset
+ * because the inset is already folded in here.
+ */
+export function windowEdgeGap(inset: number, gap = 0): number {
+  return Math.max(inset + gap, EDGE_GAP);
+}

package/src/layout/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Window-edge geometry, shared by every floating surface.
+ *
+ * `edge` answers "how far from the edge"; `bottom-edge` answers "what is already
+ * parked there". A surface that floats at the bottom needs both.
+ */
+export { EDGE_GAP, windowEdgeGap } from './edge';
+export { BottomEdgeProvider, useBottomEdgeInset, useClaimBottomEdge } from './bottom-edge';

package/src/provider/BloomProvider.tsx

@@ -34,6 +34,7 @@
 import type { ReactNode } from 'react';
 
 import { GlassBlurTargetProvider } from '../glass/blur-target';
+import { BottomEdgeProvider } from '../layout/bottom-edge';
 import { ImageResolverProvider, type ImageResolver } from '../image-resolver';
 import { BloomHapticsProvider } from '../hooks/use-haptics';
 import { TabBarMinimizeProvider } from '../tab-bar/context';
@@ -67,7 +68,16 @@ export function BloomProvider({
               provider already does with `children`.
             */}
             <GlassBlurTargetProvider>
-              <TabBarMinimizeProvider>{children}</TabBarMinimizeProvider>
+              {/*
+                The bottom edge's claim registry. Also a provider, not an outlet:
+                it renders nothing and holds only the set of surfaces currently
+                parked at the bottom edge, so a tab bar can publish its footprint
+                and a FAB or a toast stack can read it without either importing
+                the other.
+              */}
+              <BottomEdgeProvider>
+                <TabBarMinimizeProvider>{children}</TabBarMinimizeProvider>
+              </BottomEdgeProvider>
             </GlassBlurTargetProvider>
           </BloomHapticsProvider>
         </ScrollRestorationProvider>

package/src/tab-bar/TabBarBase.tsx

@@ -38,6 +38,8 @@ import Animated, {
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
 import { useHaptics } from '../hooks/use-haptics';
+import { useClaimBottomEdge } from '../layout/bottom-edge';
+import { windowEdgeGap } from '../layout/edge';
 import type { ProgressiveBlurProps } from '../progressive-blur/types';
 import { setMinimized, useMinimizeState } from './context';
 import {
@@ -56,7 +58,6 @@ import {
   MINIMIZED_INSET,
   ROW_PAD_H,
   SLIDE_SPRING,
-  tabBarBottomGap,
   useTabBarTheme,
   type TabBarGlyphProps,
   type TabBarSurfaceProps,
@@ -419,7 +420,15 @@ function TabBarBody({
 
   // 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);
+  const bottomOffset = windowEdgeGap(insets.bottom);
+
+  // 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);
 
   // 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

package/src/tab-bar/shared.ts

@@ -51,26 +51,6 @@ export const BLUR_BLEED = 44;
 /** Label type size. Small by design — the icon carries the meaning. */
 export const LABEL_FONT_SIZE = 9.5;
 
-/**
- * How much of the bottom safe-area inset the bar's own gap absorbs. The pill
- * already floats clear of the content, so sitting the FULL inset below it
- * strands it in the middle of the screen on a home-indicator device.
- */
-const SAFE_AREA_ABSORBED = 16;
-/** Gap floor, for a device (or a browser) reporting no bottom inset at all. */
-const MIN_BOTTOM_GAP = 12;
-
-/**
- * Vertical gap between the bottom of the pill and the bottom of the window.
- *
- * The safe-area inset is folded in HERE, which is why anything accounting for
- * the bar in its own layout must go through `useTabBarFootprint` (which derives
- * its number from this same function) rather than adding `insets.bottom` to a
- * hardcoded height — that double-counts the inset.
- */
-export function tabBarBottomGap(bottomInset: number): number {
-  return Math.max(bottomInset - SAFE_AREA_ABSORBED, MIN_BOTTOM_GAP);
-}
 
 /**
  * Slide spring: interruptible by design — rapid tab-hopping retargets with

package/src/tab-bar/use-footprint.ts

@@ -13,7 +13,8 @@
  */
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
-import { EXPANDED_HEIGHT, tabBarBottomGap } from './shared';
+import { windowEdgeGap } from '../layout/edge';
+import { EXPANDED_HEIGHT } from './shared';
 
 /**
  * The vertical space the tab bar OCCUPIES above the bottom of the window, in
@@ -30,15 +31,19 @@ import { EXPANDED_HEIGHT, tabBarBottomGap } from './shared';
  * const footprint = useTabBarFootprint();
  *
  * <Animated.ScrollView contentContainerStyle={{ paddingBottom: footprint + 12 }} />
- * <Fab style={{ position: 'absolute', right: 16, bottom: footprint }} />
  * ```
  *
- * The value ALREADY INCLUDES the bottom safe-area inset — the bar folds the
- * inset into its own gap, so this is measured from the true window edge, not
- * from the safe area. Never write `footprint + insets.bottom`: that counts the
- * home indicator twice and strands a visible band of dead space under every
- * list (114px accounted for a 76px bar on an iOS device or PWA). Whatever you
- * add on top is your own clearance — never the inset a second time.
+ * A FAB no longer needs this hook at all — `Fab` reads the bottom edge's
+ * occupancy itself (see `layout/bottom-edge`), which is what the bar publishes
+ * this exact number to. Reach for the hook when laying out something that is not
+ * a Bloom surface.
+ *
+ * The value ALREADY INCLUDES the bottom safe-area inset — `windowEdgeGap` clears
+ * the OS's reserved band in full — so this is measured from the true window
+ * edge, not from the safe area. Never write `footprint + insets.bottom`: that
+ * counts the home indicator twice and strands a visible band of dead space under
+ * every list. Whatever you add on top is your own clearance, never the inset a
+ * second time.
  *
  * It is the EXPANDED height, deliberately. The bar minimizes while scrolling
  * down and re-expands on the way up, so measuring the minimized height would
@@ -46,5 +51,9 @@ import { EXPANDED_HEIGHT, tabBarBottomGap } from './shared';
  */
 export function useTabBarFootprint(): number {
   const insets = useSafeAreaInsets();
-  return tabBarBottomGap(insets.bottom) + EXPANDED_HEIGHT;
+  // Gap 0: the bar hugs the safe area, the tightest any Bloom surface floats. It
+  // is a compact pill, not a panel, and a detached-sheet-sized gap under it would
+  // strand it mid-screen. It used to ABSORB 16px of the inset and clamp at a 12px
+  // floor, which is how it ended up drawn through the Android gesture handle.
+  return windowEdgeGap(insets.bottom) + EXPANDED_HEIGHT;
 }