@opendata-ai/openchart-core 6.3.0 → 6.4.1

package/dist/index.d.ts

@@ -455,6 +455,8 @@ interface AnnotationOffset {
 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. */
@@ -1083,9 +1085,42 @@ declare const GRAPH_ENCODING_RULES: Record<string, GraphChannelRule>;
 
 /** Identifies a specific chrome text element (title, subtitle, source, byline, footer). */
 type ChromeKey = 'title' | 'subtitle' | 'source' | 'byline' | 'footer';
+/**
+ * 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).
+ */
+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. */
+declare const elementRef: {
+    readonly annotation: (index: number, id?: string) => ElementRef;
+    readonly chrome: (key: ChromeKey) => ElementRef;
+    readonly seriesLabel: (series: string) => ElementRef;
+    readonly legend: () => ElementRef;
+    readonly legendEntry: (series: string, index: number) => ElementRef;
+};
 /**
  * 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.
  */
 type ElementEdit = {
     type: 'annotation';
@@ -1120,6 +1155,14 @@ type ElementEdit = {
     type: 'legend-toggle';
     series: string;
     hidden: boolean;
+} | {
+    type: 'delete';
+    element: ElementRef;
+} | {
+    type: 'text-edit';
+    element: ElementRef;
+    oldText: string;
+    newText: string;
 };
 /**
  * Event fired when a user interacts with a data mark (bar, point, line segment, etc.).
@@ -1159,8 +1202,14 @@ 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;
 }
 
 /**
@@ -1716,6 +1765,8 @@ interface ResolvedLabel {
 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. */
@@ -2634,4 +2685,4 @@ declare function scatterChart(data: DataRow[], x: FieldRef, y: FieldRef, options
  */
 declare function dataTable(data: DataRow[], options?: TableBuilderOptions): TableSpec;
 
-export { type A11yMetadata, type AggregateOp, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcMark, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, type BarColumnConfig, type BarTableCell, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, type CalculateExpression, type CalculateTransform, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type Encoding, type EncodingChannel, type EncodingRule, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, GRAPH_ENCODING_RULES, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineMark, type LogicalAnd, type LogicalNot, type LogicalOr, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointMark, type RangeAnnotation, type Rect, type RectMark, type RefLineAnnotation, type ResolveConfig, type ResolveMode, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedTheme, type RuleMarkLayout, SEQUENTIAL_PALETTES, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickMarkLayout, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getBreakpoint, getHeightClass, getLayoutStrategy, inferFieldType, isChartSpec, isConditionalDef, isEncodingChannel, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isTableSpec, isTextAnnotation, lineChart, meetsAA, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveTheme, scatterChart, simulateColorBlindness };
+export { type A11yMetadata, type AggregateOp, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcMark, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, type BarColumnConfig, type BarTableCell, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, type CalculateExpression, type CalculateTransform, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, GRAPH_ENCODING_RULES, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineMark, type LogicalAnd, type LogicalNot, type LogicalOr, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointMark, type RangeAnnotation, type Rect, type RectMark, type RefLineAnnotation, type ResolveConfig, type ResolveMode, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedTheme, type RuleMarkLayout, SEQUENTIAL_PALETTES, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickMarkLayout, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, elementRef, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getBreakpoint, getHeightClass, getLayoutStrategy, inferFieldType, isChartSpec, isConditionalDef, isEncodingChannel, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isTableSpec, isTextAnnotation, lineChart, meetsAA, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveTheme, scatterChart, simulateColorBlindness };

package/dist/index.js

@@ -147,6 +147,19 @@ var GRAPH_ENCODING_RULES = {
   nodeLabel: { required: false, allowedTypes: [] }
 };
 
+// src/types/events.ts
+var elementRef = {
+  annotation: (index, id) => ({ type: "annotation", index, id }),
+  chrome: (key) => ({ type: "chrome", key }),
+  seriesLabel: (series) => ({ type: "series-label", series }),
+  legend: () => ({ type: "legend" }),
+  legendEntry: (series, index) => ({
+    type: "legend-entry",
+    series,
+    index
+  })
+};
+
 // src/types/spec.ts
 function isEncodingChannel(def) {
   if (!def) return false;
@@ -2749,6 +2762,7 @@ export {
   detectCollision,
   donutChart,
   dotChart,
+  elementRef,
   estimateTextWidth,
   findAccessibleColor,
   formatDate,