@opendata-ai/openchart-core 6.25.3 → 6.26.0

package/src/types/spec.ts

@@ -240,6 +240,8 @@ export interface AxisConfig {
   labelPadding?: number;
   /** Color override for axis tick labels and title. Useful in dual-axis charts to match axis color to its series. */
   labelColor?: string;
+  /** Secondary data field to display alongside each tick label. Renders in lighter weight/color. Only effective on categorical y-axis labels (horizontal bar charts). */
+  labelField?: string;
 }
 
 /** Scale configuration for an encoding channel. */
@@ -705,6 +707,9 @@ export interface LabelConfig {
   offsets?: Record<string, AnnotationOffset>;
 }
 
+/** Shorthand: `false` disables all labels, `true` uses defaults, or pass a full config object. */
+export type LabelSpec = boolean | LabelConfig;
+
 // ---------------------------------------------------------------------------
 // Legend configuration
 // ---------------------------------------------------------------------------
@@ -813,7 +818,7 @@ export interface ChartSpecOverride {
   /** Override editorial chrome at this breakpoint. */
   chrome?: Chrome;
   /** Override label configuration at this breakpoint. */
-  labels?: LabelConfig;
+  labels?: LabelSpec;
   /** Override legend configuration at this breakpoint. */
   legend?: LegendConfig;
   /** Override annotations at this breakpoint. */
@@ -846,8 +851,8 @@ export interface ChartSpec {
   chrome?: Chrome;
   /** Data annotations (text callouts, highlighted ranges, reference lines). */
   annotations?: Annotation[];
-  /** Label display configuration (density, format). */
-  labels?: LabelConfig;
+  /** Label display configuration. `false` disables all labels, `true` uses defaults. */
+  labels?: LabelSpec;
   /** Legend display configuration (position override). */
   legend?: LegendConfig;
   /** Whether the chart adapts to container width. Defaults to true. */
@@ -875,6 +880,12 @@ export interface ChartSpec {
    * - AnimationConfig: full control via enter/update/exit phases
    */
   animation?: AnimationSpec;
+  /**
+   * Show a vertical crosshair line that tracks the nearest data point on
+   * line and area charts. Only active when a voronoi overlay is present.
+   * Defaults to false.
+   */
+  crosshair?: boolean;
   /**
    * Render order within a LayerSpec. Higher values render on top.
    * When omitted, layers render in array order (later layers paint on top).
@@ -1019,8 +1030,8 @@ export interface LayerSpec {
   chrome?: Chrome;
   /** Annotations on the layered view. */
   annotations?: Annotation[];
-  /** Label display configuration. */
-  labels?: LabelConfig;
+  /** Label display configuration. `false` disables all labels, `true` uses defaults. */
+  labels?: LabelSpec;
   /** Legend display configuration. */
   legend?: LegendConfig;
   /** Whether the chart adapts to container width. Defaults to true. */
@@ -1117,6 +1128,58 @@ export interface SankeySpec {
   valueFormat?: string;
 }
 
+// ---------------------------------------------------------------------------
+// TileMap spec (US state tile grid map)
+// ---------------------------------------------------------------------------
+
+/** Encoding channels specific to tile map visualizations. */
+export interface TileMapEncoding {
+  /** State code field (required, nominal). Maps to US state abbreviations. */
+  state: EncodingChannel;
+  /** Value field (required, quantitative). Maps to the sequential color scale. */
+  value: EncodingChannel;
+  /** Tooltip encoding (optional). */
+  tooltip?: EncodingChannel | EncodingChannel[];
+}
+
+/** Sequential color palette names available for tile maps. */
+export type TileMapPalette = 'blue' | 'green' | 'orange' | 'purple';
+
+export interface TileMapSpec {
+  /** Discriminant: always "tilemap". */
+  type: 'tilemap';
+  /**
+   * Data for the tile map. Accepts either:
+   * - A record mapping state codes to numeric values: `{ "CA": 12000, "TX": 8500 }`
+   * - Tabular data rows with state and value fields (requires encoding)
+   */
+  data: Record<string, number | null> | DataRow[];
+  /**
+   * Encoding channels mapping data fields to visual properties.
+   * Required when data is DataRow[]. Auto-generated when data is a record map.
+   */
+  encoding?: TileMapEncoding;
+  /** Sequential color palette. Defaults to 'blue'. */
+  palette?: TileMapPalette;
+  /** Editorial chrome (title, subtitle, source, byline, footer). */
+  chrome?: Chrome;
+  /** Legend display configuration. */
+  legend?: LegendConfig;
+  /** Theme configuration overrides. */
+  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;
+  /**
+   * d3-format string applied to tile values, legend labels, and tooltips.
+   * Examples: ".1f" for one decimal, "$,.0f" for currency, "~s" for SI.
+   */
+  valueFormat?: string;
+}
+
 /**
  * Top-level visualization spec: union discriminated by structural shape.
  *
@@ -1125,8 +1188,9 @@ export interface SankeySpec {
  * - TableSpec: has `type: 'table'`
  * - GraphSpec: has `type: 'graph'`
  * - SankeySpec: has `type: 'sankey'`
+ * - TileMapSpec: has `type: 'tilemap'`
  */
-export type VizSpec = ChartSpec | LayerSpec | TableSpec | GraphSpec | SankeySpec;
+export type VizSpec = ChartSpec | LayerSpec | TableSpec | GraphSpec | SankeySpec | TileMapSpec;
 
 /** Chart spec without runtime data, for persistence/storage. */
 export type ChartSpecWithoutData = Omit<ChartSpec, 'data'>;
@@ -1136,12 +1200,15 @@ export type TableSpecWithoutData = Omit<TableSpec, 'data' | 'columns'>;
 export type GraphSpecWithoutData = Omit<GraphSpec, 'nodes' | 'edges'>;
 /** Sankey spec without runtime data, for persistence/storage. */
 export type SankeySpecWithoutData = Omit<SankeySpec, 'data'>;
+/** TileMap spec without runtime data, for persistence/storage. */
+export type TileMapSpecWithoutData = Omit<TileMapSpec, 'data'>;
 /** Union of data-stripped spec types for persistence/storage. */
 export type StoredVizSpec =
   | ChartSpecWithoutData
   | TableSpecWithoutData
   | GraphSpecWithoutData
-  | SankeySpecWithoutData;
+  | SankeySpecWithoutData
+  | TileMapSpecWithoutData;
 
 // ---------------------------------------------------------------------------
 // Transforms (Vega-Lite aligned)
@@ -1162,6 +1229,13 @@ export interface LogicalNot<T> {
   not: T;
 }
 
+/** A relative-time reference that resolves against the data extent. */
+export interface RelativeTimeRef {
+  anchor: 'max' | 'min';
+  offset: number;
+  unit: 'day' | 'week' | 'month' | 'quarter' | 'year';
+}
+
 /** A predicate that tests a field value against a condition. */
 export interface FieldPredicate {
   /** Data field to test. */
@@ -1169,15 +1243,15 @@ export interface FieldPredicate {
   /** Equals comparison. */
   equal?: unknown;
   /** Less than. */
-  lt?: number;
+  lt?: number | RelativeTimeRef;
   /** Less than or equal. */
-  lte?: number;
+  lte?: number | RelativeTimeRef;
   /** Greater than. */
-  gt?: number;
+  gt?: number | RelativeTimeRef;
   /** Greater than or equal. */
-  gte?: number;
+  gte?: number | RelativeTimeRef;
   /** Inclusive range [min, max]. */
-  range?: [number, number];
+  range?: [number | RelativeTimeRef, number | RelativeTimeRef];
   /** Value is one of these. */
   oneOf?: unknown[];
   /** Whether the value is valid (non-null, non-undefined, non-NaN). */
@@ -1283,6 +1357,33 @@ export interface FoldTransform {
   as?: [string, string];
 }
 
+/** Window operation types for computing values relative to other rows. */
+export type WindowOp = 'lag' | 'lead' | 'diff' | 'pct_change' | 'cumsum' | 'rank' | 'first_value';
+
+/** Sort field definition for window transforms. */
+export interface WindowSortField {
+  field: string;
+  order?: 'ascending' | 'descending';
+}
+
+/** Window field definition specifying which operation to compute. */
+export interface WindowFieldDef {
+  op: WindowOp;
+  field: string;
+  /** Row offset for lag/lead/diff/pct_change. Defaults to 1. */
+  offset?: number;
+  as: string;
+}
+
+/** Window transform: computes values relative to other rows in sort order within a partition. */
+export interface WindowTransform {
+  window: WindowFieldDef[];
+  /** Fields to sort by within each partition. */
+  sort: WindowSortField[];
+  /** Fields to partition (group) by. Each group is windowed independently. */
+  groupby?: string[];
+}
+
 /** Discriminated union of all transform types. */
 export type Transform =
   | FilterTransform
@@ -1290,7 +1391,8 @@ export type Transform =
   | CalculateTransform
   | TimeUnitTransform
   | AggregateTransform
-  | FoldTransform;
+  | FoldTransform
+  | WindowTransform;
 
 // ---------------------------------------------------------------------------
 // Conditional encoding (Vega-Lite aligned)
@@ -1409,6 +1511,11 @@ export function isSankeySpec(spec: VizSpec | Record<string, unknown>): spec is S
   return 'type' in spec && (spec as Record<string, unknown>).type === 'sankey';
 }
 
+/** Check if a spec is a TileMapSpec. */
+export function isTileMapSpec(spec: VizSpec | Record<string, unknown>): spec is TileMapSpec {
+  return 'type' in spec && (spec as Record<string, unknown>).type === 'tilemap';
+}
+
 // ---------------------------------------------------------------------------
 // Annotation type guards
 // ---------------------------------------------------------------------------