@cardenelabs/cdl 0.105.0 → 0.107.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.105.0",
+  "version": "0.107.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/layout/spec.ts

@@ -272,6 +272,87 @@ export function titleFontSize(kind: string | undefined): number {
  */
 export const TITLE_BOX_PADDING = 52;
 
+/**
+ * 低い箱の時だけ題を箱に収まるまで小さくする種別。
+ *
+ * この 4 種は `kinds/compact-title.ts` の `titlePlacement` を通す。 低い箱 (`h` が
+ * `COMPACT_TITLE_MAX_H` 未満) では `fitTextSize` が字を 1 ずつ落として収めるが、
+ * それ以外の高さでは種別ごとの大きさをそのまま描くため、長い題は箱を超える。
+ */
+const KINDS_SCALING_TITLE_WHEN_LOW: ReadonlySet<string> = new Set(["actor", "event", "function", "storage"]);
+
+/**
+ * 高さに関わらず題を箱に収まるまで小さくする種別。
+ *
+ * `card` は `fitTextSize` を直に呼び、残る 34 種は絵の中の字として箱の幅に収まる倍率を掛ける。
+ * 一覧は `test/title-fit-kinds.test.tsx` が `NODE_KINDS` を全件描いて突き合わせる。
+ */
+const KINDS_SCALING_TITLE_ALWAYS: ReadonlySet<string> = new Set([
+  "card",
+  "shape-file",
+  "shape-folder",
+  "shape-cloud",
+  "shape-cylinder",
+  "shape-hexagon",
+  "shape-diamond",
+  "shape-stack",
+  "shape-person",
+  "shape-server-rack",
+  "shape-network-node",
+  "shape-mobile-device",
+  "shape-satellite",
+  "shape-smart-contract",
+  "shape-rpc-node",
+  "shape-wallet",
+  "shape-nft",
+  "shape-token",
+  "shape-blockchain",
+  "shape-bitcoin-chain",
+  "shape-ethereum-chain",
+  "shape-blockchain-node",
+  "shape-bank",
+  "shape-trust-bank",
+  "shape-payment-provider",
+  "shape-credit-card",
+  "shape-brokerage",
+  "shape-exchange",
+  "shape-atm",
+  "shape-website",
+  "shape-storefront",
+  "shape-warehouse",
+  "shape-online-shop",
+  "shape-cdn-edge",
+  "shape-api-gateway",
+]);
+
+/**
+ * これより低い箱を「低い箱」 とみなす。 `kinds/compact-title.ts` の `COMPACT_MAX_H` と同じ値。
+ *
+ * 写しているのは向きが逆だから = `compact-title.ts` は描く側の module で、`layout/` から
+ * 引くと組み方が描画に依存する。 2 つがずれないことは `test/title-fit-kinds.test.tsx` が見る。
+ */
+export const COMPACT_TITLE_MAX_H = 100;
+
+/**
+ * その箱が題を収まるまで小さくするか (SSOT)。
+ *
+ * 小さくする種別は題がはみ出さない代わりに、字が読めない大きさまで落ちうる。
+ * 軸 3 はこの 2 群で見るものを変える = 小さくしない種別は「箱の幅を超えるか」、
+ * 小さくする種別は「読める下限 (`MIN_TITLE_FONT_SIZE`) を割るか」 を見る。
+ */
+export function titleScalesToFit(kind: string | undefined, h: number): boolean {
+  const k = kind ?? "";
+  if (KINDS_SCALING_TITLE_ALWAYS.has(k)) return true;
+  return KINDS_SCALING_TITLE_WHEN_LOW.has(k) && h < COMPACT_TITLE_MAX_H;
+}
+
+/**
+ * 題を小さくする時の下限 (world)。 `kinds/compact-title.ts` の `MIN_TEXT_SIZE` と同じ値。
+ *
+ * 写している理由は `COMPACT_TITLE_MAX_H` と同じ。
+ */
+export const MIN_TITLE_FONT_SIZE = 11;
+
 /**
  * `rows` を文字として描く node の種別。
  *

package/src/layout/text-width.ts

@@ -21,11 +21,24 @@
 
 type FontFamily = "sans" | "mono";
 
+/**
+ * 見積りをどちらへ外すか。
+ *
+ * `layout` (既定) は **広い側** へ外す。 箱の大きさと線の置き場を決める側は、狭く見積もると
+ * 字が枠から出るため、外すなら広い側でなければならない。 表の値はこの向きに寄せてある。
+ *
+ * `drawn` は **実描画に合わせる**。 「はみ出すか」 を判定する側は、広く見積もると収まっている
+ * 字を挙げてしまう。 見本帳の題 407 か所を `getComputedTextLength()` で測り、和文は 1.08 倍 /
+ * 欧文は 1.16 倍の上振れだと判った (`DRAWN_*` の説明)。 その分を割り戻す。
+ */
+type WidthBound = "layout" | "drawn";
+
 interface MeasureOptions {
   fontSize?: number;
   fontWeight?: number;
   letterSpacing?: number;
   fontFamily?: FontFamily;
+  bound?: WidthBound;
 }
 
 /**
@@ -91,6 +104,28 @@ const EMOJI_ADVANCE_EM = 1.05;
 /** mono text から fallback する絵文字の advance (em)。 fontSize 19 の実測 22.0 px。 */
 const MONO_EMOJI_ADVANCE_EM = 1.16;
 
+/**
+ * 和文の上振れ幅。 `bound: "drawn"` で割り戻す。
+ *
+ * 実測 = 見本帳の題のうち和文だけの 247 件が **例外なく** 見積りの 1/1.08 で描かれていた
+ * (最小 1.080 / 中央 1.080)。 和文の字は全角 1.0 em で、表の 1.08 はその上振れぶんになる。
+ */
+const DRAWN_CJK_RATIO = 1.08;
+
+/**
+ * 欧文の上振れ幅。 `bound: "drawn"` で割り戻す。
+ *
+ * 実測 = 欧文だけの 119 件で見積りが実描画の 1.16 から 1.82 倍 (中央 1.27 倍) だった。
+ * **最小の 1.16 を採る** = 割り戻した値が実描画を下回ると、はみ出す題を見落とす。
+ * 407 件すべてで下回らないことを `title-drawn-width.test.ts` が突き合わせる。
+ */
+const DRAWN_ASCII_RATIO = 1.16;
+
+/** ASCII か。 `bound: "drawn"` で割り戻す係数を選ぶためだけに使う。 */
+function isAscii(code: number): boolean {
+  return code < 0x80;
+}
+
 /**
  * 絵文字ではない非 ASCII の記号 1 つ分の advance (em)。 実ブラウザで測った値 (`#481`)。
  *
@@ -189,6 +224,7 @@ export function measureTextWidth(text: string, opts: MeasureOptions = {}): numbe
   const fontSize = opts.fontSize ?? 22;
   const letterSpacing = opts.letterSpacing ?? 0;
   const fontFamily = opts.fontFamily ?? "sans";
+  const bound = opts.bound ?? "layout";
   let advanceEmSum = 0;
   let charCount = 0;
   // 1 つの絵に畳まれる並びがある時だけ書記素で数える (`CLUSTER_JOINER_RE` の説明)
@@ -196,13 +232,23 @@ export function measureTextWidth(text: string, opts: MeasureOptions = {}): numbe
   for (const ch of 文字列) {
     charCount++;
     const code = ch.codePointAt(0) ?? 0;
+    // 実描画に合わせる時は、字種ごとの上振れぶんを割り戻す。 絵文字と記号は実測が無いので
+    // 割り戻さない = 測っていない字を狭く見積もると、はみ出す題を見落とす
+    const 割り戻し =
+      bound === "drawn" && !isEmojiGrapheme(ch, code)
+        ? isAscii(code)
+          ? DRAWN_ASCII_RATIO
+          : isCJK(code)
+            ? DRAWN_CJK_RATIO
+            : 1
+        : 1;
     if (isEmojiGrapheme(ch, code)) {
       // mono を指定しても絵文字は JetBrains Mono ではなく emoji font へ fallback する。
       advanceEmSum += fontFamily === "mono" ? MONO_EMOJI_ADVANCE_EM : EMOJI_ADVANCE_EM;
       continue;
     }
     if (fontFamily === "mono") {
-      advanceEmSum += isCJK(code) ? 1.08 : JETBRAINS_MONO_ADVANCE_EM;
+      advanceEmSum += (isCJK(code) ? 1.08 : JETBRAINS_MONO_ADVANCE_EM) / 割り戻し;
       continue;
     }
     if (isCJK(code)) {
@@ -210,14 +256,16 @@ export function measureTextWidth(text: string, opts: MeasureOptions = {}): numbe
       // Inter fontSize 22 baseline に対し 1.08 em 前後で描画される (実測係数化)。
       // 1.08 が cookbook / presets / text-dsl の合計 G5 warn 最小 (10 件)、
       // 1.15 以上に上げると flow-demo が過大化して +2-6 件増える tradeoff。
-      advanceEmSum += 1.08;
+      advanceEmSum += 1.08 / 割り戻し;
       continue;
     }
     const table = ch.length === 1 ? INTER_BOLD_ADVANCE_EM[ch] : undefined;
-    advanceEmSum += table !== undefined ? table : defaultAdvanceEm(ch, code);
+    advanceEmSum += (table !== undefined ? table : defaultAdvanceEm(ch, code)) / 割り戻し;
   }
   const w = advanceEmSum * fontSize + letterSpacing * charCount;
-  return Math.max(w, fontSize * 1.2);
+  // 最低幅は組み方のための下駄 (短い札で bbox が細くなり判定が揺れるのを防ぐ)。
+  // 実描画に合わせる時は当てない = 1 字の題が 1.2 em で描かれることは無い
+  return bound === "drawn" ? w : Math.max(w, fontSize * 1.2);
 }
 
 /**

package/src/visual-validate.ts

@@ -144,6 +144,8 @@ import {
   rendersTitleText,
   fitsOwnTitleWidth,
   drawsTitleOutsideBox,
+  titleScalesToFit,
+  MIN_TITLE_FONT_SIZE,
   titleFontSize,
   TITLE_BOX_PADDING,
   rowBaselineY,
@@ -2003,18 +2005,41 @@ function runAxes(
     if (!isRenderedNode(n)) continue;
     const titleTrimmed = n.title?.trim() ?? "";
     if (!titleTrimmed) continue;
-    // 1 字の幅は **その種別が題を描く大きさ** から出す (#946)。 22 の定数で持っていたが、
+    // 幅は **字ごとの実幅** で出す (#949)。 字数に 1 字の幅を掛ける近似は、英数字の題で
+    // 過大に見積もる (英数字は全角の半分ほどしか取らない)。 34 で描く `storage` に
+    // `order_items` を書くと、近似は 426 と数えるが実際は 250 ほどしか使わない。
+    //
+    // 1 字の大きさは **その種別が題を描く大きさ** から渡す (#946)。 22 の定数で持っていたが、
     // 22 で描く種別は 1 つも無く、見積りが実物の 1.2 倍から 1.7 倍になっていた。
     //
+    // 見積りは **実描画に合わせた向き** で取る (#951)。 既定の値は組み方のために広い側へ
+    // 寄せてあり (和文 1.08 倍 / 欧文 1.16 倍以上)、そのまま「はみ出すか」 を判定すると
+    // 収まっている題を挙げる。 見本帳の題 407 か所の実測で、広い側の値では 9 枚が挙がり、
+    // 実測ではその 9 枚とも箱の中に 20px 以上の余白を残していた。
+    //
     // 箱の内側の余白 (52) は、題を箱の中に描く種別にだけ足す。 箱の外に描く種別 (`dyn-*` の
     // 名前と図表の題) は内側の余白に縛られないので、足すと収まっている題まで挙がる。
-    const titleLen = titleTrimmed.length;
-    const expectedW =
-      titleLen * titleFontSize(n.kind) + (drawsTitleOutsideBox(n.kind) ? 0 : TITLE_BOX_PADDING);
-    if (expectedW > n.w + 8) {
+    const 余白 = drawsTitleOutsideBox(n.kind) ? 0 : TITLE_BOX_PADDING;
+    const 使える幅 = n.w - 余白;
+    const 実幅 = measureTextWidth(titleTrimmed, { fontSize: titleFontSize(n.kind), bound: "drawn" });
+    if (titleScalesToFit(n.kind, n.h)) {
+      // 収まるまで縮める種別は、題がはみ出すことが起きない。 代わりに字が読めない大きさまで
+      // 落ちるので、**読める下限を割るか** を見る (#951)。 下限まで縮めても収まらない時
+      // (`actor` 等の 4 種) と、下限を無視して縮め続ける時 (絵の中の字) の両方がここに入る
+      const 縮めた大きさ =
+        実幅 > 0 ? titleFontSize(n.kind) * Math.min(1, 使える幅 / 実幅) : titleFontSize(n.kind);
+      if (縮めた大きさ < MIN_TITLE_FONT_SIZE) {
+        push(
+          "text-readability",
+          `node "${n.id}" title "${n.title}" が node 幅 ${n.w}px に収まらず、読める下限 ${MIN_TITLE_FONT_SIZE}px を割る (縮めて ${縮めた大きさ.toFixed(1)}px)`,
+          "warn",
+        );
+      }
+    } else if (実幅 > 使える幅 + 8) {
       push(
         "text-readability",
-        `node "${n.id}" title "${n.title}" が node 幅 ${n.w}px を超過する可能性 (期待 ${expectedW}px)`,
+        // 字ごとの実幅は小数になるので、読む人に出す時だけ丸める (判定は丸めない)
+        `node "${n.id}" title "${n.title}" が node 幅 ${n.w}px を超過する可能性 (期待 ${Math.round(実幅 + 余白)}px)`,
         "warn",
       );
     }