@opendata-ai/openchart-core 8.0.0-rc.11 → 8.0.0-rc.13

package/schema/vizspec.schema.json

@@ -5898,6 +5898,10 @@
         "color": {
           "type": "string",
           "description": "Text color (CSS color string)."
+        },
+        "maxLines": {
+          "type": "number",
+          "description": "Maximum number of lines this chrome text may wrap to. Additional lines are dropped and the last kept line is truncated with an ellipsis. Bounds the chrome's contribution to layout height at any container width. Applies whether the font size comes from the theme default or an explicit override. Caps height only, not horizontal overflow of a single unbreakable word."
         }
       },
       "additionalProperties": false,
@@ -9331,6 +9335,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -9780,6 +9792,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -10229,6 +10249,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -10678,6 +10706,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -11127,6 +11163,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -11576,6 +11620,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -12025,6 +12077,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -12474,6 +12534,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -12923,6 +12991,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -13372,6 +13448,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -13821,6 +13905,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -14270,6 +14362,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -14719,6 +14819,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -15168,6 +15276,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -15617,6 +15733,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -16066,6 +16190,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -16699,6 +16831,34 @@
           "$ref": "#/definitions/DarkMode",
           "description": "Dark mode behavior."
         },
+        "animation": {
+          "$ref": "#/definitions/GraphAnimationSpec",
+          "description": "Motion configuration. DEFAULT-ON: omit for full defaults, `false` to opt out of choreography (layout warmup still applies)."
+        },
+        "interaction": {
+          "$ref": "#/definitions/GraphInteractionConfig",
+          "description": "Interaction behavior (hover mode, select-fly, opt-in physics)."
+        },
+        "legend": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "interactive": {
+                  "type": "boolean"
+                },
+                "counts": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "description": "Built-in legend. Interactive by default. Set `false` if you render your own legend, so the built-in filter UI doesn't compete with it."
+        },
         "watermark": {
           "type": "boolean",
           "description": "Whether to show the tryOpenData.ai watermark. Defaults to true."
@@ -16757,7 +16917,11 @@
         },
         "nodeSize": {
           "$ref": "#/definitions/GraphEncodingChannel",
-          "description": "Size mapping for nodes."
+          "description": "Size mapping for nodes. `scale.type` defaults to `'sqrt'` (area-perceptual, today's behavior); set `scale.type: 'linear'` for a linear radius ramp. `scale.range` sets the pixel radius extent (default `[3, 12]`)."
+        },
+        "nodeOpacity": {
+          "$ref": "#/definitions/GraphEncodingChannel",
+          "description": "Opacity mapping for nodes (VL opacity channel). Quantitative fields map linearly to `[0.25, 1]`; `scale.range` overrides.\n\nNOTE: there is deliberately no `edgeOpacity` channel — edge alpha is owned by the interaction alpha-tier machinery (hover dimming, search)."
         },
         "edgeColor": {
           "$ref": "#/definitions/GraphEncodingChannel",
@@ -16793,6 +16957,42 @@
         "scale": {
           "$ref": "#/definitions/ScaleConfig",
           "description": "Scale configuration. Auto-derived from data if omitted."
+        },
+        "sort": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "ascending"
+            },
+            {
+              "type": "string",
+              "const": "descending"
+            },
+            {
+              "type": "null"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Category ordering for the color domain and legend. Graph channels default `'ascending'` (VL-aligned, deterministic); `string[]` pins an explicit order; `null` keeps data order.\n\nNOTE: chart encoding channels keep data-order — this graph default is a deliberate divergence this release (see docs/migrating-v8.md)."
+        },
+        "highlight": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Category values to emphasize on load; the rest dim. Mirrors the chart `encoding.color.highlight` value list. Distinct from the `highlight()` runtime verb and `interaction.hover.mode`."
         }
       },
       "required": [
@@ -16846,6 +17046,35 @@
         "centerForce": {
           "type": "boolean",
           "description": "Whether to apply center force (default true)."
+        },
+        "seed": {
+          "type": "number",
+          "description": "Deterministic layout seed. Same spec + seed ⇒ identical settled layout within a given execution path (worker vs sync parity is not guaranteed)."
+        },
+        "energy": {
+          "type": "string",
+          "enum": [
+            "gentle",
+            "balanced",
+            "energetic"
+          ],
+          "description": "Repulsion preset (plain-language, no d3 jargon): `gentle`/`balanced`/`energetic` → chargeStrength −150/−300/−600 and velocityDecay 0.5/0.4/0.3. A raw `chargeStrength` wins over the preset."
+        },
+        "settle": {
+          "type": "string",
+          "enum": [
+            "quick",
+            "balanced",
+            "thorough"
+          ],
+          "description": "Settle-speed preset: `quick`/`balanced`/`thorough` → alphaDecay 0.05/0.0228/0.01. Higher = faster cool-down, less final refinement."
+        },
+        "warmup": {
+          "type": [
+            "boolean",
+            "number"
+          ],
+          "description": "Headless settle ticks run before the first paint. `true` → 100 ticks under a 250ms budget; a number sets an explicit tick count; `false` disables.\n\nLives in `layout`, NOT `animation`, on purpose: warmup *reduces* motion, so it must survive `animation: false` (opt-out consumers get less settling chaos, not more)."
         }
       },
       "required": [
@@ -16881,6 +17110,157 @@
       "additionalProperties": false,
       "description": "Per-node visual overrides, keyed by node id."
     },
+    "GraphAnimationSpec": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "$ref": "#/definitions/GraphAnimationConfig"
+        }
+      ],
+      "description": "Graph motion spec.\n- omitted → full defaults (default-ON)\n- `false` → no choreography (warmup still applies)\n- object → per-phase control\n\n`prefers-reduced-motion` is always respected regardless of this value."
+    },
+    "GraphAnimationConfig": {
+      "type": "object",
+      "properties": {
+        "enter": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnimationPhaseConfig"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Node/edge reveal on first render. Default `{ duration: 600, ease: 'smooth', stagger: true }`."
+        },
+        "update": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnimationPhaseConfig"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Data-update enter-fade for newly added marks. Default `{ duration: 300, ease: 'smooth' }`."
+        },
+        "exit": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnimationPhaseConfig"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Ghost fade-out for removed marks. Default `{ duration: 300, ease: 'smooth' }`."
+        },
+        "camera": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "duration": {
+                  "type": "number"
+                },
+                "ease": {
+                  "$ref": "#/definitions/AnimationEase"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Camera flight easing. Default duration `'auto'` (derived from the zoom distance)."
+        },
+        "hover": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "duration": {
+                  "type": "number"
+                },
+                "ease": {
+                  "$ref": "#/definitions/AnimationEase"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Hover emphasis crossfade. Default `{ duration: 150, ease: 'smooth' }`."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Per-phase and per-behavior motion config for a graph.\n\nDEFAULT-ON semantics (deliberately different from charts, which are opt-in): omit `animation` → the resolver returns full defaults; `animation: false` → no choreography (but `layout.warmup` still applies); a per-phase `false` disables just that phase. Graphs are default-on because physics motion already exists on load and choreography reduces the chaos."
+    },
+    "GraphInteractionConfig": {
+      "type": "object",
+      "properties": {
+        "hover": {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "neighbors",
+                "category",
+                "node",
+                "none"
+              ]
+            },
+            "dimOpacity": {
+              "type": "number"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Hover emphasis behavior. `neighbors` (default) lights the hovered node and its adjacency; `category` lights same-category nodes; `node` lights only the hovered node; `none` disables. `dimOpacity` (default 0.15) is the node dim tier. Named `mode` (not `highlight`) to avoid colliding with the three other meanings of \"highlight\" (the encoding value list, the `highlight()` verb)."
+        },
+        "select": {
+          "type": "object",
+          "properties": {
+            "flyTo": {
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Selecting a node flies the camera to it. Default `false`."
+        },
+        "cursorRepulsion": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "radius": {
+                  "type": "number"
+                },
+                "strength": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "description": "Opt-in cursor repulsion (nodes drift away from the pointer). Disabled under `prefers-reduced-motion` and above the node-count gate."
+        },
+        "springyDrag": {
+          "type": "boolean",
+          "description": "Opt-in springy node drag (user-initiated; no reduced-motion gate)."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Interaction behavior for a graph (hover mode, select-fly, opt-in physics)."
+    },
     "SankeySpec": {
       "type": "object",
       "properties": {
@@ -17748,6 +18128,14 @@
           "$ref": "#/definitions/Chrome",
           "description": "Editorial chrome (title, subtitle, source, etc.)."
         },
+        "chromeLayout": {
+          "type": "string",
+          "enum": [
+            "subtract",
+            "grow"
+          ],
+          "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+        },
         "title": {
           "anyOf": [
             {