@opendata-ai/openchart-core 8.0.0-rc.9 → 8.1.0

package/src/types/encoding.ts

@@ -1,280 +0,0 @@
-/**
- * Per-mark-type encoding validation rules.
- *
- * 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 { FieldType, MarkType } from './spec';
-
-// ---------------------------------------------------------------------------
-// Encoding rule types
-// ---------------------------------------------------------------------------
-
-/** Constraint on what field types are valid for an encoding channel. */
-export interface ChannelRule {
-  /** Whether this channel is required for the chart type. */
-  required: boolean;
-  /** Allowed field types. If empty, any field type is accepted. */
-  allowedTypes: FieldType[];
-}
-
-/** Encoding rules for a single chart type: which channels are required/optional. */
-export interface EncodingRule {
-  x: ChannelRule;
-  y: ChannelRule;
-  x2?: ChannelRule;
-  y2?: ChannelRule;
-  color: ChannelRule;
-  size: ChannelRule;
-  opacity?: ChannelRule;
-  strokeDash?: ChannelRule;
-  text?: ChannelRule;
-  tooltip?: ChannelRule;
-  theta?: ChannelRule;
-  detail: ChannelRule;
-}
-
-// ---------------------------------------------------------------------------
-// Mark encoding rules
-// ---------------------------------------------------------------------------
-
-/** Helper to create a required channel rule. */
-function required(...types: FieldType[]): ChannelRule {
-  return { required: true, allowedTypes: types };
-}
-
-/** Helper to create an optional channel rule. */
-function optional(...types: FieldType[]): ChannelRule {
-  return { required: false, allowedTypes: types };
-}
-
-/**
- * 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: 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
- * - beeswarm: both axes optional at the channel level; the compiler enforces
- *   the combination (exactly one quantitative value axis, the other axis an
- *   optional nominal/ordinal lane channel)
- * - waffle: no positional axes; y is the share value (quantitative, with
- *   theta accepted as an alias like arc), color is the category
- * - calendar: x is the daily date (temporal), color the per-day value
- *   (quantitative); no y channel (the calendar owns its own geometry)
- * - parliament: no positional axes; theta (aliased to y) is the seat count
- *   (quantitative), color the party
- */
-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(),
-    detail: optional('nominal'),
-  },
-  line: {
-    x: required('temporal', 'ordinal'),
-    y: required('quantitative'),
-    color: optional('nominal', 'ordinal', 'quantitative'),
-    size: optional(),
-    opacity: optional('quantitative'),
-    strokeDash: optional('nominal', 'ordinal'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  area: {
-    x: required('temporal', 'ordinal'),
-    y: required('quantitative'),
-    y2: optional('quantitative'),
-    color: optional('nominal', 'ordinal', 'quantitative'),
-    size: optional(),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  point: {
-    x: required('quantitative', 'temporal', 'nominal', 'ordinal'),
-    y: required('quantitative', 'temporal', 'nominal', 'ordinal'),
-    color: optional('nominal', 'ordinal', 'quantitative'),
-    size: optional('quantitative'),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  circle: {
-    x: required('quantitative'),
-    y: required('nominal', 'ordinal'),
-    color: optional('nominal', 'ordinal', 'quantitative'),
-    size: optional('quantitative'),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  lollipop: {
-    x: required('quantitative'),
-    y: required('nominal', 'ordinal'),
-    color: optional('nominal', 'ordinal', 'quantitative'),
-    size: optional('quantitative'),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  beeswarm: {
-    x: optional('quantitative', 'nominal', 'ordinal'),
-    y: optional('quantitative', 'nominal', 'ordinal'),
-    color: optional('nominal', 'ordinal', 'quantitative'),
-    size: optional('quantitative'),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  // Range: x+x2 with nominal y (horizontal) or y+y2 with nominal x (vertical).
-  // The orientation-dependent x2/y2 requirement is enforced by a dedicated
-  // check in the validator; the static table can only mark them optional.
-  range: {
-    x: required('quantitative', 'nominal', 'ordinal'),
-    y: required('quantitative', 'nominal', 'ordinal'),
-    x2: optional('quantitative'),
-    y2: optional('quantitative'),
-    color: optional('nominal', 'ordinal'),
-    size: optional(),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  arc: {
-    x: optional(),
-    y: optional('quantitative'),
-    theta: required('quantitative'),
-    color: required('nominal', 'ordinal'),
-    size: optional(),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  waffle: {
-    x: optional(),
-    y: required('quantitative'),
-    color: required('nominal', 'ordinal'),
-    size: optional(),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    theta: optional('quantitative'),
-    detail: optional('nominal'),
-  },
-  // parliament: hemicycle seat chart. Like arc/waffle, no positional axes;
-  // color is the party (required), theta the seat count (aliased to y in the
-  // sugar pass). y is accepted so the theta alias resolves before the rules
-  // check runs.
-  parliament: {
-    x: optional(),
-    y: required('quantitative'),
-    color: required('nominal', 'ordinal'),
-    size: optional(),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    theta: optional('quantitative'),
-    detail: optional('nominal'),
-  },
-  text: {
-    x: optional(),
-    y: optional(),
-    color: optional(),
-    size: optional('quantitative'),
-    opacity: optional('quantitative'),
-    text: required(),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  rule: {
-    x: optional(),
-    y: optional(),
-    x2: optional(),
-    y2: optional(),
-    color: optional(),
-    size: optional(),
-    opacity: optional('quantitative'),
-    strokeDash: optional('nominal', 'ordinal'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  tick: {
-    x: required(),
-    y: required(),
-    color: optional(),
-    size: optional(),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  rect: {
-    x: required(),
-    y: required(),
-    x2: optional(),
-    y2: optional(),
-    color: optional(),
-    size: optional(),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-  // calendar: x is the daily date (temporal), color the per-day value
-  // (quantitative). No y channel: the calendar computes its own
-  // weeks-x-weekdays geometry, so y is left optional here and the dedicated
-  // validator rejects it with a pointed message.
-  calendar: {
-    x: required('temporal'),
-    y: optional(),
-    color: required('quantitative'),
-    size: optional(),
-    opacity: optional('quantitative'),
-    tooltip: optional(),
-    detail: optional('nominal'),
-  },
-};
-
-/** @deprecated Use MARK_ENCODING_RULES instead. */
-export const CHART_ENCODING_RULES = MARK_ENCODING_RULES;
-
-// ---------------------------------------------------------------------------
-// Graph encoding rules
-// ---------------------------------------------------------------------------
-
-/** Encoding rule for a single graph visual channel. */
-export interface GraphChannelRule {
-  /** Whether this channel is required. */
-  required: boolean;
-  /** Allowed field types. Empty means any type. */
-  allowedTypes: FieldType[];
-}
-
-/**
- * Encoding rules for graph visualizations.
- *
- * All graph encoding channels are optional since a graph can be rendered
- * with just nodes and edges (uniform appearance). Encoding channels add
- * visual differentiation based on data fields.
- */
-export const GRAPH_ENCODING_RULES: Record<string, GraphChannelRule> = {
-  nodeColor: { required: false, allowedTypes: ['nominal', 'ordinal'] },
-  nodeSize: { required: false, allowedTypes: ['quantitative'] },
-  edgeColor: { required: false, allowedTypes: ['nominal', 'ordinal'] },
-  edgeWidth: { required: false, allowedTypes: ['quantitative'] },
-  nodeLabel: { required: false, allowedTypes: [] },
-};

package/src/types/events.ts

@@ -1,236 +0,0 @@
-/**
- * Chart interaction event types.
- *
- * These types define the callback signatures for user interactions with
- * chart elements: clicking marks, hovering, legend toggles, and annotation clicks.
- *
- * Event handlers are optional and passed through MountOptions (vanilla) or
- * ChartProps (React). The vanilla adapter wires DOM event listeners to
- * mark elements and constructs these typed events from the raw browser events.
- */
-
-import type {
-  Annotation,
-  AnnotationOffset,
-  DataRow,
-  RangeAnnotation,
-  RefLineAnnotation,
-  TextAnnotation,
-} from './spec';
-
-// ---------------------------------------------------------------------------
-// Chrome key identifiers
-// ---------------------------------------------------------------------------
-
-/** Identifies a specific chrome text element (title, subtitle, source, byline, footer). */
-export type ChromeKey = 'title' | 'subtitle' | 'source' | 'byline' | 'footer';
-
-// ---------------------------------------------------------------------------
-// Element references (identity for selection/edit callbacks)
-// ---------------------------------------------------------------------------
-
-/**
- * Reference to an editable chart element.
- * Carries enough info to find the element in both the spec and the DOM.
- * The `annotation` variant uses two-tier identity: `id` (when the consumer provides one)
- * and `index` (always available, position in the spec's annotations array).
- */
-export type ElementRef =
-  | {
-      type: 'annotation';
-      index: number;
-      id?: string;
-      /** RFC 6901 JSON Pointer to the edited property in the spec. */
-      path?: string;
-    }
-  | {
-      type: 'chrome';
-      key: ChromeKey;
-      /** RFC 6901 JSON Pointer to the edited property in the spec. */
-      path?: string;
-    }
-  | {
-      type: 'series-label';
-      series: string;
-      /** RFC 6901 JSON Pointer to the edited property in the spec. */
-      path?: string;
-    }
-  | {
-      type: 'legend';
-      /** RFC 6901 JSON Pointer to the edited property in the spec. */
-      path?: string;
-    }
-  | {
-      type: 'legend-entry';
-      series: string;
-      index: number;
-      /** RFC 6901 JSON Pointer to the edited property in the spec. */
-      path?: string;
-    };
-
-/** Helper constructors for ergonomic ElementRef creation. */
-export const elementRef = {
-  annotation: (index: number, id?: string, path?: string): ElementRef => ({
-    type: 'annotation',
-    index,
-    ...(id !== undefined ? { id } : {}),
-    ...(path !== undefined ? { path } : {}),
-  }),
-  chrome: (key: ChromeKey, path?: string): ElementRef => ({
-    type: 'chrome',
-    key,
-    ...(path !== undefined ? { path } : {}),
-  }),
-  seriesLabel: (series: string, path?: string): ElementRef => ({
-    type: 'series-label',
-    series,
-    ...(path !== undefined ? { path } : {}),
-  }),
-  legend: (path?: string): ElementRef => ({
-    type: 'legend',
-    ...(path !== undefined ? { path } : {}),
-  }),
-  legendEntry: (series: string, index: number, path?: string): ElementRef => ({
-    type: 'legend-entry',
-    series,
-    index,
-    ...(path !== undefined ? { path } : {}),
-  }),
-} as const;
-
-// ---------------------------------------------------------------------------
-// Element edit events
-// ---------------------------------------------------------------------------
-
-/**
- * Discriminated union of all element edit events.
- * Fired by the `onEdit` callback when any editable chart element is modified.
- * Covers repositioning (drag), deletion (Delete key), and text editing (double-click).
- * Selection events (onSelect/onDeselect) are separate callbacks, not part of this union.
- *
- * For the `annotation` variant:
- * - `annotation` is the ORIGINAL spec annotation (may have a stale or missing offset)
- * - `offset` is the NEW accumulated position after the drag completes
- * - To persist a drag edit back into your spec: `{ ...edit.annotation, offset: edit.offset }`
- */
-export type ElementEdit =
-  | {
-      type: 'annotation';
-      element: ElementRef;
-      annotation: TextAnnotation;
-      offset: AnnotationOffset;
-    }
-  | {
-      type: 'annotation-connector';
-      element: ElementRef;
-      annotation: TextAnnotation;
-      endpoint: 'from' | 'to';
-      offset: AnnotationOffset;
-    }
-  | {
-      type: 'range-label';
-      element: ElementRef;
-      annotation: RangeAnnotation;
-      labelOffset: AnnotationOffset;
-    }
-  | {
-      type: 'refline-label';
-      element: ElementRef;
-      annotation: RefLineAnnotation;
-      labelOffset: AnnotationOffset;
-    }
-  | {
-      type: 'annotation-anchor';
-      element: ElementRef;
-      annotation: TextAnnotation;
-      x: string | number;
-      y: string | number;
-    }
-  | { type: 'chrome'; key: ChromeKey; text: string; offset: AnnotationOffset }
-  | { type: 'series-label'; series: string; offset: AnnotationOffset }
-  | { type: 'legend'; offset: AnnotationOffset }
-  /**
-   * Transient legend visibility toggle. Reports the same runtime show/hide
-   * a reader triggers; not persisted by openchart. To author default-hidden
-   * series, set `spec.hiddenSeries` directly. Hosts building spec
-   * persistence should generally not write legend-toggle edits back into
-   * the authored spec. `hidden: true` means the series was just hidden.
-   */
-  | { type: 'legend-toggle'; series: string; hidden: boolean }
-  | { type: 'add'; annotation: TextAnnotation }
-  | { type: 'delete'; element: ElementRef }
-  | { type: 'text-edit'; element: ElementRef; oldText: string; newText: string };
-
-// ---------------------------------------------------------------------------
-// Mark events
-// ---------------------------------------------------------------------------
-
-/**
- * Event fired when a user interacts with a data mark (bar, point, line segment, etc.).
- *
- * Contains the underlying data row, the series it belongs to (if multi-series),
- * the position within the chart container, and the raw browser MouseEvent.
- */
-export interface MarkEvent {
-  /** The data row associated with the mark that was interacted with. */
-  datum: DataRow;
-  /** Series identifier, if the chart has multiple series (e.g. multi-line). */
-  series?: string;
-  /** Position of the interaction relative to the chart container. */
-  position: { x: number; y: number };
-  /** The raw browser MouseEvent. */
-  event: MouseEvent;
-}
-
-// ---------------------------------------------------------------------------
-// Chart event handler interface
-// ---------------------------------------------------------------------------
-
-/**
- * Event handler callbacks for chart interactions.
- *
- * All handlers are optional. Pass these through MountOptions (vanilla adapter)
- * or ChartProps (React component) to receive interaction callbacks.
- */
-export interface ChartEventHandlers {
-  /**
-   * Explicitly enable or disable edit interactions (drag, select, keyboard
-   * delete/edit). When true, the interaction layer is wired even without
-   * onEdit. When false, all edit interactions are suppressed even when
-   * onEdit is provided. When omitted, each interaction block uses its
-   * existing callback-presence gate.
-   */
-  editable?: boolean;
-  /** Called when a data mark is clicked. */
-  onMarkClick?: (event: MarkEvent) => void;
-  /** Called when the mouse enters a data mark. */
-  onMarkHover?: (event: MarkEvent) => void;
-  /** Called when the mouse leaves a data mark. */
-  onMarkLeave?: () => void;
-  /** Called when a legend entry is toggled (clicked to show/hide a series). */
-  onLegendToggle?: (series: string, visible: boolean) => void;
-  /**
-   * Called when the series search (`seriesSearch`) changes the highlight set.
-   * Receives the full set of highlighted values after the change, including
-   * the authored `encoding.color.highlight` baseline.
-   */
-  onHighlightChange?: (values: string[]) => void;
-  /** Called when an annotation element is clicked. */
-  onAnnotationClick?: (annotation: Annotation, event: MouseEvent) => void;
-  /** Called when a text annotation label is dragged to a new position. */
-  onAnnotationEdit?: (annotation: TextAnnotation, updatedOffset: AnnotationOffset) => void;
-  /** Unified edit callback. Fires for any spec-modifying edit (repositioning, deletion, text editing). */
-  onEdit?: (edit: ElementEdit) => void;
-  /** Fired when an element is selected via click or programmatic select(). */
-  onSelect?: (element: ElementRef) => void;
-  /** Fired when the current element is deselected (click empty, Escape, or new selection replaces old). */
-  onDeselect?: (element: ElementRef) => void;
-  /** Fired when inline text editing commits. Also flows through onEdit as a 'text-edit' event. */
-  onTextEdit?: (element: ElementRef, oldText: string, newText: string) => void;
-  /**
-   * Fired when a "you draw it" (`youDrawIt`) drawing is revealed (button click
-   * or programmatic reveal), with the reader's guess in data coordinates,
-   * ordered by x. For newsrooms aggregating reader guesses.
-   */
-  onReveal?: (guess: Array<{ x: string | number; y: number }>) => void;
-}