@cardenelabs/cdl 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as CdlDiagram, S as Signal, a as CdlInput, b as CdlLane, c as CdlNode, T as Tone, d as Side, E as EdgeStyle, e as CdlState, f as CdlEventTarget, g as Computed, h as CdlDerivedValue, i as CdlScrollTrigger, L as LaidDiagram, j as CdlDiagramViewProps, k as LaidEdge, l as LaidNode, m as CdlEdge, B as BBox, N as NodeKind, J as JourneyEmotion, Q as QuadrantKey } from './render-DquCvgOB.cjs';
-export { n as CdlDiagramView, o as CdlEventBinding, p as CdlEventKind, q as CdlFormula, r as CdlPhase, I as InteractiveHandlerMap, s as InteractiveSignalsAccessor, t as LaidLane, u as NODE_KINDS, v as ScrollProgressHandle, w as TONES, x as computeEventBindingKey, y as computeFormulaKey, z as computeInputSignalKey, A as computeScrollTriggerKey, D as computed, F as createInteractiveSignalsAccessor, G as createScrollProgressHandle, H as createScrollProgressSignals, K as hasInteractivePrimitives, M as signal } from './render-DquCvgOB.cjs';
+import { C as CdlDiagram, S as Signal, a as CdlInput, b as CdlLane, c as CdlNode, T as Tone, d as Side, E as EdgeStyle, e as CdlState, f as CdlEventTarget, g as Computed, h as CdlDerivedValue, i as CdlScrollTrigger, L as LaidDiagram, j as CdlDiagramViewProps, k as LaidEdge, l as LaidNode, m as CdlEdge, B as BBox, N as NodeKind, J as JourneyEmotion, Q as QuadrantKey } from './render-hmFRAabt.cjs';
+export { n as CdlDiagramView, o as CdlEventBinding, p as CdlEventKind, q as CdlFormula, r as CdlPhase, I as InteractiveHandlerMap, s as InteractiveSignalsAccessor, t as LaidLane, u as NODE_KINDS, v as ScrollProgressHandle, w as TONES, x as computeEventBindingKey, y as computeFormulaKey, z as computeInputSignalKey, A as computeScrollTriggerKey, D as computed, F as createInteractiveSignalsAccessor, G as createScrollProgressHandle, H as createScrollProgressSignals, K as hasInteractivePrimitives, M as signal } from './render-hmFRAabt.cjs';
 import { JSX } from 'react';
 
 declare function effect(fn: () => void | (() => void)): () => void;
@@ -1535,7 +1535,7 @@ interface Violation {
     detail: string;
     severity: "error" | "warn";
 }
-type VisualAxis = "node-visibility" | "edge-label-overlap" | "edge-label-proximity" | "text-readability" | "row-format" | "alignment" | "clearance" | "arrow-endpoint-anchoring" | "label-char-range" | "node-overlap" | "edge-crossing" | "edge-node-cross" | "edge-segment-orthogonality" | "label-inside-viewbox" | "lane-cx-consistency" | "row-vertical-spacing" | "group-boundary-clearance" | "node-vertical-clearance" | "lane-lane-gap" | "arrow-marker-clearance" | "grid-alignment" | "phase-layout-stability" | "responsive-viewport" | "accessibility-basics" | "animation-frame-integrity" | "i18n-cjk-detection" | "contrast-basics" | "print-media-compat" | "color-blind-safety" | "marker-gradient-def-integrity" | "subpixel-precision" | "dom-complexity-budget" | "reduced-motion-compat" | "touch-target-size" | "row-content-typing" | "terminal-safe-text" | "gpu-layer-efficiency" | "memory-budget" | "svg-injection-safety" | "seo-metadata-quality" | "bidi-hyphenation" | "structured-data-extraction" | "diagram-version-semver" | "migration-path-consistency" | "axis-coverage-meta" | "axis-documentation-completeness" | "fixture-drift-detection" | "locale-parity" | "validate-performance-budget" | "node-inside-viewbox" | "node-inside-lane" | "edge-inside-viewbox" | "lane-label-inside-viewbox" | "lane-label-overlap" | "row-alignment" | "column-alignment" | "edge-stubout-min" | "fan-origin-single-point" | "detour-slot-distinct" | "arrow-endpoint-center" | "lane-border-clearance" | "row-gap-uniform" | "column-gap-uniform" | "rows-not-rendered" | "malformed-input" | "validation-interrupted";
+type VisualAxis = "node-visibility" | "edge-label-overlap" | "edge-label-proximity" | "text-readability" | "row-format" | "alignment" | "clearance" | "arrow-endpoint-anchoring" | "label-char-range" | "node-overlap" | "edge-crossing" | "edge-node-cross" | "edge-segment-orthogonality" | "label-inside-viewbox" | "lane-cx-consistency" | "row-vertical-spacing" | "group-boundary-clearance" | "node-vertical-clearance" | "lane-lane-gap" | "arrow-marker-clearance" | "grid-alignment" | "phase-layout-stability" | "responsive-viewport" | "accessibility-basics" | "animation-frame-integrity" | "i18n-cjk-detection" | "contrast-basics" | "print-media-compat" | "color-blind-safety" | "marker-gradient-def-integrity" | "subpixel-precision" | "dom-complexity-budget" | "reduced-motion-compat" | "touch-target-size" | "row-content-typing" | "terminal-safe-text" | "gpu-layer-efficiency" | "memory-budget" | "svg-injection-safety" | "seo-metadata-quality" | "bidi-hyphenation" | "structured-data-extraction" | "diagram-version-semver" | "migration-path-consistency" | "axis-coverage-meta" | "axis-documentation-completeness" | "fixture-drift-detection" | "locale-parity" | "validate-performance-budget" | "node-inside-viewbox" | "shape-label-dropped" | "node-inside-lane" | "edge-inside-viewbox" | "lane-label-inside-viewbox" | "lane-label-overlap" | "row-alignment" | "column-alignment" | "edge-stubout-min" | "fan-origin-single-point" | "detour-slot-distinct" | "arrow-endpoint-center" | "lane-border-clearance" | "row-gap-uniform" | "column-gap-uniform" | "rows-not-rendered" | "malformed-input" | "validation-interrupted";
 /**
  * 検査の用途。 用途によって見るべき軸が違う。
  *
@@ -2643,6 +2643,16 @@ declare function bboxDiffWorld(predicted: {
     max: number;
 };
 
+/**
+ * 状態を読む書き方 (`{名前}`)。
+ *
+ * 中身の型 (`BoundNumber` / `BoundEnum`) は任意の文字列を受けるが、 **入口はこの形だけに
+ * 限る** (#468 Round 1)。 広いままだと `value: "abc"` や `quadrant: "topLfet"` のような
+ * 書き間違いが、 これまで組み立ての時点で止まっていたのに実行時まで進み、 解決側の既定値
+ * (0 / 左下 / 普通) に落ちた図が出る。
+ */
+type 名前の頭 = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "_";
+type BindingRef = `{${名前の頭}${string}}`;
 /**
  * 高位 API ... 著者が「lane / node / edge を 1 件ずつ宣言」 する低位 API を簡略化。
  *
@@ -2690,10 +2700,32 @@ type FlowPreset = {
     /** edge tone / style の default (各 step → next step の edge) */
     defaultTone?: Tone;
     defaultStyle?: EdgeStyle;
+    /**
+     * step 間の edge を自動生成するか (既定 true)。
+     *
+     * `false` にすると `step()` は node だけを置き、矢印は呼び手が `edge()` で宣言する。
+     * **並び順と違う流れ** (`alpha` から `gamma` へ直接繋いで `beta` を経由しない等) を
+     * 書きたい時に使う。 自動生成しか無かった間、その形は本 preset では作れなかった (#474)。
+     *
+     * 既定を `true` にしているので、既存の呼び出しは 1 行も変えずに同じ図になる。
+     */
+    autoChain?: boolean;
 };
 type FlowBuilder = {
-    /** step を順番に追加、 自動で前 step から edge 接続 */
+    /** step を順番に追加、 自動で前 step から edge 接続 (`autoChain: false` なら node だけ) */
     step: (node: FlowStepInput, edgeLabel?: string) => FlowBuilder;
+    /**
+     * 矢印を宣言する (#474)。 tone / style は preset の既定を引き継ぐ。
+     *
+     * ここで作った矢印も `build()` の phase の `activate` に載る (自動生成分と同じ扱い)。
+     * 載せないと animation で光らず、自動生成と見た目が揃わない。
+     */
+    edge: (from: string, to: string, opts?: {
+        id?: string;
+        label?: string;
+        tone?: Tone;
+        style?: EdgeStyle;
+    }) => FlowBuilder;
     build: () => ReturnType<DiagramBuilder["build"]>;
 };
 /**
@@ -3023,8 +3055,8 @@ type TreeNode = {
     parent?: string;
     /** 表示 kind (default "card") */
     kind?: NodeKind;
+    /** 箱の 2 行目に出す補足。 上の小ラベルは木では受けない (#471、 `TreeNodePayload` 参照) */
     subtitle?: string;
-    eyebrow?: string;
 };
 type TreePreset = {
     id: string;
@@ -3055,7 +3087,8 @@ declare function tree(preset: TreePreset): TreeBuilder;
 type JourneyStep = {
     id: string;
     title: string;
-    emotion: JourneyEmotion;
+    /** 起伏の段階。 `{名前}` を書くと状態から読む (#468) */
+    emotion: JourneyEmotion | BindingRef;
     /** どの touchpoint (例 "Website", "Email", "Support") */
     touchpoint?: string;
     /** opportunity (改善余地のメモ) */
@@ -3121,8 +3154,8 @@ declare function mindMap(preset: MindMapPreset): MindMapBuilder;
 type FunnelStage = {
     id: string;
     title: string;
-    /** この stage の人数 / 件数 */
-    count: number;
+    /** この stage の人数 / 件数。 `{名前}` を書くと状態から読む (#468) */
+    count: number | BindingRef;
     /** stage 詳細 */
     subtitle?: string;
 };
@@ -3153,8 +3186,8 @@ type QuadrantQuadrantLabel = QuadrantKey;
 type QuadrantItem = {
     id: string;
     title: string;
-    /** どの象限 (4 象限) */
-    quadrant: QuadrantQuadrantLabel;
+    /** どの象限 (4 象限)。 `{名前}` を書くと状態から読む (#468) */
+    quadrant: QuadrantQuadrantLabel | BindingRef;
     subtitle?: string;
 };
 type QuadrantPreset = {
@@ -3198,7 +3231,8 @@ type ChartType = "pie" | "bar" | "line";
 type ChartDatum = {
     id: string;
     label: string;
-    value: number;
+    /** 棒 / 折れ線 / 扇の大きさ。 `{名前}` を書くと状態から読む (#468) */
+    value: number | BindingRef;
     /** 個別 tone (default は preset の defaultTone) */
     tone?: Tone;
 };
@@ -3231,9 +3265,15 @@ declare function chart(preset: ChartPreset): ChartBuilder;
 type GanttTask = {
     id: string;
     title: string;
-    /** 開始 (例 "2026-Q1" / "Day 1") */
+    /**
+     * 開始の目盛りの名前 (例 "2026-Q1" / "Day 1")。
+     *
+     * `{名前}` を書くと **位置そのもの** を状態から読む (#468)。 目盛りの名前の対応付けは
+     * 飛ばす = 名前の並びに `{名前}` が混ざると、 位置が状態で動くたびに目盛りの並びが
+     * 変わってしまう。
+     */
     start: string;
-    /** 終了 (例 "2026-Q2") */
+    /** 終了の目盛りの名前。 `{名前}` の扱いは `start` と同じ (#468) */
     end: string;
     /** owner / assignee */
     owner?: string;
@@ -3245,6 +3285,17 @@ type GanttPreset = {
     topic: string;
     defaultTone?: Tone;
     laneWidth?: number;
+    /**
+     * 横軸を何目盛り分にするか (`#483`)。
+     *
+     * 書かないと今までどおり全 task の最大値から自動で決まるため、 `{名前}` で動く task が
+     * 1 つあると **動かしていない task の帯まで伸び縮みする** (実測 = 端を 3 から 9 に動かすと
+     * 静的な task の帯が 252 から 97.2 になった)。
+     *
+     * 書くと尺がその値で固定され、 他の task の帯の位置と幅が変わらない。 範囲から外れる task の
+     * 帯は右端の目盛りに寄せて描く (`kinds/gantt.tsx` SSOT)。
+     */
+    axisMax?: number;
 };
 type GanttBuilder = {
     task: (t: GanttTask) => GanttBuilder;
@@ -3254,8 +3305,11 @@ type GanttBuilder = {
  * gantt preset ... Gantt chart / sprint planning / release timeline。
  * task ごとに 1 lane を作り、 start - end + owner を subtitle、 dependsOn で前 task → 次 task の edge を auto 生成。
  *
+ * 横軸の範囲は既定では全 task の最大値から自動で決まる。 `axisMax` を書くと尺がその値で
+ * 固定され、 `{名前}` で動く task があっても他の task の帯が動かない (`#483`)。
+ *
  * @example
- * gantt({ id: "release", topic: "Release timeline" })
+ * gantt({ id: "release", topic: "Release timeline", axisMax: 4 })
  *   .task({ id: "design", title: "Design", start: "Q1", end: "Q1" })
  *   .task({ id: "build", title: "Build", start: "Q2", end: "Q2", dependsOn: "design" })
  *   .task({ id: "test", title: "Test", start: "Q3", end: "Q3", dependsOn: "build" })

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CdlDiagram, S as Signal, a as CdlInput, b as CdlLane, c as CdlNode, T as Tone, d as Side, E as EdgeStyle, e as CdlState, f as CdlEventTarget, g as Computed, h as CdlDerivedValue, i as CdlScrollTrigger, L as LaidDiagram, j as CdlDiagramViewProps, k as LaidEdge, l as LaidNode, m as CdlEdge, B as BBox, N as NodeKind, J as JourneyEmotion, Q as QuadrantKey } from './render-DquCvgOB.js';
-export { n as CdlDiagramView, o as CdlEventBinding, p as CdlEventKind, q as CdlFormula, r as CdlPhase, I as InteractiveHandlerMap, s as InteractiveSignalsAccessor, t as LaidLane, u as NODE_KINDS, v as ScrollProgressHandle, w as TONES, x as computeEventBindingKey, y as computeFormulaKey, z as computeInputSignalKey, A as computeScrollTriggerKey, D as computed, F as createInteractiveSignalsAccessor, G as createScrollProgressHandle, H as createScrollProgressSignals, K as hasInteractivePrimitives, M as signal } from './render-DquCvgOB.js';
+import { C as CdlDiagram, S as Signal, a as CdlInput, b as CdlLane, c as CdlNode, T as Tone, d as Side, E as EdgeStyle, e as CdlState, f as CdlEventTarget, g as Computed, h as CdlDerivedValue, i as CdlScrollTrigger, L as LaidDiagram, j as CdlDiagramViewProps, k as LaidEdge, l as LaidNode, m as CdlEdge, B as BBox, N as NodeKind, J as JourneyEmotion, Q as QuadrantKey } from './render-hmFRAabt.js';
+export { n as CdlDiagramView, o as CdlEventBinding, p as CdlEventKind, q as CdlFormula, r as CdlPhase, I as InteractiveHandlerMap, s as InteractiveSignalsAccessor, t as LaidLane, u as NODE_KINDS, v as ScrollProgressHandle, w as TONES, x as computeEventBindingKey, y as computeFormulaKey, z as computeInputSignalKey, A as computeScrollTriggerKey, D as computed, F as createInteractiveSignalsAccessor, G as createScrollProgressHandle, H as createScrollProgressSignals, K as hasInteractivePrimitives, M as signal } from './render-hmFRAabt.js';
 import { JSX } from 'react';
 
 declare function effect(fn: () => void | (() => void)): () => void;
@@ -1535,7 +1535,7 @@ interface Violation {
     detail: string;
     severity: "error" | "warn";
 }
-type VisualAxis = "node-visibility" | "edge-label-overlap" | "edge-label-proximity" | "text-readability" | "row-format" | "alignment" | "clearance" | "arrow-endpoint-anchoring" | "label-char-range" | "node-overlap" | "edge-crossing" | "edge-node-cross" | "edge-segment-orthogonality" | "label-inside-viewbox" | "lane-cx-consistency" | "row-vertical-spacing" | "group-boundary-clearance" | "node-vertical-clearance" | "lane-lane-gap" | "arrow-marker-clearance" | "grid-alignment" | "phase-layout-stability" | "responsive-viewport" | "accessibility-basics" | "animation-frame-integrity" | "i18n-cjk-detection" | "contrast-basics" | "print-media-compat" | "color-blind-safety" | "marker-gradient-def-integrity" | "subpixel-precision" | "dom-complexity-budget" | "reduced-motion-compat" | "touch-target-size" | "row-content-typing" | "terminal-safe-text" | "gpu-layer-efficiency" | "memory-budget" | "svg-injection-safety" | "seo-metadata-quality" | "bidi-hyphenation" | "structured-data-extraction" | "diagram-version-semver" | "migration-path-consistency" | "axis-coverage-meta" | "axis-documentation-completeness" | "fixture-drift-detection" | "locale-parity" | "validate-performance-budget" | "node-inside-viewbox" | "node-inside-lane" | "edge-inside-viewbox" | "lane-label-inside-viewbox" | "lane-label-overlap" | "row-alignment" | "column-alignment" | "edge-stubout-min" | "fan-origin-single-point" | "detour-slot-distinct" | "arrow-endpoint-center" | "lane-border-clearance" | "row-gap-uniform" | "column-gap-uniform" | "rows-not-rendered" | "malformed-input" | "validation-interrupted";
+type VisualAxis = "node-visibility" | "edge-label-overlap" | "edge-label-proximity" | "text-readability" | "row-format" | "alignment" | "clearance" | "arrow-endpoint-anchoring" | "label-char-range" | "node-overlap" | "edge-crossing" | "edge-node-cross" | "edge-segment-orthogonality" | "label-inside-viewbox" | "lane-cx-consistency" | "row-vertical-spacing" | "group-boundary-clearance" | "node-vertical-clearance" | "lane-lane-gap" | "arrow-marker-clearance" | "grid-alignment" | "phase-layout-stability" | "responsive-viewport" | "accessibility-basics" | "animation-frame-integrity" | "i18n-cjk-detection" | "contrast-basics" | "print-media-compat" | "color-blind-safety" | "marker-gradient-def-integrity" | "subpixel-precision" | "dom-complexity-budget" | "reduced-motion-compat" | "touch-target-size" | "row-content-typing" | "terminal-safe-text" | "gpu-layer-efficiency" | "memory-budget" | "svg-injection-safety" | "seo-metadata-quality" | "bidi-hyphenation" | "structured-data-extraction" | "diagram-version-semver" | "migration-path-consistency" | "axis-coverage-meta" | "axis-documentation-completeness" | "fixture-drift-detection" | "locale-parity" | "validate-performance-budget" | "node-inside-viewbox" | "shape-label-dropped" | "node-inside-lane" | "edge-inside-viewbox" | "lane-label-inside-viewbox" | "lane-label-overlap" | "row-alignment" | "column-alignment" | "edge-stubout-min" | "fan-origin-single-point" | "detour-slot-distinct" | "arrow-endpoint-center" | "lane-border-clearance" | "row-gap-uniform" | "column-gap-uniform" | "rows-not-rendered" | "malformed-input" | "validation-interrupted";
 /**
  * 検査の用途。 用途によって見るべき軸が違う。
  *
@@ -2643,6 +2643,16 @@ declare function bboxDiffWorld(predicted: {
     max: number;
 };
 
+/**
+ * 状態を読む書き方 (`{名前}`)。
+ *
+ * 中身の型 (`BoundNumber` / `BoundEnum`) は任意の文字列を受けるが、 **入口はこの形だけに
+ * 限る** (#468 Round 1)。 広いままだと `value: "abc"` や `quadrant: "topLfet"` のような
+ * 書き間違いが、 これまで組み立ての時点で止まっていたのに実行時まで進み、 解決側の既定値
+ * (0 / 左下 / 普通) に落ちた図が出る。
+ */
+type 名前の頭 = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "_";
+type BindingRef = `{${名前の頭}${string}}`;
 /**
  * 高位 API ... 著者が「lane / node / edge を 1 件ずつ宣言」 する低位 API を簡略化。
  *
@@ -2690,10 +2700,32 @@ type FlowPreset = {
     /** edge tone / style の default (各 step → next step の edge) */
     defaultTone?: Tone;
     defaultStyle?: EdgeStyle;
+    /**
+     * step 間の edge を自動生成するか (既定 true)。
+     *
+     * `false` にすると `step()` は node だけを置き、矢印は呼び手が `edge()` で宣言する。
+     * **並び順と違う流れ** (`alpha` から `gamma` へ直接繋いで `beta` を経由しない等) を
+     * 書きたい時に使う。 自動生成しか無かった間、その形は本 preset では作れなかった (#474)。
+     *
+     * 既定を `true` にしているので、既存の呼び出しは 1 行も変えずに同じ図になる。
+     */
+    autoChain?: boolean;
 };
 type FlowBuilder = {
-    /** step を順番に追加、 自動で前 step から edge 接続 */
+    /** step を順番に追加、 自動で前 step から edge 接続 (`autoChain: false` なら node だけ) */
     step: (node: FlowStepInput, edgeLabel?: string) => FlowBuilder;
+    /**
+     * 矢印を宣言する (#474)。 tone / style は preset の既定を引き継ぐ。
+     *
+     * ここで作った矢印も `build()` の phase の `activate` に載る (自動生成分と同じ扱い)。
+     * 載せないと animation で光らず、自動生成と見た目が揃わない。
+     */
+    edge: (from: string, to: string, opts?: {
+        id?: string;
+        label?: string;
+        tone?: Tone;
+        style?: EdgeStyle;
+    }) => FlowBuilder;
     build: () => ReturnType<DiagramBuilder["build"]>;
 };
 /**
@@ -3023,8 +3055,8 @@ type TreeNode = {
     parent?: string;
     /** 表示 kind (default "card") */
     kind?: NodeKind;
+    /** 箱の 2 行目に出す補足。 上の小ラベルは木では受けない (#471、 `TreeNodePayload` 参照) */
     subtitle?: string;
-    eyebrow?: string;
 };
 type TreePreset = {
     id: string;
@@ -3055,7 +3087,8 @@ declare function tree(preset: TreePreset): TreeBuilder;
 type JourneyStep = {
     id: string;
     title: string;
-    emotion: JourneyEmotion;
+    /** 起伏の段階。 `{名前}` を書くと状態から読む (#468) */
+    emotion: JourneyEmotion | BindingRef;
     /** どの touchpoint (例 "Website", "Email", "Support") */
     touchpoint?: string;
     /** opportunity (改善余地のメモ) */
@@ -3121,8 +3154,8 @@ declare function mindMap(preset: MindMapPreset): MindMapBuilder;
 type FunnelStage = {
     id: string;
     title: string;
-    /** この stage の人数 / 件数 */
-    count: number;
+    /** この stage の人数 / 件数。 `{名前}` を書くと状態から読む (#468) */
+    count: number | BindingRef;
     /** stage 詳細 */
     subtitle?: string;
 };
@@ -3153,8 +3186,8 @@ type QuadrantQuadrantLabel = QuadrantKey;
 type QuadrantItem = {
     id: string;
     title: string;
-    /** どの象限 (4 象限) */
-    quadrant: QuadrantQuadrantLabel;
+    /** どの象限 (4 象限)。 `{名前}` を書くと状態から読む (#468) */
+    quadrant: QuadrantQuadrantLabel | BindingRef;
     subtitle?: string;
 };
 type QuadrantPreset = {
@@ -3198,7 +3231,8 @@ type ChartType = "pie" | "bar" | "line";
 type ChartDatum = {
     id: string;
     label: string;
-    value: number;
+    /** 棒 / 折れ線 / 扇の大きさ。 `{名前}` を書くと状態から読む (#468) */
+    value: number | BindingRef;
     /** 個別 tone (default は preset の defaultTone) */
     tone?: Tone;
 };
@@ -3231,9 +3265,15 @@ declare function chart(preset: ChartPreset): ChartBuilder;
 type GanttTask = {
     id: string;
     title: string;
-    /** 開始 (例 "2026-Q1" / "Day 1") */
+    /**
+     * 開始の目盛りの名前 (例 "2026-Q1" / "Day 1")。
+     *
+     * `{名前}` を書くと **位置そのもの** を状態から読む (#468)。 目盛りの名前の対応付けは
+     * 飛ばす = 名前の並びに `{名前}` が混ざると、 位置が状態で動くたびに目盛りの並びが
+     * 変わってしまう。
+     */
     start: string;
-    /** 終了 (例 "2026-Q2") */
+    /** 終了の目盛りの名前。 `{名前}` の扱いは `start` と同じ (#468) */
     end: string;
     /** owner / assignee */
     owner?: string;
@@ -3245,6 +3285,17 @@ type GanttPreset = {
     topic: string;
     defaultTone?: Tone;
     laneWidth?: number;
+    /**
+     * 横軸を何目盛り分にするか (`#483`)。
+     *
+     * 書かないと今までどおり全 task の最大値から自動で決まるため、 `{名前}` で動く task が
+     * 1 つあると **動かしていない task の帯まで伸び縮みする** (実測 = 端を 3 から 9 に動かすと
+     * 静的な task の帯が 252 から 97.2 になった)。
+     *
+     * 書くと尺がその値で固定され、 他の task の帯の位置と幅が変わらない。 範囲から外れる task の
+     * 帯は右端の目盛りに寄せて描く (`kinds/gantt.tsx` SSOT)。
+     */
+    axisMax?: number;
 };
 type GanttBuilder = {
     task: (t: GanttTask) => GanttBuilder;
@@ -3254,8 +3305,11 @@ type GanttBuilder = {
  * gantt preset ... Gantt chart / sprint planning / release timeline。
  * task ごとに 1 lane を作り、 start - end + owner を subtitle、 dependsOn で前 task → 次 task の edge を auto 生成。
  *
+ * 横軸の範囲は既定では全 task の最大値から自動で決まる。 `axisMax` を書くと尺がその値で
+ * 固定され、 `{名前}` で動く task があっても他の task の帯が動かない (`#483`)。
+ *
  * @example
- * gantt({ id: "release", topic: "Release timeline" })
+ * gantt({ id: "release", topic: "Release timeline", axisMax: 4 })
  *   .task({ id: "design", title: "Design", start: "Q1", end: "Q1" })
  *   .task({ id: "build", title: "Build", start: "Q2", end: "Q2", dependsOn: "design" })
  *   .task({ id: "test", title: "Test", start: "Q3", end: "Q3", dependsOn: "build" })