@matthieumordrel/chart-studio 0.2.4 → 0.3.0

package/dist/core/types.d.mts

@@ -501,7 +501,18 @@ type ChartSchemaValidationTarget<T, TSchema extends ChartSchema<T, any>> = {
 type ValidatedChartSchema<T, TSchema> = TSchema extends ChartSchema<T, any> ? TSchema & ExactShape<ChartSchemaValidationTarget<T, TSchema>, TSchema> & ValidateChartSchemaLiterals<T, TSchema> : TSchema;
 /** Strict schema object returned by `defineChartSchema(...)`. */
 type DefinedChartSchema<T, TSchema extends ChartSchema<T, any> = ChartSchema<T, any>> = TSchema & ChartSchemaDefinitionBrand;
-type ResolvedChartSchemaFromDefinition<TSchema> = TSchema extends DefinedChartSchema<any, infer TResolvedSchema> ? TResolvedSchema : undefined;
+/**
+ * Public schema definition input accepted by chart-studio APIs.
+ *
+ * Most callers use the fluent builder returned by `defineChartSchema<Row>()`.
+ * Plain schema objects are also accepted at the runtime boundary.
+ */
+type ChartSchemaDefinition<T, TSchema extends ChartSchema<T, any> = ChartSchema<T, any>> = TSchema | {
+  build: () => DefinedChartSchema<T, TSchema>;
+};
+type ResolvedChartSchemaFromDefinition<TSchema> = TSchema extends DefinedChartSchema<any, infer TResolvedSchema> ? TResolvedSchema : TSchema extends {
+  build: () => DefinedChartSchema<any, infer TResolvedSchema>;
+} ? TResolvedSchema : TSchema extends ChartSchema<any, any> ? TSchema : undefined;
 /** GroupBy IDs narrowed by explicit schema restrictions when present. */
 type RestrictedGroupByColumnIdFromSchema<T, TSchema extends ChartSchema<T, any> | undefined = undefined> = RestrictOptionsFromControlConfig<ResolvedGroupByColumnIdFromSchema<T, TSchema>, ConfigSection<TSchema, 'groupBy'>>;
 /** X-axis IDs narrowed by explicit schema restrictions when present. */
@@ -657,7 +668,7 @@ type ChartTypeConfig = SelectableControlConfig<ChartType>;
 type TimeBucketConfig = SelectableControlConfig<TimeBucket>;
 type ExtractSchemaColumns<TSchema> = TSchema extends {
   columns?: infer TColumns;
-} ? Extract<TColumns, Record<string, unknown>> : undefined;
+} ? [Extract<TColumns, Record<string, unknown>>] extends [never] ? undefined : Extract<TColumns, Record<string, unknown>> : undefined;
 type RawSchemaColumnsFromColumns<T, TColumns extends Record<string, unknown> | undefined> = TColumns extends Record<string, unknown> ? { [TKey in keyof TColumns as TKey extends InferableFieldKey<T> ? TKey : never]: TColumns[TKey] } : undefined;
 type RawSchemaColumns<T, TSchema> = RawSchemaColumnsFromColumns<T, ExtractSchemaColumns<TSchema>>;
 type DerivedColumnIdsFromColumns<TColumns extends Record<string, unknown> | undefined> = Extract<TColumns extends Record<string, unknown> ? { [TKey in keyof TColumns]-?: TColumns[TKey] extends DerivedColumnSchema<any> ? TKey : never }[keyof TColumns] : never, string>;
@@ -750,11 +761,11 @@ type SortConfig = {
  * @property data - Array of raw data items
  * @property schema - Optional explicit schema layered on top of inference
  */
-type ChartSourceOptions<TId extends string = string, T = unknown, TSchema extends ChartSchema<T, any> | undefined = undefined> = {
+type ChartSourceOptions<TId extends string = string, T = unknown, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> = {
   id: TId;
   label: string;
   data: readonly T[];
-  schema?: DefinedChartSchema<T, Exclude<TSchema, undefined>>;
+  schema?: TSchema;
 };
 /** Convenience alias for any multi-source input definition. */
 type AnyChartSourceOptions = {
@@ -933,14 +944,16 @@ type ChartInstance<T, TColumnId extends string = string, TChartType extends Char
 };
 /** Single-source chart instance narrowed by one explicit schema. */
 type ChartInstanceFromSchema<T, TSchema extends ChartSchema<T, any> | undefined = undefined> = ChartInstance<T, ResolvedColumnIdFromSchema<T, TSchema>, RestrictedChartTypeFromSchema<TSchema>, RestrictedXAxisColumnIdFromSchema<T, TSchema>, RestrictedGroupByColumnIdFromSchema<T, TSchema>, Extract<MetricColumnIdFromMetric<RestrictedMetricFromSchema<T, TSchema>>, ResolvedMetricColumnIdFromSchema<T, TSchema>>, RestrictedMetricFromSchema<T, TSchema>, RestrictedFilterColumnIdFromSchema<T, TSchema>, ResolvedDateColumnIdFromSchema<T, TSchema>, RestrictedTimeBucketFromSchema<TSchema>>;
+/** Single-source chart instance narrowed by any supported schema input. */
+type ChartInstanceFromSchemaDefinition<T, TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined> = ChartInstanceFromSchema<T, ResolvedChartSchemaFromDefinition<TSchema>>;
 type SourceIdFromSource<TSource extends AnyChartSourceOptions> = TSource['id'];
 type SourceRowFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, any> ? TRow : never;
-type SourceColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? ResolvedColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
-type SourceXAxisColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedXAxisColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
-type SourceGroupByColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedGroupByColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
-type SourceMetricColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? Extract<MetricColumnIdFromMetric<RestrictedMetricFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>>>, ResolvedMetricColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>>> : never;
-type SourceFilterColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedFilterColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
-type SourceDateColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? ResolvedDateColumnIdFromSchema<TRow, Extract<TSchema, ChartSchema<TRow> | undefined>> : never;
+type SourceColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? ResolvedColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
+type SourceXAxisColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedXAxisColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
+type SourceGroupByColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedGroupByColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
+type SourceMetricColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? Extract<MetricColumnIdFromMetric<RestrictedMetricFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>>>, ResolvedMetricColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>>> : never;
+type SourceFilterColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? RestrictedFilterColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
+type SourceDateColumnIdFromSource<TSource extends AnyChartSourceOptions> = TSource extends ChartSourceOptions<string, infer TRow, infer TSchema> ? ResolvedDateColumnIdFromSchema<TRow, ResolvedChartSchemaFromDefinition<TSchema>> : never;
 type SourceIdFromSources<TSources extends NonEmptyChartSourceOptions> = Extract<TSources[number]['id'], string>;
 type SourceColumnIdFromSources<TSources extends NonEmptyChartSourceOptions> = TSources[number] extends infer TSource ? TSource extends AnyChartSourceOptions ? SourceColumnIdFromSource<TSource> : never : never;
 type MultiSourceChartBranch<TSources extends NonEmptyChartSourceOptions, TSource extends AnyChartSourceOptions> = Omit<ChartInstance<SourceRowFromSource<TSource>, SourceColumnIdFromSources<TSources>>, 'activeSourceId' | 'setActiveSource' | 'sources' | 'xAxisId' | 'setXAxis' | 'availableXAxes' | 'groupById' | 'setGroupBy' | 'availableGroupBys' | 'metric' | 'setMetric' | 'availableMetrics' | 'filters' | 'toggleFilter' | 'clearFilter' | 'availableFilters' | 'dateRange' | 'referenceDateId' | 'setReferenceDateId' | 'availableDateColumns' | 'columns'> & {
@@ -985,4 +998,4 @@ type MultiSourceChartBranch<TSources extends NonEmptyChartSourceOptions, TSource
  */
 type MultiSourceChartInstance<TSources extends NonEmptyChartSourceOptions> = TSources[number] extends infer TSource ? TSource extends AnyChartSourceOptions ? MultiSourceChartBranch<TSources, TSource> : never : never;
 //#endregion
-export { AggregateFunction, AggregateMetric, AvailableFilter, BooleanColumn, CategoricalChartType, CategoryColumn, ChartColumn, ChartColumnType, ChartInstance, ChartInstanceFromSchema, ChartSchema, ChartSeries, ChartSourceOptions, ChartType, ChartTypeConfig, ColumnFormat, ColumnFormatPreset, CountMetric, DateColumn, DateColumnFormat, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, ExactShape, FilterState, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricConfig, MultiSourceChartInstance, NonEmptyChartSourceOptions, NumberColumn, NumberColumnFormat, NumericAggregateFunction, RawColumnSchemaFor, RawColumnSchemaMap, ResolvedChartSchemaFromDefinition, ResolvedColumnIdFromSchema, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, RestrictedChartTypeFromSchema, RestrictedFilterColumnIdFromSchema, RestrictedGroupByColumnIdFromSchema, RestrictedMetricFromSchema, RestrictedTimeBucketFromSchema, RestrictedXAxisColumnIdFromSchema, SchemaColumnsValidationShape, SelectableControlConfig, SortConfig, SortDirection, TimeBucket, TimeBucketConfig, TimeSeriesChartType, TransformedDataPoint, ValidatedChartSchema, XAxisConfig };
+export { AggregateFunction, AggregateMetric, AvailableFilter, BaseColumnHint, BooleanColumn, CategoricalChartType, CategoryColumn, ChartColumn, ChartColumnType, ChartInstance, ChartInstanceFromSchema, ChartInstanceFromSchemaDefinition, ChartSchema, ChartSchemaDefinition, ChartSeries, ChartSourceOptions, ChartType, ChartTypeConfig, ColumnFormat, ColumnFormatPreset, CountMetric, DateColumn, DateColumnFormat, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, FilterState, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricConfig, MultiSourceChartInstance, NonEmptyChartSourceOptions, NumberColumn, NumberColumnFormat, NumericAggregateFunction, RawColumnSchemaFor, RawColumnSchemaMap, ResolvedChartSchemaFromDefinition, ResolvedColumnIdFromSchema, ResolvedFilterColumnIdFromSchema, ResolvedGroupByColumnIdFromSchema, ResolvedMetricColumnIdFromSchema, ResolvedXAxisColumnIdFromSchema, RestrictedChartTypeFromSchema, RestrictedFilterColumnIdFromSchema, RestrictedGroupByColumnIdFromSchema, RestrictedMetricFromSchema, RestrictedTimeBucketFromSchema, RestrictedXAxisColumnIdFromSchema, SelectableControlConfig, SortConfig, SortDirection, TimeBucket, TimeBucketConfig, TimeSeriesChartType, TransformedDataPoint, ValidatedChartSchema, XAxisConfig };

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

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

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

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

package/dist/core/use-chart.mjs

@@ -1,8 +1,9 @@
 import { TIME_BUCKET_ORDER, resolveConfiguredIdSelection, resolveConfiguredValue, restrictConfiguredIdOptions, restrictConfiguredValues } from "./config-utils.mjs";
 import { CHART_TYPE_CONFIG, getAvailableChartTypes } from "./chart-capabilities.mjs";
 import { resolvePresetFilter } from "./date-range-presets.mjs";
+import { buildAvailableMetrics, isSameMetric, resolveMetric, restrictAvailableMetrics } from "./metric-utils.mjs";
+import { resolveChartSchemaDefinition } from "./schema-builder.mjs";
 import { inferColumnsFromData } from "./infer-columns.mjs";
-import { DEFAULT_METRIC, buildAvailableMetrics, isSameMetric, resolveMetric, restrictAvailableMetrics } from "./metric-utils.mjs";
 import { applyFilters, extractAvailableFilters, runPipeline } from "./pipeline.mjs";
 import { computeDateRange, filterByDateRange } from "./date-utils.mjs";
 import { DEFAULT_TIME_BUCKET } from "./use-chart-options.mjs";
@@ -21,28 +22,32 @@ function createAvailableFilterValueMap(availableFilters) {
 function useChart(options) {
 	if ("sources" in options && options.sources?.length === 0) throw new Error("useChart requires at least one source");
 	const sources = useMemo(() => {
-		if ("sources" in options && options.sources) return options.sources.map((source) => ({
-			id: source.id,
-			label: source.label,
-			data: source.data,
-			columns: inferColumnsFromData(source.data, source.schema),
-			schema: source.schema
-		}));
+		if ("sources" in options && options.sources) return options.sources.map((source) => {
+			const schema = resolveChartSchemaDefinition(source.schema);
+			return {
+				id: source.id,
+				label: source.label,
+				data: source.data,
+				columns: inferColumnsFromData(source.data, schema),
+				schema
+			};
+		});
+		const schema = resolveChartSchemaDefinition(options.schema);
 		return [{
 			id: "default",
 			label: options.sourceLabel ?? "Unnamed Source",
 			data: options.data,
-			columns: inferColumnsFromData(options.data, options.schema),
-			schema: options.schema
+			columns: inferColumnsFromData(options.data, schema),
+			schema
 		}];
 	}, [options]);
 	const hasMultipleSources = sources.length > 1;
 	const [activeSourceIdRaw, setActiveSourceRaw] = useState(sources[0]?.id ?? "default");
-	const [chartType, setChartTypeRaw] = useState("bar");
+	const [chartType, setChartTypeRaw] = useState(null);
 	const [xAxisId, setXAxisRaw] = useState(null);
 	const [groupById, setGroupByRaw] = useState(null);
-	const [metric, setMetricRaw] = useState(DEFAULT_METRIC);
-	const [timeBucket, setTimeBucketRaw] = useState(DEFAULT_TIME_BUCKET);
+	const [metric, setMetricRaw] = useState(null);
+	const [timeBucket, setTimeBucketRaw] = useState(null);
 	const [filters, setFilters] = useState(() => /* @__PURE__ */ new Map());
 	const [sorting, setSorting] = useState(null);
 	const [referenceDateIdRaw, setReferenceDateIdRaw] = useState(null);
@@ -114,7 +119,7 @@ function useChart(options) {
 		resolvedXAxisType,
 		activeSource.schema
 	]);
-	const resolvedChartType = useMemo(() => resolveConfiguredValue(chartType, availableChartTypes, activeSource.schema?.chartType?.default), [
+	const resolvedChartType = useMemo(() => resolveConfiguredValue(chartType, availableChartTypes, activeSource.schema?.chartType?.default, "bar"), [
 		chartType,
 		availableChartTypes,
 		activeSource.schema
@@ -127,7 +132,7 @@ function useChart(options) {
 		resolvedChartType,
 		activeSource.schema
 	]);
-	const resolvedTimeBucket = useMemo(() => resolveConfiguredValue(timeBucket, availableTimeBuckets, activeSource.schema?.timeBucket?.default), [
+	const resolvedTimeBucket = useMemo(() => resolveConfiguredValue(timeBucket, availableTimeBuckets, activeSource.schema?.timeBucket?.default, DEFAULT_TIME_BUCKET), [
 		timeBucket,
 		availableTimeBuckets,
 		activeSource.schema

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AggregateFunction, AggregateMetric, AvailableFilter, BooleanColumn, CategoricalChartType, CategoryColumn, ChartColumn, ChartColumnType, ChartInstance, ChartInstanceFromSchema, ChartSchema, ChartSeries, ChartSourceOptions, ChartType, ChartTypeConfig, ColumnFormat, ColumnFormatPreset, CountMetric, DateColumn, DateColumnFormat, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, FilterState, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricConfig, MultiSourceChartInstance, NumberColumn, NumberColumnFormat, NumericAggregateFunction, RawColumnSchemaFor, RawColumnSchemaMap, ResolvedColumnIdFromSchema, RestrictedChartTypeFromSchema, RestrictedFilterColumnIdFromSchema, RestrictedGroupByColumnIdFromSchema, RestrictedMetricFromSchema, RestrictedTimeBucketFromSchema, RestrictedXAxisColumnIdFromSchema, SelectableControlConfig, SortConfig, SortDirection, TimeBucket, TimeBucketConfig, TimeSeriesChartType, TransformedDataPoint, ValidatedChartSchema, XAxisConfig } from "./core/types.mjs";
+import { AggregateFunction, AggregateMetric, AvailableFilter, BooleanColumn, CategoricalChartType, CategoryColumn, ChartColumn, ChartColumnType, ChartInstance, ChartInstanceFromSchema, ChartInstanceFromSchemaDefinition, ChartSchema, ChartSchemaDefinition, ChartSeries, ChartSourceOptions, ChartType, ChartTypeConfig, ColumnFormat, ColumnFormatPreset, CountMetric, DateColumn, DateColumnFormat, DefinedChartSchema, DerivedBooleanColumnSchema, DerivedCategoryColumnSchema, DerivedColumnSchema, DerivedDateColumnSchema, DerivedNumberColumnSchema, FilterState, FiltersConfig, GroupByConfig, InferableFieldKey, Metric, MetricConfig, MultiSourceChartInstance, NumberColumn, NumberColumnFormat, NumericAggregateFunction, RawColumnSchemaFor, RawColumnSchemaMap, ResolvedColumnIdFromSchema, RestrictedChartTypeFromSchema, RestrictedFilterColumnIdFromSchema, RestrictedGroupByColumnIdFromSchema, RestrictedMetricFromSchema, RestrictedTimeBucketFromSchema, RestrictedXAxisColumnIdFromSchema, SelectableControlConfig, SortConfig, SortDirection, TimeBucket, TimeBucketConfig, TimeSeriesChartType, TransformedDataPoint, ValidatedChartSchema, XAxisConfig } from "./core/types.mjs";
 import { CHART_TYPE_CONFIG, ChartAxisType, ChartTypeCapabilities } from "./core/chart-capabilities.mjs";
 import { buildColorMap, getSeriesColor } from "./core/colors.mjs";
 import { defineChartSchema } from "./core/define-chart-schema.mjs";
@@ -7,4 +7,4 @@ import { buildAvailableMetrics, getMetricLabel } from "./core/metric-utils.mjs";
 import { PipelineInput, PipelineOutput, applyFilters, extractAvailableFilters, runPipeline } from "./core/pipeline.mjs";
 import { UseChartOptions } from "./core/use-chart-options.mjs";
 import { useChart } from "./core/use-chart.mjs";
-export { type AggregateFunction, type AggregateMetric, type AvailableFilter, type BooleanColumn, CHART_TYPE_CONFIG, type CategoricalChartType, type CategoryColumn, type ChartAxisType, type ChartColumn, type ChartColumnType, type ChartInstance, type ChartInstanceFromSchema, type ChartSchema, type ChartSeries, type ChartSourceOptions, type ChartType, type ChartTypeCapabilities, type ChartTypeConfig, type ColumnFormat, type ColumnFormatPreset, type CountMetric, type DateColumn, type DateColumnFormat, type DefinedChartSchema, type DerivedBooleanColumnSchema, type DerivedCategoryColumnSchema, type DerivedColumnSchema, type DerivedDateColumnSchema, type DerivedNumberColumnSchema, type FilterState, type FiltersConfig, type GroupByConfig, type InferableFieldKey, type Metric, type MetricConfig, type MultiSourceChartInstance, type NumberColumn, type NumberColumnFormat, type NumericAggregateFunction, type PipelineInput, type PipelineOutput, type RawColumnSchemaFor, type RawColumnSchemaMap, type ResolvedColumnIdFromSchema, type RestrictedChartTypeFromSchema, type RestrictedFilterColumnIdFromSchema, type RestrictedGroupByColumnIdFromSchema, type RestrictedMetricFromSchema, type RestrictedTimeBucketFromSchema, type RestrictedXAxisColumnIdFromSchema, type SelectableControlConfig, type SortConfig, type SortDirection, type TimeBucket, type TimeBucketConfig, type TimeSeriesChartType, type TransformedDataPoint, type UseChartOptions, type ValidatedChartSchema, type XAxisConfig, applyFilters, buildAvailableMetrics, buildColorMap, defineChartSchema, extractAvailableFilters, getMetricLabel, getSeriesColor, inferColumnsFromData, runPipeline, useChart };
+export { type AggregateFunction, type AggregateMetric, type AvailableFilter, type BooleanColumn, CHART_TYPE_CONFIG, type CategoricalChartType, type CategoryColumn, type ChartAxisType, type ChartColumn, type ChartColumnType, type ChartInstance, type ChartInstanceFromSchema, type ChartInstanceFromSchemaDefinition, type ChartSchema, type ChartSchemaDefinition, type ChartSeries, type ChartSourceOptions, type ChartType, type ChartTypeCapabilities, type ChartTypeConfig, type ColumnFormat, type ColumnFormatPreset, type CountMetric, type DateColumn, type DateColumnFormat, type DefinedChartSchema, type DerivedBooleanColumnSchema, type DerivedCategoryColumnSchema, type DerivedColumnSchema, type DerivedDateColumnSchema, type DerivedNumberColumnSchema, type FilterState, type FiltersConfig, type GroupByConfig, type InferableFieldKey, type Metric, type MetricConfig, type MultiSourceChartInstance, type NumberColumn, type NumberColumnFormat, type NumericAggregateFunction, type PipelineInput, type PipelineOutput, type RawColumnSchemaFor, type RawColumnSchemaMap, type ResolvedColumnIdFromSchema, type RestrictedChartTypeFromSchema, type RestrictedFilterColumnIdFromSchema, type RestrictedGroupByColumnIdFromSchema, type RestrictedMetricFromSchema, type RestrictedTimeBucketFromSchema, type RestrictedXAxisColumnIdFromSchema, type SelectableControlConfig, type SortConfig, type SortDirection, type TimeBucket, type TimeBucketConfig, type TimeSeriesChartType, type TransformedDataPoint, type UseChartOptions, type ValidatedChartSchema, type XAxisConfig, applyFilters, buildAvailableMetrics, buildColorMap, defineChartSchema, extractAvailableFilters, getMetricLabel, getSeriesColor, inferColumnsFromData, runPipeline, useChart };

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { CHART_TYPE_CONFIG } from "./core/chart-capabilities.mjs";
 import { buildColorMap, getSeriesColor } from "./core/colors.mjs";
+import { buildAvailableMetrics, getMetricLabel } from "./core/metric-utils.mjs";
 import { defineChartSchema } from "./core/define-chart-schema.mjs";
 import { inferColumnsFromData } from "./core/infer-columns.mjs";
-import { buildAvailableMetrics, getMetricLabel } from "./core/metric-utils.mjs";
 import { applyFilters, extractAvailableFilters, runPipeline } from "./core/pipeline.mjs";
 import { useChart } from "./core/use-chart.mjs";
 export { CHART_TYPE_CONFIG, applyFilters, buildAvailableMetrics, buildColorMap, defineChartSchema, extractAvailableFilters, getMetricLabel, getSeriesColor, inferColumnsFromData, runPipeline, useChart };

package/dist/ui/chart-canvas.d.mts

@@ -15,11 +15,15 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
  * @property showDataLabels - Opt into cartesian/pie value labels using the shared formatting rules.
  */
 type ChartCanvasProps = {
-  height?: number;
-  className?: string;
+  /** Chart height in pixels (default: 300) */height?: number; /** Additional CSS classes */
+  className?: string; /** Will show labels using the shared formatting rules. (default: false) */
   showDataLabels?: boolean;
 };
-/** Renders the appropriate recharts chart based on the chart instance state. */
+/** Renders the appropriate recharts chart based on the chart instance state.
+ * @param height - Chart height in pixels (default: 300)
+ * @param className - Additional CSS classes
+ * @param showDataLabels - Opt into cartesian/pie value labels using the shared formatting rules.
+ */
 declare function ChartCanvas({
   height,
   className,

package/dist/ui/chart-canvas.mjs

@@ -2,6 +2,7 @@ import { getSeriesColor } from "../core/colors.mjs";
 import { createNumericRange, formatChartValue, formatTimeBucketLabel, shouldAllowDecimalTicks } from "../core/formatting.mjs";
 import { useChartContext } from "./chart-context.mjs";
 import { selectVisibleXAxisTicks } from "./chart-axis-ticks.mjs";
+import { getPercentStackedDisplayValue } from "./percent-stacked.mjs";
 import { useEffect, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Area, AreaChart, Bar, BarChart, CartesianGrid, LabelList, Legend, Line, LineChart, Pie, PieChart, Tooltip, XAxis, YAxis } from "recharts";
@@ -213,7 +214,11 @@ function useCssBarRadius() {
 	}, []);
 	return radiusPx;
 }
-/** Renders the appropriate recharts chart based on the chart instance state. */
+/** Renders the appropriate recharts chart based on the chart instance state.
+* @param height - Chart height in pixels (default: 300)
+* @param className - Additional CSS classes
+* @param showDataLabels - Opt into cartesian/pie value labels using the shared formatting rules.
+*/
 function ChartCanvas({ height = 300, className, showDataLabels = false }) {
 	const chart = useChartContext();
 	const { chartType, transformedData, series, connectNulls } = chart;
@@ -335,13 +340,19 @@ function ChartCanvas({ height = 300, className, showDataLabels = false }) {
 */
 const PERCENT_STACKED_COLUMN = {
 	type: "number",
-	format: "percent",
-	formatter: void 0
+	format: "percent"
 };
 const PERCENT_STACKED_RANGE = {
 	min: 0,
 	max: 1
 };
+function createStackedTooltipItemSorter(series) {
+	const order = new Map(series.map((s, index) => [s.dataKey, index]));
+	return (item) => {
+		const dataKey = typeof item.dataKey === "string" ? item.dataKey : typeof item.name === "string" ? item.name : "";
+		return -(order.get(dataKey) ?? -1);
+	};
+}
 /**
 * Remove data points where every series value is null.
 *
@@ -360,7 +371,7 @@ function filterAllNullPoints(data, series) {
 * Owns the grid, axes, tooltip, and legend — the only things that change
 * per chart type are the root component and the series element.
 */
-function CartesianChartShell({ data, series, width, height, valueColumn, valueRange, allowDecimalTicks, xColumn, timeBucket, showDataLabels, Chart, renderSeries }) {
+function CartesianChartShell({ data, series, width, height, valueColumn, valueRange, allowDecimalTicks, xColumn, timeBucket, showDataLabels, Chart, renderSeries, tooltipItemSorter }) {
 	const yAxisWidth = estimateYAxisWidth(valueRange, valueColumn);
 	const xAxisTickValues = selectVisibleXAxisTicks({
 		values: data.map(getXAxisTickValue),
@@ -402,6 +413,7 @@ function CartesianChartShell({ data, series, width, height, valueColumn, valueRa
 				}) : String(value)
 			}),
 			/* @__PURE__ */ jsx(Tooltip, {
+				itemSorter: tooltipItemSorter,
 				formatter: (value) => typeof value === "number" ? formatChartValue(value, {
 					column: valueColumn,
 					surface: "tooltip",
@@ -443,6 +455,7 @@ function BarChartRenderer(props) {
 	return /* @__PURE__ */ jsx(CartesianChartShell, {
 		...props,
 		Chart: BarChart,
+		tooltipItemSorter: isStacked ? createStackedTooltipItemSorter(series) : void 0,
 		renderSeries: (s) => {
 			const isTop = !isStacked || s.dataKey === topSeriesKey;
 			return /* @__PURE__ */ jsx(Bar, {
@@ -511,6 +524,8 @@ function AreaChartRenderer(props) {
 }
 function PercentAreaChartRenderer(props) {
 	const { series, data, xColumn, timeBucket, showDataLabels, connectNulls, width, height } = props;
+	const seriesKeys = series.map((s) => s.dataKey);
+	const tooltipItemSorter = createStackedTooltipItemSorter(series);
 	const stackableData = filterAllNullPoints(data, series);
 	const yAxisWidth = estimateYAxisWidth(PERCENT_STACKED_RANGE, PERCENT_STACKED_COLUMN);
 	const xAxisTickValues = selectVisibleXAxisTicks({
@@ -553,11 +568,20 @@ function PercentAreaChartRenderer(props) {
 				width: yAxisWidth
 			}),
 			/* @__PURE__ */ jsx(Tooltip, {
-				formatter: (value) => typeof value === "number" ? formatChartValue(value, {
-					column: PERCENT_STACKED_COLUMN,
-					surface: "tooltip",
-					numericRange: PERCENT_STACKED_RANGE
-				}) : value,
+				itemSorter: tooltipItemSorter,
+				formatter: (_value, _name, entry) => {
+					const proportion = getPercentStackedDisplayValue(entry, String(entry.dataKey ?? ""), seriesKeys);
+					if (proportion != null) return formatChartValue(proportion, {
+						column: PERCENT_STACKED_COLUMN,
+						surface: "tooltip",
+						numericRange: PERCENT_STACKED_RANGE
+					});
+					return typeof _value === "number" ? formatChartValue(_value, {
+						column: PERCENT_STACKED_COLUMN,
+						surface: "tooltip",
+						numericRange: PERCENT_STACKED_RANGE
+					}) : _value;
+				},
 				labelFormatter: (label, payload) => formatTooltipLabel(label, payload, xColumn, timeBucket)
 			}),
 			series.length > 1 && /* @__PURE__ */ jsx(Legend, {}),
@@ -573,6 +597,7 @@ function PercentAreaChartRenderer(props) {
 				children: showDataLabels && /* @__PURE__ */ jsx(LabelList, {
 					position: "top",
 					offset: 8,
+					valueAccessor: (entry) => getPercentStackedDisplayValue(entry, s.dataKey, seriesKeys) ?? 0,
 					formatter: (value) => formatDataLabel(value, PERCENT_STACKED_COLUMN, PERCENT_STACKED_RANGE)
 				})
 			}, s.dataKey))
@@ -608,14 +633,9 @@ function PercentBarChartRenderer(props) {
 	const { series, data, xColumn, timeBucket, showDataLabels, width, height } = props;
 	const barRadius = useCssBarRadius();
 	const topSeriesKey = series[series.length - 1]?.dataKey;
-	const yAxisWidth = estimateYAxisWidth({
-		min: 0,
-		max: 100
-	}, {
-		type: "number",
-		format: void 0,
-		formatter: void 0
-	});
+	const seriesKeys = series.map((s) => s.dataKey);
+	const tooltipItemSorter = createStackedTooltipItemSorter(series);
+	const yAxisWidth = estimateYAxisWidth(PERCENT_STACKED_RANGE, PERCENT_STACKED_COLUMN);
 	const xAxisTickValues = selectVisibleXAxisTicks({
 		values: data.map(getXAxisTickValue),
 		labels: data.map((point) => formatXAxisValue(getXAxisTickValue(point), xColumn, timeBucket, "axis")),
@@ -648,13 +668,27 @@ function PercentBarChartRenderer(props) {
 				tickLine: false,
 				axisLine: false,
 				tickMargin: 4,
-				tickFormatter: (value) => typeof value === "number" ? `${Math.round(value * 100)}%` : String(value),
+				tickFormatter: (value) => typeof value === "number" ? formatChartValue(value, {
+					column: PERCENT_STACKED_COLUMN,
+					surface: "axis",
+					numericRange: PERCENT_STACKED_RANGE
+				}) : String(value),
 				width: yAxisWidth
 			}),
 			/* @__PURE__ */ jsx(Tooltip, {
-				formatter: (value, name) => {
-					if (typeof value === "number") return [`${(value * 100).toFixed(1)}%`, name];
-					return [value, name];
+				itemSorter: tooltipItemSorter,
+				formatter: (_value, _name, entry) => {
+					const proportion = getPercentStackedDisplayValue(entry, String(entry.dataKey ?? ""), seriesKeys);
+					if (proportion != null) return formatChartValue(proportion, {
+						column: PERCENT_STACKED_COLUMN,
+						surface: "tooltip",
+						numericRange: PERCENT_STACKED_RANGE
+					});
+					return typeof _value === "number" ? formatChartValue(_value, {
+						column: PERCENT_STACKED_COLUMN,
+						surface: "tooltip",
+						numericRange: PERCENT_STACKED_RANGE
+					}) : _value;
 				},
 				labelFormatter: (label, payload) => formatTooltipLabel(label, payload, xColumn, timeBucket)
 			}),
@@ -672,7 +706,13 @@ function PercentBarChartRenderer(props) {
 						0,
 						0
 					] : 0,
-					stackId: "percent"
+					stackId: "percent",
+					children: showDataLabels && /* @__PURE__ */ jsx(LabelList, {
+						position: "top",
+						offset: 8,
+						valueAccessor: (entry) => getPercentStackedDisplayValue(entry, s.dataKey, seriesKeys) ?? 0,
+						formatter: (value) => formatDataLabel(value, PERCENT_STACKED_COLUMN, PERCENT_STACKED_RANGE)
+					})
 				}, s.dataKey);
 			})
 		]

package/dist/ui/chart-context.d.mts

@@ -1,4 +1,4 @@
-import { ChartColumn, ChartInstance, ChartInstanceFromSchema, ChartSchema, Metric, ResolvedChartSchemaFromDefinition } from "../core/types.mjs";
+import { ChartColumn, ChartInstance, ChartInstanceFromSchemaDefinition, ChartSchemaDefinition, Metric } from "../core/types.mjs";
 import { ReactElement, ReactNode } from "react";
 
 //#region src/ui/chart-context.d.ts
@@ -70,10 +70,14 @@ declare function useChartContext(): ChartContextChart;
  * React cannot infer provider generics through arbitrary subtrees, so callers
  * provide the row type (and optional schema type) explicitly.
  */
-declare function useTypedChartContext<T, const TSchema extends ChartSchema<T, any> | undefined = undefined>(): ChartInstanceFromSchema<T, ResolvedChartSchemaFromDefinition<TSchema>>;
+declare function useTypedChartContext<T, const TSchema extends ChartSchemaDefinition<T, any> | undefined = undefined>(): ChartInstanceFromSchemaDefinition<T, TSchema>;
 /**
  * Root provider component. Wraps children with the chart instance context.
  *
+ * @param chart - The chart instance to share
+ * @param children - The children to render
+ * @param className - Additional CSS classes for the chart container
+ *
  * @example
  * ```tsx
  * <Chart chart={chart}>
@@ -87,8 +91,8 @@ declare function Chart({
   children,
   className
 }: {
-  chart: AnyChartInstance;
-  children: ReactNode;
+  /** The chart instance to share. Create it with `useChart()` first.*/chart: AnyChartInstance; /** The children to render. Can be any UI primitives from the UI package. */
+  children: ReactNode; /** Additional CSS classes for the chart container. */
   className?: string;
 }): ReactElement;
 //#endregion

package/dist/ui/chart-debug.d.mts

@@ -5,12 +5,16 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
  * Debug panel — shows raw data, transformed data, series, and current state.
  * Drop `<ChartDebug />` inside a `<Chart>` to inspect what's happening.
  */
-/** Debug panel that renders chart internals as formatted JSON. */
+/** Debug panel that renders chart internals as formatted JSON.
+ *
+ * @param className - Additional CSS classes for the debug panel.
+ * @param defaultOpen - Whether the debug panel should be open by default. (default: false)
+ */
 declare function ChartDebug({
   className,
   defaultOpen
 }: {
-  className?: string;
+  /** Additional CSS classes for the debug panel. */className?: string; /** Whether the debug panel should be open by default. (default: false) */
   defaultOpen?: boolean;
 }): react_jsx_runtime0.JSX.Element;
 //#endregion

package/dist/ui/chart-debug.mjs

@@ -112,7 +112,11 @@ function TabButton({ tab, isActive, onClick }) {
 		children: tab.label
 	});
 }
-/** Debug panel that renders chart internals as formatted JSON. */
+/** Debug panel that renders chart internals as formatted JSON.
+* 
+* @param className - Additional CSS classes for the debug panel.
+* @param defaultOpen - Whether the debug panel should be open by default. (default: false)
+*/
 function ChartDebug({ className, defaultOpen = false }) {
 	const chart = useChartContext();
 	const [isOpen, setIsOpen] = useState(defaultOpen);

package/dist/ui/chart-toolbar.d.mts

@@ -10,8 +10,8 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
  * @property hidden - Control IDs to completely hide (not in toolbar, not in overflow)
  */
 type ChartToolbarProps = {
-  className?: string;
-  pinned?: readonly ControlId[];
+  /** Additional CSS classes for the toolbar container. */className?: string; /** Control IDs to always show in the toolbar row (outside the overflow menu) */
+  pinned?: readonly ControlId[]; /** Control IDs to completely hide (not in toolbar, not in overflow) */
   hidden?: readonly ControlId[];
 };
 /**
@@ -19,6 +19,10 @@ type ChartToolbarProps = {
  *
  * Controls are rendered in registry order. Each sub-component still
  * auto-hides when not relevant (e.g. time bucket only shows for date X-axis).
+ *
+ * @param className - Additional CSS classes for the toolbar container
+ * @param pinned - Control IDs to always show in the toolbar row (outside the overflow menu)
+ * @param hidden - Control IDs to completely hide (not in toolbar, not in overflow)
  */
 declare function ChartToolbar({
   className,

package/dist/ui/chart-toolbar.mjs

@@ -32,6 +32,10 @@ const DEFAULT_PINNED_CONTROLS = ["dateRange"];
 *
 * Controls are rendered in registry order. Each sub-component still
 * auto-hides when not relevant (e.g. time bucket only shows for date X-axis).
+* 
+* @param className - Additional CSS classes for the toolbar container
+* @param pinned - Control IDs to always show in the toolbar row (outside the overflow menu)
+* @param hidden - Control IDs to completely hide (not in toolbar, not in overflow)
 */
 function ChartToolbar({ className, pinned = DEFAULT_PINNED_CONTROLS, hidden = [] }) {
 	const pinnedSet = useMemo(() => new Set(pinned), [pinned]);

package/dist/ui/percent-stacked.mjs

@@ -0,0 +1,36 @@
+//#region src/ui/percent-stacked.ts
+/**
+* Recharts stacked graphical entries expose [lower, upper] bounds after
+* stackOffset="expand". The visible segment size is upper - lower.
+*/
+function getPercentStackedProportion(entry) {
+	const value = entry.value;
+	if (Array.isArray(value) && typeof value[0] === "number" && typeof value[1] === "number") return value[1] - value[0];
+	return null;
+}
+/**
+* Recharts tooltip payload entries are rebuilt from the raw transformed row,
+* so value stays as the raw metric and payload contains the full bucket.
+*/
+function getPercentStackedProportionFromPayload(payload, dataKey, seriesKeys) {
+	if (!payload || typeof payload !== "object") return null;
+	const point = payload;
+	const rawValue = point[dataKey];
+	if (typeof rawValue !== "number") return null;
+	let total = 0;
+	for (const seriesKey of seriesKeys) {
+		const seriesValue = point[seriesKey];
+		if (typeof seriesValue === "number") total += seriesValue;
+	}
+	if (total <= 0) return null;
+	return rawValue / total;
+}
+/**
+* Prefer the raw-row calculation because it works for both tooltip payloads
+* and label entries, then fall back to stacked bounds when present.
+*/
+function getPercentStackedDisplayValue(entry, dataKey, seriesKeys) {
+	return getPercentStackedProportionFromPayload(entry.payload, dataKey, seriesKeys) ?? getPercentStackedProportion(entry);
+}
+//#endregion
+export { getPercentStackedDisplayValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthieumordrel/chart-studio",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Headless, composable charting for React with an optional batteries-included UI layer.",
   "type": "module",
   "sideEffects": false,