@opendata-ai/openchart-core 6.12.0 → 6.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "6.12.0",
+  "version": "6.13.0",
   "description": "Types, theme, colors, accessibility, and utilities for openchart",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",

package/src/helpers/__tests__/spec-builders.test.ts

@@ -112,7 +112,7 @@ describe('lineChart', () => {
     const xChannel: EncodingChannel = {
       field: 'date',
       type: 'temporal',
-      axis: { label: 'Year' },
+      axis: { title: 'Year' },
     };
     const yChannel: EncodingChannel = {
       field: 'value',
@@ -173,7 +173,7 @@ describe('barChart', () => {
     const catChannel: EncodingChannel = {
       field: 'name',
       type: 'ordinal',
-      axis: { label: 'Fruit' },
+      axis: { title: 'Fruit' },
     };
 
     const spec = barChart(categoricalData, catChannel, 'count');
@@ -320,7 +320,7 @@ describe('mixed FieldRef usage', () => {
       field: 'value',
       type: 'quantitative',
       aggregate: 'mean',
-      axis: { label: 'Average Value', format: ',.1f' },
+      axis: { title: 'Average Value', format: ',.1f' },
     };
 
     const spec = lineChart(timeSeriesData, 'date', yChannel, {
@@ -331,7 +331,7 @@ describe('mixed FieldRef usage', () => {
     expect(spec.encoding.x?.type).toBe('temporal');
     // y was a full object, so it's passed through
     expect(spec.encoding.y?.aggregate).toBe('mean');
-    expect(spec.encoding.y?.axis?.label).toBe('Average Value');
+    expect(spec.encoding.y?.axis?.title).toBe('Average Value');
     // color was a full object
     expect(spec.encoding.color?.type).toBe('nominal');
   });

package/src/index.ts

@@ -17,8 +17,7 @@ export * from './types/index';
 // Colors: palette collections, contrast utilities, color-blindness simulation
 //
 // Individual named palettes (SEQUENTIAL_BLUE, DIVERGING_RED_BLUE, etc.) are
-// available via SEQUENTIAL_PALETTES and DIVERGING_PALETTES or by direct import
-// from '@opendata-ai/openchart-core/src/colors/palettes'.
+// available via the SEQUENTIAL_PALETTES and DIVERGING_PALETTES collections.
 // ---------------------------------------------------------------------------
 
 export type {

package/src/types/index.ts

@@ -84,6 +84,7 @@ export type {
 // Spec types (user input)
 export type {
   AggregateOp,
+  AggregateTransform,
   AnimationConfig,
   AnimationEase,
   AnimationPhaseConfig,
@@ -114,6 +115,7 @@ export type {
   FieldType,
   FilterPredicate,
   FilterTransform,
+  FoldTransform,
   GradientDef,
   GradientStop,
   GraphEdge,

package/src/types/spec.ts

@@ -195,7 +195,18 @@ export interface MarkDef {
 export type FieldType = 'quantitative' | 'temporal' | 'nominal' | 'ordinal';
 
 /** Aggregate function applied to a field before encoding. */
-export type AggregateOp = 'count' | 'sum' | 'mean' | 'median' | 'min' | 'max';
+export type AggregateOp =
+  | 'count'
+  | 'sum'
+  | 'mean'
+  | 'median'
+  | 'min'
+  | 'max'
+  | 'variance'
+  | 'stdev'
+  | 'distinct'
+  | 'q1'
+  | 'q3';
 
 /** Axis configuration for an encoding channel. */
 export interface AxisConfig {
@@ -227,12 +238,6 @@ export interface AxisConfig {
   titlePadding?: number;
   /** Padding between tick labels and axis. */
   labelPadding?: number;
-
-  // --- Deprecated aliases (will be removed) ---
-  /** @deprecated Use `title` instead. */
-  label?: string;
-  /** @deprecated Use `labelAngle` instead. */
-  tickAngle?: number;
 }
 
 /** Scale configuration for an encoding channel. */
@@ -309,10 +314,47 @@ export interface EncodingChannel {
   scale?: ScaleConfig;
   /**
    * Stacking behavior for quantitative channels (Vega-Lite aligned).
-   * - undefined | true | 'zero': stack (default, cumulative segments)
+   * - undefined | true | 'zero': stack from zero baseline (default)
+   * - 'normalize': stack and normalize to fraction of total (0-1 per category)
+   * - 'center': center stacks around zero (streamgraph style)
    * - null | false: no stacking (grouped/dodged side-by-side)
    */
-  stack?: boolean | 'zero' | null;
+  stack?: boolean | 'zero' | 'normalize' | 'center' | null;
+  /**
+   * Encoding-level bin shorthand (Vega-Lite aligned).
+   * When set, auto-generates a BinTransform during normalization and updates
+   * the field reference to the binned output (convention: `bin_<fieldName>`).
+   * - true: bin with default params
+   * - BinParams: bin with custom params (maxbins, step, etc.)
+   */
+  bin?: boolean | BinParams;
+  /**
+   * Encoding-level timeUnit shorthand (Vega-Lite aligned).
+   * When set, auto-generates a TimeUnitTransform during normalization and
+   * updates the field reference to the output (convention: `<timeUnit>_<fieldName>`).
+   */
+  timeUnit?: TimeUnit;
+  /**
+   * Sort order for categorical (nominal/ordinal) scale domains (Vega-Lite aligned).
+   * - 'ascending': sort domain values ascending (default VL behavior)
+   * - 'descending': sort domain values descending
+   * - null: use data order (no sorting)
+   * - undefined: ascending (VL default)
+   */
+  sort?: 'ascending' | 'descending' | null;
+  /**
+   * Display title override (Vega-Lite aligned).
+   * Used as the label in tooltips instead of the raw field name.
+   * Also usable for axis titles, but `axis.title` takes precedence there.
+   */
+  title?: string;
+  /**
+   * Format string for values (Vega-Lite aligned).
+   * For quantitative fields: d3-format string (e.g. ",.0f", "$,.2f").
+   * For temporal fields: d3-time-format string (e.g. "%Y", "%b %d").
+   * Used in tooltips; `axis.format` takes precedence for axis tick labels.
+   */
+  format?: string;
 }
 
 /**
@@ -1198,8 +1240,34 @@ export interface TimeUnitTransform {
   as: string;
 }
 
+/**
+ * Aggregate transform: group rows and compute summary statistics (VL aligned).
+ * Produces one row per group with the groupby fields and computed aggregates.
+ */
+export interface AggregateTransform {
+  aggregate: Array<{ op: AggregateOp; field: string; as: string }>;
+  groupby: string[];
+}
+
+/**
+ * Fold transform: unpivot wide-format columns into key/value rows (VL aligned).
+ * For each input row, produces N output rows (one per fold field) with all
+ * non-fold fields copied plus a key column (field name) and value column (field value).
+ */
+export interface FoldTransform {
+  fold: string[];
+  /** Output field names for [key, value]. Defaults to ['key', 'value']. */
+  as?: [string, string];
+}
+
 /** Discriminated union of all transform types. */
-export type Transform = FilterTransform | BinTransform | CalculateTransform | TimeUnitTransform;
+export type Transform =
+  | FilterTransform
+  | BinTransform
+  | CalculateTransform
+  | TimeUnitTransform
+  | AggregateTransform
+  | FoldTransform;
 
 // ---------------------------------------------------------------------------
 // Conditional encoding (Vega-Lite aligned)