@opendata-ai/openchart-core 6.10.0 → 6.11.0

package/package.json

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

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. */

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. */