@matthieumordrel/chart-studio 0.2.2 → 0.2.4

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

@@ -23,6 +23,16 @@ declare const CHART_TYPE_CONFIG: {
     readonly supportsGrouping: true;
     readonly supportsTimeBucketing: true;
   };
+  readonly 'grouped-bar': {
+    readonly supportedXAxisTypes: readonly ["date", "category", "boolean"];
+    readonly supportsGrouping: true;
+    readonly supportsTimeBucketing: true;
+  };
+  readonly 'percent-bar': {
+    readonly supportedXAxisTypes: readonly ["date", "category", "boolean"];
+    readonly supportsGrouping: true;
+    readonly supportsTimeBucketing: true;
+  };
   readonly line: {
     readonly supportedXAxisTypes: readonly ["date"];
     readonly supportsGrouping: true;
@@ -33,6 +43,11 @@ declare const CHART_TYPE_CONFIG: {
     readonly supportsGrouping: true;
     readonly supportsTimeBucketing: true;
   };
+  readonly 'percent-area': {
+    readonly supportedXAxisTypes: readonly ["date"];
+    readonly supportsGrouping: true;
+    readonly supportsTimeBucketing: true;
+  };
   readonly pie: {
     readonly supportedXAxisTypes: readonly ["category", "boolean"];
     readonly supportsGrouping: false;

package/dist/core/chart-capabilities.mjs

@@ -13,6 +13,24 @@ const CHART_TYPE_CONFIG = {
 		supportsGrouping: true,
 		supportsTimeBucketing: true
 	},
+	"grouped-bar": {
+		supportedXAxisTypes: [
+			"date",
+			"category",
+			"boolean"
+		],
+		supportsGrouping: true,
+		supportsTimeBucketing: true
+	},
+	"percent-bar": {
+		supportedXAxisTypes: [
+			"date",
+			"category",
+			"boolean"
+		],
+		supportsGrouping: true,
+		supportsTimeBucketing: true
+	},
 	line: {
 		supportedXAxisTypes: ["date"],
 		supportsGrouping: true,
@@ -23,6 +41,11 @@ const CHART_TYPE_CONFIG = {
 		supportsGrouping: true,
 		supportsTimeBucketing: true
 	},
+	"percent-area": {
+		supportedXAxisTypes: ["date"],
+		supportsGrouping: true,
+		supportsTimeBucketing: true
+	},
 	pie: {
 		supportedXAxisTypes: ["category", "boolean"],
 		supportsGrouping: false,

package/dist/core/colors.mjs

@@ -20,11 +20,11 @@ const FALLBACK_COLORS = [
 ];
 /** 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%)))`
+	`var(--chart-1, var(--cs-chart-1, oklch(0.501 0.228 277.992)))`,
+	`var(--chart-2, var(--cs-chart-2, oklch(0.550 0.235 302.715)))`,
+	`var(--chart-3, var(--cs-chart-3, oklch(0.609 0.206 354.673)))`,
+	`var(--chart-4, var(--cs-chart-4, oklch(0.635 0.109 178.228)))`,
+	`var(--chart-5, var(--cs-chart-5, oklch(0.732 0.166 58.213)))`
 ];
 /**
 * Get a color for the Nth series.

package/dist/core/config-utils.mjs

@@ -70,8 +70,11 @@ const TIME_BUCKET_ORDER = [
 */
 const CHART_TYPE_ORDER = [
 	"bar",
+	"grouped-bar",
+	"percent-bar",
 	"line",
 	"area",
+	"percent-area",
 	"pie",
 	"donut"
 ];

package/dist/core/date-range-presets.d.mts

@@ -0,0 +1,12 @@
+//#region src/core/date-range-presets.d.ts
+/**
+ * All recognised date range preset identifiers.
+ *
+ * - `'auto'`          — derived from the active time bucket
+ * - `'all-time'`      — no date filtering
+ * - Relative presets   — rolling window from "now"
+ * - Calendar presets   — aligned to calendar boundaries
+ */
+type DateRangePresetId = 'auto' | 'all-time' | 'last-7-days' | 'last-30-days' | 'last-3-months' | 'last-12-months' | 'quarter-to-date' | 'year-to-date' | 'last-year';
+//#endregion
+export { DateRangePresetId };

package/dist/core/date-range-presets.mjs

@@ -0,0 +1,152 @@
+//#region src/core/date-range-presets.ts
+/**
+* Ordered list of all date range presets shown in the UI.
+*
+* Layout hint (2-column grid):
+*   Auto          | All time
+*   Last 7 days   | Last 30 days
+*   Last 3 months | Last 12 months
+*   Quarter to date | Year to date
+*   Last year     |
+*/
+const DATE_RANGE_PRESETS = [
+	{
+		id: "auto",
+		label: "Auto",
+		description: "Adjusts the date range based on the time bucket: day → last 30 days, week → last 3 months, month → last 12 months, quarter/year → all time",
+		buildFilter: () => null
+	},
+	{
+		id: "all-time",
+		label: "All time",
+		buildFilter: () => null
+	},
+	{
+		id: "last-7-days",
+		label: "Last 7 days",
+		buildFilter: () => ({
+			from: daysAgo(7),
+			to: null
+		})
+	},
+	{
+		id: "last-30-days",
+		label: "Last 30 days",
+		buildFilter: () => ({
+			from: daysAgo(30),
+			to: null
+		})
+	},
+	{
+		id: "last-3-months",
+		label: "Last 3 months",
+		buildFilter: () => ({
+			from: monthsAgo(3),
+			to: null
+		})
+	},
+	{
+		id: "last-12-months",
+		label: "Last 12 months",
+		buildFilter: () => ({
+			from: monthsAgo(12),
+			to: null
+		})
+	},
+	{
+		id: "quarter-to-date",
+		label: "Quarter to date",
+		buildFilter: () => ({
+			from: startOfQuarter(),
+			to: null
+		})
+	},
+	{
+		id: "year-to-date",
+		label: "Year to date",
+		buildFilter: () => ({
+			from: startOfYear(),
+			to: null
+		})
+	},
+	{
+		id: "last-year",
+		label: "Last year",
+		buildFilter: () => lastYear()
+	}
+];
+/**
+* Map a time bucket to a sensible default date range.
+*
+* - `day`     → last 30 days (enough for a meaningful daily trend)
+* - `week`    → last 3 months (~13 weeks)
+* - `month`   → last 12 months
+* - `quarter` → all time (null)
+* - `year`    → all time (null)
+*/
+function autoFilterForBucket(bucket) {
+	switch (bucket) {
+		case "day": return {
+			from: daysAgo(30),
+			to: null
+		};
+		case "week": return {
+			from: monthsAgo(3),
+			to: null
+		};
+		case "month": return {
+			from: monthsAgo(12),
+			to: null
+		};
+		case "quarter":
+		case "year": return null;
+	}
+}
+/**
+* Compute the effective `DateRangeFilter` for a given preset.
+*
+* For `'auto'`, this uses the provided `timeBucket` to derive the range.
+* For all other presets, the filter is computed from the preset definition.
+*
+* @returns The resolved filter, or `null` for "all time".
+*/
+function resolvePresetFilter(presetId, timeBucket) {
+	if (presetId === "auto") return autoFilterForBucket(timeBucket);
+	return DATE_RANGE_PRESETS.find((p) => p.id === presetId)?.buildFilter() ?? null;
+}
+/**
+* Get the human-readable label for a preset ID.
+*/
+function getPresetLabel(presetId) {
+	return DATE_RANGE_PRESETS.find((p) => p.id === presetId)?.label ?? "Custom";
+}
+function daysAgo(n) {
+	const d = /* @__PURE__ */ new Date();
+	d.setDate(d.getDate() - n);
+	d.setHours(0, 0, 0, 0);
+	return d;
+}
+function monthsAgo(n) {
+	const d = /* @__PURE__ */ new Date();
+	d.setMonth(d.getMonth() - n);
+	d.setHours(0, 0, 0, 0);
+	return d;
+}
+function startOfQuarter() {
+	const d = /* @__PURE__ */ new Date();
+	const quarterMonth = Math.floor(d.getMonth() / 3) * 3;
+	return new Date(d.getFullYear(), quarterMonth, 1);
+}
+function startOfYear() {
+	const d = /* @__PURE__ */ new Date();
+	return new Date(d.getFullYear(), 0, 1);
+}
+function lastYear() {
+	const year = (/* @__PURE__ */ new Date()).getFullYear() - 1;
+	return {
+		from: new Date(year, 0, 1),
+		to: new Date(year, 11, 31)
+	};
+}
+//#endregion
+export { DATE_RANGE_PRESETS, getPresetLabel, resolvePresetFilter };

package/dist/core/pipeline-data-points.mjs

@@ -157,7 +157,10 @@ function buildTimeBuckets(items, xColumn, groupByColumn, groups, metric, metricC
 				xKey: key
 			};
 			const groupMap = accumulator.get(key);
-			for (const group of groups) point[group] = aggregate(groupMap.get(group) ?? [], metric.kind === "aggregate" ? metric.aggregate : "count", metric.kind === "aggregate" ? metric.includeZeros ?? true : true);
+			for (const group of groups) {
+				const values = groupMap.get(group) ?? [];
+				point[group] = values.length === 0 ? null : aggregate(values, metric.kind === "aggregate" ? metric.aggregate : "count", metric.kind === "aggregate" ? metric.includeZeros ?? true : true);
+			}
 			return point;
 		}),
 		groups

package/dist/core/types.d.mts

@@ -1,3 +1,5 @@
+import { DateRangePresetId } from "./date-range-presets.mjs";
+
 //#region src/core/types.d.ts
 /**
  * Core types for chart-studio.
@@ -570,9 +572,9 @@ type NumberColumn<T, TId extends string = string> = ColumnBase<T, TId> & {
 /** Union of all column types. */
 type ChartColumn<T, TId extends string = string> = DateColumn<T, TId> | CategoryColumn<T, TId> | BooleanColumn<T, TId> | NumberColumn<T, TId>;
 /** Chart types available for time-series (date X-axis). */
-type TimeSeriesChartType = 'bar' | 'line' | 'area';
+type TimeSeriesChartType = 'bar' | 'grouped-bar' | 'percent-bar' | 'line' | 'area' | 'percent-area';
 /** Chart types available for categorical (category/boolean X-axis). */
-type CategoricalChartType = 'bar' | 'pie' | 'donut';
+type CategoricalChartType = 'bar' | 'grouped-bar' | 'percent-bar' | 'pie' | 'donut';
 /** All supported chart types. */
 type ChartType = TimeSeriesChartType | CategoricalChartType;
 /** Time bucket sizes for date X-axis. */
@@ -706,6 +708,18 @@ type ChartSchema<T, TColumns extends Record<string, unknown> | undefined = Recor
   metric?: MetricConfig<string>; /** Restrict which chart types are available to the user. */
   chartType?: ChartTypeConfig; /** Restrict which time buckets are available for date X-axes. */
   timeBucket?: TimeBucketConfig;
+  /**
+   * Whether line and area charts should connect across null (empty bucket)
+   * data points instead of showing a gap.
+   *
+   * When `true` (default), the line bridges across empty buckets.
+   * When `false`, empty time buckets produce a visible gap in the line/area.
+   *
+   * This is useful for sparse datasets (e.g. quarterly data displayed in a
+   * monthly time bucket) where connecting across gaps produces a cleaner
+   * visual than showing drops to zero.
+   */
+  connectNulls?: boolean;
 };
 type ChartSchemaDefinitionBrand = {
   readonly __chartSchemaBrand: 'chart-schema-definition';
@@ -767,7 +781,7 @@ type ChartSeries = {
  * A single data point in the transformed output.
  * Keys are dynamic based on groupBy values.
  */
-type TransformedDataPoint = Record<string, string | number>;
+type TransformedDataPoint = Record<string, string | number | null>;
 /**
  * Available filter options extracted from the data for a column.
  *
@@ -869,7 +883,12 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
   timeBucket: TTimeBucket; /** Change the time bucket. Runtime accepts only values in `availableTimeBuckets`. */
   setTimeBucket: (bucket: TTimeBucket) => void; /** Time buckets currently available for the active chart state and config. */
   availableTimeBuckets: TTimeBucket[]; /** Whether time bucketing controls should be shown. */
-  isTimeSeries: boolean; /** Active filter values per column. */
+  isTimeSeries: boolean;
+  /**
+   * Whether line and area charts connect across null data points.
+   * Derived from the schema's `connectNulls` option.
+   */
+  connectNulls: boolean; /** Active filter values per column. */
   filters: FilterState<TFilterColumnId>;
   /**
    * Toggle a specific filter value on/off for a column.
@@ -891,8 +910,20 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
   availableDateColumns: Array<{
     id: TDateColumnId;
     label: string;
-  }>; /** Active date range filter (null = all time). */
-  dateRangeFilter: DateRangeFilter | null; /** Set the date range filter. Pass null to clear (show all time). */
+  }>; /** Active date range preset (null = custom range via `dateRangeFilter`). */
+  dateRangePreset: DateRangePresetId | null;
+  /**
+   * Select a named date range preset.
+   * The `dateRangeFilter` is derived automatically from the preset.
+   * For `'auto'`, the filter adjusts reactively when the time bucket changes.
+   */
+  setDateRangePreset: (preset: DateRangePresetId) => void; /** Active date range filter (null = all time). Derived from the preset when one is active. */
+  dateRangeFilter: DateRangeFilter | null;
+  /**
+   * Set the date range filter directly (custom range).
+   * Clears any active preset — the range becomes "Custom".
+   * Pass null to clear (show all time, equivalent to selecting 'all-time' preset).
+   */
   setDateRangeFilter: (filter: DateRangeFilter | null) => void; /** Transformed data points ready for recharts. */
   transformedData: TransformedDataPoint[]; /** Auto-generated series definitions for recharts. */
   series: ChartSeries[]; /** Active columns for the current source. */

package/dist/core/use-chart.mjs

@@ -1,5 +1,6 @@
 import { TIME_BUCKET_ORDER, resolveConfiguredIdSelection, resolveConfiguredValue, restrictConfiguredIdOptions, restrictConfiguredValues } from "./config-utils.mjs";
 import { CHART_TYPE_CONFIG, getAvailableChartTypes } from "./chart-capabilities.mjs";
+import { resolvePresetFilter } from "./date-range-presets.mjs";
 import { inferColumnsFromData } from "./infer-columns.mjs";
 import { DEFAULT_METRIC, buildAvailableMetrics, isSameMetric, resolveMetric, restrictAvailableMetrics } from "./metric-utils.mjs";
 import { applyFilters, extractAvailableFilters, runPipeline } from "./pipeline.mjs";
@@ -45,7 +46,8 @@ function useChart(options) {
 	const [filters, setFilters] = useState(() => /* @__PURE__ */ new Map());
 	const [sorting, setSorting] = useState(null);
 	const [referenceDateIdRaw, setReferenceDateIdRaw] = useState(null);
-	const [dateRangeFilter, setDateRangeFilter] = useState(null);
+	const [dateRangePreset, setDateRangePresetRaw] = useState("all-time");
+	const [customDateRangeFilter, setCustomDateRangeFilter] = useState(null);
 	const sourceIds = useMemo(() => new Set(sources.map((source) => source.id)), [sources]);
 	const activeSourceId = sourceIds.has(activeSourceIdRaw) ? activeSourceIdRaw : sources[0]?.id ?? "default";
 	const setActiveSource = (sourceId) => {
@@ -82,17 +84,6 @@ function useChart(options) {
 		resolvedXAxisId,
 		isTimeSeries
 	]);
-	const effectiveData = useMemo(() => {
-		const column = dateColumns.find((candidate) => candidate.id === referenceDateId);
-		if (!column) return rawData;
-		if (dateRangeFilter === null) return rawData;
-		return filterByDateRange(rawData, column, dateRangeFilter);
-	}, [
-		rawData,
-		dateRangeFilter,
-		dateColumns,
-		referenceDateId
-	]);
 	const availableGroupBys = useMemo(() => restrictConfiguredIdOptions(activeColumns.filter((column) => (column.type === "category" || column.type === "boolean") && column.id !== resolvedXAxisId).map((column) => ({
 		id: column.id,
 		label: column.label
@@ -115,19 +106,6 @@ function useChart(options) {
 		availableMetrics,
 		activeSource.schema
 	]);
-	const availableFilters = useMemo(() => {
-		return restrictConfiguredIdOptions(extractAvailableFilters(effectiveData, activeColumns).map((filter) => ({
-			...filter,
-			id: filter.columnId
-		})), activeSource.schema?.filters).map(({ id: _id, ...filter }) => filter);
-	}, [
-		effectiveData,
-		activeColumns,
-		activeSource.schema
-	]);
-	const availableFilterValues = useMemo(() => createAvailableFilterValueMap(availableFilters), [availableFilters]);
-	const filterColumns = useMemo(() => activeColumns.filter((column) => availableFilters.some((filter) => filter.columnId === column.id)), [activeColumns, availableFilters]);
-	const resolvedFilters = useMemo(() => sanitizeFilters(filters, filterColumns), [filters, filterColumns]);
 	const availableChartTypes = useMemo(() => restrictConfiguredValues(getAvailableChartTypes({
 		xAxisType: resolvedXAxisType,
 		hasGroupBy: resolvedGroupById !== null
@@ -154,6 +132,38 @@ function useChart(options) {
 		availableTimeBuckets,
 		activeSource.schema
 	]);
+	const dateRangeFilter = useMemo(() => {
+		if (dateRangePreset !== null) return resolvePresetFilter(dateRangePreset, resolvedTimeBucket);
+		return customDateRangeFilter;
+	}, [
+		dateRangePreset,
+		customDateRangeFilter,
+		resolvedTimeBucket
+	]);
+	const effectiveData = useMemo(() => {
+		const column = dateColumns.find((candidate) => candidate.id === referenceDateId);
+		if (!column) return rawData;
+		if (dateRangeFilter === null) return rawData;
+		return filterByDateRange(rawData, column, dateRangeFilter);
+	}, [
+		rawData,
+		dateRangeFilter,
+		dateColumns,
+		referenceDateId
+	]);
+	const availableFilters = useMemo(() => {
+		return restrictConfiguredIdOptions(extractAvailableFilters(effectiveData, activeColumns).map((filter) => ({
+			...filter,
+			id: filter.columnId
+		})), activeSource.schema?.filters).map(({ id: _id, ...filter }) => filter);
+	}, [
+		effectiveData,
+		activeColumns,
+		activeSource.schema
+	]);
+	const availableFilterValues = useMemo(() => createAvailableFilterValueMap(availableFilters), [availableFilters]);
+	const filterColumns = useMemo(() => activeColumns.filter((column) => availableFilters.some((filter) => filter.columnId === column.id)), [activeColumns, availableFilters]);
+	const resolvedFilters = useMemo(() => sanitizeFilters(filters, filterColumns), [filters, filterColumns]);
 	const pipelineResult = useMemo(() => {
 		if (!resolvedXAxisId) return {
 			data: [],
@@ -249,6 +259,18 @@ function useChart(options) {
 		if (!availableDateColumnIds.has(columnId)) return;
 		setReferenceDateIdRaw(columnId);
 	};
+	const setDateRangePreset = (preset) => {
+		setDateRangePresetRaw(preset);
+	};
+	const setDateRangeFilter = (filter) => {
+		if (filter === null) {
+			setDateRangePresetRaw("all-time");
+			setCustomDateRangeFilter(null);
+		} else {
+			setDateRangePresetRaw(null);
+			setCustomDateRangeFilter(filter);
+		}
+	};
 	const chart = {
 		activeSourceId,
 		setActiveSource,
@@ -273,6 +295,7 @@ function useChart(options) {
 		setTimeBucket,
 		availableTimeBuckets,
 		isTimeSeries,
+		connectNulls: activeSource.schema?.connectNulls ?? true,
 		filters: resolvedFilters,
 		toggleFilter,
 		clearFilter,
@@ -284,6 +307,8 @@ function useChart(options) {
 		referenceDateId,
 		setReferenceDateId,
 		availableDateColumns,
+		dateRangePreset,
+		setDateRangePreset,
 		dateRangeFilter,
 		setDateRangeFilter,
 		transformedData: pipelineResult.data,

package/dist/ui/chart-canvas.d.mts

@@ -4,7 +4,7 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
 /**
  * Chart canvas — renders the actual recharts chart based on the current state.
  *
- * Supports: bar, line, area (time-series), bar, pie, donut (categorical).
+ * Supports: bar, grouped-bar, percent-bar, line, area, percent-area (time-series), bar, grouped-bar, percent-bar, pie, donut (categorical).
  * Automatically switches between chart types based on the chart instance state.
  */
 /**