@opendata-ai/openchart-core 3.0.0 → 6.1.0

package/src/types/encoding.ts

@@ -1,12 +1,12 @@
 /**
- * Per-chart-type encoding validation rules.
+ * Per-mark-type encoding validation rules.
  *
- * Defines which encoding channels are required vs optional for each chart type.
+ * Defines which encoding channels are required vs optional for each mark type.
  * The engine compiler uses these rules to validate specs at runtime (TypeScript
  * catches compile-time errors; these catch runtime JSON from Claude or APIs).
  */
 
-import type { ChartType, FieldType } from './spec';
+import type { FieldType, MarkType } from './spec';
 
 // ---------------------------------------------------------------------------
 // Encoding rule types
@@ -24,13 +24,24 @@ export interface ChannelRule {
 export interface EncodingRule {
   x: ChannelRule;
   y: ChannelRule;
+  x2?: ChannelRule;
+  y2?: ChannelRule;
   color: ChannelRule;
   size: ChannelRule;
+  shape?: ChannelRule;
+  opacity?: ChannelRule;
+  strokeDash?: ChannelRule;
+  text?: ChannelRule;
+  tooltip?: ChannelRule;
+  href?: ChannelRule;
+  order?: ChannelRule;
+  theta?: ChannelRule;
+  radius?: ChannelRule;
   detail: ChannelRule;
 }
 
 // ---------------------------------------------------------------------------
-// Chart encoding rules
+// Mark encoding rules
 // ---------------------------------------------------------------------------
 
 /** Helper to create a required channel rule. */
@@ -44,78 +55,148 @@ function optional(...types: FieldType[]): ChannelRule {
 }
 
 /**
- * Encoding rules per chart type.
+ * Encoding rules per mark type.
  *
  * Defines which channels are required and what field types they accept.
  * The compiler uses this map to validate user specs at runtime.
  *
  * Key design decisions:
  * - line/area: x is temporal/ordinal (the axis), y is quantitative (the value)
- * - bar: horizontal bars, so y is the category axis, x is the value
- * - column: vertical columns, so x is the category axis, y is the value
- * - pie/donut: no x axis; y is the value (quantitative), color is the category
- * - dot: y is the category, x is quantitative
- * - scatter: both axes are quantitative
+ * - bar: covers both horizontal and vertical orientations, so both axes accept
+ *   all relevant types. The engine validates the combination later (one axis
+ *   must be quantitative).
+ * - arc: no x axis; y is the value (quantitative), color is the category
+ * - circle: y is the category, x is quantitative
+ * - point: both axes are quantitative
+ * - text/rule: fully optional positioning
+ * - tick/rect: both axes required, any type
  */
-export const CHART_ENCODING_RULES: Record<ChartType, EncodingRule> = {
+export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
+  bar: {
+    x: required('quantitative', 'nominal', 'ordinal', 'temporal'),
+    y: required('quantitative', 'nominal', 'ordinal'),
+    x2: optional('quantitative'),
+    y2: optional('quantitative'),
+    color: optional('nominal', 'ordinal', 'quantitative'),
+    size: optional(),
+    opacity: optional('quantitative'),
+    tooltip: optional(),
+    href: optional(),
+    order: optional('quantitative', 'ordinal'),
+    detail: optional('nominal'),
+  },
   line: {
     x: required('temporal', 'ordinal'),
     y: required('quantitative'),
-    color: optional('nominal', 'ordinal'),
-    size: optional('quantitative'),
+    color: optional('nominal', 'ordinal', 'quantitative'),
+    size: optional(),
+    opacity: optional('quantitative'),
+    strokeDash: optional('nominal', 'ordinal'),
+    tooltip: optional(),
+    href: optional(),
+    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
   area: {
     x: required('temporal', 'ordinal'),
     y: required('quantitative'),
-    color: optional('nominal', 'ordinal'),
-    size: optional('quantitative'),
+    y2: optional('quantitative'),
+    color: optional('nominal', 'ordinal', 'quantitative'),
+    size: optional(),
+    opacity: optional('quantitative'),
+    tooltip: optional(),
+    href: optional(),
+    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
-  bar: {
+  point: {
     x: required('quantitative'),
-    y: required('nominal', 'ordinal'),
+    y: required('quantitative'),
     color: optional('nominal', 'ordinal', 'quantitative'),
     size: optional('quantitative'),
+    shape: optional('nominal', 'ordinal'),
+    opacity: optional('quantitative'),
+    tooltip: optional(),
+    href: optional(),
+    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
-  column: {
-    x: required('nominal', 'ordinal', 'temporal'),
-    y: required('quantitative'),
+  circle: {
+    x: required('quantitative'),
+    y: required('nominal', 'ordinal'),
     color: optional('nominal', 'ordinal', 'quantitative'),
     size: optional('quantitative'),
+    opacity: optional('quantitative'),
+    tooltip: optional(),
+    href: optional(),
+    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
-  pie: {
+  arc: {
     x: optional(),
     y: required('quantitative'),
     color: required('nominal', 'ordinal'),
-    size: optional('quantitative'),
+    size: optional(),
+    opacity: optional('quantitative'),
+    tooltip: optional(),
+    href: optional(),
+    order: optional('quantitative', 'ordinal'),
+    theta: optional('quantitative'),
+    radius: optional('quantitative'),
     detail: optional('nominal'),
   },
-  donut: {
+  text: {
     x: optional(),
-    y: required('quantitative'),
-    color: required('nominal', 'ordinal'),
+    y: optional(),
+    color: optional(),
     size: optional('quantitative'),
+    opacity: optional('quantitative'),
+    text: required(),
+    tooltip: optional(),
+    href: optional(),
     detail: optional('nominal'),
   },
-  dot: {
-    x: required('quantitative'),
-    y: required('nominal', 'ordinal'),
-    color: optional('nominal', 'ordinal'),
-    size: optional('quantitative'),
+  rule: {
+    x: optional(),
+    y: optional(),
+    x2: optional(),
+    y2: optional(),
+    color: optional(),
+    size: optional(),
+    opacity: optional('quantitative'),
+    strokeDash: optional('nominal', 'ordinal'),
+    tooltip: optional(),
+    href: optional(),
     detail: optional('nominal'),
   },
-  scatter: {
-    x: required('quantitative'),
-    y: required('quantitative'),
-    color: optional('nominal', 'ordinal'),
-    size: optional('quantitative'),
+  tick: {
+    x: required(),
+    y: required(),
+    color: optional(),
+    size: optional(),
+    opacity: optional('quantitative'),
+    tooltip: optional(),
+    href: optional(),
+    detail: optional('nominal'),
+  },
+  rect: {
+    x: required(),
+    y: required(),
+    x2: optional(),
+    y2: optional(),
+    color: optional(),
+    size: optional(),
+    opacity: optional('quantitative'),
+    tooltip: optional(),
+    href: optional(),
+    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
 };
 
+/** @deprecated Use MARK_ENCODING_RULES instead. */
+export const CHART_ENCODING_RULES = MARK_ENCODING_RULES;
+
 // ---------------------------------------------------------------------------
 // Graph encoding rules
 // ---------------------------------------------------------------------------

package/src/types/index.ts

@@ -14,6 +14,7 @@ export type {
 export {
   CHART_ENCODING_RULES,
   GRAPH_ENCODING_RULES,
+  MARK_ENCODING_RULES,
 } from './encoding';
 // Event types (chart interaction callbacks)
 export type {
@@ -59,6 +60,7 @@ export type {
   ResolvedChromeElement,
   ResolvedColumn,
   ResolvedLabel,
+  RuleMarkLayout,
   SortState,
   SparklineData,
   SparklineTableCell,
@@ -66,8 +68,10 @@ export type {
   TableCellBase,
   TableLayout,
   TableRow,
+  TextMarkLayout,
   TextStyle,
   TextTableCell,
+  TickMarkLayout,
   TooltipContent,
   TooltipField,
 } from './layout';
@@ -78,6 +82,10 @@ export type {
   AnnotationAnchor,
   AnnotationOffset,
   AxisConfig,
+  BinParams,
+  BinTransform,
+  CalculateExpression,
+  CalculateTransform,
   ChartSpec,
   ChartSpecOverride,
   ChartSpecWithoutData,
@@ -85,11 +93,16 @@ export type {
   Chrome,
   ChromeText,
   ChromeTextStyle,
+  Condition,
+  ConditionalValueDef,
   DarkMode,
   DataRow,
   Encoding,
   EncodingChannel,
+  FieldPredicate,
   FieldType,
+  FilterPredicate,
+  FilterTransform,
   GraphEdge,
   GraphEncoding,
   GraphEncodingChannel,
@@ -99,27 +112,46 @@ export type {
   GraphSpecWithoutData,
   LabelConfig,
   LabelDensity,
+  LayerSpec,
   LegendConfig,
+  LogicalAnd,
+  LogicalNot,
+  LogicalOr,
+  MarkDef,
+  MarkType,
   NodeOverride,
   RangeAnnotation,
   RefLineAnnotation,
+  ResolveConfig,
+  ResolveMode,
   ScaleConfig,
+  ScaleType,
   SeriesStyle,
   StoredVizSpec,
   TableSpec,
   TableSpecWithoutData,
   TextAnnotation,
   ThemeConfig,
+  TimeUnit,
+  TimeUnitTransform,
+  Transform,
   VizSpec,
 } from './spec';
 export {
   CHART_TYPES,
   isChartSpec,
+  isConditionalDef,
+  isEncodingChannel,
   isGraphSpec,
+  isLayerSpec,
   isRangeAnnotation,
   isRefLineAnnotation,
   isTableSpec,
   isTextAnnotation,
+  MARK_DISPLAY_NAMES,
+  MARK_TYPES,
+  resolveMarkDef,
+  resolveMarkType,
 } from './spec';
 // Table types
 export type {

package/src/types/layout.ts

@@ -148,6 +148,22 @@ export interface AxisLayout {
   start: Point;
   /** Axis line end position. */
   end: Point;
+  /** Axis orientation (which side it appears on). */
+  orient?: 'top' | 'bottom' | 'left' | 'right';
+  /** Whether to show the axis domain line. Defaults to true. */
+  domainLine?: boolean;
+  /** Whether to show tick marks. Defaults to true. */
+  tickMarks?: boolean;
+  /** Axis position offset in pixels. */
+  offset?: number;
+  /** Padding between axis title and axis in pixels. */
+  titlePadding?: number;
+  /** Padding between tick labels and axis in pixels. */
+  labelPadding?: number;
+  /** How overlapping labels should be handled. */
+  labelOverlap?: boolean | 'parity' | 'greedy';
+  /** Whether to flush labels to the axis edges. */
+  labelFlush?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -187,6 +203,16 @@ export interface LineMark {
   seriesKey?: string;
   /** Original data rows for this series. */
   data: Record<string, unknown>[];
+  /**
+   * Pixel-coordinate data points for spatial tooltip lookup (voronoi overlay).
+   * Each entry pairs a pixel position with its original data row.
+   */
+  dataPoints?: Array<{
+    x: number;
+    y: number;
+    datum: Record<string, unknown>;
+    tooltip?: TooltipContent;
+  }>;
   /** Resolved label after collision detection. */
   label?: ResolvedLabel;
   /** Accessibility attributes. */
@@ -219,6 +245,16 @@ export interface AreaMark {
   seriesKey?: string;
   /** Original data rows. */
   data: Record<string, unknown>[];
+  /**
+   * Pixel-coordinate data points for spatial tooltip lookup (voronoi overlay).
+   * Each entry pairs a pixel position with its original data row.
+   */
+  dataPoints?: Array<{
+    x: number;
+    y: number;
+    datum: Record<string, unknown>;
+    tooltip?: TooltipContent;
+  }>;
   /** Accessibility attributes. */
   aria: MarkAria;
 }
@@ -315,8 +351,102 @@ export interface PointMark {
   aria: MarkAria;
 }
 
+/**
+ * Text mark: data-positioned text label.
+ * Used by text charts for showing values directly at data coordinates.
+ */
+export interface TextMarkLayout {
+  type: 'textMark';
+  /** X position. */
+  x: number;
+  /** Y position. */
+  y: number;
+  /** Text content to display. */
+  text: string;
+  /** Fill color. */
+  fill: string;
+  /** Font size in pixels. */
+  fontSize: number;
+  /** Font weight. */
+  fontWeight?: number;
+  /** Font family override. */
+  fontFamily?: string;
+  /** Horizontal text alignment. */
+  textAnchor: 'start' | 'middle' | 'end';
+  /** Rotation angle in degrees. */
+  angle?: number;
+  /** Original data row. */
+  data: Record<string, unknown>;
+  /** Resolved label. */
+  label?: ResolvedLabel;
+  /** Accessibility attributes. */
+  aria: MarkAria;
+}
+
+/**
+ * Rule mark: a line segment between two points.
+ * Used for reference lines rendered as data marks.
+ */
+export interface RuleMarkLayout {
+  type: 'rule';
+  /** Start x position. */
+  x1: number;
+  /** Start y position. */
+  y1: number;
+  /** End x position. */
+  x2: number;
+  /** End y position. */
+  y2: number;
+  /** Stroke color. */
+  stroke: string;
+  /** Stroke width in pixels. */
+  strokeWidth: number;
+  /** Stroke dash pattern (e.g. "4 2"). */
+  strokeDasharray?: string;
+  /** Opacity (0-1). */
+  opacity?: number;
+  /** Original data row. */
+  data: Record<string, unknown>;
+  /** Accessibility attributes. */
+  aria: MarkAria;
+}
+
+/**
+ * Tick mark: a short line segment at a data coordinate.
+ * Used for strip plots and rug plots.
+ */
+export interface TickMarkLayout {
+  type: 'tick';
+  /** X position. */
+  x: number;
+  /** Y position. */
+  y: number;
+  /** Length of the tick mark in pixels. */
+  length: number;
+  /** Whether the tick is horizontal or vertical. */
+  orient: 'horizontal' | 'vertical';
+  /** Stroke color. */
+  stroke: string;
+  /** Stroke width in pixels. */
+  strokeWidth: number;
+  /** Opacity (0-1). */
+  opacity?: number;
+  /** Original data row. */
+  data: Record<string, unknown>;
+  /** Accessibility attributes. */
+  aria: MarkAria;
+}
+
 /** Discriminated union of all mark types. */
-export type Mark = LineMark | AreaMark | RectMark | ArcMark | PointMark;
+export type Mark =
+  | LineMark
+  | AreaMark
+  | RectMark
+  | ArcMark
+  | PointMark
+  | TextMarkLayout
+  | RuleMarkLayout
+  | TickMarkLayout;
 
 // ---------------------------------------------------------------------------
 // Labels