@cardenelabs/cdl 0.5.0

package/src/kinds/shape-region.tsx

@@ -0,0 +1,383 @@
+/**
+ * `shape-` の絵をどこに置き、 どこまで縮めるかを決める共通部 (#433)。
+ *
+ * `shape-` は絵を **自分の大きさ** で描くため、 箱が小さいと絵が箱の外に出る。 呼び出し側
+ * (順序図の名札は高さ 72) で実測すると 49 種のうち 36 種が下か左右にはみ出していた。
+ *
+ * 原因は 2 つに分かれる。 ここが直すのは前者。
+ *
+ * | 型 | 件数 | 中身 |
+ * |---|---|---|
+ * | 高さに依存 | 23 | 箱を大きくすると収まる。 絵が固定の寸法で描かれ、 箱の高さを見ていない |
+ * | 高さに依らない | 13 | どんな箱でも出る。 幾何そのものの誤り (`#434`) |
+ *
+ * ## 覆えていない範囲 (#436)
+ *
+ * **収めた分だけ絵は小さくなる**。 高さ 72 の箱に「絵 180px + 名前 + 説明 + 肩書」 を入れると
+ * 絵に残るのは 28px で、 倍率 0.156 = 3px の線が 0.47px になり細部が読めない。
+ *
+ * | 書いた文字 | h=72 の倍率 | 3px の線 |
+ * |---|---|---|
+ * | 名前だけ | 0.290 | 0.87 |
+ * | + 説明 | 0.223 | 0.67 |
+ * | + 説明 + 肩書 | 0.156 | 0.47 |
+ *
+ * 直すには「絵を優先して字を削る」 か「字を優先して絵を描かない」 かの判断が要り、 製品の
+ * 方針として決める必要がある。 `#436` で扱う。
+ */
+import type { JSX } from "react";
+import type { LaidNode } from "../types";
+
+// 既存の呼出 (検査を含む) がここから取っているため、 そのまま出し直す。
+export { textWidth } from "./text-width";
+
+/** 名前の字の大きさの上限。 大きい箱ではここに当たり、 今までの見え方を保つ。 */
+const TITLE_MAX = 18;
+
+/**
+ * 読める字の下限。 **これを割るのは箱が狭すぎる時だけ**。
+ *
+ * 一律の下限にはできない。 3 行で高さ 36 以下の箱では、 9 を守ると塊が箱の上端を越える
+ * (review 指摘)。 箱に入る大きさを優先し、 下限を割ったことは `labelPlan` の返り値で分かる。
+ */
+const TITLE_MIN = 9;
+
+/** 箱の高さに対する名前の字の割合。 高さ 72 で 12、 高さ 106 以上で上限 18 に当たる。 */
+const TITLE_RATIO = 0.17;
+
+/** 名前に対する説明と肩書の字の割合。 */
+const SUB_RATIO = 0.72;
+
+/** 字と字の間に空ける量。 */
+const LINE_GAP = 3;
+
+/** 箱の下端との間に空ける量の下限。 字の下の張り出しがこれを超えるならそちらを採る。 */
+const BOTTOM_PAD = 4;
+
+/**
+ * 字が baseline から上下へ張り出す量の見積り。
+ *
+ * 描く側 (`shape-basement` の `commonLabel`) と測る側 (検査) が同じ値を使う = 書き写すと
+ * 片方だけ古くなる。
+ */
+export const ASCENT = 0.72;
+export const DESCENT = 0.25;
+
+/** 絵と名前の塊の間に空ける量。 */
+const ART_GAP = 4;
+
+/** 名前の塊の 1 行。 */
+export type LabelLine = { y: number; size: number };
+
+/**
+ * 名前の塊を **箱の下端から積み上げる**。
+ *
+ * 上から順に置くと、 箱が小さい時に肩書が絵の領域へ食い込む (実測 = 高さ 72 で 13.6)。
+ * 下から積めば、 書いてある行だけが必要な高さを取り、 残りがそのまま絵の帯になる。
+ *
+ * 字の大きさは箱の高さに比例させ、 上限で止める。 大きい箱では上限に当たるので今までの
+ * 見え方が変わらない。
+ */
+export function labelPlan(node: LaidNode): {
+  名前: LabelLine;
+  説明: LabelLine | null;
+  肩書: LabelLine | null;
+  /** 名前の塊の上端。 絵の帯はここまで。 */
+  top: number;
+  /**
+   * 描いた行の **すべて** が読める下限 (9) を保てたか。 箱が狭すぎると `false` になる。
+   *
+   * 名前だけを見てはいけない。 説明と肩書は名前の 0.72 倍なので、 名前が 9 でも補いの行は 6 に
+   * なる (高さ 53 で実測、 review 指摘)。 一番小さい行で判定する。
+   */
+  読める: boolean;
+} {
+  const 高さ = Math.max(0, node.h);
+  const 底 = node.cy + 高さ / 2;
+  const 天 = node.cy - 高さ / 2;
+
+  /**
+   * 下から順に積んで、 各行の baseline と塊の上端を返す。
+   *
+   * **式で近似しない**。 積み方 (`y -= 大きさ + 隙間`) と別に高さの式を持つと、 2 つがずれて
+   * 塊が箱から出る (h=9 の 2 行で 0.28 出た)。 実際に積んで測る。
+   */
+  const 積む = (名前大: number, 説明あり: boolean, 肩書あり: boolean, 下余白: number) => {
+    const 小さい字 = Math.max(1, Math.round(名前大 * SUB_RATIO));
+    let y = 底 - 下余白;
+    const 説明 = 説明あり ? { y, size: 小さい字 } : null;
+    if (説明 !== null) y -= 小さい字 + LINE_GAP;
+    const 名前 = { y, size: 名前大 };
+    y -= 名前大 + LINE_GAP;
+    const 肩書 = 肩書あり ? { y, size: 小さい字 } : null;
+    const 上の行 = 肩書 ?? 名前;
+    return { 名前, 説明, 肩書, 上端: 上の行.y - 上の行.size * ASCENT };
+  };
+
+  /**
+   * 何行入るか。 **入らない行は描かない**。
+   *
+   * 隙間だけで箱の高さを超える組合せがある (2 行は隙間 3 で、 高さ 1 の箱には入らない)。
+   * 字を小さくしても解けないので、 補いの行を落とす。 落とす順は肩書が先で、 名前は必ず残す。
+   */
+  const 入る = (説明あり: boolean, 肩書あり: boolean): boolean =>
+    積む(1, 説明あり, 肩書あり, 1 * DESCENT).上端 >= 天;
+
+  let 説明あり = Boolean(node.subtitle);
+  let 肩書あり = Boolean(node.eyebrow);
+  if (!入る(説明あり, 肩書あり)) 肩書あり = false;
+  if (!入る(説明あり, 肩書あり)) 説明あり = false;
+
+  // 箱に入る一番大きい字を探す。 上限は「高さに比例」 と「読める上限」 の小さい方
+  const 上限 = Math.min(TITLE_MAX, Math.max(1, Math.round(高さ * TITLE_RATIO)));
+  let 名前大 = 0;
+  for (let size = 上限; size >= 1; size--) {
+    const 小さい字 = Math.max(1, Math.round(size * SUB_RATIO));
+    const 下の行大 = 説明あり ? 小さい字 : size;
+    if (積む(size, 説明あり, 肩書あり, 下の行大 * DESCENT).上端 >= 天) {
+      名前大 = size;
+      break;
+    }
+  }
+
+  // **1 でも入らない箱がある**。 名前 1 行でも上下の張り出しで 0.97 要るため、 高さ 0.97 未満の
+  // 箱では整数の大きさに解が無い (review 指摘)。 名前は落とせないので、 ちょうど入る大きさまで
+  // 下げる。 見えない字にはなるが、 箱の外へ出て隣の領域を汚すよりは良い
+  if (名前大 === 0) 名前大 = 高さ / (ASCENT + DESCENT);
+
+  // 下の余白は余った分までしか取れない。 固定の 4 を無条件に取ると塊が上へ出る
+  const 小さい字 = Math.max(1, Math.round(名前大 * SUB_RATIO));
+  const 張り出し = (説明あり ? 小さい字 : 名前大) * DESCENT;
+  const 余り = Math.max(0, 積む(名前大, 説明あり, 肩書あり, 張り出し).上端 - 天);
+  const 下余白 = Math.min(Math.max(BOTTOM_PAD, 張り出し), 張り出し + 余り);
+
+  const 組 = 積む(名前大, 説明あり, 肩書あり, 下余白);
+  const 一番小さい行 = Math.min(
+    ...[組.名前, 組.説明, 組.肩書].filter((l) => l !== null).map((l) => l.size),
+  );
+  return {
+    名前: 組.名前,
+    説明: 組.説明,
+    肩書: 組.肩書,
+    top: 組.上端,
+    読める: 一番小さい行 >= TITLE_MIN,
+  };
+}
+
+/**
+ * 絵を置く領域。 箱の上端から、 名前の塊の手前まで。
+ *
+ * `labelY` は名前の baseline (今までの呼出との互換)。
+ */
+export function shapeRegion(node: LaidNode): {
+  cx: number;
+  cy: number;
+  availW: number;
+  availH: number;
+  labelY: number;
+  label: ReturnType<typeof labelPlan>;
+} {
+  const label = labelPlan(node);
+  const 天 = node.cy - node.h / 2;
+  const availH = Math.max(0, label.top - ART_GAP - 天);
+  return {
+    cx: node.cx,
+    cy: 天 + availH / 2,
+    availW: node.w,
+    availH,
+    labelY: label.名前.y,
+    label,
+  };
+}
+
+/**
+ * 影の楕円を本体の下端からどれだけ下に置くか。 `shape-basement` の `dropShadow` と共有する
+ * = 別々に持つと、 影を動かした時に帯の計算だけが古くなる。
+ */
+export const SHADOW_GAP = 8;
+
+/** 枠線の太さ (`active` の 3) の半分。 線は path の中心から外へこれだけ出る。 */
+export const FRAME_HALF = 1.5;
+
+/** 絵を描いてよい帯。 `右` と `底` は `x + w` / `y + h` を書き写さないために持つ。 */
+export type BodyBand = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  cx: number;
+  cy: number;
+  右: number;
+  底: number;
+};
+
+/**
+ * 箱から **影と枠を先に引いた帯**。 絵はこの帯いっぱいに描く。
+ *
+ * 影は本体の下端から `SHADOW_GAP` 下がった中心に `ry` で描くため、 **下へ出る量は箱の高さに
+ * 依らない** (高さ 72 でも 400 でも 12)。 比で縮めて (`fitArt`) 解こうとすると、 影が出ない
+ * 大きい箱まで絵が小さくなるうえ、 小さい箱では影の分がそのまま残る。 先に引いてから描く。
+ *
+ * 帯を使うと **箱の縁と絵の縁の隙間が箱の高さに依らない定数** になる。 比で縮める直し方は
+ * この定数性を破るので、 検査が誤った直し方を捕まえられる。
+ *
+ * `外` は枠以外の理由で外へ出る絵 (`shape-hexagon` の頂点の点) がある時に広げる。
+ *
+ * ## 大きい箱でも余白を引く (捨てた要件)
+ *
+ * **帯は箱の大きさに関わらず余白を引く**。 高さ 400 の箱でも高さ 40 の箱でも同じだけ引く
+ * (`外` 既定 1.5 + `SHADOW_GAP` 8 + `影ry` 4 = 縦 13.5、 横は `外` × 2 = 3)。 本体は帯いっぱいに
+ * 描くので、 **変更前より本体が縦 13.5 / 横 3 小さくなる**。 高さ 200 でも 400 でも同じ差 (実測)。
+ *
+ * | 種別 | 本体の縮み (縦 / 横) | 理由 |
+ * |---|---|---|
+ * | folder / diamond / stack / file / cloud | 13.5 / 3 | `外` 1.5 + 影 12 |
+ * | hexagon | 14.5 / 5 | `外` が頂点の点で 2.5 |
+ * | cylinder | 12.5 / 3 | `影ry` が 3 |
+ *
+ * 「影まで箱に収める」 と「大きい箱では本体の大きさと位置を変えない」 は **同時には満たせない**。
+ * 影は本体の下端から `SHADOW_GAP + 影ry` 下に出て、 その量は箱の高さに依らないので、 本体を
+ * 箱いっぱいに描く限り影は必ず箱の外に残る。 **前者を採った**。 大きい箱で本体が一回り
+ * 小さくなるのは、 影を箱に入れるために払う代償。
+ */
+export function bodyBand(node: LaidNode, opt: { 影ry: number; 外?: number }): BodyBand {
+  const 影 = Math.max(0, opt.影ry);
+  const 外 = Math.max(0, opt.外 ?? FRAME_HALF);
+  const 下余白 = Math.max(SHADOW_GAP + 影, 外);
+  const 箱w = Math.max(0, node.w);
+  const 箱h = Math.max(0, node.h);
+
+  // 余白の合計が箱を超える小さい箱では比で詰める。 引き切ると帯が箱の外へ回り込む
+  const 縦余白 = 外 + 下余白;
+  const ky = 縦余白 > 箱h && 縦余白 > 0 ? 箱h / 縦余白 : 1;
+  const 横余白 = 外 * 2;
+  const kx = 横余白 > 箱w && 横余白 > 0 ? 箱w / 横余白 : 1;
+
+  const x = node.cx - 箱w / 2 + 外 * kx;
+  const y = node.cy - 箱h / 2 + 外 * ky;
+  const w = Math.max(0, 箱w - 横余白 * kx);
+  const h = Math.max(0, 箱h - 縦余白 * ky);
+  return { x, y, w, h, cx: x + w / 2, cy: y + h / 2, 右: x + w, 底: y + h };
+}
+
+/**
+ * 字の塊を帯に収める倍率と置き場所。
+ *
+ * 字の大きさと行間が固定なので、 小さい箱では塊が箱の下へ出る (高さ 40 の `shape-folder` で
+ * 下へ 6.4)。 **一様に縮めてから帯の内へ寄せる** = 塊の縦横はどちらも倍率にそのまま比例
+ * するので、 帯に入る倍率が 1 なら大きい箱では今までどおりの位置と大きさになる。
+ *
+ * **縦だけで倍率を決めてはいけない**。 字数を見ないと、 幅 120 の箱で 22 字の名前が左右へ
+ * 50 以上出る (中央揃えなので両側に出る)。 `幅` を分母に入れて横も見る。
+ *
+ * `上` / `下` は倍率 1 の時に baseline から上下へ張り出す量、 `幅` は一番広い行の横幅。
+ * 呼ぶ側が自分の書式から出す。
+ */
+export function fitLabel(
+  band: { x: number; y: number; w: number; h: number },
+  block: { 上: number; 下: number; 幅: number },
+  pos: { x: number; y: number },
+): { k: number; x: number; y: number } {
+  const 縦 = block.上 + block.下;
+  const 横 = Math.max(0, block.幅);
+  if (!(縦 > 0)) return { k: 1, x: pos.x, y: pos.y };
+  // 帯が潰れた箱では寄せ先が無い。 倍率 0 で描けば箱の外は汚さない
+  if (!(band.h > 0) || !(band.w > 0)) return { k: 0, x: band.x + band.w / 2, y: band.y };
+  const k = Math.min(1, band.h / 縦, 横 > 0 ? band.w / 横 : 1);
+  // 下端と右端を帯に入れてから、 上端と左端が出る分だけ押し戻す。 倍率が帯に入るまで
+  // 落ちているので、 2 つの寄せは両立する
+  const 半 = (横 * k) / 2;
+  return {
+    k,
+    x: Math.max(band.x + 半, Math.min(pos.x, band.x + band.w - 半)),
+    y: Math.max(band.y + block.上 * k, Math.min(pos.y, band.y + band.h - block.下 * k)),
+  };
+}
+
+/**
+ * 絵が (cx, cy) を中心にどこまで広がるか。 描く側が **自分の定数から** 出す。
+ *
+ * 表に書き写さない = 絵の定数を変えた時に片方だけ古くなる。
+ */
+export type ArtExtent = { 上: number; 下: number; 左: number; 右: number };
+
+/**
+ * 絵を領域に収める。 **判定できる入力では常に中心を合わせ、 収まらない時だけ縮める**。
+ *
+ * **縦横の比は保つ**。 潰すと絵が読めなくなる (`shape-wallet` が上へ 12.1 しか出ないのに
+ * 名前と重なって読めなくなった例がある)。
+ *
+ * 手を触れずにそのまま返すのは 4 通り。 それ以外は必ず包む。
+ *
+ * | 入力 | 返り値 |
+ * |---|---|
+ * | 広がりの縦か横が有限の正の値でない | 渡された絵をそのまま (判定できないので手を触れない) |
+ * | 領域の幅か高さが有限の正の値でない | 同上 |
+ * | 倍率が有限の正の値でない | 同上 |
+ * | 倍率 1 かつ中心が既に合っている (対称な絵) | 同上 (余計な `<g>` を挟まない) |
+ * | 上記以外 | `<g transform="translate(...) scale(...)">` で包む |
+ *
+ * **「正」 だけでなく「有限」 も要る**。 `Infinity > 0` は真になるため、 大小の比較だけでは
+ * 無限値が防御をすり抜ける。 すり抜けても変換の数値は壊れない (`cx` / `cy` が有限なら
+ * `dx` / `dy` も有限) が、 **縁を持たない軸では「収まるか」 の判定が常に真になる**。 この
+ * 関数が返しているのは「領域に収めた絵」 で、 その約束がその軸で意味を失う。 負の値は倍率も
+ * 負にして絵を反転させ、 `NaN` は大小の比較そのものをすり抜ける。 いずれも渡された値を領域
+ * として扱えないので、 **判定できない入力では手を触れない**。
+ *
+ * **倍率 1 でも包むことがある** (#438)。 上下 (左右) の広がりが非対称な絵は、 縮まない
+ * 大きさの箱でも中心を合わせるために `scale(1)` 付きで包む。 この wrapper を「不要な層」 と
+ * 見て外すと、 非対称な絵が領域の中心から外れて名前に食い込む (実測 = 人型が高さ 240 の箱で
+ * 帯を 26.5 超えた)。
+ */
+export function fitArt(
+  region: { cx: number; cy: number; availW: number; availH: number },
+  extent: ArtExtent,
+  art: JSX.Element,
+): JSX.Element {
+  const 縦 = extent.上 + extent.下;
+  const 横 = extent.左 + extent.右;
+  // 広がりが無限なら倍率が 0 になるので後段の `s` の防御でも止まる。 ここで先に落とすのは
+  // 契約 (有限で正の値だけを通す) を入口で 1 つに揃えるため
+  if (!Number.isFinite(縦) || !Number.isFinite(横) || 縦 <= 0 || 横 <= 0) return art;
+
+  // **ここは後段の `s` の防御では代替できない**。 無限の軸は倍率の候補が `Infinity` になって
+  // `Math.min` から落ちるだけなので、 残りの候補 (上限 1 と反対の軸) で倍率が決まり、 通常の
+  // 入力として後段へ進む。 負なら倍率も負になって絵が反転する
+  if (
+    !Number.isFinite(region.availH) ||
+    !Number.isFinite(region.availW) ||
+    region.availH <= 0 ||
+    region.availW <= 0
+  ) {
+    return art;
+  }
+
+  const s = Math.min(1, region.availH / 縦, region.availW / 横);
+  if (!Number.isFinite(s) || s <= 0) return art;
+
+  // 絵の外接矩形の中心を領域の中心に合わせる。 上下 (左右) の広がりが違うので、 中心を
+  // そろえないと片側だけはみ出す
+  const 絵cx = region.cx + (extent.右 - extent.左) / 2;
+  const 絵cy = region.cy + (extent.下 - extent.上) / 2;
+  const dx = region.cx - s * 絵cx;
+  const dy = region.cy - s * 絵cy;
+
+  // **縮める時だけ中心を合わせるのは誤り** (#438)。 上下の広がりが非対称な絵は、 縮まない
+  // 大きさの箱でも領域の中心から外れたまま描かれる。
+  //
+  // 実測 = 人型は下へ 128 広がる。 高さ 240 の箱では帯が 101.5 で、 縦の合計 (上 51.5 +
+  // 下 128 = 179.5) は帯に収まるので倍率は 1 になるが、 絵の下端は帯を 26.5 超えて名前に
+  // 食い込む。 「収まるか」 を合計だけで見て位置を見ていなかった。
+  //
+  // 倍率が 1 で中心も合っている時だけ包まない = 対称な絵に余計な `<g>` を挟まない。
+  if (s >= 1 && dx === 0 && dy === 0) return art;
+
+  // **包む時は必ず `translate` と `scale` を両方書く**。 倍率 1 の時に `translate` だけを
+  // 書くと変換の形が 2 通りになり、 読む側が両方を扱う必要が出る (実測 = 検査の変換 parser が
+  // `translate(0 1)` を読めず 8 件落ちた)。 `scale(1)` は無害なので形を 1 つに保つ
+  return (
+    <g transform={`translate(${dx} ${dy}) scale(${s})`}>
+      {art}
+    </g>
+  );
+}