@cardenelabs/cdl 0.50.0 → 0.52.0

package/dist/{render-C53-PeJZ.d.cts → render-C0PJ2weJ.d.cts}

@@ -686,6 +686,19 @@ type CdlEdge = {
      * compileEr 経路で edge label に "(1:N)" 形式で併記、 他 preset では透過。
      */
     cardinality?: string;
+    /**
+     * 行き先の端に添える短い字 (#821)。 クラス図の多重度 (`1..*`) に使う。
+     *
+     * 線の中ほどの札 (`label` / `sub`) に入れると、どちらの端の数かが読めない。
+     * 置き場所は線の最後の区間から決まる (`layout/head-label.ts`)。
+     */
+    headLabel?: string;
+    /**
+     * 出どころの端に添える短い字 (#825)。 `headLabel` と対。 クラス図の出どころ側の多重度に使う。
+     *
+     * UML は関係の両端に多重度を書く。 置き場所の計算は `headLabel` と同じ (`layout/head-label.ts`)。
+     */
+    tailLabel?: string;
     /** label の x 方向 fine offset (default 0)、 著者が細かく位置調整するための逃げ道 */
     labelOffsetX?: number;
     /** label の y 方向 fine offset (default 0、 + で下、 - で上) */

package/dist/{render-C53-PeJZ.d.ts → render-C0PJ2weJ.d.ts}

@@ -686,6 +686,19 @@ type CdlEdge = {
      * compileEr 経路で edge label に "(1:N)" 形式で併記、 他 preset では透過。
      */
     cardinality?: string;
+    /**
+     * 行き先の端に添える短い字 (#821)。 クラス図の多重度 (`1..*`) に使う。
+     *
+     * 線の中ほどの札 (`label` / `sub`) に入れると、どちらの端の数かが読めない。
+     * 置き場所は線の最後の区間から決まる (`layout/head-label.ts`)。
+     */
+    headLabel?: string;
+    /**
+     * 出どころの端に添える短い字 (#825)。 `headLabel` と対。 クラス図の出どころ側の多重度に使う。
+     *
+     * UML は関係の両端に多重度を書く。 置き場所の計算は `headLabel` と同じ (`layout/head-label.ts`)。
+     */
+    tailLabel?: string;
     /** label の x 方向 fine offset (default 0)、 著者が細かく位置調整するための逃げ道 */
     labelOffsetX?: number;
     /** label の y 方向 fine offset (default 0、 + で下、 - で上) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.50.0",
+  "version": "0.52.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

@@ -1452,6 +1452,10 @@ export type DiagramBuilder = {
       guard?: string;
       /** ER 関係 cardinality、 text-dsl v0.5 inline option (`cardinality: "1:N"`) を CdlEdge.cardinality へ透過 */
       cardinality?: string;
+      /** 行き先の端に添える字 (#821)。 クラス図の多重度に使う */
+      headLabel?: string;
+      /** 出どころの端に添える字 (#825)。 クラス図の出どころ側の多重度に使う */
+      tailLabel?: string;
       labelOffsetX?: number;
       labelOffsetY?: number;
       routing?: "default" | "back-detour";
@@ -1560,6 +1564,10 @@ export type DiagramBuilder = {
       tailHeadFill?: EdgeHeadFill;
       guard?: string;
       cardinality?: string;
+      /** 行き先の端に添える字 (#821)。 クラス図の多重度に使う */
+      headLabel?: string;
+      /** 出どころの端に添える字 (#825)。 クラス図の出どころ側の多重度に使う */
+      tailLabel?: string;
       labelOffsetX?: number;
       labelOffsetY?: number;
       routing?: "default" | "back-detour";
@@ -1776,6 +1784,8 @@ export function diagram(
         tailHeadFill: opts.tailHeadFill,
         guard: opts.guard,
         cardinality: opts.cardinality,
+        headLabel: opts.headLabel,
+        tailLabel: opts.tailLabel,
         labelOffsetX: opts.labelOffsetX,
         labelOffsetY: opts.labelOffsetY,
         routing: opts.routing,
@@ -1910,6 +1920,8 @@ export function diagram(
           tailHeadFill: d.tailHeadFill,
           guard: d.guard,
           cardinality: d.cardinality,
+          headLabel: d.headLabel,
+          tailLabel: d.tailLabel,
           labelOffsetX: d.labelOffsetX,
           labelOffsetY: d.labelOffsetY,
           routing: d.routing,

package/src/layout/head-label.ts

@@ -0,0 +1,156 @@
+/**
+ * 線の端に添える字 (`headLabel` / `tailLabel`) の置き場所 (#821 / #825)。
+ *
+ * 描く側 (`render/edges.tsx`) と検査が同じ値を使うため、計算をここに 1 つだけ置く。
+ * 行き先の端 (`head`) と出どころの端 (`tail`) は、端での線の向きの取り方だけが違う。
+ *
+ * 端での線の向きで決める。 端から `端の字を戻す距離` だけ線を戻った点を基準に、線の脇へ置く。
+ * 字は端に近い側の縁を基準点に揃える = 字の長さが変わっても、端から字までの隙間は変わらない。
+ *
+ * **線の札の反対側に置く**。 札と同じ側に置くと、札の語と多重度が続けて読まれる (「持つ」 の
+ * 隣に `1..*`、 英字の頃は「HAS1」)。 実測で、札と同じ側 (横向きなら上、縦向きなら右) に
+ * 置く形は見本帳のクラス図で 1 本が札と重なり、 もう 1 本が札と 2 world まで寄った。
+ * 札を持たない線は、横向きなら下、縦向きなら左に置く (engine が札を置く既定の側の反対)。
+ *
+ * 斜めの線と曲線は、向きの大きいほうの軸で横向き / 縦向きに振り分ける。 曲線の向きは
+ * 端の接線 (行き先の端なら最後の制御点から終点へ、出どころの端なら最初の制御点から始点へ) を
+ * 使う。 弦の向きを使うと、大きく膨らむ曲線で線が端へ入ってくる向きと別の向きが出る。
+ */
+import { EDGE_LABEL_TEXT } from "../label-text";
+import { extractPathSegments } from "./collisions";
+import { hasRenderedLabel } from "./spec";
+import { measureTextWidth } from "./text-width";
+
+/**
+ * 端から字までの、線に沿った距離 (world)。
+ *
+ * 端の印の長さの最大 (光っている時の 14、 `render/stage.tsx` の marker の大きさ) に隙間 8 を足す。
+ * 印を持たない端 (菱が出どころ側にある「持つ」 「抱える」 の行き先) でも同じ距離にする = 端ごとに
+ * 距離が変わると、図の中で多重度の位置が揃わない。
+ */
+export const 端の字を戻す距離 = 22;
+
+/** 線と字の間の隙間 (world) */
+export const 端の字と線の隙間 = 8;
+
+/** 端の字の大きさ。 札の下の行と同じ等幅の字 = 多重度を札に入れていた頃と同じ見え方 */
+export const 端の字の大きさ = EDGE_LABEL_TEXT.sub.fontSize;
+
+/** 字の箱の高さ。 字の大きさに上下の余白を足す */
+const 箱の高さ = Math.round(端の字の大きさ * 1.2);
+
+/** 字の大きさに対する baseline の深さ。 等幅の字の ascent が字の大きさの 8 割ほど */
+const BASELINE_RATIO = 0.8;
+
+/** どちらの端か。 `head` = 行き先 (`to`)、 `tail` = 出どころ (`from`) */
+export type 線の端 = "head" | "tail";
+
+export interface 端の字の置き場所 {
+  /** `text` の x。 どちらの縁かは `anchor` が決める */
+  x: number;
+  /** `text` の baseline の y */
+  y: number;
+  anchor: "start" | "end";
+  /** 字が占める箱 (world)。 重なりの検査に使う */
+  box: { x: number; y: number; w: number; h: number };
+}
+
+type 点 = { x: number; y: number };
+
+/** 端の点と、線がその端へ入ってくる向き (単位ベクトル)。 取れない時は `null` */
+function 向きを取る(end: 点, 候補: ReadonlyArray<点 | undefined>): { end: 点; ux: number; uy: number } | null {
+  for (const p of 候補) {
+    if (!p) continue;
+    const dx = end.x - p.x;
+    const dy = end.y - p.y;
+    const len = Math.hypot(dx, dy);
+    if (len > 1e-6) return { end, ux: dx / len, uy: dy / len };
+  }
+  return null;
+}
+
+/**
+ * 端の点と、線がその端へ入ってくる向き。
+ *
+ * 行き先の端は最後の区間から、出どころの端は最初の区間を逆にたどって取る。 端の区間の長さが
+ * 0 の時は隣の区間へ進む。 向きが取れない (区間が無い / 全て長さ 0) 時は `null`。
+ */
+function 端での向き(d: string, 端: 線の端): { end: 点; ux: number; uy: number } | null {
+  const segs = extractPathSegments(d);
+  if (segs.length === 0) return null;
+  if (端 === "head") {
+    const last = segs[segs.length - 1]!;
+    const end = { x: last.x2, y: last.y2 };
+    const 候補 = segs
+      .slice()
+      .reverse()
+      .flatMap((s) => [s.cmd === "Q" ? s.ctrl?.[0] : s.cmd === "C" ? s.ctrl?.[1] : undefined, { x: s.x1, y: s.y1 }]);
+    return 向きを取る(end, 候補);
+  }
+  const first = segs[0]!;
+  const end = { x: first.x1, y: first.y1 };
+  const 候補 = segs.flatMap((s) => [...(s.ctrl ?? []), { x: s.x2, y: s.y2 }]);
+  return 向きを取る(end, 候補);
+}
+
+/** 端の字を描く位置。 字が空か、線の向きが取れない時は `null` (描かない) */
+export function 端の字を置く(
+  edge: {
+    d: string;
+    headLabel?: string;
+    tailLabel?: string;
+    label?: string;
+    sub?: string;
+    labelX?: number;
+    labelY?: number;
+  },
+  端: 線の端 = "head",
+): 端の字の置き場所 | null {
+  const text = (端 === "head" ? edge.headLabel : edge.tailLabel)?.trim();
+  if (!text) return null;
+  const 向き = 端での向き(edge.d, 端);
+  if (!向き) return null;
+  const { end, ux, uy } = 向き;
+  const bx = end.x - ux * 端の字を戻す距離;
+  const by = end.y - uy * 端の字を戻す距離;
+  const w = measureTextWidth(text, {
+    fontSize: 端の字の大きさ,
+    fontWeight: EDGE_LABEL_TEXT.sub.fontWeight,
+    fontFamily: "mono",
+  });
+  const h = 箱の高さ;
+  // 札の中心。 札を描かない線と、位置がまだ無い線は `null`
+  const 札 =
+    hasRenderedLabel(edge) && edge.labelX !== undefined && edge.labelY !== undefined
+      ? { x: edge.labelX, y: edge.labelY }
+      : null;
+
+  let anchor: "start" | "end";
+  let box: { x: number; y: number; w: number; h: number };
+  if (Math.abs(ux) >= Math.abs(uy)) {
+    // 横向き。 右へ進む線は字が端の手前 (左) に伸びるので右の縁を揃える
+    const 右へ進む = ux > 0;
+    const 上に置く = 札 !== null && 札.y > by;
+    anchor = 右へ進む ? "end" : "start";
+    box = {
+      x: 右へ進む ? bx - w : bx,
+      y: 上に置く ? by - 端の字と線の隙間 - h : by + 端の字と線の隙間,
+      w,
+      h,
+    };
+  } else {
+    // 縦向き。 下へ進む線は字が端の手前 (上) に来るので下の辺を揃える
+    const 下へ進む = uy > 0;
+    const 右に置く = 札 !== null && 札.x < bx;
+    anchor = 右に置く ? "start" : "end";
+    box = {
+      x: 右に置く ? bx + 端の字と線の隙間 : bx - 端の字と線の隙間 - w,
+      y: 下へ進む ? by - h : by,
+      w,
+      h,
+    };
+  }
+  const x = anchor === "start" ? box.x : box.x + box.w;
+  const y = box.y + (h - 端の字の大きさ) / 2 + 端の字の大きさ * BASELINE_RATIO;
+  return { x, y, anchor, box };
+}

package/src/presets.ts

@@ -1430,8 +1430,10 @@ export type UmlRelation = {
   type: ClassRelationType;
   /** 関係 label (default は type 名) */
   label?: string;
-  /** 多重度 (例 "1..*" / "0..1") */
+  /** 多重度 (例 "1..*" / "0..1")。 行き先 (`to`) の端に添える (#821) */
   cardinality?: string;
+  /** 出どころ (`from`) 側の多重度 (例 "1")。 出どころの端に添える (#825) */
+  tailCardinality?: string;
   tone?: Tone;
   /**
    * 矢印の先の形 (cdl#574)。 書かなければ種類から決まる (`CLASS_RELATION_LOOK`)。
@@ -1573,7 +1575,10 @@ export function classDiagram(preset: ClassDiagramPreset): ClassDiagramBuilder {
         b.edge(r.from, r.to, {
           id: edgeId,
           label: r.label ?? r.type,
-          ...(r.cardinality ? { sub: r.cardinality } : {}),
+          // 多重度は行き先の端に添える (#821)。 札の下の行に入れると語と続けて読まれ
+          // (英字の頃は「HAS 1..*」 が「HAS1」)、 どちらの端の数かも読めない
+          ...(r.cardinality ? { headLabel: r.cardinality } : {}),
+          ...(r.tailCardinality ? { tailLabel: r.tailCardinality } : {}),
           tone: r.tone ?? 図の既定 ?? CLASS_RELATION_TONE[r.type],
           // 関係の種類から線と端の形を決める (cdl#574 / #578)。 書いた値が勝つ
           style: r.style ?? 見た目.style,

package/src/render/edges.tsx

@@ -1,6 +1,7 @@
 import { 等幅の字 } from "./mono-text";
 import type { JSX } from "react";
 import { computeLabelBBoxWorld, hasRenderedLabel, LABEL_PILL_PAD_X } from "../layout/spec";
+import { 端の字の大きさ, 端の字を置く, type 線の端 } from "../layout/head-label";
 import type { EdgeRole, LaidEdge, Tone } from "../types";
 import { edgeHeadMarkerName } from "./edge-head";
 import { toneColor } from "./tone";
@@ -394,3 +395,43 @@ export function CdlEdgeLabelView({
     </g>
   );
 }
+
+/**
+ * 線の端に添える字 (#821 / #825)。 札と同じく最前面の pass で描く。 `端` で行き先か出どころかを選ぶ。
+ *
+ * 下地の四角は敷かず、字の周りに下地色の縁取りを付ける (`paint-order: stroke`)。 字は線の脇、
+ * 箱の角の近くに置くので、四角い下地だと箱の角や線に被って小さな箱に見える。
+ */
+export function CdlEdgeEndLabelView({
+  edge,
+  active,
+  端,
+}: {
+  edge: LaidEdge;
+  active: boolean;
+  端: 線の端;
+}): JSX.Element | null {
+  const 置き場所 = 端の字を置く(edge, 端);
+  if (!置き場所) return null;
+  const color = edgeColor(edge);
+  return (
+    <text
+      data-cdl-role="edge-end-label"
+      data-cdl-edge-end-label-for={edge.id}
+      data-cdl-edge-end={端}
+      x={置き場所.x}
+      y={置き場所.y}
+      fontSize={端の字の大きさ}
+      fontWeight={EDGE_LABEL_TEXT.sub.fontWeight}
+      textAnchor={置き場所.anchor}
+      fill={active ? color : "var(--cdl-text-dim, #5a6270)"}
+      stroke="var(--cdl-label-bg, #ffffff)"
+      strokeWidth={4}
+      strokeLinejoin="round"
+      paintOrder="stroke"
+      style={{ fontFamily: fontFamilyAttr("sub") }}
+    >
+      {等幅の字(端 === "head" ? edge.headLabel : edge.tailLabel, 端の字の大きさ)}
+    </text>
+  );
+}

package/src/render/stage.tsx

@@ -20,7 +20,7 @@ import {
   edgeHeadMarkerName,
   edgeHeadPaint,
 } from "./edge-head";
-import { CdlEdgeView, CdlEdgeGlowView, CdlEdgeLabelView } from "./edges";
+import { CdlEdgeView, CdlEdgeGlowView, CdlEdgeEndLabelView, CdlEdgeLabelView } from "./edges";
 import { CdlNodeView } from "./nodes";
 import { resolveChartData } from "./payload-binding";
 import { relatedFocusSet } from "./relation-focus";
@@ -453,6 +453,20 @@ export function CdlStage({
           />
         ))}
 
+        {/* 線の端に添える字 (#821 / #825)。 札と同じ最前面の pass */}
+        {laid.edges
+          .filter((edge) => (edge.headLabel || edge.tailLabel) && 矢印の出番.出るか(edge.id))
+          .flatMap((edge) =>
+            (["head", "tail"] as const).map((端) => (
+              <CdlEdgeEndLabelView
+                key={`${端}-label-${edge.id}`}
+                edge={edge}
+                active={activeSet.has(edge.id)}
+                端={端}
+              />
+            )),
+          )}
+
         {/* debug overlay = engine が把握している bbox + collision を半透明で重ね描き */}
         {debug && (
           <g pointerEvents="none">

package/src/types.ts

@@ -758,6 +758,19 @@ export type CdlEdge = {
    * compileEr 経路で edge label に "(1:N)" 形式で併記、 他 preset では透過。
    */
   cardinality?: string;
+  /**
+   * 行き先の端に添える短い字 (#821)。 クラス図の多重度 (`1..*`) に使う。
+   *
+   * 線の中ほどの札 (`label` / `sub`) に入れると、どちらの端の数かが読めない。
+   * 置き場所は線の最後の区間から決まる (`layout/head-label.ts`)。
+   */
+  headLabel?: string;
+  /**
+   * 出どころの端に添える短い字 (#825)。 `headLabel` と対。 クラス図の出どころ側の多重度に使う。
+   *
+   * UML は関係の両端に多重度を書く。 置き場所の計算は `headLabel` と同じ (`layout/head-label.ts`)。
+   */
+  tailLabel?: string;
   /** label の x 方向 fine offset (default 0)、 著者が細かく位置調整するための逃げ道 */
   labelOffsetX?: number;
   /** label の y 方向 fine offset (default 0、 + で下、 - で上) */