@multiplatform.one/frappe-ui 7.8.0 → 7.10.0

package/src/FrappeChartCard.spec.tsx

@@ -0,0 +1,179 @@
+/**
+ * MPO-287: a `dataSource` with no data source in scope is a misconfiguration,
+ * not static mode — the same defect MPO-237 fixed one component over. The
+ * card asked for a computed series and there is nowhere to compute it, so
+ * `config.data` must never be painted as the series: a plausible shape
+ * presented confidently is worse than a visible gap, because nothing
+ * downstream can tell it was never computed.
+ *
+ * Static mode (no `dataSource` at all) is the documented, intended path and
+ * is asserted here too, so the fix cannot over-correct into it. A fixture
+ * corpus is a data source (MPO-228), so it stands in for a baseURL and must
+ * not trip the guard.
+ *
+ * The chart body itself is not assertable here: ChartSurface measures its
+ * own width through `onLayout`, which never fires in happy-dom, so no SVG
+ * reaches the DOM. Two things stand in. The card's plain title renders only
+ * when a series reached `ChartCard` — the skeleton, the empty surface and
+ * the not-configured surface each carry different text. And `formatLabel`
+ * is called once per computed group, so spying on it proves whether the
+ * aggregate ran at all.
+ */
+
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { FrappeChartCard } from "./FrappeChartCard";
+import { FrappeProvider } from "./FrappeProvider";
+import { __resetFrappeDevWarnSeen } from "./shared/devWarn";
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+beforeEach(() => {
+  __resetFrappeDevWarnSeen();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const config = {
+  id: "todo-by-status",
+  title: "ToDos by Status",
+  type: "bar" as const,
+  data: [
+    { label: "Open", value: 41 },
+    { label: "Closed", value: 7 },
+  ],
+};
+
+const dataSource = { doctype: "ToDo", groupBy: "status" };
+
+const todos = [
+  { name: "TD-1", doctype: "ToDo", status: "Open" },
+  { name: "TD-2", doctype: "ToDo", status: "Open" },
+  { name: "TD-3", doctype: "ToDo", status: "Closed" },
+];
+
+describe("FrappeChartCard with a dataSource and no baseURL (MPO-287)", () => {
+  it("does not render config.data as though it were the computed series", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderWithProviders(<FrappeChartCard config={config} dataSource={dataSource} />);
+
+    expect(screen.queryByText("ToDos by Status")).toBeNull();
+    expect(screen.getByText("ToDos by Status is not configured")).toBeInTheDocument();
+    expect(screen.getByText(/no Frappe baseURL is in scope/)).toBeInTheDocument();
+  });
+
+  it("logs a development warning naming the missing baseURL", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderWithProviders(<FrappeChartCard config={config} dataSource={dataSource} />);
+
+    const line = warn.mock.calls.map((call) => String(call[0])).join("\n");
+    expect(line).toContain("[frappe-ui] chart-datasource-without-baseurl");
+    expect(line).toContain("baseURL");
+    expect(line).toContain("component=FrappeChartCard");
+    expect(line).toContain("id=todo-by-status");
+    expect(line).toContain("doctype=ToDo");
+  });
+
+  it("warns once per card, not once per render", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { rerender } = renderWithProviders(
+      <FrappeChartCard config={config} dataSource={dataSource} />,
+    );
+    rerender(<FrappeChartCard config={{ ...config }} dataSource={dataSource} />);
+    rerender(<FrappeChartCard config={{ ...config }} dataSource={dataSource} />);
+
+    const lines = warn.mock.calls.filter((call) =>
+      String(call[0]).includes("chart-datasource-without-baseurl"),
+    );
+    expect(lines).toHaveLength(1);
+  });
+
+  it("stays silent in production", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const previous = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+    try {
+      renderWithProviders(<FrappeChartCard config={config} dataSource={dataSource} />);
+    } finally {
+      process.env.NODE_ENV = previous;
+    }
+
+    expect(
+      warn.mock.calls.filter((call) =>
+        String(call[0]).includes("chart-datasource-without-baseurl"),
+      ),
+    ).toHaveLength(0);
+  });
+});
+
+describe("FrappeChartCard configured paths stay untouched (MPO-287)", () => {
+  it("renders config.data with no warning when no dataSource is set", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderWithProviders(<FrappeChartCard config={config} />);
+
+    expect(screen.getByText("ToDos by Status")).toBeInTheDocument();
+    expect(screen.queryByText("ToDos by Status is not configured")).toBeNull();
+    expect(
+      warn.mock.calls.filter((call) =>
+        String(call[0]).includes("chart-datasource-without-baseurl"),
+      ),
+    ).toHaveLength(0);
+  });
+
+  it("computes the series, and does not warn, when the provider supplies a baseURL", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const formatLabel = vi.fn((label: string) => label);
+    renderWithProviders(
+      <FrappeProvider baseURL="http://test" fixtures={new InMemoryFixtureProvider({ ToDo: todos })}>
+        <FrappeChartCard config={config} dataSource={{ ...dataSource, formatLabel }} />
+      </FrappeProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByText("ToDos by Status")).toBeInTheDocument());
+    expect([...new Set(formatLabel.mock.calls.map((call) => call[0]))].sort()).toEqual([
+      "Closed",
+      "Open",
+    ]);
+    expect(screen.queryByText("ToDos by Status is not configured")).toBeNull();
+    expect(
+      warn.mock.calls.filter((call) =>
+        String(call[0]).includes("chart-datasource-without-baseurl"),
+      ),
+    ).toHaveLength(0);
+  });
+
+  it("treats a fixture corpus as the data source when no baseURL is set (MPO-228)", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const formatLabel = vi.fn((label: string) => label);
+    renderWithProviders(
+      <FrappeProvider fixtures={new InMemoryFixtureProvider({ ToDo: todos })}>
+        <FrappeChartCard config={config} dataSource={{ ...dataSource, formatLabel }} />
+      </FrappeProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByText("ToDos by Status")).toBeInTheDocument());
+    expect([...new Set(formatLabel.mock.calls.map((call) => call[0]))].sort()).toEqual([
+      "Closed",
+      "Open",
+    ]);
+    expect(screen.queryByText("ToDos by Status is not configured")).toBeNull();
+    expect(
+      warn.mock.calls.filter((call) =>
+        String(call[0]).includes("chart-datasource-without-baseurl"),
+      ),
+    ).toHaveLength(0);
+  });
+});

package/src/FrappeChartCard.tsx

@@ -15,6 +15,14 @@
  * (permission failures called out), catalog empty state when the aggregate
  * returns no groups, and a subtle stale dim while a post-event refetch is
  * in flight.
+ *
+ * A `dataSource` with no data source in scope — no `baseURL` from the prop
+ * or a FrappeProvider, and no fixture corpus either — is a misconfiguration,
+ * not static mode: the caller asked for a computed series and there is
+ * nowhere to compute it. The card renders the not-configured surface and
+ * warns in dev. It never falls back to `config.data`, which would present
+ * an uncomputed shape as the series. A fixture corpus answers every read
+ * locally, so it stands in for a baseURL (MPO-228).
  */
 import {
   AsyncBoundary,
@@ -23,12 +31,13 @@ import {
   type ChartCardProps,
   type ChartConfig,
 } from "@multiplatform.one/components";
-import React, { useMemo } from "react";
+import React, { useEffect, useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { YStack, type YStackProps } from "tamagui";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { ChartCard } from "./ChartCard";
 import { useFrappeConfig } from "./FrappeProvider";
+import { frappeDevWarn } from "./shared/devWarn";
 import {
   useFrappeAggregate,
   type FrappeAggregateConnection,
@@ -52,10 +61,18 @@ export interface FrappeChartDataSource {
 }
 
 export interface FrappeChartCardProps extends Omit<ChartCardProps, "config"> {
-  /** Chart chrome (title, type, height…). In live mode `data` is overridden. */
+  /**
+   * Chart chrome (title, type, height…). In live mode `data` is overridden.
+   * With a `dataSource` and no data source in scope, `data` is not rendered
+   * at all.
+   */
   config: Omit<ChartConfig, "data"> & { data?: ChartConfig["data"] };
   /** When set, the chart series goes live against this doctype. */
   dataSource?: FrappeChartDataSource;
+  /**
+   * Falls back to the FrappeProvider's. Required whenever `dataSource` is
+   * set, unless the provider carries a fixture corpus.
+   */
   baseURL?: string;
   auth?: { useToken?: boolean; token?: string; type?: string };
   syncOptions?: unknown;
@@ -94,8 +111,9 @@ export function FrappeChartCard({
   const { t } = useTranslation();
 
   const finalBaseURL = baseURL ?? providerConfig?.baseURL;
+  const fixtures = providerConfig?.fixtures;
   const connection: FrappeAggregateConnection | undefined =
-    dataSource && finalBaseURL
+    dataSource && (finalBaseURL || fixtures)
       ? {
           baseURL: finalBaseURL,
           socketPort: providerConfig?.socketPort,
@@ -104,10 +122,22 @@ export function FrappeChartCard({
           auth: auth ?? providerConfig?.auth,
           syncOptions: syncOptions ?? providerConfig?.syncOptions,
           realtime: providerConfig?.realtime,
-          fixtures: providerConfig?.fixtures,
+          fixtures,
         }
       : undefined;
 
+  const missingConnection = !!dataSource && !connection;
+  const doctype = dataSource?.doctype;
+  useEffect(() => {
+    if (!missingConnection) return;
+    frappeDevWarn("chart-datasource-without-baseurl", {
+      component: "FrappeChartCard",
+      id: config.id,
+      doctype,
+      suggest: "set baseURL on FrappeChartCard or on the FrappeProvider above it",
+    });
+  }, [missingConnection, config.id, doctype]);
+
   const { groups, isLoading, isStale, error, isPermissionError } = useFrappeAggregate(connection, {
     doctype: dataSource?.doctype ?? "",
     aggregate: dataSource?.aggregate,
@@ -128,11 +158,30 @@ export function FrappeChartCard({
     return { ...config, data } as ChartConfig;
   }, [config, dataSource, groups]);
 
-  // Static passthrough — sanitizing bridge, palette untouched.
-  if (!dataSource || !connection) {
+  // Static passthrough — sanitizing bridge, palette untouched. The caller
+  // supplied the series and asked for no computation.
+  if (!dataSource) {
     return <ChartCard config={liveConfig} {...chartCardProps} />;
   }
 
+  // A requested series with nowhere to compute it. `config.data` is the
+  // caller's placeholder, so drawing it here would publish a shape nothing
+  // downstream could tell was never computed.
+  if (!connection) {
+    return (
+      <AsyncBoundary
+        compact
+        error
+        errorTitle={t("{{title}} is not configured", { title: config.title })}
+        errorDescription={t(
+          "This chart reads {{doctype}} live, but no Frappe baseURL is in scope, so the series was never computed.",
+          { doctype: dataSource.doctype },
+        )}
+        {...(chartCardProps as YStackProps)}
+      />
+    );
+  }
+
   if (isLoading) {
     return (
       <ChartCardSkeleton

package/src/FrappeKPICard.spec.tsx

@@ -125,4 +125,29 @@ describe("FrappeKPICard configured paths stay untouched (MPO-237)", () => {
       warn.mock.calls.filter((call) => String(call[0]).includes("kpi-datasource-without-baseurl")),
     ).toHaveLength(0);
   });
+
+  it("treats a fixture corpus as the data source when no baseURL is set (MPO-228)", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderWithProviders(
+      <FrappeProvider
+        fixtures={
+          new InMemoryFixtureProvider({
+            ToDo: [
+              { name: "TD-1", doctype: "ToDo", status: "Open" },
+              { name: "TD-2", doctype: "ToDo", status: "Open" },
+            ],
+          })
+        }
+      >
+        <FrappeKPICard config={config} dataSource={{ doctype: "ToDo" }} />
+      </FrappeProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByText("2")).toBeInTheDocument());
+    expect(screen.queryByText("999")).toBeNull();
+    expect(screen.queryByText("Open ToDos is not configured")).toBeNull();
+    expect(
+      warn.mock.calls.filter((call) => String(call[0]).includes("kpi-datasource-without-baseurl")),
+    ).toHaveLength(0);
+  });
 });

package/src/FrappeKPICard.tsx

@@ -12,11 +12,13 @@
  * (the card dims while a post-event refetch is in flight), and "—" when the
  * aggregate has no result (e.g. avg over an empty set).
  *
- * A `dataSource` with no `baseURL` in scope (neither the prop nor a
- * FrappeProvider) is a misconfiguration, not static mode: the caller asked
- * for a computed figure and there is nowhere to compute it. The card renders
- * the not-configured surface and warns in dev. It never falls back to
- * `config.value`, which would present an uncomputed number as the KPI.
+ * A `dataSource` with no data source in scope — no `baseURL` from the prop
+ * or a FrappeProvider, and no fixture corpus either — is a misconfiguration,
+ * not static mode: the caller asked for a computed figure and there is
+ * nowhere to compute it. The card renders the not-configured surface and
+ * warns in dev. It never falls back to `config.value`, which would present
+ * an uncomputed number as the KPI. A fixture corpus answers every read
+ * locally, so it stands in for a baseURL (MPO-228).
  */
 import {
   AsyncBoundary,
@@ -57,7 +59,10 @@ export interface FrappeKPICardProps extends Omit<YStackProps, "children"> {
   config: KPICardConfig;
   /** When set, the card's value goes live against this doctype. */
   dataSource?: FrappeKPIDataSource;
-  /** Falls back to the FrappeProvider's. Required whenever `dataSource` is set. */
+  /**
+   * Falls back to the FrappeProvider's. Required whenever `dataSource` is
+   * set, unless the provider carries a fixture corpus.
+   */
   baseURL?: string;
   auth?: { useToken?: boolean; token?: string; type?: string };
   syncOptions?: unknown;
@@ -87,8 +92,9 @@ export function FrappeKPICard({
   const { t } = useTranslation();
 
   const finalBaseURL = baseURL ?? providerConfig?.baseURL;
+  const fixtures = providerConfig?.fixtures;
   const connection: FrappeAggregateConnection | undefined =
-    dataSource && finalBaseURL
+    dataSource && (finalBaseURL || fixtures)
       ? {
           baseURL: finalBaseURL,
           socketPort: providerConfig?.socketPort,
@@ -97,21 +103,21 @@ export function FrappeKPICard({
           auth: auth ?? providerConfig?.auth,
           syncOptions: syncOptions ?? providerConfig?.syncOptions,
           realtime: providerConfig?.realtime,
-          fixtures: providerConfig?.fixtures,
+          fixtures,
         }
       : undefined;
 
-  const missingBaseURL = !!dataSource && !finalBaseURL;
+  const missingConnection = !!dataSource && !connection;
   const doctype = dataSource?.doctype;
   useEffect(() => {
-    if (!missingBaseURL) return;
+    if (!missingConnection) return;
     frappeDevWarn("kpi-datasource-without-baseurl", {
       component: "FrappeKPICard",
       id: config.id,
       doctype,
       suggest: "set baseURL on FrappeKPICard or on the FrappeProvider above it",
     });
-  }, [missingBaseURL, config.id, doctype]);
+  }, [missingConnection, config.id, doctype]);
 
   const { value, isLoading, isStale, error, isPermissionError } = useFrappeAggregate(connection, {
     doctype: dataSource?.doctype ?? "",

package/src/FrappeListView.tsx

@@ -298,7 +298,7 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
               {title}
             </Text>
             {subtitleParts.length > 0 && (
-              <Text {...knobProps.body} color={componentColors.text.muted} numberOfLines={1}>
+              <Text {...knobProps.body} color={knobProps.textAccentColor} numberOfLines={1}>
                 {subtitleParts.map((part, index) => (
                   <React.Fragment key={index}>
                     {index > 0 ? " · " : null}
@@ -432,7 +432,7 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
         {...stackProps}
       >
         <Spinner size="large" />
-        <Text {...knobProps.body} color={componentColors.text.muted} marginTop="$2">
+        <Text {...knobProps.body} color={knobProps.textAccentColor} marginTop="$2">
           {t("Loading {{doctype}} schema...", { doctype })}
         </Text>
       </YStack>
@@ -517,17 +517,17 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
         {...knobProps.panelPadding}
         {...knobProps.gap}
       >
-        <Text {...knobProps.label} color={componentColors.text.muted}>
+        <Text {...knobProps.label} color={knobProps.textAccentColor}>
           {t("Filters")}
         </Text>
         {standardFilterFields.length > 0 && (
           <YStack {...knobProps.gap}>
             {standardFilterFields.map((field) => (
               <YStack key={field.fieldname} {...knobProps.gap}>
-                <Text {...knobProps.label} color={componentColors.text.muted}>
+                <Text {...knobProps.label} color={knobProps.textAccentColor}>
                   {field.label || field.fieldname}
                 </Text>
-                <Text {...knobProps.body} color={componentColors.text.muted}>
+                <Text {...knobProps.body} color={knobProps.textAccentColor}>
                   {field.fieldtype === "Select" ? field.options || "—" : "—"}
                 </Text>
               </YStack>
@@ -536,7 +536,7 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
         )}
         {savedFiltersHook.filters.length > 0 && (
           <YStack {...knobProps.gap}>
-            <Text {...knobProps.label} color={componentColors.text.muted}>
+            <Text {...knobProps.label} color={knobProps.textAccentColor}>
               {t("Saved Filters")}
             </Text>
             <SavedFilterDropdown

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

@@ -10,7 +10,7 @@
  * a seeded value is not a user edit).
  */
 
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeAll } from "vitest";
 
 // The first field-module import in a cold fork transforms the whole fields
 // graph (same budget as tests/fieldRenderers.spec.tsx).
@@ -79,6 +79,13 @@ function getDayButton(root: ParentNode, day: number): HTMLButtonElement | undefi
   });
 }
 
+// Warm the graph here, not inside the first `it`: the transform is setup cost
+// (110-155s quiet, past 240s under load), and charging it to an assertion made
+// whichever case ran first time out.
+beforeAll(async () => {
+  await loadDateField();
+}, 900_000);
+
 describe("Date wrapper — late-arriving value display", () => {
   it("a value arriving after mount displays, without onChange", async () => {
     const DateField = await loadDateField();

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

@@ -18,7 +18,7 @@
  * than rendered) and the platform flags.
  */
 
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeAll, beforeEach } from "vitest";
 
 // Same cold-fork budget as the sibling Date.spec.tsx: the first field-module
 // import transforms the whole fields graph.
@@ -132,6 +132,13 @@ async function press(root: ParentNode, text: string) {
 const lastPick = () => mockState.picks[mockState.picks.length - 1];
 const waitForPick = (predicate: () => void) => waitFor(predicate, { timeout: 30_000 });
 
+// Warm the graph here, not inside the first `it`: the transform is setup cost
+// (110-155s quiet, past 240s under load), and charging it to an assertion made
+// whichever case ran first time out.
+beforeAll(async () => {
+  await loadNativeDateField();
+}, 900_000);
+
 beforeEach(() => {
   // The iOS sheet is a portal, so a previous case's chrome would otherwise
   // still be in the document when the next one asserts on it.

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

@@ -17,7 +17,7 @@
  * rather than rendered) and the platform flags. The web half imports neither.
  */
 
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeAll, beforeEach } from "vitest";
 
 // Same cold-fork budget as the sibling Date specs: the first field-module
 // import transforms the whole fields graph.
@@ -176,6 +176,13 @@ async function selectPeriod(period: "AM" | "PM") {
   });
 }
 
+// Warm the graph here, not inside the first `it`: the transform is setup cost
+// (110-155s quiet, past 240s under load), and charging it to an assertion made
+// whichever case ran first time out.
+beforeAll(async () => {
+  await Promise.all([loadWebDateField(), loadNativeDateField()]);
+}, 900_000);
+
 beforeEach(() => {
   // Both halves portal their surfaces, so a previous case's chrome would
   // otherwise still be in the document when the next one queries it.

package/src/fields/DateRange/DateRange.spec.tsx

@@ -2,19 +2,16 @@
  * DateRangeField contract specs. The `Date Range` fieldtype composes the forms
  * DateRangePicker, so the adapter's contract is which props survive the hop.
  *
- * One of them does not, and that is pinned here deliberately: `value` and
- * `onChange` are DECLARED on DateRangeFieldProps and then destructured away
- * (`value: _value`, `onChange: _onChange`) instead of being handed to
- * DateRangePicker. The registry feeds `props.value` straight into the adapter,
- * so a saved Date Range never paints and a picked range never emits. These
- * tests describe today's behaviour and will go red the moment someone wires it
- * up — which is the point: that is the signal to update them alongside the fix.
- * Reported on MPO-123.
+ * `value` and `onChange` used to be DECLARED on DateRangeFieldProps and then
+ * destructured away instead of being handed to the picker, so a saved range
+ * never painted and a picked one never emitted (MPO-137, found by the MPO-123
+ * spec pass). Both are now wired, and the range is carried as the two calendar
+ * dates comma-separated — the shape the registry feeds in and reads back.
  */
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { cleanup } from "@testing-library/react";
+import { act, cleanup, fireEvent, waitFor } from "@testing-library/react";
 import type React from "react";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { getFieldComponent, type FieldRenderProps } from "../../fieldRegistry";
 import { DateRangeField } from ".";
 
@@ -27,6 +24,24 @@ const trigger = (container: HTMLElement) =>
 const combobox = (container: HTMLElement) =>
   container.querySelector('[data-testid="date-picker-trigger"]');
 
+/**
+ * An enabled day cell in the month the picker opened on. The panel is
+ * portaled, and the wide layout renders the previous month first, so the
+ * range's own month is the LAST calendar panel in the document.
+ */
+function getDayButton(day: number): HTMLButtonElement | undefined {
+  const panels = document.body.querySelectorAll('[data-testid="date-picker-calendar"]');
+  const panel = panels[panels.length - 1];
+  if (!panel) return undefined;
+  return Array.from(panel.querySelectorAll('button, [role="button"]')).find((btn) => {
+    const disabled =
+      btn.hasAttribute("disabled") ||
+      btn.getAttribute("aria-disabled") === "true" ||
+      btn.hasAttribute("data-disabled");
+    return btn.textContent?.trim() === String(day) && !disabled;
+  }) as HTMLButtonElement | undefined;
+}
+
 describe("DateRangeField composes the forms DateRangePicker", () => {
   it("renders a single range trigger, not two date inputs", () => {
     const result = renderWithProviders(<DateRangeField label="Period" />);
@@ -84,21 +99,77 @@ describe("DateRangeField composes the forms DateRangePicker", () => {
   });
 });
 
-describe("DateRangeField value gap (MPO-123)", () => {
+describe("DateRangeField controlled value (MPO-137)", () => {
   it("declares value on its props type", () => {
     // Type-level promise: the adapter advertises a controlled value.
     const props: React.ComponentProps<typeof DateRangeField> = { value: "2026-01-01" };
     expect(props.value).toBe("2026-01-01");
   });
 
-  it("but a controlled value does not reach the control — the trigger stays empty", () => {
+  it("paints a saved range on the trigger rather than the placeholder", () => {
+    const result = renderWithProviders(
+      <DateRangeField label="Period" placeholder="From – To" value="2026-01-01,2026-01-31" />,
+    );
+    expect(trigger(result.container)?.value).toBe("Jan 1, 2026 – Jan 31, 2026");
+  });
+
+  it("paints a range that arrives after mount, without emitting (LC-14)", async () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <DateRangeField label="Period" value="" onChange={onChange} />,
+    );
+    expect(trigger(result.container)?.value ?? "").toBe("");
+
+    // Late seed: the engine applies create defaults once meta loads.
+    result.rerender(
+      <DateRangeField label="Period" value="2026-01-01,2026-01-31" onChange={onChange} />,
+    );
+    await waitFor(() => {
+      expect(trigger(result.container)?.value).toBe("Jan 1, 2026 – Jan 31, 2026");
+    });
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("emits the comma-separated wire string once a range is picked", async () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <DateRangeField label="Period" value="2026-03-05,2026-03-31" onChange={onChange} />,
+    );
+    await act(async () => {
+      fireEvent.click(trigger(result.container)!);
+    });
+    // The panel opens on the range's own month; in the wide (dual-calendar)
+    // layout that is the LAST panel, the previous month being the first.
+    await waitFor(() => {
+      expect(getDayButton(15)).toBeTruthy();
+    });
+    // A complete range restarts on the next click, so this one only re-anchors.
+    await act(async () => {
+      fireEvent.click(getDayButton(15)!);
+    });
+    expect(onChange).not.toHaveBeenCalled();
+
+    await act(async () => {
+      fireEvent.click(getDayButton(20)!);
+    });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith("2026-03-15,2026-03-20");
+  });
+
+  it("clearing the range emits the empty wire value", async () => {
+    const onChange = vi.fn();
     const result = renderWithProviders(
-      <DateRangeField label="Period" value="2026-01-01,2026-01-31" />,
+      <DateRangeField label="Period" value="2026-03-05,2026-03-31" onChange={onChange} />,
     );
-    expect(trigger(result.container)?.value).toBe("");
+    await act(async () => {
+      fireEvent.click(
+        result.container.querySelector('[data-testid="date-picker-clear"]') as HTMLElement,
+      );
+    });
+    expect(onChange).toHaveBeenCalledWith("");
   });
 
-  it("and the registry hands that value straight to the adapter, so the drop is on this file", () => {
+  it("the registry hands value and onChange straight to the adapter", () => {
     const Component = getFieldComponent("Date Range")!;
     const element = (Component as Function)({
       value: "2026-01-01,2026-01-31",
@@ -106,6 +177,7 @@ describe("DateRangeField value gap (MPO-123)", () => {
     } as FieldRenderProps) as React.ReactElement<Record<string, any>>;
     expect(element.type).toBe(DateRangeField);
     expect(element.props.value).toBe("2026-01-01,2026-01-31");
+    expect(typeof element.props.onChange).toBe("function");
   });
 });