@cardenelabs/cdl 0.59.1 → 0.60.0

package/dist/{render-DpwY2hzM.d.cts → render-MbIjRWdX.d.cts}

@@ -2463,6 +2463,13 @@ type CdlFormula = {
     id: string;
     /** safe subset expression 文字列。 例 `"gasBase * (1 + delta/8)"` */
     expression: string;
+    /**
+     * 操作部の式の行に描く名札 (#853)。 無ければ id を描く。
+     *
+     * 名札があると、式の中身の名前のうち名札を持つ入力欄と式の id も名札に置き換えて描く。
+     * 置き換えは表示だけで、計算は `expression` を読む。
+     */
+    label?: string;
 };
 /**
  * event handler の bind target (CAR #246)。 node / edge / lane の id 指定 or diagram 全体 (root)。

package/dist/{render-DpwY2hzM.d.ts → render-MbIjRWdX.d.ts}

@@ -2463,6 +2463,13 @@ type CdlFormula = {
     id: string;
     /** safe subset expression 文字列。 例 `"gasBase * (1 + delta/8)"` */
     expression: string;
+    /**
+     * 操作部の式の行に描く名札 (#853)。 無ければ id を描く。
+     *
+     * 名札があると、式の中身の名前のうち名札を持つ入力欄と式の id も名札に置き換えて描く。
+     * 置き換えは表示だけで、計算は `expression` を読む。
+     */
+    label?: string;
 };
 /**
  * event handler の bind target (CAR #246)。 node / edge / lane の id 指定 or diagram 全体 (root)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.59.1",
+  "version": "0.60.0",
   "description": "CDL (Chainome Diagram Language). Mermaid-like declarative DSL that compiles to animated SVG diagrams. Built for blockchain / Solidity flows, generic enough for sequence / flow / state / ER / topology diagrams.",
   "license": "MIT",
   "author": "cardene777",

package/src/builder.ts

@@ -1596,8 +1596,10 @@ export type DiagramBuilder = {
    * consumer が createFormulaComputeds() で computed 化して signal と reactive bind する。
    * expression syntax error は本 method 内で throw (fail-fast)。
    * 例 `.formula("gasFee", "gasBase * (1 + delta/8)")`
+   *
+   * `opts.label` は操作部の式の行に描く名札 (#853)。 例 `.formula("total", "baseFee + tip", { label: "合計" })`
    */
-  formula: (id: string, expression: string) => DiagramBuilder;
+  formula: (id: string, expression: string, opts?: { label?: string }) => DiagramBuilder;
   /**
    * derive chain = 「連鎖形 formula」 を N 個宣言的に生成 (CAR: derive chain)。
    * 各 iteration で `{i}` 置換と、 直前 iteration の id (`prev`) を参照可能。
@@ -1607,11 +1609,14 @@ export type DiagramBuilder = {
    *
    * baseId は「gas1 / gas2 / gas3」 のように `gas${i+1}` として使われる、
    * expr fn は index (0..count-1) と prev id (前 iteration の完全 id) を受け取る。
+   *
+   * `opts.label` は index を受け取り、その式の名札を返す (#853)。 例 `{ label: (i) => \`${i + 1} 回目\` }`
    */
   deriveChain: (
     baseId: string,
     count: number,
     exprFn: (i: number, prev: string | null) => string,
+    opts?: { label?: (i: number) => string },
   ) => DiagramBuilder;
   /**
    * animation primitive (CAR #245)。 `.animation.scroll(id, opts)` で scroll-driven trigger を追加。
@@ -2213,7 +2218,7 @@ export function diagram(
         return api;
       },
     },
-    formula(formulaId, expression) {
+    formula(formulaId, expression, opts) {
       assertUniqueFormulaId(formulaId);
       // 入口で parse を試み、 syntax error は formula id 付きで throw (fail-fast)
       try {
@@ -2222,10 +2227,11 @@ export function diagram(
         const msg = e instanceof Error ? e.message : String(e);
         throw new Error(`formula '${formulaId}' の expression syntax error: ${msg}`);
       }
-      formulas.push({ id: formulaId, expression });
+      // 名札の無い式は `label` を持たせない (空の文字列も持たせない = 名札の無い図の形を変えない)
+      formulas.push({ id: formulaId, expression, ...(opts?.label ? { label: opts.label } : {}) });
       return api;
     },
-    deriveChain(baseId, count, exprFn) {
+    deriveChain(baseId, count, exprFn, opts) {
       if (!Number.isInteger(count) || count < 1 || count > 100) {
         throw new Error(`deriveChain: count (${count}) は 1..100 の整数である必要があります`);
       }
@@ -2242,7 +2248,9 @@ export function diagram(
           const msg = e instanceof Error ? e.message : String(e);
           throw new Error(`deriveChain '${id}' の expression syntax error: ${msg}`);
         }
-        formulas.push({ id, expression: expr });
+        const label = opts?.label?.(i);
+        // 名札の無い式は `label` を持たせない (空の文字列も持たせない = 名札の無い図の形を変えない)
+        formulas.push({ id, expression: expr, ...(label ? { label } : {}) });
         prev = id;
       }
       return api;

package/src/formula/parser.ts

@@ -21,7 +21,8 @@ import { isValidTemplateName } from "../template-name";
 
 type Token =
   | { kind: "num"; value: number; pos: number }
-  | { kind: "id"; name: string; pos: number }
+  /** `end` は字句の直後の位置。 `{name}` の形は閉じ括弧の直後 (表示用の置き換えが字句ごと差し替える) */
+  | { kind: "id"; name: string; pos: number; end: number }
   | { kind: "math"; fn: MathFnName; pos: number }
   | { kind: "op"; op: BinaryOp; pos: number }
   | { kind: "lparen"; pos: number }
@@ -92,7 +93,7 @@ function tokenize(src: string): Token[] {
           `invalid name "{${name}}" at position ${start} (空白 / { } / . / [ ] は名前に使えない)`,
         );
       }
-      tokens.push({ kind: "id", name, pos: start });
+      tokens.push({ kind: "id", name, pos: start, end: close + 1 });
       i = close + 1;
       continue;
     }
@@ -156,7 +157,7 @@ function tokenize(src: string): Token[] {
           `property access "${name}.${src[i + 1] ?? ""}..." at position ${start} is not allowed (only Math.* namespace is accessible)`,
         );
       }
-      tokens.push({ kind: "id", name, pos: start });
+      tokens.push({ kind: "id", name, pos: start, end: i });
       continue;
     }
     // operators
@@ -401,6 +402,34 @@ export function parseFormula(expression: string): FormulaAst {
   return new Parser(tokens).parse();
 }
 
+/**
+ * 式の中身の名前を、`名札` に載る名前だけ名札に置き換えた表示用の字を返す (#853)。 **計算には使わない**。
+ *
+ * 置き換えは字句の位置で行う。 文字列の検索で探すと、`gas1` の置き換えが `gas10` の先頭に当たり、
+ * 値の `min` の置き換えが `Math.min` の中に当たる。 関数の名前 (`Math.min` / 直後が `(` の `min`) と数は
+ * 名前の字句にならないので置き換わらない。 名札が空の文字列の名前は置き換えない。
+ *
+ * 字句に切れない式 (構文の誤り) は、元の字をそのまま返す。
+ */
+export function 式を名札で読む(expression: string, 名札: ReadonlyMap<string, string>): string {
+  let tokens: Token[];
+  try {
+    tokens = tokenize(expression);
+  } catch {
+    return expression;
+  }
+  let 読み = "";
+  let 前 = 0;
+  for (const t of tokens) {
+    if (t.kind !== "id") continue;
+    const 札 = 名札.get(t.name);
+    if (札 === undefined || 札 === "") continue;
+    読み += expression.slice(前, t.pos) + 札;
+    前 = t.end;
+  }
+  return 読み + expression.slice(前);
+}
+
 /**
  * AST 内で参照される identifier (signal 名) を全て収集する。 evaluator が signal 経由で
  * runtime value を lookup する時の識別子リスト作成に使う。

package/src/render/interactive-panel.tsx

@@ -5,6 +5,7 @@ import { assertNever } from "../assert-never";
 import type { CdlDiagram, CdlInput, CdlReadout } from "../types";
 import { createInputSignals, inputDefaultValue } from "../input-signals";
 import { createFormulaComputeds } from "../formula";
+import { 式を名札で読む } from "../formula/parser";
 import {
   createScrollProgressSignals,
   type ScrollProgressHandle,
@@ -643,6 +644,10 @@ export function useInteractiveIntegration(
       readouts.length === 0
     )
       return null;
+    // 式の中身の名前を読む名札 (#853)。 名札を持つ入力欄と式だけを載せる。
+    // 巻き取りは載せない = 式は入力欄と前の式しか参照できず (`createFormulaComputeds` が他の名前を拒む)、巻き取りの名前は中身に出ない
+    const 名札 = new Map<string, string>();
+    for (const x of [...inputs, ...formulasList]) if (x.label) 名札.set(x.id, x.label);
     return (
       // 操作部の中の読み出しと入力欄へ、図の言語を届ける (#849)。 型の外の値は英語に落ちる
       <操作部の言語.Provider value={resolveLang(diagram.lang)}>
@@ -660,7 +665,9 @@ export function useInteractiveIntegration(
               <FormulaReadout
                 key={f.id}
                 id={f.id}
-                expression={f.expression}
+                name={f.label || f.id}
+                // 名札の無い式は中身も書いたまま描く。 入力欄の名札は多くの図にあるので、置き換えると名札を付けていない式の描き方まで変わる
+                expression={f.label ? 式を名札で読む(f.expression, 名札) : f.expression}
                 value={stateOverrides[f.id]}
               />
             ))}
@@ -669,7 +676,7 @@ export function useInteractiveIntegration(
         {scrolls.length > 0 && (
           <div className="cdl-ip-group">
             {scrolls.map((s) => (
-              <ScrollReadout key={s.id} id={s.id} progress={stateOverrides[s.id]} />
+              <ScrollReadout key={s.id} id={s.id} name={s.label || s.id} progress={stateOverrides[s.id]} />
             ))}
           </div>
         )}
@@ -966,30 +973,36 @@ function NumberInputWidget({
   );
 }
 
+/** 式の行。 `name` は名札か id (#853)、目印 `data-cdl-formula` は名札の有無によらず id */
 function FormulaReadout({
   id,
+  name,
   expression,
   value,
 }: {
   id: string;
+  name: string;
   expression: string;
   value: unknown;
 }): JSX.Element {
   return (
     <div className="cdl-ip-item cdl-ip-formula" data-cdl-formula={id}>
-      <span className="cdl-ip-label">{id}</span>
+      <span className="cdl-ip-label">{name}</span>
       <code className="cdl-ip-formula-expr">= {expression}</code>
       <span className="cdl-ip-formula-value">{String(value ?? "")}</span>
     </div>
   );
 }
 
-function ScrollReadout({ id, progress }: { id: string; progress: unknown }): JSX.Element {
+/**
+ * 巻き取りの進みの行。 `name` は名札か id (#853)。 型と組み立ては `label` を持っていたが、この行は id を描いていた
+ */
+function ScrollReadout({ id, name, progress }: { id: string; name: string; progress: unknown }): JSX.Element {
   const p = typeof progress === "number" ? progress : 0;
   const pct = Math.round(p * 100);
   return (
     <div className="cdl-ip-item cdl-ip-scroll" data-cdl-scroll={id}>
-      <span className="cdl-ip-label">{id}</span>
+      <span className="cdl-ip-label">{name}</span>
       <div className="cdl-ip-scroll-track">
         <div className="cdl-ip-scroll-fill" style={{ width: `${pct}%` }} />
       </div>

package/src/types.ts

@@ -2514,6 +2514,13 @@ export type CdlFormula = {
   id: string;
   /** safe subset expression 文字列。 例 `"gasBase * (1 + delta/8)"` */
   expression: string;
+  /**
+   * 操作部の式の行に描く名札 (#853)。 無ければ id を描く。
+   *
+   * 名札があると、式の中身の名前のうち名札を持つ入力欄と式の id も名札に置き換えて描く。
+   * 置き換えは表示だけで、計算は `expression` を読む。
+   */
+  label?: string;
 };
 
 /**