@matthieumordrel/chart-studio 0.2.1 → 0.2.3

package/dist/ui/chart-canvas.mjs

@@ -0,0 +1,461 @@
+import { getSeriesColor } from "../core/colors.mjs";
+import { createNumericRange, formatChartValue, formatTimeBucketLabel, shouldAllowDecimalTicks } from "../core/formatting.mjs";
+import { useChartContext } from "./chart-context.mjs";
+import { selectVisibleXAxisTicks } from "./chart-axis-ticks.mjs";
+import { useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Area, AreaChart, Bar, BarChart, CartesianGrid, LabelList, Legend, Line, LineChart, Pie, PieChart, Tooltip, XAxis, YAxis } from "recharts";
+//#region src/ui/chart-canvas.tsx
+/**
+* Chart canvas — renders the actual recharts chart based on the current state.
+*
+* Supports: bar, line, area (time-series), bar, pie, donut (categorical).
+* Automatically switches between chart types based on the chart instance state.
+*/
+/**
+* Estimates the pixel width the YAxis needs so no label is ever clipped.
+* Considers both the visible range and the likely "nice" axis boundary Recharts
+* may choose above it, then measures the widest formatted label and adds a
+* small gutter for tick spacing.
+*/
+function estimateYAxisWidth(numericRange, valueColumn) {
+	const widestLabel = getYAxisLabelCandidates(numericRange, valueColumn).reduce((maxWidth, label) => Math.max(maxWidth, measureAxisLabelWidth(label)), 0);
+	return Math.max(MIN_Y_AXIS_WIDTH, Math.ceil(widestLabel + Y_AXIS_WIDTH_GUTTER));
+}
+/**
+* Font used by the shared chart axis ticks (`text-xs` in the default theme).
+*/
+const AXIS_TICK_FONT = "12px system-ui, sans-serif";
+/**
+* Canvas measurement can be unavailable in some environments, so keep a
+* slightly generous character-width fallback.
+*/
+const FALLBACK_AXIS_CHARACTER_WIDTH = 8;
+/**
+* Minimum width so short numeric axes still have breathing room.
+*/
+const MIN_Y_AXIS_WIDTH = 48;
+/**
+* Extra space for tick margin plus a small anti-clipping buffer.
+*/
+const Y_AXIS_WIDTH_GUTTER = 18;
+/**
+* Horizontal breathing room kept between two visible X-axis labels.
+*/
+const X_AXIS_MINIMUM_TICK_GAP = 8;
+/**
+* Build a small set of realistic axis labels and size for the widest one.
+* This catches cases where the chart data tops out below the rounded axis
+* tick, such as `950` minutes producing a `1000` minute top tick.
+*/
+function getYAxisLabelCandidates(numericRange, valueColumn) {
+	return getYAxisCandidateValues(numericRange).map((value) => formatChartValue(value, {
+		column: valueColumn,
+		surface: "axis",
+		numericRange
+	}));
+}
+/**
+* Include the visible extrema plus rounded axis boundaries so the width
+* estimate matches what the axis is likely to render.
+*/
+function getYAxisCandidateValues(numericRange) {
+	if (!numericRange) return [0];
+	const maxAbs = Math.max(Math.abs(numericRange.min), Math.abs(numericRange.max));
+	const niceMaxAbs = getNiceAxisBoundary(maxAbs);
+	const values = new Set([
+		0,
+		numericRange.min,
+		numericRange.max,
+		maxAbs,
+		niceMaxAbs
+	]);
+	if (numericRange.min < 0) values.add(-niceMaxAbs);
+	return Array.from(values);
+}
+/**
+* Approximate the rounded outer tick value chart libraries tend to choose for
+* a human-friendly numeric axis.
+*/
+function getNiceAxisBoundary(value) {
+	if (!Number.isFinite(value) || value <= 0) return 0;
+	const magnitude = 10 ** Math.floor(Math.log10(value));
+	const fraction = value / magnitude;
+	if (fraction <= 1) return magnitude;
+	if (fraction <= 2) return 2 * magnitude;
+	if (fraction <= 5) return 5 * magnitude;
+	return 10 * magnitude;
+}
+/**
+* Measure axis text width in the browser and fall back to a safe character
+* estimate in non-DOM environments.
+*/
+function measureAxisLabelWidth(label) {
+	if (typeof document === "undefined") return label.length * FALLBACK_AXIS_CHARACTER_WIDTH;
+	const context = document.createElement("canvas").getContext("2d");
+	if (!context) return label.length * FALLBACK_AXIS_CHARACTER_WIDTH;
+	context.font = AXIS_TICK_FONT;
+	return context.measureText(label).width;
+}
+/**
+* Approximate the drawable X-axis width after margins, Y-axis labels, and axis
+* padding have taken their share of the SVG width.
+*/
+function getCartesianPlotWidth(totalWidth, yAxisWidth) {
+	return Math.max(1, totalWidth - yAxisWidth - CARTESIAN_BASE_MARGIN.left - CARTESIAN_BASE_MARGIN.right - CARTESIAN_X_AXIS_PADDING.left - CARTESIAN_X_AXIS_PADDING.right);
+}
+/**
+* Resolve the raw categorical tick value used by Recharts for one transformed
+* pipeline point.
+*/
+function getXAxisTickValue(point) {
+	return typeof point["xKey"] === "string" || typeof point["xKey"] === "number" ? point["xKey"] : String(point["xLabel"]);
+}
+/**
+* Important recharts styling — mirrors shadcn's ChartContainer CSS.
+* Ensures proper text colors, grid lines, and outline handling.
+*/
+const RECHARTS_STYLES = [
+	"text-xs",
+	"[&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground",
+	"[&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-border/50",
+	"[&_.recharts-curve.recharts-tooltip-cursor]:stroke-border",
+	"[&_.recharts-layer]:outline-hidden",
+	"[&_.recharts-rectangle.recharts-tooltip-cursor]:fill-muted",
+	"[&_.recharts-reference-line_[stroke='#ccc']]:stroke-border",
+	"[&_.recharts-sector]:outline-hidden",
+	"[&_.recharts-surface]:outline-hidden"
+].join(" ");
+/**
+* Reserve enough top padding for the tallest bar/point label plus its offset so
+* data labels never clip against the SVG edge.
+*/
+const CARTESIAN_BASE_MARGIN = {
+	top: 4,
+	right: 8,
+	left: 0,
+	bottom: 0
+};
+/**
+* Vertical headroom required for one top-positioned cartesian data label.
+*/
+const CARTESIAN_DATA_LABEL_TOP_CLEARANCE = 28;
+/**
+* Expand the cartesian chart margin only when top-positioned data labels are
+* enabled.
+*/
+function getCartesianChartMargin(showDataLabels) {
+	return showDataLabels ? {
+		...CARTESIAN_BASE_MARGIN,
+		top: CARTESIAN_BASE_MARGIN.top + CARTESIAN_DATA_LABEL_TOP_CLEARANCE
+	} : CARTESIAN_BASE_MARGIN;
+}
+/**
+* Keep the first and last rendered values from hugging the chart edges.
+*/
+const CARTESIAN_X_AXIS_PADDING = {
+	left: 12,
+	right: 12
+};
+/**
+* Hook that measures a container's width using ResizeObserver.
+* Avoids the ResponsiveContainer issues with flexbox/grid layouts.
+*/
+function useContainerWidth() {
+	const ref = useRef(null);
+	const [width, setWidth] = useState(0);
+	useEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		const observer = new ResizeObserver((entries) => {
+			const entry = entries[0];
+			if (entry) setWidth(entry.contentRect.width);
+		});
+		observer.observe(el);
+		return () => observer.disconnect();
+	}, []);
+	return {
+		ref,
+		width
+	};
+}
+/** Renders the appropriate recharts chart based on the chart instance state. */
+function ChartCanvas({ height = 300, className, showDataLabels = false }) {
+	const chart = useChartContext();
+	const { chartType, transformedData, series } = chart;
+	const { ref, width } = useContainerWidth();
+	const xColumn = chart.columns.find((column) => column.id === chart.xAxisId) ?? null;
+	const aggregateMetric = chart.metric.kind === "aggregate" ? chart.metric : null;
+	const valueColumn = (aggregateMetric ? chart.columns.find((column) => column.id === aggregateMetric.columnId && column.type === "number") : null) ?? {
+		type: "number",
+		format: void 0
+	};
+	const numericValues = transformedData.flatMap((point) => series.flatMap((seriesItem) => {
+		const value = point[seriesItem.dataKey];
+		return typeof value === "number" ? [value] : [];
+	}));
+	const valueRange = createNumericRange(numericValues);
+	const allowDecimalTicks = shouldAllowDecimalTicks(numericValues);
+	if (transformedData.length === 0) return /* @__PURE__ */ jsx("div", {
+		ref,
+		className: `flex items-center justify-center text-sm text-muted-foreground ${className ?? ""}`,
+		style: { height },
+		children: "No data available"
+	});
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		className: `${RECHARTS_STYLES} ${className ?? ""}`,
+		style: { height },
+		children: width > 0 && (chartType === "pie" || chartType === "donut" ? /* @__PURE__ */ jsx(PieChartRenderer, {
+			data: transformedData,
+			series,
+			innerRadius: chartType === "donut",
+			width,
+			height,
+			valueColumn,
+			valueRange,
+			allowDecimalTicks,
+			xColumn,
+			timeBucket: chart.isTimeSeries ? chart.timeBucket : void 0,
+			showDataLabels
+		}) : chartType === "line" ? /* @__PURE__ */ jsx(LineChartRenderer, {
+			data: transformedData,
+			series,
+			width,
+			height,
+			valueColumn,
+			valueRange,
+			allowDecimalTicks,
+			xColumn,
+			timeBucket: chart.isTimeSeries ? chart.timeBucket : void 0,
+			showDataLabels
+		}) : chartType === "area" ? /* @__PURE__ */ jsx(AreaChartRenderer, {
+			data: transformedData,
+			series,
+			width,
+			height,
+			valueColumn,
+			valueRange,
+			allowDecimalTicks,
+			xColumn,
+			timeBucket: chart.isTimeSeries ? chart.timeBucket : void 0,
+			showDataLabels
+		}) : /* @__PURE__ */ jsx(BarChartRenderer, {
+			data: transformedData,
+			series,
+			width,
+			height,
+			valueColumn,
+			valueRange,
+			allowDecimalTicks,
+			xColumn,
+			timeBucket: chart.isTimeSeries ? chart.timeBucket : void 0,
+			showDataLabels
+		}))
+	});
+}
+/**
+* Shared shell for all Cartesian chart types.
+* Owns the grid, axes, tooltip, and legend — the only things that change
+* per chart type are the root component and the series element.
+*/
+function CartesianChartShell({ data, series, width, height, valueColumn, valueRange, allowDecimalTicks, xColumn, timeBucket, showDataLabels, Chart, renderSeries }) {
+	const yAxisWidth = estimateYAxisWidth(valueRange, valueColumn);
+	const xAxisTickValues = selectVisibleXAxisTicks({
+		values: data.map(getXAxisTickValue),
+		labels: data.map((point) => formatXAxisValue(getXAxisTickValue(point), xColumn, timeBucket, "axis")),
+		plotWidth: getCartesianPlotWidth(width, yAxisWidth),
+		minimumTickGap: X_AXIS_MINIMUM_TICK_GAP,
+		measureLabelWidth: measureAxisLabelWidth
+	});
+	return /* @__PURE__ */ jsxs(Chart, {
+		data,
+		width,
+		height,
+		margin: getCartesianChartMargin(showDataLabels),
+		children: [
+			/* @__PURE__ */ jsx(CartesianGrid, {
+				vertical: false,
+				strokeDasharray: "3 3"
+			}),
+			/* @__PURE__ */ jsx(XAxis, {
+				dataKey: "xKey",
+				tickLine: false,
+				axisLine: false,
+				tickMargin: 8,
+				interval: 0,
+				padding: CARTESIAN_X_AXIS_PADDING,
+				ticks: xAxisTickValues,
+				tickFormatter: (value) => formatXAxisValue(value, xColumn, timeBucket, "axis")
+			}),
+			/* @__PURE__ */ jsx(YAxis, {
+				tickLine: false,
+				axisLine: false,
+				tickMargin: 4,
+				allowDecimals: allowDecimalTicks,
+				width: yAxisWidth,
+				tickFormatter: (value) => typeof value === "number" ? formatChartValue(value, {
+					column: valueColumn,
+					surface: "axis",
+					numericRange: valueRange
+				}) : String(value)
+			}),
+			/* @__PURE__ */ jsx(Tooltip, {
+				formatter: (value) => typeof value === "number" ? formatChartValue(value, {
+					column: valueColumn,
+					surface: "tooltip",
+					numericRange: valueRange
+				}) : value,
+				labelFormatter: (label, payload) => formatTooltipLabel(label, payload, xColumn, timeBucket)
+			}),
+			series.length > 1 && /* @__PURE__ */ jsx(Legend, {}),
+			series.map(renderSeries)
+		]
+	});
+}
+/**
+* Resolve the most descriptive tooltip label from the transformed data point.
+*/
+function formatTooltipLabel(label, payload, xColumn, timeBucket) {
+	if (!xColumn) return String(label);
+	const point = payload?.[0]?.payload;
+	return formatXAxisValue(typeof point?.["xKey"] === "string" || typeof point?.["xKey"] === "number" ? point["xKey"] : label, xColumn, timeBucket, "tooltip");
+}
+/**
+* Format one X-axis value using the same shared column rules as the rest of the
+* chart while preserving the special bucket labels for inferred date buckets.
+*/
+function formatXAxisValue(value, xColumn, timeBucket, surface) {
+	if (!xColumn) return String(value);
+	if (xColumn.type === "date" && timeBucket && typeof value === "string" && !xColumn.formatter) return formatTimeBucketLabel(value, timeBucket, surface);
+	return formatChartValue(value, {
+		column: xColumn,
+		surface,
+		timeBucket
+	});
+}
+function BarChartRenderer(props) {
+	const { series, showDataLabels, valueColumn, valueRange } = props;
+	return /* @__PURE__ */ jsx(CartesianChartShell, {
+		...props,
+		Chart: BarChart,
+		renderSeries: (s) => /* @__PURE__ */ jsx(Bar, {
+			dataKey: s.dataKey,
+			name: s.label,
+			fill: s.color,
+			radius: [
+				4,
+				4,
+				0,
+				0
+			],
+			stackId: series.length > 1 ? "stack" : void 0,
+			children: showDataLabels && /* @__PURE__ */ jsx(LabelList, {
+				position: "top",
+				offset: 8,
+				formatter: (value) => formatDataLabel(value, valueColumn, valueRange)
+			})
+		}, s.dataKey)
+	});
+}
+function LineChartRenderer(props) {
+	const { showDataLabels, valueColumn, valueRange } = props;
+	return /* @__PURE__ */ jsx(CartesianChartShell, {
+		...props,
+		Chart: LineChart,
+		renderSeries: (s) => /* @__PURE__ */ jsx(Line, {
+			type: "monotone",
+			dataKey: s.dataKey,
+			name: s.label,
+			stroke: s.color,
+			strokeWidth: 2,
+			dot: { r: 3 },
+			activeDot: { r: 5 },
+			children: showDataLabels && /* @__PURE__ */ jsx(LabelList, {
+				position: "top",
+				offset: 8,
+				formatter: (value) => formatDataLabel(value, valueColumn, valueRange)
+			})
+		}, s.dataKey)
+	});
+}
+function AreaChartRenderer(props) {
+	const { series, showDataLabels, valueColumn, valueRange } = props;
+	return /* @__PURE__ */ jsx(CartesianChartShell, {
+		...props,
+		Chart: AreaChart,
+		renderSeries: (s) => /* @__PURE__ */ jsx(Area, {
+			type: "monotone",
+			dataKey: s.dataKey,
+			name: s.label,
+			stroke: s.color,
+			fill: s.color,
+			fillOpacity: .3,
+			stackId: series.length > 1 ? "stack" : void 0,
+			children: showDataLabels && /* @__PURE__ */ jsx(LabelList, {
+				position: "top",
+				offset: 8,
+				formatter: (value) => formatDataLabel(value, valueColumn, valueRange)
+			})
+		}, s.dataKey)
+	});
+}
+function PieChartRenderer({ data, series, innerRadius, width, height, valueColumn, valueRange, xColumn, timeBucket, showDataLabels }) {
+	const valueKey = series[0]?.dataKey;
+	const pieData = data.map((point, index) => {
+		return {
+			name: typeof point["xKey"] === "string" || typeof point["xKey"] === "number" ? formatXAxisValue(point["xKey"], xColumn, timeBucket, "tooltip") : String(point["xLabel"]),
+			value: valueKey && typeof point[valueKey] === "number" ? point[valueKey] : 0,
+			fill: getSeriesColor(index)
+		};
+	});
+	return /* @__PURE__ */ jsxs(PieChart, {
+		width,
+		height,
+		children: [
+			/* @__PURE__ */ jsx(Tooltip, { formatter: (value) => typeof value === "number" ? formatChartValue(value, {
+				column: valueColumn,
+				surface: "tooltip",
+				numericRange: valueRange
+			}) : value }),
+			/* @__PURE__ */ jsx(Legend, {}),
+			/* @__PURE__ */ jsx(Pie, {
+				data: pieData,
+				dataKey: "value",
+				nameKey: "name",
+				cx: "50%",
+				cy: "50%",
+				innerRadius: innerRadius ? "40%" : 0,
+				outerRadius: "80%",
+				label: showDataLabels ? ({ name, value }) => shouldHideDataLabel(value) ? "" : `${name}: ${typeof value === "number" ? formatChartValue(value, {
+					column: valueColumn,
+					surface: "data-label",
+					numericRange: valueRange
+				}) : value}` : false,
+				labelLine: false
+			})
+		]
+	});
+}
+/**
+* Format one cartesian data label with the same surface-aware rules used
+* elsewhere in the chart UI.
+*/
+function formatDataLabel(value, valueColumn, valueRange) {
+	if (shouldHideDataLabel(value)) return "";
+	if (typeof value !== "number") return String(value);
+	return formatChartValue(value, {
+		column: valueColumn,
+		surface: "data-label",
+		numericRange: valueRange
+	});
+}
+/**
+* Suppress zero-value labels in the built-in UI so charts stay quieter by
+* default while tooltips and raw values remain unchanged.
+*/
+function shouldHideDataLabel(value) {
+	return typeof value === "number" && value === 0;
+}
+//#endregion
+export { ChartCanvas };

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

@@ -0,0 +1,92 @@
+import { ChartColumn, ChartInstance, ChartInstanceFromSchema, ChartSchema, Metric, ResolvedChartSchemaFromDefinition } from "../core/types.mjs";
+import { ReactElement, ReactNode } from "react";
+
+//#region src/ui/chart-context.d.ts
+/**
+ * Type-erased chart instance stored in React context.
+ * This keeps the default UI primitives honest and safe for both single-source
+ * and multi-source charts.
+ */
+type ChartContextChart = Omit<ChartInstance<unknown, string>, 'columns' | 'filters'> & {
+  columns: readonly ChartColumn<any, string>[];
+  filters: Map<string, Set<string>>;
+};
+type AnyChartInstance = {
+  activeSourceId: string;
+  setActiveSource: (...args: any[]) => unknown;
+  hasMultipleSources: boolean;
+  sources: Array<{
+    id: string;
+    label: string;
+  }>;
+  chartType: ChartContextChart['chartType'];
+  setChartType: (...args: any[]) => unknown;
+  availableChartTypes: ChartContextChart['availableChartTypes'];
+  xAxisId: string | null;
+  setXAxis: (...args: any[]) => unknown;
+  availableXAxes: ChartContextChart['availableXAxes'];
+  groupById: string | null;
+  setGroupBy: (...args: any[]) => unknown;
+  availableGroupBys: ChartContextChart['availableGroupBys'];
+  metric: Metric<any>;
+  setMetric: (...args: any[]) => unknown;
+  availableMetrics: ChartContextChart['availableMetrics'];
+  timeBucket: ChartContextChart['timeBucket'];
+  setTimeBucket: (...args: any[]) => unknown;
+  availableTimeBuckets: ChartContextChart['availableTimeBuckets'];
+  isTimeSeries: boolean;
+  filters: Map<any, Set<string>>;
+  toggleFilter: (...args: any[]) => unknown;
+  clearFilter: (...args: any[]) => unknown;
+  clearAllFilters: () => void;
+  availableFilters: ChartContextChart['availableFilters'];
+  sorting: ChartContextChart['sorting'];
+  setSorting: (...args: any[]) => unknown;
+  dateRange: ChartContextChart['dateRange'];
+  referenceDateId: string | null;
+  setReferenceDateId: (...args: any[]) => unknown;
+  availableDateColumns: ChartContextChart['availableDateColumns'];
+  dateRangeFilter: ChartContextChart['dateRangeFilter'];
+  setDateRangeFilter: (...args: any[]) => unknown;
+  transformedData: ChartContextChart['transformedData'];
+  series: ChartContextChart['series'];
+  columns: readonly ChartColumn<any, string>[];
+  rawData: readonly unknown[];
+  recordCount: number;
+};
+/**
+ * Hook to access the chart instance from context.
+ * Must be used within a `<Chart>` provider.
+ *
+ * This hook stays intentionally broad so the default UI primitives remain safe
+ * for both single-source and multi-source charts.
+ */
+declare function useChartContext(): ChartContextChart;
+/**
+ * Typed single-source chart context escape hatch for inferred charts.
+ * React cannot infer provider generics through arbitrary subtrees, so callers
+ * provide the row type (and optional schema type) explicitly.
+ */
+declare function useTypedChartContext<T, const TSchema extends ChartSchema<T, any> | undefined = undefined>(): ChartInstanceFromSchema<T, ResolvedChartSchemaFromDefinition<TSchema>>;
+/**
+ * Root provider component. Wraps children with the chart instance context.
+ *
+ * @example
+ * ```tsx
+ * <Chart chart={chart}>
+ *   <ChartToolbar />
+ *   <ChartCanvas />
+ * </Chart>
+ * ```
+ */
+declare function Chart({
+  chart,
+  children,
+  className
+}: {
+  chart: AnyChartInstance;
+  children: ReactNode;
+  className?: string;
+}): ReactElement;
+//#endregion
+export { Chart, useChartContext, useTypedChartContext };

package/dist/ui/chart-context.mjs

@@ -0,0 +1,112 @@
+import { createContext, useContext, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/ui/chart-context.tsx
+/**
+* React context for sharing the chart instance across composable UI components.
+*/
+const ChartContext = createContext(null);
+/**
+* Check whether a candidate column ID exists in the current chart.
+*/
+function isKnownColumnId(columnIds, columnId) {
+	return columnIds.has(columnId);
+}
+/**
+* Create the broad-but-safe chart shape shared through React context.
+*/
+function createChartContextChart(chart) {
+	const columnIds = new Set(chart.columns.map((column) => column.id));
+	return {
+		activeSourceId: chart.activeSourceId,
+		setActiveSource: chart.setActiveSource,
+		hasMultipleSources: chart.hasMultipleSources,
+		sources: chart.sources,
+		chartType: chart.chartType,
+		setChartType: chart.setChartType,
+		availableChartTypes: chart.availableChartTypes,
+		xAxisId: chart.xAxisId,
+		setXAxis: (columnId) => {
+			if (!isKnownColumnId(columnIds, columnId)) throw new Error(`Unknown chart column ID: "${columnId}"`);
+			chart.setXAxis(columnId);
+		},
+		availableXAxes: chart.availableXAxes,
+		groupById: chart.groupById,
+		setGroupBy: (columnId) => {
+			if (columnId === null) {
+				chart.setGroupBy(null);
+				return;
+			}
+			if (!isKnownColumnId(columnIds, columnId)) throw new Error(`Unknown chart column ID: "${columnId}"`);
+			chart.setGroupBy(columnId);
+		},
+		availableGroupBys: chart.availableGroupBys,
+		metric: chart.metric,
+		setMetric: (metric) => {
+			if (metric.kind === "aggregate" && !isKnownColumnId(columnIds, metric.columnId)) throw new Error(`Unknown metric column ID: "${metric.columnId}"`);
+			chart.setMetric(metric);
+		},
+		availableMetrics: chart.availableMetrics,
+		timeBucket: chart.timeBucket,
+		setTimeBucket: chart.setTimeBucket,
+		availableTimeBuckets: chart.availableTimeBuckets,
+		isTimeSeries: chart.isTimeSeries,
+		filters: new Map(chart.filters),
+		toggleFilter: (columnId, value) => {
+			if (!isKnownColumnId(columnIds, columnId)) throw new Error(`Unknown chart column ID: "${columnId}"`);
+			chart.toggleFilter(columnId, value);
+		},
+		clearFilter: (columnId) => {
+			if (!isKnownColumnId(columnIds, columnId)) throw new Error(`Unknown chart column ID: "${columnId}"`);
+			chart.clearFilter(columnId);
+		},
+		clearAllFilters: chart.clearAllFilters,
+		availableFilters: chart.availableFilters,
+		sorting: chart.sorting,
+		setSorting: chart.setSorting,
+		dateRange: chart.dateRange,
+		referenceDateId: chart.referenceDateId,
+		setReferenceDateId: (columnId) => {
+			if (!isKnownColumnId(columnIds, columnId)) throw new Error(`Unknown chart column ID: "${columnId}"`);
+			chart.setReferenceDateId(columnId);
+		},
+		availableDateColumns: chart.availableDateColumns,
+		dateRangeFilter: chart.dateRangeFilter,
+		setDateRangeFilter: chart.setDateRangeFilter,
+		transformedData: chart.transformedData,
+		series: chart.series,
+		columns: chart.columns,
+		rawData: chart.rawData,
+		recordCount: chart.recordCount
+	};
+}
+function useChartContext() {
+	const ctx = useContext(ChartContext);
+	if (!ctx) throw new Error("useChartContext must be used within a <Chart> provider");
+	return ctx.chart;
+}
+/**
+* Typed single-source chart context escape hatch for inferred charts.
+* React cannot infer provider generics through arbitrary subtrees, so callers
+* provide the row type (and optional schema type) explicitly.
+*/
+function useTypedChartContext() {
+	const ctx = useContext(ChartContext);
+	if (!ctx) throw new Error("useTypedChartContext must be used within a <Chart> provider");
+	if (ctx.chart.hasMultipleSources) throw new Error("useTypedChartContext only supports single-source charts right now. Multi-source charts stay broad because the active source schema can change.");
+	return ctx.typedChart;
+}
+function Chart({ chart, children, className }) {
+	const contextValue = useMemo(() => ({
+		chart: createChartContextChart(chart),
+		typedChart: chart
+	}), [chart]);
+	return /* @__PURE__ */ jsx(ChartContext.Provider, {
+		value: contextValue,
+		children: /* @__PURE__ */ jsx("div", {
+			className,
+			children
+		})
+	});
+}
+//#endregion
+export { Chart, useChartContext, useTypedChartContext };

package/dist/ui/{chart-date-range-badge.d.ts → chart-date-range-badge.d.mts}

@@ -1,3 +1,6 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/ui/chart-date-range-badge.d.ts
 /**
  * Read-only badge that always displays the current date range in the toolbar.
  *
@@ -8,7 +11,10 @@
  * Read-only badge showing the active date range preset and computed bounds.
  * Renders nothing if no date columns are available.
  */
-export declare function ChartDateRangeBadge({ className }: {
-    className?: string;
-}): import("react/jsx-runtime").JSX.Element | null;
-//# sourceMappingURL=chart-date-range-badge.d.ts.map
+declare function ChartDateRangeBadge({
+  className
+}: {
+  className?: string;
+}): react_jsx_runtime0.JSX.Element | null;
+//#endregion
+export { ChartDateRangeBadge };