@opendata-ai/openchart-core 6.10.0 → 6.12.0

package/package.json

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

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/__tests__/gradient.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import type { GradientDef } from '../spec';
+import { getRepresentativeColor, isGradientDef } from '../spec';
+
+describe('isGradientDef', () => {
+  it('returns true for a valid linear gradient', () => {
+    expect(
+      isGradientDef({
+        gradient: 'linear',
+        stops: [
+          { offset: 0, color: '#f00' },
+          { offset: 1, color: '#00f' },
+        ],
+      }),
+    ).toBe(true);
+  });
+
+  it('returns true for a valid radial gradient', () => {
+    expect(
+      isGradientDef({
+        gradient: 'radial',
+        stops: [{ offset: 0, color: '#f00' }],
+      }),
+    ).toBe(true);
+  });
+
+  it('returns false for a plain string', () => {
+    expect(isGradientDef('#ff0000')).toBe(false);
+  });
+
+  it('returns false for null', () => {
+    expect(isGradientDef(null)).toBe(false);
+  });
+
+  it('returns false for undefined', () => {
+    expect(isGradientDef(undefined)).toBe(false);
+  });
+
+  it('returns false for an object without gradient property', () => {
+    expect(isGradientDef({ stops: [] })).toBe(false);
+  });
+
+  it('returns false for an object without stops', () => {
+    expect(isGradientDef({ gradient: 'linear' })).toBe(false);
+  });
+
+  it('returns false for an object with invalid gradient type', () => {
+    expect(isGradientDef({ gradient: 'mesh', stops: [] })).toBe(false);
+  });
+});
+
+describe('getRepresentativeColor', () => {
+  it('returns the string directly when given a string', () => {
+    expect(getRepresentativeColor('#1b7fa3')).toBe('#1b7fa3');
+  });
+
+  it('returns the last stop color for a linear gradient', () => {
+    const grad: GradientDef = {
+      gradient: 'linear',
+      stops: [
+        { offset: 0, color: '#f00' },
+        { offset: 0.5, color: '#0f0' },
+        { offset: 1, color: '#00f' },
+      ],
+    };
+    expect(getRepresentativeColor(grad)).toBe('#00f');
+  });
+
+  it('returns the last stop color for a radial gradient', () => {
+    const grad: GradientDef = {
+      gradient: 'radial',
+      stops: [
+        { offset: 0, color: '#fff' },
+        { offset: 1, color: '#000' },
+      ],
+    };
+    expect(getRepresentativeColor(grad)).toBe('#000');
+  });
+
+  it('returns #000000 for a gradient with empty stops array', () => {
+    const grad: GradientDef = {
+      gradient: 'linear',
+      stops: [],
+    };
+    expect(getRepresentativeColor(grad)).toBe('#000000');
+  });
+
+  it('returns the single stop color for a gradient with one stop', () => {
+    const grad: GradientDef = {
+      gradient: 'radial',
+      stops: [{ offset: 0, color: '#abc' }],
+    };
+    expect(getRepresentativeColor(grad)).toBe('#abc');
+  });
+});

package/src/types/index.ts

@@ -114,6 +114,8 @@ export type {
   FieldType,
   FilterPredicate,
   FilterTransform,
+  GradientDef,
+  GradientStop,
   GraphEdge,
   GraphEncoding,
   GraphEncodingChannel,
@@ -125,12 +127,14 @@ export type {
   LabelDensity,
   LayerSpec,
   LegendConfig,
+  LinearGradient,
   LogicalAnd,
   LogicalNot,
   LogicalOr,
   MarkDef,
   MarkType,
   NodeOverride,
+  RadialGradient,
   RangeAnnotation,
   RefLineAnnotation,
   ResolveConfig,
@@ -155,9 +159,11 @@ export type {
 } from './spec';
 export {
   CHART_TYPES,
+  getRepresentativeColor,
   isChartSpec,
   isConditionalDef,
   isEncodingChannel,
+  isGradientDef,
   isGraphSpec,
   isLayerSpec,
   isRangeAnnotation,

package/src/types/layout.ts

@@ -9,6 +9,7 @@
  * fully resolved with computed positions, colors, and dimensions.
  */
 
+import type { GradientDef } from './spec';
 import type { ResolvedTheme } from './theme';
 
 // ---------------------------------------------------------------------------
@@ -235,8 +236,8 @@ export interface AreaMark {
   path: string;
   /** SVG path string for just the top boundary (for stroking the data line only). */
   topPath: string;
-  /** Fill color. */
-  fill: string;
+  /** Fill color or gradient. */
+  fill: string | GradientDef;
   /** Fill opacity. */
   fillOpacity: number;
   /** Optional stroke for the top boundary. */
@@ -277,8 +278,8 @@ export interface RectMark {
   width: number;
   /** Height. */
   height: number;
-  /** Fill color. */
-  fill: string;
+  /** Fill color or gradient. */
+  fill: string | GradientDef;
   /** Stroke color. */
   stroke?: string;
   /** Stroke width. */
@@ -321,8 +322,8 @@ export interface ArcMark {
   startAngle: number;
   /** End angle in radians. */
   endAngle: number;
-  /** Fill color. */
-  fill: string;
+  /** Fill color or gradient. */
+  fill: string | GradientDef;
   /** Stroke color (usually white for slice separation). */
   stroke: string;
   /** Stroke width. */
@@ -349,8 +350,8 @@ export interface PointMark {
   cy: number;
   /** Radius in pixels. */
   r: number;
-  /** Fill color. */
-  fill: string;
+  /** Fill color or gradient. */
+  fill: string | GradientDef;
   /** Stroke color. */
   stroke: string;
   /** Stroke width. */
@@ -666,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -842,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -1019,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -1053,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

@@ -48,6 +48,87 @@ export type MarkType =
 /** @deprecated Use MarkType instead. Kept for internal migration references. */
 export type ChartType = MarkType;
 
+// ---------------------------------------------------------------------------
+// Gradient definitions (Vega-aligned)
+// ---------------------------------------------------------------------------
+
+/** A single color stop in a gradient definition. */
+export interface GradientStop {
+  /** Position along the gradient, 0 to 1. */
+  offset: number;
+  /** CSS color string at this stop. */
+  color: string;
+  /** Opacity at this stop, 0 to 1. Maps to SVG stop-opacity. */
+  opacity?: number;
+}
+
+/**
+ * Linear gradient definition.
+ * Coordinates are in [0,1] normalized space relative to the mark's bounding box
+ * (maps to SVG gradientUnits="objectBoundingBox").
+ */
+export interface LinearGradient {
+  gradient: 'linear';
+  /** Color stops from start to end. */
+  stops: GradientStop[];
+  /** Start x coordinate (0-1). Default: 0. */
+  x1?: number;
+  /** Start y coordinate (0-1). Default: 0. */
+  y1?: number;
+  /** End x coordinate (0-1). Default: 0. */
+  x2?: number;
+  /** End y coordinate (0-1). Default: 1 (top-to-bottom). */
+  y2?: number;
+}
+
+/**
+ * Radial gradient definition.
+ * Coordinates are in [0,1] normalized space relative to the mark's bounding box.
+ */
+export interface RadialGradient {
+  gradient: 'radial';
+  /** Color stops from inner to outer. */
+  stops: GradientStop[];
+  /** Inner circle center x (0-1). Default: 0.5. */
+  x1?: number;
+  /** Inner circle center y (0-1). Default: 0.5. */
+  y1?: number;
+  /** Inner circle radius (0-1). Default: 0. */
+  r1?: number;
+  /** Outer circle center x (0-1). Default: 0.5. */
+  x2?: number;
+  /** Outer circle center y (0-1). Default: 0.5. */
+  y2?: number;
+  /** Outer circle radius (0-1). Default: 0.5. */
+  r2?: number;
+}
+
+/** A gradient definition, either linear or radial. */
+export type GradientDef = LinearGradient | RadialGradient;
+
+/** Type guard: check if a value is a GradientDef object. */
+export function isGradientDef(value: unknown): value is GradientDef {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'gradient' in value &&
+    'stops' in value &&
+    ((value as GradientDef).gradient === 'linear' || (value as GradientDef).gradient === 'radial')
+  );
+}
+
+/**
+ * Extract a single representative color from a fill value.
+ * Returns the fill directly if it's a string, or the last stop color
+ * if it's a gradient. Used by tooltips, labels, legends, and voronoi
+ * overlays that need a flat color.
+ */
+export function getRepresentativeColor(fill: string | GradientDef): string {
+  if (typeof fill === 'string') return fill;
+  const stops = fill.stops;
+  return stops.length > 0 ? stops[stops.length - 1].color : '#000000';
+}
+
 // ---------------------------------------------------------------------------
 // Mark definition (Vega-Lite aligned)
 // ---------------------------------------------------------------------------
@@ -94,8 +175,8 @@ export interface MarkDef {
   filled?: boolean;
   /** Default opacity (0-1). */
   opacity?: number;
-  /** Default fill color. */
-  fill?: string;
+  /** Default fill color or gradient. */
+  fill?: string | GradientDef;
   /** Default stroke color. */
   stroke?: string;
   /** Default stroke width. */
@@ -723,6 +804,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). */
@@ -763,6 +846,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. */
@@ -830,6 +915,8 @@ export interface GraphSpec {
   theme?: ThemeConfig;
   /** Dark mode behavior. */
   darkMode?: DarkMode;
+  /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -883,6 +970,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. */
@@ -949,6 +1038,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;
   /**