@opendata-ai/openchart-core 7.11.0 → 8.0.0-rc.10

package/src/types/encoding.ts

@@ -28,15 +28,11 @@ export interface EncodingRule {
   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;
 }
 
@@ -70,6 +66,15 @@ function optional(...types: FieldType[]): ChannelRule {
  * - 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: {
@@ -81,8 +86,6 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     size: optional(),
     opacity: optional('quantitative'),
     tooltip: optional(),
-    href: optional(),
-    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
   line: {
@@ -93,8 +96,6 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     opacity: optional('quantitative'),
     strokeDash: optional('nominal', 'ordinal'),
     tooltip: optional(),
-    href: optional(),
-    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
   area: {
@@ -105,8 +106,6 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     size: optional(),
     opacity: optional('quantitative'),
     tooltip: optional(),
-    href: optional(),
-    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
   point: {
@@ -114,11 +113,8 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     y: required('quantitative', 'temporal', 'nominal', 'ordinal'),
     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'),
   },
   circle: {
@@ -128,8 +124,6 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     size: optional('quantitative'),
     opacity: optional('quantitative'),
     tooltip: optional(),
-    href: optional(),
-    order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
   lollipop: {
@@ -139,21 +133,63 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     size: optional('quantitative'),
     opacity: optional('quantitative'),
     tooltip: optional(),
-    href: optional(),
-    order: optional('quantitative', 'ordinal'),
+    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(),
-    href: optional(),
-    order: optional('quantitative', 'ordinal'),
     theta: optional('quantitative'),
-    radius: optional('quantitative'),
     detail: optional('nominal'),
   },
   text: {
@@ -164,7 +200,6 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     opacity: optional('quantitative'),
     text: required(),
     tooltip: optional(),
-    href: optional(),
     detail: optional('nominal'),
   },
   rule: {
@@ -177,7 +212,6 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     opacity: optional('quantitative'),
     strokeDash: optional('nominal', 'ordinal'),
     tooltip: optional(),
-    href: optional(),
     detail: optional('nominal'),
   },
   tick: {
@@ -187,7 +221,6 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     size: optional(),
     opacity: optional('quantitative'),
     tooltip: optional(),
-    href: optional(),
     detail: optional('nominal'),
   },
   rect: {
@@ -199,8 +232,19 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     size: optional(),
     opacity: optional('quantitative'),
     tooltip: optional(),
-    href: optional(),
-    order: optional('quantitative', 'ordinal'),
+    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'),
   },
 };

package/src/types/events.ts

@@ -36,22 +36,65 @@ export type ChromeKey = 'title' | 'subtitle' | 'source' | 'byline' | 'footer';
  * and `index` (always available, position in the spec's annotations array).
  */
 export type ElementRef =
-  | { type: 'annotation'; index: number; id?: string }
-  | { type: 'chrome'; key: ChromeKey }
-  | { type: 'series-label'; series: string }
-  | { type: 'legend' }
-  | { type: 'legend-entry'; series: string; index: number };
+  | {
+      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): ElementRef => ({ type: 'annotation', index, id }),
-  chrome: (key: ChromeKey): ElementRef => ({ type: 'chrome', key }),
-  seriesLabel: (series: string): ElementRef => ({ type: 'series-label', series }),
-  legend: (): ElementRef => ({ type: 'legend' }),
-  legendEntry: (series: string, index: number): 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;
 
@@ -71,19 +114,50 @@ export const elementRef = {
  * - To persist a drag edit back into your spec: `{ ...edit.annotation, offset: edit.offset }`
  */
 export type ElementEdit =
-  | { type: 'annotation'; annotation: TextAnnotation; offset: AnnotationOffset }
+  | {
+      type: 'annotation';
+      element: ElementRef;
+      annotation: TextAnnotation;
+      offset: AnnotationOffset;
+    }
   | {
       type: 'annotation-connector';
+      element: ElementRef;
       annotation: TextAnnotation;
       endpoint: 'from' | 'to';
       offset: AnnotationOffset;
     }
-  | { type: 'range-label'; annotation: RangeAnnotation; labelOffset: AnnotationOffset }
-  | { type: 'refline-label'; annotation: RefLineAnnotation; labelOffset: 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 };
 
@@ -119,6 +193,14 @@ export interface MarkEvent {
  * 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. */
@@ -127,6 +209,12 @@ export interface ChartEventHandlers {
   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. */
@@ -139,4 +227,10 @@ export interface ChartEventHandlers {
   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;
 }

package/src/types/index.ts

@@ -12,7 +12,6 @@ export type {
   GraphChannelRule,
 } from './encoding';
 export {
-  CHART_ENCODING_RULES,
   GRAPH_ENCODING_RULES,
   MARK_ENCODING_RULES,
 } from './encoding';
@@ -43,10 +42,15 @@ export type {
   ChartLayout,
   CompileOptions,
   CompileTableOptions,
+  CompileWarning,
+  ContinuousLegendBin,
+  ContinuousLegendLayout,
+  ContinuousLegendTick,
   EndpointLabelEntry,
   EndpointLabelsLayout,
   FacetLayout,
   FacetPanelLayout,
+  FillPatternType,
   FlagTableCell,
   GradientColorStop,
   GradientLegendLayout,
@@ -56,10 +60,16 @@ export type {
   Gridline,
   HeatmapTableCell,
   ImageTableCell,
+  LegendChannel,
   LegendEntry,
   LegendEntryPosition,
   LegendLayout,
   LineMark,
+  MapBorders,
+  MapFeatureMark,
+  MapFocusLayout,
+  MapLayout,
+  MapPointMark,
   Margins,
   Mark,
   MarkAria,
@@ -75,13 +85,19 @@ export type {
   ResolvedChrome,
   ResolvedChromeElement,
   ResolvedColumn,
+  ResolvedFillPattern,
   ResolvedLabel,
   ResolvedMetricBar,
   ResolvedMetricCell,
+  ResolvedSeriesSearch,
+  ResolvedYouDrawIt,
   RuleMarkLayout,
   SankeyLayout,
   SankeyLinkMark,
   SankeyNodeMark,
+  ScaleInvert,
+  SizeLegendCircle,
+  SizeLegendLayout,
   SortState,
   SparklineData,
   SparklineTableCell,
@@ -97,9 +113,12 @@ export type {
   TileMapTileMark,
   TooltipContent,
   TooltipField,
+  YouDrawItSample,
+  YouDrawItYInvert,
 } from './layout';
 // Spec types (user input)
 export type {
+  A11yConfig,
   AggregateOp,
   AggregateTransform,
   AnimationConfig,
@@ -117,14 +136,15 @@ export type {
   BarListEncoding,
   BarListSpec,
   BarListSpecWithoutData,
+  BeeswarmEncoding,
   BinParams,
   BinTransform,
   CalculateExpression,
   CalculateTransform,
+  CalendarEncoding,
   ChartSpec,
   ChartSpecOverride,
   ChartSpecWithoutData,
-  ChartType,
   Chrome,
   ChromeText,
   ChromeTextStyle,
@@ -132,11 +152,14 @@ export type {
   CircleEncoding,
   Condition,
   ConditionalValueDef,
+  ConnectorConfig,
+  ConnectorType,
   DarkMode,
   DataRow,
   Display,
   Encoding,
   EncodingChannel,
+  EndpointLabelContent,
   EndpointLabelsConfig,
   FacetChannel,
   FieldPredicate,
@@ -164,13 +187,22 @@ export type {
   LogicalNot,
   LogicalOr,
   LollipopEncoding,
+  MapEncoding,
+  MapFocus,
+  MapGeo,
+  MapPointsLayer,
+  MapProjection,
+  MapSpec,
+  MapSpecWithoutData,
   MarkDef,
   MarkType,
   Metric,
   NodeOverride,
+  ParliamentEncoding,
   PointEncoding,
   RadialGradient,
   RangeAnnotation,
+  RangeEncoding,
   RectEncoding,
   RefLineAnnotation,
   RelativeTimeRef,
@@ -184,7 +216,9 @@ export type {
   SankeySpecWithoutData,
   ScaleConfig,
   ScaleType,
+  SeriesSearchConfig,
   SeriesStyle,
+  SortByField,
   StoredVizSpec,
   TableSpec,
   TableSpecWithoutData,
@@ -199,15 +233,18 @@ export type {
   TimeUnit,
   TimeUnitTransform,
   Transform,
+  ValueDef,
   VizSpec,
+  WaffleEncoding,
   WindowFieldDef,
   WindowOp,
   WindowSortField,
   WindowTransform,
+  YouDrawItConfig,
 } from './spec';
 export {
-  CHART_TYPES,
   getRepresentativeColor,
+  isAxislessMark,
   isBarListSpec,
   isChartSpec,
   isConditionalDef,
@@ -215,12 +252,14 @@ export {
   isGradientDef,
   isGraphSpec,
   isLayerSpec,
+  isMapSpec,
   isRangeAnnotation,
   isRefLineAnnotation,
   isSankeySpec,
   isTableSpec,
   isTextAnnotation,
   isTileMapSpec,
+  isValueDef,
   MARK_DISPLAY_NAMES,
   MARK_TYPES,
   resolveMarkDef,