@oxy.so/bloom 2.12.3 → 3.0.0

package/lib/typescript/module/theme/glass-colors.d.ts

@@ -192,4 +192,71 @@ export interface GlassColors {
  * and pins both on every alpha or surface change.
  */
 export declare function resolveGlassColors(fill: string): GlassColors;
+/**
+ * The CHROME alpha — the neutral counterpart of {@link GLASS_FILL_ALPHA}.
+ *
+ * ── WHY A SECOND ALPHA AND NOT THE SAME ONE ─────────────────────────────────
+ *
+ * {@link GLASS_FILL_ALPHA} prices a BRAND fill: a `primary` button whose label
+ * is that fill's own on-colour, sitting on one of Bloom's five neutral
+ * surfaces. A page header's island is neither of those things. It is a NEUTRAL
+ * surface off the existing ladder (`styles/surface-levels`, rung 1 — the same
+ * fill a card and a menu panel paint) and it floats over content Bloom does not
+ * own: a photograph, a video still, a map, a list that scrolls under it. Its
+ * label is the theme's own `text`, not an on-fill token.
+ *
+ * So the two materials are priced against different backdrops, and the number
+ * that is right for one is wrong for the other in a measurable direction:
+ *
+ *   brand fill   backdrop ∈ Bloom's own five surfaces      worst case: light mode,
+ *                                                          a white-ish page LIFTS
+ *                                                          the pane under a white
+ *                                                          label
+ *   chrome fill  backdrop ∈ [black, white] — anything      worst case: DARK mode
+ *                                                          over a WHITE backdrop,
+ *                                                          which lifts a dark pane
+ *                                                          under a white label
+ *
+ * That is why dark carries the HIGHER alpha here and light the lower one, which
+ * is the opposite of the intuition that a dark UI can afford more transparency.
+ * A dark island has the whole luminance range above it to be washed out INTO; a
+ * light island over the same white backdrop barely moves, because it is already
+ * near white.
+ *
+ * ── WHAT THESE TWO VALUES BUY ───────────────────────────────────────────────
+ *
+ * Measured over 64 presets x the two extremes of the backdrop range, with the
+ * theme's own `text` as the label, in `theme/__tests__/glass-colors.test.ts`.
+ * The gate pins the floors EXACTLY, in both directions, so a hundredth in
+ * either direction has to be a decision:
+ *
+ *   light 0.72  worst AA ratio over the range  …pinned by the gate
+ *   dark  0.80  worst AA ratio over the range  …pinned by the gate
+ *
+ * and both remain genuinely translucent: the gate also measures how far the
+ * PAINTED pane moves between a black and a white backdrop, asserts that
+ * movement is non-zero, and asserts it is monotonic in the alpha — so an alpha
+ * quietly raised to 1.0 to buy contrast fails on the translucency side rather
+ * than passing on the legibility side.
+ */
+export declare const GLASS_CHROME_ALPHA: {
+    readonly light: 0.72;
+    readonly dark: 0.8;
+};
+/**
+ * Resolve the pane around a NEUTRAL chrome fill — an island of controls
+ * floating over content.
+ *
+ * Both arguments are resolved colour strings the caller already holds, for the
+ * same reason {@link resolveGlassColors} takes one: the caller is the only one
+ * who knows which rung of the surface ladder its container sits on. In practice
+ * that is `resolveSurfaceLevel(theme, 1)` — `.background` for `fill`, `.border`
+ * for `hairline` — which is the fill a card and a menu panel already paint, so
+ * an island reads as Bloom chrome rather than as a fourth material.
+ *
+ * The LABEL is not returned, exactly as in `resolveGlassColors`: a neutral pane
+ * carries the theme's own `text`, and the rungs under it come from
+ * `surfaceTextOn(theme, fill)` — the caller is already holding both.
+ */
+export declare function resolveChromeGlassColors(fill: string, hairline: string, isDark: boolean): GlassColors;
 //# sourceMappingURL=glass-colors.d.ts.map

package/lib/typescript/module/theme/glass-colors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glass-colors.d.ts","sourceRoot":"","sources":["../../../../src/theme/glass-colors.ts"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;IAItB,0EAA0E;;CAElE,CAAC;AAEX,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAElF,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,6CAA6C,CAAC;AAE9E,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,eAAoC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,QAA4K,CAAC;AAE9M;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,QAA6B,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAM5D"}
+{"version":3,"file":"glass-colors.d.ts","sourceRoot":"","sources":["../../../../src/theme/glass-colors.ts"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;IAItB,0EAA0E;;CAElE,CAAC;AAEX,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAElF,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,6CAA6C,CAAC;AAE9E,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,eAAoC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,QAA4K,CAAC;AAE9M;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,QAA6B,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAM5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,kBAAkB;;;CAAsC,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,GACd,WAAW,CAUb"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/bloom",
-  "version": "2.12.3",
+  "version": "3.0.0",
   "packageManager": "bun@1.3.14",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
@@ -272,6 +272,20 @@
         "default": "./lib/commonjs/button-group/index.js"
       }
     },
+    "./control-surface": {
+      "react-native": {
+        "types": "./lib/typescript/module/control-surface/index.d.ts",
+        "default": "./src/control-surface/index.ts"
+      },
+      "import": {
+        "types": "./lib/typescript/module/control-surface/index.d.ts",
+        "default": "./lib/module/control-surface/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/control-surface/index.d.ts",
+        "default": "./lib/commonjs/control-surface/index.js"
+      }
+    },
     "./layout": {
       "react-native": {
         "types": "./lib/typescript/module/layout/index.d.ts",

package/src/button/Button.tsx

@@ -135,7 +135,16 @@ const ButtonGradientFill = memo(function ButtonGradientFill({
       pointerEvents="none"
       style={[StyleSheet.absoluteFill, { borderRadius: radius, overflow: 'hidden' }]}
     >
-      <Svg style={StyleSheet.absoluteFill}>
+      {/*
+        `width`/`height` are load-bearing beside `absoluteFill`: an `<svg>` is a
+        REPLACED element, so `width: auto` resolves to its intrinsic size and an
+        SVG without one falls back to CSS's 300 x 150 — `left: 0; right: 0` does
+        not stretch it. A button wider than 300px stopped its gradient dead at
+        300, and every narrower one scaled the vertical ramp over 150px instead
+        of its own 36, so only the top quarter of the gradient was ever visible.
+        Native is unaffected. Gate: `src/__tests__/svg-absolute-fill-size.test.ts`.
+      */}
+      <Svg width="100%" height="100%" style={StyleSheet.absoluteFill}>
         <Defs>
           <LinearGradient id={id} x1="0" y1="0" x2="0" y2="1">
             <Stop offset="0" stopColor={gradient[0]} />

package/src/button-group/ButtonGroup.tsx

@@ -1,10 +1,14 @@
 import React, { Children, createContext, Fragment, isValidElement, memo, useContext, useMemo } from 'react';
 import { Platform, Pressable, View, type TextStyle } from 'react-native';
 
+import { useInheritedControl } from '../control-surface';
+import { GlassIsland } from '../glass';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography/Typography';
 import { useInteractionState } from '../hooks/use-interaction-state';
+import { resolveSurfaceLevel } from '../styles/surface-levels';
 import { NOT_DISABLED, interactiveWebCss, useInteractiveWebCss } from '../styles/interactive-web-css';
+import { withAlpha } from '../theme/color-utils';
 import type { WebCssStyle } from '../styles/web-view-style';
 import {
   BUTTON_RADIUS,
@@ -13,14 +17,30 @@ import {
   mixColor,
   resolveButtonRamps,
 } from '../button/shared';
+import type { ControlMaterial } from '../control-surface/types';
 import type { Theme } from '../theme/types';
 import type { ButtonGroupItemProps, ButtonGroupProps, ButtonGroupSize } from './types';
 
 /**
- * A group of secondary-style buttons fused into one control — one bordered,
- * shadowed container, items divided by 1px hairlines, only the outer ends
- * rounded. Colours come from the same Bloom-derived ramps as `Button`
- * (`button/shared.ts`), and like `Button` the container is a full pill.
+ * A group of buttons the consumer has declared as ONE control.
+ *
+ * ── TWO MATERIALS, ONE GROUP ────────────────────────────────────────────────
+ *
+ * `solid` is the original: one bordered, shadowed container, items divided by
+ * 1px hairlines, only the outer ends rounded, colours from the same
+ * Bloom-derived ramps as `Button` (`button/shared.ts`).
+ *
+ * `glass` is the same group as a floating ISLAND — one translucent pane
+ * (`glass/GlassIsland`) that the items sit FLUSH on. The group owns the
+ * material and the items paint no fill of their own at rest; a second fill
+ * under a translucent pane is the thing that makes a row of controls read as a
+ * row of cards rather than as one island, and a second BLUR is not available at
+ * all on Android.
+ *
+ * Neither is a decoration a caller has to ask for by name. The variant is
+ * INHERITED from the nearest `ControlSurface`, so `<ButtonGroup>` inside a
+ * floating `PageHeader` is glass and the same group inside a card is solid,
+ * with no prop either way. An explicit `variant` still wins.
  *
  *              medium    small
  *   item h     34        30       (plus the container's 1px border = 36 / 32)
@@ -75,6 +95,43 @@ function resolveGroupPalette(theme: Theme): GroupPalette {
       };
 }
 
+/**
+ * The items' paint on a GLASS island.
+ *
+ * Every state that is not "at rest" is an alpha of the theme's own `text` — an
+ * ink wash, not a fill. That is the one recipe that works on a pane whose
+ * composited colour Bloom cannot predict: a fixed neutral tuned against the
+ * island's own fill goes invisible the moment a photograph behind it moves the
+ * pane 40 levels, while a wash of the label's colour keeps the same relation to
+ * the label at every composite.
+ *
+ * `transparent` at rest is load-bearing rather than tidy. It is what makes the
+ * island ONE pane: give the items a fill and the group is a row of chips inside
+ * a capsule, which is the shape this variant exists to stop.
+ *
+ * The disabled label is read off the island's own fill with `surfaceTextOn`
+ * rather than picked from the ramp, because a ramp stop measured against the
+ * page is not measured against this surface.
+ */
+function resolveGlassItemPalette(theme: Theme): GroupPalette {
+  const { accent } = resolveButtonRamps(theme);
+  const level = resolveSurfaceLevel(theme, 1);
+  const ink = theme.colors.text;
+  const wash = theme.isDark ? { hover: 0.12, active: 0.2 } : { hover: 0.08, active: 0.14 };
+  return {
+    // The island owns the box: the group draws neither border nor divider.
+    groupBorder: 'transparent',
+    divider: withAlpha(ink, theme.isDark ? 0.16 : 0.12),
+    background: 'transparent',
+    hover: withAlpha(ink, wash.hover),
+    active: withAlpha(ink, wash.active),
+    disabledBackground: 'transparent',
+    foreground: ink,
+    disabledForeground: level.textGraphical,
+    ring: accent[500],
+  };
+}
+
 // ---------------------------------------------------------------------------
 //  Keyboard focus on web — an inset `ring-2`. Items are react-native-web
 //  `Pressable`s, so the rules hang off a `dataSet` attribute (a class never
@@ -110,10 +167,18 @@ ${SELECTOR}${NOT_DISABLED}:focus-visible {
 
 const IS_WEB = Platform.OS === 'web';
 
-const GroupContext = createContext<{ size: ButtonGroupSize; palette: GroupPalette } | null>(null);
+interface GroupContextValue {
+  size: ButtonGroupSize;
+  material: ControlMaterial;
+  palette: GroupPalette;
+}
+
+const GroupContext = createContext<GroupContextValue | null>(null);
 
 const ButtonGroupComponent: React.FC<ButtonGroupProps> = ({
-  size = 'medium',
+  variant,
+  size: sizeProp,
+  dividers,
   children,
   accessibilityLabel,
   style,
@@ -121,9 +186,48 @@ const ButtonGroupComponent: React.FC<ButtonGroupProps> = ({
 }) => {
   const theme = useTheme();
   useInteractiveWebCss(STYLE_ID, BUTTON_GROUP_CSS);
-  const palette = useMemo(() => resolveGroupPalette(theme), [theme]);
-  const context = useMemo(() => ({ size, palette }), [size, palette]);
+  const material = useInheritedControl('material', variant, 'solid');
+  const size = useInheritedControl('density', sizeProp, 'medium');
+  const palette = useMemo(
+    () => (material === 'glass' ? resolveGlassItemPalette(theme) : resolveGroupPalette(theme)),
+    [material, theme],
+  );
+  const context = useMemo<GroupContextValue>(
+    () => ({ size, material, palette }),
+    [size, material, palette],
+  );
   const items = Children.toArray(children).filter(isValidElement);
+  const showDividers = dividers ?? material === 'solid';
+
+  const row = items.map((item, index) => (
+    <Fragment key={item.key ?? index}>
+      {/* `divide-x`: a hairline BETWEEN items, never at the ends. */}
+      {showDividers && index > 0 ? (
+        <View style={{ width: 1, backgroundColor: palette.divider }} />
+      ) : null}
+      {item}
+    </Fragment>
+  ));
+
+  if (material === 'glass') {
+    return (
+      <GroupContext.Provider value={context}>
+        {/*
+          The island mounts its own `ControlSurface` with `material: 'glass'`,
+          so an item rendered through a trigger's `asChild` — outside this
+          group's own children, in a caller's tree — still paints flush.
+        */}
+        <GlassIsland
+          role="group"
+          accessibilityLabel={accessibilityLabel}
+          style={style}
+          testID={testID}
+        >
+          {row}
+        </GlassIsland>
+      </GroupContext.Provider>
+    );
+  }
 
   return (
     <GroupContext.Provider value={context}>
@@ -146,13 +250,7 @@ const ButtonGroupComponent: React.FC<ButtonGroupProps> = ({
           style,
         ]}
       >
-        {items.map((item, index) => (
-          <Fragment key={item.key ?? index}>
-            {/* `divide-x`: a hairline BETWEEN items, never at the ends. */}
-            {index > 0 ? <View style={{ width: 1, backgroundColor: palette.divider }} /> : null}
-            {item}
-          </Fragment>
-        ))}
+        {row}
       </View>
     </GroupContext.Provider>
   );
@@ -160,21 +258,42 @@ const ButtonGroupComponent: React.FC<ButtonGroupProps> = ({
 
 const ButtonGroupItemComponent: React.FC<ButtonGroupItemProps> = ({
   onPress,
+  onLongPress,
   children,
   size: sizeProp,
+  variant,
   selected = false,
   disabled = false,
   iconOnly = false,
   leadingIcon: LeadingIcon,
   trailingIcon: TrailingIcon,
   accessibilityLabel,
+  accessibilityRole = 'button',
+  hitSlop,
+  'aria-expanded': ariaExpanded,
+  'aria-haspopup': ariaHasPopup,
   style,
   testID,
 }) => {
   const theme = useTheme();
   const group = useContext(GroupContext);
-  const palette = useMemo(() => group?.palette ?? resolveGroupPalette(theme), [group, theme]);
-  const size = sizeProp ?? group?.size ?? 'medium';
+  // An item can be rendered OUTSIDE its group's children — an anchored family's
+  // `asChild` trigger clones it into the caller's tree — so the material falls
+  // back to the inherited `ControlSurface` (which `GlassIsland` mounts) before
+  // it falls back to `solid`.
+  const inheritedMaterial = useInheritedControl('material', undefined, 'solid');
+  const inheritedDensity = useInheritedControl('density', undefined, 'medium');
+  const material = variant ?? group?.material ?? inheritedMaterial;
+  const palette = useMemo(
+    () =>
+      group && group.material === material
+        ? group.palette
+        : material === 'glass'
+          ? resolveGlassItemPalette(theme)
+          : resolveGroupPalette(theme),
+    [group, material, theme],
+  );
+  const size = sizeProp ?? group?.size ?? inheritedDensity;
   const geometry = GEOMETRY[size];
   const { state: hovered, onIn: onHoverIn, onOut: onHoverOut } = useInteractionState();
   const { state: pressed, onIn: onPressIn, onOut: onPressOut } = useInteractionState();
@@ -198,6 +317,10 @@ const ButtonGroupItemComponent: React.FC<ButtonGroupItemProps> = ({
     justifyContent: 'center',
     gap: 4,
     backgroundColor: background,
+    // On glass the island does not clip (a clipping node loses its iOS drop
+    // shadow), so the item rounds its OWN highlight. On solid the container
+    // clips and a square item is what makes the fused ends read as one pill.
+    borderRadius: material === 'glass' ? BUTTON_RADIUS : undefined,
     '--bloom-button-group-ring': palette.ring,
   };
 
@@ -208,17 +331,21 @@ const ButtonGroupItemComponent: React.FC<ButtonGroupItemProps> = ({
       {...(IS_WEB ? ({ dataSet: { bloomButtonGroupItem: '' } } as Record<string, unknown>) : {})}
       style={[containerStyle, style]}
       onPress={disabled ? undefined : onPress}
+      onLongPress={disabled ? undefined : onLongPress}
       onPressIn={disabled ? undefined : onPressIn}
       onPressOut={disabled ? undefined : onPressOut}
       onHoverIn={onHoverIn}
       onHoverOut={onHoverOut}
+      hitSlop={hitSlop}
       disabled={disabled}
-      accessibilityRole="button"
+      accessibilityRole={accessibilityRole}
       accessibilityLabel={accessibilityLabel}
       // Both spellings: react-native-web reads only `aria-pressed`, React Native
       // has no `aria-pressed` and reads `accessibilityState`.
-      accessibilityState={{ disabled, selected }}
+      accessibilityState={{ disabled, selected, expanded: ariaExpanded }}
       aria-pressed={selected}
+      aria-expanded={ariaExpanded}
+      aria-haspopup={ariaHasPopup}
       testID={testID}
     >
       {LeadingIcon ? (

package/src/button-group/types.ts

@@ -1,27 +1,59 @@
-import type { StyleProp, ViewStyle } from 'react-native';
+import type { GestureResponderEvent, StyleProp, ViewStyle } from 'react-native';
 
+import type { ControlMaterial } from '../control-surface/types';
 import type { ButtonIconComponent } from '../button/types';
+import type { WebAriaProps } from '../styles/styled-primitives';
 
 /** The two group sizes: 34px (`medium`) and 30px (`small`) items. */
 export type ButtonGroupSize = 'medium' | 'small';
 
 export interface ButtonGroupProps {
-  /** Size for every item that does not set its own. */
+  /**
+   * The material the group paints: `solid` (an opaque bordered pill, Bloom's
+   * default chrome) or `glass` (one translucent island the items sit flush on).
+   *
+   * Omitted, it is INHERITED from the nearest `ControlSurface` — which is what a
+   * `PageHeader`'s action slot mounts — and falls back to `solid`. So a group in
+   * a floating header needs no variant written on it, and the same group in a
+   * card is solid without one either. Precedence and its limits:
+   * `docs/composition.mdx`.
+   */
+  variant?: ControlMaterial;
+  /**
+   * Size for every item that does not set its own. Inherited from the nearest
+   * `ControlSurface` when omitted, then `medium`.
+   */
   size?: ButtonGroupSize;
-  /** `ButtonGroupItem` children. Hairlines are drawn between them. */
+  /**
+   * Whether to draw the 1px hairlines BETWEEN items.
+   *
+   * Defaults to `true` for `solid` and `false` for `glass`. A divider is how a
+   * solid pill says "these are separate controls, fused"; on a translucent
+   * island the press highlight already says it, and a hairline over a moving
+   * backdrop reads as an artifact of the material.
+   */
+  dividers?: boolean;
+  /** `ButtonGroupItem` children. */
   children: React.ReactNode;
-  /** Names the group for assistive tech. */
+  /** Names the group. */
   accessibilityLabel?: string;
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }
 
 export interface ButtonGroupItemProps {
-  onPress?: () => void;
+  /**
+   * Press handler. Receives the event, so a handler composed onto this item by
+   * an anchored family's `asChild` trigger can `preventDefault()` it — see
+   * `floating/TriggerSlot.tsx`.
+   */
+  onPress?: (event: GestureResponderEvent) => void;
   /** Label. Ignored when `iconOnly`. */
   children?: React.ReactNode;
   /** Overrides the group's size. */
   size?: ButtonGroupSize;
+  /** Overrides the group's material. Rarely needed; the group owns it. */
+  variant?: ControlMaterial;
   /** Highlights the item like its hover state and announces it as pressed. */
   selected?: boolean;
   disabled?: boolean;
@@ -32,6 +64,37 @@ export interface ButtonGroupItemProps {
   /** Icon component after the label. */
   trailingIcon?: ButtonIconComponent;
   accessibilityLabel?: string;
+
+  // ── The trigger contract ────────────────────────────────────────────────
+  //
+  // Declared, not spread. An anchored family's `asChild` trigger merges
+  // `TriggerHandleProps` onto its child, and a child whose props are a closed
+  // list DROPS the ones it does not declare — silently, since every one of them
+  // is optional. Naming them is what makes `<PopoverTrigger asChild>` around an
+  // item announce its own expanded state instead of looking like a plain
+  // button. Gate: `button-group-trigger.test.tsx`.
+
+  /** Long-press handler, composed by a `ContextMenu` trigger. */
+  onLongPress?: (event: GestureResponderEvent) => void;
+  /** Set by an anchored family: whether the surface this opens is showing. */
+  'aria-expanded'?: boolean;
+  /** Set by an anchored family: what kind of surface this opens. */
+  'aria-haspopup'?: WebAriaProps['aria-haspopup'];
+  /** Set by an anchored family. The item is a `button` either way. */
+  accessibilityRole?: 'button';
+
+  /**
+   * Extra touch area around the item, in px.
+   *
+   * NOT set by the group, and deliberately not defaulted: items in a group are
+   * adjacent, so slop on one overlaps its neighbour and the press lands on
+   * whichever the platform happens to hit-test first. It is for an item that
+   * stands ALONE in its own island — a page header's back capsule, where 4px on
+   * each side turns the 36pt capsule into a 44pt target with nothing beside it
+   * to steal from.
+   */
+  hitSlop?: number | { top?: number; bottom?: number; left?: number; right?: number };
+
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }

package/src/control-surface/ControlSurface.tsx

@@ -0,0 +1,41 @@
+import React, { memo, useMemo } from 'react';
+
+import { ControlSurfaceProvider, useControlSurface } from './context';
+import type { ControlSurfaceProps } from './types';
+
+/**
+ * Declare the presentation the controls inside should default to.
+ *
+ * Renders nothing of its own — no view, no layout node — so it can be dropped
+ * anywhere without moving anything. Bloom's own containers (`ButtonGroup`'s
+ * glass variant, `PageHeader`'s islands) mount it for you; this is the explicit
+ * entry point for an app that wants the same effect around its own controls.
+ *
+ * ```tsx
+ * <ControlSurface material="glass">
+ *   <ButtonGroup accessibilityLabel="Playback">…</ButtonGroup>
+ * </ControlSurface>
+ * ```
+ *
+ * A field left `undefined` INHERITS rather than resetting, so a nested
+ * `<ControlSurface density="small">` inside a glass island stays glass. The
+ * full precedence rule is in `control-surface/context.ts`.
+ */
+const ControlSurfaceComponent: React.FC<ControlSurfaceProps> = ({
+  material,
+  density,
+  children,
+}) => {
+  const inherited = useControlSurface();
+  const value = useMemo(
+    () => ({
+      material: material ?? inherited?.material ?? 'solid',
+      density: density ?? inherited?.density ?? 'medium',
+    }),
+    [material, density, inherited?.material, inherited?.density],
+  );
+  return <ControlSurfaceProvider value={value}>{children}</ControlSurfaceProvider>;
+};
+
+export const ControlSurface = memo(ControlSurfaceComponent);
+ControlSurface.displayName = 'ControlSurface';

package/src/control-surface/context.ts

@@ -0,0 +1,81 @@
+/**
+ * The inherited CONTROL PRESENTATION contract — the third of Bloom's visual
+ * contexts, beside the theme (`theme/use-theme`) and the surface ladder
+ * (`styles/surface-levels`).
+ *
+ * ## What it is for
+ *
+ * A container that owns a material has to be able to say so once, rather than
+ * have every control inside it repeat the material as a prop. A page header's
+ * action island owns its glass; the `ButtonGroup` inside it should not need
+ * `variant="glass"` written on it, and the items inside THAT should not need it
+ * either. Written as props it is three places to keep in step, and the app is
+ * the one that pays when they drift.
+ *
+ * ## Precedence, in one rule
+ *
+ *     an explicit prop  >  the nearest container  >  the component's default
+ *
+ * {@link useInheritedControl} is that rule, and it is a function rather than a
+ * convention so the three consumers cannot each interpret it slightly
+ * differently. `undefined` is the only value that defers: passing
+ * `material="solid"` inside a glass island paints a solid control, which is a
+ * decision the caller is allowed to make.
+ *
+ * ## What deliberately does NOT travel through it
+ *
+ * Only VISUAL CONFIGURATION. A constraint — `disabled`, a modal's inertness,
+ * the user's reduce-transparency preference — is not a default, and the rule
+ * above is exactly wrong for one: a descendant must not be able to re-enable an
+ * action its group disabled by passing a prop. Constraints keep their own
+ * channels (a group's `disabled` is applied by the group when it renders its
+ * items; accessibility preferences are read from the OS at the point of use).
+ *
+ * Nor does STATE. `checked`, `selected`, a field's value and any business datum
+ * are owned by the component that holds them; a visual context that also
+ * carried state would make every container a place state could leak from.
+ *
+ * ## Scope
+ *
+ * One context, two fields, both of which change rarely (a container sets them
+ * once at mount). Scroll offsets, focus, form state and the overlay stack each
+ * have their own context for the opposite reason — they change often, and a
+ * consumer of one must not re-render for a change in another.
+ */
+import { createContext, useContext } from 'react';
+
+import type { ControlSurfaceValue } from './types';
+
+const ControlSurfaceContext = createContext<ControlSurfaceValue | null>(null);
+ControlSurfaceContext.displayName = 'BloomControlSurfaceContext';
+
+/** @internal The provider `ControlSurface` renders. */
+export const ControlSurfaceProvider = ControlSurfaceContext.Provider;
+
+/**
+ * The nearest container's presentation, or `null` when there is none.
+ *
+ * `null` rather than a default object on purpose: a control's own default is
+ * the control's to choose (`ButtonGroup` defaults to `solid`, a media overlay's
+ * toolbar could default to `glass`), and a context that invented one here would
+ * take that choice away by looking like an answer.
+ */
+export function useControlSurface(): ControlSurfaceValue | null {
+  return useContext(ControlSurfaceContext);
+}
+
+/**
+ * Resolve one field by the precedence rule: `explicit` → container → `fallback`.
+ *
+ * ```ts
+ * const material = useInheritedControl('material', variant, 'solid');
+ * ```
+ */
+export function useInheritedControl<K extends keyof ControlSurfaceValue>(
+  key: K,
+  explicit: ControlSurfaceValue[K] | undefined,
+  fallback: ControlSurfaceValue[K],
+): ControlSurfaceValue[K] {
+  const inherited = useContext(ControlSurfaceContext);
+  return explicit ?? inherited?.[key] ?? fallback;
+}

package/src/control-surface/index.ts

@@ -0,0 +1,4 @@
+export { ControlSurface } from './ControlSurface';
+export { useControlSurface, useInheritedControl } from './context';
+
+export type { ControlDensity, ControlMaterial, ControlSurfaceProps, ControlSurfaceValue } from './types';

package/src/control-surface/types.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+
+/**
+ * The MATERIAL a control container paints itself in.
+ *
+ * `solid` is Bloom's default chrome: an opaque fill off the surface ladder, a
+ * hairline and a shadow. `glass` is the translucent chrome a container paints
+ * when it floats over content the container does not own — a page header's
+ * islands, a media overlay's toolbar.
+ *
+ * It names the container's SURFACE, never the action's meaning. A destructive
+ * action stays destructive in either material; see `docs/composition.mdx`.
+ */
+export type ControlMaterial = 'solid' | 'glass';
+
+/** The size a container asks the controls inside it for. */
+export type ControlDensity = 'medium' | 'small';
+
+/**
+ * What a container tells the controls inside it about presentation — and
+ * nothing else.
+ *
+ * Both fields are VISUAL CONFIGURATION: a descendant may override either with
+ * an explicit prop. Restrictions do not travel here, deliberately. `disabled`,
+ * a modal's inertness and the effective accessibility preferences are
+ * constraints rather than defaults, and a descendant must not be able to
+ * re-enable itself by passing a prop — so they stay on their own channels.
+ */
+export interface ControlSurfaceValue {
+  material: ControlMaterial;
+  density: ControlDensity;
+}
+
+export interface ControlSurfaceProps {
+  /** The material controls inside should default to. Inherited when omitted. */
+  material?: ControlMaterial;
+  /** The density controls inside should default to. Inherited when omitted. */
+  density?: ControlDensity;
+  children?: ReactNode;
+}