@nanobpm/urban 0.58.0 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.58.0",
+	"version": "0.59.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;
@@ -2176,4 +2212,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 () => {