@opendata-ai/openchart-core 7.2.1 → 7.2.3

package/package.json

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

package/src/index.ts

@@ -82,6 +82,7 @@ export {
   AXIS_TITLE_OFFSET_COMPACT,
   AXIS_TITLE_OFFSET_DEFAULT,
   AXIS_TITLE_TRAILING_PAD,
+  axisTitleOffset,
   BREAKPOINT_COMPACT_MAX,
   BREAKPOINT_MEDIUM_MAX,
   getAxisTitleOffset,

package/src/responsive/__tests__/metrics.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import {
+  AXIS_TITLE_GAP,
+  AXIS_TITLE_OFFSET_DEFAULT,
+  axisTitleOffset,
+  TICK_LABEL_OFFSET,
+} from '../metrics';
+
+// The rotated y-axis title is anchored at its center and its glyph box extends
+// half the title font size toward the tick labels. axisTitleOffset() returns the
+// distance from the chart edge to that center; visible clearance between the
+// widest tick label and the title's near edge is therefore:
+//   offset - TICK_LABEL_OFFSET - tickLabelWidth - titleFontSize / 2
+const visibleClearance = (offset: number, tickLabelWidth: number, titleFontSize: number): number =>
+  offset - TICK_LABEL_OFFSET - tickLabelWidth - titleFontSize / 2;
+
+describe('axisTitleOffset', () => {
+  const WIDE = 1200; // wide viewport so the dynamic value wins over the floor
+
+  it('leaves the title clear of the tick labels at the default font size', () => {
+    const offset = axisTitleOffset(40, 13, WIDE);
+    // ~AXIS_TITLE_GAP of clearance, never overlapping (negative).
+    expect(visibleClearance(offset, 40, 13)).toBeGreaterThanOrEqual(AXIS_TITLE_GAP - 1);
+  });
+
+  it('keeps clearance constant as the title font size grows', () => {
+    // The original bug: a fixed gap let large title fonts overlap the tick
+    // labels because the title's half-glyph ate into the gap. Clearance must
+    // stay ~AXIS_TITLE_GAP regardless of how big the title font is.
+    const small = visibleClearance(axisTitleOffset(40, 13, WIDE), 40, 13);
+    const large = visibleClearance(axisTitleOffset(40, 30, WIDE), 40, 30);
+
+    expect(large).toBeGreaterThanOrEqual(AXIS_TITLE_GAP - 1);
+    expect(Math.abs(large - small)).toBeLessThanOrEqual(1); // rounding only
+  });
+
+  it('pushes the title further left as tick labels get wider', () => {
+    // Both label widths sit above the viewport floor, so the offset tracks the
+    // label width 1:1 (a 60px wider label moves the title 60px further left).
+    const narrow = axisTitleOffset(50, 13, WIDE);
+    const wide = axisTitleOffset(110, 13, WIDE);
+    expect(narrow).toBeGreaterThan(AXIS_TITLE_OFFSET_DEFAULT); // floor not in play
+    expect(wide - narrow).toBeCloseTo(60, 0);
+  });
+
+  it('falls back to the viewport-minimum offset for short labels on wide containers', () => {
+    // Tiny label + small font: the dynamic value is below the floor, so the
+    // floor wins (prevents the title from hugging the chart edge).
+    const offset = axisTitleOffset(2, 11, WIDE);
+    expect(offset).toBe(AXIS_TITLE_OFFSET_DEFAULT);
+  });
+});

package/src/responsive/index.ts

@@ -26,6 +26,7 @@ export {
   AXIS_TITLE_OFFSET_COMPACT,
   AXIS_TITLE_OFFSET_DEFAULT,
   AXIS_TITLE_TRAILING_PAD,
+  axisTitleOffset,
   getAxisTitleOffset,
   HPAD_COMPACT_FRACTION,
   HPAD_COMPACT_MIN,

package/src/responsive/metrics.ts

@@ -64,15 +64,41 @@ export const AXIS_TITLE_TRAILING_PAD = 4;
 // ---------------------------------------------------------------------------
 
 /**
- * Breathing room between the widest tick label's far edge and the rotated
- * y-axis title center. The title glyph extends ~halfGlyph (ceil(bodyFontSize/2))
- * from its center toward the tick labels, so visible clearance is
- * AXIS_TITLE_GAP - halfGlyph (~7px at default body size 13).
+ * Visible breathing room between the widest tick label's far edge and the
+ * rotated y-axis title's near edge.
+ *
+ * The title is rotated -90deg and anchored at its center, so its glyph box
+ * extends half the title font size toward the tick labels. To keep the gap
+ * constant regardless of title font size, callers add that half-glyph on top
+ * of this value (see axisTitleOffset() below). At the old fixed gap of 14 the
+ * clearance silently shrank as the font grew (14 - 11 = 3px at body size 21),
+ * which let large-font titles collide with the tick labels.
  *
  * Used in both the engine (dimensions.ts margin reservation) and the renderer
- * (axes.ts title placement). Both must agree on this value.
+ * (axes.ts title placement) via axisTitleOffset(). Both must agree on this value.
  */
-export const AXIS_TITLE_GAP = 14;
+export const AXIS_TITLE_GAP = 7;
+
+/**
+ * Computes the distance from the chart edge to the rotated y-axis title's center.
+ *
+ * The title center must sit far enough left that, after accounting for the
+ * widest tick label and the title's own half-glyph height, AXIS_TITLE_GAP of
+ * visible clearance remains. Falls back to the viewport-minimum offset when the
+ * dynamic value would be smaller (short tick labels on wide containers).
+ *
+ * Shared by the engine (margin reservation) and the renderer (title placement)
+ * so the reserved space always matches where the title is drawn.
+ */
+export function axisTitleOffset(
+  maxTickLabelWidth: number,
+  titleFontSize: number,
+  width: number,
+): number {
+  const halfTitleGlyph = Math.ceil(titleFontSize / 2);
+  const dynamic = TICK_LABEL_OFFSET + maxTickLabelWidth + AXIS_TITLE_GAP + halfTitleGlyph;
+  return Math.max(dynamic, getAxisTitleOffset(width));
+}
 
 // ---------------------------------------------------------------------------
 // Narrow viewport threshold (between compact and medium)

package/src/theme/defaults.ts

@@ -42,6 +42,8 @@ export const DEFAULT_THEME: Theme = {
       body: 13,
       small: 11,
       axisTick: 11,
+      metricLabel: 10,
+      metricValue: 22,
     },
     weights: {
       normal: 450,
@@ -57,7 +59,10 @@ export const DEFAULT_THEME: Theme = {
     chartToFooter: 8,
     axisMargin: 6,
     xAxisHeight: 26,
-    xAxisLabelPadding: 14,
+    // Gap (px) between the x-axis line and the TOP of the tick labels. The
+    // renderer anchors x-tick labels at their top edge (hanging baseline), so
+    // this is a literal top gap that holds regardless of font size.
+    xAxisLabelPadding: 4,
   },
   borderRadius: 2,
   chrome: {

package/src/types/spec.ts

@@ -727,10 +727,24 @@ export interface RangeAnnotation extends AnnotationBase {
   y1?: string | number;
   /** End of the range on the y-axis. */
   y2?: string | number;
+  /**
+   * For band/point (ordinal) x or y scales, whether the range extends from the
+   * data point's center out to the band/step edge. Default `true`: a range on a
+   * bar chart spans full columns, and a range on a line chart extends half a step
+   * past the first/last point so the band reaches the plot edge. Set `false` to
+   * anchor the range exactly at the data point centers instead — useful when you
+   * want the band inset from the axis (e.g. starting at the first data point
+   * rather than flush against the y-axis guide). No effect on linear/time scales.
+   */
+  extendToEdges?: boolean;
   /** Pixel offset for the range label. */
   labelOffset?: AnnotationOffset;
   /** Anchor direction for the range label. */
   labelAnchor?: AnnotationAnchor;
+  /** Font size override for the range label (px). Default: 11. */
+  fontSize?: number;
+  /** Font weight override for the range label. Default: 500. */
+  fontWeight?: number;
 }
 
 /**
@@ -753,6 +767,10 @@ export interface RefLineAnnotation extends AnnotationBase {
   labelOffset?: AnnotationOffset;
   /** Anchor direction for the reference line label. */
   labelAnchor?: AnnotationAnchor;
+  /** Label font size in pixels. Default: 11. */
+  fontSize?: number;
+  /** Label font weight. Default: 400. */
+  fontWeight?: number;
 }
 
 /** Discriminated union of all annotation types. */
@@ -824,6 +842,10 @@ export interface ThemeConfig {
       small?: number;
       /** Axis tick labels. Default: 11. */
       axisTick?: number;
+      /** KPI metric uppercase label. Default: 10. */
+      metricLabel?: number;
+      /** KPI metric primary value. Default: 22. Delta/secondary derive from this. */
+      metricValue?: number;
     };
   };
   /** Spacing overrides in pixels. */

package/src/types/theme.ts

@@ -51,6 +51,11 @@ export interface ThemeFontSizes {
   small: number;
   /** Axis tick label font size in pixels. */
   axisTick: number;
+  /** KPI metric uppercase label font size in pixels. */
+  metricLabel: number;
+  /** KPI metric primary value font size in pixels. The delta and secondary
+   *  values derive from this (each ~0.55x), so scaling this scales the whole cell. */
+  metricValue: number;
 }
 
 /** Font weight presets. */