@multiplatform.one/frappe-ui 7.77.2 → 7.79.0

package/src/FrappeForm.recordChanged.spec.tsx

@@ -0,0 +1,179 @@
+/**
+ * LC-191 RECORD-CHANGED-UNDER-YOU: an open record that changes on the server
+ * says so and keeps the work. A newer server version pushed mid-edit keeps
+ * the edit, names the field by its label and offers Reload or Overwrite; a
+ * record deleted mid-edit stays mounted, turns read-only and says so, which
+ * is not the not-found state.
+ *
+ * The server is the fixture corpus; a snapshot refresh of the shared
+ * SyncModule plays the change the live socket would deliver.
+ */
+
+import { getFrappeSyncModule, type InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { act, cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { Text } from "tamagui";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { assetLoanLifecycleFixtures } from "../tests/fixtures/assetLoanLifecycle";
+import { FrappeForm } from "./FrappeForm";
+import { FrappeProvider } from "./FrappeProvider";
+import type { FieldOverride } from "./schemaForm";
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+afterEach(cleanup);
+
+const probe: FieldOverride = (props) => {
+  const name = props.fieldMeta?.name ?? "";
+  const value = props.value === undefined || props.value === null ? "" : String(props.value);
+  return (
+    <>
+      <Text
+        testID={`probe-${name}`}
+      >{`ro=${!!props.readOnly || !!props.disabled} val=${value}`}</Text>
+      <button type="button" data-testid={`set-${name}`} onClick={() => props.onChange("mine")}>
+        set
+      </button>
+    </>
+  );
+};
+
+const overrides = { employee_name: probe, serial_no: probe, remarks: probe };
+
+function renderDraft(fixtures: InMemoryFixtureProvider) {
+  return renderWithProviders(
+    <FrappeProvider baseURL="http://test" fixtures={fixtures}>
+      <FrappeForm
+        doctype="Asset Loan"
+        name="LOAN-DRAFT"
+        roles={["Loan Manager"]}
+        overrides={overrides}
+        showSidebar={false}
+        showTimeline={false}
+        onDelete={() => {}}
+      />
+    </FrappeProvider>,
+  );
+}
+
+async function serverWrites(fixtures: InMemoryFixtureProvider, write: () => Promise<unknown>) {
+  await act(async () => {
+    await write();
+    await getFrappeSyncModule({ fixtures })!.refreshSubscriptions({ doctypes: ["Asset Loan"] });
+  });
+}
+
+async function expectProbe(field: string, text: string) {
+  await waitFor(() => expect(screen.getByTestId(`probe-${field}`).textContent).toContain(text));
+}
+
+describe("a newer server version lands mid-edit (LC-191)", () => {
+  it("keeps the edit, names the field by its label and offers Reload and Overwrite", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    renderDraft(fixtures);
+    await expectProbe("employee_name", "val=Ada Lovelace");
+    fireEvent.click(screen.getByTestId("set-employee_name"));
+    await expectProbe("employee_name", "val=mine");
+
+    await serverWrites(fixtures, () =>
+      fixtures.updateDoc("Asset Loan", "LOAN-DRAFT", { employee_name: "Grace Hopper" }),
+    );
+
+    const banner = await screen.findByTestId("frappe-form-conflict-banner");
+    expect(banner.textContent).toContain("Employee Name");
+    expect(banner.textContent).not.toContain("employee_name");
+    expect(screen.getByTestId("probe-employee_name").textContent).toContain("val=mine");
+    expect(banner.querySelector("[role='button'], button")).toBeTruthy();
+    expect(screen.getByText("Reload")).toBeTruthy();
+    expect(screen.getByText("Overwrite")).toBeTruthy();
+  });
+
+  it("a server change to a field the user left alone lands without a banner", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    renderDraft(fixtures);
+    await expectProbe("remarks", "val=");
+    fireEvent.click(screen.getByTestId("set-employee_name"));
+
+    await serverWrites(fixtures, () =>
+      fixtures.updateDoc("Asset Loan", "LOAN-DRAFT", { remarks: "from the server" }),
+    );
+
+    await expectProbe("remarks", "val=from the server");
+    expect(screen.getByTestId("probe-employee_name").textContent).toContain("val=mine");
+    expect(screen.queryByTestId("frappe-form-conflict-banner")).toBeNull();
+  });
+
+  it("Reload drops the edit for the server copy", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    renderDraft(fixtures);
+    await expectProbe("employee_name", "val=Ada Lovelace");
+    fireEvent.click(screen.getByTestId("set-employee_name"));
+    await serverWrites(fixtures, () =>
+      fixtures.updateDoc("Asset Loan", "LOAN-DRAFT", { employee_name: "Grace Hopper" }),
+    );
+    await screen.findByTestId("frappe-form-conflict-banner");
+
+    fireEvent.click(screen.getByText("Reload"));
+
+    await expectProbe("employee_name", "val=Grace Hopper");
+    expect(screen.queryByTestId("frappe-form-conflict-banner")).toBeNull();
+  });
+
+  it("Overwrite writes the edit over the newer server value", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    renderDraft(fixtures);
+    await expectProbe("employee_name", "val=Ada Lovelace");
+    fireEvent.click(screen.getByTestId("set-employee_name"));
+    await serverWrites(fixtures, () =>
+      fixtures.updateDoc("Asset Loan", "LOAN-DRAFT", { employee_name: "Grace Hopper" }),
+    );
+    await screen.findByTestId("frappe-form-conflict-banner");
+
+    fireEvent.click(screen.getByText("Overwrite"));
+
+    await waitFor(async () =>
+      expect((await fixtures.getDoc("Asset Loan", "LOAN-DRAFT"))?.employee_name).toBe("mine"),
+    );
+    await waitFor(() => expect(screen.queryByTestId("frappe-form-conflict-banner")).toBeNull());
+  });
+});
+
+describe("the record is deleted mid-edit (LC-191)", () => {
+  it("stays mounted, turns read-only and says the edits can no longer be saved", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    renderDraft(fixtures);
+    await expectProbe("employee_name", "ro=false val=Ada Lovelace");
+    fireEvent.click(screen.getByTestId("set-employee_name"));
+
+    await serverWrites(fixtures, () => fixtures.deleteDoc("Asset Loan", "LOAN-DRAFT"));
+
+    const banner = await screen.findByTestId("frappe-form-deleted-banner");
+    expect(banner.textContent).toContain("deleted on the server");
+    expect(banner.textContent).toContain("unsaved edits can no longer be saved");
+    await expectProbe("employee_name", "ro=true val=mine");
+    expect(screen.queryByTestId("frappe-form-status-notFound")).toBeNull();
+    expect(screen.queryByText("Asset Loan not found")).toBeNull();
+    expect(screen.queryByTestId("frappe-form-conflict-banner")).toBeNull();
+  });
+
+  it("a clean record says only that it is read-only now", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    renderDraft(fixtures);
+    await expectProbe("employee_name", "ro=false val=Ada Lovelace");
+
+    await serverWrites(fixtures, () => fixtures.deleteDoc("Asset Loan", "LOAN-DRAFT"));
+
+    const banner = await screen.findByTestId("frappe-form-deleted-banner");
+    expect(banner.textContent).toContain("Fields are read-only.");
+    expect(banner.textContent).not.toContain("unsaved edits");
+    await expectProbe("employee_name", "ro=true val=Ada Lovelace");
+  });
+});

package/src/FrappeForm.recordChanged.stories.tsx

@@ -0,0 +1,83 @@
+import { getFrappeSyncModule, type InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { useEffect, useMemo, useRef } from "react";
+import { assetLoanLifecycleFixtures } from "../tests/fixtures/assetLoanLifecycle";
+import { FrappeForm } from "./FrappeForm";
+import { FrappeProvider } from "./FrappeProvider";
+import { useFrappeForm } from "./useFrappeForm";
+
+export default {
+  title: "FrappeUI/FrappeForm Record Changed",
+  component: FrappeForm,
+  tags: ["!test"],
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "LC-191: the open record changes on the server. A newer version that touches a field the reader edited keeps the edit, names the field by its label and offers Reload or Overwrite. A record deleted mid-edit stays on screen, read-only, and says the unsaved edits can no longer be saved. Each story edits Employee Name, then plays the server change on the fixture corpus.",
+      },
+    },
+  },
+};
+
+type Loan = { name: string; doctype: string; employee_name?: string };
+
+function Changed({
+  fixtures,
+  serverChange,
+}: {
+  fixtures: InMemoryFixtureProvider;
+  serverChange: (fixtures: InMemoryFixtureProvider) => Promise<unknown>;
+}) {
+  const form = useFrappeForm<Loan>({
+    doctype: "Asset Loan",
+    name: "LOAN-DRAFT",
+    roles: ["Loan Manager"],
+  });
+  const played = useRef(false);
+  const loaded = form.status === "ready" && form.baseline?.employee_name === "Ada Lovelace";
+  useEffect(() => {
+    if (!loaded || played.current) return;
+    played.current = true;
+    form.setValue("employee_name", "Ada King");
+    void serverChange(fixtures).then(() =>
+      getFrappeSyncModule({ fixtures })?.refreshSubscriptions({ doctypes: ["Asset Loan"] }),
+    );
+  }, [loaded, form, fixtures, serverChange]);
+  return (
+    <FrappeForm<Loan>
+      form={form}
+      doctype="Asset Loan"
+      name="LOAN-DRAFT"
+      showSidebar={false}
+      showTimeline={false}
+    />
+  );
+}
+
+function Story({
+  serverChange,
+}: {
+  serverChange: (fixtures: InMemoryFixtureProvider) => Promise<unknown>;
+}) {
+  const fixtures = useMemo(() => assetLoanLifecycleFixtures(), []);
+  return (
+    <FrappeProvider baseURL="https://form-record-changed.mock.test" fixtures={fixtures}>
+      <Changed fixtures={fixtures} serverChange={serverChange} />
+    </FrappeProvider>
+  );
+}
+
+/** Someone else saved Employee Name while it was being edited. */
+export const ChangedOnServer = () => (
+  <Story
+    serverChange={(fixtures) =>
+      fixtures.updateDoc("Asset Loan", "LOAN-DRAFT", { employee_name: "Grace Hopper" })
+    }
+  />
+);
+
+/** The record was deleted while it was open with an unsaved edit. */
+export const DeletedOnServer = () => (
+  <Story serverChange={(fixtures) => fixtures.deleteDoc("Asset Loan", "LOAN-DRAFT")} />
+);

package/src/FrappeForm.successIsCallback.spec.tsx

@@ -0,0 +1,154 @@
+/**
+ * LC-194 SUCCESS-IS-A-CALLBACK: a data component reports, the page reacts.
+ * FrappeForm completes a create, a save and a delete and hands each result to
+ * its callback, with no toast or notify of its own and no navigation, even
+ * when the host has a router it could push.
+ */
+
+import type { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { Text } from "tamagui";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { assetLoanLifecycleFixtures } from "../tests/fixtures/assetLoanLifecycle";
+import { FrappeForm } from "./FrappeForm";
+import type { FrappeNavigation } from "./frappeNavigation";
+import { FrappeProvider } from "./FrappeProvider";
+import type { FieldOverride } from "./schemaForm";
+
+const feedback = vi.hoisted(() => ({ notify: vi.fn(), showToast: vi.fn() }));
+
+vi.mock("@multiplatform.one/components", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@multiplatform.one/components")>();
+  return {
+    ...actual,
+    notify: (...args: Parameters<typeof actual.notify>) => {
+      feedback.notify(...args);
+      return actual.notify(...args);
+    },
+    showToast: (...args: Parameters<typeof actual.showToast>) => {
+      feedback.showToast(...args);
+      return actual.showToast(...args);
+    },
+  };
+});
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+beforeEach(() => {
+  vi.stubGlobal(
+    "confirm",
+    vi.fn(() => true),
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  feedback.notify.mockClear();
+  feedback.showToast.mockClear();
+});
+
+const probe: FieldOverride = (props) => {
+  const name = props.fieldMeta?.name ?? "";
+  const value = props.value === undefined || props.value === null ? "" : String(props.value);
+  return (
+    <>
+      <Text testID={`probe-${name}`}>{`val=${value}`}</Text>
+      <button type="button" data-testid={`set-${name}`} onClick={() => props.onChange("Edited")}>
+        set
+      </button>
+    </>
+  );
+};
+
+const overrides = { employee_name: probe, serial_no: probe, remarks: probe };
+
+function renderForm(fixtures: InMemoryFixtureProvider, name?: string) {
+  const pushed: string[] = [];
+  const navigation: FrappeNavigation = {
+    usePathname: () => "/loans",
+    useNavigate: () => (href) => pushed.push(href),
+  };
+  const onSave = vi.fn();
+  const onDelete = vi.fn();
+  renderWithProviders(
+    <FrappeProvider baseURL="http://test" fixtures={fixtures} navigation={navigation}>
+      <FrappeForm
+        doctype="Asset Loan"
+        name={name}
+        roles={["Loan Manager"]}
+        overrides={overrides}
+        showSidebar={false}
+        showTimeline={false}
+        onSave={onSave}
+        onDelete={onDelete}
+      />
+    </FrappeProvider>,
+  );
+  return { pushed, onSave, onDelete };
+}
+
+function press(name: string) {
+  const byLabel = document.querySelector(`[aria-label='${name}']`);
+  fireEvent.click((byLabel as HTMLElement | null) ?? screen.getByText(name));
+}
+
+function expectNoOwnFeedback(pushed: string[]) {
+  expect(feedback.notify).not.toHaveBeenCalled();
+  expect(feedback.showToast).not.toHaveBeenCalled();
+  expect(pushed).toEqual([]);
+}
+
+describe("FrappeForm reports a mutation through its callback only (LC-194)", () => {
+  it("a create hands the new record to onSave", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    const { pushed, onSave } = renderForm(fixtures);
+    await screen.findByTestId("probe-employee_name");
+    fireEvent.click(screen.getByTestId("set-employee_name"));
+
+    press("Save");
+
+    await waitFor(() => expect(onSave).toHaveBeenCalledTimes(1));
+    expect(onSave.mock.calls[0]?.[0]).toMatchObject({ employee_name: "Edited" });
+    expect(typeof onSave.mock.calls[0]?.[0].name).toBe("string");
+    expectNoOwnFeedback(pushed);
+  });
+
+  it("a save hands the saved record to onSave", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    const { pushed, onSave } = renderForm(fixtures, "LOAN-DRAFT");
+    await waitFor(() => expect(screen.getByTestId("probe-remarks").textContent).toBe("val="));
+    fireEvent.click(screen.getByTestId("set-remarks"));
+
+    press("Save");
+
+    await waitFor(() => expect(onSave).toHaveBeenCalledTimes(1));
+    expect(onSave.mock.calls[0]?.[0]).toMatchObject({ name: "LOAN-DRAFT", remarks: "Edited" });
+    expect((await fixtures.getDoc("Asset Loan", "LOAN-DRAFT"))?.remarks).toBe("Edited");
+    expectNoOwnFeedback(pushed);
+  });
+
+  it("a delete hands the removed record to onDelete", async () => {
+    const fixtures = assetLoanLifecycleFixtures();
+    const { pushed, onDelete } = renderForm(fixtures, "LOAN-DRAFT");
+    await waitFor(() =>
+      expect(screen.getByTestId("probe-employee_name").textContent).toBe("val=Ada Lovelace"),
+    );
+
+    press("Delete");
+
+    await waitFor(() => expect(onDelete).toHaveBeenCalledTimes(1));
+    expect(onDelete.mock.calls[0]?.[0]).toMatchObject({ name: "LOAN-DRAFT" });
+    expect(await fixtures.getDoc("Asset Loan", "LOAN-DRAFT")).toBeFalsy();
+    expectNoOwnFeedback(pushed);
+  });
+});

package/src/FrappeForm.tsx

@@ -5,6 +5,7 @@ import {
   type FormSection,
 } from "@multiplatform.one/frappe";
 import {
+  Alert,
   AsyncBoundary,
   AsyncSkeleton,
   DetailPageLayout,
@@ -516,6 +517,7 @@ function FrappeFormView<TDoc extends { name: string; doctype: string }>({
     canWrite: canWriteRecord,
     wasDeleted,
     conflictFields,
+    conflict,
     docError,
     tabs: formTabs,
     promptNamed,
@@ -968,44 +970,43 @@ function FrappeFormView<TDoc extends { name: string; doctype: string }>({
           ))
         : null}
 
+      {/* LC-191: the record changed under the open view. Deleted keeps the
+          view mounted and read-only; a conflict keeps the edits, names the
+          fields and lets the reader pick reload or overwrite. */}
       {showBanners && wasDeleted && (
-        <XStack
-          role="alert"
-          alignItems="center"
-          {...knobProps.containerRadius}
-          {...knobProps.panelPadding}
-          backgroundColor="$red3"
-          testID="frappe-form-deleted-banner"
-        >
-          <TamaguiText color={formCommonColors.error} {...knobProps.body}>
-            {hasUnsavedChanges
-              ? t(
-                  "This {{doctype}} was deleted on the server. Fields are read-only and your unsaved edits can no longer be saved.",
-                  { doctype },
-                )
-              : t("This {{doctype}} was deleted on the server. Fields are read-only.", {
-                  doctype,
-                })}
-          </TamaguiText>
-        </XStack>
+        <Alert intent="error" testID="frappe-form-deleted-banner">
+          {hasUnsavedChanges
+            ? t(
+                "This {{doctype}} was deleted on the server. Fields are read-only and your unsaved edits can no longer be saved.",
+                { doctype },
+              )
+            : t("This {{doctype}} was deleted on the server. Fields are read-only.", {
+                doctype,
+              })}
+        </Alert>
       )}
 
-      {showBanners && !wasDeleted && conflictFields.length > 0 && (
-        <XStack
-          role="status"
-          alignItems="center"
-          {...knobProps.containerRadius}
-          {...knobProps.panelPadding}
-          backgroundColor="$orange3"
+      {showBanners && !wasDeleted && conflict && (
+        <Alert
+          intent="warning"
           testID="frappe-form-conflict-banner"
+          title={t("Changed on the server")}
+          actionLabel={t("Reload")}
+          onAction={() => form.reset()}
+          {...(canWriteRecord && !effectiveDisabled
+            ? { secondaryActionLabel: t("Overwrite"), onSecondaryAction: handleSave }
+            : {})}
         >
-          <TamaguiText color="$orange11" {...knobProps.body}>
-            {t(
-              "Changed elsewhere while you were editing: {{fields}}. Your edits are kept — saving will overwrite the newer server values.",
-              { fields: conflictLabels },
-            )}
-          </TamaguiText>
-        </XStack>
+          {conflictLabels
+            ? t(
+                "{{fields}} changed while you were editing. Your edits are kept until you reload or overwrite.",
+                { fields: conflictLabels },
+              )
+            : t(
+                "This {{doctype}} changed after you opened it. Your edits are kept until you reload or overwrite.",
+                { doctype },
+              )}
+        </Alert>
       )}
 
       {/* flexBasis auto — see the root stack note (zero-height collapse in