@opendata-ai/openchart-core 6.24.2 → 6.25.1

package/package.json

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

package/src/index.ts

@@ -77,9 +77,30 @@ export type {
   LegendPosition,
 } from './responsive/index';
 export {
+  AXIS_TITLE_OFFSET_COMPACT,
+  AXIS_TITLE_OFFSET_DEFAULT,
+  AXIS_TITLE_TRAILING_PAD,
+  BREAKPOINT_COMPACT_MAX,
+  BREAKPOINT_MEDIUM_MAX,
+  getAxisTitleOffset,
   getBreakpoint,
   getHeightClass,
   getLayoutStrategy,
+  HEIGHT_CRAMPED_MAX,
+  HEIGHT_SHORT_MAX,
+  HPAD_COMPACT_FRACTION,
+  HPAD_COMPACT_MIN,
+  LABEL_GAP_COMPACT,
+  LABEL_GAP_DEFAULT,
+  LABEL_GAP_NARROW_MAX,
+  MAX_LEFT_LABEL_FRACTION_COMPACT,
+  MAX_LEFT_LABEL_FRACTION_DEFAULT,
+  MAX_LEFT_LABEL_FRACTION_MEDIUM,
+  MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
+  NARROW_VIEWPORT_MAX,
+  TICK_LABEL_OFFSET,
+  TOP_PAD_EXTRA_NARROW,
+  TOP_PAD_NARROW_MAX,
 } from './responsive/index';
 
 // ---------------------------------------------------------------------------

package/src/responsive/index.ts

@@ -21,3 +21,22 @@ export {
   HEIGHT_CRAMPED_MAX,
   HEIGHT_SHORT_MAX,
 } from './breakpoints';
+export {
+  AXIS_TITLE_OFFSET_COMPACT,
+  AXIS_TITLE_OFFSET_DEFAULT,
+  AXIS_TITLE_TRAILING_PAD,
+  getAxisTitleOffset,
+  HPAD_COMPACT_FRACTION,
+  HPAD_COMPACT_MIN,
+  LABEL_GAP_COMPACT,
+  LABEL_GAP_DEFAULT,
+  LABEL_GAP_NARROW_MAX,
+  MAX_LEFT_LABEL_FRACTION_COMPACT,
+  MAX_LEFT_LABEL_FRACTION_DEFAULT,
+  MAX_LEFT_LABEL_FRACTION_MEDIUM,
+  MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
+  NARROW_VIEWPORT_MAX,
+  TICK_LABEL_OFFSET,
+  TOP_PAD_EXTRA_NARROW,
+  TOP_PAD_NARROW_MAX,
+} from './metrics';

package/src/responsive/metrics.ts

@@ -0,0 +1,114 @@
+/**
+ * Pixel-level responsive metrics for chart layout.
+ *
+ * These are the numeric tuning values that correspond to the semantic decisions
+ * in LayoutStrategy. Centralizing them here ensures the engine and renderer
+ * always agree on the same thresholds and offsets without duplicating raw numbers.
+ *
+ * LayoutStrategy is semantic (what to show), this module is metric (how much space).
+ */
+
+import { BREAKPOINT_COMPACT_MAX } from './breakpoints';
+
+// ---------------------------------------------------------------------------
+// Y-axis title offsets
+// ---------------------------------------------------------------------------
+
+/** Distance from the chart edge to the rotated y-axis title center (compact viewports). */
+export const AXIS_TITLE_OFFSET_COMPACT = 35;
+
+/** Distance from the chart edge to the rotated y-axis title center (standard viewports). */
+export const AXIS_TITLE_OFFSET_DEFAULT = 45;
+
+/** Returns the y-axis title offset appropriate for the given container width. */
+export function getAxisTitleOffset(width: number): number {
+  return width < BREAKPOINT_COMPACT_MAX ? AXIS_TITLE_OFFSET_COMPACT : AXIS_TITLE_OFFSET_DEFAULT;
+}
+
+// ---------------------------------------------------------------------------
+// Horizontal padding
+// ---------------------------------------------------------------------------
+
+/**
+ * On compact viewports axis titles and tick labels tolerate closer container edges
+ * than chrome text (title, subtitle). Reduce horizontal padding to reclaim space.
+ */
+export const HPAD_COMPACT_FRACTION = 0.5;
+
+/** Minimum horizontal padding regardless of scaling. */
+export const HPAD_COMPACT_MIN = 4;
+
+// ---------------------------------------------------------------------------
+// Tick label offset
+// ---------------------------------------------------------------------------
+
+/**
+ * Horizontal gap between the chart edge and the near edge of y-axis tick labels.
+ * The engine uses this to reserve right-axis margin; the renderer uses it to position labels.
+ * Both must agree on this value — do not change one without the other.
+ */
+export const TICK_LABEL_OFFSET = 6;
+
+// ---------------------------------------------------------------------------
+// Axis title trailing padding
+// ---------------------------------------------------------------------------
+
+/**
+ * Extra padding beyond half-glyph height added to the rotated axis title margin on
+ * standard (non-compact) viewports. Omitted on compact viewports to save space.
+ */
+export const AXIS_TITLE_TRAILING_PAD = 4;
+
+// ---------------------------------------------------------------------------
+// Narrow viewport threshold (between compact and medium)
+// ---------------------------------------------------------------------------
+
+/**
+ * Width below which "narrow" adjustments apply: extra iOS Safari top padding and
+ * tighter category label gaps. Sits between compact (< 400) and medium (400–700).
+ * Not a semantic breakpoint — a layout heuristic for narrow-but-not-compact containers.
+ */
+export const NARROW_VIEWPORT_MAX = 500;
+
+// ---------------------------------------------------------------------------
+// Top padding (iOS Safari address bar / notch clearance)
+// ---------------------------------------------------------------------------
+
+/** Extra top padding added below NARROW_VIEWPORT_MAX to clear iOS Safari browser chrome. */
+export const TOP_PAD_EXTRA_NARROW = 10;
+
+/** @deprecated Use NARROW_VIEWPORT_MAX instead. */
+export const TOP_PAD_NARROW_MAX = NARROW_VIEWPORT_MAX;
+
+// ---------------------------------------------------------------------------
+// Category label gaps (left-axis bar/dot charts)
+// ---------------------------------------------------------------------------
+
+/** Gap between category label text and chart edge on narrow viewports (< NARROW_VIEWPORT_MAX). */
+export const LABEL_GAP_COMPACT = 8;
+
+/** Gap between category label text and chart edge on standard viewports. */
+export const LABEL_GAP_DEFAULT = 12;
+
+/** @deprecated Use NARROW_VIEWPORT_MAX instead. */
+export const LABEL_GAP_NARROW_MAX = NARROW_VIEWPORT_MAX;
+
+// ---------------------------------------------------------------------------
+// Max left-axis label fraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Width threshold for the medium left-label fraction cap.
+ * Sits between medium (400-700) and full (> 700) to prevent wide category labels
+ * from consuming too much horizontal space at mid-range widths.
+ */
+export const MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX = 600;
+
+/** Max fraction of container width reservable for left category labels (compact). */
+export const MAX_LEFT_LABEL_FRACTION_COMPACT = 0.45;
+
+/** Max fraction of container width reservable for left category labels (mid-range). */
+export const MAX_LEFT_LABEL_FRACTION_MEDIUM = 0.55;
+
+/** Max fraction of container width reservable for left category labels (standard). */
+export const MAX_LEFT_LABEL_FRACTION_DEFAULT = 1;

package/src/types/layout.ts

@@ -220,6 +220,8 @@ export interface LineMark {
   aria: MarkAria;
   /** Index for stagger animation ordering. */
   animationIndex?: number;
+  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
+  yScale?: 'y' | 'y2';
 }
 
 /**
@@ -262,6 +264,8 @@ export interface AreaMark {
   aria: MarkAria;
   /** Index for stagger animation ordering. */
   animationIndex?: number;
+  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
+  yScale?: 'y' | 'y2';
 }
 
 /**
@@ -300,6 +304,8 @@ export interface RectMark {
   stackGroup?: string;
   /** Position of this segment within its stack group (0, 1, 2...). Set by engine for stacked bars. */
   stackPos?: number;
+  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
+  yScale?: 'y' | 'y2';
 }
 
 /**
@@ -366,6 +372,8 @@ export interface PointMark {
   aria: MarkAria;
   /** Index for stagger animation ordering. */
   animationIndex?: number;
+  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
+  yScale?: 'y' | 'y2';
 }
 
 /**
@@ -400,6 +408,8 @@ export interface TextMarkLayout {
   aria: MarkAria;
   /** Index for stagger animation ordering. */
   animationIndex?: number;
+  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
+  yScale?: 'y' | 'y2';
 }
 
 /**
@@ -430,6 +440,8 @@ export interface RuleMarkLayout {
   aria: MarkAria;
   /** Index for stagger animation ordering. */
   animationIndex?: number;
+  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
+  yScale?: 'y' | 'y2';
 }
 
 /**
@@ -458,6 +470,8 @@ export interface TickMarkLayout {
   aria: MarkAria;
   /** Index for stagger animation ordering. */
   animationIndex?: number;
+  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
+  yScale?: 'y' | 'y2';
 }
 
 /** Discriminated union of all mark types. */
@@ -654,6 +668,8 @@ export interface ChartLayout {
   axes: {
     x?: AxisLayout;
     y?: AxisLayout;
+    /** Right-side y-axis for independent-scale layers (dual-axis charts). */
+    y2?: AxisLayout;
   };
   /** Data marks: the visual representation of data points. */
   marks: Mark[];
@@ -1076,6 +1092,8 @@ export interface CompileOptions {
    * If not provided, the engine falls back to heuristic estimation.
    */
   measureText?: MeasureTextFn;
+  /** Extra pixels to reserve on the right margin for a secondary y-axis. Set by compileLayer when resolve.scale.y is 'independent'. */
+  rightAxisReserve?: number;
 }
 
 /** Extended compile options for table visualizations. */

package/src/types/spec.ts

@@ -238,6 +238,8 @@ export interface AxisConfig {
   titlePadding?: number;
   /** Padding between tick labels and axis. */
   labelPadding?: number;
+  /** Color override for axis tick labels and title. Useful in dual-axis charts to match axis color to its series. */
+  labelColor?: string;
 }
 
 /** Scale configuration for an encoding channel. */