mayacharts 0.1.0

package/dist/styles/theme.d.ts

@@ -0,0 +1 @@
+export declare const css: string;

package/dist/theme.css

@@ -0,0 +1 @@
+:host,.maya-root{--maya-font:system-ui,sans-serif;--maya-font-size:12px;--maya-fg:light-dark(#1f2328,#e6edf3);--maya-fg-muted:light-dark(#656d76,#9198a1);--maya-grid:color-mix(in oklab,var(--maya-fg) 12%,transparent);--maya-bg:light-dark(#fff,#0d1117);--maya-accent:oklch(.6 .17 255);--maya-radius:2px;--maya-tooltip-bg:var(--maya-fg);--maya-tooltip-fg:var(--maya-bg);--maya-focus:var(--maya-accent);--maya-good:light-dark(#1a7f37,#3fb950);--maya-bad:light-dark(#cf222e,#f85149);--maya-series-1:var(--maya-accent);--maya-series-2:oklch(.66 .16 50);--maya-series-3:oklch(.62 .15 160);--maya-series-4:oklch(.66 .17 330);--maya-series-5:oklch(.62 .14 90);--maya-series-6:oklch(.62 .12 205);--maya-series-7:oklch(.64 .19 22);--maya-series-8:oklch(.62 .16 295);color-scheme:light dark}@supports not (color:light-dark(#000,#fff)){:host,.maya-root{--maya-fg:#1f2328;--maya-fg-muted:#656d76;--maya-bg:#fff}@media (prefers-color-scheme:dark){:host,.maya-root{--maya-fg:#e6edf3;--maya-fg-muted:#9198a1;--maya-bg:#0d1117}}}:host{display:block;position:relative;container-type:inline-size;min-height:200px}.maya{display:flex;flex-direction:column;height:100%;font:var(--maya-font-size) var(--maya-font);font-variant-numeric:tabular-nums;color:var(--maya-fg)}.maya-title{font-weight:600;font-size:14px}.maya-legend,.maya-crumbs{color:var(--maya-fg-muted);display:flex;flex-wrap:wrap;align-items:center;gap:4px 12px;margin:0 0 8px}.maya-crumbs{min-height:1.25em;line-height:1.25}.maya-legend button,.maya-crumbs button,.maya-reset{display:inline-flex;align-items:center;gap:6px;border:0;background:none;padding:0;font:inherit;color:var(--maya-fg-muted);cursor:pointer;border-radius:4px}.maya-legend [aria-pressed=false]{opacity:.4}:is(.maya-legend,.maya-crumbs) button:focus-visible,.maya-reset:focus-visible,.maya-ctl :focus-visible{outline:2px solid var(--maya-focus);outline-offset:2px}i{width:10px;height:10px;border-radius:3px;background:var(--c)}[data-maya=ramp]{display:flex;align-items:center;gap:6px}[data-maya=ramp] i{width:80px;height:8px;background:linear-gradient(90deg,color-mix(in oklab,var(--maya-accent) 20%,var(--b)),var(--maya-accent))}[data-q],[data-maya=ramp] i{--b:light-dark(var(--maya-bg),color-mix(in oklab,var(--maya-accent) 15%,var(--maya-bg)))}.maya-legend span{display:inline-flex;align-items:center;gap:6px}.maya-reset{position:absolute;top:4px;right:4px;border:1px solid var(--maya-grid);border-radius:99px;padding:2px 10px;background:var(--maya-bg)}.maya-ctl{position:relative;display:inline-grid;grid-auto-flow:column;grid-auto-columns:1fr;align-self:flex-start;margin:0 0 8px;padding:2px;border-radius:8px;background:var(--maya-grid)}.maya-ctl::before{content:'';position:absolute;inset:2px auto 2px 2px;width:calc(100% - 4px);border-radius:6px;background:var(--maya-bg);transition:transform .2s}.maya-ctl[data-n="2"]::before{width:calc((100% - 4px)/2)}.maya-ctl[data-n="3"]::before{width:calc((100% - 4px)/3)}.maya-ctl[data-n="4"]::before{width:calc((100% - 4px)/4)}.maya-ctl[data-i="1"]::before{transform:translateX(100%)}.maya-ctl[data-i="2"]::before{transform:translateX(200%)}.maya-ctl[data-i="3"]::before{transform:translateX(300%)}.maya-ctl [role=radio]{border:0;background:none;padding:0;font:inherit;color:var(--maya-fg-muted);cursor:pointer;position:relative;padding:4px 12px;border-radius:6px}.maya-ctl [aria-checked=true]{color:var(--maya-fg);font-weight:600}.maya-err{margin:0;padding:8px;color:var(--maya-bad);white-space:pre-wrap;font:12px monospace}.maya-box{flex:1;min-height:0;position:relative}.maya-box svg{display:block;width:100%;height:100%;overflow:visible}.maya-svg{direction:ltr;font:var(--maya-font-size) var(--maya-font);font-variant-numeric:tabular-nums}.maya-svg text{fill:var(--maya-fg-muted);unicode-bidi:plaintext}[data-maya=grid] *{stroke:var(--maya-grid);shape-rendering:crispEdges}[data-s="0"]{--c:var(--maya-series-1)}[data-s="1"]{--c:var(--maya-series-2)}[data-s="2"]{--c:var(--maya-series-3)}[data-s="3"]{--c:var(--maya-series-4)}[data-s="4"]{--c:var(--maya-series-5)}[data-s="5"]{--c:var(--maya-series-6)}[data-s="6"]{--c:var(--maya-series-7)}[data-s="7"]{--c:var(--maya-series-8)}[data-other],[data-total]{--c:var(--maya-fg-muted)}[data-tone=good]{--c:var(--maya-good)}[data-tone=bad]{--c:var(--maya-bad)}[data-q]{--c:color-mix(in oklab,var(--maya-accent) var(--q),var(--b))}[data-q="0"]{--q:20%}[data-q="1"]{--q:29%}[data-q="2"]{--q:38%}[data-q="3"]{--q:47%}[data-q="4"]{--q:56%}[data-q="5"]{--q:64%}[data-q="6"]{--q:73%}[data-q="7"]{--q:82%}[data-q="8"]{--q:91%}[data-q="9"]{--q:100%}[data-maya=mark]{fill:var(--c,var(--maya-series-1));rx:var(--maya-radius);transform-box:fill-box;transform-origin:0 0}[data-dir=h] [data-neg]{transform-origin:100% 0}[data-maya=mark],[data-maya=link]{transition:opacity .2s}[data-maya=mark][data-active]{fill:color-mix(in oklab,var(--c,var(--maya-series-1)),var(--maya-fg) 18%)}:where([data-xd] circle[data-maya=mark]){stroke:var(--maya-bg);stroke-width:1}[data-maya=line]~circle[data-maya=mark]:not([data-active],[data-selected],[data-last]){fill-opacity:0}[data-maya=line]{fill:none;stroke:var(--c);stroke-width:2;stroke-linejoin:round}[data-maya=area]{fill:color-mix(in oklab,var(--c) 18%,transparent);stroke:none}[data-maya=link]{fill:var(--c);opacity:.3}[data-maya=link][data-active]{opacity:.6}line[data-maya=link]{stroke:var(--c,var(--maya-fg-muted));opacity:1}text[data-maya=mark]{fill:var(--maya-fg);font-weight:600}[data-kpi=track]{fill:var(--maya-grid)}[data-kpi=target]{stroke:var(--maya-fg)}[data-maya=labels] [data-tone]{fill:var(--c)}[data-maya=labels] :is([data-kpi=period],[data-kpi=of]){fill:var(--maya-fg-muted)}[data-line] i{height:2px;border-radius:1px}[data-depth]{stroke:var(--maya-bg);stroke-width:1}[data-maya=marks]:has([data-active]) [data-maya=mark]:not([data-active],text){opacity:.55}[data-maya=marks]:has([data-selected]) [data-maya=mark]:not([data-selected]){opacity:.35}[data-selected]{stroke:var(--maya-fg);stroke-width:2}.maya:has([data-s="0"]:hover) [data-maya=mark]:not([data-s="0"]){opacity:.3}.maya:has([data-s="1"]:hover) [data-maya=mark]:not([data-s="1"]){opacity:.3}.maya:has([data-s="2"]:hover) [data-maya=mark]:not([data-s="2"]){opacity:.3}.maya:has([data-s="3"]:hover) [data-maya=mark]:not([data-s="3"]){opacity:.3}.maya:has([data-s="4"]:hover) [data-maya=mark]:not([data-s="4"]){opacity:.3}.maya:has([data-s="5"]:hover) [data-maya=mark]:not([data-s="5"]){opacity:.3}.maya:has([data-s="6"]:hover) [data-maya=mark]:not([data-s="6"]){opacity:.3}.maya:has([data-s="7"]:hover) [data-maya=mark]:not([data-s="7"]){opacity:.3}[data-maya=labels],[data-maya=cross]{pointer-events:none}[data-maya=cross]{opacity:0}[data-maya=labels] text{fill:var(--maya-fg);paint-order:stroke;stroke:var(--maya-bg);stroke-width:3;stroke-linejoin:round}[data-maya=labels] [data-in]{stroke:none}[data-maya=cross] line{stroke:var(--maya-fg-muted);stroke-dasharray:3 3}[data-maya=brush]{fill:var(--maya-accent);fill-opacity:.12;stroke:var(--maya-accent);vector-effect:non-scaling-stroke;pointer-events:none}.maya-svg:focus-visible{outline:2px solid var(--maya-focus)}.maya-sr{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0}.maya-probe{position:absolute;width:0;height:0;pointer-events:none;anchor-name:--maya-probe}.maya-tip{margin:0;inset:auto;border:0;padding:6px 8px;background:var(--maya-tooltip-bg);color:var(--maya-tooltip-fg);border-radius:6px;box-shadow:0 2px 8px #0003;font:var(--maya-font-size) var(--maya-font);pointer-events:none}@supports (anchor-name:--x){.maya-tip{position-anchor:--maya-probe;position-area:block-start;position-try-fallbacks:flip-block,block-start span-inline-start,block-start span-inline-end;margin:8px}}.maya-tip{opacity:0;transition:opacity .12s}.maya-tip.maya-open{opacity:1}.maya-tip b{display:block}.maya-tip div{display:flex;align-items:center;gap:6px}.maya-tip i{outline:1px solid}.maya-tip [data-on]{font-weight:600}@media (pointer:coarse){:is(.maya-legend,.maya-crumbs) button,.maya-ctl [role=radio],.maya-reset,.maya-crumbs{min-height:24px}}@container (max-width:320px){.maya-legend{display:none}.maya-title{font-size:12px}}@media (prefers-contrast:more){:host,.maya-root{--maya-fg-muted:var(--maya-fg);--maya-grid:color-mix(in oklab,var(--maya-fg) 40%,transparent)}}@media (forced-colors:active){.maya-svg,i{forced-color-adjust:none}[data-maya=mark]{stroke:CanvasText;stroke-width:1}[data-tone=bad]{stroke-dasharray:4 2}}@media (prefers-reduced-motion:reduce){*{transition:none!important}}

package/llms.txt

@@ -0,0 +1,102 @@
+mayaCharts: Beautiful, accessible charts in five lines. Zero dependencies. The browser is the chart engine.
+Uses modern platform: Custom Elements, Web Animations API, CSS Anchor Positioning + Popover, CSS custom properties.
+
+USAGE:
+HTML: <maya-chart><script type="application/json">{spec}</script></maya-chart>
+JavaScript: chart.spec = {type: "bar", data, x: "month", y: "revenue"}; chart.data = newRows;
+SSR: import {render, renderShell} from "mayacharts"; render(spec, {width, height});
+Global: <script src="https://cdn.jsdelivr.net/npm/mayacharts/dist/maya.global.js"></script>
+Modules: import "mayacharts/hierarchy" (treemap, sunburst); "mayacharts/flow" (sankey); "mayacharts/geo" (hexmap).
+
+SPEC FIELDS:
+type: enum = required. bar line area scatter heatmap waterfall kpi dumbbell treemap sunburst sankey hexmap
+data: Row[] = required. Row objects with field values.
+y: field | field[] = required. Value field; array adds measure toggle.
+x: field = "". Category field (scatter: numeric x; hexmap: state).
+aggregate: sum|mean|count|min|max = sum. How rows sharing (category, series) combine.
+sort: asc|desc = data order. Order categories by total across all series. bar line area heatmap.
+limit: positive integer = -. Keep top N categories; rest roll up into "Other". bar line area heatmap.
+series: field = null. Split into series (heatmap: row category). bar line area scatter heatmap.
+path: field[] = []. Hierarchy outer to inner. treemap sunburst sankey; bar/line/area with drill.
+size: field = null. Bubble area (sqrt scale). scatter only.
+name: field = null. Point identity and tooltip title. scatter only.
+totals: string[] = []. x values drawn as running-total bars. waterfall only.
+stack: boolean = false. Stack series instead of grouping. bar area only.
+horizontal: boolean = false. Categories on left axis. bar dumbbell.
+y2: field = null. Second value field drawn as line on right axis. bar only.
+format: preset|{[field]: preset|Intl} = auto. Per field or one string for all measures.
+titles: {[field]: string} = {}. Display names everywhere (axis, tooltip, legend, table).
+labels: boolean = null. Formatted value on marks. heatmap: true at ≥24 px.
+text: {[key]: string} = {}. Localised UI strings with {0} placeholders. Keys: noData other back reset showing drilledInto zoomedTo selected selectionCleared chartOf firstOf measures crumbs positive negative above below.
+locale: BCP47 = en-US. Formatting locale.
+currency: ISO4217 = USD. Currency for "currency" preset.
+title: string = "". Visible heading and accessible name.
+description: string = "". Accessible description; auto-generated when omitted.
+yDomain: [min, max] = null. Fixed value-axis domain. Not with y array.
+xDomain: [min, max] = null. Fixed x domain. scatter only.
+tooltip: boolean = true. Hover/keyboard tooltip.
+legend: boolean = true if series. Legend; clicking toggles series.
+drill: boolean = false. Click/Enter zooms into branch of path; breadcrumb, Back, Escape pop. treemap sunburst sankey; bar line area with path.
+select: true|"multi" = off. Click/Enter/legend selects marks; Escape clears. Not with drill. All types but sankey.
+zoom: boolean = false. Drag to zoom. line area scatter. Reset, double-click, Escape restore.
+animate: boolean = true. Animate updates (element only).
+colors: string[]|{[series]: color} = null. Max 8; slot assignment stable across updates.
+colorBy: "sign"|{target: n}|field = null. Tone by sign or target, or ramp by numeric field. Not with series. All types but heatmap and sankey.
+theme: {[token]: css} = {}. Theme token overrides (CSS values, allowlisted). Tokens: font fontSize fg fgMuted grid bg accent radius tooltipBg tooltipFg focus good bad series1..series8.
+grid: boolean = true. Grid lines perpendicular to value axis.
+xAxis: boolean = true. Bottom axis.
+yAxis: boolean = true. Left axis.
+table: boolean = true. Visually hidden data table for screen readers.
+$schema: string = "". Ignored; for editors and LLMs.
+
+EXAMPLES:
+1. Currency bar: {type: "bar", x: "month", y: "revenue", format: "currency", data: [{month: "Jan", revenue: 10500}]}
+2. Stacked bar: {type: "bar", x: "state", y: "units", series: "region", stack: true, data: [{state: "CA", region: "West", units: 120}]}
+3. Horizontal sorted limited labelled bar: {type: "bar", horizontal: true, x: "product", y: "margin", sort: "desc", limit: 5, labels: true, data: [{product: "A", margin: 22}]}
+4. Sign-coloured percent bar: {type: "bar", x: "metric", y: "variance", format: "percent", colorBy: "sign", data: [{metric: "revenue", variance: 0.15}]}
+5. Multi-measure line with date format and zoom: {type: "line", x: "date", y: ["revenue", "units"], zoom: true, format: {date: "date", revenue: "currency"}, data: [{date: "2024-01-01", revenue: 10000, units: 50}]}
+6. Stacked area: {type: "area", x: "month", y: "sales", series: "region", stack: true, data: [{month: "Jan", region: "North", sales: 1500}]}
+7. Waterfall with totals: {type: "waterfall", x: "stage", y: "amount", totals: ["Q1", "FY"], data: [{stage: "Q1", amount: 100}]}
+8. Bubble scatter with select: {type: "scatter", x: "population", y: "gdp", size: "area", name: "country", select: "multi", data: [{country: "USA", population: 331, gdp: 23, area: 9.8}]}
+9. Heatmap count: {type: "heatmap", x: "hour", y: "traffic", aggregate: "count", data: [{hour: "09", traffic: "high"}]}
+10. Treemap drill: {type: "treemap", path: ["region", "state", "product"], y: "revenue", drill: true, data: [{region: "West", state: "CA", product: "A", revenue: 5000}]}
+11. KPI with delta and sparkline: {type: "kpi", x: "month", y: "sales", format: "currency", data: [{month: "Mar", sales: 45000}, {month: "Apr", sales: 50700}, {month: "May", sales: 54500}]}
+12. Dumbbell horizontal: {type: "dumbbell", x: "region", y: "revenue", series: "year", horizontal: true, format: "currency", data: [{region: "North", year: "2024", revenue: 45000}, {region: "North", year: "2025", revenue: 52000}]}
+13. Bar with dual axis: {type: "bar", x: "month", y: "revenue", y2: "customers", format: {revenue: "currency", customers: "integer"}, data: [{month: "Jan", revenue: 10500, customers: 120}, {month: "Feb", revenue: 12000, customers: 145}]}
+
+ERROR CODES:
+spec-not-object: spec must be a plain object
+missing-field: type/data/x (or path)/y is required but missing
+unknown-type: chart type not recognized (with module hint if needed)
+data-not-array: data must be an array of row objects
+row-not-object: data[i] must be a plain object
+unknown-field: field-valued option names no field in data
+non-numeric-y: y field value not a finite number (null allowed)
+non-numeric-field: size/scatter x/colorBy field value not a finite number
+non-positive-value: treemap/sunburst/sankey y value must be positive
+unknown-option: top-level spec key not recognized
+invalid-option: option value wrong type or invalid value
+option-unsupported: option not valid for this chart type or incompatible with another option
+stack-unsupported: stack: true not allowed with type "line" (use "area" instead)
+invalid-domain: yDomain/xDomain not [min, max] with min < max
+invalid-format: format preset unknown, bad Intl options, or unsupported locale/currency
+invalid-theme: theme token not recognized
+unsafe-css-value: colors/theme CSS value blocked by allowlist (no url(), other functions, ; { } < > \)
+invalid-size: RenderOptions width/height not a finite number > 0
+unknown-state: hexmap x value is not a US state (two-letter code or full name; 50 states, DC, PR)
+too-many-marks: more than 5000 marks (suggest limit or aggregate)
+
+EVENTS AND STATE:
+Events (bubbles: true, composed: true):
+  maya-select {selected: Sel[], target: (Sel & {value}) | null}
+  maya-view {measure, drill, window, hidden} (user actions only; window = zoom slice)
+  maya-error {code, path, message} (cancelable with preventDefault())
+  maya-render {} (signals host that render is complete)
+Two-way sync properties:
+  el.view: {measure?, drill?, window?, hidden?} - getter/setter (no events on set; {} resets)
+  el.selected: Sel[] - getter/setter (no events on set)
+
+RULES FOR AGENTS:
+1. Never put functions in spec: the spec is JSON, serializable, diffable, and hashable. No callbacks, formatters, or data transforms.
+2. Unknown types need imports: if type "treemap", "sunburst", "sankey", or "hexmap" fails with unknown-type, add import "mayacharts/<module>".
+3. Read errors.html when MayaSpecError thrown: every error links https://bbekshr.github.io/mayacharts/errors.html#<code> with cause and fixed example.

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "mayacharts",
+  "version": "0.1.0",
+  "description": "Beautiful, accessible charts in five lines. Zero dependencies. The browser is the chart engine.",
+  "keywords": [
+    "chart",
+    "charts",
+    "svg",
+    "web-component",
+    "custom-element",
+    "dataviz",
+    "ssr"
+  ],
+  "license": "MIT",
+  "author": "Bibek Shrestha",
+  "homepage": "https://bbekshr.github.io/mayacharts/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BbekShr/mayacharts.git"
+  },
+  "bugs": "https://github.com/BbekShr/mayacharts/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./element": {
+      "types": "./dist/element.d.ts",
+      "default": "./dist/element.js"
+    },
+    "./hierarchy": {
+      "types": "./dist/hierarchy.d.ts",
+      "default": "./dist/hierarchy.js"
+    },
+    "./flow": {
+      "types": "./dist/flow.d.ts",
+      "default": "./dist/flow.js"
+    },
+    "./geo": {
+      "types": "./dist/geo.d.ts",
+      "default": "./dist/geo.js"
+    },
+    "./global": "./dist/maya.global.js",
+    "./theme.css": "./dist/theme.css",
+    "./schema.json": "./schema.json",
+    "./jsx": {
+      "types": "./dist/jsx.d.ts"
+    }
+  },
+  "sideEffects": [
+    "./dist/element.js",
+    "./dist/hierarchy.js",
+    "./dist/flow.js",
+    "./dist/geo.js",
+    "./dist/maya.global.js",
+    "./src/element.ts",
+    "./src/hierarchy.ts",
+    "./src/flow.ts",
+    "./src/geo.ts",
+    "./src/global.ts"
+  ],
+  "files": [
+    "dist",
+    "schema.json",
+    "llms.txt"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "node scripts/ssr-demo.ts && vite --config site/vite.config.ts",
+    "build": "vite build --mode index && vite build --mode element && vite build --mode hierarchy && vite build --mode flow && vite build --mode geo && vite build --mode global && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "size": "node scripts/size.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "e2e": "playwright test",
+    "site:build": "node scripts/ssr-demo.ts && vite build --config site/vite.config.ts"
+  },
+  "mayaSize": {
+    "dist/index.js": 20480,
+    "dist/element.js": 28672,
+    "dist/theme.css": 2450,
+    "dist/hierarchy.js": 3072,
+    "dist/flow.js": 2560,
+    "dist/geo.js": 3584,
+    "dist/maya.global.js": 32768
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@playwright/test": "^1.63.0",
+    "@types/node": "^26.6.4",
+    "happy-dom": "^20.14.5",
+    "prettier": "^3.9.9",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3"
+  }
+}

package/schema.json

@@ -0,0 +1,381 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bbekshr.github.io/mayacharts/schema.json",
+  "title": "mayaCharts spec",
+  "type": "object",
+  "required": ["type", "data", "y"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Ignored; lets editors and LLMs find the JSON schema."
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "bar",
+        "line",
+        "area",
+        "scatter",
+        "heatmap",
+        "waterfall",
+        "kpi",
+        "dumbbell",
+        "treemap",
+        "sunburst",
+        "sankey",
+        "hexmap"
+      ],
+      "description": "Chart type. treemap/sunburst need `mayacharts/hierarchy`, sankey `flow`, hexmap `geo`."
+    },
+    "data": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "Row objects."
+    },
+    "aggregate": {
+      "type": "string",
+      "enum": ["sum", "mean", "count", "min", "max"],
+      "default": "sum",
+      "description": "How rows sharing a (category, series) combine. `count` counts non-null y."
+    },
+    "sort": {
+      "type": "string",
+      "enum": ["asc", "desc"],
+      "description": "Order categories by total across all series (hidden ones too)."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Keep the top N categories by total; the rest roll up into a final \"Other\"."
+    },
+    "x": {
+      "type": "string",
+      "description": "Category field (scatter: numeric x; hexmap: US state). Not used by path types."
+    },
+    "y": {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Value field."
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "description": "An array adds a measure toggle, first one active."
+        }
+      ]
+    },
+    "y2": {
+      "type": "string",
+      "description": "Second value field, drawn as a line on a right axis over the bars. Vertical bar only."
+    },
+    "series": {
+      "type": "string",
+      "description": "Splits rows into series (heatmap: the row category; dumbbell: exactly two, from and to). bar line area scatter heatmap dumbbell."
+    },
+    "path": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1,
+      "description": "Hierarchy fields, outer to inner. treemap sunburst sankey; bar/line/area with `drill` (replaces `x`)."
+    },
+    "size": {
+      "type": "string",
+      "description": "Bubble area field (sqrt scale). scatter only."
+    },
+    "name": {
+      "type": "string",
+      "description": "Point identity and tooltip title. scatter only."
+    },
+    "totals": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "x values drawn as running-total bars. waterfall only."
+    },
+    "stack": {
+      "type": "boolean",
+      "description": "Stack series instead of grouping them. bar and area only."
+    },
+    "horizontal": {
+      "type": "boolean",
+      "description": "Categories on the left axis. bar and dumbbell."
+    },
+    "format": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "auto",
+            "integer",
+            "decimal",
+            "compact",
+            "percent",
+            "currency",
+            "date",
+            "month",
+            "year",
+            "time",
+            "datetime"
+          ],
+          "description": "A preset for every `y`."
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "auto",
+                  "integer",
+                  "decimal",
+                  "compact",
+                  "percent",
+                  "currency",
+                  "date",
+                  "month",
+                  "year",
+                  "time",
+                  "datetime"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "prefix": {
+                    "type": "string"
+                  },
+                  "suffix": {
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": true
+              }
+            ]
+          },
+          "description": "A preset / Intl options per field. Display only."
+        }
+      ],
+      "description": "Display format for values."
+    },
+    "titles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Display names by field: axis titles (shown only when set), tooltip, legend, table."
+    },
+    "labels": {
+      "type": "boolean",
+      "description": "Formatted values on marks. Default false (heatmap: true when cells are ≥ 24 px)."
+    },
+    "text": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Localised UI strings with `{0}` placeholders.",
+      "propertyNames": {
+        "enum": [
+          "noData",
+          "other",
+          "back",
+          "reset",
+          "showing",
+          "drilledInto",
+          "zoomedTo",
+          "selected",
+          "selectionCleared",
+          "chartOf",
+          "firstOf",
+          "measures",
+          "crumbs",
+          "positive",
+          "negative",
+          "above",
+          "below",
+          "vs",
+          "ofTarget"
+        ]
+      }
+    },
+    "locale": {
+      "type": "string",
+      "default": "en-US",
+      "description": "BCP 47 locale for formatting."
+    },
+    "currency": {
+      "type": "string",
+      "default": "USD",
+      "description": "ISO 4217 code for the \"currency\" preset."
+    },
+    "title": {
+      "type": "string",
+      "description": "Visible heading, also the accessible name."
+    },
+    "description": {
+      "type": "string",
+      "description": "Accessible description; auto-generated when omitted."
+    },
+    "yDomain": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      },
+      "minItems": 2,
+      "maxItems": 2,
+      "description": "Fixed value-axis domain. Not allowed with a `y` array."
+    },
+    "xDomain": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      },
+      "minItems": 2,
+      "maxItems": 2,
+      "description": "Fixed x domain. scatter only."
+    },
+    "tooltip": {
+      "type": "boolean",
+      "default": true,
+      "description": "Hover/keyboard tooltip."
+    },
+    "legend": {
+      "type": "boolean",
+      "description": "Legend; clicking toggles series. Default: true when `series` is set."
+    },
+    "drill": {
+      "type": "boolean",
+      "description": "Click/Enter zooms into a branch of `path`; breadcrumb, Back and Escape pop."
+    },
+    "select": {
+      "oneOf": [
+        {
+          "type": "boolean",
+          "enum": [true]
+        },
+        {
+          "type": "string",
+          "enum": ["multi"]
+        }
+      ],
+      "description": "Click/Enter/legend selects marks, others dim; Escape clears. Not with `drill`."
+    },
+    "zoom": {
+      "type": "boolean",
+      "description": "Drag to zoom. line, area, scatter. Reset chip, double-click and Escape restore."
+    },
+    "animate": {
+      "type": "boolean",
+      "default": true,
+      "description": "Animate updates (element only)."
+    },
+    "colors": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "maxItems": 8,
+          "description": "Palette in series order (max 8)."
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Colours by series value.",
+          "maxProperties": 8
+        }
+      ],
+      "description": "Palette or colours by series value."
+    },
+    "colorBy": {
+      "anyOf": [
+        {
+          "type": "string",
+          "enum": ["sign"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "target": {
+              "type": "number"
+            }
+          },
+          "required": ["target"],
+          "additionalProperties": false
+        },
+        {
+          "type": "string",
+          "description": "A numeric field.",
+          "minLength": 1
+        }
+      ],
+      "description": "Tone by sign of y, by a target, or a ramp by a numeric field. Not with `series`."
+    },
+    "theme": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Theme token overrides (CSS values, allowlisted).",
+      "propertyNames": {
+        "enum": [
+          "font",
+          "fontSize",
+          "fg",
+          "fgMuted",
+          "grid",
+          "bg",
+          "accent",
+          "radius",
+          "tooltipBg",
+          "tooltipFg",
+          "focus",
+          "good",
+          "bad",
+          "series1",
+          "series2",
+          "series3",
+          "series4",
+          "series5",
+          "series6",
+          "series7",
+          "series8"
+        ]
+      }
+    },
+    "grid": {
+      "type": "boolean",
+      "default": true,
+      "description": "Grid lines perpendicular to the value axis."
+    },
+    "xAxis": {
+      "type": "boolean",
+      "default": true,
+      "description": "Bottom axis."
+    },
+    "yAxis": {
+      "type": "boolean",
+      "default": true,
+      "description": "Left axis."
+    },
+    "table": {
+      "type": "boolean",
+      "default": true,
+      "description": "Visually hidden data table for screen readers."
+    }
+  }
+}