@cardenelabs/cdl 0.5.0

package/src/event-handler/index.ts

@@ -0,0 +1,184 @@
+import type { CdlDiagram, CdlEventBinding, CdlEventTarget } from "../types";
+
+/**
+ * event handler function type (CAR #246)。
+ * consumer が signal update / computed 参照 / batch update 等を実装する。
+ * event 引数は DOM Event 本体 (target / clientX / preventDefault 等が使える)。
+ */
+export type CdlEventHandler = (event: Event) => void;
+
+/**
+ * attach 結果 handle (CAR #246)。 dispose 呼出で全 listener を cleanup。
+ */
+export type EventAttachHandle = {
+  /** 全 event listener を DOM から解除、 hydration unmount 経路。 */
+  dispose: () => void;
+};
+
+/**
+ * diagram の eventBindings を DOM element に attach する (CAR #246)。
+ *
+ * root element 内で target 記述に応じて element を lookup:
+ * - node: `[data-cdl-node="{id}"]` selector
+ * - edge: `[data-cdl-edge="{id}"]` selector
+ * - lane: `[data-cdl-lane="{id}"]` selector
+ * - diagram: root 自身
+ *
+ * event 種別:
+ * - click: `click` event
+ * - hover: `mouseenter` + `mouseleave` の 2 event を同 handler に bind、 consumer は
+ *   `event.type` で enter / leave を分岐する (tooltip / highlight の enter+clear を 1 binding で表現)
+ *
+ * listener は passive: true で登録 (scroll blocking 回避)。 target element が見つからない場合は
+ * silent skip + console warn (initial render 未完了の可能性、 fatal ではない)。
+ * handler map に該当 handlerId がない場合も silent skip + warn。
+ *
+ * 戻り値の dispose() で全 listener を解除。 hydration lifecycle (React useEffect の cleanup / unmount)
+ * と紐付けて use する。
+ */
+export function attachEventHandlers(
+  root: Element,
+  diagram: CdlDiagram,
+  handlers: Record<string, CdlEventHandler>,
+): EventAttachHandle {
+  const bindings = diagram.eventBindings ?? [];
+  const removers: Array<() => void> = [];
+
+  for (const binding of bindings) {
+    if (!Object.hasOwn(handlers, binding.handlerId)) {
+      warn(
+        `attachEventHandlers: handler '${binding.handlerId}' for binding '${binding.id}' not provided、 skip`,
+      );
+      continue;
+    }
+    const handler = handlers[binding.handlerId];
+    if (typeof handler !== "function") {
+      warn(
+        `attachEventHandlers: handler '${binding.handlerId}' is not a function (got ${typeof handler})、 skip`,
+      );
+      continue;
+    }
+    const elements = resolveTargetAll(root, binding.target);
+    if (elements.length === 0) {
+      warn(
+        `attachEventHandlers: target ${JSON.stringify(binding.target)} for binding '${binding.id}' not found in root、 skip`,
+      );
+      continue;
+    }
+    const eventNames = eventKindToDomEvents(binding.event);
+    // passive: false 相当 (default) = handler が event.preventDefault() を呼べる。
+    // click / mouseenter / mouseleave は scroll blocking の主要 event ではないため passive は不要、
+    // 逆に click で cancelable な interaction (link 抑制 / form submit 抑制) を消してしまう副作用が問題
+    // (codex Round 1 P2 finding)。
+    for (const el of elements) {
+      for (const eventName of eventNames) {
+        el.addEventListener(eventName, handler);
+        removers.push(() => {
+          el.removeEventListener(eventName, handler);
+        });
+      }
+    }
+  }
+
+  return {
+    dispose() {
+      while (removers.length > 0) {
+        const remover = removers.pop();
+        if (remover) remover();
+      }
+    },
+  };
+}
+
+/**
+ * event target 記述から実 DOM element を 1 つ lookup (最初の一致)。 test / debug 用途。
+ * edge target で label sibling も対象にする場合は resolveTargetAll を使う。
+ */
+export function resolveTarget(root: Element, target: CdlEventTarget): Element | null {
+  const all = resolveTargetAll(root, target);
+  return all[0] ?? null;
+}
+
+/**
+ * event target 記述から実 DOM element を全て lookup (attach 経路の SSOT)。
+ * edge target は本体 `[data-cdl-edge="{id}"]` + label sibling `[data-cdl-edge-label-for="{id}"]` の 2 系統
+ * を含める (label 上での click / hover を miss しないため、 codex Round 2 P2 finding)。
+ * 該当 element がなければ空配列を返す (silent skip 判定は attach 側)。
+ */
+export function resolveTargetAll(root: Element, target: CdlEventTarget): Element[] {
+  switch (target.kind) {
+    case "diagram":
+      return [root];
+    case "node":
+      return Array.from(root.querySelectorAll(`[data-cdl-node="${cssEscape(target.id)}"]`));
+    case "edge": {
+      // edge 本体 + label sibling を両方対象化
+      const edgeEls = root.querySelectorAll(`[data-cdl-edge="${cssEscape(target.id)}"]`);
+      const labelEls = root.querySelectorAll(
+        `[data-cdl-edge-label-for="${cssEscape(target.id)}"]`,
+      );
+      return [...Array.from(edgeEls), ...Array.from(labelEls)];
+    }
+    case "lane":
+      // node wrapper も `data-cdl-lane={parent lane}` を持つため、 lane container だけを対象化するには
+      // `:not([data-cdl-node])` で node element を除外する必要がある (codex Round 4 P2 finding)。
+      // 加えて edge 系 (`data-cdl-edge`) も念のため除外して、 純粋な lane container だけを取得。
+      return Array.from(
+        root.querySelectorAll(
+          `[data-cdl-lane="${cssEscape(target.id)}"]:not([data-cdl-node]):not([data-cdl-edge])`,
+        ),
+      );
+    default: {
+      const _exhaustive: never = target;
+      throw new Error(`resolveTarget: unsupported target kind (got ${JSON.stringify(_exhaustive)})`);
+    }
+  }
+}
+
+/**
+ * CdlEventKind → 対応する DOM event 名の配列。 hover は mouseenter + mouseleave の 2 event を
+ * 同 handler で受ける (handler 内 `event.type` で分岐して highlight / tooltip の enter/leave を実装可能)。
+ * click は 1 event のみ。 codex Round 3 P2 finding fix = hover に mouseleave を必ず含める。
+ */
+function eventKindToDomEvents(kind: CdlEventBinding["event"]): string[] {
+  switch (kind) {
+    case "click":
+      return ["click"];
+    case "hover":
+      return ["mouseenter", "mouseleave"];
+    case "double-click":
+      return ["dblclick"];
+    case "long-press":
+      // long-press は pointerdown/up の距離で判定するため、 生 event 側で
+      // 2 event 登録して handler 側で time diff を測る簡易実装。 500ms hold で発火
+      return ["pointerdown", "pointerup", "pointercancel"];
+    case "drag":
+      return ["pointerdown", "pointermove", "pointerup"];
+    case "drop":
+      return ["drop", "dragover"];
+    case "keydown":
+      return ["keydown"];
+    case "focus":
+      return ["focus"];
+    case "blur":
+      return ["blur"];
+  }
+}
+
+/**
+ * CSS.escape の polyfill 相当 (最低限、 id が特殊文字を含む場合の attribute selector 安全化)。
+ * CSS.escape が使える環境ではそちらを優先、 SSR / 古い環境の fallback として quotation double を用意。
+ */
+function cssEscape(value: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+  // fallback = double quote / backslash を escape
+  return value.replace(/["\\]/g, (m) => `\\${m}`);
+}
+
+function warn(message: string): void {
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(`[cdl event-handler] ${message}`);
+  }
+}

package/src/formula/ast.ts

@@ -0,0 +1,46 @@
+/**
+ * formula expression の AST 型 (CAR #244)。
+ *
+ * safe subset のみを表現する。 演算子 (+ - * / %) / 比較 (< <= > >= == !=) / 三項 (?:) / 括弧 /
+ * 数値リテラル / identifier (signal 名) / Math.* 関数呼出の 7 pattern。
+ *
+ * discriminated union で kind ごとに fields を厳密化、 evaluator / extractor が type narrowing で走査する。
+ */
+export type FormulaAst =
+  | { type: "number"; value: number }
+  | { type: "identifier"; name: string }
+  | { type: "binaryOp"; op: BinaryOp; left: FormulaAst; right: FormulaAst }
+  | { type: "unaryOp"; op: "-"; operand: FormulaAst }
+  | { type: "ternary"; condition: FormulaAst; whenTrue: FormulaAst; whenFalse: FormulaAst }
+  | { type: "call"; fn: MathFnName; args: FormulaAst[] };
+
+export type BinaryOp =
+  | "+"
+  | "-"
+  | "*"
+  | "/"
+  | "%"
+  | "<"
+  | "<="
+  | ">"
+  | ">="
+  | "=="
+  | "!=";
+
+export type MathFnName =
+  | "Math.min"
+  | "Math.max"
+  | "Math.abs"
+  | "Math.floor"
+  | "Math.ceil"
+  | "Math.round";
+
+/** parser / evaluator で許可された Math.* 関数の short name (Math. prefix なし)。 */
+export const ALLOWED_MATH_FNS = new Set<string>([
+  "min",
+  "max",
+  "abs",
+  "floor",
+  "ceil",
+  "round",
+]);

package/src/formula/evaluator.ts

@@ -0,0 +1,163 @@
+import type { FormulaAst } from "./ast";
+
+/**
+ * formula 評価 context = identifier 名 → runtime value の map。 caller が signal.value 等から構築して渡す。
+ * `evaluate` に直接渡す eager 経路の型 (簡易 use case)。
+ */
+export type FormulaContext = Record<string, number | boolean>;
+
+/**
+ * formula 評価 resolver = identifier 名 を受け取って値を返す関数。
+ * lazy evaluation を可能にする (ternary の unselected branch で undefined identifier / division by zero を回避)。
+ */
+export type FormulaResolver = (name: string) => number | boolean;
+
+/**
+ * AST を pure に評価して結果を返す (CAR #244)。
+ * safe subset のみサポート (parser 側で syntax error は既に排除済)。
+ *
+ * 第 2 引数は `FormulaContext` (record) or `FormulaResolver` (function) のどちらも受け付ける。
+ * ternary の unselected branch を skip したい caller は resolver 経路を使う (evaluator が identifier
+ * node に到達した時のみ resolver を呼ぶので、 unselected branch の identifier は lookup されない)。
+ *
+ * runtime error として:
+ * - undefined identifier (resolver / ctx が throw)
+ * - number 期待箇所に boolean が来た (or 逆)
+ * - division by zero (`/ 0` and `% 0`)
+ * - ternary condition が boolean でない
+ */
+export function evaluate(
+  ast: FormulaAst,
+  ctxOrResolver: FormulaContext | FormulaResolver,
+): number | boolean {
+  const resolver: FormulaResolver =
+    typeof ctxOrResolver === "function"
+      ? ctxOrResolver
+      : (name: string) => {
+          if (!Object.hasOwn(ctxOrResolver, name)) {
+            throw new Error(`undefined identifier '${name}' in formula (signal not registered?)`);
+          }
+          const v = ctxOrResolver[name];
+          if (typeof v !== "number" && typeof v !== "boolean") {
+            throw new Error(
+              `identifier '${name}' must be number or boolean (got ${typeof v})`,
+            );
+          }
+          return v;
+        };
+  return evaluateInternal(ast, resolver);
+}
+
+function evaluateInternal(ast: FormulaAst, resolver: FormulaResolver): number | boolean {
+  switch (ast.type) {
+    case "number":
+      return ast.value;
+    case "identifier":
+      return resolver(ast.name);
+    case "unaryOp": {
+      const operand = evaluateInternal(ast.operand, resolver);
+      if (typeof operand !== "number") {
+        throw new Error(`unary '-' requires number operand (got ${typeof operand})`);
+      }
+      return -operand;
+    }
+    case "binaryOp": {
+      const left = evaluateInternal(ast.left, resolver);
+      const right = evaluateInternal(ast.right, resolver);
+      switch (ast.op) {
+        case "+":
+        case "-":
+        case "*":
+        case "/":
+        case "%":
+          if (typeof left !== "number" || typeof right !== "number") {
+            throw new Error(
+              `binary '${ast.op}' requires number operands (got ${typeof left} and ${typeof right})`,
+            );
+          }
+          if ((ast.op === "/" || ast.op === "%") && right === 0) {
+            throw new Error(`division by zero in formula ('${ast.op}' with right = 0)`);
+          }
+          switch (ast.op) {
+            case "+":
+              return left + right;
+            case "-":
+              return left - right;
+            case "*":
+              return left * right;
+            case "/":
+              return left / right;
+            case "%":
+              return left % right;
+          }
+        // eslint-disable-next-line no-fallthrough
+        case "<":
+        case "<=":
+        case ">":
+        case ">=":
+          if (typeof left !== "number" || typeof right !== "number") {
+            throw new Error(
+              `comparison '${ast.op}' requires number operands (got ${typeof left} and ${typeof right})`,
+            );
+          }
+          switch (ast.op) {
+            case "<":
+              return left < right;
+            case "<=":
+              return left <= right;
+            case ">":
+              return left > right;
+            case ">=":
+              return left >= right;
+          }
+        // eslint-disable-next-line no-fallthrough
+        case "==":
+          return left === right;
+        case "!=":
+          return left !== right;
+      }
+    }
+    // eslint-disable-next-line no-fallthrough
+    case "ternary": {
+      const condition = evaluateInternal(ast.condition, resolver);
+      if (typeof condition !== "boolean") {
+        throw new Error(
+          `ternary condition must be boolean (got ${typeof condition})`,
+        );
+      }
+      // lazy: unselected branch は evaluate しない (undefined identifier / division by zero を skip 可能)
+      return condition
+        ? evaluateInternal(ast.whenTrue, resolver)
+        : evaluateInternal(ast.whenFalse, resolver);
+    }
+    case "call": {
+      const args = ast.args.map((a) => evaluateInternal(a, resolver));
+      for (const a of args) {
+        if (typeof a !== "number") {
+          throw new Error(`${ast.fn} requires number arguments (got ${typeof a})`);
+        }
+      }
+      const nums = args as number[];
+      switch (ast.fn) {
+        case "Math.min":
+          if (nums.length === 0) throw new Error("Math.min requires at least 1 argument");
+          return Math.min(...nums);
+        case "Math.max":
+          if (nums.length === 0) throw new Error("Math.max requires at least 1 argument");
+          return Math.max(...nums);
+        case "Math.abs":
+          if (nums.length !== 1) throw new Error("Math.abs requires exactly 1 argument");
+          return Math.abs(nums[0]!);
+        case "Math.floor":
+          if (nums.length !== 1) throw new Error("Math.floor requires exactly 1 argument");
+          return Math.floor(nums[0]!);
+        case "Math.ceil":
+          if (nums.length !== 1) throw new Error("Math.ceil requires exactly 1 argument");
+          return Math.ceil(nums[0]!);
+        case "Math.round":
+          if (nums.length !== 1) throw new Error("Math.round requires exactly 1 argument");
+          return Math.round(nums[0]!);
+      }
+    }
+  }
+}

package/src/formula/formula-computeds.ts

@@ -0,0 +1,83 @@
+import { computed, type Computed, type Signal } from "../reactive";
+import type { CdlDiagram } from "../types";
+import { extractIdentifiers, parseFormula } from "./parser";
+import { evaluate } from "./evaluator";
+
+/**
+ * diagram の `formulas` から computed を生成、 formula.id をキーにした map を返す helper (CAR #244)。
+ *
+ * 各 formula は expression を parse し、 参照する identifier (signal 名) を signals map から lookup して
+ * computed を生成する。 computed.value を read すると:
+ *   1. formula 内 identifier に対応する signal.value を read (自動 dep 登録)
+ *   2. AST を evaluate して結果を返す
+ * signal 変化で computed が自動再計算される (Step 2 の reactive graph に統合)。
+ *
+ * `Object.create(null)` で prototype pollution safe (input-signals.ts と同 pattern)。
+ */
+export function createFormulaComputeds(
+  diagram: CdlDiagram,
+  signals: Record<string, Signal<unknown>>,
+): Record<string, Computed<number | boolean>> {
+  const result = Object.create(null) as Record<string, Computed<number | boolean>>;
+  const formulas = diagram.formulas ?? [];
+
+  // signals map と formula id の cross-check。 collision があると (formulas x=2 / y=x*3 に対して
+  // 外部から signals.x = signal(10) を渡すと) y が formula "x" ではなく signal "x" を参照して
+  // 誤った値を silent に返す (codex Round 3 finding)。 builder は input 側の collision を防いでいるが、
+  // 手動 signal registration 経路には触れないため createFormulaComputeds 側でも checked する。
+  for (const formula of formulas) {
+    if (Object.hasOwn(signals, formula.id)) {
+      throw new Error(
+        `signal / formula id collision: signal '${formula.id}' が formula id と衝突しています (formula '${formula.id}' の resolution が silent に上書きされます)`,
+      );
+    }
+  }
+
+  for (const formula of formulas) {
+    let ast;
+    try {
+      ast = parseFormula(formula.expression);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`formula '${formula.id}' parse error: ${msg}`);
+    }
+    const referenced = extractIdentifiers(ast);
+    // pre-check: 各 identifier は signal or 既生成の formula computed のいずれかに存在必須。
+    // formulas 配列の 宣言順で iterate するため、 後方 formula が前方 formula を参照するのは OK、
+    // 逆向き (前方 formula が後方 formula を参照) と self-reference は「未定義 identifier」 で throw。
+    for (const name of referenced) {
+      if (!Object.hasOwn(signals, name) && !Object.hasOwn(result, name)) {
+        throw new Error(
+          `formula '${formula.id}' references undefined identifier '${name}' (must be a signal or a previously-declared formula)`,
+        );
+      }
+    }
+    result[formula.id] = computed(() => {
+      // lazy resolver: evaluator が identifier node に到達した時のみ signal / formula.value を read する。
+      // ternary の unselected branch や skip pass では該当 identifier に触れないため、
+      // 「safe = useRisk ? risky : 0」 で useRisk=false の時に risky の division by zero を回避できる (codex Round 4)。
+      return evaluate(ast, (name: string): number | boolean => {
+        let v: unknown;
+        let source: "signal" | "formula";
+        if (Object.hasOwn(signals, name)) {
+          v = signals[name]!.value;
+          source = "signal";
+        } else if (Object.hasOwn(result, name)) {
+          v = result[name]!.value;
+          source = "formula";
+        } else {
+          throw new Error(
+            `formula '${formula.id}' identifier '${name}' disappeared at evaluation time`,
+          );
+        }
+        if (typeof v !== "number" && typeof v !== "boolean") {
+          throw new Error(
+            `formula '${formula.id}' ${source} '${name}' must resolve to number or boolean at evaluation time (got ${typeof v})`,
+          );
+        }
+        return v;
+      });
+    });
+  }
+  return result;
+}

package/src/formula/index.ts

@@ -0,0 +1,5 @@
+export { parseFormula, extractIdentifiers } from "./parser";
+export { evaluate } from "./evaluator";
+export type { FormulaContext } from "./evaluator";
+export type { FormulaAst, BinaryOp, MathFnName } from "./ast";
+export { createFormulaComputeds } from "./formula-computeds";