@matthieumordrel/chart-studio 0.3.0 → 0.4.0

package/dist/core/dashboard.types.d.mts

@@ -0,0 +1,220 @@
+import { DateRangePresetId } from "./date-range-presets.mjs";
+import { ChartInstance, ChartInstanceFromSchemaDefinition, DateRangeFilter, ResolvedDateColumnIdFromSchema, ResolvedFilterColumnIdFromSchema } from "./types.mjs";
+import { DatasetChartDefinition, DatasetRow } from "./dataset-builder.types.mjs";
+import { MaterializedViewDefinition } from "./materialized-view.types.mjs";
+import { AnyDefinedDataModel, DataModelDefinition, ModelAttributeDefinition, ModelDataInput, ModelDatasetId, ModelDatasets, ResolvedDataModelFromDefinition } from "./data-model.types.mjs";
+
+//#region src/core/dashboard.types.d.ts
+type UniqueId<TId extends string, TExisting extends string> = TId extends TExisting ? never : TId;
+type AnyDatasetChartDefinition = DatasetChartDefinition<any, any, any, any, any, any, any, any, any, any, any>;
+type ChartOwnerFromDefinition<TChart> = TChart extends DatasetChartDefinition<any, any, any, any, any, any, any, any, any, any, infer TOwner> ? TOwner : never;
+type DatasetFilterColumnId<TDataset> = TDataset extends {
+  columns?: Record<string, unknown> | undefined;
+} | undefined ? ResolvedFilterColumnIdFromSchema<DatasetRow<TDataset>, TDataset> : never;
+type DatasetDateColumnId<TDataset> = TDataset extends {
+  columns?: Record<string, unknown> | undefined;
+} | undefined ? ResolvedDateColumnIdFromSchema<DatasetRow<TDataset>, TDataset> : never;
+type DatasetIdForOwner<TModel extends AnyDefinedDataModel, TOwner> = Extract<{ [TId in keyof TModel['datasets']]: TOwner extends TModel['datasets'][TId] ? TId : never }[keyof TModel['datasets']], string>;
+type ResolvedDashboardChartDatasetId<TModel extends AnyDefinedDataModel, TChart extends AnyDatasetChartDefinition> = ChartOwnerFromDefinition<TChart> extends MaterializedViewDefinition<any, any, any, any, any, infer TBaseDatasetId extends string, any> ? TBaseDatasetId : DatasetIdForOwner<TModel, ChartOwnerFromDefinition<TChart>>;
+type DashboardChartRegistration<TDatasetId extends string = string, TChart extends AnyDatasetChartDefinition = AnyDatasetChartDefinition, TDataSource extends DashboardChartDataSource<TDatasetId> = DashboardChartDataSource<TDatasetId>> = {
+  readonly id: string;
+  readonly datasetId: TDatasetId;
+  readonly schema: TChart;
+  readonly dataSource: TDataSource;
+};
+type DashboardCharts = Record<string, DashboardChartRegistration>;
+type DashboardDatasetChartDataSource<TDatasetId extends string = string> = {
+  readonly kind: 'dataset';
+  readonly datasetId: TDatasetId;
+};
+type DashboardMaterializedViewChartDataSource<TDatasetId extends string = string, TView extends MaterializedViewDefinition<any, any, any, any> = MaterializedViewDefinition<any, any, any, any>> = {
+  readonly kind: 'materialized-view';
+  readonly datasetId: TDatasetId;
+  readonly view: TView;
+};
+type DashboardChartDataSource<TDatasetId extends string = string> = DashboardDatasetChartDataSource<TDatasetId> | DashboardMaterializedViewChartDataSource<TDatasetId>;
+type DashboardChartDataSourceForOwner<TDatasetId extends string, TOwner> = TOwner extends MaterializedViewDefinition<any, any, any, any> ? DashboardMaterializedViewChartDataSource<TDatasetId, TOwner> : DashboardDatasetChartDataSource<TDatasetId>;
+type ResolvedDashboardChartDataSource<TModel extends AnyDefinedDataModel, TChart extends AnyDatasetChartDefinition> = DashboardChartDataSourceForOwner<ResolvedDashboardChartDatasetId<TModel, TChart>, ChartOwnerFromDefinition<TChart>>;
+type DashboardLocalSharedSelectFilterConfig<TDatasets extends ModelDatasets, TSourceDatasetId extends ModelDatasetId<TDatasets>, TSourceColumnId extends DatasetFilterColumnId<TDatasets[TSourceDatasetId]>, TTargets extends readonly DashboardSharedSelectTarget<TDatasets>[] | undefined = undefined> = {
+  readonly kind: 'select';
+  readonly label?: string;
+  readonly source: {
+    readonly dataset: TSourceDatasetId;
+    readonly column: TSourceColumnId;
+  };
+  readonly targets?: TTargets;
+};
+type DashboardSharedSelectTarget<TDatasets extends ModelDatasets, TDatasetId extends ModelDatasetId<TDatasets> = ModelDatasetId<TDatasets>> = {
+  readonly dataset: TDatasetId;
+  readonly column: DatasetFilterColumnId<TDatasets[TDatasetId]>;
+};
+type DashboardSharedDateRangeTarget<TDatasets extends ModelDatasets, TDatasetId extends ModelDatasetId<TDatasets> = ModelDatasetId<TDatasets>> = {
+  readonly dataset: TDatasetId;
+  readonly column: DatasetDateColumnId<TDatasets[TDatasetId]>;
+};
+type DashboardSharedDateRangeFilterConfig<TDatasets extends ModelDatasets, TTargets extends readonly DashboardSharedDateRangeTarget<TDatasets>[] = readonly DashboardSharedDateRangeTarget<TDatasets>[]> = {
+  readonly kind: 'date-range';
+  readonly label?: string;
+  readonly targets: TTargets;
+};
+type DashboardModelSharedFilterDefinition<TId extends string = string, TAttribute extends ModelAttributeDefinition = ModelAttributeDefinition> = {
+  readonly id: TId;
+  readonly kind: 'select';
+  readonly label: string;
+  readonly source: {
+    readonly kind: 'attribute';
+    readonly dataset: TAttribute['source']['dataset'];
+    readonly key: TAttribute['source']['key'];
+    readonly label: TAttribute['source']['label'];
+  };
+  readonly targets: TAttribute['targets'];
+  readonly attribute: TId;
+};
+type DashboardLocalSharedSelectFilterDefinition<TId extends string = string, TDatasets extends ModelDatasets = ModelDatasets> = {
+  readonly id: TId;
+  readonly kind: 'select';
+  readonly label: string;
+  readonly source: {
+    readonly kind: 'column';
+    readonly dataset: ModelDatasetId<TDatasets>;
+    readonly column: DatasetFilterColumnId<TDatasets[ModelDatasetId<TDatasets>]>;
+  };
+  readonly targets: readonly DashboardSharedSelectTarget<TDatasets>[];
+};
+type DashboardSharedDateRangeFilterDefinition<TId extends string = string, TDatasets extends ModelDatasets = ModelDatasets> = {
+  readonly id: TId;
+  readonly kind: 'date-range';
+  readonly label: string;
+  readonly targets: readonly DashboardSharedDateRangeTarget<TDatasets>[];
+};
+type DashboardSharedFilterDefinition<TModel extends AnyDefinedDataModel = AnyDefinedDataModel> = DashboardModelSharedFilterDefinition<string, ModelAttributeDefinition> | DashboardLocalSharedSelectFilterDefinition<string, TModel['datasets']> | DashboardSharedDateRangeFilterDefinition<string, TModel['datasets']>;
+type DashboardSharedFilters<TModel extends AnyDefinedDataModel = AnyDefinedDataModel> = Record<string, DashboardSharedFilterDefinition<TModel>>;
+type DefinedDashboard<TModel extends AnyDefinedDataModel = AnyDefinedDataModel, TCharts extends DashboardCharts = {}, TSharedFilters extends DashboardSharedFilters<TModel> = {}> = {
+  readonly model: TModel;
+  readonly charts: TCharts;
+  readonly sharedFilters: TSharedFilters;
+  build(): DefinedDashboard<TModel, TCharts, TSharedFilters>;
+  readonly __dashboardBrand: 'dashboard-definition';
+};
+type DashboardDefinition<TModel extends AnyDefinedDataModel = AnyDefinedDataModel, TCharts extends DashboardCharts = {}, TSharedFilters extends DashboardSharedFilters<TModel> = {}> = {
+  build(): DefinedDashboard<TModel, TCharts, TSharedFilters>;
+};
+type ResolvedDashboardFromDefinition<TDashboard> = TDashboard extends DashboardDefinition<any, any, any> ? ReturnType<TDashboard['build']> : never;
+type DashboardChartIdFromDefinition<TDashboard> = Extract<keyof ResolvedDashboardFromDefinition<TDashboard>['charts'], string>;
+type DashboardSharedFilterIdFromDefinition<TDashboard> = Extract<keyof ResolvedDashboardFromDefinition<TDashboard>['sharedFilters'], string>;
+type DashboardDatasetIdFromDefinition<TDashboard> = Extract<keyof ResolvedDashboardFromDefinition<TDashboard>['model']['datasets'], string>;
+type DashboardDataInputFromDefinition<TDashboard extends DashboardDefinition<any, any, any>> = ModelDataInput<ResolvedDashboardFromDefinition<TDashboard>['model']['datasets']>;
+type DashboardChartDefinitionFromDefinition<TDashboard, TChartId extends DashboardChartIdFromDefinition<TDashboard>> = ResolvedDashboardFromDefinition<TDashboard>['charts'][TChartId]['schema'];
+type DashboardChartDatasetIdFromDefinition<TDashboard, TChartId extends DashboardChartIdFromDefinition<TDashboard>> = ResolvedDashboardFromDefinition<TDashboard>['charts'][TChartId]['datasetId'];
+type DashboardRelationshipsFromDefinition<TDashboard> = ResolvedDashboardFromDefinition<TDashboard>['model']['relationships'];
+type StripIdSuffix<TValue extends string> = TValue extends `${infer TPrefix}Id` ? TPrefix : never;
+type ProjectedLookupAliasForDataset<TRelationships, TSourceDatasetId extends string, TBaseDatasetId extends string> = Extract<{ [TRelationshipId in keyof TRelationships]: TRelationships[TRelationshipId] extends {
+  from: {
+    dataset: TSourceDatasetId;
+  };
+  to: {
+    dataset: TBaseDatasetId;
+    column: infer TColumnId extends string;
+  };
+} ? StripIdSuffix<TColumnId> : never }[keyof TRelationships], string>;
+type ProjectedOwnedColumnId<TRelationships, TSourceDatasetId extends string, TBaseDatasetId extends string, TColumnId extends string> = ProjectedLookupAliasForDataset<TRelationships, TSourceDatasetId, TBaseDatasetId> extends infer TAlias extends string ? `${TAlias}${Capitalize<TColumnId>}` : never;
+type OwnedColumnIdForDatasetColumn<TRelationships, TDatasetId extends string, TBaseDatasetId extends string, TColumnId extends string> = TDatasetId extends TBaseDatasetId ? TColumnId : ProjectedOwnedColumnId<TRelationships, TDatasetId, TBaseDatasetId, TColumnId>;
+type SharedFilterTargetOwnedFilterColumnIds<TRelationships, TBaseDatasetId extends string, TTargets> = TTargets extends readonly (infer TTarget)[] ? TTarget extends {
+  dataset: infer TDatasetId extends string;
+  column: infer TColumnId extends string;
+} ? OwnedColumnIdForDatasetColumn<TRelationships, TDatasetId, TBaseDatasetId, TColumnId> : never : never;
+type SharedFilterTargetOwnedDateColumnIds<TRelationships, TBaseDatasetId extends string, TTargets> = TTargets extends readonly (infer TTarget)[] ? TTarget extends {
+  dataset: infer TDatasetId extends string;
+  column: infer TColumnId extends string;
+} ? OwnedColumnIdForDatasetColumn<TRelationships, TDatasetId, TBaseDatasetId, TColumnId> : never : never;
+type DashboardOwnedFilterColumnIdsForSharedFilter<TDashboard, TChartId extends DashboardChartIdFromDefinition<TDashboard>, TFilter> = TFilter extends {
+  kind: 'select';
+  source: {
+    kind: 'attribute';
+    dataset: infer TSourceDatasetId extends string;
+    key: infer TSourceKey extends string;
+    label: infer TSourceLabel extends string;
+  };
+  targets: infer TTargets;
+} ? OwnedColumnIdForDatasetColumn<DashboardRelationshipsFromDefinition<TDashboard>, TSourceDatasetId, DashboardChartDatasetIdFromDefinition<TDashboard, TChartId>, TSourceKey | TSourceLabel> | SharedFilterTargetOwnedFilterColumnIds<DashboardRelationshipsFromDefinition<TDashboard>, DashboardChartDatasetIdFromDefinition<TDashboard, TChartId>, TTargets> : TFilter extends {
+  kind: 'select';
+  source: {
+    kind: 'column';
+    dataset: infer TSourceDatasetId extends string;
+    column: infer TSourceColumnId extends string;
+  };
+  targets: infer TTargets;
+} ? OwnedColumnIdForDatasetColumn<DashboardRelationshipsFromDefinition<TDashboard>, TSourceDatasetId, DashboardChartDatasetIdFromDefinition<TDashboard, TChartId>, TSourceColumnId> | SharedFilterTargetOwnedFilterColumnIds<DashboardRelationshipsFromDefinition<TDashboard>, DashboardChartDatasetIdFromDefinition<TDashboard, TChartId>, TTargets> : never;
+type DashboardOwnedDateColumnIdsForSharedFilter<TDashboard, TChartId extends DashboardChartIdFromDefinition<TDashboard>, TFilter> = TFilter extends {
+  kind: 'date-range';
+  targets: infer TTargets;
+} ? SharedFilterTargetOwnedDateColumnIds<DashboardRelationshipsFromDefinition<TDashboard>, DashboardChartDatasetIdFromDefinition<TDashboard, TChartId>, TTargets> : never;
+type DashboardOwnedFilterColumnIdFromDefinition<TDashboard, TChartId extends DashboardChartIdFromDefinition<TDashboard>> = DashboardSharedFilterIdFromDefinition<TDashboard> extends infer TFilterId ? TFilterId extends DashboardSharedFilterIdFromDefinition<TDashboard> ? DashboardOwnedFilterColumnIdsForSharedFilter<TDashboard, TChartId, ResolvedDashboardFromDefinition<TDashboard>['sharedFilters'][TFilterId]> : never : never;
+type DashboardOwnedDateColumnIdFromDefinition<TDashboard, TChartId extends DashboardChartIdFromDefinition<TDashboard>> = DashboardSharedFilterIdFromDefinition<TDashboard> extends infer TFilterId ? TFilterId extends DashboardSharedFilterIdFromDefinition<TDashboard> ? DashboardOwnedDateColumnIdsForSharedFilter<TDashboard, TChartId, ResolvedDashboardFromDefinition<TDashboard>['sharedFilters'][TFilterId]> : never : never;
+type DashboardOwnedChartInstance<TChartInstance, TOwnedFilterColumnId extends string, TOwnedDateColumnId extends string> = TChartInstance extends ChartInstance<infer TRow, infer TColumnId, infer TChartType, infer TXAxisId, infer TGroupById, infer TMetricColumnId, infer TMetric, infer TFilterColumnId, infer TDateColumnId, infer TTimeBucket> ? ChartInstance<TRow, TColumnId, TChartType, TXAxisId, TGroupById, TMetricColumnId, TMetric, Exclude<TFilterColumnId, TOwnedFilterColumnId>, Exclude<TDateColumnId, TOwnedDateColumnId>, TTimeBucket> : never;
+type DashboardChartInstanceFromDefinition<TDashboard, TChartId extends DashboardChartIdFromDefinition<TDashboard>> = DashboardChartDefinitionFromDefinition<TDashboard, TChartId> extends DatasetChartDefinition<infer TRow, any, any, any, any, any, any, any, any, any, any> ? DashboardOwnedChartInstance<ChartInstanceFromSchemaDefinition<TRow, DashboardChartDefinitionFromDefinition<TDashboard, TChartId>>, Extract<DashboardOwnedFilterColumnIdFromDefinition<TDashboard, TChartId>, string>, Extract<DashboardOwnedDateColumnIdFromDefinition<TDashboard, TChartId>, string>> : never;
+type DashboardDatasetRowsFromDefinition<TDashboard, TDatasetId extends DashboardDatasetIdFromDefinition<TDashboard>> = readonly DatasetRow<ResolvedDashboardFromDefinition<TDashboard>['model']['datasets'][TDatasetId]>[];
+type DashboardSharedDateRangePresetId = Exclude<DateRangePresetId, 'auto'>;
+type DashboardDateRangeSelection = {
+  preset: DashboardSharedDateRangePresetId | null;
+  customFilter: DateRangeFilter | null;
+};
+type DashboardSharedSelectFilterRuntime = {
+  readonly id: string;
+  readonly kind: 'select';
+  readonly label: string;
+  readonly values: ReadonlySet<string>;
+  readonly options: Array<{
+    value: string;
+    label: string;
+    count: number;
+  }>;
+  toggleValue(value: string): void;
+  setValues(values: Iterable<string>): void;
+  clear(): void;
+};
+type DashboardSharedDateRangeFilterRuntime = {
+  readonly id: string;
+  readonly kind: 'date-range';
+  readonly label: string;
+  readonly selection: DashboardDateRangeSelection;
+  readonly dateRangeFilter: DateRangeFilter | null;
+  setSelection(selection: DashboardDateRangeSelection): void;
+  setDateRangePreset(preset: DashboardSharedDateRangePresetId): void;
+  setDateRangeFilter(filter: DateRangeFilter | null): void;
+  clear(): void;
+};
+type DashboardSharedFilterRuntime = DashboardSharedSelectFilterRuntime | DashboardSharedDateRangeFilterRuntime;
+type DashboardSharedFilterRuntimeFromDefinition<TDashboard, TFilterId extends DashboardSharedFilterIdFromDefinition<TDashboard>> = ResolvedDashboardFromDefinition<TDashboard>['sharedFilters'][TFilterId] extends {
+  kind: 'date-range';
+} ? DashboardSharedDateRangeFilterRuntime : DashboardSharedSelectFilterRuntime;
+type DashboardResolvedChartOwnership = {
+  readonly sharedFilterIds: readonly string[];
+  readonly filterColumnIds: ReadonlySet<string>;
+  readonly dateColumnIds: ReadonlySet<string>;
+};
+type DashboardResolvedChart<TDashboard, TChartId extends DashboardChartIdFromDefinition<TDashboard>> = DashboardChartDefinitionFromDefinition<TDashboard, TChartId> extends DatasetChartDefinition<infer TRow, any, any, any, any, any, any, any, any, any, any> ? {
+  readonly id: TChartId;
+  readonly datasetId: ResolvedDashboardFromDefinition<TDashboard>['charts'][TChartId]['datasetId'];
+  readonly source: ResolvedDashboardFromDefinition<TDashboard>['charts'][TChartId]['dataSource'];
+  readonly data: readonly TRow[];
+  readonly schema: DashboardChartDefinitionFromDefinition<TDashboard, TChartId>;
+  readonly ownership: DashboardResolvedChartOwnership;
+} : never;
+type DashboardRuntime<TDashboard extends DashboardDefinition<any, any, any> = DashboardDefinition<any, any, any>> = {
+  readonly definition: ResolvedDashboardFromDefinition<TDashboard>;
+  readonly chartIds: DashboardChartIdFromDefinition<TDashboard>[];
+  readonly sharedFilterIds: DashboardSharedFilterIdFromDefinition<TDashboard>[];
+  chart<TChartId extends DashboardChartIdFromDefinition<TDashboard>>(id: TChartId): DashboardResolvedChart<TDashboard, TChartId>;
+  dataset<TDatasetId extends DashboardDatasetIdFromDefinition<TDashboard>>(id: TDatasetId): DashboardDatasetRowsFromDefinition<TDashboard, TDatasetId>;
+  sharedFilter<TFilterId extends DashboardSharedFilterIdFromDefinition<TDashboard>>(id: TFilterId): DashboardSharedFilterRuntimeFromDefinition<TDashboard, TFilterId>;
+};
+interface DashboardBuilder<TModel extends AnyDefinedDataModel = AnyDefinedDataModel, TCharts extends DashboardCharts = {}, TSharedFilters extends DashboardSharedFilters<TModel> = {}> extends DashboardDefinition<TModel, TCharts, TSharedFilters> {
+  chart<const TId extends string, const TChart extends AnyDatasetChartDefinition>(id: UniqueId<TId, Extract<keyof TCharts, string>>, chart: TChart): DashboardBuilder<TModel, TCharts & Record<TId, DashboardChartRegistration<ResolvedDashboardChartDatasetId<TModel, TChart>, TChart, ResolvedDashboardChartDataSource<TModel, TChart>>>, TSharedFilters>;
+  sharedFilter<const TId extends Extract<keyof TModel['attributes'], string>>(id: UniqueId<TId, Extract<keyof TSharedFilters, string>>): DashboardBuilder<TModel, TCharts, TSharedFilters & Record<TId, DashboardModelSharedFilterDefinition<TId, ModelAttributeDefinition>>>;
+  sharedFilter<const TId extends string, const TSourceDatasetId extends ModelDatasetId<TModel['datasets']>, const TSourceColumnId extends DatasetFilterColumnId<TModel['datasets'][TSourceDatasetId]>, const TTargets extends readonly DashboardSharedSelectTarget<TModel['datasets']>[] | undefined = undefined>(id: UniqueId<TId, Extract<keyof TSharedFilters, string>>, config: DashboardLocalSharedSelectFilterConfig<TModel['datasets'], TSourceDatasetId, TSourceColumnId, TTargets>): DashboardBuilder<TModel, TCharts, TSharedFilters & Record<TId, DashboardLocalSharedSelectFilterDefinition<TId, TModel['datasets']>>>;
+  sharedFilter<const TId extends string, const TTargets extends readonly DashboardSharedDateRangeTarget<TModel['datasets']>[]>(id: UniqueId<TId, Extract<keyof TSharedFilters, string>>, config: DashboardSharedDateRangeFilterConfig<TModel['datasets'], TTargets>): DashboardBuilder<TModel, TCharts, TSharedFilters & Record<TId, DashboardSharedDateRangeFilterDefinition<TId, TModel['datasets']>>>;
+}
+type DashboardInputModel<TModel extends DataModelDefinition<any, any, any, any>> = ResolvedDataModelFromDefinition<TModel>;
+//#endregion
+export { DashboardBuilder, DashboardChartIdFromDefinition, DashboardChartInstanceFromDefinition, DashboardDataInputFromDefinition, DashboardDatasetIdFromDefinition, DashboardDatasetRowsFromDefinition, DashboardDateRangeSelection, DashboardDefinition, DashboardInputModel, DashboardLocalSharedSelectFilterConfig, DashboardResolvedChart, DashboardResolvedChartOwnership, DashboardRuntime, DashboardSharedDateRangeFilterConfig, DashboardSharedDateRangeFilterDefinition, DashboardSharedDateRangeFilterRuntime, DashboardSharedDateRangePresetId, DashboardSharedDateRangeTarget, DashboardSharedFilterDefinition, DashboardSharedFilterIdFromDefinition, DashboardSharedFilterRuntime, DashboardSharedFilterRuntimeFromDefinition, DashboardSharedFilters, DashboardSharedSelectFilterRuntime, DashboardSharedSelectTarget, DefinedDashboard, ResolvedDashboardFromDefinition };

package/dist/core/data-label-defaults.mjs

@@ -0,0 +1,74 @@
+//#region src/core/data-label-defaults.ts
+const STYLE_TOP = {
+	position: "top",
+	offset: 8
+};
+/**
+* Default data-label behaviour for each chart type.
+*
+* This is the single source of truth consumed by `<ChartCanvas>` when the
+* consumer leaves `showDataLabels` at its default `'auto'` value.  Edit
+* this object to change which charts show labels and how they look.
+*/
+const DATA_LABEL_DEFAULTS = {
+	bar: {
+		showByDefault: true,
+		style: STYLE_TOP
+	},
+	"grouped-bar": {
+		showByDefault: true,
+		style: STYLE_TOP
+	},
+	"percent-bar": {
+		showByDefault: true,
+		style: STYLE_TOP
+	},
+	line: {
+		showByDefault: {
+			day: false,
+			week: false,
+			month: false,
+			quarter: true,
+			year: true
+		},
+		style: STYLE_TOP
+	},
+	area: {
+		showByDefault: {
+			day: false,
+			week: false,
+			month: false,
+			quarter: false,
+			year: false
+		},
+		style: STYLE_TOP
+	},
+	"percent-area": {
+		showByDefault: false,
+		style: STYLE_TOP
+	},
+	pie: {
+		showByDefault: true,
+		style: STYLE_TOP
+	},
+	donut: {
+		showByDefault: true,
+		style: STYLE_TOP
+	}
+};
+/**
+* Resolve whether data labels should be shown for the current chart state.
+*
+* When the consumer passes `true` or `false`, their explicit choice wins.
+* When `'auto'` (the default), the declarative config in
+* {@link DATA_LABEL_DEFAULTS} decides based on chart type and — for
+* time-series charts — the active time bucket.
+*/
+function resolveShowDataLabels(chartType, timeBucket, override) {
+	if (override !== "auto") return override;
+	const { showByDefault } = DATA_LABEL_DEFAULTS[chartType];
+	if (typeof showByDefault === "boolean") return showByDefault;
+	return timeBucket ? showByDefault[timeBucket] ?? false : false;
+}
+//#endregion
+export { DATA_LABEL_DEFAULTS, resolveShowDataLabels };

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

@@ -0,0 +1,196 @@
+import { InferableFieldKey, ResolvedGroupByColumnIdFromSchema } from "./types.mjs";
+import { DatasetChartDefinition, DatasetDefinition, DatasetKey, DatasetRow, DefinedDataset, ResolvedDatasetFromDefinition, SingleDatasetKeyId } from "./dataset-builder.types.mjs";
+import { MaterializedViewDefinition, ModelMaterializationStartBuilder } from "./materialized-view.types.mjs";
+import { CompileModelChartDefinition, InferredModelChartBuilder, ModelChartBuilder, ModelChartStartBuilder } from "./model-chart.types.mjs";
+import { InferAttributesForModel, InferRelationshipsForModel } from "./model-inference.types.mjs";
+
+//#region src/core/data-model.types.d.ts
+type NonNullish<T> = Exclude<T, null | undefined>;
+type UniqueId<TId extends string, TExisting extends string> = TId extends TExisting ? never : TId;
+type KeyedDatasetDefinition<TRow = any, TColumns extends Record<string, unknown> | undefined = any, TKey extends DatasetKey<TRow> = DatasetKey<TRow>> = DatasetDefinition<TRow, TColumns, TKey>;
+type ModelDatasets = Record<string, DefinedDataset<any, any, any>>;
+type ModelDatasetId<TDatasets extends ModelDatasets> = Extract<keyof TDatasets, string>;
+type ModelSingleKeyDatasetId<TDatasets extends ModelDatasets> = Extract<{ [TId in keyof TDatasets]: SingleDatasetKeyId<TDatasets[TId]> extends never ? never : TId }[keyof TDatasets], string>;
+type DatasetForeignKeyColumnId<TDataset> = TDataset extends DefinedDataset<infer TRow, any, any> ? InferableFieldKey<TRow> : never;
+type DatasetKeyValue<TDataset> = TDataset extends DefinedDataset<infer TRow, any, any> ? SingleDatasetKeyId<TDataset> extends infer TKeyId extends keyof TRow ? NonNullish<TRow[TKeyId]> : never : never;
+type ModelRelationshipDefinition<TFromDatasetId extends string = string, TToDatasetId extends string = string, TFromKey extends string = string, TToColumn extends string = string> = {
+  readonly kind: 'relationship';
+  readonly id: string;
+  readonly from: {
+    readonly dataset: TFromDatasetId;
+    readonly key: TFromKey;
+  };
+  readonly to: {
+    readonly dataset: TToDatasetId;
+    readonly column: TToColumn;
+  };
+  readonly reverse: {
+    readonly dataset: TToDatasetId;
+    readonly column: TToColumn;
+    readonly to: {
+      readonly dataset: TFromDatasetId;
+      readonly key: TFromKey;
+    };
+  };
+};
+type RelationshipConfig<TDatasets extends ModelDatasets, TFromDatasetId extends ModelSingleKeyDatasetId<TDatasets>, TToDatasetId extends ModelDatasetId<TDatasets>> = {
+  readonly from: {
+    readonly dataset: TFromDatasetId;
+    readonly key: SingleDatasetKeyId<TDatasets[TFromDatasetId]>;
+  };
+  readonly to: {
+    readonly dataset: TToDatasetId;
+    readonly column: DatasetForeignKeyColumnId<TDatasets[TToDatasetId]>;
+  };
+};
+type AssociationEndpoints<TDatasets extends ModelDatasets, TFromDatasetId extends ModelSingleKeyDatasetId<TDatasets>, TToDatasetId extends ModelSingleKeyDatasetId<TDatasets>> = {
+  readonly from: {
+    readonly dataset: TFromDatasetId;
+    readonly key: SingleDatasetKeyId<TDatasets[TFromDatasetId]>;
+  };
+  readonly to: {
+    readonly dataset: TToDatasetId;
+    readonly key: SingleDatasetKeyId<TDatasets[TToDatasetId]>;
+  };
+};
+type ExplicitAssociationConfig<TDatasets extends ModelDatasets, TFromDatasetId extends ModelSingleKeyDatasetId<TDatasets>, TToDatasetId extends ModelSingleKeyDatasetId<TDatasets>, TEdgeRow extends Record<string, unknown>> = AssociationEndpoints<TDatasets, TFromDatasetId, TToDatasetId> & {
+  readonly data: readonly TEdgeRow[];
+  readonly columns: {
+    readonly from: Extract<keyof TEdgeRow, string>;
+    readonly to: Extract<keyof TEdgeRow, string>;
+  };
+};
+type DerivedAssociationConfigForSource<TDatasets extends ModelDatasets, TSourceDatasetId extends ModelSingleKeyDatasetId<TDatasets>, TOtherDatasetId extends ModelSingleKeyDatasetId<TDatasets>> = AssociationEndpoints<TDatasets, TSourceDatasetId, TOtherDatasetId> & {
+  readonly deriveFrom: {
+    readonly dataset: TSourceDatasetId;
+    readonly values: (row: DatasetRow<TDatasets[TSourceDatasetId]>) => readonly DatasetKeyValue<TDatasets[TOtherDatasetId]>[] | null | undefined;
+  };
+};
+type DerivedAssociationConfig<TDatasets extends ModelDatasets, TFromDatasetId extends ModelSingleKeyDatasetId<TDatasets>, TToDatasetId extends ModelSingleKeyDatasetId<TDatasets>, TDeriveDatasetId extends TFromDatasetId | TToDatasetId = TFromDatasetId | TToDatasetId> = TDeriveDatasetId extends TFromDatasetId ? DerivedAssociationConfigForSource<TDatasets, TFromDatasetId, TToDatasetId> : DerivedAssociationConfigForSource<TDatasets, TToDatasetId, TFromDatasetId>;
+type ModelAssociationDefinition<TFromDatasetId extends string = string, TToDatasetId extends string = string, TFromKey extends string = string, TToKey extends string = string> = {
+  readonly kind: 'association';
+  readonly id: string;
+  readonly from: {
+    readonly dataset: TFromDatasetId;
+    readonly key: TFromKey;
+  };
+  readonly to: {
+    readonly dataset: TToDatasetId;
+    readonly key: TToKey;
+  };
+  readonly reverse: {
+    readonly dataset: TToDatasetId;
+    readonly key: TToKey;
+    readonly to: {
+      readonly dataset: TFromDatasetId;
+      readonly key: TFromKey;
+    };
+  };
+  readonly edge: {
+    readonly kind: 'explicit';
+    readonly data: readonly Record<string, unknown>[];
+    readonly columns: {
+      readonly from: string;
+      readonly to: string;
+    };
+  } | {
+    readonly kind: 'derived';
+    readonly deriveFrom: {
+      readonly dataset: string;
+      readonly values: (row: unknown) => readonly unknown[] | null | undefined;
+    };
+  };
+};
+type RelationshipTarget<TRelationships extends Record<string, ModelRelationshipDefinition>, TSourceDatasetId extends string> = { [TRelationshipId in keyof TRelationships]: TRelationships[TRelationshipId] extends ModelRelationshipDefinition<TSourceDatasetId, infer TTargetDatasetId extends string, any, infer TToColumn extends string> ? {
+  readonly dataset: TTargetDatasetId;
+  readonly column: TToColumn;
+  readonly via: Extract<TRelationshipId, string>;
+} : never }[keyof TRelationships];
+type AssociationTarget<TAssociations extends Record<string, ModelAssociationDefinition>, TSourceDatasetId extends string> = { [TAssociationId in keyof TAssociations]: TAssociations[TAssociationId] extends ModelAssociationDefinition<infer TFromDatasetId extends string, infer TToDatasetId extends string, any, any> ? TFromDatasetId extends TSourceDatasetId ? {
+  readonly dataset: TToDatasetId;
+  readonly through: Extract<TAssociationId, string>;
+  readonly mode: 'exists';
+} : TToDatasetId extends TSourceDatasetId ? {
+  readonly dataset: TFromDatasetId;
+  readonly through: Extract<TAssociationId, string>;
+  readonly mode: 'exists';
+} : never : never }[keyof TAssociations];
+type ModelAttributeTarget<TRelationships extends Record<string, ModelRelationshipDefinition>, TAssociations extends Record<string, ModelAssociationDefinition>, TSourceDatasetId extends string> = RelationshipTarget<TRelationships, TSourceDatasetId> | AssociationTarget<TAssociations, TSourceDatasetId>;
+type SelectAttributeConfig<TDatasets extends ModelDatasets, TRelationships extends Record<string, ModelRelationshipDefinition>, TAssociations extends Record<string, ModelAssociationDefinition>, TSourceDatasetId extends ModelSingleKeyDatasetId<TDatasets>, TTargets extends readonly ModelAttributeTarget<TRelationships, TAssociations, TSourceDatasetId>[]> = {
+  readonly kind: 'select';
+  readonly source: {
+    readonly dataset: TSourceDatasetId;
+    readonly key: SingleDatasetKeyId<TDatasets[TSourceDatasetId]>;
+    readonly label: ResolvedGroupByColumnIdFromSchema<DatasetRow<TDatasets[TSourceDatasetId]>, TDatasets[TSourceDatasetId]>;
+  };
+  readonly targets: TTargets;
+};
+type ModelAttributeDefinition<TSourceDatasetId extends string = string, TTargets extends readonly unknown[] = readonly unknown[]> = {
+  readonly kind: 'select';
+  readonly id: string;
+  readonly source: {
+    readonly dataset: TSourceDatasetId;
+    readonly key: string;
+    readonly label: string;
+  };
+  readonly targets: TTargets;
+};
+type ModelDataInput<TDatasets extends ModelDatasets> = { readonly [TId in keyof TDatasets]: readonly DatasetRow<TDatasets[TId]>[] };
+type ModelInferExcludeId<TDatasets extends ModelDatasets> = { [TDatasetId in ModelDatasetId<TDatasets>]: `${TDatasetId}.${InferableFieldKey<DatasetRow<TDatasets[TDatasetId]>>}` }[ModelDatasetId<TDatasets>];
+type ModelInferOptions<TDatasets extends ModelDatasets, TExclude extends readonly ModelInferExcludeId<TDatasets>[] | undefined = readonly ModelInferExcludeId<TDatasets>[] | undefined> = {
+  readonly relationships?: boolean;
+  readonly attributes?: boolean;
+  readonly exclude?: TExclude;
+};
+type DefinedDataModel<TDatasets extends ModelDatasets = ModelDatasets, TRelationships extends Record<string, ModelRelationshipDefinition> = Record<string, ModelRelationshipDefinition>, TAssociations extends Record<string, ModelAssociationDefinition> = Record<string, ModelAssociationDefinition>, TAttributes extends Record<string, ModelAttributeDefinition> = Record<string, ModelAttributeDefinition>> = {
+  readonly datasets: TDatasets;
+  readonly relationships: TRelationships;
+  readonly associations: TAssociations;
+  readonly attributes: TAttributes;
+  /**
+   * Define one explicit materialized view from the linked model.
+   *
+   * Use this when a chart needs a flat cross-dataset row shape such as
+   * `'job'`, `'job-skill'`, or `'requisition-owner'`.
+   */
+  materialize<const TId extends string, const TMaterializedView extends MaterializedViewDefinition<any, any, any, any>>(id: TId, defineView: (materialize: ModelMaterializationStartBuilder<TDatasets, TRelationships, TAssociations, TAttributes, TId>) => TMaterializedView): TMaterializedView;
+  chart<const TChartId extends string, const TBuilder extends ModelChartBuilder<TDatasets, TRelationships, any, any, any, any, any, any, any, any>>(id: TChartId, defineChart: (chart: ModelChartStartBuilder<TDatasets, TRelationships>) => TBuilder): CompileModelChartDefinition<TDatasets, TRelationships, TBuilder, TChartId>;
+  chart<const TChartId extends string, const TBuilder extends InferredModelChartBuilder<TDatasets, TRelationships, any, any, any, any, any, any, any, any>>(id: TChartId, defineChart: (chart: ModelChartStartBuilder<TDatasets, TRelationships>) => TBuilder): CompileModelChartDefinition<TDatasets, TRelationships, TBuilder, TChartId>;
+  validateData(data: ModelDataInput<TDatasets>): void;
+  build(): DefinedDataModel<TDatasets, TRelationships, TAssociations, TAttributes>;
+  readonly __dataModelBrand: 'data-model-definition';
+};
+type DataModelDefinition<TDatasets extends ModelDatasets = {}, TRelationships extends Record<string, ModelRelationshipDefinition> = {}, TAssociations extends Record<string, ModelAssociationDefinition> = {}, TAttributes extends Record<string, ModelAttributeDefinition> = {}> = {
+  build(): DefinedDataModel<TDatasets, TRelationships, TAssociations, TAttributes>;
+};
+type ResolvedDataModelFromDefinition<TModel> = TModel extends DataModelDefinition<any, any, any, any> ? ReturnType<TModel['build']> : never;
+type AnyDefinedDataModel = {
+  readonly datasets: ModelDatasets;
+  readonly relationships: Record<string, ModelRelationshipDefinition>;
+  readonly associations: Record<string, ModelAssociationDefinition>;
+  readonly attributes: Record<string, ModelAttributeDefinition>;
+  materialize: (id: string, defineView: (materialize: ModelMaterializationStartBuilder<any, any, any, any, string>) => MaterializedViewDefinition<any, any, any, any>) => MaterializedViewDefinition<any, any, any, any>;
+  chart: (id: string, defineChart: (chart: ModelChartStartBuilder<any, any>) => ModelChartBuilder<any, any, any, any, any, any, any, any, any, any>) => DatasetChartDefinition<any, any, any, any, any, any, any, any, any, any, any>;
+  validateData(data: ModelDataInput<ModelDatasets>): void;
+  build(): AnyDefinedDataModel;
+  readonly __dataModelBrand: 'data-model-definition';
+};
+interface DataModelBuilder<TDatasets extends ModelDatasets = {}, TRelationships extends Record<string, ModelRelationshipDefinition> = {}, TAssociations extends Record<string, ModelAssociationDefinition> = {}, TAttributes extends Record<string, ModelAttributeDefinition> = {}> extends DataModelDefinition<TDatasets, TRelationships, TAssociations, TAttributes> {
+  dataset<const TId extends string, const TDataset extends KeyedDatasetDefinition>(id: UniqueId<TId, ModelDatasetId<TDatasets>>, dataset: TDataset): DataModelBuilder<TDatasets & Record<TId, ResolvedDatasetFromDefinition<TDataset>>, TRelationships, TAssociations, TAttributes>;
+  relationship<const TId extends string, const TFromDatasetId extends ModelSingleKeyDatasetId<TDatasets>, const TToDatasetId extends ModelDatasetId<TDatasets>>(id: UniqueId<TId, Extract<keyof TRelationships, string>>, config: RelationshipConfig<TDatasets, TFromDatasetId, TToDatasetId>): DataModelBuilder<TDatasets, TRelationships & Record<TId, ModelRelationshipDefinition<TFromDatasetId, TToDatasetId, SingleDatasetKeyId<TDatasets[TFromDatasetId]>, DatasetForeignKeyColumnId<TDatasets[TToDatasetId]>>>, TAssociations, TAttributes>;
+  association<const TId extends string, const TFromDatasetId extends ModelSingleKeyDatasetId<TDatasets>, const TToDatasetId extends ModelSingleKeyDatasetId<TDatasets>, const TEdgeRow extends Record<string, unknown> = Record<string, unknown>>(id: UniqueId<TId, Extract<keyof TAssociations, string>>, config: ExplicitAssociationConfig<TDatasets, TFromDatasetId, TToDatasetId, TEdgeRow>): DataModelBuilder<TDatasets, TRelationships, TAssociations & Record<TId, ModelAssociationDefinition<TFromDatasetId, TToDatasetId, SingleDatasetKeyId<TDatasets[TFromDatasetId]>, SingleDatasetKeyId<TDatasets[TToDatasetId]>>>, TAttributes>;
+  association<const TId extends string, const TFromDatasetId extends ModelSingleKeyDatasetId<TDatasets>, const TToDatasetId extends ModelSingleKeyDatasetId<TDatasets>, const TDeriveDatasetId extends TFromDatasetId | TToDatasetId>(id: UniqueId<TId, Extract<keyof TAssociations, string>>, config: DerivedAssociationConfig<TDatasets, TFromDatasetId, TToDatasetId, TDeriveDatasetId>): DataModelBuilder<TDatasets, TRelationships, TAssociations & Record<TId, ModelAssociationDefinition<TFromDatasetId, TToDatasetId, SingleDatasetKeyId<TDatasets[TFromDatasetId]>, SingleDatasetKeyId<TDatasets[TToDatasetId]>>>, TAttributes>;
+  attribute<const TId extends string, const TSourceDatasetId extends ModelSingleKeyDatasetId<TDatasets>, const TTargets extends readonly ModelAttributeTarget<TRelationships, TAssociations, TSourceDatasetId>[]>(id: UniqueId<TId, Extract<keyof TAttributes, string>>, config: SelectAttributeConfig<TDatasets, TRelationships, TAssociations, TSourceDatasetId, TTargets>): DataModelBuilder<TDatasets, TRelationships, TAssociations, TAttributes & Record<TId, ModelAttributeDefinition<TSourceDatasetId, TTargets>>>;
+  infer<const TOptions extends ModelInferOptions<TDatasets>>(options: TOptions): DataModelBuilder<TDatasets, TOptions['relationships'] extends true ? InferRelationshipsForModel<TDatasets, TRelationships, Extract<TOptions['exclude'], readonly string[] | undefined>> : TRelationships, TAssociations, TOptions['attributes'] extends true ? InferAttributesForModel<TDatasets, TOptions['relationships'] extends true ? InferRelationshipsForModel<TDatasets, TRelationships, Extract<TOptions['exclude'], readonly string[] | undefined>> : TRelationships, TAttributes> : TAttributes>;
+  chart<const TChartId extends string, const TBuilder extends ModelChartBuilder<TDatasets, TRelationships, any, any, any, any, any, any, any, any>>(id: TChartId, defineChart: (chart: ModelChartStartBuilder<TDatasets, TRelationships>) => TBuilder): CompileModelChartDefinition<TDatasets, TRelationships, TBuilder, TChartId>;
+  chart<const TChartId extends string, const TBuilder extends InferredModelChartBuilder<TDatasets, TRelationships, any, any, any, any, any, any, any, any>>(id: TChartId, defineChart: (chart: ModelChartStartBuilder<TDatasets, TRelationships>) => TBuilder): CompileModelChartDefinition<TDatasets, TRelationships, TBuilder, TChartId>;
+  /**
+   * Define one reusable materialized view without collapsing model, chart, and
+   * dashboard concerns into one abstraction.
+   */
+  materialize<const TId extends string, const TMaterializedView extends MaterializedViewDefinition<any, any, any, any>>(id: TId, defineView: (materialize: ModelMaterializationStartBuilder<TDatasets, TRelationships, TAssociations, TAttributes, TId>) => TMaterializedView): TMaterializedView;
+  validateData(data: ModelDataInput<TDatasets>): void;
+  build(): DefinedDataModel<TDatasets, TRelationships, TAssociations, TAttributes>;
+}
+//#endregion
+export { AnyDefinedDataModel, DataModelBuilder, DataModelDefinition, DefinedDataModel, KeyedDatasetDefinition, ModelAssociationDefinition, ModelAttributeDefinition, ModelDataInput, ModelDatasetId, ModelDatasets, ModelRelationshipDefinition, ResolvedDataModelFromDefinition, SelectAttributeConfig };

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

@@ -0,0 +1,51 @@
+import { ChartType, ChartTypeConfig, DefinedChartSchema, FiltersConfig, GroupByConfig, InferableFieldKey, MetricConfig, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, TimeBucket, TimeBucketConfig, XAxisConfig } from "./types.mjs";
+import { ColumnHelper, ColumnsFromEntries, MetricBuilder, MetricBuilderConfig, SchemaColumnEntry, SchemaFromBuilder, SelectableControlBuilder, SelectableControlBuilderConfig, ValidateColumnEntries } from "./schema-builder.types.mjs";
+import { DATASET_CHART_METADATA, DatasetChartMetadata } from "./dataset-chart-metadata.mjs";
+
+//#region src/core/dataset-builder.types.d.ts
+type NonEmptyReadonlyArray<TValue> = readonly [TValue, ...TValue[]];
+type DatasetColumnsContext<TColumns extends Record<string, unknown> | undefined> = [TColumns] extends [undefined] ? undefined : {
+  columns?: TColumns;
+};
+type DefinedDatasetChartSchema<TRow, 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, TChartId extends string | undefined = undefined, TOwner = unknown> = DefinedChartSchema<TRow, SchemaFromBuilder<TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls>> & {
+  readonly [DATASET_CHART_METADATA]: DatasetChartMetadata<TChartId, TOwner>;
+};
+type DatasetKey<TRow> = NonEmptyReadonlyArray<InferableFieldKey<TRow>>;
+type DefinedDataset<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TKey extends DatasetKey<TRow> | undefined = undefined> = {
+  readonly key?: TKey;
+  readonly columns?: TColumns;
+  chart<const TChartId extends string | undefined = undefined>(id?: TChartId): DatasetChartBuilder<TRow, TColumns, undefined, undefined, undefined, undefined, undefined, undefined, undefined, TChartId, DefinedDataset<TRow, TColumns, TKey>>;
+  validateData(data: readonly TRow[]): void;
+  build(): DefinedDataset<TRow, TColumns, TKey>;
+  readonly __datasetBrand: 'dataset-definition';
+};
+type DatasetDefinition<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TKey extends DatasetKey<TRow> | undefined = undefined> = {
+  build(): DefinedDataset<TRow, TColumns, TKey>;
+};
+type ResolvedDatasetFromDefinition<TDataset> = TDataset extends DatasetDefinition<any, any, any> ? ReturnType<TDataset['build']> : never;
+type DatasetRow<TDataset> = TDataset extends DefinedDataset<infer TRow, any, any> ? TRow : never;
+type DatasetColumns<TDataset> = TDataset extends DefinedDataset<any, infer TColumns, any> ? TColumns : never;
+type DatasetKeyIds<TDataset> = TDataset extends DefinedDataset<any, any, infer TKey> ? TKey : never;
+type SingleDatasetKeyId<TDataset> = DatasetKeyIds<TDataset> extends readonly [infer TKeyId extends string] ? TKeyId : never;
+type DatasetChartBuilder<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, TChartId extends string | undefined = undefined, TOwner = unknown> = {
+  xAxis<const TBuilder extends SelectableControlBuilder<ResolvedXAxisColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, true>>(defineXAxis: (xAxis: SelectableControlBuilder<ResolvedXAxisColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, true>) => TBuilder): DatasetChartBuilder<TRow, TColumns, SelectableControlBuilderConfig<TBuilder>, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  groupBy<const TBuilder extends SelectableControlBuilder<ResolvedGroupByColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, true>>(defineGroupBy: (groupBy: SelectableControlBuilder<ResolvedGroupByColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, true>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, SelectableControlBuilderConfig<TBuilder>, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  filters<const TBuilder extends SelectableControlBuilder<ResolvedFilterColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, false>>(defineFilters: (filters: SelectableControlBuilder<ResolvedFilterColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, false>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, SelectableControlBuilderConfig<TBuilder>, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  metric<const TBuilder extends MetricBuilder<ResolvedMetricColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>, any, any, any>>(defineMetric: (metric: MetricBuilder<ResolvedMetricColumnIdFromSchema<TRow, DatasetColumnsContext<TColumns>>>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, MetricBuilderConfig<TBuilder>, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  chartType<const TBuilder extends SelectableControlBuilder<ChartType, true>>(defineChartType: (chartType: SelectableControlBuilder<ChartType, true>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, SelectableControlBuilderConfig<TBuilder>, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  timeBucket<const TBuilder extends SelectableControlBuilder<TimeBucket, true>>(defineTimeBucket: (timeBucket: SelectableControlBuilder<TimeBucket, true>) => TBuilder): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, SelectableControlBuilderConfig<TBuilder>, TConnectNulls, TChartId, TOwner>;
+  connectNulls<const TValue extends boolean>(value: TValue): DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TValue, TChartId, TOwner>;
+  build(): DefinedDatasetChartSchema<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+  readonly [DATASET_CHART_METADATA]: DatasetChartMetadata<TChartId, TOwner>;
+};
+type DatasetChartDefinition<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, TChartId extends string | undefined = undefined, TOwner = unknown> = DatasetChartBuilder<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner> | DefinedDatasetChartSchema<TRow, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket, TConnectNulls, TChartId, TOwner>;
+interface DatasetBuilder<TRow, TColumns extends Record<string, unknown> | undefined = undefined, TKey extends DatasetKey<TRow> | undefined = undefined> extends DatasetDefinition<TRow, TColumns, TKey> {
+  key<const TFieldId extends InferableFieldKey<TRow>>(id: TFieldId): DatasetBuilder<TRow, TColumns, readonly [TFieldId]>;
+  key<const TKeyIds extends DatasetKey<TRow>>(ids: TKeyIds): DatasetBuilder<TRow, TColumns, TKeyIds>;
+  columns: TColumns extends undefined ? <const TEntries extends readonly SchemaColumnEntry<TRow>[]>(defineColumns: (columns: ColumnHelper<TRow>) => TEntries & ValidateColumnEntries<TEntries>) => DatasetBuilder<TRow, ColumnsFromEntries<TRow, TEntries>, TKey> : never;
+  chart<const TChartId extends string | undefined = undefined>(id?: TChartId): DatasetChartBuilder<TRow, TColumns, undefined, undefined, undefined, undefined, undefined, undefined, undefined, TChartId, DefinedDataset<TRow, TColumns, TKey>>;
+  validateData(data: readonly TRow[]): void;
+  build(): DefinedDataset<TRow, TColumns, TKey>;
+}
+//#endregion
+export { DatasetBuilder, DatasetChartBuilder, DatasetChartDefinition, DatasetColumns, DatasetDefinition, DatasetKey, DatasetKeyIds, DatasetRow, DefinedDataset, DefinedDatasetChartSchema, ResolvedDatasetFromDefinition, SingleDatasetKeyId };

package/dist/core/dataset-chart-metadata.d.mts

@@ -0,0 +1,8 @@
+//#region src/core/dataset-chart-metadata.d.ts
+declare const DATASET_CHART_METADATA: unique symbol;
+type DatasetChartMetadata<TChartId extends string | undefined = string | undefined, TOwner = unknown> = {
+  readonly dataset: TOwner;
+  readonly chartId: TChartId;
+};
+//#endregion
+export { DATASET_CHART_METADATA, DatasetChartMetadata };

package/dist/core/dataset-chart-metadata.mjs

@@ -0,0 +1,4 @@
+//#region src/core/dataset-chart-metadata.ts
+const DATASET_CHART_METADATA = Symbol("dataset-chart-metadata");
+//#endregion
+export { DATASET_CHART_METADATA };

package/dist/core/date-range-presets.mjs

@@ -111,7 +111,7 @@ function autoFilterForBucket(bucket) {
 * @returns The resolved filter, or `null` for "all time".
 */
 function resolvePresetFilter(presetId, timeBucket) {
-	if (presetId === "auto") return autoFilterForBucket(timeBucket);
+	if (presetId === "auto") return autoFilterForBucket(timeBucket) ?? null;
 	return DATE_RANGE_PRESETS.find((p) => p.id === presetId)?.buildFilter() ?? null;
 }
 /**

package/dist/core/define-dashboard.d.mts

@@ -0,0 +1,8 @@
+import { DataModelDefinition } from "./data-model.types.mjs";
+import { DashboardBuilder, DashboardDefinition, DashboardInputModel, ResolvedDashboardFromDefinition } from "./dashboard.types.mjs";
+
+//#region src/core/define-dashboard.d.ts
+declare function resolveDashboardDefinition<TDashboard extends DashboardDefinition<any, any, any>>(dashboard: TDashboard): ResolvedDashboardFromDefinition<TDashboard>;
+declare function defineDashboard<TModel extends DataModelDefinition<any, any, any, any>>(model: TModel): DashboardBuilder<DashboardInputModel<TModel>>;
+//#endregion
+export { defineDashboard, resolveDashboardDefinition };