@oxy.so/bloom 2.12.4 → 3.0.1

package/src/page-header/PageHeader.tsx

@@ -16,32 +16,65 @@ import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
 
 import { Button } from '../button';
 import { BUTTON_SHADOW, mixColor, resolveButtonRamps } from '../button/shared';
+import { ButtonGroupItem } from '../button-group';
+import { ControlSurface } from '../control-surface';
+import { GlassIsland } from '../glass';
 import { RiArrowLeftLine } from '../icons/remix';
+import { useClaimTopEdge, useScrollOffset } from '../layout';
 import { BREAKPOINTS } from '../styles/breakpoints';
 import { WEB_POSITION_STICKY, type WebCssStyle } from '../styles/web-view-style';
 import { Z_INDEX } from '../styles/z-index';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
+import { EdgeScrim, SCRIM_TAIL_RATIO } from './EdgeScrim';
 import type { PageHeaderProps } from './types';
 
 /**
- * `PageHeader`: a screen's top bar — back button, title (+ subtitle), leading
- * node and actions, composed from the vocabulary Bloom's template headers and
- * the settings modal's compact header use:
+ * `PageHeader`: a screen's top chrome.
  *
- *   bar         min-height 56, side inset 16 (below `sm`) / 24, gap 8
- *   back        secondary medium icon button (36, pill, shadow-xs), RiArrowLeftLine 20
- *   start group gap 6 (template header `gap-1.5`)
- *   title       headline-medium, text-primary, px 4 (template `px-1`), one line
- *   subtitle    body-2-regular, text-secondary (neutral-500), one line
- *   actions     gap 10 (template `gap-2.5`)
- *   background  background/full — card / dark neutral-925
- *   separator   1px separator-border — neutral-200 / dark neutral-800
- *   shadow      shadow-xs, fading in with scroll
+ * ── THE DEFAULT IS FLOATING ─────────────────────────────────────────────────
  *
- * Scroll-linked, not timed: border (`auto`), background (`transparent`) and
- * shadow (and, when `transparent`, the title) interpolate over `[0, scrollThreshold]` of `scrollY` — the caller's
- * shared value, else `window.scrollY` on web. No press scale.
+ * Not a bar. The back button sits in its OWN translucent capsule, the actions
+ * the consumer declared as a group share ONE island, the title floats between
+ * them, and the whole thing ends in a vertical gradient rather than a hairline.
+ * Content passes under it.
+ *
+ * Three things follow from that, and each is a prop rather than an assumption:
+ *
+ *   `presentation`  `floating` | `bar`      — islands, or Bloom's flat strip
+ *   `placement`     `inline` | `overlay`    — who reserves the space
+ *   `scrim`/`titleReveal`                   — the edge effect and the title,
+ *                                             separately
+ *
+ * The last pair used to be one flag. `transparent` faded the background in with
+ * scroll AND hid the title, which is right for a header over a hero photo and
+ * wrong everywhere else — and a header that inherited it got both behaviours
+ * whether or not it wanted either. They are two questions with two answers now.
+ *
+ * ── THE ISLANDS ARE THE CONSUMER'S GROUPING ─────────────────────────────────
+ *
+ * The header never infers grouping by reading its children's types. The
+ * `actions` slot is wrapped in a `ControlSurface` with `material: 'glass'`, so
+ * a `ButtonGroup` placed there becomes one island with no prop written on it,
+ * and two `ButtonGroup`s become two islands. That is a declaration the consumer
+ * makes, which is the only way the header can be right about which actions
+ * belong together.
+ *
+ *              floating                      bar
+ *   chrome     islands + gradient            opaque strip + hairline + shadow
+ *   back       36 capsule, glass             secondary medium icon `Button`
+ *   title      headline-medium, no capsule   headline-medium
+ *   scroll     drives the scrim              drives border, background, shadow
+ *
+ * The geometry both share:
+ *
+ *   bar         min-height 56, side inset 16 (below `sm`) / 24
+ *   islands     36 tall (34 + hairline), 8 apart
+ *   title       headline-medium, text-primary, one line
+ *   subtitle    body-2-regular, secondary, one line
+ *
+ * Scroll-linked, not timed: everything interpolates over `[0, scrollThreshold]`
+ * of the resolved scroll offset. No press scale.
  */
 
 const BAR_HEIGHT = 56;
@@ -50,9 +83,26 @@ const INSET_WIDE = 24;
 const START_GAP = 6;
 const ROW_GAP = 8;
 const ACTIONS_GAP = 10;
+const FLOATING_ACTIONS_GAP = 8;
 const TITLE_PADDING = 4;
 const DEFAULT_THRESHOLD = 20;
 
+/**
+ * The narrowest the centred title may be squeezed to before it stops yielding
+ * to the two sides.
+ *
+ * Without a floor the centring inset is `max(startWidth, endWidth)` applied to
+ * BOTH sides, so on a narrow container two wide sides can ask for more than the
+ * container has — and `left + right > width` is a box of negative width, which
+ * on web collapses the title to nothing and on native logs a layout error. The
+ * title stops centring before that happens and simply sits off-centre, which is
+ * the lesser of the two wrongs and the one a reader can still use.
+ */
+const MIN_CENTERED_TITLE_WIDTH = 96;
+
+/** 44pt touch target from a 36pt capsule. Only for an island that stands alone. */
+const CAPSULE_HIT_SLOP = { top: 4, bottom: 4, left: 4, right: 4 } as const;
+
 const NO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 };
 
 function PageHeaderComponent({
@@ -60,12 +110,17 @@ function PageHeaderComponent({
   subtitle,
   titleAlign = 'start',
   headingLevel = 1,
+  titleReveal = 'always',
+  presentation = 'floating',
+  placement = 'inline',
   onBack,
   backLabel = 'Back',
   leading,
   actions,
   border = 'auto',
   transparent = false,
+  scrim = 'auto',
+  scrimColor,
   scrollY: externalScrollY,
   scrollThreshold = DEFAULT_THRESHOLD,
   sticky = true,
@@ -74,12 +129,34 @@ function PageHeaderComponent({
   testID,
 }: PageHeaderProps) {
   const isWeb = Platform.OS === 'web';
+  const floating = presentation === 'floating';
+  const overlay = placement === 'overlay';
   const theme = useTheme();
-  const { width } = useWindowDimensions();
   const insets = useContext(SafeAreaInsetsContext) ?? NO_INSETS;
   const padTop = (safeArea ?? !isWeb) ? insets.top : 0;
+
+  // The header sizes itself against its CONTAINER, not the window: a desktop
+  // split view puts a 380px panel next to a 1200px one, and a window-derived
+  // inset gives the narrow panel the wide padding. The window is only the seed
+  // for the first frame, before `onLayout` has reported.
+  const windowWidth = useWindowDimensions().width;
+  const [measuredWidth, setMeasuredWidth] = useState(0);
+  const [measuredHeight, setMeasuredHeight] = useState(0);
+  const width = measuredWidth || windowWidth;
+  const height = measuredHeight || padTop + BAR_HEIGHT;
   const sideInset = width >= BREAKPOINTS.sm ? INSET_WIDE : INSET_COMPACT;
 
+  const onContainerLayout = (e: LayoutChangeEvent) => {
+    setMeasuredWidth(e.nativeEvent.layout.width);
+    setMeasuredHeight(e.nativeEvent.layout.height);
+  };
+
+  // An overlaying header occupies no layout, so it declares what it covers and
+  // the content reads it back. Measured rather than computed: a second title
+  // line, an enlarged font or a notch all move it, and every one of those is a
+  // case a constant was written to survive and does not.
+  useClaimTopEdge(overlay ? height : 0);
+
   const paint = useMemo(() => {
     const { neutral } = resolveButtonRamps(theme);
     return theme.isDark
@@ -97,19 +174,26 @@ function PageHeaderComponent({
         };
   }, [theme]);
 
+  // ── The scroll owner ──────────────────────────────────────────────────────
+  //
+  // Prop, then the nearest `ScrollOffsetProvider`, then the document on web.
+  // The context step is the one that matters for a Bloom composition: without
+  // it a header inside a scrolling panel followed `window.scrollY`, which on a
+  // desktop shell never moves, so the header looked deliberately inert.
+  const contextScrollY = useScrollOffset();
   const internalScrollY = useSharedValue(0);
-  const scrollY = externalScrollY ?? internalScrollY;
+  const scrollY = externalScrollY ?? contextScrollY ?? internalScrollY;
+  const followsWindow = !externalScrollY && !contextScrollY;
 
-  // Web fallback: the document is the scroll owner, as in the fleet headers.
   useEffect(() => {
-    if (!isWeb || externalScrollY || typeof window === 'undefined') return undefined;
+    if (!isWeb || !followsWindow || typeof window === 'undefined') return undefined;
     const onScroll = () => {
       internalScrollY.value = window.scrollY;
     };
     onScroll();
     window.addEventListener('scroll', onScroll, { passive: true });
     return () => window.removeEventListener('scroll', onScroll);
-  }, [isWeb, externalScrollY, internalScrollY]);
+  }, [isWeb, followsWindow, internalScrollY]);
 
   const threshold = Math.max(1, scrollThreshold);
 
@@ -123,12 +207,23 @@ function PageHeaderComponent({
       : 1,
   }), [scrollY, threshold, transparent]);
 
-  // Over media the title would sit on the photo; it arrives with the bar.
+  const scrimStyle = useAnimatedStyle(() => ({
+    opacity:
+      scrim === 'always'
+        ? 1
+        : scrim === 'none'
+          ? 0
+          : interpolate(scrollY.value, [0, threshold], [0, 1], Extrapolation.CLAMP),
+  }), [scrollY, threshold, scrim]);
+
+  // Separate from the background's: a header can be transparent and still name
+  // its screen, and one over a hero photo can do the opposite.
   const titleStyle = useAnimatedStyle(() => ({
-    opacity: transparent
-      ? interpolate(scrollY.value, [0, threshold], [0, 1], Extrapolation.CLAMP)
-      : 1,
-  }), [scrollY, threshold, transparent]);
+    opacity:
+      titleReveal === 'always'
+        ? 1
+        : interpolate(scrollY.value, [0, threshold], [0, 1], Extrapolation.CLAMP),
+  }), [scrollY, threshold, titleReveal]);
 
   const borderStyle = useAnimatedStyle(() => ({
     opacity:
@@ -139,14 +234,25 @@ function PageHeaderComponent({
           : interpolate(scrollY.value, [0, threshold], [0, 1], Extrapolation.CLAMP),
   }), [scrollY, threshold, border]);
 
-  // Centred title: inset it by the wider side so it sits on the bar's centre
-  // whatever the two sides hold.
-  const [startWidth, setStartWidth] = useState(0);
-  const [endWidth, setEndWidth] = useState(0);
+  // ── Centring ──────────────────────────────────────────────────────────────
+  //
+  // Inset the title by the WIDER side so it sits on the container's centre
+  // whatever the two sides hold. A slot that is not rendered contributes 0
+  // rather than its last measurement: `onLayout` does not fire on unmount, so a
+  // header that loses its actions would otherwise keep centring around them.
+  const [startMeasure, setStartMeasure] = useState(0);
+  const [endMeasure, setEndMeasure] = useState(0);
   const centered = titleAlign === 'center';
-  const onStartLayout = (e: LayoutChangeEvent) => setStartWidth(e.nativeEvent.layout.width);
-  const onEndLayout = (e: LayoutChangeEvent) => setEndWidth(e.nativeEvent.layout.width);
-  const centerInset = Math.max(startWidth, endWidth) + ROW_GAP;
+  const hasStart = onBack != null || leading != null;
+  const hasEnd = actions != null;
+  const startWidth = hasStart ? startMeasure : 0;
+  const endWidth = hasEnd ? endMeasure : 0;
+  const onStartLayout = (e: LayoutChangeEvent) => setStartMeasure(e.nativeEvent.layout.width);
+  const onEndLayout = (e: LayoutChangeEvent) => setEndMeasure(e.nativeEvent.layout.width);
+  const centerInset = Math.min(
+    Math.max(startWidth, endWidth) + ROW_GAP,
+    Math.max(0, (width - 2 * sideInset - MIN_CENTERED_TITLE_WIDTH) / 2),
+  );
 
   const titleBlock =
     title != null || subtitle != null ? (
@@ -187,14 +293,61 @@ function PageHeaderComponent({
       </Animated.View>
     ) : null;
 
+  const backButton = onBack ? (
+    floating ? (
+      // Its own island: a back action is not a member of the page's action
+      // group, and a `role="group"` of one is noise a screen reader reads out.
+      // The control inside is a `ButtonGroupItem` because that is Bloom's
+      // island-aware control — it reads the material `GlassIsland` publishes
+      // and paints flush — rather than a second implementation of the same
+      // hover, press, focus and disabled behaviour.
+      <GlassIsland testID={testID ? `${testID}-back-island` : undefined}>
+        <ButtonGroupItem
+          iconOnly
+          leadingIcon={RiArrowLeftLine}
+          accessibilityLabel={backLabel}
+          onPress={onBack}
+          hitSlop={CAPSULE_HIT_SLOP}
+          testID={testID ? `${testID}-back` : undefined}
+        />
+      </GlassIsland>
+    ) : (
+      <Button
+        variant="secondary"
+        size="medium"
+        iconOnly
+        leadingIcon={RiArrowLeftLine}
+        accessibilityLabel={backLabel}
+        onPress={onBack}
+        testID={testID ? `${testID}-back` : undefined}
+      />
+    )
+  ) : null;
+
   const containerWeb: WebCssStyle | null =
-    isWeb && sticky ? { position: WEB_POSITION_STICKY, top: 0, zIndex: Z_INDEX.floating } : null;
+    isWeb && sticky && !overlay
+      ? { position: WEB_POSITION_STICKY, top: 0, zIndex: Z_INDEX.floating }
+      : null;
 
-  return (
-    <View
-      testID={testID}
-      style={[styles.container, { paddingTop: padTop }, containerWeb, style]}
+  const chrome = floating ? (
+    <Animated.View
+      // A PROP: react-native-web resolves `none` from the prop path only, and
+      // the scrim must never take a press meant for the content under it.
+      pointerEvents="none"
+      style={[styles.scrim, { height: height * (1 + SCRIM_TAIL_RATIO) }, scrimStyle]}
+      testID={testID ? `${testID}-scrim` : undefined}
     >
+      <EdgeScrim
+        // The PAGE colour by default: the scrim's job is to fade content into
+        // the surface it is leaving, so the right colour is the one that
+        // surface already is. A screen that paints its own background has to
+        // say so — the header cannot read the pixel behind it.
+        color={scrimColor ?? theme.colors.background}
+        testID={testID ? `${testID}-scrim-gradient` : undefined}
+      />
+    </Animated.View>
+  ) : (
+    <>
       <Animated.View
         pointerEvents="none"
         style={[StyleSheet.absoluteFill, { boxShadow: paint.shadow }, shadowStyle]}
@@ -210,43 +363,71 @@ function PageHeaderComponent({
         style={[styles.border, { backgroundColor: paint.separator }, borderStyle]}
         testID={testID ? `${testID}-border` : undefined}
       />
+    </>
+  );
+
+  const actionsSlot = actions ? (
+    <View
+      style={[styles.actions, { gap: floating ? FLOATING_ACTIONS_GAP : ACTIONS_GAP }]}
+      onLayout={centered ? onEndLayout : undefined}
+      // `box-none` so the gaps BETWEEN islands stay transparent to touch. A
+      // floating header covers content it does not own, and an invisible
+      // rectangle that swallows presses across the width of the screen is the
+      // defect this presentation could most easily ship.
+      //
+      // FLOATING ONLY, and the asymmetry is the point: a `bar` is an OPAQUE
+      // strip, and letting presses through the part of it that draws no control
+      // would hand a click on solid chrome to whatever list row is scrolled
+      // underneath.
+      pointerEvents={floating ? 'box-none' : undefined}
+      testID={testID ? `${testID}-actions` : undefined}
+    >
+      {floating ? <ControlSurface material="glass">{actions}</ControlSurface> : actions}
+    </View>
+  ) : null;
+
+  return (
+    <View
+      testID={testID}
+      onLayout={onContainerLayout}
+      pointerEvents={overlay ? 'box-none' : undefined}
+      style={[
+        styles.container,
+        { paddingTop: padTop },
+        overlay ? [styles.overlay, { zIndex: Z_INDEX.floating }] : null,
+        containerWeb,
+        style,
+      ]}
+    >
+      {chrome}
       <View
         style={[styles.bar, { paddingLeft: sideInset, paddingRight: sideInset }]}
+        pointerEvents={floating ? 'box-none' : undefined}
         testID={testID ? `${testID}-bar` : undefined}
       >
         <View
           style={[styles.start, !centered && styles.startFill]}
           onLayout={centered ? onStartLayout : undefined}
+          pointerEvents={floating ? 'box-none' : undefined}
           testID={testID ? `${testID}-start` : undefined}
         >
-          {onBack ? (
-            <Button
-              variant="secondary"
-              size="medium"
-              iconOnly
-              leadingIcon={RiArrowLeftLine}
-              accessibilityLabel={backLabel}
-              onPress={onBack}
-              testID={testID ? `${testID}-back` : undefined}
-            />
-          ) : null}
-          {leading}
+          {backButton}
+          {floating && leading ? (
+            <ControlSurface material="glass">{leading}</ControlSurface>
+          ) : (
+            leading
+          )}
           {centered ? null : titleBlock}
         </View>
-        {centered ? <View style={styles.spacer} /> : null}
-        {actions ? (
-          <View
-            style={styles.actions}
-            onLayout={centered ? onEndLayout : undefined}
-            testID={testID ? `${testID}-actions` : undefined}
-          >
-            {actions}
-          </View>
-        ) : null}
+        {centered ? <View style={styles.spacer} pointerEvents="none" /> : null}
+        {actionsSlot}
         {centered && titleBlock ? (
           <View
             pointerEvents="box-none"
-            style={[styles.centerSlot, { left: sideInset + centerInset, right: sideInset + centerInset }]}
+            style={[
+              styles.centerSlot,
+              { left: sideInset + centerInset, right: sideInset + centerInset },
+            ]}
             testID={testID ? `${testID}-center` : undefined}
           >
             {titleBlock}
@@ -262,6 +443,18 @@ const styles = StyleSheet.create({
     width: '100%',
     position: 'relative',
   },
+  overlay: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+  },
+  scrim: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+  },
   border: {
     position: 'absolute',
     left: 0,
@@ -310,7 +503,6 @@ const styles = StyleSheet.create({
     flexDirection: 'row',
     alignItems: 'center',
     justifyContent: 'flex-end',
-    gap: ACTIONS_GAP,
     flexShrink: 0,
   },
 });

package/src/page-header/index.ts

@@ -1,3 +1,11 @@
 export { PageHeader } from './PageHeader';
 
-export type { PageHeaderBorder, PageHeaderProps, PageHeaderTitleAlign } from './types';
+export type {
+  PageHeaderBorder,
+  PageHeaderPlacement,
+  PageHeaderPresentation,
+  PageHeaderProps,
+  PageHeaderScrim,
+  PageHeaderTitleAlign,
+  PageHeaderTitleReveal,
+} from './types';

package/src/page-header/types.ts

@@ -5,12 +5,69 @@ import type { SharedValue } from 'react-native-reanimated';
 /** Where the title sits: after the back button, or centred on the bar. */
 export type PageHeaderTitleAlign = 'start' | 'center';
 
+/**
+ * How the header presents itself.
+ *
+ * `floating` is the default: no bar at all. The back button sits in its own
+ * translucent capsule, related actions share one island, the title floats
+ * between them, and the whole thing ends in a soft vertical gradient instead of
+ * a horizontal edge. Content passes UNDER it.
+ *
+ * `bar` is Bloom's original flat header — an opaque full-width strip with a
+ * hairline separator and a scroll-linked shadow. It is still the right shape
+ * for a dense tool screen, a split-pane sidebar header or anywhere the chrome
+ * must not be mistaken for content; it is no longer the default.
+ */
+export type PageHeaderPresentation = 'floating' | 'bar';
+
+/**
+ * Who reserves the space the header occupies.
+ *
+ * `inline` (default): the header is a sibling ABOVE the content, in a column.
+ * It occupies layout, so nothing passes under it and nothing needs padding.
+ *
+ * `overlay`: the header is absolutely positioned over the content, which starts
+ * at the top of the container and scrolls under the islands. The header then
+ * CLAIMS its measured height on `layout/top-edge`, and the content reads it
+ * with `useTopEdgeInset()` so its first item is not born underneath. This is
+ * the placement the floating presentation was designed for; the two are
+ * separate props because a floating header above a fixed panel is also a real
+ * arrangement.
+ */
+export type PageHeaderPlacement = 'inline' | 'overlay';
+
 /**
  * The bottom separator: `auto` fades it in once the page has scrolled past
  * `scrollThreshold`, `always` draws it at rest, `none` never draws it.
+ *
+ * `presentation="bar"` only. A floating header has no edge to separate.
  */
 export type PageHeaderBorder = 'auto' | 'always' | 'none';
 
+/**
+ * The floating header's edge effect: a vertical gradient from the page colour
+ * to full transparency, behind the title and the islands.
+ *
+ * `auto` (default) fades it in over `[0, scrollThreshold]` of the scroll
+ * offset, so it appears exactly when content starts passing under it. `always`
+ * paints it at rest — for a header that is born over a photograph. `none`
+ * removes it, which leaves the islands to carry legibility on their own.
+ */
+export type PageHeaderScrim = 'auto' | 'always' | 'none';
+
+/**
+ * When the title is visible.
+ *
+ * `always` (default) is the ordinary screen header. `onScroll` holds the title
+ * back and fades it in with the scrim — the shape a header over a hero photo
+ * wants, where the photo already names the screen.
+ *
+ * It is a prop of its own rather than a side effect of the background, because
+ * the two are different questions and conflating them is how every header that
+ * turned transparent also lost its title.
+ */
+export type PageHeaderTitleReveal = 'always' | 'onScroll';
+
 export interface PageHeaderProps {
   /** A string renders as the heading; a node renders as-is (and owns its own semantics). */
   title?: ReactNode;
@@ -20,6 +77,13 @@ export interface PageHeaderProps {
   titleAlign?: PageHeaderTitleAlign;
   /** The title's heading level. Default 1. */
   headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Default `always`. */
+  titleReveal?: PageHeaderTitleReveal;
+
+  /** Default `floating`. */
+  presentation?: PageHeaderPresentation;
+  /** Default `inline`. */
+  placement?: PageHeaderPlacement;
 
   /**
    * Renders the back button and is called when it is pressed. The header is
@@ -31,25 +95,54 @@ export interface PageHeaderProps {
 
   /** Rendered after the back button, before the title (an avatar, a logo). */
   leading?: ReactNode;
-  /** Rendered at the end of the bar, 10 apart — typically Bloom `Button`s. */
+  /**
+   * Rendered at the end of the bar. In the floating presentation this slot is
+   * wrapped in a `ControlSurface` with `material: 'glass'`, so a `ButtonGroup`
+   * inside it becomes one island with no prop written on it. Declare the
+   * grouping yourself — the header never infers it by reading children.
+   */
   actions?: ReactNode;
 
-  /** Default `auto`. */
+  /** `presentation="bar"` only. Default `auto`. */
   border?: PageHeaderBorder;
   /**
-   * The bar's background, shadow and title fade in with scroll instead of
-   * showing at rest — for a header over media. The back button and actions
-   * stay visible (their own fill reads over any image).
+   * `presentation="bar"` only: the bar's background and shadow fade in with
+   * scroll instead of showing at rest.
+   *
+   * It no longer hides the title — that is `titleReveal="onScroll"`, and the
+   * two are set independently. A `bar` header that wants the old combined
+   * behaviour asks for both.
    */
   transparent?: boolean;
+  /** `presentation="floating"` only. Default `auto`. */
+  scrim?: PageHeaderScrim;
+  /**
+   * The colour the edge effect fades FROM. Defaults to `theme.colors.background`
+   * — the page colour, which is what the content scrolling under the header is
+   * disappearing into.
+   *
+   * Pass it when the screen paints a background the theme does not know about:
+   * a tinted section, a brand panel, a dark surface inside a light app. The
+   * header cannot read the colour behind it, and a scrim in the theme's
+   * background over a page in some other colour is a wash of the wrong hue
+   * rather than a fade.
+   *
+   * It must be OPAQUE. The alpha is the ramp's, and a colour that brings its
+   * own would multiply with it — `rgba(0,0,0,0.5)` at the ramp's 0.86 paints
+   * 0.43 and reads as a weak, dirty veil rather than the colour you asked for.
+   */
+  scrimColor?: string;
+
   /**
-   * The scroll offset driving `border="auto"`, `transparent` and the shadow.
-   * Pass it from a Reanimated scroll handler on native or for any scroll
-   * container. Omitted on web, the header follows `window.scrollY`; omitted on
-   * native, the header stays at rest.
+   * The scroll offset driving the scrim, the separator and the shadow.
+   *
+   * Resolution order: this prop, then the nearest `ScrollOffsetProvider`
+   * (`@oxy.so/bloom/layout`) — which is how a header inside a Bloom scroll
+   * composition gets it with no wiring — then, on web only, `window.scrollY`.
+   * On native with none of the three, the header stays at rest.
    */
   scrollY?: SharedValue<number>;
-  /** The offset (px) over which border, background and shadow fade in. Default 20. */
+  /** The offset (px) over which the scrim, separator and shadow fade in. Default 20. */
   scrollThreshold?: number;
 
   /** Web only: pin the bar to the top of its scroll container. Default true. */

package/src/provider/BloomProvider.tsx

@@ -35,6 +35,7 @@ import type { ReactNode } from 'react';
 
 import { GlassBlurTargetProvider } from '../glass/blur-target';
 import { BottomEdgeProvider } from '../layout/bottom-edge';
+import { TopEdgeProvider } from '../layout/top-edge';
 import { ImageResolverProvider, type ImageResolver } from '../image-resolver';
 import { BloomHapticsProvider } from '../hooks/use-haptics';
 import { TabBarMinimizeProvider } from '../tab-bar/context';
@@ -76,7 +77,17 @@ export function BloomProvider({
                 the other.
               */}
               <BottomEdgeProvider>
-                <TabBarMinimizeProvider>{children}</TabBarMinimizeProvider>
+                {/*
+                  And the top edge's, for the same reason one edge further up: a
+                  floating `PageHeader` overlays the content rather than sitting
+                  above it, so the content has to be told how much of the edge is
+                  gone. Two registries rather than one keyed by edge, because a
+                  reader of either only ever wants one number and must not
+                  re-render when the other moves.
+                */}
+                <TopEdgeProvider>
+                  <TabBarMinimizeProvider>{children}</TabBarMinimizeProvider>
+                </TopEdgeProvider>
               </BottomEdgeProvider>
             </GlassBlurTargetProvider>
           </BloomHapticsProvider>

package/src/social-button/OxyMark.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import Svg, { ClipPath, Defs, G, Path } from 'react-native-svg';
 
-import { useSvgIdPrefix } from './use-svg-id';
+import { useSvgIdPrefix } from '../styles/svg-id';
 
 /**
  * The Oxy mark for `SocialButton` — the same drawing the Oxy SDK ships.

package/src/social-button/SocialButton.tsx

@@ -20,7 +20,7 @@ import { StyledPressable } from '../styles/styled-primitives';
 import type { WebCssStyle } from '../styles/web-view-style';
 import { SOCIAL_COLOR_LOGOS } from './color-logos';
 import { OxyMark } from './OxyMark';
-import { useSvgIdPrefix } from './use-svg-id';
+import { useSvgIdPrefix } from '../styles/svg-id';
 import { SOCIAL_PROVIDERS, type SocialColorLogo, type SocialProvider } from './providers';
 import type {
   SocialBrand,

package/src/styles/svg-id.ts

@@ -0,0 +1,23 @@
+import { useId } from 'react';
+
+/**
+ * A DOM-safe id prefix, per component instance.
+ *
+ * Two SVGs of one shape on a page must not resolve each other's `url(#…)`, and
+ * React's `useId` carries characters an SVG id cannot (`:r0:`). Stripping them
+ * keeps the id UNIQUE — `useId` is unique per instance before the strip and the
+ * strip is injective over React's own alphabet — while staying a legal XML name.
+ *
+ * It is `useId` rather than a module-scope counter for one reason a counter
+ * cannot give: SSR. A counter increments in a different order on the server than
+ * during hydration, so the markup React sends and the markup it re-renders
+ * reference different gradients and one of them is not there. `useId` is the
+ * hook React added for exactly this and is stable across the two passes.
+ *
+ * Lives in `styles/` rather than beside its first caller because it now has
+ * three (`social-button`'s mark and button, `page-header`'s edge gradient) —
+ * the second real need is the bar for extracting it, and this cleared it.
+ */
+export function useSvgIdPrefix(prefix: string): string {
+  return `${prefix}-${useId().replace(/[^a-zA-Z0-9]/g, '')}-`;
+}