@promptctl/cc-candybar 1.7.3 → 1.8.0

package/src/render/menu.ts

@@ -0,0 +1,120 @@
+// [LAW:locality-or-seam] The runtime half of the `{{ menu }}` seam — sibling to
+// `{{ action }}`/`{{ picker }}`. A menu is a self-contained disclosure: an inline
+// glyph that toggles open/closed, and (when open) its body — a picker grid —
+// dropped onto the next line. It composes the two existing helpers, adding only
+// the disclosure: the glyph is realized through the synthesized cycle action
+// (`renderAction`), the body through the one picker renderer (`renderPicker`).
+//
+// [LAW:one-source-of-truth] A menu is CONTEXT-FREE in the template but its
+// accordion identity (which row key, which member name) is a fact about WHERE its
+// host segment sits — derived once in menu-keys and published into this runtime
+// by the render walk before each segment's template evaluates. The helper reads
+// that placement; it never invents a key from its own argument string, so the
+// rendered toggle and the loader-synthesized state var + gate share one source.
+//
+// [LAW:dataflow-not-control-flow] Openness is the value of the row key, not a
+// when-gated reveal: open ⇔ the row key holds THIS menu's member name. Open is a
+// length-1 drop appended after a "\n"; closed is just the glyph. One expression,
+// one returned RichText (the "\n" splits into a dropped line downstream).
+
+import { RichText } from "@promptctl/rich-js";
+import type { FuncMap } from "@promptctl/go-template-js";
+import {
+  MENU_GLYPH_CLOSED,
+  MENU_GLYPH_OPEN,
+  menuActionName,
+  menuStateKey,
+} from "../config/menu-keys.js";
+import { readVar, renderAction, type ActionRuntime } from "./action.js";
+import { renderPicker } from "./picker.js";
+
+// [LAW:types-are-the-program] One menu placement: the structural facts a context-
+// free `{{ menu }}` cannot see about itself. Published by the walk per segment
+// render; the helper reads the live value.
+export interface MenuPlacement {
+  readonly rowKey: string;
+  readonly segName: string;
+}
+
+// [LAW:locality-or-seam] The runtime the `menu` func closes over. It shares the
+// ACTION runtime (the menu's glyph and body resolve their actions/state from the
+// same compiled table + store as every other helper) and reads the walk-published
+// current placement. `current` is mutated by the single owner (the render walk,
+// set immediately before each segment template eval) — the spatial cousin of the
+// hue cursor, one mutator, never ambient. [LAW:no-ambient-temporal-coupling]
+export interface MenuRuntime {
+  readonly action: ActionRuntime;
+  current: MenuPlacement | null;
+}
+
+// Realize a `{{ menu }}` against the live placement + state into ONE RichText.
+function renderMenu(
+  applyName: string,
+  pageName: string,
+  closeOnPick: boolean,
+  paged: boolean,
+  runtime: MenuRuntime,
+): RichText {
+  const placement = runtime.current;
+  // [LAW:no-defensive-null-guards] The walk publishes a placement before every
+  // segment template evaluates; a `{{ menu }}` only renders inside a segment. A
+  // null here is a wiring bug (the func fired with no current segment), surfaced
+  // loudly rather than rendering a placeless menu.
+  if (placement === null) {
+    throw new Error(
+      "{{ menu }} rendered with no active segment placement — the render walk must publish one before evaluating a segment template",
+    );
+  }
+  const { rowKey, segName } = placement;
+  const action = runtime.action;
+
+  // [LAW:single-enforcer] The disclosure glyph IS the synthesized cycle action —
+  // displays bound one-per-member (closed ▸ / open ▾), the current member's glyph
+  // renders, the click writes the successor. Same toggle as group sugar.
+  const glyph = renderAction(
+    menuActionName(rowKey, segName),
+    [MENU_GLYPH_CLOSED, MENU_GLYPH_OPEN],
+    action,
+  );
+
+  // [LAW:dataflow-not-control-flow] Open ⇔ the row key holds this menu's member.
+  // Closed ⇒ just the glyph; open ⇒ glyph + "\n" + body. The "\n" is the sole
+  // vertical sentinel (splitCellsIntoLines drops the body below the row).
+  const open = readVar(action.store, menuStateKey(rowKey)) === segName;
+  if (!open) return glyph;
+
+  const body = renderPicker(applyName, pageName, closeOnPick, paged, action);
+  const combined = RichText.fromFragments([glyph, new RichText("\n"), body]);
+  combined.end = "";
+  return combined;
+}
+
+// [LAW:dataflow-not-control-flow] One func; the two action NAMES select the
+// body's apply/page effects, the two optional bools are the bounded author
+// choices (closeOnPick, paged) — identical surface to `{{ picker }}`, since the
+// body IS a picker. The disclosure takes no argument: its identity is derived
+// from placement, never authored.
+//
+// [LAW:one-way-deps] Injected into the engine by registerDslConfig as data; the
+// generic engine never imports this module.
+export function menuFuncs(runtime: MenuRuntime): FuncMap {
+  return {
+    menu: {
+      fn: (
+        applyName: string,
+        pageName: string,
+        closeOnPick?: boolean,
+        paged?: boolean,
+      ) =>
+        renderMenu(
+          applyName,
+          pageName,
+          closeOnPick === true,
+          paged === true,
+          runtime,
+        ),
+      argTypes: ["string", "string", "bool", "bool"],
+      returnType: "T",
+    },
+  };
+}

package/src/render/picker.ts

@@ -124,7 +124,11 @@ function requireKind<K extends CompiledActionDecl["kind"]>(
 // click APPLIES its option AND (when closeOnPick) resets the page key to -1 in one
 // atomic set-state — the picker owns the page key, so it derives the close-write
 // rather than the author re-stating the key.
-function renderPicker(
+// [LAW:single-enforcer] Exported so the `{{ menu }}` helper renders its body
+// through the SAME picker renderer — a menu body IS a picker grid; there is no
+// second grid implementation to drift. The menu adds only the disclosure
+// wrapper, never a parallel picker.
+export function renderPicker(
   applyName: string,
   pageName: string,
   closeOnPick: boolean,

package/src/template-engine/funcs.ts

@@ -34,34 +34,17 @@ import { renderSparkline, parseSeries } from "./sparkline.js";
 const THEMES_LIST: readonly string[] = listResolvablePaletteNames();
 const STYLES_LIST: readonly string[] = [...STRIP_STYLES];
 
-// Normalize an engine-supplied numeric argument. The "number" argType admits
-// both number and bigint (per @promptctl/go-template-js); the underlying
-// formatters take a JS number, so collapse bigint here. [LAW:single-enforcer]
-// every formatter wrapper goes through this — no per-wrapper bigint check.
-//
-// [LAW:no-silent-fallbacks] A bigint outside JS's safe-integer range cannot
-// round-trip through Number without silent precision loss (53-bit mantissa)
-// or overflow to ±Infinity. Either would feed a wrong value into a formatter
-// (e.g. formatDuration) and produce confidently-wrong output. Throw at the
-// conversion boundary so the failure surfaces where the conversion happens,
-// not deep inside a formatter doing math on a corrupted number.
-function num(v: number | bigint): number {
-  if (typeof v === "bigint") {
-    if (
-      v > BigInt(Number.MAX_SAFE_INTEGER) ||
-      v < BigInt(Number.MIN_SAFE_INTEGER)
-    ) {
-      throw new TypeError(
-        `Numeric argument ${v}n is outside JS safe-integer range ` +
-          `(|v| > Number.MAX_SAFE_INTEGER = ${Number.MAX_SAFE_INTEGER}); ` +
-          `Number(v) would lose precision or overflow. ` +
-          `Pass a value within ±Number.MAX_SAFE_INTEGER.`,
-      );
-    }
-    return Number(v);
-  }
-  return v;
-}
+// [LAW:single-enforcer] Numeric validation lives at ONE boundary — the engine's
+// `int`/`float` argType gate (@promptctl/go-template-js), which proves membership
+// and normalizes the carrier to a JS `number` before the func body runs. `int`
+// admits only finite integer-valued numbers + safe-integer bigints (rejecting
+// fractionals and precision-losing/overflowing bigints loudly at the gate);
+// `float` admits any finite number. So a formatter wrapper receives a clean
+// `number` and needs no bigint guard of its own — the prior `num()` helper was a
+// second enforcer of what the gate now owns, removed when the formatters adopted
+// int/float. [LAW:no-silent-failure] the gate's rejection is the loud failure on
+// a precision-losing integer input; this is not weaker than the old runtime
+// check, it is the same guarantee moved to the true boundary.
 
 // cc-candybar-specific functions not already covered by sprig or Go builtins.
 // The engine also includes sprigDefaults(), sprigStrings(), and sprigLists()
@@ -185,11 +168,13 @@ export function formatterFuncs(clock: () => Date = () => new Date()): FuncMap {
     // segments (`formatLongTimeRemaining (minutesUntilReset .resetsAt)`) and the
     // cacheTimer warmth countdown (numeric `le` thresholds).
     minutesUntilReset: {
-      fn: (epochSeconds: number | bigint) =>
+      fn: (epochSeconds: number) =>
         Math.round(
-          Math.max(0, num(epochSeconds) * 1000 - clock().getTime()) / 60000,
+          Math.max(0, epochSeconds * 1000 - clock().getTime()) / 60000,
         ),
-      argTypes: ["number"],
+      // [LAW:types-are-the-program] An epoch is integer-valued; `int` rejects a
+      // fractional or precision-losing carrier at the gate.
+      argTypes: ["int"],
     },
 
     // ─── Locale-grouped integer (context's "50,000") ──────────────────
@@ -200,8 +185,10 @@ export function formatterFuncs(clock: () => Date = () => new Date()): FuncMap {
     // of grouping policy — same parsing/formatting boundary that keeps
     // formatModelName here.
     formatInteger: {
-      fn: (n: number | bigint) => formatInteger(num(n)),
-      argTypes: ["number"],
+      fn: (n: number) => formatInteger(n),
+      // [LAW:types-are-the-program] Integer grouping is meaningful only for an
+      // integer; `int` rejects a fractional/precision-losing carrier at the gate.
+      argTypes: ["int"],
     },
 
     // ─── Numeric helper (block/weekly's Math.round of pct) ────────────
@@ -210,8 +197,10 @@ export function formatterFuncs(clock: () => Date = () => new Date()): FuncMap {
     // formatters.ts module documents domain-meaningful rules; rounding is
     // not domain-meaningful, so it stays here.
     round: {
-      fn: (n: number | bigint) => Math.round(num(n)),
-      argTypes: ["number"],
+      fn: (n: number) => Math.round(n),
+      // [LAW:types-are-the-program] round takes a fractional value (e.g. a
+      // percentage) → `float` admits any finite number.
+      argTypes: ["float"],
     },
 
     // ─── Model-name normalizers (chunk-7 model dsl-pending → dsl-parity) ─