@nanobpm/urban 0.58.0 → 0.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.58.0",
+	"version": "0.60.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

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

@@ -321,6 +321,36 @@ function interpTemplate(tpl, row) {
       })
     : tpl;
 }
+
+// Format a single-field cell value per a column's opt-in `col.format` (issue
+// #327). This runs in the browser, so it is the ONLY place that can render a
+// stored UTC ISO timestamp in the VIEWER'S local timezone — the server never
+// knows the viewer's zone, so a server-formatted string would always be wrong
+// for someone. Currently the sole format is "datetime": a parseable ISO/date
+// value → "11:42am Aug 19" (h:mm + lowercase am/pm, then short-month day), both
+// parts in local time. Defensive by construction: an empty value, an unparseable
+// date, or any unknown format returns the raw text verbatim — a mis-set format
+// never blanks a cell or throws, matching how an unrecognised link.kind degrades
+// to plain text. Display-only: the untransformed rawText still drives the badge
+// gate/tooltip and any sort/groupBy (those key off the real field).
+/** @param {any} format
+ * @param {string} raw
+ * @returns {string} */
+function fmtCellValue(format, raw) {
+  if (format !== "datetime" || raw === "") return raw;
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime())) return raw;
+  // Present in a stable en-US format ("11:42am Aug 19") regardless of the
+  // viewer's locale ordering (e.g. en-GB would emit "19 Aug"), while the ABSENCE
+  // of a `timeZone` option keeps both parts in the viewer's LOCAL zone. hour12
+  // forces am/pm; the replace lowercases "AM"/"a.m."/… to "am"/"pm" and drops the
+  // separating space so the output is exactly "11:42am".
+  const time = d
+    .toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit", hour12: true })
+    .replace(/\s*([AaPp])\.?\s*[Mm]\.?$/, (_m, p) => p.toLowerCase() + "m");
+  const date = d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+  return time + " " + date;
+}
 /** @param {any} node */
 function renderText(node) {
   const v = node.props.variant;
@@ -641,9 +671,15 @@ function gridCell(col, row, role) {
   // field-derived defaults. Kept separate from the (possibly templated) display
   // text so a template never re-lights or blanks a badge.
   const rawText = row[col.field] == null ? "" : String(row[col.field]);
+  // Per-column display format (issue #327): an opt-in `col.format` transforms the
+  // single-field value for display only (e.g. "datetime" → the viewer's local
+  // time). rawText above stays untransformed so the badge gate/tooltip and any
+  // sort/groupBy still key off the real field. A col.template composes its own
+  // {{field}} tokens and therefore wins over the formatted field text below.
+  const fieldText = col.format ? fmtCellValue(col.format, rawText) : rawText;
   // Visible text: a col.template (interpolated from the row) wins over the
-  // raw field value, else the field value is shown verbatim.
-  const text = typeof col.template === "string" ? interpTemplate(col.template, row) : rawText;
+  // formatted/raw field value, else the field value is shown verbatim.
+  const text = typeof col.template === "string" ? interpTemplate(col.template, row) : fieldText;
   // 1. badge — a compact status indicator. When the row's field value is
   //    non-empty (truthy after trimming) render a small circular badge (e.g. a
   //    red "1" dot flagging an incident) whose tooltip is the full field text;
@@ -1595,10 +1631,13 @@ function renderDataGrid(node) {
   }
 
   /** @param {Record<string, any>} row
+   * @param {any} formCfg the panel's own form config (top-level or child grid); a
+   *   missing/undefined form means this panel has no form — it must NOT fall back to
+   *   the top-level grid's form, or a child panel would render the parent's form.
    * @returns {HTMLElement|null}
    */
-  function detailForm(row) {
-    const f = detail.form;
+  function detailForm(row, formCfg) {
+    const f = formCfg;
     if (!f || !row[f.showWhenField]) return null;
     const box = el("div", { class: "pc-subform" });
     if (f.title) box.append(el("div", { class: "pc-subform-title" }, f.title));
@@ -1637,21 +1676,61 @@ function renderDataGrid(node) {
     const ccols = cg.columns || [];
     const croles = classifyColumns(ccols);
     const chasHidden = croles.indexOf("hidden") >= 0;
+    // Per-row expansion for child grids: a `detail` (alias `expandable`) block
+    // gives each child row a chevron that reveals the same detailPanel() content
+    // the top-level grid uses (link + fields + nested child grids + form). Rows are
+    // collapsed by default; `detail.defaultCollapsed`/`detail.collapsed` (default
+    // true) seeds the initial state, and — when the child grid declares a `rowKey`
+    // — the per-row collapse is persisted in localStorage keyed by page + node +
+    // parent rowKey + child rowKey, so it survives the top-level grid's refresh
+    // poll (which rebuilds this whole subtree) and a full reload, mirroring how
+    // groupBy group-collapse is persisted. Absent a `detail` block the child grid
+    // is byte-for-byte unchanged (backward compatible).
+    const cdetail = cg.detail || cg.expandable || null;
+    const chasExpand = cdetail != null;
+    const cextra = (cg.lazyField ? 1 : 0) + (chasExpand ? 1 : 0);
+    const cdefaultCollapsed = chasExpand
+      ? (cdetail.defaultCollapsed != null
+        ? !!cdetail.defaultCollapsed
+        : cdetail.collapsed != null
+          ? !!cdetail.collapsed
+          : true)
+      : true;
+    const cnodeId = node.id || p.title || "grid";
+    const cchildId = cg.node || cg.table || cg.title || "child";
+    // The parent-row discriminator is the value this child grid is queried by
+    // (row[cg.parentField]) — NOT the top-level grid's rowKey. That keeps per-row
+    // collapse state unique per parent row even when the parent grid declares no
+    // rowKey (rowKeyOf(row) would then be null and every parent row would collide
+    // under the literal "_"). When no parent discriminator is available there is no
+    // safe key, so persistence is disabled (ckeyBase null) instead of colliding.
+    const cparentKey = cg.parentField != null && row[cg.parentField] != null
+      ? String(row[cg.parentField]) : null;
+    const ckeyBase = cparentKey == null ? null
+      : "pc:collapsed:" + CURRENT + ":" + cnodeId + ":" + cchildId + ":" + cparentKey + ":r:";
+    /** @param {Record<string, any>} cr @returns {string|null} */
+    const crowKeyOf = (cr) => {
+      if (!cg.rowKey) return null;
+      const v = cr[cg.rowKey];
+      return v == null ? null : String(v);
+    };
     const cbody = el("tbody", {});
-    const ccolgroup = buildColgroup(ccols, cg.lazyField ? 1 : 0);
+    const ccolgroup = buildColgroup(ccols, cextra);
     const cthead = el("thead", {}, el("tr", {}, ...ccols.map((c) => el("th", {}, c.header || c.field)),
-      ...(cg.lazyField ? [el("th", {}, "")] : [])));
+      ...(cg.lazyField ? [el("th", {}, "")] : []),
+      ...(chasExpand ? [el("th", {}, "")] : [])));
     const ctable = ccolgroup
       ? el("table", { class: "pc-grid" }, ccolgroup, cthead, cbody)
       : el("table", { class: "pc-grid" }, cthead, cbody);
     wrap.append(ctable);
-    /** @type {any} */
-    var cspan;
+    // Compute the colspan eagerly (before the fetch) so BOTH the success path and
+    // the catch's error row have a valid, table-spanning colspan — if getJSON()
+    // throws, a lazily-assigned cspan would still be undefined here.
+    const cspan = String((ccols.length || 1) + cextra);
     try {
       /** @type {{ rows: Array<Record<string, any>> }} */
       const { rows } = await getJSON(dataUrl(cg.source || "app", cg.table,
         [{ field: cg.childField, eq: row[cg.parentField] }], cg.orderBy));
-      cspan = String((ccols.length || 1) + (cg.lazyField ? 1 : 0));
       if (!rows.length) {
         cbody.append(el("tr", {}, el("td", { colspan: cspan }, "None")));
       }
@@ -1673,6 +1752,33 @@ function renderDataGrid(node) {
           }
           cells.push(cell);
         }
+        // Per-row expander cell (trailing, after any lazyField cell): a chevron
+        // that reveals this row's detailPanel in a following full-width row. The
+        // panel is built lazily on first open (and eagerly when the row starts
+        // expanded), matching the top-level grid.
+        /** @type {any} */
+        let cdtr = null;
+        if (chasExpand) {
+          const crk = crowKeyOf(cr);
+          const cskey = ckeyBase && crk != null ? ckeyBase + crk : null;
+          const collapsed = cskey ? readCollapsed(cskey, cdefaultCollapsed) : cdefaultCollapsed;
+          const ctoggle = el("button", { class: "pc-btn pc-btn-sm pc-chevron" }, collapsed ? "▸" : "▾");
+          cells.push(el("td", { class: "pc-row-actions" }, ctoggle));
+          cdtr = el("tr", { hidden: collapsed ? "" : null }, el("td", { colspan: cspan }));
+          let built = false;
+          const build = () => {
+            if (!built) { built = true; cdtr.firstChild.append(detailPanel(cr, cdetail)); }
+          };
+          if (!collapsed) build();
+          ctoggle.addEventListener("click", /** @param {MouseEvent} ev */ (ev) => {
+            ev.stopPropagation();
+            const open = cdtr.hidden;
+            cdtr.hidden = !open;
+            ctoggle.textContent = open ? "▾" : "▸";
+            if (open) build();
+            if (cskey) writeCollapsed(cskey, !open);
+          });
+        }
         // Child grids classify columns into the same mobile roles (including
         // "hidden") as the top-level grid, so they need the same per-row "More"
         // toggle — without it a mobile:{priority:"hidden"} child column would be
@@ -1680,6 +1786,7 @@ function renderDataGrid(node) {
         const ctr = el("tr", {}, ...cells);
         if (chasHidden) ctr.append(mobileMoreCell(ctr));
         cbody.append(ctr);
+        if (cdtr) cbody.append(cdtr);
       }
     } catch (e) {
       cbody.append(el("tr", {}, el("td", { colspan: cspan }, String(e.message || e))));
@@ -1687,11 +1794,18 @@ function renderDataGrid(node) {
     return wrap;
   }
 
-  /** @param {Record<string, any>} row */
-  function detailPanel(row) {
+  /** Build an expandable-row detail panel. Used by the top-level grid (with the
+   * closure `detail` config) and by child grids (which pass their own `cg.detail`
+   * as `cfg`) so both share one look/behaviour — link, fields, nested child grids
+   * and an optional escalation form.
+   * @param {Record<string, any>} row
+   * @param {any} [cfg] detail config; defaults to the top-level grid's `detail`
+   */
+  function detailPanel(row, cfg) {
+    const d = cfg || detail;
     const box = el("div", { class: "pc-detail" });
-    if (detail.linkField && row[detail.linkField]) {
-      const href = String(row[detail.linkField]);
+    if (d.linkField && row[d.linkField]) {
+      const href = String(row[d.linkField]);
       // Render as a link only for http(s); anything else (e.g. a javascript: URL
       // smuggled through row data) is shown as inert text. External links get
       // rel="noopener noreferrer" so the opened page can't reach window.opener.
@@ -1701,17 +1815,17 @@ function renderDataGrid(node) {
         box.append(el("span", { class: "pc-link" }, href));
       }
     }
-    for (const df of detail.fields || []) {
+    for (const df of d.fields || []) {
       box.append(el("div", { class: "pc-detail-field" },
         el("span", { class: "pc-detail-label" }, df.label || df.field),
         el("span", {}, row[df.field] == null ? "" : String(row[df.field]))));
     }
-    for (const cg of detail.children || []) {
+    for (const cg of d.children || []) {
       const holder = el("div", {});
       box.append(holder);
       childGrid(cg, row).then((w) => holder.replaceChildren(w));
     }
-    const form = detailForm(row);
+    const form = detailForm(row, d.form);
     if (form) box.append(form);
     return box;
   }
@@ -2176,4 +2290,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 };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, fmtCellValue, gridCell };

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

@@ -7,7 +7,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { PAGE_NODE_TYPES } from "@nanobpm/nano-app-schema";
-import { RENDERERS, renderText } from "./runtime.browser.js";
+import { RENDERERS, renderText, fmtCellValue, gridCell } from "./runtime.browser.js";
 
 // ── Minimal fake DOM ────────────────────────────────────────────────────────
 // Just enough of the Element/Document surface that el()/renderText touch:
@@ -116,3 +116,45 @@ test("#291: renderText degrades to empty text (never throws) on a missing text p
   assert.equal(node.tagName, "P");
   assert.equal(node.textContent, "");
 });
+
+test('#327: fmtCellValue "datetime" renders an ISO timestamp in the viewer\'s local time as "h:mmam Mon D"', () => {
+  const iso = "2026-08-18T23:42:47.788Z";
+  const out = fmtCellValue("datetime", iso);
+  // Shape: h:mm + lowercase am/pm (no separating space), then short-month day.
+  assert.match(out, /^\d{1,2}:\d{2}(am|pm) [A-Z][a-z]{2} \d{1,2}$/, `unexpected shape: ${out}`);
+  // Local, not UTC: the hour/minute/am-pm/day track the runner's local zone, so
+  // the assertion is timezone-independent (derives the expectation from the same
+  // Date in local time) yet still proves the value isn't rendered as raw UTC.
+  const d = new Date(iso);
+  let h = d.getHours() % 12;
+  if (h === 0) h = 12;
+  const mm = String(d.getMinutes()).padStart(2, "0");
+  const ampm = d.getHours() < 12 ? "am" : "pm";
+  assert.ok(out.startsWith(`${h}:${mm}${ampm} `), `local time prefix wrong: ${out}`);
+  assert.ok(out.endsWith(` ${d.getDate()}`), `local day suffix wrong: ${out}`);
+});
+
+test("#327: fmtCellValue passes through empty, unparseable, and unknown-format values verbatim (never blank/throw)", () => {
+  assert.equal(fmtCellValue("datetime", ""), "");
+  assert.equal(fmtCellValue("datetime", "not-a-date"), "not-a-date");
+  // An unknown format is a no-op — a mis-set column shows its raw value, not blank.
+  assert.equal(fmtCellValue("nope", "2026-08-18T23:42:47.788Z"), "2026-08-18T23:42:47.788Z");
+});
+
+test("#327: gridCell applies col.format to the cell text, leaving an unformatted column verbatim", (t) => {
+  t.after(installFakeDom());
+  const iso = "2026-08-18T23:42:47.788Z";
+  const formatted = gridCell(
+    { field: "updated_at", header: "Updated", format: "datetime" },
+    { updated_at: iso },
+    "secondary",
+  );
+  assert.match(
+    formatted.textContent,
+    /^\d{1,2}:\d{2}(am|pm) [A-Z][a-z]{2} \d{1,2}$/,
+    `cell not local-formatted: ${formatted.textContent}`,
+  );
+  // No `format` → the field value renders exactly as stored (backward compatible).
+  const plain = gridCell({ field: "updated_at", header: "Updated" }, { updated_at: iso }, "secondary");
+  assert.equal(plain.textContent, iso);
+});

package/src/runtime/core/modules/pages.test.ts

@@ -378,10 +378,12 @@ test("renderer interpolates a column's per-cell template into DOM text (#214)",
   // resolving to prototype cruft — guard the own-property gate explicitly.
   assert.match(js, /Object\.prototype\.hasOwnProperty\.call\(row, key\) \? row\[key\] : null/);
   assert.match(js, /return v == null \? "" : String\(v\);/);
-  // gridCell keeps the raw single-field value separate (drives the badge gate)
-  // and lets a string template win for the rendered text.
+  // gridCell keeps the raw single-field value separate (drives the badge gate),
+  // applies an opt-in col.format to the field text (#327), and lets a string
+  // template win for the rendered text over that formatted/raw field value.
   assert.match(js, /const rawText = row\[col\.field\] == null \? "" : String\(row\[col\.field\]\);/);
-  assert.match(js, /const text = typeof col\.template === "string" \? interpTemplate\(col\.template, row\) : rawText;/);
+  assert.match(js, /const fieldText = col\.format \? fmtCellValue\(col\.format, rawText\) : rawText;/);
+  assert.match(js, /const text = typeof col\.template === "string" \? interpTemplate\(col\.template, row\) : fieldText;/);
 });
 
 test("renderer renders a column's subtitle as a muted second line, never an href (#257)", async () => {
@@ -1312,6 +1314,84 @@ test("child grids reuse the same per-row More toggle for hidden columns (#268)",
   assert.match(js, /if \(chasHidden\) ctr\.append\(mobileMoreCell\(ctr\)\);/);
 });
 
+test("child grids support per-row detail expansion, collapsed by default (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // A child grid opts into per-row expansion with a `detail` (alias `expandable`)
+  // block that reuses the top-level grid's detailPanel() — so a nested table (e.g.
+  // a Convergence "Rounds" child) can render each row as an expandable, collapsed
+  // affordance instead of dumping the whole history flat.
+  assert.match(js, /const cdetail = cg\.detail \|\| cg\.expandable \|\| null;/);
+  assert.match(js, /const chasExpand = cdetail != null;/);
+  // The expander shares the top-level detail look: a pc-chevron button in a
+  // pc-row-actions cell, revealing detailPanel(cr, cdetail) in a following row.
+  assert.match(js, /class: "pc-btn pc-btn-sm pc-chevron" \}, collapsed \? "▸" : "▾"/);
+  assert.match(js, /cells\.push\(el\("td", \{ class: "pc-row-actions" \}, ctoggle\)\);/);
+  assert.match(js, /cdtr\.firstChild\.append\(detailPanel\(cr, cdetail\)\)/);
+  // Rows are collapsed by default; detail.defaultCollapsed/detail.collapsed (both
+  // defaulting to true) seed the initial state.
+  assert.match(js, /cdetail\.defaultCollapsed != null/);
+  assert.match(js, /cdetail\.collapsed != null/);
+  // detailPanel is now config-parametrised so the top-level grid and child grids
+  // share one implementation (link + fields + nested children + form).
+  assert.match(js, /function detailPanel\(row, cfg\)/);
+  assert.match(js, /const d = cfg \|\| detail;/);
+});
+
+test("child-grid per-row collapse state is persisted across the refresh poll (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The top-level grid rebuilds each child grid on every refreshMs poll, so an
+  // open row would collapse on the next tick without durable state. Per-row
+  // collapse is persisted in localStorage — keyed by page + node + parent
+  // discriminator + child rowKey — via the same readCollapsed/writeCollapsed
+  // helpers groupBy group-collapse uses, so it survives both the poll and a full
+  // reload.
+  assert.match(js, /const cskey = ckeyBase && crk != null \? ckeyBase \+ crk : null;/);
+  assert.match(js, /readCollapsed\(cskey, cdefaultCollapsed\)/);
+  assert.match(js, /if \(cskey\) writeCollapsed\(cskey, !open\);/);
+  assert.match(js, /"pc:collapsed:" \+ CURRENT \+ ":" \+ cnodeId \+ ":" \+ cchildId/);
+});
+
+test("child-grid collapse key is scoped by row[cg.parentField], not the parent grid's rowKey (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The parent-row discriminator in the localStorage key MUST be the value the
+  // child grid is queried by (row[cg.parentField]) — NOT rowKeyOf(row), which is
+  // null whenever the top-level grid declares no `rowKey`. With the old rowKeyOf
+  // key every parent row collapsed under the literal "_", so opening one parent's
+  // child row silently toggled the same-keyed child row under every other parent.
+  assert.match(
+    js,
+    /const cparentKey = cg\.parentField != null && row\[cg\.parentField\] != null\s*\?\s*String\(row\[cg\.parentField\]\) : null;/,
+  );
+  // No safe key ⇒ persistence disabled (ckeyBase null), never a colliding "_".
+  assert.match(js, /const ckeyBase = cparentKey == null \? null/);
+  assert.doesNotMatch(js, /cparentKey == null \? "_" : cparentKey/);
+});
+
+test("child-grid detail panel never falls back to the top-level grid's form (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // detailPanel(cr, cdetail) renders a child grid's own detail config. Its form is
+  // detailForm(row, d.form): when the child config declares no `form` the panel
+  // must have NO form — it must NOT implicitly reuse the top-level grid's
+  // detail.form. So detailForm uses its argument verbatim rather than falling back
+  // to `detail && detail.form` when the argument is undefined.
+  assert.match(js, /function detailForm\(row, formCfg\) \{\s*const f = formCfg;/);
+  assert.doesNotMatch(js, /formCfg !== undefined \? formCfg : \(detail && detail\.form\)/);
+});
+
+test("child-grid fetch failure renders a full-width error row (#332)", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  const js = res.body ?? "";
+  // The child grid's colspan is computed eagerly, BEFORE the getJSON() fetch, so
+  // the catch path's error row (colspan: cspan) spans the whole table even when
+  // the fetch throws. A lazily-assigned cspan would be undefined in the catch.
+  assert.match(js, /const cspan = String\(\(ccols\.length \|\| 1\) \+ cextra\);\s*try \{/);
+  assert.match(js, /\} catch \(e\) \{\s*cbody\.append\(el\("tr", \{\}, el\("td", \{ colspan: cspan \}/);
+});
+
 test("the renderer honours an optional Tier-2 page-level mobile layout variant (#268)", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   const js = res.body ?? "";