ding-react-admin 1.0.4 → 2.0.0

package/src/crud/utils/useFormRecord.ts

@@ -0,0 +1,156 @@
+import type { MessageInstance } from "antd/es/message/interface";
+import {
+  useCallback,
+  useState,
+  type MutableRefObject,
+} from "react";
+import type { NavigateFunction } from "react-router-dom";
+import type { DataProvider } from "../../data/dataProviderTypes";
+import { isAbortError } from "../../data/abortError";
+import {
+  type DefaultValues,
+  type FieldValues,
+  type UseFormReturn,
+} from "react-hook-form";
+import type { InlineFieldRegistration } from "../context/InlineFieldsRegistry";
+import { buildResourceFormSubmitBody } from "./buildResourceFormSubmitBody";
+import { applyApiErrorsToForm } from "./formErrors";
+import { useAbortableEffect } from "./useAbortableEffect";
+
+type LoadOptions<T extends FieldValues> = {
+  dp: DataProvider;
+  resource: string;
+  id: string | undefined;
+  isNew: boolean;
+  form: UseFormReturn<T>;
+  message: MessageInstance;
+  defaultValues?: Partial<T>;
+};
+
+/** Edit mode: `getOne` → `form.reset` → bump `formVersion` so field arrays remount. */
+export function useFormRecordLoad<T extends FieldValues>({
+  dp,
+  resource,
+  id,
+  isNew,
+  form,
+  message,
+  defaultValues,
+}: LoadOptions<T>) {
+  const [loading, setLoading] = useState(!isNew);
+  const [formVersion, setFormVersion] = useState(0);
+
+  const load = useCallback(
+    async (signal?: AbortSignal) => {
+      if (isNew || !id) {
+        if (defaultValues) {
+          form.reset({ ...defaultValues } as DefaultValues<T>);
+        }
+        setLoading(false);
+        return;
+      }
+      setLoading(true);
+      try {
+        const res = await dp.getOne(resource, id, { signal });
+        if (signal?.aborted) return;
+        form.reset(res.data as DefaultValues<T>);
+        setFormVersion((v) => v + 1);
+      } catch (e) {
+        if (!isAbortError(e)) {
+          message.error(e instanceof Error ? e.message : "Load failed");
+        }
+      } finally {
+        if (!signal?.aborted) setLoading(false);
+      }
+    },
+    [dp, resource, id, isNew, form, message, defaultValues],
+  );
+
+  useAbortableEffect((signal) => load(signal), [load]);
+
+  return { loading, formVersion };
+}
+
+type SubmitOptions<T extends FieldValues & { id?: unknown }> = {
+  dp: DataProvider;
+  resource: string;
+  id: string | undefined;
+  isNew: boolean;
+  form: UseFormReturn<T>;
+  message: MessageInstance;
+  navigate: NavigateFunction;
+  listPath: string;
+  payloadFieldsRef: MutableRefObject<Set<string>>;
+  inlineRegistryRef: MutableRefObject<Map<string, InlineFieldRegistration>>;
+  onSaved?: (record: T) => void;
+  stayOnPage?: boolean;
+};
+
+/** Save: `buildFormPayload` → clean inline rows → one `create` or `update`. */
+export function useFormRecordSave<T extends FieldValues & { id?: unknown }>({
+  dp,
+  resource,
+  id,
+  isNew,
+  form,
+  message,
+  navigate,
+  listPath,
+  payloadFieldsRef,
+  inlineRegistryRef,
+  onSaved,
+  stayOnPage,
+}: SubmitOptions<T>) {
+  return useCallback(
+    async (values: T) => {
+      try {
+        const raw = values as Record<string, unknown>;
+        const body = buildResourceFormSubmitBody(
+          raw,
+          Array.from(payloadFieldsRef.current),
+          inlineRegistryRef.current.values(),
+        );
+
+        let saved: T;
+        if (isNew) {
+          const res = await dp.create(resource, body);
+          saved = res.data as T;
+          message.success("Created");
+        } else if (id) {
+          const res = await dp.update(resource, { id, data: body });
+          saved = res.data as T;
+          message.success("Updated");
+        } else {
+          return;
+        }
+
+        onSaved?.(saved);
+        if (!stayOnPage) navigate(listPath);
+      } catch (e) {
+        const inlineFieldPaths = Array.from(inlineRegistryRef.current.keys());
+        const handled = await applyApiErrorsToForm(dp, form, message, e, {
+          resource,
+          mutation: isNew ? "create" : "update",
+          inlineFieldPaths,
+        });
+        if (!handled) {
+          message.error(e instanceof Error ? e.message : "Save failed");
+        }
+      }
+    },
+    [
+      dp,
+      resource,
+      id,
+      isNew,
+      form,
+      message,
+      navigate,
+      listPath,
+      payloadFieldsRef,
+      inlineRegistryRef,
+      onSaved,
+      stayOnPage,
+    ],
+  );
+}

package/src/data/createRestResourceHandlers.ts

@@ -1,4 +1,4 @@
-import type { GetListParams, GetOneParams, Identifier } from "./dataProviderTypes";
+import type { GetListParams, GetOneParams, Identifier, FormMutationBody } from "./dataProviderTypes";
 import type { ResourceHandlers } from "./resourceHandlers";
 
 export type RestResourceHandlersConfig<
@@ -6,12 +6,12 @@ export type RestResourceHandlersConfig<
 > = {
   list: (params: GetListParams) => Promise<{ data: T[]; total: number }>;
   retrieve: (id: Identifier, params?: GetOneParams) => Promise<T>;
-  create: (data: Record<string, unknown>) => Promise<T>;
-  update: (id: Identifier, data: Record<string, unknown>) => Promise<T>;
+  create: (data: FormMutationBody) => Promise<T>;
+  update: (id: Identifier, data: FormMutationBody) => Promise<T>;
   destroy: (id: Identifier) => Promise<void>;
-  /** When API create body differs from form `source` paths. */
+  /** When API create body differs from form `source` paths. Not applied when body is already `FormData`. */
   transformCreate?: (data: Record<string, unknown>) => unknown;
-  /** When API update body differs from form `source` paths. */
+  /** When API update body differs from form `source` paths. Not applied when body is already `FormData`. */
   transformUpdate?: (data: Record<string, unknown>) => unknown;
 };
 
@@ -32,20 +32,26 @@ export function createRestResourceHandlers<
     },
 
     async create(data) {
-      const body = config.transformCreate
-        ? config.transformCreate(data as Record<string, unknown>)
-        : data;
+      const body =
+        data instanceof FormData
+          ? data
+          : config.transformCreate
+            ? config.transformCreate(data as Record<string, unknown>)
+            : data;
       return {
-        data: await config.create(body as Record<string, unknown>),
+        data: await config.create(body as FormMutationBody),
       };
     },
 
     async update({ id, data }) {
-      const body = config.transformUpdate
-        ? config.transformUpdate(data as Record<string, unknown>)
-        : data;
+      const body =
+        data instanceof FormData
+          ? data
+          : config.transformUpdate
+            ? config.transformUpdate(data as Record<string, unknown>)
+            : data;
       return {
-        data: await config.update(id, body as Record<string, unknown>),
+        data: await config.update(id, body as FormMutationBody),
       };
     },
 

package/src/data/dataProviderTypes.ts

@@ -43,7 +43,7 @@ export type CreateResult<RecordType extends Record<string, unknown>> = {
 
 export type UpdateParams<RecordType extends Record<string, unknown>> = {
   id: Identifier;
-  data: Partial<RecordType>;
+  data: Partial<RecordType> | FormData;
 };
 
 export type UpdateResult<RecordType extends Record<string, unknown>> = {
@@ -54,14 +54,16 @@ export type DeleteResult<RecordType extends Record<string, unknown>> = {
   data: RecordType | null;
 };
 
+/** Save body from forms — plain JSON object or multipart `FormData` when uploads are present. */
+export type FormMutationBody = Record<string, unknown> | FormData;
+
 export type FormMutation = "create" | "update";
 
 export type ParseFormErrorContext = {
   resource: string;
   mutation: FormMutation;
-  /** Set when saving an inline row — prefix field paths for that row. */
-  inlineArrayName?: string;
-  rowIndex?: number;
+  /** Top-level inline field-array paths on the form, e.g. `["lines"]`. */
+  inlineFieldPaths?: string[];
 };
 
 /** Field paths match react-hook-form `name` (form `source` or inline `arrayName.index.source`). */
@@ -94,7 +96,7 @@ export type DataProvider<
   ) => Promise<GetOneResult<RecordType>>;
   create: (
     resource: string,
-    data: Partial<RecordType>,
+    data: Partial<RecordType> | FormData,
   ) => Promise<CreateResult<RecordType>>;
   update: (
     resource: string,

package/src/data/dataUtils.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it, vi } from "vitest";
-import { pickBySources } from "../crud/utils/pickBySources";
+import { buildFormPayload } from "../crud/utils/buildFormPayload";
+import { buildInlineRowsPayload } from "../crud/utils/buildInlineRowsPayload";
+import { nestedFieldPath } from "../crud/utils/nestedFieldPath";
+import { hasUploadValues } from "../crud/utils/hasUploadValues";
+import { prepareFormSubmitBody } from "../crud/utils/prepareFormSubmitBody";
+import { toFormData } from "../crud/utils/toFormData";
 import { createRestResourceHandlers } from "./createRestResourceHandlers";
 import {
   toDjangoRestOrdering,
@@ -7,14 +12,14 @@ import {
   toODataOrderBy,
 } from "./sortHelpers";
 
-describe("pickBySources", () => {
+describe("buildFormPayload", () => {
   it("picks flat fields", () => {
     const values = {
       username: "jane",
       email: "jane@example.com",
       tenants: [{ id: 1 }],
     };
-    expect(pickBySources(values, ["username", "email"])).toEqual({
+    expect(buildFormPayload(values, ["username", "email"])).toEqual({
       username: "jane",
       email: "jane@example.com",
     });
@@ -25,14 +30,101 @@ describe("pickBySources", () => {
       invoiceLine: { product: "SKU-1", quantity: 2 },
       extra: "ignored",
     };
-    expect(pickBySources(values, ["invoiceLine.product", "invoiceLine.quantity"])).toEqual({
+    expect(
+      buildFormPayload(values, ["invoiceLine.product", "invoiceLine.quantity"]),
+    ).toEqual({
       invoiceLine: { product: "SKU-1", quantity: 2 },
     });
   });
 
-  it("returns all values when no sources registered", () => {
+  it("returns all values when no field paths registered", () => {
     const values = { a: 1, b: 2 };
-    expect(pickBySources(values, [])).toEqual(values);
+    expect(buildFormPayload(values, [])).toEqual(values);
+  });
+});
+
+describe("buildInlineRowsPayload", () => {
+  it("picks sources and keeps record id", () => {
+    const rows = [
+      { rowKey: "a", id: 10, label: "A", quantity: 2, extra: "x" },
+      { rowKey: "b", label: "B", quantity: 1 },
+    ];
+    expect(buildInlineRowsPayload(rows, ["label", "quantity"])).toEqual([
+      { label: "A", quantity: 2, id: 10 },
+      { label: "B", quantity: 1 },
+    ]);
+  });
+
+  it("applies transformRows", () => {
+    const rows = [{ rowKey: "a", label: "A" }];
+    const result = buildInlineRowsPayload(rows, ["label"], {
+      transformRows: (cleaned) => cleaned.map((r) => ({ ...r, kind: "line" })),
+    });
+    expect(result).toEqual([{ label: "A", kind: "line" }]);
+  });
+});
+
+describe("nestedFieldPath", () => {
+  it("builds dot paths", () => {
+    expect(nestedFieldPath("lines", 0, "label")).toBe("lines.0.label");
+  });
+});
+
+describe("hasUploadValues", () => {
+  it("detects File in nested payload", () => {
+    const file = new File(["x"], "a.png", { type: "image/png" });
+    expect(hasUploadValues({ name: "x" })).toBe(false);
+    expect(hasUploadValues({ photo: file })).toBe(true);
+    expect(hasUploadValues({ lines: [{ photo: file }] })).toBe(true);
+  });
+});
+
+describe("toFormData", () => {
+  it("encodes flat scalars and files", () => {
+    const file = new File(["x"], "photo.png", { type: "image/png" });
+    const fd = toFormData({ name: "Widget", active: true, count: 2, photo: file });
+
+    expect(fd.get("name")).toBe("Widget");
+    expect(fd.get("active")).toBe("true");
+    expect(fd.get("count")).toBe("2");
+    expect(fd.get("photo")).toBe(file);
+  });
+
+  it("encodes null as empty string and skips unchanged upload URLs", () => {
+    const fd = toFormData({
+      photo: null,
+      avatar: "https://cdn.example.com/a.jpg",
+      title: "Hello",
+    });
+
+    expect(fd.get("photo")).toBe("");
+    expect(fd.get("avatar")).toBeNull();
+    expect(fd.get("title")).toBe("Hello");
+  });
+
+  it("encodes inline rows with bracket notation", () => {
+    const file = new File(["x"], "line.png", { type: "image/png" });
+    const fd = toFormData({
+      lines: [{ id: 10, label: "A", photo: file }],
+    });
+
+    expect(fd.get("lines[0][id]")).toBe("10");
+    expect(fd.get("lines[0][label]")).toBe("A");
+    expect(fd.get("lines[0][photo]")).toBe(file);
+  });
+});
+
+describe("prepareFormSubmitBody", () => {
+  it("returns plain object when no uploads", () => {
+    const payload = { name: "Widget" };
+    expect(prepareFormSubmitBody(payload)).toBe(payload);
+  });
+
+  it("returns FormData when uploads are present", () => {
+    const file = new File(["x"], "a.png", { type: "image/png" });
+    const body = prepareFormSubmitBody({ name: "Widget", photo: file });
+    expect(body).toBeInstanceOf(FormData);
+    expect((body as FormData).get("photo")).toBe(file);
   });
 });
 
@@ -105,4 +197,24 @@ describe("createRestResourceHandlers", () => {
     await handlers.update({ id: "1", data: { username: "bob" } });
     expect(update).toHaveBeenCalledWith("1", { patch: { username: "bob" } });
   });
+
+  it("passes FormData through without transform", async () => {
+    const create = vi.fn(async (data) => data);
+    const transformCreate = vi.fn((data) => data);
+
+    const handlers = createRestResourceHandlers({
+      list: async () => ({ data: [], total: 0 }),
+      retrieve: async () => ({}),
+      create,
+      update: async (_id, data) => data,
+      destroy: async () => {},
+      transformCreate,
+    });
+
+    const fd = new FormData();
+    fd.append("name", "Widget");
+    await handlers.create(fd);
+    expect(transformCreate).not.toHaveBeenCalled();
+    expect(create).toHaveBeenCalledWith(fd);
+  });
 });

package/src/data/parseFormErrorHelpers.test.ts

@@ -1,84 +1,138 @@
-import { describe, expect, it } from "vitest";
-import {
-  parseDjangoDRFFormErrors,
-  parseDotNetFormErrors,
-  parseNodeFormErrors,
-} from "./parseFormErrorHelpers";
-
-const mainCtx = { resource: "users", mutation: "create" as const };
-const inlineCtx = {
-  resource: "invoice-lines",
-  mutation: "create" as const,
-  inlineArrayName: "__inline_invoice_lines",
-  rowIndex: 1,
-};
-
-describe("parseDjangoDRFFormErrors", () => {
-  it("maps field and non_field_errors", () => {
-    const parsed = parseDjangoDRFFormErrors(
-      {
-        body: {
-          email: ["Enter a valid email."],
-          non_field_errors: ["Cannot save"],
-        },
-      },
-      mainCtx,
-    );
-    expect(parsed).toEqual({
-      fields: { email: "Enter a valid email." },
-      global: ["Cannot save"],
-    });
-  });
-
-  it("prefixes inline row fields", () => {
-    const parsed = parseDjangoDRFFormErrors(
-      { body: { quantity: ["Must be positive"] } },
-      inlineCtx,
-    );
-    expect(parsed?.fields).toEqual({
-      "__inline_invoice_lines.1.quantity": "Must be positive",
-    });
-  });
-});
-
-describe("parseDotNetFormErrors", () => {
-  it("maps errors object with camelCase", () => {
-    const parsed = parseDotNetFormErrors(
-      {
-        body: {
-          errors: { Email: ["The Email field is required."] },
-        },
-      },
-      mainCtx,
-    );
-    expect(parsed?.fields).toEqual({
-      email: "The Email field is required.",
-    });
-  });
-});
-
-describe("parseNodeFormErrors", () => {
-  it("maps express-validator array", () => {
-    const parsed = parseNodeFormErrors(
-      {
-        body: {
-          errors: [{ path: "email", msg: "Invalid email" }],
-        },
-      },
-      mainCtx,
-    );
-    expect(parsed?.fields).toEqual({ email: "Invalid email" });
-  });
-
-  it("maps Joi details", () => {
-    const parsed = parseNodeFormErrors(
-      {
-        body: {
-          details: [{ message: "Required", path: ["email"] }],
-        },
-      },
-      mainCtx,
-    );
-    expect(parsed?.fields).toEqual({ email: "Required" });
-  });
-});
+import { describe, expect, it } from "vitest";
+import {
+  parseDjangoDRFFormErrors,
+  parseDotNetFormErrors,
+  parseNodeFormErrors,
+  flattenNestedArrayErrors,
+  resolveErrorBody,
+} from "./parseFormErrorHelpers";
+
+const mainCtx = { resource: "users", mutation: "create" as const };
+
+describe("parseDjangoDRFFormErrors", () => {
+  it("maps field and non_field_errors", () => {
+    const parsed = parseDjangoDRFFormErrors(
+      {
+        body: {
+          email: ["Enter a valid email."],
+          non_field_errors: ["Cannot save"],
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed).toEqual({
+      fields: { email: "Enter a valid email." },
+      global: ["Cannot save"],
+    });
+  });
+
+  it("flattens nested inline row errors", () => {
+    const parsed = parseDjangoDRFFormErrors(
+      {
+        body: {
+          lines: [
+            { quantity: ["Must be positive"] },
+            {},
+            { label: ["Required"] },
+          ],
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed?.fields).toEqual({
+      "lines.0.quantity": "Must be positive",
+      "lines.2.label": "Required",
+    });
+  });
+});
+
+describe("resolveErrorBody", () => {
+  it("reads axios-style response.data", async () => {
+    const body = await resolveErrorBody({
+      response: { data: { email: ["Invalid"] } },
+    });
+    expect(body).toEqual({ email: ["Invalid"] });
+  });
+
+  it("reads fetch ResponseError response.json()", async () => {
+    const response = new Response(
+      JSON.stringify({ email: ["Enter a valid email address."] }),
+      {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+    const body = await resolveErrorBody({
+      name: "ResponseError",
+      message: "Response returned an error code",
+      response,
+    });
+    expect(body).toEqual({ email: ["Enter a valid email address."] });
+  });
+
+  it("returns null for non-json fetch responses", async () => {
+    const response = new Response("bad request", {
+      status: 400,
+      headers: { "Content-Type": "text/plain" },
+    });
+    const body = await resolveErrorBody({ response });
+    expect(body).toBeNull();
+  });
+});
+
+describe("flattenNestedArrayErrors", () => {
+  it("maps row errors to RHF paths", () => {
+    const fields: Record<string, string | string[]> = {};
+    flattenNestedArrayErrors("lines", [
+      { label: ["Required"] },
+      { quantity: ["Too small", "Invalid"] },
+    ], fields);
+    expect(fields).toEqual({
+      "lines.0.label": "Required",
+      "lines.1.quantity": ["Too small", "Invalid"],
+    });
+  });
+});
+
+describe("parseDotNetFormErrors", () => {
+  it("maps errors object with camelCase", () => {
+    const parsed = parseDotNetFormErrors(
+      {
+        body: {
+          errors: { Email: ["The Email field is required."] },
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed?.fields).toEqual({
+      email: "The Email field is required.",
+    });
+  });
+});
+
+describe("parseNodeFormErrors", () => {
+  it("maps express-validator array", () => {
+    const parsed = parseNodeFormErrors(
+      {
+        body: {
+          errors: [{ path: "email", msg: "Invalid email" }],
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed?.fields).toEqual({ email: "Invalid email" });
+  });
+
+  it("maps Joi details", () => {
+    const parsed = parseNodeFormErrors(
+      {
+        body: {
+          details: [{ message: "Required", path: ["email"] }],
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed?.fields).toEqual({ email: "Required" });
+  });
+});
+