@nanobpm/urban 0.60.0 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.60.0",
+	"version": "0.61.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

@@ -2054,7 +2054,9 @@ function renderDataGrid(node) {
 // ({ label, page } -> an in-app #/<page> hash link, highlighted when it's the
 // current page) or to an external URL ({ label, href } -> a hardened new-tab
 // link; only http(s) is honoured). With items:"auto" (or omitted) the nav
-// lists every page from the /app/pages index, using each page's title.
+// lists every page from the /app/pages index, using each page's title. An item
+// may also carry a `badge` ({ source, table, filter, tone, refreshMs,
+// hideWhenZero }) that renders a live count pill from the /app/data gateway.
 /** @param {any} item
  * @returns {HTMLAnchorElement|null}
  */
@@ -2073,8 +2075,87 @@ function navLink(item) {
   /** @type {Array<Node|string>} */
   const kids = [];
   if (item.icon != null) kids.push(el("span", { class: "pc-nav-icon" }, String(item.icon)));
-  kids.push(el("span", { class: "pc-nav-label" }, String(item.label != null ? item.label : (item.page || item.href))));
-  return el("a", attrs, ...kids);
+  const labelText = String(item.label != null ? item.label : (item.page || item.href));
+  kids.push(el("span", { class: "pc-nav-label" }, labelText));
+  const link = el("a", attrs, ...kids);
+  // A nav item may carry a live count badge sourced from a datasource (e.g. the
+  // Tasks tab showing how many escalations await a human). It reuses the same
+  // /app/data gateway + .pc-badge tone pills as dataGrid, and polls on refreshMs.
+  // Absent/invalid badge → the link is exactly as before (backward compatible).
+  wireNavBadge(link, labelText, item.badge);
+  return link;
+}
+
+// Attach + drive a nav item's live count badge. Best-effort throughout: a bad
+// config or a failed fetch degrades to no badge, never a broken nav link. The
+// pill is appended hidden and only appears once a fetch yields a count (and, when
+// hideWhenZero, only when that count is > 0). The accessible name of the whole
+// link is kept in sync ("Tasks (3 open)") so assistive tech announces the count,
+// which the small "3" glyph alone would not convey; the pill itself is aria-hidden
+// to avoid a double announcement.
+/** @param {HTMLElement} link
+ * @param {string} baseLabel
+ * @param {any} badge
+ */
+function wireNavBadge(link, baseLabel, badge) {
+  if (!badge || typeof badge !== "object") return;
+  if (typeof badge.table !== "string" || badge.table === "") return;
+  const source = typeof badge.source === "string" && badge.source !== "" ? badge.source : "app";
+  const t = badge.tone;
+  const tone = t === "warn" || t === "ok" || t === "info" || t === "danger" ? t : "danger";
+  const hideWhenZero = badge.hideWhenZero === true;
+  const pill = el("span", { class: "pc-badge pc-nav-badge pc-badge-" + tone, "aria-hidden": "true" });
+  pill.hidden = true;
+  link.append(pill);
+  const filter = Array.isArray(badge.filter) ? badge.filter : [];
+  const paramScoped = filter.some(/** @param {any} f */(f) => f && f.eqParam);
+  const refresh = () => {
+    // A param-scoped badge ("count for the selected entity") with no route param
+    // present would otherwise build the URL with dataUrl baking in an empty PARAM
+    // and query field="", surfacing a wrong count. Match the dataGrid/list pollers:
+    // degrade to 0 (hidden when hideWhenZero) without a request instead.
+    if (paramScoped && PARAM === "") {
+      applyNavBadge(link, pill, baseLabel, hideWhenZero, 0);
+      return;
+    }
+    const url = dataUrl(source, badge.table, filter, null);
+    const countUrl = url + (url.indexOf("?") >= 0 ? "&" : "?") + "count=1";
+    getJSON(countUrl)
+      .then(/** @param {any} res */(res) => applyNavBadge(link, pill, baseLabel, hideWhenZero, res && res.count))
+      .catch(() => applyNavBadge(link, pill, baseLabel, hideWhenZero, NaN));
+  };
+  refresh();
+  const ms = Number(badge.refreshMs);
+  if (Number.isFinite(ms) && ms > 0) {
+    const timer = setInterval(refresh, ms);
+    disposers.push(() => clearInterval(timer));
+  }
+}
+
+// Reflect a fetched count into the pill + the link's accessible name. A
+// non-finite/negative count (a failed or malformed fetch) hides the pill and
+// restores the plain label — the nav degrades quietly rather than showing a
+// broken/"NaN" badge. hideWhenZero also hides the pill at exactly 0.
+/** @param {HTMLElement} link
+ * @param {any} pill
+ * @param {string} baseLabel
+ * @param {boolean} hideWhenZero
+ * @param {any} count
+ */
+function applyNavBadge(link, pill, baseLabel, hideWhenZero, count) {
+  const n = Number(count);
+  if (!Number.isFinite(n) || n < 0 || (n === 0 && hideWhenZero)) {
+    pill.hidden = true;
+    pill.textContent = "";
+    link.setAttribute("aria-label", baseLabel);
+    return;
+  }
+  const shown = String(Math.floor(n));
+  pill.hidden = false;
+  pill.textContent = shown;
+  const aria = baseLabel + " (" + shown + " open)";
+  pill.setAttribute("title", aria);
+  link.setAttribute("aria-label", aria);
 }
 /** @param {HTMLElement} list
  * @param {any[]} items
@@ -2290,4 +2371,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, fmtCellValue, gridCell };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, navLink, wireNavBadge, applyNavBadge, teardown, 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, fmtCellValue, gridCell } from "./runtime.browser.js";
+import { RENDERERS, renderText, navLink, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell } from "./runtime.browser.js";
 
 // ── Minimal fake DOM ────────────────────────────────────────────────────────
 // Just enough of the Element/Document surface that el()/renderText touch:
@@ -158,3 +158,183 @@ test("#327: gridCell applies col.format to the cell text, leaving an unformatted
   const plain = gridCell({ field: "updated_at", header: "Updated" }, { updated_at: iso }, "secondary");
   assert.equal(plain.textContent, iso);
 });
+
+// Find the first descendant span carrying `cls` in a FakeElement tree. Accepts
+// `any` so it can walk either a FakeElement or a renderer's DOM-typed return.
+function findByClass(node: any, cls: string): FakeElement | null {
+  for (const kid of node.children) {
+    if (kid instanceof FakeElement) {
+      if (kid.className.split(/\s+/).includes(cls)) return kid;
+      const deep = findByClass(kid, cls);
+      if (deep) return deep;
+    }
+  }
+  return null;
+}
+
+// Install a fake `fetch` on globalThis returning a fixed JSON body, so navLink's
+// badge poll resolves deterministically without a real network call. Returns a
+// restore fn (register with t.after) so it never leaks into other tests.
+function installFakeFetch(body: unknown): () => void {
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  Reflect.set(globalThis, "fetch", () =>
+    Promise.resolve({ ok: true, json: () => Promise.resolve(body) }),
+  );
+  return () => {
+    if (prior) Reflect.defineProperty(globalThis, "fetch", prior);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  };
+}
+
+test("#338: navLink without a badge is unchanged — no pill, no aria-label override", (t) => {
+  t.after(installFakeDom());
+  const link = navLink({ label: "Home", page: "home" });
+  assert.ok(link, "expected a nav link");
+  assert.equal(link.tagName, "A");
+  assert.equal(findByClass(link, "pc-nav-badge"), null, "no badge pill without item.badge");
+  assert.equal(link.getAttribute("aria-label"), null, "aria-label untouched without a badge");
+});
+
+test("#338: navLink with a badge appends a hidden tone-classed pill and polls a count", async (t) => {
+  t.after(installFakeDom());
+  t.after(installFakeFetch({ count: 3 }));
+  const link = navLink({
+    label: "Tasks",
+    page: "tasks",
+    badge: { source: "app", table: "user_tasks", filter: [], tone: "danger" },
+  });
+  assert.ok(link);
+  const pill = findByClass(link, "pc-nav-badge");
+  assert.ok(pill, "expected a badge pill for item.badge");
+  assert.ok(pill.className.includes("pc-badge"), "reuses the .pc-badge pill");
+  assert.ok(pill.className.includes("pc-badge-danger"), "carries the requested tone class");
+  // The poll resolves asynchronously; flush microtasks then assert the live count.
+  await new Promise((r) => setTimeout(r, 0));
+  assert.equal(pill.hidden, false, "pill shows once a positive count arrives");
+  assert.equal(pill.textContent, "3");
+  assert.equal(link.getAttribute("aria-label"), "Tasks (3 open)", "accessible name carries the count");
+});
+
+test("#338: navLink badge degrades to no pill (never a broken nav) when the fetch fails", async (t) => {
+  t.after(installFakeDom());
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  Reflect.set(globalThis, "fetch", () => Promise.reject(new Error("boom")));
+  t.after(() => {
+    if (prior) Reflect.defineProperty(globalThis, "fetch", prior);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  });
+  const link = navLink({ label: "Tasks", page: "tasks", badge: { table: "user_tasks" } });
+  const pill = findByClass(link, "pc-nav-badge");
+  assert.ok(pill);
+  await new Promise((r) => setTimeout(r, 0));
+  assert.equal(pill.hidden, true, "a failed fetch leaves the pill hidden");
+  assert.equal(pill.textContent, "");
+});
+
+test("#338: applyNavBadge honours hideWhenZero and mirrors the count into the accessible name", (t) => {
+  const restore = installFakeDom();
+  t.after(restore);
+  const doc: { createElement: (tag: string) => FakeElement } = Reflect.get(globalThis, "document");
+  // The renderer's applyNavBadge is DOM-typed (HTMLElement); the fake elements
+  // satisfy the subset it touches, so the locals are `any` (no banned `as` cast).
+  const mk = (): { link: any; pill: any } => ({ link: doc.createElement("a"), pill: doc.createElement("span") });
+
+  // Positive count → visible pill + "(n open)" accessible name.
+  const a = mk();
+  applyNavBadge(a.link, a.pill, "Tasks", true, 5);
+  assert.equal(a.pill.hidden, false);
+  assert.equal(a.pill.textContent, "5");
+  assert.equal(a.link.getAttribute("aria-label"), "Tasks (5 open)");
+
+  // Zero with hideWhenZero → nothing (a quiet nav stays clean), label reset.
+  const b = mk();
+  applyNavBadge(b.link, b.pill, "Tasks", true, 0);
+  assert.equal(b.pill.hidden, true);
+  assert.equal(b.pill.textContent, "");
+  assert.equal(b.link.getAttribute("aria-label"), "Tasks");
+
+  // Zero WITHOUT hideWhenZero → the pill still shows "0".
+  const c = mk();
+  applyNavBadge(c.link, c.pill, "Tasks", false, 0);
+  assert.equal(c.pill.hidden, false);
+  assert.equal(c.pill.textContent, "0");
+
+  // A non-finite/malformed count degrades to hidden, never "NaN".
+  const d = mk();
+  applyNavBadge(d.link, d.pill, "Tasks", false, Number.NaN);
+  assert.equal(d.pill.hidden, true);
+  assert.equal(d.pill.textContent, "");
+});
+
+test("#338: wireNavBadge registers its poll interval with the per-page teardown so page switches stop it", (t) => {
+  // Defect-class guard: any refreshMs poller MUST clear its interval on teardown,
+  // or navigating between pages leaks a setInterval that fetches forever and pins
+  // the old link/pill alive via closure. This drives wireNavBadge with stubbed
+  // timers + fetch and asserts teardown() actually clears the interval it started.
+  const restore = installFakeDom();
+  t.after(restore);
+  const doc: { createElement: (tag: string) => FakeElement } = Reflect.get(globalThis, "document");
+
+  const cleared: number[] = [];
+  let nextId = 1;
+  const started: number[] = [];
+  const priorSet = Reflect.getOwnPropertyDescriptor(globalThis, "setInterval");
+  const priorClear = Reflect.getOwnPropertyDescriptor(globalThis, "clearInterval");
+  const priorFetch = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  Reflect.set(globalThis, "setInterval", (): number => {
+    const id = nextId++;
+    started.push(id);
+    return id;
+  });
+  Reflect.set(globalThis, "clearInterval", (id: number): void => {
+    cleared.push(id);
+  });
+  // getJSON awaits fetch(); a rejection is swallowed by wireNavBadge's .catch, so
+  // the immediate poll degrades quietly without an unhandled rejection.
+  Reflect.set(globalThis, "fetch", () => Promise.reject(new Error("offline")));
+  t.after(() => {
+    if (priorSet) Reflect.defineProperty(globalThis, "setInterval", priorSet);
+    if (priorClear) Reflect.defineProperty(globalThis, "clearInterval", priorClear);
+    if (priorFetch) Reflect.defineProperty(globalThis, "fetch", priorFetch);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  });
+
+  const link: any = doc.createElement("a");
+  wireNavBadge(link, "Tasks", { source: "app", table: "tasks", refreshMs: 5000 });
+  assert.equal(started.length, 1, "wireNavBadge should start exactly one poll interval");
+  assert.equal(cleared.length, 0, "interval must not be cleared before teardown");
+
+  teardown();
+  assert.deepEqual(cleared, started, "teardown() must clear the interval wireNavBadge started");
+});
+
+test("#338: a param-scoped nav badge with no route param degrades to 0 without querying field=\"\"", (t) => {
+  // Defect-class guard mirroring the dataGrid/list pollers: a badge whose filter is
+  // param-scoped ({ eqParam: true }) but with an empty route PARAM must NOT build a
+  // where=field: query (which the server reads as field equals empty string and can
+  // surface a wrong count). It must short-circuit to a 0/hidden badge with no fetch.
+  const restore = installFakeDom();
+  t.after(restore);
+  const doc: { createElement: (tag: string) => FakeElement } = Reflect.get(globalThis, "document");
+
+  let fetchCalls = 0;
+  const priorFetch = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  Reflect.set(globalThis, "fetch", () => {
+    fetchCalls++;
+    return Promise.reject(new Error("should not fetch"));
+  });
+  t.after(() => {
+    if (priorFetch) Reflect.defineProperty(globalThis, "fetch", priorFetch);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  });
+
+  // PARAM defaults to "" (no renderPage has run), so a param-scoped badge is the
+  // empty-selection case the guard must short-circuit.
+  const link: any = doc.createElement("a");
+  wireNavBadge(link, "Tasks", { source: "app", table: "tasks", filter: [{ field: "owner", eqParam: true }] });
+
+  assert.equal(fetchCalls, 0, "param-scoped badge with empty PARAM must not issue a count query");
+  const pill: any = link.children[link.children.length - 1];
+  assert.equal(pill.textContent, "0", "badge degrades to 0 rather than an empty-string-filtered count");
+  assert.equal(pill.hidden, false, "0 is shown (hideWhenZero is off) rather than a stale count");
+});

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

@@ -1047,6 +1047,33 @@ test("GET /app/data whitelists filter columns", async () => {
   assert.equal(bad.status, 400);
 });
 
+test("#338: GET /app/data?count=1 returns a COUNT(*), honouring the same whitelisted where", async () => {
+  // count mode issues a COUNT(*) (not SELECT *) so a nav badge can show a live
+  // number without transferring rows; the where filter is still column-whitelisted.
+  let seenSql = "";
+  let seenParams: unknown[] = [];
+  const { router } = build({
+    query: async (sql: string, params?: unknown[]) => {
+      if (/PRAGMA table_info/i.test(sql)) {
+        return [{ name: "id" }, { name: "status" }, { name: "total" }];
+      }
+      seenSql = sql;
+      seenParams = params ?? [];
+      return [{ n: 7 }];
+    },
+  });
+  const res = await router(req("GET", "/app/data/app/orders", { query: "count=1&where=status:new" }));
+  assert.equal(res.status, 200);
+  assert.equal(JSON.parse(res.body ?? "{}").count, 7);
+  assert.match(seenSql, /SELECT COUNT\(\*\) AS n FROM/i, "count mode must issue a COUNT(*), not SELECT *");
+  assert.doesNotMatch(seenSql, /LIMIT/i, "a count has no LIMIT");
+  assert.deepEqual(seenParams, ["new"], "the where value is still bound as a parameter");
+
+  // An unknown filter column is rejected in count mode too (no whitelist bypass).
+  const bad = await router(req("GET", "/app/data/app/orders", { query: "count=1&where=evil:1" }));
+  assert.equal(bad.status, 400);
+});
+
 test("POST /app/actions/start/<process> creates an instance", async () => {
   const { router, calls } = build();
   const res = await router(req("POST", "/app/actions/start/my-proc", { body: { variables: { a: 1 } } }));

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

@@ -92,6 +92,15 @@ function javascript(
  * (checked against `schema()`), so `/app/data/:table` can never inject SQL. */
 const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+// A query flag (e.g. ?count=1) is "on" when present and not one of the falsy
+// spellings. A bare `?count` (empty string) still counts as on, so a caller can
+// opt in without inventing a value.
+function isTruthyParam(v: string | null): boolean {
+  if (v === null) return false;
+  const s = v.trim().toLowerCase();
+  return s !== "0" && s !== "false" && s !== "no";
+}
+
 /**
  * Build the page-runtime routes over an injected datasource + engine. Pure over its deps
  * so it is unit-testable without a real host/server (see pages.test.ts).
@@ -272,6 +281,24 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
         orderSql = ` ORDER BY ${quoteIdent(field)} ${dir}`;
       }
       const whereSql = clauses.length ? ` WHERE ${clauses.join(" AND ")}` : "";
+      // ?count=1 → a lightweight COUNT(*) instead of the rows themselves. The same
+      // whitelisted where clauses apply, so a caller (e.g. a nav item's live count
+      // badge) gets exactly the number of matching rows without transferring or
+      // materialising them. ORDER BY / LIMIT are irrelevant to a count and skipped.
+      if (isTruthyParam(req.query.get("count"))) {
+        try {
+          const rows = await db.query(
+            `SELECT COUNT(*) AS n FROM ${quoteIdent(table)}${whereSql}`,
+            params,
+          );
+          const first = Array.isArray(rows) && rows.length > 0 ? rows[0] : undefined;
+          const rawCount = isRecord(first) ? first.n : 0;
+          const count = Number(rawCount);
+          return json({ count: Number.isFinite(count) ? count : 0 });
+        } catch (e) {
+          return json({ error: errorMessage(e) }, 500);
+        }
+      }
       try {
         const rows = await db.query(
           `SELECT * FROM ${quoteIdent(table)}${whereSql}${orderSql} LIMIT ${rowLimit}`,
@@ -682,6 +709,11 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-nav-link:hover { background:var(--nano-hover); color:var(--nano-text); }
 .pc-nav-link.active { background:var(--nano-accent); color:var(--nano-on-accent); }
 .pc-nav-icon { line-height:1; }
+/* A nav item's live count pill (item.badge). Slightly more compact than the base
+   .pc-badge so it sits neatly beside a nav label; [hidden] must win over the
+   .pc-badge inline-flex display so hideWhenZero / a failed fetch truly hides it. */
+.pc-nav-badge { min-width:1.1rem; height:1.1rem; font-size:.68rem; padding:0 .35rem; margin-left:.1rem; }
+.pc-nav-badge[hidden] { display:none; }
 .pc-nav-empty { color:var(--nano-text-faint); font-size:.85rem; padding:.4rem .7rem; }
 /* The per-row mobile "More" toggle (revealing mobile:{priority:"hidden"} columns)
    only exists for the card view — hidden on the desktop table, shown by the