@multiplatform.one/frappe-ui 7.6.2 → 7.7.0

package/src/fields/Phone/Phone.spec.tsx

@@ -0,0 +1,151 @@
+/**
+ * Phone contract specs. The adapter is thin by design — compose the forms
+ * PhoneInput, emit canonical onChange — so what has to be pinned is that every
+ * prop the Frappe layer sets actually ARRIVES: the country the number is
+ * parsed against (`defaultCountry`, fed from df.options by the registry), the
+ * controlled value, and the read-only / disabled gates.
+ *
+ * A dropped `defaultCountry` is the failure that matters here: the same digits
+ * serialise to a different E.164 number under a different region, so a silent
+ * default of US would corrupt every non-US phone field on save.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { act, 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 { Phone } from ".";
+
+afterEach(cleanup);
+
+const phoneInput = (container: HTMLElement) =>
+  container.querySelector('[data-testid="phone-input"]') as HTMLInputElement | null;
+
+describe("Phone composes the forms PhoneInput", () => {
+  it("renders the composite phone control, not a bare Input", () => {
+    const result = renderWithProviders(<Phone label="Mobile" value="" onChange={() => {}} />);
+    expect(phoneInput(result.container)).toBeTruthy();
+    expect(result.container.querySelector('[data-testid="phone-box"]')).toBeTruthy();
+  });
+
+  it("shows the national form of a controlled E.164 value", () => {
+    const result = renderWithProviders(
+      <Phone label="Mobile" value="+14155550123" onChange={() => {}} />,
+    );
+    const input = phoneInput(result.container);
+    expect(input?.value).toContain("415");
+    expect(input?.value).toContain("555");
+  });
+
+  it("emits a serialised number through canonical onChange", async () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(<Phone label="Mobile" value="" onChange={onChange} />);
+    const input = phoneInput(result.container) as HTMLInputElement;
+    await act(async () => {
+      fireEvent.change(input, { target: { value: "4155550123" } });
+    });
+    expect(onChange).toHaveBeenCalled();
+    const emitted = onChange.mock.calls.at(-1)?.[0] as string;
+    expect(emitted.startsWith("+")).toBe(true);
+    expect(emitted).toContain("4155550123");
+  });
+});
+
+describe("Phone defaultCountry", () => {
+  it("defaults to the +1 region when the field declares no country", () => {
+    const result = renderWithProviders(<Phone label="Mobile" value="" onChange={() => {}} />);
+    expect(result.container.textContent).toContain("+1");
+  });
+
+  it("honours defaultCountry, so the dial code follows the DocField", () => {
+    const result = renderWithProviders(
+      <Phone label="Mobile" value="" defaultCountry="GB" onChange={() => {}} />,
+    );
+    expect(result.container.textContent).toContain("+44");
+  });
+
+  it("parses the same digits under the declared region", async () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <Phone label="Mobile" value="" defaultCountry="IN" onChange={onChange} />,
+    );
+    await act(async () => {
+      fireEvent.change(phoneInput(result.container) as HTMLInputElement, {
+        target: { value: "8074052136" },
+      });
+    });
+    const emitted = onChange.mock.calls.at(-1)?.[0] as string;
+    expect(emitted.startsWith("+91")).toBe(true);
+  });
+});
+
+describe("Phone gates", () => {
+  it("readOnly marks the control read-only", () => {
+    const result = renderWithProviders(
+      <Phone label="Mobile" value="+14155550123" readOnly onChange={() => {}} />,
+    );
+    expect(phoneInput(result.container)?.hasAttribute("readonly")).toBe(true);
+  });
+
+  it("skeleton branch renders no phone control", () => {
+    const result = renderWithProviders(
+      <Phone label="Mobile" value="+14155550123" skeleton onChange={() => {}} />,
+    );
+    expect(phoneInput(result.container)).toBeNull();
+  });
+
+  it("shows the label, helperText and error", () => {
+    const result = renderWithProviders(
+      <Phone
+        label="Mobile"
+        value=""
+        helperText="include the country code"
+        error="not a number"
+        onChange={() => {}}
+      />,
+    );
+    expect(result.container.textContent).toContain("Mobile");
+    expect(result.container.textContent).toContain("not a number");
+  });
+});
+
+describe("registry resolution (Phone fieldtype)", () => {
+  function propsFor(overrides: Partial<FieldRenderProps> = {}): FieldRenderProps {
+    return { value: "", onChange: () => {}, ...overrides };
+  }
+
+  it("resolves 'Phone' to the Phone adapter", () => {
+    const Component = getFieldComponent("Phone")!;
+    expect(Component).toBeTruthy();
+    const element = (Component as Function)(
+      propsFor({ value: "+14155550123", label: "Mobile" }),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.type).toBe(Phone);
+    expect(element.props.value).toBe("+14155550123");
+    expect(element.props.label).toBe("Mobile");
+  });
+
+  it("takes defaultCountry from df.options — this is the DocField's own region", () => {
+    const Component = getFieldComponent("Phone")!;
+    const element = (Component as Function)(
+      propsFor({ fieldMeta: { options: "IN" } } as Partial<FieldRenderProps>),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.props.defaultCountry).toBe("IN");
+  });
+
+  it("leaves defaultCountry unset when df.options is empty, so PhoneInput owns the default", () => {
+    const Component = getFieldComponent("Phone")!;
+    const element = (Component as Function)(
+      propsFor({ fieldMeta: { options: "" } } as Partial<FieldRenderProps>),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.props.defaultCountry).toBeUndefined();
+  });
+
+  it("substitutes an empty string for a null value", () => {
+    const Component = getFieldComponent("Phone")!;
+    const element = (Component as Function)(
+      propsFor({ value: null as unknown as string }),
+    ) as React.ReactElement<Record<string, any>>;
+    expect(element.props.value).toBe("");
+  });
+});

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");
+  });
+});