@cardenelabs/cdl 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -5,8 +5,255 @@ CDL (Chainome Diagram Language) の主要変更履歴。
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-08-28
+
+### Fixed
+
+- **狭い枠で帯の図の一覧が箱をはみ出すのを直した** (#568)
+
+  `chart-stacked-bar` の一覧は左から順に足して並べており、枠の幅を見ていなかった。
+  名前が長い図を細い枠で描くと右へ流れて箱の外へ出る (260 幅の枠で 16 はみ出した)。
+  枠に入らなくなったら行を変える。 名前は切らない = 折り返しで収まるなら、その方が読める。
+
+  **同じ形を全種別で止める検査を足した**。 図表の検査はどれも既定の枠 (640×320) で描いており、
+  枠を変えた時の振る舞いを見ていなかった。 既定は横長なので、絵の大きさを「縦から出た上限」 と
+  「横から出た上限」 の小さい方で決める種別では **縦が常に勝つ** = 横の項を式から外しても
+  1 件も落ちない。
+
+  実測で `chart-gauge` と `chart-waffle` がその死角に入っており、横の項を外す変異が
+  0 件しか落ちなかった (`visualValidate` もどの枠でも検知しない)。 同じ死角は #548 と #550 でも
+  踏んでおり 3 回目。
+
+  横長と細長の 2 枠で全種別を描き、絵が箱の右端を超えないことを見る。 対象は種別の一覧から
+  導くので、新しい図表を足した時点で検査に入る。
+
+### Added
+
+- **描く速さを段の長さと別に指定できるようにした** (#570)
+
+  `draw` に載せた node の伸び具合は段の進みそのもので決まり、段の長さと別の「描く時間」 を
+  持たなかった。 そのため「線はゆっくり引きたいが値の移りは短くしたい」 が書けず、描く速さの
+  ために段の長さを動かすことになる。 段の長さを動かすと同じ段の `tweens` まで遅くなる。
+
+  段に `drawRatio` (`.drawRatio(0.4)`) を足した。 「描き終えるまでに段の何割を使うか」 を
+  0 より大きく 1 以下で書く。 `0.4` なら進みが 0.4 に達した時点で描き終わり、残りの 0.6 は
+  描き終わった姿のまま値だけが動く。
+
+  **割合で持ち、秒数では持たない**。 割合なら段に収まるので、再生速度の切替 (0.5x / 2x) が
+  そのまま効き、段をはみ出した時の扱いを決めずに済む。 秒数だと切替との掛かり方とはみ出しの
+  扱いを新たに決めることになり、決め事が 2 つ増える。
+
+  掛かる相手は `draw` に載せた node だけ。 同じ段の他の node と edge、および `tweens` は
+  元の進みのまま動く。 範囲外 (0 以下 / 1 超 / NaN / Infinity) は 1 として扱い、`validate` が
+  知らせる = 描く動きは見え方であって図の意味ではないので、書き間違いで図が出なくなる方が
+  損が大きい。
+
+  書かない段は欄ごと出さないので、既存の図の JSON も DOM も変わらない。
+
+- **内訳と時点間の変化を帯で示す図を新設した** (#551)
+
+  `chart-pie` は 1 時点の内訳しか描けない。 段が進んで値が動くと前の姿は消えるので、
+  「昨年と今年で構成比がどう変わったか」 は読み手の記憶に頼ることになる。
+  扇の角度は近い値の比較にも弱い (45% と 39% は目測で見分けが付かない)。
+
+  `chart-stacked-bar` は 1 本の帯を割合で区切る = **長さで比べられる**。
+  帯を縦に並べれば時点間の変化がそのまま見える。 記法からは `type: stacked-bar` で書ける。
+
+  **前の時点は datum の `previous` で持つ**。 節を時点ごとに置く案は採らない = 図表は
+  「1 節に datum 配列を持ち、種別が全 datum を描く」 構造で揃っており、節を増やすと配置と
+  組み立て器の両方が別経路になる。 1 件でも書けば帯が 2 本になり、書かない図は 1 本のまま。
+
+  前の時点を持たない件も帯に残す (その時点では 0)。 落とすと帯ごとに区画の数が変わり、
+  上下で同じ位置が別の件を指す。
+
+  区画の字は **入る時だけ描く**。 細い区画に詰めると隣へはみ出して、どちらの値か読めなくなる。
+  名前は下の一覧が受け持つので、字が入らなかった件も引ける。
+
+  `previous` も `{名前}` で状態から読める。 3 時点以上と縦の積み上げ、段の進みで帯が伸びる
+  動きは対象外。
+
+- **割合を数えて確かめられる格子の図を新設した** (#552)
+
+  `chart-pie` は角度、`chart-bar` は長さで割合を示すが、どちらも **目測** になる。
+  「だいたい 4 割」 までは読めても、正確な値は凡例や名札の数字に頼ることになる。
+  図そのものから値を確かめられないため、図と数字が食い違っていても読み手は気付けない。
+
+  `chart-waffle` は 1 個を 1% に割り当てた印を 100 個並べる。 数えれば正確に分かる。
+  記法からは `type: waffle` で書ける。
+
+  **印の数の合計は常に 100 になる**。 割合をそれぞれ四捨五入すると合計がずれる
+  (33.3% が 3 件で 99、16.7% が 6 件で 102)。 ずれたまま描くと印が余る / 足りない図になり、
+  「数えて確かめられる」 という存在理由が消える。 最大剰余法で配ることで定義上ちょうど 100 になる。
+
+  **持ち主のいない印も地の色で描く**。 描かないと「全体のうちどれだけか」 の分母が消え、
+  棒グラフと同じ図になる。
+
+  一覧には印の数をそのまま出す = 図を数えた結果と突き合わせられる。
+
+  payload は既存の `chartData` をそのまま使う。 100 個以外の粒度、印の形の選択、
+  段の進みで印が埋まる動きは対象外。
+
+- **数値そのものを主役にする図を新設した** (#553)
+
+  既存の図表はどれも **形で比率を測る** 作りで、数値は名札や凡例に小さく添える。
+  「今月の売上は 4,500」 のように数値を読ませたい場面では、形が主役だと数値が小さすぎる。
+  `chart-bar` で 1 件だけ描く形も試せるが、比べる相手が無いのに軸と目盛が出る。
+
+  `chart-stat` は件ごとに区画を割り、名前 / 数値 / 弧 / 割合 を縦に積む。
+  **数値の字を名前より大きくする** のがこの種別の中身で、大小が逆転したら別の図になる。
+  記法からは `type: stat` で書ける。
+
+  弧は輪郭だけの細い線にする。 面で塗ると数値より目立ち、主役が入れ替わる。
+
+  縦の位置は件数に依らない。 件数から出すと、同じ図を並べた時に数値の行が揃わない。
+
+  桁の多い数値は区画に収まるまで小さくするが、**名前の級より下へは縮めない** =
+  縮めた結果として主役が入れ替わるのを防ぐ。 下限でも入らない時は入らないまま描く
+  (字を落とすと数値が別の値に読める)。
+
+  payload は既存の `chartData` をそのまま使う。 前期比と 5 件以上の折り返しは対象外。
+
+- **関係の端の形・自分から自分へ戻る線・流れの始まりと終わりの印を足した** (#560)
+
+  記法の側で 4 図 (クラス / ER / 状態遷移 / シーケンス) の見た目を決めたところ、中身は全部
+  書けたが 3 つの見た目が描画側に無かった。
+
+  **端の形** は `head` で書く。 塗った三角 (継ぐ) / 菱 (持つ) / 開いた矢 (使う) / 三又 (多) の
+  4 形で、線の種類とは別の軸に置いた。 1 つの欄に畳むと 2 軸の積を名前で列挙することになり、
+  組合せが増えるたびに語が増える。 書かなかった時の矢頭は従来と同じで、見本帳 422 図の
+  矢頭 413 本は指し先も形も 1 つも変わらない。
+
+  **自分から自分へ戻る線** は、それまで検査が「未対応」 として弾いていた。 箱の 1 辺から出て
+  外へ膨らんで同じ辺へ戻る曲線 1 本で描く。 どちら側へ出すかは他の線が使っていない辺から
+  選ぶ = 同じ辺に出すと、横へ抜ける線が輪の内側を通って重なる。
+
+  **始まりと終わりの印** は `mark-start` (塗った丸) と `mark-end` (輪で囲んだ丸)。 これに
+  当たる種別が無く、箱の小見出しに「初期」「最終」 と書いて代えていた。 印は箱いっぱいに
+  描く = 線が箱の縁で止まるので、小さく描くと矢の先と印の間が空いて線が浮く。
+
+- **弧の長さで件どうしを比べる図を新設した** (#550)
+
+  割合を示す図は `chart-pie` だけで、扇の **角度** で比べる形になる。 角度の目測は長さの
+  目測より外れやすく、40% と 45% のような近い値は見分けが付かない。 `chart-bar` は長さで
+  比べられるが、棒の長さは最大値に対する比率で **100% がどこかを示さない**。
+
+  `chart-radial` は 1 件を 1 本の弧にして内側から重ね、各弧の背後に **全周の軌道** を敷く。
+  軌道があることで「あとどれだけで一周か」 が見え、棒グラフに無い「全体に対する割合」 が出る。
+  記法からは `type: radial` で書ける。
+
+  帯の太さは **件数から割り付ける**。 固定すると件数が増えた時に内側の弧が中心を突き抜ける。
+
+  名前は左端に縦へ並べる。 弧のそばに置くと内側の弧ほど場所が狭くなって字が入らない。
+  一覧の幅は中身から決めるので、名前が長い図では弧が小さくなる。
+
+  payload は既存の `chartData` をそのまま使う。 段の進みで弧が伸びる動きは持たない。
+
+- **合計を主役に置く半円の図を新設した** (#549)
+
+  既存の 3 種 (`chart-pie` / `chart-line` / `chart-bar`) はいずれも **内訳の比較** が主役で、
+  「達成率」 「進捗」 「使用量」 のように 1 つの合計を大きく見せる形が書けなかった。 円で
+  代用すると合計を置ける場所が中央しか無く、円が縦に高さを使うため横長の枠では上下が余る。
+
+  `chart-gauge` は上半分だけを弧で描き、空いた下半分に内訳を横並びで置く。 弧が浅いぶん
+  横に広がるので横長の枠と相性が良い。 記法からは `type: gauge` で書ける。
+
+  合計の字の大きさは **内側の空きから逆算する**。 半径の比だけで決めると桁数が増えた時に
+  弧の外へはみ出し、下段の内訳に重なる (実測で踏んだ)。
+
+  内訳には実値と割合の両方を置く。 合計が主役の図で内訳が割合しか持たないと、「合計の何割」
+  は分かっても「いくつ」 が分からず、読み手が暗算することになる。
+
+  payload は既存の `chartData` をそのまま使うため、記法の語を新しく決めずに済む。
+  段の進みで弧が開く動きは持たない (別途判断する)。
+
+### Changed
+
+- **円グラフの名札を扇のそばへ移した** (#548)
+
+  凡例を右に置いていた間、扇と凡例で **目線が往復** していた。 ある扇が何を指すかを知るために
+  凡例まで目を移し、戻って次の扇を見ることになる。 実数はどこにも出ていなかった。
+
+  同じ repo の折れ線と並べて測ると差が出る = 折れ線は 目盛 / 補助線 / 実値 / 印の意匠 /
+  桁区切り の 5 層を持つのに対し、円は塗り分けた塊と凡例しか持たない。
+
+  扇の外へ引き出し線を伸ばし、名前と実数と割合をその場に置いた。 凡例は無くなる。
+  実数には桁区切りを入れる (折れ線と揃える)。
+
+  併せて中央を抜き、空いた場所に合計を置いた。 質感も 3 点変えた = 扇どうしの区切りを線から
+  地の色の余白へ広げ、輪の下に影を敷き、塗りの半透明をやめた。
+
+  **円は #542 の時より小さくなる**。 名札が四方へ出るぶん場所を取るためで、大きさと引き換えに
+  情報の層を増やす判断。 円は依然として枠の高さの 8 割を使う。
+
+  扇の `d` は中央が抜けたぶん変わるが、`data-cdl-role` は変えていない。 段の進みによらず
+  実値のまま、という cdl#516 の約束も保っている。
+
+### Added
+
+- **図表の系列専用の色を新設した** (#546)
+
+  図表は色を明示しない datum に、意味付きの色 (`--cdl-tone-*`) を使い回して配っていた。
+  意味付きの色は箱や矢印が「これは異常」 を示すための色で、**並べて見分ける前提で選ばれて
+  いない**。 明るい画面の `warning` (`#a67a2e`) は彩度が低く青と青緑の隣で沈み、色相の離れた
+  暖色を置こうとすると `error` (赤) しか無いので装飾の色に「異常」 の意味が乗っていた。
+
+  `--cdl-chart-1` から `--cdl-chart-6` を新設し、色相を離した 6 色を既定にした。
+  `--cdl-tone-*` の値は 1 つも変えていない。
+
+  dragon 側で `--cdl-chart-N` を定義すれば明暗で別の値を持てる。 datum に `tone` を明示した
+  場合は従来どおり意味付きの色が優先される。
+
+  いまは円グラフだけが使う。 棒 / 折れ線を寄せるかは別途判断する。
+
+### Fixed
+
+- **円グラフが枠の 4 割を空白にしたまま小さい円を描くのを直した** (#542)
+
+  幅を円と凡例で半分ずつ固定していた。 凡例は名札と割合しか置かないので割り当ての一部しか
+  使わず、横長の枠では右が大きく空いたまま円が小さいままだった (利用側で実測 = 枠 929×465px
+  で右の空白 369px = 幅の 39.7%、円の面積比 24.9%)。
+
+  凡例の幅を `textWidth` で中身から見積もり、残りを円に渡す。 円と凡例をまとめて枠の中央に
+  置くので、余りが左右に均等に散る。 同じ枠で右の空白が 369 → 141px、円の直径が 371 → 406px
+  になった。
+
+  凡例は 1 件 2 行から **1 件 1 行** に変えた。 2 行組みは行の間隔が群の中と群の間で同じに
+  なり、3 件が 3 群に見えなかった (実測 = 6 行が 20px 等間隔)。 割合は右端で揃える。
+
+  取り分は整数のとき小数を出さない (`45.0%` → `45%`)。 字は名札 12 → 14、割合 11 → 13。
+
+  **扇の `d` と `data-cdl-role` は触っていない**。 形から値を測る利用側の経路は変わらない。
+
+  既定の色順 (`FALLBACK_ORDER`) はこの変更に含まない。
+
 予定 ... feedback を反映した patch / minor。
 
+## [0.14.0] - 2026-08-23
+
+### Added
+
+- **箱に入らず落ちた補足を、検査が知らせるようにした** (#538)
+
+  木と放射は箱の中に名前と補足を 2 行で積む (`#471`)。 箱の高さは段の間隔から出るため、段や
+  枝が増えると 2 行が入らなくなり、入らない行は後ろから落ちる。 **落としたことはどこにも
+  出ていなかった** = 知らせも印も無く、記法に書いた文字が図から消えていた。
+
+  幅の側は切られたことが `…` で見える (`#526`) が、高さの側は箱に描く余地が無いから落ちて
+  いるので印を出せない。 検査で伝えるのが唯一の出口になる。
+
+  落ち方は段階的でない。 箱の高さは図の中で揃っているので、1 つ入らなくなると同じ図の補足が
+  全部消える (実測 = 1 本道の木は深さ 8 で 9 件すべて出て、深さ 9 で 10 件すべて消える。
+  放射は枝 18 本で 18 件すべて出て、19 本で 19 件すべて消える)。
+
+  `visual-validate` に軸 `box-line-dropped` を足し、落ちた時に `warn` を出す。 本文には落ちた
+  箱の名前と件数と箱の高さが入る。
+
+  判定は **描く時と同じ関数を同じ引数で呼ぶ**。 描いた結果と突き合わせる形は採らない = 描画と
+  判定で別の経路を通ると、片方だけ直したずれに気付けない。 箱の並べ方と字の大きさも kind 側の
+  1 箇所 (`木の中身` / `木の行` / `放射の中身` / `放射の行`) に集めた。
+
+  **箱の高さは変えない**。 配置の間隔から出ており、変えると図全体が動く。
+
 ## [0.13.1] - 2026-08-22
 
 ### Fixed
@@ -551,7 +798,9 @@ Initial OSS release.
 使わない = annotated tag を push しても GitHub Release は作られず、 Release を作っていない版で
 行き止まりになる。
 
-[Unreleased]: https://github.com/cardene777/cdl/compare/v0.13.1...HEAD
+[Unreleased]: https://github.com/cardene777/cdl/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/cardene777/cdl/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/cardene777/cdl/compare/v0.13.1...v0.14.0
 [0.13.1]: https://github.com/cardene777/cdl/compare/v0.13.0...v0.13.1
 [0.13.0]: https://github.com/cardene777/cdl/compare/v0.12.1...v0.13.0
 [0.12.1]: https://github.com/cardene777/cdl/compare/v0.12.0...v0.12.1

package/README.md

@@ -186,13 +186,32 @@ export const custom = diagram("custom", { topic: "Custom" })
 
 各 kind は shape / color / icon が異なる。 基本 5 は専用 component、 残り 24 種は `GenericNode` で汎用描画。
 
-## EdgeStyle + Tone
+流れの始まりと終わりを示す印として `mark-start` (塗った丸) と `mark-end` (輪で囲んだ丸) がある。
+印そのものが意味を持つので文字は描かない。
+
+書ける種類の全件は `NODE_KINDS` を値として公開しているので、記法を書く側は手書きせずに引ける
+(上の表は代表例で、全件ではない)。
+
+## EdgeStyle + EdgeHead + Tone
 
 | EdgeStyle | 動き |
 |---|---|
 | `solid` | 実線 + 矢頭 marker、 progress 連動で path が伸びる |
 | `dotted-flow` | 点線 + 進行点 glow (3 重円) が path 上を流れる、 node 貫通自動判定 |
 
+端の形 (`head`) は線の種類とは **別の軸** で、線の先端に何を置くかを決める。
+実線 × 三角 (継ぐ) と破線 × 三角 (満たす) は線種で分かれ、
+実線 × 三角 (継ぐ) と実線 × 菱 (持つ) は端で分かれる。
+
+| EdgeHead | 形 | 表すもの |
+|---|---|---|
+| `triangle` | 塗った三角 (**既定**) | 書かなければこれになる |
+| `diamond` | 塗った菱 | 「持っている」 側を指す |
+| `open` | 閉じない 2 本の腕 | 向きだけを示し、待たない |
+| `crow` | 三又 | 「多」 を示す (ER の鳥の足) |
+
+受理する値は `EDGE_HEADS` を値として公開しているので、記法を書く側は手書きせずに引ける。
+
 | Tone | 色 (hex) | 用途 |
 |---|---|---|
 | `accent` | `#c17f3e` | default |