@nanobpm/urban 0.79.0 → 0.81.0

package/src/runtime/browser/fake-dom.test-utils.ts

@@ -0,0 +1,114 @@
+// A small fake DOM for unit-testing the browser runtime's element-building code
+// (the shared form-js renderer and the dataGrid engine-form path) under Node,
+// without a real browser. Records every created node so a test can grab an input
+// or button and fire its listeners. Kept intentionally minimal — it supports only
+// the DOM surface those functions touch.
+
+export class FakeElement {
+  tagName: string;
+  attributes: Record<string, string> = {};
+  className = "";
+  children: Array<FakeElement | { text: string }> = [];
+  textContent = "";
+  hidden = false;
+  disabled = false;
+  value = "";
+  checked = false;
+  type = "";
+  name = "";
+  id = "";
+  listeners: Record<string, Array<(ev: unknown) => unknown>> = {};
+
+  constructor(tag: string) {
+    this.tagName = String(tag).toUpperCase();
+  }
+  setAttribute(k: string, v: unknown): void {
+    this.attributes[k] = String(v);
+    if (k === "class") this.className = String(v);
+  }
+  getAttribute(k: string): string | null {
+    return k in this.attributes ? this.attributes[k] : null;
+  }
+  addEventListener(type: string, fn: (ev: unknown) => unknown): void {
+    (this.listeners[type] ||= []).push(fn);
+  }
+  async fire(type: string, ev: unknown = { preventDefault() {}, stopPropagation() {} }): Promise<void> {
+    for (const fn of this.listeners[type] || []) await fn(ev);
+  }
+  append(...kids: Array<FakeElement | { text: string } | string>): void {
+    for (const kid of kids) {
+      if (typeof kid === "string") {
+        this.children.push({ text: kid });
+        this.textContent += kid;
+      } else if ("text" in kid) {
+        this.children.push(kid);
+        this.textContent += kid.text;
+      } else {
+        this.children.push(kid);
+        this.textContent += kid.textContent || "";
+      }
+    }
+  }
+  appendChild(kid: FakeElement | { text: string }): void {
+    this.append(kid);
+  }
+  replaceChildren(...kids: Array<FakeElement | { text: string } | string>): void {
+    this.children = [];
+    this.textContent = "";
+    this.append(...kids);
+  }
+  get firstChild(): FakeElement | { text: string } | null {
+    return this.children[0] ?? null;
+  }
+  querySelector(selector: string): FakeElement | null {
+    const walk = (nodes: Array<FakeElement | { text: string }>): FakeElement | null => {
+      for (const kid of nodes) {
+        if (kid instanceof FakeElement) {
+          if (fakeSelectorMatches(kid, selector)) return kid;
+          const found = walk(kid.children);
+          if (found) return found;
+        }
+      }
+      return null;
+    };
+    return walk(this.children);
+  }
+}
+
+// Minimal CSS-selector matcher for the DOM surface the browser runtime touches
+// (currently the radio group's `input:checked` lookup). Supports an optional tag
+// name plus `:checked`; any other pseudo/selector deliberately fails to match so
+// unsupported queries surface rather than silently returning a wrong node.
+function fakeSelectorMatches(node: FakeElement, selector: string): boolean {
+  const parts = selector.trim().split(":");
+  const tag = parts[0];
+  if (tag && node.tagName !== tag.toUpperCase()) return false;
+  for (const pseudo of parts.slice(1)) {
+    if (pseudo === "checked") {
+      if (!node.checked) return false;
+    } else {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Install a fake `document` on globalThis; returns a restore function. */
+export function installFakeDom(created: FakeElement[]): () => void {
+  const doc = {
+    createElement: (tag: string) => {
+      const n = new FakeElement(tag);
+      created.push(n);
+      return n;
+    },
+    createTextNode: (text: string) => ({ text: String(text) }),
+    getElementById: () => null,
+    dispatchEvent: () => true,
+  };
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "document");
+  Reflect.set(globalThis, "document", doc);
+  return () => {
+    if (prior) Reflect.defineProperty(globalThis, "document", prior);
+    else Reflect.deleteProperty(globalThis, "document");
+  };
+}

package/src/runtime/browser/formjs.browser.js

@@ -0,0 +1,192 @@
+// @ts-check
+// ── Shared, XSS-safe form-js schema renderer (ADR 0026, extended by #457) ─────
+// This is the ONE client implementation of "render a deployed `.form`'s form-js
+// schema and collect its field values", shared verbatim by BOTH:
+//   • the `taskInbox` surface (surfaces.ts `inboxPage`), and
+//   • the pages `dataGrid` engine-form detail (runtime.browser.js).
+// It used to live inline in surfaces.ts; factoring it here means the two surfaces
+// can never fork the renderer or drift on how a form-js component maps to an input
+// and its submitted value.
+//
+// Like the rest of the browser runtime it is authored/type-checked/linted/tested
+// as real source and served as a generated string artifact (formjs.gen.ts, emitted
+// by scripts/gen-runtime.mjs). It performs NO DOM access at load — every DOM touch
+// is inside a function — so it is import-safe under Node/Deno for unit testing.
+//
+// SECURITY: every value the engine returns is placed via textContent / setAttribute
+// (never innerHTML), so nothing in the form schema can inject markup. The submitted
+// `variables` bag is null-prototype so an engine-supplied component key of
+// `__proto__`/`constructor` lands as a plain own property and can never mutate a
+// prototype (prototype-pollution class).
+
+/** Create an element, setting attributes via setAttribute and text via textContent only.
+ * @param {string} tag
+ * @param {Record<string, string>} [attrs]
+ * @param {string} [text]
+ * @returns {any}
+ */
+function fjEl(tag, attrs, text) {
+  const e = document.createElement(tag);
+  if (attrs) for (const k in attrs) e.setAttribute(k, attrs[k]);
+  if (text != null) e.textContent = text;
+  return e;
+}
+
+/** A plain type="button" with an optional click handler.
+ * @param {string} label
+ * @param {(() => void) | null} [onClick]
+ * @returns {any}
+ */
+function fjBtn(label, onClick) {
+  const b = document.createElement("button");
+  b.type = "button";
+  b.textContent = label;
+  if (onClick) b.addEventListener("click", onClick);
+  return b;
+}
+
+/** Build one form-js component into its field element and (for keyed inputs) a reader
+ * that returns the entered `{ key, value }` or null when blank. Static (keyless)
+ * components render as inert text; layout-only components are skipped (null).
+ * @param {any} c
+ * @returns {{ field: any, read?: () => ({ key: string, value: any } | null) } | null}
+ */
+function buildField(c) {
+  const type = c && c.type;
+  // Static (keyless) components: show text as a paragraph, ignore layout-only ones.
+  if (type === "text") {
+    return { field: fjEl("p", { class: "njf-text" }, typeof c.text === "string" ? c.text : "") };
+  }
+  const key = c && c.key;
+  if (!key) return null;
+  const wrap = fjEl("div", { class: "njf-field" });
+  const label = typeof c.label === "string" && c.label ? c.label : key;
+  if (type === "checkbox") {
+    const input = document.createElement("input");
+    input.type = "checkbox";
+    const lab = fjEl("label", {});
+    lab.appendChild(input);
+    lab.appendChild(document.createTextNode(" " + label));
+    wrap.appendChild(lab);
+    return { field: wrap, read: () => ({ key, value: input.checked }) };
+  }
+  const labelEl = fjEl("label", {}, label);
+  wrap.appendChild(labelEl);
+  let input;
+  if (type === "textarea") {
+    input = document.createElement("textarea");
+  } else if (type === "select") {
+    input = document.createElement("select");
+    input.appendChild(fjEl("option", { value: "" }, "\u2014"));
+    for (const o of Array.isArray(c.values) ? c.values : []) {
+      input.appendChild(fjEl("option", { value: String(o.value) }, String(o.label != null ? o.label : o.value)));
+    }
+  } else if (type === "radio") {
+    const name = "r" + Math.random().toString(36).slice(2);
+    const group = fjEl("div", {});
+    for (const o of Array.isArray(c.values) ? c.values : []) {
+      const rlab = fjEl("label", {});
+      const r = document.createElement("input");
+      r.type = "radio";
+      r.name = name;
+      r.value = String(o.value);
+      rlab.appendChild(r);
+      rlab.appendChild(document.createTextNode(" " + String(o.label != null ? o.label : o.value)));
+      group.appendChild(rlab);
+    }
+    wrap.appendChild(group);
+    return {
+      field: wrap,
+      read: () => {
+        const sel = group.querySelector("input:checked");
+        return sel ? { key, value: sel.value } : null;
+      },
+    };
+  } else {
+    input = document.createElement("input");
+    input.type = type === "number" ? "number" : type === "datetime" ? "datetime-local" : "text";
+  }
+  // Associate the label with the input (for/id) so screen readers announce it on focus.
+  const fieldId = "f" + Math.random().toString(36).slice(2);
+  input.id = fieldId;
+  labelEl.setAttribute("for", fieldId);
+  wrap.appendChild(input);
+  const isNumber = type === "number";
+  return {
+    field: wrap,
+    read: () => {
+      const raw = input.value;
+      if (raw === "" || raw == null) return null;
+      if (isNumber) {
+        const n = Number(raw);
+        // A non-numeric value in a number field is only reachable via tampering (the browser
+        // blanks invalid type=number input). Treat it as absent rather than silently submitting
+        // NaN, which JSON.stringify serializes as null — quietly changing the submitted value.
+        return Number.isFinite(n) ? { key, value: n } : null;
+      }
+      return { key, value: raw };
+    },
+  };
+}
+
+/**
+ * Render a form-js schema into a `<form>` element with a submit + optional cancel.
+ * On submit it assembles every keyed field's value into one null-prototype
+ * `variables` bag and calls `opts.onSubmit(variables)`; a rejected submit re-enables
+ * the button so the operator can retry. `opts.onCancel`, when supplied, wires a
+ * cancel button.
+ * @param {any} schema the parsed form-js document (`{ components: [...] }`)
+ * @param {{ heading?: string, submitLabel?: string, cancelLabel?: string,
+ *           onSubmit: (variables: Record<string, any>) => (void | Promise<void>),
+ *           onCancel?: () => void }} opts
+ * @returns {any} the built <form> element
+ */
+function renderForm(schema, opts) {
+  const form = document.createElement("form");
+  form.className = "njf-form";
+  if (opts.heading) form.appendChild(fjEl("h2", { class: "njf-heading" }, opts.heading));
+  const components = schema && Array.isArray(schema.components) ? schema.components : [];
+  /** @type {Array<() => ({ key: string, value: any } | null)>} */
+  const inputs = [];
+  for (const c of components) {
+    const built = buildField(c);
+    if (!built) continue;
+    form.appendChild(built.field);
+    if (built.read) inputs.push(built.read);
+  }
+  const submit = fjBtn(opts.submitLabel || "Submit", null);
+  submit.type = "submit";
+  const bar = fjEl("div", { class: "njf-actions" });
+  bar.appendChild(submit);
+  if (opts.onCancel) bar.appendChild(fjBtn(opts.cancelLabel || "Cancel", opts.onCancel));
+  form.appendChild(bar);
+  form.addEventListener("submit", (e) => {
+    e.preventDefault();
+    // Null-prototype: field keys come from the engine-supplied form schema. A component
+    // keyed '__proto__'/'constructor' must land as a plain own property (and round-trip
+    // through JSON), never mutate a prototype — no prototype pollution in the page runtime.
+    const variables = Object.create(null);
+    for (const read of inputs) {
+      const kv = read();
+      if (kv) variables[kv.key] = kv.value;
+    }
+    submit.disabled = true;
+    Promise.resolve()
+      .then(() => opts.onSubmit(variables))
+      .catch(() => {
+        submit.disabled = false;
+      });
+  });
+  return form;
+}
+
+export { buildField, renderForm };
+
+// Expose the renderer as a browser global so both self-contained page bundles can
+// reach the ONE implementation without importing it: the taskInbox page embeds this
+// module inline and the pages shell does the same before loading the ES-module
+// runtime, which reads `globalThis.NanoFormJs` lazily when it renders an engine form.
+// Guarded so importing under Node/Deno for tests is a harmless no-op-ish assignment.
+if (typeof globalThis !== "undefined") {
+  /** @type {any} */ (globalThis).NanoFormJs = { buildField, renderForm };
+}

package/src/runtime/browser/formjs.browser.test.ts

@@ -0,0 +1,136 @@
+// Unit tests for the shared form-js renderer (formjs.browser.js, ADR 0026/#457):
+// the ONE client implementation of "render a deployed .form's form-js schema and
+// collect its field values", shared by BOTH the taskInbox surface and the pages
+// dataGrid engine-form detail. Importing the module also registers it as the
+// `globalThis.NanoFormJs` global that the pages runtime consumes.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildField, renderForm } from "./formjs.browser.js";
+import { type FakeElement, installFakeDom } from "./fake-dom.test-utils.ts";
+
+test("NanoFormJs is registered as a browser global on import", () => {
+  const g = Reflect.get(globalThis, "NanoFormJs");
+  assert.ok(g, "importing the module exposes globalThis.NanoFormJs");
+});
+
+test("buildField skips keyless layout components and renders static text", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  assert.equal(buildField({ type: "spacer" }), null, "a keyless, non-text component is skipped");
+  const textOnly = buildField({ type: "text", text: "Read me" });
+  assert.ok(textOnly && !textOnly.read, "a static text component has no reader");
+  assert.equal(textOnly!.field.textContent, "Read me");
+});
+
+test("buildField reads a textfield's entered value, and omits a blank one", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "textfield", key: "note", label: "Note" });
+  assert.ok(built?.read);
+  const input = created.find((n) => n.tagName === "INPUT");
+  assert.ok(input);
+  input!.value = "hello";
+  assert.deepEqual(built!.read!(), { key: "note", value: "hello" });
+  input!.value = "";
+  assert.equal(built!.read!(), null, "a blank field is omitted from the submitted variables");
+});
+
+test("buildField coerces a number field and drops a non-finite value", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "number", key: "qty" });
+  const input = created.find((n) => n.tagName === "INPUT");
+  input!.value = "42";
+  assert.deepEqual(built!.read!(), { key: "qty", value: 42 });
+  input!.value = "not-a-number";
+  assert.equal(built!.read!(), null, "a tampered non-numeric number field is treated as absent, never NaN→null");
+});
+
+test("buildField maps a checkbox to a boolean value", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "checkbox", key: "agree", label: "Agree" });
+  const input = created.find((n) => n.tagName === "INPUT");
+  input!.checked = true;
+  assert.deepEqual(built!.read!(), { key: "agree", value: true });
+});
+
+test("buildField reads the checked radio option (and omits an unselected group)", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({
+    type: "radio",
+    key: "size",
+    label: "Size",
+    values: [
+      { value: "s", label: "Small" },
+      { value: "l", label: "Large" },
+    ],
+  });
+  assert.ok(built?.read);
+  assert.equal(built!.read!(), null, "an unselected radio group is omitted from the submitted variables");
+  const radios = created.filter((n) => n.tagName === "INPUT" && n.type === "radio");
+  assert.equal(radios.length, 2);
+  radios[1].checked = true;
+  assert.deepEqual(built!.read!(), { key: "size", value: "l" }, "read() finds the checked option via querySelector('input:checked')");
+});
+
+test("renderForm submits a null-prototype variables bag (prototype-pollution safe)", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const schema = {
+    components: [
+      { type: "textfield", key: "note" },
+      { type: "textfield", key: "__proto__" },
+    ],
+  };
+  let submitted: Record<string, unknown> | undefined;
+  const form = renderForm(schema, {
+    heading: "Task A",
+    onSubmit: (variables) => {
+      submitted = variables;
+    },
+  });
+  const inputs = created.filter((n) => n.tagName === "INPUT");
+  inputs[0].value = "hi";
+  inputs[1].value = "evil";
+  await form.fire("submit");
+  assert.ok(submitted);
+  assert.equal(Object.getPrototypeOf(submitted!), null, "the variables bag has a null prototype");
+  assert.equal(submitted!.note, "hi");
+  assert.equal(Object.prototype.hasOwnProperty.call(submitted!, "__proto__"), true, "an untrusted key lands as an own property");
+  assert.equal(Object.getPrototypeOf({}), Object.prototype, "no prototype was mutated");
+});
+
+test("renderForm re-enables the submit button when onSubmit rejects (retryable)", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const form = renderForm(
+    { components: [{ type: "textfield", key: "x" }] },
+    {
+      onSubmit: () => Promise.reject(new Error("boom")),
+    },
+  );
+  const submit = created.find((n) => n.tagName === "BUTTON" && n.type === "submit");
+  assert.ok(submit);
+  await form.fire("submit");
+  // The rejected onSubmit settles a microtask later; flush it.
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.equal(submit!.disabled, false, "a failed submit re-enables the button so the operator can retry");
+});
+
+test("renderForm wires a cancel button only when onCancel is supplied", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  renderForm({ components: [] }, { onSubmit: () => {} });
+  assert.equal(created.filter((n) => n.tagName === "BUTTON").length, 1, "no cancel button without onCancel");
+  created.length = 0;
+  let cancelled = false;
+  renderForm({ components: [] }, { onSubmit: () => {}, onCancel: () => (cancelled = true) });
+  const buttons = created.filter((n) => n.tagName === "BUTTON");
+  assert.equal(buttons.length, 2, "a cancel button is added when onCancel is supplied");
+  await buttons[1].fire("click");
+  assert.equal(cancelled, true, "clicking cancel invokes onCancel");
+});

package/src/runtime/browser/runtime.browser.js

@@ -1859,6 +1859,101 @@ function buildDetailForm(f, row, onSuccess) {
   return box;
 }
 
+// Build a dataGrid detail's ENGINE-declared form (ADR 0026, #457). Where
+// buildDetailForm renders a page-authored `detail.form` (fields duplicated from a
+// deployed `.form`), this resolves the row's engine `formKey` and renders the
+// AUTHORITATIVE deployed form-js schema — so one grid can render the several
+// different typed forms carried by a heterogeneous task inbox, and no page-local
+// copy can drift from the deployed form. It reuses the ONE shared form-js renderer
+// (globalThis.NanoFormJs, embedded by the shell) and the shared `/app/actions/form`
+// resolution gate + `/app/actions/complete` completion — the same seams the
+// taskInbox surface uses, no fork.
+//
+// `cfg.formKeyField` (default "form_key") names the row column carrying the engine
+// formKey; `cfg.userTaskKeyField` (default "user_task_key") names the column
+// carrying the user-task key to complete. A row with no formKey degrades to a bare
+// "Complete" button (empty variables), matching taskInbox's no-form fallback.
+/** @param {any} cfg
+ *  @param {Record<string, any>} row
+ *  @param {() => void | Promise<void>} onSuccess
+ *  @returns {HTMLElement|null}
+ */
+function buildEngineForm(cfg, row, onSuccess) {
+  if (!cfg) return null;
+  const userTaskKey = row[cfg.userTaskKeyField || "user_task_key"];
+  // Without a user-task key there is nothing to complete — render nothing rather
+  // than a dead button.
+  if (userTaskKey == null || userTaskKey === "") return null;
+  const formKey = row[cfg.formKeyField || "form_key"];
+  const box = el("div", { class: "pc-subform" });
+  const msg = el("p", { class: "njf-msg", role: "status", "aria-live": "polite" });
+  /** @param {Record<string, any>} variables */
+  const complete = (variables) =>
+    getJSON("/app/actions/complete", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ userTaskKey, variables }),
+    }).then(() => onSuccess());
+  // No renderable form → the bare completion path (parity with taskInbox).
+  const renderBare = () => {
+    const bar = el("div", { class: "njf-actions" });
+    const b = el("button", { class: "pc-btn pc-btn-sm", type: "button" }, "Complete");
+    b.addEventListener("click", async () => {
+      b.disabled = true;
+      msg.className = "njf-msg";
+      msg.textContent = "Sending\u2026";
+      try {
+        await complete(Object.create(null));
+      } catch (e) {
+        b.disabled = false;
+        msg.className = "njf-msg err";
+        msg.textContent = String(e.message || e);
+      }
+    });
+    bar.append(b);
+    box.append(bar, msg);
+  };
+  if (formKey == null || formKey === "") {
+    renderBare();
+    return box;
+  }
+  box.append(el("p", { class: "njf-text" }, "loading form\u2026"));
+  getJSON("/app/actions/form?formKey=" + encodeURIComponent(String(formKey)))
+    .then((f) => {
+      box.replaceChildren();
+      const renderer = /** @type {any} */ (globalThis).NanoFormJs;
+      if (!f || !f.schema || !renderer) {
+        renderBare();
+        return;
+      }
+      box.append(
+        renderer.renderForm(f.schema, {
+          submitLabel: "Complete",
+          /** @param {Record<string, any>} variables */
+          onSubmit: (variables) => {
+            msg.className = "njf-msg";
+            msg.textContent = "Sending\u2026";
+            // Surface completion failures to the operator (parity with the bare-completion
+            // path). Rethrow so renderForm's catch still re-enables the submit button.
+            return complete(variables).catch((e) => {
+              msg.className = "njf-msg err";
+              msg.textContent = String(e.message || e);
+              throw e;
+            });
+          },
+        }),
+        msg,
+      );
+    })
+    .catch((e) => {
+      box.replaceChildren();
+      msg.className = "njf-msg err";
+      msg.textContent = "Failed to load form: " + String(e.message || e);
+      box.append(msg);
+    });
+  return box;
+}
+
 /** @param {any} node */
 function renderDataGrid(node) {
   const p = node.props;
@@ -2162,6 +2257,11 @@ function renderDataGrid(node) {
     }
     const form = buildDetailForm(d.form, row, onSuccess || (() => { document.dispatchEvent(new CustomEvent("pc:refresh")); }));
     if (form) box.append(form);
+    // An engine-declared form (ADR 0026/#457) sits ALONGSIDE the page-authored
+    // `detail.form`, not replacing it: a grid may render the deployed form-js schema
+    // for the row's user task instead of (or in addition to) a hand-authored copy.
+    const engineForm = buildEngineForm(d.engineForm, row, onSuccess || (() => { document.dispatchEvent(new CustomEvent("pc:refresh")); }));
+    if (engineForm) box.append(engineForm);
     return box;
   }
 
@@ -2849,4 +2949,4 @@ function boot() {
 // renderer functions / RENDERERS registry can be imported directly.
 if (typeof document !== "undefined" && document.getElementById("page")) boot();
 
-export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, buildEngineForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };