ding-react-admin 1.0.0

package/src/crud/utils/inlineArrayName.ts

@@ -0,0 +1,4 @@
+/** Shared field-array name for InlineFormSet + ResourceForm inline loading. */
+export function inlineArrayName(resource: string, name?: string) {
+  return name ?? `__inline_${resource.replace(/[^a-z0-9]/gi, "_")}`;
+}

package/src/crud/utils/pickBySources.ts

@@ -0,0 +1,24 @@
+import { getByPath } from "./getByPath";
+import { setByPath } from "./setByPath";
+
+/**
+ * Build a submit payload from form values using declared field `source` paths.
+ * Flat `username` → `{ username }`; nested `invoiceLine.product` → `{ invoiceLine: { product } }`.
+ */
+export function pickBySources(
+  values: Record<string, unknown>,
+  sources: string[],
+): Record<string, unknown> {
+  if (sources.length === 0) {
+    return { ...values };
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const source of sources) {
+    const value = getByPath(values, source);
+    if (value !== undefined) {
+      setByPath(result, source, value);
+    }
+  }
+  return result;
+}

package/src/crud/utils/setByPath.ts

@@ -0,0 +1,18 @@
+/** Write a value into a record using dot notation, e.g. `invoiceLine.product`. */
+export function setByPath(
+  record: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const parts = path.split(".");
+  let cur: Record<string, unknown> = record;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    const next = cur[part];
+    if (next == null || typeof next !== "object" || Array.isArray(next)) {
+      cur[part] = {};
+    }
+    cur = cur[part] as Record<string, unknown>;
+  }
+  cur[parts[parts.length - 1]!] = value;
+}

package/src/crud/utils/sortQueryParam.ts

@@ -0,0 +1,37 @@
+import type { SortOrder, SortSpec } from "../../data/dataProviderTypes";
+
+/** Parse `sort` query (Django-style: `sku,-price`; legacy: `sku:asc,price:desc`). */
+export function parseSortParam(raw: string | null): SortSpec[] {
+  if (!raw) return [];
+  const specs: SortSpec[] = [];
+  for (const part of raw.split(",").map((p) => p.trim()).filter(Boolean)) {
+    if (part.includes(":")) {
+      const [field, orderRaw] = part.split(":");
+      if (!field) continue;
+      const order: SortOrder =
+        orderRaw?.toLowerCase() === "desc" ? "DESC" : "ASC";
+      specs.push({ field, order });
+      continue;
+    }
+    if (part.startsWith("-") && part.length > 1) {
+      specs.push({ field: part.slice(1), order: "DESC" });
+    } else {
+      specs.push({ field: part, order: "ASC" });
+    }
+  }
+  return specs;
+}
+
+/** Serialize sort specs to Django-style `sku,-price`. */
+export function serializeSort(specs: SortSpec[]): string | null {
+  if (specs.length === 0) return null;
+  return specs
+    .map((s) => (s.order === "DESC" ? `-${s.field}` : s.field))
+    .join(",");
+}
+
+export function sortPrioritiesFromSpecs(
+  specs: SortSpec[],
+): Map<string, number> {
+  return new Map(specs.map((s, i) => [s.field, i + 1]));
+}

package/src/crud/utils/useChoices.ts

@@ -0,0 +1,182 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useDataProvider } from "../../context/DataProvider";
+import type { ChoiceOption, ChoicesLoader } from "../types";
+
+const choicesCache = new Map<string, ChoiceOption[]>();
+const choicesInflight = new Map<string, Promise<ChoiceOption[]>>();
+
+function loaderKey(loader: ChoicesLoader, search?: string): string {
+  if (typeof loader === "function") return `fn:${search ?? ""}`;
+  if (Array.isArray(loader)) return `static:${loader.length}`;
+  return `res:${loader.resource}:${JSON.stringify(loader.filter ?? {})}:${search ?? ""}`;
+}
+
+function resolveOptionLabel(
+  record: Record<string, unknown>,
+  optionLabel: string | ((record: Record<string, unknown>) => string),
+): string {
+  if (typeof optionLabel === "function") return optionLabel(record);
+  return String(record[optionLabel] ?? "");
+}
+
+async function fetchChoices(
+  effectiveLoader: ChoicesLoader,
+  dp: ReturnType<typeof useDataProvider>,
+  optionLabel: string | ((record: Record<string, unknown>) => string),
+  optionValue: string,
+  search?: string,
+): Promise<ChoiceOption[]> {
+  if (typeof effectiveLoader === "function") {
+    return effectiveLoader({ dataProvider: dp, search });
+  }
+  if (Array.isArray(effectiveLoader)) {
+    return effectiveLoader;
+  }
+  const res = await dp.getList(effectiveLoader.resource, {
+    filter: {
+      ...effectiveLoader.filter,
+      ...(search ? { q: search } : {}),
+    },
+    pagination: { page: 1, perPage: 500 },
+  });
+  return (res.data as Record<string, unknown>[]).map((row) => ({
+    label: resolveOptionLabel(row, optionLabel),
+    value: row[optionValue],
+    record: row,
+  }));
+}
+
+function loadChoicesShared(
+  effectiveLoader: ChoicesLoader,
+  dp: ReturnType<typeof useDataProvider>,
+  optionLabel: string | ((record: Record<string, unknown>) => string),
+  optionValue: string,
+  search?: string,
+): Promise<ChoiceOption[]> {
+  const key = loaderKey(effectiveLoader, search);
+  const cached = choicesCache.get(key);
+  if (cached && !search) {
+    return Promise.resolve(cached);
+  }
+
+  const inflight = choicesInflight.get(key);
+  if (inflight) return inflight;
+
+  const promise = fetchChoices(
+    effectiveLoader,
+    dp,
+    optionLabel,
+    optionValue,
+    search,
+  )
+    .then((result) => {
+      if (!search) choicesCache.set(key, result);
+      return result;
+    })
+    .finally(() => {
+      choicesInflight.delete(key);
+    });
+
+  choicesInflight.set(key, promise);
+  return promise;
+}
+
+export function useChoices(
+  loader: ChoicesLoader | undefined,
+  reference: string | undefined,
+  optionLabel: string | ((record: Record<string, unknown>) => string) = "name",
+  optionValue = "id",
+  search?: string,
+) {
+  const dp = useDataProvider();
+
+  const effectiveLoader = useMemo((): ChoicesLoader | undefined => {
+    if (loader) return loader;
+    if (!reference) return undefined;
+    return {
+      resource: reference,
+      filter: search ? { q: search } : undefined,
+    };
+  }, [loader, reference, search]);
+
+  const cacheKey = effectiveLoader
+    ? loaderKey(effectiveLoader, search)
+    : undefined;
+
+  const [options, setOptions] = useState<ChoiceOption[]>(() => {
+    if (!cacheKey || search) return [];
+    return choicesCache.get(cacheKey) ?? [];
+  });
+
+  const [loading, setLoading] = useState(() => {
+    if (!cacheKey || search) return Boolean(effectiveLoader);
+    return !choicesCache.has(cacheKey);
+  });
+
+  const load = useCallback(async () => {
+    if (!effectiveLoader) {
+      setOptions([]);
+      setLoading(false);
+      return;
+    }
+
+    const key = loaderKey(effectiveLoader, search);
+    const cached = choicesCache.get(key);
+    if (cached && !search) {
+      setOptions(cached);
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    try {
+      const result = await loadChoicesShared(
+        effectiveLoader,
+        dp,
+        optionLabel,
+        optionValue,
+        search,
+      );
+      setOptions(result);
+    } catch {
+      setOptions([]);
+    } finally {
+      setLoading(false);
+    }
+  }, [effectiveLoader, dp, optionLabel, optionValue, search]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const labelForValue = useCallback(
+    (value: unknown): string => {
+      const opt = options.find((o) => o.value === value);
+      return opt?.label ?? String(value ?? "—");
+    },
+    [options],
+  );
+
+  const labelsForValues = useCallback(
+    (values: unknown[]): string => {
+      if (!values?.length) return "—";
+      return values.map((v) => labelForValue(v)).join(", ");
+    },
+    [labelForValue],
+  );
+
+  const optionForValue = useCallback(
+    (value: unknown): ChoiceOption | undefined =>
+      options.find((o) => o.value === value),
+    [options],
+  );
+
+  return {
+    options,
+    loading,
+    labelForValue,
+    labelsForValues,
+    optionForValue,
+    reload: load,
+  };
+}

package/src/crud/utils/useListQueryState.ts

@@ -0,0 +1,191 @@
+import { useCallback, useMemo } from "react";
+import { useSearchParams } from "react-router-dom";
+import type { SortSpec } from "../../data/dataProviderTypes";
+import { LIST_QUERY_RESERVED } from "../types";
+import { parseSortParam, serializeSort } from "./sortQueryParam";
+
+const DEFAULT_PAGE = 1;
+const DEFAULT_PER_PAGE = 10;
+
+function parseFilterValue(raw: string): unknown {
+  if (raw.includes(",")) {
+    const parts = raw.split(",").map((p) => p.trim());
+    const nums = parts.map(Number);
+    if (nums.every((n) => Number.isFinite(n))) return nums;
+    return parts;
+  }
+  const n = Number(raw);
+  if (raw !== "" && Number.isFinite(n) && String(n) === raw) return n;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  return raw;
+}
+
+function serializeFilterValue(value: unknown): string | null {
+  if (value === undefined || value === null || value === "") return null;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return null;
+    return value.map(String).join(",");
+  }
+  return String(value);
+}
+
+export type ListQueryState = {
+  page: number;
+  perPage: number;
+  sort: SortSpec[];
+  filter: Record<string, unknown>;
+  createModal: boolean;
+  editId: string | null;
+};
+
+export type ListQueryActions = {
+  setPage: (page: number) => void;
+  setPerPage: (perPage: number) => void;
+  setSort: (sort: SortSpec[]) => void;
+  toggleSort: (field: string) => void;
+  setFilter: (source: string, value: unknown) => void;
+  setFilters: (filter: Record<string, unknown>) => void;
+  openCreateModal: () => void;
+  openEditModal: (id: string | number) => void;
+  closeModal: () => void;
+};
+
+export function useListQueryState(
+  staticFilter?: Record<string, unknown>,
+): [ListQueryState, ListQueryActions] {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const state = useMemo((): ListQueryState => {
+    const pageRaw = searchParams.get("page");
+    const perPageRaw = searchParams.get("perPage");
+    const page = pageRaw ? Math.max(1, Number(pageRaw) || DEFAULT_PAGE) : DEFAULT_PAGE;
+    const perPage = perPageRaw
+      ? Math.max(1, Number(perPageRaw) || DEFAULT_PER_PAGE)
+      : DEFAULT_PER_PAGE;
+
+    const sortEntries = searchParams.getAll("sort");
+    const sort =
+      sortEntries.length > 0
+        ? sortEntries.flatMap((s) => parseSortParam(s))
+        : parseSortParam(searchParams.get("sort"));
+
+    const filter: Record<string, unknown> = { ...staticFilter };
+    searchParams.forEach((value, key) => {
+      if (LIST_QUERY_RESERVED.has(key)) return;
+      const existing = filter[key];
+      if (existing !== undefined) {
+        const arr = Array.isArray(existing) ? existing : [existing];
+        filter[key] = [...arr, parseFilterValue(value)];
+      } else if (searchParams.getAll(key).length > 1) {
+        filter[key] = searchParams.getAll(key).map(parseFilterValue);
+      } else {
+        filter[key] = parseFilterValue(value);
+      }
+    });
+
+    const createModal = searchParams.has("create");
+    const editId = searchParams.get("edit");
+
+    return { page, perPage, sort, filter, createModal, editId };
+  }, [searchParams, staticFilter]);
+
+  const updateParams = useCallback(
+    (mutate: (params: URLSearchParams) => void) => {
+      setSearchParams(
+        (prev) => {
+          const next = new URLSearchParams(prev);
+          mutate(next);
+          return next;
+        },
+        { replace: true },
+      );
+    },
+    [setSearchParams],
+  );
+
+  const actions: ListQueryActions = useMemo(
+    () => ({
+      setPage: (page) => {
+        updateParams((p) => {
+          if (page <= 1) p.delete("page");
+          else p.set("page", String(page));
+        });
+      },
+      setPerPage: (perPage) => {
+        updateParams((p) => {
+          if (perPage === DEFAULT_PER_PAGE) p.delete("perPage");
+          else p.set("perPage", String(perPage));
+          p.delete("page");
+        });
+      },
+      setSort: (sort) => {
+        updateParams((p) => {
+          p.delete("sort");
+          const serialized = serializeSort(sort);
+          if (serialized) p.set("sort", serialized);
+        });
+      },
+      toggleSort: (field) => {
+        updateParams((p) => {
+          const current = p.getAll("sort").flatMap((s) => parseSortParam(s));
+          const idx = current.findIndex((s) => s.field === field);
+          let next: SortSpec[];
+          if (idx < 0) {
+            next = [...current, { field, order: "ASC" }];
+          } else if (current[idx].order === "ASC") {
+            next = current.map((s, i) =>
+              i === idx ? { ...s, order: "DESC" as const } : s,
+            );
+          } else {
+            next = current.filter((_, i) => i !== idx);
+          }
+          p.delete("sort");
+          const serialized = serializeSort(next);
+          if (serialized) p.set("sort", serialized);
+        });
+      },
+      setFilter: (source, value) => {
+        updateParams((p) => {
+          p.delete(source);
+          const serialized = serializeFilterValue(value);
+          if (serialized != null) p.set(source, serialized);
+          p.delete("page");
+        });
+      },
+      setFilters: (filter) => {
+        updateParams((p) => {
+          for (const key of [...p.keys()]) {
+            if (!LIST_QUERY_RESERVED.has(key)) p.delete(key);
+          }
+          for (const [key, value] of Object.entries(filter)) {
+            const serialized = serializeFilterValue(value);
+            if (serialized != null) p.set(key, serialized);
+          }
+          p.delete("page");
+        });
+      },
+      openCreateModal: () => {
+        updateParams((p) => {
+          p.set("create", "1");
+          p.delete("edit");
+        });
+      },
+      openEditModal: (id) => {
+        updateParams((p) => {
+          p.set("edit", String(id));
+          p.delete("create");
+        });
+      },
+      closeModal: () => {
+        updateParams((p) => {
+          p.delete("create");
+          p.delete("edit");
+        });
+      },
+    }),
+    [updateParams],
+  );
+
+  return [state, actions];
+}

package/src/data/createMemoryResourceHandlers.ts

@@ -0,0 +1,78 @@
+import { applyInMemoryListParams, getById, rowIdMatches } from "./inMemoryList";
+import type {
+  CreateResult,
+  DeleteResult,
+  GetListParams,
+  GetListResult,
+  GetOneResult,
+  UpdateResult,
+} from "./dataProviderTypes";
+import type { ResourceHandlers } from "./resourceHandlers";
+
+type Row = Record<string, unknown>;
+
+export type MemoryResourceHandlersConfig<
+  T extends Record<string, unknown> & { id: string | number },
+> = {
+  getRows: () => T[];
+  nextId: () => string | number;
+  /** Defaults to `{ ...data, id }` from form field sources. */
+  mapCreate?: (data: Row, id: string | number) => T;
+  /** Defaults to spread patch over current row. */
+  applyUpdate?: (current: T, patch: Row) => T;
+  scopeList?: (rows: T[], params: GetListParams) => T[];
+  afterDelete?: (removed: T) => void;
+};
+
+/**
+ * Generic in-memory CRUD for demos and tests. Override hooks for entity-specific rules.
+ */
+export function createMemoryResourceHandlers<
+  T extends Record<string, unknown> & { id: string | number },
+>(config: MemoryResourceHandlersConfig<T>): ResourceHandlers<T> {
+  const asRows = (xs: T[]) => xs as unknown as Row[];
+
+  const mapCreate =
+    config.mapCreate ??
+    ((data: Row, id: string | number) => ({ ...data, id }) as T);
+
+  const applyUpdate =
+    config.applyUpdate ??
+    ((current: T, patch: Row) => ({ ...current, ...patch, id: current.id }) as T);
+
+  return {
+    async getList(params): Promise<GetListResult<T>> {
+      const base = config.scopeList
+        ? config.scopeList(config.getRows(), params)
+        : config.getRows();
+      return applyInMemoryListParams(asRows(base), params) as GetListResult<T>;
+    },
+
+    async getOne(id): Promise<GetOneResult<T>> {
+      return { data: getById(config.getRows(), id) as T };
+    },
+
+    async create(data): Promise<CreateResult<T>> {
+      const row = mapCreate(data as Row, config.nextId());
+      config.getRows().push(row);
+      return { data: row };
+    },
+
+    async update({ id, data }): Promise<UpdateResult<T>> {
+      const current = getById(config.getRows(), id);
+      const patch = data as Row;
+      const next = applyUpdate(current, patch);
+      Object.assign(current, next);
+      return { data: current };
+    },
+
+    async delete(id): Promise<DeleteResult<T>> {
+      const rows = config.getRows();
+      const idx = rows.findIndex((r) => rowIdMatches(r.id, id));
+      if (idx < 0) return { data: null };
+      const [removed] = rows.splice(idx, 1);
+      config.afterDelete?.(removed);
+      return { data: removed };
+    },
+  };
+}

package/src/data/createRestResourceHandlers.ts

@@ -0,0 +1,57 @@
+import type { GetListParams, Identifier } 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>;
+  destroy: (id: Identifier) => Promise<void>;
+  /** When API create body differs from form `source` paths. */
+  transformCreate?: (data: Record<string, unknown>) => unknown;
+  /** When API update body differs from form `source` paths. */
+  transformUpdate?: (data: Record<string, unknown>) => unknown;
+};
+
+/**
+ * Thin CRUD glue for REST backends. Form payload comes from field `source` paths;
+ * wire your fetch or API client in the five functions below.
+ */
+export function createRestResourceHandlers<
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(config: RestResourceHandlersConfig<T>): ResourceHandlers<T> {
+  return {
+    async getList(params) {
+      return config.list(params);
+    },
+
+    async getOne(id) {
+      return { data: await config.retrieve(id) };
+    },
+
+    async create(data) {
+      const body = config.transformCreate
+        ? config.transformCreate(data as Record<string, unknown>)
+        : data;
+      return {
+        data: await config.create(body as Record<string, unknown>),
+      };
+    },
+
+    async update({ id, data }) {
+      const body = config.transformUpdate
+        ? config.transformUpdate(data as Record<string, unknown>)
+        : data;
+      return {
+        data: await config.update(id, body as Record<string, unknown>),
+      };
+    },
+
+    async delete(id) {
+      await config.destroy(id);
+      return { data: null };
+    },
+  };
+}

package/src/data/dataProviderTypes.ts

@@ -0,0 +1,101 @@
+/** Resource primary key as accepted by `DataProvider` methods. */
+export type Identifier = string | number;
+
+export type SortOrder = "ASC" | "DESC";
+
+export type SortSpec = {
+  field: string;
+  order: SortOrder;
+};
+
+export type PaginationParams = {
+  page: number;
+  perPage: number;
+};
+
+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>;
+};
+
+export type GetListResult<RecordType extends Record<string, unknown>> = {
+  data: RecordType[];
+  total: number;
+};
+
+export type GetOneResult<RecordType extends Record<string, unknown>> = {
+  data: RecordType;
+};
+
+export type CreateResult<RecordType extends Record<string, unknown>> = {
+  data: RecordType;
+};
+
+export type UpdateParams<RecordType extends Record<string, unknown>> = {
+  id: Identifier;
+  data: Partial<RecordType>;
+};
+
+export type UpdateResult<RecordType extends Record<string, unknown>> = {
+  data: RecordType;
+};
+
+export type DeleteResult<RecordType extends Record<string, unknown>> = {
+  data: RecordType | null;
+};
+
+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;
+};
+
+/** Field paths match react-hook-form `name` (form `source` or inline `arrayName.index.source`). */
+export type FormValidationErrors = {
+  fields?: Record<string, string | string[]>;
+  /** Errors not tied to a single field (e.g. non_field_errors). */
+  global?: string | string[];
+};
+
+export type ParseFormError = (
+  error: unknown,
+  context: ParseFormErrorContext,
+) => FormValidationErrors | null | undefined;
+
+/**
+ * Small, framework-agnostic data layer (react-admin–style names).
+ * Implement with REST, GraphQL, or an in-memory mock.
+ */
+export type DataProvider<
+  RecordType extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  getList: (
+    resource: string,
+    params: GetListParams,
+  ) => Promise<GetListResult<RecordType>>;
+  getOne: (
+    resource: string,
+    id: Identifier,
+  ) => Promise<GetOneResult<RecordType>>;
+  create: (
+    resource: string,
+    data: Partial<RecordType>,
+  ) => Promise<CreateResult<RecordType>>;
+  update: (
+    resource: string,
+    params: UpdateParams<RecordType>,
+  ) => Promise<UpdateResult<RecordType>>;
+  delete: (
+    resource: string,
+    id: Identifier,
+  ) => Promise<DeleteResult<RecordType>>;
+  /** Map API validation errors to form field paths. Optional. */
+  parseFormError?: ParseFormError;
+};