@opendata-ai/openchart-core 6.25.4 → 6.27.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. */
@@ -805,6 +807,17 @@ export interface AnimationConfig {
  */
 export type AnimationSpec = boolean | AnimationConfig;
 
+/**
+ * Chart display mode.
+ * - `'full'` (default): standard chart with chrome, axes, legend, padding.
+ * - `'sparkline'`: minimal inline mini-chart. Strips chrome, axes, legend,
+ *   watermark, animation, and reduces margins to a tiny safety pad. The mark
+ *   fills the container edge-to-edge. Best with `mark: 'line' | 'area' | 'bar'`.
+ *   Explicit user fields (chrome, legend, encoding.x.axis, etc.) still render
+ *   when set, so users can opt in to specific elements.
+ */
+export type Display = 'full' | 'sparkline';
+
 /**
  * Breakpoint-conditional overrides for chart specs.
  *
@@ -823,6 +836,12 @@ export interface ChartSpecOverride {
   annotations?: Annotation[];
   /** Override animation at this breakpoint. */
   animation?: AnimationSpec;
+  /** Override display mode (`'full'` or `'sparkline'`) at this breakpoint. */
+  display?: Display;
+  /** Override watermark visibility at this breakpoint. */
+  watermark?: boolean;
+  /** Override crosshair behavior at this breakpoint. */
+  crosshair?: boolean;
 }
 
 /**
@@ -878,6 +897,28 @@ 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. In sparkline display mode, defaults to false unless
+   * explicitly set.
+   */
+  crosshair?: boolean;
+  /**
+   * Display mode controlling how much chart chrome is rendered.
+   *
+   * - `'full'` (default): full publication chart with chrome, axes, legend, padding.
+   * - `'sparkline'`: inline mini-chart for dashboards/KPI cards. Strips chrome,
+   *   axes, legend, watermark, animation, and crosshair. The mark fills the
+   *   container edge-to-edge with a small safety margin. Best with
+   *   `mark: 'line' | 'area' | 'bar' | 'point'`.
+   *
+   * **Override precedence:** explicit user fields always win, even in sparkline
+   * mode. Setting `chrome.title` on a sparkline still renders the title.
+   * Setting `legend: { show: true }` still renders the legend. This applies at
+   * top-level and per-breakpoint overrides.
+   */
+  display?: Display;
   /**
    * Render order within a LayerSpec. Higher values render on top.
    * When omitted, layers render in array order (later layers paint on top).
@@ -1120,6 +1161,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.
  *
@@ -1128,8 +1221,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'>;
@@ -1139,12 +1233,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)
@@ -1165,6 +1262,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. */
@@ -1172,15 +1276,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). */
@@ -1286,6 +1390,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
@@ -1293,7 +1424,8 @@ export type Transform =
   | CalculateTransform
   | TimeUnitTransform
   | AggregateTransform
-  | FoldTransform;
+  | FoldTransform
+  | WindowTransform;
 
 // ---------------------------------------------------------------------------
 // Conditional encoding (Vega-Lite aligned)
@@ -1412,6 +1544,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
 // ---------------------------------------------------------------------------