@matthieumordrel/chart-studio 0.2.3 → 0.2.5

package/README.md

@@ -22,6 +22,10 @@ You get:
 - transformed chart data
 - filtering, grouping, metrics, and time bucketing logic
 
+Requirements:
+
+- `react` >= 18.2.0
+
 Install:
 
 ```bash
@@ -46,6 +50,12 @@ You get:
 - `<ChartCanvas>`
 - granular UI controls from `@matthieumordrel/chart-studio/ui`
 
+Requirements:
+
+- `react` >= 18.2.0
+- `recharts` >= 3.0.0 (v2 is **not** supported)
+- `lucide-react` >= 0.577.0 (optional, for toolbar icons)
+
 Install:
 
 ```bash
@@ -88,7 +98,7 @@ export function JobsChart() {
 ## How It Works
 
 1. Pass your raw data to `useChart()`.
-2. Add an optional `schema` with `defineChartSchema<Row>()(...)` when you need labels, type overrides, derived columns, or control restrictions (allowed metrics, groupings, chart types, etc.).
+2. Add an optional `schema` with `defineChartSchema<Row>()...` when you need labels, type overrides, derived columns, or control restrictions (allowed metrics, groupings, chart types, etc.).
 3. Either render your own UI from the returned state, or use the components from `@matthieumordrel/chart-studio/ui`.
 
 ## Column Types
@@ -102,41 +112,39 @@ export function JobsChart() {
 
 ## Declarative Schema and Control Restrictions
 
-If you want to expose only a subset of groupings, metrics, chart types, or axes, use `defineChartSchema<Row>()()` with the control sections:
+If you want to expose only a subset of groupings, metrics, chart types, or axes, use the fluent `defineChartSchema<Row>()` builder:
 
 ```tsx
 import { defineChartSchema, useChart } from '@matthieumordrel/chart-studio'
 
 type Row = { periodEnd: string; segment: string; revenue: number; netIncome: number }
 
-const schema = defineChartSchema<Row>()({
-  columns: {
-    periodEnd: { type: 'date', label: 'Period End' },
-    segment: { type: 'category' },
-    revenue: { type: 'number' },
-    netIncome: { type: 'number' }
-  },
-  xAxis: { allowed: ['periodEnd'] },
-  groupBy: { allowed: ['segment'] },
-  metric: {
-    allowed: [
-      { kind: 'count' },
-      { kind: 'aggregate', columnId: 'revenue', aggregate: ['sum', 'avg'] },
-      { kind: 'aggregate', columnId: 'netIncome', aggregate: 'sum' }
-    ]
-  },
-  chartType: { allowed: ['bar', 'line'] },
-  timeBucket: { allowed: ['year', 'quarter', 'month'] }
-})
+const schema = defineChartSchema<Row>()
+  .columns((c) => [
+    c.date('periodEnd', { label: 'Period End' }),
+    c.category('segment'),
+    c.number('revenue'),
+    c.number('netIncome')
+  ])
+  .xAxis((x) => x.allowed('periodEnd'))
+  .groupBy((g) => g.allowed('segment'))
+  .metric((m) =>
+    m
+      .count()
+      .aggregate('revenue', 'sum', 'avg')
+      .aggregate('netIncome', 'sum')
+  )
+  .chartType((t) => t.allowed('bar', 'line'))
+  .timeBucket((tb) => tb.allowed('year', 'quarter', 'month'))
 
 const chart = useChart({ data, schema })
 ```
 
 Why this pattern:
 
-- `columns` defines types, labels, and formats for raw fields; use `false` to exclude a column from the chart
-- Derived columns use `{ kind: 'derived', type, label?, accessor, format? }` for computed values from each row
-- `xAxis`, `groupBy`, `metric`, `chartType`, `timeBucket` restrict the allowed options
+- `columns` defines types, labels, and formats for raw fields; use `c.exclude(...)` to remove a column from the chart
+- Derived columns use `c.derived.*(...)` helpers for computed values from each row
+- `xAxis`, `groupBy`, `metric`, `chartType`, and `timeBucket` restrict the allowed options
 - invalid column IDs and config keys are rejected at compile time
 - metric restrictions preserve the order you declare, so the first allowed metric becomes the default
 
@@ -153,13 +161,12 @@ type Job = {
   salary: number
 }
 
-const jobSchema = defineChartSchema<Job>()({
-  columns: {
-    dateAdded: { type: 'date', label: 'Date Added' },
-    ownerName: { type: 'category', label: 'Consultant' },
-    salary: { type: 'number', label: 'Salary' }
-  }
-})
+const jobSchema = defineChartSchema<Job>()
+  .columns((c) => [
+    c.date('dateAdded', { label: 'Date Added' }),
+    c.category('ownerName', { label: 'Consultant' }),
+    c.number('salary', { label: 'Salary' })
+  ])
 
 export function JobsChartHeadless({ data }: { data: Job[] }) {
   const chart = useChart({ data, schema: jobSchema })
@@ -298,12 +305,6 @@ Minimal example:
 }
 ```
 
-## Compatibility
-
-- `react`: `>=18.2.0 <20`
-- `recharts`: `>=3.0.0 <4` for the UI layer
-- `lucide-react`: `>=0.577.0 <1` for the UI layer
-
 ## Common Questions
 
 ### Which import path should I use?
@@ -332,9 +333,8 @@ const chart = useChart({
       id: 'jobs',
       label: 'Jobs',
       data: jobs,
-      schema: defineChartSchema<Job>()({
-        columns: { dateAdded: { type: 'date', label: 'Date Added' } }
-      })
+      schema: defineChartSchema<Job>()
+        .columns((c) => [c.date('dateAdded', { label: 'Date Added' })])
     },
     { id: 'candidates', label: 'Candidates', data: candidates }
   ]
@@ -384,9 +384,9 @@ There is currently no built-in support for drill-down, click-to-filter, brush se
 
 Each chart instance operates on a single flat dataset. Overlaying series from different schemas (e.g. revenue on the left Y-axis and headcount on the right) would require separate chart instances today. Dual-axis and cross-dataset composition are not yet supported.
 
-### The double-call schema syntax
+### Schema Builder Ergonomics
 
-`defineChartSchema<Row>()()` uses a double function call as a workaround for TypeScript's lack of partial type argument inference. This lets you provide the row type explicitly while the column IDs are inferred automatically. It works well but can surprise newcomers — this will be revisited if TypeScript adds native support for partial inference.
+`defineChartSchema<Row>()` now returns one fluent builder that you pass directly to `useChart(...)` or `inferColumnsFromData(...)`. That keeps the public API strongly typed while improving IntelliSense for raw field ids, derived columns, and control restrictions.
 
 ## Release
 

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

@@ -23,6 +23,16 @@ declare const CHART_TYPE_CONFIG: {
     readonly supportsGrouping: true;
     readonly supportsTimeBucketing: true;
   };
+  readonly 'grouped-bar': {
+    readonly supportedXAxisTypes: readonly ["date", "category", "boolean"];
+    readonly supportsGrouping: true;
+    readonly supportsTimeBucketing: true;
+  };
+  readonly 'percent-bar': {
+    readonly supportedXAxisTypes: readonly ["date", "category", "boolean"];
+    readonly supportsGrouping: true;
+    readonly supportsTimeBucketing: true;
+  };
   readonly line: {
     readonly supportedXAxisTypes: readonly ["date"];
     readonly supportsGrouping: true;
@@ -33,6 +43,11 @@ declare const CHART_TYPE_CONFIG: {
     readonly supportsGrouping: true;
     readonly supportsTimeBucketing: true;
   };
+  readonly 'percent-area': {
+    readonly supportedXAxisTypes: readonly ["date"];
+    readonly supportsGrouping: true;
+    readonly supportsTimeBucketing: true;
+  };
   readonly pie: {
     readonly supportedXAxisTypes: readonly ["category", "boolean"];
     readonly supportsGrouping: false;

package/dist/core/chart-capabilities.mjs

@@ -13,6 +13,24 @@ const CHART_TYPE_CONFIG = {
 		supportsGrouping: true,
 		supportsTimeBucketing: true
 	},
+	"grouped-bar": {
+		supportedXAxisTypes: [
+			"date",
+			"category",
+			"boolean"
+		],
+		supportsGrouping: true,
+		supportsTimeBucketing: true
+	},
+	"percent-bar": {
+		supportedXAxisTypes: [
+			"date",
+			"category",
+			"boolean"
+		],
+		supportsGrouping: true,
+		supportsTimeBucketing: true
+	},
 	line: {
 		supportedXAxisTypes: ["date"],
 		supportsGrouping: true,
@@ -23,6 +41,11 @@ const CHART_TYPE_CONFIG = {
 		supportsGrouping: true,
 		supportsTimeBucketing: true
 	},
+	"percent-area": {
+		supportedXAxisTypes: ["date"],
+		supportsGrouping: true,
+		supportsTimeBucketing: true
+	},
 	pie: {
 		supportedXAxisTypes: ["category", "boolean"],
 		supportsGrouping: false,

package/dist/core/colors.mjs

@@ -20,11 +20,11 @@ const FALLBACK_COLORS = [
 ];
 /** Shadcn chart CSS variables (5 colors) with safe fallbacks. */
 const SHADCN_CHART_COLORS = [
-	`var(--chart-1, var(--cs-chart-1, hsl(245 72% 57%)))`,
-	`var(--chart-2, var(--cs-chart-2, hsl(271 72% 55%)))`,
-	`var(--chart-3, var(--cs-chart-3, hsl(330 68% 54%)))`,
-	`var(--chart-4, var(--cs-chart-4, hsl(170 65% 38%)))`,
-	`var(--chart-5, var(--cs-chart-5, hsl(30 90% 54%)))`
+	`var(--chart-1, var(--cs-chart-1, oklch(0.501 0.228 277.992)))`,
+	`var(--chart-2, var(--cs-chart-2, oklch(0.550 0.235 302.715)))`,
+	`var(--chart-3, var(--cs-chart-3, oklch(0.609 0.206 354.673)))`,
+	`var(--chart-4, var(--cs-chart-4, oklch(0.635 0.109 178.228)))`,
+	`var(--chart-5, var(--cs-chart-5, oklch(0.732 0.166 58.213)))`
 ];
 /**
 * Get a color for the Nth series.

package/dist/core/config-utils.mjs

@@ -50,9 +50,10 @@ function restrictConfiguredValues(values, config, fallbackToBaseIfEmpty = false)
 /**
 * Resolve one primitive selection against the current option list.
 */
-function resolveConfiguredValue(currentValue, values, configuredDefault) {
-	if (values.includes(currentValue)) return currentValue;
+function resolveConfiguredValue(currentValue, values, configuredDefault, globalDefault) {
+	if (currentValue !== null && values.includes(currentValue)) return currentValue;
 	if (configuredDefault && values.includes(configuredDefault)) return configuredDefault;
+	if (globalDefault && values.includes(globalDefault)) return globalDefault;
 	return values[0] ?? currentValue;
 }
 /**
@@ -70,8 +71,11 @@ const TIME_BUCKET_ORDER = [
 */
 const CHART_TYPE_ORDER = [
 	"bar",
+	"grouped-bar",
+	"percent-bar",
 	"line",
 	"area",
+	"percent-area",
 	"pie",
 	"donut"
 ];

package/dist/core/date-range-presets.d.mts

@@ -0,0 +1,12 @@
+//#region src/core/date-range-presets.d.ts
+/**
+ * All recognised date range preset identifiers.
+ *
+ * - `'auto'`          — derived from the active time bucket
+ * - `'all-time'`      — no date filtering
+ * - Relative presets   — rolling window from "now"
+ * - Calendar presets   — aligned to calendar boundaries
+ */
+type DateRangePresetId = 'auto' | 'all-time' | 'last-7-days' | 'last-30-days' | 'last-3-months' | 'last-12-months' | 'quarter-to-date' | 'year-to-date' | 'last-year';
+//#endregion
+export { DateRangePresetId };

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

@@ -0,0 +1,152 @@
+//#region src/core/date-range-presets.ts
+/**
+* Ordered list of all date range presets shown in the UI.
+*
+* Layout hint (2-column grid):
+*   Auto          | All time
+*   Last 7 days   | Last 30 days
+*   Last 3 months | Last 12 months
+*   Quarter to date | Year to date
+*   Last year     |
+*/
+const DATE_RANGE_PRESETS = [
+	{
+		id: "auto",
+		label: "Auto",
+		description: "Adjusts the date range based on the time bucket: day → last 30 days, week → last 3 months, month → last 12 months, quarter/year → all time",
+		buildFilter: () => null
+	},
+	{
+		id: "all-time",
+		label: "All time",
+		buildFilter: () => null
+	},
+	{
+		id: "last-7-days",
+		label: "Last 7 days",
+		buildFilter: () => ({
+			from: daysAgo(7),
+			to: null
+		})
+	},
+	{
+		id: "last-30-days",
+		label: "Last 30 days",
+		buildFilter: () => ({
+			from: daysAgo(30),
+			to: null
+		})
+	},
+	{
+		id: "last-3-months",
+		label: "Last 3 months",
+		buildFilter: () => ({
+			from: monthsAgo(3),
+			to: null
+		})
+	},
+	{
+		id: "last-12-months",
+		label: "Last 12 months",
+		buildFilter: () => ({
+			from: monthsAgo(12),
+			to: null
+		})
+	},
+	{
+		id: "quarter-to-date",
+		label: "Quarter to date",
+		buildFilter: () => ({
+			from: startOfQuarter(),
+			to: null
+		})
+	},
+	{
+		id: "year-to-date",
+		label: "Year to date",
+		buildFilter: () => ({
+			from: startOfYear(),
+			to: null
+		})
+	},
+	{
+		id: "last-year",
+		label: "Last year",
+		buildFilter: () => lastYear()
+	}
+];
+/**
+* Map a time bucket to a sensible default date range.
+*
+* - `day`     → last 30 days (enough for a meaningful daily trend)
+* - `week`    → last 3 months (~13 weeks)
+* - `month`   → last 12 months
+* - `quarter` → all time (null)
+* - `year`    → all time (null)
+*/
+function autoFilterForBucket(bucket) {
+	switch (bucket) {
+		case "day": return {
+			from: daysAgo(30),
+			to: null
+		};
+		case "week": return {
+			from: monthsAgo(3),
+			to: null
+		};
+		case "month": return {
+			from: monthsAgo(12),
+			to: null
+		};
+		case "quarter":
+		case "year": return null;
+	}
+}
+/**
+* Compute the effective `DateRangeFilter` for a given preset.
+*
+* For `'auto'`, this uses the provided `timeBucket` to derive the range.
+* For all other presets, the filter is computed from the preset definition.
+*
+* @returns The resolved filter, or `null` for "all time".
+*/
+function resolvePresetFilter(presetId, timeBucket) {
+	if (presetId === "auto") return autoFilterForBucket(timeBucket);
+	return DATE_RANGE_PRESETS.find((p) => p.id === presetId)?.buildFilter() ?? null;
+}
+/**
+* Get the human-readable label for a preset ID.
+*/
+function getPresetLabel(presetId) {
+	return DATE_RANGE_PRESETS.find((p) => p.id === presetId)?.label ?? "Custom";
+}
+function daysAgo(n) {
+	const d = /* @__PURE__ */ new Date();
+	d.setDate(d.getDate() - n);
+	d.setHours(0, 0, 0, 0);
+	return d;
+}
+function monthsAgo(n) {
+	const d = /* @__PURE__ */ new Date();
+	d.setMonth(d.getMonth() - n);
+	d.setHours(0, 0, 0, 0);
+	return d;
+}
+function startOfQuarter() {
+	const d = /* @__PURE__ */ new Date();
+	const quarterMonth = Math.floor(d.getMonth() / 3) * 3;
+	return new Date(d.getFullYear(), quarterMonth, 1);
+}
+function startOfYear() {
+	const d = /* @__PURE__ */ new Date();
+	return new Date(d.getFullYear(), 0, 1);
+}
+function lastYear() {
+	const year = (/* @__PURE__ */ new Date()).getFullYear() - 1;
+	return {
+		from: new Date(year, 0, 1),
+		to: new Date(year, 11, 31)
+	};
+}
+//#endregion
+export { DATE_RANGE_PRESETS, getPresetLabel, resolvePresetFilter };

package/dist/core/define-chart-schema.d.mts

@@ -1,106 +1,38 @@
-import { ChartTypeConfig, DefinedChartSchema, ExactShape, FiltersConfig, GroupByConfig, MetricConfig, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, SchemaColumnsValidationShape, TimeBucketConfig, XAxisConfig } from "./types.mjs";
+import { ChartSchemaBuilder } from "./schema-builder.types.mjs";
 
 //#region src/core/define-chart-schema.d.ts
-type SchemaFromSections<T, TColumns extends Record<string, unknown> | undefined, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket> = {
-  columns?: Extract<TColumns, Record<string, unknown> | undefined>;
-  xAxis?: Extract<TXAxis, XAxisConfig<ResolvedXAxisColumnIdFromSchema<T, {
-    columns?: TColumns;
-  }>> | undefined>;
-  groupBy?: Extract<TGroupBy, GroupByConfig<ResolvedGroupByColumnIdFromSchema<T, {
-    columns?: TColumns;
-  }>> | undefined>;
-  filters?: Extract<TFilters, FiltersConfig<ResolvedFilterColumnIdFromSchema<T, {
-    columns?: TColumns;
-  }>> | undefined>;
-  metric?: Extract<TMetric, MetricConfig<ResolvedMetricColumnIdFromSchema<T, {
-    columns?: TColumns;
-  }>> | undefined>;
-  chartType?: Extract<TChartType, ChartTypeConfig | undefined>;
-  timeBucket?: Extract<TTimeBucket, TimeBucketConfig | undefined>;
-};
-type DefineChartSchemaInput<T, TColumns extends Record<string, unknown> | undefined, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket> = {
-  /**
-   * Shape the available chart columns.
-   *
-   * This is usually the most important part of the schema. Use it to:
-   * - rename inferred raw fields with `label`
-   * - force a field to a specific `type`
-   * - apply `format` or `formatter`
-   * - remove a raw field with `false`
-   * - add brand new derived columns with `kind: 'derived'`
-   */
-  columns?: TColumns & ExactShape<SchemaColumnsValidationShape<T, NoInfer<TColumns>>, NoInfer<TColumns>>;
-  /**
-   * Restrict which resolved columns may be selected on the X-axis.
-   *
-   * Use this when you want to expose only a subset of possible X-axis fields.
-   */
-  xAxis?: TXAxis & ExactShape<XAxisConfig<ResolvedXAxisColumnIdFromSchema<T, {
-    columns?: TColumns;
-  }>>, NoInfer<TXAxis>>;
-  /**
-   * Restrict which resolved columns may be used to split the chart into series.
-   *
-   * This powers grouped / multi-series charts.
-   */
-  groupBy?: TGroupBy & ExactShape<GroupByConfig<ResolvedGroupByColumnIdFromSchema<T, {
-    columns?: TColumns;
-  }>>, NoInfer<TGroupBy>>;
-  /**
-   * Restrict which resolved columns appear in the filters UI.
-   *
-   * Only category and boolean-like columns are eligible here.
-   */
-  filters?: TFilters & ExactShape<FiltersConfig<ResolvedFilterColumnIdFromSchema<T, {
-    columns?: TColumns;
-  }>>, NoInfer<TFilters>>;
-  /**
-   * Restrict which metrics and aggregate combinations remain selectable.
-   *
-   * Use this when you want to curate the metric dropdown rather than exposing
-   * every available numeric aggregate.
-   */
-  metric?: TMetric & ExactShape<MetricConfig<ResolvedMetricColumnIdFromSchema<T, {
-    columns?: TColumns;
-  }>>, NoInfer<TMetric>>; /** Restrict which chart renderers are available to the user. */
-  chartType?: TChartType & ExactShape<ChartTypeConfig, NoInfer<TChartType>>;
-  /**
-   * Restrict which time buckets remain available for date X-axes.
-   *
-   * Example: allow only `'month'` and `'quarter'`.
-   */
-  timeBucket?: TTimeBucket & ExactShape<TimeBucketConfig, NoInfer<TTimeBucket>>;
-};
 /**
- * Define one explicit chart schema with strict exact-object checking.
+ * Define one explicit chart schema through a fluent builder API.
  *
- * The schema is the single advanced authoring surface for chart-studio:
- * `columns` can override or exclude inferred raw fields and also define derived
- * columns, while the top-level control sections restrict the public chart
- * contract.
+ * Put `.columns(...)` early in the chain so later sections can narrow against
+ * the declared column ids and roles.
  *
  * Typical shape:
  *
  * ```ts
- * const schema = defineChartSchema<Row>()({
- *   columns: {
- *     createdAt: {type: 'date', label: 'Created'},
- *     revenue: {type: 'number', format: 'currency'},
- *     margin: {
- *       kind: 'derived',
- *       type: 'number',
- *       label: 'Margin',
- *       format: 'percent',
- *       accessor: row => row.profit / row.revenue,
- *     },
- *   },
- *   xAxis: {allowed: ['createdAt']},
- *   metric: {
- *     allowed: [{kind: 'aggregate', columnId: 'revenue', aggregate: 'sum'}],
- *   },
- * })
+ * const schema = defineChartSchema<Row>()
+ *   .columns((c) => [
+ *     c.date('createdAt', {label: 'Created'}),
+ *     c.category('ownerName', {label: 'Owner'}),
+ *     c.number('salary', {format: 'currency'}),
+ *     c.exclude('internalId'),
+ *     c.derived.category('salaryBand', {
+ *       label: 'Salary Band',
+ *       accessor: row => row.salary != null && row.salary > 100_000 ? 'High' : 'Base',
+ *     }),
+ *   ])
+ *   .xAxis((x) => x.allowed('createdAt').default('createdAt'))
+ *   .groupBy((g) => g.allowed('ownerName', 'salaryBand'))
+ *   .metric((m) =>
+ *     m
+ *       .count()
+ *       .aggregate('salary', 'sum', 'avg')
+ *       .defaultAggregate('salary', 'sum')
+ *   )
+ *
+ * // Pass the builder directly to useChart(...) or inferColumnsFromData(...).
  * ```
  */
-declare function defineChartSchema<T>(): <const TColumns extends Record<string, unknown> | undefined = undefined, const TXAxis = undefined, const TGroupBy = undefined, const TFilters = undefined, const TMetric = undefined, const TChartType = undefined, const TTimeBucket = undefined>(schema: DefineChartSchemaInput<T, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket>) => DefinedChartSchema<T, SchemaFromSections<T, TColumns, TXAxis, TGroupBy, TFilters, TMetric, TChartType, TTimeBucket>>;
+declare function defineChartSchema<TRow>(): ChartSchemaBuilder<TRow, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined>;
 //#endregion
 export { defineChartSchema };

package/dist/core/define-chart-schema.mjs

@@ -1,47 +1,39 @@
+import { createChartSchemaBuilder } from "./schema-builder.mjs";
 //#region src/core/define-chart-schema.ts
 /**
-* Define one explicit chart schema with strict exact-object checking.
+* Define one explicit chart schema through a fluent builder API.
 *
-* The schema is the single advanced authoring surface for chart-studio:
-* `columns` can override or exclude inferred raw fields and also define derived
-* columns, while the top-level control sections restrict the public chart
-* contract.
+* Put `.columns(...)` early in the chain so later sections can narrow against
+* the declared column ids and roles.
 *
 * Typical shape:
 *
 * ```ts
-* const schema = defineChartSchema<Row>()({
-*   columns: {
-*     createdAt: {type: 'date', label: 'Created'},
-*     revenue: {type: 'number', format: 'currency'},
-*     margin: {
-*       kind: 'derived',
-*       type: 'number',
-*       label: 'Margin',
-*       format: 'percent',
-*       accessor: row => row.profit / row.revenue,
-*     },
-*   },
-*   xAxis: {allowed: ['createdAt']},
-*   metric: {
-*     allowed: [{kind: 'aggregate', columnId: 'revenue', aggregate: 'sum'}],
-*   },
-* })
+* const schema = defineChartSchema<Row>()
+*   .columns((c) => [
+*     c.date('createdAt', {label: 'Created'}),
+*     c.category('ownerName', {label: 'Owner'}),
+*     c.number('salary', {format: 'currency'}),
+*     c.exclude('internalId'),
+*     c.derived.category('salaryBand', {
+*       label: 'Salary Band',
+*       accessor: row => row.salary != null && row.salary > 100_000 ? 'High' : 'Base',
+*     }),
+*   ])
+*   .xAxis((x) => x.allowed('createdAt').default('createdAt'))
+*   .groupBy((g) => g.allowed('ownerName', 'salaryBand'))
+*   .metric((m) =>
+*     m
+*       .count()
+*       .aggregate('salary', 'sum', 'avg')
+*       .defaultAggregate('salary', 'sum')
+*   )
+*
+* // Pass the builder directly to useChart(...) or inferColumnsFromData(...).
 * ```
 */
 function defineChartSchema() {
-	/**
-	* Brand one schema object while preserving its literal types.
-	*
-	* This is what lets the schema stay both strongly typed and editor-friendly
-	* when it is later passed to `useChart(...)`.
-	*/
-	return function defineSchema(schema) {
-		return {
-			...schema,
-			__chartSchemaBrand: "chart-schema-definition"
-		};
-	};
+	return createChartSchemaBuilder();
 }
 //#endregion
 export { defineChartSchema };

package/dist/core/infer-columns.d.mts

@@ -1,9 +1,9 @@
-import { ChartColumn, ChartSchema, ResolvedColumnIdFromSchema } from "./types.mjs";
+import { ChartColumn, ChartSchemaDefinition, ResolvedChartSchemaFromDefinition, ResolvedColumnIdFromSchema } from "./types.mjs";
 
 //#region src/core/infer-columns.d.ts
 /**
  * Resolve chart columns directly from raw data and an optional explicit schema.
  */
-declare function inferColumnsFromData<T, const TSchema extends ChartSchema<T, any> | undefined = undefined>(data: readonly T[], schema?: TSchema): readonly ChartColumn<T, ResolvedColumnIdFromSchema<T, TSchema>>[];
+declare function inferColumnsFromData<T, const TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined>(data: readonly T[], schema?: TSchema): readonly ChartColumn<T, ResolvedColumnIdFromSchema<T, ResolvedChartSchemaFromDefinition<TSchema>>>[];
 //#endregion
 export { inferColumnsFromData };