@multiplatform.one/forms 7.4.0 → 7.5.0

package/src/FloatingPanel/useFloatingPanel.spec.tsx

@@ -1,26 +1,54 @@
 /**
- * OVERLAY_ANCHOR_GAP rule (theme/layoutTokens): anchored listbox panels match
- * the trigger width EXACTLY — no oversize fudge. These specs pin the size
- * middleware's min-width so a regression back to `width + 8` (which broke
- * flush start-alignment via shift() and let trigger decorations ghost around
- * the panel) fails loudly.
+ * The FloatingPanel family's anchoring and width contract (MPO-38, Clay's
+ * ruling 2026-08-28).
+ *
+ * COVER is the defining behaviour: a panel attaches to the trigger it was
+ * opened from and does not float clear of it. Before this landed, four
+ * members took `OVERLAY_ANCHOR_GAP` and measured 3.96–4.00px of daylight
+ * between trigger bottom and panel top.
+ *
+ * WIDTH is three declared modes, not a boolean. `fit-content` ignores the
+ * trigger; `match-trigger` is the trigger's width EXACTLY for content both
+ * narrower and wider; `at-least-trigger` (the default) is max(trigger,
+ * content) — the floor that keeps a panel from coming out narrower than the
+ * control that opened it.
  */
 import { waitFor } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { describe, expect, it } from "vitest";
-import { useFloatingPanel } from "./useFloatingPanel";
+import {
+  type PanelWidthMode,
+  panelAnchorOffset,
+  resolvePanelWidthMode,
+  useFloatingPanel,
+} from "./useFloatingPanel";
 
-function Harness({ open, fitContent }: { open: boolean; fitContent?: boolean }) {
+function Harness({
+  open,
+  fitContent,
+  widthMode,
+}: {
+  open: boolean;
+  fitContent?: boolean;
+  widthMode?: PanelWidthMode;
+}) {
   const panel = useFloatingPanel({
     open,
     onOpenChange: () => {},
     useAutoUpdate: false,
     fitContent,
+    widthMode,
   });
   return (
     <>
       <div data-testid="anchor-trigger" ref={panel.setReferenceRef} />
-      {panel.mounted && <div data-testid="anchor-floating" ref={panel.refs.setFloating} />}
+      {panel.mounted && (
+        <div
+          data-testid="anchor-floating"
+          data-panel-y={String(panel.y)}
+          ref={panel.refs.setFloating}
+        />
+      )}
     </>
   );
 }
@@ -37,23 +65,104 @@ function mockRect(el: HTMLElement, rect: { x: number; y: number; width: number;
     }) as DOMRect;
 }
 
-describe("useFloatingPanel width matching", () => {
-  it("sets the panel min-width to the trigger width exactly", async () => {
-    const result = renderWithProviders(<Harness open={false} />);
-    mockRect(result.getByTestId("anchor-trigger"), { x: 16, y: 16, width: 240, height: 44 });
-    result.rerender(<Harness open />);
+/** Open the panel against a trigger of a known geometry and hand back the
+ *  floating element once floating-ui has positioned it. */
+async function openAgainstTrigger(
+  props: { fitContent?: boolean; widthMode?: PanelWidthMode },
+  triggerRect: { x: number; y: number; width: number; height: number },
+) {
+  const result = renderWithProviders(<Harness open={false} {...props} />);
+  mockRect(result.getByTestId("anchor-trigger"), triggerRect);
+  result.rerender(<Harness open {...props} />);
+  await waitFor(() => {
+    expect(result.getByTestId("anchor-floating")).toBeTruthy();
+  });
+  return result;
+}
+
+const trigger = { x: 16, y: 16, width: 240, height: 44 };
+
+describe("FloatingPanel anchoring (MPO-38 cover ruling)", () => {
+  it("attaches to the trigger with no gap", () => {
+    // The house token IS the contract; a member cannot opt back into 4px
+    // without changing the token every member reads.
+    expect(panelAnchorOffset).toBe(0);
+  });
+
+  it("places the panel top on the trigger's bottom edge, not 4px below it", async () => {
+    const result = await openAgainstTrigger({}, trigger);
+    await waitFor(() => {
+      const y = Number(result.getByTestId("anchor-floating").dataset.panelY);
+      // trigger.bottom = 16 + 44 = 60. Anything larger is daylight.
+      expect(y).toBe(60);
+    });
+  });
+});
+
+describe("FloatingPanel width modes (MPO-38)", () => {
+  it("resolves the deprecated boolean onto the three modes", () => {
+    expect(resolvePanelWidthMode(undefined, undefined)).toBe("at-least-trigger");
+    expect(resolvePanelWidthMode(undefined, false)).toBe("at-least-trigger");
+    expect(resolvePanelWidthMode(undefined, true)).toBe("fit-content");
+    // An explicit mode always wins over the boolean, in both directions.
+    expect(resolvePanelWidthMode("match-trigger", true)).toBe("match-trigger");
+    expect(resolvePanelWidthMode("fit-content", false)).toBe("fit-content");
+  });
+
+  it("at-least-trigger writes min-width only, so content may still grow it", async () => {
+    const result = await openAgainstTrigger({ widthMode: "at-least-trigger" }, trigger);
+    await waitFor(() => {
+      const el = result.getByTestId("anchor-floating");
+      expect(el.style.minWidth).toBe("240px");
+      expect(el.style.width).toBe("");
+      expect(el.style.maxWidth).toBe("");
+    });
+  });
+
+  it("at-least-trigger is what the bare default means", async () => {
+    const result = await openAgainstTrigger({}, trigger);
+    await waitFor(() => {
+      expect(result.getByTestId("anchor-floating").style.minWidth).toBe("240px");
+    });
+  });
+
+  it("at-least-trigger is what an explicit fitContent={false} means", async () => {
+    const result = await openAgainstTrigger({ fitContent: false }, trigger);
     await waitFor(() => {
       expect(result.getByTestId("anchor-floating").style.minWidth).toBe("240px");
     });
   });
 
-  it("leaves width alone for fitContent panels", async () => {
-    const result = renderWithProviders(<Harness open={false} fitContent />);
-    mockRect(result.getByTestId("anchor-trigger"), { x: 16, y: 16, width: 240, height: 44 });
-    result.rerender(<Harness open fitContent />);
+  it("match-trigger pins the width exactly — narrow content cannot shrink it", async () => {
+    const result = await openAgainstTrigger({ widthMode: "match-trigger" }, trigger);
     await waitFor(() => {
-      expect(result.getByTestId("anchor-floating")).toBeTruthy();
+      const el = result.getByTestId("anchor-floating");
+      expect(el.style.width).toBe("240px");
+      expect(el.style.minWidth).toBe("240px");
+      expect(el.style.maxWidth).toBe("240px");
     });
+  });
+
+  it("match-trigger pins the width exactly — wide content cannot grow it", async () => {
+    // max-width is the half at-least-trigger does not write, and it is the
+    // half that stops a wide option list from overflowing the trigger.
+    const wide = { x: 16, y: 16, width: 96, height: 44 };
+    const result = await openAgainstTrigger({ widthMode: "match-trigger" }, wide);
+    await waitFor(() => {
+      expect(result.getByTestId("anchor-floating").style.maxWidth).toBe("96px");
+    });
+  });
+
+  it("fit-content leaves every width channel alone", async () => {
+    const result = await openAgainstTrigger({ widthMode: "fit-content" }, trigger);
+    const el = result.getByTestId("anchor-floating");
+    expect(el.style.minWidth).toBe("");
+    expect(el.style.width).toBe("");
+    expect(el.style.maxWidth).toBe("");
+  });
+
+  it("fitContent still reaches fit-content, so existing consumers do not move", async () => {
+    const result = await openAgainstTrigger({ fitContent: true }, trigger);
     expect(result.getByTestId("anchor-floating").style.minWidth).toBe("");
   });
 });

package/src/FloatingPanel/useFloatingPanel.ts

@@ -1,6 +1,6 @@
 import type { Middleware, Placement } from "@floating-ui/react";
 import { autoUpdate, offset, shift, size, useFloating } from "@floating-ui/react";
-import { OVERLAY_ANCHOR_GAP, useResolvedKnobs } from "@multiplatform.one/theme";
+import { OVERLAY_ATTACH_GAP, useResolvedKnobs } from "@multiplatform.one/theme";
 import {
   type Dispatch,
   type RefObject,
@@ -33,10 +33,24 @@ function roundToDevicePixel(value: number): number {
 export const panelAnimationDuration = 180;
 export const panelGrowDuration = 200;
 export const panelViewportPadding = 10;
-/** Gap between trigger and panel (Radix / Apple popover offset). Restored
- * after the 2026-08-14 merge dropped it while its importers survived —
- * aliased to the house overlay gap so there is one source (Axiom 5). */
-export const panelAnchorOffset = OVERLAY_ANCHOR_GAP;
+/** Gap between trigger and panel. Clay's cover ruling (MPO-38) makes this
+ * ZERO for the FloatingPanel family: the panel attaches to the trigger it
+ * was opened from. Aliased to the house token so there is one source
+ * (Axiom 5); `OVERLAY_ANCHOR_GAP` still governs FREE overlays. */
+export const panelAnchorOffset = OVERLAY_ATTACH_GAP;
+
+/**
+ * How a panel's width relates to the trigger it opened from (MPO-38).
+ * Three declared modes, not a boolean:
+ * - `"fit-content"` — content-sized; the trigger's width is ignored. For
+ *   icon-button triggers, where matching a 32px button would be absurd.
+ * - `"match-trigger"` — width EXACTLY the trigger's, both when the content
+ *   is narrower and when it is wider. The content scrolls or wraps.
+ * - `"at-least-trigger"` — `max(trigger, content)`. The default, and the
+ *   floor for every panel opened from a field-shaped trigger: a panel
+ *   narrower than the control you clicked is not reachable.
+ */
+export type PanelWidthMode = "fit-content" | "match-trigger" | "at-least-trigger";
 export const panelTransition = `opacity ${panelAnimationDuration}ms ease-out, transform ${panelAnimationDuration}ms ease-out, top ${panelGrowDuration}ms ease-out, max-height ${panelGrowDuration}ms ease-out, height ${panelGrowDuration}ms ease-out`;
 
 // ── Options ───────────────────────────────────────────────────
@@ -66,12 +80,29 @@ export interface UseFloatingPanelOptions {
    */
   wheelGrowRef?: RefObject<boolean>;
   /**
-   * When true, the floating panel width is based on its content rather than
-   * matching the trigger element width.
+   * How the panel's width relates to its trigger (MPO-38).
+   * Default `"at-least-trigger"`.
+   */
+  widthMode?: PanelWidthMode;
+  /**
+   * @deprecated Pass `widthMode` instead. `fitContent` is the two-valued
+   * spelling of the same idea and cannot express `"match-trigger"`.
+   * `true` → `"fit-content"`, `false`/undefined → `"at-least-trigger"`.
+   * An explicit `widthMode` always wins.
    */
   fitContent?: boolean;
 }
 
+/** One place that resolves the deprecated boolean onto the three modes, so
+ *  the hook and the component cannot disagree about what a consumer meant. */
+export function resolvePanelWidthMode(
+  widthMode: PanelWidthMode | undefined,
+  fitContent: boolean | undefined,
+): PanelWidthMode {
+  if (widthMode) return widthMode;
+  return fitContent ? "fit-content" : "at-least-trigger";
+}
+
 // ── Return type ───────────────────────────────────────────────
 
 export interface UseFloatingPanelReturn {
@@ -136,8 +167,10 @@ export function useFloatingPanel({
   middleware: middlewareProp,
   useAutoUpdate: useAutoUpdateProp = true,
   wheelGrowRef,
+  widthMode: widthModeProp,
   fitContent,
 }: UseFloatingPanelOptions): UseFloatingPanelReturn {
+  const widthMode = resolvePanelWidthMode(widthModeProp, fitContent);
   const { knobProps } = useResolvedKnobs();
   const hasBorder = knobProps.borderRadius.borderWidth > 0;
   // Radius equality (see measureDrawnRadius): once the trigger has been
@@ -232,12 +265,13 @@ export function useFloatingPanel({
   // ── Floating UI setup ─────────────────────────────────────
 
   const defaultMiddleware: Middleware[] = [
-    offset({ mainAxis: OVERLAY_ANCHOR_GAP }),
+    // Cover ruling (MPO-38): the family ATTACHES to its trigger. Zero.
+    offset({ mainAxis: OVERLAY_ATTACH_GAP }),
     // Horizontal collision handling: panels anchored near the right viewport
     // edge (e.g. a ColorPicker in the last table column) shift back into view
     // instead of clipping. Vertical placement is handled by computePlacement.
     shift({ padding: panelViewportPadding }),
-    ...(fitContent
+    ...(widthMode === "fit-content"
       ? []
       : [
           size({
@@ -247,15 +281,25 @@ export function useFloatingPanel({
               },
               elements,
             }) {
-              // OVERLAY_ANCHOR_GAP rule (theme/layoutTokens): anchored
-              // listboxes match the trigger width EXACTLY. Any oversize here
-              // both breaks the flush start-alignment (a wider panel near the
-              // viewport edge gets shift()ed off the trigger's x) and lets
-              // trigger decorations peek around the panel as ghosted edges.
-              // Content may still grow the panel wider (min-width only).
-              const minWidth = width;
-              Object.assign(floatingStyleRef.current, { minWidth });
-              elements.floating.style.minWidth = `${minWidth}px`;
+              // MPO-38 width modes. `at-least-trigger` writes only min-width,
+              // so content may still grow the panel wider; `match-trigger`
+              // pins all three so the panel is the trigger's width EXACTLY,
+              // for content narrower AND wider than it.
+              //
+              // Any oversize on an anchored listbox breaks the flush
+              // start-alignment (a wider panel near the viewport edge gets
+              // shift()ed off the trigger's x) and lets trigger decorations
+              // peek around the panel as ghosted edges.
+              const style: Record<string, number> =
+                widthMode === "match-trigger"
+                  ? { minWidth: width, width, maxWidth: width }
+                  : { minWidth: width };
+              Object.assign(floatingStyleRef.current, style);
+              elements.floating.style.minWidth = `${width}px`;
+              if (widthMode === "match-trigger") {
+                elements.floating.style.width = `${width}px`;
+                elements.floating.style.maxWidth = `${width}px`;
+              }
             },
             padding: panelViewportPadding,
           }),

package/src/Form/Form.stories.tsx

@@ -104,6 +104,25 @@ export const Basic = () => (
 );
 Basic.storyName = "Main";
 
+export const WithSaveBar = () => (
+  <Form
+    saveBar
+    maxWidth={formReadableMaxWidth}
+    width="100%"
+    formOptions={{
+      defaultValues: {
+        username: "desk-user",
+        email: "desk@example.com",
+      },
+    }}
+    onSubmit={(values) => action("onSubmit")(values)}
+  >
+    <Input label="Username" name="username" required />
+    <Input label="Email" name="email" required />
+  </Form>
+);
+WithSaveBar.storyName = "Save bar";
+
 export const WithValidation = () => (
   <Form
     formOptions={{

package/src/Form/form.spec.tsx

@@ -387,7 +387,7 @@ describe("Form", () => {
       expect(layout?.getAttribute("data-density")).toBe("comfortable");
     });
 
-    it("compact nested scale steps space and size together via shared density", () => {
+    it("compact nested scale steps space without changing size (density≠size)", () => {
       const result = renderWithProviders(
         <Form compact onSubmit={vi.fn()}>
           <YStack>Content</YStack>
@@ -396,7 +396,7 @@ describe("Form", () => {
       const layout = result.container.querySelector("[data-mpo-form-layout]");
       expect(layout?.getAttribute("data-nested")).toBe("true");
       expect(layout?.getAttribute("data-density")).toBe("compact");
-      expect(layout?.getAttribute("data-size")).toBe("small");
+      expect(layout?.getAttribute("data-size")).toBe("medium");
       expect(layout?.getAttribute("data-gap")).toBe("$2");
     });
 
@@ -410,6 +410,8 @@ describe("Form", () => {
       );
       const actions = result.container.querySelector("[data-mpo-form-actions]");
       expect(actions?.getAttribute("data-gap")).toBe("$2");
+      expect(actions?.getAttribute("data-size")).toBe("large");
+      expect(actions?.getAttribute("data-density")).toBe("comfortable");
     });
   });
 });

package/src/Form/index.tsx

@@ -17,6 +17,7 @@ import {
   YStack,
   isWeb,
 } from "tamagui";
+import { ContextualSaveBar, type ContextualSaveBarProps } from "../ContextualSaveBar";
 import { ErrorSummary, collectFormFieldErrors, type ErrorSummaryItem } from "../ErrorSummary";
 import { RequiredMarkingContext, mapHouseRequiredMarking } from "../requiredMarking";
 import { type FormValidateOn, resolveEffectiveValidateOn } from "./validateOn";
@@ -66,6 +67,22 @@ export function useFormValidate(): FormValidateContextValue {
   return useContext(FormValidateContext);
 }
 
+export type FormSaveMode = "embedded" | "declarative";
+
+export interface FormSaveModeContextValue {
+  mode: FormSaveMode;
+  onAutoCommit?: (name: string, value: unknown) => void;
+}
+
+const defaultSaveMode: FormSaveModeContextValue = { mode: "embedded" };
+
+/** DG-ACT-06 — declarative forms stage text/checkbox/radio; switches auto-commit. */
+export const FormSaveModeContext = createContext<FormSaveModeContextValue>(defaultSaveMode);
+
+export function useFormSaveMode(): FormSaveModeContextValue {
+  return useContext(FormSaveModeContext);
+}
+
 export interface FormProps<TFormData, _TFormValidator = any> extends Omit<
   TamaguiFormProps,
   "onSubmit"
@@ -93,12 +110,19 @@ export interface FormProps<TFormData, _TFormValidator = any> extends Omit<
    */
   validateOn?: FormValidateOn;
   /**
-   * Nested scale (LC-73). Steps space + size down one level and wraps
+   * Nested scale (LC-73). Steps space/density down one level and wraps
    * descendants in a compact density Preset so fields inherit the same
-   * scale without a per-field `compact` prop. Density/space still own
+   * gaps without a per-field `compact` prop. Density/space still own
    * gaps; size still owns control height (density≠size).
    */
   compact?: boolean;
+  /**
+   * Desk/record surfaces where the form IS the route (DG-ACT-06). Renders
+   * {@link ContextualSaveBar} and puts fields in declarative save mode —
+   * text/checkbox/radio stage; Switch auto-commits and never raises the bar.
+   * Resting/embedded forms keep {@link FormActions}.
+   */
+  saveBar?: boolean | ContextualSaveBarProps;
 }
 
 function AutoErrorSummary({
@@ -188,6 +212,7 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
   errorSummaryTitle,
   validateOn = "submit",
   compact,
+  saveBar,
   ...tamaguiFormProps
 }: FormProps<TFormData, TFormValidator>) {
   const { knobProps } = useResolvedKnobs(compact === undefined ? undefined : { compact });
@@ -283,34 +308,45 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
     didAutofocusRef.current = true;
   }, [formAutofocusOn, children]);
 
+  const saveBarProps = typeof saveBar === "object" ? saveBar : {};
+  const saveMode: FormSaveModeContextValue = {
+    mode: saveBar ? "declarative" : "embedded",
+    onAutoCommit: saveBarProps.onAutoCommit,
+  };
+
   const formNode = (
     <FormContext.Provider value={form}>
-      <RequiredMarkingContext.Provider value={{ mode: requiredMarkMode }}>
-        <FormValidateProvider form={form} validateOn={validateOn}>
-          <TamaguiForm ref={setFormRef} onSubmit={handleSubmit} {...tamaguiFormProps}>
-            <YStack
-              data-mpo-form-layout=""
-              data-gap={knobProps.gap.gap}
-              data-density={knobProps.density}
-              data-size={knobProps.size}
-              data-nested={compact ? "true" : undefined}
-              width="100%"
-              minWidth={0}
-              {...knobProps.gap}
-              {...(tamaguiFormProps.flex != null ? { flex: tamaguiFormProps.flex as never } : {})}
-            >
-              {showErrorSummary ? (
-                <AutoErrorSummary
-                  form={form}
-                  title={errorSummaryTitle}
-                  formElement={formElementRef.current}
-                />
-              ) : null}
-              {children}
-            </YStack>
-          </TamaguiForm>
-        </FormValidateProvider>
-      </RequiredMarkingContext.Provider>
+      <FormSaveModeContext.Provider value={saveMode}>
+        <RequiredMarkingContext.Provider value={{ mode: requiredMarkMode }}>
+          <FormValidateProvider form={form} validateOn={validateOn}>
+            <TamaguiForm ref={setFormRef} onSubmit={handleSubmit} {...tamaguiFormProps}>
+              <YStack
+                data-mpo-form-layout=""
+                data-gap={knobProps.gap.gap}
+                data-density={knobProps.density}
+                data-size={knobProps.size}
+                data-nested={compact ? "true" : undefined}
+                width="100%"
+                minWidth={0}
+                {...knobProps.gap}
+                {...(tamaguiFormProps.flex != null ? { flex: tamaguiFormProps.flex as never } : {})}
+              >
+                {showErrorSummary ? (
+                  <AutoErrorSummary
+                    form={form}
+                    title={errorSummaryTitle}
+                    formElement={formElementRef.current}
+                  />
+                ) : null}
+                {children}
+                {saveBar ? (
+                  <ContextualSaveBar {...(typeof saveBar === "object" ? saveBar : {})} />
+                ) : null}
+              </YStack>
+            </TamaguiForm>
+          </FormValidateProvider>
+        </RequiredMarkingContext.Provider>
+      </FormSaveModeContext.Provider>
     </FormContext.Provider>
   );
 
@@ -334,6 +370,8 @@ export function FormActions({ children, gap }: FormActionsProps) {
     <XStack
       data-mpo-form-actions=""
       data-gap={String(resolvedGap)}
+      data-density={knobProps.density}
+      data-size={knobProps.size}
       gap={resolvedGap as never}
       alignSelf="flex-start"
       alignItems="center"

package/src/FormGrid.spec.tsx

@@ -151,9 +151,21 @@ describe("FormGrid", () => {
     );
     const grid = result.container.querySelector("[data-mpo-form-grid]");
     expect(grid?.getAttribute("data-density")).toBe("compact");
-    expect(grid?.getAttribute("data-size")).toBe("small");
+    expect(grid?.getAttribute("data-size")).toBe("medium");
     expect(grid?.getAttribute("data-gap")).toBe("$2");
   });
+
+  it("spreads the space-recipe gap fragment (not a raw 16)", () => {
+    const result = renderWithProviders(
+      <Preset overrides={{ space: "large" }}>
+        <FormGrid>
+          <div>a</div>
+        </FormGrid>
+      </Preset>,
+    );
+    const grid = result.container.querySelector("[data-mpo-form-grid]");
+    expect(grid?.getAttribute("data-gap")).toBe("$5");
+  });
 });
 
 describe("FieldGroup", () => {

package/src/FormGrid.tsx

@@ -54,7 +54,8 @@ function resolveWideColumns(
  */
 export function FormGrid({ columns = 1, maxColumns = 2, gap, compact, children }: FormGridProps) {
   const { knobProps } = useResolvedKnobs(compact === undefined ? undefined : { compact });
-  const resolvedGap = gap ?? knobProps.gap.gap;
+  const gapFragment = gap === undefined ? knobProps.gap : { gap };
+  const resolvedGap = gapFragment.gap;
   const wideColumns = resolveWideColumns(columns, maxColumns);
 
   if (isWeb) {
@@ -63,6 +64,7 @@ export function FormGrid({ columns = 1, maxColumns = 2, gap, compact, children }
         columns={wideColumns}
         maxColumns={maxColumns}
         gap={resolvedGap}
+        gapFragment={gapFragment}
         density={knobProps.density}
         size={knobProps.size}
       >
@@ -76,6 +78,7 @@ export function FormGrid({ columns = 1, maxColumns = 2, gap, compact, children }
       columns={wideColumns}
       maxColumns={maxColumns}
       gap={resolvedGap}
+      gapFragment={gapFragment}
       density={knobProps.density}
       size={knobProps.size}
     >
@@ -88,6 +91,7 @@ function FormGridWeb({
   columns,
   maxColumns,
   gap,
+  gapFragment,
   density,
   size,
   children,
@@ -95,6 +99,7 @@ function FormGridWeb({
   columns: FormGridColumns;
   maxColumns: FormGridColumns;
   gap: number | string;
+  gapFragment: { gap: number | string };
   density: string;
   size: string;
   children: ReactNode;
@@ -148,7 +153,7 @@ function FormGridWeb({
       data-gap={String(gap)}
       data-density={density}
       data-size={size}
-      gap={gap as never}
+      {...gapFragment}
       width="100%"
       minWidth={0}
       style={style}
@@ -162,6 +167,7 @@ function FormGridNative({
   columns,
   maxColumns,
   gap,
+  gapFragment,
   density,
   size,
   children,
@@ -169,6 +175,7 @@ function FormGridNative({
   columns: FormGridColumns;
   maxColumns: FormGridColumns;
   gap: number | string;
+  gapFragment: { gap: number | string };
   density: string;
   size: string;
   children: ReactNode;
@@ -208,7 +215,7 @@ function FormGridNative({
 
   return (
     <YStack
-      gap={gap as never}
+      {...gapFragment}
       width="100%"
       data-mpo-form-grid=""
       data-columns={effectiveColumns}
@@ -219,7 +226,7 @@ function FormGridNative({
       data-size={size}
     >
       {rows.map((row, rowIndex) => (
-        <XStack key={rowIndex} gap={gap as never}>
+        <XStack key={rowIndex} {...gapFragment}>
           {row.map((child, colIndex) => (
             <YStack key={colIndex} flex={1} minWidth={0}>
               {child}

package/src/FormSection.tsx

@@ -81,15 +81,23 @@ export function FormSection({
         useFieldset ? (
           <Text
             render="legend"
+            data-mpo-legend=""
             {...knobProps.label}
-            {...knobProps.heading}
+            fontWeight="400"
+            color={knobProps.textAccentColor}
             // legend is inline by default; stretch to a full heading row
             style={{ padding: 0, marginBottom: 0, float: "left", width: "100%" } as never}
           >
             {label}
           </Text>
         ) : (
-          <Text {...knobProps.label} {...knobProps.heading} role="heading" aria-level={3}>
+          <Text
+            {...knobProps.label}
+            fontWeight="400"
+            color={knobProps.textAccentColor}
+            role="heading"
+            aria-level={3}
+          >
             {label}
           </Text>
         )
@@ -101,9 +109,11 @@ export function FormSection({
 
 /**
  * Gallery Fieldset — semantic fieldset/legend grouping.
- * Alias of {@link FormSection} (same API, form-section rhythm tokens).
+ * Named export of {@link FormSection} (same API, form-section rhythm tokens).
  */
-export const Fieldset = FormSection;
+export function Fieldset(props: FormSectionProps) {
+  return <FormSection {...props} />;
+}
 export type FieldsetProps = FormSectionProps;
 
 export interface FormSectionStackProps {