@oxy.so/bloom 3.0.0 → 3.1.0

package/src/date-picker/TimeField.tsx

@@ -9,6 +9,8 @@ import { TYPE_SCALE } from '../typography';
 import { resolveCalendarPalette } from './palette';
 import { formatTime, parseTime, snapTime, stepTime } from './time';
 import type { TimeFieldProps, TimeFieldSize } from './types';
+import { useInheritedControl } from '../control-surface';
+import { useFieldMembership } from '../field/membership';
 
 /**
  * A time of day, typed. `DatePicker` is the day; this is the hour and minute,
@@ -60,8 +62,8 @@ function TimeFieldComponent({
   max,
   step = 1,
   hourFormat = '24h',
-  size = 'medium',
-  disabled = false,
+  size: sizeProp,
+  disabled: disabledProp = false,
   accessibilityLabel,
   placeholder,
   width,
@@ -69,6 +71,12 @@ function TimeFieldComponent({
   testID,
 }: TimeFieldProps) {
   const theme = useTheme();
+  // `"--:--"` names nothing, so the name is a prop — or, inside a `Field`, the
+  // field's label. The density contract supplies the size the same way: a
+  // container can ask for `small` once instead of on every control.
+  const size = useInheritedControl('density', sizeProp, 'medium');
+  const field = useFieldMembership({ accessibilityLabel, disabled: disabledProp });
+  const disabled = field.disabled;
   const palette = useMemo(() => resolveCalendarPalette(theme), [theme]);
   const config = SIZE_CONFIG[size];
 
@@ -150,7 +158,10 @@ function TimeFieldComponent({
       placeholder={placeholder ?? (hourFormat === '12h' ? '--:-- --' : '--:--')}
       placeholderTextColor={palette.secondaryText}
       inputMode={hourFormat === '12h' ? 'text' : 'numeric'}
-      accessibilityLabel={accessibilityLabel}
+      nativeID={field.nativeID}
+      accessibilityLabel={field.accessibilityLabel}
+      aria-describedby={field.describedBy}
+      aria-invalid={field.invalid || undefined}
       aria-disabled={disabled || undefined}
       style={[FIELD_TRANSITION, fieldStyle, style]}
       testID={testID}

package/src/date-picker/types.ts

@@ -207,10 +207,13 @@ export interface TimeFieldProps {
   size?: TimeFieldSize;
   disabled?: boolean;
   /**
-   * The NAME of the time ("Viewing time", "Check-in"). Required: the field
-   * draws no label of its own, and `"--:--"` names nothing.
+   * The NAME of the time ("Viewing time", "Check-in").
+   *
+   * The field draws no label of its own and `"--:--"` names nothing, so this or
+   * an enclosing `Field`'s label is the only route to a name. With neither it
+   * warns once in development (`hooks/use-accessible-name-warning.ts`).
    */
-  accessibilityLabel: string;
+  accessibilityLabel?: string;
   /** The text while empty. Default `"--:--"`, or `"--:-- --"` in 12h. */
   placeholder?: string;
   /** Fixed width. Default: 104 at `medium`, 96 at `small`. */

package/src/dialog/DialogContent.tsx

@@ -4,6 +4,7 @@ import { View, type GestureResponderEvent } from 'react-native';
 import { Text } from '../typography';
 
 import { useTheme } from '../theme/use-theme';
+import { ScreenScope } from '../layout';
 import { Button } from '../button';
 import type { ButtonVariant } from '../button/types';
 import { useDialogContext } from './context';
@@ -40,7 +41,10 @@ export function DialogBody({
 }) {
   const theme = useTheme();
   return (
-    <>
+    // A dialog is its own screen: chrome inside it claims THIS surface's top
+    // edge and follows THIS surface's scroller, not the page's underneath
+    // (`layout/screen-scope.tsx`).
+    <ScreenScope>
       {title ? (
         // Bloom's `Text`, not react-native's: the raw one renders in whatever
         // font the platform picks and takes no theme colour, so every dialog
@@ -74,7 +78,7 @@ export function DialogBody({
       ) : null}
       {children}
       {actions && actions.length > 0 ? <ActionRow actions={actions} /> : null}
-    </>
+    </ScreenScope>
   );
 }
 

package/src/field/index.ts

@@ -1,5 +1,7 @@
 export { Field } from './Field';
 export { useFieldControl } from './context';
+export { useFieldMembership } from './membership';
 
 export type { FieldControlValue } from './context';
+export type { FieldLabelPlacement, FieldMembership, FieldMembershipInput } from './membership';
 export type { FieldProps } from './types';

package/src/field/membership.ts

@@ -0,0 +1,164 @@
+/**
+ * ONE resolution of field membership, for every control that opts in.
+ *
+ * `useFieldControl()` hands a control the field's ids and state; applying them
+ * is four separate decisions, and each has a direction that is silently wrong:
+ *
+ *   the NAME         defers to the field   (`??`) — a control inside a labelled
+ *                                          field must not announce nothing
+ *   the CONSTRAINTS  combine with the field (`||`) — `disabled` and `invalid`
+ *                                          restrict, so a control cannot opt out
+ *   the ID           is the field's        (`??` the caller's own, which wins)
+ *   `describedBy`    is a LIST, so the two are joined rather than one chosen
+ *
+ * Fifteen families resolving that by hand is fifteen chances to write `??` where
+ * `||` belongs — and the failure is silent in both directions: a control that
+ * re-enables itself inside a disabled field looks fine and a field-labelled
+ * control that announces nothing looks fine too. So it is a function, for the
+ * same reason `useInheritedControl` is one.
+ *
+ * `TextFieldInput` is the one family that resolves the same rule inline, because
+ * it also reconciles the text-field shell's own context and its standalone
+ * branch. It is not exempt from the RULE: `FieldMembership.test.tsx` asserts the
+ * observable properties for every family, so the two implementations cannot
+ * disagree about what a field means without going red.
+ *
+ * ## The name, and why placement decides it
+ *
+ * A control's own label is either STACKED above it (`TextField`, `Textarea`:
+ * the field's label and the control's label are two spellings of one thing, and
+ * a `Field` around it should win) or ADJACENT to it (a checkbox's caption, a
+ * radio's option text: the words the user reads AS the control, which the
+ * announced name must match). Getting that backwards makes a screen reader say
+ * one thing while the eye reads another, so it is a declared property of the
+ * family rather than a guess this hook could make.
+ *
+ * A control with neither — `Switch`, `Slider`, a progress bar — can be named by
+ * NOTHING but the field, which is the case this hook exists for.
+ */
+import { useMemo } from 'react';
+
+import { useFieldControl } from './context';
+
+/** Where the control renders its own label, which decides which name wins. */
+export type FieldLabelPlacement = 'stacked' | 'adjacent';
+
+export interface FieldMembershipInput {
+  /** The name the caller wrote on the control. Always wins. */
+  accessibilityLabel?: string;
+  /** The control's own label, when it has one. */
+  label?: string;
+  /**
+   * Whether that label sits above the control (`stacked`, the default — the
+   * field's label is the same thing said twice, so the field wins) or beside it
+   * as the control's visible text (`adjacent` — it wins, so the announced name
+   * and the words on screen cannot disagree).
+   */
+  labelPlacement?: FieldLabelPlacement;
+  /** The control's own `disabled`. Combined with the field's, never replaced. */
+  disabled?: boolean;
+  /** The control's own invalid state. Combined with the field's. */
+  invalid?: boolean;
+  /** The control's own `required`. Combined with the field's. */
+  required?: boolean;
+  /** An id the caller wrote on the control. Outranks the field's. */
+  nativeID?: string;
+  /** An `aria-describedby` the caller wrote. JOINED with the field's, not replaced. */
+  describedBy?: string;
+}
+
+export interface FieldMembership {
+  /** Whether there is an enclosing `Field` at all. */
+  inField: boolean;
+  /** The id to render, or `undefined` when neither side has one. */
+  nativeID?: string;
+  /** The accessible name to render, or `undefined` when nothing names it. */
+  accessibilityLabel?: string;
+  /** The `aria-describedby` id list, or `undefined` when there is nothing to describe it. */
+  describedBy?: string;
+  /** The effective disabled state: the control's OR the field's. */
+  disabled: boolean;
+  /** The effective invalid state: the control's OR the field's. */
+  invalid: boolean;
+  /** The effective required state: the control's OR the field's. */
+  required: boolean;
+}
+
+/**
+ * Resolve what an enclosing `Field` contributes to one control.
+ *
+ * ```tsx
+ * const field = useFieldMembership({ accessibilityLabel, label, labelPlacement: 'adjacent', disabled });
+ * <Pressable
+ *   nativeID={field.nativeID}
+ *   accessibilityLabel={field.accessibilityLabel}
+ *   aria-describedby={field.describedBy}
+ *   aria-invalid={field.invalid || undefined}
+ *   disabled={field.disabled}
+ * />
+ * ```
+ *
+ * Outside a `Field` it returns the control's own values unchanged, so a control
+ * can call it unconditionally.
+ */
+export function useFieldMembership(input: FieldMembershipInput = {}): FieldMembership {
+  const field = useFieldControl();
+  const {
+    accessibilityLabel,
+    label,
+    labelPlacement = 'stacked',
+    disabled = false,
+    invalid = false,
+    required = false,
+    nativeID,
+    describedBy,
+  } = input;
+
+  const fieldLabel = field?.labelText;
+  const fieldDescribedBy = field?.describedBy;
+  const fieldControlId = field?.controlId;
+  const fieldDisabled = field?.disabled === true;
+  const fieldInvalid = field?.invalid === true;
+  const fieldRequired = field?.required === true;
+
+  return useMemo<FieldMembership>(() => {
+    const own = label ?? undefined;
+    const name =
+      accessibilityLabel ??
+      (labelPlacement === 'adjacent' ? (own ?? fieldLabel) : (fieldLabel ?? own));
+
+    // An id LIST: a control that already points at its own hint keeps it, and
+    // the field's error is added rather than swapped in. Duplicates are
+    // dropped — an id named twice is read twice by some screen readers.
+    const described = [describedBy, fieldDescribedBy].filter(
+      (id): id is string => typeof id === 'string' && id.length > 0,
+    );
+    const uniqueDescribed = Array.from(new Set(described.flatMap((ids) => ids.split(/\s+/))));
+
+    return {
+      inField: field != null,
+      nativeID: nativeID ?? fieldControlId,
+      accessibilityLabel: name,
+      describedBy: uniqueDescribed.length > 0 ? uniqueDescribed.join(' ') : undefined,
+      disabled: disabled || fieldDisabled,
+      invalid: invalid || fieldInvalid,
+      required: required || fieldRequired,
+    };
+  }, [
+    field,
+    accessibilityLabel,
+    label,
+    labelPlacement,
+    disabled,
+    invalid,
+    required,
+    nativeID,
+    describedBy,
+    fieldLabel,
+    fieldDescribedBy,
+    fieldControlId,
+    fieldDisabled,
+    fieldInvalid,
+    fieldRequired,
+  ]);
+}

package/src/file-upload/FileUpload.tsx

@@ -92,6 +92,7 @@ type StaggerState = 'shown' | 'hiding' | 'hidden';
 
 import { formatFileSize } from './shared';
 import { DISABLED_OPACITY } from '../styles/tokens';
+import { useFieldMembership } from '../field/membership';
 
 export { formatFileSize };
 
@@ -445,12 +446,19 @@ const FileUploadComponent = function FileUpload({
   maxBytes = DEFAULT_MAX_BYTES,
   renderFileIcon,
   labels: labelOverrides,
-  disabled = false,
-  accessibilityLabel = 'Upload a file',
+  disabled: disabledProp = false,
+  accessibilityLabel,
   style,
   testID,
 }: FileUploadProps) {
   const theme = useTheme();
+  // The drop zone draws a prompt but names itself with a prop, so a `Field`
+  // around it is the other place the name can come from — and the field's
+  // `disabled` blocks the picker whatever the caller passed. `'Upload a file'`
+  // stays the last resort rather than a default that would outrank a label the
+  // user can read.
+  const field = useFieldMembership({ accessibilityLabel, disabled: disabledProp });
+  const disabled = field.disabled;
   useInteractiveWebCss(STYLE_ID, BLOOM_FILE_UPLOAD_CSS);
   const reducedMotion = useReducedMotion();
   const paint = useMemo(() => resolveFileUploadPaint(theme), [theme]);
@@ -644,7 +652,10 @@ const FileUploadComponent = function FileUpload({
       ref={rootRef}
       {...webDataSet({ bloomFileUpload: busy ? 'busy' : 'idle' })}
       accessibilityRole="button"
-      accessibilityLabel={accessibilityLabel}
+      nativeID={field.nativeID}
+      accessibilityLabel={field.accessibilityLabel ?? 'Upload a file'}
+      aria-describedby={field.describedBy}
+      aria-invalid={field.invalid || undefined}
       aria-busy={busy}
       disabled={disabled}
       focusable={!blocked}

package/src/floating/types.ts

@@ -162,6 +162,19 @@ export interface TriggerHandleProps {
   accessibilityLabel?: string;
   accessibilityRole?: 'button';
   'aria-expanded'?: boolean;
+  /**
+   * The trigger's id, so an enclosing `Field`'s label can point at it.
+   *
+   * Only a trigger that IS a form control sets it — `Select` does; a `Popover`
+   * or a `DropdownMenu` inside a field is not the field's control and must not
+   * take its id. `TriggerSlot` therefore does not read the field context
+   * itself; each family decides whether it is the control.
+   */
+  nativeID?: string;
+  /** The field's hint or error, for a trigger that is a form control. */
+  'aria-describedby'?: string;
+  /** The field's invalid state, for a trigger that is a form control. */
+  'aria-invalid'?: boolean;
   /**
    * What this trigger OPENS. Set by each family from its own constant in
    * `floating/constants.ts`, never defaulted here — the five families open three

package/src/index.ts

@@ -167,6 +167,7 @@ export {
   useTopEdgeInset,
   ScrollOffsetProvider,
   useScrollOffset,
+  ScreenScope,
 } from './layout';
 export { Fab } from './fab';
 export type { FabProps, FabVariant, FabSize, FabPlacement } from './fab';
@@ -282,8 +283,14 @@ export * from './date-picker';
 export { Search } from './search';
 export { Label } from './label';
 export type { LabelProps } from './label';
-export { Field } from './field';
-export type { FieldProps } from './field';
+export { Field, useFieldControl, useFieldMembership } from './field';
+export type {
+  FieldControlValue,
+  FieldLabelPlacement,
+  FieldMembership,
+  FieldMembershipInput,
+  FieldProps,
+} from './field';
 export { InputGroup, InputGroupAddon } from './input-group';
 export type { InputGroupProps, InputGroupAddonProps } from './input-group';
 export { RangeSlider, Slider } from './slider';

package/src/index.web.ts

@@ -172,6 +172,7 @@ export {
   useTopEdgeInset,
   ScrollOffsetProvider,
   useScrollOffset,
+  ScreenScope,
 } from './layout';
 export { Fab } from './fab/index.web';
 export type { FabProps, FabVariant, FabSize, FabPlacement } from './fab/index.web';
@@ -287,8 +288,14 @@ export * from './date-picker';
 export { Search } from './search';
 export { Label } from './label';
 export type { LabelProps } from './label';
-export { Field } from './field';
-export type { FieldProps } from './field';
+export { Field, useFieldControl, useFieldMembership } from './field';
+export type {
+  FieldControlValue,
+  FieldLabelPlacement,
+  FieldMembership,
+  FieldMembershipInput,
+  FieldProps,
+} from './field';
 export { InputGroup, InputGroupAddon } from './input-group';
 export type { InputGroupProps, InputGroupAddonProps } from './input-group';
 export { RangeSlider, Slider } from './slider';

package/src/input-group/InputGroup.tsx

@@ -24,6 +24,7 @@ import {
 } from '../text-field/shared';
 import { TextFieldGroupContext } from '../text-field/TextField';
 import type { InputGroupAddonProps, InputGroupProps } from './types';
+import { useFieldMembership } from '../field/membership';
 
 /**
  * The group is the input shell (`base/input/input.tsx`) with its adornment
@@ -149,12 +150,21 @@ InputGroupAddon.displayName = 'InputGroupAddon';
  */
 const InputGroupComponent = function InputGroup({
   children,
-  isInvalid = false,
-  disabled = false,
+  isInvalid: isInvalidProp = false,
+  disabled: disabledProp = false,
   size = 'md',
   style,
   testID,
 }: InputGroupProps) {
+  // A group holding a control and its addons is ONE control as far as a `Field`
+  // is concerned: the field's `disabled` and invalid state reach every member
+  // through the group's own contexts, including an addon's `Button`, which reads
+  // neither the field nor the text-field group. The group publishes no name — it
+  // does not know which of its children is the control the label points at, so
+  // that stays the field's `nativeID` and the input's to apply.
+  const member = useFieldMembership({ disabled: disabledProp, invalid: isInvalidProp });
+  const disabled = member.disabled;
+  const isInvalid = member.invalid;
   const cfg = SIZE_CONFIG[size];
   const { state: focused, onIn: onFocus, onOut: onBlur } = useInteractionState();
   const { state: hovered, onIn: onHoverIn, onOut: onHoverOut } =
@@ -211,6 +221,7 @@ const InputGroupComponent = function InputGroup({
           // react-native-web has no `disabled` prop to derive the attribute from
           // and never reads `accessibilityState`. React Native folds it back.
           aria-disabled={disabled || undefined}
+          aria-invalid={isInvalid || undefined}
           // Capture focus bubbling from a nested input so the whole chrome
           // reflects focus — RN-web bubbles focus/blur, native does not but a
           // nested TextInput's own focus ring is sufficient there.

package/src/input-otp/InputOtp.tsx

@@ -24,6 +24,7 @@ import {
 } from '../text-field/shared';
 import { TYPE_SCALE } from '../typography/scale';
 import type { InputOtpProps } from './types';
+import { useFieldMembership } from '../field/membership';
 
 /**
  * `InputOtp`: one box per digit, side by side, behaving as ONE value.
@@ -185,13 +186,25 @@ export function InputOtp({
   disabled: disabledAlias,
   groupEvery,
   autoFocus = false,
-  accessibilityLabel = 'One-time code',
+  accessibilityLabel,
   style,
   testID,
 }: InputOtpProps) {
   const theme = useTheme();
   const palette = useMemo(() => resolveInputOtpPalette(theme), [theme]);
-  const disabled = isDisabled ?? disabledAlias ?? false;
+  // SEVERAL controls behind one name: the boxes are the field's `multiple` case
+  // (`docs/field.mdx`), so the GROUP takes the field's name and description and
+  // each box keeps its own name and its own `aria-invalid`. A caller's own
+  // `accessibilityLabel` still wins; `'One-time code'` is the last resort rather
+  // than a default that would outrank the field's label.
+  const membership = useFieldMembership({
+    accessibilityLabel,
+    disabled: isDisabled ?? disabledAlias ?? false,
+    invalid: isInvalid,
+  });
+  const disabled = membership.disabled;
+  const invalid = membership.invalid;
+  const groupName = membership.accessibilityLabel ?? 'One-time code';
 
   const inputsRef = useRef<Array<TextInput | null>>([]);
   const [internal, setInternal] = useState(() => clean(defaultValue, length));
@@ -259,7 +272,8 @@ export function InputOtp({
   return (
     <View
       role="group"
-      accessibilityLabel={accessibilityLabel}
+      accessibilityLabel={groupName}
+      aria-describedby={membership.describedBy}
       testID={testID}
       // No `aria-invalid` here: `group` does not support it. Each box carries
       // its own, which is where a screen reader looks anyway.
@@ -270,7 +284,7 @@ export function InputOtp({
         const paint = resolveInputOtpBoxPaint(palette, {
           hovered: hoveredIndex === index,
           focused: focusedIndex === index,
-          invalid: isInvalid,
+          invalid,
           disabled,
         });
 
@@ -302,7 +316,7 @@ export function InputOtp({
             caretHidden={false}
             editable={!disabled}
             accessibilityLabel={`Digit ${index + 1} of ${length}`}
-            aria-invalid={isInvalid || undefined}
+            aria-invalid={invalid || undefined}
             aria-disabled={disabled || undefined}
             value={digit === ' ' ? '' : digit}
             onChangeText={(text) => writeFrom(index, text)}

package/src/input-otp/types.ts

@@ -20,7 +20,13 @@ export interface InputOtpProps extends ViewStyleProp {
   groupEvery?: number;
   /** Focus the first box on mount. */
   autoFocus?: boolean;
-  /** The group's accessible name, default `"One-time code"`. */
+  /**
+   * The group's accessible name.
+   *
+   * Inside a `Field` the field's label supplies it. `"One-time code"` is the
+   * last resort when neither is given — a default here would outrank the
+   * field's label, which is the one thing on screen the user can read.
+   */
   accessibilityLabel?: string;
   testID?: string;
 }

package/src/layout/index.ts

@@ -5,9 +5,12 @@
  * `edge` answers "how far from the edge"; `bottom-edge` and `top-edge` answer
  * "what is already parked there"; `scroll-offset` answers "which scroller am I
  * following". A surface that floats at an edge needs the first two; chrome that
- * reacts to scrolling needs the third.
+ * reacts to scrolling needs the third. `screen-scope` answers "am I my own
+ * screen" — a modal or a sheet, whose chrome must claim and read its own edges
+ * rather than the screen's underneath.
  */
 export { EDGE_GAP, windowEdgeGap } from './edge';
 export { BottomEdgeProvider, useBottomEdgeInset, useClaimBottomEdge } from './bottom-edge';
 export { TopEdgeProvider, useClaimTopEdge, useTopEdgeInset } from './top-edge';
 export { ScrollOffsetProvider, useScrollOffset } from './scroll-offset';
+export { ScreenScope } from './screen-scope';

package/src/layout/screen-scope.tsx

@@ -0,0 +1,54 @@
+/**
+ * A surface that is its OWN screen, for the two contracts that are screen-scoped.
+ *
+ * ## What goes wrong without it
+ *
+ * `top-edge.tsx` and `scroll-offset.ts` are per-SCREEN by design: one registry
+ * of what is parked at the top, one scroller that the chrome follows. A modal,
+ * a bottom sheet or a detail panel is a second screen drawn over the first, and
+ * both contracts reach into it from outside:
+ *
+ *   - A header inside a full-screen dialog CLAIMS the top edge of the screen
+ *     underneath it. The claim combines with `max`, so the page behind the modal
+ *     is padded for a header it cannot see — and when the modal closes the claim
+ *     unregisters, so the padding appears and disappears with the modal.
+ *   - Chrome inside the sheet READS the page's scroll offset and follows a
+ *     scroller the user is not touching. The sheet's own list scrolls and the
+ *     sheet's header does not react; the page behind scrolls and it does.
+ *
+ * Neither throws, neither warns, and both look like layout decisions.
+ *
+ * ## What it does
+ *
+ * Nests a fresh `TopEdgeProvider` (an empty registry the surface's own chrome
+ * claims against) and publishes a `null` scroll offset, which is the honest
+ * value: nothing inside has said which scroller it owns yet. A scroll owner
+ * INSIDE the surface publishes its own offset in the ordinary way and wins,
+ * because it is nearer.
+ *
+ * The BOTTOM edge is scoped too, and for the same reason read from the other
+ * side: the bottom edge is the tab bar and the FAB, and a sheet covers both. A
+ * form inside a sheet that padded itself for a tab bar it is drawn over ends in
+ * a band of empty space.
+ *
+ * Bloom's own overlay surfaces mount it (`DialogBody`, `BottomSheetBase`), so a
+ * consumer gets this by using them. It is exported for a surface Bloom does not
+ * own — an app's own full-screen route presented over another.
+ */
+import type { PropsWithChildren } from 'react';
+
+import { BottomEdgeProvider } from './bottom-edge';
+import { ScrollOffsetProvider } from './scroll-offset';
+import { TopEdgeProvider } from './top-edge';
+
+export function ScreenScope({ children }: PropsWithChildren) {
+  return (
+    <TopEdgeProvider>
+      <BottomEdgeProvider>
+        {/* `null`, not a zero SharedValue: the two mean different things to the
+            chrome reading it (`scroll-offset.ts`). */}
+        <ScrollOffsetProvider value={null}>{children}</ScrollOffsetProvider>
+      </BottomEdgeProvider>
+    </TopEdgeProvider>
+  );
+}

package/src/phone-input/PhoneInput.tsx

@@ -11,6 +11,7 @@ import {
 } from '../text-field';
 import { CountryCodeSelect } from './CountryCodeSelect';
 import type { PhoneInputProps } from './types';
+import { useFieldMembership } from '../field/membership';
 
 /**
  * A phone number field: `Input` with a country-code `Select` in its
@@ -29,7 +30,7 @@ export function PhoneInput({
   hint,
   required,
   tooltip,
-  size = 'medium',
+  size,
   isInvalid,
   disabled,
   value,
@@ -46,6 +47,17 @@ export function PhoneInput({
   testID,
   style,
 }: PhoneInputProps) {
+  // The country select is a SECOND control inside this field, and it is the one
+  // a `Field disabled` used to miss: the number input reads the field context
+  // itself, the select does not, so the picker stayed operable inside a disabled
+  // field. Resolving membership here hands the same state to both halves.
+  const field = useFieldMembership({
+    accessibilityLabel,
+    label: label ?? 'Phone number',
+    disabled,
+    invalid: isInvalid,
+    required,
+  });
   const [text, setText] = useControllableState({
     value,
     defaultValue,
@@ -55,14 +67,14 @@ export function PhoneInput({
   return (
     <View style={[{ width: '100%' }, style]} testID={testID}>
       {label ? (
-        <TextFieldLabel required={required} tooltip={tooltip}>
+        <TextFieldLabel required={field.required} tooltip={tooltip}>
           {label}
         </TextFieldLabel>
       ) : null}
       <TextField
         size={size}
-        isInvalid={isInvalid}
-        disabled={disabled}
+        isInvalid={field.invalid}
+        disabled={field.disabled}
         leadingAddon={
           <CountryCodeSelect
             value={country}
@@ -70,15 +82,15 @@ export function PhoneInput({
             onValueChange={onCountryChange}
             countries={countries}
             label={countrySelectLabel}
-            disabled={disabled}
+            disabled={field.disabled}
           />
         }>
         <TextFieldInput
-          label={accessibilityLabel ?? label ?? 'Phone number'}
+          label={field.accessibilityLabel ?? 'Phone number'}
           placeholder={placeholder ?? null}
           value={text}
           onChangeText={setText}
-          isInvalid={isInvalid}
+          isInvalid={field.invalid}
           keyboardType="phone-pad"
           autoComplete="tel"
           textContentType="telephoneNumber"
@@ -87,7 +99,7 @@ export function PhoneInput({
         />
         {trailingIcon ? <TextFieldIcon icon={trailingIcon} position="trailing" /> : null}
       </TextField>
-      {hint ? <TextFieldHint isInvalid={isInvalid}>{hint}</TextFieldHint> : null}
+      {hint ? <TextFieldHint isInvalid={field.invalid}>{hint}</TextFieldHint> : null}
     </View>
   );
 }