@opendata-ai/openchart-core 6.2.1 → 6.4.1

package/package.json

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

package/src/index.ts

@@ -88,8 +88,15 @@ export {
 export type {
   LabelCandidate,
   LabelPriority,
+  OffsetStrategy,
+} from './labels/index';
+export {
+  computeLabelBounds,
+  detectCollision,
+  EXTENDED_OFFSET_STRATEGIES,
+  OFFSET_STRATEGIES,
+  resolveCollisions,
 } from './labels/index';
-export { computeLabelBounds, detectCollision, resolveCollisions } from './labels/index';
 
 // ---------------------------------------------------------------------------
 // Locale: number and date formatting

package/src/labels/__tests__/collision.test.ts

@@ -1,7 +1,12 @@
 import { describe, expect, it } from 'vitest';
 import type { TextStyle } from '../../types/layout';
-import type { LabelCandidate } from '../collision';
-import { detectCollision, resolveCollisions } from '../collision';
+import {
+  detectCollision,
+  EXTENDED_OFFSET_STRATEGIES,
+  type LabelCandidate,
+  OFFSET_STRATEGIES,
+  resolveCollisions,
+} from '../collision';
 
 const defaultStyle: TextStyle = {
   fontFamily: 'Inter',
@@ -194,4 +199,64 @@ describe('resolveCollisions', () => {
   it('handles empty input', () => {
     expect(resolveCollisions([])).toEqual([]);
   });
+
+  it('accepts custom strategies without breaking default behavior', () => {
+    const labels: LabelCandidate[] = [
+      {
+        text: 'A',
+        anchorX: 0,
+        anchorY: 0,
+        width: 20,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+      {
+        text: 'B',
+        anchorX: 100,
+        anchorY: 100,
+        width: 20,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+    ];
+
+    // Explicit default strategies should behave the same as no parameter
+    const defaultResults = resolveCollisions(labels);
+    const explicitResults = resolveCollisions(labels, OFFSET_STRATEGIES);
+    expect(explicitResults).toEqual(defaultResults);
+  });
+
+  it('resolves more dense labels with extended strategies than default', () => {
+    // 10 labels at the exact same position, simulating many converging line endpoints.
+    // The default 7 strategies can place at most 7; extended strategies should place more.
+    const labels: LabelCandidate[] = Array.from({ length: 10 }, (_, i) => ({
+      text: `Series ${i}`,
+      anchorX: 400,
+      anchorY: 200,
+      width: 60,
+      height: 14,
+      priority: 'data' as const,
+      style: defaultStyle,
+    }));
+
+    const defaultResults = resolveCollisions(labels);
+    const extendedResults = resolveCollisions(labels, EXTENDED_OFFSET_STRATEGIES);
+
+    const defaultVisible = defaultResults.filter((r) => r.visible).length;
+    const extendedVisible = extendedResults.filter((r) => r.visible).length;
+
+    // Default has 7 strategies, so at most 7 can be placed
+    expect(defaultVisible).toBeLessThanOrEqual(OFFSET_STRATEGIES.length);
+    // Extended strategies should place more labels than default
+    expect(extendedVisible).toBeGreaterThan(defaultVisible);
+  });
+
+  it('EXTENDED_OFFSET_STRATEGIES includes all base strategies', () => {
+    for (const strategy of OFFSET_STRATEGIES) {
+      expect(EXTENDED_OFFSET_STRATEGIES).toContainEqual(strategy);
+    }
+    expect(EXTENDED_OFFSET_STRATEGIES.length).toBeGreaterThan(OFFSET_STRATEGIES.length);
+  });
 });

package/src/labels/collision.ts

@@ -59,8 +59,14 @@ export function detectCollision(a: Rect, b: Rect): boolean {
 // Offset strategies
 // ---------------------------------------------------------------------------
 
+/** An offset position to try when resolving a label collision. */
+export interface OffsetStrategy {
+  dx: number;
+  dy: number;
+}
+
 /** Offsets to try when a label collides with an existing placement. */
-const OFFSET_STRATEGIES = [
+export const OFFSET_STRATEGIES: readonly OffsetStrategy[] = [
   { dx: 0, dy: 0 }, // original position
   { dx: 0, dy: -1.2 }, // above (factor of height)
   { dx: 0, dy: 1.2 }, // below
@@ -70,6 +76,20 @@ const OFFSET_STRATEGIES = [
   { dx: -1.1, dy: -1.2 }, // upper-left
 ];
 
+/**
+ * Extended offset strategies with additional vertical spread for dense
+ * multi-series endpoints (e.g. 5+ line series converging at similar y-values).
+ */
+export const EXTENDED_OFFSET_STRATEGIES: readonly OffsetStrategy[] = [
+  ...OFFSET_STRATEGIES,
+  { dx: 0, dy: -2.4 }, // further above
+  { dx: 0, dy: 2.4 }, // further below
+  { dx: 0, dy: -3.6 }, // even further above
+  { dx: 0, dy: 3.6 }, // even further below
+  { dx: 1.1, dy: -2.4 }, // upper-right far
+  { dx: 1.1, dy: 2.4 }, // lower-right far
+];
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -83,9 +103,13 @@ const OFFSET_STRATEGIES = [
  * demoted to tooltip-only (visible: false).
  *
  * @param labels - Array of label candidates to position.
+ * @param strategies - Optional offset strategies to use (defaults to OFFSET_STRATEGIES).
  * @returns Array of resolved labels with computed positions and visibility.
  */
-export function resolveCollisions(labels: LabelCandidate[]): ResolvedLabel[] {
+export function resolveCollisions(
+  labels: LabelCandidate[],
+  strategies: readonly OffsetStrategy[] = OFFSET_STRATEGIES,
+): ResolvedLabel[] {
   // Sort by priority (highest first)
   const sorted = [...labels].sort(
     (a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority],
@@ -100,7 +124,7 @@ export function resolveCollisions(labels: LabelCandidate[]): ResolvedLabel[] {
     let bestY = label.anchorY;
 
     // Try each offset strategy
-    for (const offset of OFFSET_STRATEGIES) {
+    for (const offset of strategies) {
       const candidateX = label.anchorX + offset.dx * label.width;
       const candidateY = label.anchorY + offset.dy * label.height;
       const candidateRect: Rect = {

package/src/labels/index.ts

@@ -2,5 +2,11 @@
  * Labels module barrel export.
  */
 
-export type { LabelCandidate, LabelPriority } from './collision';
-export { computeLabelBounds, detectCollision, resolveCollisions } from './collision';
+export type { LabelCandidate, LabelPriority, OffsetStrategy } from './collision';
+export {
+  computeLabelBounds,
+  detectCollision,
+  EXTENDED_OFFSET_STRATEGIES,
+  OFFSET_STRATEGIES,
+  resolveCollisions,
+} from './collision';

package/src/locale/__tests__/format.test.ts

@@ -102,6 +102,14 @@ describe('buildD3Formatter', () => {
   it('returns null for completely invalid format', () => {
     expect(buildD3Formatter('not-a-format!!!')).toBeNull();
   });
+
+  it('$~s formats low thousands with SI suffix', () => {
+    const fmt = buildD3Formatter('$~s');
+    expect(fmt).not.toBeNull();
+    expect(fmt!(6000)).toBe('$6k');
+    expect(fmt!(7000)).toBe('$7k');
+    expect(fmt!(14000)).toBe('$14k');
+  });
 });
 
 describe('formatDate', () => {

package/src/types/__tests__/encoding.test.ts

@@ -27,7 +27,7 @@ function getOptionalChannels(markType: MarkType): string[] {
 // ---------------------------------------------------------------------------
 
 describe('MARK_ENCODING_RULES', () => {
-  it('has entries for all 10 mark types', () => {
+  it('has entries for all 11 mark types', () => {
     const expectedTypes: MarkType[] = [
       'bar',
       'line',
@@ -39,6 +39,7 @@ describe('MARK_ENCODING_RULES', () => {
       'rule',
       'tick',
       'rect',
+      'lollipop',
     ];
     for (const type of expectedTypes) {
       expect(MARK_ENCODING_RULES[type]).toBeDefined();
@@ -110,6 +111,17 @@ describe('line encoding rules', () => {
 });
 
 describe('point encoding rules', () => {
+  it('accepts all four field types on x and y', () => {
+    const rules = MARK_ENCODING_RULES.point;
+    for (const axis of ['x', 'y'] as const) {
+      expect(rules[axis].required).toBe(true);
+      expect(rules[axis].allowedTypes).toContain('quantitative');
+      expect(rules[axis].allowedTypes).toContain('temporal');
+      expect(rules[axis].allowedTypes).toContain('nominal');
+      expect(rules[axis].allowedTypes).toContain('ordinal');
+    }
+  });
+
   it('supports shape as optional', () => {
     expect(getOptionalChannels('point')).toContain('shape');
   });
@@ -200,6 +212,23 @@ describe('rect encoding rules', () => {
   });
 });
 
+describe('lollipop encoding rules', () => {
+  it('has the same rules as circle (semantic alias)', () => {
+    const lollipopRules = MARK_ENCODING_RULES.lollipop;
+    const circleRules = MARK_ENCODING_RULES.circle;
+    expect(lollipopRules).toEqual(circleRules);
+  });
+
+  it('requires x (quantitative) and y (nominal/ordinal)', () => {
+    const rules = MARK_ENCODING_RULES.lollipop;
+    expect(rules.x.required).toBe(true);
+    expect(rules.x.allowedTypes).toEqual(['quantitative']);
+    expect(rules.y.required).toBe(true);
+    expect(rules.y.allowedTypes).toContain('nominal');
+    expect(rules.y.allowedTypes).toContain('ordinal');
+  });
+});
+
 describe('common channels across marks', () => {
   it('tooltip is optional on all mark types', () => {
     const allTypes: MarkType[] = [
@@ -213,6 +242,7 @@ describe('common channels across marks', () => {
       'rule',
       'tick',
       'rect',
+      'lollipop',
     ];
     for (const type of allTypes) {
       const rules = MARK_ENCODING_RULES[type];
@@ -234,6 +264,7 @@ describe('common channels across marks', () => {
       'rule',
       'tick',
       'rect',
+      'lollipop',
     ];
     for (const type of allTypes) {
       const rules = MARK_ENCODING_RULES[type];
@@ -255,6 +286,7 @@ describe('common channels across marks', () => {
       'rule',
       'tick',
       'rect',
+      'lollipop',
     ];
     for (const type of allTypes) {
       const rules = MARK_ENCODING_RULES[type];

package/src/types/__tests__/spec.test.ts

@@ -81,6 +81,7 @@ describe('isChartSpec', () => {
       'rule',
       'tick',
       'rect',
+      'lollipop',
     ] as const;
 
     for (const markType of markTypes) {
@@ -151,8 +152,8 @@ describe('type guard mutual exclusivity', () => {
 // ---------------------------------------------------------------------------
 
 describe('MARK_TYPES', () => {
-  it('contains all 10 mark types', () => {
-    expect(MARK_TYPES.size).toBe(10);
+  it('contains all 11 mark types', () => {
+    expect(MARK_TYPES.size).toBe(11);
   });
 
   it('contains expected types', () => {
@@ -167,6 +168,7 @@ describe('MARK_TYPES', () => {
       'rule',
       'tick',
       'rect',
+      'lollipop',
     ];
     for (const t of expected) {
       expect(MARK_TYPES.has(t)).toBe(true);

package/src/types/encoding.ts

@@ -110,8 +110,8 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     detail: optional('nominal'),
   },
   point: {
-    x: required('quantitative'),
-    y: required('quantitative'),
+    x: required('quantitative', 'temporal', 'nominal', 'ordinal'),
+    y: required('quantitative', 'temporal', 'nominal', 'ordinal'),
     color: optional('nominal', 'ordinal', 'quantitative'),
     size: optional('quantitative'),
     shape: optional('nominal', 'ordinal'),
@@ -132,6 +132,17 @@ export const MARK_ENCODING_RULES: Record<MarkType, EncodingRule> = {
     order: optional('quantitative', 'ordinal'),
     detail: optional('nominal'),
   },
+  lollipop: {
+    x: required('quantitative'),
+    y: required('nominal', 'ordinal'),
+    color: optional('nominal', 'ordinal', 'quantitative'),
+    size: optional('quantitative'),
+    opacity: optional('quantitative'),
+    tooltip: optional(),
+    href: optional(),
+    order: optional('quantitative', 'ordinal'),
+    detail: optional('nominal'),
+  },
   arc: {
     x: optional(),
     y: required('quantitative'),

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

@@ -42,7 +42,8 @@ export type MarkType =
   | 'text'
   | 'rule'
   | 'tick'
-  | 'rect';
+  | 'rect'
+  | 'lollipop';
 
 /** @deprecated Use MarkType instead. Kept for internal migration references. */
 export type ChartType = MarkType;
@@ -381,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. */
@@ -567,6 +570,10 @@ export interface LegendConfig {
   offset?: AnnotationOffset;
   /** Whether to show the legend. Defaults to true. Set to false to hide. */
   show?: boolean;
+  /** Number of columns for horizontal legend layout. Overrides the default row limit. */
+  columns?: number;
+  /** Max number of legend entries before truncation. Remaining entries show as "+N more". */
+  symbolLimit?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -1007,6 +1014,7 @@ export const MARK_TYPES: ReadonlySet<string> = new Set<MarkType>([
   'rule',
   'tick',
   'rect',
+  'lollipop',
 ]);
 
 /** @deprecated Use MARK_TYPES instead. */
@@ -1085,4 +1093,5 @@ export const MARK_DISPLAY_NAMES: Record<MarkType, string> = {
   rule: 'Rule chart',
   tick: 'Tick plot',
   rect: 'Heatmap',
+  lollipop: 'Lollipop chart',
 };