@opendata-ai/openchart-core 6.3.0 → 6.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "6.3.0",
+  "version": "6.4.1",
   "description": "Types, theme, colors, accessibility, and utilities for openchart",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",

package/src/types/events.ts

@@ -25,13 +25,45 @@ import type {
 /** 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 }
+  | { type: 'chrome'; key: ChromeKey }
+  | { type: 'series-label'; series: string }
+  | { type: 'legend' }
+  | { type: 'legend-entry'; series: string; index: number };
+
+/** 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 => ({
+    type: 'legend-entry',
+    series,
+    index,
+  }),
+} as const;
+
 // ---------------------------------------------------------------------------
 // Element edit events
 // ---------------------------------------------------------------------------
 
 /**
  * Discriminated union of all element edit events.
- * Fired by the `onEdit` callback when any editable chart element is repositioned.
+ * 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.
  */
 export type ElementEdit =
   | { type: 'annotation'; annotation: TextAnnotation; offset: AnnotationOffset }
@@ -46,7 +78,9 @@ export type ElementEdit =
   | { type: 'chrome'; key: ChromeKey; text: string; offset: AnnotationOffset }
   | { type: 'series-label'; series: string; offset: AnnotationOffset }
   | { type: 'legend'; offset: AnnotationOffset }
-  | { type: 'legend-toggle'; series: string; hidden: boolean };
+  | { type: 'legend-toggle'; series: string; hidden: boolean }
+  | { type: 'delete'; element: ElementRef }
+  | { type: 'text-edit'; element: ElementRef; oldText: string; newText: string };
 
 // ---------------------------------------------------------------------------
 // Mark events
@@ -92,6 +126,12 @@ export interface ChartEventHandlers {
   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 editable chart element (annotations, chrome, legend, series labels). */
+  /** 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;
 }

package/src/types/index.ts

@@ -21,8 +21,10 @@ export type {
   ChartEventHandlers,
   ChromeKey,
   ElementEdit,
+  ElementRef,
   MarkEvent,
 } from './events';
+export { elementRef } from './events';
 // Layout types (engine output)
 export type {
   A11yMetadata,

package/src/types/layout.ts

@@ -490,6 +490,8 @@ export interface ResolvedLabel {
 export interface ResolvedAnnotation {
   /** Original annotation type. */
   type: 'text' | 'range' | 'refline';
+  /** Stable identifier from the spec annotation, for selection/edit callbacks. */
+  id?: string;
   /** Label text (if any). */
   label?: ResolvedLabel;
   /** For range: the highlighted rectangle in pixel coordinates. */

package/src/types/spec.ts

@@ -382,6 +382,8 @@ export type AnnotationAnchor = 'top' | 'bottom' | 'left' | 'right' | 'auto';
 
 /** Base properties shared by all annotation types. */
 interface AnnotationBase {
+  /** Stable identifier for selection and edit callbacks. When provided, edit events include this ID for reliable element matching. */
+  id?: string;
   /** Human-readable label for the annotation. */
   label?: string;
   /** Fill color for the annotation element. */