@opendata-ai/openchart-core 6.2.0 → 6.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "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/locale/format.ts

@@ -136,26 +136,32 @@ const GRANULARITY_FORMATS: Record<DateGranularity, string> = {
  * @param value - Date object, ISO string, or timestamp number.
  * @param locale - Locale string (currently unused, reserved for i18n).
  * @param granularity - Time granularity for format selection.
+ * @param useUtc - Whether to infer granularity and format using UTC methods.
+ *   Pass `false` when formatting ticks from a local-time scale (d3 scaleTime),
+ *   so that e.g. midnight local isn't misread as an intra-day UTC time.
+ *   Defaults to `true` for backward compatibility.
  */
 export function formatDate(
   value: Date | string | number,
   _locale?: string,
   granularity?: DateGranularity,
+  useUtc: boolean = true,
 ): string {
   const date = value instanceof Date ? value : new Date(value);
   if (Number.isNaN(date.getTime())) return String(value);
 
-  const gran = granularity ?? inferGranularity(date);
+  const gran = granularity ?? inferGranularity(date, useUtc);
 
   // Special handling for quarter (not a d3 format token)
   if (gran === 'quarter') {
-    const q = Math.ceil((date.getMonth() + 1) / 3);
+    const q = useUtc
+      ? Math.ceil((date.getUTCMonth() + 1) / 3)
+      : Math.ceil((date.getMonth() + 1) / 3);
     return `Q${q} ${date.getFullYear()}`;
   }
 
   const formatStr = GRANULARITY_FORMATS[gran];
-  // Use UTC format for year/month/day to avoid timezone shifts
-  if (['year', 'month', 'day'].includes(gran)) {
+  if (useUtc) {
     return utcFormat(formatStr)(date);
   }
   return timeFormat(formatStr)(date);
@@ -181,12 +187,20 @@ export function buildTemporalFormatter(
 /**
  * Infer the appropriate granularity from a date value.
  * If time components are all zero, assume day or higher.
+ *
+ * @param useUtc - When true, inspect UTC fields. When false, inspect local-time
+ *   fields. This must match the D3 scale type: scaleUtc -> true, scaleTime -> false.
  */
-function inferGranularity(date: Date): DateGranularity {
-  if (date.getUTCHours() !== 0 || date.getUTCMinutes() !== 0) {
-    return date.getUTCMinutes() !== 0 ? 'minute' : 'hour';
+function inferGranularity(date: Date, useUtc: boolean = true): DateGranularity {
+  const hours = useUtc ? date.getUTCHours() : date.getHours();
+  const minutes = useUtc ? date.getUTCMinutes() : date.getMinutes();
+  const day = useUtc ? date.getUTCDate() : date.getDate();
+  const month = useUtc ? date.getUTCMonth() : date.getMonth();
+
+  if (hours !== 0 || minutes !== 0) {
+    return minutes !== 0 ? 'minute' : 'hour';
   }
-  if (date.getUTCDate() !== 1) return 'day';
-  if (date.getUTCMonth() !== 0) return 'month';
+  if (day !== 1) return 'day';
+  if (month !== 0) return 'month';
   return 'year';
 }

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/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;
@@ -567,6 +568,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 +1012,7 @@ export const MARK_TYPES: ReadonlySet<string> = new Set<MarkType>([
   'rule',
   'tick',
   'rect',
+  'lollipop',
 ]);
 
 /** @deprecated Use MARK_TYPES instead. */
@@ -1085,4 +1091,5 @@ export const MARK_DISPLAY_NAMES: Record<MarkType, string> = {
   rule: 'Rule chart',
   tick: 'Tick plot',
   rect: 'Heatmap',
+  lollipop: 'Lollipop chart',
 };