rastack 0.0.43 → 0.0.45

package/admin/adapters.ts

@@ -0,0 +1,346 @@
+/**
+ * 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;
+  /** Unique constraint — such fields are identifiers, not filter facets. */
+  unique?: 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;
+  unique?: 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,
+      unique: f.unique === 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;
+}
+
+// -- filters (Linear-style changelist filter bar) ---------------------------
+
+/** How a filter's values are sourced/rendered. */
+export type FilterKind = "fk" | "bool" | "choice";
+
+/** A single selectable filter value. */
+export interface FilterOption {
+  value: string;
+  label: string;
+}
+
+/** A field the changelist can filter on, and how to build its value list. */
+export interface FilterableField {
+  name: string;
+  label: string;
+  kind: FilterKind;
+  /** FK target table (`kind === "fk"`). */
+  relation?: { app: string; model: string };
+}
+
+/** Distinct-value cap: above this a `string` field is an identifier, not a facet. */
+export const DISTINCT_CAP = 40;
+
+/**
+ * The fields a changelist offers as filters, mirroring what makes sense as a
+ * Django `list_filter`: every foreign key (filter by related row), every boolean
+ * (true/false), and every non-unique plain-string field (filter by one of its
+ * observed values). Unique strings, numbers, ids and timestamps are excluded —
+ * they identify a row rather than group many, so they belong in search, not a
+ * facet.
+ */
+export function filterableFields(resource: AdminResource): FilterableField[] {
+  const out: FilterableField[] = [];
+  for (const f of resource.fields) {
+    if (f.primaryKey) continue;
+    if (f.type === "fk" && f.relation) {
+      out.push({ name: f.name, label: humanizeKey(f.name), kind: "fk", relation: f.relation });
+    } else if (f.type === "bool") {
+      out.push({ name: f.name, label: humanizeKey(f.name), kind: "bool" });
+    } else if (f.type === "string" && !f.unique) {
+      out.push({ name: f.name, label: humanizeKey(f.name), kind: "choice" });
+    }
+  }
+  return out;
+}
+
+/** The fixed True/False options a boolean filter offers. */
+export function boolFilterOptions(): FilterOption[] {
+  return [
+    { value: "true", label: "True" },
+    { value: "false", label: "False" },
+  ];
+}
+
+/**
+ * Distinct non-empty values of `field` across `rows`, sorted, as filter options.
+ * Returns `[]` when the field has more than `cap` distinct values (too
+ * high-cardinality to be a useful facet — it should be searched, not filtered).
+ */
+export function distinctValueOptions(
+  rows: Record<string, unknown>[],
+  field: string,
+  cap = DISTINCT_CAP,
+): FilterOption[] {
+  const seen = new Set<string>();
+  for (const row of rows) {
+    const v = row[field];
+    if (v === null || v === undefined || v === "") continue;
+    seen.add(String(v));
+    if (seen.size > cap) return [];
+  }
+  return [...seen].sort().map((value) => ({ value, label: value }));
+}
+
+/**
+ * The label for an FK filter value: reuse the `<select>` option label heuristic
+ * (first non-id string field, else `#id`) against the target table's rows.
+ */
+export function fkFilterOptions(rows: Record<string, unknown>[]): FilterOption[] {
+  return rows.map((row) => ({
+    value: String(row.id ?? ""),
+    label: optionLabel(row),
+  }));
+}
+
+/** Merge active filters into an engine list-query object (field → value). */
+export function withFilters(
+  query: Record<string, string>,
+  filters: Record<string, string>,
+): Record<string, string> {
+  // Filters first, then reserved keys, so a field named `page`/`search` can
+  // never shadow pagination — the reserved keys always win.
+  return { ...filters, ...query };
+}
+
+/** 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/httpEngine.ts

@@ -0,0 +1,56 @@
+/**
+ * An HTTP-backed `RastackEngine` — the same `handle(method, path, query, body)`
+ * seam the WASM engine exposes, implemented over `fetch` against a live
+ * `rastack-server`. This is what lets the *identical* admin UI run two ways:
+ * over WebAssembly in `rastack dev` (`client.engine`), or over the real Rust
+ * API + Iceberg store in `rastack admin` (this adapter) — the components,
+ * hooks and adapters above it never learn which.
+ */
+
+import type { RastackEngine } from "../provider/types";
+
+/** Build a same-origin (or `baseUrl`-rooted) HTTP engine. */
+export function createHttpEngine(baseUrl = ""): RastackEngine {
+  const base = baseUrl.replace(/\/+$/, "");
+
+  async function handle(
+    method: string,
+    path: string,
+    query: Record<string, string> | undefined,
+    body: unknown,
+  ): Promise<{ status: number; body: any }> {
+    const qs =
+      query && Object.keys(query).length
+        ? "?" + new URLSearchParams(query).toString()
+        : "";
+    const hasBody = body !== undefined && body !== null;
+    const res = await fetch(base + path + qs, {
+      method,
+      headers: hasBody ? { "Content-Type": "application/json" } : undefined,
+      body: hasBody ? JSON.stringify(body) : undefined,
+      credentials: "same-origin",
+    });
+    // 204 (delete) and errors may carry no body; parse defensively.
+    const text = await res.text();
+    let parsed: any = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    return { status: res.status, body: parsed };
+  }
+
+  const unavailable = (op: string) => async (): Promise<never> => {
+    throw new Error(`${op} is only available over the local WASM engine.`);
+  };
+
+  return {
+    handle,
+    seedFile: unavailable("seedFile"),
+    importWarehouse: unavailable("importWarehouse"),
+    exportWarehouse: unavailable("exportWarehouse") as RastackEngine["exportWarehouse"],
+  };
+}

package/admin/index.tsx

@@ -0,0 +1,140 @@
+/**
+ * Entry point for the admin bundle (`dist/admin.js`). It runs two ways from the
+ * *same* build, chosen by a `window.__RASTACK_ADMIN__` config the host page
+ * injects (defaulting to local):
+ *
+ *  • `rastack dev`   → `mode: "local"`  — boots the WASM engine via
+ *    `<RAStackProvider mode="local">`, seeding from the served `/data/warehouse/`.
+ *  • `rastack admin` → `mode: "remote"` — talks to the live `rastack-server`
+ *    over HTTP through an `httpEngine`, against the real Iceberg warehouse.
+ *
+ * Either way it fetches the compiled schema, themes everything with
+ * `<ThemeProvider>` and the design tokens, and renders the manifest-driven
+ * `<AdminApp>` — which never learns which engine it got.
+ */
+
+import React, { useEffect, useMemo, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { RAStackProvider, useRastackClient } from "../provider";
+import type { RastackWasmModule } from "../provider/types";
+import { Spinner } from "../components";
+import { ThemeProvider } from "../theme";
+import { defineTheme } from "../tokens";
+import { AdminApp } from "./AdminApp";
+import { parseManifest, type AdminResource } from "./adapters";
+import { createHttpEngine } from "./httpEngine";
+
+interface AdminConfig {
+  mode: "local" | "remote";
+  /** Remote: base URL the `/api/...` paths are joined onto (default same origin). */
+  apiBase?: string;
+  /** Where to fetch the compiled `schema.rastack.json`. */
+  schemaUrl?: string;
+  /** Local: base URL of the committed Iceberg warehouse to seed from. */
+  warehouseBaseUrl?: string;
+}
+
+const cfg: AdminConfig =
+  (typeof window !== "undefined" && (window as any).__RASTACK_ADMIN__) || {
+    mode: "local",
+    schemaUrl: "/schema.rastack.json",
+    warehouseBaseUrl: "/data/warehouse/",
+  };
+
+// The framework's own design system paints the whole console.
+const theme = defineTheme({ brand: "#4F6BFF", radius: "rounded" });
+
+/** Load the WASM engine from the URL `rastack dev` serves it at (`/wasm/…`). */
+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;
+};
+
+function Loading({ label }: { label: string }): React.JSX.Element {
+  return (
+    <div className="ras-boot">
+      <Spinner /> {label}
+    </div>
+  );
+}
+
+/** Local (WASM) admin: wait for the provider's engine, then render. */
+function LocalAdmin({ resources }: { resources: AdminResource[] }): React.JSX.Element {
+  const client = useRastackClient();
+  if (client.status === "error")
+    return <Loading label="The WASM engine failed to start — check the console." />;
+  if (!client.engine || client.status !== "ready")
+    return (
+      <Loading
+        label={
+          client.status === "seeding"
+            ? "Seeding the local warehouse…"
+            : "Starting the WASM engine…"
+        }
+      />
+    );
+  return <AdminApp engine={client.engine} resources={resources} />;
+}
+
+function Boot(): React.JSX.Element {
+  const [resources, setResources] = useState<AdminResource[] | null>(null);
+  const [manifest, setManifest] = useState<object | null>(null);
+  const [openapi, setOpenapi] = useState<object | undefined>();
+  const [error, setError] = useState<string>();
+  const httpEngine = useMemo(() => createHttpEngine(cfg.apiBase ?? ""), []);
+
+  useEffect(() => {
+    (async () => {
+      const schemaUrl = cfg.schemaUrl || "/schema.rastack.json";
+      const res = await fetch(schemaUrl);
+      if (!res.ok) throw new Error(`${schemaUrl} (${res.status})`);
+      const doc = await res.json();
+      setManifest(doc);
+      setResources(parseManifest(doc));
+      if (cfg.mode === "local") {
+        try {
+          const o = await fetch("/openapi.json");
+          if (o.ok) setOpenapi(await o.json());
+        } catch {
+          /* openapi is optional */
+        }
+      }
+    })().catch((e) => setError(String(e)));
+  }, []);
+
+  if (error)
+    return <div className="ras-boot">Failed to load the schema: {error}</div>;
+  if (!resources || !manifest) return <Loading label="Loading the schema…" />;
+
+  if (cfg.mode === "remote") {
+    return (
+      <ThemeProvider tokens={theme}>
+        <AdminApp engine={httpEngine} resources={resources} />
+      </ThemeProvider>
+    );
+  }
+
+  return (
+    <RAStackProvider
+      mode="local"
+      manifest={manifest}
+      openapi={openapi}
+      loadEngine={loadEngine}
+      warehouseBaseUrl={cfg.warehouseBaseUrl ?? "/data/warehouse/"}
+      persist={false}
+      cache={false}
+    >
+      <ThemeProvider tokens={theme}>
+        <LocalAdmin resources={resources} />
+      </ThemeProvider>
+    </RAStackProvider>
+  );
+}
+
+const container = document.getElementById("root");
+if (container) createRoot(container).render(<Boot />);