@oxy.so/bloom 4.16.0 → 4.17.0

package/lib/typescript/module/icons/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/icons/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACpD,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/icons/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACpD,cAAc,SAAS,CAAC"}

package/lib/typescript/module/icons/render-icon.d.ts

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react';
+/**
+ * What a Bloom component tells an icon slot to draw: the box, and the colour of
+ * the glyph in the CURRENT state (rest, hover, pressed, disabled, checked).
+ *
+ * `color` carries the same value the component would have passed as `fill`. It
+ * is spelled `color` because this object is handed to CALLER code, and an app's
+ * own icon set almost always names it that.
+ */
+export interface BloomIconPaint {
+    size: number;
+    color: string;
+}
+/**
+ * A caller-owned glyph that still follows the control's state.
+ *
+ * Bloom's own icon slots take a {@link BloomIconComponent} and tint it by
+ * passing `fill`. An app whose icons paint from a `color` prop — which most app
+ * icon sets do — cannot be handed to one of those slots directly: the props
+ * have nothing in common, so it does not typecheck, and were it cast it would
+ * render at its default size in its default colour, silently.
+ *
+ * Passing `color` alongside `fill` is not the fix, and deliberately so:
+ * `frosted-icon-button/shared.ts` records why — "the prop is not ours to
+ * claim", because components use `color` for semantic variants (`color="danger"`).
+ *
+ * Nor can the function form share the existing prop. A component is a function
+ * too, so a slot accepting both could not tell an app's ADAPTER component —
+ * `({ width, fill }) => <Glyph size={width} color={fill} />`, which works today
+ * and is the documented way to do this — from a paint callback. It would break
+ * exactly the callers who already did the right thing. Hence its own prop.
+ *
+ * ```tsx
+ * <ButtonGroupItem
+ *   iconOnly
+ *   renderLeadingIcon={({ size, color }) => <AppSearchIcon size={size} color={color} />}
+ *   accessibilityLabel="Search"
+ * />
+ * ```
+ *
+ * This is `GlyphButton`'s `children?: ReactNode | ((foreground: string) => ReactNode)`
+ * generalised to the slots that take an icon rather than a child — including
+ * its precedence rule: where a family offers both, the renderer wins over the
+ * icon component.
+ */
+export type BloomIconRenderer = (paint: BloomIconPaint) => ReactNode;
+/**
+ * Resolve an icon slot that offers both forms.
+ *
+ * `render` wins when present, matching `GlyphButton`, where the caller-painted
+ * glyph wins over `icon`. Returns `null` when neither is set, so a call site
+ * stays a single expression.
+ */
+export declare function resolveIconSlot(render: BloomIconRenderer | undefined, size: number, color: string, fallback: () => ReactNode): ReactNode;
+//# sourceMappingURL=render-icon.d.ts.map

package/lib/typescript/module/icons/render-icon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-icon.d.ts","sourceRoot":"","sources":["../../../../src/icons/render-icon.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,SAAS,CAAC;AAErE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,SAAS,GACxB,SAAS,CAGX"}

package/lib/typescript/module/page-header/PageHeader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PageHeader.d.ts","sourceRoot":"","sources":["../../../../src/page-header/PageHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAyD,MAAM,OAAO,CAAC;AAkC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA8E/C,iBAAS,mBAAmB,CAAC,EAC3B,KAAK,EACL,QAAQ,EACR,UAAoB,EACpB,YAAgB,EAChB,WAAsB,EACtB,iBAAqB,EACrB,YAAyB,EACzB,SAAoB,EACpB,MAAM,EACN,SAAkB,EAClB,OAAO,EACP,OAAO,EACP,MAAe,EACf,WAAmB,EACnB,KAAc,EACd,UAAU,EACV,OAAO,EAAE,eAAe,EACxB,eAAmC,EACnC,MAAa,EACb,QAAQ,EACR,KAAK,EACL,MAAM,GACP,EAAE,eAAe,2CAwUjB;AAuED,eAAO,MAAM,UAAU,uDAA4B,CAAC"}
+{"version":3,"file":"PageHeader.d.ts","sourceRoot":"","sources":["../../../../src/page-header/PageHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAyD,MAAM,OAAO,CAAC;AAkC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA8E/C,iBAAS,mBAAmB,CAAC,EAC3B,KAAK,EACL,QAAQ,EACR,UAAoB,EACpB,YAAgB,EAChB,WAAsB,EACtB,iBAAqB,EACrB,YAAyB,EACzB,SAAoB,EACpB,MAAM,EACN,SAAkB,EAClB,OAAO,EACP,OAAO,EACP,MAAe,EACf,WAAmB,EACnB,KAAc,EACd,UAAU,EACV,OAAO,EAAE,eAAe,EACxB,eAAmC,EACnC,MAAa,EACb,QAAQ,EACR,KAAK,EACL,MAAM,GACP,EAAE,eAAe,2CA6UjB;AAuED,eAAO,MAAM,UAAU,uDAA4B,CAAC"}

package/lib/typescript/module/tab-bar/TabBarBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TabBarBase.d.ts","sourceRoot":"","sources":["../../../../src/tab-bar/TabBarBase.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EASL,KAAK,aAAa,EAEnB,MAAM,OAAO,CAAC;AA2Bf,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAItE,OAAO,EAkBL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAe,MAAM,SAAS,CAAC;AAwqB3E;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,EAC1C,IAAI,EAAE,aAAa,CAAC,oBAAoB,CAAC;YAElB,WAAW;;EAGnC;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC;YAC1C,iBAAiB;;EAG/C"}
+{"version":3,"file":"TabBarBase.d.ts","sourceRoot":"","sources":["../../../../src/tab-bar/TabBarBase.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EASL,KAAK,aAAa,EAEnB,MAAM,OAAO,CAAC;AA4Bf,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAItE,OAAO,EAkBL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAe,MAAM,SAAS,CAAC;AA8rB3E;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,EAC1C,IAAI,EAAE,aAAa,CAAC,oBAAoB,CAAC;YAElB,WAAW;;EAGnC;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC;YAC1C,iBAAiB;;EAG/C"}

package/lib/typescript/module/tabs/Tabs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tabs.d.ts","sourceRoot":"","sources":["../../../../src/tabs/Tabs.tsx"],"names":[],"mappings":"AACA,OAAO,KAUN,MAAM,OAAO,CAAC;AAoBf,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAS5C,OAAO,KAAK,EACV,gBAAgB,EAEhB,SAAS,EACT,gBAAgB,EAChB,WAAW,EACZ,MAAM,SAAS,CAAC;AAuGjB,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB,EAAE,MAAM,CAAC;IAChC,uBAAuB,EAAE,MAAM,CAAC;IAChC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,SAA0B,GAAG,SAAS,CAyBjH;AAqGD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1C;;;;;;;;;OASG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACzC;AAsrBD,eAAO,MAAM,IAAI,iFAAyB,CAAC;AAG3C,eAAO,MAAM,WAAW,8CAAqB,CAAC;AAG9C,eAAO,MAAM,WAAW,8CAA0B,CAAC"}
+{"version":3,"file":"Tabs.d.ts","sourceRoot":"","sources":["../../../../src/tabs/Tabs.tsx"],"names":[],"mappings":"AACA,OAAO,KAUN,MAAM,OAAO,CAAC;AAoBf,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAS5C,OAAO,KAAK,EACV,gBAAgB,EAEhB,SAAS,EACT,gBAAgB,EAChB,WAAW,EACZ,MAAM,SAAS,CAAC;AAuGjB,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB,EAAE,MAAM,CAAC;IAChC,uBAAuB,EAAE,MAAM,CAAC;IAChC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,SAA0B,GAAG,SAAS,CAyBjH;AAqGD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1C;;;;;;;;;OASG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACzC;AAyrBD,eAAO,MAAM,IAAI,iFAAyB,CAAC;AAG3C,eAAO,MAAM,WAAW,8CAAqB,CAAC;AAG9C,eAAO,MAAM,WAAW,8CAA0B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/bloom",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "packageManager": "bun@1.3.14",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",

package/src/app-shell/AppShellEngine.tsx

@@ -538,7 +538,11 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   // Plain navigation belongs to the viewport; only the reading surfaces are inset.
   const documentPanelInset = feedRevealed ? 12 : compactPanel ? 0 : gutter;
   const externalTopHeight = showTopBar ? topBarHeight : 0;
-  const plainDocumentFrame = doc && contentAligned && flowSidebar?.surface === 'plain' && !topBarNode;
+  // A property of the NAVIGATION, not of who scrolls: native resolves every
+  // shell to container scroll, and gating this on `document` left native
+  // phones with an 8px frame around the reading panel that the same layout on
+  // the web does not draw.
+  const plainFrame = contentAligned && flowSidebar?.surface === 'plain' && !topBarNode;
   const readingGap = Math.max(0, asideGap ?? columnGap);
   const readingGroupWidth = contentWidth + (asideBeside ? asideWidth + readingGap : 0);
   const centredBody = (
@@ -556,7 +560,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
           // grows the page, the aside is sticky). Bounded: they stretch.
           alignItems: doc ? 'flex-start' : 'stretch',
           ...(contentAligned ? { flexGrow: compactPanel ? 1 : 0, flexBasis: compactPanel ? 'auto' : readingGroupWidth, maxWidth: compactPanel ? undefined : readingGroupWidth } : {}),
-          ...(plainDocumentFrame ? { paddingTop: compactPanel ? 0 : gutter, paddingBottom: compactPanel ? 0 : gutter } : {}),
+          ...(plainFrame ? { paddingTop: compactPanel ? 0 : gutter, paddingBottom: compactPanel ? 0 : gutter } : {}),
         },
         fill,
       ]}
@@ -747,7 +751,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   const navRegion =
     navInFlow && flowSidebar ? (
       doc ? (
-        <View testID={testID ? `${testID}-navigation` : undefined} style={stickyRail(dockedNav || plainDocumentFrame ? 0 : gutter)}>
+        <View testID={testID ? `${testID}-navigation` : undefined} style={stickyRail(dockedNav || plainFrame ? 0 : gutter)}>
           <Sidebar {...flowSidebar} />
         </View>
       ) : canvas && !dockedNav ? (
@@ -794,8 +798,8 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
     // shorthand to physical sides, and which of two declarations for one edge
     // wins is then a matter of declaration order rather than intent.
     ...(dockedNav
-      ? { paddingTop: 0, paddingBottom: 0, paddingInlineStart: 0, paddingInlineEnd: canvas || plainDocumentFrame ? 0 : gutter }
-      : { padding: canvas || plainDocumentFrame ? 0 : gutter }),
+      ? { paddingTop: 0, paddingBottom: 0, paddingInlineStart: 0, paddingInlineEnd: canvas || plainFrame ? 0 : gutter }
+      : { padding: canvas || plainFrame ? 0 : gutter }),
     backgroundColor: background,
   };
 

package/src/button/Button.tsx

@@ -1,5 +1,6 @@
 import type { LinkButtonProps } from './types';
 import React, { useMemo, memo, type ComponentType } from 'react';
+import { resolveIconSlot } from '../icons/render-icon';
 import {
   ActivityIndicator,
   Linking,
@@ -175,6 +176,8 @@ const ButtonComponent: React.FC<ButtonProps> = ({
   trailing,
   leadingIcon: LeadingIcon,
   trailingIcon: TrailingIcon,
+  renderLeadingIcon,
+  renderTrailingIcon,
   iconOnly = false,
   linkTone = 'primary',
   underline,
@@ -298,9 +301,11 @@ const ButtonComponent: React.FC<ButtonProps> = ({
 
   const content = (
     <>
-      {LeadingIcon ? (
-        <LeadingIcon width={iconSize} height={iconSize} fill={paint.foreground} />
-      ) : null}
+      {resolveIconSlot(renderLeadingIcon, iconSize, paint.foreground, () =>
+        LeadingIcon ? (
+          <LeadingIcon width={iconSize} height={iconSize} fill={paint.foreground} />
+        ) : null,
+      )}
       {leading}
       {iconNode}
       {!isSquare && children != null && (
@@ -313,9 +318,13 @@ const ButtonComponent: React.FC<ButtonProps> = ({
         </Text>
       )}
       {trailing}
-      {!isSquare && TrailingIcon ? (
-        <TrailingIcon width={iconSize} height={iconSize} fill={paint.foreground} />
-      ) : null}
+      {!isSquare
+        ? resolveIconSlot(renderTrailingIcon, iconSize, paint.foreground, () =>
+            TrailingIcon ? (
+              <TrailingIcon width={iconSize} height={iconSize} fill={paint.foreground} />
+            ) : null,
+          )
+        : null}
     </>
   );
 

package/src/button/Button.web.tsx

@@ -9,6 +9,7 @@ import React, {
   type ReactElement,
 } from 'react';
 
+import { resolveIconSlot } from '../icons/render-icon';
 import { useBloomAppearance } from '../appearance/context';
 import { useTheme } from '../theme/use-theme';
 import { SpinnerIcon } from '../loading/SpinnerIcon.web';
@@ -182,6 +183,8 @@ const ButtonWebComponent: React.FC<ButtonProps> = ({
   trailing,
   leadingIcon: LeadingIcon,
   trailingIcon: TrailingIcon,
+  renderLeadingIcon,
+  renderTrailingIcon,
   iconOnly = false,
   linkTone = 'primary',
   underline,
@@ -339,11 +342,29 @@ const ButtonWebComponent: React.FC<ButtonProps> = ({
   const iconNode =
     icon == null ? null : isIconComponent(icon) ? renderIcon(icon) : (icon as React.ReactNode);
 
+  // A caller-drawn glyph is handed `currentColor` rather than the resolved
+  // foreground, for the same reason the icon components above are: on web the
+  // state colours come from the stylesheet, so a glyph that inherits them needs
+  // no re-render when hover or press changes them. Native has no cascade and
+  // passes the resolved value.
+  const renderSlot = (render: typeof renderLeadingIcon, fallback: () => React.ReactNode) => (
+    <span
+      aria-hidden="true"
+      style={{ display: 'inline-flex', flexShrink: 0, width: iconSize, height: iconSize }}
+    >
+      {resolveIconSlot(render, iconSize, 'currentColor', fallback)}
+    </span>
+  );
+
   const labelPadding = isLink ? 0 : geometry.labelPaddingHorizontal;
   const hasLabel = !isSquare && children != null && children !== false;
   const content = (
     <>
-      {LeadingIcon ? renderIcon(LeadingIcon) : null}
+      {renderLeadingIcon
+        ? renderSlot(renderLeadingIcon, () => null)
+        : LeadingIcon
+          ? renderIcon(LeadingIcon)
+          : null}
       {leading}
       {iconNode}
       {hasLabel &&
@@ -367,9 +388,15 @@ const ButtonWebComponent: React.FC<ButtonProps> = ({
         ) : (
           children
         ))}
-      {isSquare && !LeadingIcon && !iconNode && children != null ? children : null}
+      {isSquare && !renderLeadingIcon && !LeadingIcon && !iconNode && children != null
+        ? children
+        : null}
       {trailing}
-      {!isSquare && TrailingIcon ? renderIcon(TrailingIcon) : null}
+      {!isSquare && renderTrailingIcon
+        ? renderSlot(renderTrailingIcon, () => null)
+        : !isSquare && TrailingIcon
+          ? renderIcon(TrailingIcon)
+          : null}
     </>
   );
 

package/src/button/types.ts

@@ -1,4 +1,5 @@
 import type { BloomAppearance, BloomTone, BloomSize } from '../appearance/types';
+import type { BloomIconRenderer } from '../icons/render-icon';
 import type { ComponentType, ReactNode } from 'react';
 import type { GestureResponderEvent, StyleProp, ViewStyle, TextStyle } from 'react-native';
 import type { WebAriaProps } from '../styles/styled-primitives';
@@ -173,6 +174,15 @@ export interface ButtonProps {
   leadingIcon?: ButtonIconComponent;
   /** Same as {@link ButtonProps.leadingIcon}, after the label. Ignored when `iconOnly`. */
   trailingIcon?: ButtonIconComponent;
+  /**
+   * Draw the leading glyph yourself, handed the button's icon size and the
+   * foreground for the CURRENT state — for an app's own icon set, whose props
+   * Bloom's icon slot cannot name. Wins over `leadingIcon`, and is used for the
+   * glyph when `iconOnly`. See `icons/render-icon.tsx`.
+   */
+  renderLeadingIcon?: BloomIconRenderer;
+  /** Same as {@link ButtonProps.renderLeadingIcon}, after the label. Ignored when `iconOnly`. */
+  renderTrailingIcon?: BloomIconRenderer;
   /**
    * Render a square icon-only button (24 / 32 / 36 / 44) from `leadingIcon` or
    * `icon`. Name it with `accessibilityLabel` — there is no text to read.

package/src/button-group/ButtonGroup.tsx

@@ -3,6 +3,7 @@ import React, { Children, createContext, Fragment, isValidElement, memo, useCont
 import { Platform, Pressable, View, type TextStyle } from 'react-native';
 
 import { useInheritedControl } from '../control-surface';
+import { resolveIconSlot } from '../icons/render-icon';
 import { GlassIsland } from '../glass';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography/Typography';
@@ -271,6 +272,8 @@ const ButtonGroupItemComponent: React.FC<ButtonGroupItemProps> = ({
   iconOnly = false,
   leadingIcon: LeadingIcon,
   trailingIcon: TrailingIcon,
+  renderLeadingIcon,
+  renderTrailingIcon,
   accessibilityLabel,
   accessibilityRole = 'button',
   hitSlop,
@@ -355,9 +358,11 @@ const ButtonGroupItemComponent: React.FC<ButtonGroupItemProps> = ({
       aria-haspopup={ariaHasPopup}
       testID={testID}
     >
-      {LeadingIcon ? (
-        <LeadingIcon width={geometry.iconSize} height={geometry.iconSize} fill={foreground} />
-      ) : null}
+      {resolveIconSlot(renderLeadingIcon, geometry.iconSize, foreground, () =>
+        LeadingIcon ? (
+          <LeadingIcon width={geometry.iconSize} height={geometry.iconSize} fill={foreground} />
+        ) : null,
+      )}
       {!iconOnly && children != null ? (
         typeof children === 'string' || typeof children === 'number' ? (
           <Text variant="body-medium" numberOfLines={1} style={labelStyle}>
@@ -367,9 +372,13 @@ const ButtonGroupItemComponent: React.FC<ButtonGroupItemProps> = ({
           children
         )
       ) : null}
-      {!iconOnly && TrailingIcon ? (
-        <TrailingIcon width={geometry.iconSize} height={geometry.iconSize} fill={foreground} />
-      ) : null}
+      {!iconOnly
+        ? resolveIconSlot(renderTrailingIcon, geometry.iconSize, foreground, () =>
+            TrailingIcon ? (
+              <TrailingIcon width={geometry.iconSize} height={geometry.iconSize} fill={foreground} />
+            ) : null,
+          )
+        : null}
     </Pressable>
   );
 };

package/src/button-group/types.ts

@@ -2,6 +2,7 @@ import type { GestureResponderEvent, StyleProp, ViewStyle } from 'react-native';
 
 import type { ControlMaterial } from '../control-surface/types';
 import type { ButtonIconComponent } from '../button/types';
+import type { BloomIconRenderer } from '../icons/render-icon';
 import type { WebAriaProps } from '../styles/styled-primitives';
 
 /** The two group sizes: 34px (`md`) and 30px (`sm`) items. */
@@ -67,6 +68,14 @@ export interface ButtonGroupItemProps {
   leadingIcon?: ButtonIconComponent;
   /** Icon component after the label. */
   trailingIcon?: ButtonIconComponent;
+  /**
+   * Draw the leading glyph yourself, handed the item's size and the foreground
+   * for the CURRENT state — for an app's own icon set, whose props Bloom's icon
+   * slot cannot name. Wins over `leadingIcon`. See `icons/render-icon.tsx`.
+   */
+  renderLeadingIcon?: BloomIconRenderer;
+  /** Same as {@link ButtonGroupItemProps.renderLeadingIcon}, after the label. */
+  renderTrailingIcon?: BloomIconRenderer;
   accessibilityLabel?: string;
 
   // ── The trigger contract ────────────────────────────────────────────────

package/src/icons/index.ts

@@ -4,5 +4,7 @@
 // rewrites an app's imports.
 export type { IconStyle, Props } from './shared';
 export type { BloomIconComponent } from './icon-component';
+export type { BloomIconPaint, BloomIconRenderer } from './render-icon';
+export { resolveIconSlot } from './render-icon';
 export { sizes, useCommonSVGProps } from './shared';
 export * from './remix';

package/src/icons/render-icon.tsx

@@ -0,0 +1,65 @@
+import type { ReactNode } from 'react';
+
+/**
+ * What a Bloom component tells an icon slot to draw: the box, and the colour of
+ * the glyph in the CURRENT state (rest, hover, pressed, disabled, checked).
+ *
+ * `color` carries the same value the component would have passed as `fill`. It
+ * is spelled `color` because this object is handed to CALLER code, and an app's
+ * own icon set almost always names it that.
+ */
+export interface BloomIconPaint {
+  size: number;
+  color: string;
+}
+
+/**
+ * A caller-owned glyph that still follows the control's state.
+ *
+ * Bloom's own icon slots take a {@link BloomIconComponent} and tint it by
+ * passing `fill`. An app whose icons paint from a `color` prop — which most app
+ * icon sets do — cannot be handed to one of those slots directly: the props
+ * have nothing in common, so it does not typecheck, and were it cast it would
+ * render at its default size in its default colour, silently.
+ *
+ * Passing `color` alongside `fill` is not the fix, and deliberately so:
+ * `frosted-icon-button/shared.ts` records why — "the prop is not ours to
+ * claim", because components use `color` for semantic variants (`color="danger"`).
+ *
+ * Nor can the function form share the existing prop. A component is a function
+ * too, so a slot accepting both could not tell an app's ADAPTER component —
+ * `({ width, fill }) => <Glyph size={width} color={fill} />`, which works today
+ * and is the documented way to do this — from a paint callback. It would break
+ * exactly the callers who already did the right thing. Hence its own prop.
+ *
+ * ```tsx
+ * <ButtonGroupItem
+ *   iconOnly
+ *   renderLeadingIcon={({ size, color }) => <AppSearchIcon size={size} color={color} />}
+ *   accessibilityLabel="Search"
+ * />
+ * ```
+ *
+ * This is `GlyphButton`'s `children?: ReactNode | ((foreground: string) => ReactNode)`
+ * generalised to the slots that take an icon rather than a child — including
+ * its precedence rule: where a family offers both, the renderer wins over the
+ * icon component.
+ */
+export type BloomIconRenderer = (paint: BloomIconPaint) => ReactNode;
+
+/**
+ * Resolve an icon slot that offers both forms.
+ *
+ * `render` wins when present, matching `GlyphButton`, where the caller-painted
+ * glyph wins over `icon`. Returns `null` when neither is set, so a call site
+ * stays a single expression.
+ */
+export function resolveIconSlot(
+  render: BloomIconRenderer | undefined,
+  size: number,
+  color: string,
+  fallback: () => ReactNode,
+): ReactNode {
+  if (render) return render({ size, color });
+  return fallback();
+}

package/src/page-header/PageHeader.tsx

@@ -416,7 +416,12 @@ function PageHeaderComponent({
       style={[
         styles.container,
         { paddingTop: padTop },
-        overlay ? [styles.overlay, { zIndex: Z_INDEX.floating }] : null,
+        overlay ? [styles.overlay, {
+          zIndex: Z_INDEX.floating,
+          // Android's native scroll surfaces also participate in elevation.
+          // Keep this local chrome above its sibling list without a portal.
+          ...(!isWeb ? { elevation: Z_INDEX.floating } : {}),
+        }] : null,
         containerWeb,
         placement === 'overlap' ? { marginBottom: -height, zIndex: Z_INDEX.floating } : null,
         style,

package/src/tab-bar/TabBarBase.tsx

@@ -30,6 +30,7 @@ import {
   Pressable,
   StyleSheet,
   View,
+  type GestureResponderEvent,
   type ViewStyle,
 } from 'react-native';
 import { Gesture, GestureDetector } from 'react-native-gesture-handler';
@@ -112,6 +113,28 @@ type BarContextValue = {
 
 const BarContext = createContext<BarContextValue | null>(null);
 
+/**
+ * Whether the bar's `Tap` gesture has already reported the touch a button's
+ * press came from. The gesture activates on RELEASE, after the `Pressable` has
+ * fired, and it cancels that press on iOS alone:
+ *
+ * - iOS: RNGH sets `cancelsTouchesInView`, so a press that still arrives came
+ *   from something the gesture never saw (VoiceOver, a hardware keyboard).
+ * - Android: nothing is cancelled. Measured on a Pixel 10 Pro, one tap produced
+ *   `PRESSABLE selectIndex(1)` AND `GESTURE tap selectIndex(1)` ~600ms apart.
+ *   A press there cannot say whether it was a touch, so every press is taken
+ *   for one.
+ * - Web: nothing is cancelled either. Measured in Mention's web build, one
+ *   mouse click reached `onIndexChange` twice. react-native-web says which
+ *   input it was: a pointer press arrives as the DOM `click`, and a keyboard
+ *   Enter or Space as `keyup`, which the gesture never sees.
+ */
+function gestureReportedPress(event: GestureResponderEvent): boolean {
+  if (Platform.OS === 'android') return true;
+  if (Platform.OS === 'web') return (event.nativeEvent as { type?: string }).type === 'click';
+  return false;
+}
+
 function OptionalGesture({ enabled, children, ...props }: ComponentProps<typeof GestureDetector> & { enabled: boolean }) {
   return enabled ? <GestureDetector {...props}>{children}</GestureDetector> : <Fragment>{children}</Fragment>;
 }
@@ -699,8 +722,8 @@ function TabBarButtonBody({
         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.
+        // Fires for keyboard and assistive-technology activation, and on
+        // Android and web also for the pointer taps the gesture reports.
         if (bar) {
           // Appear at the tab when hidden, slide to it when visible — the same
           // rule the tap gesture and the controlled path follow. Skipped on the
@@ -713,20 +736,20 @@ function TabBarButtonBody({
           bar.highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
         }
         setMinimized(minimized, 0);
-        // 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 && (bar?.scrollable || Platform.OS !== 'android')) bar?.selectIndex(index);
-        onPress?.(event);
+        // A tap the bar's gesture already reported is not reported again
+        // (`gestureReportedPress`). A scrollable bar has no gesture, so its
+        // presses are the only reporter.
+        const reported = bar != null && !bar.scrollable && gestureReportedPress(event);
+        // 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 && !reported) bar?.selectIndex(index);
+        // The trigger's `onPress` is for what the gesture cannot see (keyboard,
+        // assistive technology). On web a pointer click has already navigated
+        // through `onIndexChange`, so it stands down. Android keeps calling it:
+        // a press there cannot tell a touch from a keyboard or D-pad, and
+        // dropping it would strand keyboard navigation.
+        if (!(reported && Platform.OS === 'web')) onPress?.(event);
       }}
       // `Pressable`'s `style` also accepts a function of the press state; both
       // forms are composed on top of the flex-share base so a caller can tint

package/src/tabs/Tabs.tsx

@@ -780,6 +780,9 @@ const TabsBarComponent = forwardRef<TabsDragController, TabsProps>(function Tabs
           ref={scrollRef}
           {...stripA11y}
           horizontal
+          // A tab strip owns its intrinsic cross-axis height. RN ScrollView's
+          // default flexGrow: 1 otherwise consumes the list's remaining space.
+          style={{ flexGrow: 0, flexShrink: 0 }}
           showsHorizontalScrollIndicator={false}
           contentContainerStyle={[containerStyle, style]}
           onLayout={(e) => {