@multiplatform.one/backoffice 7.34.4 → 7.35.0

package/src/formBuilder/FormBuilderScreen.screen.spec.tsx

@@ -0,0 +1,392 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { InMemoryFixtureProvider, type FrappeDocData } from "@multiplatform.one/frappe";
+import { FrappeProvider } from "@multiplatform.one/frappe-ui";
+import { fireEvent, screen, waitFor, within } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import pokemon from "../../../../apps/frappe/apps/core/core/app/doctype/pokemon/pokemon.json";
+import { BackofficeProvider } from "../config/BackofficeProvider";
+import { createMemoryNavigator } from "../navigation/navigator";
+import { Desk } from "../desk/Desk";
+import { FormBuilderScreen } from "./FormBuilderScreen";
+import type { BuilderDocField } from "./model";
+
+const viewport = vi.hoisted(() => ({ size: "xl" }));
+vi.mock("@multiplatform.one/theme", async (original) => ({
+  ...(await original<typeof import("@multiplatform.one/theme")>()),
+  useLayoutSizeClass: () => viewport.size,
+}));
+
+let host = 0;
+afterEach(() => {
+  viewport.size = "xl";
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+function renderBuilder(
+  options: {
+    initialSelection?: string;
+    reject?: boolean;
+    fields?: BuilderDocField[];
+    picker?: boolean;
+    desk?: boolean;
+    catalogError?: boolean;
+    metaError?: boolean;
+  } = {},
+) {
+  let fields: BuilderDocField[] = options.fields ?? pokemon.fields;
+  const saves: { fields: BuilderDocField[] }[] = [];
+  const reads: string[] = [];
+  const fetch = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(String(input instanceof Request ? input.url : input));
+    const body = new URLSearchParams(String(init?.body ?? ""));
+    let payload: unknown = { message: [], data: [] };
+    let status = 200;
+    if (url.pathname.endsWith("getdoctype")) {
+      reads.push("meta");
+      payload = { docs: [{ ...pokemon, fields }] };
+      if (options.metaError) {
+        status = 403;
+        payload = { exception: "Permission denied" };
+      }
+    } else if (body.get("method") === "fetch_to_customize") {
+      reads.push("source");
+      payload = {
+        docs: [
+          {
+            doctype: "Customize Form",
+            name: "Customize Form",
+            doc_type: "Pokemon",
+            modified: "fresh",
+            fields,
+          },
+        ],
+      };
+    } else if (body.get("method") === "save_customization") {
+      const doc = JSON.parse(body.get("docs")!);
+      saves.push(doc);
+      if (options.reject) {
+        status = 417;
+        payload = {
+          exc_type: "ValidationError",
+          exception: "frappe.exceptions.ValidationError: Nickname is not allowed",
+        };
+      } else {
+        fields = doc.fields;
+        payload = {};
+      }
+    } else if (url.pathname.endsWith("frappe.client.get_list")) {
+      payload = { message: [{ name: "Pokemon" }] };
+      if (options.catalogError) {
+        status = 403;
+        payload = {};
+      }
+    }
+    return new Response(JSON.stringify(payload), {
+      status,
+      headers: { "content-type": "application/json" },
+    });
+  });
+  vi.stubGlobal("fetch", fetch);
+  const navigator = createMemoryNavigator(
+    options.picker ? "/backoffice/customize-form" : "/backoffice/customize-form?doc_type=Pokemon",
+  );
+  const frappe = { baseURL: `https://builder-${++host}.screen.spec.test` };
+  renderWithProviders(
+    options.desk ? (
+      <Desk frappe={frappe} navigation={navigator} chrome="content" />
+    ) : (
+      <BackofficeProvider frappe={frappe} navigation={navigator}>
+        <FormBuilderScreen
+          doctype={options.picker ? undefined : "Pokemon"}
+          initialSelection={options.initialSelection}
+        />
+      </BackofficeProvider>
+    ),
+  );
+  return { saves, reads, navigator, fetch };
+}
+
+function columnNames(column: Element) {
+  return Array.from(column.querySelectorAll("[data-fb-fieldname]")).map((el) =>
+    el.getAttribute("data-fb-fieldname"),
+  );
+}
+function input(label: string) {
+  const element = screen.getByLabelText(label, { exact: true });
+  return element.matches("input, textarea") ? element : element.querySelector("input, textarea")!;
+}
+async function addNickname() {
+  fireEvent.click(await screen.findByRole("button", { name: "Add Data field" }));
+  fireEvent.change(input("Label"), { target: { value: "Nickname" } });
+  fireEvent.click(screen.getByRole("checkbox", { name: "Mandatory" }));
+}
+function save() {
+  fireEvent.click(document.querySelector("[data-mp-savebar-save]")!);
+}
+
+describe("FormBuilderScreen", () => {
+  it("opens the requested field properties without changing the layout", async () => {
+    renderBuilder({ initialSelection: "sprite_back" });
+    expect(await screen.findByDisplayValue("Sprite (Back)")).toBeTruthy();
+    expect(
+      document.querySelector('[data-fb-fieldname="sprite_back"]')?.getAttribute("data-fb-selected"),
+    ).toBe("true");
+    expect(document.querySelector("[data-mp-savebar-save]")).toBeNull();
+  });
+
+  it("opens the real builder through the desk route", async () => {
+    renderBuilder({ desk: true });
+    expect(await screen.findByTestId("form-builder-screen")).toBeTruthy();
+    expect(screen.getByRole("tab", { name: "Details" })).toBeTruthy();
+  });
+
+  it("opens the picker through Desk and navigates from the catalog", async () => {
+    const { navigator } = renderBuilder({ desk: true, picker: true });
+    expect(await screen.findByTestId("form-builder-picker")).toBeTruthy();
+    fireEvent.keyDown(await screen.findByRole("combobox", { name: "DocType" }), { key: "Enter" });
+    const option = await screen.findByRole("option", { name: "Pokemon" });
+    fireEvent.pointerDown(option, { button: 0, pointerId: 1 });
+    fireEvent.mouseDown(option);
+    fireEvent.mouseUp(option);
+    fireEvent.click(option);
+    await waitFor(() => expect(navigator.getLocation().params.doc_type).toBe("Pokemon"));
+    expect(await screen.findByTestId("form-builder-screen")).toBeTruthy();
+  });
+
+  it("can use a typed name when the catalog fails", async () => {
+    const { navigator } = renderBuilder({ picker: true, catalogError: true });
+    expect(
+      await screen.findByText("The DocType catalog could not be loaded. Enter a name below."),
+    ).toBeTruthy();
+    fireEvent.change(input("DocType name"), { target: { value: "Sales Order" } });
+    fireEvent.click(screen.getByRole("button", { name: "Open form builder" }));
+    expect(navigator.getLocation()).toEqual({
+      path: "/backoffice/customize-form",
+      params: { doc_type: "Sales Order" },
+    });
+  });
+
+  it("saves and reloads with a fixtures-only FrappeProvider", async () => {
+    const fetch = vi.fn();
+    vi.stubGlobal("fetch", fetch);
+    const fixtures = new InMemoryFixtureProvider({
+      DocType: [pokemon as unknown as FrappeDocData],
+    });
+    renderWithProviders(
+      <BackofficeProvider
+        frappe={{ baseURL: "" }}
+        navigation={createMemoryNavigator("/backoffice/customize-form")}
+      >
+        <FrappeProvider fixtures={fixtures}>
+          <FormBuilderScreen doctype="Pokemon" />
+        </FrappeProvider>
+      </BackofficeProvider>,
+    );
+    await addNickname();
+    save();
+    await waitFor(async () => {
+      const saved = await fixtures.getDoc("DocType", "Pokemon");
+      expect((saved!.fields as BuilderDocField[])[6]).toMatchObject({
+        fieldname: "nickname",
+        reqd: 1,
+      });
+    });
+    await waitFor(() => expect(screen.queryByDisplayValue("Nickname")).toBeNull());
+    expect(columnNames(document.querySelector("[data-fb-column]")!)).toContain("nickname");
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("draws empty and failed metadata through the catalog states", async () => {
+    renderBuilder({ fields: [] });
+    expect(await screen.findByText("This form has no fields")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Add field" }));
+    expect(screen.getByDisplayValue("Data")).toBeTruthy();
+  });
+
+  it("draws a metadata error instead of an empty form", async () => {
+    renderBuilder({ metaError: true });
+    expect(await screen.findByText("Permission denied")).toBeTruthy();
+    expect(screen.queryByTestId("form-builder-screen")).toBeNull();
+  });
+
+  it("renders every Pokemon field in its Frappe section and column", async () => {
+    renderBuilder();
+    await screen.findByRole("tab", { name: "Details" });
+    const sections = document.querySelectorAll("[data-fb-section]");
+    expect(sections).toHaveLength(2);
+    expect(within(sections[1].firstElementChild as HTMLElement).getByText("Stats")).toBeTruthy();
+    expect(within(sections[0].firstElementChild as HTMLElement).getByText("8 fields")).toBeTruthy();
+    expect(within(sections[1].firstElementChild as HTMLElement).getByText("1 field")).toBeTruthy();
+    const columns = sections[0].querySelectorAll("[data-fb-column]");
+    expect(Array.from(columns, columnNames)).toEqual([
+      pokemon.field_order.slice(0, 6),
+      ["sprite_front", "sprite_back"],
+    ]);
+    expect(columnNames(sections[1])).toEqual(["stats"]);
+    expect(screen.getByRole("button", { name: "Add field to Stats, column 1" })).toBeTruthy();
+  });
+
+  it("moves through the keyboard machine, saves the order and reloads it", async () => {
+    const { saves, reads } = renderBuilder();
+    const grip = await screen.findByRole("button", { name: "Reorder Sprite (Back)" });
+    fireEvent.keyDown(grip, { key: " " });
+    fireEvent.keyDown(grip, { key: "ArrowLeft" });
+    expect(document.querySelector("[aria-live=polite]")?.textContent).toContain("position 2");
+    expect(columnNames(document.querySelector("[data-fb-column]")!)).not.toContain("sprite_back");
+    fireEvent.keyDown(grip, { key: " " });
+    save();
+    await waitFor(() => expect(reads).toEqual(["meta", "source", "meta"]));
+    expect(saves[0].fields.slice(0, 3).map((f) => [f.fieldname, f.idx])).toEqual([
+      ["pokemon_name", 1],
+      ["sprite_back", 2],
+      ["poke_id", 3],
+    ]);
+    await waitFor(() =>
+      expect(columnNames(document.querySelector("[data-fb-column]")!)[1]).toBe("sprite_back"),
+    );
+    expect(document.querySelector("[data-mp-savebar-save]")).toBeNull();
+  });
+
+  it("moves through the field menu and persists the first column destination", async () => {
+    const { saves } = renderBuilder();
+    fireEvent.click(await screen.findByRole("button", { name: "Menu for Sprite (Back)" }));
+    fireEvent.click(await screen.findByRole("menuitem", { name: "Move to section: Stats" }));
+    fireEvent.click(screen.getByRole("button", { name: "Menu for Sprite (Back)" }));
+    fireEvent.click(
+      await screen.findByRole("menuitem", { name: "Move to section: Untitled section" }),
+    );
+    save();
+    await waitFor(() => expect(saves).toHaveLength(1));
+    expect(saves[0].fields[6]).toMatchObject({ fieldname: "sprite_back", idx: 7 });
+    await waitFor(() =>
+      expect(columnNames(document.querySelector("[data-fb-column]")!).at(-1)).toBe("sprite_back"),
+    );
+  });
+
+  it("adds a required custom Data field at the end of the first column", async () => {
+    const { saves } = renderBuilder();
+    await addNickname();
+    save();
+    await waitFor(() => expect(saves).toHaveLength(1));
+    expect(saves[0].fields[6]).toMatchObject({
+      fieldname: "nickname",
+      fieldtype: "Data",
+      label: "Nickname",
+      reqd: 1,
+      is_custom_field: 1,
+      idx: 7,
+    });
+    await waitFor(() =>
+      expect(columnNames(document.querySelector("[data-fb-column]")!)).toContain("nickname"),
+    );
+  });
+
+  it("adds and selects a Data field at the end of the second column", async () => {
+    const { saves } = renderBuilder();
+    fireEvent.click(
+      await screen.findByRole("button", {
+        name: "Add field to Untitled section, column 2",
+      }),
+    );
+    const columns = document.querySelectorAll("[data-fb-column]");
+    expect(columnNames(columns[0])).toEqual(pokemon.field_order.slice(0, 6));
+    expect(columnNames(columns[1])).toEqual(["sprite_front", "sprite_back", "data"]);
+    expect(
+      columns[1].querySelector('[data-fb-fieldname="data"]')?.getAttribute("data-fb-selected"),
+    ).toBe("true");
+    expect(input("Label")).toHaveValue("Data");
+    expect(input("Fieldname")).toHaveValue("data");
+    save();
+    await waitFor(() => expect(saves).toHaveLength(1));
+    expect(saves[0].fields[9]).toMatchObject({ fieldname: "data", fieldtype: "Data", idx: 10 });
+  });
+
+  it("filters the palette through its group chips", async () => {
+    renderBuilder();
+    const group = await screen.findByRole("group", { name: "Field group" });
+    const chip = (name: string) => within(group).getByRole("button", { name });
+    expect(chip("All").getAttribute("aria-pressed")).toBe("true");
+    expect(document.querySelector('[data-fb-palette="Data"]')).not.toBeNull();
+    fireEvent.click(chip("Layout"));
+    await waitFor(() => expect(chip("Layout").getAttribute("aria-pressed")).toBe("true"));
+    expect(chip("All").getAttribute("aria-pressed")).toBe("false");
+    expect(document.querySelector('[data-fb-palette="Section Break"]')).not.toBeNull();
+    expect(document.querySelector('[data-fb-palette="Data"]')).toBeNull();
+  });
+
+  it("opens section and column properties from the section menu", async () => {
+    renderBuilder();
+    fireEvent.click(await screen.findByRole("button", { name: "Menu for section Stats" }));
+    fireEvent.click(await screen.findByRole("menuitem", { name: "Section properties" }));
+    expect(input("Label")).toHaveValue("Stats");
+    fireEvent.click(screen.getByRole("button", { name: "Menu for section Untitled section" }));
+    fireEvent.click(await screen.findByRole("menuitem", { name: "Column 2 properties" }));
+    expect(screen.getByText("Column properties")).toBeTruthy();
+    fireEvent.change(input("Label"), { target: { value: "Sprites" } });
+    expect(input("Label")).toHaveValue("Sprites");
+  });
+
+  it("keeps edits and shows field errors after a 417 rejection", async () => {
+    renderBuilder({ reject: true });
+    await addNickname();
+    save();
+    expect((await screen.findByTestId("form-builder-error")).textContent).toContain(
+      "Nickname is not allowed",
+    );
+    expect(screen.getByDisplayValue("Nickname")).toBeTruthy();
+    expect(input("Label").getAttribute("aria-invalid")).toBe("true");
+    expect(document.querySelector("[data-mp-savebar-save]")).toBeTruthy();
+    fireEvent.click(document.querySelector("[data-mp-savebar-discard]")!);
+    fireEvent.click(await screen.findByRole("button", { name: "Discard changes" }));
+    await waitFor(() => expect(screen.queryByTestId("form-builder-error")).toBeNull());
+    expect(columnNames(document.querySelector("[data-fb-column]")!)).not.toContain("nickname");
+  });
+
+  it("does not submit when a field grip is clicked", async () => {
+    const { saves, reads } = renderBuilder();
+    await addNickname();
+    const grip = screen.getByRole("button", { name: "Reorder Nickname" });
+    const event = new MouseEvent("click", { bubbles: true, cancelable: true });
+    fireEvent(grip, event);
+    expect(event.defaultPrevented).toBe(true);
+    expect(saves).toHaveLength(0);
+    expect(reads).toEqual(["meta"]);
+  });
+
+  it("blocks duplicate fieldnames before loading the save source", async () => {
+    const { saves, reads } = renderBuilder();
+    await addNickname();
+    fireEvent.change(input("Fieldname"), { target: { value: "pokemon_name" } });
+    save();
+    expect(await screen.findByText("Fieldnames must be unique.")).toBeTruthy();
+    expect(saves).toHaveLength(0);
+    expect(reads).toEqual(["meta"]);
+  });
+
+  it("opens both compact tools as sheets and stacks the canvas columns", async () => {
+    viewport.size = "compact";
+    renderBuilder();
+    fireEvent.click(await screen.findByRole("button", { name: "Field types" }));
+    expect(await screen.findByRole("button", { name: "Add Data field" })).toBeTruthy();
+    fireEvent.keyDown(document, { key: "Escape" });
+    fireEvent.click(screen.getByRole("button", { name: "Menu for Sprite (Back)" }));
+    fireEvent.click(await screen.findByRole("menuitem", { name: "Edit properties" }));
+    expect(await screen.findByDisplayValue("Sprite (Back)")).toBeTruthy();
+    expect(document.querySelector("[data-fb-columns]")?.getAttribute("data-fb-stacked")).toBe(
+      "true",
+    );
+  });
+
+  it("opens the tools as sheets on a tablet and keeps the columns side by side", async () => {
+    viewport.size = "expanded";
+    renderBuilder();
+    const tools = await screen.findByRole("button", { name: "Field types" });
+    expect(screen.queryByRole("button", { name: "Add Data field" })).toBeNull();
+    fireEvent.click(tools);
+    expect(await screen.findByRole("button", { name: "Add Data field" })).toBeTruthy();
+    expect(document.querySelector("[data-fb-columns]")?.getAttribute("data-fb-stacked")).toBe(
+      "false",
+    );
+  });
+});

package/src/formBuilder/FormBuilderScreen.stories.tsx

@@ -0,0 +1,122 @@
+// Proves the real Pokemon layout, empty and multi-tab forms, selected properties and compact sheets.
+import { ToastViewport, YStack } from "@multiplatform.one/components";
+import { InMemoryFixtureProvider, type FrappeDocData } from "@multiplatform.one/frappe";
+import { Preset, sizeRecipeEscape } from "@multiplatform.one/theme";
+import { useState, useSyncExternalStore } from "react";
+import pokemon from "../../../../apps/frappe/apps/core/core/app/doctype/pokemon/pokemon.json";
+import { BackofficeProvider } from "../config/BackofficeProvider";
+import { createMemoryNavigator } from "../navigation/navigator";
+import { FormBuilderScreen, type FormBuilderScreenProps } from "./FormBuilderScreen";
+import type { BuilderDocField } from "./model";
+
+const meta = {
+  title: "Screens/Backoffice/FormBuilder",
+  component: FormBuilderScreen,
+  parameters: {
+    status: { type: "stable" },
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Visual DocType layout editing with fixture-backed saves. Standard DocTypes use Customize Form; custom DocTypes save their document. On compact screens the palette and properties open as sheets beside a single-column canvas.",
+      },
+    },
+  },
+};
+export default meta;
+
+const frameHeight = sizeRecipeEscape(
+  780,
+  "story canvas: a fixed-height frame for a full-height form builder",
+);
+const emptyMeta = { doctype: "DocType", name: "Empty Form", custom: 1, fields: [] };
+const fieldKinds = [
+  { fieldtype: "Data", label: "Title" },
+  { fieldtype: "Select", label: "Status", options: "Draft\nReady\nArchived" },
+  { fieldtype: "Link", label: "Pokemon", options: "Pokemon" },
+  { fieldtype: "Table", label: "Stats", options: "Pokemon Stat" },
+  { fieldtype: "Check", label: "Enabled" },
+  { fieldtype: "Text Editor", label: "Notes" },
+  { fieldtype: "Attach Image", label: "Portrait" },
+  { fieldtype: "Date", label: "Review date" },
+];
+const manyFields: BuilderDocField[] = Array.from({ length: 3 }, (_, tab) => [
+  {
+    fieldname: `tab_${tab}`,
+    fieldtype: "Tab Break",
+    label: ["Overview", "Training", "Review"][tab],
+  },
+  ...Array.from({ length: 2 }, (_, section) => [
+    {
+      fieldname: `section_${tab}_${section}`,
+      fieldtype: "Section Break",
+      label: `${["Overview", "Training", "Review"][tab]} ${section + 1}`,
+    },
+    ...Array.from({ length: section + 2 }, (_, column) => [
+      ...(column
+        ? [{ fieldname: `column_${tab}_${section}_${column}`, fieldtype: "Column Break" }]
+        : []),
+      ...Array.from({ length: 2 }, (_, field) => ({
+        ...fieldKinds[(tab * 10 + section * 4 + column * 2 + field) % fieldKinds.length],
+        fieldname: `field_${tab}_${section}_${column}_${field}`,
+      })),
+    ]).flat(),
+  ]).flat(),
+])
+  .flat()
+  .map((field, index) => ({ ...field, idx: index + 1 }));
+const manyMeta = { doctype: "DocType", name: "Training Plan", custom: 1, fields: manyFields };
+
+function BuilderStory({ doctype, initialSelection }: FormBuilderScreenProps) {
+  const [fixtures] = useState(
+    () =>
+      new InMemoryFixtureProvider({
+        DocType: [pokemon, emptyMeta, manyMeta] as unknown as FrappeDocData[],
+      }),
+  );
+  const [navigation] = useState(() =>
+    createMemoryNavigator(
+      `/backoffice/customize-form${doctype ? `?doc_type=${encodeURIComponent(doctype)}` : ""}`,
+    ),
+  );
+  const location = useSyncExternalStore(
+    navigation.subscribe,
+    navigation.getLocation,
+    navigation.getLocation,
+  );
+  return (
+    <BackofficeProvider
+      frappe={{ baseURL: "https://form-builder.mock.test", fixtures }}
+      navigation={navigation}
+    >
+      <YStack
+        height={frameHeight}
+        maxHeight="100dvh"
+        minHeight={0}
+        minWidth={0}
+        backgroundColor="$background"
+      >
+        <FormBuilderScreen
+          doctype={
+            typeof location.params.doc_type === "string" ? location.params.doc_type : undefined
+          }
+          initialSelection={initialSelection}
+        />
+        <ToastViewport />
+      </YStack>
+    </BackofficeProvider>
+  );
+}
+
+export const Default = () => <BuilderStory doctype="Pokemon" />;
+export const Picker = () => <BuilderStory />;
+export const EmptyDoctype = () => <BuilderStory doctype="Empty Form" />;
+export const ManySections = () => <BuilderStory doctype="Training Plan" />;
+export const FieldSelected = () => (
+  <BuilderStory doctype="Pokemon" initialSelection="sprite_back" />
+);
+export const Dark = () => (
+  <Preset theme="dark">
+    <BuilderStory doctype="Pokemon" />
+  </Preset>
+);