@multiplatform.one/forms 6.4.2 → 6.6.0

package/src/Button/Button.stories.tsx

@@ -119,7 +119,26 @@ export const CompoundPattern: Story = {
   ),
 };
 
+/**
+ * FOREIGN CONTRAST SPECIMEN (LC-56 STORY-HONESTY): the right column renders the
+ * RAW tamagui Button beside the house Button strictly so the difference stays
+ * visible. Raw primitives here are by design and labeled — knob/contrast probes
+ * skip this story via `parameters.foreignContrastSpecimen`.
+ */
 export const Comparison: Story = {
+  name: "Foreign contrast specimen (raw tamagui)",
+  parameters: {
+    // Machine-readable exemption for knob/contrast probes and the LC-56 linter arm.
+    foreignContrastSpecimen: true,
+    docs: {
+      description: {
+        story:
+          "FOREIGN CONTRAST SPECIMEN (LC-56 STORY-HONESTY). The right column is the raw " +
+          "tamagui Button, rendered for contrast only: it ignores house knobs and intent " +
+          "recipes by design. Probes asserting house rendering must skip this story.",
+      },
+    },
+  },
   render: () => (
     <XStack gap="$6" alignItems="flex-start" padding="$4" flexWrap="wrap">
       <YStack gap="$3" width={200}>

package/src/Button/index.tsx

@@ -19,6 +19,7 @@ import {
   type ButtonProps as TamaguiButtonProps,
   SizableText,
   View,
+  XStack,
   YStack,
   Theme,
   styled,
@@ -173,6 +174,14 @@ export interface ButtonProps extends Omit<TamaguiButtonProps, "form" | "icon" |
    * — bare `disabled` emits `bare-disabled`.
    */
   disabledReason?: string;
+  /**
+   * Where the visible reason renders relative to the control. `"below"`
+   * (default) stacks it under the button — right for forms and vertical
+   * layouts. `"inline"` puts it beside the button on the same line — for
+   * toolbar/control rows, where a stacked reason breaks the row's shared
+   * control height and wraps into cramped multi-line type.
+   */
+  disabledReasonPlacement?: "below" | "inline";
 }
 
 export function Button({
@@ -198,6 +207,7 @@ export function Button({
   noun,
   actionRole,
   disabledReason,
+  disabledReasonPlacement = "below",
   ...props
 }: ButtonProps) {
   const { resolvedForm: formFromHook } = useFormField({ form: formProp });
@@ -360,6 +370,15 @@ export function Button({
       : isCircular
         ? { minWidth: MIN_PRESS_TARGET, minHeight: MIN_PRESS_TARGET }
         : { minHeight: MIN_PRESS_TARGET };
+  // Axiom 3 NULL / LC-18: `circular` is a SHAPE eject, not a radius eject —
+  // a Button is R-SCALE, so in the square world (`borderRadius:none`) it goes
+  // square like every other control. The tamagui `circular` variant expands
+  // to a ~100000 radius that beats a plain borderRadius prop, so this rides
+  // an inline style (same idiom as the DatePicker day cell). Without it every
+  // `circular` Button in the catalog is an undeclared knob-immune shape
+  // (D-09 / LC-60 sweep finding: Pagination prev/next).
+  const circularSquareAtNone =
+    isCircular && knobProps.pointy ? { style: { borderRadius: 0 } } : null;
   const buttonElement = (
     <ButtonFrame
       // DG-ST-03: an explained disable is aria-disabled (focusable, press
@@ -427,6 +446,7 @@ export function Button({
       {...(tabIndex != null ? { tabIndex } : undefined)}
       {...props}
       {...circularPressFloor}
+      {...circularSquareAtNone}
       {...(explainedDisable
         ? {
             // No `title`: hover-only reveals are banned on disabled controls
@@ -466,19 +486,32 @@ export function Button({
 
   // DG-ST-03 explain affordance: visible reason adjacent to the control —
   // discoverable by pointer, touch, keyboard, and SR (aria-describedby)
-  // without any hover interaction (Axiom 12).
+  // without any hover interaction (Axiom 12). "below" stacks (forms);
+  // "inline" keeps toolbar rows on one shared control line, where the
+  // stacked reason wrapped into cramped multi-line type under the button.
+  const reasonText = explainedDisable ? (
+    <SizableText
+      id={reasonId}
+      size="$2"
+      color={formCommonColors.muted}
+      flexShrink={1}
+      data-mp-disabled-reason="true"
+    >
+      {disabledReason}
+    </SizableText>
+  ) : null;
   const explainedElement = explainedDisable ? (
-    <YStack gap="$1" flexShrink={1} data-mp-disabled-reason-wrapper="true">
-      {buttonElement}
-      <SizableText
-        id={reasonId}
-        size="$1"
-        color={formCommonColors.muted}
-        data-mp-disabled-reason="true"
-      >
-        {disabledReason}
-      </SizableText>
-    </YStack>
+    disabledReasonPlacement === "inline" ? (
+      <XStack gap="$2" alignItems="center" flexShrink={1} data-mp-disabled-reason-wrapper="true">
+        {buttonElement}
+        {reasonText}
+      </XStack>
+    ) : (
+      <YStack gap="$1" flexShrink={1} data-mp-disabled-reason-wrapper="true">
+        {buttonElement}
+        {reasonText}
+      </YStack>
+    )
   ) : (
     buttonElement
   );

package/src/ControlGroup/ControlGroup.stories.tsx

@@ -1,3 +1,4 @@
+import type { GuardrailSpecimenParameter } from "@multiplatform.one/theme";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { Input as TamaguiInput, Paragraph, YStack } from "tamagui";
 import { Button } from "../Button";
@@ -69,6 +70,17 @@ export const ChildCounts: Story = {
 };
 
 export const MixedControls: Story = {
+  parameters: {
+    // LC-57 allowlist: the middle group deliberately shows a disabled segment
+    // inside a joined strip. ControlGroup styles its DIRECT children by index,
+    // so Button's visible disabledReason wrapper cannot ride along without
+    // breaking the strip geometry — the same no-room class as icon toolbars.
+    guardrailSpecimen: {
+      warns: ["bare-disabled"],
+      reason:
+        "Disabled-segment specimen: a joined ControlGroup strip has no room for the visible reason line.",
+    } satisfies GuardrailSpecimenParameter,
+  },
   render: () => (
     <YStack gap="$4" maxWidth={480}>
       <ControlGroup>

package/src/FieldDisplay/formatters.ts

@@ -7,7 +7,7 @@
  * either component.
  */
 
-import { formatAbsoluteDate } from "@multiplatform.one/theme";
+import { formatAbsoluteDate, formatCurrency, formatNumber } from "@multiplatform.one/theme";
 
 export const EMPTY = "—";
 
@@ -27,24 +27,20 @@ export function asText(v: any): string {
 
 export interface NumericFormatOptions {
   precision?: number;
-  /** ISO 4217 currency code, e.g. "USD". */
+  /** ISO 4217 currency code (or a symbol a code is known for), e.g. "USD". */
   currency?: string;
 }
 
+/**
+ * Read-only numeric cells speak the house number registers (LC-12 render
+ * channel): the same figure reads identically in a table cell, a KPI tile
+ * and a group aggregate. `precision` pins the fraction digits a Frappe field
+ * declares; the register owns everything else.
+ */
 export function formatNumericText(num: number, options: NumericFormatOptions = {}): string {
   const { precision, currency } = options;
-  if (currency) {
-    return new Intl.NumberFormat(undefined, {
-      style: "currency",
-      currency,
-      minimumFractionDigits: precision,
-      maximumFractionDigits: precision,
-    }).format(num);
-  }
-  return new Intl.NumberFormat(undefined, {
-    minimumFractionDigits: precision,
-    maximumFractionDigits: precision,
-  }).format(num);
+  if (currency) return formatCurrency(num, { precision, symbol: currency });
+  return formatNumber(num, { precision });
 }
 
 // Re-exported for existing consumers; the canonical shape lives in theme.

package/src/FieldLayout.stories.tsx

@@ -46,7 +46,8 @@ export const ErrorStates: Story = {
         id="fl-err-string"
         label="String error"
         helperText="Helper should be hidden"
-        error="This field is invalid"
+        // DG-COPY-02: error copy states the rule broken — never "invalid"/"please"/"error".
+        error="Value must use letters only"
       >
         <TamaguiInput id="fl-err-string" />
       </FieldLayout>
@@ -96,7 +97,7 @@ export const AnatomyEdgeCases: Story = {
       <FieldLayout
         id="fl-long"
         label="Long messages"
-        error="This error message is extremely long and keeps going to make sure long validation copy wraps correctly under the control without pushing the layout sideways or clipping any of its content at narrow widths"
+        error="This validation message is extremely long and keeps going to make sure long validation copy wraps correctly under the control without pushing the layout sideways or clipping any of its content at narrow widths"
       >
         <TamaguiInput id="fl-long" />
       </FieldLayout>

package/src/Form/Form.stories.tsx

@@ -224,9 +224,14 @@ export const DynamicFields = () => {
           label="Account Type"
           name="accountType"
           required
+          // >5 options: shorter single-select lists trip `select-too-few-options` (DG-CTRL-01).
           options={[
             { label: "Personal", value: "personal" },
             { label: "Business", value: "business" },
+            { label: "Nonprofit", value: "nonprofit" },
+            { label: "Government", value: "government" },
+            { label: "Education", value: "education" },
+            { label: "Other", value: "other" },
           ]}
         />
 
@@ -323,18 +328,26 @@ InputWithLinkResolver.parameters = {
   },
 };
 
+// Six entries: still renders without scroll (the "short list" the story demos)
+// while clearing the ≤5 `select-too-few-options` guardrail (DG-CTRL-01).
 const shortPriorityOptions = [
+  { value: "lowest", label: "Lowest" },
   { value: "low", label: "Low" },
   { value: "medium", label: "Medium" },
   { value: "high", label: "High" },
+  { value: "highest", label: "Highest" },
+  { value: "critical", label: "Critical" },
 ];
 
+// Six entries: still the "short list" the story demos, while clearing the ≤5
+// `select-too-few-options` guardrail (DG-CTRL-01).
 const shortCountryOptions: ComboboxOption[] = [
   { value: "us", label: "United States", keywords: "usa america" },
   { value: "ca", label: "Canada", keywords: "north america" },
   { value: "uk", label: "United Kingdom", keywords: "britain england" },
   { value: "de", label: "Germany", keywords: "europe deutschland" },
   { value: "fr", label: "France", keywords: "europe paris" },
+  { value: "jp", label: "Japan", keywords: "asia tokyo" },
 ];
 
 const countryOptions: ComboboxOption[] = [

package/src/Skeleton/index.tsx

@@ -1,4 +1,4 @@
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { radiusClassProps, useResolvedKnobs } from "@multiplatform.one/theme";
 import type { GetProps } from "tamagui";
 import { View, styled, isWeb } from "tamagui";
 
@@ -107,6 +107,10 @@ export function Skeleton({
         : variant === "text" && knobProps.pointy
           ? { borderRadius: 0 }
           : undefined)}
+      // R-PILL (spec Skeleton "circle"): the circular variant stays 1:1 and
+      // round at every radius value, so it declares the class the
+      // `radius:none` sweep licenses it under (D-09 / LC-60).
+      {...(variant === "circular" ? radiusClassProps("R-PILL", "SkeletonCircle") : undefined)}
       {...props}
       {...(mergedStyle ? { style: mergedStyle } : undefined)}
     />

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

@@ -1,10 +1,34 @@
-import { fireEvent } from "@testing-library/react";
+import { fireEvent, render } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import {
+  createThemesBuilder,
+  defaultAccentTheme,
+  defaultBaseTheme,
+  defaultBuilderOptions,
+} from "@multiplatform.one/theme";
+import { configWithoutAnimations } from "@tamagui/config";
+import { animationsCSS } from "@tamagui/config/v5-css";
+import { TamaguiProvider, createTamagui } from "tamagui";
 import { Form } from "../../Form";
 import { Checkbox } from "./Checkbox";
 import { CheckboxGroup } from "./CheckboxGroup";
 
+// House builder themes for the LC-05 mark assertion — created at MODULE
+// scope: tamagui registers a config's theme variables globally at
+// createTamagui time, and a config created after the first render (inside a
+// test body) never resolves its tokens (Progress.spec pattern).
+const houseThemes = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes() as Record<string, Record<string, string>>;
+const houseConfig = createTamagui({
+  ...configWithoutAnimations,
+  animations: animationsCSS,
+  themes: houseThemes as any,
+});
+
 describe("Checkbox", () => {
   describe("without form context", () => {
     it("renders with label", () => {
@@ -256,4 +280,29 @@ describe("CheckboxGroup", () => {
       expect(new Set(ids).size).toBe(2);
     });
   });
+
+  describe("selected mark (LC-05 ONE-EMPHASIS / D-01 census addition)", () => {
+    it("fills the checked box with the accent mark; the unchecked box stays neutral chrome", () => {
+      const { container } = render(
+        <TamaguiProvider config={houseConfig} defaultTheme="light" disableInjectCSS>
+          <Checkbox label="Checked" checked />
+          <Checkbox label="Unchecked" checked={false} />
+        </TamaguiProvider>,
+      );
+      const boxes = Array.from(container.querySelectorAll('[role="checkbox"]'));
+      expect(boxes.length).toBe(2);
+      const checked = boxes.find((b) => b.getAttribute("aria-checked") === "true");
+      const unchecked = boxes.find((b) => b.getAttribute("aria-checked") === "false");
+      expect(checked).toBeTruthy();
+      expect(unchecked).toBeTruthy();
+      // The visible glyph box (a descendant of the 44px transparent target)
+      // carries the accent mark fill only while checked.
+      const marked = (root: Element) =>
+        Array.from(root.querySelectorAll("*")).filter((el) =>
+          (el as HTMLElement).className?.toString().includes("_bg-accentBackg"),
+        );
+      expect(marked(checked!).length).toBeGreaterThan(0);
+      expect(marked(unchecked!).length).toBe(0);
+    });
+  });
 });

package/src/fields/Checkbox/Checkbox.tsx

@@ -1,7 +1,8 @@
 import { CheckIcon as CheckRegular, MinusIcon as MinusRegular } from "@phosphor-icons/react";
+import { useReadableTextOn } from "@multiplatform.one/theme";
 import type { AnyFormApi } from "../../types";
 import type { ReactNode } from "react";
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
 import type {
   CheckedState,
   CheckboxProps as TamaguiCheckboxProps,
@@ -23,7 +24,7 @@ import { getSize } from "@tamagui/get-token";
 import { useIsInTableCell } from "../../shared/tableCellContext";
 import { Skeleton } from "../../Skeleton";
 import { Field, FieldLayout } from "../../fieldLayout";
-import { formCommonColors, formControlColors } from "../../shared/colorRamps";
+import { formCommonColors, formControlColors, formSelectedColors } from "../../shared/colorRamps";
 import {
   clampRadiusForControl,
   clampRadiusInStateProps,
@@ -150,6 +151,15 @@ export function Checkbox({
   const indicatorColor = getVariable(
     tamaguiTheme[accentTokenKey as any]?.get("web") ?? tamaguiTheme.color?.get("web"),
   );
+  // LC-05 ONE-EMPHASIS / D-01 (census addition): the checked box IS the
+  // selection mark, so it fills with the shared accent mark — the checked
+  // Switch track precedent — and the check/minus glyph takes the
+  // luminance-computed anchor for that fill. It painted the LABEL ink tier
+  // (`textAccentColor`) on unchanged neutral chrome — the same defect the
+  // RadioGroup dot carried — so a checked box read as chrome, not as chosen.
+  // When the accent ramp is absent, `onMark` is undefined and the glyph keeps
+  // the previous ink resolution as the declared fallback.
+  const onMark = useReadableTextOn(formSelectedColors.mark);
   const indicatorWeight =
     knobProps.textWeight.fontWeight === "700"
       ? "bold"
@@ -161,12 +171,12 @@ export function Checkbox({
     if (children) return children;
     return (
       <TamaguiCheckbox.Indicator
-        {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+        {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
       >
         {currentChecked === "indeterminate" ? (
-          <MinusRegular color={indicatorColor} weight={indicatorWeight} />
+          <MinusRegular color={onMark ?? indicatorColor} weight={indicatorWeight} />
         ) : (
-          <CheckRegular color={indicatorColor} weight={indicatorWeight} />
+          <CheckRegular color={onMark ?? indicatorColor} weight={indicatorWeight} />
         )}
       </TamaguiCheckbox.Indicator>
     );
@@ -196,20 +206,37 @@ export function Checkbox({
   // Interaction-state tints stay off the (invisible) 44px frame; the knob
   // state props (ring/halo) still apply around the target.
   const stateBaseStyle = { backgroundColor: "transparent" };
-  const glyphBox = (currentChecked: CheckedState | undefined) => (
-    <View
-      width={glyphSize}
-      height={glyphSize}
-      {...knobProps.inputSurface}
-      {...resolvedRadius}
-      backgroundColor={knobProps.outlined ? "transparent" : formControlColors.background}
-      borderColor={formControlColors.border}
-      alignItems="center"
-      justifyContent="center"
-    >
-      {renderIndicator(currentChecked)}
-    </View>
+  // Live checked value for the standalone-uncontrolled branch: the box fill
+  // below is keyed on it (tamagui's internal state only mounts/unmounts the
+  // indicator, it cannot repaint the box).
+  const [uncontrolledChecked, setUncontrolledChecked] = useState<CheckedState | undefined>(
+    defaultValue as CheckedState | undefined,
   );
+  const glyphBox = (currentChecked: CheckedState | undefined) => {
+    // Indeterminate is a selected-ish state: it carries the mark fill too,
+    // with the minus glyph, so "partially chosen" never reads as idle chrome.
+    const isMarked = currentChecked === true || currentChecked === "indeterminate";
+    return (
+      <View
+        width={glyphSize}
+        height={glyphSize}
+        {...knobProps.inputSurface}
+        {...resolvedRadius}
+        backgroundColor={
+          isMarked
+            ? formSelectedColors.mark
+            : knobProps.outlined
+              ? "transparent"
+              : formControlColors.background
+        }
+        borderColor={isMarked ? formSelectedColors.mark : formControlColors.border}
+        alignItems="center"
+        justifyContent="center"
+      >
+        {renderIndicator(currentChecked)}
+      </View>
+    );
+  };
   // Elevation wraps the visible glyph, never the invisible target (cells
   // keep elevation suppressed as before).
   const renderControlContent = (currentChecked: CheckedState | undefined) =>
@@ -308,11 +335,12 @@ export function Checkbox({
         {...nativeCheckboxA11y(typeof error === "string" && error ? error : undefined)}
         onCheckedChange={(val) => {
           if (disabled || readOnly) return;
+          setUncontrolledChecked(val);
           handleValueChange(val);
         }}
         {...(onBlur ? { onBlur } : undefined)}
       >
-        {renderControlContent(checked ?? (defaultValue as CheckedState | undefined))}
+        {renderControlContent(checked ?? uncontrolledChecked)}
       </CheckboxFieldFrame>
     );
 

package/src/fields/Checkbox/index.tsx

@@ -1,7 +1,11 @@
 import type { RovingFocusGroupProps, RovingFocusItemProps } from "@tamagui/roving-focus";
 import { RovingFocusGroup } from "@tamagui/roving-focus";
 import { CheckIcon as CheckRegular } from "@phosphor-icons/react";
-import { ensureFocusVisibleRing, useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  ensureFocusVisibleRing,
+  useReadableTextOn,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import type { ElementRef, KeyboardEvent, PropsWithChildren } from "react";
 import { forwardRef } from "react";
 import type { CheckedState, YStackProps } from "tamagui";
@@ -28,7 +32,7 @@ import {
 } from "./CheckboxCard";
 import { CheckboxFieldFrame } from "./CheckboxFieldFrame";
 import { clampRadiusForControl } from "../../shared/utils";
-import { formControlColors } from "../../shared/colorRamps";
+import { formControlColors, formSelectedColors } from "../../shared/colorRamps";
 
 // ─── Checkboxes Compound Component ────────────────────────────────────────────
 
@@ -133,6 +137,10 @@ const CheckboxesCheckbox = TamaguiCheckbox.styleable((checkboxProps, ref) => {
   const { values, onValuesChange } = CheckboxesContext.useStyledContext();
   const { value: focusItemValue } = FocusItemContext.useStyledContext();
   const { knobProps } = useResolvedKnobs();
+  // LC-05 ONE-EMPHASIS / D-01: the checked box is the selection mark, so it
+  // fills with the shared accent mark (same treatment as fields/Checkbox and
+  // the checked Switch track); unchecked chrome stays neutral.
+  const isMarked = Boolean(values[focusItemValue]);
   const radiusToken = knobProps.borderRadius.borderRadius;
   const cappedRadius = clampRadiusForControl(radiusToken, 2);
   const resolvedRadius =
@@ -196,8 +204,14 @@ const CheckboxesCheckbox = TamaguiCheckbox.styleable((checkboxProps, ref) => {
         height={glyphSize}
         {...knobProps.inputSurface}
         {...resolvedRadius}
-        backgroundColor={knobProps.outlined ? "transparent" : formControlColors.background}
-        borderColor={formControlColors.border}
+        backgroundColor={
+          isMarked
+            ? formSelectedColors.mark
+            : knobProps.outlined
+              ? "transparent"
+              : formControlColors.background
+        }
+        borderColor={isMarked ? formSelectedColors.mark : formControlColors.border}
         alignItems="center"
         justifyContent="center"
       >
@@ -240,9 +254,13 @@ const CheckboxCardDescriptionSized = CheckboxCardDescription.styleable((props, r
 
 const CheckboxesIndicator = TamaguiCheckbox.Indicator.styleable((indicatorProps, ref) => {
   const { children, ...props } = indicatorProps;
+  // LC-05: the glyph rides the accent mark fill, so it takes the
+  // luminance-computed anchor for that fill (never assumed scheme ink);
+  // consumer-provided children keep their own colors (explicit eject).
+  const onMark = useReadableTextOn(formSelectedColors.mark);
   return (
     <TamaguiCheckbox.Indicator ref={ref} {...props}>
-      {children ?? <CheckRegular />}
+      {children ?? <CheckRegular {...(onMark ? { color: onMark } : undefined)} />}
     </TamaguiCheckbox.Indicator>
   );
 });

package/src/fields/ColorPicker/ColorPicker.stories.tsx

@@ -158,7 +158,8 @@ export const WithError: Story = {
   render: (args) => <ColorPicker {...args} />,
   args: {
     label: "Required Color",
-    error: "Please select a valid color",
+    // DG-COPY-02: error copy states the rule broken — never "please"/"invalid"/"error".
+    error: "Color must be a recognized value",
     required: true,
   },
 };

package/src/fields/Combobox/index.tsx

@@ -333,7 +333,7 @@ const ComboboxItem = memo(function ComboboxItem({
         ? // Two-line rows need to grow past the size-variant height.
           { height: "auto", paddingVertical: "$2" }
         : undefined)}
-      {...(ctx.knobProps.transition ? { animation: ctx.knobProps.transition } : undefined)}
+      {...(ctx.knobProps.transition ? { transition: ctx.knobProps.transition } : undefined)}
     >
       {option.description ? (
         <YStack flex={1} minWidth={0}>
@@ -1258,6 +1258,11 @@ function FloatingComboboxCore({
         : {
             borderRadius: knobProps.borderRadius.borderRadius,
             borderWidth: knobProps.borderRadius.borderWidth,
+            // LC-54 PRESS-FLOOR: compact/small size tokens render a sub-44
+            // trigger (the 36px "Allocated To" quick filter breaking the
+            // list's 44px control row) — same floor the house Select holds
+            // on both its trigger variants.
+            minHeight: 44,
           })}
     >
       <SyncFocusToOpen open={open} />
@@ -1497,7 +1502,7 @@ function FloatingComboboxCore({
                           : undefined
                       }
                       onPress={handleCreate}
-                      {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+                      {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
                     >
                       <PlusIcon size={14} color={knobProps.textAccentColor} />
                       <Text
@@ -1538,7 +1543,7 @@ function FloatingComboboxCore({
                       : "transparent"
                   }
                   pressStyle={{ backgroundColor: formInputColors.background.focus }}
-                  {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+                  {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
                 >
                   <PlusIcon size={14} color={knobProps.textAccentColor} />
                   <Text

package/src/fields/DatePicker/DatePicker.spec.tsx

@@ -223,6 +223,99 @@ describe("DatePicker", () => {
     });
   });
 
+  describe("late-arriving value display (create-mode seeding)", () => {
+    // The form branch only ever displayed the mount-time value (`selectedDate`
+    // was never re-synced from field state), so a value applied AFTER first
+    // paint — create-mode engine seeding, form.setFieldValue, live server
+    // merge — never rendered. Adopting a programmatic value must not emit
+    // onChange (LC-14: a seeded value is not a user edit).
+    const getDisplayInput = (container: ParentNode) =>
+      container.querySelector("input") as HTMLInputElement | null;
+
+    it("standalone controlled: a value arriving after mount displays, without onChange", async () => {
+      const DatePicker = await loadDatePicker();
+      const onChange = vi.fn();
+      const onValueChange = vi.fn();
+      const result = renderWithProviders(
+        <DatePicker
+          label="Due Date"
+          value={null}
+          onChange={onChange}
+          onValueChange={onValueChange}
+        />,
+      );
+      expect(getDisplayInput(result.container)?.value ?? "").toBe("");
+
+      // Late seed: the upstream doc value (frappe wire string) arrives after
+      // first paint.
+      result.rerender(
+        <DatePicker
+          label="Due Date"
+          value="2026-03-05"
+          onChange={onChange}
+          onValueChange={onValueChange}
+        />,
+      );
+      await waitFor(() => {
+        expect(getDisplayInput(result.container)?.value).toBe("Mar 5, 2026");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+      expect(onValueChange).not.toHaveBeenCalled();
+    });
+
+    it("form-integrated: a field value set after mount displays, without onChange", async () => {
+      const DatePicker = await loadDatePicker();
+      const onChange = vi.fn();
+      let formApi: { setFieldValue: (name: "date", value: string | null) => void } | undefined;
+      const TestComponent = () => {
+        const form = useForm({ defaultValues: { date: null as string | null } });
+        formApi = form as unknown as typeof formApi;
+        return (
+          <Form form={form}>
+            <DatePicker label="Due Date" name="date" onChange={onChange} />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      expect(getDisplayInput(result.container)?.value ?? "").toBe("");
+
+      await act(async () => {
+        formApi?.setFieldValue("date", "2026-03-05");
+      });
+      await waitFor(() => {
+        expect(getDisplayInput(result.container)?.value).toBe("Mar 5, 2026");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("form-integrated: clearing the field value programmatically clears the display", async () => {
+      const DatePicker = await loadDatePicker();
+      const onChange = vi.fn();
+      let formApi: { setFieldValue: (name: "date", value: string | null) => void } | undefined;
+      const TestComponent = () => {
+        const form = useForm({ defaultValues: { date: "2026-03-05" as string | null } });
+        formApi = form as unknown as typeof formApi;
+        return (
+          <Form form={form}>
+            <DatePicker label="Due Date" name="date" onChange={onChange} />
+          </Form>
+        );
+      };
+      const result = renderWithProviders(<TestComponent />);
+      await waitFor(() => {
+        expect(getDisplayInput(result.container)?.value).toBe("Mar 5, 2026");
+      });
+
+      await act(async () => {
+        formApi?.setFieldValue("date", null);
+      });
+      await waitFor(() => {
+        expect(getDisplayInput(result.container)?.value ?? "").toBe("");
+      });
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
+
   describe("date utilities", () => {
     it("formats display values in the house absolute register and handles null", () => {
       expect(formatDateDisplay(null)).toBe("");