@jarenjs/charts 0.34.0

package/dist/types/types/treemap.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @file The treemap chart type: part-of-whole tiles by area, laid out
+ * with the squarified algorithm (rows chosen to keep tile aspect ratios
+ * near 1). Data shape:
+ *
+ *   data   = { items: [{ label, value }] }                  // flat
+ *   data   = { items: [{ label, children: [{label, value}] }] }  // grouped
+ *   config = { type:'treemap', title?, aspect? }
+ *
+ * The AST is a flat list of unit-square tiles (`x0..x1`/`y0..y1` in
+ * [0,1], `y` growing downward — a treemap has no axes, so reading order
+ * wins). Squarification optimizes *rendered* aspect ratios, so the
+ * build needs the drawing's width:height ratio — that is `aspect`
+ * (default 1.6), carried in the AST so the render maps height from
+ * width with the same value.
+ *
+ * One level of grouping is supported: an item with `children` is a
+ * group whose value is its children's sum. Groups squarify against each
+ * other, then each group's children squarify inside its rect below a
+ * header band that names it — the package→module reading. Groups take a
+ * palette color each, so a group is one hue and its children are told
+ * apart by the hairline between them. A childless item in a grouped
+ * chart becomes a group of one, so no data is dropped either way; a
+ * chart with no `children` anywhere lays out exactly as it always has.
+ */
+export type TreemapTileAST = {
+    label: string;
+    value: number;
+    /**
+     * fraction of the total (0..1)
+     */
+    frac: number;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    /**
+     * the group this tile belongs to (null when flat)
+     */
+    group: string | null;
+    /**
+     * palette index for the fill
+     */
+    swatch: number;
+};
+export type TreemapGroupAST = {
+    label: string;
+    /**
+     * the children's sum
+     */
+    value: number;
+    /**
+     * fraction of the total (0..1)
+     */
+    frac: number;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    /**
+     * height of the naming band at the group's top
+     * (a fraction of the map height; the children fill what is left)
+     */
+    header: number;
+    /**
+     * palette index
+     */
+    swatch: number;
+};
+export type TreemapAST = {
+    type: 'treemap';
+    title: string | null;
+    /**
+     * layout width:height ratio
+     */
+    aspect: number;
+    total: number;
+    /**
+     * value-descending, grouped when
+     * `groups` is non-empty (descending inside each group)
+     */
+    tiles: TreemapTileAST[];
+    /**
+     * empty for a flat treemap
+     */
+    groups: TreemapGroupAST[];
+};
+/**
+ * Build the geometry-free treemap AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {TreemapAST}
+ */
+export declare function buildTreemapAST(data: any, config?: any): TreemapAST;
+/**
+ * Render a treemap AST to a pure-vnode SVG: inset tile rects on the
+ * categorical palette, labels inside the tiles that fit them (ink
+ * picked by fill luminance), and a label+share `<title>` on every tile.
+ * A grouped treemap adds the group's name in its header band and a
+ * hairline between same-hue siblings — both only when there are groups,
+ * so a flat treemap renders exactly as it did before grouping existed.
+ * @param {TreemapAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[], width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export declare function renderTreemapAST(ast: TreemapAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    palette?: readonly string[];
+    width?: number;
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): any;

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@jarenjs/charts",
+  "private": false,
+  "version": "0.34.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./component": {
+      "types": "./dist/types/component/index.d.ts",
+      "default": "./src/component/index.js"
+    },
+    "./stream-adapter": {
+      "types": "./dist/types/core/stream-adapter.d.ts",
+      "default": "./src/core/stream-adapter.js"
+    },
+    "./transforms/mermaid-adapter": {
+      "types": "./dist/types/transforms/mermaid-adapter.d.ts",
+      "default": "./src/transforms/mermaid-adapter.js"
+    },
+    "./transforms/benchmark-adapter": {
+      "types": "./dist/types/transforms/benchmark-adapter.d.ts",
+      "default": "./src/transforms/benchmark-adapter.js"
+    },
+    "./styles/charts.css": "./styles/charts.css",
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/types/",
+    "src/",
+    "schemas/",
+    "styles/"
+  ],
+  "description": "Headless charts for the jaren suite: chart definitions compiled to a geometry-free AST and rendered as pure-vnode SVG through @jarenjs/view — SSR-able, structurally shared, themeable via host-linked tokens",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "components/charts"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "charts",
+    "svg",
+    "pie",
+    "bar",
+    "line",
+    "scatter",
+    "headless",
+    "streaming",
+    "vnode"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.34.0",
+    "@jarenjs/view": "^0.34.0"
+  }
+}

package/schemas/chart-definition.schema.json

@@ -0,0 +1,448 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.github.io/schemas/chart-definition.schema.json",
+  "title": "Chart definition",
+  "description": "A self-contained chart definition for @jarenjs/charts compileChart: the type, presentation fields, and (inline) the data fields the type reads. Streaming callers may omit the data fields and pass data separately.",
+  "type": "object",
+  "required": ["type"],
+  "properties": {
+    "type": {
+      "enum": ["pie", "bar", "line", "scatter", "candlestick", "radar", "gauge", "boxplot", "heatmap", "treemap", "streamgraph", "sankey", "map"]
+    },
+    "title": {
+      "type": ["string", "null"]
+    },
+    "stream": { "$ref": "#/$defs/streamSpec" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "type": { "const": "pie" } } },
+      "then": {
+        "properties": {
+          "donut": {
+            "description": "true for the default hole fraction, or the hole radius as a fraction of the outer radius",
+            "type": ["boolean", "number"],
+            "exclusiveMinimum": 0,
+            "exclusiveMaximum": 1
+          },
+          "slices": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/slice" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "bar" } } },
+      "then": {
+        "properties": {
+          "stacked": { "type": "boolean" },
+          "log": { "type": "boolean" },
+          "orient": { "enum": ["v", "h"] },
+          "catLabel": { "type": ["string", "null"] },
+          "valLabel": { "type": ["string", "null"] },
+          "categories": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "series": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/barSeries" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "line" } } },
+      "then": {
+        "properties": {
+          "x": { "enum": ["linear", "time"] },
+          "log": { "type": "boolean" },
+          "markers": { "type": "boolean" },
+          "xLabel": { "type": ["string", "null"] },
+          "yLabel": { "type": ["string", "null"] },
+          "domain": { "$ref": "#/$defs/domainPolicy" },
+          "series": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/lineSeries" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "candlestick" } } },
+      "then": {
+        "properties": {
+          "xLabel": { "type": ["string", "null"] },
+          "yLabel": { "type": ["string", "null"] },
+          "domain": { "$ref": "#/$defs/domainPolicy" },
+          "candles": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/candle" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "scatter" } } },
+      "then": {
+        "properties": {
+          "xLog": { "type": "boolean" },
+          "yLog": { "type": "boolean" },
+          "refY": { "type": "number" },
+          "refLabel": { "type": ["string", "null"] },
+          "xLabel": { "type": ["string", "null"] },
+          "yLabel": { "type": ["string", "null"] },
+          "points": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/point" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "radar" } } },
+      "then": {
+        "properties": {
+          "max": { "type": "number", "exclusiveMinimum": 0 },
+          "axes": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "series": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/valueSeries" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "gauge" } } },
+      "then": {
+        "properties": {
+          "value": { "type": "number" },
+          "min": { "type": "number" },
+          "max": { "type": "number" },
+          "unit": { "type": ["string", "null"] },
+          "tone": { "$ref": "#/$defs/tone" }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "boxplot" } } },
+      "then": {
+        "properties": {
+          "catLabel": { "type": ["string", "null"] },
+          "valLabel": { "type": ["string", "null"] },
+          "boxes": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/box" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "heatmap" } } },
+      "then": {
+        "properties": {
+          "log": { "type": "boolean" },
+          "xLabel": { "type": ["string", "null"] },
+          "yLabel": { "type": ["string", "null"] },
+          "xLabels": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "yLabels": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "values": {
+            "description": "values[yi][xi], row-major from the top row; null marks a missing cell",
+            "type": "array",
+            "items": {
+              "type": "array",
+              "items": { "type": ["number", "null"] }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "treemap" } } },
+      "then": {
+        "properties": {
+          "aspect": { "type": "number", "exclusiveMinimum": 0 },
+          "items": {
+            "description": "leaves, or one level of groups; a chart with any group treats a bare leaf as a group of one",
+            "type": "array",
+            "items": {
+              "anyOf": [
+                { "$ref": "#/$defs/treemapItem" },
+                { "$ref": "#/$defs/treemapGroup" }
+              ]
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "streamgraph" } } },
+      "then": {
+        "properties": {
+          "xLabel": { "type": ["string", "null"] },
+          "xs": {
+            "type": "array",
+            "items": { "type": "number" }
+          },
+          "series": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/valueSeries" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "sankey" } } },
+      "then": {
+        "properties": {
+          "nodes": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                { "type": "string" },
+                {
+                  "type": "object",
+                  "required": ["name"],
+                  "properties": { "name": { "type": "string" } }
+                }
+              ]
+            }
+          },
+          "links": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/sankeyLink" }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "map" } } },
+      "then": {
+        "properties": {
+          "value": {
+            "description": "feature property to shade by; absent leaves the map unshaded",
+            "type": "string"
+          },
+          "label": {
+            "description": "feature property to name features by (default 'name')",
+            "type": "string"
+          },
+          "log": { "type": "boolean" },
+          "aspect": { "type": "number", "exclusiveMinimum": 0 },
+          "simplify": {
+            "description": "Douglas-Peucker tolerance as a fraction of the frame's width, or false to keep every vertex",
+            "type": ["number", "boolean"],
+            "minimum": 0
+          },
+          "features": {
+            "description": "GeoJSON: a FeatureCollection, or an array of Features or geometries",
+            "type": ["object", "array"]
+          },
+          "points": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/mapPoint" }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "streamSpec": {
+      "description": "createStreamAdapter mapping: how reader events accumulate into this chart's data",
+      "type": "object",
+      "properties": {
+        "recordPath": {
+          "type": "array",
+          "items": { "type": ["string", "number"] }
+        },
+        "recordBoundary": { "enum": ["path", "document"] },
+        "xField": { "type": "string" },
+        "yField": { "type": "string" },
+        "seriesField": { "type": "string" },
+        "maxPoints": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "slice": {
+      "type": "object",
+      "required": ["label", "value"],
+      "properties": {
+        "label": { "type": "string" },
+        "value": { "type": "number", "minimum": 0 }
+      }
+    },
+    "tone": {
+      "enum": ["win", "loss", null]
+    },
+    "barSeries": {
+      "type": "object",
+      "required": ["name", "values"],
+      "properties": {
+        "name": { "type": "string" },
+        "values": {
+          "type": "array",
+          "items": { "type": ["number", "null"] }
+        },
+        "tone": { "$ref": "#/$defs/tone" },
+        "tones": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/tone" }
+        }
+      }
+    },
+    "lineSeries": {
+      "type": "object",
+      "required": ["name", "points"],
+      "properties": {
+        "name": { "type": "string" },
+        "points": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/point" }
+        }
+      }
+    },
+    "point": {
+      "type": "object",
+      "required": ["x", "y"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "tone": { "$ref": "#/$defs/tone" }
+      }
+    },
+    "candle": {
+      "type": "object",
+      "required": ["t", "open", "high", "low", "close"],
+      "properties": {
+        "t": { "type": "number" },
+        "open": { "type": "number" },
+        "high": { "type": "number" },
+        "low": { "type": "number" },
+        "close": { "type": "number" }
+      }
+    },
+    "valueSeries": {
+      "description": "a named series of index-aligned values (radar axes / streamgraph samples)",
+      "type": "object",
+      "required": ["name", "values"],
+      "properties": {
+        "name": { "type": "string" },
+        "values": {
+          "type": "array",
+          "items": { "type": ["number", "null"] }
+        }
+      }
+    },
+    "box": {
+      "description": "one boxplot category: raw samples in `values`, or a precomputed five-number summary",
+      "type": "object",
+      "required": ["label"],
+      "properties": {
+        "label": { "type": "string" },
+        "values": {
+          "type": "array",
+          "items": { "type": ["number", "null"] }
+        },
+        "min": { "type": "number" },
+        "q1": { "type": "number" },
+        "med": { "type": "number" },
+        "q3": { "type": "number" },
+        "max": { "type": "number" },
+        "outliers": {
+          "type": "array",
+          "items": { "type": "number" }
+        }
+      },
+      "anyOf": [
+        { "required": ["values"] },
+        { "required": ["min", "q1", "med", "q3", "max"] }
+      ]
+    },
+    "treemapItem": {
+      "type": "object",
+      "required": ["label", "value"],
+      "properties": {
+        "label": { "type": "string" },
+        "value": { "type": "number", "exclusiveMinimum": 0 }
+      }
+    },
+    "treemapGroup": {
+      "description": "one hierarchy level: the group's value is its children's sum",
+      "type": "object",
+      "required": ["label", "children"],
+      "properties": {
+        "label": { "type": "string" },
+        "children": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/treemapItem" }
+        }
+      }
+    },
+    "sankeyLink": {
+      "description": "a flow from source to target; endpoints are node names or node indexes",
+      "type": "object",
+      "required": ["source", "target", "value"],
+      "properties": {
+        "source": { "type": ["string", "integer"] },
+        "target": { "type": ["string", "integer"] },
+        "value": { "type": "number", "exclusiveMinimum": 0 }
+      }
+    },
+    "mapPoint": {
+      "description": "a place marker: the convenience path for a caller holding positions rather than GeoJSON",
+      "type": "object",
+      "required": ["at"],
+      "properties": {
+        "at": {
+          "description": "a GeoJSON position: [longitude, latitude]",
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 3,
+          "items": { "type": "number" },
+          "prefixItems": [
+            { "type": "number", "minimum": -180, "maximum": 180 },
+            { "type": "number", "minimum": -90, "maximum": 90 }
+          ]
+        },
+        "label": { "type": "string" },
+        "value": { "type": "number" }
+      }
+    },
+    "domainPolicy": {
+      "description": "domain-stability policy: a quantized sliding x window and/or pinned or step-quantized y bounds, so most streaming ticks keep the scales still",
+      "type": "object",
+      "properties": {
+        "x": {
+          "type": "object",
+          "required": ["window"],
+          "properties": {
+            "window": { "type": "number", "exclusiveMinimum": 0 },
+            "slide": { "type": "number", "exclusiveMinimum": 0 }
+          }
+        },
+        "y": {
+          "anyOf": [
+            { "const": "step" },
+            {
+              "type": "object",
+              "properties": {
+                "min": { "type": "number" },
+                "max": { "type": "number" }
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+}