ding-react-admin 1.0.4 → 2.0.4

package/src/crud/index.ts

@@ -1,90 +1,99 @@
-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 { ResourceFormModal } from "./ResourceFormModal";
-export type { ResourceFormModalProps } from "./ResourceFormModal";
-export {
-  InlineFormSet,
-  InlineFormSetStacked,
-  saveInlineRows,
-  loadInlineRows,
-} from "./InlineFormSet";
-export type {
-  InlineFormSetProps,
-  InlineFormSetStackedProps,
-  SaveInlineOptions,
-  InlineFormSetLayout,
-} from "./InlineFormSet";
-export { FormTabs, FormTab } from "./FormTabs";
-export type { FormTabsProps, FormTabProps } from "./FormTabs";
-export { FormSteps, FormStep } from "./FormSteps";
-export type { FormStepsProps, FormStepProps } from "./FormSteps";
-
-export { TextField } from "./fields/TextField";
-export { NumberField } from "./fields/NumberField";
-export { BooleanField } from "./fields/BooleanField";
-export { DateField } from "./fields/DateField";
-export { SelectField } from "./fields/SelectField";
-export { PasswordField } from "./fields/PasswordField";
-export { ReferenceField } from "./fields/ReferenceField";
-export { ReferenceManyField } from "./fields/ReferenceManyField";
-export { FieldWrapper } from "./fields/FieldWrapper";
-export type { FieldWrapperProps } from "./fields/FieldWrapper";
-
-export { TextColumn } from "./columns/TextColumn";
-export { NumberColumn } from "./columns/NumberColumn";
-export { BooleanColumn } from "./columns/BooleanColumn";
-export { DateColumn } from "./columns/DateColumn";
-export { ReferenceColumn } from "./columns/ReferenceColumn";
-export { ReferenceManyColumn } from "./columns/ReferenceManyColumn";
-export { CustomColumn } from "./columns/CustomColumn";
-
-export { TextFilter } from "./filters/TextFilter";
-export { NumberFilter } from "./filters/NumberFilter";
-export { BooleanFilter } from "./filters/BooleanFilter";
-export { DateFilter } from "./filters/DateFilter";
-export { SelectFilter } from "./filters/SelectFilter";
-export {
-  ReferenceFilter,
-  ReferenceManyFilter,
-} from "./filters/ReferenceFilter";
-
-export { useListQueryState } from "./utils/useListQueryState";
-export { useAbortableEffect } from "./utils/useAbortableEffect";
-export type {
-  ListQueryState,
-  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 {
-  useSubmitField,
-  useSectionField,
-} from "./context/SubmitFieldsContext";
-
-export type {
-  BaseSourceProps,
-  ChoiceOption,
-  ChoicesLoader,
-  ReferenceProps,
-  DisplayProps,
-  EditMode,
-  FieldRules,
-  InlineCellContext,
-  InlineColumnDef,
-  InlineFormSetBaseProps,
-  InlineRowContext,
-  ResourceListBuiltInActions,
-  ResourceListBulkAction,
-  ResourceListBulkActionHelpers,
-  ResourceListRowActionsHelpers,
-} from "./types";
+export { ResourceList, useResourceListContext } from "./ResourceList";
+export type { ResourceListProps } from "./ResourceList";
+export { FilterBar } from "./FilterBar";
+export { ResourceForm } from "./ResourceForm";
+export type { ResourceFormProps } from "./ResourceForm";
+export { ResourceFormModal } from "./ResourceFormModal";
+export type { ResourceFormModalProps } from "./ResourceFormModal";
+export { InlineFormSet, InlineFormSetStacked } from "./InlineFormSet";
+export type {
+  InlineFormSetProps,
+  InlineFormSetStackedProps,
+  InlineFormSetLayout,
+} from "./InlineFormSet";
+export { FormTabs, FormTab } from "./FormTabs";
+export type { FormTabsProps, FormTabProps } from "./FormTabs";
+export { FormSteps, FormStep } from "./FormSteps";
+export type { FormStepsProps, FormStepProps } from "./FormSteps";
+
+export { TextField } from "./fields/TextField";
+export { NumberField } from "./fields/NumberField";
+export { BooleanField } from "./fields/BooleanField";
+export { DateField } from "./fields/DateField";
+export { SelectField } from "./fields/SelectField";
+export { PasswordField } from "./fields/PasswordField";
+export { ReferenceField } from "./fields/ReferenceField";
+export type { ReferenceFieldProps } from "./fields/ReferenceField";
+export { ReferenceManyField } from "./fields/ReferenceManyField";
+export type { ReferenceManyFieldProps } from "./fields/ReferenceManyField";
+export { ReferenceInputActions } from "./fields/ReferenceInputActions";
+export type { ReferenceInputActionsProps } from "./fields/ReferenceInputActions";
+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";
+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";
+export { NumberFilter } from "./filters/NumberFilter";
+export { BooleanFilter } from "./filters/BooleanFilter";
+export { DateFilter } from "./filters/DateFilter";
+export { SelectFilter } from "./filters/SelectFilter";
+export {
+  ReferenceFilter,
+  ReferenceManyFilter,
+} from "./filters/ReferenceFilter";
+
+export { useListQueryState } from "./utils/useListQueryState";
+export { useAbortableEffect } from "./utils/useAbortableEffect";
+export type {
+  ListQueryState,
+  ListQueryActions,
+} from "./utils/useListQueryState";
+export { useChoices } from "./utils/useChoices";
+export type { UseChoicesOptions } from "./utils/useChoices";
+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 {
+  useRegisterPayloadField,
+  useRegisterSectionField,
+} from "./context/PayloadFieldsContext";
+export type { InlineFieldRegistration } from "./context/InlineFieldsRegistry";
+
+export type {
+  BaseSourceProps,
+  ChoiceOption,
+  ChoicesLoader,
+  ReferenceProps,
+  DisplayProps,
+  EditMode,
+  FieldRules,
+  InlineCellContext,
+  InlineColumnDef,
+  InlineFormSetBaseProps,
+  InlineRowContext,
+  ResourceListBuiltInActions,
+  ResourceListBulkAction,
+  ResourceListBulkActionHelpers,
+  ResourceListRowActionsHelpers,
+} from "./types";

package/src/crud/types.ts

@@ -1,132 +1,146 @@
-import type { ReactNode } from "react";
-import type { ColumnsType } from "antd/es/table";
-import type { DataProvider } from "../data/dataProviderTypes";
-import type { RegisterOptions } from "react-hook-form";
-
-export type BaseSourceProps = {
-  source: string;
-  label?: string;
-};
-
-export type ChoiceOption = {
-  label: string;
-  value: unknown;
-  /** Full record when loaded from a reference resource (for dependent fields). */
-  record?: Record<string, unknown>;
-};
-
-export type ChoicesContext = {
-  dataProvider: DataProvider;
-  search?: string;
-};
-
-export type ChoicesLoader =
-  | { resource: string; filter?: Record<string, unknown> }
-  | ChoiceOption[]
-  | ((ctx: ChoicesContext) => Promise<ChoiceOption[]>);
-
-export type ReferenceProps = {
-  reference?: string;
-  choices?: ChoicesLoader;
-  optionLabel?: string | ((record: Record<string, unknown>) => string);
-  optionValue?: string;
-};
-
-export type DisplayProps = {
-  display?: string | ((record: Record<string, unknown>) => ReactNode);
-};
-
-export type FieldRules = RegisterOptions;
-
-export type ColumnDefinition<T extends Record<string, unknown>> = {
-  key: string;
-  source: string;
-  label?: string;
-  sortable?: boolean;
-  buildColumn: () => ColumnsType<T>[number];
-};
-
-export type FilterDefinition = {
-  key: string;
-  source: string;
-  label?: string;
-  render: (props: {
-    value: unknown;
-    onChange: (value: unknown) => void;
-  }) => ReactNode;
-};
-
-export type InlineFormSetBaseProps = {
-  resource: string;
-  foreignKey: string;
-  label?: string;
-  name?: string;
-};
-
-/** Passed to each tabular inline column's `cell` renderer. */
-export type InlineCellContext = {
-  /** Full RHF path, e.g. `__inline_invoice_lines.0.label`. */
-  name: string;
-  index: number;
-  arrayName: string;
-};
-
-export type InlineColumnDef = {
-  source: string;
-  label?: string;
-  width?: number | string;
-  minWidth?: number | string;
-  cell: (ctx: InlineCellContext) => ReactNode;
-};
-
-/** Passed to `InlineFormSetStacked`'s `renderRow` for one related row. */
-export type InlineRowContext = {
-  arrayName: string;
-  index: number;
-  /** RHF path helper — `name("label")` → `arrayName.index.label`. */
-  name: (source: string) => string;
-};
-
-export type EditMode = "page" | "modal" | "both";
-
-/** Toggle built-in row actions. Omitted keys default to `true` (still gated by permissions). */
-export type ResourceListBuiltInActions = {
-  edit?: boolean;
-  quickEdit?: boolean;
-  delete?: boolean;
-};
-
-export type ResourceListRowActionsHelpers = {
-  reload: () => void;
-  openEditModal: (id: string | number) => void;
-};
-
-export type ResourceListBulkActionHelpers = {
-  reload: () => void;
-  clearSelection: () => void;
-};
-
-/** Bulk list action (Django admin–style). Runs on selected row ids. */
-export type ResourceListBulkAction = {
-  key: string;
-  label: string;
-  /** Optional confirmation message. Return false to cancel. */
-  confirm?:
-    | string
-    | ((
-        selectedIds: (string | number)[],
-        helpers: ResourceListBulkActionHelpers,
-      ) => string | false | Promise<string | false>);
-  execute: (
-    selectedIds: (string | number)[],
-    helpers: ResourceListBulkActionHelpers,
-  ) => void | Promise<void>;
-};
-
-export const LIST_QUERY_RESERVED = new Set([
-  "page",
-  "perPage",
-  "sort",
-  "create",
-  "edit",
-]);
+import type { ReactNode } from "react";
+import type { ColumnsType } from "antd/es/table";
+import type { DataProvider } from "../data/dataProviderTypes";
+import type { RegisterOptions } from "react-hook-form";
+
+export type BaseSourceProps = {
+  source: string;
+  label?: string;
+};
+
+export type ChoiceOption = {
+  label: string;
+  value: unknown;
+  /** Full record when loaded from a reference resource (for dependent fields). */
+  record?: Record<string, unknown>;
+};
+
+export type ChoicesContext = {
+  dataProvider: DataProvider;
+  search?: string;
+};
+
+export type ChoicesLoader =
+  | { resource: string; filter?: Record<string, unknown> }
+  | ChoiceOption[]
+  | ((ctx: ChoicesContext) => Promise<ChoiceOption[]>);
+
+export type ReferenceProps = {
+  reference?: string;
+  choices?: ChoicesLoader;
+  optionLabel?: string | ((record: Record<string, unknown>) => string);
+  optionValue?: string;
+  /** When true (default), options load on dropdown open / search instead of on mount. */
+  lazy?: boolean;
+  /**
+   * Key on the loaded form record with the related object or array of objects.
+   * Use when retrieve embeds relations, e.g. `source="branch_id"` + `recordSource="branch"`.
+   */
+  recordSource?: string;
+  /**
+   * When true (default), fetch labels for primitive ids via `getOne` if they are not
+   * already embedded in the form record. Set `false` to never call `getOne`.
+   */
+  fetchSelected?: boolean;
+};
+
+export type DisplayProps = {
+  display?: string | ((record: Record<string, unknown>) => ReactNode);
+};
+
+export type FieldRules = RegisterOptions;
+
+export type ColumnDefinition<T extends Record<string, unknown>> = {
+  key: string;
+  source: string;
+  label?: string;
+  sortable?: boolean;
+  buildColumn: () => ColumnsType<T>[number];
+};
+
+export type FilterDefinition = {
+  key: string;
+  source: string;
+  label?: string;
+  render: (props: {
+    value: unknown;
+    onChange: (value: unknown) => void;
+  }) => ReactNode;
+};
+
+export type InlineFormSetBaseProps = {
+  /** RHF `useFieldArray` name and default API nested key, e.g. `"lines"`. */
+  field: string;
+  label?: 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. `lines.0.label`. */
+  name: string;
+  index: number;
+  field: string;
+};
+
+export type InlineColumnDef = {
+  source: string;
+  label?: string;
+  width?: number | string;
+  minWidth?: number | string;
+  cell: (ctx: InlineCellContext) => ReactNode;
+};
+
+/** Passed to `InlineFormSetStacked`'s `renderRow` for one related row. */
+export type InlineRowContext = {
+  field: string;
+  index: number;
+  /** RHF path helper — `name("label")` → `field.index.label`. */
+  name: (source: string) => string;
+};
+
+export type EditMode = "page" | "modal" | "both";
+
+/** Toggle built-in row actions. Omitted keys default to `true` (still gated by permissions). */
+export type ResourceListBuiltInActions = {
+  edit?: boolean;
+  quickEdit?: boolean;
+  delete?: boolean;
+};
+
+export type ResourceListRowActionsHelpers = {
+  reload: () => void;
+  openEditModal: (id: string | number) => void;
+};
+
+export type ResourceListBulkActionHelpers = {
+  reload: () => void;
+  clearSelection: () => void;
+};
+
+/** Bulk list action (Django admin–style). Runs on selected row ids. */
+export type ResourceListBulkAction = {
+  key: string;
+  label: string;
+  /** Optional confirmation message. Return false to cancel. */
+  confirm?:
+    | string
+    | ((
+        selectedIds: (string | number)[],
+        helpers: ResourceListBulkActionHelpers,
+      ) => string | false | Promise<string | false>);
+  execute: (
+    selectedIds: (string | number)[],
+    helpers: ResourceListBulkActionHelpers,
+  ) => void | Promise<void>;
+};
+
+export const LIST_QUERY_RESERVED = new Set([
+  "page",
+  "perPage",
+  "sort",
+  "create",
+  "edit",
+]);

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

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import {
+  collectSelectedRecords,
+  isRecordObject,
+  normalizeSelectedIds,
+  recordsToOptions,
+  valueAsId,
+  valuesAsIds,
+} from "./choiceSelectionUtils";
+
+describe("choiceSelectionUtils", () => {
+  it("detects nested record objects", () => {
+    expect(isRecordObject({ id: 1, name: "Branch 1" }, "id")).toBe(true);
+    expect(isRecordObject("1", "id")).toBe(false);
+  });
+
+  it("extracts ids from primitive or nested values", () => {
+    expect(valueAsId("abc", "id")).toBe("abc");
+    expect(valueAsId({ id: 2, name: "Two" }, "id")).toBe(2);
+    expect(valuesAsIds([{ id: 1, name: "One" }, "2"], "id")).toEqual([1, "2"]);
+    expect(normalizeSelectedIds([{ id: 3, name: "Three" }], "id")).toEqual([3]);
+  });
+
+  it("collects embedded records from value and recordSource data", () => {
+    const records = collectSelectedRecords(
+      [{ id: 1, name: "One" }, "2"],
+      { id: 3, name: "Three" },
+      "id",
+    );
+    expect(records).toHaveLength(2);
+    expect(records.map((record) => record.id).sort()).toEqual([1, 3]);
+  });
+
+  it("maps records to select options", () => {
+    expect(
+      recordsToOptions([{ id: 1, name: "Branch 1" }], "name", "id"),
+    ).toEqual([
+      {
+        label: "Branch 1",
+        value: 1,
+        record: { id: 1, name: "Branch 1" },
+      },
+    ]);
+  });
+});