@matthieumordrel/chart-studio 0.2.1 → 0.2.3

package/README.md

@@ -364,6 +364,30 @@ If you are importing the package source directly in a local playground or monore
 
 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.
+
+### The double-call schema syntax
+
+`defineChartSchema<Row>()()` uses a double function call as a workaround for TypeScript's lack of partial type argument inference. This lets you provide the row type explicitly while the column IDs are inferred automatically. It works well but can surprise newcomers — this will be revisited if TypeScript adds native support for partial inference.
+
 ## Release
 
 - `bun run release:check`

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

@@ -0,0 +1,48 @@
+//#region src/core/chart-capabilities.d.ts
+/**
+ * X-axis kinds understood by chart-studio when validating chart types.
+ */
+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.
+ */
+type ChartTypeCapabilities = {
+  supportedXAxisTypes: readonly ChartAxisType[];
+  supportsGrouping: boolean;
+  supportsTimeBucketing: boolean;
+};
+/**
+ * Capabilities for each supported chart type.
+ */
+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;
+  };
+};
+//#endregion
+export { CHART_TYPE_CONFIG, ChartAxisType, ChartTypeCapabilities };

package/dist/core/chart-capabilities.mjs

@@ -0,0 +1,55 @@
+import { CHART_TYPE_ORDER } from "./config-utils.mjs";
+//#region src/core/chart-capabilities.ts
+/**
+* Capabilities for each supported chart type.
+*/
+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.
+*/
+function isChartTypeAvailable(chartType, availability) {
+	const { hasGroupBy, xAxisType } = availability;
+	if (xAxisType === null) return false;
+	const capabilities = CHART_TYPE_CONFIG[chartType];
+	if (!capabilities.supportedXAxisTypes.includes(xAxisType)) return false;
+	if (hasGroupBy && !capabilities.supportsGrouping) return false;
+	return true;
+}
+/**
+* Chart types valid for the current axis + feature combination.
+*/
+function getAvailableChartTypes(availability) {
+	return CHART_TYPE_ORDER.filter((chartType) => isChartTypeAvailable(chartType, availability));
+}
+//#endregion
+export { CHART_TYPE_CONFIG, getAvailableChartTypes };

package/dist/core/{colors.d.ts → colors.d.mts}

@@ -1,3 +1,4 @@
+//#region src/core/colors.d.ts
 /**
  * Color assignment for chart series.
  *
@@ -12,7 +13,7 @@
  * @param useShadcn - Whether to use shadcn CSS variables (default: true)
  * @returns CSS color value
  */
-export declare function getSeriesColor(index: number, useShadcn?: boolean): string;
+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.
@@ -21,5 +22,6 @@ export declare function getSeriesColor(index: number, useShadcn?: boolean): stri
  * @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
+declare function buildColorMap(groups: string[], useShadcn?: boolean): Map<string, string>;
+//#endregion
+export { buildColorMap, getSeriesColor };

package/dist/core/colors.mjs

@@ -0,0 +1,55 @@
+//#region src/core/colors.ts
+/**
+* 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)",
+	"oklch(0.65 0.15 350)",
+	"oklch(0.65 0.15 200)",
+	"oklch(0.65 0.15 70)",
+	"oklch(0.65 0.15 150)",
+	"oklch(0.65 0.15 30)",
+	"oklch(0.65 0.15 300)",
+	"oklch(0.65 0.15 120)",
+	"oklch(0.65 0.12 170)",
+	"oklch(0.65 0.12 220)"
+];
+/** Shadcn chart CSS variables (5 colors) with safe fallbacks. */
+const SHADCN_CHART_COLORS = [
+	`var(--chart-1, var(--cs-chart-1, hsl(245 72% 57%)))`,
+	`var(--chart-2, var(--cs-chart-2, hsl(271 72% 55%)))`,
+	`var(--chart-3, var(--cs-chart-3, hsl(330 68% 54%)))`,
+	`var(--chart-4, var(--cs-chart-4, hsl(170 65% 38%)))`,
+	`var(--chart-5, var(--cs-chart-5, hsl(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
+*/
+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
+*/
+function buildColorMap(groups, useShadcn = true) {
+	const map = /* @__PURE__ */ new Map();
+	for (let i = 0; i < groups.length; i++) map.set(groups[i], getSeriesColor(i, useShadcn));
+	return map;
+}
+//#endregion
+export { buildColorMap, getSeriesColor };

package/dist/core/config-utils.mjs

@@ -0,0 +1,79 @@
+//#region src/core/config-utils.ts
+/**
+* Build the visible runtime option list after applying config restrictions.
+*
+* The pipeline is always:
+* 1. start from runtime-valid options
+* 2. if `allowed` exists, keep only allowed entries in declared order
+* 3. if `hidden` exists, subtract hidden entries
+*
+* When `fallbackToBaseIfEmpty` is enabled, required controls can recover their
+* base runtime options if the config leaves nothing selectable for the active
+* source. This recovery is intentionally separate from default resolution.
+*/
+function restrictConfiguredCollection(items, config, getKey, fallbackToBaseIfEmpty) {
+	const keyedItems = new Map(items.map((item) => [getKey(item), item]));
+	const allowedKeys = config?.allowed;
+	const hiddenKeys = config?.hidden ? new Set(config.hidden) : void 0;
+	const orderedItems = allowedKeys ? allowedKeys.flatMap((allowedKey) => {
+		const match = keyedItems.get(allowedKey);
+		return match ? [match] : [];
+	}) : [...items];
+	const visibleItems = hiddenKeys ? orderedItems.filter((item) => !hiddenKeys.has(getKey(item))) : orderedItems;
+	if (fallbackToBaseIfEmpty && visibleItems.length === 0) return [...items];
+	return visibleItems;
+}
+/**
+* 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.
+*/
+function restrictConfiguredIdOptions(options, config, fallbackToBaseIfEmpty = false) {
+	return restrictConfiguredCollection(options, config, (option) => option.id, fallbackToBaseIfEmpty);
+}
+/**
+* Resolve one ID-based selection against the current option list.
+*/
+function resolveConfiguredIdSelection(currentValue, options, configuredDefault, fallbackValue, preferFirstAvailable = true) {
+	if (currentValue && options.some((option) => option.id === currentValue)) return currentValue;
+	if (configuredDefault && options.some((option) => option.id === configuredDefault)) return configuredDefault;
+	if (preferFirstAvailable) return options[0]?.id ?? fallbackValue;
+	return fallbackValue;
+}
+/**
+* Restrict a primitive option list with `allowed`/`hidden`.
+*/
+function restrictConfiguredValues(values, config, fallbackToBaseIfEmpty = false) {
+	return restrictConfiguredCollection(values, config, (value) => value, fallbackToBaseIfEmpty);
+}
+/**
+* Resolve one primitive selection against the current option list.
+*/
+function resolveConfiguredValue(currentValue, values, configuredDefault) {
+	if (values.includes(currentValue)) return currentValue;
+	if (configuredDefault && values.includes(configuredDefault)) return configuredDefault;
+	return values[0] ?? currentValue;
+}
+/**
+* Ordered time buckets exposed by the headless API.
+*/
+const TIME_BUCKET_ORDER = [
+	"day",
+	"week",
+	"month",
+	"quarter",
+	"year"
+];
+/**
+* Ordered chart types exposed by the headless API.
+*/
+const CHART_TYPE_ORDER = [
+	"bar",
+	"line",
+	"area",
+	"pie",
+	"donut"
+];
+//#endregion
+export { CHART_TYPE_ORDER, TIME_BUCKET_ORDER, resolveConfiguredIdSelection, resolveConfiguredValue, restrictConfiguredIdOptions, restrictConfiguredValues };

package/dist/core/date-utils.mjs

@@ -0,0 +1,49 @@
+//#region src/core/date-utils.ts
+/**
+* Filter data by a date range on a specific date column.
+* Both bounds are inclusive (to is extended to end of day).
+*
+* @param data - Raw data items
+* @param dateColumn - The date column to filter on
+* @param filter - Date range filter with from/to bounds
+* @returns Filtered data items within the date range
+*/
+function filterByDateRange(data, dateColumn, filter) {
+	const { from, to } = filter;
+	if (!from && !to) return [...data];
+	const toEnd = to ? new Date(to.getFullYear(), to.getMonth(), to.getDate(), 23, 59, 59, 999) : null;
+	return data.filter((item) => {
+		const raw = dateColumn.accessor(item);
+		if (raw == null) return false;
+		const d = new Date(raw);
+		if (Number.isNaN(d.getTime())) return false;
+		if (from && d < from) return false;
+		if (toEnd && d > toEnd) return false;
+		return true;
+	});
+}
+/**
+* Compute the min/max date range from data for a given date column.
+*
+* @param data - Data items to scan
+* @param dateColumn - The date column to extract dates from
+* @returns Object with min and max dates (both null if no valid dates)
+*/
+function computeDateRange(data, dateColumn) {
+	let min = null;
+	let max = null;
+	for (const item of data) {
+		const raw = dateColumn.accessor(item);
+		if (raw == null) continue;
+		const d = new Date(raw);
+		if (Number.isNaN(d.getTime())) continue;
+		if (!min || d < min) min = d;
+		if (!max || d > max) max = d;
+	}
+	return {
+		min,
+		max
+	};
+}
+//#endregion
+export { computeDateRange, filterByDateRange };

package/dist/core/define-chart-schema.d.mts

@@ -0,0 +1,106 @@
+import { ChartTypeConfig, DefinedChartSchema, ExactShape, FiltersConfig, GroupByConfig, MetricConfig, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, SchemaColumnsValidationShape, TimeBucketConfig, XAxisConfig } from "./types.mjs";
+
+//#region src/core/define-chart-schema.d.ts
+type SchemaFromSections<T, TColumns extends Record<string, unknown> | undefined, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket> = {
+  columns?: Extract<TColumns, Record<string, unknown> | undefined>;
+  xAxis?: Extract<TXAxis, XAxisConfig<ResolvedXAxisColumnIdFromSchema<T, {
+    columns?: TColumns;
+  }>> | undefined>;
+  groupBy?: Extract<TGroupBy, GroupByConfig<ResolvedGroupByColumnIdFromSchema<T, {
+    columns?: TColumns;
+  }>> | undefined>;
+  filters?: Extract<TFilters, FiltersConfig<ResolvedFilterColumnIdFromSchema<T, {
+    columns?: TColumns;
+  }>> | undefined>;
+  metric?: Extract<TMetric, MetricConfig<ResolvedMetricColumnIdFromSchema<T, {
+    columns?: TColumns;
+  }>> | undefined>;
+  chartType?: Extract<TChartType, ChartTypeConfig | undefined>;
+  timeBucket?: Extract<TTimeBucket, TimeBucketConfig | undefined>;
+};
+type DefineChartSchemaInput<T, TColumns extends Record<string, unknown> | undefined, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket> = {
+  /**
+   * Shape the available chart columns.
+   *
+   * This is usually the most important part of the schema. Use it to:
+   * - rename inferred raw fields with `label`
+   * - force a field to a specific `type`
+   * - apply `format` or `formatter`
+   * - remove a raw field with `false`
+   * - add brand new derived columns with `kind: 'derived'`
+   */
+  columns?: TColumns & ExactShape<SchemaColumnsValidationShape<T, NoInfer<TColumns>>, NoInfer<TColumns>>;
+  /**
+   * Restrict which resolved columns may be selected on the X-axis.
+   *
+   * Use this when you want to expose only a subset of possible X-axis fields.
+   */
+  xAxis?: TXAxis & ExactShape<XAxisConfig<ResolvedXAxisColumnIdFromSchema<T, {
+    columns?: TColumns;
+  }>>, NoInfer<TXAxis>>;
+  /**
+   * Restrict which resolved columns may be used to split the chart into series.
+   *
+   * This powers grouped / multi-series charts.
+   */
+  groupBy?: TGroupBy & ExactShape<GroupByConfig<ResolvedGroupByColumnIdFromSchema<T, {
+    columns?: TColumns;
+  }>>, NoInfer<TGroupBy>>;
+  /**
+   * Restrict which resolved columns appear in the filters UI.
+   *
+   * Only category and boolean-like columns are eligible here.
+   */
+  filters?: TFilters & ExactShape<FiltersConfig<ResolvedFilterColumnIdFromSchema<T, {
+    columns?: TColumns;
+  }>>, NoInfer<TFilters>>;
+  /**
+   * Restrict which metrics and aggregate combinations remain selectable.
+   *
+   * Use this when you want to curate the metric dropdown rather than exposing
+   * every available numeric aggregate.
+   */
+  metric?: TMetric & ExactShape<MetricConfig<ResolvedMetricColumnIdFromSchema<T, {
+    columns?: TColumns;
+  }>>, NoInfer<TMetric>>; /** Restrict which chart renderers are available to the user. */
+  chartType?: TChartType & ExactShape<ChartTypeConfig, NoInfer<TChartType>>;
+  /**
+   * Restrict which time buckets remain available for date X-axes.
+   *
+   * Example: allow only `'month'` and `'quarter'`.
+   */
+  timeBucket?: TTimeBucket & ExactShape<TimeBucketConfig, NoInfer<TTimeBucket>>;
+};
+/**
+ * Define one explicit chart schema with strict exact-object checking.
+ *
+ * The schema is the single advanced authoring surface for chart-studio:
+ * `columns` can override or exclude inferred raw fields and also define derived
+ * columns, while the top-level control sections restrict the public chart
+ * contract.
+ *
+ * Typical shape:
+ *
+ * ```ts
+ * const schema = defineChartSchema<Row>()({
+ *   columns: {
+ *     createdAt: {type: 'date', label: 'Created'},
+ *     revenue: {type: 'number', format: 'currency'},
+ *     margin: {
+ *       kind: 'derived',
+ *       type: 'number',
+ *       label: 'Margin',
+ *       format: 'percent',
+ *       accessor: row => row.profit / row.revenue,
+ *     },
+ *   },
+ *   xAxis: {allowed: ['createdAt']},
+ *   metric: {
+ *     allowed: [{kind: 'aggregate', columnId: 'revenue', aggregate: 'sum'}],
+ *   },
+ * })
+ * ```
+ */
+declare function defineChartSchema<T>(): <const TColumns extends Record<string, unknown> | undefined = undefined, const TXAxis = undefined, const TGroupBy = undefined, const TFilters = undefined, const TMetric = undefined, const TChartType = undefined, const TTimeBucket = undefined>(schema: DefineChartSchemaInput<T, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket>) => DefinedChartSchema<T, SchemaFromSections<T, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket>>;
+//#endregion
+export { defineChartSchema };

package/dist/core/define-chart-schema.mjs

@@ -0,0 +1,47 @@
+//#region src/core/define-chart-schema.ts
+/**
+* Define one explicit chart schema with strict exact-object checking.
+*
+* The schema is the single advanced authoring surface for chart-studio:
+* `columns` can override or exclude inferred raw fields and also define derived
+* columns, while the top-level control sections restrict the public chart
+* contract.
+*
+* Typical shape:
+*
+* ```ts
+* const schema = defineChartSchema<Row>()({
+*   columns: {
+*     createdAt: {type: 'date', label: 'Created'},
+*     revenue: {type: 'number', format: 'currency'},
+*     margin: {
+*       kind: 'derived',
+*       type: 'number',
+*       label: 'Margin',
+*       format: 'percent',
+*       accessor: row => row.profit / row.revenue,
+*     },
+*   },
+*   xAxis: {allowed: ['createdAt']},
+*   metric: {
+*     allowed: [{kind: 'aggregate', columnId: 'revenue', aggregate: 'sum'}],
+*   },
+* })
+* ```
+*/
+function defineChartSchema() {
+	/**
+	* Brand one schema object while preserving its literal types.
+	*
+	* This is what lets the schema stay both strongly typed and editor-friendly
+	* when it is later passed to `useChart(...)`.
+	*/
+	return function defineSchema(schema) {
+		return {
+			...schema,
+			__chartSchemaBrand: "chart-schema-definition"
+		};
+	};
+}
+//#endregion
+export { defineChartSchema };