@matthieumordrel/chart-studio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthieu Mordrel
+
+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

@@ -0,0 +1,371 @@
+# chart-studio
+
+Composable charting for React with two adoption paths:
+
+- 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
+
+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
+
+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`
+
+Install:
+
+```bash
+bun add @matthieumordrel/chart-studio react recharts lucide-react
+```
+
+Then import the package theme once in your app stylesheet:
+
+```css
+@import 'tailwindcss';
+@import '@matthieumordrel/chart-studio/ui/theme.css';
+```
+
+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 `defineChartSchema<Row>()()` with the control sections:
+
+```tsx
+import { defineChartSchema, useChart } from '@matthieumordrel/chart-studio'
+
+type Row = { periodEnd: string; segment: string; revenue: number; netIncome: number }
+
+const schema = defineChartSchema<Row>()({
+  columns: {
+    periodEnd: { type: 'date', label: 'Period End' },
+    segment: { type: 'category' },
+    revenue: { type: 'number' },
+    netIncome: { type: 'number' }
+  },
+  xAxis: { allowed: ['periodEnd'] },
+  groupBy: { allowed: ['segment'] },
+  metric: {
+    allowed: [
+      { kind: 'count' },
+      { kind: 'aggregate', columnId: 'revenue', aggregate: ['sum', 'avg'] },
+      { kind: 'aggregate', columnId: 'netIncome', aggregate: 'sum' }
+    ]
+  },
+  chartType: { allowed: ['bar', 'line'] },
+  timeBucket: { allowed: ['year', 'quarter', 'month'] }
+})
+
+const chart = useChart({ data, schema })
+```
+
+Why this pattern:
+
+- `columns` defines types, labels, and formats for raw fields; use `false` to exclude a column from the chart
+- Derived columns use `{ kind: 'derived', type, label?, accessor, format? }` for computed values from each row
+- `xAxis`, `groupBy`, `metric`, `chartType`, `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: {
+    dateAdded: { type: 'date', label: 'Date Added' },
+    ownerName: { type: 'category', label: 'Consultant' },
+    salary: { type: 'number', 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%;
+}
+```
+
+## Compatibility
+
+- `react`: `>=18.2.0 <20`
+- `recharts`: `>=2.15.4 <3` for the UI layer
+- `lucide-react`: `>=0.577.0 <1` for the UI layer
+
+## 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: { dateAdded: { type: 'date', 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';
+```
+
+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.
+
+## Release
+
+- `bun run release:check`
+- `bun run release:publish -- --tag=latest`
+- `npm publish` runs `prepublishOnly`, which calls `bun run release:check`

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

@@ -0,0 +1,60 @@
+import type { ChartType } from './types.js';
+/**
+ * X-axis kinds understood by chart-studio when validating chart types.
+ */
+export type ChartAxisType = 'date' | 'category' | 'boolean';
+/**
+ * Declarative chart-type capability matrix.
+ *
+ * Centralizing these rules keeps UI controls and state validation aligned as
+ * more chart types are added later.
+ */
+export type ChartTypeCapabilities = {
+    supportedXAxisTypes: readonly ChartAxisType[];
+    supportsGrouping: boolean;
+    supportsTimeBucketing: boolean;
+};
+/**
+ * Capabilities for each supported chart type.
+ */
+export declare const CHART_TYPE_CONFIG: {
+    readonly bar: {
+        readonly supportedXAxisTypes: readonly ["date", "category", "boolean"];
+        readonly supportsGrouping: true;
+        readonly supportsTimeBucketing: true;
+    };
+    readonly line: {
+        readonly supportedXAxisTypes: readonly ["date"];
+        readonly supportsGrouping: true;
+        readonly supportsTimeBucketing: true;
+    };
+    readonly area: {
+        readonly supportedXAxisTypes: readonly ["date"];
+        readonly supportsGrouping: true;
+        readonly supportsTimeBucketing: true;
+    };
+    readonly pie: {
+        readonly supportedXAxisTypes: readonly ["category", "boolean"];
+        readonly supportsGrouping: false;
+        readonly supportsTimeBucketing: false;
+    };
+    readonly donut: {
+        readonly supportedXAxisTypes: readonly ["category", "boolean"];
+        readonly supportsGrouping: false;
+        readonly supportsTimeBucketing: false;
+    };
+};
+type ChartTypeAvailability = {
+    hasGroupBy: boolean;
+    xAxisType: ChartAxisType | null;
+};
+/**
+ * Whether a chart type can represent the current chart state.
+ */
+export declare function isChartTypeAvailable(chartType: ChartType, availability: ChartTypeAvailability): boolean;
+/**
+ * Chart types valid for the current axis + feature combination.
+ */
+export declare function getAvailableChartTypes(availability: ChartTypeAvailability): ChartType[];
+export {};
+//# sourceMappingURL=chart-capabilities.d.ts.map

package/dist/core/chart-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-capabilities.d.ts","sourceRoot":"","sources":["../../src/core/chart-capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAA;AAGzC;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,mBAAmB,EAAE,SAAS,aAAa,EAAE,CAAA;IAC7C,gBAAgB,EAAE,OAAO,CAAA;IACzB,qBAAqB,EAAE,OAAO,CAAA;CAC/B,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B+B,CAAA;AAE7D,KAAK,qBAAqB,GAAG;IAC3B,UAAU,EAAE,OAAO,CAAA;IACnB,SAAS,EAAE,aAAa,GAAG,IAAI,CAAA;CAChC,CAAA;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAeT;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,qBAAqB,GAAG,SAAS,EAAE,CAEvF"}

package/dist/core/chart-capabilities.js

@@ -0,0 +1,55 @@
+import { CHART_TYPE_ORDER } from './config-utils.js';
+/**
+ * Capabilities for each supported chart type.
+ */
+export const CHART_TYPE_CONFIG = {
+    bar: {
+        supportedXAxisTypes: ['date', 'category', 'boolean'],
+        supportsGrouping: true,
+        supportsTimeBucketing: true,
+    },
+    line: {
+        supportedXAxisTypes: ['date'],
+        supportsGrouping: true,
+        supportsTimeBucketing: true,
+    },
+    area: {
+        supportedXAxisTypes: ['date'],
+        supportsGrouping: true,
+        supportsTimeBucketing: true,
+    },
+    pie: {
+        supportedXAxisTypes: ['category', 'boolean'],
+        supportsGrouping: false,
+        supportsTimeBucketing: false,
+    },
+    donut: {
+        supportedXAxisTypes: ['category', 'boolean'],
+        supportsGrouping: false,
+        supportsTimeBucketing: false,
+    },
+};
+/**
+ * Whether a chart type can represent the current chart state.
+ */
+export function isChartTypeAvailable(chartType, availability) {
+    const { hasGroupBy, xAxisType } = availability;
+    if (xAxisType === null)
+        return false;
+    const capabilities = CHART_TYPE_CONFIG[chartType];
+    const supportedXAxisTypes = capabilities.supportedXAxisTypes;
+    if (!supportedXAxisTypes.includes(xAxisType)) {
+        return false;
+    }
+    if (hasGroupBy && !capabilities.supportsGrouping) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Chart types valid for the current axis + feature combination.
+ */
+export function getAvailableChartTypes(availability) {
+    return CHART_TYPE_ORDER.filter((chartType) => isChartTypeAvailable(chartType, availability));
+}
+//# sourceMappingURL=chart-capabilities.js.map

package/dist/core/chart-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-capabilities.js","sourceRoot":"","sources":["../../src/core/chart-capabilities.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,gBAAgB,EAAC,MAAM,mBAAmB,CAAA;AAmBlD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,GAAG,EAAE;QACH,mBAAmB,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC;QACpD,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,IAAI;KAC5B;IACD,IAAI,EAAE;QACJ,mBAAmB,EAAE,CAAC,MAAM,CAAC;QAC7B,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,IAAI;KAC5B;IACD,IAAI,EAAE;QACJ,mBAAmB,EAAE,CAAC,MAAM,CAAC;QAC7B,gBAAgB,EAAE,IAAI;QACtB,qBAAqB,EAAE,IAAI;KAC5B;IACD,GAAG,EAAE;QACH,mBAAmB,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;QAC5C,gBAAgB,EAAE,KAAK;QACvB,qBAAqB,EAAE,KAAK;KAC7B;IACD,KAAK,EAAE;QACL,mBAAmB,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;QAC5C,gBAAgB,EAAE,KAAK;QACvB,qBAAqB,EAAE,KAAK;KAC7B;CAC0D,CAAA;AAO7D;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAoB,EACpB,YAAmC;IAEnC,MAAM,EAAC,UAAU,EAAE,SAAS,EAAC,GAAG,YAAY,CAAA;IAC5C,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAEpC,MAAM,YAAY,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAA;IACjD,MAAM,mBAAmB,GAA6B,YAAY,CAAC,mBAAmB,CAAA;IACtF,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,UAAU,IAAI,CAAC,YAAY,CAAC,gBAAgB,EAAE,CAAC;QACjD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,YAAmC;IACxE,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,oBAAoB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAA;AAC9F,CAAC"}

package/dist/core/colors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Color assignment for chart series.
+ *
+ * Uses shadcn chart CSS variables (`--chart-1` through `--chart-5`) by default.
+ * Falls back to a built-in OKLCH palette when CSS variables are not available.
+ */
+/**
+ * Get a color for the Nth series.
+ * Cycles through the palette when index exceeds palette length.
+ *
+ * @param index - Zero-based series index
+ * @param useShadcn - Whether to use shadcn CSS variables (default: true)
+ * @returns CSS color value
+ */
+export declare function getSeriesColor(index: number, useShadcn?: boolean): string;
+/**
+ * Generate a color map for a list of group labels.
+ * Assigns colors deterministically based on array order.
+ *
+ * @param groups - Array of group labels
+ * @param useShadcn - Whether to use shadcn CSS variables (default: true)
+ * @returns Map from group label to CSS color
+ */
+export declare function buildColorMap(groups: string[], useShadcn?: boolean): Map<string, string>;
+//# sourceMappingURL=colors.d.ts.map

package/dist/core/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/core/colors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyBH;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,UAAO,GAAG,MAAM,CAGtE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,UAAO,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrF"}

package/dist/core/colors.js

@@ -0,0 +1,55 @@
+/**
+ * Color assignment for chart series.
+ *
+ * Uses shadcn chart CSS variables (`--chart-1` through `--chart-5`) by default.
+ * Falls back to a built-in OKLCH palette when CSS variables are not available.
+ */
+/** Fallback palette using OKLCH for perceptually uniform colors. */
+const FALLBACK_COLORS = [
+    'oklch(0.65 0.15 250)', // blue
+    'oklch(0.65 0.15 350)', // rose
+    'oklch(0.65 0.15 200)', // cyan
+    'oklch(0.65 0.15 70)', // amber
+    'oklch(0.65 0.15 150)', // teal
+    'oklch(0.65 0.15 30)', // orange
+    'oklch(0.65 0.15 300)', // purple
+    'oklch(0.65 0.15 120)', // green
+    'oklch(0.65 0.12 170)', // mint
+    'oklch(0.65 0.12 220)', // slate blue
+];
+/** Shadcn chart CSS variables (5 colors) with safe fallbacks. */
+const SHADCN_CHART_COLORS = [
+    `hsl(var(--chart-1, var(--cs-chart-1, 245 72% 57%)))`,
+    `hsl(var(--chart-2, var(--cs-chart-2, 271 72% 55%)))`,
+    `hsl(var(--chart-3, var(--cs-chart-3, 330 68% 54%)))`,
+    `hsl(var(--chart-4, var(--cs-chart-4, 170 65% 38%)))`,
+    `hsl(var(--chart-5, var(--cs-chart-5, 30 90% 54%)))`,
+];
+/**
+ * Get a color for the Nth series.
+ * Cycles through the palette when index exceeds palette length.
+ *
+ * @param index - Zero-based series index
+ * @param useShadcn - Whether to use shadcn CSS variables (default: true)
+ * @returns CSS color value
+ */
+export function getSeriesColor(index, useShadcn = true) {
+    const palette = useShadcn ? SHADCN_CHART_COLORS : FALLBACK_COLORS;
+    return palette[index % palette.length];
+}
+/**
+ * Generate a color map for a list of group labels.
+ * Assigns colors deterministically based on array order.
+ *
+ * @param groups - Array of group labels
+ * @param useShadcn - Whether to use shadcn CSS variables (default: true)
+ * @returns Map from group label to CSS color
+ */
+export function buildColorMap(groups, useShadcn = true) {
+    const map = new Map();
+    for (let i = 0; i < groups.length; i++) {
+        map.set(groups[i], getSeriesColor(i, useShadcn));
+    }
+    return map;
+}
+//# sourceMappingURL=colors.js.map

package/dist/core/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../../src/core/colors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oEAAoE;AACpE,MAAM,eAAe,GAAG;IACtB,sBAAsB,EAAE,OAAO;IAC/B,sBAAsB,EAAE,OAAO;IAC/B,sBAAsB,EAAE,OAAO;IAC/B,qBAAqB,EAAE,QAAQ;IAC/B,sBAAsB,EAAE,OAAO;IAC/B,qBAAqB,EAAE,SAAS;IAChC,sBAAsB,EAAE,SAAS;IACjC,sBAAsB,EAAE,QAAQ;IAChC,sBAAsB,EAAE,OAAO;IAC/B,sBAAsB,EAAE,aAAa;CAC7B,CAAA;AAEV,iEAAiE;AACjE,MAAM,mBAAmB,GAAG;IAC1B,qDAAqD;IACrD,qDAAqD;IACrD,qDAAqD;IACrD,qDAAqD;IACrD,oDAAoD;CAC5C,CAAA;AAEV;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,SAAS,GAAG,IAAI;IAC5D,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,eAAe,CAAA;IACjE,OAAO,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAE,CAAA;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAgB,EAAE,SAAS,GAAG,IAAI;IAC9D,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAA;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAE,EAAE,cAAc,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/core/config-utils.d.ts

@@ -0,0 +1,43 @@
+import type { ChartType, TimeBucket } from './types.js';
+type IdOption<TId extends string> = {
+    id: TId;
+};
+type IdControlConfig<TId extends string> = {
+    allowed?: readonly TId[];
+    hidden?: readonly TId[];
+    default?: TId;
+};
+type ValueControlConfig<TValue extends string> = {
+    allowed?: readonly TValue[];
+    hidden?: readonly TValue[];
+    default?: TValue;
+};
+/**
+ * Restrict an ID-keyed option list with `allowed`/`hidden`.
+ *
+ * When `fallbackToBaseIfEmpty` is enabled, required controls keep their base
+ * runtime options even if the config does not match the active source.
+ */
+export declare function restrictConfiguredIdOptions<TId extends string, TOption extends IdOption<TId>>(options: readonly TOption[], config: IdControlConfig<TId> | undefined, fallbackToBaseIfEmpty?: boolean): TOption[];
+/**
+ * Resolve one ID-based selection against the current option list.
+ */
+export declare function resolveConfiguredIdSelection<TId extends string>(currentValue: TId | null, options: readonly IdOption<TId>[], configuredDefault: TId | undefined, fallbackValue: TId | null, preferFirstAvailable?: boolean): TId | null;
+/**
+ * Restrict a primitive option list with `allowed`/`hidden`.
+ */
+export declare function restrictConfiguredValues<TValue extends string>(values: readonly TValue[], config: ValueControlConfig<TValue> | undefined, fallbackToBaseIfEmpty?: boolean): TValue[];
+/**
+ * Resolve one primitive selection against the current option list.
+ */
+export declare function resolveConfiguredValue<TValue extends string>(currentValue: TValue, values: readonly TValue[], configuredDefault: TValue | undefined): TValue;
+/**
+ * Ordered time buckets exposed by the headless API.
+ */
+export declare const TIME_BUCKET_ORDER: readonly TimeBucket[];
+/**
+ * Ordered chart types exposed by the headless API.
+ */
+export declare const CHART_TYPE_ORDER: readonly ChartType[];
+export {};
+//# sourceMappingURL=config-utils.d.ts.map

package/dist/core/config-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-utils.d.ts","sourceRoot":"","sources":["../../src/core/config-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACX,MAAM,YAAY,CAAA;AAEnB,KAAK,QAAQ,CAAC,GAAG,SAAS,MAAM,IAAI;IAClC,EAAE,EAAE,GAAG,CAAA;CACR,CAAA;AAED,KAAK,eAAe,CAAC,GAAG,SAAS,MAAM,IAAI;IACzC,OAAO,CAAC,EAAE,SAAS,GAAG,EAAE,CAAA;IACxB,MAAM,CAAC,EAAE,SAAS,GAAG,EAAE,CAAA;IACvB,OAAO,CAAC,EAAE,GAAG,CAAA;CACd,CAAA;AAED,KAAK,kBAAkB,CAAC,MAAM,SAAS,MAAM,IAAI;IAC/C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AA+CD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,SAAS,MAAM,EAAE,OAAO,SAAS,QAAQ,CAAC,GAAG,CAAC,EAC3F,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,SAAS,EACxC,qBAAqB,UAAQ,GAC5B,OAAO,EAAE,CAEX;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,SAAS,MAAM,EAC7D,YAAY,EAAE,GAAG,GAAG,IAAI,EACxB,OAAO,EAAE,SAAS,QAAQ,CAAC,GAAG,CAAC,EAAE,EACjC,iBAAiB,EAAE,GAAG,GAAG,SAAS,EAClC,aAAa,EAAE,GAAG,GAAG,IAAI,EACzB,oBAAoB,UAAO,GAC1B,GAAG,GAAG,IAAI,CAcZ;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,SAAS,MAAM,EAC5D,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,SAAS,EAC9C,qBAAqB,UAAQ,GAC5B,MAAM,EAAE,CAEV;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,SAAS,MAAM,EAC1D,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,iBAAiB,EAAE,MAAM,GAAG,SAAS,GACpC,MAAM,CAUR;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,UAAU,EAAgD,CAAA;AAEnG;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,SAAS,EAA4C,CAAA"}