@multiplatform.one/frappe-ui 7.6.3 → 7.7.1

package/src/fields/ReadOnly/ReadOnly.spec.tsx

@@ -0,0 +1,229 @@
+/**
+ * ReadOnly field contract specs. This is the display half of every fieldtype:
+ * SchemaForm swaps a live control for ReadOnly whenever a DocField is
+ * read-only, so what it prints IS the value the user sees. The contract is the
+ * formatting matrix (one per ReadOnlyType), the empty fallback, and the two
+ * types that render more than text — Color (swatch) and Link (pressable).
+ *
+ * Formatted output is asserted against the shared registers
+ * (formatNumericText / formatCurrency / formatPercent / formatDateText /
+ * formatTimeOfDay) rather than against hardcoded strings: the contract is
+ * "ReadOnly speaks the house register", not "ReadOnly speaks en-GB".
+ */
+import { formatDateText, formatNumericText } from "@multiplatform.one/forms";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { formatCurrency, formatPercent, formatTimeOfDay } from "@multiplatform.one/theme";
+import { cleanup, fireEvent, screen } from "@testing-library/react";
+import type React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getFieldComponent, type FieldRenderProps } from "../../fieldRegistry";
+import { ReadOnly } from ".";
+
+afterEach(cleanup);
+
+describe("ReadOnly formatting matrix", () => {
+  it("Data prints the value verbatim", () => {
+    renderWithProviders(<ReadOnly label="Title" type="Data" value="Sales Invoice" />);
+    expect(screen.getByText("Sales Invoice")).toBeTruthy();
+  });
+
+  it("Check prints Yes / No, never true / false", () => {
+    const yes = renderWithProviders(<ReadOnly label="Paid" type="Check" value={true} />);
+    expect(yes.container.textContent).toContain("Yes");
+    expect(yes.container.textContent).not.toContain("true");
+    cleanup();
+    const no = renderWithProviders(<ReadOnly label="Paid" type="Check" value={false} />);
+    expect(no.container.textContent).toContain("No");
+  });
+
+  it("Int rounds and drops the decimals", () => {
+    renderWithProviders(<ReadOnly label="Qty" type="Int" value={3.7} />);
+    expect(screen.getByText(formatNumericText(4, { precision: 0 }))).toBeTruthy();
+  });
+
+  it("Float honours precision", () => {
+    renderWithProviders(<ReadOnly label="Rate" type="Float" value={1.23456} precision={3} />);
+    expect(screen.getByText(formatNumericText(1.23456, { precision: 3 }))).toBeTruthy();
+  });
+
+  it("Currency goes through the money register with the given symbol", () => {
+    renderWithProviders(
+      <ReadOnly label="Total" type="Currency" value={1234.5} currencySymbol="$" precision={2} />,
+    );
+    expect(screen.getByText(formatCurrency(1234.5, { precision: 2, symbol: "$" }))).toBeTruthy();
+  });
+
+  it("Percent goes through the percent register", () => {
+    renderWithProviders(<ReadOnly label="Done" type="Percent" value={42.5} precision={1} />);
+    expect(screen.getByText(formatPercent(42.5, { precision: 1 }))).toBeTruthy();
+  });
+
+  it("Date goes through the date register", () => {
+    renderWithProviders(<ReadOnly label="Posting" type="Date" value="2026-03-04" />);
+    expect(screen.getByText(formatDateText("2026-03-04", { dateFormat: undefined }))).toBeTruthy();
+  });
+
+  it("Datetime carries the time half", () => {
+    const wire = "2026-03-04 14:30:00";
+    renderWithProviders(<ReadOnly label="Modified" type="Datetime" value={wire} />);
+    expect(
+      screen.getByText(formatDateText(wire, { withTime: true, dateFormat: undefined })),
+    ).toBeTruthy();
+  });
+
+  it("Time speaks the time-of-day register, not the raw wire string (LC-12)", () => {
+    renderWithProviders(<ReadOnly label="Start" type="Time" value="14:30:00" />);
+    expect(screen.getByText(formatTimeOfDay("14:30:00"))).toBeTruthy();
+    expect(screen.queryByText("14:30:00")).toBeNull();
+  });
+
+  it("Color uppercases the hex", () => {
+    renderWithProviders(<ReadOnly label="Brand" type="Color" value="#ab12ef" />);
+    expect(screen.getByText("#AB12EF")).toBeTruthy();
+  });
+});
+
+describe("ReadOnly empty handling", () => {
+  it.each([
+    ["undefined", undefined],
+    ["null", null],
+    ["empty string", ""],
+  ])("prints the default dash for %s", (_label, value) => {
+    const result = renderWithProviders(
+      <ReadOnly label="Ref" type="Data" value={value as string | null | undefined} />,
+    );
+    expect(result.container.textContent).toContain("-");
+  });
+
+  it("honours a custom emptyText", () => {
+    const result = renderWithProviders(
+      <ReadOnly label="Ref" type="Data" value={null} emptyText="Not set" />,
+    );
+    expect(result.container.textContent).toContain("Not set");
+  });
+
+  it("an empty Date is empty, not an epoch", () => {
+    const result = renderWithProviders(<ReadOnly label="Posting" type="Date" value="" />);
+    expect(result.container.textContent).toContain("-");
+    expect(result.container.textContent).not.toContain("1970");
+  });
+
+  it("a zero number is a value, not an empty", () => {
+    renderWithProviders(<ReadOnly label="Qty" type="Int" value={0} />);
+    expect(screen.getByText(formatNumericText(0, { precision: 0 }))).toBeTruthy();
+  });
+});
+
+describe("ReadOnly Color swatch", () => {
+  it("renders a swatch beside the text for a 6-digit hex", () => {
+    renderWithProviders(<ReadOnly label="Brand" type="Color" value="#FF0000" />);
+    const text = screen.getByText("#FF0000");
+    expect(text.parentElement?.childElementCount).toBe(2);
+  });
+
+  it("renders a swatch for a 3-digit hex too", () => {
+    renderWithProviders(<ReadOnly label="Brand" type="Color" value="#f00" />);
+    const text = screen.getByText("#F00");
+    expect(text.parentElement?.childElementCount).toBe(2);
+  });
+
+  it("refuses a swatch for a value that is not a hex colour", () => {
+    renderWithProviders(<ReadOnly label="Brand" type="Color" value="red" />);
+    const text = screen.getByText("RED");
+    expect(text.parentElement?.childElementCount).toBe(1);
+  });
+});
+
+describe("ReadOnly Link", () => {
+  it("calls onLinkPress when the value is pressed", () => {
+    const onLinkPress = vi.fn();
+    renderWithProviders(
+      <ReadOnly label="Customer" type="Link" value="CUST-0001" onLinkPress={onLinkPress} />,
+    );
+    fireEvent.click(screen.getByText("CUST-0001"));
+    expect(onLinkPress).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not make an empty Link pressable", () => {
+    const onLinkPress = vi.fn();
+    const result = renderWithProviders(
+      <ReadOnly label="Customer" type="Link" value="" onLinkPress={onLinkPress} />,
+    );
+    fireEvent.click(result.getByText("-"));
+    expect(onLinkPress).not.toHaveBeenCalled();
+  });
+
+  it("a Link with neither href nor handler is plain text", () => {
+    const result = renderWithProviders(<ReadOnly label="Customer" type="Link" value="CUST-1" />);
+    expect(result.container.textContent).toContain("CUST-1");
+  });
+});
+
+describe("ReadOnly chrome", () => {
+  it("shows the label and helperText", () => {
+    const result = renderWithProviders(
+      <ReadOnly label="Status" type="Data" value="Draft" helperText="set by the workflow" />,
+    );
+    expect(result.container.textContent).toContain("Status");
+    expect(result.container.textContent).toContain("set by the workflow");
+  });
+
+  it("skeleton branch hides the value", () => {
+    const result = renderWithProviders(
+      <ReadOnly label="Status" type="Data" value="Draft" skeleton />,
+    );
+    expect(result.container.textContent).not.toContain("Draft");
+  });
+});
+
+describe("registry resolution (Read Only fieldtype)", () => {
+  function propsFor(overrides: Partial<FieldRenderProps> = {}): FieldRenderProps {
+    return { value: "", onChange: () => {}, ...overrides };
+  }
+
+  it("resolves 'Read Only' to ReadOnly", () => {
+    const Component = getFieldComponent("Read Only")!;
+    expect(Component).toBeTruthy();
+    const element = (Component as Function)(
+      propsFor({ value: "Draft", label: "Status" }),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.type).toBe(ReadOnly);
+    expect(element.props.value).toBe("Draft");
+  });
+
+  it("forwards the whole formatting contract, not just the value", () => {
+    const Component = getFieldComponent("Read Only")!;
+    const onLinkPress = () => {};
+    const element = (Component as Function)(
+      propsFor({
+        value: 12.5,
+        type: "Currency",
+        precision: 3,
+        currencySymbol: "€",
+        emptyText: "n/a",
+        dateFormat: "dd-MM-yyyy",
+        datetimeFormat: "dd-MM-yyyy HH:mm",
+        timeFormat: "HH:mm",
+        linkHref: "/app/x",
+        onLinkPress,
+      } as Partial<FieldRenderProps>),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.props.type).toBe("Currency");
+    expect(element.props.precision).toBe(3);
+    expect(element.props.currencySymbol).toBe("€");
+    expect(element.props.emptyText).toBe("n/a");
+    expect(element.props.dateFormat).toBe("dd-MM-yyyy");
+    expect(element.props.datetimeFormat).toBe("dd-MM-yyyy HH:mm");
+    expect(element.props.timeFormat).toBe("HH:mm");
+    expect(element.props.linkHref).toBe("/app/x");
+    expect(element.props.onLinkPress).toBe(onLinkPress);
+  });
+
+  it("does not coerce a null value to an empty string — ReadOnly owns the empty text", () => {
+    const Component = getFieldComponent("Read Only")!;
+    const element = (Component as Function)(
+      propsFor({ value: null as unknown as string }),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.props.value).toBeNull();
+  });
+});

package/src/fields/SmallText/SmallText.spec.tsx

@@ -0,0 +1,175 @@
+/**
+ * SmallText contract specs. Frappe's `Small Text` is the short free-text
+ * fieldtype, and the adapter's promise is that it is the SAME control as
+ * LongText with a smaller row budget (2..4 instead of 6..16) — not a second
+ * textarea implementation, and not an Input with a taller box.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent } from "@testing-library/react";
+import type React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getFieldComponent, type FieldRenderProps } from "../../fieldRegistry";
+import { LongText } from "../LongText";
+import { SmallText } from ".";
+
+afterEach(cleanup);
+
+describe("SmallText composes the forms TextArea", () => {
+  it("renders a textarea, not a single-line input", () => {
+    const result = renderWithProviders(<SmallText label="Note" value="" onChange={() => {}} />);
+    expect(result.getTextArea()).toBeTruthy();
+    expect(result.container.querySelector('input[type="text"]')).toBeNull();
+  });
+
+  it("shows the controlled value", () => {
+    const result = renderWithProviders(
+      <SmallText label="Note" value="short note" onChange={() => {}} />,
+    );
+    expect((result.getTextArea() as HTMLTextAreaElement).value).toBe("short note");
+  });
+
+  it("emits the text through canonical onChange", () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(<SmallText label="Note" value="" onChange={onChange} />);
+    fireEvent.change(result.getTextArea() as HTMLTextAreaElement, { target: { value: "typed" } });
+    expect(onChange).toHaveBeenCalledWith("typed");
+  });
+
+  it("readOnly blocks emission", () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <SmallText label="Note" value="original" readOnly onChange={onChange} />,
+    );
+    const textarea = result.getTextArea() as HTMLTextAreaElement;
+    expect(textarea.hasAttribute("readonly")).toBe(true);
+    fireEvent.change(textarea, { target: { value: "sneaky" } });
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("disabled blocks emission", () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <SmallText label="Note" value="original" disabled onChange={onChange} />,
+    );
+    fireEvent.change(result.getTextArea() as HTMLTextAreaElement, { target: { value: "sneaky" } });
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("forwards maxLength — Frappe's df.length caps a Small Text", () => {
+    const result = renderWithProviders(
+      <SmallText label="Note" value="" maxLength={80} onChange={() => {}} />,
+    );
+    expect((result.getTextArea() as HTMLTextAreaElement).getAttribute("maxlength")).toBe("80");
+  });
+
+  it("forwards placeholder and textAreaProps", () => {
+    const result = renderWithProviders(
+      <SmallText
+        label="Note"
+        value=""
+        placeholder="One or two lines"
+        textAreaProps={{ tabIndex: -1 }}
+        onChange={() => {}}
+      />,
+    );
+    const textarea = result.getTextArea() as HTMLTextAreaElement;
+    expect(textarea.getAttribute("placeholder")).toBe("One or two lines");
+    expect(textarea.getAttribute("tabindex")).toBe("-1");
+  });
+});
+
+/**
+ * The row budget does not reach the DOM as the textarea's `rows` attribute:
+ * TextArea spreads `numberOfLines: minRows` onto the Tamagui TextArea and web
+ * drops it, so `rows` measured 3 for every adapter at every setting. The
+ * budget DOES drive the rendered minimum height, `getFieldHeight(size,
+ * minRows)`, so it is asserted through that. Reported on MPO-123.
+ */
+const minHeightPxOf = (container: HTMLElement) => {
+  const cls = container.querySelector("textarea")?.getAttribute("class") ?? "";
+  const match = /(?:^|\s)_mih-(\d+)px(?:\s|$)/.exec(cls);
+  return match ? Number(match[1]) : undefined;
+};
+
+describe("SmallText row budget", () => {
+  it("opens at a two-row box", () => {
+    const small = renderWithProviders(<SmallText label="Note" value="" onChange={() => {}} />);
+    const smallPx = minHeightPxOf(small.container);
+    cleanup();
+    // LongText's default budget is six rows to SmallText's two, on the same
+    // per-row height — so the ratio is the row count, with no hard-coded px.
+    const long = renderWithProviders(<LongText label="Note" value="" onChange={() => {}} />);
+    const longPx = minHeightPxOf(long.container);
+    expect(smallPx).toBeGreaterThan(0);
+    expect((longPx as number) / (smallPx as number)).toBe(3);
+  });
+
+  it("is shorter than LongText, which is the only thing that distinguishes them", () => {
+    const small = renderWithProviders(<SmallText label="Note" value="" onChange={() => {}} />);
+    const smallPx = minHeightPxOf(small.container) as number;
+    cleanup();
+    const long = renderWithProviders(<LongText label="Note" value="" onChange={() => {}} />);
+    const longPx = minHeightPxOf(long.container) as number;
+    expect(smallPx).toBeLessThan(longPx);
+  });
+
+  it("ignores minHeight — a Small Text does not grow into a Long Text", () => {
+    const plain = renderWithProviders(<SmallText label="Note" value="" onChange={() => {}} />);
+    const plainPx = minHeightPxOf(plain.container);
+    cleanup();
+    const result = renderWithProviders(
+      <SmallText
+        label="Note"
+        value=""
+        onChange={() => {}}
+        {...({ minHeight: 480 } as Record<string, unknown>)}
+      />,
+    );
+    expect(minHeightPxOf(result.container)).toBe(plainPx);
+  });
+});
+
+describe("registry resolution (Small Text fieldtype)", () => {
+  function propsFor(overrides: Partial<FieldRenderProps> = {}): FieldRenderProps {
+    return { value: "", onChange: () => {}, ...overrides };
+  }
+
+  it("resolves 'Small Text' to SmallText, and not to the Long Text adapter", () => {
+    const Component = getFieldComponent("Small Text")!;
+    expect(Component).toBeTruthy();
+    expect(Component).not.toBe(getFieldComponent("Long Text"));
+    const element = (Component as Function)(
+      propsFor({ value: "note", label: "Remark" }),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.type).toBe(SmallText);
+    expect(element.props.value).toBe("note");
+    expect(element.props.label).toBe("Remark");
+  });
+
+  it("substitutes an empty string for a null value", () => {
+    const Component = getFieldComponent("Small Text")!;
+    const element = (Component as Function)(
+      propsFor({ value: null as unknown as string }),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.props.value).toBe("");
+  });
+
+  it("a disabled field also blocks the DOM textarea", () => {
+    const Component = getFieldComponent("Small Text")!;
+    const element = (Component as Function)(propsFor({ disabled: true })) as React.ReactElement<
+      Record<string, any>
+    >;
+    expect(element.props.textAreaProps).toEqual({ readOnly: true, tabIndex: -1 });
+  });
+
+  it("passes helperText / readOnly / skeleton / compact through", () => {
+    const Component = getFieldComponent("Small Text")!;
+    const element = (Component as Function)(
+      propsFor({ helperText: "keep it short", readOnly: true, skeleton: true, compact: true }),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.props.helperText).toBe("keep it short");
+    expect(element.props.readOnly).toBe(true);
+    expect(element.props.skeleton).toBe(true);
+    expect(element.props.compact).toBe(true);
+  });
+});

package/src/fields/shared/EditorPreviewPanes.spec.tsx

@@ -0,0 +1,122 @@
+/**
+ * EditorPreviewPanes contract specs. Both source-editing fields
+ * (MarkdownEditorField, CodeEditorField) get their edit/preview arrangement
+ * from here, so the promises worth pinning are the ones a field author relies
+ * on without re-reading the file:
+ *
+ *   - below the house md breakpoint it is Write/Preview TABS, and the tab
+ *     labels are the caller's words, not hardcoded ones;
+ *   - `defaultPreview` opens on the preview, which is what a read-only field
+ *     wants — lead with the rendering, not with the source;
+ *   - the tabs stay interactive on a disabled or read-only field, because
+ *     those states gate EDITING and never VIEWING. A preview you cannot reach
+ *     is the regression this component exists to prevent.
+ *
+ * The ≥ md two-pane branch pivots on a real layout measurement
+ * (`onLayout` → ResizeObserver), which happy-dom's stub never delivers, so it
+ * is left to the rendered proof rather than faked here.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent, screen } from "@testing-library/react";
+import { Text } from "tamagui";
+import { afterEach, describe, expect, it } from "vitest";
+import { EditorPreviewPanes, PreviewSurface } from "./EditorPreviewPanes";
+
+afterEach(cleanup);
+
+const panes = (extra: Partial<React.ComponentProps<typeof EditorPreviewPanes>> = {}) => (
+  <EditorPreviewPanes
+    editor={<Text>the source</Text>}
+    preview={<Text>the rendering</Text>}
+    editTabLabel="Write"
+    previewTabLabel="Preview"
+    {...extra}
+  />
+);
+
+describe("EditorPreviewPanes narrow arrangement", () => {
+  it("collapses into a two-tab strip", () => {
+    renderWithProviders(panes());
+    expect(screen.getByRole("tablist")).toBeTruthy();
+    expect(screen.getAllByRole("tab")).toHaveLength(2);
+  });
+
+  it("uses the caller's tab labels", () => {
+    renderWithProviders(panes({ editTabLabel: "Source", previewTabLabel: "Rendered" }));
+    expect(screen.getByText("Source")).toBeTruthy();
+    expect(screen.getByText("Rendered")).toBeTruthy();
+  });
+
+  it("opens on the editor and mounts only that pane", () => {
+    renderWithProviders(panes());
+    expect(screen.getByText("the source")).toBeTruthy();
+    expect(screen.queryByText("the rendering")).toBeNull();
+  });
+
+  it("defaultPreview opens on the preview instead", () => {
+    renderWithProviders(panes({ defaultPreview: true }));
+    expect(screen.getByText("the rendering")).toBeTruthy();
+    expect(screen.queryByText("the source")).toBeNull();
+  });
+
+  it("switches to the preview on a tab press", () => {
+    renderWithProviders(panes());
+    fireEvent.click(screen.getByText("Preview"));
+    expect(screen.getByText("the rendering")).toBeTruthy();
+    expect(screen.queryByText("the source")).toBeNull();
+  });
+
+  it("switches back to the editor", () => {
+    renderWithProviders(panes({ defaultPreview: true }));
+    fireEvent.click(screen.getByText("Write"));
+    expect(screen.getByText("the source")).toBeTruthy();
+    expect(screen.queryByText("the rendering")).toBeNull();
+  });
+
+  it("marks the open tab selected", () => {
+    renderWithProviders(panes());
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs[0].getAttribute("aria-selected")).toBe("true");
+    expect(tabs[1].getAttribute("aria-selected")).toBe("false");
+    fireEvent.click(screen.getByText("Preview"));
+    expect(screen.getAllByRole("tab")[1].getAttribute("aria-selected")).toBe("true");
+  });
+
+  it("keeps the preview reachable even when the editor pane is a read-only surface", () => {
+    // The gate belongs to the editor, never to the tab strip: a read-only
+    // field still has to be able to look at its own rendering.
+    renderWithProviders(panes({ editor: <Text>read-only source</Text>, defaultPreview: true }));
+    fireEvent.click(screen.getByText("Write"));
+    expect(screen.getByText("read-only source")).toBeTruthy();
+    fireEvent.click(screen.getByText("Preview"));
+    expect(screen.getByText("the rendering")).toBeTruthy();
+  });
+});
+
+describe("PreviewSurface", () => {
+  it("renders its children inside a scrollable surface", () => {
+    const result = renderWithProviders(
+      <PreviewSurface>
+        <Text>rendered output</Text>
+      </PreviewSurface>,
+    );
+    expect(result.container.textContent).toContain("rendered output");
+  });
+
+  it("adds a second, horizontal scroller for code panes", () => {
+    const plain = renderWithProviders(
+      <PreviewSurface>
+        <Text>wrapped prose</Text>
+      </PreviewSurface>,
+    );
+    const plainDepth = plain.container.querySelectorAll("*").length;
+    cleanup();
+    const code = renderWithProviders(
+      <PreviewSurface horizontalScroll>
+        <Text>long unwrapped line</Text>
+      </PreviewSurface>,
+    );
+    expect(code.container.querySelectorAll("*").length).toBeGreaterThan(plainDepth);
+    expect(code.container.textContent).toContain("long unwrapped line");
+  });
+});

package/src/formEngine/createPrefill.ts

@@ -0,0 +1,28 @@
+/**
+ * One-shot create-mode prefill hand-off.
+ *
+ * Two producers, one mechanism:
+ * - Duplicate and Amend navigate to `newDocPath(doctype)` and stash the
+ *   copied values here (in-memory only — a refresh honestly falls back to
+ *   a blank form; no URL-size limits for large docs).
+ * - NewDocRouteScreen stashes parsed `?d=` URL defaults (kanban column "+",
+ *   calendar day click, connections "+") before rendering the form — those
+ *   survive refresh because the URL re-stashes them.
+ *
+ * The create-mode form (useFormEngine seeding) consumes and clears the
+ * stash on mount, merging it over meta defaults. Last stash per doctype
+ * wins, so a `?d=` navigation cannot double-apply with a stale
+ * Duplicate/Amend hand-off.
+ */
+
+const prefills = new Map<string, Record<string, unknown>>();
+
+export function setCreatePrefill(doctype: string, values: Record<string, unknown>): void {
+  prefills.set(doctype, values);
+}
+
+export function takeCreatePrefill(doctype: string): Record<string, unknown> | undefined {
+  const values = prefills.get(doctype);
+  if (values) prefills.delete(doctype);
+  return values;
+}

package/src/formEngine/dirtyTracking.spec.ts

@@ -0,0 +1,91 @@
+// R-1 false "Not Saved": engine-level dirty-tracking contract.
+// An untouched existing doc must read pristine, a real edit must read dirty,
+// create mode must read dirty from applied defaults (desk parity).
+import { describe, expect, it } from "vitest";
+import { computeDirtyFields, isSameValue } from "./dirtyTracking";
+
+describe("isSameValue (normalization-insensitive equality)", () => {
+  it("treats null / undefined / empty string / empty array as one empty state", () => {
+    expect(isSameValue(null, "")).toBe(true);
+    expect(isSameValue(undefined, "")).toBe(true);
+    expect(isSameValue(null, undefined)).toBe(true);
+    expect(isSameValue([], null)).toBe(true);
+    expect(isSameValue("  ", "")).toBe(true);
+  });
+
+  it("folds boolean and wire 0/1 representations", () => {
+    expect(isSameValue(false, 0)).toBe(true);
+    expect(isSameValue(true, 1)).toBe(true);
+    expect(isSameValue(0, false)).toBe(true);
+    expect(isSameValue(true, 0)).toBe(false);
+    expect(isSameValue(false, 1)).toBe(false);
+  });
+
+  it("does not conflate empty with falsy non-empty values", () => {
+    expect(isSameValue(0, "")).toBe(false);
+    expect(isSameValue(false, "")).toBe(false);
+    expect(isSameValue(0, null)).toBe(false);
+  });
+
+  it("stays strict for real values — no deep equality", () => {
+    expect(isSameValue("a", "a")).toBe(true);
+    expect(isSameValue("a", "b")).toBe(false);
+    // Distinct array/object identities read as different even when
+    // structurally equal (deliberate: no deep-equality time bombs).
+    expect(isSameValue([{ a: 1 }], [{ a: 1 }])).toBe(false);
+    // Representation changes of real content are edits (the field layer is
+    // responsible for not emitting them during initialization).
+    expect(isSameValue("plain", "<p>plain</p>")).toBe(false);
+  });
+});
+
+describe("computeDirtyFields", () => {
+  const baseline = {
+    doctype: "ToDo",
+    name: "abc",
+    description: "hello",
+    status: "Open",
+    color: null,
+    priority: "Medium",
+    date: "2026-08-12",
+    checked: 0,
+  };
+
+  it("existing doc mount: local === baseline snapshot reads pristine", () => {
+    expect(computeDirtyFields({ ...baseline }, baseline)).toEqual([]);
+  });
+
+  it("field re-representation during init does not dirty (null→'' and 0→false)", () => {
+    const local = { ...baseline, color: "", checked: false };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("a real edit reads dirty", () => {
+    const local = { ...baseline, description: "hello edited" };
+    expect(computeDirtyFields(local, baseline)).toEqual(["description"]);
+  });
+
+  it("revert to the exact baseline value reads clean again", () => {
+    // Documented behavior: value equality, not edit history — typing and
+    // deleting back to the original string is pristine. An equivalent-but-
+    // differently-represented value (e.g. tiptap-normalized HTML) would
+    // still read dirty, which matches desk.
+    const local = { ...baseline, description: "hello" };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("bookkeeping keys never dirty", () => {
+    const local = { ...baseline, name: "renamed", doctype: "Other" };
+    expect(computeDirtyFields(local, baseline)).toEqual([]);
+  });
+
+  it("new doc (no baseline) with applied create-defaults reads dirty — desk parity", () => {
+    const local = { doctype: "ToDo", status: "Open", priority: "Medium", description: "" };
+    expect(computeDirtyFields(local, undefined)).toEqual(["status", "priority"]);
+  });
+
+  it("new doc with only empty values reads pristine", () => {
+    const local = { doctype: "ToDo", description: "", color: null };
+    expect(computeDirtyFields(local, undefined)).toEqual([]);
+  });
+});