@matthieumordrel/chart-studio 0.2.0 → 0.2.2

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

@@ -0,0 +1,212 @@
+import { isAggregateMetric } from "./metric-utils.mjs";
+import { aggregate, dateBucketKey, dateBucketLabel, getStringValue } from "./pipeline-helpers.mjs";
+//#region src/core/pipeline-data-points.ts
+/**
+* Bucket and aggregation steps for the chart transformation pipeline.
+*/
+/**
+* Build chart-ready data points by bucketing the X-axis, pivoting groups, and
+* aggregating the selected metric.
+*
+* @param items - Filtered source data
+* @param xColumn - Active X-axis column
+* @param groupByColumn - Optional group-by column
+* @param metric - Selected metric configuration
+* @param numberColumns - Number columns available for metric lookup
+* @param timeBucket - Time bucket used for date X-axes
+* @returns Aggregated chart data points and group labels
+*/
+function buildDataPoints(items, xColumn, groupByColumn, metric, numberColumns, timeBucket) {
+	const groupSet = /* @__PURE__ */ new Set();
+	if (groupByColumn) for (const item of items) groupSet.add(getStringValue(item, groupByColumn));
+	const groups = groupByColumn ? [...groupSet].toSorted() : ["value"];
+	const metricColumn = isAggregateMetric(metric) ? numberColumns.find((column) => column.id === metric.columnId) ?? null : null;
+	if (xColumn.type === "date") return buildTimeBuckets(items, xColumn, groupByColumn, groups, metric, metricColumn, timeBucket);
+	return buildCategoryBuckets(items, xColumn, groupByColumn, groups, metric, metricColumn);
+}
+/**
+* Generate a continuous sequence of date buckets from the minimum to maximum
+* date found in the data.
+*
+* @param items - Filtered source data
+* @param xColumn - Active date column
+* @param bucket - Time bucket granularity
+* @returns Every bucket between the first and last date in the dataset
+*/
+function generateBucketsFromData(items, xColumn, bucket) {
+	let min = null;
+	let max = null;
+	for (const item of items) {
+		const rawValue = xColumn.accessor(item);
+		if (rawValue == null) continue;
+		const date = new Date(rawValue);
+		if (Number.isNaN(date.getTime())) continue;
+		if (!min || date < min) min = date;
+		if (!max || date > max) max = date;
+	}
+	if (!min || !max) return [];
+	const buckets = [];
+	const cursor = startOfBucket(min, bucket);
+	const seenKeys = /* @__PURE__ */ new Set();
+	const maxBuckets = 500;
+	for (let bucketCount = 0; bucketCount < maxBuckets; bucketCount += 1) {
+		if (cursor > max) break;
+		const key = dateBucketKey(cursor, bucket);
+		if (!seenKeys.has(key)) {
+			seenKeys.add(key);
+			buckets.push({
+				key,
+				label: dateBucketLabel(key, bucket)
+			});
+		}
+		advanceBucketCursor(cursor, bucket);
+	}
+	return buckets;
+}
+/**
+* Normalize a date to the start of its containing bucket.
+*
+* @param date - Source date
+* @param bucket - Time bucket granularity
+* @returns Start boundary for the bucket containing the source date
+*/
+function startOfBucket(date, bucket) {
+	const normalized = new Date(date);
+	normalized.setHours(0, 0, 0, 0);
+	switch (bucket) {
+		case "day": return normalized;
+		case "week": {
+			const day = normalized.getDay();
+			normalized.setDate(normalized.getDate() - (day + 6) % 7);
+			return normalized;
+		}
+		case "month":
+			normalized.setDate(1);
+			return normalized;
+		case "quarter":
+			normalized.setMonth(Math.floor(normalized.getMonth() / 3) * 3, 1);
+			return normalized;
+		case "year":
+			normalized.setMonth(0, 1);
+			return normalized;
+	}
+}
+/**
+* Advance a mutable cursor by a single bucket interval.
+*
+* @param cursor - Current date cursor
+* @param bucket - Time bucket granularity
+*/
+function advanceBucketCursor(cursor, bucket) {
+	switch (bucket) {
+		case "day":
+			cursor.setDate(cursor.getDate() + 1);
+			break;
+		case "week":
+			cursor.setDate(cursor.getDate() + 7);
+			break;
+		case "month":
+			cursor.setMonth(cursor.getMonth() + 1);
+			break;
+		case "quarter":
+			cursor.setMonth(cursor.getMonth() + 3);
+			break;
+		case "year":
+			cursor.setFullYear(cursor.getFullYear() + 1);
+			break;
+	}
+}
+/**
+* Build data points for a date X-axis.
+*
+* @param items - Filtered source data
+* @param xColumn - Active date column
+* @param groupByColumn - Optional group-by column
+* @param groups - Resolved group labels
+* @param metric - Selected metric configuration
+* @param metricColumn - Resolved numeric metric column
+* @param timeBucket - Time bucket granularity
+* @returns Aggregated date-bucketed data points
+*/
+function buildTimeBuckets(items, xColumn, groupByColumn, groups, metric, metricColumn, timeBucket) {
+	const allBuckets = generateBucketsFromData(items, xColumn, timeBucket);
+	const accumulator = /* @__PURE__ */ new Map();
+	for (const { key } of allBuckets) {
+		const groupMap = /* @__PURE__ */ new Map();
+		for (const group of groups) groupMap.set(group, []);
+		accumulator.set(key, groupMap);
+	}
+	for (const item of items) {
+		const rawValue = xColumn.accessor(item);
+		if (rawValue == null) continue;
+		const key = dateBucketKey(new Date(rawValue), timeBucket);
+		const groupMap = accumulator.get(key);
+		if (!groupMap) continue;
+		const group = groupByColumn ? getStringValue(item, groupByColumn) : "value";
+		const values = groupMap.get(group);
+		if (!values) continue;
+		if (metricColumn) {
+			const metricValue = metricColumn.accessor(item);
+			if (metricValue != null) values.push(metricValue);
+		} else values.push(1);
+	}
+	return {
+		data: allBuckets.map(({ key, label }) => {
+			const point = {
+				xLabel: label,
+				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);
+			return point;
+		}),
+		groups
+	};
+}
+/**
+* Build data points for a categorical or boolean X-axis.
+*
+* @param items - Filtered source data
+* @param xColumn - Active X-axis column
+* @param groupByColumn - Optional group-by column
+* @param groups - Resolved group labels
+* @param metric - Selected metric configuration
+* @param metricColumn - Resolved numeric metric column
+* @returns Aggregated category-bucketed data points
+*/
+function buildCategoryBuckets(items, xColumn, groupByColumn, groups, metric, metricColumn) {
+	const xValues = /* @__PURE__ */ new Set();
+	for (const item of items) xValues.add(getStringValue(item, xColumn));
+	const accumulator = /* @__PURE__ */ new Map();
+	for (const xValue of xValues) {
+		const groupMap = /* @__PURE__ */ new Map();
+		for (const group of groups) groupMap.set(group, []);
+		accumulator.set(xValue, groupMap);
+	}
+	for (const item of items) {
+		const xValue = getStringValue(item, xColumn);
+		const groupMap = accumulator.get(xValue);
+		if (!groupMap) continue;
+		const group = groupByColumn ? getStringValue(item, groupByColumn) : "value";
+		const values = groupMap.get(group);
+		if (!values) continue;
+		if (metricColumn) {
+			const metricValue = metricColumn.accessor(item);
+			if (metricValue != null) values.push(metricValue);
+		} else values.push(1);
+	}
+	return {
+		data: [...xValues].map((xValue) => {
+			const point = {
+				xLabel: xValue,
+				xKey: xValue
+			};
+			const groupMap = accumulator.get(xValue);
+			for (const group of groups) point[group] = aggregate(groupMap.get(group) ?? [], metric.kind === "aggregate" ? metric.aggregate : "count", metric.kind === "aggregate" ? metric.includeZeros ?? true : true);
+			return point;
+		}),
+		groups
+	};
+}
+//#endregion
+export { buildDataPoints };

package/dist/core/pipeline-helpers.mjs

@@ -0,0 +1,85 @@
+import { formatTimeBucketLabel } from "./formatting.mjs";
+//#region src/core/pipeline-helpers.ts
+/**
+* Shared helpers for the chart transformation pipeline.
+*/
+/**
+* Format a stable key for a date bucket.
+*
+* @param date - Source date
+* @param bucket - Time bucket granularity
+* @returns Machine-friendly bucket key
+*/
+function dateBucketKey(date, bucket) {
+	const year = date.getFullYear();
+	const month = date.getMonth();
+	switch (bucket) {
+		case "day": return `${year}-${String(month + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+		case "week": {
+			const day = date.getDay();
+			const monday = new Date(date);
+			monday.setDate(date.getDate() - (day + 6) % 7);
+			return `${monday.getFullYear()}-${String(monday.getMonth() + 1).padStart(2, "0")}-${String(monday.getDate()).padStart(2, "0")}`;
+		}
+		case "month": return `${year}-${String(month + 1).padStart(2, "0")}`;
+		case "quarter": return `${year}-Q${Math.floor(month / 3) + 1}`;
+		case "year": return `${year}`;
+	}
+}
+/**
+* Format a bucket key into a human-readable label.
+*
+* @param key - Bucket key
+* @param bucket - Time bucket granularity
+* @returns Display label for the chart axis
+*/
+function dateBucketLabel(key, bucket) {
+	return formatTimeBucketLabel(key, bucket, "axis");
+}
+/**
+* Extract a comparable string value from an item using a column definition.
+*
+* @param item - Raw data item
+* @param column - Column definition to read from
+* @returns String value used by filters and groups
+*/
+function getStringValue(item, column) {
+	switch (column.type) {
+		case "boolean": {
+			const value = column.accessor(item);
+			if (value === true) return column.trueLabel;
+			if (value === false) return column.falseLabel;
+			return "Unknown";
+		}
+		case "category": return column.accessor(item) ?? "Unknown";
+		case "date": {
+			const value = column.accessor(item);
+			return value != null ? String(value) : "Unknown";
+		}
+		case "number": {
+			const value = column.accessor(item);
+			return value != null ? String(value) : "Unknown";
+		}
+	}
+}
+/**
+* Aggregate numeric values using the requested function.
+*
+* @param values - Numeric values to aggregate
+* @param fn - Aggregation strategy
+* @param includeZeros - Whether zero values should participate in avg/min/max
+* @returns Aggregated numeric result
+*/
+function aggregate(values, fn, includeZeros = true) {
+	if (fn === "count") return values.length;
+	const effectiveValues = !includeZeros && fn !== "sum" ? values.filter((value) => value !== 0) : values;
+	if (effectiveValues.length === 0) return 0;
+	switch (fn) {
+		case "sum": return effectiveValues.reduce((sum, value) => sum + value, 0);
+		case "avg": return effectiveValues.reduce((sum, value) => sum + value, 0) / effectiveValues.length;
+		case "min": return Math.min(...effectiveValues);
+		case "max": return Math.max(...effectiveValues);
+	}
+}
+//#endregion
+export { aggregate, dateBucketKey, dateBucketLabel, getStringValue };

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

@@ -1,10 +1,6 @@
-/**
- * Data transformation pipeline.
- *
- * Pure functions that transform raw data into chart-ready format.
- * Pipeline: Raw Data -> Filter -> Bucket by X-axis -> Pivot by groupBy -> Aggregate -> Sort
- */
-import type { AvailableFilter, ChartColumn, ChartSeries, FilterState, Metric, SortConfig, TimeBucket, TransformedDataPoint } from './types.js';
+import { AvailableFilter, ChartColumn, ChartSeries, FilterState, Metric, SortConfig, TimeBucket, TransformedDataPoint } from "./types.mjs";
+
+//#region src/core/pipeline.d.ts
 /**
  * Input for the transformation pipeline.
  *
@@ -17,15 +13,15 @@ import type { AvailableFilter, ChartColumn, ChartSeries, FilterState, Metric, So
  * @property filters - Active filter state
  * @property sorting - Sort configuration
  */
-export type PipelineInput<T, TColumnId extends string = string> = {
-    data: readonly T[];
-    columns: readonly ChartColumn<T, TColumnId>[];
-    xAxisId: TColumnId;
-    groupById: TColumnId | null;
-    metric: Metric<TColumnId>;
-    timeBucket: TimeBucket;
-    filters: FilterState<TColumnId>;
-    sorting: SortConfig | null;
+type PipelineInput<T, TColumnId extends string = string> = {
+  data: readonly T[];
+  columns: readonly ChartColumn<T, TColumnId>[];
+  xAxisId: TColumnId;
+  groupById: TColumnId | null;
+  metric: Metric<TColumnId>;
+  timeBucket: TimeBucket;
+  filters: FilterState<TColumnId>;
+  sorting: SortConfig | null;
 };
 /**
  * Output of the transformation pipeline.
@@ -34,10 +30,10 @@ export type PipelineInput<T, TColumnId extends string = string> = {
  * @property series - Series definitions for rendering
  * @property groups - Unique group labels
  */
-export type PipelineOutput = {
-    data: TransformedDataPoint[];
-    series: ChartSeries[];
-    groups: string[];
+type PipelineOutput = {
+  data: TransformedDataPoint[];
+  series: ChartSeries[];
+  groups: string[];
 };
 /**
  * Apply active filters to the raw data.
@@ -48,7 +44,7 @@ export type PipelineOutput = {
  * @param filters - Active filter state
  * @returns Filtered data items
  */
-export declare function applyFilters<T, TColumnId extends string>(data: readonly T[], columns: readonly ChartColumn<T, TColumnId>[], filters: FilterState<TColumnId>): T[];
+declare function applyFilters<T, TColumnId extends string>(data: readonly T[], columns: readonly ChartColumn<T, TColumnId>[], filters: FilterState<TColumnId>): T[];
 /**
  * Run the full transformation pipeline.
  *
@@ -57,7 +53,7 @@ export declare function applyFilters<T, TColumnId extends string>(data: readonly
  * @param input - Pipeline configuration and source data
  * @returns Transformed data, series metadata, and group labels
  */
-export declare function runPipeline<T, TColumnId extends string>(input: PipelineInput<T, TColumnId>): PipelineOutput;
+declare function runPipeline<T, TColumnId extends string>(input: PipelineInput<T, TColumnId>): PipelineOutput;
 /**
  * Extract available filter options from data for every category and boolean
  * column.
@@ -66,5 +62,6 @@ export declare function runPipeline<T, TColumnId extends string>(input: Pipeline
  * @param columns - Column definitions
  * @returns Filter metadata and option counts per filterable column
  */
-export declare function extractAvailableFilters<T, TColumnId extends string>(data: readonly T[], columns: readonly ChartColumn<T, TColumnId>[]): AvailableFilter<TColumnId>[];
-//# sourceMappingURL=pipeline.d.ts.map
+declare function extractAvailableFilters<T, TColumnId extends string>(data: readonly T[], columns: readonly ChartColumn<T, TColumnId>[]): AvailableFilter<TColumnId>[];
+//#endregion
+export { PipelineInput, PipelineOutput, applyFilters, extractAvailableFilters, runPipeline };

package/dist/core/pipeline.mjs

@@ -0,0 +1,153 @@
+import { getSeriesColor } from "./colors.mjs";
+import { getMetricLabel } from "./metric-utils.mjs";
+import { formatChartValue } from "./formatting.mjs";
+import { getStringValue } from "./pipeline-helpers.mjs";
+import { buildDataPoints } from "./pipeline-data-points.mjs";
+//#region src/core/pipeline.ts
+/**
+* Data transformation pipeline.
+*
+* Pure functions that transform raw data into chart-ready format.
+* Pipeline: Raw Data -> Filter -> Bucket by X-axis -> Pivot by groupBy -> Aggregate -> Sort
+*/
+/**
+* Apply active filters to the raw data.
+* Filters are AND-combined across columns and OR-combined within a column.
+*
+* @param data - Raw data items
+* @param columns - Column definitions used to read values
+* @param filters - Active filter state
+* @returns Filtered data items
+*/
+function applyFilters(data, columns, filters) {
+	if (filters.size === 0) return [...data];
+	return data.filter((item) => {
+		for (const [columnId, activeValues] of filters) {
+			if (activeValues.size === 0) continue;
+			const column = columns.find((candidate) => candidate.id === columnId);
+			if (!column) continue;
+			if (!activeValues.has(getStringValue(item, column))) return false;
+		}
+		return true;
+	});
+}
+/**
+* Apply sorting to transformed data points.
+*
+* @param data - Aggregated chart data points
+* @param sorting - Explicit sort configuration
+* @param isTimeSeries - Whether the X-axis is date-based
+* @returns Sorted chart data points
+*/
+function applySorting(data, sorting, isTimeSeries) {
+	if (isTimeSeries) return data.toSorted((a, b) => String(a["xKey"]).localeCompare(String(b["xKey"])));
+	if (!sorting) return data.toSorted((a, b) => getPointTotal(b) - getPointTotal(a));
+	const direction = sorting.direction === "asc" ? 1 : -1;
+	return data.toSorted((a, b) => {
+		const aValue = a[sorting.key] ?? 0;
+		const bValue = b[sorting.key] ?? 0;
+		if (typeof aValue === "number" && typeof bValue === "number") return (aValue - bValue) * direction;
+		return String(aValue).localeCompare(String(bValue)) * direction;
+	});
+}
+/**
+* Sum all numeric series values for a transformed data point.
+*
+* @param point - Transformed chart data point
+* @returns Combined numeric total across series keys
+*/
+function getPointTotal(point) {
+	return Object.entries(point).filter(([key]) => key !== "xLabel" && key !== "xKey").reduce((sum, [, value]) => sum + (typeof value === "number" ? value : 0), 0);
+}
+/**
+* Build recharts series definitions from group labels.
+*
+* @param groups - Group labels returned by the pivot step
+* @param metricLabel - Human-readable label for the selected metric
+* @param useShadcn - Whether to use shadcn-compatible color variables
+* @returns Recharts series metadata
+*/
+function buildSeries(groups, metricLabel, useShadcn = true) {
+	return groups.map((group, index) => ({
+		dataKey: group,
+		label: group === "value" ? metricLabel : group,
+		color: getSeriesColor(index, useShadcn)
+	}));
+}
+/**
+* Run the full transformation pipeline.
+*
+* Raw Data -> Filter -> Bucket -> Pivot -> Aggregate -> Sort -> Output
+*
+* @param input - Pipeline configuration and source data
+* @returns Transformed data, series metadata, and group labels
+*/
+function runPipeline(input) {
+	const { data, columns, xAxisId, groupById, metric, timeBucket, filters, sorting } = input;
+	const xColumn = columns.find((column) => column.id === xAxisId);
+	if (!xColumn) return {
+		data: [],
+		series: [],
+		groups: []
+	};
+	const groupByColumn = groupById ? columns.find((column) => column.id === groupById) ?? null : null;
+	const numberColumns = columns.filter((column) => column.type === "number");
+	const { data: points, groups } = buildDataPoints(applyFilters(data, columns, filters), xColumn, groupByColumn, metric, numberColumns, timeBucket);
+	return {
+		data: applySorting(points, sorting, xColumn.type === "date"),
+		series: buildSeries(groups, getMetricLabel(metric, columns)),
+		groups
+	};
+}
+/**
+* Extract available filter options from data for every category and boolean
+* column.
+*
+* @param data - Raw data items
+* @param columns - Column definitions
+* @returns Filter metadata and option counts per filterable column
+*/
+function extractAvailableFilters(data, columns) {
+	return columns.filter((column) => column.type === "category" || column.type === "boolean").map((column) => {
+		const counts = /* @__PURE__ */ new Map();
+		for (const item of data) {
+			const value = getStringValue(item, column);
+			const formattedLabel = formatFilterOptionLabel(item, column);
+			const existing = counts.get(value);
+			if (existing) {
+				counts.set(value, {
+					count: existing.count + 1,
+					label: existing.label
+				});
+				continue;
+			}
+			counts.set(value, {
+				count: 1,
+				label: formattedLabel
+			});
+		}
+		return {
+			columnId: column.id,
+			label: column.label,
+			type: column.type,
+			options: [...counts.entries()].toSorted(([, left], [, right]) => right.count - left.count).map(([value, option]) => ({
+				value,
+				label: option.label,
+				count: option.count
+			}))
+		};
+	});
+}
+/**
+* Derive one human-facing filter option label from the typed column value while
+* keeping the underlying filter state keyed by the stable string value.
+*/
+function formatFilterOptionLabel(item, column) {
+	return formatChartValue(column.accessor(item), {
+		column,
+		surface: "tooltip",
+		item
+	});
+}
+//#endregion
+export { applyFilters, extractAvailableFilters, runPipeline };