ding-react-admin 1.0.0

package/src/crud/filters/BooleanFilter.tsx

@@ -0,0 +1,38 @@
+import { Select } from "antd";
+import { useMemo } from "react";
+import type { BaseSourceProps } from "../types";
+import { useRegisterFilter } from "../context/FilterContext";
+
+export type BooleanFilterProps = BaseSourceProps;
+
+export function BooleanFilter({ source, label }: BooleanFilterProps) {
+  const def = useMemo(
+    () => ({
+      key: source,
+      source,
+      label,
+      render: ({
+        value,
+        onChange,
+      }: {
+        value: unknown;
+        onChange: (value: unknown) => void;
+      }) => (
+        <Select
+          allowClear
+          placeholder={label ?? source}
+          value={value as boolean | undefined}
+          onChange={(v) => onChange(v)}
+          options={[
+            { label: "Yes", value: true },
+            { label: "No", value: false },
+          ]}
+          style={{ minWidth: 100 }}
+        />
+      ),
+    }),
+    [source, label],
+  );
+  useRegisterFilter(def);
+  return null;
+}

package/src/crud/filters/DateFilter.tsx

@@ -0,0 +1,35 @@
+import { DatePicker } from "antd";
+import dayjs from "dayjs";
+import { useMemo } from "react";
+import type { BaseSourceProps } from "../types";
+import { useRegisterFilter } from "../context/FilterContext";
+
+export type DateFilterProps = BaseSourceProps;
+
+export function DateFilter({ source, label }: DateFilterProps) {
+  const def = useMemo(
+    () => ({
+      key: source,
+      source,
+      label,
+      render: ({
+        value,
+        onChange,
+      }: {
+        value: unknown;
+        onChange: (value: unknown) => void;
+      }) => (
+        <DatePicker
+          allowClear
+          placeholder={label ?? source}
+          value={value ? dayjs(String(value)) : null}
+          onChange={(d) => onChange(d ? d.format("YYYY-MM-DD") : undefined)}
+          style={{ minWidth: 160 }}
+        />
+      ),
+    }),
+    [source, label],
+  );
+  useRegisterFilter(def);
+  return null;
+}

package/src/crud/filters/NumberFilter.tsx

@@ -0,0 +1,33 @@
+import { InputNumber } from "antd";
+import { useMemo } from "react";
+import type { BaseSourceProps } from "../types";
+import { useRegisterFilter } from "../context/FilterContext";
+
+export type NumberFilterProps = BaseSourceProps;
+
+export function NumberFilter({ source, label }: NumberFilterProps) {
+  const def = useMemo(
+    () => ({
+      key: source,
+      source,
+      label,
+      render: ({
+        value,
+        onChange,
+      }: {
+        value: unknown;
+        onChange: (value: unknown) => void;
+      }) => (
+        <InputNumber
+          placeholder={label ?? source}
+          value={value as number | undefined}
+          onChange={(v) => onChange(v ?? undefined)}
+          style={{ minWidth: 120 }}
+        />
+      ),
+    }),
+    [source, label],
+  );
+  useRegisterFilter(def);
+  return null;
+}

package/src/crud/filters/ReferenceFilter.tsx

@@ -0,0 +1,173 @@
+import { Select } from "antd";
+import { useMemo, useState } from "react";
+import type { BaseSourceProps, ChoiceOption, ReferenceProps } from "../types";
+import { useRegisterFilter } from "../context/FilterContext";
+import { useChoices } from "../utils/useChoices";
+
+export type SelectFilterProps = BaseSourceProps & {
+  choices: ChoiceOption[];
+  multiple?: boolean;
+};
+
+function SelectFilterInput({
+  source,
+  label,
+  choices,
+  multiple,
+  value,
+  onChange,
+}: SelectFilterProps & {
+  value: unknown;
+  onChange: (value: unknown) => void;
+}) {
+  return (
+    <Select
+      allowClear
+      mode={multiple ? "multiple" : undefined}
+      placeholder={label ?? source}
+      value={value as string | number | (string | number)[] | undefined}
+      onChange={onChange}
+      options={choices}
+      style={{ minWidth: 160 }}
+    />
+  );
+}
+
+export function SelectFilter({
+  source,
+  label,
+  choices,
+  multiple,
+}: SelectFilterProps) {
+  const def = useMemo(
+    () => ({
+      key: source,
+      source,
+      label,
+      render: ({
+        value,
+        onChange,
+      }: {
+        value: unknown;
+        onChange: (value: unknown) => void;
+      }) => (
+        <SelectFilterInput
+          source={source}
+          label={label}
+          choices={choices}
+          multiple={multiple}
+          value={value}
+          onChange={onChange}
+        />
+      ),
+    }),
+    [source, label, choices, multiple],
+  );
+  useRegisterFilter(def);
+  return null;
+}
+
+export type ReferenceFilterProps = BaseSourceProps &
+  ReferenceProps & {
+    multiple?: boolean;
+    search?: boolean;
+  };
+
+function ReferenceFilterInput({
+  source,
+  label,
+  reference,
+  choices,
+  optionLabel,
+  optionValue,
+  multiple,
+  search,
+  value,
+  onChange,
+}: ReferenceFilterProps & {
+  value: unknown;
+  onChange: (value: unknown) => void;
+}) {
+  const [searchText, setSearchText] = useState<string | undefined>();
+  const { options, loading } = useChoices(
+    choices,
+    reference,
+    optionLabel,
+    optionValue,
+    search ? searchText : undefined,
+  );
+  return (
+    <Select
+      allowClear
+      mode={multiple ? "multiple" : undefined}
+      placeholder={label ?? source}
+      value={value as string | number | (string | number)[] | undefined}
+      onChange={onChange}
+      options={options.map((o) => ({
+        label: o.label,
+        value: o.value as string | number,
+      }))}
+      loading={loading}
+      showSearch={search}
+      filterOption={search ? false : undefined}
+      onSearch={search ? setSearchText : undefined}
+      optionFilterProp="label"
+      style={{ minWidth: 180 }}
+    />
+  );
+}
+
+export function ReferenceFilter({
+  source,
+  label,
+  reference,
+  choices,
+  optionLabel = "name",
+  optionValue = "id",
+  multiple,
+  search,
+}: ReferenceFilterProps) {
+  const def = useMemo(
+    () => ({
+      key: source,
+      source,
+      label,
+      render: ({
+        value,
+        onChange,
+      }: {
+        value: unknown;
+        onChange: (value: unknown) => void;
+      }) => (
+        <ReferenceFilterInput
+          source={source}
+          label={label}
+          reference={reference}
+          choices={choices}
+          optionLabel={optionLabel}
+          optionValue={optionValue}
+          multiple={multiple}
+          search={search}
+          value={value}
+          onChange={onChange}
+        />
+      ),
+    }),
+    [
+      source,
+      label,
+      reference,
+      choices,
+      optionLabel,
+      optionValue,
+      multiple,
+      search,
+    ],
+  );
+  useRegisterFilter(def);
+  return null;
+}
+
+export function ReferenceManyFilter(props: ReferenceFilterProps) {
+  return <ReferenceFilter {...props} multiple />;
+}

package/src/crud/filters/SelectFilter.tsx

@@ -0,0 +1,44 @@
+import { Select } from "antd";
+import { useMemo } from "react";
+import type { BaseSourceProps, ChoiceOption } from "../types";
+import { useRegisterFilter } from "../context/FilterContext";
+
+export type SelectFilterProps = BaseSourceProps & {
+  choices: ChoiceOption[];
+  multiple?: boolean;
+};
+
+export function SelectFilter({
+  source,
+  label,
+  choices,
+  multiple,
+}: SelectFilterProps) {
+  const def = useMemo(
+    () => ({
+      key: source,
+      source,
+      label,
+      render: ({
+        value,
+        onChange,
+      }: {
+        value: unknown;
+        onChange: (value: unknown) => void;
+      }) => (
+        <Select
+          allowClear
+          mode={multiple ? "multiple" : undefined}
+          placeholder={label ?? source}
+          value={value as string | number | (string | number)[] | undefined}
+          onChange={onChange}
+          options={choices}
+          style={{ minWidth: 160 }}
+        />
+      ),
+    }),
+    [source, label, choices, multiple],
+  );
+  useRegisterFilter(def);
+  return null;
+}

package/src/crud/filters/TextFilter.tsx

@@ -0,0 +1,36 @@
+import { Input } from "antd";
+import { useMemo } from "react";
+import type { BaseSourceProps } from "../types";
+import { useRegisterFilter } from "../context/FilterContext";
+
+export type TextFilterProps = BaseSourceProps & {
+  placeholder?: string;
+};
+
+export function TextFilter({ source, label, placeholder }: TextFilterProps) {
+  const def = useMemo(
+    () => ({
+      key: source,
+      source,
+      label,
+      render: ({
+        value,
+        onChange,
+      }: {
+        value: unknown;
+        onChange: (value: unknown) => void;
+      }) => (
+        <Input
+          allowClear
+          placeholder={placeholder ?? label ?? source}
+          value={(value as string) ?? ""}
+          onChange={(e) => onChange(e.target.value || undefined)}
+          style={{ minWidth: 160 }}
+        />
+      ),
+    }),
+    [source, label, placeholder],
+  );
+  useRegisterFilter(def);
+  return null;
+}

package/src/crud/index.ts

@@ -0,0 +1,73 @@
+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,
+  saveInlineRows,
+  loadInlineRows,
+} from "./InlineFormSet";
+export type { InlineFormSetProps, 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 { 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 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 { setByPath } from "./utils/setByPath";
+export { useRegisterFormSource } from "./context/FormFieldsContext";
+
+export type {
+  BaseSourceProps,
+  ChoiceOption,
+  ChoicesLoader,
+  ReferenceProps,
+  DisplayProps,
+  EditMode,
+  FieldRules,
+  ResourceListBuiltInActions,
+  ResourceListBulkAction,
+  ResourceListBulkActionHelpers,
+  ResourceListRowActionsHelpers,
+} from "./types";

package/src/crud/types.ts

@@ -0,0 +1,130 @@
+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 InlineFieldDefinition = {
+  key: string;
+  source: string;
+  label?: string;
+  /** Column width in tabular inline tables (Ant Design Table `width`). */
+  width?: number | string;
+  /** Minimum column width in tabular inline tables. */
+  minWidth?: number | string;
+  render: (props: {
+    name: string;
+    index: number;
+  }) => ReactNode;
+};
+
+export type InlineFieldOptions = {
+  width?: number | string;
+  minWidth?: number | string;
+};
+
+export type FieldRenderProps = {
+  value: unknown;
+  onChange: (value: unknown) => void;
+  onBlur: () => void;
+  disabled?: boolean;
+  /** Set when rendered inside `InlineFormSet`. */
+  name?: string;
+  index?: number;
+};
+
+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/formErrors.ts

@@ -0,0 +1,38 @@
+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;
+}

package/src/crud/utils/formSectionErrors.ts

@@ -0,0 +1,85 @@
+import { useEffect, useRef, type MutableRefObject } from "react";
+import {
+  useFormContext,
+  useFormState,
+  type FieldPath,
+  type FieldValues,
+  type FormState,
+  type UseFormGetFieldState,
+} from "react-hook-form";
+
+export function sectionHasError<T extends FieldValues>(
+  sources: Set<string>,
+  getFieldState: UseFormGetFieldState<T>,
+  formState: FormState<T>,
+): boolean {
+  for (const source of sources) {
+    if (getFieldState(source as FieldPath<T>, formState).invalid) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function useSectionSourceRefs(count: number) {
+  const refs = useRef<MutableRefObject<Set<string>>[]>([]);
+
+  while (refs.current.length < count) {
+    refs.current.push({ current: new Set() });
+  }
+  if (refs.current.length > count) {
+    refs.current.length = count;
+  }
+
+  return refs.current;
+}
+
+export function useActivateFirstErrorSection(
+  sectionRefs: MutableRefObject<Set<string>>[],
+  activate: (index: number) => void,
+) {
+  const { control, getFieldState, setFocus } = useFormContext<FieldValues>();
+  const formState = useFormState({ control });
+  const prevSubmitCount = useRef(0);
+  const prevErrorCount = useRef(0);
+
+  useEffect(() => {
+    if (formState.submitCount === 0) return;
+
+    const errorCount = Object.keys(formState.errors).length;
+    const submitChanged = formState.submitCount !== prevSubmitCount.current;
+    const serverErrorsArrived =
+      !submitChanged && errorCount > 0 && prevErrorCount.current === 0;
+
+    prevSubmitCount.current = formState.submitCount;
+    prevErrorCount.current = errorCount;
+
+    if ((!submitChanged && !serverErrorsArrived) || errorCount === 0) {
+      return;
+    }
+
+    const first = sectionRefs.findIndex((ref) =>
+      sectionHasError(ref.current, getFieldState, formState),
+    );
+    if (first < 0) return;
+
+    activate(first);
+
+    const firstInvalid = [...sectionRefs[first].current].find((source) =>
+      getFieldState(source as FieldPath<FieldValues>, formState).invalid,
+    );
+    if (firstInvalid) {
+      requestAnimationFrame(() => {
+        void setFocus(firstInvalid as FieldPath<FieldValues>);
+      });
+    }
+  }, [
+    activate,
+    formState,
+    formState.errors,
+    formState.submitCount,
+    getFieldState,
+    sectionRefs,
+    setFocus,
+  ]);
+}

package/src/crud/utils/getByPath.ts

@@ -0,0 +1,13 @@
+/** Read nested value from a record using dot notation, e.g. `brand.name`. */
+export function getByPath(
+  record: Record<string, unknown>,
+  path: string,
+): unknown {
+  const parts = path.split(".");
+  let cur: unknown = record;
+  for (const part of parts) {
+    if (cur == null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  return cur;
+}