@matthieumordrel/chart-studio 0.2.5 → 0.4.0

package/dist/core/schema-builder.mjs

@@ -1,7 +1,6 @@
-import { isSameMetric, normalizeMetricAllowances } from "./metric-utils.mjs";
+import { createMetricBuilder, createSelectableControlBuilder, getMetricBuilderConfig, getSelectableControlConfig } from "./chart-builder-controls.mjs";
+import { DATASET_CHART_METADATA } from "./dataset-chart-metadata.mjs";
 //#region src/core/schema-builder.ts
-const SELECTABLE_CONTROL_CONFIG = Symbol("chart-schema-selectable-control-config");
-const METRIC_CONTROL_CONFIG = Symbol("chart-schema-metric-config");
 const COLUMN_HELPER = {
 	field(id, options = {}) {
 		return {
@@ -104,141 +103,6 @@ const COLUMN_HELPER = {
 		}
 	}
 };
-function uniqueValues(values) {
-	if (!values || values.length === 0) return;
-	return [...new Set(values)];
-}
-function sanitizeSelectableControlConfig(config, supportsDefault) {
-	const allowed = uniqueValues(config.allowed);
-	let hidden = uniqueValues(config.hidden);
-	if (allowed && hidden) {
-		const allowedSet = new Set(allowed);
-		hidden = hidden.filter((option) => allowedSet.has(option));
-	}
-	let nextDefault = supportsDefault ? config.default : void 0;
-	if (nextDefault !== void 0) {
-		if (allowed && !allowed.includes(nextDefault)) nextDefault = void 0;
-		if (nextDefault !== void 0 && hidden?.includes(nextDefault)) nextDefault = void 0;
-	}
-	const nextConfig = {};
-	if (allowed && allowed.length > 0) nextConfig.allowed = allowed;
-	if (hidden && hidden.length > 0) nextConfig.hidden = hidden;
-	if (nextDefault !== void 0) nextConfig.default = nextDefault;
-	return nextConfig;
-}
-function createSelectableControlBuilder(config = {}, supportsDefault) {
-	const nextConfig = sanitizeSelectableControlConfig(config, supportsDefault);
-	return {
-		allowed(...options) {
-			return createSelectableControlBuilder({
-				...nextConfig,
-				allowed: options
-			}, supportsDefault);
-		},
-		hidden(...options) {
-			return createSelectableControlBuilder({
-				...nextConfig,
-				hidden: [...nextConfig.hidden ?? [], ...options]
-			}, supportsDefault);
-		},
-		default(option) {
-			return createSelectableControlBuilder({
-				...nextConfig,
-				default: option
-			}, supportsDefault);
-		},
-		[SELECTABLE_CONTROL_CONFIG]: nextConfig
-	};
-}
-function uniqueMetrics(metrics) {
-	if (!metrics || metrics.length === 0) return;
-	const unique = [];
-	for (const metric of metrics) if (!unique.some((candidate) => isSameMetric(candidate, metric))) unique.push(metric);
-	return unique;
-}
-function sanitizeMetricConfig(config) {
-	const allowed = config.allowed && config.allowed.length > 0 ? [...config.allowed] : void 0;
-	let hidden = uniqueMetrics(config.hidden);
-	const expandedAllowed = normalizeMetricAllowances(allowed);
-	if (expandedAllowed && hidden) hidden = hidden.filter((metric) => expandedAllowed.some((allowedMetric) => isSameMetric(allowedMetric, metric)));
-	let nextDefault = config.default;
-	if (nextDefault) {
-		const defaultMetric = nextDefault;
-		if (expandedAllowed && !expandedAllowed.some((metric) => isSameMetric(metric, defaultMetric))) nextDefault = void 0;
-		if (nextDefault) {
-			const visibleDefault = nextDefault;
-			if (hidden?.some((metric) => isSameMetric(metric, visibleDefault))) nextDefault = void 0;
-		}
-	}
-	const nextConfig = {};
-	if (allowed && allowed.length > 0) nextConfig.allowed = allowed;
-	if (hidden && hidden.length > 0) nextConfig.hidden = hidden;
-	if (nextDefault) nextConfig.default = nextDefault;
-	return nextConfig;
-}
-function createMetricBuilder(config = {}) {
-	const nextConfig = sanitizeMetricConfig(config);
-	return {
-		count() {
-			return createMetricBuilder({
-				...nextConfig,
-				allowed: [...nextConfig.allowed ?? [], { kind: "count" }]
-			});
-		},
-		aggregate(columnId, firstAggregate, ...restAggregates) {
-			const aggregates = [firstAggregate, ...restAggregates];
-			const selection = restAggregates.length === 0 ? firstAggregate : aggregates;
-			return createMetricBuilder({
-				...nextConfig,
-				allowed: [...nextConfig.allowed ?? [], {
-					kind: "aggregate",
-					columnId,
-					aggregate: selection
-				}]
-			});
-		},
-		hideCount() {
-			return createMetricBuilder({
-				...nextConfig,
-				hidden: [...nextConfig.hidden ?? [], { kind: "count" }]
-			});
-		},
-		hideAggregate(columnId, firstAggregate, ...restAggregates) {
-			const aggregates = [firstAggregate, ...restAggregates];
-			return createMetricBuilder({
-				...nextConfig,
-				hidden: [...nextConfig.hidden ?? [], ...aggregates.map((aggregate) => ({
-					kind: "aggregate",
-					columnId,
-					aggregate
-				}))]
-			});
-		},
-		defaultCount() {
-			return createMetricBuilder({
-				...nextConfig,
-				default: { kind: "count" }
-			});
-		},
-		defaultAggregate(columnId, aggregate) {
-			return createMetricBuilder({
-				...nextConfig,
-				default: {
-					kind: "aggregate",
-					columnId,
-					aggregate
-				}
-			});
-		},
-		[METRIC_CONTROL_CONFIG]: nextConfig
-	};
-}
-function getSelectableControlConfig(builder) {
-	return builder[SELECTABLE_CONTROL_CONFIG];
-}
-function getMetricBuilderConfig(builder) {
-	return builder[METRIC_CONTROL_CONFIG];
-}
 function buildColumnsMap(entries) {
 	const columns = {};
 	for (const entry of entries) {
@@ -247,69 +111,62 @@ function buildColumnsMap(entries) {
 	}
 	return columns;
 }
-function assertColumnEntries(entries) {
-	if (!Array.isArray(entries)) throw new TypeError("defineChartSchema().columns(...) must return an array of column entries.");
+function assertColumnEntries(entries, owner = "defineDataset") {
+	if (!Array.isArray(entries)) throw new TypeError(`${owner}().columns(...) must return an array of column entries.`);
 }
 function resolveChartSchemaDefinition(schema) {
 	if (!schema) return;
 	if (typeof schema === "object" && "build" in schema && typeof schema.build === "function") return schema.build();
 	return schema;
 }
-function createChartSchemaBuilder(state = {}) {
+function createDatasetChartBuilder(state = {}, metadata) {
 	let cachedSchema;
-	return {
-		columns(defineColumns) {
-			const entries = defineColumns(COLUMN_HELPER);
-			assertColumnEntries(entries);
-			return createChartSchemaBuilder({
-				...state,
-				columns: buildColumnsMap(entries)
-			});
-		},
+	const createNext = (nextState) => createDatasetChartBuilder(nextState, metadata);
+	const builder = {
 		xAxis(defineXAxis) {
 			const builder = defineXAxis(createSelectableControlBuilder({}, true));
-			return createChartSchemaBuilder({
+			return createNext({
 				...state,
 				xAxis: getSelectableControlConfig(builder)
 			});
 		},
 		groupBy(defineGroupBy) {
 			const builder = defineGroupBy(createSelectableControlBuilder({}, true));
-			return createChartSchemaBuilder({
+			return createNext({
 				...state,
 				groupBy: getSelectableControlConfig(builder)
 			});
 		},
 		filters(defineFilters) {
 			const builder = defineFilters(createSelectableControlBuilder({}, false));
-			return createChartSchemaBuilder({
+			return createNext({
 				...state,
 				filters: getSelectableControlConfig(builder)
 			});
 		},
 		metric(defineMetric) {
 			const builder = defineMetric(createMetricBuilder());
-			return createChartSchemaBuilder({
+			return createNext({
 				...state,
 				metric: getMetricBuilderConfig(builder)
 			});
 		},
 		chartType(defineChartType) {
 			const builder = defineChartType(createSelectableControlBuilder({}, true));
-			return createChartSchemaBuilder({
+			return createNext({
 				...state,
 				chartType: getSelectableControlConfig(builder)
 			});
 		},
 		timeBucket(defineTimeBucket) {
 			const builder = defineTimeBucket(createSelectableControlBuilder({}, true));
-			return createChartSchemaBuilder({
+			return createNext({
 				...state,
 				timeBucket: getSelectableControlConfig(builder)
 			});
 		},
 		connectNulls(value) {
-			return createChartSchemaBuilder({
+			return createNext({
 				...state,
 				connectNulls: value
 			});
@@ -327,9 +184,22 @@ function createChartSchemaBuilder(state = {}) {
 				...state.connectNulls !== void 0 ? { connectNulls: state.connectNulls } : {},
 				__chartSchemaBrand: "chart-schema-definition"
 			};
+			if (metadata) Object.defineProperty(cachedSchema, DATASET_CHART_METADATA, {
+				value: metadata,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			});
 			return cachedSchema;
 		}
 	};
+	if (metadata) Object.defineProperty(builder, DATASET_CHART_METADATA, {
+		value: metadata,
+		enumerable: false,
+		configurable: false,
+		writable: false
+	});
+	return builder;
 }
 //#endregion
-export { createChartSchemaBuilder, resolveChartSchemaDefinition };
+export { COLUMN_HELPER, assertColumnEntries, buildColumnsMap, createDatasetChartBuilder, resolveChartSchemaDefinition };

package/dist/core/schema-builder.types.d.mts

@@ -1,4 +1,4 @@
-import { BaseColumnHint, ChartType, ChartTypeConfig, CountMetric, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricConfig, NumericAggregateFunction, RawColumnSchemaFor, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, TimeBucket, TimeBucketConfig, XAxisConfig } from "./types.mjs";
+import { BaseColumnHint, ChartTypeConfig, CountMetric, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricConfig, NumericAggregateFunction, RawColumnSchemaFor, TimeBucketConfig, XAxisConfig } from "./types.mjs";
 
 //#region src/core/schema-builder.types.d.ts
 type Nullish = null | undefined;
@@ -7,9 +7,6 @@ type Simplify<T> = { [TKey in keyof T]: T[TKey] } & {};
 type NonEmptyReadonlyArray<TValue> = readonly [TValue, ...TValue[]];
 type FieldKeyMatchingValue<T, TValue> = Extract<{ [TKey in InferableFieldKey<T>]-?: [NonNullish<T[TKey]>] extends [TValue] ? TKey : never }[InferableFieldKey<T>], string>;
 type ReplaceConfigValue<TConfig, TKey extends PropertyKey, TValue> = Simplify<Omit<TConfig, TKey> & { [TProperty in TKey]: TValue }>;
-type SchemaColumnsContext<TColumns extends Record<string, unknown> | undefined> = [TColumns] extends [undefined] ? undefined : {
-  columns?: TColumns;
-};
 type AppendConfigValue<TConfig, TKey extends PropertyKey, TValue> = Simplify<Omit<TConfig, TKey> & { [TProperty in TKey]: TConfig extends Record<TKey, infer TExisting extends readonly unknown[]> ? readonly [...TExisting, TValue] : readonly [TValue] }>;
 type AppendManyConfigValues<TConfig, TKey extends PropertyKey, TValues extends readonly unknown[]> = Simplify<Omit<TConfig, TKey> & { [TProperty in TKey]: TConfig extends Record<TKey, infer TExisting extends readonly unknown[]> ? readonly [...TExisting, ...TValues] : TValues }>;
 type AggregateSelectionFromList<TAggregates extends readonly NumericAggregateFunction[]> = TAggregates extends readonly [infer TOnlyAggregate extends NumericAggregateFunction] ? TOnlyAggregate : TAggregates;
@@ -231,49 +228,5 @@ type SchemaFromBuilder<TColumns extends Record<string, unknown> | undefined, TXA
   timeBucket?: Extract<TTimeBucket, TimeBucketConfig | undefined>;
   connectNulls?: Extract<TConnectNulls, boolean | undefined>;
 };
-type ChartSchemaBuilder<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TXAxis extends XAxisConfig<any> | undefined = undefined, TGroupBy extends GroupByConfig<any> | undefined = undefined, TFilters extends FiltersConfig<any> | undefined = undefined, TMetric extends MetricConfig<any> | undefined = undefined, TChartType extends ChartTypeConfig | undefined = undefined, TTimeBucket extends TimeBucketConfig | undefined = undefined, TConnectNulls extends boolean | undefined = undefined> = {
-  /**
-   * Declare explicit raw and derived columns for this schema.
-   *
-   * Place this early in the chain so later sections can narrow against the
-   * final column ids and roles.
-   */
-  columns: TColumns extends undefined ? <const TEntries extends readonly SchemaColumnEntry<TRow>[]>(defineColumns: (columns: ColumnHelper<TRow>) => TEntries & ValidateColumnEntries<TEntries>) => ChartSchemaBuilder<TRow, ColumnsFromEntries<TRow, TEntries>, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls> : never;
-  /**
-   * Configure which columns may appear on the X-axis.
-   */
-  xAxis<const TBuilder extends SelectableControlBuilder<ResolvedXAxisColumnIdFromSchema<TRow, SchemaColumnsContext<TColumns>>, true>>(defineXAxis: (xAxis: SelectableControlBuilder<ResolvedXAxisColumnIdFromSchema<TRow, SchemaColumnsContext<TColumns>>, true>) => TBuilder): ChartSchemaBuilder<TRow, TColumns, SelectableControlBuilderConfig<TBuilder>, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls>;
-  /**
-   * Configure which columns may split the chart into series.
-   */
-  groupBy<const TBuilder extends SelectableControlBuilder<ResolvedGroupByColumnIdFromSchema<TRow, SchemaColumnsContext<TColumns>>, true>>(defineGroupBy: (groupBy: SelectableControlBuilder<ResolvedGroupByColumnIdFromSchema<TRow, SchemaColumnsContext<TColumns>>, true>) => TBuilder): ChartSchemaBuilder<TRow, TColumns, TXAxis, SelectableControlBuilderConfig<TBuilder>, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls>;
-  /**
-   * Configure which columns may appear in the filters UI.
-   */
-  filters<const TBuilder extends SelectableControlBuilder<ResolvedFilterColumnIdFromSchema<TRow, SchemaColumnsContext<TColumns>>, false>>(defineFilters: (filters: SelectableControlBuilder<ResolvedFilterColumnIdFromSchema<TRow, SchemaColumnsContext<TColumns>>, false>) => TBuilder): ChartSchemaBuilder<TRow, TColumns, TXAxis, TGroupBy, SelectableControlBuilderConfig<TBuilder>, TMetric, TChartType, TTimeBucket, TConnectNulls>;
-  /**
-   * Configure the public metric surface.
-   */
-  metric<const TBuilder extends MetricBuilder<ResolvedMetricColumnIdFromSchema<TRow, SchemaColumnsContext<TColumns>>, any, any, any>>(defineMetric: (metric: MetricBuilder<ResolvedMetricColumnIdFromSchema<TRow, SchemaColumnsContext<TColumns>>>) => TBuilder): ChartSchemaBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, MetricBuilderConfig<TBuilder>, TChartType, TTimeBucket, TConnectNulls>;
-  /**
-   * Restrict which chart renderers are exposed to users.
-   */
-  chartType<const TBuilder extends SelectableControlBuilder<ChartType, true>>(defineChartType: (chartType: SelectableControlBuilder<ChartType, true>) => TBuilder): ChartSchemaBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, SelectableControlBuilderConfig<TBuilder>, TTimeBucket, TConnectNulls>;
-  /**
-   * Restrict which time buckets are exposed for date X-axes.
-   */
-  timeBucket<const TBuilder extends SelectableControlBuilder<TimeBucket, true>>(defineTimeBucket: (timeBucket: SelectableControlBuilder<TimeBucket, true>) => TBuilder): ChartSchemaBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, SelectableControlBuilderConfig<TBuilder>, TConnectNulls>;
-  /**
-   * Control whether line and area charts visually bridge null gaps.
-   *
-   * `true` keeps the line connected across missing buckets. `false` shows a
-   * visible gap.
-   */
-  connectNulls<const TValue extends boolean>(value: TValue): ChartSchemaBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TValue>;
-  /**
-   * Finalize the schema into the runtime object consumed by `useChart(...)`.
-   */
-  build(): DefinedChartSchema<TRow, SchemaFromBuilder<TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls>>;
-};
 //#endregion
-export { ChartSchemaBuilder };
+export { ColumnHelper, ColumnsFromEntries, MetricBuilder, MetricBuilderConfig, SchemaColumnEntry, SchemaFromBuilder, SelectableControlBuilder, SelectableControlBuilderConfig, ValidateColumnEntries };

package/dist/core/types.d.mts

@@ -497,15 +497,21 @@ type ChartSchemaValidationTarget<T, TSchema extends ChartSchema<T, any>> = {
   chartType?: ChartTypeConfig;
   timeBucket?: TimeBucketConfig;
 };
-/** Strict schema object returned by `defineChartSchema(...)`. */
+/** Strict schema object returned by a chart schema builder. */
 type ValidatedChartSchema<T, TSchema> = TSchema extends ChartSchema<T, any> ? TSchema & ExactShape<ChartSchemaValidationTarget<T, TSchema>, TSchema> & ValidateChartSchemaLiterals<T, TSchema> : TSchema;
-/** Strict schema object returned by `defineChartSchema(...)`. */
+/** Strict schema object returned by a chart schema builder. */
 type DefinedChartSchema<T, TSchema extends ChartSchema<T, any> = ChartSchema<T, any>> = TSchema & ChartSchemaDefinitionBrand;
 /**
  * Public schema definition input accepted by chart-studio APIs.
  *
- * Most callers use the fluent builder returned by `defineChartSchema<Row>()`.
- * Plain schema objects are also accepted at the runtime boundary.
+ * In the simple single-chart case this is the contract for
+ * `useChart({data, schema})`.
+ *
+ * Most callers use the dataset-backed chart builder from
+ * `defineDataset<Row>().chart(...)`.
+ *
+ * Builders can be passed directly. Plain schema objects are also accepted at
+ * the runtime boundary.
  */
 type ChartSchemaDefinition<T, TSchema extends ChartSchema<T, any> = ChartSchema<T, any>> = TSchema | {
   build: () => DefinedChartSchema<T, TSchema>;
@@ -741,6 +747,8 @@ type ChartSchemaDefinitionBrand = {
  * - For boolean columns: true/false/null (null = no filter)
  */
 type FilterState<TColumnId extends string = string> = Map<TColumnId, Set<string>>;
+/** Whether one chart input slice is owned externally or by the hook itself. */
+type ChartControlMode = 'controlled' | 'uncontrolled';
 /** Sort direction. */
 type SortDirection = 'asc' | 'desc';
 /**
@@ -836,6 +844,37 @@ type DateRangeFilter = {
   from: Date | null;
   to: Date | null;
 };
+/**
+ * Requested date-range selection for externally driven chart inputs.
+ *
+ * When `preset` is non-null, the effective `dateRangeFilter` is derived from
+ * that preset and `customFilter` is simply preserved for later custom mode.
+ */
+type ChartDateRangeSelection = {
+  preset: DateRangePresetId | null;
+  customFilter: DateRangeFilter | null;
+};
+/**
+ * Optional externally driven inputs for the chart's data scope.
+ *
+ * Provide a value to control that slice. Omit it to let `useChart(...)` own
+ * the state internally. Callbacks fire for both controlled and uncontrolled
+ * usage; in controlled mode they are the only way setters can request changes.
+ */
+type ChartDataScopeInputs<TFilterColumnId extends string = string, TDateColumnId extends string = string> = {
+  filters?: FilterState<TFilterColumnId>;
+  onFiltersChange?: (filters: FilterState<TFilterColumnId>) => void;
+  referenceDateId?: TDateColumnId | null;
+  onReferenceDateIdChange?: (columnId: TDateColumnId | null) => void;
+  dateRange?: ChartDateRangeSelection;
+  onDateRangeChange?: (selection: ChartDateRangeSelection) => void;
+};
+/** Controlled/uncontrolled status for each data-scope slice. */
+type ChartDataScopeControlState = {
+  filters: ChartControlMode;
+  referenceDateId: ChartControlMode;
+  dateRange: ChartControlMode;
+};
 /**
  * Full chart state returned by the useChart hook.
  * Contains both controlled state and derived computations.
@@ -879,7 +918,12 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
   availableGroupBys: Array<{
     id: TGroupById;
     label: string;
-  }>; /** Current metric (what the Y-axis measures). */
+  }>;
+  /**
+   * Whether groupBy can be set to `null` (no grouping).
+   * False when the schema forces a default that always resolves to a column.
+   */
+  isGroupByOptional: boolean; /** Current metric (what the Y-axis measures). */
   metric: TMetric;
   /**
    * Change the metric.
@@ -899,7 +943,8 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
    * Whether line and area charts connect across null data points.
    * Derived from the schema's `connectNulls` option.
    */
-  connectNulls: boolean; /** Active filter values per column. */
+  connectNulls: boolean; /** Which data-scope slices are externally controlled vs chart-owned. */
+  dataScopeControl: ChartDataScopeControlState; /** Active filter values per column after runtime sanitization for the active source. */
   filters: FilterState<TFilterColumnId>;
   /**
    * Toggle a specific filter value on/off for a column.
@@ -911,7 +956,7 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
   availableFilters: AvailableFilter<TFilterColumnId>[]; /** Current sort configuration (null = default order). */
   sorting: SortConfig | null; /** Change sorting. */
   setSorting: (sorting: SortConfig | null) => void; /** Date range for the active reference date column (computed from filtered data). */
-  dateRange: DateRange<TDateColumnId> | null; /** Which date column provides the visible date range context. */
+  dateRange: DateRange<TDateColumnId> | null; /** Which date column provides the visible date range context after source-local fallback. */
   referenceDateId: TDateColumnId | null;
   /**
    * Change the reference date column.
@@ -946,6 +991,8 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
 type ChartInstanceFromSchema<T, TSchema extends ChartSchema<T, any> | undefined = undefined> = ChartInstance<T, ResolvedColumnIdFromSchema<T, TSchema>, RestrictedChartTypeFromSchema<TSchema>, RestrictedXAxisColumnIdFromSchema<T, TSchema>, RestrictedGroupByColumnIdFromSchema<T, TSchema>, Extract<MetricColumnIdFromMetric<RestrictedMetricFromSchema<T, TSchema>>, ResolvedMetricColumnIdFromSchema<T, TSchema>>, RestrictedMetricFromSchema<T, TSchema>, RestrictedFilterColumnIdFromSchema<T, TSchema>, ResolvedDateColumnIdFromSchema<T, TSchema>, RestrictedTimeBucketFromSchema<TSchema>>;
 /** Single-source chart instance narrowed by any supported schema input. */
 type ChartInstanceFromSchemaDefinition<T, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> = ChartInstanceFromSchema<T, ResolvedChartSchemaFromDefinition<TSchema>>;
+/** Data-scope input typing for one single-source chart definition. */
+type ChartDataScopeInputsFromSchemaDefinition<T, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> = ChartDataScopeInputs<RestrictedFilterColumnIdFromSchema<T, ResolvedChartSchemaFromDefinition<TSchema>>, ResolvedDateColumnIdFromSchema<T, ResolvedChartSchemaFromDefinition<TSchema>>>;
 type SourceIdFromSource<TSource extends AnyChartSourceOptions> = TSource['id'];
 type SourceRowFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, any> ? TRow : never;
 type SourceColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? ResolvedColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
@@ -956,6 +1003,8 @@ type SourceFilterColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSo
 type SourceDateColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? ResolvedDateColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
 type SourceIdFromSources<TSources extends NonEmptyChartSourceOptions> = Extract<TSources[number]['id'], string>;
 type SourceColumnIdFromSources<TSources extends NonEmptyChartSourceOptions> = TSources[number] extends infer TSource ? TSource extends AnyChartSourceOptions ? SourceColumnIdFromSource<TSource> : never : never;
+type SourceFilterColumnIdFromSources<TSources extends NonEmptyChartSourceOptions> = TSources[number] extends infer TSource ? TSource extends AnyChartSourceOptions ? SourceFilterColumnIdFromSource<TSource> : never : never;
+type SourceDateColumnIdFromSources<TSources extends NonEmptyChartSourceOptions> = TSources[number] extends infer TSource ? TSource extends AnyChartSourceOptions ? SourceDateColumnIdFromSource<TSource> : never : never;
 type MultiSourceChartBranch<TSources extends NonEmptyChartSourceOptions, TSource extends AnyChartSourceOptions> = Omit<ChartInstance<SourceRowFromSource<TSource>, SourceColumnIdFromSources<TSources>>, 'activeSourceId' | 'setActiveSource' | 'sources' | 'xAxisId' | 'setXAxis' | 'availableXAxes' | 'groupById' | 'setGroupBy' | 'availableGroupBys' | 'metric' | 'setMetric' | 'availableMetrics' | 'filters' | 'toggleFilter' | 'clearFilter' | 'availableFilters' | 'dateRange' | 'referenceDateId' | 'setReferenceDateId' | 'availableDateColumns' | 'columns'> & {
   activeSourceId: SourceIdFromSource<TSource>;
   setActiveSource: (sourceId: SourceIdFromSources<TSources>) => void;
@@ -997,5 +1046,7 @@ type MultiSourceChartBranch<TSources extends NonEmptyChartSourceOptions, TSource
  * Narrow on `activeSourceId` to recover the source-specific row and column IDs.
  */
 type MultiSourceChartInstance<TSources extends NonEmptyChartSourceOptions> = TSources[number] extends infer TSource ? TSource extends AnyChartSourceOptions ? MultiSourceChartBranch<TSources, TSource> : never : never;
+/** Data-scope input typing for one multi-source source-switching chart. */
+type MultiSourceChartDataScopeInputs<TSources extends NonEmptyChartSourceOptions> = ChartDataScopeInputs<SourceFilterColumnIdFromSources<TSources>, SourceDateColumnIdFromSources<TSources>>;
 //#endregion
-export { AggregateFunction, AggregateMetric, AvailableFilter, BaseColumnHint, BooleanColumn, CategoricalChartType, CategoryColumn, ChartColumn, ChartColumnType, ChartInstance, ChartInstanceFromSchema, ChartInstanceFromSchemaDefinition, ChartSchema, ChartSchemaDefinition, ChartSeries, ChartSourceOptions, ChartType, ChartTypeConfig, ColumnFormat, ColumnFormatPreset, CountMetric, DateColumn, DateColumnFormat, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, FilterState, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricConfig, MultiSourceChartInstance, NonEmptyChartSourceOptions, NumberColumn, NumberColumnFormat, NumericAggregateFunction, RawColumnSchemaFor, RawColumnSchemaMap, ResolvedChartSchemaFromDefinition, ResolvedColumnIdFromSchema, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, RestrictedChartTypeFromSchema, RestrictedFilterColumnIdFromSchema, RestrictedGroupByColumnIdFromSchema, RestrictedMetricFromSchema, RestrictedTimeBucketFromSchema, RestrictedXAxisColumnIdFromSchema, SelectableControlConfig, SortConfig, SortDirection, TimeBucket, TimeBucketConfig, TimeSeriesChartType, TransformedDataPoint, ValidatedChartSchema, XAxisConfig };
+export { AggregateFunction, AggregateMetric, AggregateMetricAllowance, AvailableFilter, BaseColumnHint, BooleanColumn, CategoricalChartType, CategoryColumn, ChartColumn, ChartColumnType, ChartControlMode, ChartDataScopeControlState, ChartDataScopeInputs, ChartDataScopeInputsFromSchemaDefinition, ChartDateRangeSelection, ChartInstance, ChartInstanceFromSchema, ChartInstanceFromSchemaDefinition, ChartSchema, ChartSchemaDefinition, ChartSeries, ChartSourceOptions, ChartType, ChartTypeConfig, ColumnFormat, ColumnFormatPreset, ColumnHintFor, CountMetric, DateColumn, DateColumnFormat, DateRange, DateRangeFilter, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, DurationColumnFormat, DurationInputUnit, FilterState, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricAllowance, MetricConfig, MultiSourceChartDataScopeInputs, MultiSourceChartInstance, NonEmptyChartSourceOptions, NumberColumn, NumberColumnFormat, NumericAggregateFunction, NumericAggregateSelection, RawColumnSchemaFor, RawColumnSchemaMap, ResolvedChartSchemaFromDefinition, ResolvedColumnIdFromSchema, ResolvedDateColumnIdFromSchema, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, RestrictedChartTypeFromSchema, RestrictedFilterColumnIdFromSchema, RestrictedGroupByColumnIdFromSchema, RestrictedMetricFromSchema, RestrictedTimeBucketFromSchema, RestrictedXAxisColumnIdFromSchema, SelectableControlConfig, SortConfig, SortDirection, TimeBucket, TimeBucketConfig, TimeSeriesChartType, TransformedDataPoint, ValidatedChartSchema, XAxisConfig };

package/dist/core/use-chart-options.d.mts

@@ -1,11 +1,11 @@
-import { ChartSchemaDefinition, ChartSourceOptions, NonEmptyChartSourceOptions } from "./types.mjs";
+import { ChartDataScopeInputsFromSchemaDefinition, ChartSchemaDefinition, ChartSourceOptions, MultiSourceChartDataScopeInputs, NonEmptyChartSourceOptions } from "./types.mjs";
 
 //#region src/core/use-chart-options.d.ts
 /**
  * Single-source options for `useChart(...)`.
  *
- * This is the common case: one dataset, one optional schema, one optional
- * human-readable source label.
+ * This is the stable chart-first path:
+ * one dataset, one optional schema, one chart.
  */
 interface SingleSourceOptions<T, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> {
   /**
@@ -18,8 +18,11 @@ interface SingleSourceOptions<T, TSchema extends ChartSchemaDefinition<T, any> |
   /**
    * Optional explicit schema layered on top of inference.
    *
-   * Usually this is the fluent builder returned by `defineChartSchema<Row>()`.
-   * Plain schema objects are also accepted.
+   * Usually this is the dataset-backed chart builder from
+   * `defineDataset<Row>().chart(...)`.
+   *
+   * Builders can be passed directly without calling `.build()`. Plain schema
+   * objects are also accepted.
    *
    * Use this when you want to:
    * - rename fields with `label`
@@ -28,6 +31,9 @@ interface SingleSourceOptions<T, TSchema extends ChartSchemaDefinition<T, any> |
    * - exclude fields
    * - create derived columns
    * - restrict what users can select in the chart UI
+   *
+   * Unspecified raw fields still participate through inference unless you
+   * explicitly exclude them.
    */
   schema?: TSchema;
   /**
@@ -36,18 +42,39 @@ interface SingleSourceOptions<T, TSchema extends ChartSchemaDefinition<T, any> |
    * Example: `'Jobs'`, `'Quarterly Financials'`, or `'Pipeline Health'`.
    */
   sourceLabel?: string;
+  /**
+   * Optional externally driven data-scope inputs for this one chart.
+   *
+   * This is additive:
+   * `useChart({data})` and `useChart({data, schema})` stay the simple chart-first paths.
+   *
+   * Only data-scope state belongs here:
+   * filters, reference-date selection, and date-range selection.
+   *
+   * Presentation controls such as `xAxis`, `groupBy`, `metric`, and
+   * `chartType` remain chart-local.
+   */
+  inputs?: ChartDataScopeInputsFromSchemaDefinition<T, TSchema>;
   sources?: never;
 }
 /**
  * Multi-source options for `useChart(...)`.
  *
- * Use this when the user should be able to switch between several datasets that
- * may each have their own schema.
+ * Use this for source-switching within one chart. It is separate from the
+ * single-source `useChart({data, schema})` contract and is not dashboard
+ * composition.
  */
 interface MultiSourceOptions<TSources extends NonEmptyChartSourceOptions = NonEmptyChartSourceOptions> {
   data?: never;
   schema?: never;
   sourceLabel?: never;
+  /**
+   * Optional externally driven data-scope inputs for one source-switching chart.
+   *
+   * These inputs are chart-level and sanitize against the active source at
+   * runtime. They do not turn `sources` into dashboard composition.
+   */
+  inputs?: MultiSourceChartDataScopeInputs<TSources>;
   /**
    * Named list of chart sources.
    *
@@ -64,4 +91,4 @@ interface MultiSourceOptions<TSources extends NonEmptyChartSourceOptions = NonEm
  */
 type UseChartOptions<T, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> = SingleSourceOptions<T, TSchema> | MultiSourceOptions;
 //#endregion
-export { SingleSourceOptions, UseChartOptions };
+export { MultiSourceOptions, SingleSourceOptions, UseChartOptions };

package/dist/core/use-chart-resolvers.mjs

@@ -1,5 +1,12 @@
 //#region src/core/use-chart-resolvers.ts
 /**
+* Clone filter state so callers can safely derive the next map without sharing
+* mutable `Set` instances.
+*/
+function cloneFilterState(filters) {
+	return new Map([...filters].map(([columnId, values]) => [columnId, new Set(values)]));
+}
+/**
 * Resolve the active X-axis, preferring date columns first.
 */
 function resolveXAxisId(xAxisId, activeColumns) {
@@ -21,14 +28,17 @@ function resolveReferenceDateId(referenceDateIdRaw, dateColumns, resolvedXAxisId
 /**
 * Remove filters that target columns not present in the active source.
 */
-function sanitizeFilters(filters, activeColumns) {
+function sanitizeFilters(filters, activeColumns, availableValues) {
 	const validColumnIds = new Set(activeColumns.map((column) => column.id));
 	const next = /* @__PURE__ */ new Map();
 	for (const [columnId, values] of filters) {
 		if (!validColumnIds.has(columnId)) continue;
-		next.set(columnId, new Set(values));
+		const allowedValues = availableValues?.get(columnId);
+		const sanitizedValues = allowedValues ? new Set([...values].filter((value) => allowedValues.has(value))) : new Set(values);
+		if (sanitizedValues.size === 0) continue;
+		next.set(columnId, sanitizedValues);
 	}
 	return next;
 }
 //#endregion
-export { resolveReferenceDateId, resolveXAxisId, sanitizeFilters };
+export { cloneFilterState, resolveReferenceDateId, resolveXAxisId, sanitizeFilters };

package/dist/core/use-chart.d.mts

@@ -1,13 +1,18 @@
 import { ChartInstanceFromSchemaDefinition, ChartSchemaDefinition, MultiSourceChartInstance, NonEmptyChartSourceOptions } from "./types.mjs";
-import { SingleSourceOptions } from "./use-chart-options.mjs";
+import { MultiSourceOptions, SingleSourceOptions } from "./use-chart-options.mjs";
 
 //#region src/core/use-chart.d.ts
 /**
- * Headless React hook that manages all chart configuration, state, and derived/transformed data for chart rendering.
+ * Headless React hook that manages one chart's configuration, state, and
+ * derived/transformed data for rendering.
  *
- * There are two major usage patterns:
- * - Single source: Provide plain `data` and optional `schema`.
- * - Multi-source: Provide a `sources` array, each having an `id`, `label`, `data`, and optional `schema`.
+ * The stable primary path is single-source:
+ * - `useChart({data})` for zero-config inference
+ * - `useChart({data, schema})` when one chart needs an explicit contract
+ *
+ * Multi-source `sources` support exists for source-switching between
+ * interchangeable datasets, but it is intentionally separate from the
+ * single-chart schema contract and is not dashboard composition.
  *
  * @template T - The type of each data record in the dataset.
  * @template TSchema - Optional explicit schema for inferred single-source columns.
@@ -15,8 +20,11 @@ import { SingleSourceOptions } from "./use-chart-options.mjs";
  *   Chart configuration options. Should provide either:
  *   - `data`, optional `schema`, and (optionally) `sourceLabel` for a single source
  *   - or `sources` array for multiple sources
+ *   - and optional `inputs` when filters/reference-date/date-range state is
+ *     driven externally
  *   Any explicit single-source or per-source schema is usually authored with
- *   `defineChartSchema<Row>()...`. Plain schema objects are also accepted.
+ *   `defineDataset<Row>().chart(...)`.
+ *   Builders can be passed directly; plain schema objects are also accepted.
  *
  * @returns {ChartInstance}
  *   An object representing chart configuration, state, and all derived data/operations:
@@ -30,6 +38,7 @@ import { SingleSourceOptions } from "./use-chart-options.mjs";
  *   - `metric`, `setMetric`, `availableMetrics`: Current aggregation metric, setter, and options
  *   - `timeBucket`, `setTimeBucket`, `availableTimeBuckets`: Date/time bucketing state, setter, and options
  *   - `isTimeSeries`: Whether the chart is a time series (based on axis)
+ *   - `dataScopeControl`: Which data-scope slices are controlled externally
  *   - `filters`, `toggleFilter`, `clearFilter`, `clearAllFilters`, `availableFilters`: Current filters and their controls
  *   - `sorting`, `setSorting`: Current sorting config and setter
  *   - `dateRange`, `referenceDateId`, `setReferenceDateId`, `availableDateColumns`, `dateRangeFilter`, `setDateRangeFilter`: Date filtering state and controls
@@ -39,12 +48,7 @@ import { SingleSourceOptions } from "./use-chart-options.mjs";
  *   - `rawData`: The raw input data for the active data source
  *   - `recordCount`: Number of records present in the current data source
  */
-declare function useChart<const TSources extends NonEmptyChartSourceOptions>(options: {
-  data?: never;
-  schema?: never;
-  sourceLabel?: never;
-  sources: TSources;
-}): MultiSourceChartInstance<TSources>;
+declare function useChart<const TSources extends NonEmptyChartSourceOptions>(options: MultiSourceOptions<TSources>): MultiSourceChartInstance<TSources>;
 declare function useChart<T, const TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined>(options: SingleSourceOptions<T, TSchema>): ChartInstanceFromSchemaDefinition<T, TSchema>;
 //#endregion
 export { useChart };