@opendata-ai/openchart-core 2.9.1 → 2.10.0

package/package.json

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

package/src/index.ts

@@ -66,12 +66,15 @@ export type {
   AnnotationPosition,
   AxisLabelDensity,
   Breakpoint,
+  ChromeMode,
+  HeightClass,
   LabelMode,
   LayoutStrategy,
   LegendPosition,
 } from './responsive/index';
 export {
   getBreakpoint,
+  getHeightClass,
   getLayoutStrategy,
 } from './responsive/index';
 

package/src/layout/chrome.ts

@@ -3,8 +3,17 @@
  *
  * Takes a Chrome spec + resolved theme and produces a ResolvedChrome
  * with computed text positions, styles, and total chrome heights.
+ *
+ * Supports three chrome modes:
+ * - full: all chrome elements rendered at normal size
+ * - compact: title only, no subtitle/source/byline/footer
+ * - hidden: no chrome at all (maximizes chart area)
+ *
+ * Font sizes scale down continuously at narrow widths to keep
+ * chrome proportional to the container.
  */
 
+import type { ChromeMode } from '../responsive/breakpoints';
 import type {
   MeasureTextFn,
   ResolvedChrome,
@@ -28,16 +37,32 @@ function normalizeChromeText(
   return { text: value.text, style: value.style, offset: value.offset };
 }
 
-/** Build a TextStyle from chrome defaults + optional overrides. */
+/**
+ * Scale a font size based on container width. Only applies to default sizes
+ * (not user overrides). Scales from 100% at >= 500px down to 72% at <= 250px.
+ */
+function scaleFontSize(baseFontSize: number, width: number): number {
+  if (width >= 500) return baseFontSize;
+  if (width <= 250) return Math.max(Math.round(baseFontSize * 0.72), 10);
+  const t = (width - 250) / 250;
+  return Math.max(Math.round(baseFontSize * (0.72 + t * 0.28)), 10);
+}
+
+/** Build a TextStyle from chrome defaults + optional overrides, with width-based scaling. */
 function buildTextStyle(
   defaults: ChromeDefaults,
   fontFamily: string,
   textColor: string,
+  width: number,
   overrides?: ChromeText['style'],
 ): TextStyle {
+  const hasExplicitSize = overrides?.fontSize !== undefined;
+  const baseFontSize = overrides?.fontSize ?? defaults.fontSize;
+  const fontSize = hasExplicitSize ? baseFontSize : scaleFontSize(baseFontSize, width);
+
   return {
     fontFamily: overrides?.fontFamily ?? fontFamily,
-    fontSize: overrides?.fontSize ?? defaults.fontSize,
+    fontSize,
     fontWeight: overrides?.fontWeight ?? defaults.fontWeight,
     fill: overrides?.color ?? textColor ?? defaults.color,
     lineHeight: defaults.lineHeight,
@@ -83,24 +108,28 @@ function estimateLineCount(
  * @param theme - The fully resolved theme.
  * @param width - Total available width in pixels.
  * @param measureText - Optional real text measurement function from the adapter.
+ * @param chromeMode - Chrome display mode: full, compact (title only), or hidden.
+ * @param padding - Override padding (for scaled padding from dimensions).
  */
 export function computeChrome(
   chrome: Chrome | undefined,
   theme: ResolvedTheme,
   width: number,
   measureText?: MeasureTextFn,
+  chromeMode: ChromeMode = 'full',
+  padding?: number,
 ): ResolvedChrome {
-  if (!chrome) {
+  if (!chrome || chromeMode === 'hidden') {
     return { topHeight: 0, bottomHeight: 0 };
   }
 
-  const padding = theme.spacing.padding;
+  const pad = padding ?? theme.spacing.padding;
   const chromeGap = theme.spacing.chromeGap;
-  const maxWidth = width - padding * 2;
+  const maxWidth = width - pad * 2;
   const fontFamily = theme.fonts.family;
 
   // Track vertical cursor for top elements
-  let topY = padding;
+  let topY = pad;
   const topElements: Partial<Pick<ResolvedChrome, 'title' | 'subtitle'>> = {};
 
   // Title
@@ -110,12 +139,13 @@ export function computeChrome(
       theme.chrome.title,
       fontFamily,
       theme.chrome.title.color,
+      width,
       titleNorm.style,
     );
     const lineCount = estimateLineCount(titleNorm.text, style, maxWidth, measureText);
     const element: ResolvedChromeElement = {
       text: titleNorm.text,
-      x: padding + (titleNorm.offset?.dx ?? 0),
+      x: pad + (titleNorm.offset?.dx ?? 0),
       y: topY + (titleNorm.offset?.dy ?? 0),
       maxWidth,
       style,
@@ -124,19 +154,20 @@ export function computeChrome(
     topY += estimateTextHeight(style.fontSize, lineCount, style.lineHeight) + chromeGap;
   }
 
-  // Subtitle
-  const subtitleNorm = normalizeChromeText(chrome.subtitle);
+  // Subtitle (hidden in compact mode)
+  const subtitleNorm = chromeMode === 'compact' ? null : normalizeChromeText(chrome.subtitle);
   if (subtitleNorm) {
     const style = buildTextStyle(
       theme.chrome.subtitle,
       fontFamily,
       theme.chrome.subtitle.color,
+      width,
       subtitleNorm.style,
     );
     const lineCount = estimateLineCount(subtitleNorm.text, style, maxWidth, measureText);
     const element: ResolvedChromeElement = {
       text: subtitleNorm.text,
-      x: padding + (subtitleNorm.offset?.dx ?? 0),
+      x: pad + (subtitleNorm.offset?.dx ?? 0),
       y: topY + (subtitleNorm.offset?.dy ?? 0),
       maxWidth,
       style,
@@ -147,10 +178,18 @@ export function computeChrome(
 
   // Add chromeToChart gap if there are any top elements
   const hasTopChrome = titleNorm || subtitleNorm;
-  const topHeight = hasTopChrome ? topY - padding + theme.spacing.chromeToChart - chromeGap : 0;
+  const topHeight = hasTopChrome ? topY - pad + theme.spacing.chromeToChart - chromeGap : 0;
+
+  // Bottom elements hidden in compact mode
+  if (chromeMode === 'compact') {
+    return {
+      topHeight,
+      bottomHeight: 0,
+      ...topElements,
+    };
+  }
 
   // Bottom elements: source, byline, footer
-  // We compute heights bottom-up but position them after knowing total
   const bottomElements: Partial<Pick<ResolvedChrome, 'source' | 'byline' | 'footer'>> = {};
   let bottomHeight = 0;
 
@@ -191,7 +230,13 @@ export function computeChrome(
     bottomHeight += theme.spacing.chartToFooter;
 
     for (const item of bottomItems) {
-      const style = buildTextStyle(item.defaults, fontFamily, item.defaults.color, item.norm.style);
+      const style = buildTextStyle(
+        item.defaults,
+        fontFamily,
+        item.defaults.color,
+        width,
+        item.norm.style,
+      );
       const lineCount = estimateLineCount(item.norm.text, style, maxWidth, measureText);
       const height = estimateTextHeight(style.fontSize, lineCount, style.lineHeight);
 
@@ -199,7 +244,7 @@ export function computeChrome(
       // chart area by the engine. We store offsets from bottom start.
       bottomElements[item.key] = {
         text: item.norm.text,
-        x: padding + (item.norm.offset?.dx ?? 0),
+        x: pad + (item.norm.offset?.dx ?? 0),
         y: bottomHeight + (item.norm.offset?.dy ?? 0), // offset from where bottom chrome starts
         maxWidth,
         style,
@@ -211,7 +256,7 @@ export function computeChrome(
     // Remove trailing gap
     bottomHeight -= chromeGap;
     // Add bottom padding
-    bottomHeight += padding;
+    bottomHeight += pad;
   }
 
   return {

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { getBreakpoint, getLayoutStrategy } from '../breakpoints';
+import { getBreakpoint, getHeightClass, getLayoutStrategy } from '../breakpoints';
 
 describe('getBreakpoint', () => {
   it('returns compact for widths below 400', () => {
@@ -55,4 +55,92 @@ describe('getLayoutStrategy', () => {
     expect(compact.legendPosition).not.toBe(full.legendPosition);
     expect(compact.labelMode).not.toBe(full.labelMode);
   });
+
+  it('includes chromeMode and legendMaxHeight at normal height', () => {
+    const strategy = getLayoutStrategy('full');
+    expect(strategy.chromeMode).toBe('full');
+    expect(strategy.legendMaxHeight).toBe(-1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Height class detection
+// ---------------------------------------------------------------------------
+
+describe('getHeightClass', () => {
+  it('returns cramped for heights below 200', () => {
+    expect(getHeightClass(100)).toBe('cramped');
+    expect(getHeightClass(199)).toBe('cramped');
+  });
+
+  it('returns short for heights 200-350', () => {
+    expect(getHeightClass(200)).toBe('short');
+    expect(getHeightClass(280)).toBe('short');
+    expect(getHeightClass(350)).toBe('short');
+  });
+
+  it('returns normal for heights above 350', () => {
+    expect(getHeightClass(351)).toBe('normal');
+    expect(getHeightClass(800)).toBe('normal');
+  });
+
+  it('handles edge cases', () => {
+    expect(getHeightClass(0)).toBe('cramped');
+    expect(getHeightClass(-10)).toBe('cramped');
+    expect(getHeightClass(5000)).toBe('normal');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Height-aware layout strategy
+// ---------------------------------------------------------------------------
+
+describe('getLayoutStrategy with height class', () => {
+  it('normal height does not modify the width strategy', () => {
+    const withoutHeight = getLayoutStrategy('full');
+    const withNormal = getLayoutStrategy('full', 'normal');
+    expect(withoutHeight).toEqual(withNormal);
+  });
+
+  it('cramped height hides chrome and labels', () => {
+    const strategy = getLayoutStrategy('full', 'cramped');
+    expect(strategy.chromeMode).toBe('hidden');
+    expect(strategy.legendMaxHeight).toBe(0);
+    expect(strategy.labelMode).toBe('none');
+    expect(strategy.annotationPosition).toBe('tooltip-only');
+  });
+
+  it('cramped overrides even compact width strategy', () => {
+    const strategy = getLayoutStrategy('compact', 'cramped');
+    expect(strategy.chromeMode).toBe('hidden');
+    expect(strategy.legendMaxHeight).toBe(0);
+    expect(strategy.labelMode).toBe('none');
+  });
+
+  it('short height compresses chrome and caps legend', () => {
+    const strategy = getLayoutStrategy('full', 'short');
+    expect(strategy.chromeMode).toBe('compact');
+    expect(strategy.legendMaxHeight).toBe(0.15);
+  });
+
+  it('short height preserves width-based label and legend settings', () => {
+    const strategy = getLayoutStrategy('full', 'short');
+    // Width strategy for 'full' sets these; short only touches chromeMode and legendMaxHeight
+    expect(strategy.labelMode).toBe('all');
+    expect(strategy.legendPosition).toBe('right');
+    expect(strategy.axisLabelDensity).toBe('full');
+  });
+
+  it('short height preserves compact width label settings', () => {
+    const strategy = getLayoutStrategy('compact', 'short');
+    expect(strategy.labelMode).toBe('none');
+    expect(strategy.legendPosition).toBe('top');
+    expect(strategy.chromeMode).toBe('compact');
+  });
+
+  it('defaults heightClass to normal when omitted', () => {
+    const strategy = getLayoutStrategy('medium');
+    expect(strategy.chromeMode).toBe('full');
+    expect(strategy.legendMaxHeight).toBe(-1);
+  });
 });

package/src/responsive/breakpoints.ts

@@ -1,14 +1,19 @@
 /**
  * Responsive breakpoints and layout strategies.
  *
- * Three breakpoints based on container width:
+ * Width breakpoints:
  * - compact: < 400px (mobile, small embeds)
  * - medium: 400-700px (tablet, sidebars)
  * - full: > 700px (desktop, full-width)
+ *
+ * Height classes:
+ * - cramped: < 200px (dashboard widgets, thumbnails)
+ * - short: 200-350px (embedded panels, short containers)
+ * - normal: > 350px (standard containers)
  */
 
 // ---------------------------------------------------------------------------
-// Breakpoint type and detection
+// Width breakpoint type and detection
 // ---------------------------------------------------------------------------
 
 /** Responsive breakpoint based on container width. */
@@ -27,6 +32,26 @@ export function getBreakpoint(width: number): Breakpoint {
   return 'full';
 }
 
+// ---------------------------------------------------------------------------
+// Height class type and detection
+// ---------------------------------------------------------------------------
+
+/** Height classification based on container height. */
+export type HeightClass = 'cramped' | 'short' | 'normal';
+
+/** Height class thresholds in pixels. */
+export const HEIGHT_CRAMPED_MAX = 200;
+export const HEIGHT_SHORT_MAX = 350;
+
+/**
+ * Determine the height class for a given container height.
+ */
+export function getHeightClass(height: number): HeightClass {
+  if (height < HEIGHT_CRAMPED_MAX) return 'cramped';
+  if (height <= HEIGHT_SHORT_MAX) return 'short';
+  return 'normal';
+}
+
 // ---------------------------------------------------------------------------
 // Layout strategy
 // ---------------------------------------------------------------------------
@@ -43,9 +68,12 @@ export type AnnotationPosition = 'inline' | 'tooltip-only';
 /** Axis label density (controls tick count reduction). */
 export type AxisLabelDensity = 'full' | 'reduced' | 'minimal';
 
+/** Chrome display mode based on available height. */
+export type ChromeMode = 'full' | 'compact' | 'hidden';
+
 /**
  * Layout strategy defining how the visualization adapts to available space.
- * Returned by getLayoutStrategy() based on the current breakpoint.
+ * Returned by getLayoutStrategy() based on width breakpoint and height class.
  */
 export interface LayoutStrategy {
   /** How data labels are displayed. */
@@ -56,16 +84,16 @@ export interface LayoutStrategy {
   annotationPosition: AnnotationPosition;
   /** Axis tick density. */
   axisLabelDensity: AxisLabelDensity;
+  /** Chrome display mode: full, compact (title only), or hidden. */
+  chromeMode: ChromeMode;
+  /** Max fraction of container height for legend (0-1). -1 means unlimited. */
+  legendMaxHeight: number;
 }
 
 /**
- * Get the layout strategy for a given breakpoint.
- *
- * Compact: minimal chrome, no inline labels, legend on top, reduced axes.
- * Medium: moderate labels, legend on top, reduced axes.
- * Full: all labels, legend on right, full axes.
+ * Get the base layout strategy for a width breakpoint.
  */
-export function getLayoutStrategy(breakpoint: Breakpoint): LayoutStrategy {
+function getWidthStrategy(breakpoint: Breakpoint): LayoutStrategy {
   switch (breakpoint) {
     case 'compact':
       return {
@@ -73,6 +101,8 @@ export function getLayoutStrategy(breakpoint: Breakpoint): LayoutStrategy {
         legendPosition: 'top',
         annotationPosition: 'tooltip-only',
         axisLabelDensity: 'minimal',
+        chromeMode: 'full',
+        legendMaxHeight: -1,
       };
     case 'medium':
       return {
@@ -80,6 +110,8 @@ export function getLayoutStrategy(breakpoint: Breakpoint): LayoutStrategy {
         legendPosition: 'top',
         annotationPosition: 'inline',
         axisLabelDensity: 'reduced',
+        chromeMode: 'full',
+        legendMaxHeight: -1,
       };
     case 'full':
       return {
@@ -87,6 +119,54 @@ export function getLayoutStrategy(breakpoint: Breakpoint): LayoutStrategy {
         legendPosition: 'right',
         annotationPosition: 'inline',
         axisLabelDensity: 'full',
+        chromeMode: 'full',
+        legendMaxHeight: -1,
       };
   }
 }
+
+/**
+ * Apply height constraints to a width-based strategy.
+ * Short containers compress chrome and cap legend height.
+ * Cramped containers hide chrome and labels entirely.
+ */
+function applyHeightConstraints(
+  strategy: LayoutStrategy,
+  heightClass: HeightClass,
+): LayoutStrategy {
+  if (heightClass === 'normal') return strategy;
+
+  if (heightClass === 'cramped') {
+    return {
+      ...strategy,
+      chromeMode: 'hidden',
+      legendMaxHeight: 0,
+      labelMode: 'none',
+      annotationPosition: 'tooltip-only',
+    };
+  }
+
+  // short
+  return {
+    ...strategy,
+    chromeMode: 'compact',
+    legendMaxHeight: 0.15,
+  };
+}
+
+/**
+ * Get the layout strategy for a given breakpoint and height class.
+ *
+ * Compact: minimal chrome, no inline labels, legend on top, reduced axes.
+ * Medium: moderate labels, legend on top, reduced axes.
+ * Full: all labels, legend on right, full axes.
+ *
+ * Height constraints further reduce chrome and legend when container is short.
+ */
+export function getLayoutStrategy(
+  breakpoint: Breakpoint,
+  heightClass: HeightClass = 'normal',
+): LayoutStrategy {
+  const base = getWidthStrategy(breakpoint);
+  return applyHeightConstraints(base, heightClass);
+}

package/src/responsive/index.ts

@@ -6,6 +6,8 @@ export type {
   AnnotationPosition,
   AxisLabelDensity,
   Breakpoint,
+  ChromeMode,
+  HeightClass,
   LabelMode,
   LayoutStrategy,
   LegendPosition,
@@ -14,5 +16,8 @@ export {
   BREAKPOINT_COMPACT_MAX,
   BREAKPOINT_MEDIUM_MAX,
   getBreakpoint,
+  getHeightClass,
   getLayoutStrategy,
+  HEIGHT_CRAMPED_MAX,
+  HEIGHT_SHORT_MAX,
 } from './breakpoints';

package/src/types/layout.ts

@@ -394,6 +394,8 @@ export interface LegendEntry {
   shape: 'circle' | 'square' | 'line';
   /** Whether this entry is currently highlighted/active. */
   active?: boolean;
+  /** True for overflow indicator entries ("+N more"). Not interactive. */
+  overflow?: boolean;
 }
 
 /** Resolved legend layout with position and entries. */