@zerotal/admin 1.0.0

package/src/form/ResourceForm.ts

@@ -0,0 +1,48 @@
+/**
+ * Build a Flow {@link Form} subclass from a resource's form schema for a given
+ * mode. The form's own enumerable properties are the visible field keys (so
+ * `flow:model="form.<key>"` binds + survives WebSocket round-trips), and its
+ * `rules()` are derived from the fields' validators.
+ *
+ * Accepts the full schema (`FormComponent[]` — fields and/or sections); the
+ * sections are flattened to fields for the generated form. The page renders the
+ * layout; the form only holds state + validation.
+ *
+ * One class is generated per (resource, mode) at boot and reused; a stable class
+ * name lets the Form synth reconstruct it on hydration.
+ */
+import { Form } from "@zerotal/flow";
+import type { RuleBuilder, FieldRule } from "@zerotal/validator";
+import type { Field, FieldMode } from "./Field.ts";
+import { type FormComponent, flattenFields } from "./Section.ts";
+
+export type ResourceFormClass = new () => Form & Record<string, unknown>;
+
+export function makeResourceForm(
+  schema: FormComponent[],
+  mode: FieldMode,
+  className: string,
+): { FormClass: ResourceFormClass; fields: Field[] } {
+  const visible = flattenFields(schema).filter((f) => f.visibleIn(mode));
+  const defaults: Record<string, unknown> = {};
+  for (const f of visible) defaults[f._key] = f.defaultValue();
+
+  class ResourceForm extends Form {
+    constructor() {
+      super();
+      Object.assign(this, structuredClone(defaults));
+    }
+
+    override rules(v: RuleBuilder): Record<string, FieldRule> {
+      const out: Record<string, FieldRule> = {};
+      for (const f of visible) out[f._key] = f.buildRule(v);
+      return out;
+    }
+  }
+
+  Object.defineProperty(ResourceForm, "name", { value: className });
+  // Instantiate once so the Form registry knows this class for hydration.
+  new ResourceForm();
+
+  return { FormClass: ResourceForm as unknown as ResourceFormClass, fields: visible };
+}

package/src/form/Section.ts

@@ -0,0 +1,364 @@
+/**
+ * Form layout — group fields into titled, multi-column sections, tabs, wizard
+ * steps and splits. A resource's `form()` may return a flat list of fields *or*
+ * a mix of fields and sections; loose fields are gathered into a default
+ * section. Fields and sections compose into the same `FormComponent[]`.
+ *
+ *   static form() {
+ *     return [
+ *       formSection("Profile").description("Public details").columns(2).schema([
+ *         textInput("name").required(),
+ *         textInput("email").email().required(),
+ *       ]),
+ *       formSection("Security").schema([
+ *         textInput("password").password().confirmed().visibleOn("create"),
+ *       ]),
+ *     ];
+ *   }
+ */
+import { Field } from "./Field.ts";
+
+export class FormSection {
+  /** @internal */ _heading?: string | undefined;
+  /** @internal */ _description?: string;
+  /** @internal */ _icon?: string;
+  /** @internal */ _columns = 2;
+  /** @internal */ _collapsible = false;
+  /** @internal Render as a bordered <fieldset> with a <legend>. */
+  _fieldset = false;
+  /** @internal */ _fields: Field[] = [];
+
+  constructor(heading?: string) {
+    this._heading = heading;
+  }
+
+  static make(heading?: string): FormSection {
+    return new FormSection(heading);
+  }
+
+  heading(heading: string): this {
+    this._heading = heading;
+    return this;
+  }
+
+  description(description: string): this {
+    this._description = description;
+    return this;
+  }
+
+  icon(name: string): this {
+    this._icon = name;
+    return this;
+  }
+
+  /** Number of columns the fields flow into (1–4). */
+  columns(n: number): this {
+    this._columns = Math.min(4, Math.max(1, n));
+    return this;
+  }
+
+  collapsible(value = true): this {
+    this._collapsible = value;
+    return this;
+  }
+
+  /** The fields contained in this section. */
+  schema(fields: Field[]): this {
+    this._fields = fields;
+    return this;
+  }
+
+  getFields(): Field[] {
+    return this._fields;
+  }
+}
+
+// ── Tabs layout ─────────────────────────────────────────────────────────────────
+
+export class FormTab {
+  /** @internal */ _label: string;
+  /** @internal */ _icon?: string;
+  /** @internal */ _columns = 2;
+  /** @internal */ _fields: Field[] = [];
+
+  constructor(label: string) {
+    this._label = label;
+  }
+
+  icon(name: string): this {
+    this._icon = name;
+    return this;
+  }
+
+  columns(n: number): this {
+    this._columns = Math.min(4, Math.max(1, n));
+    return this;
+  }
+
+  schema(fields: Field[]): this {
+    this._fields = fields;
+    return this;
+  }
+
+  getFields(): Field[] {
+    return this._fields;
+  }
+}
+
+/** A tabbed group of fields — switches client-side; all panels stay in the DOM. */
+export class FormTabs {
+  /** @internal */ _tabs: FormTab[];
+  constructor(tabs: FormTab[]) {
+    this._tabs = tabs;
+  }
+  getFields(): Field[] {
+    return this._tabs.flatMap((t) => t.getFields());
+  }
+}
+
+/** Factory for a single tab. */
+export function formTab(label: string): FormTab {
+  return new FormTab(label);
+}
+
+/** Factory for a tabbed layout. */
+export function formTabs(tabs: FormTab[]): FormTabs {
+  return new FormTabs(tabs);
+}
+
+// ── Wizard layout ───────────────────────────────────────────────────────────────
+
+export class WizardStep {
+  /** @internal */ _label: string;
+  /** @internal */ _description?: string;
+  /** @internal */ _icon?: string;
+  /** @internal */ _columns = 1;
+  /** @internal */ _fields: Field[] = [];
+
+  constructor(label: string) {
+    this._label = label;
+  }
+
+  description(text: string): this {
+    this._description = text;
+    return this;
+  }
+
+  icon(name: string): this {
+    this._icon = name;
+    return this;
+  }
+
+  columns(n: number): this {
+    this._columns = Math.min(4, Math.max(1, n));
+    return this;
+  }
+
+  schema(fields: Field[]): this {
+    this._fields = fields;
+    return this;
+  }
+
+  getFields(): Field[] {
+    return this._fields;
+  }
+}
+
+/** A multi-step wizard — validates each step before advancing; submits on the last. */
+export class Wizard {
+  /** @internal */ _steps: WizardStep[];
+  constructor(steps: WizardStep[]) {
+    this._steps = steps;
+  }
+  getFields(): Field[] {
+    return this._steps.flatMap((s) => s.getFields());
+  }
+}
+
+/** Factory for a single wizard step. */
+export function wizardStep(label: string): WizardStep {
+  return new WizardStep(label);
+}
+
+/** Factory for a wizard layout. */
+export function wizard(steps: WizardStep[]): Wizard {
+  return new Wizard(steps);
+}
+
+// ── Fieldset / Split / Callout / Prime (minor layout primitives) ─────────────────
+
+/** A section rendered as a bordered `<fieldset>` with a `<legend>`. */
+export function fieldset(legend?: string): FormSection {
+  const s = new FormSection(legend);
+  s._fieldset = true;
+  s._columns = 1;
+  return s;
+}
+
+export type CalloutTone = "default" | "primary" | "success" | "warning" | "destructive";
+
+/** A non-field callout/notice block in a form schema. */
+export class Callout {
+  /** @internal */ _content: string;
+  /** @internal */ _tone: CalloutTone = "default";
+  /** @internal */ _icon?: string;
+  /** @internal */ _heading?: string | undefined;
+  constructor(content: string) {
+    this._content = content;
+  }
+  tone(tone: CalloutTone): this {
+    this._tone = tone;
+    return this;
+  }
+  icon(name: string): this {
+    this._icon = name;
+    return this;
+  }
+  heading(heading: string): this {
+    this._heading = heading;
+    return this;
+  }
+}
+export function callout(content: string): Callout {
+  return new Callout(content);
+}
+
+export type PrimeKind = "text" | "html" | "image";
+
+/** A static "prime" display component in a schema — text, raw HTML, or an image. */
+export class Prime {
+  /** @internal */ _kind: PrimeKind;
+  /** @internal */ _content: string;
+  /** @internal */ _alt?: string;
+  constructor(kind: PrimeKind, content: string) {
+    this._kind = kind;
+    this._content = content;
+  }
+  alt(alt: string): this {
+    this._alt = alt;
+    return this;
+  }
+}
+export function prime(text: string): Prime {
+  return new Prime("text", text);
+}
+export function primeHtml(html: string): Prime {
+  return new Prime("html", html);
+}
+export function primeImage(src: string): Prime {
+  return new Prime("image", src);
+}
+
+/** Side-by-side sections. */
+export class FormSplit {
+  /** @internal */ _sections: FormSection[];
+  constructor(sections: FormSection[]) {
+    this._sections = sections;
+  }
+  getFields(): Field[] {
+    return this._sections.flatMap((s) => s.getFields());
+  }
+}
+export function split(sections: FormSection[]): FormSplit {
+  return new FormSplit(sections);
+}
+
+/** A form is an ordered list of layout components and/or loose fields. */
+export type FormComponent = FormSection | FormTabs | Wizard | FormSplit | Callout | Prime | Field;
+
+/** A titled, multi-column block of form fields. */
+export function formSection(heading?: string): FormSection {
+  return new FormSection(heading);
+}
+
+export function isFormSection(c: FormComponent): c is FormSection {
+  return c instanceof FormSection;
+}
+
+/** Collect every field across sections, tab groups, + loose fields, in order. */
+export function flattenFields(components: FormComponent[]): Field[] {
+  const out: Field[] = [];
+  for (const c of components) {
+    if (
+      c instanceof FormSection ||
+      c instanceof FormTabs ||
+      c instanceof Wizard ||
+      c instanceof FormSplit
+    ) {
+      out.push(...c.getFields());
+    } else if (c instanceof Callout || c instanceof Prime) {
+      // Display-only — no fields.
+    } else {
+      out.push(c);
+    }
+  }
+  return out;
+}
+
+/** Normalize components into sections, wrapping loose fields in a default section. */
+export function toFormSections(components: FormComponent[]): FormSection[] {
+  const sections: FormSection[] = [];
+  let loose: Field[] = [];
+  const flush = (): void => {
+    if (loose.length) {
+      sections.push(new FormSection().columns(2).schema(loose));
+      loose = [];
+    }
+  };
+  for (const c of components) {
+    if (c instanceof FormSection) {
+      flush();
+      sections.push(c);
+    } else if (c instanceof Field) {
+      loose.push(c);
+    }
+  }
+  flush();
+  return sections;
+}
+
+/** A renderable layout block. */
+export type FormBlock =
+  | { kind: "section"; section: FormSection }
+  | { kind: "tabs"; tabs: FormTabs }
+  | { kind: "wizard"; wizard: Wizard }
+  | { kind: "split"; split: FormSplit }
+  | { kind: "callout"; callout: Callout }
+  | { kind: "prime"; prime: Prime };
+
+/** Normalize the schema into ordered layout blocks (loose fields → a section). */
+export function toFormLayout(components: FormComponent[]): FormBlock[] {
+  const blocks: FormBlock[] = [];
+  let loose: Field[] = [];
+  const flush = (): void => {
+    if (loose.length) {
+      blocks.push({ kind: "section", section: new FormSection().columns(2).schema(loose) });
+      loose = [];
+    }
+  };
+  for (const c of components) {
+    if (c instanceof FormTabs) {
+      flush();
+      blocks.push({ kind: "tabs", tabs: c });
+    } else if (c instanceof Wizard) {
+      flush();
+      blocks.push({ kind: "wizard", wizard: c });
+    } else if (c instanceof FormSplit) {
+      flush();
+      blocks.push({ kind: "split", split: c });
+    } else if (c instanceof Callout) {
+      flush();
+      blocks.push({ kind: "callout", callout: c });
+    } else if (c instanceof Prime) {
+      flush();
+      blocks.push({ kind: "prime", prime: c });
+    } else if (c instanceof FormSection) {
+      flush();
+      blocks.push({ kind: "section", section: c });
+    } else {
+      loose.push(c);
+    }
+  }
+  flush();
+  return blocks;
+}

package/src/form/editors.ts

@@ -0,0 +1,43 @@
+/**
+ * Tiny client helpers for the editor field types, injected once per form page
+ * (guarded so it defines its globals only once). They are intentionally
+ * dependency-free — no CDN editor — so they survive Flow's DOM morph:
+ *
+ *  - `__kTab`       — tab-to-indent inside the code textarea.
+ *  - `__kMd`        — wrap the markdown textarea selection (bold/italic/link…).
+ *  - `__kRich`      — bind a contenteditable to a hidden, Flow-modeled textarea
+ *                     (writes innerHTML back + dispatches `input` so the server syncs).
+ *  - `__kRichCmd`   — `document.execCommand` for the rich toolbar.
+ *
+ * Each writes to the bound field and dispatches a bubbling `input` event, which is
+ * exactly what Flow's `flow:model` listener consumes — so editor edits round-trip
+ * to the server like any other field.
+ */
+export const EDITOR_SCRIPT = `
+(function(){
+  if (window.__kEditors) return; window.__kEditors = 1;
+  function sync(el){ el.dispatchEvent(new Event('input', { bubbles: true })); }
+  window.__kTab = function(ev, id){
+    if (ev.key !== 'Tab') return; ev.preventDefault();
+    var ta = document.getElementById(id); if (!ta) return;
+    var s = ta.selectionStart, e = ta.selectionEnd;
+    ta.value = ta.value.slice(0, s) + '  ' + ta.value.slice(e);
+    ta.selectionStart = ta.selectionEnd = s + 2; sync(ta);
+  };
+  window.__kMd = function(id, before, after){
+    var ta = document.getElementById(id); if (!ta) return;
+    var s = ta.selectionStart, e = ta.selectionEnd, v = ta.value;
+    ta.value = v.slice(0, s) + before + v.slice(s, e) + after + v.slice(e);
+    sync(ta); ta.focus();
+    ta.selectionStart = s + before.length; ta.selectionEnd = e + before.length;
+  };
+  window.__kRich = function(edId, hId){
+    var ed = document.getElementById(edId), h = document.getElementById(hId);
+    if (!ed || !h || ed.__k) return; ed.__k = 1;
+    if (document.activeElement !== ed) ed.innerHTML = h.value || '';
+    ed.addEventListener('input', function(){ h.value = ed.innerHTML; sync(h); });
+    ed.addEventListener('blur', function(){ h.value = ed.innerHTML; sync(h); });
+  };
+  window.__kRichCmd = function(cmd){ try { document.execCommand(cmd, false, null); } catch (e) {} };
+})();
+`.trim();

package/src/form/index.ts

@@ -0,0 +1,59 @@
+/** Form building blocks — editable schemas for the Create and Edit pages. */
+export {
+  Field,
+  textInput,
+  textarea,
+  select,
+  checkbox,
+  toggle,
+  radio,
+  checkboxList,
+  datePicker,
+  dateTimePicker,
+  timePicker,
+  colorPicker,
+  hidden,
+  tagsInput,
+  keyValue,
+  fileUpload,
+  mediaPicker,
+  slider,
+  toggleButtons,
+  codeEditor,
+  markdownEditor,
+  richEditor,
+  repeater,
+  builder,
+  customField,
+  BuilderBlock,
+  builderBlock,
+} from "./Field.ts";
+export type { FieldType, FieldMode, SelectOption, FieldPredicate } from "./Field.ts";
+export {
+  FormSection,
+  formSection,
+  isFormSection,
+  flattenFields,
+  toFormSections,
+  toFormLayout,
+  FormTab,
+  FormTabs,
+  formTab,
+  formTabs,
+  WizardStep,
+  Wizard,
+  wizardStep,
+  wizard,
+  fieldset,
+  Callout,
+  callout,
+  Prime,
+  prime,
+  primeHtml,
+  primeImage,
+  FormSplit,
+  split,
+} from "./Section.ts";
+export type { FormComponent, FormBlock, CalloutTone, PrimeKind } from "./Section.ts";
+export { makeResourceForm } from "./ResourceForm.ts";
+export type { ResourceFormClass } from "./ResourceForm.ts";

package/src/history.ts

@@ -0,0 +1,151 @@
+/**
+ * Record history — who changed what, and putting it back.
+ *
+ * `@zerotal/audit` already records every create, update and delete on a model
+ * that composes `Auditable`. This turns that into something a person can read on
+ * the record's own page, and — where the change was an update — undo:
+ *
+ *   export class OrderResource extends Resource {
+ *     static override history = true;
+ *   }
+ *
+ * The audit package is resolved lazily, so it stays an optional peer: a resource
+ * that asks for history without it installed simply shows nothing.
+ */
+import { frameworkLog } from "@zerotal/core/logger";
+
+/** One entry in a record's history, already shaped for display. */
+export interface HistoryEntry {
+  id: string;
+  /** `created`, `updated`, `deleted`, `restored`. */
+  event: string;
+  /** Who did it, resolved to a name where possible. */
+  actor: string | null;
+  /** When, as an ISO string. */
+  at: string;
+  /** Field-by-field before/after, for an update. */
+  changes: HistoryChange[];
+  /** True when this entry can be put back — an update with recorded old values. */
+  revertible: boolean;
+}
+
+export interface HistoryChange {
+  field: string;
+  from: unknown;
+  to: unknown;
+}
+
+/** The stored audit row, as `@zerotal/audit` writes it. */
+interface AuditRow {
+  id: unknown;
+  event: string;
+  actorId: number | null;
+  oldValues: Record<string, unknown> | null;
+  newValues: Record<string, unknown> | null;
+  createdAt: unknown;
+}
+
+export interface HistoryOptions {
+  /** Model name the audit rows are filed under — defaults to the resource's model. */
+  type: string;
+  id: unknown;
+  /** How many entries to show. Defaults to 25 — a record page is not an archive. */
+  limit?: number;
+  /** Turn an actor id into a name. Defaults to `#<id>`. */
+  resolveActor?: (id: number) => Promise<string | null> | string | null;
+}
+
+/** Fields that change on every write and say nothing about intent. */
+const NOISE = new Set(["updated_at", "updatedAt", "created_at", "createdAt"]);
+
+/**
+ * Read a record's history, newest first.
+ *
+ * Returns an empty list rather than throwing when the audit package isn't
+ * installed or its table doesn't exist yet — a missing history is a missing
+ * section, not a broken page.
+ */
+export async function recordHistory(options: HistoryOptions): Promise<HistoryEntry[]> {
+  const limit = options.limit ?? 25;
+  try {
+    const mod = (await import(/* @vite-ignore */ "@zerotal/audit" as string)) as {
+      AuditLog?: {
+        forModel?: (
+          type: string,
+          id: unknown,
+        ) => {
+          orderBy: (
+            c: string,
+            d: string,
+          ) => { limit: (n: number) => { get: () => Promise<AuditRow[]> } };
+        };
+      };
+    };
+    const model = mod.AuditLog;
+    if (!model?.forModel) return [];
+
+    const rows = await model
+      .forModel(options.type, options.id)
+      .orderBy("created_at", "desc")
+      .limit(limit)
+      .get();
+
+    return Promise.all(rows.map((row) => toEntry(row, options.resolveActor)));
+  } catch (error) {
+    frameworkLog("admin").warn("Record history unavailable", undefined, error);
+    return [];
+  }
+}
+
+async function toEntry(
+  row: AuditRow,
+  resolveActor?: HistoryOptions["resolveActor"],
+): Promise<HistoryEntry> {
+  const changes = diff(row.oldValues, row.newValues);
+  let actor: string | null = null;
+  if (row.actorId != null) {
+    actor = (await resolveActor?.(row.actorId)) ?? `#${row.actorId}`;
+  }
+
+  return {
+    id: String(row.id),
+    event: row.event,
+    actor,
+    at: stringifyDate(row.createdAt),
+    changes,
+    // Only an update can be put back: a create has nothing to restore to, and a
+    // delete is the restore action's job rather than history's.
+    revertible: row.event === "updated" && changes.length > 0,
+  };
+}
+
+/** Field-by-field difference, ignoring the columns that always move. */
+function diff(
+  before: Record<string, unknown> | null,
+  after: Record<string, unknown> | null,
+): HistoryChange[] {
+  const keys = new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]);
+  const changes: HistoryChange[] = [];
+  for (const field of keys) {
+    if (NOISE.has(field)) continue;
+    const from = before?.[field];
+    const to = after?.[field];
+    if (JSON.stringify(from) === JSON.stringify(to)) continue;
+    changes.push({ field, from, to });
+  }
+  return changes;
+}
+
+/** The values that would put a record back to how it was before an entry. */
+export function revertPayload(entry: HistoryEntry): Record<string, unknown> {
+  const payload: Record<string, unknown> = {};
+  for (const change of entry.changes) payload[change.field] = change.from;
+  return payload;
+}
+
+function stringifyDate(value: unknown): string {
+  if (value instanceof Date) return value.toISOString();
+  const withIso = value as { toISOString?: () => string } | null | undefined;
+  if (typeof withIso?.toISOString === "function") return withIso.toISOString();
+  return String(value ?? "");
+}