@rokkit/chart 1.0.0-next.15 → 1.0.0-next.150

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Jerry Thomas
+Copyright (c) 2025 Jerry Thomas
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,55 +1,159 @@
-# Charts for Svelte
+# @rokkit/chart
 
-The core idea behind the implementation is to use the respective strengths of both D3 and Svelte to build Themable, Composable, Animated, Responsive, Accessible, and Reactive Data Visualization components.
+Data-driven D3 chart components for Svelte 5, inspired by the composable approach of [dc.js](https://dc-js.github.io/dc.js/).
 
-- [D3](https://d3js.org/) makes working with SVG a breeze. It provides a large set of utility functions for graph visualization that includes the computation of scales, interpolation, shapes, and more.
-- [Svelte](https://svelte.dev/) makes UI development fun again. It provides modularization, interactivity, reactivity, and responsiveness.
+## Install
 
-This component library borrows concepts from the following articles, products, and repositories.
+```bash
+bun add @rokkit/chart
+# or
+npm install @rokkit/chart
+```
 
-- [Introduction to Accessible Contrast and Color for Data Visualization](https://observablehq.com/@frankelavsky/chartability-contrast-series) by [Frank Elavsky](https://observablehq.com/@frankelavsky)
-- [Animated, Responsive, and Reactive Data Visualization with Svelte](https://www.infoq.com/news/2020/10/svelte-d3-animation-data-vis/)
-- [Barchart Race using Svelte & D3](https://t.co/iIoJw4f7Jc?amp=1) by [Amelia Wattenberger](https://mobile.twitter.com/Wattenberger) & [Russell Goldenberg](https://mobile.twitter.com/codenberg)
-- [The D3.js Graph Gallery](https://www.d3-graph-gallery.com/index.html)
-- [DC.js](https://dc-js.github.io/dc.js/) is an awesome implementation of interactive animated charts using D3.
+## Overview
 
-## Getting Started
+`@rokkit/chart` provides composable SVG chart components built on D3. All components are placed inside `Plot.Root`, which manages shared state (scales, dimensions, color mapping) via Svelte context. Child components read from that context — you do not wire them together manually.
 
-Get started quickly using [degit](https://github.com/Rich-Harris/degit).
+## Usage
 
-```bash
-degit jerrythomas/sparsh-ui/sites/playground my-app
+### Basic bar chart
+
+```svelte
+<script>
+  import { Plot } from '@rokkit/chart'
+
+  const data = [
+    { month: 'Jan', sales: 120, returns: 30 },
+    { month: 'Feb', sales: 150, returns: 20 },
+    { month: 'Mar', sales: 90, returns: 40 }
+  ]
+</script>
+
+<Plot.Root {data} width={600} height={400} fill="month">
+  <Plot.Grid />
+  <Plot.Axis type="x" field="month" label="Month" />
+  <Plot.Axis type="y" field="sales" label="Sales" />
+  <Plot.Bar x="month" y="sales" />
+  <Plot.Legend />
+</Plot.Root>
 ```
 
-## Features
-
-- [x] Fill patterns
-- [x] Symbols
-- [x] Colors
-- [ ] Themes
-
-### Plots
-
-- [x] Box
-- [ ] Violin
-- [x] Scatter
-- [ ] Line
-- [ ] Histogram
-- [ ] StackedBar
-- [ ] Funnel
-
-### Chart
-
-- [x] Axis
-  - [x] Labels
-  - [x] Grid
-  - [x] Ticks
-- [ ] Margins
-- [ ] Legend
-- [ ] Composable
-- [ ] Facet Grid
-- [ ] Combine multiple plots
-- [ ] Animation
-- [ ] Time lapse
-  - [ ] Sliding window
-  - [ ] Rolling window
+### Using `@rokkit/data` for preprocessing
+
+```svelte
+<script>
+  import { Plot } from '@rokkit/chart'
+  import { dataset } from '@rokkit/data'
+
+  const raw = [
+    { category: 'Electronics', name: 'A', revenue: 450 },
+    { category: 'Clothing', name: 'B', revenue: 320 },
+    { category: 'Electronics', name: 'C', revenue: 620 }
+  ]
+
+  const data = dataset(raw)
+    .groupBy('category')
+    .summarize('name', { total: (vals) => vals.reduce((s, v) => s + v.revenue, 0) })
+    .rollup()
+</script>
+
+<Plot.Root {data} fill="category" width={500} height={350}>
+  <Plot.Axis type="x" field="category" />
+  <Plot.Axis type="y" field="total" />
+  <Plot.Bar x="category" y="total" />
+  <Plot.Legend />
+</Plot.Root>
+```
+
+### Using `ChartBrewer` for advanced control
+
+`ChartBrewer` is the reactive state manager that `Plot.Root` uses internally. Use it directly when you need programmatic access to scales, axes, or legend state outside of the component tree.
+
+```js
+import { ChartBrewer, createScales, createBars } from '@rokkit/chart'
+
+const brewer = new ChartBrewer({
+  width: 600,
+  height: 400,
+  margin: { top: 20, right: 30, bottom: 40, left: 50 },
+  padding: 0.2,
+  animationDuration: 300
+})
+
+brewer.setData(data)
+brewer.setFields({ x: 'month', y: 'sales', color: 'month' })
+brewer.createScales()
+
+const scales = brewer.getScales()
+const dimensions = brewer.getDimensions()
+```
+
+## API
+
+### Components (`Plot` namespace)
+
+| Component     | Description                                               |
+| ------------- | --------------------------------------------------------- |
+| `Plot.Root`   | Chart container. Manages dimensions, scales, and context. |
+| `Plot.Bar`    | Bar series. Reads x/y fields and renders SVG rects.       |
+| `Plot.Axis`   | X or Y axis with optional label and tick formatting.      |
+| `Plot.Grid`   | Background grid lines derived from axis scales.           |
+| `Plot.Legend` | Color legend; clicking items filters the visible series.  |
+
+### `Plot.Root` props
+
+| Prop                | Type               | Default                               | Description                                                           |
+| ------------------- | ------------------ | ------------------------------------- | --------------------------------------------------------------------- |
+| `data`              | `array \| dataset` | `[]`                                  | Chart data. Accepts a plain array or a `@rokkit/data` dataset object. |
+| `width`             | `number`           | `600`                                 | SVG width in pixels.                                                  |
+| `height`            | `number`           | `400`                                 | SVG height in pixels.                                                 |
+| `margin`            | `object`           | `{top:20,right:30,bottom:40,left:50}` | Chart margins.                                                        |
+| `fill`              | `string`           | `null`                                | Field name used for color mapping.                                    |
+| `responsive`        | `boolean`          | `true`                                | Resize with the container.                                            |
+| `animationDuration` | `number`           | `300`                                 | Transition duration in ms.                                            |
+
+### `Plot.Bar` props
+
+| Prop                | Type       | Default     | Description                                   |
+| ------------------- | ---------- | ----------- | --------------------------------------------- |
+| `x`                 | `string`   | —           | Field for x-axis values.                      |
+| `y`                 | `string`   | —           | Field for y-axis values.                      |
+| `fill`              | `string`   | —           | Field for color mapping (overrides root).     |
+| `color`             | `string`   | `'#4682b4'` | Fallback bar color when no fill field is set. |
+| `opacity`           | `number`   | `1`         | Bar opacity.                                  |
+| `animationDuration` | `number`   | `300`       | Per-bar transition duration in ms.            |
+| `onClick`           | `function` | `null`      | Click handler; receives the data row.         |
+
+### `Plot.Axis` props
+
+| Prop         | Type         | Default | Description                       |
+| ------------ | ------------ | ------- | --------------------------------- |
+| `type`       | `'x' \| 'y'` | `'x'`   | Axis orientation.                 |
+| `field`      | `string`     | —       | Data field this axis represents.  |
+| `label`      | `string`     | `''`    | Axis label.                       |
+| `ticks`      | `number`     | —       | Suggested tick count.             |
+| `tickFormat` | `function`   | —       | D3 tick formatter.                |
+| `grid`       | `boolean`    | `false` | Render grid lines from this axis. |
+
+### Utility functions
+
+| Export                                    | Description                                 |
+| ----------------------------------------- | ------------------------------------------- |
+| `createDimensions(width, height, margin)` | Compute chart area dimensions with margins  |
+| `createScales(data, fields, dimensions)`  | Generate D3 band/linear scales              |
+| `createBars(data, scales, fields)`        | Compute bar x/y/width/height attributes     |
+| `createGroupedBars(data, scales, fields)` | Compute grouped bar layout                  |
+| `createLegend(data, colorScale)`          | Build legend item array                     |
+| `filterByLegend(data, activeItems)`       | Filter data rows by active legend selection |
+| `createXAxis(scale, options)`             | Build D3 x-axis descriptor                  |
+| `createYAxis(scale, options)`             | Build D3 y-axis descriptor                  |
+| `createGrid(scales, dimensions)`          | Build grid line descriptors                 |
+
+## Dependencies
+
+- `d3-scale`, `d3-axis`, `d3-format`, `d3-selection`, `d3-array`, `d3-transition`, `d3-scale-chromatic`
+- `@rokkit/core`, `@rokkit/data`, `@rokkit/states`
+
+---
+
+Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.

package/dist/Plot/index.d.ts

@@ -0,0 +1,9 @@
+export { default as Root } from "./Root.svelte";
+export { default as Axis } from "./Axis.svelte";
+export { default as Bar } from "./Bar.svelte";
+export { default as Legend } from "./Legend.svelte";
+export { default as Grid } from "./Grid.svelte";
+export { default as Line } from "./Line.svelte";
+export { default as Area } from "./Area.svelte";
+export { default as Point } from "./Point.svelte";
+export { default as Arc } from "./Arc.svelte";

package/dist/PlotState.svelte.d.ts

@@ -0,0 +1,47 @@
+export class PlotState {
+    constructor(config?: {});
+    axisOrigin: undefined[];
+    orientation: string;
+    colorScaleType: any;
+    xScale: any;
+    yScale: any;
+    colors: Map<unknown, {
+        fill: string;
+        stroke: string;
+    }>;
+    patterns: Map<any, any>;
+    symbols: Map<any, any>;
+    colorField: any;
+    patternField: any;
+    symbolField: any;
+    geomTypes: Set<any>;
+    xAxisY: any;
+    yAxisX: any;
+    update(config: any): void;
+    registerGeom(config: any): string;
+    updateGeom(id: any, config: any): void;
+    unregisterGeom(id: any): void;
+    geomData(id: any): any[];
+    label(field: any): any;
+    format(field: any): any;
+    tooltip(): any;
+    geomComponent(type: any): any;
+    preset(): {
+        colors: any;
+        patterns: any;
+        symbols: any;
+    };
+    get margin(): {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    get innerWidth(): number;
+    get innerHeight(): number;
+    get mode(): string;
+    get hovered(): null;
+    setHovered(data: any): void;
+    clearHovered(): void;
+    #private;
+}

package/dist/crossfilter/createCrossFilter.svelte.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Creates a reactive cross-filter state object.
+ *
+ * Filter values follow the spec type:
+ *   FilterState = Map<string, Set<unknown> | [number, number]>
+ *   - categorical: raw Set of selected values
+ *   - continuous:  [min, max] tuple
+ *
+ * Exposes a `filters` getter so CrossFilter.svelte can bind to current state.
+ * Exposes a `version` counter that increments on every mutation, giving
+ * components a simple reactive signal to watch for filter changes.
+ *
+ * @returns {CrossFilter}
+ */
+export function createCrossFilter(): CrossFilter;

package/dist/elements/index.d.ts

@@ -0,0 +1,6 @@
+export { default as Bar } from "./Bar.svelte";
+export { default as ColorRamp } from "./ColorRamp.svelte";
+export { default as ContinuousLegend } from "./ContinuousLegend.svelte";
+export { default as Label } from "./Label.svelte";
+export { default as DefinePatterns } from "./DefinePatterns.svelte";
+export { default as SymbolGrid } from "./SymbolGrid.svelte";

package/dist/geoms/lib/areas.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Builds area path geometry for multi-series area charts.
+ *
+ * @param {Object[]} data
+ * @param {{ x: string, y: string, color?: string }} channels
+ * @param {Function} xScale
+ * @param {Function} yScale
+ * @param {Map<unknown, {fill: string, stroke: string}>} colors
+ * @param {'linear'|'smooth'|'step'} [curve]
+ * @param {Map<unknown, string>} [patterns]
+ * @returns {{ d: string, fill: string, stroke: string, key: unknown, patternId: string|null }[]}
+ */
+export function buildAreas(data: Object[], channels: {
+    x: string;
+    y: string;
+    color?: string;
+}, xScale: Function, yScale: Function, colors: Map<unknown, {
+    fill: string;
+    stroke: string;
+}>, curve?: "linear" | "smooth" | "step", patterns?: Map<unknown, string>): {
+    d: string;
+    fill: string;
+    stroke: string;
+    key: unknown;
+    patternId: string | null;
+}[];
+/**
+ * Builds stacked area paths using d3 stack layout.
+ *
+ * @param {Object[]} data
+ * @param {{ x: string, y: string, color: string }} channels
+ * @param {Function} xScale
+ * @param {Function} yScale
+ * @param {Map<unknown, {fill: string, stroke: string}>} colors
+ * @param {'linear'|'smooth'|'step'} [curve]
+ * @param {Map<unknown, string>} [patterns]
+ * @returns {{ d: string, fill: string, stroke: string, key: unknown, patternId: string|null }[]}
+ */
+export function buildStackedAreas(data: Object[], channels: {
+    x: string;
+    y: string;
+    color: string;
+}, xScale: Function, yScale: Function, colors: Map<unknown, {
+    fill: string;
+    stroke: string;
+}>, curve?: "linear" | "smooth" | "step", patterns?: Map<unknown, string>): {
+    d: string;
+    fill: string;
+    stroke: string;
+    key: unknown;
+    patternId: string | null;
+}[];

package/dist/geoms/lib/bars.d.ts

@@ -0,0 +1,3 @@
+export function buildGroupedBars(data: any, channels: any, xScale: any, yScale: any, colors: any, innerHeight: any, patterns: any): any;
+export function buildStackedBars(data: any, channels: any, xScale: any, yScale: any, colors: any, innerHeight: any, patterns: any): any;
+export function buildHorizontalBars(data: any, channels: any, xScale: any, yScale: any, colors: any, _innerHeight: any): any;

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+export namespace PlotLayers {
+    export { Root };
+    export { Axis };
+    export { Bar };
+    export { Grid };
+    export { Legend };
+    export { Line };
+    export { Area };
+    export { Point };
+    export { Arc };
+}
+export { default as PlotChart } from "./Plot.svelte";
+export { default as FacetPlot } from "./FacetPlot.svelte";
+export { default as AnimatedPlot } from "./AnimatedPlot.svelte";
+export { default as GeomBar } from "./geoms/Bar.svelte";
+export { default as GeomLine } from "./geoms/Line.svelte";
+export { default as GeomArea } from "./geoms/Area.svelte";
+export { default as GeomPoint } from "./geoms/Point.svelte";
+export { default as GeomArc } from "./geoms/Arc.svelte";
+export { default as GeomBox } from "./geoms/Box.svelte";
+export { default as GeomViolin } from "./geoms/Violin.svelte";
+export { default as Chart } from "./Chart.svelte";
+export { default as Sparkline } from "./Sparkline.svelte";
+export { default as BarChart } from "./charts/BarChart.svelte";
+export { default as LineChart } from "./charts/LineChart.svelte";
+export { default as AreaChart } from "./charts/AreaChart.svelte";
+export { default as PieChart } from "./charts/PieChart.svelte";
+export { default as ScatterPlot } from "./charts/ScatterPlot.svelte";
+export { default as BoxPlot } from "./charts/BoxPlot.svelte";
+export { default as ViolinPlot } from "./charts/ViolinPlot.svelte";
+export { default as BubbleChart } from "./charts/BubbleChart.svelte";
+export { PlotState } from "./PlotState.svelte.js";
+export { ChartBrewer } from "./lib/brewing/index.svelte.js";
+export * from "./lib/brewing/index.svelte.js";
+export { CartesianBrewer } from "./lib/brewing/CartesianBrewer.svelte.js";
+export { PieBrewer } from "./lib/brewing/PieBrewer.svelte.js";
+export { BoxBrewer } from "./lib/brewing/BoxBrewer.svelte.js";
+export { ViolinBrewer } from "./lib/brewing/ViolinBrewer.svelte.js";
+export { createCrossFilter } from "./crossfilter/createCrossFilter.svelte.js";
+export { default as CrossFilter } from "./crossfilter/CrossFilter.svelte";
+export { default as FilterBar } from "./crossfilter/FilterBar.svelte";
+export { default as FilterSlider } from "./crossfilter/FilterSlider.svelte";
+import Root from './Plot/Root.svelte';
+import Axis from './Plot/Axis.svelte';
+import Bar from './Plot/Bar.svelte';
+import Grid from './Plot/Grid.svelte';
+import Legend from './Plot/Legend.svelte';
+import Line from './Plot/Line.svelte';
+import Area from './Plot/Area.svelte';
+import Point from './Plot/Point.svelte';
+import Arc from './Plot/Arc.svelte';

package/dist/lib/brewer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Get fill patterns for a set of values
+ *
+ * @param {Array} values - Array of values
+ * @param {Object} swatch - Object with keys for color, gray, and pattern
+ * @param {Boolean} gray - Boolean to determine if gray or color
+ * @returns {Object} - Object with keys for pattern and color
+ */
+export function getFillPatterns(values: any[], swatch: Object, gray?: boolean): Object;

package/dist/lib/brewing/BoxBrewer.svelte.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Brewer for box plots. Always computes quartile statistics regardless of the stat prop.
+ * Groups by x + fill (primary) or x + color (fallback).
+ * fill = box interior color, color = whisker/outline stroke.
+ */
+export class BoxBrewer extends ChartBrewer {
+    transform(data: any, channels: any): any;
+    boxes: any[];
+}
+import { ChartBrewer } from './brewer.svelte.js';

package/dist/lib/brewing/CartesianBrewer.svelte.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Brewer for cartesian charts (Bar, Line, Area).
+ * Groups by x (and fill/color if set) and applies the given stat.
+ */
+export class CartesianBrewer extends ChartBrewer {
+    transform(data: any, channels: any, stat: any): any;
+}
+import { ChartBrewer } from './brewer.svelte.js';

package/dist/lib/brewing/PieBrewer.svelte.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Brewer for pie charts. Always aggregates by the label field.
+ * 'identity' is not meaningful for pie charts — falls back to 'sum'.
+ */
+export class PieBrewer extends ChartBrewer {
+    transform(data: any, channels: any, stat: any): any;
+}
+import { ChartBrewer } from './brewer.svelte.js';

package/dist/lib/brewing/ViolinBrewer.svelte.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Brewer for violin plots. Computes the same quartile statistics as BoxBrewer.
+ * fill = violin body color, color = outline stroke.
+ */
+export class ViolinBrewer extends ChartBrewer {
+    transform(data: any, channels: any): any;
+    violins: any[];
+}
+import { ChartBrewer } from './brewer.svelte.js';

package/dist/lib/brewing/axes.svelte.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Creates x-axis tick data for rendering
+ *
+ * @param {Object} scales - Chart scales
+ * @param {Function} scales.x - X-axis scale
+ * @param {Object} dimensions - Chart dimensions
+ * @param {Object} options - Axis options
+ * @param {number} [options.tickCount] - Number of ticks to show
+ * @param {Function} [options.tickFormat] - Tick formatting function
+ * @param {string} [options.label] - Axis label
+ * @returns {AxisData} Axis rendering data
+ */
+export function createXAxis(scales: {
+    x: Function;
+}, dimensions: Object, options: {
+    tickCount?: number | undefined;
+    tickFormat?: Function | undefined;
+    label?: string | undefined;
+}): AxisData;
+/**
+ * Creates y-axis tick data for rendering
+ *
+ * @param {Object} scales - Chart scales
+ * @param {Function} scales.y - Y-axis scale
+ * @param {Object} dimensions - Chart dimensions
+ * @param {Object} options - Axis options
+ * @param {number} [options.tickCount] - Number of ticks to show
+ * @param {Function} [options.tickFormat] - Tick formatting function
+ * @param {string} [options.label] - Axis label
+ * @returns {AxisData} Axis rendering data
+ */
+export function createYAxis(scales: {
+    y: Function;
+}, dimensions: Object, options: {
+    tickCount?: number | undefined;
+    tickFormat?: Function | undefined;
+    label?: string | undefined;
+}): AxisData;
+/**
+ * Creates grid line data for rendering
+ *
+ * @param {Object} scales - Chart scales
+ * @param {Object} dimensions - Chart dimensions
+ * @param {Object} options - Grid options
+ * @param {string} [options.direction='both'] - Grid direction ('x', 'y', or 'both')
+ * @param {number} [options.xTickCount] - Number of x-axis ticks
+ * @param {number} [options.yTickCount] - Number of y-axis ticks
+ * @returns {Object} Grid rendering data
+ */
+export function createGrid(scales: Object, dimensions: Object, options: {
+    direction?: string | undefined;
+    xTickCount?: number | undefined;
+    yTickCount?: number | undefined;
+}): Object;
+/**
+ * Creates DOM attributes for a tick element
+ *
+ * @param {TickData} tick - Tick data
+ * @param {string} axis - Axis type ('x' or 'y')
+ * @returns {Object} Attributes for the tick
+ */
+export function createTickAttributes(tick: TickData, axis: string): Object;
+export type TickData = import("./types").TickData;
+export type AxisData = import("./types").AxisData;
+export type ChartScales = import("./types").ChartScales;
+export type ChartDimensions = import("./types").ChartDimensions;

package/dist/lib/brewing/bars.svelte.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Creates bar data for rendering
+ *
+ * @param {Array} data - Chart data
+ * @param {Object} fields - Field mappings
+ * @param {string} fields.x - X-axis field
+ * @param {string} fields.y - Y-axis field
+ * @param {string} fields.color - Color field (optional)
+ * @param {Object} scales - Chart scales
+ * @param {Function} scales.x - X-axis scale
+ * @param {Function} scales.y - Y-axis scale
+ * @param {Function} scales.color - Color scale
+ * @param {Object} options - Options including dimensions and defaultColor
+ * @param {Object} options.dimensions - Chart dimensions
+ * @param {string} [options.defaultColor='#4682b4'] - Default color if no color scale
+ * @returns {BarData[]} Bar data for rendering
+ */
+export function createBars(data: any[], fields: {
+    x: string;
+    y: string;
+    color: string;
+}, scales: {
+    x: Function;
+    y: Function;
+    color: Function;
+}, options: {
+    dimensions: Object;
+    defaultColor?: string | undefined;
+}): BarData[];
+/**
+ * Filter bars based on a selection criteria
+ *
+ * @param {BarData[]} bars - Bar data array
+ * @param {Object} selection - Selection criteria
+ * @returns {BarData[]} Filtered bars
+ */
+export function filterBars(bars: BarData[], selection: Object): BarData[];
+/**
+ * Creates a grouped bars layout
+ *
+ * @param {Array} data - Chart data
+ * @param {Object} fields - Field mappings
+ * @param {Object} scales - Chart scales
+ * @param {Object} options - Options including dimensions and padding
+ * @param {Object} options.dimensions - Chart dimensions
+ * @param {number} [options.padding=0.1] - Padding between bars in a group
+ * @returns {Object} Grouped bar data
+ */
+export function createGroupedBars(data: any[], fields: Object, scales: Object, options: {
+    dimensions: Object;
+    padding?: number | undefined;
+}): Object;
+export type BarData = import("./types").BarData;
+export type ScaleFields = import("./types").ScaleFields;
+export type ChartScales = import("./types").ChartScales;
+export type ChartDimensions = import("./types").ChartDimensions;