@shwfed/config 3.0.12 → 3.0.14

package/dist/runtime/share/invoice-eval.js

@@ -0,0 +1,88 @@
+import { computed, onMounted, ref, watch } from "vue";
+import { Effect, Option } from "effect";
+import { Fetch } from "fx-fetch";
+import { cel } from "../utils/cel.js";
+import { celBindings, injectCELContext } from "../utils/cel-context.js";
+import { fetchJsonOption } from "./request.js";
+import { toCapital } from "./rmb.js";
+const MONEY_FORMAT = new Intl.NumberFormat("zh-CN", {
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2
+});
+function toFiniteNumber(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+export function useInvoiceEval(requestExpr) {
+  const inheritedContext = injectCELContext();
+  const json = ref(void 0);
+  const jsonOption = computed(
+    () => json.value === void 0 ? Option.none() : Option.some(json.value)
+  );
+  const hasRequest = computed(() => {
+    const expr = requestExpr();
+    return !!expr && expr.trim().length > 0;
+  });
+  function baseContext() {
+    const inherited = celBindings(inheritedContext);
+    if (!hasRequest.value && "json" in inherited) return inherited;
+    return { ...inherited, json: jsonOption.value };
+  }
+  async function refresh() {
+    const expr = requestExpr();
+    if (!expr || expr.trim().length === 0) {
+      json.value = void 0;
+      return;
+    }
+    const program = Effect.gen(function* () {
+      const body = yield* fetchJsonOption(
+        yield* cel(expr, celBindings(inheritedContext))
+      );
+      return Option.getOrUndefined(body);
+    });
+    try {
+      json.value = await Effect.runPromise(Effect.provide(program, Fetch.layer));
+    } catch (err) {
+      console.warn("[shwfed-invoice] request failed", err);
+      json.value = void 0;
+    }
+  }
+  onMounted(() => void refresh());
+  watch(() => requestExpr() ?? "", () => void refresh());
+  function evaluate(expression, scope) {
+    if (!expression || expression.trim().length === 0) return void 0;
+    try {
+      return Effect.runSync(cel(expression, { ...baseContext(), ...scope }));
+    } catch (err) {
+      console.warn("[shwfed-invoice] expression evaluation failed", expression, err);
+      return void 0;
+    }
+  }
+  function text(expression, scope) {
+    const v = evaluate(expression, scope);
+    return v === null || v === void 0 ? "" : String(v);
+  }
+  function money(expression, scope) {
+    const v = evaluate(expression, scope);
+    if (v === null || v === void 0) return "";
+    if (typeof v === "number") return Number.isFinite(v) ? MONEY_FORMAT.format(v) : "";
+    return String(v);
+  }
+  function plain(expression, scope) {
+    const v = evaluate(expression, scope);
+    if (v === null || v === void 0) return "";
+    return String(v);
+  }
+  function bool(expression, scope) {
+    return evaluate(expression, scope) === true;
+  }
+  function capital(expression) {
+    const n = toFiniteNumber(evaluate(expression));
+    return n === null ? "" : toCapital(n) ?? "";
+  }
+  return { json, evaluate, text, money, plain, bool, capital };
+}

package/dist/runtime/share/invoice.d.ts

@@ -0,0 +1,68 @@
+import { Schema } from 'effect';
+import type { Environment } from '../vendor/cel-js/lib/index.js';
+import type { ResultType } from './expression.js';
+/**
+ * The pieces every 数电票 block shares. The 税总 invoice family (通用数电票、不动产
+ * 经营租赁服务、不动产销售、建筑服务…) is one 版式 with a per-业务 label, per-业务
+ * 明细 columns and a per-业务 备注 — everything else (抬头 / 购销双方 / 合计 /
+ * 价税合计 / 开票人) is byte-identical across members. This module holds the schema
+ * half of that overlap; `ui/invoice` holds the rendering half and `share/
+ * invoice-eval.ts` the per-栏 evaluation.
+ *
+ * Deliberately NOT a "common fields" factory: each block composes its own
+ * `Schema.Struct` so that `type` / `compatibilityDate` stay literal `Schema.tag`s
+ * at the folder that owns them. A factory would have to take those as arguments
+ * and hand back a half-built struct — more indirection than the duplication it
+ * would remove.
+ */
+export type Configure = (env: Environment) => void;
+/**
+ * 票面绝大多数栏位是文本。上下文取值的表达式常被 CEL 推断为 `dyn`（只在运行时收
+ * 窄），所以与 animated-number / card 的字符串字段一样容忍 `dyn` / `optional`。
+ */
+export declare const textResult: ResultType;
+/**
+ * 金额类栏位同时接受 `number` 与 `string`：格式化规则是「返回 string 原样打印，
+ * 返回 number 按票面惯例格式化」（见 `share/invoice-eval.ts` 的 `money`）。后端常以
+ * string 传小数以免丢精度，作者也可借此完全接管格式。
+ */
+export declare const moneyResult: ResultType;
+export declare const listResult: ResultType;
+export declare const boolResult: ResultType;
+/**
+ * 票面自己的（可选）取数：`request` 求值出的 HTTP 响应体，票面**每一栏**都能读。
+ *
+ * 与「不内建 DataSource」的边界不冲突 —— 只有 `request`，没有 `data`：票面各栏本来
+ * 就是逐栏 CEL 映射，`json` 只是多了一个可读的上下文变量，而不是又一层「列表 → 行」
+ * 的取数抽象。不配置时 `json` 为 `none`，票面照旧从外层上下文（`item` / 详情页变量）
+ * 取值。
+ *
+ * 也导出给各块的 `config.vue` —— 它直接渲染 `ExpressionEditor`（不经过 schema），
+ * 不共享这份声明的话，编辑器会把 `json` 误报成 `Unknown variable`。镜像 card 块的
+ * `JSON_VAR`。
+ */
+export declare const JSON_VAR: {
+    readonly type: "optional<dyn>";
+    readonly label: "HTTP 响应体";
+    readonly description: "HTTP 响应体（配置了「请求」时为已解析 JSON，否则为 none）";
+};
+/**
+ * 登记 `json`，但外层 `configure` 已经声明过就跳过 —— 宿主（详情页）本来就可能把自己
+ * 的响应体以 `json` 喂进来，重复声明会被 CEL 注册表拒掉（`'json' is already
+ * registered`），整个配置面直接抛错。与 `registerLoopVariablesIfAbsent` 同解。
+ *
+ * 外层已有时以**外层的声明为准**（类型通常是 `dyn` 而不是这里的 `optional<dyn>`）。
+ * 运行期的对应规则见 `share/invoice-eval.ts` 的 `baseContext`：配了「请求」本块的
+ * 响应体遮蔽外层的 `json`，没配则外层的 `json` 原样透传。
+ */
+export declare function registerJsonIfAbsent(env: Environment): void;
+/**
+ * 购买方 / 销售方信息栏。票面只有「名称」与「统一社会信用代码/纳税人识别号」两栏 ——
+ * 开户行与账号在真实发票上属于「备注」栏的自由文本（不是独立栏位），因此不建模，
+ * 由各块的备注承载。整个发票家族逐字相同，故在此共享。
+ */
+export declare function partySchema(configure: Configure, role: '购买方' | '销售方'): Schema.Struct<{
+    name: Schema.Schema<string, string, never>;
+    taxId: Schema.Schema<string, string, never>;
+}>;
+export type PartyValue = Schema.Schema.Type<ReturnType<typeof partySchema>>;

package/dist/runtime/share/invoice.js

@@ -0,0 +1,35 @@
+import { Schema } from "effect";
+import { Expression } from "./expression.js";
+export const textResult = (t) => t === "string" || t === "dyn" || t.startsWith("optional");
+export const moneyResult = (t) => t === "number" || t === "string" || t === "dyn" || t.startsWith("optional");
+export const listResult = (t) => t === "dyn" || t.startsWith("list") || t.startsWith("optional");
+export const boolResult = (t) => t === "bool" || t === "dyn" || t.startsWith("optional");
+export const JSON_VAR = {
+  type: "optional<dyn>",
+  label: "HTTP \u54CD\u5E94\u4F53",
+  description: "HTTP \u54CD\u5E94\u4F53\uFF08\u914D\u7F6E\u4E86\u300C\u8BF7\u6C42\u300D\u65F6\u4E3A\u5DF2\u89E3\u6790 JSON\uFF0C\u5426\u5219\u4E3A none\uFF09"
+};
+export function registerJsonIfAbsent(env) {
+  const declared = env.getDefinitions().variables.some((v) => v.name === "json");
+  if (declared) return;
+  env.registerVariable("json", JSON_VAR.type, {
+    label: JSON_VAR.label,
+    description: JSON_VAR.description
+  });
+}
+export function partySchema(configure, role) {
+  const CelText = Expression({ configure, resultType: textResult });
+  return Schema.Struct({
+    name: CelText.annotations({
+      title: "\u540D\u79F0",
+      description: `\u8FD4\u56DE${role}\u540D\u79F0\uFF08\`string\`\uFF09\u7684 CEL \u8868\u8FBE\u5F0F`
+    }),
+    taxId: CelText.annotations({
+      title: "\u7EDF\u4E00\u793E\u4F1A\u4FE1\u7528\u4EE3\u7801/\u7EB3\u7A0E\u4EBA\u8BC6\u522B\u53F7",
+      description: `\u8FD4\u56DE${role}\u7EDF\u4E00\u793E\u4F1A\u4FE1\u7528\u4EE3\u7801\u6216\u7EB3\u7A0E\u4EBA\u8BC6\u522B\u53F7\uFF08\`string\`\uFF09\u7684 CEL \u8868\u8FBE\u5F0F`
+    })
+  }).annotations({
+    title: `${role}\u4FE1\u606F`,
+    description: `${role}\u7684\u540D\u79F0\u4E0E\u7EB3\u7A0E\u4EBA\u8BC6\u522B\u53F7\uFF1B\u5F00\u6237\u884C / \u8D26\u53F7\u8BF7\u5199\u5165\u300C\u5907\u6CE8\u300D`
+  });
+}

package/dist/runtime/share/slot-renderer.vue

@@ -14,6 +14,16 @@ const props = defineProps({
 const emit = defineEmits(["update:slotValue"]);
 const inherited = injectCELContext();
 const $cel = (expression, context) => _rawCel(expression, { ...celBindings(inherited), ...context });
+function isHidden(block) {
+  const expr = block.hidden;
+  if (typeof expr !== "string" || expr.length === 0) return false;
+  try {
+    return Effect.runSync($cel(expr));
+  } catch (err) {
+    console.error(`[shwfed-slot-renderer] failed to evaluate hidden for ${block.id}:`, err);
+    return false;
+  }
+}
 function pickLayout(sets) {
   if (sets.length === 0) return void 0;
   for (const set of sets) {
@@ -40,6 +50,7 @@ const placedBlocks = computed(() => {
     const block = b;
     const placement = layout.placements[block.id];
     if (!placement) continue;
+    if (isHidden(block)) continue;
     const entry = props.findEntry(block.type, block.compatibilityDate);
     if (!entry) {
       const key = `${block.type}@${block.compatibilityDate}`;
@@ -53,37 +64,83 @@ const placedBlocks = computed(() => {
   }
   return out;
 });
+const authoredAreas = computed(() => {
+  const layout = activeLayout.value?.layout;
+  if (!layout) return [];
+  const out = [];
+  for (const b of props.slotValue.blocks) {
+    const block = b;
+    const placement = layout.placements[block.id];
+    if (!placement) continue;
+    if (!props.findEntry(block.type, block.compatibilityDate)) continue;
+    out.push(placement.area);
+  }
+  return out;
+});
+function buildRemap(count, keep) {
+  const line = Array.from({ length: count + 2 });
+  const keptFlags = [];
+  let acc = 1;
+  for (let L = 1; L <= count + 1; L++) {
+    line[L] = acc;
+    if (L <= count) {
+      const k = keep(L);
+      keptFlags.push(k);
+      if (k) acc++;
+    }
+  }
+  return { line, keptFlags, kept: acc - 1 };
+}
+const compaction = computed(() => {
+  const l = activeLayout.value?.layout;
+  if (!l) return null;
+  const authored = authoredAreas.value;
+  const visible = placedBlocks.value.map((p) => p.placement.area);
+  const coversCol = (a, c) => a[0][0] <= c && c < a[1][0];
+  const coversRow = (a, r) => a[0][1] <= r && r < a[1][1];
+  const rowCount = l.rows ?? authored.reduce((m, a) => Math.max(m, a[1][1] - 1), 0);
+  const grows = Array.from({ length: rowCount }, () => false);
+  for (const p of placedBlocks.value) {
+    if (!p.entry.metadata?.h?.grow) continue;
+    const [[, y1], [, y2]] = p.placement.area;
+    const lo = Math.max(1, y1);
+    const hi = Math.min(rowCount, y2 - 1);
+    for (let r = lo; r <= hi; r++) grows[r - 1] = true;
+  }
+  const col = buildRemap(l.columns, (c) => visible.some((a) => coversCol(a, c)) || !authored.some((a) => coversCol(a, c)));
+  const row = buildRemap(rowCount, (r) => visible.some((a) => coversRow(a, r)) || !authored.some((a) => coversRow(a, r)));
+  const rowTemplate = l.rows ? row.keptFlags.map((keep, i) => keep ? grows[i] ? "auto" : "minmax(auto, 1fr)" : null).filter(Boolean).join(" ") : "";
+  return {
+    colLine: col.line,
+    rowLine: row.line,
+    keptColumns: Math.max(1, col.kept),
+    rowTemplate
+  };
+});
 const gridStyle = computed(() => {
   const l = activeLayout.value?.layout;
-  if (!l) return "";
-  const tracks = (n, min) => `repeat(${n}, minmax(${min}, 1fr))`;
+  const comp = compaction.value;
+  if (!l || !comp) return "";
+  const colTemplate = `repeat(${comp.keptColumns}, minmax(0, 1fr))`;
   const gap = `calc(${l.gap ?? DEFAULT_GAP} * 0.25rem)`;
-  const colGap = l.columns > 1 ? `min(${gap}, calc(100% / ${l.columns - 1}))` : gap;
-  let rowTemplate = "";
-  if (l.rows) {
-    const grows = Array.from({ length: l.rows }, () => false);
-    for (const p of placedBlocks.value) {
-      if (!p.entry.metadata?.h?.grow) continue;
-      const [[, y1], [, y2]] = p.placement.area;
-      const lo = Math.max(1, y1);
-      const hi = Math.min(l.rows, y2 - 1);
-      for (let r = lo; r <= hi; r++) grows[r - 1] = true;
-    }
-    rowTemplate = grows.map((g) => g ? "auto" : "minmax(auto, 1fr)").join(" ");
-  }
+  const colGap = comp.keptColumns > 1 ? `min(${gap}, calc(100% / ${comp.keptColumns - 1}))` : gap;
   const parts = [
     "display: grid",
-    `grid-template-columns: ${tracks(l.columns, "0")}`,
-    rowTemplate ? `grid-template-rows: ${rowTemplate}` : "",
+    `grid-template-columns: ${colTemplate}`,
+    comp.rowTemplate ? `grid-template-rows: ${comp.rowTemplate}` : "",
     `column-gap: ${colGap}`,
     `row-gap: ${gap}`,
     l.style ?? ""
   ].filter(Boolean);
   return parts.join("; ");
 });
-function cellStyle(placement) {
+function cellStyle(placement, comp) {
   const [[x1, y1], [x2, y2]] = placement.area;
-  const parts = [`grid-column: ${x1} / ${x2}`, `grid-row: ${y1} / ${y2}`, "min-width: 0"];
+  const parts = [
+    `grid-column: ${comp.colLine[x1]} / ${comp.colLine[x2]}`,
+    `grid-row: ${comp.rowLine[y1]} / ${comp.rowLine[y2]}`,
+    "min-width: 0"
+  ];
   const h = placement.h && placement.h !== "stretch" ? placement.h : null;
   const v = placement.v && placement.v !== "stretch" ? placement.v : null;
   if (h || v) {
@@ -94,14 +151,16 @@ function cellStyle(placement) {
   }
   return parts.join("; ");
 }
-const rendered = computed(
-  () => placedBlocks.value.map((p) => ({
+const rendered = computed(() => {
+  const comp = compaction.value;
+  if (!comp) return [];
+  return placedBlocks.value.map((p) => ({
     key: p.block.id,
-    style: cellStyle(p.placement),
+    style: cellStyle(p.placement, comp),
     component: p.entry.runtime,
     block: p.block
-  }))
-);
+  }));
+});
 function updateBlock(id, next) {
   const blocks = props.slotValue.blocks.map((b) => b.id === id ? next : b);
   emit("update:slotValue", { ...props.slotValue, blocks });

package/dist/runtime/vendor/cel-js/CLAUDE.md

@@ -20,11 +20,13 @@ A `list.slice(number)` / `list.slice(number, number)` receiver pair has been add
 
 A `string.replace(string, string): string` / `string.replace(string, string, number): string` receiver pair has been added (in `functions.ts` beside `string.trim()`), matching the CEL strings-extension `replace`. The two-arg form delegates to JS `String.prototype.replaceAll` (so all non-overlapping occurrences are replaced; an empty `from` interleaves `to`). The three-arg form takes a limit and mirrors Go's `strings.Replace` via the `replaceLimited` helper: `limit < 0` replaces all, `0` replaces none, otherwise the first `limit` occurrences (`"foo".replace("", "_", 2) == "_f_oo"`).
 
+A `number.format(map): string` receiver method has been added (not from upstream, in `functions.ts` beside the `string(number)` conversion) — renders a number as a display string via `Intl.NumberFormat`. The map argument is passed through verbatim as the second (`options`) argument of `new Intl.NumberFormat('en-US', options)` — the same options object `Number.prototype.toLocaleString(locales, options)` accepts (`minimumFractionDigits`, `maximumFractionDigits`, `useGrouping`, `style`, `currency`, …); the locale is hardcoded to `'en-US'` so grouping renders as a comma and results are deterministic. Two precision-critical details: (1) the value is handed to `.format()` as a **string** (`Decimal.toString()`), not a JS number — `Intl` parses the decimal string at full precision, whereas the `.toNumber()` round-trip would clip past the safe-integer range (this matters for money); the `format` type only admits `number | bigint`, so the call is cast (`fmt.format as (value: string) => string`). (2) The option *values* arrive as `Decimal` (a CEL map literal's `2` is a `Decimal`) and must be unwrapped to JS numbers before `Intl` sees them — `intlOptionsFromMap` walks the map (plain object or host `Map`) and `.toNumber()`s any `Decimal`/`bigint` value, leaving strings/bools; these are small config knobs so their float round-trip is precision-safe. An impossible option combination (e.g. `maximumFractionDigits < minimumFractionDigits`) throws a `RangeError` from the `Intl` constructor, surfaced as `invalid_format_options`. A `dyn` receiver that is a number at runtime resolves too (overload resolution is by runtime type). Tested in `__tests__/number-format.test.ts`.
+
 `evaluate` now returns `Effect<T, ParseError | EvaluationError | TypeError>` instead of a plain value. The entire evaluation pipeline is Effect-based — every AST node's `evaluate` function returns an Effect, and sub-expressions are composed via `Effect.gen` / `yield*`. Promise-based async handling has been removed. User-registered functions may return `Effect` values, which are automatically flatMapped into the evaluation pipeline. Import `Effect` from `effect` and use `Effect.runSync` or `Effect.runPromise` to execute the returned Effect.
 
 The `homogeneousAggregateLiterals` and `enableOptionalTypes` environment options have been removed. Aggregate data structures (lists, maps) are always heterogeneous — mixed-type literals are inferred as `list<dyn>` or `map<dyn, dyn>`. Optional types (`.?`, `[?]`, `optional.*` helpers) are always enabled.
 
-The custom `Optional` class has been replaced with Effect's `Option` type (`import { Option } from 'effect'`). Internal helpers `optionalOf(value)` and `optionalValue(opt)` in `optional.js` handle the CEL-specific semantics (treating `undefined` as `None`, throwing `EvaluationError` on missing value access). The optional surface is `optional.of(A): optional<A>` (the lift / `pure` — `of(null)` is `Some(null)`), `optional.ofNullable(A): optional<A>` (the null-tolerant lift, Java-style — `null` becomes `None`), `optional.none()`, `optional.hasValue()`, `optional.value()`, `optional.or(optional)`, `optional.orValue(value)`, plus `optional<A>.flatMap(var, body): optional<B>` (monadic bind), `optional<A>.map(var, body): optional<B>` (the Functor `fmap`), `optional<A>.zip(other, x, y, body): optional<C>` (the applicative `liftA2` / `zipWith`), `optional<A>.filter(var, predicate): optional<A>` (Rust `Option::filter` / Haskell `mfilter`), and the folds `optional<A>.exists(var, predicate): bool` (predicate on `Some`, `false` on `None` — Rust `is_some_and`) and `optional<A>.all(var, predicate): bool` (predicate on `Some`, vacuously `true` on `None` — Scala `forall`) — all local additions (not from upstream). All are variable-binding macros (registered with `ast` arg types so the unbound args stay unevaluated): on `Some` they bind the value(s) and evaluate `body`; on `None` they short-circuit without touching `body`. `flatMap`'s body must itself yield an `optional`; `map`'s body is a plain value that gets re-wrapped in `Some`; `filter` / `exists` / `all` predicates must be `bool` (enforced at type-check when static, at runtime via `invalid_condition_type` otherwise). `map` is the derived `o.flatMap(v, optional.of(body))` promoted to a first-class macro. `zip` is the flattened `a.flatMap(x, b.map(y, body))`: it type-checks `other` in the outer ctx, binds `x` then `y` under two chained overlays, re-wraps the plain body in `Some`, and short-circuits to `None` if either side is `None` (a `None` receiver skips evaluating `other`). Because CEL has no tuple type the transform is fused (there is no useful `optional<pair>` to return), so `zip` is `zipWith`, not Rust/Scala's pair-building `Option.zip`. The short-circuit makes `zip` observationally monadic — harmless for `optional` (a `None` carries no payload) but it would not generalise to an error-accumulating applicative. An `optional.none()` receiver/argument carries a `param` element type; the shared `bindOptionalValueType` helper (exported from `optional.ts`) binds it as `dyn` so a boolean body still type-checks — every binding macro (`map` / `flatMap` / `zip` / `filter` / `exists` / `all`) goes through it (leaking the `param` into the iteration variable was a real bug in `map` / `flatMap`, regression-tested in `optional-extras.test.ts`). `zip` lives in `optional.ts` beside `flatMap`; the two-variable binding is why it is not folded into the shared `map` expander. NOTE: `map`, `filter`, `all`, and `exists` are **registered in `macros.ts`**, not here — the parser resolves a macro by name before types are known, so the optional variants and the list-comprehension variants must share one expander per name that dispatches on the receiver type at type-check (an `optional` receiver → optional semantics; `list`/`map` → comprehension; a `dyn` receiver is deferred to a runtime `Option.isOption` check). `exists_one` and `find` stay list-only.
+The custom `Optional` class has been replaced with Effect's `Option` type (`import { Option } from 'effect'`). Internal helpers `optionalOf(value)` and `optionalValue(opt)` in `optional.js` handle the CEL-specific semantics (treating `undefined` as `None`, throwing `EvaluationError` on missing value access). **Optional field access diverges from CEL**: `#getOptionalField` in `registry.ts` collapses a present-but-`null` field to `None`, where upstream (and cel-go) yield `Some(null)` — so `row.?foo` and `row.items[?0]` are absent-tolerant against backend JSON, in which `null` is overwhelmingly "absent" (without it `row.?foo.orValue([])` returns `null` and a downstream `size()` fails the overload check — a designer-facing footgun, since `.?` reads as the null-safe path). The collapse is **scoped to field access on purpose**: `optionalOf` itself keeps CEL semantics, so `optional.of(null)` is still `Some(null)` and `find` can still match a null element (its `Option` is the only channel for "did it match", so collapsing there would make a hit indistinguishable from a miss — unlike field access, where `has(row.foo)` and plain `row.foo` remain as escape hatches). `URL.query` is unaffected either way: it null-coalesces (`?? undefined`) before `optionalOf`. Pinned in `optional-extras.test.ts`. The optional surface is `optional.of(A): optional<A>` (the lift / `pure` — `of(null)` is `Some(null)`), `optional.ofNullable(A): optional<A>` (the null-tolerant lift, Java-style — `null` becomes `None`), `optional.none()`, `optional.hasValue()`, `optional.value()`, `optional.or(optional)`, `optional.orValue(value)`, plus `optional<A>.flatMap(var, body): optional<B>` (monadic bind), `optional<A>.map(var, body): optional<B>` (the Functor `fmap`), `optional<A>.zip(other, x, y, body): optional<C>` (the applicative `liftA2` / `zipWith`), `optional<A>.filter(var, predicate): optional<A>` (Rust `Option::filter` / Haskell `mfilter`), and the folds `optional<A>.exists(var, predicate): bool` (predicate on `Some`, `false` on `None` — Rust `is_some_and`) and `optional<A>.all(var, predicate): bool` (predicate on `Some`, vacuously `true` on `None` — Scala `forall`) — all local additions (not from upstream). All are variable-binding macros (registered with `ast` arg types so the unbound args stay unevaluated): on `Some` they bind the value(s) and evaluate `body`; on `None` they short-circuit without touching `body`. `flatMap`'s body must itself yield an `optional`; `map`'s body is a plain value that gets re-wrapped in `Some`; `filter` / `exists` / `all` predicates must be `bool` (enforced at type-check when static, at runtime via `invalid_condition_type` otherwise). `map` is the derived `o.flatMap(v, optional.of(body))` promoted to a first-class macro. `zip` is the flattened `a.flatMap(x, b.map(y, body))`: it type-checks `other` in the outer ctx, binds `x` then `y` under two chained overlays, re-wraps the plain body in `Some`, and short-circuits to `None` if either side is `None` (a `None` receiver skips evaluating `other`). Because CEL has no tuple type the transform is fused (there is no useful `optional<pair>` to return), so `zip` is `zipWith`, not Rust/Scala's pair-building `Option.zip`. The short-circuit makes `zip` observationally monadic — harmless for `optional` (a `None` carries no payload) but it would not generalise to an error-accumulating applicative. An `optional.none()` receiver/argument carries a `param` element type; the shared `bindOptionalValueType` helper (exported from `optional.ts`) binds it as `dyn` so a boolean body still type-checks — every binding macro (`map` / `flatMap` / `zip` / `filter` / `exists` / `all`) goes through it (leaking the `param` into the iteration variable was a real bug in `map` / `flatMap`, regression-tested in `optional-extras.test.ts`). `zip` lives in `optional.ts` beside `flatMap`; the two-variable binding is why it is not folded into the shared `map` expander. NOTE: `map`, `filter`, `all`, and `exists` are **registered in `macros.ts`**, not here — the parser resolves a macro by name before types are known, so the optional variants and the list-comprehension variants must share one expander per name that dispatches on the receiver type at type-check (an `optional` receiver → optional semantics; `list`/`map` → comprehension; a `dyn` receiver is deferred to a runtime `Option.isOption` check). `exists_one` and `find` stay list-only.
 
 A `list.filterMap(var, body): list<dyn>` macro has been added (not from upstream, in `macros.ts` beside `find`) — Rust's `Iterator::filter_map`. The body evaluates to an `optional<B>` per element; `Some` values are kept (unwrapped), `None`s dropped, yielding `list<B>`. It fuses the map-then-strip-absent pattern (which would otherwise need `.map(...)` to build a `list<optional>` plus a second pass to drop the `None`s) and is the optional-gated complement to the 3-arg `map(var, filter, transform)`, whose gate is a bool predicate. NOTE: it is **not** a comprehension desugar — the accu/ternary primitives gate on a bool, not on `Option` presence — so unlike the 2/3-arg `map` and `filter` it runs a manual fold like `find` (eval receiver → coerce Set/Map/object to an array → per-element `ev.eval(body)` → `ensureOptional` → push the `Some`s). Type-check: the receiver element type comes from list `valueType` / map `keyType` / `dyn` (same `invalid_comprehension_range` contract as `find`); the body must be `optional<B>` when statically typed (via `ensureOptionalType`), and a `dyn` body defers to the runtime `ensureOptional` (matching `flatMap`); the result is `registry.getListType(bindOptionalValueType(bodyType))`. Because the body already returns an `optional`, `filterMap` needs no receiver-type dispatch (there is no `optional<A>.filterMap` — that role is `flatMap`), so it is a single list-only expander. Tested in `__tests__/filter-map-macro.test.ts`.
 

package/dist/runtime/vendor/cel-js/PROMPT.md

@@ -91,8 +91,8 @@ time when statically known, at runtime when the source is `dyn`.
 ```cel
 obj.field                   // access field on map/object
 obj["field"]                // bracket access (equivalent)
-obj.?field                  // optional field access (returns optional)
-obj[?0]                     // optional index access (returns optional)
+obj.?field                  // optional field access (returns optional; null counts as absent)
+obj[?0]                     // optional index access (returns optional; null counts as absent)
 ```
 
 ## Built-in Functions
@@ -116,6 +116,26 @@ There is no `int()`, `uint()`, or `double()` — `number` is the only numeric
 type. To produce an integer, round explicitly with `math.trunc` / `math.floor`
 / `math.ceil` / `math.round`.
 
+`string(number)` renders a plain number (no grouping). For a **formatted**
+display string — thousands separators, fixed decimal places, currency, percent —
+use `number.format(options)`:
+```cel
+(1234567).format({})                                     // "1,234,567"  (comma grouping on by default)
+(1234567.5).format({"minimumFractionDigits": 2})         // "1,234,567.50"
+(3.14159).format({"maximumFractionDigits": 2})           // "3.14"
+(1234.5).format({"minimumFractionDigits": 2,
+                 "maximumFractionDigits": 2})             // "1,234.50"  (fixed 2 decimals)
+(1234567).format({"useGrouping": false})                 // "1234567"   (no separators)
+(1234.5).format({"style": "currency", "currency": "CNY"}) // "CN¥1,234.50"
+(0.42).format({"style": "percent"})                      // "42%"
+```
+The map is exactly the `options` object of JavaScript's
+`Number.prototype.toLocaleString(locales, options)` / `Intl.NumberFormat` — the
+locale is fixed to `en-US` (so grouping renders as a comma). The number is
+formatted at full precision (large integers past the float safe range keep every
+digit). An impossible combination (e.g. `minimumFractionDigits` above
+`maximumFractionDigits`) is an error.
+
 ### Math
 ```cel
 math.trunc(3.7)            // 3  — drop the fraction (toward zero)
@@ -414,12 +434,21 @@ An `optional<T>` is either present (`Some`) or absent (`None`). They come from
 (the lift — wraps a value as present), `optional.ofNullable(x)` (like `of`, but
 `null` lifts to absent), and `optional.none()`.
 
+`.?` / `[?]` treat a `null` field as absent, so `row.?foo` is `None` whether
+`foo` is missing, `null`, or `row` itself is `null` — reach for `orValue` and
+trust it. (This differs from standard CEL, where a null field is present.) Only
+`null` collapses; `""`, `0` and `false` are ordinary present values.
+
 ```cel
 optional.of(5)                          // present, holds 5
 optional.of(null)                       // present, holds null (of never inspects the value)
 optional.ofNullable(row.middleName)     // absent when the field is null
 optional.none()                         // absent
 
+row.?foo.orValue([])                    // [] when foo is missing OR null
+row.?foo.orValue("-")                   // "-" when absent; "" stays "" (only null collapses)
+has(row.foo)                            // true even when foo is null — tells null from missing
+
 o.hasValue()                            // bool — is it present?
 o.value()                               // unwrap — ERRORS if absent
 o.orValue(default)                      // unwrap, or `default` when absent

package/dist/runtime/vendor/cel-js/lib/functions.js

@@ -3,7 +3,7 @@ import { Decimal } from "./decimal.js";
 import { TYPES, Type } from "./registry.js";
 import { Option } from "effect";
 import { register as registerOptional, optionalOf } from "./optional.js";
-import { objKeys, arrayFrom } from "./globals.js";
+import { objKeys, arrayFrom, isArray } from "./globals.js";
 import { TZDate } from "@date-fns/tz";
 import { startOfMinute, startOfHour, startOfDay, startOfWeek, startOfMonth, startOfYear, endOfMinute, endOfHour, endOfDay, endOfWeek, endOfMonth, endOfYear, addMilliseconds, addSeconds, addMinutes, addHours, addDays, addWeeks, addMonths, addYears, setMilliseconds, setSeconds, setMinutes, setHours, setDate as setDayOfMonth, setMonth, setYear, format as formatDate, differenceInMilliseconds, differenceInSeconds, differenceInMinutes, differenceInHours, differenceInDays, differenceInWeeks, differenceInMonths, differenceInYears } from "date-fns";
 function toNum(v) {
@@ -87,6 +87,18 @@ export function registerFunctions(registry) {
   functionOverload("string(bool): string", (v) => `${v}`);
   functionOverload("string(number): string", (v) => Decimal.from(v).toString());
   functionOverload("string(bytes): string", (v) => ByteOpts.toUtf8(v));
+  functionOverload("number.format(map): string", (v, options) => {
+    const intlOptions = intlOptionsFromMap(options);
+    let fmt;
+    try {
+      fmt = new Intl.NumberFormat("en-US", intlOptions);
+    } catch (e) {
+      throw evaluationError("invalid_format_options", `number.format(): ${e.message}`);
+    }
+    return fmt.format(
+      Decimal.from(v).toString()
+    );
+  });
   functionOverload("string.startsWith(string): bool", (a, b) => a.startsWith(b));
   functionOverload("string.endsWith(string): bool", (a, b) => a.endsWith(b));
   functionOverload("string.contains(string): bool", (a, b) => a.includes(b));
@@ -440,6 +452,21 @@ export function registerFunctions(registry) {
   functionOverload("string(URL): string", (v) => v.href);
   registerOptional(registry);
 }
+function intlOptionsFromMap(m) {
+  const out = {};
+  const put = (k, val) => {
+    out[String(k)] = val instanceof Decimal ? val.toNumber() : typeof val === "bigint" ? Number(val) : val;
+  };
+  if (m instanceof Map) {
+    for (const [k, val] of m) put(k, val);
+  } else if (m !== null && typeof m === "object" && !isArray(m)) {
+    const obj = m;
+    for (const k of objKeys(obj)) put(k, obj[k]);
+  } else {
+    throw evaluationError("invalid_argument", "number.format(): options must be a map");
+  }
+  return out;
+}
 function stringSize(str) {
   let count = 0;
   for (const _ of str) count++;

package/dist/runtime/vendor/cel-js/lib/registry.js

@@ -180,7 +180,8 @@ export class TypeDeclaration {
     if (unwrapped === void 0) return Option.none();
     const type = ev.debugType(unwrapped);
     try {
-      return optionalOf(type.fieldLazy(unwrapped, key, ast, ev));
+      const value = type.fieldLazy(unwrapped, key, ast, ev);
+      return value === null ? Option.none() : optionalOf(value);
     } catch (e) {
       if (e instanceof EvaluationError) return Option.none();
       throw e;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shwfed/config",
-  "version": "3.0.12",
+  "version": "3.0.14",
   "description": "Configurable UI for SHWFED",
   "type": "module",
   "publishConfig": {