@multiplatform.one/forms 7.7.4 → 7.8.0

package/src/FloatingPanel/index.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode, UIEvent } from "react";
+import type { ReactNode, RefObject, UIEvent } from "react";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import {
   OVERLAY_ATTACH_GAP,
@@ -15,6 +15,9 @@ import { useSheetEscapeDismiss } from "../shared/useSheetEscapeDismiss";
 import { useFloatingPanel, panelTransition, panelViewportPadding } from "./useFloatingPanel";
 import type { PanelWidthMode } from "./useFloatingPanel";
 import { zIndex } from "../shared/zIndex";
+import { isNestedPanelAction, type PanelActionEvent } from "./nestedAction";
+
+export { floatingPanelActionProps, isNestedPanelAction } from "./nestedAction";
 
 // Re-export hook for Select / Combobox / external consumers
 export {
@@ -37,6 +40,10 @@ export type {
 export interface FloatingPanelProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
+  /** Native only: the modal is presented and its inputs can receive focus. */
+  onNativeShow?: () => void;
+  /** Suppress delayed trigger focus when a consumer handles close focus itself. Web only. */
+  skipReturnFocusRef?: RefObject<boolean>;
   trigger: ReactNode;
   /**
    * Optional control rendered beside the trigger but OUTSIDE the native press
@@ -120,6 +127,11 @@ export interface FloatingPanelProps {
    * the strings must live on the Pressable itself. Web ignores this.
    */
   triggerA11y?: { label?: string; value?: string; hint?: string };
+  /**
+   * Stretch keeps the whole field pressable by default. Content lets an
+   * adornment trigger hug its content inside a composite field.
+   */
+  triggerSizing?: "stretch" | "content";
   /**
    * How the trigger opens the panel. `"press"` (default) is click/tap.
    * `"contextmenu"` is the ContextMenu gesture: web `contextmenu` (right-click
@@ -231,8 +243,10 @@ export function FloatingPanel(props: FloatingPanelProps) {
 function FloatingPanelSheet({
   open,
   onOpenChange,
+  skipReturnFocusRef,
   trigger,
   triggerEnd,
+  triggerSizing = "stretch",
   children,
   scrollable,
   disabled,
@@ -260,7 +274,7 @@ function FloatingPanelSheet({
   // DG-A11Y-04 / Axiom 7: Sheet has no focus scope — move focus into the
   // frame on open, trap Tab while open, return focus to the trigger on close.
   const sheetFrameRef = useRef<HTMLElement | null>(null);
-  useSheetModalFocus(open, sheetFrameRef);
+  useSheetModalFocus(open, sheetFrameRef, skipReturnFocusRef);
   useKeyboardFocusIntoPanel(open, sheetFrameRef);
 
   const framePadding = contentPadding === "none" ? "$0" : knobProps.panelPadding.padding;
@@ -283,7 +297,10 @@ function FloatingPanelSheet({
   // shut the sheet it had just opened. Nothing is lost: the sheet is modal, so
   // its overlay covers the trigger and the toggle could only ever have run
   // with `open === false`.
-  const openFromTrigger = () => handleOpenChange(true);
+  const openFromTrigger = (event?: PanelActionEvent) => {
+    if (event && isNestedPanelAction(event)) return;
+    handleOpenChange(true);
+  };
   const isContextMenu = openOn === "contextmenu";
   const triggerActivation = isWeb
     ? isContextMenu
@@ -298,9 +315,13 @@ function FloatingPanelSheet({
 
   return (
     <>
-      <View flexDirection="row" alignItems="center" width="100%">
+      <View
+        flexDirection="row"
+        alignItems="center"
+        width={triggerSizing === "content" ? "auto" : "100%"}
+      >
         <View
-          flex={1}
+          flex={triggerSizing === "content" ? undefined : 1}
           minWidth={0}
           {...(isContextMenu ? undefined : { onPress: openFromTrigger })}
           cursor={disabled ? "not-allowed" : "pointer"}
@@ -361,6 +382,7 @@ function FloatingPanelSheet({
 function FloatingPanelWeb({
   open,
   onOpenChange,
+  skipReturnFocusRef,
   trigger,
   children,
   disabled,
@@ -379,6 +401,7 @@ function FloatingPanelWeb({
   const growDownOnlyRef = useRef(false);
   const lastScrollTopRef = useRef(0);
   const keyboardOpenRef = useRef(false);
+  const contentRef = useRef<HTMLElement | null>(null);
 
   const repositionFnRef = useRef<(() => void) | null>(null);
 
@@ -405,7 +428,7 @@ function FloatingPanelWeb({
   // Escape (or outside click on empty space) closes the panel while focus is
   // inside it, focus falls to <body>. Return it to the pre-open element
   // (the trigger's focusable). Deliberate focus moves elsewhere are kept.
-  useReturnFocusOnClose(open);
+  useReturnFocusOnClose(open, skipReturnFocusRef);
   useKeyboardFocusIntoPanel(open && panel.mounted, panel.refs.floating, keyboardOpenRef);
   useEffect(() => {
     if (!open) keyboardOpenRef.current = false;
@@ -573,6 +596,29 @@ function FloatingPanelWeb({
     repositionOverlay();
   }, [open, panel.mounted, repositionOverlay, panel.y]);
 
+  useLayoutEffect(() => {
+    const content = contentRef.current;
+    if (!open || !panel.mounted || !isFill || !content || typeof ResizeObserver === "undefined") {
+      return;
+    }
+    // Matching the trigger width can rewrap content after the panel's first
+    // height measurement. Observe the content, not the clamped viewport, so a
+    // later open or result change uses its actual height without a resize loop.
+    let frame = 0;
+    const observer = new ResizeObserver(() => {
+      if (frame) cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        repositionOverlay();
+      });
+    });
+    observer.observe(content);
+    return () => {
+      observer.disconnect();
+      if (frame) cancelAnimationFrame(frame);
+    };
+  }, [open, panel.mounted, isFill, repositionOverlay]);
+
   const handleScroll = useCallback(
     (event: UIEvent) => {
       const el = event.target as HTMLElement;
@@ -633,8 +679,8 @@ function FloatingPanelWeb({
   // (`p-results/trigger-slot/detail.json`): a pointer click carries the click
   // count, `element.click()` and native keyboard activation carry 0.
   const openFromSynthesizedClick = useCallback(
-    (event: { detail: number }) => {
-      if (disabled || isContextMenu || event.detail !== 0) return;
+    (event: { detail: number } & PanelActionEvent) => {
+      if (disabled || isContextMenu || event.detail !== 0 || isNestedPanelAction(event)) return;
       // detail 0 is keyboard/programmatic activation (LC-50). Count it as
       // keyboard-origin so the first inner control rings (LC-71).
       keyboardOpenRef.current = true;
@@ -652,14 +698,26 @@ function FloatingPanelWeb({
     [disabled, onOpenChange],
   );
 
+  const referenceProps = getReferenceProps({
+    ref: panel.setReferenceRef,
+    onClickCapture: openFromSynthesizedClick,
+    ...(isContextMenu ? { onContextMenu: openFromContextMenu } : {}),
+  });
+  // Guard the composed floating-ui openers, after hook handlers are merged.
+  // Declining leaves each action's own events and focus defaults intact.
+  for (const name of ["onMouseDown", "onClick", "onKeyDown", "onKeyUp"] as const) {
+    const handler = referenceProps[name];
+    if (typeof handler === "function") {
+      referenceProps[name] = (event: PanelActionEvent) => {
+        if (!isNestedPanelAction(event)) handler(event);
+      };
+    }
+  }
+
   return (
     <>
       <View
-        {...getReferenceProps({
-          ref: panel.setReferenceRef,
-          onClickCapture: openFromSynthesizedClick,
-          ...(isContextMenu ? { onContextMenu: openFromContextMenu } : {}),
-        })}
+        {...referenceProps}
         cursor={disabled ? "not-allowed" : "pointer"}
         opacity={disabled ? 0.5 : 1}
         // The cover contract is stated as a relation between the panel's top
@@ -693,6 +751,14 @@ function FloatingPanelWeb({
               transformOrigin: panelTransformOrigin(panel.placement),
             },
             onScroll: handleScroll,
+            onTransitionEnd: (event) => {
+              if (
+                event.target === event.currentTarget &&
+                (event.propertyName === "height" || event.propertyName === "max-height")
+              ) {
+                panel.updateArrows(event.currentTarget);
+              }
+            },
           })}
           data-testid="floating-panel-viewport"
           data-fp-panel=""
@@ -714,6 +780,7 @@ function FloatingPanelWeb({
             arrowScrollDirRef={panel.arrowScrollDirRef}
           />
           <View
+            ref={contentRef as any}
             {...(contentPadding !== "none" ? panel.knobProps.panelPadding : undefined)}
             {...(contentPadding !== "none" ? panel.knobProps.gapLg : undefined)}
           >

package/src/FloatingPanel/nestedAction.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { isNestedPanelAction } from "./nestedAction";
+
+describe("independent actions inside panel triggers", () => {
+  it("recognizes an SVG descendant of a marked action", () => {
+    const wrapper = document.createElement("div");
+    wrapper.innerHTML = '<button data-floating-panel-action="true"><svg><path /></svg></button>';
+    expect(
+      isNestedPanelAction({
+        nativeEvent: { target: wrapper.querySelector("path") },
+        currentTarget: wrapper,
+      }),
+    ).toBe(true);
+  });
+
+  it("does not let a marker above the wrapper suppress an ordinary opener", () => {
+    const outer = document.createElement("div");
+    outer.setAttribute("data-floating-panel-action", "true");
+    outer.innerHTML = "<div><button>Open</button></div>";
+    expect(
+      isNestedPanelAction({
+        target: outer.querySelector("button"),
+        currentTarget: outer.firstElementChild,
+      }),
+    ).toBe(false);
+  });
+
+  it("keeps unmarked buttons and non-DOM events as ordinary trigger presses", () => {
+    const wrapper = document.createElement("div");
+    wrapper.innerHTML = "<button>Open</button>";
+    expect(isNestedPanelAction({ target: wrapper.firstElementChild, currentTarget: wrapper })).toBe(
+      false,
+    );
+    expect(isNestedPanelAction({})).toBe(false);
+  });
+});

package/src/FloatingPanel/nestedAction.ts

@@ -0,0 +1,15 @@
+export const floatingPanelActionProps = { "data-floating-panel-action": "true" } as const;
+
+export interface PanelActionEvent {
+  target?: unknown;
+  currentTarget?: unknown;
+  nativeEvent?: { target?: unknown };
+}
+
+/** Marked actions inside a trigger keep their own press and keyboard behavior. */
+export function isNestedPanelAction(event: PanelActionEvent): boolean {
+  const target = (event.nativeEvent?.target ?? event.target) as Element | null;
+  const wrapper = event.currentTarget as Element | null;
+  const action = target?.closest?.('[data-floating-panel-action="true"]');
+  return !!action && !!wrapper?.contains?.(action);
+}

package/src/FloatingPanel/panelWidthContract.spec.ts

@@ -1,6 +1,5 @@
 /**
- * MPO-38 AC: no FloatingPanel consumer renders a panel narrower than its
- * trigger.
+ * Text listboxes match the field width; intrinsic editors size to their content.
  *
  * The runtime half is covered in `useFloatingPanel.spec.tsx`. This is the
  * source half, and it exists because the defect it guards is invisible at
@@ -8,11 +7,9 @@
  * DatePicker measured 262px of calendar under a 289px trigger purely because
  * the call site said `fitContent`.
  *
- * A FIELD-shaped trigger (a control the user reads a value out of) takes
- * `at-least-trigger`. A BUTTON-shaped trigger — an icon, a toolbar chip —
- * legitimately keeps `fit-content`, because matching a 32px button would be
- * absurd; those are listed explicitly so the exemption is a decision rather
- * than an oversight.
+ * Calendar grids take fit-content (MPO-262): a full-width field wrapper is
+ * unrelated to seven day columns and must not create a mostly empty popup.
+ * Text listboxes retain at-least-trigger; icon/button launchers may also hug.
  */
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -22,13 +19,9 @@ import { describe, expect, it } from "vitest";
 const fieldsDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "fields");
 
 /** Pickers whose trigger is a form FIELD: the panel may never be narrower. */
-const fieldShapedPickers = [
-  "DatePicker/parts.tsx",
-  "DatePicker/DatetimePicker.catalog.tsx",
-  "TimePicker/catalog.tsx",
-  "ColorPicker/parts.tsx",
-  "Icon/index.tsx",
-];
+const fieldShapedPickers = ["TimePicker/catalog.tsx", "ColorPicker/parts.tsx", "Icon/index.tsx"];
+
+const intrinsicGridPickers = ["DatePicker/parts.tsx", "DatePicker/DatetimePicker.catalog.tsx"];
 
 /** Panels opened from an icon/button trigger, where fit-content is correct. */
 const buttonShapedPickers = ["Geolocation/index.tsx"];
@@ -37,7 +30,11 @@ function read(relative: string): string {
   return readFileSync(resolve(fieldsDir, relative), "utf8");
 }
 
-describe("FloatingPanel width contract (MPO-38)", () => {
+describe("FloatingPanel width contract (MPO-38, MPO-262)", () => {
+  it.each(intrinsicGridPickers)("%s hugs its calendar grid", (relative) => {
+    expect(read(relative)).toContain('widthMode="fit-content"');
+  });
+
   it.each(fieldShapedPickers)("%s declares at-least-trigger", (relative) => {
     const source = read(relative);
     expect(source).toContain('widthMode="at-least-trigger"');

package/src/FormsIntegration.stories.tsx

@@ -212,9 +212,7 @@ export const multiStepRegistration: Story = {
         />
 
         <FormActions>
-          <Button variant="outlined" onPress={() => setStep("personal")}>
-            Back
-          </Button>
+          <Button onPress={() => setStep("personal")}>Back</Button>
           <Button onPress={() => setStep("verification")}>Next: Verification</Button>
         </FormActions>
       </FormSection>
@@ -240,9 +238,7 @@ export const multiStepRegistration: Story = {
         />
 
         <FormActions>
-          <Button variant="outlined" onPress={() => setStep("contact")}>
-            Back
-          </Button>
+          <Button onPress={() => setStep("contact")}>Back</Button>
           <form.Subscribe selector={(state) => [state.canSubmit, state.isSubmitting]}>
             {([canSubmit, isSubmitting]) => (
               <Button action="submit" disabled={!canSubmit || isSubmitting}>

package/src/InputParts/index.tsx

@@ -1,6 +1,6 @@
 import { getFontSized } from "@tamagui/get-font-sized";
 import type { SizeVariantSpreadFunction } from "@tamagui/web";
-import { useEffect, useState, type ReactNode } from "react";
+import { useCallback, useEffect, useState, type ReactNode } from "react";
 import type { ComponentProps, Ref, RefObject } from "react";
 import { Pressable as RNPressable } from "react-native";
 import type {
@@ -443,7 +443,10 @@ const InputGroupImpl = InputGroupFrame.styleable<{
   // paints outside overflow:hidden, so the ring clip can stay.
   const paintsRing = !grouped && !inTableCell;
   const hasElevation = knobProps.elevation != null;
-  const boxOverflow: BoxOverflow = paintsRing && !(hasElevation && !isWeb) ? "hidden" : "visible";
+  const hasWebPressSlop =
+    isWeb && (props as { "data-mp-press-slop"?: string })["data-mp-press-slop"] != null;
+  const boxOverflow: BoxOverflow =
+    paintsRing && !(hasElevation && !isWeb) && !hasWebPressSlop ? "hidden" : "visible";
   const ringMode = boxRingMode(boxOverflow, paintsRing);
   if (isWeb) {
     ensureCompositeFocusRing();
@@ -536,6 +539,7 @@ const InputGroupImpl = InputGroupFrame.styleable<{
             minWidth={0}
             elevation={undefined}
             {...props}
+            {...controlFragment}
             {...passthroughSizeProps}
             {...insetPadProps}
             {...sizeRecipeEscapeOverride}
@@ -1031,6 +1035,16 @@ const InputButtonImpl = InputButton.styleable<{ glyphRing?: boolean }>((buttonPr
     size: knobProps.controlIcon.width,
     color: paint as never,
   });
+  const decorativeRef = useCallback(
+    (node: TamaguiElement | null) => {
+      // Tamagui 2.7.6 Button stamps tabIndex=0 after consumer props.
+      // Correct the host at hydration; decorative caps share the field stop.
+      if (isWeb && node && "tabIndex" in node) node.tabIndex = tabIndexProp ?? -1;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref, tabIndexProp],
+  );
 
   if (glyphRing) {
     // A real tab stop must square off the token it was HANDED, not the
@@ -1073,7 +1087,7 @@ const InputButtonImpl = InputButton.styleable<{ glyphRing?: boolean }>((buttonPr
   const square = knobProps.control.height;
   return (
     <InputButton
-      ref={ref}
+      ref={decorativeRef}
       size={size}
       height={square}
       width={square}
@@ -1162,9 +1176,8 @@ export const InputContainerFrame = styled(View, {
 
   variants: {
     size: {
-      "...size": (val, { tokens }) => ({
-        gap: (tokens.space[val] as any)?.val * 0.3,
-      }),
+      // Size is shared with the child parts; layout spacing belongs to space.
+      "...size": () => ({}),
     },
     color: {
       "...color": () => ({}),
@@ -1190,6 +1203,7 @@ const InputContainerImpl = InputContainerFrame.styleable((props, forwardedRef) =
       ref={forwardedRef}
       size={knobProps.sizeToken}
       {...knobProps.body}
+      {...knobProps.gap}
       // LC-06/LC-10 (UX-P12): inside a table cell the field root must adopt
       // the cell width — the raw web <input> carries an intrinsic width that
       // otherwise floors the whole column at ~200px and lays out past the

package/src/InputParts/layoutGap.spec.tsx

@@ -0,0 +1,43 @@
+import { createRef } from "react";
+import { Preset } from "@multiplatform.one/theme";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import { Input } from "./index";
+
+afterEach(cleanup);
+
+function measure(size: "small" | "medium", space: "small" | "large", gap?: number) {
+  const ref = createRef<HTMLElement>();
+  const { getByTestId } = renderWithProviders(
+    <Preset overrides={{ size, space }}>
+      <Input testID="root" ref={ref as never} {...(gap === undefined ? {} : { gap })}>
+        <Input.Label>Location</Input.Label>
+        <Input.Box>
+          <Input.Area placeholder="Location" />
+        </Input.Box>
+      </Input>
+    </Preset>,
+  );
+  const root = getByTestId("root");
+  expect(ref.current).toBe(root);
+  // Happy DOM leaves token-backed CSS gaps unresolved; browser coverage reads
+  // the actual pixels. Keep this test checking the rendered gap owner.
+  const value =
+    getComputedStyle(root).gap || [...root.classList].find((name) => name.startsWith("_gap-"));
+  expect(value).toBeTruthy();
+  cleanup();
+  return value;
+}
+
+it("lets space change the multi-slot layout gap at a fixed control size", () => {
+  expect(measure("medium", "small")).not.toBe(measure("medium", "large"));
+});
+
+it("keeps the layout gap stable when only control size changes", () => {
+  expect(measure("small", "small")).toBe(measure("medium", "small"));
+});
+
+it("preserves the consumer gap eject and forwarded root ref", () => {
+  expect(measure("medium", "large", 11)).toBe("11px");
+});

package/src/Wheel/Wheel.spec.tsx

@@ -7,6 +7,22 @@ import { Wheel } from "./index";
 afterEach(cleanup);
 
 describe("Wheel contrast contract", () => {
+  it("uses the selected-text weight and keeps rounding on the selection band", () => {
+    renderWithProviders(
+      <Preset overrides={{ borderRadius: "full" }}>
+        <Wheel items={[1, 2, 3, 4, 5]} value={3} visibleItems={5} />
+      </Preset>,
+    );
+    const wheel = screen.getByTestId("wheel");
+    const selected = wheel.querySelector('[data-selected="true"]')?.firstElementChild;
+    expect(selected).toBeTruthy();
+    expect(["700", "bold"]).toContain(getComputedStyle(selected as Element).fontWeight);
+    expect(["", "0px"]).toContain(getComputedStyle(wheel).borderTopLeftRadius);
+    expect(getComputedStyle(screen.getByTestId("wheel-selection")).borderStartStartRadius).not.toBe(
+      "0px",
+    );
+  });
+
   it("keeps inactive item text on the AA $color11 ramp (not opacity-dimmed)", () => {
     renderWithProviders(
       <Wheel items={[1, 2, 3, 4, 5]} value={3} onChange={() => {}} visibleItems={5} />,

package/src/Wheel/index.tsx

@@ -112,7 +112,7 @@ function ensureWheelFocusStyles() {
   const style = document.createElement("style");
   style.id = WHEEL_FOCUS_STYLE_ID;
   style.textContent =
-    ".mp1-wheel-wrapper:focus-visible { outline: 2px solid var(--outlineColor, rgba(0,0,0,0.5)); outline-offset: -2px; }";
+    ".mp1-wheel-wrapper:focus-visible { outline: 2px solid var(--outlineColor, var(--c-outlineColor, CanvasText)); outline-offset: -2px; }";
   document.head.appendChild(style);
 }
 
@@ -847,7 +847,7 @@ export function Wheel<T = string | number>({
       <Text
         {...knobProps.body}
         fontSize={size}
-        fontWeight={isSelected && !disabled ? "600" : "400"}
+        fontWeight={isSelected && !disabled ? "bold" : knobProps.textWeight.fontWeight}
         color={itemColor(isSelected)}
         numberOfLines={1}
         ellipsizeMode="tail"
@@ -865,7 +865,7 @@ export function Wheel<T = string | number>({
       width={flex ? "100%" : columnWidth}
       minWidth={flex ? 0 : columnWidth}
       flex={flex}
-      {...knobProps.containerRadius}
+      borderRadius={0}
       data-testid="wheel"
       data-disabled={disabled ? true : undefined}
       aria-disabled={disabled || undefined}

package/src/fieldLayout.spec.tsx

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Preset } from "@multiplatform.one/theme";
 import { Input as TamaguiInput } from "tamagui";
-import { FieldLayout } from "./fieldLayout";
+import { FieldLayout, useFieldDescribedBy } from "./fieldLayout";
 import { __resetDevWarnSeen } from "./shared/devWarn";
 
 function classIncludes(container: HTMLElement, fragment: string): boolean {
@@ -188,6 +188,47 @@ describe("FieldLayout error precedence (Axiom 5 eject-last)", () => {
   });
 });
 
+describe("FieldLayout message-before-control anatomy", () => {
+  function Control() {
+    return <input id="ordered" aria-describedby={useFieldDescribedBy()} />;
+  }
+
+  for (const mode of ["top", "side", "compact"] as const) {
+    it(`${mode}: helper and replacement error precede the control and describe only the rendered slot`, () => {
+      const renderField = (error?: string) => (
+        <Preset overrides={{ fieldLabelPlacement: mode === "side" ? "side" : "top" }}>
+          <FieldLayout
+            id="ordered"
+            label="Email"
+            compactSpacing={mode === "compact"}
+            helperText="Use your work address"
+            error={error}
+          >
+            <Control />
+          </FieldLayout>
+        </Preset>
+      );
+      const result = renderWithProviders(renderField());
+      const assertSlot = (id: string, text: string) => {
+        const input = result.container.querySelector("input")!;
+        const message = result.container.querySelector(`#${id}`)!;
+        expect(message.textContent).toBe(text);
+        expect(
+          message.compareDocumentPosition(input) & Node.DOCUMENT_POSITION_FOLLOWING,
+        ).toBeTruthy();
+        expect(input.getAttribute("aria-describedby")).toBe(id);
+        expect(
+          result.container.querySelectorAll("[id$='-description'], [id$='-error']"),
+        ).toHaveLength(1);
+      };
+      assertSlot("ordered-description", "Use your work address");
+      result.rerender(renderField("Enter an email address"));
+      assertSlot("ordered-error", "Enter an email address");
+      expect(result.container.textContent).not.toContain("Use your work address");
+    });
+  }
+});
+
 describe("FieldLayout banned-error-word DEV warn", () => {
   let warnSpy: ReturnType<typeof vi.spyOn>;
 

package/src/fieldLayout.tsx

@@ -218,13 +218,13 @@ export function FieldLayout({
     ...(width !== undefined ? { width } : {}),
   };
 
-  const describedBy =
-    [
-      helperText && id ? `${id}-description` : undefined,
-      errorMessage && id ? `${id}-error` : undefined,
-    ]
-      .filter(Boolean)
-      .join(" ") || undefined;
+  const describedBy = id
+    ? errorMessage
+      ? `${id}-error`
+      : helperText
+        ? `${id}-description`
+        : undefined
+    : undefined;
 
   const a11yLabel = typeof label === "string" ? `${label}${requiredSuffix}` : ariaLabel;
   const a11yDescription = errorMessage ?? helperText;
@@ -293,9 +293,9 @@ export function FieldLayout({
 
   const controlColumn = (
     <YStack flex={sideLabel ? 1 : undefined} {...gapProps}>
-      {children}
       {helperNode}
       {errorNode}
+      {children}
     </YStack>
   );
 
@@ -330,9 +330,9 @@ export function FieldLayout({
           ) : (
             <>
               {labelNode}
-              {children}
               {helperNode}
               {errorNode}
+              {children}
             </>
           )}
         </YStack>

package/src/fields/Checkbox/CheckboxFieldFrame.spec.tsx

@@ -11,6 +11,8 @@
 import { cleanup } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { afterEach, describe, expect, it } from "vitest";
+import { createRef } from "react";
+import { FieldLayout } from "../../fieldLayout";
 import { CheckboxFieldFrame } from "./CheckboxFieldFrame";
 
 afterEach(cleanup);
@@ -31,6 +33,22 @@ function frame(container: HTMLElement): HTMLElement {
 }
 
 describe("CheckboxFieldFrame", () => {
+  it("links the rendered field message, forwards its ref, and preserves an explicit description", () => {
+    const ref = createRef<any>();
+    const fixture = (override?: { "aria-describedby": string | undefined }) => (
+      <FieldLayout id="consent" helperText="Read the terms" error="Accept the terms">
+        <CheckboxFieldFrame id="consent" checked={false} ref={ref} {...override} />
+      </FieldLayout>
+    );
+    const result = renderWithProviders(fixture());
+    expect(frame(result.container).getAttribute("aria-describedby")).toBe("consent-error");
+    expect(ref.current).toBe(frame(result.container));
+    result.rerender(fixture({ "aria-describedby": "consumer-description" }));
+    expect(frame(result.container).getAttribute("aria-describedby")).toBe("consumer-description");
+    result.rerender(fixture({ "aria-describedby": undefined }));
+    expect(frame(result.container).getAttribute("aria-describedby")).toBeNull();
+  });
+
   it("still renders a real role=checkbox, so the styling never costs the semantics", () => {
     const { container } = renderWithProviders(<CheckboxFieldFrame checked={false} />);
     expect(frame(container)).toBeTruthy();

package/src/fields/Checkbox/CheckboxFieldFrame.tsx

@@ -1,7 +1,8 @@
 import { Checkbox as TamaguiCheckbox, styled } from "tamagui";
+import { useFieldDescribedBy } from "../../fieldLayout";
 
 /** Hit-target frame. The painted box is CheckboxGlyphBox (LC-71). */
-export const CheckboxFieldFrame = styled(TamaguiCheckbox, {
+const CheckboxFieldFrameBase = styled(TamaguiCheckbox, {
   backgroundColor: "transparent",
   borderColor: "transparent",
   borderWidth: 0,
@@ -21,3 +22,7 @@ export const CheckboxFieldFrame = styled(TamaguiCheckbox, {
   },
   activeStyle: { backgroundColor: "transparent", borderColor: "transparent" },
 });
+
+export const CheckboxFieldFrame = CheckboxFieldFrameBase.styleable((props, ref) => (
+  <CheckboxFieldFrameBase aria-describedby={useFieldDescribedBy()} {...props} ref={ref} />
+));