@matthieumordrel/chart-studio 0.2.1 → 0.2.3

package/dist/core/types.d.mts

@@ -0,0 +1,957 @@
+//#region src/core/types.d.ts
+/**
+ * Core types for chart-studio.
+ *
+ * The type system is built around two concepts:
+ * 1. **Columns** describe the shape of your data (date, category, boolean, number)
+ * 2. **Chart state** tracks what the user has selected (chart type, groupBy, filters, etc.)
+ *
+ * Column types determine what operations are available:
+ * - `date`     → X-axis candidate, time bucketing (day/week/month/quarter/year)
+ * - `category` → X-axis candidate, groupBy candidate, multi-select filter
+ * - `boolean`  → groupBy candidate, toggle filter
+ * - `number`   → metric/aggregation (count, sum, avg, min, max)
+ */
+type Nullish = null | undefined;
+/** Primitive field values that chart-studio can infer directly from raw data. */
+type InferableColumnValue = string | number | boolean | Date | Nullish;
+/** Top-level dataset keys whose values can be charted without a custom accessor. */
+type InferableFieldKey<T> = Extract<{ [TKey in keyof T]-?: Exclude<T[TKey], Nullish> extends InferableColumnValue ? TKey : never }[keyof T], string>;
+/**
+ * Built-in format presets for `schema.columns.*.format`.
+ *
+ * Use these for the common cases before reaching for the object form:
+ * - `'number'` for a normal numeric display such as `12,340`
+ * - `'compact-number'` for short numeric display such as `12.3K`
+ * - `'currency'` for money such as `$12.3K` / `$12,340`
+ * - `'percent'` for ratios such as `27.8%`
+ * - `'date'` for date-only values such as `Mar 11, 2026`
+ * - `'datetime'` for date+time values such as `Mar 11, 2026, 3:30 PM`
+ */
+type ColumnFormatPreset = 'number' | 'compact-number' | 'currency' | 'percent' | 'date' | 'datetime';
+/**
+ * Fixed-size duration units that can be converted reliably without calendar
+ * ambiguity.
+ *
+ * These are used by `format: {kind: 'duration', unit: ...}` to tell the chart
+ * system what one raw numeric value represents.
+ */
+type DurationInputUnit = 'seconds' | 'minutes' | 'hours' | 'days';
+/**
+ * `Intl.NumberFormat` options for `format: {kind: 'number', ...}`.
+ *
+ * This is still a native `Intl` passthrough, but the most common properties are
+ * re-documented here so new users can understand them directly from editor
+ * hover text without opening MDN first.
+ *
+ * Typical example:
+ *
+ * ```ts
+ * format: {
+ *   kind: 'number',
+ *   options: {
+ *     style: 'currency',
+ *     currency: 'USD',
+ *     notation: 'compact',
+ *     maximumFractionDigits: 1,
+ *   },
+ * }
+ * ```
+ */
+type ChartNumberFormatOptions = Omit<Intl.NumberFormatOptions, 'style' | 'currency' | 'notation' | 'maximumFractionDigits'> & {
+  /**
+   * Which numeric family to render.
+   *
+   * Common values:
+   * - `'decimal'` -> `1,234`
+   * - `'currency'` -> `$1,234`
+   * - `'percent'` -> `27.8%`
+   */
+  style?: Intl.NumberFormatOptions['style'];
+  /**
+   * Currency code used when `style: 'currency'`.
+   *
+   * Common examples:
+   * - `'USD'`
+   * - `'EUR'`
+   * - `'GBP'`
+   */
+  currency?: string;
+  /**
+   * Whether large values should stay full length or use compact suffixes.
+   *
+   * Common values:
+   * - `'standard'` -> `1,200,000`
+   * - `'compact'` -> `1.2M`
+   */
+  notation?: Intl.NumberFormatOptions['notation'];
+  /**
+   * Maximum number of digits shown after the decimal separator.
+   *
+   * Examples:
+   * - `0` -> `1M`
+   * - `1` -> `1.2M`
+   * - `2` -> `1.23M`
+   */
+  maximumFractionDigits?: number;
+};
+/**
+ * `Intl.DateTimeFormat` options for `format: {kind: 'date', ...}`.
+ *
+ * Like `ChartNumberFormatOptions`, this is still a native `Intl` passthrough
+ * with friendlier docs for the properties chart users reach for most often.
+ *
+ * Typical example:
+ *
+ * ```ts
+ * format: {
+ *   kind: 'date',
+ *   options: {
+ *     month: 'short',
+ *     year: 'numeric',
+ *   },
+ * }
+ * ```
+ */
+type ChartDateFormatOptions = Omit<Intl.DateTimeFormatOptions, 'dateStyle' | 'timeStyle' | 'year' | 'month' | 'day'> & {
+  /**
+   * Prebuilt date preset.
+   *
+   * Examples:
+   * - `'short'` -> `3/11/26`
+   * - `'medium'` -> `Mar 11, 2026`
+   * - `'long'` -> `March 11, 2026`
+   */
+  dateStyle?: Intl.DateTimeFormatOptions['dateStyle'];
+  /**
+   * Prebuilt time preset.
+   *
+   * Examples:
+   * - `'short'` -> `3:30 PM`
+   * - `'medium'` -> `3:30:00 PM`
+   */
+  timeStyle?: Intl.DateTimeFormatOptions['timeStyle']; /** How the year should render, for example `'numeric'` or `'2-digit'`. */
+  year?: Intl.DateTimeFormatOptions['year']; /** How the month should render, for example `'numeric'`, `'short'`, or `'long'`. */
+  month?: Intl.DateTimeFormatOptions['month']; /** How the day should render, usually `'numeric'` or `'2-digit'`. */
+  day?: Intl.DateTimeFormatOptions['day'];
+};
+/**
+ * Explicit number formatting object.
+ *
+ * Use this when the preset strings are close, but you want to control the
+ * locale or specific `Intl.NumberFormat` options yourself.
+ */
+type NumberColumnFormat = {
+  /** Marks this object as the number-format form of `format`. */kind: 'number';
+  /**
+   * Optional locale passed to `Intl.NumberFormat`.
+   *
+   * Examples:
+   * - `'en-US'`
+   * - `'fr-FR'`
+   * - `'de-DE'`
+   */
+  locale?: string;
+  /**
+   * Native `Intl.NumberFormat` options.
+   *
+   * This is where you customize things like currency, compact notation, and the
+   * number of decimal places to show.
+   */
+  options?: ChartNumberFormatOptions;
+};
+/**
+ * Explicit date formatting object.
+ *
+ * Use this when the preset strings are close, but you want to control the
+ * locale or specific `Intl.DateTimeFormat` options yourself.
+ */
+type DateColumnFormat = {
+  /** Marks this object as the date-format form of `format`. */kind: 'date';
+  /**
+   * Optional locale passed to `Intl.DateTimeFormat`.
+   *
+   * Examples:
+   * - `'en-US'`
+   * - `'fr-FR'`
+   * - `'ja-JP'`
+   */
+  locale?: string;
+  /**
+   * Native `Intl.DateTimeFormat` options.
+   *
+   * This is where you customize things like month/year-only displays, long
+   * versus short month names, or full date+time output.
+   */
+  options?: ChartDateFormatOptions;
+};
+/**
+ * Explicit duration formatting object for numeric values that represent elapsed
+ * time.
+ *
+ * Use this when the charted value is a duration and you want chart-studio to
+ * render compact labels like `36s`, `1h36m`, or `1d5h`.
+ *
+ * Typical example:
+ *
+ * ```ts
+ * format: {
+ *   kind: 'duration',
+ *   unit: 'minutes',
+ * }
+ * ```
+ */
+type DurationColumnFormat = {
+  /** Marks this object as the duration-format form of `format`. */kind: 'duration';
+  /**
+   * Unit represented by one raw numeric value.
+   *
+   * Examples:
+   * - `'seconds'` when `90` means ninety seconds
+   * - `'minutes'` when `45` means forty-five minutes
+   * - `'hours'` when `1.5` means one hour and thirty minutes
+   * - `'days'` when `2` means two days
+   */
+  unit: DurationInputUnit;
+};
+/**
+ * Full declarative formatting surface accepted by `schema.columns.*.format`.
+ *
+ * Start with a preset string for the common case. Move to the object form when
+ * you need to customize locale, low-level `Intl` options, or duration units.
+ */
+type ColumnFormat = ColumnFormatPreset | NumberColumnFormat | DateColumnFormat | DurationColumnFormat;
+/** Column kinds understood by the chart pipeline. */
+type ChartColumnType = 'date' | 'category' | 'boolean' | 'number';
+/** Confidence attached to runtime field inference. */
+type InferenceConfidence = 'low' | 'medium' | 'high';
+/** Debug metadata describing how a column was inferred. */
+type ColumnInferenceMetadata = {
+  detectedType: ChartColumnType;
+  confidence: InferenceConfidence;
+  hinted: boolean;
+};
+/**
+ * Shared schema properties available on both raw-field overrides and derived
+ * columns.
+ *
+ * Most users will interact with these through `schema.columns.someField`.
+ */
+interface BaseColumnHint<T, TValue> {
+  /**
+   * User-facing column label shown in selectors, tooltips, legends, and filter
+   * headers.
+   *
+   * Example: `revenuePerSeat` becomes `Revenue Per Seat` by default, but you can
+   * override it with `label: 'Revenue / Seat'`.
+   */
+  label?: string;
+  /**
+   * How this column should be displayed in the chart UI.
+   *
+   * Use a preset like `'currency'` or `'percent'` for the common case. Use the
+   * object form when you need to control locale, specific `Intl` options, or
+   * duration units like `'minutes'`.
+   *
+   * This affects display surfaces such as:
+   * - axis tick labels
+   * - tooltip values
+   * - chart data labels
+   * - filter option labels when the values are typed
+   */
+  format?: ColumnFormat;
+  /**
+   * Final escape hatch for fully custom display logic.
+   *
+   * Receives the resolved field value and, when the UI surface still maps to a
+   * single raw row, that source item as well. Prefer `format` first when a
+   * declarative option is enough, and use `formatter` only when the output
+   * really depends on custom business logic.
+   */
+  formatter?: (value: TValue | null | undefined, item?: T) => string;
+}
+/**
+ * Schema override for a raw string field.
+ *
+ * Use this when a dataset field already exists and you want to relabel it,
+ * force its type, or change how it formats in the chart UI.
+ */
+interface StringColumnHint<T> extends BaseColumnHint<T, string> {
+  /**
+   * How this string field should behave in the chart system.
+   *
+   * - `'category'` keeps it as a label-like field
+   * - `'date'` tells chart-studio to parse it as a date/time field
+   */
+  type?: 'category' | 'date';
+}
+/**
+ * Schema override for a raw numeric field.
+ *
+ * This is the most common place to use `format: 'currency'`,
+ * `format: 'percent'`, or a `kind: 'number'` object.
+ */
+interface NumberColumnHint<T> extends BaseColumnHint<T, number> {
+  /**
+   * How this numeric field should behave in the chart system.
+   *
+   * - `'number'` keeps it as an aggregatable metric
+   * - `'date'` is useful for Unix timestamps or numeric date representations
+   */
+  type?: 'number' | 'date';
+}
+/**
+ * Schema override for a raw boolean field.
+ *
+ * These fields are useful for grouping and filtering, especially when paired
+ * with `trueLabel` / `falseLabel`.
+ */
+interface BooleanColumnHint<T> extends BaseColumnHint<T, boolean> {
+  /** Boolean fields always resolve to the `'boolean'` column type. */
+  type?: 'boolean';
+  /** Label shown in the UI when the value is `true`, for example `'Open'`. */
+  trueLabel?: string;
+  /** Label shown in the UI when the value is `false`, for example `'Closed'`. */
+  falseLabel?: string;
+}
+/**
+ * Schema override for a raw date-like field.
+ *
+ * This is useful when your field is already a `Date`, ISO string, or timestamp
+ * and you want date-specific behavior with an optional custom display format.
+ */
+interface DateValueColumnHint<T> extends BaseColumnHint<T, string | number | Date> {
+  /** Date-valued fields always resolve to the `'date'` column type. */
+  type?: 'date';
+}
+/** Override options for mixed primitive fields when runtime values need the final say. */
+interface MixedPrimitiveColumnHint<T, TValue> extends BaseColumnHint<T, TValue> {
+  /** Explicitly pin the runtime-inferred field to one chart column type. */
+  type?: ChartColumnType;
+  /** Human-facing label used when a mixed field is interpreted as boolean `true`. */
+  trueLabel?: string;
+  /** Human-facing label used when a mixed field is interpreted as boolean `false`. */
+  falseLabel?: string;
+}
+/**
+ * Type-safe schema entry for one raw dataset field.
+ *
+ * The available properties depend on the field's runtime type, so a boolean
+ * field gets boolean-specific options, a number field gets numeric options, and
+ * so on.
+ */
+type ColumnHintFor<TValue, T> = [Exclude<TValue, Nullish>] extends [boolean] ? BooleanColumnHint<T> : [Exclude<TValue, Nullish>] extends [Date] ? DateValueColumnHint<T> : [Exclude<TValue, Nullish>] extends [number] ? NumberColumnHint<T> : [Exclude<TValue, Nullish>] extends [string] ? StringColumnHint<T> : MixedPrimitiveColumnHint<T, Exclude<TValue, Nullish>>;
+/** Partial per-field overrides layered on top of automatic inference. */
+type ColumnHints<T> = Partial<{ [TKey in InferableFieldKey<T>]: ColumnHintFor<T[TKey], T> | false }>;
+/**
+ * Override or exclude one inferred raw field inside `schema.columns`.
+ *
+ * This lightweight shape intentionally matches the inference override story so
+ * callers can keep the common case terse while the surrounding `schema` object
+ * becomes the single explicit chart contract.
+ */
+type RawColumnSchemaFor<TValue, T> = ColumnHintFor<TValue, T>;
+/**
+ * Raw-field schema entries keyed by existing top-level dataset fields.
+ *
+ * Set a field to `false` to exclude it from the chart API entirely.
+ */
+type RawColumnSchemaMap<T> = Partial<{ [TKey in InferableFieldKey<T>]: RawColumnSchemaFor<T[TKey], T> | false }>;
+/**
+ * Shared contract for every explicit derived column declared in `schema.columns`.
+ *
+ * Derived columns are how you add a brand new chart field that does not exist as
+ * a raw property on the input row.
+ *
+ * They are intentionally narrow:
+ * - they are additive-only and must use a new id
+ * - they compute from one row at a time via `accessor`
+ * - they reuse the same labeling and formatting surface as raw columns
+ * - they do not currently expose any extra metadata channel
+ */
+interface DerivedColumnSchemaBase<T, TValue, TType extends ChartColumnType> extends Omit<BaseColumnHint<T, TValue>, 'label'> {
+  /**
+   * Marks this schema entry as a derived column.
+   *
+   * Without `kind: 'derived'`, a `schema.columns` entry is interpreted as an
+   * override for an existing raw field.
+   */
+  kind: 'derived';
+  /** User-facing label for this new derived column. */
+  label: string;
+  /**
+   * Declared column role.
+   *
+   * This controls how the derived column behaves:
+   * - `'date'` can be used on time-series X-axes
+   * - `'category'` can be used for X-axis, group-by, and filters
+   * - `'boolean'` can be used for group-by and filters
+   * - `'number'` can be aggregated as a metric
+   */
+  type: TType;
+}
+/** Explicit derived date column definition. */
+interface DerivedDateColumnSchema<T> extends DerivedColumnSchemaBase<T, string | number | Date, 'date'> {
+  /** Compute one date-like value from a row for time-series usage. */
+  accessor: (item: T) => string | number | Date | null | undefined;
+}
+/** Explicit derived category column definition. */
+interface DerivedCategoryColumnSchema<T> extends DerivedColumnSchemaBase<T, string, 'category'> {
+  /** Compute one category label from a row. */
+  accessor: (item: T) => string | null | undefined;
+}
+/** Explicit derived boolean column definition. */
+interface DerivedBooleanColumnSchema<T> extends DerivedColumnSchemaBase<T, boolean, 'boolean'> {
+  /** Compute one boolean value from a row. */
+  accessor: (item: T) => boolean | null | undefined;
+  /** Human-facing label used when the derived value is `true`. */
+  trueLabel?: string;
+  /** Human-facing label used when the derived value is `false`. */
+  falseLabel?: string;
+}
+/** Explicit derived numeric column definition. */
+interface DerivedNumberColumnSchema<T> extends DerivedColumnSchemaBase<T, number, 'number'> {
+  /** Compute one numeric value from a row for aggregation. */
+  accessor: (item: T) => number | null | undefined;
+}
+/** Any explicit derived column accepted in `schema.columns`. */
+type DerivedColumnSchema<T> = DerivedDateColumnSchema<T> | DerivedCategoryColumnSchema<T> | DerivedBooleanColumnSchema<T> | DerivedNumberColumnSchema<T>;
+type ExcludedHintKeys<THints> = Extract<{ [TKey in keyof THints]-?: THints[TKey] extends false ? TKey : never }[keyof THints], string>;
+/** Column ID union after removing any fields explicitly disabled by hints. */
+type ResolvedColumnIdFromHints<T, THints extends ColumnHints<T> | undefined = undefined> = Exclude<InferableFieldKey<T>, THints extends ColumnHints<T> ? ExcludedHintKeys<THints> : never>;
+type ExplicitHintedColumnType<THint> = Extract<THint extends {
+  type?: infer TType;
+} ? TType : never, ChartColumnType>;
+type PotentialColumnTypeFromValue<TValue> = [Exclude<TValue, Nullish>] extends [boolean] ? 'boolean' : [Exclude<TValue, Nullish>] extends [Date] ? 'date' : [Exclude<TValue, Nullish>] extends [number] ? 'date' | 'number' : [Exclude<TValue, Nullish>] extends [string] ? 'date' | 'category' : ChartColumnType;
+type PotentialColumnTypeFromHints<T, THints extends ColumnHints<T> | undefined, TKey extends ResolvedColumnIdFromHints<T, THints>> = THints extends ColumnHints<T> ? [ExplicitHintedColumnType<THints[TKey]>] extends [never] ? PotentialColumnTypeFromValue<T[TKey]> : ExplicitHintedColumnType<THints[TKey]> : PotentialColumnTypeFromValue<T[TKey]>;
+type ColumnIdsMatchingPotentialTypes<T, THints extends ColumnHints<T> | undefined, TAllowedType extends ChartColumnType> = Extract<{ [TKey in ResolvedColumnIdFromHints<T, THints>]: Extract<PotentialColumnTypeFromHints<T, THints, TKey>, TAllowedType> extends never ? never : TKey }[ResolvedColumnIdFromHints<T, THints>], string>;
+/** Column IDs that can safely be treated as X-axis candidates from static information. */
+type ResolvedXAxisColumnIdFromHints<T, THints extends ColumnHints<T> | undefined = undefined> = ColumnIdsMatchingPotentialTypes<T, THints, 'date' | 'category' | 'boolean'>;
+/** Column IDs that can safely be treated as groupBy candidates from static information. */
+type ResolvedGroupByColumnIdFromHints<T, THints extends ColumnHints<T> | undefined = undefined> = ColumnIdsMatchingPotentialTypes<T, THints, 'category' | 'boolean'>;
+/** Column IDs that can safely be treated as filter candidates from static information. */
+type ResolvedFilterColumnIdFromHints<T, THints extends ColumnHints<T> | undefined = undefined> = ColumnIdsMatchingPotentialTypes<T, THints, 'category' | 'boolean'>;
+/** Column IDs that can safely be treated as metric candidates from static information. */
+type ResolvedMetricColumnIdFromHints<T, THints extends ColumnHints<T> | undefined = undefined> = ColumnIdsMatchingPotentialTypes<T, THints, 'number'>;
+/** Column IDs that can safely be treated as date candidates from static information. */
+type ResolvedDateColumnIdFromHints<T, THints extends ColumnHints<T> | undefined = undefined> = ColumnIdsMatchingPotentialTypes<T, THints, 'date'>;
+type ConfigSection<TConfig, TKey extends string> = TKey extends keyof TConfig ? TConfig[TKey] : never;
+type AllowedOptionFromControlConfig<TControlConfig> = TControlConfig extends {
+  allowed?: readonly (infer TAllowedOption)[];
+} ? TAllowedOption : never;
+type HiddenOptionFromControlConfig<TControlConfig> = TControlConfig extends {
+  hidden?: readonly (infer THiddenOption)[];
+} ? THiddenOption : never;
+type RestrictUnionOrFallback<TAllowed, TFallback> = [Extract<TAllowed, TFallback>] extends [never] ? TFallback : Extract<TAllowed, TFallback>;
+type ExcludeHiddenOrFallback<TBase, THidden> = [Extract<THidden, TBase>] extends [TBase] ? TBase : Exclude<TBase, Extract<THidden, TBase>>;
+type RestrictOptionsFromControlConfig<TBaseOption, TControlConfig> = ExcludeHiddenOrFallback<RestrictUnionOrFallback<AllowedOptionFromControlConfig<TControlConfig>, TBaseOption>, Extract<HiddenOptionFromControlConfig<TControlConfig>, TBaseOption>>;
+type AllowedMetricFromConfig<TConfig> = TConfig extends {
+  metric?: {
+    allowed?: readonly (infer TAllowedMetric)[];
+  };
+} ? TAllowedMetric : never;
+type HiddenMetricFromConfig<TConfig> = TConfig extends {
+  metric?: {
+    hidden?: readonly (infer THiddenMetric)[];
+  };
+} ? THiddenMetric : never;
+type ExpandMetricAllowance<TMetricAllowance> = TMetricAllowance extends CountMetric ? CountMetric : TMetricAllowance extends {
+  kind: 'aggregate';
+  columnId: infer TColumnId extends string;
+  aggregate: infer TAggregate;
+  includeZeros?: infer TIncludeZeros;
+} ? TAggregate extends readonly NumericAggregateFunction[] ? { [TSelectedAggregate in TAggregate[number]]: {
+  kind: 'aggregate';
+  columnId: TColumnId;
+  aggregate: TSelectedAggregate;
+  includeZeros?: Extract<TIncludeZeros, boolean | undefined>;
+} }[TAggregate[number]] : TAggregate extends NumericAggregateFunction ? {
+  kind: 'aggregate';
+  columnId: TColumnId;
+  aggregate: TAggregate;
+  includeZeros?: Extract<TIncludeZeros, boolean | undefined>;
+} : never : never;
+type MetricColumnIdFromMetric<TMetric> = Extract<TMetric extends AggregateMetric<infer TColumnId> ? TColumnId : never, string>;
+type StaticConfigError<TMessage extends string> = {
+  __configError__: TMessage;
+};
+type IsExactly<TLeft, TRight> = [TLeft] extends [TRight] ? [TRight] extends [TLeft] ? true : false : false;
+type IsTuple<TArray extends readonly unknown[]> = number extends TArray['length'] ? false : true;
+type NarrowConfigLiteral<TValue, TWide> = IsExactly<TValue, TWide> extends true ? never : TValue;
+type RequiredKeys<TObject> = Extract<{ [TKey in keyof TObject]-?: undefined extends TObject[TKey] ? never : TKey }[keyof TObject], PropertyKey>;
+type ExactShape<TExpected, TActual> = TExpected extends unknown ? TActual extends readonly (infer TActualItem)[] ? TExpected extends readonly (infer TExpectedItem)[] ? readonly ExactShape<TExpectedItem, TActualItem>[] : never : TActual extends ((...args: never[]) => unknown) ? TActual extends TExpected ? TActual : never : TActual extends object ? TExpected extends object ? { [TKey in keyof TActual]: TKey extends keyof TExpected ? ExactShape<TExpected[TKey], TActual[TKey]> : never } & { [TKey in Exclude<RequiredKeys<TExpected>, keyof TActual>]-?: never } : never : TActual extends TExpected ? TActual : never : never;
+type SchemaColumnsValidationShape<T, TColumns extends Record<string, unknown> | undefined> = TColumns extends Record<string, unknown> ? { [TKey in keyof TColumns]: TKey extends InferableFieldKey<T> ? RawColumnSchemaFor<T[TKey], T> | false : DerivedColumnSchema<T> } : never;
+type ValidateLiteralDefaultNotHidden<TSection, TWideOption, TSectionName extends string> = TSection extends {
+  default?: infer TDefault;
+  hidden?: infer THidden;
+} ? THidden extends readonly unknown[] ? IsTuple<THidden> extends true ? [NarrowConfigLiteral<Exclude<TDefault, undefined>, TWideOption>] extends [never] ? unknown : [Extract<NarrowConfigLiteral<Exclude<TDefault, undefined>, TWideOption>, THidden[number]>] extends [never] ? unknown : StaticConfigError<`${TSectionName}.default cannot also appear in ${TSectionName}.hidden`> : unknown : unknown : unknown;
+type ValidateChartSchemaLiterals<T, TSchema extends ChartSchema<T, any>> = ValidateLiteralDefaultNotHidden<ConfigSection<TSchema, 'xAxis'>, ResolvedXAxisColumnIdFromSchema<T, TSchema>, 'xAxis'> & ValidateLiteralDefaultNotHidden<ConfigSection<TSchema, 'groupBy'>, ResolvedGroupByColumnIdFromSchema<T, TSchema>, 'groupBy'> & ValidateLiteralDefaultNotHidden<ConfigSection<TSchema, 'metric'>, Metric<ResolvedMetricColumnIdFromSchema<T, TSchema>>, 'metric'> & ValidateLiteralDefaultNotHidden<ConfigSection<TSchema, 'chartType'>, ChartType, 'chartType'> & ValidateLiteralDefaultNotHidden<ConfigSection<TSchema, 'timeBucket'>, TimeBucket, 'timeBucket'>;
+type ChartSchemaValidationTarget<T, TSchema extends ChartSchema<T, any>> = {
+  columns?: SchemaColumnsValidationShape<T, ExtractSchemaColumns<TSchema>>;
+  xAxis?: XAxisConfig<ResolvedXAxisColumnIdFromSchema<T, TSchema>>;
+  groupBy?: GroupByConfig<ResolvedGroupByColumnIdFromSchema<T, TSchema>>;
+  filters?: FiltersConfig<ResolvedFilterColumnIdFromSchema<T, TSchema>>;
+  metric?: MetricConfig<ResolvedMetricColumnIdFromSchema<T, TSchema>>;
+  chartType?: ChartTypeConfig;
+  timeBucket?: TimeBucketConfig;
+};
+/** Strict schema object returned by `defineChartSchema(...)`. */
+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(...)`. */
+type DefinedChartSchema<T, TSchema extends ChartSchema<T, any> = ChartSchema<T, any>> = TSchema & ChartSchemaDefinitionBrand;
+type ResolvedChartSchemaFromDefinition<TSchema> = TSchema extends DefinedChartSchema<any, infer TResolvedSchema> ? TResolvedSchema : undefined;
+/** GroupBy IDs narrowed by explicit schema restrictions when present. */
+type RestrictedGroupByColumnIdFromSchema<T, TSchema extends ChartSchema<T, any> | undefined = undefined> = RestrictOptionsFromControlConfig<ResolvedGroupByColumnIdFromSchema<T, TSchema>, ConfigSection<TSchema, 'groupBy'>>;
+/** X-axis IDs narrowed by explicit schema restrictions when present. */
+type RestrictedXAxisColumnIdFromSchema<T, TSchema extends ChartSchema<T, any> | undefined = undefined> = RestrictOptionsFromControlConfig<ResolvedXAxisColumnIdFromSchema<T, TSchema>, ConfigSection<TSchema, 'xAxis'>>;
+/** Filter column IDs narrowed by explicit schema restrictions when present. */
+type RestrictedFilterColumnIdFromSchema<T, TSchema extends ChartSchema<T, any> | undefined = undefined> = RestrictOptionsFromControlConfig<ResolvedFilterColumnIdFromSchema<T, TSchema>, ConfigSection<TSchema, 'filters'>>;
+/** Metric union narrowed by explicit schema restrictions when present. */
+type RestrictedMetricFromSchema<T, TSchema extends ChartSchema<T, any> | undefined = undefined> = ExcludeHiddenOrFallback<RestrictUnionOrFallback<ExpandMetricAllowance<AllowedMetricFromConfig<TSchema>>, Metric<ResolvedMetricColumnIdFromSchema<T, TSchema>>>, HiddenMetricFromConfig<TSchema>>;
+/** Chart types narrowed by explicit schema restrictions when present. */
+type RestrictedChartTypeFromSchema<TSchema> = RestrictOptionsFromControlConfig<ChartType, ConfigSection<TSchema, 'chartType'>>;
+/** Time buckets narrowed by explicit schema restrictions when present. */
+type RestrictedTimeBucketFromSchema<TSchema> = RestrictOptionsFromControlConfig<TimeBucket, ConfigSection<TSchema, 'timeBucket'>>;
+/** Base properties shared by all column types. */
+type ColumnBase<T, TId extends string> = {
+  /** Unique identifier — typically the field key in the data object. */id: TId; /** Human-readable label for the UI. */
+  label: string; /** Optional display formatter preset used by the UI layer. */
+  format?: ColumnFormat;
+  /**
+   * Optional per-value formatter used by the UI layer.
+   *
+   * The source `item` is passed when the rendered value still maps to one raw
+   * row, such as filter option labels. Aggregated chart values do not have a
+   * single backing row, so `item` is optional there by design.
+   */
+  formatter?: (value: unknown, item?: T) => string; /** Optional debug metadata describing how the column was inferred. */
+  inference?: ColumnInferenceMetadata;
+};
+/**
+ * A date column — eligible as a time-series X-axis.
+ *
+ * @property accessor - Extracts a date value from a data item
+ */
+type DateColumn<T, TId extends string = string> = ColumnBase<T, TId> & {
+  type: 'date';
+  accessor: (item: T) => string | number | Date | null | undefined;
+};
+/**
+ * A category column — eligible for X-axis, groupBy, and filtering.
+ *
+ * @property accessor - Extracts a string category value from a data item
+ */
+type CategoryColumn<T, TId extends string = string> = ColumnBase<T, TId> & {
+  type: 'category';
+  accessor: (item: T) => string | null | undefined;
+};
+/**
+ * A boolean column — eligible for groupBy (2 groups) and toggle filtering.
+ *
+ * @property accessor - Extracts a boolean value from a data item
+ * @property trueLabel - Label for the `true` group (e.g. "Open")
+ * @property falseLabel - Label for the `false` group (e.g. "Closed")
+ */
+type BooleanColumn<T, TId extends string = string> = ColumnBase<T, TId> & {
+  type: 'boolean';
+  accessor: (item: T) => boolean | null | undefined;
+  trueLabel: string;
+  falseLabel: string;
+};
+/**
+ * A number column — eligible as a metric for aggregation.
+ *
+ * @property accessor - Extracts a numeric value from a data item
+ */
+type NumberColumn<T, TId extends string = string> = ColumnBase<T, TId> & {
+  type: 'number';
+  accessor: (item: T) => number | null | undefined;
+};
+/** Union of all column types. */
+type ChartColumn<T, TId extends string = string> = DateColumn<T, TId> | CategoryColumn<T, TId> | BooleanColumn<T, TId> | NumberColumn<T, TId>;
+/** Chart types available for time-series (date X-axis). */
+type TimeSeriesChartType = 'bar' | 'line' | 'area';
+/** Chart types available for categorical (category/boolean X-axis). */
+type CategoricalChartType = 'bar' | 'pie' | 'donut';
+/** All supported chart types. */
+type ChartType = TimeSeriesChartType | CategoricalChartType;
+/** Time bucket sizes for date X-axis. */
+type TimeBucket = 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** Aggregation functions for the Y-axis metric. */
+type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+/** Numeric aggregation functions that operate on number columns. */
+type NumericAggregateFunction = Exclude<AggregateFunction, 'count'>;
+/** One or many numeric aggregates accepted by declarative metric restrictions. */
+type NumericAggregateSelection = NumericAggregateFunction | readonly NumericAggregateFunction[];
+/**
+ * A metric definition — what the Y-axis measures.
+ *
+ * `count` represents item count.
+ * `aggregate` represents a numeric column aggregation.
+ */
+type CountMetric = {
+  kind: 'count';
+};
+/**
+ * A numeric aggregation metric.
+ *
+ * @property columnId - The number column to aggregate
+ * @property aggregate - The numeric aggregation function to apply
+ * @property includeZeros - Whether zero values are included in aggregation
+ */
+type AggregateMetric<TColumnId extends string = string> = {
+  kind: 'aggregate';
+  columnId: TColumnId;
+  aggregate: NumericAggregateFunction;
+  includeZeros?: boolean;
+};
+/** Metric union returned by the chart hook. */
+type Metric<TColumnId extends string = string> = CountMetric | AggregateMetric<TColumnId>;
+/**
+ * Aggregate metric restriction accepted by `config.metric.allowed`.
+ *
+ * Unlike `AggregateMetric`, the `aggregate` field may be either one aggregate
+ * or an array shorthand that expands into several allowed metrics.
+ */
+type AggregateMetricAllowance<TColumnId extends string = string> = {
+  kind: 'aggregate';
+  columnId: TColumnId;
+  aggregate: NumericAggregateSelection;
+  includeZeros?: boolean;
+};
+/** One declarative metric entry accepted by `config.metric.allowed`. */
+type MetricAllowance<TColumnId extends string = string> = CountMetric | AggregateMetricAllowance<TColumnId>;
+/** Shared config shape for one selectable control. */
+type SelectableControlConfig<TOption extends string = string> = {
+  /** Optional whitelist of options that remain visible/selectable. */allowed?: readonly TOption[]; /** Optional blacklist of options to hide after whitelisting. */
+  hidden?: readonly TOption[]; /** Preferred selection when the current value is missing or invalid. */
+  default?: TOption;
+};
+/** Declarative config for the X-axis control. */
+type XAxisConfig<TColumnId extends string = string> = SelectableControlConfig<TColumnId>;
+/** Declarative config for the groupBy control. */
+type GroupByConfig<TColumnId extends string = string> = SelectableControlConfig<TColumnId>;
+/**
+ * Declarative config for which columns may appear in the filters UI.
+ *
+ * Filter value restrictions are intentionally out of scope for now. This keeps
+ * `filters` aligned with the existing column-first headless model.
+ */
+type FiltersConfig<TColumnId extends string = string> = Omit<SelectableControlConfig<TColumnId>, 'default'>;
+/**
+ * Declarative config for the metric control.
+ *
+ * `allowed` keeps the shorthand array-expansion form while `hidden` and
+ * `default` operate on fully resolved metric objects.
+ */
+type MetricConfig<TColumnId extends string = string> = {
+  allowed?: readonly MetricAllowance<TColumnId>[];
+  hidden?: readonly Metric<TColumnId>[];
+  default?: Metric<TColumnId>;
+};
+/** Declarative config for chart-type selection. */
+type ChartTypeConfig = SelectableControlConfig<ChartType>;
+/** Declarative config for time-bucket selection. */
+type TimeBucketConfig = SelectableControlConfig<TimeBucket>;
+type ExtractSchemaColumns<TSchema> = TSchema extends {
+  columns?: infer TColumns;
+} ? Extract<TColumns, Record<string, unknown>> : undefined;
+type RawSchemaColumnsFromColumns<T, TColumns extends Record<string, unknown> | undefined> = TColumns extends Record<string, unknown> ? { [TKey in keyof TColumns as TKey extends InferableFieldKey<T> ? TKey : never]: TColumns[TKey] } : undefined;
+type RawSchemaColumns<T, TSchema> = RawSchemaColumnsFromColumns<T, ExtractSchemaColumns<TSchema>>;
+type DerivedColumnIdsFromColumns<TColumns extends Record<string, unknown> | undefined> = Extract<TColumns extends Record<string, unknown> ? { [TKey in keyof TColumns]-?: TColumns[TKey] extends DerivedColumnSchema<any> ? TKey : never }[keyof TColumns] : never, string>;
+type DerivedColumnIdsByTypeFromColumns<TColumns extends Record<string, unknown> | undefined, TAllowedType extends ChartColumnType> = Extract<TColumns extends Record<string, unknown> ? { [TKey in keyof TColumns]-?: TColumns[TKey] extends {
+  kind: 'derived';
+  type: infer TType;
+} ? Extract<TType, TAllowedType> extends never ? never : TKey : never }[keyof TColumns] : never, string>;
+/** Column ID union resolved from one explicit schema definition. */
+type ResolvedColumnIdFromSchema<T, TSchema extends {
+  columns?: Record<string, unknown>;
+} | undefined = undefined> = ResolvedColumnIdFromHints<T, Extract<RawSchemaColumns<T, TSchema>, ColumnHints<T> | undefined>> | DerivedColumnIdsFromColumns<ExtractSchemaColumns<TSchema>>;
+/** X-axis IDs resolved from one explicit schema definition. */
+type ResolvedXAxisColumnIdFromSchema<T, TSchema extends {
+  columns?: Record<string, unknown>;
+} | undefined = undefined> = ResolvedXAxisColumnIdFromHints<T, Extract<RawSchemaColumns<T, TSchema>, ColumnHints<T> | undefined>> | DerivedColumnIdsByTypeFromColumns<ExtractSchemaColumns<TSchema>, 'date' | 'category' | 'boolean'>;
+/** GroupBy IDs resolved from one explicit schema definition. */
+type ResolvedGroupByColumnIdFromSchema<T, TSchema extends {
+  columns?: Record<string, unknown>;
+} | undefined = undefined> = ResolvedGroupByColumnIdFromHints<T, Extract<RawSchemaColumns<T, TSchema>, ColumnHints<T> | undefined>> | DerivedColumnIdsByTypeFromColumns<ExtractSchemaColumns<TSchema>, 'category' | 'boolean'>;
+/** Filter IDs resolved from one explicit schema definition. */
+type ResolvedFilterColumnIdFromSchema<T, TSchema extends {
+  columns?: Record<string, unknown>;
+} | undefined = undefined> = ResolvedFilterColumnIdFromHints<T, Extract<RawSchemaColumns<T, TSchema>, ColumnHints<T> | undefined>> | DerivedColumnIdsByTypeFromColumns<ExtractSchemaColumns<TSchema>, 'category' | 'boolean'>;
+/** Metric column IDs resolved from one explicit schema definition. */
+type ResolvedMetricColumnIdFromSchema<T, TSchema extends {
+  columns?: Record<string, unknown>;
+} | undefined = undefined> = ResolvedMetricColumnIdFromHints<T, Extract<RawSchemaColumns<T, TSchema>, ColumnHints<T> | undefined>> | DerivedColumnIdsByTypeFromColumns<ExtractSchemaColumns<TSchema>, 'number'>;
+/** Date column IDs resolved from one explicit schema definition. */
+type ResolvedDateColumnIdFromSchema<T, TSchema extends {
+  columns?: Record<string, unknown>;
+} | undefined = undefined> = ResolvedDateColumnIdFromHints<T, Extract<RawSchemaColumns<T, TSchema>, ColumnHints<T> | undefined>> | DerivedColumnIdsByTypeFromColumns<ExtractSchemaColumns<TSchema>, 'date'>;
+/**
+ * Single authoritative explicit chart schema accepted by `useChart({schema})`.
+ *
+ * Think of this as the contract that sits on top of inference:
+ * - `columns` shapes what fields exist and how they behave
+ * - the top-level sections shape what the user is allowed to select in the UI
+ */
+type ChartSchema<T, TColumns extends Record<string, unknown> | undefined = Record<string, unknown> | undefined> = {
+  /**
+   * Override raw inferred fields, exclude raw fields with `false`, or declare
+   * brand new derived columns.
+   */
+  columns?: TColumns & Partial<Record<InferableFieldKey<T>, unknown>>; /** Restrict which non-numeric columns can be selected on the X-axis. */
+  xAxis?: XAxisConfig<string>; /** Restrict which categorical/boolean columns can split the chart into series. */
+  groupBy?: GroupByConfig<string>; /** Restrict which categorical/boolean columns appear in the filters UI. */
+  filters?: FiltersConfig<string>; /** Restrict which metrics and aggregations can be selected. */
+  metric?: MetricConfig<string>; /** Restrict which chart types are available to the user. */
+  chartType?: ChartTypeConfig; /** Restrict which time buckets are available for date X-axes. */
+  timeBucket?: TimeBucketConfig;
+};
+type ChartSchemaDefinitionBrand = {
+  readonly __chartSchemaBrand: 'chart-schema-definition';
+};
+/**
+ * Active filter state per column.
+ * - For category columns: Set of selected values (empty = no filter = show all)
+ * - For boolean columns: true/false/null (null = no filter)
+ */
+type FilterState<TColumnId extends string = string> = Map<TColumnId, Set<string>>;
+/** Sort direction. */
+type SortDirection = 'asc' | 'desc';
+/**
+ * Sort configuration.
+ *
+ * @property key - The data key to sort by (e.g. "count", a group label)
+ * @property direction - Sort direction
+ */
+type SortConfig = {
+  key: string;
+  direction: SortDirection;
+};
+/**
+ * Inference-first source definition accepted by multi-source charts.
+ *
+ * @property id - Unique identifier for this source
+ * @property label - Display label in the source switcher
+ * @property data - Array of raw data items
+ * @property schema - Optional explicit schema layered on top of inference
+ */
+type ChartSourceOptions<TId extends string = string, T = unknown, TSchema extends ChartSchema<T, any> | undefined = undefined> = {
+  id: TId;
+  label: string;
+  data: readonly T[];
+  schema?: DefinedChartSchema<T, Exclude<TSchema, undefined>>;
+};
+/** Convenience alias for any multi-source input definition. */
+type AnyChartSourceOptions = {
+  id: string;
+  label: string;
+  data: readonly any[];
+  schema?: any;
+};
+/** Multi-source charts require at least one source so an active source always exists. */
+type NonEmptyChartSourceOptions = readonly [AnyChartSourceOptions, ...AnyChartSourceOptions[]];
+/**
+ * A single series to render in the chart.
+ *
+ * @property dataKey - Key in the transformed data row
+ * @property label - Display label for tooltips/legend
+ * @property color - CSS color value (shadcn chart variable)
+ */
+type ChartSeries = {
+  dataKey: string;
+  label: string;
+  color: string;
+};
+/**
+ * A single data point in the transformed output.
+ * Keys are dynamic based on groupBy values.
+ */
+type TransformedDataPoint = Record<string, string | number>;
+/**
+ * Available filter options extracted from the data for a column.
+ *
+ * @property columnId - The column this filter belongs to
+ * @property label - Column label
+ * @property type - Column type (category or boolean)
+ * @property options - Available values with counts
+ */
+type AvailableFilter<TColumnId extends string = string> = {
+  columnId: TColumnId;
+  label: string;
+  type: 'category' | 'boolean';
+  options: Array<{
+    value: string;
+    label: string;
+    count: number;
+  }>;
+};
+/**
+ * Date range for a date column computed from the (filtered) data.
+ *
+ * @property columnId - The date column this range belongs to
+ * @property label - Column display label
+ * @property min - Earliest date in the data (null if no valid dates)
+ * @property max - Latest date in the data (null if no valid dates)
+ */
+type DateRange<TColumnId extends string = string> = {
+  columnId: TColumnId;
+  label: string;
+  min: Date | null;
+  max: Date | null;
+};
+/**
+ * User-selected date range filter applied to the reference date column.
+ * Both bounds are inclusive. Null = no bound on that side.
+ *
+ * @property from - Start date (inclusive), null = no lower bound
+ * @property to - End date (inclusive), null = no upper bound
+ */
+type DateRangeFilter = {
+  from: Date | null;
+  to: Date | null;
+};
+/**
+ * Full chart state returned by the useChart hook.
+ * Contains both controlled state and derived computations.
+ */
+type ChartInstance<T, TColumnId extends string = string, TChartType extends ChartType = ChartType, TXAxisId extends TColumnId = TColumnId, TGroupById extends TColumnId = TColumnId, TMetricColumnId extends TColumnId = TColumnId, TMetric extends Metric<any> = Metric<TMetricColumnId>, TFilterColumnId extends TColumnId = TColumnId, TDateColumnId extends TColumnId = TColumnId, TTimeBucket extends TimeBucket = TimeBucket> = {
+  /** Active source ID (only relevant for multi-source). */activeSourceId: string; /** Switch to a different data source. */
+  setActiveSource: (sourceId: string) => void; /** Whether multiple sources are available. */
+  hasMultipleSources: boolean; /** Labels for all available sources. */
+  sources: Array<{
+    id: string;
+    label: string;
+  }>; /** Current chart type. */
+  chartType: TChartType; /** Change the chart type. Runtime accepts only values in `availableChartTypes`. */
+  setChartType: (type: TChartType) => void; /** Chart types currently available given the active axis, grouping, and config. */
+  availableChartTypes: TChartType[]; /** Current X-axis column ID. */
+  xAxisId: TXAxisId | null;
+  /**
+   * Change the X-axis column.
+   * Runtime accepts only IDs currently present in `availableXAxes`.
+   */
+  setXAxis: (columnId: TXAxisId) => void;
+  /**
+   * Columns currently eligible for X-axis at runtime.
+   * Typing narrows only from explicit `columnHints.type`, not from runtime inference.
+   */
+  availableXAxes: Array<{
+    id: TXAxisId;
+    label: string;
+    type: 'date' | 'category' | 'boolean';
+  }>; /** Current groupBy column ID (null = no grouping). */
+  groupById: TGroupById | null;
+  /**
+   * Change the groupBy column.
+   * Runtime accepts only `null` or IDs currently present in `availableGroupBys`.
+   */
+  setGroupBy: (columnId: TGroupById | null) => void;
+  /**
+   * Columns currently eligible for groupBy at runtime.
+   * Explicit `config.groupBy.allowed` further narrows this list and the setter type.
+   */
+  availableGroupBys: Array<{
+    id: TGroupById;
+    label: string;
+  }>; /** Current metric (what the Y-axis measures). */
+  metric: TMetric;
+  /**
+   * Change the metric.
+   * Runtime accepts only metrics currently present in `availableMetrics`.
+   */
+  setMetric: (metric: TMetric) => void;
+  /**
+   * Metrics currently available at runtime.
+   * Explicit `config.metric.allowed` narrows both this list and the setter type.
+   */
+  availableMetrics: TMetric[]; /** Current time bucket (only relevant when X-axis is date). */
+  timeBucket: TTimeBucket; /** Change the time bucket. Runtime accepts only values in `availableTimeBuckets`. */
+  setTimeBucket: (bucket: TTimeBucket) => void; /** Time buckets currently available for the active chart state and config. */
+  availableTimeBuckets: TTimeBucket[]; /** Whether time bucketing controls should be shown. */
+  isTimeSeries: boolean; /** Active filter values per column. */
+  filters: FilterState<TFilterColumnId>;
+  /**
+   * Toggle a specific filter value on/off for a column.
+   * Runtime accepts only values currently exposed through `availableFilters`.
+   */
+  toggleFilter: (columnId: TFilterColumnId, value: string) => void; /** Clear all filters for a column when that column is currently filterable. */
+  clearFilter: (columnId: TFilterColumnId) => void; /** Clear all filters. */
+  clearAllFilters: () => void; /** Filter options currently available from the runtime data. */
+  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. */
+  referenceDateId: TDateColumnId | null;
+  /**
+   * Change the reference date column.
+   * Runtime accepts only IDs currently present in `availableDateColumns`.
+   */
+  setReferenceDateId: (columnId: TDateColumnId) => void; /** Date columns currently available as reference dates at runtime. */
+  availableDateColumns: Array<{
+    id: TDateColumnId;
+    label: string;
+  }>; /** Active date range filter (null = all time). */
+  dateRangeFilter: DateRangeFilter | null; /** Set the date range filter. Pass null to clear (show all time). */
+  setDateRangeFilter: (filter: DateRangeFilter | null) => void; /** Transformed data points ready for recharts. */
+  transformedData: TransformedDataPoint[]; /** Auto-generated series definitions for recharts. */
+  series: ChartSeries[]; /** Active columns for the current source. */
+  columns: readonly ChartColumn<T, TColumnId>[]; /** Raw data for the active source. */
+  rawData: readonly T[]; /** Total number of records in the active source (before filtering). */
+  recordCount: number;
+};
+/** Single-source chart instance narrowed by one explicit schema. */
+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>>;
+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, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
+type SourceXAxisColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedXAxisColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
+type SourceGroupByColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedGroupByColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
+type SourceMetricColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? Extract<MetricColumnIdFromMetric<RestrictedMetricFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>>>, ResolvedMetricColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>>> : never;
+type SourceFilterColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedFilterColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
+type SourceDateColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? ResolvedDateColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : 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 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;
+  sources: Array<{
+    id: SourceIdFromSources<TSources>;
+    label: string;
+  }>;
+  xAxisId: SourceXAxisColumnIdFromSource<TSource> | null;
+  setXAxis: (columnId: SourceColumnIdFromSources<TSources>) => void;
+  availableXAxes: Array<{
+    id: SourceXAxisColumnIdFromSource<TSource>;
+    label: string;
+    type: 'date' | 'category' | 'boolean';
+  }>;
+  groupById: SourceGroupByColumnIdFromSource<TSource> | null;
+  setGroupBy: (columnId: SourceColumnIdFromSources<TSources> | null) => void;
+  availableGroupBys: Array<{
+    id: SourceGroupByColumnIdFromSource<TSource>;
+    label: string;
+  }>;
+  metric: Metric<SourceMetricColumnIdFromSource<TSource>>;
+  setMetric: (metric: Metric<SourceColumnIdFromSources<TSources>>) => void;
+  availableMetrics: Metric<SourceMetricColumnIdFromSource<TSource>>[];
+  filters: FilterState<SourceFilterColumnIdFromSource<TSource>>;
+  toggleFilter: (columnId: SourceColumnIdFromSources<TSources>, value: string) => void;
+  clearFilter: (columnId: SourceColumnIdFromSources<TSources>) => void;
+  availableFilters: AvailableFilter<SourceFilterColumnIdFromSource<TSource>>[];
+  dateRange: DateRange<SourceDateColumnIdFromSource<TSource>> | null;
+  referenceDateId: SourceDateColumnIdFromSource<TSource> | null;
+  setReferenceDateId: (columnId: SourceColumnIdFromSources<TSources>) => void;
+  availableDateColumns: Array<{
+    id: SourceDateColumnIdFromSource<TSource>;
+    label: string;
+  }>;
+  columns: readonly ChartColumn<SourceRowFromSource<TSource>, SourceColumnIdFromSource<TSource>>[];
+};
+/**
+ * Direct multi-source hook return type.
+ * 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;
+//#endregion
+export { AggregateFunction, AggregateMetric, AvailableFilter, BooleanColumn, CategoricalChartType, CategoryColumn, ChartColumn, ChartColumnType, ChartInstance, ChartInstanceFromSchema, ChartSchema, ChartSeries, ChartSourceOptions, ChartType, ChartTypeConfig, ColumnFormat, ColumnFormatPreset, CountMetric, DateColumn, DateColumnFormat, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, ExactShape, 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, SchemaColumnsValidationShape, SelectableControlConfig, SortConfig, SortDirection, TimeBucket, TimeBucketConfig, TimeSeriesChartType, TransformedDataPoint, ValidatedChartSchema, XAxisConfig };