@opendata-ai/openchart-vanilla 6.3.0 → 6.5.0

package/src/mount.ts

@@ -17,6 +17,7 @@ import type {
   CompileOptions,
   DarkMode,
   ElementEdit,
+  ElementRef,
   GraphSpec,
   LayerSpec,
   MeasureTextFn,
@@ -26,8 +27,9 @@ import type {
   ThemeConfig,
   TooltipContent,
 } from '@opendata-ai/openchart-core';
-import { isLayerSpec } from '@opendata-ai/openchart-core';
+import { elementRef, isLayerSpec } from '@opendata-ai/openchart-core';
 import { compileChart, compileLayer } from '@opendata-ai/openchart-engine';
+import { cancelAnimations, setupAnimationCleanup } from './animation';
 import {
   exportCSV,
   exportJPG,
@@ -39,6 +41,7 @@ import {
 } from './export';
 import { observeResize } from './resize-observer';
 import { renderChartSVG } from './svg-renderer';
+import { createTextEditOverlay } from './text-edit-overlay';
 import { createTooltipManager, type TooltipManager } from './tooltip';
 
 // ---------------------------------------------------------------------------
@@ -54,6 +57,13 @@ export interface MountOptions extends ChartEventHandlers {
   onDataPointClick?: (data: Record<string, unknown>) => void;
   /** Enable responsive resizing. Defaults to true. */
   responsive?: boolean;
+  /** Initial selected element. */
+  selectedElement?: ElementRef;
+}
+
+export interface UpdateOptions {
+  /** Override the selected element after update. When omitted, preserves current selection. */
+  selectedElement?: ElementRef;
 }
 
 export interface ExportOptions extends JPGExportOptions {
@@ -62,7 +72,7 @@ export interface ExportOptions extends JPGExportOptions {
 
 export interface ChartInstance {
   /** Re-compile and re-render with a new spec. */
-  update(spec: ChartSpec | LayerSpec | GraphSpec): void;
+  update(spec: ChartSpec | LayerSpec | GraphSpec, options?: UpdateOptions): void;
   /** Re-compile at current container dimensions. */
   resize(): void;
   /** Export the chart. */
@@ -79,6 +89,14 @@ export interface ChartInstance {
   destroy(): void;
   /** The current compiled layout (for hooks / debugging). */
   readonly layout: ChartLayout;
+  /** Get the currently selected element, or null if none. */
+  getSelectedElement(): ElementRef | null;
+  /** Programmatically select an element. Silent no-op if element not found. */
+  select(ref: ElementRef): void;
+  /** Deselect the current element. */
+  deselect(): void;
+  /** Whether inline text editing is active. */
+  readonly isEditing: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -460,7 +478,7 @@ function wireChartEvents(
 
   // Wire annotation click events
   if (handlers.onAnnotationClick) {
-    const annotationElements = svg.querySelectorAll('.viz-annotation');
+    const annotationElements = svg.querySelectorAll('.oc-annotation');
 
     for (let i = 0; i < annotationElements.length; i++) {
       const el = annotationElements[i];
@@ -696,7 +714,7 @@ function wireAnnotationDrag(
   onEdit: ((edit: ElementEdit) => void) | undefined,
   setDragging: (dragging: boolean) => void,
 ): () => void {
-  const annotationElements = svg.querySelectorAll('.viz-annotation-text');
+  const annotationElements = svg.querySelectorAll('.oc-annotation-text');
   const cleanups: Array<() => void> = [];
 
   for (const el of annotationElements) {
@@ -714,13 +732,13 @@ function wireAnnotationDrag(
     annotationG.style.cursor = 'grab';
 
     // Stash connector info for real-time updates during drag
-    const connectorLine = annotationG.querySelector('line.viz-annotation-connector');
+    const connectorLine = annotationG.querySelector('line.oc-annotation-connector');
     const origX2 = connectorLine ? Number(connectorLine.getAttribute('x2')) : 0;
     const origY2 = connectorLine ? Number(connectorLine.getAttribute('y2')) : 0;
 
     // For curved connectors, stash path/polygon elements to hide during drag
-    const curvedPath = annotationG.querySelector('path.viz-annotation-connector');
-    const arrowhead = annotationG.querySelector('polygon.viz-annotation-connector');
+    const curvedPath = annotationG.querySelector('path.oc-annotation-connector');
+    const arrowhead = annotationG.querySelector('polygon.oc-annotation-connector');
     const hasCurvedConnector = curvedPath !== null;
 
     const origDx = textAnnotation.offset?.dx ?? 0;
@@ -807,7 +825,7 @@ function wireConnectorEndpointDrag(
 ): () => void {
   const SVG_NS = 'http://www.w3.org/2000/svg';
   const cleanups: Array<() => void> = [];
-  const annotationGroups = svg.querySelectorAll('.viz-annotation-text');
+  const annotationGroups = svg.querySelectorAll('.oc-annotation-text');
 
   for (const el of annotationGroups) {
     const annotationG = el as SVGGElement;
@@ -821,8 +839,8 @@ function wireConnectorEndpointDrag(
     const textAnnotation = specAnnotation as TextAnnotation;
 
     // Find connector line or curved connector to determine endpoints
-    const connectorLine = annotationG.querySelector('line.viz-annotation-connector');
-    const curvedPath = annotationG.querySelector('path.viz-annotation-connector');
+    const connectorLine = annotationG.querySelector('line.oc-annotation-connector');
+    const curvedPath = annotationG.querySelector('path.oc-annotation-connector');
     if (!connectorLine && !curvedPath) continue;
 
     // Determine connector endpoint positions from the connector element
@@ -840,7 +858,7 @@ function wireConnectorEndpointDrag(
       fromX = mMatch ? Number(mMatch[1]) : 0;
       fromY = mMatch ? Number(mMatch[2]) : 0;
       // For curved connectors, the arrow polygon has the target
-      const arrowhead = annotationG.querySelector('polygon.viz-annotation-connector');
+      const arrowhead = annotationG.querySelector('polygon.oc-annotation-connector');
       const points = arrowhead?.getAttribute('points') ?? '';
       const firstPoint = points.split(' ')[0] ?? '0,0';
       const [px, py] = firstPoint.split(',');
@@ -861,7 +879,7 @@ function wireConnectorEndpointDrag(
       if (!Number.isFinite(ep.cx) || !Number.isFinite(ep.cy)) continue;
 
       const handleEl = document.createElementNS(SVG_NS, 'circle') as SVGCircleElement;
-      handleEl.setAttribute('class', 'viz-connector-handle');
+      handleEl.setAttribute('class', 'oc-connector-handle');
       handleEl.setAttribute('data-endpoint', ep.name);
       handleEl.setAttribute('cx', String(ep.cx));
       handleEl.setAttribute('cy', String(ep.cy));
@@ -985,15 +1003,15 @@ function wireAnnotationLabelDrag(
 
   // Target range and refline annotation labels
   const selectors = [
-    '.viz-annotation-range .viz-annotation-label',
-    '.viz-annotation-refline .viz-annotation-label',
+    '.oc-annotation-range .oc-annotation-label',
+    '.oc-annotation-refline .oc-annotation-label',
   ];
 
   for (const selector of selectors) {
     const labels = svg.querySelectorAll(selector);
 
     for (const label of labels) {
-      const annotationG = label.closest('.viz-annotation') as SVGGElement | null;
+      const annotationG = label.closest('.oc-annotation') as SVGGElement | null;
       if (!annotationG) continue;
 
       const indexStr = annotationG.getAttribute('data-annotation-index');
@@ -1068,7 +1086,7 @@ function wireChromeDrag(
   onEdit: (edit: ElementEdit) => void,
   setDragging: (dragging: boolean) => void,
 ): () => void {
-  const chromeTexts = svg.querySelectorAll('.viz-chrome text[data-chrome-key]');
+  const chromeTexts = svg.querySelectorAll('.oc-chrome text[data-chrome-key]');
   const cleanups: Array<() => void> = [];
 
   // Read existing chrome offsets from the spec
@@ -1136,7 +1154,7 @@ function wireLegendDrag(
   onEdit: (edit: ElementEdit) => void,
   setDragging: (dragging: boolean) => void,
 ): () => void {
-  const legendG = svg.querySelector('.viz-legend') as SVGGElement | null;
+  const legendG = svg.querySelector('.oc-legend') as SVGGElement | null;
   if (!legendG) return () => {};
 
   const cleanups: Array<() => void> = [];
@@ -1180,7 +1198,7 @@ function wireLegendDrag(
 // ---------------------------------------------------------------------------
 
 /**
- * Wire drag on series label elements (.viz-mark-label[data-series]).
+ * Wire drag on series label elements (.oc-mark-label[data-series]).
  * On drag end, fires onEdit with the series name and offset.
  * Returns a cleanup function.
  */
@@ -1190,7 +1208,7 @@ function wireSeriesLabelDrag(
   onEdit: (edit: ElementEdit) => void,
   setDragging: (dragging: boolean) => void,
 ): () => void {
-  const labels = svg.querySelectorAll('.viz-mark-label');
+  const labels = svg.querySelectorAll('.oc-mark-label');
   const cleanups: Array<() => void> = [];
 
   // Read existing label offsets from the spec
@@ -1290,7 +1308,7 @@ function wireLegendInteraction(
       // Toggle visibility of marks with matching series.
       // Uses the data-series attribute set by the SVG renderer, which works
       // for all mark types (line, area, rect, arc, point).
-      const marks = svg.querySelectorAll('.viz-mark');
+      const marks = svg.querySelectorAll('.oc-mark');
       for (const mark of marks) {
         const seriesName = mark.getAttribute('data-series');
         if (!seriesName) continue;
@@ -1350,7 +1368,7 @@ function wireKeyboardNav(
   function highlightMark(index: number): void {
     // Remove previous highlight
     if (focusIndex >= 0 && focusIndex < markElements.length) {
-      markElements[focusIndex].classList.remove('viz-mark-focused');
+      markElements[focusIndex].classList.remove('oc-mark-focused');
       markElements[focusIndex].removeAttribute('aria-selected');
     }
 
@@ -1358,7 +1376,7 @@ function wireKeyboardNav(
 
     if (focusIndex >= 0 && focusIndex < markElements.length) {
       const el = markElements[focusIndex];
-      el.classList.add('viz-mark-focused');
+      el.classList.add('oc-mark-focused');
       el.setAttribute('aria-selected', 'true');
     }
   }
@@ -1447,7 +1465,7 @@ function createScreenReaderTable(
   if (!data || data.length === 0) return null;
 
   const table = document.createElement('table');
-  table.className = 'viz-sr-only';
+  table.className = 'oc-sr-only';
   // Inline critical SR-only styles so the table stays hidden even when the
   // external stylesheet isn't loaded (e.g. CDN / esm.sh usage).
   table.style.position = 'absolute';
@@ -1497,6 +1515,252 @@ function createScreenReaderTable(
   return table;
 }
 
+// ---------------------------------------------------------------------------
+// Editable element helpers
+// ---------------------------------------------------------------------------
+
+/** CSS for editable hover feedback, injected into the SVG as a <style> element. */
+const EDITABLE_HOVER_CSS = `
+.oc-editable-hover {
+  outline: 1.5px solid rgba(79, 70, 229, 0.35);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+`;
+
+/**
+ * Inject editable styles into an SVG element and make it focusable.
+ * Called when any editing callback is provided.
+ */
+function makeEditable(svg: SVGElement): void {
+  svg.setAttribute('tabindex', '0');
+  svg.style.outline = 'none';
+
+  // Inject hover style into SVG defs
+  const style = document.createElementNS('http://www.w3.org/2000/svg', 'style');
+  style.textContent = EDITABLE_HOVER_CSS;
+  svg.insertBefore(style, svg.firstChild);
+}
+
+/**
+ * Check whether any editing-related callback is provided in the options.
+ */
+function hasEditingCallbacks(opts?: MountOptions): boolean {
+  return !!(opts?.onEdit || opts?.onSelect || opts?.onDeselect || opts?.onTextEdit);
+}
+
+/**
+ * Find a DOM element inside the SVG that matches the given ElementRef.
+ */
+function findElementByRef(svg: SVGElement, ref: ElementRef): SVGElement | null {
+  switch (ref.type) {
+    case 'annotation': {
+      // Prefer id-based lookup when available
+      if (ref.id) {
+        const byId = svg.querySelector(`[data-annotation-id="${ref.id}"]`);
+        if (byId) return byId as SVGElement;
+      }
+      return svg.querySelector(`[data-annotation-index="${ref.index}"]`) as SVGElement | null;
+    }
+    case 'chrome':
+      return svg.querySelector(`[data-chrome-key="${ref.key}"]`) as SVGElement | null;
+    case 'series-label':
+      return svg.querySelector(`.oc-mark-label[data-series="${ref.series}"]`) as SVGElement | null;
+    case 'legend':
+      return svg.querySelector('.oc-legend') as SVGElement | null;
+    case 'legend-entry':
+      return svg.querySelector(`[data-legend-index="${ref.index}"]`) as SVGElement | null;
+  }
+}
+
+/**
+ * Build an ElementRef from a DOM element's data attributes.
+ * Walks up the tree to find the closest editable ancestor if needed.
+ */
+function buildElementRef(element: Element, _specAnnotations: Annotation[]): ElementRef | null {
+  // Check for annotation
+  const annotationEl = element.closest('[data-annotation-index]');
+  if (annotationEl) {
+    const index = Number(annotationEl.getAttribute('data-annotation-index'));
+    const id = annotationEl.getAttribute('data-annotation-id') ?? undefined;
+    return elementRef.annotation(index, id);
+  }
+
+  // Check for chrome
+  const chromeEl = element.closest('[data-chrome-key]');
+  if (chromeEl) {
+    const key = chromeEl.getAttribute('data-chrome-key') as ChromeKey;
+    if (key) return elementRef.chrome(key);
+  }
+
+  // Check for series label
+  const seriesLabelEl = element.closest('.oc-mark-label[data-series]');
+  if (seriesLabelEl) {
+    const series = seriesLabelEl.getAttribute('data-series');
+    if (series) return elementRef.seriesLabel(series);
+  }
+
+  // Check for legend entry
+  const legendEntryEl = element.closest('[data-legend-index]');
+  if (legendEntryEl) {
+    const index = Number(legendEntryEl.getAttribute('data-legend-index'));
+    const series = legendEntryEl.getAttribute('data-legend-label') ?? '';
+    return elementRef.legendEntry(series, index);
+  }
+
+  // Check for legend group
+  const legendEl = element.closest('.oc-legend');
+  if (legendEl) return elementRef.legend();
+
+  return null;
+}
+
+/**
+ * Get an ordered list of all editable ElementRefs from the current spec and layout.
+ * Order: chrome (title, subtitle, source, byline, footer), annotations by index,
+ * series labels alphabetical, legend.
+ */
+function getEditableElements(
+  spec: ChartSpec | LayerSpec | GraphSpec,
+  layout: ChartLayout,
+): ElementRef[] {
+  const refs: ElementRef[] = [];
+
+  // Chrome keys in display order
+  const chromeKeys: ChromeKey[] = ['title', 'subtitle', 'source', 'byline', 'footer'];
+  for (const key of chromeKeys) {
+    if (layout.chrome[key]) {
+      refs.push(elementRef.chrome(key));
+    }
+  }
+
+  // Annotations by index
+  const annotations: Annotation[] =
+    'annotations' in spec && Array.isArray(spec.annotations) ? spec.annotations : [];
+  for (let i = 0; i < annotations.length; i++) {
+    refs.push(elementRef.annotation(i, annotations[i].id));
+  }
+
+  // Series labels (alphabetical)
+  const seriesLabels: string[] = [];
+  for (const mark of layout.marks) {
+    if (mark.type === 'line' && mark.label?.visible && mark.seriesKey) {
+      seriesLabels.push(mark.seriesKey);
+    }
+  }
+  seriesLabels.sort();
+  for (const series of seriesLabels) {
+    refs.push(elementRef.seriesLabel(series));
+  }
+
+  // Legend
+  if (layout.legend.entries.length > 0) {
+    refs.push(elementRef.legend());
+  }
+
+  return refs;
+}
+
+/**
+ * Check if an ElementRef points to a text-editable element (chrome text or text annotation).
+ */
+function isTextEditable(ref: ElementRef, specAnnotations: Annotation[]): boolean {
+  if (ref.type === 'chrome') return true;
+  if (ref.type === 'annotation') {
+    const annotation = specAnnotations[ref.index];
+    return annotation?.type === 'text';
+  }
+  return false;
+}
+
+/**
+ * Get the current text content for an element ref.
+ */
+function getElementText(ref: ElementRef, spec: ChartSpec | LayerSpec | GraphSpec): string | null {
+  if (ref.type === 'chrome') {
+    const chromeConfig = 'chrome' in spec ? spec.chrome : undefined;
+    if (!chromeConfig) return null;
+    const entry = chromeConfig[ref.key];
+    if (typeof entry === 'string') return entry;
+    if (typeof entry === 'object' && entry !== null && 'text' in entry) {
+      return (entry as { text: string }).text;
+    }
+    return null;
+  }
+  if (ref.type === 'annotation') {
+    const annotations: Annotation[] =
+      'annotations' in spec && Array.isArray(spec.annotations) ? spec.annotations : [];
+    const annotation = annotations[ref.index];
+    if (annotation?.type === 'text') return (annotation as TextAnnotation).text ?? null;
+    if (annotation?.label) return annotation.label;
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Compare two ElementRefs for equality.
+ */
+function refsEqual(a: ElementRef | null, b: ElementRef | null): boolean {
+  if (a === null || b === null) return a === b;
+  if (a.type !== b.type) return false;
+  switch (a.type) {
+    case 'annotation': {
+      const bAnno = b as typeof a;
+      if (a.id && bAnno.id) return a.id === bAnno.id;
+      return a.index === bAnno.index;
+    }
+    case 'chrome':
+      return a.key === (b as typeof a).key;
+    case 'series-label':
+      return a.series === (b as typeof a).series;
+    case 'legend':
+      return true;
+    case 'legend-entry': {
+      const bEntry = b as typeof a;
+      return a.index === bEntry.index && a.series === bEntry.series;
+    }
+  }
+}
+
+/**
+ * Render a selection overlay rectangle around a target element.
+ * Returns the overlay group element.
+ */
+function renderSelectionOverlay(
+  svg: SVGElement,
+  ref: ElementRef,
+  layout: ChartLayout,
+): SVGGElement | null {
+  const target = findElementByRef(svg, ref);
+  if (!target) return null;
+
+  const bbox = (target as SVGGraphicsElement).getBBox();
+  const padding = 4;
+
+  // Resolve accent color from theme
+  const accentColor = layout.theme.colors.categorical?.[0] ?? '#4f46e5';
+
+  const g = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+  g.setAttribute('class', 'oc-selection-overlay');
+
+  const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+  rect.setAttribute('x', String(bbox.x - padding));
+  rect.setAttribute('y', String(bbox.y - padding));
+  rect.setAttribute('width', String(bbox.width + padding * 2));
+  rect.setAttribute('height', String(bbox.height + padding * 2));
+  rect.setAttribute('rx', '3');
+  rect.setAttribute('fill', 'transparent');
+  rect.setAttribute('stroke', accentColor);
+  rect.setAttribute('stroke-width', '1.5');
+  rect.setAttribute('pointer-events', 'none');
+
+  g.appendChild(rect);
+  svg.appendChild(g);
+
+  return g;
+}
+
 // ---------------------------------------------------------------------------
 // Main API
 // ---------------------------------------------------------------------------
@@ -1526,12 +1790,24 @@ export function createChart(
   let cleanupChartEvents: (() => void) | null = null;
   let cleanupAnnotationDrag: (() => void) | null = null;
   let cleanupEditDrags: (() => void) | null = null;
+  let cleanupSelection: (() => void) | null = null;
+  let cleanupKeyboardEdit: (() => void) | null = null;
   let srTable: HTMLTableElement | null = null;
   let destroyed = false;
   let isDragging = false;
   let pendingRender = false;
   let resizeTimer: ReturnType<typeof setTimeout> | null = null;
 
+  // Animation state
+  let isFirstRender = true;
+  let cleanupAnimations: (() => void) | null = null;
+
+  // Selection and text editing state
+  let selectedElement: ElementRef | null = options?.selectedElement ?? null;
+  let overlayElement: SVGGElement | null = null;
+  let isTextEditingActive = false;
+  let textEditCleanup: (() => void) | null = null;
+
   const measureText = createMeasureText();
 
   function compile(): ChartLayout {
@@ -1560,6 +1836,274 @@ export function createChart(
     };
   }
 
+  /** Get the current spec's annotations array. */
+  function getSpecAnnotations(): Annotation[] {
+    return 'annotations' in currentSpec && Array.isArray(currentSpec.annotations)
+      ? currentSpec.annotations
+      : [];
+  }
+
+  /** Select an element: render overlay, fire onSelect, update state. */
+  function selectElement(ref: ElementRef): void {
+    if (!svgElement) return;
+
+    // Confirm the target element exists before deselecting the previous one
+    const target = findElementByRef(svgElement, ref);
+    if (!target) return;
+
+    // Deselect previous if different
+    if (selectedElement && !refsEqual(selectedElement, ref)) {
+      deselectElement();
+    }
+
+    selectedElement = ref;
+    overlayElement = renderSelectionOverlay(svgElement, ref, currentLayout);
+    options?.onSelect?.(ref);
+
+    // Focus SVG for keyboard events
+    (svgElement as SVGSVGElement).focus();
+  }
+
+  /** Deselect the current element: remove overlay, fire onDeselect, clear state. */
+  function deselectElement(): void {
+    if (!selectedElement) return;
+
+    // Cancel text editing if active
+    if (isTextEditingActive && textEditCleanup) {
+      textEditCleanup();
+      textEditCleanup = null;
+      isTextEditingActive = false;
+    }
+
+    const prev = selectedElement;
+    selectedElement = null;
+
+    if (overlayElement?.parentNode) {
+      overlayElement.parentNode.removeChild(overlayElement);
+    }
+    overlayElement = null;
+
+    options?.onDeselect?.(prev);
+  }
+
+  /** Enter text editing mode for the currently selected element. */
+  function enterTextEditing(): void {
+    if (!svgElement || !selectedElement || isTextEditingActive) return;
+
+    const specAnnotations = getSpecAnnotations();
+    if (!isTextEditable(selectedElement, specAnnotations)) return;
+
+    const currentText = getElementText(selectedElement, currentSpec);
+    if (currentText === null) return;
+
+    // Find the text element within the selected element
+    const target = findElementByRef(svgElement, selectedElement);
+    if (!target) return;
+
+    // The target might be a group; find the actual text element
+    const textEl = target.tagName === 'text' ? target : target.querySelector('text');
+    if (!textEl) return;
+
+    isTextEditingActive = true;
+    const editRef = selectedElement;
+
+    const overlay = createTextEditOverlay({
+      container,
+      svg: svgElement as SVGSVGElement,
+      targetElement: textEl as SVGElement,
+      currentText,
+      onCommit: (newText: string) => {
+        isTextEditingActive = false;
+        textEditCleanup = null;
+
+        if (newText !== currentText) {
+          // Fire text edit callbacks
+          options?.onTextEdit?.(editRef, currentText, newText);
+          options?.onEdit?.({
+            type: 'text-edit',
+            element: editRef,
+            oldText: currentText,
+            newText,
+          });
+        }
+      },
+      onCancel: () => {
+        isTextEditingActive = false;
+        textEditCleanup = null;
+      },
+    });
+
+    textEditCleanup = overlay.destroy;
+  }
+
+  /**
+   * Wire click-based selection events on the SVG.
+   * Uses event delegation for efficiency.
+   */
+  function wireSelectionEvents(): () => void {
+    if (!svgElement) return () => {};
+
+    const svg = svgElement;
+    const cleanups: Array<() => void> = [];
+
+    // Click handler for selection
+    const handleClick = (e: Event) => {
+      const mouseEvent = e as MouseEvent;
+      const target = mouseEvent.target as Element;
+
+      // Don't interfere with text editing
+      if (isTextEditingActive) return;
+
+      const specAnnotations = getSpecAnnotations();
+      const ref = buildElementRef(target, specAnnotations);
+
+      if (ref) {
+        // Clicked on an editable element
+        selectElement(ref);
+      } else {
+        // Clicked on empty area / non-editable element, deselect
+        deselectElement();
+      }
+    };
+
+    svg.addEventListener('click', handleClick);
+    cleanups.push(() => svg.removeEventListener('click', handleClick));
+
+    // Hover feedback on editable elements
+    const handleMouseEnter = (e: Event) => {
+      const target = (e.target as Element).closest(
+        '[data-annotation-index], [data-chrome-key], .oc-mark-label[data-series], .oc-legend, [data-legend-index]',
+      );
+      if (target) {
+        (target as SVGElement).classList.add('oc-editable-hover');
+      }
+    };
+
+    const handleMouseLeave = (e: Event) => {
+      const target = (e.target as Element).closest('.oc-editable-hover');
+      if (target) {
+        (target as SVGElement).classList.remove('oc-editable-hover');
+      }
+    };
+
+    svg.addEventListener('mouseenter', handleMouseEnter, true);
+    svg.addEventListener('mouseleave', handleMouseLeave, true);
+    cleanups.push(() => {
+      svg.removeEventListener('mouseenter', handleMouseEnter, true);
+      svg.removeEventListener('mouseleave', handleMouseLeave, true);
+    });
+
+    // Double-click to enter text editing
+    const handleDblClick = (e: Event) => {
+      const mouseEvent = e as MouseEvent;
+      const target = mouseEvent.target as Element;
+      const specAnnotations = getSpecAnnotations();
+      const ref = buildElementRef(target, specAnnotations);
+
+      if (ref && isTextEditable(ref, specAnnotations)) {
+        // Select first if not already selected
+        if (!refsEqual(selectedElement, ref)) {
+          selectElement(ref);
+        }
+        enterTextEditing();
+      }
+    };
+
+    svg.addEventListener('dblclick', handleDblClick);
+    cleanups.push(() => svg.removeEventListener('dblclick', handleDblClick));
+
+    return () => {
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+    };
+  }
+
+  /**
+   * Wire keyboard events for edit actions on the SVG.
+   * Delete/Backspace -> delete, Escape -> cancel/deselect, Tab -> cycle, Enter -> text edit.
+   */
+  function wireKeyboardEditEvents(): () => void {
+    if (!svgElement) return () => {};
+
+    const svg = svgElement;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      const specAnnotations = getSpecAnnotations();
+
+      switch (e.key) {
+        case 'Delete':
+        case 'Backspace': {
+          if (selectedElement && !isTextEditingActive) {
+            e.preventDefault();
+            options?.onEdit?.({ type: 'delete', element: selectedElement });
+            // Stay selected (consumer decides whether to remove the element)
+          }
+          break;
+        }
+
+        case 'Escape': {
+          e.preventDefault();
+          if (isTextEditingActive && textEditCleanup) {
+            // Cancel text editing, remain selected
+            textEditCleanup();
+            textEditCleanup = null;
+            isTextEditingActive = false;
+          } else if (selectedElement) {
+            deselectElement();
+          }
+          break;
+        }
+
+        case 'ArrowDown':
+        case 'ArrowRight': {
+          if (!isTextEditingActive && selectedElement) {
+            e.preventDefault();
+            const editables = getEditableElements(currentSpec, currentLayout);
+            if (editables.length === 0) break;
+
+            const currentIndex = editables.findIndex((r) => refsEqual(r, selectedElement));
+            const nextIndex = currentIndex >= editables.length - 1 ? 0 : currentIndex + 1;
+
+            selectElement(editables[nextIndex]);
+          }
+          break;
+        }
+
+        case 'ArrowUp':
+        case 'ArrowLeft': {
+          if (!isTextEditingActive && selectedElement) {
+            e.preventDefault();
+            const editables = getEditableElements(currentSpec, currentLayout);
+            if (editables.length === 0) break;
+
+            const currentIndex = editables.findIndex((r) => refsEqual(r, selectedElement));
+            const nextIndex = currentIndex <= 0 ? editables.length - 1 : currentIndex - 1;
+
+            selectElement(editables[nextIndex]);
+          }
+          break;
+        }
+
+        case 'Enter': {
+          if (selectedElement && !isTextEditingActive) {
+            if (isTextEditable(selectedElement, specAnnotations)) {
+              e.preventDefault();
+              enterTextEditing();
+            }
+          }
+          break;
+        }
+      }
+    };
+
+    svg.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      svg.removeEventListener('keydown', handleKeyDown);
+    };
+  }
+
   function render(): void {
     // Defer re-render if a drag is in progress to avoid destroying the dragged element
     if (isDragging) {
@@ -1567,6 +2111,13 @@ export function createChart(
       return;
     }
 
+    // Cancel any in-progress entrance animations before tearing down
+    if (cleanupAnimations) {
+      cleanupAnimations();
+      cleanupAnimations = null;
+    }
+    cancelAnimations(svgElement);
+
     // Clean up previous render
     if (cleanupTooltipEvents) {
       cleanupTooltipEvents();
@@ -1596,6 +2147,20 @@ export function createChart(
       cleanupEditDrags();
       cleanupEditDrags = null;
     }
+    if (cleanupSelection) {
+      cleanupSelection();
+      cleanupSelection = null;
+    }
+    if (cleanupKeyboardEdit) {
+      cleanupKeyboardEdit();
+      cleanupKeyboardEdit = null;
+    }
+    if (textEditCleanup) {
+      textEditCleanup();
+      textEditCleanup = null;
+      isTextEditingActive = false;
+    }
+    overlayElement = null;
     if (svgElement?.parentNode) {
       svgElement.parentNode.removeChild(svgElement);
     }
@@ -1608,7 +2173,8 @@ export function createChart(
     }
 
     currentLayout = compile();
-    svgElement = renderChartSVG(currentLayout, container);
+    const shouldAnimate = isFirstRender && !!currentLayout.animation?.enabled;
+    svgElement = renderChartSVG(currentLayout, container, { animate: shouldAnimate });
     tooltipManager = createTooltipManager(container);
 
     // Wire tooltip events on mark elements
@@ -1709,27 +2275,63 @@ export function createChart(
       };
     }
 
+    // Wire selection and keyboard edit events when editing callbacks are provided
+    if (hasEditingCallbacks(options)) {
+      makeEditable(svgElement);
+      cleanupSelection = wireSelectionEvents();
+      cleanupKeyboardEdit = wireKeyboardEditEvents();
+
+      // Restore selection overlay after re-render
+      if (selectedElement) {
+        const target = findElementByRef(svgElement, selectedElement);
+        if (target) {
+          overlayElement = renderSelectionOverlay(svgElement, selectedElement, currentLayout);
+        } else {
+          // Element no longer exists in DOM, clear selection silently
+          selectedElement = null;
+          overlayElement = null;
+        }
+      }
+    }
+
     // Create hidden data table for screen readers
     srTable = createScreenReaderTable(currentLayout, container);
 
     // Apply container classes for CSS variable scoping and dark mode
-    container.classList.add('viz-root');
+    container.classList.add('oc-root');
     const isDark = resolveDarkMode(options?.darkMode);
     if (isDark) {
-      container.classList.add('viz-dark');
+      container.classList.add('oc-dark');
     } else {
-      container.classList.remove('viz-dark');
+      container.classList.remove('oc-dark');
+    }
+
+    // Set up animation cleanup on first render only.
+    if (shouldAnimate && svgElement) {
+      cleanupAnimations = setupAnimationCleanup(svgElement);
+    }
+    if (isFirstRender) {
+      isFirstRender = false;
     }
   }
 
-  function update(newSpec: ChartSpec | GraphSpec): void {
+  function update(newSpec: ChartSpec | GraphSpec, updateOpts?: UpdateOptions): void {
     if (destroyed) return;
     currentSpec = newSpec;
+    if (updateOpts && 'selectedElement' in updateOpts) {
+      selectedElement = updateOpts.selectedElement ?? null;
+    }
     render();
   }
 
   function resize(): void {
     if (destroyed) return;
+    // Skip resize during entrance animation. The resize observer fires
+    // immediately when the container first enters DOM layout, and re-rendering
+    // would destroy the animated SVG. This also blocks genuine resizes during
+    // the animation window (~1s), but catches up on the next resize event
+    // after the cleanup timeout fires.
+    if (cleanupAnimations) return;
     render();
   }
 
@@ -1768,6 +2370,13 @@ export function createChart(
     if (destroyed) return;
     destroyed = true;
 
+    // Cancel entrance animations
+    if (cleanupAnimations) {
+      cleanupAnimations();
+      cleanupAnimations = null;
+    }
+    cancelAnimations(svgElement);
+
     if (resizeTimer !== null) {
       clearTimeout(resizeTimer);
       resizeTimer = null;
@@ -1800,6 +2409,21 @@ export function createChart(
       cleanupEditDrags();
       cleanupEditDrags = null;
     }
+    if (cleanupSelection) {
+      cleanupSelection();
+      cleanupSelection = null;
+    }
+    if (cleanupKeyboardEdit) {
+      cleanupKeyboardEdit();
+      cleanupKeyboardEdit = null;
+    }
+    if (textEditCleanup) {
+      textEditCleanup();
+      textEditCleanup = null;
+      isTextEditingActive = false;
+    }
+    selectedElement = null;
+    overlayElement = null;
     if (disconnectResize) {
       disconnectResize();
       disconnectResize = null;
@@ -1816,8 +2440,8 @@ export function createChart(
       srTable.parentNode.removeChild(srTable);
       srTable = null;
     }
-    container.classList.remove('viz-dark');
-    container.classList.remove('viz-root');
+    container.classList.remove('oc-dark');
+    container.classList.remove('oc-root');
   }
 
   // Initial render
@@ -1842,5 +2466,19 @@ export function createChart(
     get layout() {
       return currentLayout;
     },
+    getSelectedElement(): ElementRef | null {
+      return selectedElement;
+    },
+    select(ref: ElementRef): void {
+      if (destroyed) return;
+      selectElement(ref);
+    },
+    deselect(): void {
+      if (destroyed) return;
+      deselectElement();
+    },
+    get isEditing(): boolean {
+      return isTextEditingActive;
+    },
   };
 }