@rokkit/chart 1.0.0-next.14 → 1.0.0-next.141

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,5 @@
+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";

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/index.d.ts

@@ -0,0 +1,14 @@
+export namespace Plot {
+    export { Root };
+    export { Axis };
+    export { Bar };
+    export { Grid };
+    export { Legend };
+}
+export { ChartBrewer } from "./lib/brewing/index.svelte.js";
+export * from "./lib/brewing/index.svelte.js";
+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';

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;

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

@@ -0,0 +1,35 @@
+/**
+ * Creates chart dimensions based on width, height and margins
+ *
+ * @param {number} width - Total chart width
+ * @param {number} height - Total chart height
+ * @param {ChartMargin} margin - Chart margins
+ * @returns {ChartDimensions} Chart dimensions
+ */
+export function createDimensions(width?: number, height?: number, margin?: ChartMargin): ChartDimensions;
+/**
+ * Updates existing dimensions with new values
+ *
+ * @param {ChartDimensions} dimensions - Current dimensions
+ * @param {Object} updates - Values to update
+ * @param {number} [updates.width] - New width
+ * @param {number} [updates.height] - New height
+ * @param {ChartMargin} [updates.margin] - New margin
+ * @returns {ChartDimensions} Updated dimensions
+ */
+export function updateDimensions(dimensions: ChartDimensions, updates?: {
+    width?: number | undefined;
+    height?: number | undefined;
+    margin?: import("./types.js").ChartMargin | undefined;
+}): ChartDimensions;
+/**
+ * @typedef {import('./types').ChartMargin} ChartMargin
+ * @typedef {import('./types').ChartDimensions} ChartDimensions
+ */
+/**
+ * Default chart margin
+ * @type {ChartMargin}
+ */
+export const DEFAULT_MARGIN: ChartMargin;
+export type ChartMargin = import("./types").ChartMargin;
+export type ChartDimensions = import("./types").ChartDimensions;

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

@@ -0,0 +1,118 @@
+/**
+ * Main class that manages chart state and provides access to all brewing functions
+ */
+export class ChartBrewer {
+    /**
+     * Creates a new ChartBrewer instance
+     *
+     * @param {Object} options Configuration options
+     */
+    constructor(options?: Object);
+    /**
+     * Sets the data for the chart
+     *
+     * @param {Array} data Data array
+     * @returns {ChartBrewer} this for method chaining
+     */
+    setData(data: any[]): ChartBrewer;
+    /**
+     * Sets the field mappings for axes and color
+     *
+     * @param {Object} fields Field mappings
+     * @returns {ChartBrewer} this for method chaining
+     */
+    setFields({ x, y, color }: Object): ChartBrewer;
+    /**
+     * Sets the dimensions of the chart
+     *
+     * @param {Object} dimensions Chart dimensions
+     * @returns {ChartBrewer} this for method chaining
+     */
+    setDimensions({ width, height, margin }: Object): ChartBrewer;
+    /**
+     * Creates scales based on data and dimensions
+     *
+     * @returns {ChartBrewer} this for method chaining
+     */
+    createScales(): ChartBrewer;
+    /**
+     * Creates bar data for rendering
+     *
+     * @returns {Array} Data for rendering bars
+     */
+    createBars(): any[];
+    /**
+     * Creates x-axis tick data for rendering
+     *
+     * @param {Object} options Axis options
+     * @returns {Object} Axis rendering data
+     */
+    createXAxis(options?: Object): Object;
+    /**
+     * Creates y-axis tick data for rendering
+     *
+     * @param {Object} options Axis options
+     * @returns {Object} Axis rendering data
+     */
+    createYAxis(options?: Object): Object;
+    /**
+     * Creates grid line data for rendering
+     *
+     * @param {Object} options Grid options
+     * @returns {Object} Grid rendering data
+     */
+    createGrid(options?: Object): Object;
+    /**
+     * Creates legend data for rendering
+     *
+     * @param {Object} options Legend options
+     * @returns {Object} Legend rendering data
+     */
+    createLegend(options?: Object): Object;
+    /**
+     * Gets all chart dimensions
+     *
+     * @returns {Object} Chart dimensions
+     */
+    getDimensions(): Object;
+    /**
+     * Gets all chart scales
+     *
+     * @returns {Object} Chart scales
+     */
+    getScales(): Object;
+    /**
+     * Gets the animation duration
+     *
+     * @returns {number} Animation duration in ms
+     */
+    getAnimationDuration(): number;
+    /**
+     * Gets the data being used
+     *
+     * @returns {Array} Chart data
+     */
+    getData(): any[];
+    /**
+     * Gets the fields configuration
+     *
+     * @returns {Object} Fields configuration
+     */
+    getFields(): Object;
+    #private;
+}
+import { createDimensions } from './dimensions.svelte.js';
+import { updateDimensions } from './dimensions.svelte.js';
+import { createScales } from './scales.svelte.js';
+import { getOrigin } from './scales.svelte.js';
+import { createBars } from './bars.svelte.js';
+import { filterBars } from './bars.svelte.js';
+import { createGroupedBars } from './bars.svelte.js';
+import { createXAxis } from './axes.svelte.js';
+import { createYAxis } from './axes.svelte.js';
+import { createGrid } from './axes.svelte.js';
+import { createTickAttributes } from './axes.svelte.js';
+import { createLegend } from './legends.svelte.js';
+import { filterByLegend } from './legends.svelte.js';
+import { createLegendItemAttributes } from './legends.svelte.js';
+export { createDimensions, updateDimensions, createScales, getOrigin, createBars, filterBars, createGroupedBars, createXAxis, createYAxis, createGrid, createTickAttributes, createLegend, filterByLegend, createLegendItemAttributes };

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

@@ -0,0 +1,48 @@
+/**
+ * Creates legend data for rendering
+ *
+ * @param {Array} data - Chart data
+ * @param {Object} fields - Field mappings
+ * @param {string} fields.color - Color field
+ * @param {Object} scales - Chart scales
+ * @param {Function} scales.color - Color scale
+ * @param {Object} options - Legend options including dimensions
+ * @param {Object} options.dimensions - Chart dimensions
+ * @param {string} [options.title=''] - Legend title
+ * @param {string} [options.align='right'] - Legend alignment ('left', 'center', or 'right')
+ * @param {string} [options.shape='rect'] - Legend marker shape ('rect' or 'circle')
+ * @param {number} [options.markerSize=10] - Size of legend markers
+ * @returns {LegendData} Legend rendering data
+ */
+export function createLegend(data: any[], fields: {
+    color: string;
+}, scales: {
+    color: Function;
+}, options: {
+    dimensions: Object;
+    title?: string | undefined;
+    align?: string | undefined;
+    shape?: string | undefined;
+    markerSize?: number | undefined;
+}): LegendData;
+/**
+ * Filter data based on legend selection
+ *
+ * @param {Array} data - Chart data
+ * @param {string} colorField - Field used for color mapping
+ * @param {Array} selectedValues - Selected legend values
+ * @returns {Array} Filtered data
+ */
+export function filterByLegend(data: any[], colorField: string, selectedValues: any[]): any[];
+/**
+ * Create attributes for legend items
+ *
+ * @param {LegendItem} item - Legend item
+ * @returns {Object} Attributes for the legend item
+ */
+export function createLegendItemAttributes(item: LegendItem): Object;
+export type LegendItem = import("./types").LegendItem;
+export type LegendData = import("./types").LegendData;
+export type ScaleFields = import("./types").ScaleFields;
+export type ChartScales = import("./types").ChartScales;
+export type ChartDimensions = import("./types").ChartDimensions;

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

@@ -0,0 +1,24 @@
+/**
+ * Creates scales based on data, fields, and dimensions
+ *
+ * @param {Array} data - Chart data
+ * @param {ScaleFields} fields - Field mappings
+ * @param {Object} dimensions - Chart dimensions
+ * @param {Object} options - Scale options
+ * @param {number} [options.padding=0.2] - Padding for band scales
+ * @returns {ChartScales} Chart scales
+ */
+export function createScales(data: any[], fields: ScaleFields, dimensions: Object, options?: {
+    padding?: number | undefined;
+}): ChartScales;
+/**
+ * Gets the origin coordinates for the axes
+ *
+ * @param {ChartScales} scales - Chart scales
+ * @param {Object} dimensions - Chart dimensions
+ * @returns {Object} Origin coordinates
+ */
+export function getOrigin(scales: ChartScales, dimensions: Object): Object;
+export type ChartScales = import("./types").ChartScales;
+export type ScaleFields = import("./types").ScaleFields;
+export type ChartDimensions = import("./types").ChartDimensions;