@cardenelabs/dragon 0.28.0 → 0.32.0

package/src/compile/placement.ts

@@ -0,0 +1,15 @@
+/**
+ * 置けたかどうかの判定に使う幅 (#2034 で `compile.ts` から移した)。
+ *
+ * **葉に置く** = 配置を確かめる側 (`verifyPlacement` / `applyLayoutOffsets`) と
+ * 部品の取り込み側 (`縦列に置いた部品を揃える`) の両方が読む。 どちらかに置くと、
+ * もう片方から逆向きの取り込みが生まれて輪になる。
+ */
+
+/**
+ * 書いた通りに置けたと見なす誤差。
+ *
+ * 補正が効いた図種では実測 0.0 で一致する。 効かない向き (順序図の縦) は数百ずれるので、
+ * その間で切る。 丸めと配置計算の揺れを吸収する幅として 1 を取る。
+ */
+export const PLACEMENT_TOLERANCE = 1;

package/src/compile/quadrant.ts

@@ -0,0 +1,265 @@
+import { diagram } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+import { 図表の大きさ, 図表の大きさを読む, 数の欄から参照できる名前, 語の欄から参照できる名前 } from "./chart-fields";
+import { 箱の題 } from "./node-title";
+import type { CompileNotice } from "./notice";
+import { slugify } from "./slug";
+import { 図の小見出し } from "./subtitle";
+import { 区画 } from "./word-state";
+/**
+ * 四象限 (`type: quadrant`) の組み立て (#1154)。 描画側に 1 つの箱で渡す。
+ *
+ * 登場人物ごとに **どの区画か** を読む (`- 重複削除: "左上"`)。 使える語は `区画` が持つ。
+ */
+export function compileQuadrant(
+  doc: DslDocument,
+  onNotice?: (n: CompileNotice) => void,
+): CdlDiagram {
+  const b = diagram(slugify(doc.title), { topic: doc.title, type: "quadrant" });
+  const { w: W, h: H } = 図表の大きさを読む(doc, 図表の大きさ.quadrant);
+  b.lane("chart", { width: W + 64 });
+  const items: NonNullable<CdlDiagram["nodes"][number]["quadrantData"]>["items"] = [];
+  const 読めない: string[] = [];
+  const 参照できる = 語の欄から参照できる名前(doc, 区画);
+  const 数を参照できる = 数の欄から参照できる名前(doc);
+  const 伝える = (a: DslDocument["actors"][number], message: string): void => {
+    onNotice?.({
+      kind: "chart-value-unreadable",
+      actor: a.name,
+      line: a.atPos?.line ?? a.pos?.line ?? 0,
+      message,
+    });
+    if (typeof console !== "undefined" && console.warn) console.warn(`[dragon] ${message}`);
+  };
+  for (const a of doc.actors) {
+    const 語 = (a.value ?? a.subtitle ?? "").trim();
+    if (a.at !== undefined) {
+      const 座標 = 四象限の座標(a.at, 数を参照できる);
+      if (座標 === null) {
+        伝える(
+          a,
+          `type: quadrant で ${a.name} の at (${a.at.raw}) が読めません (図に載せません)。 at: [0.2, 0.8] の形で 0..1 の数か {状態名} を 2 つ書いてください`,
+        );
+        continue;
+      }
+      const 範囲外 = [
+        座標.x,
+        座標.y,
+        ...[座標.x, 座標.y].flatMap((v) =>
+          typeof v === "string" ? 状態が取る値(v, doc) : [],
+        ),
+      ].filter(
+        (v): v is number => typeof v === "number" && (v < 0 || v > 1),
+      );
+      if (範囲外.length > 0) {
+        伝える(
+          a,
+          `type: quadrant で ${a.name} の at (${a.at.raw}) が 0..1 の範囲外です (描画時に最寄りの端へ寄せます)`,
+        );
+      }
+      const q = 区画.get(語);
+      const 座標の区画 = 数の象限(座標);
+      if (q !== undefined && 座標の区画 !== undefined && q !== 座標の区画) {
+        伝える(
+          a,
+          `type: quadrant で ${a.name} の区画 (${語}) と at (${a.at.raw}) の象限が食い違います (at を採ります)`,
+        );
+      }
+      items.push({ id: slugify(a.name), title: 箱の題(a), at: 座標 });
+      continue;
+    }
+    const 参照 = 語.match(/^\{(\w+)\}$/);
+    if (参照) {
+      if (!参照できる.has(参照[1]!)) {
+        読めない.push(a.name);
+        continue;
+      }
+      items.push({ id: slugify(a.name), title: 箱の題(a), quadrant: 語 });
+      continue;
+    }
+    const q = 区画.get(語);
+    if (q === undefined) {
+      読めない.push(a.name);
+      continue;
+    }
+    items.push({ id: slugify(a.name), title: 箱の題(a), quadrant: q });
+  }
+  if (読めない.length > 0) {
+    const m = `type: quadrant で区画を読めない項目があります (図に載せません): ${読めない.join(", ")}。 \`- 重複削除: "左上"\` の形で、 ${[...区画.keys()].join(" / ")} のどれかを書いてください`;
+    onNotice?.({ kind: "chart-value-unreadable", actor: 読めない[0]!, line: 0, message: m });
+    if (typeof console !== "undefined" && console.warn) console.warn(`[dragon] ${m}`);
+  }
+  // 矢印は描けない。 書かれていたら伝える (黙って捨てると「書いたのに効かない」 が残る)
+  if (doc.flow.length > 0) {
+    const m2 = `type: quadrant では矢印を描けません (${doc.flow.length} 本を無視しました)。 関係を描くなら type: flow を使ってください`;
+    onNotice?.({
+      kind: "chart-edge-dropped",
+      actor: doc.flow[0]?.from ?? "",
+      line: doc.flow[0]?.pos?.line ?? 0,
+      message: m2,
+    });
+    if (typeof console !== "undefined" && console.warn) console.warn(`[dragon] ${m2}`);
+  }
+  b.node(`${slugify(doc.title) || "quadrant"}-chart`, {
+    lane: "chart",
+    stack: 0,
+    kind: "quadrant-matrix",
+    title: doc.title,
+    ...図の小見出し(doc),
+    w: W,
+    h: H,
+    quadrantData: { ...軸と区画の名前(doc), items },
+    ...(doc.quadrantPointLabelSide !== undefined
+      ? { quadrantPointLabelSide: doc.quadrantPointLabelSide }
+      : {}),
+    ...(doc.quadrantLabelPosition !== undefined ? { quadrantLabelPosition: doc.quadrantLabelPosition } : {}),
+    ...(doc.quadrantSize !== undefined ? { quadrantSize: doc.quadrantSize } : {}),
+  });
+  return b.build();
+}
+
+function 四象限の座標(
+  at: NonNullable<DslDocument["actors"][number]["at"]>,
+  参照できる: ReadonlySet<string>,
+): { x: number | string; y: number | string } | null {
+  if (!at.raw.startsWith("[") || !at.raw.endsWith("]") || at.x === undefined || at.y === undefined)
+    return null;
+  if (at.raw.slice(1, -1).split(",").length !== 2) return null;
+  const 読める = (v: number | string): boolean => {
+    if (typeof v === "number") return Number.isFinite(v);
+    const m = v.match(/^\{([\w-]+)\}$/);
+    return m !== null && 参照できる.has(m[1]!);
+  };
+  return 読める(at.x) && 読める(at.y) ? { x: at.x, y: at.y } : null;
+}
+
+/** 座標の `{状態名}` が、記法に書かれた範囲で取り得る数を集める。 */
+function 状態が取る値(参照: string, doc: DslDocument): number[] {
+  const m = 参照.match(/^\{([\w-]+)\}$/);
+  if (m === null) return [];
+  const 名前 = m[1]!;
+  const values: number[] = [];
+  const 数を加える = (value: unknown): void => {
+    if (typeof value === "number" && Number.isFinite(value)) values.push(value);
+    else if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)))
+      values.push(Number(value));
+  };
+  let 初期値: unknown;
+  let 初期値あり = false;
+  for (const state of doc.animate?.states ?? []) {
+    if (state.name !== 名前) continue;
+    初期値 = state.initial;
+    初期値あり = true;
+  }
+  if (初期値あり) 数を加える(初期値);
+  for (const phase of doc.animate?.phases ?? []) {
+    for (const tween of phase.tweens ?? []) {
+      if (tween.state !== 名前) continue;
+      数を加える(tween.from);
+      数を加える(tween.to);
+    }
+    for (const set of phase.sets ?? []) if (set.state === 名前) 数を加える(set.value);
+  }
+  return values;
+}
+
+function 数の象限(at: { x: number | string; y: number | string }):
+  | "topLeft"
+  | "topRight"
+  | "bottomLeft"
+  | "bottomRight"
+  | undefined {
+  if (typeof at.x !== "number" || typeof at.y !== "number") return undefined;
+  return `${at.y >= 0.5 ? "top" : "bottom"}${at.x >= 0.5 ? "Right" : "Left"}`;
+}
+
+/** 軸を書かなかった時の名前。 何の軸か分からないため、位置をそのまま出す */
+const 軸の既定 = {
+  xAxis: { left: "小さい", right: "大きい" },
+  yAxis: { bottom: "小さい", top: "大きい" },
+  quadrantLabels: { topLeft: "左上", topRight: "右上", bottomLeft: "左下", bottomRight: "右下" },
+} as const;
+
+/**
+ * 2 軸で仕分ける図の軸と区画の名前を決める (#1251)。
+ *
+ * `axes:` を書かなければ従来どおり位置の名前 (`左上` 等) を出す = 既に描いてある図が動かない。
+ *
+ * 書いたら区画の名前は **軸の名前から決める** (`{上} × {右}`)。 組立て API 側が同じ規則で
+ * 導いており (実測 = `xAxis: {left: "L", right: "R"}` / `yAxis: {bottom: "B", top: "T"}` で
+ * `topLeft: "T × L"`)、 別の規則にすると同じ内容を書いても図が食い違う。
+ *
+ * 片側だけ書いた形では、書かなかった側は既定のままにする。 空文字を渡すと名前の無い軸が描かれる。
+ */
+function 軸と区画の名前(
+  doc: DslDocument,
+): Omit<NonNullable<CdlDiagram["nodes"][number]["quadrantData"]>, "items"> {
+  const 端 = 軸の名前(doc);
+  const x = doc.axes?.x;
+  const y = doc.axes?.y;
+  const xAxis = x !== undefined && "direction" in x && x.direction === true
+    ? { label: x.label, direction: true as const }
+    : 端.xAxis;
+  const yAxis = y !== undefined && "direction" in y && y.direction === true
+    ? { label: y.label, direction: true as const }
+    : 端.yAxis;
+  return { xAxis, yAxis, quadrantLabels: 区画の名前(doc, 端) };
+}
+
+/** 軸の両端の名前。 書かなかった側は既定のまま = 空文字を渡すと名前の無い軸が描かれる */
+function 軸の名前(doc: DslDocument): {
+  xAxis: { left: string; right: string };
+  yAxis: { bottom: string; top: string };
+} {
+  if (doc.axes === undefined) return { xAxis: 軸の既定.xAxis, yAxis: 軸の既定.yAxis };
+  const x = doc.axes.x;
+  const y = doc.axes.y;
+  return {
+    xAxis: {
+      left: x !== undefined && "left" in x ? x.left ?? 軸の既定.xAxis.left : 軸の既定.xAxis.left,
+      right: x !== undefined && "right" in x ? x.right ?? 軸の既定.xAxis.right : 軸の既定.xAxis.right,
+    },
+    yAxis: {
+      bottom: y !== undefined && "bottom" in y ? y.bottom ?? 軸の既定.yAxis.bottom : 軸の既定.yAxis.bottom,
+      top: y !== undefined && "top" in y ? y.top ?? 軸の既定.yAxis.top : 軸の既定.yAxis.top,
+    },
+  };
+}
+
+/**
+ * 区画の中に出す名前 (#2667)。
+ *
+ * 決め方は 3 段で、書いたものが勝つ。
+ *
+ * | 何を書いたか | 出る名前 |
+ * |---|---|
+ * | `regions:` にその区画を書いた | 書いた名前 |
+ * | `axes:` を書いた | 軸の掛け合わせ (`{上} × {左}`) |
+ * | どちらも書かない | 位置の名前 (`左上` 等) |
+ *
+ * **区画ごとに独立して決める**。 `regions:` を 1 つだけ書いた図で、残り 3 つが
+ * 位置の名前に戻ると「書いた所だけ変わる」 という読み方ができなくなる。
+ */
+function 区画の名前(
+  doc: DslDocument,
+  軸: { xAxis: { left: string; right: string }; yAxis: { bottom: string; top: string } },
+): { topLeft: string; topRight: string; bottomLeft: string; bottomRight: string } {
+  const 掛け合わせ =
+    doc.axes === undefined
+      ? 軸の既定.quadrantLabels
+      : {
+          topLeft: `${軸.yAxis.top} × ${軸.xAxis.left}`,
+          topRight: `${軸.yAxis.top} × ${軸.xAxis.right}`,
+          bottomLeft: `${軸.yAxis.bottom} × ${軸.xAxis.left}`,
+          bottomRight: `${軸.yAxis.bottom} × ${軸.xAxis.right}`,
+        };
+  const r = doc.regions;
+  if (r === undefined) return { ...掛け合わせ };
+  return {
+    topLeft: r.topLeft ?? 掛け合わせ.topLeft,
+    topRight: r.topRight ?? 掛け合わせ.topRight,
+    bottomLeft: r.bottomLeft ?? 掛け合わせ.bottomLeft,
+    bottomRight: r.bottomRight ?? 掛け合わせ.bottomRight,
+  };
+}

package/src/compile/record.ts

@@ -0,0 +1,75 @@
+import { CLASS_RELATION_LOOK } from "@cardenelabs/cdl";
+import type { CdlDiagram, CdlEdge, ClassRelationType, Tone } from "@cardenelabs/cdl";
+import type { DslDocument, DslStep } from "../types";
+
+import { ERの関係の指定を作る, ERの関係の矢印 } from "./er-relation";
+import { compileGenericWithAnimate } from "./generic";
+
+/** UML の関係を、印の形と同じ 3 群の色へ寄せる。描画側の classDiagram と同じ決まり。 */
+const クラスの関係の色: Record<ClassRelationType, Tone> = {
+  extends: "accent",
+  implements: "accent",
+  aggregates: "teal",
+  composes: "teal",
+  associates: "success",
+  uses: "success",
+};
+
+/**
+ * 箱が行を持つ図の組み立て (#2782)。
+ *
+ * 畳む前は `er` と `state` の 2 つに分かれており、それぞれが **2 つの経路** を持っていた。
+ * 動きか縦列 (表の図) か種類 (移り変わりの図) を書いた図は共通の経路へ、書かない図は
+ * 組み立て器 (`er()` / `stateMachine()`) の経路へ落ちていた。
+ *
+ * **経路は共通の 1 本だけにする**。 組み立て器の経路は書いた行を捨てており
+ * (`rows: []` を渡していた)、記法に行を書いても図に出なかった。 動きを 1 段足すだけで
+ * 行が現れる形になっていたので、同じ記法が同じ図になるほうへ倒す。
+ */
+export function compileRecord(doc: DslDocument): CdlDiagram {
+  return compileGenericWithAnimate(doc, {
+    kind: "record",
+    laneWidth: 縦列の幅(doc),
+    edgeDefaults: 関係の既定,
+  });
+}
+
+/**
+ * record の関係の既定 (#2783)。
+ *
+ * `relation` がある時だけ UML の関係として読み、`sub` は行き先、`tailSub` は出どころの
+ * 多重度にする。 relation の無い `sub` は従来どおり線の名前の下の行として残す。
+ * relation の有無を境にすることで、既存の record の補足を壊さず、class から移した本文も
+ * 同じ欄のまま同じ端へ置ける。
+ */
+function 関係の既定(s: DslStep): Partial<CdlEdge> {
+  if (s.relation === undefined) {
+    return ERの関係の矢印(ERの関係の指定を作る(s));
+  }
+
+  const 見た目 = CLASS_RELATION_LOOK[s.relation];
+  return {
+    label: s.label,
+    tone: クラスの関係の色[s.relation],
+    style: 見た目.style,
+    head: 見た目.head,
+    headFill: 見た目.fill,
+    tailHead: 見た目.tailHead,
+    tailHeadFill: 見た目.tailFill,
+    ...(s.sub !== undefined ? { headLabel: s.sub } : {}),
+    ...(s.tailSub !== undefined ? { tailLabel: s.tailSub } : {}),
+  };
+}
+
+/**
+ * 縦列の幅 (#2782)。
+ *
+ * **行を持つ箱があるかで決める**。 行を持つ箱は名前と型が左右に分かれて並ぶので幅が要り、
+ * 持たない箱は題だけなので要らない。 畳む前は図種ごとに持っていた値 (表の図 450 /
+ * 移り変わりの図 360) で、どちらも「行を持つか」 の言い換えだった。
+ *
+ * 書いた `lanes:` の幅はこの既定より強い (`compile/lanes.ts` が後から重ねる)。
+ */
+function 縦列の幅(doc: DslDocument): number {
+  return doc.actors.some((a) => (a.rows?.length ?? 0) > 0) ? 450 : 360;
+}

package/src/compile/row-marks.ts

@@ -0,0 +1,128 @@
+import type { RowMark } from "@cardenelabs/cdl";
+
+/**
+ * 行頭の印を dragon の語で決める (#2782)。
+ *
+ * 描画側が持つ印は 3 軸しかない。 形 (四角 / 山形) と 塗り (塗る / 中空) と
+ * 名前の下線で、この 3 軸に 1 対 1 で当たる語を dragon 自身が持つ。
+ *
+ * | 語 | 軸 | 意味 |
+ * |---|---|---|
+ * | `鍵` | 名前に下線を引く | その行で箱を見分ける |
+ * | `外` | 行頭を山形にする | その行は箱の外とつながる |
+ * | `条件` | 行頭を中空にする | その行は条件が揃った時だけ効く |
+ *
+ * 畳む前は 図種ごとに語を持っていた (表の図は `pk` / `fk` / `opt`、移り変わりの図は
+ * `entry` / `exit` / `do` / `internal`)。 2 つの語彙は同じ 2 軸の格子を別の名前で
+ * 呼んでいただけで、格子の 4 隅は 1 対 1 に重なる。
+ *
+ * |  | 塗る | 中空 |
+ * |---|---|---|
+ * | 四角 | 語なし / `do` | `条件` / `opt` / `internal` |
+ * | 山形 | `外` / `fk` / `entry` | `外 条件` / `fk opt` / `exit` |
+ *
+ * 古い語から dragon の語への読み替えは本 file の `行頭の語へ読み替える` が持ち、
+ * 読み取りの入口 (記法 / JSON の 2 経路) が通す。 印にする時点で古い語は 1 つも残っていない。
+ */
+export const 行頭の語 = ["鍵", "外", "条件"] as const;
+
+export type 行頭の語 = (typeof 行頭の語)[number];
+
+/**
+ * 行頭の印の古い語から dragon の 3 語への読み替え (#2782)。
+ *
+ * **ここは図種の別名と向きが違う**。 図種の `er` / `state` は綴りごと消したが (畳んだ先の
+ * `record` が別の名前なので、古い綴りを残すと「名前を無くす」 という目的が達たない)、
+ * 行頭の語は残す = 語が指す印は 1 つに決まっており、`pk` と `鍵` は同じ絵になる。
+ *
+ * 読み替え先は空白区切りの語。 `exit` だけが 2 語になる = 山形 + 中空 の 2 軸を同時に動かす。
+ */
+const 行頭の語の別名: ReadonlyMap<string, string> = new Map([
+  ["pk", "鍵"],
+  ["fk", "外"],
+  ["opt", "条件"],
+  ["entry", "外"],
+  ["exit", "外 条件"],
+  ["do", ""],
+  ["internal", "条件"],
+]);
+
+/**
+ * 1 行分の印の語を dragon の 3 語に揃える (#2782)。
+ *
+ * 1 行に語を 2 つ以上書ける (`pk fk` の形) ので、語ごとに引いて繋ぎ直す。
+ * 知らない語はそのまま通す = 組み立て側が無視するため、書いた人が気付ける形は変わらない。
+ *
+ * **読み取りの入口は 3 経路ある** (縦に並べた形 / 中括弧の形 / JSON)。 3 つとも本 file の
+ * この関数を通す = 1 経路でも素通りさせると、その書き方だけ古い語が印を持たないまま通る
+ * (中括弧の形が実際にそうなっていた)。
+ */
+export function 行頭の語へ読み替える(値: string): string {
+  const 語 = 値.trim().split(/\s+/).filter(Boolean);
+  if (語.length === 0) return 値;
+  return 語
+    .map((w) => 行頭の語の別名.get(w) ?? w)
+    .filter((w) => w !== "")
+    .join(" ");
+}
+
+/**
+ * 書いた語を行頭の印にする (#2782)。
+ *
+ * **語を書かない行にも既定の印を付ける**。 四角 + 塗る + 下線なしで、箱の中で完結して
+ * 常に在る行を表す。
+ *
+ * 印なしにすると、書かなかった行だけ行頭が空いて **群の区切りと見分けが付かなくなる**
+ * (群の区切りは行頭の印が持っている)。 畳む前の表の図が同じ理由で既定を配っていた。
+ */
+export function 行頭の印にする(
+  marks: readonly (string | { mark: string; tone?: "primary" | "muted" })[],
+  行数: number,
+): (RowMark | null)[] {
+  return Array.from({ length: 行数 }, (_, i) => {
+    const 値 = marks[i] ?? "";
+    const 語 = (typeof 値 === "string" ? 値 : 値.mark).trim().split(/\s+/).filter(Boolean);
+    return {
+      shape: 語.includes("外") ? ("chevron" as const) : ("square" as const),
+      filled: !語.includes("条件"),
+      ...(typeof 値 === "object" && 値.tone !== undefined ? { tone: 値.tone } : {}),
+      ...(語.includes("鍵") ? { underline: true } : {}),
+    };
+  });
+}
+
+/**
+ * 箱を見分ける行を上にまとめる (#2782)。
+ *
+ * `鍵` を書いた行を先に、残りを後に置く。 畳む前の表の図が同じ並べ替えをしていた
+ * (組み立て器 `er()` と同じ形)。 `鍵` を 1 つも書かない図では並びが 1 行も動かない。
+ *
+ * **空の行では群を分けない**。 群の区切りは行頭の印が持っており、空の行を挟むと
+ * 行の間隔が不揃いになる (描画側が cdl 0.23.0 で空の行をやめた)。
+ */
+export function 鍵の行を上にまとめる(
+  rows: readonly string[],
+  印: readonly (RowMark | null)[],
+): { rows: string[]; rowMarks: (RowMark | null)[] } {
+  const 鍵: number[] = [];
+  const 値: number[] = [];
+  rows.forEach((_, i) => ((印[i]?.underline === true ? 鍵 : 値).push(i)));
+  const 並び = [...鍵, ...値];
+  return {
+    rows: 並び.map((i) => rows[i] ?? ""),
+    rowMarks: 並び.map((i) => 印[i] ?? null),
+  };
+}
+
+/**
+ * 行頭の印を読む図種か (#2782)。
+ *
+ * **図種の名前を案内の文に写さない**。 読む図種を足した日に案内だけが古くなるため、
+ * 知らせを組む側はここに聞く (`compile.ts` の `行頭の印を読む図種`)。
+ *
+ * 畳む前は 2 図種 (表の図 / 移り変わりの図) が別の語彙で読んでいた。 クラス図は行を
+ * 組み立て器が作るので読まない。
+ */
+export function 行頭の印を読むか(type: string): boolean {
+  return type === "record";
+}

package/src/compile/rows.ts

@@ -0,0 +1,40 @@
+/**
+ * 箱に書いた行を読み取る (#2030 で `compile.ts` から移した)。
+ *
+ * `compileC4` と、`compile.ts` に残る v0.5 の拡張の両方が呼ぶ。
+ *
+ * **葉に置く** = どちらかの側に置くと、もう片方から逆向きの取り込みが生まれる。
+ */
+
+/**
+ * 段の目印を読み取る。 目印と、 それを落とした残りの説明を返す (#1098)。
+ *
+ * 目印 (`L1` / `L2` / `L3`) は「どの段に置くか」 を組み立てに伝えるためのもので、 読む人には
+ * 意味を持たない。 段の名前は枠のラベル (`全体の見取り図` 等) が出すので二重でもある。
+ * 読み取ったら説明から落とす = 書いた人が説明として書いた部分だけが箱に出る。
+ *
+ * | 書いた文字 | 段 | 残る説明 |
+ * |---|---|---|
+ * | `"L1"` | 1 | (無し) |
+ * | `"L2: container"` | 2 | `container` |
+ * | `"L1 利用者"` | 1 | `利用者` |
+ * | `"利用者"` | 1 (既定) | `利用者` |
+ *
+ * 目印の直後の区切り (`:` と空白) も落とす。 残さないと `: container` のように区切りだけが
+ * 先頭に残る。 `L2X` のような別の語を目印と読み違えないよう、 数字の直後が英数字でないことを
+ * 条件にする。
+ */
+export function 段を読み取る(subtitle: string | undefined): {
+  段: number;
+  説明: string | undefined;
+} {
+  const 元 = (subtitle ?? "").trim();
+  const m = 元.match(/^L([123])(?![0-9A-Za-z])/i);
+  if (m === null) return { 段: 1, 説明: subtitle };
+  // 目印と、 その直後の区切り (`:` / 全角コロン / 空白) を落とす
+  const 残り = 元
+    .slice(m[0].length)
+    .replace(/^[:：\s]+/, "")
+    .trim();
+  return { 段: Number(m[1]), 説明: 残り === "" ? undefined : 残り };
+}