ding-react-admin 1.0.4 → 2.0.0

package/src/crud/fields/ImageField.tsx

@@ -0,0 +1,120 @@
+import { DeleteOutlined, UploadOutlined } from "@ant-design/icons";
+import { Button, Image, Space } from "antd";
+import { useRef } from "react";
+import type { BaseSourceProps, FieldRules } from "../types";
+import { FieldWrapper } from "./FieldWrapper";
+import { hasUploadValue, type UploadFieldValue } from "./uploadFieldUtils";
+import { useUploadPreviewUrl } from "./useUploadPreviewUrl";
+
+export type ImageFieldProps = BaseSourceProps & {
+  name?: string;
+  required?: boolean;
+  rules?: FieldRules;
+  hideLabel?: boolean;
+  /** Allow clearing an existing or newly selected image. */
+  clearable?: boolean;
+  accept?: string;
+  /** Max preview width in pixels. */
+  previewWidth?: number;
+};
+
+function ImageFieldInput({
+  value,
+  onChange,
+  disabled,
+  clearable,
+  accept = "image/*",
+  previewWidth = 200,
+}: {
+  value: UploadFieldValue;
+  onChange: (value: UploadFieldValue) => void;
+  disabled?: boolean;
+  clearable?: boolean;
+  accept?: string;
+  previewWidth?: number;
+}) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const previewUrl = useUploadPreviewUrl(value);
+  const showClear = clearable && hasUploadValue(value);
+
+  return (
+    <Space direction="vertical" size="middle" style={{ width: "100%" }}>
+      {previewUrl ? (
+        <Image
+          src={previewUrl}
+          alt=""
+          style={{ maxWidth: previewWidth, maxHeight: previewWidth, objectFit: "contain" }}
+        />
+      ) : null}
+      <Space wrap>
+        <Button
+          icon={<UploadOutlined />}
+          disabled={disabled}
+          onClick={() => inputRef.current?.click()}
+        >
+          Choose image
+        </Button>
+        {showClear ? (
+          <Button
+            icon={<DeleteOutlined />}
+            disabled={disabled}
+            onClick={() => {
+              onChange(null);
+              if (inputRef.current) inputRef.current.value = "";
+            }}
+          >
+            Clear
+          </Button>
+        ) : null}
+      </Space>
+      <input
+        ref={inputRef}
+        type="file"
+        accept={accept}
+        disabled={disabled}
+        tabIndex={-1}
+        aria-hidden
+        style={{ display: "none" }}
+        onChange={(e) => {
+          const file = e.target.files?.[0];
+          onChange(file ?? null);
+          e.target.value = "";
+        }}
+      />
+    </Space>
+  );
+}
+
+export function ImageField({
+  source,
+  name,
+  label,
+  required,
+  rules,
+  hideLabel,
+  clearable,
+  accept,
+  previewWidth,
+}: ImageFieldProps) {
+  return (
+    <FieldWrapper
+      source={source}
+      name={name}
+      label={label}
+      required={required}
+      rules={rules}
+      hideLabel={hideLabel}
+    >
+      {({ value, onChange, disabled }) => (
+        <ImageFieldInput
+          value={value as UploadFieldValue}
+          onChange={onChange}
+          disabled={disabled}
+          clearable={clearable}
+          accept={accept}
+          previewWidth={previewWidth}
+        />
+      )}
+    </FieldWrapper>
+  );
+}

package/src/crud/fields/uploadFieldUtils.ts

@@ -0,0 +1,21 @@
+/** Form value for file/image fields — backend-agnostic. */
+export type UploadFieldValue = File | string | null | undefined;
+
+export function hasUploadValue(value: UploadFieldValue): boolean {
+  if (value instanceof File) return true;
+  return typeof value === "string" && value.length > 0;
+}
+
+export function getUploadFileName(value: UploadFieldValue): string | undefined {
+  if (value instanceof File) return value.name;
+  if (typeof value === "string" && value.length > 0) {
+    try {
+      const pathname = new URL(value, "http://local").pathname;
+      const name = pathname.split("/").filter(Boolean).pop();
+      return name || value;
+    } catch {
+      return value.split("/").filter(Boolean).pop() || value;
+    }
+  }
+  return undefined;
+}

package/src/crud/fields/useUploadPreviewUrl.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+import type { UploadFieldValue } from "./uploadFieldUtils";
+
+/** Preview URL for uploads — `URL.createObjectURL` for `File`, direct URL for existing strings. */
+export function useUploadPreviewUrl(value: UploadFieldValue): string | undefined {
+  const [objectUrl, setObjectUrl] = useState<string | undefined>();
+
+  useEffect(() => {
+    if (value instanceof File) {
+      const url = URL.createObjectURL(value);
+      setObjectUrl(url);
+      return () => URL.revokeObjectURL(url);
+    }
+    setObjectUrl(undefined);
+  }, [value]);
+
+  if (value instanceof File) return objectUrl;
+  if (typeof value === "string" && value.length > 0) return value;
+  return undefined;
+}

package/src/crud/index.ts

@@ -2,22 +2,13 @@ export { ResourceList, useResourceListContext } from "./ResourceList";
 export type { ResourceListProps } from "./ResourceList";
 export { FilterBar } from "./FilterBar";
 export { ResourceForm } from "./ResourceForm";
-export type {
-  ResourceFormProps,
-  ResourceFormInlineConfig,
-} from "./ResourceForm";
+export type { ResourceFormProps } from "./ResourceForm";
 export { ResourceFormModal } from "./ResourceFormModal";
 export type { ResourceFormModalProps } from "./ResourceFormModal";
-export {
-  InlineFormSet,
-  InlineFormSetStacked,
-  saveInlineRows,
-  loadInlineRows,
-} from "./InlineFormSet";
+export { InlineFormSet, InlineFormSetStacked } from "./InlineFormSet";
 export type {
   InlineFormSetProps,
   InlineFormSetStackedProps,
-  SaveInlineOptions,
   InlineFormSetLayout,
 } from "./InlineFormSet";
 export { FormTabs, FormTab } from "./FormTabs";
@@ -33,8 +24,13 @@ export { SelectField } from "./fields/SelectField";
 export { PasswordField } from "./fields/PasswordField";
 export { ReferenceField } from "./fields/ReferenceField";
 export { ReferenceManyField } from "./fields/ReferenceManyField";
+export { ImageField } from "./fields/ImageField";
+export { FileField } from "./fields/FileField";
 export { FieldWrapper } from "./fields/FieldWrapper";
 export type { FieldWrapperProps } from "./fields/FieldWrapper";
+export type { ImageFieldProps } from "./fields/ImageField";
+export type { FileFieldProps } from "./fields/FileField";
+export type { UploadFieldValue } from "./fields/uploadFieldUtils";
 
 export { TextColumn } from "./columns/TextColumn";
 export { NumberColumn } from "./columns/NumberColumn";
@@ -42,6 +38,7 @@ export { BooleanColumn } from "./columns/BooleanColumn";
 export { DateColumn } from "./columns/DateColumn";
 export { ReferenceColumn } from "./columns/ReferenceColumn";
 export { ReferenceManyColumn } from "./columns/ReferenceManyColumn";
+export { ImageColumn } from "./columns/ImageColumn";
 export { CustomColumn } from "./columns/CustomColumn";
 
 export { TextFilter } from "./filters/TextFilter";
@@ -61,15 +58,22 @@ export type {
   ListQueryActions,
 } from "./utils/useListQueryState";
 export { useChoices } from "./utils/useChoices";
-export { getByPath } from "./utils/getByPath";
-export { pickBySources } from "./utils/pickBySources";
-export { inlineArrayName } from "./utils/inlineArrayName";
-export { inlineFieldName } from "./utils/inlineFieldName";
-export { setByPath } from "./utils/setByPath";
+export { getFormValue } from "./utils/getFormValue";
+export { setFormValue } from "./utils/setFormValue";
+export { buildFormPayload } from "./utils/buildFormPayload";
+export { buildInlineRowsPayload } from "./utils/buildInlineRowsPayload";
+export { buildResourceFormSubmitBody } from "./utils/buildResourceFormSubmitBody";
+export { prepareFormSubmitBody } from "./utils/prepareFormSubmitBody";
+export { toFormData } from "./utils/toFormData";
+export { hasUploadValues } from "./utils/hasUploadValues";
+export type { ToFormDataOptions } from "./utils/toFormData";
+export type { PrepareFormSubmitBodyOptions } from "./utils/prepareFormSubmitBody";
+export { nestedFieldPath } from "./utils/nestedFieldPath";
 export {
-  useSubmitField,
-  useSectionField,
-} from "./context/SubmitFieldsContext";
+  useRegisterPayloadField,
+  useRegisterSectionField,
+} from "./context/PayloadFieldsContext";
+export type { InlineFieldRegistration } from "./context/InlineFieldsRegistry";
 
 export type {
   BaseSourceProps,

package/src/crud/types.ts

@@ -57,18 +57,20 @@ export type FilterDefinition = {
 };
 
 export type InlineFormSetBaseProps = {
-  resource: string;
-  foreignKey: string;
+  /** RHF `useFieldArray` name and default API nested key, e.g. `"lines"`. */
+  field: string;
   label?: string;
-  name?: string;
+  /** API key when different from `field`. */
+  payloadKey?: string;
+  transformRows?: (rows: Record<string, unknown>[]) => unknown;
 };
 
 /** Passed to each tabular inline column's `cell` renderer. */
 export type InlineCellContext = {
-  /** Full RHF path, e.g. `__inline_invoice_lines.0.label`. */
+  /** Full RHF path, e.g. `lines.0.label`. */
   name: string;
   index: number;
-  arrayName: string;
+  field: string;
 };
 
 export type InlineColumnDef = {
@@ -81,9 +83,9 @@ export type InlineColumnDef = {
 
 /** Passed to `InlineFormSetStacked`'s `renderRow` for one related row. */
 export type InlineRowContext = {
-  arrayName: string;
+  field: string;
   index: number;
-  /** RHF path helper — `name("label")` → `arrayName.index.label`. */
+  /** RHF path helper — `name("label")` → `field.index.label`. */
   name: (source: string) => string;
 };
 

package/src/crud/utils/buildFormPayload.ts

@@ -0,0 +1,24 @@
+import { getFormValue } from "./getFormValue";
+import { setFormValue } from "./setFormValue";
+
+/**
+ * Build the API save body from form values using registered field paths.
+ * Flat `email` → `{ email }`; nested `address.city` → `{ address: { city } }`.
+ */
+export function buildFormPayload(
+  values: Record<string, unknown>,
+  fieldPaths: string[],
+): Record<string, unknown> {
+  if (fieldPaths.length === 0) {
+    return { ...values };
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const path of fieldPaths) {
+    const value = getFormValue(values, path);
+    if (value !== undefined) {
+      setFormValue(result, path, value);
+    }
+  }
+  return result;
+}

package/src/crud/utils/buildInlineRowsPayload.ts

@@ -0,0 +1,37 @@
+export type BuildInlineRowsPayloadOptions = {
+  transformRows?: (rows: Record<string, unknown>[]) => unknown;
+};
+
+/** Clean inline field-array rows for the API (strip RHF `rowKey`, keep record `id`). */
+export function buildInlineRowsPayload(
+  rows: unknown,
+  sources: string[],
+  options?: BuildInlineRowsPayloadOptions,
+): unknown {
+  if (!Array.isArray(rows)) return [];
+
+  const cleaned = rows.map((row) => {
+    if (!row || typeof row !== "object") return {};
+    const record = row as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+
+    for (const source of sources) {
+      const value = record[source];
+      if (value !== undefined) {
+        out[source] = value;
+      }
+    }
+
+    const id = record.id;
+    if (id !== undefined && id !== null) {
+      out.id = id;
+    }
+
+    return out;
+  });
+
+  if (options?.transformRows) {
+    return options.transformRows(cleaned);
+  }
+  return cleaned;
+}

package/src/crud/utils/buildResourceFormSubmitBody.ts

@@ -0,0 +1,29 @@
+import type { InlineFieldRegistration } from "../context/InlineFieldsRegistry";
+import { buildFormPayload } from "./buildFormPayload";
+import { buildInlineRowsPayload } from "./buildInlineRowsPayload";
+import {
+  prepareFormSubmitBody,
+  type PrepareFormSubmitBodyOptions,
+} from "./prepareFormSubmitBody";
+
+/** Build the create/update body from form values, auto-switching to multipart when needed. */
+export function buildResourceFormSubmitBody(
+  raw: Record<string, unknown>,
+  payloadFieldPaths: string[],
+  inlineRegistry?: Iterable<InlineFieldRegistration>,
+  options?: PrepareFormSubmitBodyOptions,
+): Record<string, unknown> | FormData {
+  const payload = buildFormPayload(raw, payloadFieldPaths);
+
+  if (inlineRegistry) {
+    for (const inline of inlineRegistry) {
+      const rows = raw[inline.field];
+      const key = inline.payloadKey ?? inline.field;
+      payload[key] = buildInlineRowsPayload(rows, inline.sources, {
+        transformRows: inline.transformRows,
+      });
+    }
+  }
+
+  return prepareFormSubmitBody(payload, options);
+}

package/src/crud/utils/formErrors.ts

@@ -1,38 +1,42 @@
-import type { MessageInstance } from "antd/es/message/interface";
-import type { FieldPath, FieldValues, UseFormReturn } from "react-hook-form";
-import type { DataProvider, ParseFormErrorContext } from "../../data/dataProviderTypes";
-
-function toMessages(value: string | string[] | undefined): string[] {
-  if (!value) return [];
-  return Array.isArray(value) ? value : [value];
-}
-
-export function applyFormErrors<T extends FieldValues>(
-  form: UseFormReturn<T>,
-  parsed: { fields?: Record<string, string | string[]>; global?: string | string[] },
-  message: MessageInstance,
-) {
-  for (const msg of toMessages(parsed.global)) {
-    message.error(msg);
-  }
-  for (const [path, msg] of Object.entries(parsed.fields ?? {})) {
-    const text = Array.isArray(msg) ? msg.join(", ") : msg;
-    form.setError(path as FieldPath<T>, { type: "server", message: text });
-  }
-}
-
-export function parseAndApplyFormErrors<T extends FieldValues>(
-  dp: DataProvider,
-  form: UseFormReturn<T>,
-  message: MessageInstance,
-  error: unknown,
-  context: ParseFormErrorContext,
-): boolean {
-  const parsed = dp.parseFormError?.(error, context);
-  if (!parsed) return false;
-  const hasFields = Object.keys(parsed.fields ?? {}).length > 0;
-  const hasGlobal = toMessages(parsed.global).length > 0;
-  if (!hasFields && !hasGlobal) return false;
-  applyFormErrors(form, parsed, message);
-  return true;
-}
+import type { MessageInstance } from "antd/es/message/interface";
+import type { FieldPath, FieldValues, UseFormReturn } from "react-hook-form";
+import type { DataProvider, ParseFormErrorContext } from "../../data/dataProviderTypes";
+import { resolveErrorBody } from "../../data/parseFormErrorHelpers";
+
+function toMessages(value: string | string[] | undefined): string[] {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+export function applyFormErrors<T extends FieldValues>(
+  form: UseFormReturn<T>,
+  parsed: { fields?: Record<string, string | string[]>; global?: string | string[] },
+  message: MessageInstance,
+) {
+  for (const msg of toMessages(parsed.global)) {
+    message.error(msg);
+  }
+  for (const [path, msg] of Object.entries(parsed.fields ?? {})) {
+    const text = Array.isArray(msg) ? msg.join(", ") : msg;
+    form.setError(path as FieldPath<T>, { type: "server", message: text });
+  }
+}
+
+export async function applyApiErrorsToForm<T extends FieldValues>(
+  dp: DataProvider,
+  form: UseFormReturn<T>,
+  message: MessageInstance,
+  error: unknown,
+  context: ParseFormErrorContext,
+): Promise<boolean> {
+  const body = await resolveErrorBody(error);
+  const normalizedError = body != null ? { body } : error;
+  const parsed = dp.parseFormError?.(normalizedError, context);
+  if (!parsed) return false;
+  const hasFields = Object.keys(parsed.fields ?? {}).length > 0;
+  const hasGlobal = toMessages(parsed.global).length > 0;
+  if (!hasFields && !hasGlobal) return false;
+  applyFormErrors(form, parsed, message);
+  return true;
+}
+

package/src/crud/utils/{getByPath.ts → getFormValue.ts}

@@ -1,5 +1,5 @@
-/** Read nested value from a record using dot notation, e.g. `brand.name`. */
-export function getByPath(
+/** Read a nested value from form values or a record, e.g. `lines.0.label`. */
+export function getFormValue(
   record: Record<string, unknown>,
   path: string,
 ): unknown {

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