rastack 0.0.42 → 0.0.44

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.44](https://github.com/theserverkid/reactapistack/compare/v0.0.43...v0.0.44) (2026-07-12)
+
+
+### Features
+
+* **dev:** replace `rastack serve`/`wasm` with `rastack dev` — full in-browser admin over WASM ([6f3f579](https://github.com/theserverkid/reactapistack/commit/6f3f579422624bd0dd3d834b6c0eff47eeef2214))
+
+### [0.0.43](https://github.com/theserverkid/reactapistack/compare/v0.0.42...v0.0.43) (2026-07-12)
+
+
+### Bug Fixes
+
+* **init:** require the bootstrap stack instead of creating it ([085c59d](https://github.com/theserverkid/reactapistack/commit/085c59df4a61c5d28312edb7d0895c5b2f0442b5))
+* **update:** silence Node DEP0190 when launching npm on Windows ([959fe61](https://github.com/theserverkid/reactapistack/commit/959fe6177ec4e6e0d634e2751a1099717f2bda3b))
+
 ### [0.0.42](https://github.com/theserverkid/reactapistack/compare/v0.0.41...v0.0.42) (2026-07-12)
 
 

package/admin/AdminApp.tsx

@@ -0,0 +1,308 @@
+/**
+ * The in-browser admin — a Django-admin-style, manifest-driven UI that runs
+ * entirely over the WASM engine (`useRastackClient().engine`). It reuses the
+ * headless `rastack/components` (`DataTable`, `AutoForm`, primitives) and is
+ * app-generic: every screen is built from the compiled manifest, so the same
+ * bundle admins any app. Faithful to `rust/rastack-api/src/admin.rs`.
+ */
+
+import React, { useEffect, useMemo, useState } from "react";
+import { useRastackClient } from "../provider";
+import {
+  Button,
+  Card,
+  DataTable,
+  AutoForm,
+  Spinner,
+  type DataTableColumnInput,
+} from "../components";
+import {
+  AdminResource,
+  adminResources,
+  changelistHeaders,
+  detailPath,
+  findResource,
+  parseManifest,
+} from "./adapters";
+import { useDeleteRecord, useResourceForm, useResourceTable } from "./useAdmin";
+import type { RastackEngine } from "../provider/types";
+
+// -- hash routing (dependency-free) -----------------------------------------
+
+type Route =
+  | { name: "index" }
+  | { name: "list"; app: string; model: string }
+  | { name: "add"; app: string; model: string }
+  | { name: "change"; app: string; model: string; id: string };
+
+function parseRoute(hash: string): Route {
+  const parts = hash.replace(/^#\/?/, "").split("/").filter(Boolean);
+  if (parts.length < 2) return { name: "index" };
+  const [app, model, third] = parts;
+  if (!third) return { name: "list", app, model };
+  if (third === "add") return { name: "add", app, model };
+  return { name: "change", app, model, id: decodeURIComponent(third) };
+}
+
+function useRoute(): Route {
+  const [hash, setHash] = useState(() =>
+    typeof location !== "undefined" ? location.hash : "",
+  );
+  useEffect(() => {
+    const on = () => setHash(location.hash);
+    window.addEventListener("hashchange", on);
+    return () => window.removeEventListener("hashchange", on);
+  }, []);
+  return useMemo(() => parseRoute(hash), [hash]);
+}
+
+const go = (hash: string) => {
+  location.hash = hash;
+};
+
+// -- shell ------------------------------------------------------------------
+
+function Shell(props: {
+  crumbs: { label: string; hash?: string }[];
+  children: React.ReactNode;
+}): React.JSX.Element {
+  return (
+    <div style={{ maxWidth: 1024, margin: "0 auto", padding: "24px 20px" }}>
+      <nav style={{ marginBottom: 20, fontSize: 14 }}>
+        {props.crumbs.map((c, i) => (
+          <span key={i}>
+            {i > 0 ? <span style={{ opacity: 0.5 }}> / </span> : null}
+            {c.hash ? (
+              <a href={c.hash} style={{ textDecoration: "none" }}>
+                {c.label}
+              </a>
+            ) : (
+              <span>{c.label}</span>
+            )}
+          </span>
+        ))}
+      </nav>
+      {props.children}
+    </div>
+  );
+}
+
+// -- screens ----------------------------------------------------------------
+
+function IndexScreen(props: { resources: AdminResource[] }): React.JSX.Element {
+  const byApp = useMemo(() => {
+    const map = new Map<string, AdminResource[]>();
+    for (const r of adminResources(props.resources)) {
+      (map.get(r.app) ?? map.set(r.app, []).get(r.app)!).push(r);
+    }
+    return [...map.entries()].sort(([a], [b]) => a.localeCompare(b));
+  }, [props.resources]);
+
+  return (
+    <Shell crumbs={[{ label: "Admin" }]}>
+      <h1 style={{ fontSize: 22, margin: "0 0 16px" }}>Administration</h1>
+      {byApp.map(([app, models]) => (
+        <Card key={app} style={{ marginBottom: 16, padding: 16 }}>
+          <h2 style={{ fontSize: 15, textTransform: "capitalize", margin: "0 0 8px" }}>
+            {app}
+          </h2>
+          <ul style={{ margin: 0, paddingLeft: 18 }}>
+            {models
+              .slice()
+              .sort((a, b) => a.model.localeCompare(b.model))
+              .map((r) => (
+                <li key={r.key} style={{ margin: "4px 0" }}>
+                  <a href={`#/${r.app}/${r.model}/`}>{r.label}</a>
+                </li>
+              ))}
+          </ul>
+        </Card>
+      ))}
+    </Shell>
+  );
+}
+
+/** DataTable columns with id + FK cells rendered as links (like the Rust admin). */
+function columnsFor(resource: AdminResource): DataTableColumnInput[] {
+  return changelistHeaders(resource).map((h) => {
+    if (h.key === "id") {
+      return {
+        key: "id",
+        header: "id",
+        render: (row: Record<string, unknown>, value: unknown) => (
+          <a href={`#/${resource.app}/${resource.model}/${String(value)}`}>
+            {String(value)}
+          </a>
+        ),
+      };
+    }
+    const field = resource.fields.find((f) => f.name === h.key);
+    if (field?.type === "fk" && field.relation) {
+      const { app, model } = field.relation;
+      return {
+        key: h.key,
+        header: h.name,
+        render: (_row: Record<string, unknown>, value: unknown) =>
+          value == null || value === "" ? (
+            ""
+          ) : (
+            <a href={`#/${app}/${model}/${String(value)}`}>
+              {model} #{String(value)}
+            </a>
+          ),
+      };
+    }
+    return { key: h.key, header: h.name };
+  });
+}
+
+function ListScreen(props: {
+  engine: RastackEngine;
+  resource: AdminResource;
+}): React.JSX.Element {
+  const { engine, resource } = props;
+  const { query } = useResourceTable(engine, resource);
+  const columns = useMemo(() => columnsFor(resource), [resource.key]);
+  return (
+    <Shell
+      crumbs={[
+        { label: "Admin", hash: "#/" },
+        { label: resource.label },
+      ]}
+    >
+      <div
+        style={{
+          display: "flex",
+          justifyContent: "space-between",
+          alignItems: "center",
+          marginBottom: 12,
+        }}
+      >
+        <h1 style={{ fontSize: 20, margin: 0 }}>{resource.label}</h1>
+        <Button onClick={() => go(`#/${resource.app}/${resource.model}/add`)}>
+          Add {resource.label}
+        </Button>
+      </div>
+      <DataTable
+        query={query}
+        columns={columns}
+        onRowClick={(row) =>
+          go(`#/${resource.app}/${resource.model}/${String(row.id)}`)
+        }
+      />
+    </Shell>
+  );
+}
+
+function FormScreen(props: {
+  engine: RastackEngine;
+  resource: AdminResource;
+  id?: string;
+}): React.JSX.Element {
+  const { engine, resource, id } = props;
+  const { model, loading, loadError, submitError, done } = useResourceForm(
+    engine,
+    resource,
+    id,
+  );
+  const del = useDeleteRecord(engine, resource);
+  const listHash = `#/${resource.app}/${resource.model}/`;
+
+  // On successful save, return to the changelist.
+  useEffect(() => {
+    if (done) go(listHash);
+  }, [done]);
+
+  const onDelete = async () => {
+    if (!id) return;
+    if (typeof confirm === "function" && !confirm("Delete this record?")) return;
+    if (await del(id)) go(listHash);
+  };
+
+  return (
+    <Shell
+      crumbs={[
+        { label: "Admin", hash: "#/" },
+        { label: resource.label, hash: listHash },
+        { label: id ? `Edit #${id}` : "Add" },
+      ]}
+    >
+      <h1 style={{ fontSize: 20, margin: "0 0 16px" }}>
+        {id ? `Edit ${resource.label} #${id}` : `Add ${resource.label}`}
+      </h1>
+      {loadError ? (
+        <p style={{ color: "#c93c37" }}>{loadError}</p>
+      ) : loading ? (
+        <Spinner />
+      ) : (
+        <Card style={{ padding: 20, maxWidth: 560 }}>
+          <AutoForm form={model} onCancel={() => go(listHash)} />
+          {submitError ? (
+            <p style={{ color: "#c93c37", marginTop: 12 }}>{submitError}</p>
+          ) : null}
+          {id ? (
+            <div style={{ marginTop: 16 }}>
+              <Button variant="danger" onClick={onDelete}>
+                Delete
+              </Button>
+            </div>
+          ) : null}
+        </Card>
+      )}
+    </Shell>
+  );
+}
+
+// -- root -------------------------------------------------------------------
+
+export function AdminApp(props: {
+  manifest: object | string;
+}): React.JSX.Element {
+  const client = useRastackClient();
+  const route = useRoute();
+  const resources = useMemo(() => parseManifest(props.manifest), [props.manifest]);
+
+  if (client.status === "error") {
+    return (
+      <Shell crumbs={[{ label: "Admin" }]}>
+        <p style={{ color: "#c93c37" }}>
+          The WASM engine failed to start. Check the console.
+        </p>
+      </Shell>
+    );
+  }
+  if (!client.engine || client.status !== "ready") {
+    return (
+      <Shell crumbs={[{ label: "Admin" }]}>
+        <div style={{ display: "flex", gap: 10, alignItems: "center" }}>
+          <Spinner />
+          <span>
+            {client.status === "seeding"
+              ? "Seeding the local warehouse…"
+              : "Starting the WASM engine…"}
+          </span>
+        </div>
+      </Shell>
+    );
+  }
+
+  if (route.name === "index") return <IndexScreen resources={resources} />;
+
+  const resource = findResource(resources, route.app, route.model);
+  if (!resource) {
+    return (
+      <Shell crumbs={[{ label: "Admin", hash: "#/" }, { label: "Not found" }]}>
+        <p>
+          Unknown resource <code>{route.app}.{route.model}</code>.
+        </p>
+      </Shell>
+    );
+  }
+  if (route.name === "list")
+    return <ListScreen engine={client.engine} resource={resource} />;
+  if (route.name === "add")
+    return <FormScreen engine={client.engine} resource={resource} />;
+  return (
+    <FormScreen engine={client.engine} resource={resource} id={route.id} />
+  );
+}

package/admin/adapters.ts

@@ -0,0 +1,247 @@
+/**
+ * Pure adapters that turn the compiled manifest (`schema.rastack.json`) into the
+ * shapes the in-browser admin renders from — resource/field descriptors, the
+ * changelist columns, form field controls, value coercion, and the REST paths
+ * the WASM engine's `handle` answers. No React, no DOM, no engine — unit-tested
+ * directly (mirrors the Rust admin's manifest-driven rendering in
+ * `rust/rastack-api/src/admin.rs`, which derives every control from `field.ty`).
+ */
+
+import type { FormType } from "../hooks/form/interfaces";
+import type { FieldOption } from "../hooks/form/interfaces";
+import type { ReturnedHeader } from "../hooks/query/interfaces";
+import { humanizeKey } from "../components/util";
+
+/** The manifest's scalar/fk field type, as serialized in schema.rastack.json. */
+export type ManifestFieldType =
+  | "string"
+  | "int"
+  | "float"
+  | "bool"
+  | "datetime"
+  | "uuid"
+  | "fk";
+
+export interface AdminField {
+  name: string;
+  type: ManifestFieldType;
+  primaryKey: boolean;
+  maxLength?: number;
+  nullable: boolean;
+  /** `{ app, model }` for a foreign key (`type === "fk"`). */
+  relation?: { app: string; model: string };
+}
+
+export interface AdminResource {
+  app: string;
+  model: string;
+  /** `"app.model"` — the stable id used in routes. */
+  key: string;
+  label: string;
+  fields: AdminField[];
+  /** Searchable field names (drives the search box + the API `search` param). */
+  search: string[];
+  /** `admin.listDisplay` columns, or null to fall back to all fields. */
+  listDisplay: string[] | null;
+  /** Whether this resource is shown in the admin (admin !== false). */
+  adminEnabled: boolean;
+}
+
+interface RawField {
+  name: string;
+  type: ManifestFieldType;
+  primaryKey?: boolean;
+  maxLength?: number;
+  null?: boolean;
+  relation?: { app: string; model: string };
+}
+interface RawResource {
+  app: string;
+  model: string;
+  fields: RawField[];
+  search?: string[];
+  admin?: { listDisplay?: string[] } | false;
+}
+interface RawManifest {
+  resources?: RawResource[];
+}
+
+/** Parse a manifest (object or JSON string) into admin resource descriptors. */
+export function parseManifest(manifest: object | string): AdminResource[] {
+  const doc: RawManifest =
+    typeof manifest === "string" ? JSON.parse(manifest) : (manifest as RawManifest);
+  return (doc.resources ?? []).map((r) => ({
+    app: r.app,
+    model: r.model,
+    key: `${r.app}.${r.model}`,
+    label: humanizeKey(r.model),
+    fields: (r.fields ?? []).map((f) => ({
+      name: f.name,
+      type: f.type,
+      primaryKey: f.primaryKey === true,
+      maxLength: f.maxLength,
+      nullable: f.null === true,
+      relation: f.relation,
+    })),
+    search: r.search ?? [],
+    listDisplay:
+      r.admin && Array.isArray(r.admin.listDisplay) ? r.admin.listDisplay : null,
+    adminEnabled: r.admin !== false,
+  }));
+}
+
+/** The resources shown in the admin index (admin not disabled). */
+export function adminResources(resources: AdminResource[]): AdminResource[] {
+  return resources.filter((r) => r.adminEnabled);
+}
+
+export function findResource(
+  resources: AdminResource[],
+  app: string,
+  model: string,
+): AdminResource | undefined {
+  return resources.find((r) => r.app === app && r.model === model);
+}
+
+// -- REST paths the WASM engine's `handle` answers --------------------------
+
+export function listPath(app: string, model: string): string {
+  return `/api/${app}/v1/${model}/`;
+}
+export function detailPath(app: string, model: string, id: string | number): string {
+  return `/api/${app}/v1/${model}/${id}/`;
+}
+
+// -- changelist -------------------------------------------------------------
+
+/** The DRF list envelope the engine returns for a list request. */
+export interface ListEnvelope {
+  count: number;
+  results: Record<string, unknown>[];
+}
+
+/** Read the DRF `{ count, results }` list envelope defensively. */
+export function readListEnvelope(body: unknown): ListEnvelope {
+  const b = (body ?? {}) as { count?: unknown; results?: unknown };
+  return {
+    count: typeof b.count === "number" ? b.count : 0,
+    results: Array.isArray(b.results) ? (b.results as Record<string, unknown>[]) : [],
+  };
+}
+
+/**
+ * Changelist columns: an `id` column first, then `admin.listDisplay` if set,
+ * else every field name — matching the Rust admin (`admin.rs` changelist).
+ */
+export function changelistHeaders(resource: AdminResource): ReturnedHeader[] {
+  const names =
+    resource.listDisplay ?? resource.fields.map((f) => f.name);
+  const keys = ["id", ...names.filter((n) => n !== "id")];
+  return keys.map((key) => ({ key, name: humanizeKey(key) }));
+}
+
+/** Page count for a total + page size (never below 1, like the Rust admin). */
+export function pageCount(total: number, pageSize: number): number {
+  return Math.max(1, Math.ceil(total / Math.max(1, pageSize)));
+}
+
+/** The admin's fixed changelist page size (matches `admin.rs`). */
+export const PAGE_SIZE = 25;
+
+// -- forms ------------------------------------------------------------------
+
+/** The fields an add/change form renders — every field except the primary key. */
+export function formFields(resource: AdminResource): AdminField[] {
+  return resource.fields.filter((f) => !f.primaryKey);
+}
+
+/**
+ * The `<AutoForm>` control kind for a manifest field. Foreign keys become a
+ * `select` (populated from the target table); the rest map by scalar type —
+ * exactly the control choices the Rust admin's `render_input` makes.
+ */
+export function fieldControlType(field: AdminField): FormType {
+  switch (field.type) {
+    case "fk":
+      return "select";
+    case "bool":
+      return "boolean";
+    case "int":
+    case "float":
+      return "number";
+    case "datetime":
+      return "datetime";
+    default:
+      return "text";
+  }
+}
+
+/**
+ * A human label for a row in an FK `<select>`: the first non-`id` string field's
+ * value, else `#{id}` — the same heuristic as the Rust admin's `option_label`.
+ */
+export function optionLabel(row: Record<string, unknown>): string {
+  for (const [key, value] of Object.entries(row)) {
+    if (key !== "id" && typeof value === "string" && value.length > 0) {
+      return `${value} (#${row.id})`;
+    }
+  }
+  return `#${row.id ?? ""}`;
+}
+
+/** FK `<select>` options from the target table's rows. */
+export function optionsFromRows(rows: Record<string, unknown>[]): FieldOption[] {
+  return rows.map((row) => ({
+    label: optionLabel(row),
+    value: (row.id as string | number) ?? "",
+  }));
+}
+
+/** Initial form values keyed by field name (drives AutoForm's field order). */
+export function initialFormValues(
+  resource: AdminResource,
+): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const field of formFields(resource)) {
+    values[field.name] = field.type === "bool" ? false : "";
+  }
+  return values;
+}
+
+/**
+ * Coerce one raw form value to the type the API expects, mirroring the Rust
+ * admin's `form_to_row`: booleans always sent; numbers/FKs parsed (raw string
+ * on parse failure); empty non-bool values are omitted (so nullable fields are
+ * not sent as `""`). Returns `undefined` to signal "omit this field".
+ */
+export function coerceFormValue(field: AdminField, raw: unknown): unknown {
+  if (field.type === "bool") return raw === true || raw === "true";
+  if (raw === "" || raw === null || raw === undefined) return undefined;
+  if (field.type === "int" || field.type === "float" || field.type === "fk") {
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : raw;
+  }
+  return raw;
+}
+
+/** Build the request body from form values, applying `coerceFormValue`. */
+export function buildWriteBody(
+  resource: AdminResource,
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+  for (const field of formFields(resource)) {
+    const coerced = coerceFormValue(field, values[field.name]);
+    if (coerced !== undefined) body[field.name] = coerced;
+  }
+  return body;
+}
+
+/** Extract a `{detail}` error message from a non-2xx `handle` body. */
+export function errorDetail(body: unknown): string {
+  if (body && typeof body === "object" && "detail" in body) {
+    const detail = (body as { detail: unknown }).detail;
+    return typeof detail === "string" ? detail : JSON.stringify(detail);
+  }
+  return typeof body === "string" ? body : "Request failed";
+}

package/admin/index.tsx

@@ -0,0 +1,88 @@
+/**
+ * Entry point for the `rastack dev` in-browser admin, bundled by esbuild into
+ * `dist/admin.js` and served at `/dev/admin.js`. It fetches the compiled
+ * schema/openapi, boots the WASM engine via `<RAStackProvider mode="local">`
+ * (seeding from the served `/data/warehouse/`), themes everything with
+ * `<ThemeProvider>`, and renders the manifest-driven `<AdminApp>`.
+ */
+
+import React, { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { RAStackProvider } from "../provider";
+import type { RastackWasmModule } from "../provider/types";
+import { ThemeProvider } from "../theme";
+import { defineTheme } from "../tokens";
+import { AdminApp } from "./AdminApp";
+
+/**
+ * Load the wasm engine from the URL `rastack dev` serves it at (`/wasm/…`).
+ * The dynamic `import()` is hidden behind `new Function` so esbuild leaves it
+ * for the browser to resolve at runtime (the same trick `defaultEngineLoader`
+ * uses) rather than trying to bundle the `.wasm` at build time.
+ */
+const loadEngine = async (): Promise<RastackWasmModule> => {
+  const runtimeImport = new Function("s", "return import(s)") as (
+    s: string,
+  ) => Promise<any>;
+  const mod: RastackWasmModule = await runtimeImport("/wasm/rastack_wasm.js");
+  const init = mod.default || mod.init;
+  if (typeof init === "function") await init();
+  return mod;
+};
+
+const theme = defineTheme({ brand: "#2f6feb", radius: "rounded" });
+
+interface Compiled {
+  manifest: object;
+  openapi?: object;
+}
+
+function Boot(): React.JSX.Element {
+  const [compiled, setCompiled] = useState<Compiled | null>(null);
+  const [error, setError] = useState<string | undefined>();
+
+  useEffect(() => {
+    (async () => {
+      const manifestRes = await fetch("/schema.rastack.json");
+      if (!manifestRes.ok)
+        throw new Error(`schema.rastack.json (${manifestRes.status})`);
+      const manifest = await manifestRes.json();
+      let openapi: object | undefined;
+      try {
+        const openapiRes = await fetch("/openapi.json");
+        if (openapiRes.ok) openapi = await openapiRes.json();
+      } catch {
+        /* openapi is optional */
+      }
+      setCompiled({ manifest, openapi });
+    })().catch((e) => setError(String(e)));
+  }, []);
+
+  if (error)
+    return (
+      <div className="rastack-boot">
+        Failed to load the compiled schema: {error}
+      </div>
+    );
+  if (!compiled)
+    return <div className="rastack-boot">Compiling the schema…</div>;
+
+  return (
+    <RAStackProvider
+      mode="local"
+      manifest={compiled.manifest}
+      openapi={compiled.openapi}
+      loadEngine={loadEngine}
+      warehouseBaseUrl="/data/warehouse/"
+      persist={false}
+      cache={false}
+    >
+      <ThemeProvider tokens={theme}>
+        <AdminApp manifest={compiled.manifest} />
+      </ThemeProvider>
+    </RAStackProvider>
+  );
+}
+
+const container = document.getElementById("root");
+if (container) createRoot(container).render(<Boot />);