@matthieumordrel/chart-studio 0.3.0 → 0.4.0

package/dist/core/define-dashboard.mjs

@@ -0,0 +1,156 @@
+import { DATASET_CHART_METADATA } from "./dataset-chart-metadata.mjs";
+//#region src/core/define-dashboard.ts
+function humanizeId(id) {
+	return id.replace(/[_-]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").trim().split(/\s+/).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function assertUniqueId(collection, kind, id) {
+	if (id in collection) throw new Error(`Duplicate ${kind} id: "${id}"`);
+}
+function getDatasetChartMetadata(chart) {
+	if (chart && typeof chart === "object" && DATASET_CHART_METADATA in chart) return chart[DATASET_CHART_METADATA];
+	if (chart && typeof chart === "object" && "build" in chart && typeof chart.build === "function") {
+		const built = chart.build();
+		if (built && typeof built === "object" && DATASET_CHART_METADATA in built) return built[DATASET_CHART_METADATA];
+	}
+}
+function findModelDatasetId(model, dataset) {
+	return Object.entries(model.datasets).find(([, candidate]) => candidate === dataset)?.[0];
+}
+function isMaterializedView(source) {
+	return !!source && typeof source === "object" && "__materializedViewBrand" in source && "materialization" in source && "build" in source && typeof source.build === "function";
+}
+function resolveChartDataSource(model, datasetOrView) {
+	const datasetId = findModelDatasetId(model, datasetOrView);
+	if (datasetId) return {
+		kind: "dataset",
+		datasetId
+	};
+	if (!isMaterializedView(datasetOrView)) return;
+	const view = datasetOrView;
+	const baseDatasetId = view.materialization.baseDataset;
+	if (!(baseDatasetId in model.datasets)) return;
+	return {
+		kind: "materialized-view",
+		datasetId: baseDatasetId,
+		view
+	};
+}
+function createDefinedDashboard(state) {
+	let cachedDashboard;
+	const build = () => {
+		if (cachedDashboard) return cachedDashboard;
+		const definedDashboard = {
+			model: state.model,
+			charts: state.charts,
+			sharedFilters: state.sharedFilters,
+			build() {
+				return definedDashboard;
+			},
+			__dashboardBrand: "dashboard-definition"
+		};
+		cachedDashboard = definedDashboard;
+		return definedDashboard;
+	};
+	return build();
+}
+function createDashboardBuilder(state) {
+	let cachedDashboard;
+	return {
+		chart(id, chart) {
+			assertUniqueId(state.charts, "dashboard chart", id);
+			const metadata = getDatasetChartMetadata(chart);
+			if (!metadata) throw new Error(`Dashboard chart "${id}" must come from defineDataset(...).chart(...).`);
+			if (metadata.chartId && metadata.chartId !== id) throw new Error(`Dashboard chart "${id}" does not match the chart authoring id "${metadata.chartId}".`);
+			const dataSource = resolveChartDataSource(state.model, metadata.dataset);
+			if (!dataSource) throw new Error(`Dashboard chart "${id}" references a dataset or materialized view that is not registered in this data model.`);
+			return createDashboardBuilder({
+				...state,
+				charts: {
+					...state.charts,
+					[id]: {
+						id,
+						datasetId: dataSource.datasetId,
+						schema: chart,
+						dataSource
+					}
+				}
+			});
+		},
+		sharedFilter(id, config) {
+			assertUniqueId(state.sharedFilters, "shared filter", id);
+			if (config === void 0) {
+				const attribute = state.model.attributes[id];
+				if (!attribute) throw new Error(`Unknown model attribute id: "${id}"`);
+				return createDashboardBuilder({
+					...state,
+					sharedFilters: {
+						...state.sharedFilters,
+						[id]: {
+							id,
+							kind: "select",
+							label: humanizeId(id),
+							source: {
+								kind: "attribute",
+								dataset: attribute.source.dataset,
+								key: attribute.source.key,
+								label: attribute.source.label
+							},
+							targets: attribute.targets,
+							attribute: id
+						}
+					}
+				});
+			}
+			if (config.kind === "select") return createDashboardBuilder({
+				...state,
+				sharedFilters: {
+					...state.sharedFilters,
+					[id]: {
+						id,
+						kind: "select",
+						label: config.label ?? humanizeId(id),
+						source: {
+							kind: "column",
+							dataset: config.source.dataset,
+							column: config.source.column
+						},
+						targets: config.targets ?? [{
+							dataset: config.source.dataset,
+							column: config.source.column
+						}]
+					}
+				}
+			});
+			if (!Array.isArray(config.targets) || config.targets.length === 0) throw new Error(`Dashboard shared date-range filter "${id}" requires at least one target.`);
+			return createDashboardBuilder({
+				...state,
+				sharedFilters: {
+					...state.sharedFilters,
+					[id]: {
+						id,
+						kind: "date-range",
+						label: config.label ?? humanizeId(id),
+						targets: config.targets
+					}
+				}
+			});
+		},
+		build() {
+			if (cachedDashboard) return cachedDashboard;
+			cachedDashboard = createDefinedDashboard(state);
+			return cachedDashboard;
+		}
+	};
+}
+function resolveDashboardDefinition(dashboard) {
+	return dashboard.build();
+}
+function defineDashboard(model) {
+	return createDashboardBuilder({
+		model: model.build(),
+		charts: {},
+		sharedFilters: {}
+	});
+}
+//#endregion
+export { defineDashboard, resolveDashboardDefinition };

package/dist/core/define-data-model.d.mts

@@ -0,0 +1,11 @@
+import { DataModelBuilder } from "./data-model.types.mjs";
+
+//#region src/core/define-data-model.d.ts
+/**
+ * Define one linked data model for dataset registration, relationships,
+ * associations, reusable model-level filter attributes, and explicit
+ * Phase 7 materialized views.
+ */
+declare function defineDataModel(): DataModelBuilder<{}, {}, {}, {}>;
+//#endregion
+export { defineDataModel };

package/dist/core/define-data-model.mjs

@@ -0,0 +1,327 @@
+import { resolveDatasetDefinition, validateDatasetData } from "./define-dataset.mjs";
+import { createMaterializationStartBuilder } from "./materialized-view.mjs";
+import { attachModelRuntimeMetadata, getModelRuntimeMetadata, inferModelAttributes, inferModelRelationships, rewriteInferredRelationshipError } from "./model-inference.mjs";
+import { compileModelChart } from "./model-chart.mjs";
+//#region src/core/define-data-model.ts
+function formatValue(value) {
+	if (value instanceof Date) return value.toISOString();
+	return String(value);
+}
+function buildFingerprint(value) {
+	if (value instanceof Date) return `date:${value.toISOString()}`;
+	return `${typeof value}:${String(value)}`;
+}
+function getSingleDatasetKey(dataset, datasetId) {
+	if (!dataset.key || dataset.key.length !== 1) throw new Error(`Dataset "${datasetId}" must declare exactly one key to participate in relationships or associations.`);
+	return dataset.key[0];
+}
+function assertUniqueId(collection, kind, id) {
+	if (id in collection) throw new Error(`Duplicate ${kind} id: "${id}"`);
+}
+function getDatasetOrThrow(datasets, datasetId) {
+	const dataset = datasets[datasetId];
+	if (!dataset) throw new Error(`Unknown dataset id: "${datasetId}"`);
+	return dataset;
+}
+function createKeyLookup(datasetId, keyId, rows) {
+	const values = /* @__PURE__ */ new Set();
+	rows.forEach((row, index) => {
+		const value = row[keyId];
+		if (value == null) throw new Error(`Dataset "${datasetId}" key "${keyId}" is missing a value at row ${index}.`);
+		values.add(buildFingerprint(value));
+	});
+	return {
+		keyId,
+		values
+	};
+}
+function validateRelationshipData(relationship, data, keyLookups) {
+	const toRows = data[relationship.to.dataset];
+	const sourceLookup = keyLookups[relationship.from.dataset]?.[relationship.from.key];
+	if (!sourceLookup) throw new Error(`Relationship "${relationship.id}" requires dataset "${relationship.from.dataset}" data.`);
+	if (!Array.isArray(toRows)) throw new Error(`Relationship "${relationship.id}" requires dataset "${relationship.to.dataset}" data.`);
+	toRows.forEach((row, index) => {
+		const value = row[relationship.to.column];
+		if (value == null) return;
+		if (!sourceLookup.values.has(buildFingerprint(value))) throw new Error(`Relationship "${relationship.id}" has an orphan foreign key "${formatValue(value)}" in dataset "${relationship.to.dataset}" column "${relationship.to.column}" at row ${index}.`);
+	});
+}
+function validateExplicitAssociationData(association, associationId, fromDatasetId, toDatasetId, fromLookup, toLookup) {
+	association.data.forEach((row, index) => {
+		const fromValue = row[association.columns.from];
+		const toValue = row[association.columns.to];
+		if (fromValue == null) throw new Error(`Association "${associationId}" is missing "${association.columns.from}" at edge row ${index}.`);
+		if (toValue == null) throw new Error(`Association "${associationId}" is missing "${association.columns.to}" at edge row ${index}.`);
+		if (!fromLookup.values.has(buildFingerprint(fromValue))) throw new Error(`Association "${associationId}" has an orphan "${association.columns.from}" value "${formatValue(fromValue)}" for dataset "${fromDatasetId}".`);
+		if (!toLookup.values.has(buildFingerprint(toValue))) throw new Error(`Association "${associationId}" has an orphan "${association.columns.to}" value "${formatValue(toValue)}" for dataset "${toDatasetId}".`);
+	});
+}
+function validateDerivedAssociationData(association, state, data, keyLookups) {
+	const derivedEdge = association.edge;
+	if (derivedEdge.kind !== "derived") return;
+	const deriveDatasetId = derivedEdge.deriveFrom.dataset;
+	const deriveRows = data[deriveDatasetId];
+	const deriveKeyId = getSingleDatasetKey(getDatasetOrThrow(state.datasets, deriveDatasetId), deriveDatasetId);
+	const oppositeDatasetId = deriveDatasetId === association.from.dataset ? association.to.dataset : association.from.dataset;
+	const oppositeKeyId = oppositeDatasetId === association.from.dataset ? association.from.key : association.to.key;
+	const oppositeLookup = keyLookups[oppositeDatasetId]?.[oppositeKeyId];
+	if (!oppositeLookup) throw new Error(`Association "${association.id}" requires dataset "${oppositeDatasetId}" data.`);
+	if (!Array.isArray(deriveRows)) throw new Error(`Association "${association.id}" requires dataset "${deriveDatasetId}" data.`);
+	deriveRows.forEach((row, index) => {
+		if (row[deriveKeyId] == null) throw new Error(`Association "${association.id}" source dataset "${deriveDatasetId}" is missing key "${deriveKeyId}" at row ${index}.`);
+		const rawValues = derivedEdge.deriveFrom.values(row) ?? [];
+		if (!Array.isArray(rawValues)) throw new Error(`Association "${association.id}" deriveFrom.values(...) must return an array.`);
+		rawValues.forEach((value) => {
+			if (value == null) throw new Error(`Association "${association.id}" deriveFrom.values(...) returned an empty key value.`);
+			if (!oppositeLookup.values.has(buildFingerprint(value))) throw new Error(`Association "${association.id}" has an orphan derived key "${formatValue(value)}" targeting dataset "${oppositeDatasetId}".`);
+		});
+	});
+}
+function validateAssociationData(association, state, data, keyLookups) {
+	const fromLookup = keyLookups[association.from.dataset]?.[association.from.key];
+	const toLookup = keyLookups[association.to.dataset]?.[association.to.key];
+	if (!fromLookup || !toLookup) throw new Error(`Association "${association.id}" requires both endpoint datasets to be present.`);
+	if (association.edge.kind === "explicit") {
+		validateExplicitAssociationData(association.edge, association.id, association.from.dataset, association.to.dataset, fromLookup, toLookup);
+		return;
+	}
+	validateDerivedAssociationData(association, state, data, keyLookups);
+}
+function validateModelRuntimeData(state, data) {
+	const keyLookups = {};
+	const requiredKeysByDataset = /* @__PURE__ */ new Map();
+	const addRequiredKey = (datasetId, keyId) => {
+		if (!keyId) return;
+		const existing = requiredKeysByDataset.get(datasetId);
+		if (existing) {
+			existing.add(keyId);
+			return;
+		}
+		requiredKeysByDataset.set(datasetId, new Set([keyId]));
+	};
+	Object.entries(state.datasets).forEach(([datasetId, dataset]) => {
+		const rows = data[datasetId];
+		if (!Array.isArray(rows)) throw new Error(`Missing dataset data for "${datasetId}".`);
+		validateDatasetData(dataset, rows, datasetId);
+	});
+	Object.values(state.relationships).forEach((relationship) => {
+		addRequiredKey(relationship.from.dataset, relationship.from.key);
+	});
+	Object.values(state.associations).forEach((association) => {
+		addRequiredKey(association.from.dataset, association.from.key);
+		addRequiredKey(association.to.dataset, association.to.key);
+	});
+	Object.values(state.attributes).forEach((attribute) => {
+		addRequiredKey(attribute.source.dataset, attribute.source.key);
+	});
+	Object.entries(state.datasets).forEach(([datasetId, dataset]) => {
+		if (dataset.key && dataset.key.length === 1) addRequiredKey(datasetId, dataset.key[0]);
+	});
+	requiredKeysByDataset.forEach((keyIds, datasetId) => {
+		const rows = data[datasetId];
+		if (!Array.isArray(rows)) throw new Error(`Missing dataset data for "${datasetId}".`);
+		keyLookups[datasetId] = {};
+		keyIds.forEach((keyId) => {
+			keyLookups[datasetId][keyId] = createKeyLookup(datasetId, keyId, rows);
+		});
+	});
+	Object.values(state.relationships).forEach((relationship) => {
+		validateRelationshipData(relationship, data, keyLookups);
+	});
+	Object.values(state.associations).forEach((association) => {
+		validateAssociationData(association, state, data, keyLookups);
+	});
+}
+function createDefinedDataModel(state) {
+	let cachedModel;
+	const build = () => {
+		if (cachedModel) return cachedModel;
+		const definedModel = {
+			datasets: state.datasets,
+			relationships: state.relationships,
+			associations: state.associations,
+			attributes: state.attributes,
+			materialize(id, defineView) {
+				return defineView(createMaterializationStartBuilder(id, definedModel));
+			},
+			chart(id, defineChart) {
+				return compileModelChart(definedModel, id, defineChart);
+			},
+			validateData(data) {
+				try {
+					validateModelRuntimeData(state, data);
+				} catch (error) {
+					rewriteInferredRelationshipError(getModelRuntimeMetadata(definedModel), error);
+				}
+			},
+			build() {
+				return definedModel;
+			},
+			__dataModelBrand: "data-model-definition"
+		};
+		attachModelRuntimeMetadata(definedModel, { inferredRelationships: new Map([...state.inferredRelationshipIds].map((relationshipId) => {
+			const relationship = state.relationships[relationshipId];
+			return [relationshipId, {
+				id: relationshipId,
+				fromDataset: relationship.from.dataset,
+				fromKey: relationship.from.key,
+				toDataset: relationship.to.dataset,
+				toColumn: relationship.to.column
+			}];
+		})) });
+		cachedModel = definedModel;
+		return definedModel;
+	};
+	return build();
+}
+function createDataModelBuilder(state = {
+	datasets: {},
+	relationships: {},
+	associations: {},
+	attributes: {},
+	inferredRelationshipIds: /* @__PURE__ */ new Set()
+}) {
+	let cachedModel;
+	return {
+		dataset(id, dataset) {
+			assertUniqueId(state.datasets, "dataset", id);
+			const resolvedDataset = resolveDatasetDefinition(dataset);
+			if (!resolvedDataset.key || resolvedDataset.key.length === 0) throw new Error(`Dataset "${id}" must declare a .key() before being added to a data model.`);
+			return createDataModelBuilder({
+				...state,
+				datasets: {
+					...state.datasets,
+					[id]: resolvedDataset
+				}
+			});
+		},
+		relationship(id, config) {
+			assertUniqueId(state.relationships, "relationship", id);
+			const fromKeyId = getSingleDatasetKey(getDatasetOrThrow(state.datasets, config.from.dataset), config.from.dataset);
+			getDatasetOrThrow(state.datasets, config.to.dataset);
+			if (config.from.key !== fromKeyId) throw new Error(`Relationship "${id}" must use declared key "${fromKeyId}" from dataset "${config.from.dataset}".`);
+			return createDataModelBuilder({
+				...state,
+				relationships: {
+					...state.relationships,
+					[id]: {
+						kind: "relationship",
+						id,
+						from: config.from,
+						to: config.to,
+						reverse: {
+							dataset: config.to.dataset,
+							column: config.to.column,
+							to: {
+								dataset: config.from.dataset,
+								key: config.from.key
+							}
+						}
+					}
+				}
+			});
+		},
+		association(id, config) {
+			assertUniqueId(state.associations, "association", id);
+			const fromDataset = getDatasetOrThrow(state.datasets, config.from.dataset);
+			const toDataset = getDatasetOrThrow(state.datasets, config.to.dataset);
+			const fromKeyId = getSingleDatasetKey(fromDataset, config.from.dataset);
+			const toKeyId = getSingleDatasetKey(toDataset, config.to.dataset);
+			if (config.from.key !== fromKeyId) throw new Error(`Association "${id}" must use declared key "${fromKeyId}" from dataset "${config.from.dataset}".`);
+			if (config.to.key !== toKeyId) throw new Error(`Association "${id}" must use declared key "${toKeyId}" from dataset "${config.to.dataset}".`);
+			if ("deriveFrom" in config) {
+				if (config.deriveFrom.dataset !== config.from.dataset && config.deriveFrom.dataset !== config.to.dataset) throw new Error(`Association "${id}" deriveFrom.dataset must match either "${config.from.dataset}" or "${config.to.dataset}".`);
+			}
+			return createDataModelBuilder({
+				...state,
+				associations: {
+					...state.associations,
+					[id]: {
+						kind: "association",
+						id,
+						from: config.from,
+						to: config.to,
+						reverse: {
+							dataset: config.to.dataset,
+							key: config.to.key,
+							to: {
+								dataset: config.from.dataset,
+								key: config.from.key
+							}
+						},
+						edge: "deriveFrom" in config ? {
+							kind: "derived",
+							deriveFrom: config.deriveFrom
+						} : {
+							kind: "explicit",
+							data: config.data,
+							columns: config.columns
+						}
+					}
+				}
+			});
+		},
+		attribute(id, config) {
+			assertUniqueId(state.attributes, "attribute", id);
+			return createDataModelBuilder({
+				...state,
+				attributes: {
+					...state.attributes,
+					[id]: {
+						id,
+						kind: config.kind,
+						source: config.source,
+						targets: config.targets
+					}
+				}
+			});
+		},
+		infer(options) {
+			const nextRelationships = options.relationships === true ? inferModelRelationships(state.datasets, state.relationships, new Set(options.exclude ?? [])) : {
+				relationships: state.relationships,
+				metadata: { inferredRelationships: /* @__PURE__ */ new Map() }
+			};
+			const nextAttributes = options.attributes === true ? inferModelAttributes(state.datasets, nextRelationships.relationships, state.attributes) : state.attributes;
+			return createDataModelBuilder({
+				...state,
+				relationships: nextRelationships.relationships,
+				attributes: nextAttributes,
+				inferredRelationshipIds: new Set([...state.inferredRelationshipIds, ...nextRelationships.metadata.inferredRelationships.keys()])
+			});
+		},
+		chart(id, defineChart) {
+			const model = cachedModel ?? createDefinedDataModel(state);
+			cachedModel = model;
+			return compileModelChart(model, id, defineChart);
+		},
+		materialize(id, defineView) {
+			const model = cachedModel ?? createDefinedDataModel(state);
+			cachedModel = model;
+			return defineView(createMaterializationStartBuilder(id, model));
+		},
+		validateData(data) {
+			try {
+				validateModelRuntimeData(state, data);
+			} catch (error) {
+				const model = cachedModel ?? createDefinedDataModel(state);
+				cachedModel = model;
+				rewriteInferredRelationshipError(getModelRuntimeMetadata(model), error);
+			}
+		},
+		build() {
+			if (cachedModel) return cachedModel;
+			cachedModel = createDefinedDataModel(state);
+			return cachedModel;
+		}
+	};
+}
+/**
+* Define one linked data model for dataset registration, relationships,
+* associations, reusable model-level filter attributes, and explicit
+* Phase 7 materialized views.
+*/
+function defineDataModel() {
+	return createDataModelBuilder();
+}
+//#endregion
+export { defineDataModel };

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/index.d.mts

@@ -0,0 +1,17 @@
+import { DateRangePresetId } 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 { 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 { buildAvailableMetrics, getMetricLabel } from "./metric-utils.mjs";
+import { PipelineInput, PipelineOutput, applyFilters, extractAvailableFilters, runPipeline } from "./pipeline.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";