@matthieumordrel/chart-studio 0.2.4 → 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/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;
 }
 /**

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

package/dist/core/infer-columns.mjs

@@ -1,3 +1,4 @@
+import { resolveChartSchemaDefinition } from "./schema-builder.mjs";
 //#region src/core/infer-columns.ts
 const MAX_SAMPLE_COUNT = 50;
 const DATE_KEY_PATTERN = /(date|time|timestamp|created|updated|start|end|deadline|due|scheduled|posted|published|at)$/i;
@@ -463,7 +464,8 @@ function sortResolvedColumns(columns) {
 * Resolve chart columns directly from raw data and an optional explicit schema.
 */
 function inferColumnsFromData(data, schema) {
-	const rawColumnSchema = getRawColumnSchemaMap(schema);
+	const resolvedSchema = resolveChartSchemaDefinition(schema);
+	const rawColumnSchema = getRawColumnSchemaMap(resolvedSchema);
 	const fields = collectFieldKeys(data, rawColumnSchema);
 	const rawFieldIds = new Set(fields);
 	const resolvedColumns = [];
@@ -473,7 +475,7 @@ function inferColumnsFromData(data, schema) {
 		const column = buildRawColumn(typedField, samples, rawColumnSchema?.[typedField]);
 		if (column) resolvedColumns.push(column);
 	}
-	for (const [key, columnSchema] of getDerivedColumnSchemas(schema, rawFieldIds)) resolvedColumns.push(buildDerivedColumn(key, columnSchema));
+	for (const [key, columnSchema] of getDerivedColumnSchemas(resolvedSchema, rawFieldIds)) resolvedColumns.push(buildDerivedColumn(key, columnSchema));
 	if (resolvedColumns.length === 0) warn("No inferable or explicit chart columns were found. Provide non-empty data or schema.columns.");
 	return finalizeResolvedColumns(sortResolvedColumns(resolvedColumns));
 }

package/dist/core/metric-utils.mjs

@@ -109,13 +109,21 @@ function restrictAvailableMetrics(metrics, config) {
 */
 function resolveMetric(metric, columns, availableMetrics, configuredDefaultMetric) {
 	if (availableMetrics && availableMetrics.length > 0) {
-		const selectedMetric = availableMetrics.find((candidate) => isSameMetric(candidate, metric));
-		if (selectedMetric) return selectedMetric;
-		return (configuredDefaultMetric ? availableMetrics.find((candidate) => isSameMetric(candidate, configuredDefaultMetric)) : void 0) ?? availableMetrics[0];
+		if (metric !== null) {
+			const selectedMetric = availableMetrics.find((candidate) => isSameMetric(candidate, metric));
+			if (selectedMetric) return selectedMetric;
+		}
+		const defaultMetric = configuredDefaultMetric ? availableMetrics.find((candidate) => isSameMetric(candidate, configuredDefaultMetric)) : void 0;
+		if (defaultMetric) return defaultMetric;
+		if (metric === null) {
+			const countMetric = availableMetrics.find((candidate) => candidate.kind === "count");
+			if (countMetric) return countMetric;
+		}
+		return availableMetrics[0];
 	}
-	if (!isAggregateMetric(metric)) return DEFAULT_METRIC;
+	if (metric === null || !isAggregateMetric(metric)) return DEFAULT_METRIC;
 	if (!columns.find((candidate) => candidate.type === "number" && candidate.id === metric.columnId)) return DEFAULT_METRIC;
 	return metric;
 }
 //#endregion
-export { DEFAULT_METRIC, buildAvailableMetrics, getMetricLabel, isAggregateMetric, isSameMetric, resolveMetric, restrictAvailableMetrics };
+export { DEFAULT_METRIC, buildAvailableMetrics, getMetricLabel, isAggregateMetric, isSameMetric, normalizeMetricAllowances, resolveMetric, restrictAvailableMetrics };