@oxy.so/bloom 2.12.4 → 3.0.0

package/src/field/context.ts

@@ -0,0 +1,110 @@
+/**
+ * FIELD MEMBERSHIP — what a `Field` tells the control inside it, so the label,
+ * the description and the error are wired to it rather than merely stacked
+ * above and below it.
+ *
+ * ## What was missing
+ *
+ * `Field` drew the three pieces and rendered `children` untouched. Every
+ * association — the id the label points at, the `aria-describedby` that makes a
+ * screen reader read the error, the invalid state, the disabled state — was the
+ * app's to wire by hand, on every field, and the failure when it was not wired
+ * is silent: the field LOOKS associated, because the parts are in the right
+ * places and the error is red.
+ *
+ * ## The contract
+ *
+ * `Field` publishes ids and state; a control that can accept them calls
+ * {@link useFieldControl} and applies them. Opt-IN, not magic: an arbitrary
+ * child cannot be given behaviour by being wrapped, and a container that
+ * inspected its children's types to decide what to do with them would be the
+ * thing `docs/composition.mdx` argues against. A control that does not read the
+ * context renders exactly as it did before.
+ *
+ * ## The ids are stable across SSR
+ *
+ * From `useId`, seeded by the caller's `nativeID` when it gave one. A
+ * module-scope counter would number the server's render and the client's
+ * hydration differently, so the `for` attribute React sent and the `id` it
+ * re-rendered would stop matching — which is invisible until someone clicks a
+ * label.
+ *
+ * ## One control or several
+ *
+ * A field with ONE control gives it the field's id, and the error is described
+ * BY that control. A field with several (a radio set, a date's three inputs)
+ * must not: three inputs sharing one id is invalid HTML, and an error attached
+ * to each of them is read three times. `multiple` switches the field to a
+ * labelled `group` and publishes no control id at all — the group carries the
+ * name and the description, and each control keeps its own.
+ *
+ * ## What does NOT travel here
+ *
+ * The VALUE, the validation and the submission. Bloom owns presentation and
+ * association; an app's form library owns the data. A context that also carried
+ * the value would make `Field` a form framework, which is the one thing this is
+ * not.
+ */
+import { createContext, useContext } from 'react';
+
+export interface FieldControlValue {
+  /**
+   * The id the single control should carry, so the label's `for` points at it.
+   * `undefined` in a `multiple` field, where each control keeps its own.
+   */
+  controlId?: string;
+  /** The label's own id — for a control that names itself by reference. */
+  labelId?: string;
+  /**
+   * The id list for `aria-describedby`: the description, or the error when
+   * there is one. `undefined` when the field has neither.
+   */
+  describedBy?: string;
+  /**
+   * The label as TEXT, when the field's label is a string.
+   *
+   * This is the cross-platform half of naming. On web a `<label for>` is a real
+   * association and the control needs no name of its own; React Native has no
+   * equivalent, so the control has to carry the name, and the name it should
+   * carry is the one the user can see. A control that has both its own label
+   * prop and this should prefer this — otherwise the visible label and the
+   * announced name can disagree, which is worse than either alone.
+   */
+  labelText?: string;
+  /** Whether the field is currently in its error state. */
+  invalid: boolean;
+  /** Whether the field is marked required. */
+  required: boolean;
+  /**
+   * The field's disabled state.
+   *
+   * A CONSTRAINT, not a default: a control inside a disabled field must not be
+   * able to re-enable itself, so a consumer applies this with `||` against its
+   * own prop rather than with `??`.
+   */
+  disabled: boolean;
+}
+
+const FieldControlContext = createContext<FieldControlValue | null>(null);
+FieldControlContext.displayName = 'BloomFieldControlContext';
+
+/** @internal The provider `Field` renders. */
+export const FieldControlProvider = FieldControlContext.Provider;
+
+/**
+ * The enclosing `Field`'s association, or `null` outside one.
+ *
+ * ```tsx
+ * const field = useFieldControl();
+ * <TextInput
+ *   nativeID={field?.controlId ?? nativeID}
+ *   aria-describedby={field?.describedBy}
+ *   aria-invalid={field?.invalid || isInvalid || undefined}
+ *   accessibilityLabel={field?.labelText ?? label}
+ *   editable={!(field?.disabled || disabled)}
+ * />
+ * ```
+ */
+export function useFieldControl(): FieldControlValue | null {
+  return useContext(FieldControlContext);
+}

package/src/field/index.ts

@@ -1,2 +1,5 @@
 export { Field } from './Field';
+export { useFieldControl } from './context';
+
+export type { FieldControlValue } from './context';
 export type { FieldProps } from './types';

package/src/field/types.ts

@@ -14,11 +14,30 @@ export interface FieldProps {
   error?: string | null;
   /** Mark the field's label with a required asterisk. */
   required?: boolean;
-  /** Disabled styling for the label/description. */
+  /**
+   * Disables the label/description styling AND, for a control that reads the
+   * field context, the control itself.
+   *
+   * It is a CONSTRAINT rather than a default: a control inside a disabled field
+   * combines it with `||`, so nothing inside can re-enable itself.
+   */
   disabled?: boolean;
   /**
-   * `nativeID` wired to the label's `htmlFor` (web) so a label click focuses
-   * the control. Set the same id on the child control's `nativeID`.
+   * The field holds SEVERAL controls — a radio set, a date's three boxes.
+   *
+   * It becomes a labelled `group` and publishes no control id, because one id
+   * shared by three inputs is invalid HTML and one error described by three
+   * inputs is announced three times. Each control keeps its own id and name.
+   */
+  multiple?: boolean;
+  /**
+   * The control's id, wired to the label's `htmlFor` on web so a label click
+   * focuses it.
+   *
+   * Optional now: omitted, the field generates one from `useId` and hands it to
+   * a control that reads `useFieldControl()`. Pass it when the id has to be a
+   * particular string — an app's form library keyed by field name, or a control
+   * that does not read the context and needs the id written on it by hand.
    */
   nativeID?: string;
   style?: StyleProp<ViewStyle>;

package/src/floating/TriggerSlot.tsx

@@ -22,7 +22,7 @@
  * `alignSelf: 'flex-start'` keeps that wrapper from stretching across its
  * parent, which would anchor the surface to the row rather than to the control.
  */
-import React, { Children, cloneElement, isValidElement, useRef } from 'react';
+import React, { Children, cloneElement, Fragment, isValidElement, useRef } from 'react';
 import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
 
 import { useRestoreAccessibilityFocus } from '../hooks/use-accessibility-focus';
@@ -50,6 +50,16 @@ export interface TriggerSlotProps {
  * several children, which is the right failure: `asChild` has no meaning for a
  * fragment, and silently picking the first child is how a trigger ends up
  * un-pressable with nothing logged.
+ *
+ * ── A FRAGMENT PASSES `isValidElement` AND DROPS EVERY PROP ─────────────────
+ *
+ * `Children.only` accepts `<>{child}</>` — a fragment IS one child, and it IS a
+ * valid element — and `cloneElement` on it succeeds, returning a fragment
+ * carrying an `onPress` and an `aria-expanded` that React then discards,
+ * because a fragment renders no host node to put them on. Nothing throws. The
+ * trigger is simply dead, and the caller's most likely next move is to wrap it
+ * in another fragment. So it is rejected here, by name, with the fix in the
+ * message.
  */
 function cloneTrigger(
   children: React.ReactNode,
@@ -61,6 +71,11 @@ function cloneTrigger(
       'A trigger with `asChild` needs a single React element child. Drop `asChild` to let Bloom render the pressable.',
     );
   }
+  if (child.type === Fragment) {
+    throw new Error(
+      'A trigger with `asChild` cannot clone a fragment — it renders no element, so the press handler and the a11y state would be dropped silently. Pass the control itself as the single child.',
+    );
+  }
   const childProps = child.props;
   // A disabled trigger must not OPEN, and the child's own `disabled` is where a
   // caller most naturally writes that — a disabled `Pressable` child rather than
@@ -73,10 +88,28 @@ function cloneTrigger(
     ...handle,
     // Compose rather than overwrite: the child's own handler runs first, then
     // ours opens the surface.
+    //
+    // ── AND THE CHILD'S HANDLER CAN CANCEL THE OPEN ─────────────────────────
+    //
+    // `event.preventDefault()` in the child's own handler stops the surface
+    // from opening. Composition needs an answer to "what if the first handler
+    // decides this press should not do the second thing" — a trigger that has
+    // just discovered the form is dirty, or that the row it belongs to was
+    // removed — and without one the only way to express it is to stop using
+    // `asChild` and rebuild the control.
+    //
+    // It is `preventDefault` rather than a Bloom-specific return value because
+    // the event already carries it on BOTH platforms and both mean the same
+    // thing by it: on web `onPress` is handed React's synthetic `click` event,
+    // and on native the responder event is a React synthetic event too. One
+    // consequence worth knowing on web: the same call also suppresses the
+    // browser's own default for that click, so cancelling the open on an
+    // anchor child cancels its navigation as well.
     onPress: isDisabled
       ? childProps.onPress
       : (event) => {
           childProps.onPress?.(event);
+          if (event?.defaultPrevented) return;
           handle.onPress(event);
         },
     onLongPress:
@@ -84,6 +117,7 @@ function cloneTrigger(
         ? childProps.onLongPress
         : (event) => {
             childProps.onLongPress?.(event);
+            if (event?.defaultPrevented) return;
             handle.onLongPress?.(event);
           },
     // A label the caller already wrote is more specific than the family's.

package/src/glass/GlassIsland.tsx

@@ -0,0 +1,109 @@
+import React, { memo, useMemo } from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { ControlSurface } from '../control-surface';
+import { bloomShadowStyle } from '../design-tokens/shadows';
+import { resolveSurfaceLevel } from '../styles/surface-levels';
+import { borderRadius } from '../styles/tokens';
+import { resolveChromeGlassColors } from '../theme/glass-colors';
+import { useTheme } from '../theme/use-theme';
+import { GlassSurface } from './GlassSurface';
+import type { GlassIslandProps } from './types';
+
+/**
+ * An ISLAND: one translucent, rounded container holding one or more controls
+ * that float over content the container does not own.
+ *
+ * ── WHY THIS EXISTS RATHER THAN A SECOND MATERIAL ───────────────────────────
+ *
+ * `GlassSurface` is the material — blur, tint, sheen, lit rim — and by its own
+ * contract it does NOT own the geometry, the hairline or the shadow: it clips
+ * itself, and a shadow drawn on a clipping node is clipped away on iOS. So
+ * every caller that wants a floating pane has to assemble the same four things
+ * in the same order. Two callers now want exactly that assembly — a
+ * `ButtonGroup` in its glass variant, and a page header's back capsule — which
+ * is the second real need that justifies writing it once.
+ *
+ * ── THE FILL IS THE LADDER'S, NOT A LOCAL PALETTE ───────────────────────────
+ *
+ * The island paints rung 1 of `styles/surface-levels` — byte-for-byte the fill
+ * a card and a menu panel already paint — at the CHROME alpha. That is the
+ * whole reason it reads as Bloom rather than as a fourth material invented for
+ * headers, and it is why a preset change moves islands with everything else.
+ *
+ * ── WHAT IT TELLS ITS CHILDREN ──────────────────────────────────────────────
+ *
+ * It mounts a `ControlSurface` with `material: 'glass'`, so a control inside it
+ * paints flush — no second fill, no second blur — without the caller writing
+ * `variant="glass"` on every one. The nesting rule is the material's, not a
+ * preference: a translucent pane inside a translucent pane composites two
+ * alphas and two blurs for one pane's worth of depth, and on Android the second
+ * blur is not available at all.
+ *
+ * It does NOT publish a `SurfaceLevelProvider`. A published surface fill is a
+ * promise that a descendant can read the pixel it lands on, and the pixel here
+ * depends on content Bloom cannot see.
+ *
+ * ── NO `overflow: hidden` ───────────────────────────────────────────────────
+ *
+ * Deliberately absent, twice over: `GlassSurface` clips its own layers, and
+ * `clipsToBounds` on iOS would clip this box's drop shadow away. Controls
+ * inside round their own press highlight instead of relying on the island to
+ * cut it.
+ */
+const GlassIslandComponent: React.FC<GlassIslandProps> = ({
+  children,
+  radius = borderRadius.full,
+  role,
+  accessibilityLabel,
+  sheen = true,
+  style,
+  testID,
+}) => {
+  const theme = useTheme();
+  const paint = useMemo(() => {
+    const level = resolveSurfaceLevel(theme, 1);
+    return { fill: level.background, glass: resolveChromeGlassColors(level.background, level.border, theme.isDark) };
+  }, [theme]);
+
+  return (
+    <ControlSurface material="glass">
+      <View
+        role={role}
+        accessibilityLabel={accessibilityLabel}
+        testID={testID}
+        style={[
+          styles.island,
+          {
+            borderRadius: radius,
+            borderWidth: paint.glass.hairlineWidth,
+            borderColor: paint.glass.hairline,
+          },
+          bloomShadowStyle('glass'),
+          style,
+        ]}
+      >
+        <GlassSurface
+          fill={paint.fill}
+          material="chrome"
+          radius={radius}
+          sheen={sheen}
+          testID={testID ? `${testID}-material` : undefined}
+        />
+        {children}
+      </View>
+    </ControlSurface>
+  );
+};
+
+const styles = StyleSheet.create({
+  island: {
+    flexDirection: 'row',
+    alignItems: 'stretch',
+    alignSelf: 'flex-start',
+    position: 'relative',
+  },
+});
+
+export const GlassIsland = memo(GlassIslandComponent);
+GlassIsland.displayName = 'GlassIsland';

package/src/glass/GlassSurface.tsx

@@ -8,6 +8,7 @@ import {
   GLASS_BLUR_INTENSITY,
   GLASS_RIM_HIGHLIGHT,
   GLASS_SHEEN,
+  resolveChromeGlassColors,
   resolveGlassColors,
 } from '../theme/glass-colors';
 import type { GlassSurfaceProps } from './types';
@@ -54,12 +55,19 @@ let glassSheenIdCounter = 0;
 const GlassSurfaceComponent: React.FC<GlassSurfaceProps> = ({
   fill,
   radius,
+  material = 'accent',
   sheen = true,
   style,
   testID,
 }) => {
   const theme = useTheme();
-  const glass = useMemo(() => resolveGlassColors(fill), [fill]);
+  const glass = useMemo(
+    () =>
+      material === 'chrome'
+        ? resolveChromeGlassColors(fill, fill, theme.isDark)
+        : resolveGlassColors(fill),
+    [fill, material, theme.isDark],
+  );
   // Per instance, because two panes in one document would otherwise share an id
   // and the survivor of an unmount would reference a gradient that is gone. Same
   // counter shape as `AvatarRing`.
@@ -104,8 +112,24 @@ const GlassSurfaceComponent: React.FC<GlassSurfaceProps> = ({
         content Bloom does not own.
       */}
       <View style={[StyleSheet.absoluteFill, { backgroundColor: glass.fill }]} />
+      {/*
+        The sheen's `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 — the `right` is over-constrained and
+        dropped. On a surface narrower than 300 the sheen still covers, but its
+        gradient is scaled over 150px instead of the surface's own height, so
+        only the top of the ramp is ever visible; on a wider one it stops dead
+        at 300px. Native lays the host view out with flexbox and is unaffected.
+        Gate: `src/__tests__/svg-absolute-fill-size.test.ts`.
+      */}
       {sheen ? (
-        <Svg style={StyleSheet.absoluteFill} testID={testID ? `${testID}-sheen` : undefined}>
+        <Svg
+          width="100%"
+          height="100%"
+          style={StyleSheet.absoluteFill}
+          testID={testID ? `${testID}-sheen` : undefined}
+        >
           <Defs>
             {/* Top to bottom: simulated light from above. */}
             {/*

package/src/glass/index.ts

@@ -1,3 +1,4 @@
+export { GlassIsland } from './GlassIsland';
 export { GlassSurface } from './GlassSurface';
 export {
   GlassBlurTargetProvider,
@@ -5,6 +6,8 @@ export {
   useWindowedBlurTarget,
 } from './blur-target';
 export type {
+  GlassIslandProps,
+  GlassMaterial,
   GlassSurfaceProps,
   GlassBlurTargetProviderProps,
   GlassBlurWindowProps,

package/src/glass/types.ts

@@ -14,6 +14,20 @@ export interface GlassBlurWindowProps {
   children?: ReactNode;
 }
 
+/**
+ * Which of the two glass ROLES a pane paints.
+ *
+ * `accent` is a brand fill over one of Bloom's own neutral surfaces — a
+ * `primary` control, labelled with that fill's own on-colour. `chrome` is a
+ * neutral surface off the ladder (`styles/surface-levels`) over content Bloom
+ * does NOT own — a page header's island — labelled with the theme's own `text`.
+ *
+ * They carry different alphas because they are priced against different
+ * backdrops, and in opposite directions; the measurement is on
+ * {@link ../theme/glass-colors#GLASS_CHROME_ALPHA}.
+ */
+export type GlassMaterial = 'accent' | 'chrome';
+
 export interface GlassSurfaceProps {
   /**
    * The OPAQUE brand fill the pane is tinted with — `theme.colors.primary`,
@@ -35,6 +49,14 @@ export interface GlassSurfaceProps {
    * hides until someone uses a different shape.
    */
   radius: number;
+  /**
+   * Which role's alpha to apply to `fill`. Default `accent`.
+   *
+   * A pane cannot infer this from the colour it is given — `chrome`'s fill is a
+   * neutral that in light mode IS `colors.card`, which an accent pane could
+   * legitimately be asked to paint too.
+   */
+  material?: GlassMaterial;
   /**
    * Whether to paint the sheen — the top-lit gradient that separates glass from
    * flat tinted plastic.
@@ -49,3 +71,26 @@ export interface GlassSurfaceProps {
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }
+
+export interface GlassIslandProps {
+  children?: ReactNode;
+  /**
+   * Corner radius. A full pill by default — an island is a capsule, and a
+   * capsule of icon-only controls is what makes the row read as separated
+   * groups rather than as one bar.
+   */
+  radius?: number;
+  /**
+   * `'group'` when the island holds several RELATED actions the consumer has
+   * declared as one group. Omitted for a single control in its own capsule: a
+   * group of one is noise for a screen reader, and the control already names
+   * itself.
+   */
+  role?: 'group';
+  /** Names the group. Required by `role="group"` to be worth announcing. */
+  accessibilityLabel?: string;
+  /** Forwarded to the material. See {@link GlassSurfaceProps.sheen}. */
+  sheen?: boolean;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/index.ts

@@ -155,12 +155,18 @@ export type {
 } from './surfaces';
 export * from './button';
 export * from './button-group';
+export * from './control-surface';
 export {
   EDGE_GAP,
   windowEdgeGap,
   BottomEdgeProvider,
   useBottomEdgeInset,
   useClaimBottomEdge,
+  TopEdgeProvider,
+  useClaimTopEdge,
+  useTopEdgeInset,
+  ScrollOffsetProvider,
+  useScrollOffset,
 } from './layout';
 export { Fab } from './fab';
 export type { FabProps, FabVariant, FabSize, FabPlacement } from './fab';

package/src/index.web.ts

@@ -160,12 +160,18 @@ export type {
 } from './surfaces/index.web';
 export * from './button/index.web';
 export * from './button-group';
+export * from './control-surface';
 export {
   EDGE_GAP,
   windowEdgeGap,
   BottomEdgeProvider,
   useBottomEdgeInset,
   useClaimBottomEdge,
+  TopEdgeProvider,
+  useClaimTopEdge,
+  useTopEdgeInset,
+  ScrollOffsetProvider,
+  useScrollOffset,
 } from './layout';
 export { Fab } from './fab/index.web';
 export type { FabProps, FabVariant, FabSize, FabPlacement } from './fab/index.web';

package/src/label/Label.tsx

@@ -40,8 +40,10 @@ const LabelComponent = function Label({
 }: LabelProps) {
   const palette = useTextFieldPalette();
 
+  // `null` is DISTINCT from omitted: omitted falls back to the control's id,
+  // `null` says the label names a group and points at nothing.
   const webProps: Record<string, unknown> =
-    IS_WEB ? { htmlFor: htmlFor ?? nativeID } : {};
+    IS_WEB ? { htmlFor: htmlFor === null ? undefined : (htmlFor ?? nativeID) } : {};
 
   return (
     <Text

package/src/label/types.ts

@@ -11,8 +11,14 @@ export interface LabelProps {
   /**
    * Web-only convenience: the `id` of the form control this label is for.
    * Defaults to `nativeID` when omitted. Ignored on native.
+   *
+   * `null` means there is NO single control to point at — a label naming a
+   * GROUP of them, which is `Field`'s `multiple` case. Without a way to say
+   * that, the `nativeID` fallback makes the label its own target: a
+   * `<label for>` pointing at the label, which focuses nothing and which
+   * nothing reports.
    */
-  htmlFor?: string;
+  htmlFor?: string | null;
   /**
    * Render a required marker (an asterisk in the theme's negative color)
    * after the label text. Defaults to `false`.

package/src/layout/bottom-edge.tsx

@@ -67,57 +67,9 @@ import {
   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();
-  };
+import { createEdgeStore, NO_INSET, NO_SUBSCRIPTION, type EdgeStore } from './edge-store';
 
-  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);
+const BottomEdgeContext = createContext<EdgeStore | null>(null);
 
 /**
  * Wrap the app once — `BloomProvider` already does. Rendering a second one
@@ -126,17 +78,12 @@ const BottomEdgeContext = createContext<BottomEdgeStore | null>(null);
  * the tab bar the modal is covering.
  */
 export function BottomEdgeProvider({ children }: PropsWithChildren) {
-  const [store] = useState(createBottomEdgeStore);
+  const [store] = useState(createEdgeStore);
   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.
  *