@x12i/charts 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @x12i/charts
+
+`ChartSpec` for the Unified UI Kit: one JSON-serializable description of a chart.
+
+> **Status: foundation.** This package ships the spec types and the renderer
+> choice logic. The renderers themselves are not built yet.
+
+```ts
+import { defineChartSpec } from "@x12i/charts";
+
+export const signups = defineChartSpec({
+  title: "Weekly signups passed target in week 4",
+  source: "Product analytics",
+  data: { ref: "signups_by_week" },
+  mark: "bar",
+  x: { field: "week", type: "category" },
+  y: { field: "signups", type: "number", format: "compact" },
+  highlight: { where: "week == 'W4'" },
+  annotations: [{ type: "reference-line", y: 300, label: "Target" }],
+  a11y: { description: "Bars of weekly signups; week 4 is highest." },
+});
+```
+
+## Renderers (planned)
+
+| Renderer | Engine | Used for |
+| --- | --- | --- |
+| SVG (default) | D3 scale, shape and array modules (ISC) and visx primitives (MIT) | Up to about 5,000 points; always in reports and print |
+| Canvas | Apache ECharts (Apache-2.0), through a token bridge | Above 5,000 points, and types such as Sankey and sunburst |
+
+`resolveRenderer()` implements the `renderer="auto"` rule today.
+
+## Design rules the defaults will enforce
+
+Grey first with one accent, bars start at zero, no 3D, dual axes only behind an
+explicit flag, and every chart has a title that states the finding, a source
+line, an accessible description and a "View as table" toggle.

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * ChartSpec: a JSON-serializable description of one chart (spec section 8).
+ * The grammar is deliberately smaller than Vega-Lite. Renderers read a spec and
+ * draw it with kit tokens, so an engine can change without breaking apps.
+ */
+/** Chart types by family. Entries marked 1.x in the spec are included so specs written today stay valid. */
+declare const chartTypes: readonly ["bar", "lollipop", "dot-plot", "bullet", "slope", "dumbbell", "line", "area", "step", "sparkline", "range-band", "candlestick", "ohlc", "histogram", "box-plot", "density", "strip", "beeswarm", "violin", "ecdf", "donut", "treemap", "waterfall", "funnel", "waffle", "sunburst", "marimekko", "scatter", "bubble", "connected-scatter", "heatmap", "hexbin", "contour", "stat", "gauge", "progress-ring", "sankey", "chord", "alluvial", "choropleth", "point-map", "heat-layer", "flow-map", "gantt", "timeline", "burndown", "cumulative-flow", "calendar-heatmap"];
+type ChartType = (typeof chartTypes)[number];
+type FieldType = "category" | "number" | "time" | "boolean";
+/** Where the rows come from: a named dataset resolved by the app, or inline values. */
+type ChartData = {
+    ref: string;
+} | {
+    values: ReadonlyArray<Record<string, unknown>>;
+};
+interface Encoding {
+    field: string;
+    type: FieldType;
+    /** A named format such as `compact` or `percent`, or an ICU pattern. */
+    format?: string;
+    /** Axis or legend title. Axis titles carry units. */
+    title?: string;
+}
+/** Transforms run in order before drawing. */
+type Transform = {
+    type: "aggregate";
+    groupBy: string[];
+    op: "sum" | "mean" | "min" | "max" | "count";
+    field?: string;
+    as: string;
+} | {
+    type: "bin";
+    field: string;
+    maxBins?: number;
+    as: string;
+} | {
+    type: "stack";
+    field: string;
+    groupBy?: string[];
+    offset?: "zero" | "normalize";
+} | {
+    type: "percent-of-total";
+    field: string;
+    as: string;
+} | {
+    type: "sort";
+    field: string;
+    order?: "asc" | "desc";
+} | {
+    type: "top-n";
+    field: string;
+    n: number;
+    otherLabel?: string;
+} | {
+    type: "rolling-average";
+    field: string;
+    window: number;
+    as: string;
+} | {
+    type: "cumulative-sum";
+    field: string;
+    as: string;
+} | {
+    type: "period-change";
+    field: string;
+    periods?: number;
+    as: string;
+} | {
+    type: "downsample";
+    method: "lttb";
+    field: string;
+    threshold: number;
+};
+/** Targets, limits and forecasts are always labeled marks, never unlabeled lines. */
+type Annotation = {
+    type: "reference-line";
+    x?: number | string;
+    y?: number | string;
+    label: string;
+} | {
+    type: "reference-band";
+    from: number | string;
+    to: number | string;
+    axis: "x" | "y";
+    label: string;
+} | {
+    type: "text";
+    x: number | string;
+    y: number | string;
+    text: string;
+} | {
+    type: "forecast";
+    from: number | string;
+    label: string;
+};
+interface ChartInteractions {
+    tooltip?: boolean;
+    /** Brush to filter other charts and grids through the shared filter store. */
+    brush?: boolean;
+    /** Click a legend entry to isolate a series. */
+    legendIsolate?: boolean;
+    zoom?: boolean;
+    /** Click to drill down through the shared filter store. */
+    drilldown?: boolean;
+}
+/** Accessibility fields. Every chart has an accessible name, a description and a table view. */
+interface ChartA11y {
+    /** The long description read to screen reader users. */
+    description: string;
+    /** Show the underlying data as a table behind a "View as table" toggle. Defaults to true. */
+    table?: boolean;
+}
+type RendererChoice = "svg" | "canvas" | "auto";
+interface ChartSpec {
+    /** Schema version, so saved specs can be migrated. */
+    version?: 1;
+    /** The finding: a sentence that states what the chart shows. */
+    title: string;
+    /** Scope and units. */
+    subtitle?: string;
+    /** Where the data came from. Required in reports. */
+    source?: string;
+    data: ChartData;
+    mark: ChartType;
+    x?: Encoding;
+    y?: Encoding;
+    /** Series that differ in kind use the categorical palette, capped at 8 hues. */
+    color?: Encoding;
+    size?: Encoding;
+    /** One accent on what the title is about, for example `week == 'W4'`. */
+    highlight?: {
+        where: string;
+    };
+    transforms?: Transform[];
+    annotations?: Annotation[];
+    interactions?: ChartInteractions;
+    /** Dual axes only behind an explicit flag, which adds a visible warning. */
+    dualAxis?: boolean;
+    renderer?: RendererChoice;
+    /** Whether axes mirror in right-to-left locales. */
+    direction?: "ltr" | "rtl" | "auto";
+    a11y: ChartA11y;
+}
+/** Identity helper that gives authoring-time type checking and autocomplete. */
+declare function defineChartSpec(spec: ChartSpec): ChartSpec;
+
+/**
+ * The SVG renderer is comfortable up to roughly this many points per chart
+ * (spec section 8: about 1,000 to 5,000). Beyond it, auto mode uses canvas.
+ */
+declare const SVG_POINT_LIMIT = 5000;
+type RenderTarget = "screen" | "print" | "report";
+interface ResolveRendererInput {
+    renderer?: RendererChoice;
+    mark: ChartType;
+    pointCount: number;
+    target?: RenderTarget;
+}
+/**
+ * Picks a renderer for a chart. Reports and print always use SVG so the output
+ * stays vector; on screen, `auto` switches to canvas by point count and type.
+ */
+declare function resolveRenderer({ renderer, mark, pointCount, target, }: ResolveRendererInput): "svg" | "canvas";
+
+export { SVG_POINT_LIMIT, chartTypes, defineChartSpec, resolveRenderer };
+export type { Annotation, ChartA11y, ChartData, ChartInteractions, ChartSpec, ChartType, Encoding, FieldType, RenderTarget, RendererChoice, ResolveRendererInput, Transform };

package/dist/index.js

@@ -0,0 +1,92 @@
+// src/spec.ts
+var chartTypes = [
+  // Comparison
+  "bar",
+  "lollipop",
+  "dot-plot",
+  "bullet",
+  "slope",
+  "dumbbell",
+  // Trend
+  "line",
+  "area",
+  "step",
+  "sparkline",
+  "range-band",
+  "candlestick",
+  "ohlc",
+  // Distribution
+  "histogram",
+  "box-plot",
+  "density",
+  "strip",
+  "beeswarm",
+  "violin",
+  "ecdf",
+  // Composition
+  "donut",
+  "treemap",
+  "waterfall",
+  "funnel",
+  "waffle",
+  "sunburst",
+  "marimekko",
+  // Relationship
+  "scatter",
+  "bubble",
+  "connected-scatter",
+  "heatmap",
+  "hexbin",
+  "contour",
+  // KPI
+  "stat",
+  "gauge",
+  "progress-ring",
+  // Flow
+  "sankey",
+  "chord",
+  "alluvial",
+  // Geo
+  "choropleth",
+  "point-map",
+  "heat-layer",
+  "flow-map",
+  // Schedule and process
+  "gantt",
+  "timeline",
+  "burndown",
+  "cumulative-flow",
+  "calendar-heatmap"
+];
+function defineChartSpec(spec) {
+  return spec;
+}
+
+// src/renderer.ts
+var SVG_POINT_LIMIT = 5e3;
+var CANVAS_ONLY = /* @__PURE__ */ new Set([
+  "candlestick",
+  "ohlc",
+  "sunburst",
+  "marimekko",
+  "hexbin",
+  "contour",
+  "sankey",
+  "chord",
+  "alluvial"
+]);
+function resolveRenderer({
+  renderer = "auto",
+  mark,
+  pointCount,
+  target = "screen"
+}) {
+  if (target !== "screen") return "svg";
+  if (renderer !== "auto") return renderer;
+  if (CANVAS_ONLY.has(mark)) return "canvas";
+  return pointCount > SVG_POINT_LIMIT ? "canvas" : "svg";
+}
+
+export { SVG_POINT_LIMIT, chartTypes, defineChartSpec, resolveRenderer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/spec.ts","../src/renderer.ts"],"names":[],"mappings":";AAOO,IAAM,UAAA,GAAa;AAAA;AAAA,EAExB,KAAA;AAAA,EACA,UAAA;AAAA,EACA,UAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,UAAA;AAAA;AAAA,EAEA,MAAA;AAAA,EACA,MAAA;AAAA,EACA,MAAA;AAAA,EACA,WAAA;AAAA,EACA,YAAA;AAAA,EACA,aAAA;AAAA,EACA,MAAA;AAAA;AAAA,EAEA,WAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA,UAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA;AAAA,EAEA,OAAA;AAAA,EACA,SAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,QAAA;AAAA,EACA,UAAA;AAAA,EACA,WAAA;AAAA;AAAA,EAEA,SAAA;AAAA,EACA,QAAA;AAAA,EACA,mBAAA;AAAA,EACA,SAAA;AAAA,EACA,QAAA;AAAA,EACA,SAAA;AAAA;AAAA,EAEA,MAAA;AAAA,EACA,OAAA;AAAA,EACA,eAAA;AAAA;AAAA,EAEA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,UAAA;AAAA;AAAA,EAEA,YAAA;AAAA,EACA,WAAA;AAAA,EACA,YAAA;AAAA,EACA,UAAA;AAAA;AAAA,EAEA,OAAA;AAAA,EACA,UAAA;AAAA,EACA,UAAA;AAAA,EACA,iBAAA;AAAA,EACA;AACF;AA2FO,SAAS,gBAAgB,IAAA,EAA4B;AAC1D,EAAA,OAAO,IAAA;AACT;;;ACxJO,IAAM,eAAA,GAAkB;AAG/B,IAAM,WAAA,uBAA0C,GAAA,CAAe;AAAA,EAC7D,aAAA;AAAA,EACA,MAAA;AAAA,EACA,UAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,SAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAC,CAAA;AAeM,SAAS,eAAA,CAAgB;AAAA,EAC9B,QAAA,GAAW,MAAA;AAAA,EACX,IAAA;AAAA,EACA,UAAA;AAAA,EACA,MAAA,GAAS;AACX,CAAA,EAA2C;AACzC,EAAA,IAAI,MAAA,KAAW,UAAU,OAAO,KAAA;AAChC,EAAA,IAAI,QAAA,KAAa,QAAQ,OAAO,QAAA;AAChC,EAAA,IAAI,WAAA,CAAY,GAAA,CAAI,IAAI,CAAA,EAAG,OAAO,QAAA;AAClC,EAAA,OAAO,UAAA,GAAa,kBAAkB,QAAA,GAAW,KAAA;AACnD","file":"index.js","sourcesContent":["/**\r\n * ChartSpec: a JSON-serializable description of one chart (spec section 8).\r\n * The grammar is deliberately smaller than Vega-Lite. Renderers read a spec and\r\n * draw it with kit tokens, so an engine can change without breaking apps.\r\n */\r\n\r\n/** Chart types by family. Entries marked 1.x in the spec are included so specs written today stay valid. */\r\nexport const chartTypes = [\r\n  // Comparison\r\n  \"bar\",\r\n  \"lollipop\",\r\n  \"dot-plot\",\r\n  \"bullet\",\r\n  \"slope\",\r\n  \"dumbbell\",\r\n  // Trend\r\n  \"line\",\r\n  \"area\",\r\n  \"step\",\r\n  \"sparkline\",\r\n  \"range-band\",\r\n  \"candlestick\",\r\n  \"ohlc\",\r\n  // Distribution\r\n  \"histogram\",\r\n  \"box-plot\",\r\n  \"density\",\r\n  \"strip\",\r\n  \"beeswarm\",\r\n  \"violin\",\r\n  \"ecdf\",\r\n  // Composition\r\n  \"donut\",\r\n  \"treemap\",\r\n  \"waterfall\",\r\n  \"funnel\",\r\n  \"waffle\",\r\n  \"sunburst\",\r\n  \"marimekko\",\r\n  // Relationship\r\n  \"scatter\",\r\n  \"bubble\",\r\n  \"connected-scatter\",\r\n  \"heatmap\",\r\n  \"hexbin\",\r\n  \"contour\",\r\n  // KPI\r\n  \"stat\",\r\n  \"gauge\",\r\n  \"progress-ring\",\r\n  // Flow\r\n  \"sankey\",\r\n  \"chord\",\r\n  \"alluvial\",\r\n  // Geo\r\n  \"choropleth\",\r\n  \"point-map\",\r\n  \"heat-layer\",\r\n  \"flow-map\",\r\n  // Schedule and process\r\n  \"gantt\",\r\n  \"timeline\",\r\n  \"burndown\",\r\n  \"cumulative-flow\",\r\n  \"calendar-heatmap\",\r\n] as const;\r\n\r\nexport type ChartType = (typeof chartTypes)[number];\r\n\r\nexport type FieldType = \"category\" | \"number\" | \"time\" | \"boolean\";\r\n\r\n/** Where the rows come from: a named dataset resolved by the app, or inline values. */\r\nexport type ChartData =\r\n  | { ref: string }\r\n  | { values: ReadonlyArray<Record<string, unknown>> };\r\n\r\nexport interface Encoding {\r\n  field: string;\r\n  type: FieldType;\r\n  /** A named format such as `compact` or `percent`, or an ICU pattern. */\r\n  format?: string;\r\n  /** Axis or legend title. Axis titles carry units. */\r\n  title?: string;\r\n}\r\n\r\n/** Transforms run in order before drawing. */\r\nexport type Transform =\r\n  | { type: \"aggregate\"; groupBy: string[]; op: \"sum\" | \"mean\" | \"min\" | \"max\" | \"count\"; field?: string; as: string }\r\n  | { type: \"bin\"; field: string; maxBins?: number; as: string }\r\n  | { type: \"stack\"; field: string; groupBy?: string[]; offset?: \"zero\" | \"normalize\" }\r\n  | { type: \"percent-of-total\"; field: string; as: string }\r\n  | { type: \"sort\"; field: string; order?: \"asc\" | \"desc\" }\r\n  | { type: \"top-n\"; field: string; n: number; otherLabel?: string }\r\n  | { type: \"rolling-average\"; field: string; window: number; as: string }\r\n  | { type: \"cumulative-sum\"; field: string; as: string }\r\n  | { type: \"period-change\"; field: string; periods?: number; as: string }\r\n  | { type: \"downsample\"; method: \"lttb\"; field: string; threshold: number };\r\n\r\n/** Targets, limits and forecasts are always labeled marks, never unlabeled lines. */\r\nexport type Annotation =\r\n  | { type: \"reference-line\"; x?: number | string; y?: number | string; label: string }\r\n  | { type: \"reference-band\"; from: number | string; to: number | string; axis: \"x\" | \"y\"; label: string }\r\n  | { type: \"text\"; x: number | string; y: number | string; text: string }\r\n  | { type: \"forecast\"; from: number | string; label: string };\r\n\r\nexport interface ChartInteractions {\r\n  tooltip?: boolean;\r\n  /** Brush to filter other charts and grids through the shared filter store. */\r\n  brush?: boolean;\r\n  /** Click a legend entry to isolate a series. */\r\n  legendIsolate?: boolean;\r\n  zoom?: boolean;\r\n  /** Click to drill down through the shared filter store. */\r\n  drilldown?: boolean;\r\n}\r\n\r\n/** Accessibility fields. Every chart has an accessible name, a description and a table view. */\r\nexport interface ChartA11y {\r\n  /** The long description read to screen reader users. */\r\n  description: string;\r\n  /** Show the underlying data as a table behind a \"View as table\" toggle. Defaults to true. */\r\n  table?: boolean;\r\n}\r\n\r\nexport type RendererChoice = \"svg\" | \"canvas\" | \"auto\";\r\n\r\nexport interface ChartSpec {\r\n  /** Schema version, so saved specs can be migrated. */\r\n  version?: 1;\r\n  /** The finding: a sentence that states what the chart shows. */\r\n  title: string;\r\n  /** Scope and units. */\r\n  subtitle?: string;\r\n  /** Where the data came from. Required in reports. */\r\n  source?: string;\r\n  data: ChartData;\r\n  mark: ChartType;\r\n  x?: Encoding;\r\n  y?: Encoding;\r\n  /** Series that differ in kind use the categorical palette, capped at 8 hues. */\r\n  color?: Encoding;\r\n  size?: Encoding;\r\n  /** One accent on what the title is about, for example `week == 'W4'`. */\r\n  highlight?: { where: string };\r\n  transforms?: Transform[];\r\n  annotations?: Annotation[];\r\n  interactions?: ChartInteractions;\r\n  /** Dual axes only behind an explicit flag, which adds a visible warning. */\r\n  dualAxis?: boolean;\r\n  renderer?: RendererChoice;\r\n  /** Whether axes mirror in right-to-left locales. */\r\n  direction?: \"ltr\" | \"rtl\" | \"auto\";\r\n  a11y: ChartA11y;\r\n}\r\n\r\n/** Identity helper that gives authoring-time type checking and autocomplete. */\r\nexport function defineChartSpec(spec: ChartSpec): ChartSpec {\r\n  return spec;\r\n}\r\n","import type { ChartType, RendererChoice } from \"./spec\";\r\n\r\n/**\r\n * The SVG renderer is comfortable up to roughly this many points per chart\r\n * (spec section 8: about 1,000 to 5,000). Beyond it, auto mode uses canvas.\r\n */\r\nexport const SVG_POINT_LIMIT = 5000;\r\n\r\n/** Chart types that only the canvas renderer draws. */\r\nconst CANVAS_ONLY: ReadonlySet<ChartType> = new Set<ChartType>([\r\n  \"candlestick\",\r\n  \"ohlc\",\r\n  \"sunburst\",\r\n  \"marimekko\",\r\n  \"hexbin\",\r\n  \"contour\",\r\n  \"sankey\",\r\n  \"chord\",\r\n  \"alluvial\",\r\n]);\r\n\r\nexport type RenderTarget = \"screen\" | \"print\" | \"report\";\r\n\r\nexport interface ResolveRendererInput {\r\n  renderer?: RendererChoice;\r\n  mark: ChartType;\r\n  pointCount: number;\r\n  target?: RenderTarget;\r\n}\r\n\r\n/**\r\n * Picks a renderer for a chart. Reports and print always use SVG so the output\r\n * stays vector; on screen, `auto` switches to canvas by point count and type.\r\n */\r\nexport function resolveRenderer({\r\n  renderer = \"auto\",\r\n  mark,\r\n  pointCount,\r\n  target = \"screen\",\r\n}: ResolveRendererInput): \"svg\" | \"canvas\" {\r\n  if (target !== \"screen\") return \"svg\";\r\n  if (renderer !== \"auto\") return renderer;\r\n  if (CANVAS_ONLY.has(mark)) return \"canvas\";\r\n  return pointCount > SVG_POINT_LIMIT ? \"canvas\" : \"svg\";\r\n}\r\n"]}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@x12i/charts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "ChartSpec for the Unified UI Kit: one JSON-serializable description of a chart. Renderers (token-themed SVG, ECharts canvas) are planned.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/unified-ui-kit.git",
+    "directory": "packages/charts"
+  },
+  "homepage": "https://github.com/x12i/unified-ui-kit/tree/main/packages/charts#readme",
+  "bugs": {
+    "url": "https://github.com/x12i/unified-ui-kit/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests"
+  }
 }