@opendata-ai/openchart-engine 6.11.0 → 6.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.11.0",
+  "version": "6.12.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.11.0",
+    "@opendata-ai/openchart-core": "6.12.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__test-fixtures__/specs.ts

@@ -73,6 +73,7 @@ export function makeLineSpec(): NormalizedChartSpec {
     labels: { density: 'auto', format: '', prefix: '' },
     hiddenSeries: [],
     seriesStyles: {},
+    watermark: true,
   };
 }
 
@@ -102,6 +103,7 @@ export function makeBarSpec(): NormalizedChartSpec {
     labels: { density: 'auto', format: '', prefix: '' },
     hiddenSeries: [],
     seriesStyles: {},
+    watermark: true,
   };
 }
 
@@ -133,5 +135,6 @@ export function makeScatterSpec(): NormalizedChartSpec {
     labels: { density: 'auto', format: '', prefix: '' },
     hiddenSeries: [],
     seriesStyles: {},
+    watermark: true,
   };
 }

package/src/compile.ts

@@ -222,6 +222,10 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
 
   let chartSpec = normalized as NormalizedChartSpec;
 
+  // Resolve watermark: explicit spec value wins, then options fallback, then default true.
+  const rawWatermark = (spec as Record<string, unknown>).watermark;
+  const watermark = rawWatermark !== undefined ? chartSpec.watermark : (options.watermark ?? true);
+
   // Run data transforms (filter, bin, calculate, timeUnit) before any other data processing.
   // Transforms are defined on the original spec, not the normalized spec, since
   // NormalizedChartSpec doesn't carry the transform field.
@@ -306,10 +310,10 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     width: options.width,
     height: options.height,
   };
-  const legendLayout = computeLegend(chartSpec, strategy, theme, preliminaryArea);
+  const legendLayout = computeLegend(chartSpec, strategy, theme, preliminaryArea, watermark);
 
   // Compute dimensions (accounts for chrome + legend + responsive strategy)
-  const dims = computeDimensions(chartSpec, options, legendLayout, theme, strategy);
+  const dims = computeDimensions(chartSpec, options, legendLayout, theme, strategy, watermark);
   const chartArea = dims.chartArea;
 
   // Recompute legend bounds relative to actual chart area.
@@ -332,7 +336,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
         break;
     }
   }
-  const finalLegend = computeLegend(chartSpec, strategy, theme, legendArea);
+  const finalLegend = computeLegend(chartSpec, strategy, theme, legendArea, watermark);
 
   // Apply data filtering after legend (so legend retains all series), but before
   // scale computation (so hidden/clipped data doesn't affect domains or marks).
@@ -444,14 +448,16 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Add brand watermark as an obstacle so annotations avoid overlapping it.
   // The brand is right-aligned on the same baseline as the first bottom chrome element,
   // offset below the chart area by x-axis extent (tick labels + axis title).
-  const brandPadding = theme.spacing.padding;
-  const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
-  const xAxisExtent = axes.x?.label ? 48 : axes.x ? 26 : 0;
-  const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
-  const brandY = firstBottomChrome
-    ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
-    : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
-  obstacles.push({ x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: 30 });
+  if (watermark) {
+    const brandPadding = theme.spacing.padding;
+    const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
+    const xAxisExtent = axes.x?.label ? 48 : axes.x ? 26 : 0;
+    const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
+    const brandY = firstBottomChrome
+      ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
+      : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
+    obstacles.push({ x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: 30 });
+  }
   const annotations: ResolvedAnnotation[] = computeAnnotations(
     chartSpec,
     scales,
@@ -547,6 +553,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       height: options.height,
     },
     animation: resolvedAnimation,
+    watermark,
   };
 }
 
@@ -656,6 +663,7 @@ function buildPrimarySpec(leaves: ChartSpec[], layerSpec: LayerSpec): ChartSpec
     responsive: layerSpec.responsive ?? leaves[0].responsive,
     theme: layerSpec.theme ?? leaves[0].theme,
     darkMode: layerSpec.darkMode ?? leaves[0].darkMode,
+    watermark: layerSpec.watermark ?? leaves[0].watermark,
     hiddenSeries: layerSpec.hiddenSeries ?? leaves[0].hiddenSeries,
   };
 
@@ -697,7 +705,11 @@ export function compileTable(spec: unknown, options: CompileTableOptions): Table
     theme = adaptTheme(theme);
   }
 
-  return compileTableLayout(tableSpec, options, theme);
+  // Resolve watermark: spec-level wins, then options, then default true
+  const rawWatermark = (spec as Record<string, unknown>).watermark;
+  const watermark = rawWatermark !== undefined ? tableSpec.watermark : (options.watermark ?? true);
+
+  return compileTableLayout({ ...tableSpec, watermark }, options, theme);
 }
 
 // ---------------------------------------------------------------------------

package/src/compiler/__tests__/normalize.test.ts

@@ -1,12 +1,15 @@
 import type {
   ChartSpec,
   GraphSpec,
+  LayerSpec,
   RangeAnnotation,
   RefLineAnnotation,
+  SankeySpec,
   TableSpec,
   TextAnnotation,
 } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
+import type { NormalizedSankeySpec } from '../../sankey/types';
 import { normalizeSpec } from '../normalize';
 import type { NormalizedChartSpec, NormalizedGraphSpec, NormalizedTableSpec } from '../types';
 
@@ -52,6 +55,17 @@ describe('normalizeSpec', () => {
       });
     });
 
+    it('watermark defaults to true when not specified', () => {
+      const result = normalizeSpec(lineSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: ChartSpec = { ...lineSpec, watermark: false };
+      const result = normalizeSpec(spec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(false);
+    });
+
     it('preserves explicit values', () => {
       const spec: ChartSpec = {
         ...lineSpec,
@@ -205,6 +219,27 @@ describe('normalizeSpec', () => {
       expect(result.responsive).toBe(true);
       expect(result.darkMode).toBe('off');
     });
+
+    it('watermark defaults to true when not specified', () => {
+      const spec: TableSpec = {
+        type: 'table',
+        data: [{ name: 'Alice', age: 30 }],
+        columns: [{ key: 'name' }, { key: 'age' }],
+      };
+      const result = normalizeSpec(spec) as NormalizedTableSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: TableSpec = {
+        type: 'table',
+        data: [{ name: 'Alice', age: 30 }],
+        columns: [{ key: 'name' }, { key: 'age' }],
+        watermark: false,
+      };
+      const result = normalizeSpec(spec) as NormalizedTableSpec;
+      expect(result.watermark).toBe(false);
+    });
   });
 
   describe('graph spec normalization', () => {
@@ -221,5 +256,80 @@ describe('normalizeSpec', () => {
       expect(result.annotations).toEqual([]);
       expect(result.darkMode).toBe('off');
     });
+
+    it('watermark defaults to true when not specified', () => {
+      const spec: GraphSpec = {
+        type: 'graph',
+        nodes: [{ id: 'a' }, { id: 'b' }],
+        edges: [{ source: 'a', target: 'b' }],
+      };
+      const result = normalizeSpec(spec) as NormalizedGraphSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: GraphSpec = {
+        type: 'graph',
+        nodes: [{ id: 'a' }, { id: 'b' }],
+        edges: [{ source: 'a', target: 'b' }],
+        watermark: false,
+      };
+      const result = normalizeSpec(spec) as NormalizedGraphSpec;
+      expect(result.watermark).toBe(false);
+    });
+  });
+
+  describe('sankey spec normalization', () => {
+    const baseSankeySpec: SankeySpec = {
+      type: 'sankey',
+      data: [{ source: 'A', target: 'B', value: 10 }],
+      encoding: {
+        source: { field: 'source' },
+        target: { field: 'target' },
+        value: { field: 'value' },
+      },
+    };
+
+    it('watermark defaults to true when not specified', () => {
+      const result = normalizeSpec(baseSankeySpec) as NormalizedSankeySpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: SankeySpec = { ...baseSankeySpec, watermark: false };
+      const result = normalizeSpec(spec) as NormalizedSankeySpec;
+      expect(result.watermark).toBe(false);
+    });
+  });
+
+  describe('layer spec normalization', () => {
+    const baseLeaf: ChartSpec = {
+      mark: 'line',
+      data: [{ x: 1, y: 2 }],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' },
+        y: { field: 'y', type: 'quantitative' },
+      },
+    };
+
+    it('watermark defaults to true for layer leaves', () => {
+      const layerSpec: LayerSpec = { layer: [baseLeaf] };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('layer-level watermark: false propagates to leaves', () => {
+      const layerSpec: LayerSpec = { layer: [baseLeaf], watermark: false };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(false);
+    });
+
+    it('leaf-level watermark overrides layer-level', () => {
+      const leaf: ChartSpec = { ...baseLeaf, watermark: true };
+      const layerSpec: LayerSpec = { layer: [leaf], watermark: false };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      // Leaf explicitly sets true, which should be preserved
+      expect(result.watermark).toBe(true);
+    });
   });
 });

package/src/compiler/normalize.ts

@@ -215,6 +215,7 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     darkMode: spec.darkMode ?? 'off',
     hiddenSeries: spec.hiddenSeries ?? [],
     seriesStyles: spec.seriesStyles ?? {},
+    watermark: spec.watermark ?? true,
   };
 }
 
@@ -233,6 +234,7 @@ function normalizeTableSpec(spec: TableSpec, _warnings: string[]): NormalizedTab
     compact: spec.compact ?? false,
     responsive: spec.responsive ?? true,
     animation: spec.animation,
+    watermark: spec.watermark ?? true,
   };
 }
 
@@ -254,6 +256,7 @@ function normalizeSankeySpec(spec: SankeySpec, _warnings: string[]): NormalizedS
     animation: spec.animation,
     valueFormat: spec.valueFormat,
     linkOpacity: spec.linkOpacity,
+    watermark: spec.watermark ?? true,
   };
 }
 
@@ -282,6 +285,7 @@ function normalizeGraphSpec(spec: GraphSpec, _warnings: string[]): NormalizedGra
     annotations: normalizeAnnotations(spec.annotations),
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? 'off',
+    watermark: spec.watermark ?? true,
   };
 }
 
@@ -338,6 +342,7 @@ export function flattenLayers(
   parentData?: DataRow[],
   parentEncoding?: Encoding,
   parentTransforms?: import('@opendata-ai/openchart-core').Transform[],
+  parentWatermark?: boolean,
 ): ChartSpec[] {
   const resolvedData = spec.data ?? parentData;
   const resolvedEncoding: Encoding | undefined =
@@ -345,13 +350,23 @@ export function flattenLayers(
       ? { ...parentEncoding, ...spec.encoding }
       : (spec.encoding ?? parentEncoding);
   const resolvedTransforms = [...(parentTransforms ?? []), ...(spec.transform ?? [])];
+  // Layer-level watermark propagates to children (child can still override)
+  const resolvedWatermark = spec.watermark ?? parentWatermark;
 
   const leaves: ChartSpec[] = [];
 
   for (const child of spec.layer) {
     if (isLayerSpec(child)) {
       // Nested layer: recurse with merged context
-      leaves.push(...flattenLayers(child, resolvedData, resolvedEncoding, resolvedTransforms));
+      leaves.push(
+        ...flattenLayers(
+          child,
+          resolvedData,
+          resolvedEncoding,
+          resolvedTransforms,
+          resolvedWatermark,
+        ),
+      );
     } else {
       // Leaf ChartSpec: merge inherited properties
       const mergedData = child.data ?? resolvedData ?? [];
@@ -365,6 +380,10 @@ export function flattenLayers(
         data: mergedData,
         encoding: mergedEncoding,
         transform: mergedTransforms.length > 0 ? mergedTransforms : undefined,
+        // Inherit parent watermark if child doesn't explicitly set one
+        ...(child.watermark === undefined && resolvedWatermark !== undefined
+          ? { watermark: resolvedWatermark }
+          : {}),
       });
     }
   }

package/src/compiler/types.ts

@@ -78,6 +78,8 @@ export interface NormalizedChartSpec {
   responsive: boolean;
   theme: ThemeConfig;
   darkMode: DarkMode;
+  /** Whether the tryOpenData.ai watermark is enabled. */
+  watermark: boolean;
   /** Series names to hide from rendering. */
   hiddenSeries: string[];
   /** Per-series visual style overrides. */
@@ -93,6 +95,7 @@ export interface NormalizedTableSpec {
   chrome: NormalizedChrome;
   theme: ThemeConfig;
   darkMode: DarkMode;
+  watermark: boolean;
   search: boolean;
   pagination: boolean | { pageSize: number };
   stickyFirstColumn: boolean;
@@ -113,6 +116,7 @@ export interface NormalizedGraphSpec {
   annotations: Annotation[];
   theme: ThemeConfig;
   darkMode: DarkMode;
+  watermark: boolean;
 }
 
 /** Discriminated union of all normalized spec types. */

package/src/graphs/compile-graph.ts

@@ -194,6 +194,10 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
 
   const graphSpec = normalized as NormalizedGraphSpec;
 
+  // Resolve watermark: explicit spec value wins, then options fallback, then default true.
+  const rawWatermark = (spec as Record<string, unknown>).watermark;
+  const watermark = rawWatermark !== undefined ? graphSpec.watermark : (options.watermark ?? true);
+
   // 2. Resolve theme
   const mergedThemeConfig = options.theme
     ? { ...graphSpec.theme, ...options.theme }
@@ -288,6 +292,9 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
     theme,
     options.width,
     options.measureText,
+    'full',
+    undefined,
+    watermark,
   );
 
   // 12. Return compilation
@@ -304,6 +311,7 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
       height: options.height,
     },
     simulationConfig,
+    watermark,
   };
 }
 

package/src/graphs/types.ts

@@ -101,4 +101,6 @@ export interface GraphCompilation {
   dimensions: { width: number; height: number };
   /** Force simulation configuration. */
   simulationConfig: SimulationConfig;
+  /** Whether to show the brand watermark. */
+  watermark: boolean;
 }

package/src/layout/dimensions.ts

@@ -96,6 +96,7 @@ export function computeDimensions(
   legendLayout: LegendLayout,
   theme: ResolvedTheme,
   strategy?: LayoutStrategy,
+  watermark: boolean = true,
 ): LayoutDimensions {
   const { width, height } = options;
 
@@ -111,6 +112,7 @@ export function computeDimensions(
     options.measureText,
     chromeMode,
     padding,
+    watermark,
   );
 
   // Start with the total rect
@@ -334,6 +336,7 @@ export function computeDimensions(
       options.measureText,
       fallbackMode as 'compact' | 'hidden',
       padding,
+      watermark,
     );
 
     // Recalculate top/bottom margins with stripped chrome

package/src/legend/compute.ts

@@ -150,6 +150,7 @@ export function computeLegend(
   strategy: LayoutStrategy,
   theme: ResolvedTheme,
   chartArea: Rect,
+  watermark: boolean = true,
 ): LegendLayout {
   // Legend explicitly hidden via show: false, or height strategy says no legend
   if (spec.legend?.show === false || strategy.legendMaxHeight === 0) {
@@ -259,7 +260,8 @@ export function computeLegend(
 
   // Top/bottom-positioned legend: horizontal flow with overflow protection.
   // Reserve space on the right so legend entries don't overlap the brand watermark.
-  const availableWidth = chartArea.width - LEGEND_PADDING * 2 - BRAND_RESERVE_WIDTH;
+  const availableWidth =
+    chartArea.width - LEGEND_PADDING * 2 - (watermark ? BRAND_RESERVE_WIDTH : 0);
 
   // Apply symbolLimit first if set (minimum 1), then fit remaining entries to available rows.
   if (spec.legend?.symbolLimit != null) {

package/src/sankey/compile-sankey.ts

@@ -211,6 +211,10 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
 
   const sankeySpec = normalized as NormalizedSankeySpec;
 
+  // Resolve watermark: explicit spec value wins, then options fallback, then default true.
+  const rawWatermark = (spec as Record<string, unknown>).watermark;
+  const watermark = rawWatermark !== undefined ? sankeySpec.watermark : (options.watermark ?? true);
+
   // 2. Resolve theme
   const mergedThemeConfig = options.theme
     ? { ...sankeySpec.theme, ...options.theme }
@@ -241,6 +245,9 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
     theme,
     options.width,
     options.measureText,
+    'full',
+    undefined,
+    watermark,
   );
 
   // 4. Compute drawing area (total space minus chrome)
@@ -254,7 +261,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
 
   // Guard against negative dimensions
   if (fullArea.width <= 0 || fullArea.height <= 0) {
-    return emptyLayout(fullArea, chrome, theme, options);
+    return emptyLayout(fullArea, chrome, theme, options, watermark);
   }
 
   // 5. Extract encoding fields
@@ -298,7 +305,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
   };
 
   if (area.height <= 0) {
-    return emptyLayout(area, chrome, theme, options);
+    return emptyLayout(area, chrome, theme, options, watermark);
   }
 
   // 6. Run d3-sankey layout (may re-run once if labels overflow)
@@ -473,6 +480,7 @@ export function compileSankey(spec: unknown, options: CompileOptions): SankeyLay
       height: options.height,
     },
     animation: resolvedAnimation,
+    watermark,
   };
 }
 
@@ -631,6 +639,7 @@ function emptyLayout(
   chrome: ReturnType<typeof computeChrome>,
   theme: ResolvedTheme,
   options: CompileOptions,
+  watermark: boolean,
 ): SankeyLayout {
   return {
     area,
@@ -664,5 +673,6 @@ function emptyLayout(
       width: options.width,
       height: options.height,
     },
+    watermark,
   };
 }

package/src/sankey/types.ts

@@ -33,6 +33,7 @@ export interface NormalizedSankeySpec {
   legend?: LegendConfig;
   theme: ThemeConfig;
   darkMode: DarkMode;
+  watermark: boolean;
   animation?: AnimationSpec;
   valueFormat?: string;
   linkOpacity?: number;

package/src/tables/compile-table.ts

@@ -382,6 +382,7 @@ export function compileTableLayout(
   });
 
   // 9. Compute chrome
+  const watermark = spec.watermark;
   const chrome = computeChrome(
     {
       title: spec.chrome.title,
@@ -393,6 +394,9 @@ export function compileTableLayout(
     theme,
     options.width,
     options.measureText,
+    'full',
+    undefined,
+    watermark,
   );
 
   // 10. Build a11y
@@ -418,5 +422,6 @@ export function compileTableLayout(
     },
     theme,
     animation: resolveAnimation(spec.animation),
+    watermark,
   };
 }