@matthieumordrel/chart-studio 0.3.0 → 0.5.2

package/README.md

@@ -1,395 +1,27 @@
-# chart-studio
+# @matthieumordrel/chart-studio
 
-Composable charting for React with two adoption paths:
+> Early alpha. Active work in progress. Not recommended for production use yet.
 
-- use the **headless core** if you want chart state, filtering, grouping, and transformed data
-- use the **optional UI layer** if you also want ready-made controls and a Recharts canvas
+Headless, composable charting for React.
 
-Package: `@matthieumordrel/chart-studio`
-
-## Start Here
-
-Choose the path that matches your app:
-
-### 1. Headless core
-
-Use this if you already have your own design system or chart renderer.
-
-You get:
-
-- `useChart`
-- optional `schema` via `defineChartSchema`
-- transformed chart data
-- filtering, grouping, metrics, and time bucketing logic
-
-Requirements:
-
-- `react` >= 18.2.0
-
-Install:
-
-```bash
-bun add @matthieumordrel/chart-studio react
-```
-
-Import from:
-
-```tsx
-import { useChart } from '@matthieumordrel/chart-studio'
-```
-
-### 2. Ready-made UI
-
-Use this if you want the package to render the controls and chart for you.
-
-You get:
-
-- everything from the headless core
-- `<Chart>`
-- `<ChartToolbar>`
-- `<ChartCanvas>`
-- granular UI controls from `@matthieumordrel/chart-studio/ui`
-
-Requirements:
-
-- `react` >= 18.2.0
-- `recharts` >= 3.0.0 (v2 is **not** supported)
-- `lucide-react` >= 0.577.0 (optional, for toolbar icons)
+Use this package when you want chart state, filtering, grouping, metrics, time bucketing, transformed data, and the model/dashboard APIs without the optional UI layer.
 
 Install:
 
 ```bash
-bun add @matthieumordrel/chart-studio react recharts lucide-react
+bun add @matthieumordrel/chart-studio@alpha react
 ```
 
-Then import the package theme once in your app stylesheet:
-
-```css
-@import 'tailwindcss';
-@import '@matthieumordrel/chart-studio/ui/theme.css';
-```
+Current prereleases are published under the `alpha` dist-tag on npm.
 
 Import from:
 
 ```tsx
-import { useChart } from '@matthieumordrel/chart-studio'
-import { Chart, ChartToolbar, ChartCanvas } from '@matthieumordrel/chart-studio/ui'
-```
-
-## Smallest Working Example (Single Source)
-
-```tsx
-import { useChart } from '@matthieumordrel/chart-studio'
-import { Chart, ChartToolbar, ChartCanvas } from '@matthieumordrel/chart-studio/ui'
-import { data } from './data.json'
-
-export function JobsChart() {
-  const chart = useChart({ data })
-
-  return (
-    <Chart chart={chart}>
-      <ChartToolbar />
-      <ChartCanvas height={320} />
-    </Chart>
-  )
-}
-```
-
-## How It Works
-
-1. Pass your raw data to `useChart()`.
-2. Add an optional `schema` with `defineChartSchema<Row>()...` when you need labels, type overrides, derived columns, or control restrictions (allowed metrics, groupings, chart types, etc.).
-3. Either render your own UI from the returned state, or use the components from `@matthieumordrel/chart-studio/ui`.
-
-## Column Types
-
-| Type       | What it is for                          |
-| ---------- | --------------------------------------- |
-| `date`     | time-series X-axis                      |
-| `category` | categorical X-axis, grouping, filtering |
-| `boolean`  | grouping, filtering                     |
-| `number`   | metrics such as sum, avg, min, max      |
-
-## Declarative Schema and Control Restrictions
-
-If you want to expose only a subset of groupings, metrics, chart types, or axes, use the fluent `defineChartSchema<Row>()` builder:
-
-```tsx
-import { defineChartSchema, useChart } from '@matthieumordrel/chart-studio'
-
-type Row = { periodEnd: string; segment: string; revenue: number; netIncome: number }
-
-const schema = defineChartSchema<Row>()
-  .columns((c) => [
-    c.date('periodEnd', { label: 'Period End' }),
-    c.category('segment'),
-    c.number('revenue'),
-    c.number('netIncome')
-  ])
-  .xAxis((x) => x.allowed('periodEnd'))
-  .groupBy((g) => g.allowed('segment'))
-  .metric((m) =>
-    m
-      .count()
-      .aggregate('revenue', 'sum', 'avg')
-      .aggregate('netIncome', 'sum')
-  )
-  .chartType((t) => t.allowed('bar', 'line'))
-  .timeBucket((tb) => tb.allowed('year', 'quarter', 'month'))
-
-const chart = useChart({ data, schema })
-```
-
-Why this pattern:
-
-- `columns` defines types, labels, and formats for raw fields; use `c.exclude(...)` to remove a column from the chart
-- Derived columns use `c.derived.*(...)` helpers for computed values from each row
-- `xAxis`, `groupBy`, `metric`, `chartType`, and `timeBucket` restrict the allowed options
-- invalid column IDs and config keys are rejected at compile time
-- metric restrictions preserve the order you declare, so the first allowed metric becomes the default
-
-## Headless Example
-
-If you want to render your own UI or your own charting library, use only the core state:
-
-```tsx
-import { defineChartSchema, useChart } from '@matthieumordrel/chart-studio'
-
-type Job = {
-  dateAdded: string
-  ownerName: string
-  salary: number
-}
-
-const jobSchema = defineChartSchema<Job>()
-  .columns((c) => [
-    c.date('dateAdded', { label: 'Date Added' }),
-    c.category('ownerName', { label: 'Consultant' }),
-    c.number('salary', { label: 'Salary' })
-  ])
-
-export function JobsChartHeadless({ data }: { data: Job[] }) {
-  const chart = useChart({ data, schema: jobSchema })
-
-  return (
-    <div>
-      <div>Chart type: {chart.chartType}</div>
-      <div>Rows: {chart.transformedData.length}</div>
-      <pre>{JSON.stringify(chart.transformedData, null, 2)}</pre>
-    </div>
-  )
-}
-```
-
-## Styling Requirements
-
-The headless core has no styling requirements.
-
-The `ui` layer is Tailwind-based and uses semantic classes such as:
-
-- `bg-background`
-- `text-foreground`
-- `border-border`
-- `bg-popover`
-- `text-muted-foreground`
-
-For those classes to render correctly, Tailwind needs real values behind tokens like `background`, `foreground`, `border`, and `popover`.
-
-You can use `ui` in two ways:
-
-### 1. Recommended: import the built-in theme
-
-This is the easiest setup:
-
-```css
-@import 'tailwindcss';
-@import '@matthieumordrel/chart-studio/ui/theme.css';
-```
-
-This does three things for you:
-
-- Tailwind utilities for the package components
-- automatic scanning of the package UI classes
-- default fallback values for all semantic UI tokens
-- built-in light and dark default themes
-
-If your app already defines matching shadcn-style variables, those values take over automatically. If not, the built-in defaults are used.
-
-The shipped theme supports dark mode through either:
-
-- `.dark`
-- `[data-theme="dark"]`
-
-### 2. Advanced: define everything yourself
-
-If you do not want to import `@matthieumordrel/chart-studio/ui/theme.css`, you can provide all the required semantic tokens yourself in your app theme.
-
-If neither of those is true, use the headless core and render your own controls.
-
-### Minimum UI theme contract
-
-You do not need shadcn itself to use `@matthieumordrel/chart-studio/ui`.
-
-If you import `@matthieumordrel/chart-studio/ui/theme.css`, every token below gets a built-in fallback automatically.
-
-If your app already defines some of these variables, your values override the defaults for those specific tokens only. Missing ones still fall back to the package defaults.
-
-These are the tokens currently expected by the UI layer:
-
-| Token                | Purpose                                |
-| -------------------- | -------------------------------------- |
-| `background`         | control backgrounds and input surfaces |
-| `foreground`         | primary text                           |
-| `muted`              | subtle backgrounds and hover states    |
-| `muted-foreground`   | secondary text and icons               |
-| `border`             | outlines and separators                |
-| `popover`            | dropdowns and floating panels          |
-| `popover-foreground` | popover text color                     |
-| `primary`            | selected and active states             |
-| `primary-foreground` | text on filled primary surfaces        |
-| `ring`               | focus-visible ring color               |
-
-Minimal example:
-
-```css
-:root {
-  --background: 0 0% 100%;
-  --foreground: 222.2 84% 4.9%;
-  --muted: 210 40% 96.1%;
-  --muted-foreground: 215.4 16.3% 46.9%;
-  --border: 214.3 31.8% 91.4%;
-  --popover: 0 0% 100%;
-  --popover-foreground: 222.2 84% 4.9%;
-  --primary: 222.2 47.4% 11.2%;
-  --primary-foreground: 210 40% 98%;
-  --ring: 221.2 83.2% 53.3%;
-}
-```
-
-How this works in practice:
-
-- import `ui/theme.css` and do nothing else: the package uses its own defaults
-- toggle dark mode with either `.dark` or `[data-theme="dark"]`: the package uses its built-in dark defaults
-- import `ui/theme.css` and define only a few variables: your values win for those variables, defaults cover the rest
-- skip `ui/theme.css`: you must define the whole token contract yourself
-
-That makes the package usable out of the box while still being easy to theme.
-
-### Optional chart color tokens
-
-Chart series colors also support shadcn-style chart variables:
-
-| Token     | Purpose             |
-| --------- | ------------------- |
-| `chart-1` | first series color  |
-| `chart-2` | second series color |
-| `chart-3` | third series color  |
-| `chart-4` | fourth series color |
-| `chart-5` | fifth series color  |
-
-These are also optional when you import `ui/theme.css`.
-
-If your app defines `--chart-1` through `--chart-5`, those colors are used automatically.
-
-If they are not defined, `chart-studio` falls back to a built-in OKLCH palette, with separate light and dark defaults. That is why you may see blue, rose, cyan, or other fallback colors in charts when your app does not provide chart variables.
-
-Minimal example:
-
-```css
-:root {
-  --chart-1: 221.2 83.2% 53.3%;
-  --chart-2: 262.1 83.3% 57.8%;
-  --chart-3: 24.6 95% 53.1%;
-  --chart-4: 142.1 76.2% 36.3%;
-  --chart-5: 346.8 77.2% 49.8%;
-}
-```
-
-## Common Questions
-
-### Which import path should I use?
-
-- Use `@matthieumordrel/chart-studio` for the headless core.
-- Use `@matthieumordrel/chart-studio/ui` for the optional UI components.
-
-### Do I need Recharts?
-
-Only for the UI layer. The headless core works without it.
-
-### Do I need Tailwind?
-
-Only for the UI layer. The headless core does not require it.
-
-### Can I use multiple datasets?
-
-Yes:
-
-```tsx
-import { defineChartSchema, useChart } from '@matthieumordrel/chart-studio'
-
-const chart = useChart({
-  sources: [
-    {
-      id: 'jobs',
-      label: 'Jobs',
-      data: jobs,
-      schema: defineChartSchema<Job>()
-        .columns((c) => [c.date('dateAdded', { label: 'Date Added' })])
-    },
-    { id: 'candidates', label: 'Candidates', data: candidates }
-  ]
-})
-```
-
-### What chart types are available?
-
-- date X-axis: `bar`, `line`, `area`
-- category or boolean X-axis: `bar`, `pie`, `donut`
-- `pie` and `donut` do not support `groupBy`
-
-## Troubleshooting
-
-### The UI looks mostly unstyled
-
-If the components render but look plain, compressed, or layout incorrectly, the most common cause is that the package theme file is not imported.
-
-Start with:
-
-```css
-@import 'tailwindcss';
-@import '@matthieumordrel/chart-studio/ui/theme.css';
+import {defineDataset, useChart} from '@matthieumordrel/chart-studio'
 ```
 
-If you are importing the package source directly in a local playground or monorepo, make sure Tailwind is scanning those source files too.
-
-If your app already uses shadcn-style tokens, also make sure tokens such as `background`, `foreground`, `muted`, `border`, `popover`, `primary`, `ring`, and optionally `chart-1` through `chart-5` are defined in your theme.
-
-## On the Radar
-
-These are known limitations and areas being considered for future versions. None of these are committed — they represent directions the library may grow based on real usage.
-
-### Renderer flexibility
-
-The UI layer currently only supports Recharts. If you want to use ECharts, Plotly, or another renderer, you can use the headless core but lose the built-in toolbar and canvas composition. A renderer adapter pattern for `<ChartCanvas>` could make the UI layer renderer-agnostic.
-
-### Richer aggregation
-
-The pipeline supports sum, avg, min, and max. Derived columns can access multiple fields of a single row (e.g. `row.revenue - row.cost`), but there is no support yet for metrics that depend on other rows or on aggregated results — things like "% of total", running totals, percentiles, or post-aggregation ratios (e.g. total revenue / total orders).
-
-### Chart interactivity
-
-There is currently no built-in support for drill-down, click-to-filter, brush selection, or linked charts. The headless state can be wired manually to achieve some of these, but first-class interactivity primitives would make this significantly easier.
-
-### Multi-dataset composition
-
-Each chart instance operates on a single flat dataset. Overlaying series from different schemas (e.g. revenue on the left Y-axis and headcount on the right) would require separate chart instances today. Dual-axis and cross-dataset composition are not yet supported.
-
-### Schema Builder Ergonomics
-
-`defineChartSchema<Row>()` now returns one fluent builder that you pass directly to `useChart(...)` or `inferColumnsFromData(...)`. That keeps the public API strongly typed while improving IntelliSense for raw field ids, derived columns, and control restrictions.
+If you also want the optional ready-made React UI, install `@matthieumordrel/chart-studio-ui` alongside this package.
 
-## Release
+Special thanks to the teams behind TanStack Table and Recharts.
 
-- `bun run release:check`
-- `bun run release:publish -- --tag=latest`
-- `npm publish` runs `prepublishOnly`, which calls `bun run release:check`
+Full documentation: <https://github.com/MatthieuMordrel/chart-studio#readme>

package/dist/_internal.d.mts

@@ -0,0 +1,9 @@
+import { DATE_RANGE_PRESETS, DateRangePreset, autoFilterForBucket, getPresetLabel, resolvePresetFilter } from "./core/date-range-presets.mjs";
+import { CHART_TYPE_CONFIG } from "./core/chart-capabilities.mjs";
+import { buildColorMap, getSeriesColor } from "./core/colors.mjs";
+import { DATA_LABEL_DEFAULTS, DataLabelDefaults, DataLabelPosition, DataLabelStyle, resolveShowDataLabels } from "./core/data-label-defaults.mjs";
+import { computeDateRange, filterByDateRange } from "./core/date-utils.mjs";
+import { ChartValueSurface, NumericRange, createNumericRange, formatChartValue, formatNumericSurfaceValue, formatTimeBucketLabel, shouldAllowDecimalTicks } from "./core/formatting.mjs";
+import { DEFAULT_METRIC, getAggregateMetricLabel, getMetricLabel, isAggregateMetric, isSameMetric } from "./core/metric-utils.mjs";
+import { applyFilters } from "./core/pipeline.mjs";
+export { CHART_TYPE_CONFIG, type ChartValueSurface, DATA_LABEL_DEFAULTS, DATE_RANGE_PRESETS, DEFAULT_METRIC, type DataLabelDefaults, type DataLabelPosition, type DataLabelStyle, type DateRangePreset, type NumericRange, applyFilters, autoFilterForBucket, buildColorMap, computeDateRange, createNumericRange, filterByDateRange, formatChartValue, formatNumericSurfaceValue, formatTimeBucketLabel, getAggregateMetricLabel, getMetricLabel, getPresetLabel, getSeriesColor, isAggregateMetric, isSameMetric, resolvePresetFilter, resolveShowDataLabels, shouldAllowDecimalTicks };

package/dist/_internal.mjs

@@ -0,0 +1,9 @@
+import { CHART_TYPE_CONFIG } from "./core/chart-capabilities.mjs";
+import { DATA_LABEL_DEFAULTS, resolveShowDataLabels } from "./core/data-label-defaults.mjs";
+import { buildColorMap, getSeriesColor } from "./core/colors.mjs";
+import { DATE_RANGE_PRESETS, autoFilterForBucket, getPresetLabel, resolvePresetFilter } from "./core/date-range-presets.mjs";
+import { computeDateRange, filterByDateRange } from "./core/date-utils.mjs";
+import { DEFAULT_METRIC, getAggregateMetricLabel, getMetricLabel, isAggregateMetric, isSameMetric } from "./core/metric-utils.mjs";
+import { createNumericRange, formatChartValue, formatNumericSurfaceValue, formatTimeBucketLabel, shouldAllowDecimalTicks } from "./core/formatting.mjs";
+import { applyFilters } from "./core/pipeline.mjs";
+export { CHART_TYPE_CONFIG, DATA_LABEL_DEFAULTS, DATE_RANGE_PRESETS, DEFAULT_METRIC, applyFilters, autoFilterForBucket, buildColorMap, computeDateRange, createNumericRange, filterByDateRange, formatChartValue, formatNumericSurfaceValue, formatTimeBucketLabel, getAggregateMetricLabel, getMetricLabel, getPresetLabel, getSeriesColor, isAggregateMetric, isSameMetric, resolvePresetFilter, resolveShowDataLabels, shouldAllowDecimalTicks };

package/dist/core/chart-builder-controls.mjs

@@ -0,0 +1,141 @@
+import { isSameMetric, normalizeMetricAllowances } from "./metric-utils.mjs";
+//#region src/core/chart-builder-controls.ts
+const SELECTABLE_CONTROL_CONFIG = Symbol("chart-schema-selectable-control-config");
+const METRIC_CONTROL_CONFIG = Symbol("chart-schema-metric-config");
+function uniqueValues(values) {
+	if (!values || values.length === 0) return;
+	return [...new Set(values)];
+}
+function sanitizeSelectableControlConfig(config, supportsDefault) {
+	const allowed = uniqueValues(config.allowed);
+	let hidden = uniqueValues(config.hidden);
+	if (allowed && hidden) {
+		const allowedSet = new Set(allowed);
+		hidden = hidden.filter((option) => allowedSet.has(option));
+	}
+	let nextDefault = supportsDefault ? config.default : void 0;
+	if (nextDefault !== void 0) {
+		if (allowed && !allowed.includes(nextDefault)) nextDefault = void 0;
+		if (nextDefault !== void 0 && hidden?.includes(nextDefault)) nextDefault = void 0;
+	}
+	const nextConfig = {};
+	if (allowed && allowed.length > 0) nextConfig.allowed = allowed;
+	if (hidden && hidden.length > 0) nextConfig.hidden = hidden;
+	if (nextDefault !== void 0) nextConfig.default = nextDefault;
+	return nextConfig;
+}
+function createSelectableControlBuilder(config = {}, supportsDefault) {
+	const nextConfig = sanitizeSelectableControlConfig(config, supportsDefault);
+	return {
+		allowed(...options) {
+			return createSelectableControlBuilder({
+				...nextConfig,
+				allowed: options
+			}, supportsDefault);
+		},
+		hidden(...options) {
+			return createSelectableControlBuilder({
+				...nextConfig,
+				hidden: [...nextConfig.hidden ?? [], ...options]
+			}, supportsDefault);
+		},
+		default(option) {
+			return createSelectableControlBuilder({
+				...nextConfig,
+				default: option
+			}, supportsDefault);
+		},
+		[SELECTABLE_CONTROL_CONFIG]: nextConfig
+	};
+}
+function uniqueMetrics(metrics) {
+	if (!metrics || metrics.length === 0) return;
+	const unique = [];
+	for (const metric of metrics) if (!unique.some((candidate) => isSameMetric(candidate, metric))) unique.push(metric);
+	return unique;
+}
+function sanitizeMetricConfig(config) {
+	const allowed = config.allowed && config.allowed.length > 0 ? [...config.allowed] : void 0;
+	let hidden = uniqueMetrics(config.hidden);
+	const expandedAllowed = normalizeMetricAllowances(allowed);
+	if (expandedAllowed && hidden) hidden = hidden.filter((metric) => expandedAllowed.some((allowedMetric) => isSameMetric(allowedMetric, metric)));
+	let nextDefault = config.default;
+	if (nextDefault) {
+		const defaultMetric = nextDefault;
+		if (expandedAllowed && !expandedAllowed.some((metric) => isSameMetric(metric, defaultMetric))) nextDefault = void 0;
+		if (nextDefault) {
+			const visibleDefault = nextDefault;
+			if (hidden?.some((metric) => isSameMetric(metric, visibleDefault))) nextDefault = void 0;
+		}
+	}
+	const nextConfig = {};
+	if (allowed && allowed.length > 0) nextConfig.allowed = allowed;
+	if (hidden && hidden.length > 0) nextConfig.hidden = hidden;
+	if (nextDefault) nextConfig.default = nextDefault;
+	return nextConfig;
+}
+function createMetricBuilder(config = {}) {
+	const nextConfig = sanitizeMetricConfig(config);
+	return {
+		count() {
+			return createMetricBuilder({
+				...nextConfig,
+				allowed: [...nextConfig.allowed ?? [], { kind: "count" }]
+			});
+		},
+		aggregate(columnId, firstAggregate, ...restAggregates) {
+			const aggregates = [firstAggregate, ...restAggregates];
+			const selection = restAggregates.length === 0 ? firstAggregate : aggregates;
+			return createMetricBuilder({
+				...nextConfig,
+				allowed: [...nextConfig.allowed ?? [], {
+					kind: "aggregate",
+					columnId,
+					aggregate: selection
+				}]
+			});
+		},
+		hideCount() {
+			return createMetricBuilder({
+				...nextConfig,
+				hidden: [...nextConfig.hidden ?? [], { kind: "count" }]
+			});
+		},
+		hideAggregate(columnId, firstAggregate, ...restAggregates) {
+			const aggregates = [firstAggregate, ...restAggregates];
+			return createMetricBuilder({
+				...nextConfig,
+				hidden: [...nextConfig.hidden ?? [], ...aggregates.map((aggregate) => ({
+					kind: "aggregate",
+					columnId,
+					aggregate
+				}))]
+			});
+		},
+		defaultCount() {
+			return createMetricBuilder({
+				...nextConfig,
+				default: { kind: "count" }
+			});
+		},
+		defaultAggregate(columnId, aggregate) {
+			return createMetricBuilder({
+				...nextConfig,
+				default: {
+					kind: "aggregate",
+					columnId,
+					aggregate
+				}
+			});
+		},
+		[METRIC_CONTROL_CONFIG]: nextConfig
+	};
+}
+function getSelectableControlConfig(builder) {
+	return builder[SELECTABLE_CONTROL_CONFIG];
+}
+function getMetricBuilderConfig(builder) {
+	return builder[METRIC_CONTROL_CONFIG];
+}
+//#endregion
+export { createMetricBuilder, createSelectableControlBuilder, getMetricBuilderConfig, getSelectableControlConfig };

package/dist/core/chart-capabilities.d.mts

@@ -58,6 +58,11 @@ declare const CHART_TYPE_CONFIG: {
     readonly supportsGrouping: false;
     readonly supportsTimeBucketing: false;
   };
+  readonly table: {
+    readonly supportedXAxisTypes: readonly ["date", "category", "boolean"];
+    readonly supportsGrouping: true;
+    readonly supportsTimeBucketing: true;
+  };
 };
 //#endregion
 export { CHART_TYPE_CONFIG, ChartAxisType, ChartTypeCapabilities };

package/dist/core/chart-capabilities.mjs

@@ -55,6 +55,15 @@ const CHART_TYPE_CONFIG = {
 		supportedXAxisTypes: ["category", "boolean"],
 		supportsGrouping: false,
 		supportsTimeBucketing: false
+	},
+	table: {
+		supportedXAxisTypes: [
+			"date",
+			"category",
+			"boolean"
+		],
+		supportsGrouping: true,
+		supportsTimeBucketing: true
 	}
 };
 /**

package/dist/core/config-utils.mjs

@@ -77,7 +77,8 @@ const CHART_TYPE_ORDER = [
 	"area",
 	"percent-area",
 	"pie",
-	"donut"
+	"donut",
+	"table"
 ];
 //#endregion
 export { CHART_TYPE_ORDER, TIME_BUCKET_ORDER, resolveConfiguredIdSelection, resolveConfiguredValue, restrictConfiguredIdOptions, restrictConfiguredValues };