@multiplatform.one/frappe-ui 6.4.3 → 6.6.0

package/src/fields/Date/Date.spec.tsx

@@ -0,0 +1,149 @@
+/**
+ * Date wrapper value contract (late-value display fix):
+ *
+ * The wrapper used to fold the controlled `value` into the forms DatePicker's
+ * mount-only `defaultValue` and DROP `onChange` — so a doc value arriving
+ * after first paint (create-mode engine seeding on /backoffice/todo/new)
+ * never displayed, and picks never reached the consumer doc. It now passes
+ * `value` through controlled and converts picked Dates back to the Frappe
+ * wire shape. Programmatic value application must not emit onChange (LC-14:
+ * a seeded value is not a user edit).
+ */
+
+import { describe, it, expect, vi } from "vitest";
+
+// The first field-module import in a cold fork transforms the whole fields
+// graph (same budget as tests/fieldRenderers.spec.tsx).
+vi.setConfig({ testTimeout: 240_000 });
+
+// Mock react-native-reanimated to prevent ESM module resolution failures
+// (same shim as tests/fieldRenderers.spec.tsx).
+vi.mock("react-native-reanimated", () => ({
+  default: {
+    useSharedValue: (init: any) => ({ value: init }),
+    useAnimatedStyle: () => ({}),
+    withTiming: (val: any) => val,
+    withSpring: (val: any) => val,
+    createAnimatedComponent: (component: any) => component,
+    runOnJS: (fn: any) => fn,
+    runOnUI: (fn: any) => fn,
+    useDerivedValue: (fn: () => any) => ({ value: fn() }),
+    useAnimatedRef: () => ({ current: null }),
+    Easing: { linear: (v: any) => v, ease: (v: any) => v, bezier: () => (v: any) => v },
+    FadeIn: { duration: () => ({}) },
+    FadeOut: { duration: () => ({}) },
+    Layout: { duration: () => ({}) },
+    Extrapolation: { CLAMP: "clamp" },
+    measure: () => null,
+    scrollTo: () => {},
+    makeMutable: (init: any) => ({ value: init }),
+  },
+  useSharedValue: (init: any) => ({ value: init }),
+  useAnimatedStyle: () => ({}),
+  withTiming: (val: any) => val,
+  withSpring: (val: any) => val,
+  createAnimatedComponent: (component: any) => component,
+  runOnJS: (fn: any) => fn,
+  runOnUI: (fn: any) => fn,
+  useDerivedValue: (fn: () => any) => ({ value: fn() }),
+  useAnimatedRef: () => ({ current: null }),
+  Easing: { linear: (v: any) => v, ease: (v: any) => v, bezier: () => (v: any) => v },
+  FadeIn: { duration: () => ({}) },
+  FadeOut: { duration: () => ({}) },
+  Layout: { duration: () => ({}) },
+}));
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { act, fireEvent, waitFor } from "@testing-library/react";
+import React from "react";
+
+async function loadDateField() {
+  return (await import(".")).Date;
+}
+
+const getDisplayInput = (container: ParentNode) =>
+  container.querySelector("input") as HTMLInputElement | null;
+
+/** Enabled day-cell buttons inside the (portaled) calendar popover. */
+function getDayButton(root: ParentNode, day: number): HTMLButtonElement | undefined {
+  const allButtons = Array.from(
+    root.querySelectorAll('button, [role="button"]'),
+  ) as HTMLButtonElement[];
+  return allButtons.find((btn) => {
+    const text = btn.textContent?.trim() ?? "";
+    const disabled =
+      btn.hasAttribute("disabled") ||
+      btn.getAttribute("aria-disabled") === "true" ||
+      btn.hasAttribute("data-disabled");
+    return text === String(day) && !disabled;
+  });
+}
+
+describe("Date wrapper — late-arriving value display", () => {
+  it("a value arriving after mount displays, without onChange", async () => {
+    const DateField = await loadDateField();
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <DateField label="Due Date" value="" onChange={onChange} type="date" />,
+    );
+    expect(getDisplayInput(result.container)?.value ?? "").toBe("");
+
+    // Late seed: the engine applies create defaults once meta loads.
+    result.rerender(
+      <DateField label="Due Date" value="2026-03-05" onChange={onChange} type="date" />,
+    );
+    await waitFor(() => {
+      expect(getDisplayInput(result.container)?.value).toBe("Mar 5, 2026");
+    });
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+describe("Date wrapper — pick emits the Frappe wire string", () => {
+  it("emits YYYY-MM-DD once for a Date field pick", async () => {
+    const DateField = await loadDateField();
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <DateField label="Due Date" value="2026-03-05" onChange={onChange} type="date" />,
+    );
+    const trigger = getDisplayInput(result.container);
+    expect(trigger).toBeTruthy();
+    await act(async () => {
+      if (trigger) fireEvent.click(trigger);
+    });
+    await waitFor(() => {
+      expect(getDayButton(document.body, 15)).toBeTruthy();
+    });
+    await act(async () => {
+      fireEvent.click(getDayButton(document.body, 15)!);
+    });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith("2026-03-15");
+  });
+
+  it("preserves the existing time part for a Datetime field pick", async () => {
+    const DateField = await loadDateField();
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <DateField
+        label="Starts On"
+        value="2026-03-05 14:30:00"
+        onChange={onChange}
+        type="datetime"
+      />,
+    );
+    const trigger = getDisplayInput(result.container);
+    expect(trigger).toBeTruthy();
+    await act(async () => {
+      if (trigger) fireEvent.click(trigger);
+    });
+    await waitFor(() => {
+      expect(getDayButton(document.body, 20)).toBeTruthy();
+    });
+    await act(async () => {
+      fireEvent.click(getDayButton(document.body, 20)!);
+    });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith("2026-03-20 14:30:00");
+  });
+});

package/src/fields/Date/Date.stories.tsx

@@ -126,7 +126,7 @@ export const AllStates = () => (
     <ControlledDate label="Default (Empty)" type="date" />
     <ControlledDate label="With Value" type="date" value="2026-06-15" />
     <ControlledDate label="Required" type="date" required />
-    <ControlledDate label="With Error" type="date" error="Please select a valid date" />
+    <ControlledDate label="With Error" type="date" error="A valid date is required" />
     <ControlledDate label="Disabled" type="date" value="2026-01-01" disabled />
   </YStack>
 );

package/src/fields/Date/Datetime.stories.tsx

@@ -52,7 +52,7 @@ export const States = (args: StoryProps) => (
     <Controlled {...args} label="Disabled" disabled />
     <Controlled {...args} label="Disabled + error" disabled error="Broken while disabled" />
     <Controlled {...args} label="Required" required />
-    <Controlled {...args} label="Error" error="This field has an error" />
+    <Controlled {...args} label="Error" error="Value does not match the required format" />
     <Controlled {...args} label="Helper text" helperText="Some helpful context" />
   </YStack>
 );

package/src/fields/Date/date.native.tsx

@@ -1,9 +1,15 @@
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  formatAbsoluteDate,
+  formatAbsoluteDateTime,
+  formatTimeOfDay,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import React, { useState, useCallback, useMemo } from "react";
 import { Modal, Pressable, StyleSheet, View } from "react-native";
 import { platform } from "@multiplatform.one/platform";
 import DateTimePicker, { type DateTimePickerEvent } from "@react-native-community/datetimepicker";
 import { Button, Label, Text, XStack, YStack, type YStackProps } from "tamagui";
+import { fromFrappeDateValue, toFrappeDateValue } from "./wire";
 
 export interface DateProps extends Omit<YStackProps, "children" | "onChange"> {
   label?: string;
@@ -19,72 +25,19 @@ export interface DateProps extends Omit<YStackProps, "children" | "onChange"> {
 }
 
 /**
- * Format date to ISO string format for the given type
- */
-function formatValue(date: Date, type: "date" | "datetime" | "time"): string {
-  if (type === "time") {
-    const hours = date.getHours().toString().padStart(2, "0");
-    const minutes = date.getMinutes().toString().padStart(2, "0");
-    return `${hours}:${minutes}`;
-  }
-  if (type === "datetime") {
-    return date.toISOString().slice(0, 16).replace("T", " ");
-  }
-  // date
-  return date.toISOString().slice(0, 10);
-}
-
-/**
- * Parse value string to Date object
- */
-function parseValue(value: string, type: "date" | "datetime" | "time"): Date {
-  if (!value) return new Date();
-
-  if (type === "time") {
-    const [hours, minutes] = value.split(":").map(Number);
-    const date = new Date();
-    date.setHours(hours || 0, minutes || 0, 0, 0);
-    return date;
-  }
-  if (type === "datetime") {
-    // Handle both "YYYY-MM-DD HH:MM" and "YYYY-MM-DDTHH:MM" formats
-    const normalized = value.replace(" ", "T");
-    return new Date(normalized);
-  }
-  // date - YYYY-MM-DD
-  return new Date(value + "T00:00:00");
-}
-
-/**
- * Format display value for the button
+ * Display value for the button — the house registers (LC-12 render channel),
+ * so the native picker reads the same voice as the web picker, table date
+ * cells and the timeline. A picker is an editing surface, so the year is
+ * always shown.
  */
 function formatDisplayValue(value: string, type: "date" | "datetime" | "time"): string {
   if (!value) return "";
 
   try {
-    const date = parseValue(value, type);
-
-    if (type === "time") {
-      return date.toLocaleTimeString(undefined, {
-        hour: "2-digit",
-        minute: "2-digit",
-      });
-    }
-    if (type === "datetime") {
-      return date.toLocaleString(undefined, {
-        year: "numeric",
-        month: "short",
-        day: "numeric",
-        hour: "2-digit",
-        minute: "2-digit",
-      });
-    }
-    // date
-    return date.toLocaleDateString(undefined, {
-      year: "numeric",
-      month: "short",
-      day: "numeric",
-    });
+    const date = fromFrappeDateValue(value, type);
+    if (type === "time") return formatTimeOfDay(date);
+    if (type === "datetime") return formatAbsoluteDateTime(date, { year: "always" });
+    return formatAbsoluteDate(date, { year: "always" });
   } catch {
     return value;
   }
@@ -114,7 +67,7 @@ export function DateNative({
 
   // Parse current value to Date
   const currentDate = useMemo(() => {
-    return value ? parseValue(value, type) : new Date();
+    return value ? fromFrappeDateValue(value, type) : new Date();
   }, [value, type]);
 
   // Determine picker mode
@@ -172,7 +125,7 @@ export function DateNative({
               )
             : selectedDate;
 
-        onChange(formatValue(finalDate, type));
+        onChange(toFrappeDateValue(finalDate, type));
         setShowPicker(false);
         setShowTimePicker(false);
         setTempDate(null);
@@ -183,7 +136,7 @@ export function DateNative({
 
   const handleIOSConfirm = useCallback(() => {
     if (tempDate) {
-      onChange(formatValue(tempDate, type));
+      onChange(toFrappeDateValue(tempDate, type));
     }
     setShowPicker(false);
     setShowTimePicker(false);

package/src/fields/Date/index.tsx

@@ -2,6 +2,7 @@ import type { FormFieldProps, FieldComponentProps } from "@multiplatform.one/for
 import { DatePicker as FormsDatePicker } from "@multiplatform.one/forms";
 import type { DeepKeys } from "@tanstack/form-core";
 import { useProps } from "tamagui";
+import { toFrappeDateValue } from "./wire";
 
 export type DateProps<
   TData extends Record<string, unknown> = Record<string, unknown>,
@@ -40,31 +41,6 @@ export type DateProps<
     inputProps?: Record<string, unknown>;
   };
 
-const pad2 = (n: number) => String(n).padStart(2, "0");
-
-/**
- * Format a picked Date back into the Frappe wire shape for the fieldtype:
- * `YYYY-MM-DD` (Date), `YYYY-MM-DD HH:mm:ss` (Datetime — the picker edits
- * only the date part, so an existing time part on the previous value is
- * preserved), `HH:mm:ss` (Time). Local date parts — Frappe date strings are
- * timezone-naive (same contract as FrappeCalendar's toFrappeFieldValue).
- */
-function toFrappeDateValue(
-  date: globalThis.Date,
-  type: "date" | "datetime" | "time",
-  previousValue: string | undefined,
-): string {
-  const datePart = `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
-  if (type === "time") {
-    return `${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`;
-  }
-  if (type === "datetime") {
-    const previousTime = previousValue?.trim().split(/[ T]/)[1];
-    return `${datePart} ${previousTime ?? "00:00:00"}`;
-  }
-  return datePart;
-}
-
 export function Date<
   TData extends Record<string, unknown> = Record<string, unknown>,
   TName extends string = string,

package/src/fields/Date/wire.spec.ts

@@ -0,0 +1,172 @@
+/**
+ * The Date field's Frappe wire contract, proved in both directions across
+ * timezones — the WRITE counterpart to `parseCalendarDate`'s matrix in
+ * `@multiplatform.one/theme` (tests/dateParsing.spec.tsx covers the read side
+ * through the two Frappe views).
+ *
+ * The field used to serialize picks with `toISOString()`, which renders the
+ * UTC instant rather than the timezone-naive local value Frappe stores. Each
+ * assertion below is paired with a negative control running that old
+ * formulation through the same expectation, so a matrix that stopped
+ * discriminating — because the host stopped honouring `TZ`, say — fails
+ * loudly instead of passing vacuously.
+ */
+
+import { describe, expect, it } from "vitest";
+import { fromFrappeDateValue, toFrappeDateValue } from "./wire";
+
+// Spans UTC, two negative offsets and the far positive extreme (UTC+14), so a
+// serializer that leans on the host zone fails somewhere in this list.
+const ZONES = ["UTC", "America/Los_Angeles", "America/New_York", "Pacific/Kiritimati"] as const;
+
+function inZone<T>(timeZone: string, read: () => T): T {
+  const previous = process.env.TZ;
+  process.env.TZ = timeZone;
+  try {
+    return read();
+  } finally {
+    if (previous === undefined) delete process.env.TZ;
+    else process.env.TZ = previous;
+  }
+}
+
+const pad = (n: number) => String(n).padStart(2, "0");
+const localDay = (date: Date) =>
+  `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+
+/** The formulation this fix replaced, kept as the negative control. */
+function isoWireValue(date: Date, type: "date" | "datetime"): string {
+  return type === "datetime"
+    ? date.toISOString().slice(0, 16).replace("T", " ")
+    : date.toISOString().slice(0, 10);
+}
+
+/**
+ * The two shapes of Date the picker hands back, because which one it is
+ * decides the DIRECTION of the old defect:
+ *   - `midnight` — the field held a value, so the picker was seeded from it;
+ *   - `evening`  — the field was empty, so the picker was seeded with
+ *                  `new Date()` and the pick carries the current wall clock.
+ * Both name Aug 15 2026 on the user's calendar.
+ */
+const DATE_PICKS = {
+  midnight: () => new Date(2026, 7, 15),
+  evening: () => new Date(2026, 7, 15, 18, 30),
+} as const;
+
+describe("toFrappeDateValue — a date-only pick round-trips as a calendar date", () => {
+  for (const pick of ["midnight", "evening"] as const) {
+    it(`persists the day the user picked in every timezone (picker held ${pick})`, () => {
+      for (const timeZone of ZONES) {
+        const result = inZone(timeZone, () => {
+          const wire = toFrappeDateValue(DATE_PICKS[pick](), "date");
+          // Read it straight back: write and read must agree, or a no-op
+          // edit silently rewrites the document (the drag-move defect the
+          // read-path fix found on the Gantt).
+          return { timeZone, wire, readsBackAs: localDay(fromFrappeDateValue(wire, "date")) };
+        });
+        expect(result).toEqual({
+          timeZone,
+          wire: "2026-08-15",
+          readsBackAs: "2026-08-15",
+        });
+      }
+    });
+  }
+
+  it("negative control: the ISO formulation writes a different day, both ways", () => {
+    // UTC+14 before local noon: the UTC day is still yesterday.
+    expect(inZone("Pacific/Kiritimati", () => isoWireValue(DATE_PICKS.midnight(), "date"))).toBe(
+      "2026-08-14",
+    );
+    // UTC−7 after local 17:00: the UTC day has already rolled over.
+    expect(inZone("America/Los_Angeles", () => isoWireValue(DATE_PICKS.evening(), "date"))).toBe(
+      "2026-08-16",
+    );
+    // ...and it agrees with the fixed body exactly where the offset cannot
+    // reach across the date boundary, which is why this shipped for so long.
+    expect(inZone("America/New_York", () => isoWireValue(DATE_PICKS.evening(), "date"))).toBe(
+      "2026-08-15",
+    );
+  });
+});
+
+describe("toFrappeDateValue — a datetime pick preserves the instant", () => {
+  it("round-trips to the same instant and the same wall clock in every timezone", () => {
+    for (const timeZone of ZONES) {
+      const result = inZone(timeZone, () => {
+        const picked = new Date(2026, 7, 15, 15, 0, 0);
+        const wire = toFrappeDateValue(picked, "datetime");
+        const readBack = fromFrappeDateValue(wire, "datetime");
+        return {
+          timeZone,
+          wire,
+          // The instant itself — not merely the digits.
+          instantPreserved: readBack.getTime() === picked.getTime(),
+          readsBackAtHour: readBack.getHours(),
+        };
+      });
+      expect(result).toEqual({
+        timeZone,
+        wire: "2026-08-15 15:00:00",
+        instantPreserved: true,
+        readsBackAtHour: 15,
+      });
+    }
+  });
+
+  it("negative control: the ISO formulation shifts the instant by the whole offset", () => {
+    const shifted = inZone("America/Los_Angeles", () => {
+      const picked = new Date(2026, 7, 15, 15, 0, 0);
+      const wire = isoWireValue(picked, "datetime");
+      const readBack = fromFrappeDateValue(wire, "datetime");
+      return {
+        wire,
+        instantPreserved: readBack.getTime() === picked.getTime(),
+        driftHours: (readBack.getTime() - picked.getTime()) / 3_600_000,
+      };
+    });
+    // 15:00 picked in Los Angeles was persisted as 22:00 and read back as
+    // 22:00 LOCAL — seven hours later than the user chose, every save.
+    expect(shifted).toEqual({ wire: "2026-08-15 22:00", instantPreserved: false, driftHours: 7 });
+  });
+
+  it("keeps an existing time part when only the day was edited (web date-only picker)", () => {
+    for (const separator of [" ", "T"]) {
+      expect(
+        inZone("Pacific/Kiritimati", () =>
+          toFrappeDateValue(new Date(2026, 7, 15), "datetime", `2026-03-05${separator}14:30:00`),
+        ),
+      ).toBe("2026-08-15 14:30:00");
+    }
+  });
+});
+
+describe("toFrappeDateValue — a time pick is a local clock", () => {
+  it("emits local HH:mm:ss, never the UTC clock", () => {
+    for (const timeZone of ZONES) {
+      expect({
+        timeZone,
+        wire: inZone(timeZone, () => toFrappeDateValue(new Date(2026, 7, 15, 15, 45, 30), "time")),
+      }).toEqual({ timeZone, wire: "15:45:30" });
+    }
+  });
+});
+
+describe("fromFrappeDateValue — the read side is local too", () => {
+  it("opens a bare YYYY-MM-DD on local midnight in every timezone", () => {
+    for (const timeZone of ZONES) {
+      expect(
+        inZone(timeZone, () => {
+          const date = fromFrappeDateValue("2026-08-15", "date");
+          return { timeZone, day: localDay(date), hour: date.getHours() };
+        }),
+      ).toEqual({ timeZone, day: "2026-08-15", hour: 0 });
+    }
+  });
+
+  it("negative control: the bare ECMA-262 parse still shifts west of UTC", () => {
+    // If this ever stops shifting, the test above has stopped proving anything.
+    expect(inZone("America/Los_Angeles", () => new Date("2026-08-15").getDate())).toBe(14);
+  });
+});

package/src/fields/Date/wire.ts

@@ -0,0 +1,68 @@
+/**
+ * The Date field's Frappe wire contract, in both directions — one body shared
+ * by the web half (`index.tsx`) and the native half (`date.native.tsx`), so
+ * the same pick persists the same string on either platform.
+ *
+ * Frappe date fields are timezone-NAIVE: `Date` is a bare calendar date
+ * (`YYYY-MM-DD`), `Datetime` is a bare local wall clock
+ * (`YYYY-MM-DD HH:mm:ss`), `Time` is a bare clock (`HH:mm:ss`). None carries an
+ * offset, and every other writer in the client already builds them from LOCAL
+ * parts — `FrappeCalendar` / `FrappeGantt` `toFrappeFieldValue`, backoffice
+ * `CalendarView.toFrappeDateValue`. So does the read side here, and so does
+ * `parseCalendarDate` in `@multiplatform.one/theme`.
+ *
+ * Serializing through `toISOString()` instead renders the UTC instant, which
+ * breaks both halves of that contract: it names the wrong calendar day whenever
+ * the picked local time of day sits across the UTC date boundary (picking
+ * Aug 15 at UTC+14 wrote `2026-08-14`), and it shifts every datetime by the
+ * whole UTC offset, because the value is then read back as local wall clock.
+ */
+
+const pad2 = (n: number) => String(n).padStart(2, "0");
+
+export type FrappeDateFieldType = "date" | "datetime" | "time";
+
+/**
+ * Serialize a picked `Date` into the wire shape for the fieldtype.
+ *
+ * `previousValue` is for pickers that edit only the day: the web half wraps a
+ * date-only calendar, so an existing time part survives the edit. The native
+ * half picks the time too and passes nothing, in which case the datetime
+ * branch uses the picked Date's own local time.
+ */
+export function toFrappeDateValue(
+  date: Date,
+  type: FrappeDateFieldType,
+  previousValue?: string,
+): string {
+  const datePart = `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
+  const timePart = `${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`;
+  if (type === "time") return timePart;
+  if (type === "datetime") {
+    return `${datePart} ${previousValue?.trim().split(/[ T]/)[1] ?? timePart}`;
+  }
+  return datePart;
+}
+
+/**
+ * Read a wire value back into the `Date` the picker opens on. Empty input
+ * seeds on today — this is a picker's initial value, not a parse of stored
+ * data, so it has no null branch.
+ *
+ * A bare `YYYY-MM-DD` gets an explicit local midnight, because
+ * `new Date("YYYY-MM-DD")` means UTC midnight per ECMA-262 and would open the
+ * picker on the previous day west of UTC. A wall clock with no offset is
+ * already read as local per ES2016+.
+ */
+export function fromFrappeDateValue(value: string, type: FrappeDateFieldType): Date {
+  if (!value) return new Date();
+  if (type === "time") {
+    const [hours, minutes] = value.split(":").map(Number);
+    const date = new Date();
+    date.setHours(hours || 0, minutes || 0, 0, 0);
+    return date;
+  }
+  // Accepts both "YYYY-MM-DD HH:MM" and "YYYY-MM-DDTHH:MM".
+  if (type === "datetime") return new Date(value.replace(" ", "T"));
+  return new Date(`${value}T00:00:00`);
+}

package/src/fields/DateRange/DateRange.stories.tsx

@@ -48,7 +48,7 @@ export const States = (args: StoryProps) => (
     <Controlled {...args} label="Disabled" disabled />
     <Controlled {...args} label="Disabled + error" disabled error="Broken while disabled" />
     <Controlled {...args} label="Required" required />
-    <Controlled {...args} label="Error" error="This field has an error" />
+    <Controlled {...args} label="Error" error="Value does not match the required format" />
     <Controlled {...args} label="Helper text" helperText="Some helpful context" />
   </YStack>
 );

package/src/fields/Duration/Duration.stories.tsx

@@ -51,7 +51,7 @@ export const States = (args: StoryProps) => (
     <Controlled {...args} label="Disabled" disabled />
     <Controlled {...args} label="Disabled + error" disabled error="Broken while disabled" />
     <Controlled {...args} label="Required" required />
-    <Controlled {...args} label="Error" error="This field has an error" />
+    <Controlled {...args} label="Error" error="Value does not match the required format" />
     <Controlled {...args} label="Helper text" helperText="Some helpful context" />
   </YStack>
 );

package/src/fields/FileUploadField/FileUploadField.stories.tsx

@@ -56,11 +56,25 @@ export const States = (args: StoryProps) => (
       error="Broken while disabled"
     />
     <FileUploadField {...(args as any)} label="Required" required />
-    <FileUploadField {...(args as any)} label="Error" error="This field has an error" />
+    <FileUploadField
+      {...(args as any)}
+      label="Error"
+      error="Value does not match the required format"
+    />
     <FileUploadField {...(args as any)} label="Helper text" helperText="Some helpful context" />
   </YStack>
 );
 States.args = {} as Partial<StoryProps>;
+// LC-57 allowlist: the Disabled rows demo the disabled dial, and the field's
+// internal upload Button has no disabledReason plumbing yet (component-contract
+// follow-up). The warn still fires; the harvester tolerates exactly this code.
+States.parameters = {
+  guardrailSpecimen: {
+    warns: ["bare-disabled"],
+    reason:
+      "Disabled-dial rows: FileUpload's internal upload Button has no disabledReason plumbing yet.",
+  },
+};
 
 /** Thin-adapter contract probe: readOnly / skeleton / compact forwarding. */
 export const ContractProbe = (args: StoryProps) => (

package/src/fields/Geolocation/Geolocation.stories.tsx

@@ -52,7 +52,7 @@ export const States = (args: StoryProps) => (
     <Controlled {...args} label="Disabled" disabled />
     <Controlled {...args} label="Disabled + error" disabled error="Broken while disabled" />
     <Controlled {...args} label="Required" required />
-    <Controlled {...args} label="Error" error="This field has an error" />
+    <Controlled {...args} label="Error" error="Value does not match the required format" />
     <Controlled {...args} label="Helper text" helperText="Some helpful context" />
   </YStack>
 );
@@ -60,6 +60,17 @@ States.args = {
   label: "Location",
   value: '{"lat": 30.2672, "lng": -97.7431}',
 } as Partial<StoryProps>;
+// LC-57 allowlist: the Disabled rows demo the disabled dial, and Geolocation's
+// internal Locate/Coordinates Buttons have no disabledReason plumbing yet
+// (component-contract follow-up). The warn still fires; the harvester tolerates
+// exactly this code.
+States.parameters = {
+  guardrailSpecimen: {
+    warns: ["bare-disabled"],
+    reason:
+      "Disabled-dial rows: Geolocation's internal action Buttons have no disabledReason plumbing yet.",
+  },
+};
 
 /**
  * Thin-adapter contract probe: forwards readOnly / skeleton / compact through

package/src/fields/Link.stories.tsx

@@ -72,7 +72,7 @@ export const States = (args: StoryProps) =>
       <Controlled {...args} label="Disabled" disabled />
       <Controlled {...args} label="Disabled + error" disabled error="Broken while disabled" />
       <Controlled {...args} label="Required" required />
-      <Controlled {...args} label="Error" error="This field has an error" />
+      <Controlled {...args} label="Error" error="Value does not match the required format" />
       <Controlled {...args} label="Allow create" allowCreate onCreateNew={action("onCreateNew")} />
     </YStack>,
   );

package/src/fields/LongText/LongText.stories.tsx

@@ -51,7 +51,7 @@ export const States = (args: StoryProps) => (
     <Controlled {...args} label="Disabled" disabled />
     <Controlled {...args} label="Disabled + error" disabled error="Broken while disabled" />
     <Controlled {...args} label="Required" required />
-    <Controlled {...args} label="Error" error="This field has an error" />
+    <Controlled {...args} label="Error" error="Value does not match the required format" />
     <Controlled {...args} label="Helper text" helperText="Some helpful context" />
   </YStack>
 );