rastack 0.0.43 → 0.0.45

package/admin/useAdmin.ts

@@ -0,0 +1,434 @@
+/**
+ * React hooks that bridge the WASM engine to the reusable `rastack/components`
+ * shapes. `useResourceTable` synthesizes a `TableQuery` for `<DataTable>` from
+ * `engine.handle('GET', …)`; `useResourceForm` synthesizes an `AutoFormLike` for
+ * `<AutoForm>` (loading FK options + the edited row, wiring create/update). No
+ * generated per-app hooks — everything is driven by the manifest at runtime, so
+ * one admin serves any app.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { RastackEngine } from "../provider/types";
+import type { AutoFormField, AutoFormLike, TableQuery } from "../components/types";
+import type {
+  IPaginationActions,
+  ISearchingActions,
+} from "../hooks/query/interfaces";
+import type { FieldOption } from "../hooks/form/interfaces";
+import {
+  AdminResource,
+  FilterKind,
+  FilterOption,
+  PAGE_SIZE,
+  boolFilterOptions,
+  buildWriteBody,
+  changelistHeaders,
+  detailPath,
+  distinctValueOptions,
+  errorDetail,
+  fieldControlType,
+  filterableFields,
+  fkFilterOptions,
+  formFields,
+  initialFormValues,
+  listPath,
+  optionsFromRows,
+  pageCount,
+  readListEnvelope,
+  withFilters,
+} from "./adapters";
+
+interface EngineResult {
+  status: number;
+  body: any;
+}
+const ok = (r: EngineResult) => r.status >= 200 && r.status < 300;
+
+/** What `useResourceTable` returns: a `TableQuery` plus changelist controls. */
+export interface ResourceTable {
+  query: TableQuery;
+  reload: () => void;
+  /** Active `field → value` equality filters (the filter-bar chips). */
+  filters: Record<string, string>;
+  setFilter: (field: string, value: string) => void;
+  removeFilter: (field: string) => void;
+  clearFilters: () => void;
+  /** Current search text and its setter (rendered in the filter bar). */
+  search: string | undefined;
+  setSearch: (value: string | undefined) => void;
+  itemCount: number;
+}
+
+/** Drive a `<DataTable>` for one resource, backed by any `RastackEngine`. */
+export function useResourceTable(
+  engine: RastackEngine,
+  resource: AdminResource,
+): ResourceTable {
+  const [page, setPage] = useState(1);
+  const [search, setSearchState] = useState<string | undefined>(undefined);
+  const [filters, setFilters] = useState<Record<string, string>>({});
+  const [data, setData] = useState<Record<string, unknown>[] | undefined>(
+    undefined,
+  );
+  const [count, setCount] = useState(0);
+  const [isLoading, setLoading] = useState(true);
+  const [error, setError] = useState<unknown>(undefined);
+  const [tick, setTick] = useState(0);
+
+  // Reset paging/search/filters when the resource changes.
+  useEffect(() => {
+    setPage(1);
+    setSearchState(undefined);
+    setFilters({});
+  }, [resource.key]);
+
+  const filterKey = JSON.stringify(filters);
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(undefined);
+    const reserved: Record<string, string> = {
+      page: String(page),
+      page_size: String(PAGE_SIZE),
+    };
+    if (search) reserved.search = search;
+    engine
+      .handle(
+        "GET",
+        listPath(resource.app, resource.model),
+        withFilters(reserved, filters),
+        undefined,
+      )
+      .then((res: EngineResult) => {
+        if (cancelled) return;
+        if (ok(res)) {
+          const env = readListEnvelope(res.body);
+          setData(env.results);
+          setCount(env.count);
+        } else {
+          setError(errorDetail(res.body));
+          setData([]);
+        }
+        setLoading(false);
+      })
+      .catch((e: unknown) => {
+        if (cancelled) return;
+        setError(e);
+        setData([]);
+        setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [engine, resource.key, resource.app, resource.model, page, search, filterKey, tick]);
+
+  const setSearch = (v: string | undefined) => {
+    setSearchState(v && v.length ? v : undefined);
+    setPage(1);
+  };
+  const setFilter = (field: string, value: string) => {
+    setFilters((f) => ({ ...f, [field]: value }));
+    setPage(1);
+  };
+  const removeFilter = (field: string) => {
+    setFilters((f) => {
+      const next = { ...f };
+      delete next[field];
+      return next;
+    });
+    setPage(1);
+  };
+  const clearFilters = () => {
+    setFilters({});
+    setPage(1);
+  };
+
+  const pagination: IPaginationActions = {
+    currentPage: page,
+    pageSize: PAGE_SIZE,
+    itemCount: count,
+    pageCount: pageCount(count, PAGE_SIZE),
+    nextPage: () =>
+      setPage((p) => Math.min(pageCount(count, PAGE_SIZE), p + 1)),
+    previousPage: () => setPage((p) => Math.max(1, p - 1)),
+    setPageSize: () => {
+      /* fixed page size, like the Rust admin */
+    },
+  };
+  const searching: ISearchingActions<Record<string, unknown>> = {
+    searchText: search,
+    setSearchText: (v) => setSearch(v),
+  };
+
+  const query: TableQuery = {
+    data,
+    isLoading,
+    isError: Boolean(error),
+    error,
+    header: changelistHeaders(resource),
+    pagination,
+    // No `sorting`: the store orders by id only, so sortable headers would lie.
+    searching: resource.search.length ? searching : undefined,
+  };
+  return {
+    query,
+    reload: () => setTick((t) => t + 1),
+    filters,
+    setFilter,
+    removeFilter,
+    clearFilters,
+    search,
+    setSearch,
+    itemCount: count,
+  };
+}
+
+/** A filter facet ready for the filter bar: its label, kind and value options. */
+export interface FilterFieldModel {
+  name: string;
+  label: string;
+  kind: FilterKind;
+  options: FilterOption[];
+}
+
+/**
+ * Discover the changelist's filter facets and their value options from the
+ * engine: FK fields list their target table, `choice` (plain-string) fields are
+ * scanned for distinct values, booleans are True/False. Only facets that have
+ * at least one option are surfaced.
+ */
+export function useFilterModel(
+  engine: RastackEngine,
+  resource: AdminResource,
+): { fields: FilterFieldModel[]; loading: boolean } {
+  const specs = useMemo(() => filterableFields(resource), [resource.key]);
+  const [fields, setFields] = useState<FilterFieldModel[]>([]);
+  const [loading, setLoading] = useState(specs.length > 0);
+
+  useEffect(() => {
+    let cancelled = false;
+    if (!specs.length) {
+      setFields([]);
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    (async () => {
+      // Distinct-value facets need a scan of this table's rows (once).
+      let rows: Record<string, unknown>[] = [];
+      if (specs.some((s) => s.kind === "choice")) {
+        const res: EngineResult = await engine.handle(
+          "GET",
+          listPath(resource.app, resource.model),
+          { page_size: "1000" },
+          undefined,
+        );
+        rows = readListEnvelope(res.body).results;
+      }
+      const built = await Promise.all(
+        specs.map(async (s): Promise<FilterFieldModel> => {
+          let options: FilterOption[] = [];
+          if (s.kind === "bool") options = boolFilterOptions();
+          else if (s.kind === "choice") options = distinctValueOptions(rows, s.name);
+          else if (s.kind === "fk" && s.relation) {
+            const res: EngineResult = await engine.handle(
+              "GET",
+              listPath(s.relation.app, s.relation.model),
+              { page_size: "1000" },
+              undefined,
+            );
+            options = fkFilterOptions(readListEnvelope(res.body).results);
+          }
+          return { name: s.name, label: s.label, kind: s.kind, options };
+        }),
+      );
+      if (!cancelled) {
+        setFields(built.filter((f) => f.options.length > 0));
+        setLoading(false);
+      }
+    })().catch(() => {
+      if (!cancelled) {
+        setFields([]);
+        setLoading(false);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [engine, resource.key]);
+
+  return { fields, loading };
+}
+
+/** State a form screen needs beyond the `AutoFormLike` itself. */
+export interface FormState {
+  model: AutoFormLike;
+  loading: boolean;
+  loadError?: string;
+  submitError?: string;
+  done: boolean;
+}
+
+/** Drive an `<AutoForm>` for create (`id` undefined) or edit. */
+export function useResourceForm(
+  engine: RastackEngine,
+  resource: AdminResource,
+  id?: string,
+): FormState {
+  const fields = useMemo(() => formFields(resource), [resource.key]);
+  const [values, setValues] = useState<Record<string, unknown>>(() =>
+    initialFormValues(resource),
+  );
+  const [errors] = useState<Record<string, string>>({});
+  const [fkOptions, setFkOptions] = useState<Record<string, FieldOption[]>>({});
+  const [submitting, setSubmitting] = useState(false);
+  const [loading, setLoading] = useState(Boolean(id));
+  const [loadError, setLoadError] = useState<string | undefined>();
+  const [submitError, setSubmitError] = useState<string | undefined>();
+  const [done, setDone] = useState(false);
+
+  // Reset when switching between add/edit or resources.
+  useEffect(() => {
+    setValues(initialFormValues(resource));
+    setDone(false);
+    setSubmitError(undefined);
+    setLoadError(undefined);
+    setLoading(Boolean(id));
+  }, [resource.key, id]);
+
+  // Load FK target options once per resource.
+  useEffect(() => {
+    let cancelled = false;
+    const fks = fields.filter((f) => f.type === "fk" && f.relation);
+    Promise.all(
+      fks.map(async (f) => {
+        const res: EngineResult = await engine.handle(
+          "GET",
+          listPath(f.relation!.app, f.relation!.model),
+          { page_size: "1000" },
+          undefined,
+        );
+        return [f.name, optionsFromRows(readListEnvelope(res.body).results)] as const;
+      }),
+    ).then((entries) => {
+      if (!cancelled) setFkOptions(Object.fromEntries(entries));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [engine, resource.key]);
+
+  // Load the existing row when editing.
+  useEffect(() => {
+    if (!id) return;
+    let cancelled = false;
+    engine
+      .handle("GET", detailPath(resource.app, resource.model, id), undefined, undefined)
+      .then((res: EngineResult) => {
+        if (cancelled) return;
+        if (ok(res) && res.body && typeof res.body === "object") {
+          const row = res.body as Record<string, unknown>;
+          const next: Record<string, unknown> = {};
+          for (const f of fields) {
+            next[f.name] =
+              row[f.name] ?? (f.type === "bool" ? false : "");
+          }
+          setValues(next);
+        } else {
+          setLoadError(errorDetail(res.body));
+        }
+        setLoading(false);
+      })
+      .catch((e: unknown) => {
+        if (!cancelled) {
+          setLoadError(String(e));
+          setLoading(false);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [engine, resource.key, id]);
+
+  const setValue = useCallback(
+    (name: string) => (v: unknown) =>
+      setValues((prev) => ({ ...prev, [name]: v })),
+    [],
+  );
+
+  const getFormField = useCallback(
+    (name: string): AutoFormField => {
+      const field = fields.find((f) => f.name === name)!;
+      const value = values[name];
+      return {
+        value,
+        setValue: setValue(name),
+        error: errors[name] ?? "",
+        type: fieldControlType(field),
+        isChecked: value === true,
+        isError: Boolean(errors[name]),
+        isDisabled: submitting,
+        isRequired: !field.nullable,
+        setTouched: () => {
+          /* touched tracked by AutoForm itself */
+        },
+        maxLength: field.maxLength,
+        options: field.type === "fk" ? fkOptions[field.name] ?? [] : undefined,
+        relation: field.relation,
+        nullable: field.nullable,
+      };
+    },
+    [fields, values, errors, submitting, fkOptions, setValue],
+  );
+
+  const onSubmit = useCallback(() => {
+    setSubmitting(true);
+    setSubmitError(undefined);
+    const body = buildWriteBody(resource, values);
+    const method = id ? "PUT" : "POST";
+    const path = id
+      ? detailPath(resource.app, resource.model, id)
+      : listPath(resource.app, resource.model);
+    engine
+      .handle(method, path, undefined, body)
+      .then((res: EngineResult) => {
+        setSubmitting(false);
+        if (ok(res)) setDone(true);
+        else setSubmitError(errorDetail(res.body));
+      })
+      .catch((e: unknown) => {
+        setSubmitting(false);
+        setSubmitError(String(e));
+      });
+  }, [engine, resource, values, id]);
+
+  const model: AutoFormLike = {
+    formValues: values,
+    getFormField,
+    onSubmit,
+    resetForm: () => setValues(initialFormValues(resource)),
+    isSubmitDisabled: submitting,
+    isSubmitting: submitting,
+    errors,
+  };
+  return { model, loading, loadError, submitError, done };
+}
+
+/** Delete a record via the engine; resolves true on success. */
+export function useDeleteRecord(
+  engine: RastackEngine,
+  resource: AdminResource,
+): (id: string | number) => Promise<boolean> {
+  return useCallback(
+    async (id) => {
+      const res: EngineResult = await engine.handle(
+        "DELETE",
+        detailPath(resource.app, resource.model, id),
+        undefined,
+        undefined,
+      );
+      return ok(res);
+    },
+    [engine, resource.key],
+  );
+}