@opendata-ai/openchart-core 6.28.6 → 7.0.0

package/src/theme/defaults.ts

@@ -1,9 +1,12 @@
 /**
  * Default theme definition.
  *
- * Tuned to match Infrographic's visual weight and editorial style.
- * Inter font family, typography hierarchy for chrome, and color
- * palettes from the colors module.
+ * Editorial design system with cyan-led categorical palette, Inter
+ * Variable typography (weights 400/510/590), and zinc-based achromatic
+ * surfaces. Light is the default surface; dark adaptation lives in
+ * dark-mode.ts.
+ *
+ * resolveTheme() deep-merges user overrides onto this base.
  */
 
 import { CATEGORICAL_PALETTE, DIVERGING_PALETTES, SEQUENTIAL_PALETTES } from '../colors/palettes';
@@ -11,7 +14,6 @@ import type { Theme } from '../types/theme';
 
 /**
  * The default theme. All fields are required and fully specified.
- * resolveTheme() deep-merges user overrides onto this base.
  */
 export const DEFAULT_THEME: Theme = {
   colors: {
@@ -19,26 +21,32 @@ export const DEFAULT_THEME: Theme = {
     sequential: SEQUENTIAL_PALETTES,
     diverging: DIVERGING_PALETTES,
     background: '#ffffff',
-    text: '#1d1d1d',
-    gridline: '#e8e8e8',
-    axis: '#888888',
+    text: '#09090b',
+    gridline: 'rgba(0,0,0,0.06)',
+    // Used for axis lines/ticks AND axis tick label fill. Must clear WCAG AA
+    // contrast (4.5:1) on white because tick labels are rendered with this
+    // color. Zinc-500 hits ~5.7:1.
+    axis: '#71717a',
     annotationFill: 'rgba(0,0,0,0.04)',
-    annotationText: '#555555',
+    annotationText: '#71717a',
+    positive: '#16a34a',
+    negative: '#dc2626',
   },
   fonts: {
-    family: 'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    family:
+      '"Inter Variable", Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
     mono: '"JetBrains Mono", "Fira Code", "Cascadia Code", monospace',
     sizes: {
-      title: 22,
-      subtitle: 15,
+      title: 26,
+      subtitle: 14,
       body: 13,
       small: 11,
       axisTick: 11,
     },
     weights: {
       normal: 400,
-      medium: 500,
-      semibold: 600,
+      medium: 510,
+      semibold: 590,
       bold: 700,
     },
   },
@@ -49,37 +57,43 @@ export const DEFAULT_THEME: Theme = {
     chartToFooter: 8,
     axisMargin: 6,
   },
-  borderRadius: 4,
+  borderRadius: 2,
   chrome: {
+    eyebrow: {
+      fontSize: 11,
+      fontWeight: 510,
+      color: '#06b6d4',
+      lineHeight: 1.4,
+    },
     title: {
-      fontSize: 22,
-      fontWeight: 700,
-      color: '#333333',
-      lineHeight: 1.3,
+      fontSize: 26,
+      fontWeight: 590,
+      color: '#09090b',
+      lineHeight: 1.15,
     },
     subtitle: {
-      fontSize: 15,
+      fontSize: 14,
       fontWeight: 400,
-      color: '#666666',
-      lineHeight: 1.4,
+      color: '#71717a',
+      lineHeight: 1.45,
     },
     source: {
-      fontSize: 12,
+      fontSize: 11,
       fontWeight: 400,
-      color: '#999999',
-      lineHeight: 1.3,
+      color: '#71717a',
+      lineHeight: 1.4,
     },
     byline: {
-      fontSize: 12,
+      fontSize: 11,
       fontWeight: 400,
-      color: '#999999',
-      lineHeight: 1.3,
+      color: '#71717a',
+      lineHeight: 1.4,
     },
     footer: {
-      fontSize: 12,
+      fontSize: 11,
       fontWeight: 400,
-      color: '#999999',
-      lineHeight: 1.3,
+      color: '#71717a',
+      lineHeight: 1.4,
     },
   },
 };

package/src/theme/index.ts

@@ -2,6 +2,6 @@
  * Theme module barrel export.
  */
 
-export { adaptColorForDarkMode, adaptTheme } from './dark-mode';
+export { adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme } from './dark-mode';
 export { DEFAULT_THEME } from './defaults';
 export { resolveTheme } from './resolve';

package/src/theme/resolve.ts

@@ -118,6 +118,8 @@ function adaptChromeForDarkBg(theme: Theme, textColor: string): Theme {
   return {
     ...theme,
     chrome: {
+      // Eyebrow keeps its accent tint regardless of surface mode.
+      eyebrow: theme.chrome.eyebrow,
       title: {
         ...theme.chrome.title,
         color:

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

@@ -22,7 +22,7 @@ import {
 // Test data factories
 // ---------------------------------------------------------------------------
 
-function makeChartSpec(overrides?: Partial<ChartSpec>): ChartSpec {
+function makeChartSpec(): ChartSpec {
   return {
     mark: 'line',
     data: [
@@ -33,7 +33,6 @@ function makeChartSpec(overrides?: Partial<ChartSpec>): ChartSpec {
       x: { field: 'date', type: 'temporal' },
       y: { field: 'value', type: 'quantitative' },
     },
-    ...overrides,
   };
 }
 
@@ -70,22 +69,10 @@ function makeGraphSpec(overrides?: Partial<GraphSpec>): GraphSpec {
 
 describe('isChartSpec', () => {
   it('returns true for all mark types', () => {
-    const markTypes = [
-      'line',
-      'area',
-      'bar',
-      'point',
-      'circle',
-      'arc',
-      'text',
-      'rule',
-      'tick',
-      'rect',
-      'lollipop',
-    ] as const;
-
-    for (const markType of markTypes) {
-      const spec = makeChartSpec({ mark: markType });
+    // isChartSpec is a runtime guard that only checks for the presence of `mark`.
+    // Use `as ChartSpec` here since we're testing the guard, not encoding validity.
+    for (const markType of MARK_TYPES) {
+      const spec = { mark: markType, data: [], encoding: {} } as ChartSpec;
       expect(isChartSpec(spec)).toBe(true);
     }
   });
@@ -426,3 +413,83 @@ describe('type-level spec construction', () => {
     expect(spec.edges).toHaveLength(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Negative type tests (compile-time rejection verification)
+//
+// Each variable below is annotated with @ts-expect-error on the line that
+// should be rejected. If any @ts-expect-error becomes "unused" (no error),
+// TypeScript will fail the build — meaning the type guarantee regressed.
+// ---------------------------------------------------------------------------
+
+describe('type-level rejection', () => {
+  it('compiles with @ts-expect-error annotations intact (runtime no-op)', () => {
+    // Arc requires y + color. Missing color must error.
+    const _arcMissingColor: ChartSpec = {
+      mark: 'arc',
+      data: [],
+      // @ts-expect-error ArcEncoding requires color channel
+      encoding: {
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    // Text mark requires text channel. Missing text must error.
+    const _textMissingText: ChartSpec = {
+      mark: 'text',
+      data: [],
+      // @ts-expect-error TextEncoding requires text channel
+      encoding: {},
+    };
+
+    // Typed spec: field typo must error when TData is provided.
+    type SalesRow = { date: string; revenue: number };
+    const _typoField: ChartSpec<SalesRow> = {
+      mark: 'line',
+      data: [],
+      encoding: {
+        // @ts-expect-error 'dat' is not a key of SalesRow — did you mean 'date'?
+        x: { field: 'dat', type: 'temporal' },
+        y: { field: 'revenue', type: 'quantitative' },
+      },
+    };
+
+    // Valid typed spec must compile without errors.
+    const _validTyped: ChartSpec<SalesRow> = {
+      mark: 'line',
+      data: [{ date: '2024-01', revenue: 100 }],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'revenue', type: 'quantitative' },
+      },
+    };
+
+    // Arc without theta must compile (theta is optional per MARK_ENCODING_RULES).
+    const _arcNoTheta: ChartSpec = {
+      mark: 'arc',
+      data: [],
+      encoding: {
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'category', type: 'nominal' },
+      },
+    };
+
+    // Untyped spec (no TData param) must compile — no migration cost.
+    const _untypedSpec: ChartSpec = {
+      mark: 'line',
+      data: [],
+      encoding: {
+        x: { field: 'anything', type: 'temporal' },
+        y: { field: 'anything', type: 'quantitative' },
+      },
+    };
+
+    void _arcMissingColor;
+    void _textMissingText;
+    void _typoField;
+    void _validTyped;
+    void _arcNoTheta;
+    void _untypedSpec;
+    expect(true).toBe(true);
+  });
+});

package/src/types/index.ts

@@ -42,6 +42,8 @@ export type {
   ChartLayout,
   CompileOptions,
   CompileTableOptions,
+  EndpointLabelEntry,
+  EndpointLabelsLayout,
   FlagTableCell,
   GradientColorStop,
   GradientLegendLayout,
@@ -69,6 +71,8 @@ export type {
   ResolvedChromeElement,
   ResolvedColumn,
   ResolvedLabel,
+  ResolvedMetricBar,
+  ResolvedMetricCell,
   RuleMarkLayout,
   SankeyLayout,
   SankeyLinkMark,
@@ -101,7 +105,10 @@ export type {
   Annotation,
   AnnotationAnchor,
   AnnotationOffset,
+  ArcEncoding,
+  AreaEncoding,
   AxisConfig,
+  BarEncoding,
   BarListEncoding,
   BarListSpec,
   BarListSpecWithoutData,
@@ -116,6 +123,7 @@ export type {
   Chrome,
   ChromeText,
   ChromeTextStyle,
+  CircleEncoding,
   Condition,
   ConditionalValueDef,
   DarkMode,
@@ -123,6 +131,7 @@ export type {
   Display,
   Encoding,
   EncodingChannel,
+  EndpointLabelsConfig,
   FieldPredicate,
   FieldType,
   FilterPredicate,
@@ -143,14 +152,19 @@ export type {
   LayerSpec,
   LegendConfig,
   LinearGradient,
+  LineEncoding,
   LogicalAnd,
   LogicalNot,
   LogicalOr,
+  LollipopEncoding,
   MarkDef,
   MarkType,
+  Metric,
   NodeOverride,
+  PointEncoding,
   RadialGradient,
   RangeAnnotation,
+  RectEncoding,
   RefLineAnnotation,
   RelativeTimeRef,
   ResolveConfig,
@@ -167,7 +181,9 @@ export type {
   TableSpec,
   TableSpecWithoutData,
   TextAnnotation,
+  TextEncoding,
   ThemeConfig,
+  TickEncoding,
   TileMapEncoding,
   TileMapPalette,
   TileMapSpec,

package/src/types/layout.ts

@@ -102,11 +102,13 @@ export interface ResolvedChrome {
   /** Total height consumed by chrome elements below the chart area. */
   bottomHeight: number;
   /** Resolved chrome elements. Only present if specified in the spec. */
+  eyebrow?: ResolvedChromeElement;
   title?: ResolvedChromeElement;
   subtitle?: ResolvedChromeElement;
   source?: ResolvedChromeElement;
   byline?: ResolvedChromeElement;
   footer?: ResolvedChromeElement;
+  brand?: ResolvedChromeElement;
 }
 
 // ---------------------------------------------------------------------------
@@ -167,6 +169,13 @@ export interface AxisLayout {
   labelOverlap?: boolean | 'parity' | 'greedy';
   /** Whether to flush labels to the axis edges. */
   labelFlush?: boolean;
+  /**
+   * Where tick labels render relative to the chart area.
+   * `'inline'` puts y-axis labels above their gridlines at chart-area x and
+   * suppresses the axis line and tick marks. `'gutter'` (default) keeps the
+   * classic outside-the-area placement.
+   */
+  tickPosition?: 'inline' | 'gutter';
 }
 
 // ---------------------------------------------------------------------------
@@ -175,12 +184,17 @@ export interface AxisLayout {
 
 /** Accessibility attributes for a mark. */
 export interface MarkAria {
-  /** ARIA label for the mark. */
-  label: string;
+  /** ARIA label for the mark. Optional when `decorative: true` — decorative
+   *  marks render with `aria-hidden="true"` and don't need a label. */
+  label?: string;
   /** Optional longer description. */
   description?: string;
   /** ARIA role override. */
   role?: string;
+  /** When true, the mark is purely decorative (e.g. a sparkline endpoint dot
+   *  that duplicates an existing data point). Renderers translate this into
+   *  `aria-hidden="true"` and skip the mark from the screen-reader data table. */
+  decorative?: boolean;
 }
 
 /**
@@ -292,6 +306,13 @@ export interface RectMark {
   strokeWidth?: number;
   /** Corner radius. */
   cornerRadius?: number;
+  /**
+   * Which corners receive `cornerRadius`. Defaults to all four when unset.
+   * Used by stacked bars/columns to round only the leading edge of the
+   * topmost (vertical) or rightmost (horizontal) segment so the seams
+   * between stacked segments stay square and visually contiguous.
+   */
+  cornerRadiusSides?: { tl?: boolean; tr?: boolean; br?: boolean; bl?: boolean };
   /** Original data row. */
   data: Record<string, unknown>;
   /** Resolved label. */
@@ -512,12 +533,14 @@ export interface ResolvedLabel {
   connector?: {
     /** Connector start (at the label). */
     from: Point;
-    /** Connector end (at the data point). */
+    /** Connector end (pulled back from the data point so the line doesn't touch it). */
     to: Point;
+    /** Actual data point the connector is calling out. Renderer uses this for the endpoint marker. */
+    endpoint?: Point;
     /** Connector line color. */
     stroke: string;
-    /** Connector style: straight line or curved arrow. */
-    style: 'straight' | 'curve';
+    /** Connector style: straight line, curved arrow, or vertical drop-line through the data point. */
+    style: 'straight' | 'curve' | 'drop-line';
   };
   /** Background color behind the label text. */
   background?: string;
@@ -553,6 +576,28 @@ export interface ResolvedAnnotation {
   strokeWidth?: number;
   /** Z-index for render ordering. Higher values render on top. */
   zIndex?: number;
+  /**
+   * For text annotations: optional dot marker drawn at the connector's
+   * data-point endpoint. Coordinates match `label.connector.to` exactly.
+   */
+  dot?: {
+    x: number;
+    y: number;
+    radius: number;
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+  };
+  /**
+   * For text annotations: optional muted subtitle rendered below the primary
+   * label. Positioned `lineHeight * primaryLineCount + gap` below `label.y`.
+   */
+  subtitle?: {
+    text: string;
+    x: number;
+    y: number;
+    style: TextStyle;
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -595,6 +640,8 @@ export interface CategoricalLegendLayout extends BaseLegendLayout {
   swatchGap: number;
   /** Gap between entries. */
   entryGap: number;
+  /** Fill color for the rounded chip background behind the colored bar. */
+  swatchChipFill: string;
 }
 
 /** A color stop in a gradient legend. */
@@ -622,6 +669,61 @@ export interface GradientLegendLayout extends BaseLegendLayout {
 /** Resolved legend layout — either categorical (swatches) or gradient (continuous bar). */
 export type LegendLayout = CategoricalLegendLayout | GradientLegendLayout;
 
+// ---------------------------------------------------------------------------
+// Endpoint labels (right-side per-series column for line/area charts)
+// ---------------------------------------------------------------------------
+
+/** A single resolved endpoint-label entry, fully positioned. */
+export interface EndpointLabelEntry {
+  /** Series identifier (matches mark.seriesKey). */
+  seriesKey: string;
+  /** Pre-wrapped label text lines. */
+  labelLines: string[];
+  /** Formatted value string for the last data point. */
+  value: string;
+  /** Series color. */
+  color: string;
+  /** True pixel y of the last data point on the line. */
+  dataY: number;
+  /** Displaced y after the bidirectional collision sweep. */
+  labelY: number;
+  /** True when |labelY - dataY| exceeds the threshold (renderer draws a leader line). */
+  showLeader: boolean;
+  /** Optional anchor circle drawn on the line at the chart's right edge. */
+  marker?: {
+    x: number;
+    y: number;
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+    radius: number;
+  };
+}
+
+/** Resolved layout for the endpoint labels column. */
+export interface EndpointLabelsLayout {
+  /** Per-series resolved entries. */
+  entries: EndpointLabelEntry[];
+  /** Bounding box for the column. */
+  bounds: Rect;
+  /** Style for the series-name text. */
+  labelStyle: TextStyle;
+  /** Style for the formatted value text. */
+  valueStyle: TextStyle;
+  /** Width of the colored swatch line drawn left of the label. */
+  swatchSize: number;
+  /** Horizontal gap between swatch and label text. */
+  gap: number;
+  /**
+   * Vertical gap between the last wrapped label line and the value text
+   * directly below it. Resolved by the engine so the renderer can't drift
+   * away from the height the collision sweep budgeted for each entry.
+   */
+  valueGap: number;
+  /** Fill color for the rounded chip background behind the colored bar. */
+  swatchChipFill: string;
+}
+
 // ---------------------------------------------------------------------------
 // Tooltips
 // ---------------------------------------------------------------------------
@@ -680,6 +782,42 @@ export interface ResolvedAnimation {
   annotationDelay: number;
 }
 
+// ---------------------------------------------------------------------------
+// Metric bar (resolved)
+// ---------------------------------------------------------------------------
+
+/**
+ * A resolved KPI metric cell with computed positions for label, value, and
+ * supplementary text spans. Cells render as a row above the chart area.
+ */
+export interface ResolvedMetricCell {
+  /** Cell left x in layout coordinates. */
+  x: number;
+  /** Cell width. */
+  cellWidth: number;
+  /** Baseline y for the uppercase label. */
+  labelY: number;
+  /** Baseline y for the primary value. */
+  valueY: number;
+  /** The original metric spec (label/value/delta/etc.). */
+  metric: import('./spec').Metric;
+  /** True if value+delta+secondary would overflow cellWidth. Set by layout for diagnostics. */
+  overflowed: boolean;
+}
+
+/**
+ * The full metric-bar layout. Present only when spec.metrics is supplied
+ * and the bar fits the container.
+ */
+export interface ResolvedMetricBar {
+  /** Top y of the metric row in layout coordinates. */
+  y: number;
+  /** Total reserved height of the row. */
+  height: number;
+  /** Cells laid out evenly across the chart width. */
+  cells: ResolvedMetricCell[];
+}
+
 // ---------------------------------------------------------------------------
 // ChartLayout (the main engine output for charts)
 // ---------------------------------------------------------------------------
@@ -697,6 +835,8 @@ export interface ChartLayout {
   area: Rect;
   /** Resolved chrome text elements with positions and styles. */
   chrome: ResolvedChrome;
+  /** Resolved KPI metric bar. Present only when spec.metrics is supplied and fits. */
+  metrics?: ResolvedMetricBar;
   /** Resolved axis layouts. */
   axes: {
     x?: AxisLayout;
@@ -710,6 +850,12 @@ export interface ChartLayout {
   annotations: ResolvedAnnotation[];
   /** Legend layout (position, entries, bounds). */
   legend: LegendLayout;
+  /**
+   * Right-side endpoint labels column for multi-series line/area charts.
+   * Empty `entries` means the column is suppressed (single-series, opt-out, or
+   * auto-suppressed by the truth table).
+   */
+  endpointLabels?: EndpointLabelsLayout;
   /** Tooltip descriptors keyed by a mark identifier. */
   tooltipDescriptors: Map<string, TooltipContent>;
   /** Accessibility metadata. */