@oxy.so/bloom 2.12.4 → 3.0.1

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;
+}

package/src/field/Field.tsx

@@ -1,10 +1,11 @@
-import React, { memo, useMemo } from 'react';
+import React, { memo, useId, useMemo } from 'react';
 import { View } from 'react-native';
 
 import { Text } from '../typography';
 import { Label } from '../label';
 import { atoms as a } from '../styles';
 import { TEXT_FIELD_STACK_GAP, useTextFieldPalette } from '../text-field/shared';
+import { FieldControlProvider, type FieldControlValue } from './context';
 import type { FieldProps } from './types';
 
 /**
@@ -15,6 +16,20 @@ import type { FieldProps } from './types';
  * Bloom's `Label`. Unlike `TextField` — which bakes its label/error into the
  * input chrome — `Field` wraps any arbitrary control (a `Switch`, a
  * `SegmentedControl`, a custom picker, etc.).
+ *
+ * ── IT ASSOCIATES, IT DOES NOT ONLY STACK ───────────────────────────────────
+ *
+ * The three pieces are wired to the control through `field/context.ts`: the
+ * control's id, `aria-describedby` for whichever of description/error is
+ * showing, the invalid state, the required state and the disabled state. A
+ * control opts in by reading `useFieldControl()`; one that does not renders
+ * exactly as before. Ids are generated from `useId` when the caller gives no
+ * `nativeID`, so they survive SSR and hydration.
+ *
+ * `multiple` is the several-controls case — a radio set, a date's three boxes.
+ * The field becomes a labelled `group` and stops handing out a control id,
+ * because one id on three inputs is invalid and one error described by three
+ * inputs is read three times.
  */
 /** `HintText`: 4px under the control (`gap-1`) plus its own 1px `pt-px`. */
 const hintStyle = { marginTop: TEXT_FIELD_STACK_GAP, paddingTop: 1 } as const;
@@ -26,42 +41,84 @@ const FieldComponent = function Field({
   error,
   required = false,
   disabled = false,
+  multiple = false,
   nativeID,
   style,
   testID,
 }: FieldProps) {
   const palette = useTextFieldPalette();
   const hasError = typeof error === 'string' && error.length > 0;
-  const descriptionID = nativeID ? `${nativeID}-description` : undefined;
-  const errorID = nativeID ? `${nativeID}-error` : undefined;
+  // `useId` is the seed only when the caller gave no id, so an explicit
+  // `nativeID` still owns every derived id and a consumer that wired its own
+  // `aria-describedby` keeps working.
+  const generated = useId().replace(/[^a-zA-Z0-9]/g, '');
+  const base = nativeID ?? `bloom-field-${generated}`;
+  const labelID = `${base}-label`;
+  const descriptionID = `${base}-description`;
+  const errorID = `${base}-error`;
+  const hasDescription = !hasError && description != null;
+
+  const field = useMemo<FieldControlValue>(
+    () => ({
+      controlId: multiple ? undefined : base,
+      labelId: label != null ? labelID : undefined,
+      // In a `multiple` field the GROUP is described, not each control: an
+      // error pointed at by three inputs is announced three times.
+      describedBy: multiple
+        ? undefined
+        : hasError
+          ? errorID
+          : hasDescription
+            ? descriptionID
+            : undefined,
+      labelText: typeof label === 'string' ? label : undefined,
+      invalid: hasError,
+      required,
+      disabled,
+    }),
+    [multiple, base, label, labelID, hasError, errorID, hasDescription, descriptionID, required, disabled],
+  );
 
   return (
-    <View style={[a.w_full, style]} testID={testID}>
-      {label != null ? (
-        <Label htmlFor={nativeID} required={required} disabled={disabled}>
-          {label}
-        </Label>
-      ) : null}
+    <FieldControlProvider value={field}>
+      <View
+        style={[a.w_full, style]}
+        testID={testID}
+        // A group only when it holds several controls. A `group` around one
+        // control is a wrapper a screen reader has to step into for nothing,
+        // and it competes with the control's own name.
+        role={multiple ? 'group' : undefined}
+        aria-labelledby={multiple && label != null ? labelID : undefined}
+        aria-describedby={
+          multiple ? (hasError ? errorID : hasDescription ? descriptionID : undefined) : undefined
+        }
+      >
+        {label != null ? (
+          <Label nativeID={labelID} htmlFor={multiple ? null : base} required={required} disabled={disabled}>
+            {label}
+          </Label>
+        ) : null}
 
-      {children}
+        {children}
 
-      {hasError ? (
-        <Text
-          variant="caption-1-medium"
-          nativeID={errorID}
-          accessibilityRole="alert"
-          style={[hintStyle, { color: palette.error }]}>
-          {error}
-        </Text>
-      ) : description != null ? (
-        <Text
-          variant="caption-1-medium"
-          nativeID={descriptionID}
-          style={[hintStyle, { color: disabled ? palette.placeholder : palette.hint }]}>
-          {description}
-        </Text>
-      ) : null}
-    </View>
+        {hasError ? (
+          <Text
+            variant="caption-1-medium"
+            nativeID={errorID}
+            accessibilityRole="alert"
+            style={[hintStyle, { color: palette.error }]}>
+            {error}
+          </Text>
+        ) : description != null ? (
+          <Text
+            variant="caption-1-medium"
+            nativeID={descriptionID}
+            style={[hintStyle, { color: disabled ? palette.placeholder : palette.hint }]}>
+            {description}
+          </Text>
+        ) : null}
+      </View>
+    </FieldControlProvider>
   );
 };