@matthieumordrel/chart-studio 0.3.0 → 0.5.2

package/dist/core/define-dataset.d.mts

@@ -0,0 +1,13 @@
+import { DatasetBuilder, DatasetDefinition, ResolvedDatasetFromDefinition } from "./dataset-builder.types.mjs";
+
+//#region src/core/define-dataset.d.ts
+declare function validateDatasetData<TDataset extends DatasetDefinition<any, any, any>>(dataset: TDataset, rows: Parameters<ResolvedDatasetFromDefinition<TDataset>['validateData']>[0], datasetLabel?: string): void;
+/**
+ * Define one reusable dataset contract for columns, derived fields, and row identity.
+ *
+ * Dataset-owned `.columns(...)` is the canonical reusable meaning.
+ * Use `.chart(...)` to derive chart definitions from that shared contract.
+ */
+declare function defineDataset<TRow>(): DatasetBuilder<TRow, undefined, undefined>;
+//#endregion
+export { defineDataset, validateDatasetData };

package/dist/core/define-dataset.mjs

@@ -0,0 +1,111 @@
+import { COLUMN_HELPER, assertColumnEntries, buildColumnsMap, createDatasetChartBuilder } from "./schema-builder.mjs";
+//#region src/core/define-dataset.ts
+function normalizeDatasetKey(key) {
+	return Array.isArray(key) ? key : [key];
+}
+function formatKeyValue(value) {
+	return value.length === 1 ? String(value[0]) : `[${value.map((part) => String(part)).join(", ")}]`;
+}
+function buildKeyFingerprint(parts) {
+	return JSON.stringify(parts.map((part) => {
+		if (part instanceof Date) return {
+			type: "date",
+			value: part.toISOString()
+		};
+		return {
+			type: typeof part,
+			value: part
+		};
+	}));
+}
+function validateDatasetRows(key, rows, datasetLabel) {
+	if (!key || key.length === 0) return;
+	const seen = /* @__PURE__ */ new Map();
+	rows.forEach((row, index) => {
+		const parts = key.map((keyId) => row[keyId]);
+		const missingKeyId = parts.findIndex((part) => part == null);
+		if (missingKeyId >= 0) throw new Error(`Dataset "${datasetLabel}" key "${key.join(", ")}" is missing a value at row ${index} for "${key[missingKeyId]}".`);
+		const fingerprint = buildKeyFingerprint(parts);
+		if (seen.get(fingerprint)) throw new Error(`Dataset "${datasetLabel}" key "${key.join(", ")}" must be unique. Duplicate value: ${formatKeyValue(parts)}.`);
+		seen.set(fingerprint, parts);
+	});
+}
+function resolveDatasetDefinition(dataset) {
+	return dataset.build();
+}
+function validateDatasetData(dataset, rows, datasetLabel = "dataset") {
+	validateDatasetRows(resolveDatasetDefinition(dataset).key, rows, datasetLabel);
+}
+function createDefinedDataset(state) {
+	let cachedDataset;
+	const build = () => {
+		if (cachedDataset) return cachedDataset;
+		const definedDataset = {
+			...state.key !== void 0 ? { key: state.key } : {},
+			...state.columns !== void 0 ? { columns: state.columns } : {},
+			chart(id) {
+				return createDatasetChartBuilder({ ...state.columns !== void 0 ? { columns: state.columns } : {} }, {
+					dataset: definedDataset,
+					chartId: id
+				});
+			},
+			validateData(data) {
+				validateDatasetRows(state.key, data, "dataset");
+			},
+			build() {
+				return definedDataset;
+			},
+			__datasetBrand: "dataset-definition"
+		};
+		cachedDataset = definedDataset;
+		return definedDataset;
+	};
+	return build();
+}
+function createDatasetBuilder(state = {}) {
+	let cachedDataset;
+	const getOrBuildDataset = () => {
+		if (cachedDataset) return cachedDataset;
+		cachedDataset = createDefinedDataset(state);
+		return cachedDataset;
+	};
+	return {
+		key(keyOrKeys) {
+			return createDatasetBuilder({
+				...state,
+				key: normalizeDatasetKey(keyOrKeys)
+			});
+		},
+		columns(defineColumns) {
+			const entries = defineColumns(COLUMN_HELPER);
+			assertColumnEntries(entries, "defineDataset");
+			return createDatasetBuilder({
+				...state,
+				columns: buildColumnsMap(entries)
+			});
+		},
+		chart(id) {
+			return createDatasetChartBuilder({ ...state.columns !== void 0 ? { columns: state.columns } : {} }, {
+				dataset: getOrBuildDataset(),
+				chartId: id
+			});
+		},
+		validateData(data) {
+			validateDatasetRows(state.key, data, "dataset");
+		},
+		build() {
+			return getOrBuildDataset();
+		}
+	};
+}
+/**
+* Define one reusable dataset contract for columns, derived fields, and row identity.
+*
+* Dataset-owned `.columns(...)` is the canonical reusable meaning.
+* Use `.chart(...)` to derive chart definitions from that shared contract.
+*/
+function defineDataset() {
+	return createDatasetBuilder();
+}
+//#endregion
+export { defineDataset, resolveDatasetDefinition, validateDatasetData };

package/dist/core/formatting.d.mts

@@ -0,0 +1,49 @@
+import { ChartColumn, ColumnFormat, TimeBucket } from "./types.mjs";
+
+//#region src/core/formatting.d.ts
+/** Formatting surfaces exposed by the chart UI. */
+type ChartValueSurface = 'axis' | 'tooltip' | 'data-label' | 'table-cell' | 'raw';
+/** Numeric extent used to choose sensible default precision. */
+type NumericRange = {
+  min: number;
+  max: number;
+};
+type FormatColumnLike<T> = {
+  type: ChartColumn<T>['type'];
+  format?: ColumnFormat;
+  formatter?: ChartColumn<T>['formatter'];
+  trueLabel?: string;
+  falseLabel?: string;
+};
+type FormatValueOptions<T> = {
+  column: FormatColumnLike<T>;
+  surface: ChartValueSurface;
+  timeBucket?: TimeBucket;
+  numericRange?: NumericRange | null;
+  locale?: string;
+  item?: T;
+};
+/**
+ * Build a numeric range from chart values.
+ */
+declare function createNumericRange(values: readonly number[]): NumericRange | null;
+/**
+ * Decide whether an axis should keep decimal ticks for the current visible
+ * numeric values.
+ */
+declare function shouldAllowDecimalTicks(values: readonly number[]): boolean;
+/**
+ * Format one chart value for a specific UI surface.
+ */
+declare function formatChartValue<T>(value: string | number | boolean | Date | null | undefined, options: FormatValueOptions<T>): string;
+/**
+ * Format a date bucket label from the machine-friendly pipeline key.
+ */
+declare function formatTimeBucketLabel(key: string, bucket: TimeBucket, surface: ChartValueSurface, locale?: string): string;
+/**
+ * Format the Y-axis or label width estimate with the same surface rules used in
+ * the visible chart.
+ */
+declare function formatNumericSurfaceValue(value: number, surface: ChartValueSurface, numericRange?: NumericRange | null, format?: ColumnFormat, formatter?: ChartColumn<unknown>['formatter'], locale?: string): string;
+//#endregion
+export { ChartValueSurface, NumericRange, createNumericRange, formatChartValue, formatNumericSurfaceValue, formatTimeBucketLabel, shouldAllowDecimalTicks };

package/dist/core/formatting.mjs

@@ -54,7 +54,7 @@ function formatTimeBucketLabel(key, bucket, surface, locale = "en-US") {
 		case "day": return formatDateWithOptions(parseBucketDate(key), locale, getBucketDayOptions(surface));
 		case "week": {
 			const date = parseBucketDate(key);
-			return `${surface === "tooltip" ? "Week of " : "Wk of "}${formatDateWithOptions(date, locale, getBucketWeekOptions(surface))}`;
+			return `${isFullPrecisionSurface(surface) ? "Week of " : "Wk of "}${formatDateWithOptions(date, locale, getBucketWeekOptions(surface))}`;
 		}
 		case "month": return formatDateWithOptions(parseBucketMonth(key), locale, {
 			month: "short",
@@ -68,6 +68,22 @@ function formatTimeBucketLabel(key, bucket, surface, locale = "en-US") {
 	}
 }
 /**
+* Format the Y-axis or label width estimate with the same surface rules used in
+* the visible chart.
+*/
+function formatNumericSurfaceValue(value, surface, numericRange, format, formatter, locale = "en-US") {
+	return formatChartValue(value, {
+		column: {
+			type: "number",
+			format,
+			formatter
+		},
+		surface,
+		numericRange,
+		locale
+	});
+}
+/**
 * Resolve the boolean labels while keeping null handling in the shared entry
 * point above.
 */
@@ -176,17 +192,23 @@ function formatDateWithOptions(value, locale, options) {
 /**
 * Decide which number family should power the current surface.
 */
+/**
+* Surfaces that show full-precision values (not compacted).
+*/
+function isFullPrecisionSurface(surface) {
+	return surface === "tooltip" || surface === "table-cell";
+}
 function resolveNumberFormatMode(format, surface, numericRange, value) {
 	if (typeof format === "string") switch (format) {
-		case "currency": return surface === "tooltip" ? "currency" : "compact-currency";
+		case "currency": return isFullPrecisionSurface(surface) ? "currency" : "compact-currency";
 		case "compact-number": return "compact-number";
 		case "percent": return "percent";
 		case "number":
 		case "date":
-		case "datetime": return surface === "tooltip" ? "number" : shouldUseCompactNumber(numericRange, value) ? "compact-number" : "number";
+		case "datetime": return isFullPrecisionSurface(surface) ? "number" : shouldUseCompactNumber(numericRange, value) ? "compact-number" : "number";
 	}
 	if (shouldUsePercentByDefault(numericRange)) return "percent";
-	if (surface !== "tooltip" && shouldUseCompactNumber(numericRange, value)) return "compact-number";
+	if (!isFullPrecisionSurface(surface) && shouldUseCompactNumber(numericRange, value)) return "compact-number";
 	return "number";
 }
 /**
@@ -239,7 +261,7 @@ function getNumberFormatOptions(mode, surface, numericRange, value) {
 		};
 		case "percent": return {
 			style: "percent",
-			maximumFractionDigits: surface === "tooltip" ? 2 : 1
+			maximumFractionDigits: isFullPrecisionSurface(surface) ? 2 : 1
 		};
 		case "number": return { maximumFractionDigits: getStandardFractionDigits(surface, numericRange, value) };
 	}
@@ -249,7 +271,7 @@ function getNumberFormatOptions(mode, surface, numericRange, value) {
 */
 function getStandardFractionDigits(surface, numericRange, value) {
 	const span = numericRange ? Math.abs(numericRange.max - numericRange.min) : Math.abs(value);
-	if (surface === "tooltip") {
+	if (isFullPrecisionSurface(surface)) {
 		if (span < 1) return 3;
 		if (span < 10) return 2;
 		if (span < 100) return 1;
@@ -263,7 +285,7 @@ function getStandardFractionDigits(surface, numericRange, value) {
 * Match raw date values to a clear default display.
 */
 function getDateValueOptions(mode, surface) {
-	if (mode === "datetime") return surface === "tooltip" ? {
+	if (mode === "datetime") return isFullPrecisionSurface(surface) ? {
 		dateStyle: "medium",
 		timeStyle: "short"
 	} : {
@@ -300,7 +322,7 @@ function getBucketDateOptions(bucket, surface) {
 * Keep day buckets short on axes and clearer in tooltips.
 */
 function getBucketDayOptions(surface) {
-	return surface === "tooltip" ? {
+	return isFullPrecisionSurface(surface) ? {
 		month: "short",
 		day: "numeric",
 		year: "2-digit"
@@ -313,7 +335,7 @@ function getBucketDayOptions(surface) {
 * Keep week buckets short on axes and clearer in tooltips.
 */
 function getBucketWeekOptions(surface) {
-	return surface === "tooltip" ? {
+	return isFullPrecisionSurface(surface) ? {
 		month: "short",
 		day: "numeric",
 		year: "2-digit"
@@ -346,4 +368,4 @@ function parseQuarterKey(key) {
 	};
 }
 //#endregion
-export { createNumericRange, formatChartValue, formatTimeBucketLabel, shouldAllowDecimalTicks };
+export { createNumericRange, formatChartValue, formatNumericSurfaceValue, formatTimeBucketLabel, shouldAllowDecimalTicks };

package/dist/core/index.d.mts

@@ -0,0 +1,19 @@
+import { DATE_RANGE_PRESETS, DateRangePreset, DateRangePresetId, autoFilterForBucket, getPresetLabel, resolvePresetFilter } from "./date-range-presets.mjs";
+import { AggregateFunction, AggregateMetric, AggregateMetricAllowance, AvailableFilter, BooleanColumn, CategoricalChartType, CategoryColumn, ChartColumn, ChartColumnType, ChartControlMode, ChartDataScopeControlState, ChartDataScopeInputs, ChartDataScopeInputsFromSchemaDefinition, ChartDateRangeSelection, ChartInstance, ChartInstanceFromSchema, ChartInstanceFromSchemaDefinition, ChartSchema, ChartSchemaDefinition, ChartSeries, ChartSourceOptions, ChartType, ChartTypeConfig, ColumnFormat, ColumnFormatPreset, CountMetric, DateColumn, DateColumnFormat, DateRange, DateRangeFilter, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, DurationColumnFormat, DurationInputUnit, FilterState, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricAllowance, MetricConfig, MultiSourceChartDataScopeInputs, MultiSourceChartInstance, NumberColumn, NumberColumnFormat, NumericAggregateFunction, NumericAggregateSelection, RawColumnSchemaFor, RawColumnSchemaMap, ResolvedColumnIdFromSchema, ResolvedDateColumnIdFromSchema, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, RestrictedChartTypeFromSchema, RestrictedFilterColumnIdFromSchema, RestrictedGroupByColumnIdFromSchema, RestrictedMetricFromSchema, RestrictedTimeBucketFromSchema, RestrictedXAxisColumnIdFromSchema, SelectableControlConfig, SortConfig, SortDirection, TimeBucket, TimeBucketConfig, TimeSeriesChartType, TransformedDataPoint, ValidatedChartSchema, XAxisConfig } from "./types.mjs";
+import { CHART_TYPE_CONFIG, ChartAxisType, ChartTypeCapabilities } from "./chart-capabilities.mjs";
+import { buildColorMap, getSeriesColor } from "./colors.mjs";
+import { DATA_LABEL_DEFAULTS, DataLabelDefaults, DataLabelPosition, DataLabelStyle, resolveShowDataLabels } from "./data-label-defaults.mjs";
+import { computeDateRange, filterByDateRange } from "./date-utils.mjs";
+import { buildAvailableMetrics, getMetricLabel } from "./metric-utils.mjs";
+import { PipelineInput, PipelineOutput, applyFilters, extractAvailableFilters, runPipeline } from "./pipeline.mjs";
+import { DatasetBuilder, DatasetChartBuilder, DatasetChartDefinition, DatasetDefinition, DatasetKey, DatasetRow, DefinedDataset, DefinedDatasetChartSchema, SingleDatasetKeyId } from "./dataset-builder.types.mjs";
+import { DefinedMaterializedView, MaterializedProjectableColumnId, MaterializedViewDefinition, MaterializedViewMetadata, MaterializedViewStepMetadata, ModelMaterializationBuilder, ModelMaterializationStartBuilder } from "./materialized-view.types.mjs";
+import { DataModelBuilder, DataModelDefinition, DefinedDataModel, KeyedDatasetDefinition, ModelAssociationDefinition, ModelAttributeDefinition, ModelDataInput, ModelDatasetId, ModelRelationshipDefinition, ResolvedDataModelFromDefinition, SelectAttributeConfig } from "./data-model.types.mjs";
+import { defineDataModel } from "./define-data-model.mjs";
+import { DashboardBuilder, DashboardChartIdFromDefinition, DashboardChartInstanceFromDefinition, DashboardDataInputFromDefinition, DashboardDatasetIdFromDefinition, DashboardDatasetRowsFromDefinition, DashboardDateRangeSelection, DashboardDefinition, DashboardLocalSharedSelectFilterConfig, DashboardResolvedChart, DashboardResolvedChartOwnership, DashboardRuntime, DashboardSharedDateRangeFilterConfig, DashboardSharedDateRangeFilterDefinition, DashboardSharedDateRangeFilterRuntime, DashboardSharedDateRangePresetId, DashboardSharedDateRangeTarget, DashboardSharedFilterDefinition, DashboardSharedFilterIdFromDefinition, DashboardSharedFilterRuntime, DashboardSharedFilterRuntimeFromDefinition, DashboardSharedFilters, DashboardSharedSelectFilterRuntime, DashboardSharedSelectTarget, DefinedDashboard, ResolvedDashboardFromDefinition } from "./dashboard.types.mjs";
+import { defineDashboard, resolveDashboardDefinition } from "./define-dashboard.mjs";
+import { defineDataset, validateDatasetData } from "./define-dataset.mjs";
+import { inferColumnsFromData } from "./infer-columns.mjs";
+import { DashboardProvider, useDashboard, useDashboardChart, useDashboardContext, useDashboardDataset, useDashboardSharedFilter } from "./use-dashboard.mjs";
+import { UseChartOptions } from "./use-chart-options.mjs";
+import { useChart } from "./use-chart.mjs";

package/dist/core/infer-columns.mjs

@@ -215,7 +215,7 @@ function detectStringDateSignal(key, samples) {
 	return {
 		type: "category",
 		confidence: parseRatio >= .8 ? "medium" : "low",
-		looksDateLike: parseRatio >= .8
+		looksDateLike: strongPatternRatio >= .8 || parseRatio >= .8 && hasDateKeySignal
 	};
 }
 /**
@@ -461,6 +461,32 @@ function sortResolvedColumns(columns) {
 	});
 }
 /**
+* Reorder resolved columns so that schema-declared columns maintain their
+* declaration order while inferred-only columns keep their default sorted
+* positions.
+*
+* The algorithm first sorts all columns with the default heuristic, then
+* replaces the positions occupied by declared columns with those same
+* columns in schema declaration order. This preserves type-rank placement
+* for inferred columns while honouring the author's intent for explicitly
+* declared ones.
+*
+* When no schema columns are declared, all columns are sorted using the
+* default heuristic.
+*/
+function orderResolvedColumns(columns, schemaColumnOrder) {
+	const sorted = sortResolvedColumns(columns);
+	if (!schemaColumnOrder || schemaColumnOrder.length === 0) return sorted;
+	const declaredIds = new Set(schemaColumnOrder);
+	const declaredPositions = [];
+	for (let i = 0; i < sorted.length; i++) if (declaredIds.has(sorted[i].id)) declaredPositions.push(i);
+	const schemaOrderIndex = new Map(schemaColumnOrder.map((id, index) => [id, index]));
+	const declaredInSchemaOrder = sorted.filter((column) => declaredIds.has(column.id)).sort((a, b) => schemaOrderIndex.get(a.id) - schemaOrderIndex.get(b.id));
+	const result = [...sorted];
+	for (let i = 0; i < declaredPositions.length; i++) result[declaredPositions[i]] = declaredInSchemaOrder[i];
+	return result;
+}
+/**
 * Resolve chart columns directly from raw data and an optional explicit schema.
 */
 function inferColumnsFromData(data, schema) {
@@ -477,7 +503,7 @@ function inferColumnsFromData(data, schema) {
 	}
 	for (const [key, columnSchema] of getDerivedColumnSchemas(resolvedSchema, rawFieldIds)) resolvedColumns.push(buildDerivedColumn(key, columnSchema));
 	if (resolvedColumns.length === 0) warn("No inferable or explicit chart columns were found. Provide non-empty data or schema.columns.");
-	return finalizeResolvedColumns(sortResolvedColumns(resolvedColumns));
+	return finalizeResolvedColumns(orderResolvedColumns(resolvedColumns, resolvedSchema?.columns ? Object.keys(resolvedSchema.columns) : null));
 }
 //#endregion
 export { inferColumnsFromData };