@matthieumordrel/chart-studio 0.2.3 → 0.2.5

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 };

package/dist/core/types.d.mts

@@ -1,3 +1,5 @@
+import { DateRangePresetId } from "./date-range-presets.mjs";
+
 //#region src/core/types.d.ts
 /**
  * Core types for chart-studio.
@@ -499,7 +501,18 @@ type ChartSchemaValidationTarget<T, TSchema extends ChartSchema<T, any>> = {
 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;
+/**
+ * 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.
+ */
+type ChartSchemaDefinition<T, TSchema extends ChartSchema<T, any> = ChartSchema<T, any>> = TSchema | {
+  build: () => DefinedChartSchema<T, TSchema>;
+};
+type ResolvedChartSchemaFromDefinition<TSchema> = TSchema extends DefinedChartSchema<any, infer TResolvedSchema> ? TResolvedSchema : TSchema extends {
+  build: () => DefinedChartSchema<any, infer TResolvedSchema>;
+} ? TResolvedSchema : TSchema extends ChartSchema<any, any> ? TSchema : 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. */
@@ -570,9 +583,9 @@ type NumberColumn<T, TId extends string = string> = ColumnBase<T, TId> & {
 /** 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';
+type TimeSeriesChartType = 'bar' | 'grouped-bar' | 'percent-bar' | 'line' | 'area' | 'percent-area';
 /** Chart types available for categorical (category/boolean X-axis). */
-type CategoricalChartType = 'bar' | 'pie' | 'donut';
+type CategoricalChartType = 'bar' | 'grouped-bar' | 'percent-bar' | 'pie' | 'donut';
 /** All supported chart types. */
 type ChartType = TimeSeriesChartType | CategoricalChartType;
 /** Time bucket sizes for date X-axis. */
@@ -655,7 +668,7 @@ type ChartTypeConfig = SelectableControlConfig<ChartType>;
 type TimeBucketConfig = SelectableControlConfig<TimeBucket>;
 type ExtractSchemaColumns<TSchema> = TSchema extends {
   columns?: infer TColumns;
-} ? Extract<TColumns, Record<string, unknown>> : undefined;
+} ? [Extract<TColumns, Record<string, unknown>>] extends [never] ? undefined : 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>;
@@ -706,6 +719,18 @@ type ChartSchema<T, TColumns extends Record<string, unknown> | undefined = Recor
   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;
+  /**
+   * Whether line and area charts should connect across null (empty bucket)
+   * data points instead of showing a gap.
+   *
+   * When `true` (default), the line bridges across empty buckets.
+   * When `false`, empty time buckets produce a visible gap in the line/area.
+   *
+   * This is useful for sparse datasets (e.g. quarterly data displayed in a
+   * monthly time bucket) where connecting across gaps produces a cleaner
+   * visual than showing drops to zero.
+   */
+  connectNulls?: boolean;
 };
 type ChartSchemaDefinitionBrand = {
   readonly __chartSchemaBrand: 'chart-schema-definition';
@@ -736,11 +761,11 @@ type SortConfig = {
  * @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> = {
+type ChartSourceOptions<TId extends string = string, T = unknown, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> = {
   id: TId;
   label: string;
   data: readonly T[];
-  schema?: DefinedChartSchema<T, Exclude<TSchema, undefined>>;
+  schema?: TSchema;
 };
 /** Convenience alias for any multi-source input definition. */
 type AnyChartSourceOptions = {
@@ -767,7 +792,7 @@ type ChartSeries = {
  * A single data point in the transformed output.
  * Keys are dynamic based on groupBy values.
  */
-type TransformedDataPoint = Record<string, string | number>;
+type TransformedDataPoint = Record<string, string | number | null>;
 /**
  * Available filter options extracted from the data for a column.
  *
@@ -869,7 +894,12 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
   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. */
+  isTimeSeries: boolean;
+  /**
+   * Whether line and area charts connect across null data points.
+   * Derived from the schema's `connectNulls` option.
+   */
+  connectNulls: boolean; /** Active filter values per column. */
   filters: FilterState<TFilterColumnId>;
   /**
    * Toggle a specific filter value on/off for a column.
@@ -891,8 +921,20 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
   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). */
+  }>; /** Active date range preset (null = custom range via `dateRangeFilter`). */
+  dateRangePreset: DateRangePresetId | null;
+  /**
+   * Select a named date range preset.
+   * The `dateRangeFilter` is derived automatically from the preset.
+   * For `'auto'`, the filter adjusts reactively when the time bucket changes.
+   */
+  setDateRangePreset: (preset: DateRangePresetId) => void; /** Active date range filter (null = all time). Derived from the preset when one is active. */
+  dateRangeFilter: DateRangeFilter | null;
+  /**
+   * Set the date range filter directly (custom range).
+   * Clears any active preset — the range becomes "Custom".
+   * Pass null to clear (show all time, equivalent to selecting 'all-time' preset).
+   */
   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. */
@@ -902,14 +944,16 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
 };
 /** 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>>;
+/** Single-source chart instance narrowed by any supported schema input. */
+type ChartInstanceFromSchemaDefinition<T, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> = ChartInstanceFromSchema<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, 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 SourceColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? ResolvedColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
+type SourceXAxisColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedXAxisColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
+type SourceGroupByColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedGroupByColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
+type SourceMetricColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? Extract<MetricColumnIdFromMetric<RestrictedMetricFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>>>, ResolvedMetricColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>>> : never;
+type SourceFilterColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedFilterColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
+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 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'> & {
@@ -954,4 +998,4 @@ type MultiSourceChartBranch<TSources extends NonEmptyChartSourceOptions, TSource
  */
 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 };
+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 };

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

@@ -1,4 +1,4 @@
-import { ChartSchema, ChartSourceOptions, DefinedChartSchema, NonEmptyChartSourceOptions } from "./types.mjs";
+import { ChartSchemaDefinition, ChartSourceOptions, NonEmptyChartSourceOptions } from "./types.mjs";
 
 //#region src/core/use-chart-options.d.ts
 /**
@@ -7,7 +7,7 @@ import { ChartSchema, ChartSourceOptions, DefinedChartSchema, NonEmptyChartSourc
  * This is the common case: one dataset, one optional schema, one optional
  * human-readable source label.
  */
-interface SingleSourceOptions<T, TSchema extends ChartSchema<T, any> | undefined = undefined> {
+interface SingleSourceOptions<T, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> {
   /**
    * Raw rows that chart-studio should inspect and transform.
    *
@@ -18,6 +18,9 @@ interface SingleSourceOptions<T, TSchema extends ChartSchema<T, any> | undefined
   /**
    * Optional explicit schema layered on top of inference.
    *
+   * Usually this is the fluent builder returned by `defineChartSchema<Row>()`.
+   * Plain schema objects are also accepted.
+   *
    * Use this when you want to:
    * - rename fields with `label`
    * - force or refine column `type`
@@ -26,7 +29,7 @@ interface SingleSourceOptions<T, TSchema extends ChartSchema<T, any> | undefined
    * - create derived columns
    * - restrict what users can select in the chart UI
    */
-  schema?: DefinedChartSchema<T, Exclude<TSchema, undefined>>;
+  schema?: TSchema;
   /**
    * Human-readable source name shown by the built-in UI when relevant.
    *
@@ -59,6 +62,6 @@ interface MultiSourceOptions<TSources extends NonEmptyChartSourceOptions = NonEm
 /**
  * Options for the useChart hook.
  */
-type UseChartOptions<T, TSchema extends ChartSchema<T, any> | undefined = undefined> = SingleSourceOptions<T, TSchema> | MultiSourceOptions;
+type UseChartOptions<T, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> = SingleSourceOptions<T, TSchema> | MultiSourceOptions;
 //#endregion
 export { SingleSourceOptions, UseChartOptions };

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

@@ -1,4 +1,4 @@
-import { ChartInstanceFromSchema, ChartSchema, MultiSourceChartInstance, NonEmptyChartSourceOptions } from "./types.mjs";
+import { ChartInstanceFromSchemaDefinition, ChartSchemaDefinition, MultiSourceChartInstance, NonEmptyChartSourceOptions } from "./types.mjs";
 import { SingleSourceOptions } from "./use-chart-options.mjs";
 
 //#region src/core/use-chart.d.ts
@@ -15,8 +15,8 @@ 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
- *   Any explicit single-source or per-source schema should be created with
- *   `defineChartSchema<Row>()(...)` so the schema shape stays exact and strongly typed.
+ *   Any explicit single-source or per-source schema is usually authored with
+ *   `defineChartSchema<Row>()...`. Plain schema objects are also accepted.
  *
  * @returns {ChartInstance}
  *   An object representing chart configuration, state, and all derived data/operations:
@@ -45,6 +45,6 @@ declare function useChart<const TSources extends NonEmptyChartSourceOptions>(opt
   sourceLabel?: never;
   sources: TSources;
 }): MultiSourceChartInstance<TSources>;
-declare function useChart<T, const TSchema extends ChartSchema<T, any> | undefined = undefined>(options: SingleSourceOptions<T, TSchema>): ChartInstanceFromSchema<T, TSchema>;
+declare function useChart<T, const TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined>(options: SingleSourceOptions<T, TSchema>): ChartInstanceFromSchemaDefinition<T, TSchema>;
 //#endregion
 export { useChart };