@opendata-ai/openchart-core 6.11.0 → 6.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "6.11.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/layout/__tests__/chrome.test.ts

@@ -190,4 +190,19 @@ describe('computeChrome', () => {
     expect(result.title).toBeDefined();
     // Just verify it runs without error; exact values depend on measure fn
   });
+
+  it('returns zero bottom height when watermark is false and no bottom chrome', () => {
+    const chrome: Chrome = { title: 'Title' };
+    const result = computeChrome(chrome, theme, 600, undefined, 'full', undefined, false);
+    expect(result.bottomHeight).toBe(0);
+  });
+
+  it('does not reserve brand width for bottom text when watermark is false', () => {
+    const chrome: Chrome = { source: 'Source: World Bank' };
+    const withWatermark = computeChrome(chrome, theme, 600, undefined, 'full', undefined, true);
+    const withoutWatermark = computeChrome(chrome, theme, 600, undefined, 'full', undefined, false);
+
+    // Without watermark, source text gets full width (not reduced by BRAND_RESERVE_WIDTH)
+    expect(withoutWatermark.source!.maxWidth).toBeGreaterThan(withWatermark.source!.maxWidth);
+  });
 });

package/src/layout/chrome.ts

@@ -148,6 +148,7 @@ export function computeChrome(
   measureText?: MeasureTextFn,
   chromeMode: ChromeMode = 'full',
   padding?: number,
+  watermark: boolean = true,
 ): ResolvedChrome {
   if (!chrome || chromeMode === 'hidden') {
     // Brand watermark is also skipped at cramped sizes (height < 200px triggers
@@ -217,7 +218,7 @@ export function computeChrome(
   // renders for wide-enough charts. Reserve space so it doesn't overflow.
   if (chromeMode === 'compact') {
     let compactBottom = 0;
-    if (width >= BRAND_MIN_WIDTH) {
+    if (watermark && width >= BRAND_MIN_WIDTH) {
       const brandHeight = estimateTextHeight(BRAND_FONT_SIZE, 1);
       compactBottom = theme.spacing.chartToFooter + brandHeight + pad;
     }
@@ -230,7 +231,8 @@ export function computeChrome(
 
   // Bottom elements: source, byline, footer
   // Reserve space on the right for the brand watermark so text doesn't overlap it
-  const bottomMaxWidth = maxWidth - BRAND_RESERVE_WIDTH;
+  const shouldReserveBrandWidth = watermark && width >= BRAND_MIN_WIDTH;
+  const bottomMaxWidth = maxWidth - (shouldReserveBrandWidth ? BRAND_RESERVE_WIDTH : 0);
   const bottomElements: Partial<Pick<ResolvedChrome, 'source' | 'byline' | 'footer'>> = {};
   let bottomHeight = 0;
 
@@ -300,7 +302,7 @@ export function computeChrome(
     // Ensure bottom height accommodates the brand watermark, which renders
     // at the same Y as the first bottom chrome item but is taller (20px font
     // vs 12px source). Without this, the brand overflows the SVG viewBox.
-    if (width >= BRAND_MIN_WIDTH) {
+    if (watermark && width >= BRAND_MIN_WIDTH) {
       const brandHeight = estimateTextHeight(BRAND_FONT_SIZE, 1);
       // firstItemY is chartToFooter (the Y offset of the first bottom item).
       // The brand needs brandHeight below that point; bottom chrome content
@@ -313,7 +315,7 @@ export function computeChrome(
 
     // Add bottom padding
     bottomHeight += pad;
-  } else if (width >= BRAND_MIN_WIDTH) {
+  } else if (watermark && width >= BRAND_MIN_WIDTH) {
     // No bottom chrome items, but brand watermark still renders.
     // Reserve space: chartToFooter gap + brand text height + padding.
     const brandHeight = estimateTextHeight(BRAND_FONT_SIZE, 1);

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/layout.ts

@@ -667,6 +667,8 @@ export interface ChartLayout {
   dimensions: { width: number; height: number };
   /** Resolved animation config. Present only when animation is enabled. */
   animation?: ResolvedAnimation;
+  /** Whether the tryOpenData.ai watermark is enabled. */
+  watermark: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -843,6 +845,8 @@ export interface TableLayout {
   theme: ResolvedTheme;
   /** Resolved animation config. Present only when animation is enabled. */
   animation?: ResolvedAnimation;
+  /** Whether the tryOpenData.ai watermark is enabled. */
+  watermark: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -1020,6 +1024,8 @@ export interface SankeyLayout {
   dimensions: { width: number; height: number };
   /** Resolved animation config. Present only when animation is enabled. */
   animation?: ResolvedAnimation;
+  /** Whether the tryOpenData.ai watermark is enabled. */
+  watermark: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -1054,6 +1060,8 @@ export interface CompileOptions {
    * before calling compile. The engine always receives a resolved boolean.
    */
   darkMode?: boolean;
+  /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
   /**
    * Real text measurement function provided by the adapter.
    * Uses a hidden canvas or DOM element for accurate text dimensions.

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;
 }
 
 /**
@@ -804,6 +846,8 @@ export interface ChartSpec {
   theme?: ThemeConfig;
   /** Dark mode behavior. Defaults to "off". */
   darkMode?: DarkMode;
+  /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
   /** Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed. */
   hiddenSeries?: string[];
   /** Per-series visual overrides, keyed by series name (the color field value). */
@@ -844,6 +888,8 @@ export interface TableSpec {
   theme?: ThemeConfig;
   /** Dark mode behavior. */
   darkMode?: DarkMode;
+  /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
   /** Enable client-side search/filter. */
   search?: boolean;
   /** Pagination configuration. True for defaults, or an object with pageSize. */
@@ -911,6 +957,8 @@ export interface GraphSpec {
   theme?: ThemeConfig;
   /** Dark mode behavior. */
   darkMode?: DarkMode;
+  /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -964,6 +1012,8 @@ export interface LayerSpec {
   theme?: ThemeConfig;
   /** Dark mode behavior. Defaults to "off". */
   darkMode?: DarkMode;
+  /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
   /** Resolution strategy for shared scales/axes/legends. */
   resolve?: ResolveConfig;
   /** Hidden series names. */
@@ -1030,6 +1080,8 @@ export interface SankeySpec {
   theme?: ThemeConfig;
   /** Dark mode behavior. Defaults to "off". */
   darkMode?: DarkMode;
+  /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
   /** Animation configuration for entrance animations. */
   animation?: AnimationSpec;
   /**
@@ -1188,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)