@cardenelabs/cdl 0.17.1 → 0.18.0

package/dist/{render-Dc5Pdf7e.d.cts → render-Czv0tUon.d.cts}

@@ -162,6 +162,12 @@ type EdgeHeadFill = "solid" | "hollow";
 declare const EDGE_HEAD_FILL_DEFAULT: EdgeHeadFill;
 /** 塗り方の全種。 marker の定義と検査の走査がこの並びを引く */
 declare const EDGE_HEAD_FILLS: readonly EdgeHeadFill[];
+/** 矢印をいつ出すか (#582)。 `CdlDiagram.edgeReveal` が取る値と 1 対 1 */
+type EdgeReveal = "phase" | "all";
+/** 書ける値の一覧 (#582)。 利用側はここから導く = 手で並べると増えた時に取り残される */
+declare const EDGE_REVEALS: readonly EdgeReveal[];
+/** 書かなかった時の値 (#582) */
+declare const EDGE_REVEAL_DEFAULT: EdgeReveal;
 /**
  * 行き先と出どころの **両端に印を置ける** (#578)。
  *
@@ -2409,6 +2415,22 @@ type CdlDiagram = {
      * 既定は `"extract"` = 付け忘れても検知が緩まない向き。
      */
     structuredData?: "extract" | "exclude";
+    /**
+     * 矢印をいつ出すか (既定 = `"phase"`、 #582)。
+     *
+     * - `"phase"` ... 段のどこかで光る矢印は、その段が来るまで描かない。 1 度出たら出したまま
+     * - `"all"` ... 段に関わらず最初から全部描く
+     *
+     * 既定を `"phase"` にするのは、段を進めるごとに関係が 1 本ずつ増える図で、全ての矢印が
+     * 1 段目から見えていたため (実測 = 段が矢印を引き直しても「増えた」 と読めず、無関係な線が
+     * ちらついたようにしか見えない)。
+     *
+     * **段が矢印を 1 度も名指ししない図は `"phase"` でも隠さない**。 そういう図では矢印が骨格
+     * そのもので、隠す理由が無い = 既定を変えても既存の図は動かない。
+     *
+     * `"all"` は「段で光らせはするが、線そのものは最初から見せたい」 図のための逃げ道。
+     */
+    edgeReveal?: EdgeReveal;
     /**
      * interactive input widgets (v0.5+、 CAR #243)。
      * builder chain の `.input.slider() / .number() / .dropdown() / .toggle()` で追加。
@@ -2619,6 +2641,8 @@ type LaidDiagram = {
     phases: CdlPhase[];
     /** 他の値から自動で決まる値 (`CdlDiagram.derived` をそのまま引き継ぐ) */
     derived?: CdlDerivedValue[];
+    /** 矢印をいつ出すか (`CdlDiagram.edgeReveal` をそのまま引き継ぐ、 #582) */
+    edgeReveal?: EdgeReveal;
     /**
      * キャンバス全要素の bounding box list。
      * engine が「ここに何があるか」 を全部把握、 衝突検証 / debug 表示 / validation で使う。
@@ -2786,4 +2810,4 @@ type CdlDiagramViewProps = {
 };
 declare function CdlDiagramView({ diagram, laid: laidProp, hideHeader, hideMiniPhaseIndicator, focusPhaseId, debug, emitGeometryWarn, headingLevel, interactiveHandlers }: CdlDiagramViewProps): JSX.Element;
 
-export { type LaidLane as A, type BBox as B, type CdlDiagram as C, NODE_KINDS as D, type EdgeStyle as E, type ScrollProgressHandle as F, TONES as G, computeEventBindingKey as H, type InteractiveHandlerMap as I, type JourneyEmotion as J, computeFormulaKey as K, type LaidDiagram as L, computeInputSignalKey as M, type NodeKind as N, computeScrollTriggerKey as O, computed as P, type QuadrantKey as Q, type RowMark as R, type Signal as S, type Tone as T, createInteractiveSignalsAccessor as U, createScrollProgressHandle as V, createScrollProgressSignals as W, hasInteractivePrimitives as X, sequenceBoardMetrics as Y, sequenceStepId as Z, signal as _, type CdlInput as a, type CdlLane as b, type CdlNode as c, type Side as d, type EdgeHead as e, type EdgeHeadFill as f, type CdlState as g, type CdlEventTarget as h, type Computed as i, type CdlDerivedValue as j, type CdlScrollTrigger as k, type CdlDiagramViewProps as l, type LaidEdge as m, type LaidNode as n, type CdlEdge as o, CdlDiagramView as p, type CdlEventBinding as q, type CdlEventKind as r, type CdlFormula as s, type CdlPhase as t, EDGE_HEADS as u, EDGE_HEAD_DEFAULT as v, EDGE_HEAD_FILLS as w, EDGE_HEAD_FILL_DEFAULT as x, EDGE_STYLES as y, type InteractiveSignalsAccessor as z };
+export { sequenceBoardMetrics as $, EDGE_STYLES as A, type BBox as B, type CdlDiagram as C, type EdgeReveal as D, type EdgeStyle as E, type InteractiveSignalsAccessor as F, type LaidLane as G, NODE_KINDS as H, type InteractiveHandlerMap as I, type JourneyEmotion as J, type ScrollProgressHandle as K, type LaidDiagram as L, TONES as M, type NodeKind as N, computeEventBindingKey as O, computeFormulaKey as P, type QuadrantKey as Q, type RowMark as R, type Signal as S, type Tone as T, computeInputSignalKey as U, computeScrollTriggerKey as V, computed as W, createInteractiveSignalsAccessor as X, createScrollProgressHandle as Y, createScrollProgressSignals as Z, hasInteractivePrimitives as _, type CdlInput as a, sequenceStepId as a0, signal as a1, type CdlLane as b, type CdlNode as c, type Side as d, type EdgeHead as e, type EdgeHeadFill as f, type CdlState as g, type CdlEventTarget as h, type Computed as i, type CdlDerivedValue as j, type CdlScrollTrigger as k, type CdlDiagramViewProps as l, type LaidEdge as m, type LaidNode as n, type CdlEdge as o, CdlDiagramView as p, type CdlEventBinding as q, type CdlEventKind as r, type CdlFormula as s, type CdlPhase as t, EDGE_HEADS as u, EDGE_HEAD_DEFAULT as v, EDGE_HEAD_FILLS as w, EDGE_HEAD_FILL_DEFAULT as x, EDGE_REVEALS as y, EDGE_REVEAL_DEFAULT as z };

package/dist/{render-Dc5Pdf7e.d.ts → render-Czv0tUon.d.ts}

@@ -162,6 +162,12 @@ type EdgeHeadFill = "solid" | "hollow";
 declare const EDGE_HEAD_FILL_DEFAULT: EdgeHeadFill;
 /** 塗り方の全種。 marker の定義と検査の走査がこの並びを引く */
 declare const EDGE_HEAD_FILLS: readonly EdgeHeadFill[];
+/** 矢印をいつ出すか (#582)。 `CdlDiagram.edgeReveal` が取る値と 1 対 1 */
+type EdgeReveal = "phase" | "all";
+/** 書ける値の一覧 (#582)。 利用側はここから導く = 手で並べると増えた時に取り残される */
+declare const EDGE_REVEALS: readonly EdgeReveal[];
+/** 書かなかった時の値 (#582) */
+declare const EDGE_REVEAL_DEFAULT: EdgeReveal;
 /**
  * 行き先と出どころの **両端に印を置ける** (#578)。
  *
@@ -2409,6 +2415,22 @@ type CdlDiagram = {
      * 既定は `"extract"` = 付け忘れても検知が緩まない向き。
      */
     structuredData?: "extract" | "exclude";
+    /**
+     * 矢印をいつ出すか (既定 = `"phase"`、 #582)。
+     *
+     * - `"phase"` ... 段のどこかで光る矢印は、その段が来るまで描かない。 1 度出たら出したまま
+     * - `"all"` ... 段に関わらず最初から全部描く
+     *
+     * 既定を `"phase"` にするのは、段を進めるごとに関係が 1 本ずつ増える図で、全ての矢印が
+     * 1 段目から見えていたため (実測 = 段が矢印を引き直しても「増えた」 と読めず、無関係な線が
+     * ちらついたようにしか見えない)。
+     *
+     * **段が矢印を 1 度も名指ししない図は `"phase"` でも隠さない**。 そういう図では矢印が骨格
+     * そのもので、隠す理由が無い = 既定を変えても既存の図は動かない。
+     *
+     * `"all"` は「段で光らせはするが、線そのものは最初から見せたい」 図のための逃げ道。
+     */
+    edgeReveal?: EdgeReveal;
     /**
      * interactive input widgets (v0.5+、 CAR #243)。
      * builder chain の `.input.slider() / .number() / .dropdown() / .toggle()` で追加。
@@ -2619,6 +2641,8 @@ type LaidDiagram = {
     phases: CdlPhase[];
     /** 他の値から自動で決まる値 (`CdlDiagram.derived` をそのまま引き継ぐ) */
     derived?: CdlDerivedValue[];
+    /** 矢印をいつ出すか (`CdlDiagram.edgeReveal` をそのまま引き継ぐ、 #582) */
+    edgeReveal?: EdgeReveal;
     /**
      * キャンバス全要素の bounding box list。
      * engine が「ここに何があるか」 を全部把握、 衝突検証 / debug 表示 / validation で使う。
@@ -2786,4 +2810,4 @@ type CdlDiagramViewProps = {
 };
 declare function CdlDiagramView({ diagram, laid: laidProp, hideHeader, hideMiniPhaseIndicator, focusPhaseId, debug, emitGeometryWarn, headingLevel, interactiveHandlers }: CdlDiagramViewProps): JSX.Element;
 
-export { type LaidLane as A, type BBox as B, type CdlDiagram as C, NODE_KINDS as D, type EdgeStyle as E, type ScrollProgressHandle as F, TONES as G, computeEventBindingKey as H, type InteractiveHandlerMap as I, type JourneyEmotion as J, computeFormulaKey as K, type LaidDiagram as L, computeInputSignalKey as M, type NodeKind as N, computeScrollTriggerKey as O, computed as P, type QuadrantKey as Q, type RowMark as R, type Signal as S, type Tone as T, createInteractiveSignalsAccessor as U, createScrollProgressHandle as V, createScrollProgressSignals as W, hasInteractivePrimitives as X, sequenceBoardMetrics as Y, sequenceStepId as Z, signal as _, type CdlInput as a, type CdlLane as b, type CdlNode as c, type Side as d, type EdgeHead as e, type EdgeHeadFill as f, type CdlState as g, type CdlEventTarget as h, type Computed as i, type CdlDerivedValue as j, type CdlScrollTrigger as k, type CdlDiagramViewProps as l, type LaidEdge as m, type LaidNode as n, type CdlEdge as o, CdlDiagramView as p, type CdlEventBinding as q, type CdlEventKind as r, type CdlFormula as s, type CdlPhase as t, EDGE_HEADS as u, EDGE_HEAD_DEFAULT as v, EDGE_HEAD_FILLS as w, EDGE_HEAD_FILL_DEFAULT as x, EDGE_STYLES as y, type InteractiveSignalsAccessor as z };
+export { sequenceBoardMetrics as $, EDGE_STYLES as A, type BBox as B, type CdlDiagram as C, type EdgeReveal as D, type EdgeStyle as E, type InteractiveSignalsAccessor as F, type LaidLane as G, NODE_KINDS as H, type InteractiveHandlerMap as I, type JourneyEmotion as J, type ScrollProgressHandle as K, type LaidDiagram as L, TONES as M, type NodeKind as N, computeEventBindingKey as O, computeFormulaKey as P, type QuadrantKey as Q, type RowMark as R, type Signal as S, type Tone as T, computeInputSignalKey as U, computeScrollTriggerKey as V, computed as W, createInteractiveSignalsAccessor as X, createScrollProgressHandle as Y, createScrollProgressSignals as Z, hasInteractivePrimitives as _, type CdlInput as a, sequenceStepId as a0, signal as a1, type CdlLane as b, type CdlNode as c, type Side as d, type EdgeHead as e, type EdgeHeadFill as f, type CdlState as g, type CdlEventTarget as h, type Computed as i, type CdlDerivedValue as j, type CdlScrollTrigger as k, type CdlDiagramViewProps as l, type LaidEdge as m, type LaidNode as n, type CdlEdge as o, CdlDiagramView as p, type CdlEventBinding as q, type CdlEventKind as r, type CdlFormula as s, type CdlPhase as t, EDGE_HEADS as u, EDGE_HEAD_DEFAULT as v, EDGE_HEAD_FILLS as w, EDGE_HEAD_FILL_DEFAULT as x, EDGE_REVEALS as y, EDGE_REVEAL_DEFAULT as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.17.1",
+  "version": "0.18.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/index.ts

@@ -284,6 +284,7 @@ export type {
   CdlState,
   EdgeHead,
   EdgeHeadFill,
+  EdgeReveal,
   RowMark,
   EdgeStyle,
   LaidDiagram,
@@ -305,6 +306,8 @@ export {
   EDGE_HEAD_DEFAULT,
   EDGE_HEAD_FILLS,
   EDGE_HEAD_FILL_DEFAULT,
+  EDGE_REVEALS,
+  EDGE_REVEAL_DEFAULT,
   EDGE_STYLES,
 } from "./types";
 

package/src/layout.ts

@@ -371,6 +371,8 @@ export function layout(diag: CdlDiagram): LaidDiagram {
     states: diag.states,
     phases: diag.phases,
     ...(diag.derived ? { derived: diag.derived } : {}),
+    // 矢印をいつ出すか (#582)。 描き手が読む欄なので、そのまま持ち越す
+    ...(diag.edgeReveal ? { edgeReveal: diag.edgeReveal } : {}),
     bboxes,
     collisions,
     nearCollisions,

package/src/render/stage.tsx

@@ -1,5 +1,12 @@
 import { useMemo, type JSX } from "react";
-import { EDGE_HEADS, EDGE_HEAD_FILLS, EDGE_HEAD_FILL_DEFAULT, type CdlPhase, type LaidDiagram } from "../types";
+import {
+  EDGE_HEADS,
+  EDGE_HEAD_FILLS,
+  EDGE_HEAD_FILL_DEFAULT,
+  EDGE_REVEAL_DEFAULT,
+  type CdlPhase,
+  type LaidDiagram,
+} from "../types";
 import { CdlEdgeView, CdlEdgeGlowView, CdlEdgeLabelView } from "./edges";
 import { CdlNodeView } from "./nodes";
 import { TONE, TONE_HEX } from "./tone";
@@ -27,6 +34,33 @@ export function CdlStage({
   svgRef?: React.RefObject<SVGSVGElement | null>;
 }): JSX.Element {
   const activeSet = new Set(currentPhase?.activate ?? []);
+  /*
+   * まだ出番の来ていない矢印は描かない (#582)。
+   *
+   * 段を進めるごとに関係が 1 本ずつ増える図で、全ての矢印が 1 段目から見えていた。 段が進むと
+   * その矢印だけが引き直されるが、既に見えているので「増えた」 ようには読めず、無関係な線が
+   * ちらついたようにしか見えない (user 実機確認)。
+   *
+   * **段のどこかで光る矢印だけを対象にする**。 段が矢印を 1 度も名指ししない図では、矢印は
+   * 図の骨格そのものなので隠す理由が無い。 1 度出たら以降は出したままにする = 消える向きの
+   * 動きは、読み手が「戻った」 と読む。
+   *
+   * 著者が `edgeReveal: "all"` と書いた図では隠さない。
+   */
+  const 出番の来た矢印 = useMemo(() => {
+    // 著者が「最初から全部見せる」 と書いた図では隠さない (#582)
+    if ((laid.edgeReveal ?? EDGE_REVEAL_DEFAULT) === "all") return () => true;
+    const 初出 = new Map<string, number>();
+    laid.phases.forEach((p, i) => {
+      for (const id of p.activate ?? []) if (!初出.has(id)) 初出.set(id, i);
+    });
+    const 今 = currentPhase === undefined ? -1 : laid.phases.findIndex((p) => p.id === currentPhase.id);
+    return (edgeId: string): boolean => {
+      const first = 初出.get(edgeId);
+      if (first === undefined) return true;
+      return 今 < 0 || 今 >= first;
+    };
+  }, [laid.phases, currentPhase]);
   // この phase で左の起点から描き始める node (cdl#512)。 `activate` とは別集合で持つ =
   // 焦点が当たり続ける図で毎 phase 引き直すことになるため、 光っているかを引き金にしない
   const drawSet = new Set(currentPhase?.draw ?? []);
@@ -231,7 +265,7 @@ export function CdlStage({
         ))}
 
         {/* edges (1st pass) */}
-        {laid.edges.map((edge) => (
+        {laid.edges.filter((edge) => 出番の来た矢印(edge.id)).map((edge) => (
           <CdlEdgeView key={edge.id} edge={edge} active={activeSet.has(edge.id)} progress={progress} stateValues={stateValues} />
         ))}
 
@@ -256,13 +290,13 @@ export function CdlStage({
 
         {/* 経由 node 貫通する dotted-flow edge の進行点 glow (3rd pass) */}
         {laid.edges
-          .filter((edge) => Boolean(edge.dThrough))
+          .filter((edge) => Boolean(edge.dThrough) && 出番の来た矢印(edge.id))
           .map((edge) => (
             <CdlEdgeGlowView key={`glow-${edge.id}`} edge={edge} active={activeSet.has(edge.id)} />
           ))}
 
         {/* edge labels (3rd pass) ... 全 edge の label を最前面に描画 */}
-        {laid.edges.map((edge) => (
+        {laid.edges.filter((edge) => 出番の来た矢印(edge.id)).map((edge) => (
           <CdlEdgeLabelView
             key={`label-${edge.id}`}
             edge={edge}

package/src/types.ts

@@ -213,6 +213,15 @@ export const EDGE_HEAD_FILL_DEFAULT: EdgeHeadFill = "solid";
 /** 塗り方の全種。 marker の定義と検査の走査がこの並びを引く */
 export const EDGE_HEAD_FILLS: readonly EdgeHeadFill[] = ["solid", "hollow"];
 
+/** 矢印をいつ出すか (#582)。 `CdlDiagram.edgeReveal` が取る値と 1 対 1 */
+export type EdgeReveal = "phase" | "all";
+
+/** 書ける値の一覧 (#582)。 利用側はここから導く = 手で並べると増えた時に取り残される */
+export const EDGE_REVEALS: readonly EdgeReveal[] = ["phase", "all"];
+
+/** 書かなかった時の値 (#582) */
+export const EDGE_REVEAL_DEFAULT: EdgeReveal = "phase";
+
 /**
  * 行き先と出どころの **両端に印を置ける** (#578)。
  *
@@ -2480,6 +2489,22 @@ export type CdlDiagram = {
    * 既定は `"extract"` = 付け忘れても検知が緩まない向き。
    */
   structuredData?: "extract" | "exclude";
+  /**
+   * 矢印をいつ出すか (既定 = `"phase"`、 #582)。
+   *
+   * - `"phase"` ... 段のどこかで光る矢印は、その段が来るまで描かない。 1 度出たら出したまま
+   * - `"all"` ... 段に関わらず最初から全部描く
+   *
+   * 既定を `"phase"` にするのは、段を進めるごとに関係が 1 本ずつ増える図で、全ての矢印が
+   * 1 段目から見えていたため (実測 = 段が矢印を引き直しても「増えた」 と読めず、無関係な線が
+   * ちらついたようにしか見えない)。
+   *
+   * **段が矢印を 1 度も名指ししない図は `"phase"` でも隠さない**。 そういう図では矢印が骨格
+   * そのもので、隠す理由が無い = 既定を変えても既存の図は動かない。
+   *
+   * `"all"` は「段で光らせはするが、線そのものは最初から見せたい」 図のための逃げ道。
+   */
+  edgeReveal?: EdgeReveal;
   /**
    * interactive input widgets (v0.5+、 CAR #243)。
    * builder chain の `.input.slider() / .number() / .dropdown() / .toggle()` で追加。
@@ -2692,6 +2717,8 @@ export type LaidDiagram = {
   phases: CdlPhase[];
   /** 他の値から自動で決まる値 (`CdlDiagram.derived` をそのまま引き継ぐ) */
   derived?: CdlDerivedValue[];
+  /** 矢印をいつ出すか (`CdlDiagram.edgeReveal` をそのまま引き継ぐ、 #582) */
+  edgeReveal?: EdgeReveal;
   /**
    * キャンバス全要素の bounding box list。
    * engine が「ここに何があるか」 を全部把握、 衝突検証 / debug 表示 / validation で使う。