@matthieumordrel/chart-studio 0.2.4 → 0.2.5

package/dist/core/schema-builder.mjs

@@ -0,0 +1,335 @@
+import { isSameMetric, normalizeMetricAllowances } from "./metric-utils.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 {
+			kind: "raw",
+			id,
+			column: options
+		};
+	},
+	date(id, options = {}) {
+		return {
+			kind: "raw",
+			id,
+			column: {
+				type: "date",
+				...options
+			}
+		};
+	},
+	category(id, options = {}) {
+		return {
+			kind: "raw",
+			id,
+			column: {
+				type: "category",
+				...options
+			}
+		};
+	},
+	number(id, options = {}) {
+		return {
+			kind: "raw",
+			id,
+			column: {
+				type: "number",
+				...options
+			}
+		};
+	},
+	boolean(id, options = {}) {
+		return {
+			kind: "raw",
+			id,
+			column: {
+				type: "boolean",
+				...options
+			}
+		};
+	},
+	exclude(id) {
+		return {
+			kind: "exclude",
+			id,
+			column: false
+		};
+	},
+	derived: {
+		date(id, options) {
+			return {
+				kind: "derived",
+				id,
+				column: {
+					kind: "derived",
+					type: "date",
+					...options
+				}
+			};
+		},
+		category(id, options) {
+			return {
+				kind: "derived",
+				id,
+				column: {
+					kind: "derived",
+					type: "category",
+					...options
+				}
+			};
+		},
+		boolean(id, options) {
+			return {
+				kind: "derived",
+				id,
+				column: {
+					kind: "derived",
+					type: "boolean",
+					...options
+				}
+			};
+		},
+		number(id, options) {
+			return {
+				kind: "derived",
+				id,
+				column: {
+					kind: "derived",
+					type: "number",
+					...options
+				}
+			};
+		}
+	}
+};
+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) {
+		if (entry.id in columns) throw new Error(`Duplicate chart schema column id: "${entry.id}"`);
+		columns[entry.id] = entry.column;
+	}
+	return columns;
+}
+function assertColumnEntries(entries) {
+	if (!Array.isArray(entries)) throw new TypeError("defineChartSchema().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 = {}) {
+	let cachedSchema;
+	return {
+		columns(defineColumns) {
+			const entries = defineColumns(COLUMN_HELPER);
+			assertColumnEntries(entries);
+			return createChartSchemaBuilder({
+				...state,
+				columns: buildColumnsMap(entries)
+			});
+		},
+		xAxis(defineXAxis) {
+			const builder = defineXAxis(createSelectableControlBuilder({}, true));
+			return createChartSchemaBuilder({
+				...state,
+				xAxis: getSelectableControlConfig(builder)
+			});
+		},
+		groupBy(defineGroupBy) {
+			const builder = defineGroupBy(createSelectableControlBuilder({}, true));
+			return createChartSchemaBuilder({
+				...state,
+				groupBy: getSelectableControlConfig(builder)
+			});
+		},
+		filters(defineFilters) {
+			const builder = defineFilters(createSelectableControlBuilder({}, false));
+			return createChartSchemaBuilder({
+				...state,
+				filters: getSelectableControlConfig(builder)
+			});
+		},
+		metric(defineMetric) {
+			const builder = defineMetric(createMetricBuilder());
+			return createChartSchemaBuilder({
+				...state,
+				metric: getMetricBuilderConfig(builder)
+			});
+		},
+		chartType(defineChartType) {
+			const builder = defineChartType(createSelectableControlBuilder({}, true));
+			return createChartSchemaBuilder({
+				...state,
+				chartType: getSelectableControlConfig(builder)
+			});
+		},
+		timeBucket(defineTimeBucket) {
+			const builder = defineTimeBucket(createSelectableControlBuilder({}, true));
+			return createChartSchemaBuilder({
+				...state,
+				timeBucket: getSelectableControlConfig(builder)
+			});
+		},
+		connectNulls(value) {
+			return createChartSchemaBuilder({
+				...state,
+				connectNulls: value
+			});
+		},
+		build() {
+			if (cachedSchema) return cachedSchema;
+			cachedSchema = {
+				...state.columns !== void 0 ? { columns: state.columns } : {},
+				...state.xAxis !== void 0 ? { xAxis: state.xAxis } : {},
+				...state.groupBy !== void 0 ? { groupBy: state.groupBy } : {},
+				...state.filters !== void 0 ? { filters: state.filters } : {},
+				...state.metric !== void 0 ? { metric: state.metric } : {},
+				...state.chartType !== void 0 ? { chartType: state.chartType } : {},
+				...state.timeBucket !== void 0 ? { timeBucket: state.timeBucket } : {},
+				...state.connectNulls !== void 0 ? { connectNulls: state.connectNulls } : {},
+				__chartSchemaBrand: "chart-schema-definition"
+			};
+			return cachedSchema;
+		}
+	};
+}
+//#endregion
+export { createChartSchemaBuilder, resolveChartSchemaDefinition };

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

@@ -0,0 +1,279 @@
+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";
+
+//#region src/core/schema-builder.types.d.ts
+type Nullish = null | undefined;
+type NonNullish<T> = Exclude<T, Nullish>;
+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;
+type MetricColumnIdFromMetric<TMetric> = Extract<TMetric extends {
+  kind: 'aggregate';
+  columnId: infer TColumnId extends string;
+} ? TColumnId : never, string>;
+type MetricAggregateFromMetric<TMetric, TColumnId extends string> = Extract<Extract<TMetric, {
+  kind: 'aggregate';
+  columnId: TColumnId;
+}> extends {
+  aggregate: infer TAggregate extends NumericAggregateFunction;
+} ? TAggregate : never, NumericAggregateFunction>;
+type AggregateMetricUnionFromSelection<TColumnId extends string, TAggregates extends readonly NumericAggregateFunction[]> = { [TIndex in keyof TAggregates]: TAggregates[TIndex] extends NumericAggregateFunction ? {
+  kind: 'aggregate';
+  columnId: TColumnId;
+  aggregate: TAggregates[TIndex];
+} : never }[number];
+type AggregateMetricTupleFromSelection<TColumnId extends string, TAggregates extends readonly NumericAggregateFunction[]> = TAggregates extends readonly [infer THead extends NumericAggregateFunction, ...infer TTail extends NumericAggregateFunction[]] ? readonly [{
+  kind: 'aggregate';
+  columnId: TColumnId;
+  aggregate: THead;
+}, ...AggregateMetricTupleFromSelection<TColumnId, TTail>] : readonly [];
+type SelectableMetricUnion<TMetricColumnId extends string, TAllowedMetric> = [TAllowedMetric] extends [never] ? Metric<TMetricColumnId> : TAllowedMetric;
+type VisibleMetricUnion<TMetricColumnId extends string, TAllowedMetric, THiddenMetric> = Exclude<SelectableMetricUnion<TMetricColumnId, TAllowedMetric>, THiddenMetric>;
+type DerivedColumnId<TRow, TColumnId extends string> = TColumnId extends InferableFieldKey<TRow> ? never : TColumnId;
+type ColumnEntryId<TEntry> = TEntry extends {
+  id: infer TId extends string;
+} ? TId : never;
+type DuplicateColumnIds<TEntries extends readonly unknown[], TSeen extends string = never> = TEntries extends readonly [infer THead, ...infer TTail] ? ColumnEntryId<THead> extends TSeen ? ColumnEntryId<THead> | DuplicateColumnIds<TTail, TSeen> : DuplicateColumnIds<TTail, TSeen | ColumnEntryId<THead>> : never;
+type DuplicateColumnIdError<TColumnId extends string> = {
+  __columnBuilderError__: `Duplicate column id "${TColumnId}"`;
+};
+type StringFieldKey<T> = FieldKeyMatchingValue<T, string>;
+type NumberFieldKey<T> = FieldKeyMatchingValue<T, number>;
+type BooleanFieldKey<T> = FieldKeyMatchingValue<T, boolean>;
+type DateLikeFieldKey<T> = Extract<{ [TKey in InferableFieldKey<T>]-?: [NonNullish<T[TKey]>] extends [string | number | Date] ? TKey : never }[InferableFieldKey<T>], string>;
+type SharedColumnOptions<TRow, TValue> = BaseColumnHint<TRow, TValue>;
+type FieldColumnOptions<TRow, TFieldId extends InferableFieldKey<TRow>> = RawColumnSchemaFor<TRow[TFieldId], TRow>;
+type DateColumnOptions<TRow> = SharedColumnOptions<TRow, string | number | Date>;
+type CategoryColumnOptions<TRow> = SharedColumnOptions<TRow, string>;
+type NumberColumnOptions<TRow> = SharedColumnOptions<TRow, number>;
+type BooleanColumnOptions<TRow> = SharedColumnOptions<TRow, boolean> & {
+  trueLabel?: string;
+  falseLabel?: string;
+};
+type DerivedDateColumnOptions<TRow> = Omit<DerivedDateColumnSchema<TRow>, 'kind' | 'type'>;
+type DerivedCategoryColumnOptions<TRow> = Omit<DerivedCategoryColumnSchema<TRow>, 'kind' | 'type'>;
+type DerivedBooleanColumnOptions<TRow> = Omit<DerivedBooleanColumnSchema<TRow>, 'kind' | 'type'>;
+type DerivedNumberColumnOptions<TRow> = Omit<DerivedNumberColumnSchema<TRow>, 'kind' | 'type'>;
+type RawFieldColumnEntry<TRow, TFieldId extends InferableFieldKey<TRow>, TColumn> = {
+  readonly kind: 'raw';
+  readonly id: TFieldId;
+  readonly column: TColumn;
+};
+type ExcludedFieldColumnEntry<TRow, TFieldId extends InferableFieldKey<TRow>> = {
+  readonly kind: 'exclude';
+  readonly id: TFieldId;
+  readonly column: false;
+};
+type DerivedColumnEntry<TRow, TColumnId extends string, TColumn extends DerivedDateColumnSchema<TRow> | DerivedCategoryColumnSchema<TRow> | DerivedBooleanColumnSchema<TRow> | DerivedNumberColumnSchema<TRow>> = {
+  readonly kind: 'derived';
+  readonly id: TColumnId;
+  readonly column: TColumn;
+};
+type SchemaColumnEntry<TRow> = RawFieldColumnEntry<TRow, InferableFieldKey<TRow>, unknown> | ExcludedFieldColumnEntry<TRow, InferableFieldKey<TRow>> | DerivedColumnEntry<TRow, string, DerivedDateColumnSchema<TRow> | DerivedCategoryColumnSchema<TRow> | DerivedBooleanColumnSchema<TRow> | DerivedNumberColumnSchema<TRow>>;
+type ValidateColumnEntries<TEntries extends readonly unknown[]> = [DuplicateColumnIds<TEntries>] extends [never] ? unknown : DuplicateColumnIdError<Extract<DuplicateColumnIds<TEntries>, string>>;
+type ColumnsFromEntries<TRow, TEntries extends readonly SchemaColumnEntry<TRow>[]> = Simplify<{ [TEntry in TEntries[number] as TEntry['id']]: TEntry['column'] }>;
+interface ColumnHelper<TRow> {
+  /**
+   * Override one existing raw field using the raw-field schema surface.
+   *
+   * Use this when you want the full hint surface for a field, including type
+   * overrides on string/number columns.
+   */
+  field<const TFieldId extends InferableFieldKey<TRow>>(id: TFieldId, options?: FieldColumnOptions<TRow, TFieldId>): RawFieldColumnEntry<TRow, TFieldId, FieldColumnOptions<TRow, TFieldId>>;
+  /**
+   * Treat one raw field as a date column.
+   *
+   * Supports raw `string`, `number`, and `Date` fields that should behave as a
+   * time-series axis.
+   */
+  date<const TFieldId extends DateLikeFieldKey<TRow>>(id: TFieldId, options?: DateColumnOptions<TRow>): RawFieldColumnEntry<TRow, TFieldId, {
+    type: 'date';
+  } & DateColumnOptions<TRow>>;
+  /**
+   * Treat one raw string field as a category column.
+   *
+   * Category columns are eligible for the X-axis, grouping, and filters.
+   */
+  category<const TFieldId extends StringFieldKey<TRow>>(id: TFieldId, options?: CategoryColumnOptions<TRow>): RawFieldColumnEntry<TRow, TFieldId, {
+    type: 'category';
+  } & CategoryColumnOptions<TRow>>;
+  /**
+   * Treat one raw numeric field as a number column.
+   *
+   * Number columns participate in metric aggregation.
+   */
+  number<const TFieldId extends NumberFieldKey<TRow>>(id: TFieldId, options?: NumberColumnOptions<TRow>): RawFieldColumnEntry<TRow, TFieldId, {
+    type: 'number';
+  } & NumberColumnOptions<TRow>>;
+  /**
+   * Treat one raw boolean field as a boolean column.
+   *
+   * Boolean columns are useful for grouping and filters.
+   */
+  boolean<const TFieldId extends BooleanFieldKey<TRow>>(id: TFieldId, options?: BooleanColumnOptions<TRow>): RawFieldColumnEntry<TRow, TFieldId, {
+    type: 'boolean';
+  } & BooleanColumnOptions<TRow>>;
+  /**
+   * Remove one raw field from the chart schema entirely.
+   */
+  exclude<const TFieldId extends InferableFieldKey<TRow>>(id: TFieldId): ExcludedFieldColumnEntry<TRow, TFieldId>;
+  /** Helper group for declaring new derived columns. */
+  readonly derived: {
+    /**
+     * Add one derived date column.
+     *
+     * The accessor receives the original row type.
+     */
+    date<const TColumnId extends string>(id: DerivedColumnId<TRow, TColumnId>, options: DerivedDateColumnOptions<TRow>): DerivedColumnEntry<TRow, TColumnId, {
+      kind: 'derived';
+      type: 'date';
+    } & DerivedDateColumnOptions<TRow>>;
+    /**
+     * Add one derived category column.
+     *
+     * The accessor receives the original row type.
+     */
+    category<const TColumnId extends string>(id: DerivedColumnId<TRow, TColumnId>, options: DerivedCategoryColumnOptions<TRow>): DerivedColumnEntry<TRow, TColumnId, {
+      kind: 'derived';
+      type: 'category';
+    } & DerivedCategoryColumnOptions<TRow>>;
+    /**
+     * Add one derived boolean column.
+     *
+     * The accessor receives the original row type.
+     */
+    boolean<const TColumnId extends string>(id: DerivedColumnId<TRow, TColumnId>, options: DerivedBooleanColumnOptions<TRow>): DerivedColumnEntry<TRow, TColumnId, {
+      kind: 'derived';
+      type: 'boolean';
+    } & DerivedBooleanColumnOptions<TRow>>;
+    /**
+     * Add one derived numeric column.
+     *
+     * The accessor receives the original row type.
+     */
+    number<const TColumnId extends string>(id: DerivedColumnId<TRow, TColumnId>, options: DerivedNumberColumnOptions<TRow>): DerivedColumnEntry<TRow, TColumnId, {
+      kind: 'derived';
+      type: 'number';
+    } & DerivedNumberColumnOptions<TRow>>;
+  };
+}
+type SelectableControlBuilderConfig<TBuilder> = TBuilder extends SelectableControlBuilder<any, any, any, any, infer TConfig> ? TConfig : never;
+interface SelectableControlBuilder<TOption extends string, TSupportsDefault extends boolean, TAllowedOption extends TOption = TOption, THiddenOption extends TOption = never, TConfig extends object = {}> {
+  /**
+   * Keep only the listed options visible and selectable.
+   *
+   * Calling `allowed(...)` again replaces the previous allowed list.
+   */
+  allowed<const TOptions extends NonEmptyReadonlyArray<TOption>>(...options: TOptions): SelectableControlBuilder<TOption, TSupportsDefault, Extract<TOptions[number], TOption>, Extract<THiddenOption, Extract<TOptions[number], TOption>>, ReplaceConfigValue<TConfig, 'allowed', TOptions>>;
+  /**
+   * Hide one or more options after the allowed set is resolved.
+   *
+   * Hidden options can still exist in the broader schema; they simply stop
+   * appearing in the public control surface.
+   */
+  hidden<const TOptions extends NonEmptyReadonlyArray<Exclude<TAllowedOption, THiddenOption>>>(...options: TOptions): SelectableControlBuilder<TOption, TSupportsDefault, TAllowedOption, THiddenOption | Extract<TOptions[number], TOption>, AppendConfigValue<TConfig, 'hidden', TOptions[number]>>;
+  /**
+   * Set the preferred fallback option when the current selection is missing or
+   * invalid for the current schema.
+   */
+  default: TSupportsDefault extends true ? <const TDefaultOption extends Exclude<TAllowedOption, THiddenOption>>(option: TDefaultOption) => SelectableControlBuilder<TOption, TSupportsDefault, TAllowedOption, THiddenOption, ReplaceConfigValue<TConfig, 'default', TDefaultOption>> : never;
+}
+type MetricBuilderConfig<TBuilder> = TBuilder extends MetricBuilder<any, any, any, infer TConfig> ? TConfig : never;
+interface MetricBuilder<TMetricColumnId extends string, TAllowedMetric = never, THiddenMetric = never, TConfig extends object = {}> {
+  /**
+   * Allow the built-in row count metric.
+   */
+  count(): MetricBuilder<TMetricColumnId, TAllowedMetric | CountMetric, THiddenMetric, AppendConfigValue<TConfig, 'allowed', CountMetric>>;
+  /**
+   * Allow one or more numeric aggregates for the given column.
+   *
+   * Example: `aggregate('salary', 'sum', 'avg')`
+   */
+  aggregate<const TColumnId extends TMetricColumnId, const TAggregates extends NonEmptyReadonlyArray<NumericAggregateFunction>>(columnId: TColumnId, ...aggregates: TAggregates): MetricBuilder<TMetricColumnId, TAllowedMetric | AggregateMetricUnionFromSelection<TColumnId, TAggregates>, THiddenMetric, AppendConfigValue<TConfig, 'allowed', {
+    kind: 'aggregate';
+    columnId: TColumnId;
+    aggregate: AggregateSelectionFromList<TAggregates>;
+  }>>;
+  /**
+   * Hide the row count metric from the public metric picker.
+   */
+  hideCount(...args: CountMetric extends VisibleMetricUnion<TMetricColumnId, TAllowedMetric, THiddenMetric> ? [] : [never]): MetricBuilder<TMetricColumnId, TAllowedMetric, THiddenMetric | CountMetric, AppendConfigValue<TConfig, 'hidden', CountMetric>>;
+  /**
+   * Hide one or more aggregate metrics for a numeric column.
+   */
+  hideAggregate<const TColumnId extends MetricColumnIdFromMetric<VisibleMetricUnion<TMetricColumnId, TAllowedMetric, THiddenMetric>>, const TAggregates extends NonEmptyReadonlyArray<MetricAggregateFromMetric<VisibleMetricUnion<TMetricColumnId, TAllowedMetric, THiddenMetric>, TColumnId>>>(columnId: TColumnId, ...aggregates: TAggregates): MetricBuilder<TMetricColumnId, TAllowedMetric, THiddenMetric | AggregateMetricUnionFromSelection<TColumnId, TAggregates>, AppendManyConfigValues<TConfig, 'hidden', AggregateMetricTupleFromSelection<TColumnId, TAggregates>>>;
+  /**
+   * Prefer the row count metric when the current metric becomes invalid.
+   */
+  defaultCount(...args: CountMetric extends VisibleMetricUnion<TMetricColumnId, TAllowedMetric, THiddenMetric> ? [] : [never]): MetricBuilder<TMetricColumnId, TAllowedMetric, THiddenMetric, ReplaceConfigValue<TConfig, 'default', CountMetric>>;
+  /**
+   * Prefer one aggregate metric when the current metric becomes invalid.
+   */
+  defaultAggregate<const TColumnId extends MetricColumnIdFromMetric<VisibleMetricUnion<TMetricColumnId, TAllowedMetric, THiddenMetric>>, const TAggregate extends MetricAggregateFromMetric<VisibleMetricUnion<TMetricColumnId, TAllowedMetric, THiddenMetric>, TColumnId>>(columnId: TColumnId, aggregate: TAggregate): MetricBuilder<TMetricColumnId, TAllowedMetric, THiddenMetric, ReplaceConfigValue<TConfig, 'default', {
+    kind: 'aggregate';
+    columnId: TColumnId;
+    aggregate: TAggregate;
+  }>>;
+}
+type SchemaFromBuilder<TColumns extends Record<string, unknown> | undefined, TXAxis extends XAxisConfig<any> | undefined, TGroupBy extends GroupByConfig<any> | undefined, TFilters extends FiltersConfig<any> | undefined, TMetric extends MetricConfig<any> | undefined, TChartType extends ChartTypeConfig | undefined, TTimeBucket extends TimeBucketConfig | undefined, TConnectNulls extends boolean | undefined> = {
+  columns?: Extract<TColumns, Record<string, unknown> | undefined>;
+  xAxis?: Extract<TXAxis, XAxisConfig<any> | undefined>;
+  groupBy?: Extract<TGroupBy, GroupByConfig<any> | undefined>;
+  filters?: Extract<TFilters, FiltersConfig<any> | undefined>;
+  metric?: Extract<TMetric, MetricConfig<any> | undefined>;
+  chartType?: Extract<TChartType, ChartTypeConfig | undefined>;
+  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 };