@opendata-ai/openchart-core 6.1.4 → 6.2.0

package/package.json

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

package/src/index.ts

@@ -99,6 +99,7 @@ export type { DateGranularity } from './locale/index';
 export {
   abbreviateNumber,
   buildD3Formatter,
+  buildTemporalFormatter,
   formatDate,
   formatNumber,
 } from './locale/index';

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

@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { abbreviateNumber, buildD3Formatter, formatDate, formatNumber } from '../format';
+import {
+  abbreviateNumber,
+  buildD3Formatter,
+  buildTemporalFormatter,
+  formatDate,
+  formatNumber,
+} from '../format';
 
 describe('formatNumber', () => {
   it('formats integers with commas', () => {
@@ -126,4 +132,76 @@ describe('formatDate', () => {
     const result = formatDate('not-a-date');
     expect(result).toBe('not-a-date');
   });
+
+  it('infers year granularity for bare year strings regardless of timezone', () => {
+    // "2020" parses as 2020-01-01T00:00:00Z. In negative-offset timezones,
+    // local getHours()/getDate() would see Dec 31 2019 — the UTC fix prevents that.
+    const result = formatDate('2020');
+    expect(result).toBe('2020');
+  });
+
+  it('infers year granularity for Jan 1 ISO dates', () => {
+    const result = formatDate('2020-01-01');
+    expect(result).toBe('2020');
+  });
+
+  it('infers month granularity for first-of-month dates', () => {
+    const result = formatDate('2020-06-01');
+    expect(result).toContain('Jun');
+    expect(result).toContain('2020');
+  });
+
+  it('infers day granularity for mid-month dates', () => {
+    const result = formatDate('2020-06-15');
+    expect(result).toContain('15');
+    expect(result).toContain('Jun');
+  });
+});
+
+describe('buildTemporalFormatter', () => {
+  it('returns null for undefined format', () => {
+    expect(buildTemporalFormatter(undefined)).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(buildTemporalFormatter('')).toBeNull();
+  });
+
+  it('formats dates with %Y to just the year', () => {
+    const fmt = buildTemporalFormatter('%Y');
+    expect(fmt).not.toBeNull();
+    expect(fmt!('2020-01-01')).toBe('2020');
+    expect(fmt!(new Date('2020-06-15'))).toBe('2020');
+  });
+
+  it('formats dates with %b %Y to month and year', () => {
+    const fmt = buildTemporalFormatter('%b %Y');
+    expect(fmt).not.toBeNull();
+    expect(fmt!('2020-06-01')).toBe('Jun 2020');
+  });
+
+  it('formats dates with full date format', () => {
+    const fmt = buildTemporalFormatter('%Y-%m-%d');
+    expect(fmt).not.toBeNull();
+    expect(fmt!('2020-06-15')).toBe('2020-06-15');
+  });
+
+  it('handles invalid date input gracefully', () => {
+    const fmt = buildTemporalFormatter('%Y');
+    expect(fmt).not.toBeNull();
+    expect(fmt!('not-a-date')).toBe('not-a-date');
+  });
+
+  it('handles Date objects', () => {
+    const fmt = buildTemporalFormatter('%Y');
+    expect(fmt).not.toBeNull();
+    expect(fmt!(new Date('2025-01-01T00:00:00Z'))).toBe('2025');
+  });
+
+  it('handles numeric timestamps', () => {
+    const fmt = buildTemporalFormatter('%Y');
+    expect(fmt).not.toBeNull();
+    // 2020-01-01T00:00:00Z
+    expect(fmt!(1577836800000)).toBe('2020');
+  });
 });

package/src/locale/format.ts

@@ -161,15 +161,32 @@ export function formatDate(
   return timeFormat(formatStr)(date);
 }
 
+/**
+ * Build a formatter for temporal values using a d3-time-format string (e.g. "%Y", "%b %Y").
+ * Returns a function that accepts a Date, string, or number and returns the formatted string.
+ * Returns null if the format string is falsy.
+ */
+export function buildTemporalFormatter(
+  formatStr: string | undefined,
+): ((value: Date | string | number) => string) | null {
+  if (!formatStr) return null;
+  const fmt = utcFormat(formatStr);
+  return (value: Date | string | number) => {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) return String(value);
+    return fmt(date);
+  };
+}
+
 /**
  * Infer the appropriate granularity from a date value.
  * If time components are all zero, assume day or higher.
  */
 function inferGranularity(date: Date): DateGranularity {
-  if (date.getHours() !== 0 || date.getMinutes() !== 0) {
-    return date.getMinutes() !== 0 ? 'minute' : 'hour';
+  if (date.getUTCHours() !== 0 || date.getUTCMinutes() !== 0) {
+    return date.getUTCMinutes() !== 0 ? 'minute' : 'hour';
   }
-  if (date.getDate() !== 1) return 'day';
-  if (date.getMonth() !== 0) return 'month';
+  if (date.getUTCDate() !== 1) return 'day';
+  if (date.getUTCMonth() !== 0) return 'month';
   return 'year';
 }

package/src/locale/index.ts

@@ -3,4 +3,10 @@
  */
 
 export type { DateGranularity } from './format';
-export { abbreviateNumber, buildD3Formatter, formatDate, formatNumber } from './format';
+export {
+  abbreviateNumber,
+  buildD3Formatter,
+  buildTemporalFormatter,
+  formatDate,
+  formatNumber,
+} from './format';

package/src/types/spec.ts

@@ -273,12 +273,14 @@ export interface Encoding {
 // Graph-specific encoding
 // ---------------------------------------------------------------------------
 
-/** Encoding channel for graph nodes and edges. Same structure as EncodingChannel. */
+/** Encoding channel for graph nodes and edges. */
 export interface GraphEncodingChannel {
   /** Data field name on the node/edge object. */
   field: string;
   /** How to interpret the field values. */
   type?: FieldType;
+  /** Scale configuration. Auto-derived from data if omitted. */
+  scale?: ScaleConfig;
 }
 
 /** Graph-specific encoding mapping visual properties to node/edge data fields. */