ding-react-admin 1.0.2 → 2.0.0

package/src/crud/utils/hasUploadValues.ts

@@ -0,0 +1,9 @@
+/** Whether a save payload contains a `File` or `Blob` anywhere (including inline rows). */
+export function hasUploadValues(value: unknown): boolean {
+  if (value instanceof Blob) return true;
+  if (Array.isArray(value)) return value.some(hasUploadValues);
+  if (value && typeof value === "object") {
+    return Object.values(value as Record<string, unknown>).some(hasUploadValues);
+  }
+  return false;
+}

package/src/crud/utils/nestedFieldPath.ts

@@ -0,0 +1,8 @@
+/** RHF path for one cell in a nested field array row, e.g. `lines.0.label`. */
+export function nestedFieldPath(
+  field: string,
+  index: number,
+  source: string,
+): string {
+  return `${field}.${index}.${source}`;
+}

package/src/crud/utils/prepareFormSubmitBody.ts

@@ -0,0 +1,17 @@
+import { hasUploadValues } from "./hasUploadValues";
+import { toFormData, type ToFormDataOptions } from "./toFormData";
+
+export type PrepareFormSubmitBodyOptions = ToFormDataOptions;
+
+/**
+ * When the payload contains any `File`/`Blob`, return `FormData`; otherwise the plain object.
+ */
+export function prepareFormSubmitBody(
+  payload: Record<string, unknown>,
+  options?: PrepareFormSubmitBodyOptions,
+): Record<string, unknown> | FormData {
+  if (hasUploadValues(payload)) {
+    return toFormData(payload, options);
+  }
+  return payload;
+}

package/src/crud/utils/{setByPath.ts → setFormValue.ts}

@@ -1,5 +1,5 @@
-/** Write a value into a record using dot notation, e.g. `invoiceLine.product`. */
-export function setByPath(
+/** Write a value into an object using dot notation, e.g. `invoiceLine.product`. */
+export function setFormValue(
   record: Record<string, unknown>,
   path: string,
   value: unknown,

package/src/crud/utils/toFormData.ts

@@ -0,0 +1,81 @@
+export type ToFormDataOptions = {
+  /**
+   * Omit unchanged upload URL strings (`http://` / `https://`) from the body.
+   * Default `true` — edit forms keep existing files without re-sending the URL.
+   */
+  skipExistingUploadUrls?: boolean;
+};
+
+function isExistingUploadUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function appendFormDataValue(
+  formData: FormData,
+  key: string,
+  value: unknown,
+  options: Required<ToFormDataOptions>,
+): void {
+  if (value === undefined) return;
+
+  if (value === null) {
+    formData.append(key, "");
+    return;
+  }
+
+  if (value instanceof Blob) {
+    formData.append(key, value);
+    return;
+  }
+
+  if (typeof value === "boolean" || typeof value === "number") {
+    formData.append(key, String(value));
+    return;
+  }
+
+  if (typeof value === "string") {
+    if (options.skipExistingUploadUrls && isExistingUploadUrl(value)) {
+      return;
+    }
+    formData.append(key, value);
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      appendFormDataValue(formData, `${key}[${index}]`, item, options);
+    });
+    return;
+  }
+
+  if (typeof value === "object") {
+    for (const [childKey, childValue] of Object.entries(
+      value as Record<string, unknown>,
+    )) {
+      appendFormDataValue(formData, `${key}[${childKey}]`, childValue, options);
+    }
+    return;
+  }
+
+  formData.append(key, String(value));
+}
+
+/**
+ * Flatten a save payload into `FormData` using bracket notation for nested fields
+ * and arrays (e.g. `lines[0][label]`, `address[city]`).
+ */
+export function toFormData(
+  data: Record<string, unknown>,
+  options?: ToFormDataOptions,
+): FormData {
+  const resolved: Required<ToFormDataOptions> = {
+    skipExistingUploadUrls: options?.skipExistingUploadUrls ?? true,
+  };
+  const formData = new FormData();
+
+  for (const [key, value] of Object.entries(data)) {
+    appendFormDataValue(formData, key, value, resolved);
+  }
+
+  return formData;
+}

package/src/crud/utils/useAbortableEffect.ts

@@ -0,0 +1,17 @@
+import { useEffect, type DependencyList } from "react";
+
+/**
+ * Runs an async effect with an `AbortSignal` that aborts on cleanup.
+ * Use with `params.signal` on DataProvider reads and `isAbortError` in catch blocks.
+ */
+export function useAbortableEffect(
+  effect: (signal: AbortSignal) => void | Promise<void>,
+  deps: DependencyList,
+): void {
+  useEffect(() => {
+    const controller = new AbortController();
+    void effect(controller.signal);
+    return () => controller.abort();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+}

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/abortError.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { isAbortError } from "./abortError";
+
+describe("isAbortError", () => {
+  it("detects DOM AbortError", () => {
+    expect(isAbortError({ name: "AbortError" })).toBe(true);
+  });
+
+  it("detects axios CanceledError", () => {
+    expect(isAbortError({ name: "CanceledError", code: "ERR_CANCELED" })).toBe(
+      true,
+    );
+  });
+
+  it("returns false for ordinary errors", () => {
+    expect(isAbortError(new Error("Network Error"))).toBe(false);
+    expect(isAbortError(null)).toBe(false);
+  });
+});

package/src/data/abortError.ts

@@ -0,0 +1,10 @@
+/** True when a fetch/axios call was aborted via `AbortSignal` (not a real failure). */
+export function isAbortError(error: unknown): boolean {
+  if (error == null || typeof error !== "object") return false;
+  const e = error as { name?: string; code?: string };
+  return (
+    e.name === "AbortError" ||
+    e.name === "CanceledError" ||
+    e.code === "ERR_CANCELED"
+  );
+}

package/src/data/createMemoryResourceHandlers.ts

@@ -48,7 +48,7 @@ export function createMemoryResourceHandlers<
       return applyInMemoryListParams(asRows(base), params) as GetListResult<T>;
     },
 
-    async getOne(id): Promise<GetOneResult<T>> {
+    async getOne(id, _params?): Promise<GetOneResult<T>> {
       return { data: getById(config.getRows(), id) as T };
     },
 

package/src/data/createRestResourceHandlers.ts

@@ -1,17 +1,17 @@
-import type { GetListParams, Identifier } from "./dataProviderTypes";
+import type { GetListParams, GetOneParams, Identifier, FormMutationBody } from "./dataProviderTypes";
 import type { ResourceHandlers } from "./resourceHandlers";
 
 export type RestResourceHandlersConfig<
   T extends Record<string, unknown> = Record<string, unknown>,
 > = {
   list: (params: GetListParams) => Promise<{ data: T[]; total: number }>;
-  retrieve: (id: Identifier) => Promise<T>;
-  create: (data: Record<string, unknown>) => Promise<T>;
-  update: (id: Identifier, data: Record<string, unknown>) => Promise<T>;
+  retrieve: (id: Identifier, params?: GetOneParams) => 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;
 };
 
@@ -27,25 +27,31 @@ export function createRestResourceHandlers<
       return config.list(params);
     },
 
-    async getOne(id) {
-      return { data: await config.retrieve(id) };
+    async getOne(id, params) {
+      return { data: await config.retrieve(id, params) };
     },
 
     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

@@ -13,12 +13,19 @@ export type PaginationParams = {
   perPage: number;
 };
 
+export type GetOneParams = {
+  /** Forward to fetch/axios to cancel in-flight reads when the UI unmounts or deps change. */
+  signal?: AbortSignal;
+};
+
 export type GetListParams = {
   pagination?: PaginationParams;
   /** Single or multi-column sort. */
   sort?: SortSpec | SortSpec[];
   /** Filter values; arrays mean "match any of" for that field. */
   filter?: Record<string, unknown>;
+  /** Forward to fetch/axios to cancel in-flight reads when the UI unmounts or deps change. */
+  signal?: AbortSignal;
 };
 
 export type GetListResult<RecordType extends Record<string, unknown>> = {
@@ -36,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>> = {
@@ -47,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`). */
@@ -83,10 +92,11 @@ export type DataProvider<
   getOne: (
     resource: string,
     id: Identifier,
+    params?: GetOneParams,
   ) => 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);
+  });
 });