feat: area y2 bands, annotation responsiveness, bar label improvements

- Area marks support y2 encoding channel for confidence bands / ranges
- Annotations gain responsive opt-out (responsive: false stays visible at compact breakpoints)
- RefLine annotations accept 'rule' type alias and strokeDash array override
- Bar labels position correctly for negative values (inside and outside)
- Inside-bar labels use findAccessibleColor instead of hardcoded white
- findAccessibleColor tries both lighten/darken directions for edge cases
- Legend auto-suppression respects any explicit legend config, not just show: true
- Layout skips label margin reservation when responsive strategy hides labels
- LegendConfig.exclude type added for future series exclusion support

Author: rileyhilliard

packages/core/src/colors/contrast.ts

@@ -65,30 +65,42 @@ export function findAccessibleColor(baseColor: string, bg: string, targetRatio =
   if (c == null) return baseColor;
 
   const bgLum = relativeLuminance(bg);
-  // Determine direction: darken if bg is light, lighten if bg is dark.
-  const bgIsLight = bgLum > 0.5;
-
-  // Binary search for the lightness adjustment that hits the target ratio.
-  let lo = 0;
-  let hi = 1;
-  let best = baseColor;
-
-  for (let i = 0; i < 20; i++) {
-    const mid = (lo + hi) / 2;
-    const adjusted = bgIsLight
-      ? rgb(c.r * (1 - mid), c.g * (1 - mid), c.b * (1 - mid))
-      : rgb(c.r + (255 - c.r) * mid, c.g + (255 - c.g) * mid, c.b + (255 - c.b) * mid);
-
-    const hex = adjusted.formatHex();
-    const ratio = contrastRatio(hex, bg);
-
-    if (ratio >= targetRatio) {
-      best = hex;
-      hi = mid; // try less adjustment
-    } else {
-      lo = mid; // need more adjustment
+  const baseLum = relativeLuminance(baseColor);
+
+  // Try both directions: prefer the one matching bg luminance, but fall back
+  // to the other if the base color is already at the extreme (e.g. white on
+  // a medium-luminance background can't be lightened, so darken instead).
+  const preferDarken = bgLum > 0.5;
+  const directions = preferDarken ? [true, false] : [false, true];
+
+  for (const darken of directions) {
+    // Skip impossible directions: can't lighten white or darken black.
+    if (!darken && baseLum > 0.95) continue;
+    if (darken && baseLum < 0.05) continue;
+
+    let lo = 0;
+    let hi = 1;
+    let best: string | null = null;
+
+    for (let i = 0; i < 20; i++) {
+      const mid = (lo + hi) / 2;
+      const adjusted = darken
+        ? rgb(c.r * (1 - mid), c.g * (1 - mid), c.b * (1 - mid))
+        : rgb(c.r + (255 - c.r) * mid, c.g + (255 - c.g) * mid, c.b + (255 - c.b) * mid);
+
+      const hex = adjusted.formatHex();
+      const ratio = contrastRatio(hex, bg);
+
+      if (ratio >= targetRatio) {
+        best = hex;
+        hi = mid;
+      } else {
+        lo = mid;
+      }
     }
+
+    if (best) return best;
   }
 
-  return best;
+  return baseColor;
 }

packages/core/src/types/spec.ts

@@ -523,6 +523,8 @@ interface AnnotationBase {
   opacity?: number;
   /** Z-index for render ordering. Higher values render on top. */
   zIndex?: number;
+  /** When false, the annotation is always shown even at compact breakpoints. Default true. */
+  responsive?: boolean;
 }
 
 /**
@@ -588,13 +590,15 @@ export interface RangeAnnotation extends AnnotationBase {
  * Useful for baselines (zero), targets, or thresholds.
  */
 export interface RefLineAnnotation extends AnnotationBase {
-  type: 'refline';
+  type: 'refline' | 'rule';
   /** X-axis value for a vertical reference line. */
   x?: string | number;
   /** Y-axis value for a horizontal reference line. */
   y?: string | number;
   /** Line style. */
   style?: 'solid' | 'dashed' | 'dotted';
+  /** Raw SVG dash pattern override, e.g. [4, 4]. Takes precedence over style. */
+  strokeDash?: number[];
   /** Line width in pixels. */
   strokeWidth?: number;
   /** Pixel offset for the reference line label. */
@@ -715,6 +719,8 @@ export interface LegendConfig {
   symbolLimit?: number;
   /** Maximum number of rows for top-positioned legends before truncation. Defaults to 2. */
   maxRows?: number;
+  /** Series names to exclude from the legend. Excluded series still render in the chart. */
+  exclude?: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -1408,7 +1414,7 @@ export function isRangeAnnotation(annotation: Annotation): annotation is RangeAn
 
 /** Check if an annotation is a RefLineAnnotation. */
 export function isRefLineAnnotation(annotation: Annotation): annotation is RefLineAnnotation {
-  return annotation.type === 'refline';
+  return annotation.type === 'refline' || annotation.type === 'rule';
 }
 
 // ---------------------------------------------------------------------------

packages/engine/src/__tests__/legend.test.ts

@@ -354,6 +354,17 @@ describe('computeLegend', () => {
       expect(legend.entries).toHaveLength(3);
     });
 
+    it('preserves legend when any legend config is present (e.g. position)', () => {
+      const spec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        legend: { position: 'top' },
+        hiddenSeries: [],
+        seriesStyles: {},
+      };
+      const legend = computeLegend(spec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
     it('preserves legend when labels density is none', () => {
       const spec: NormalizedChartSpec = {
         ...lineWithLabels,

packages/engine/src/annotations/compute.ts

@@ -45,14 +45,15 @@ export function computeAnnotations(
   obstacles: Rect[] = [],
   svgDimensions?: { width: number; height: number },
 ): ResolvedAnnotation[] {
-  // At compact breakpoints, skip all annotations
-  if (strategy.annotationPosition === 'tooltip-only') {
-    return [];
-  }
+  const isCompact = strategy.annotationPosition === 'tooltip-only';
 
   const annotations: ResolvedAnnotation[] = [];
 
   for (const annotation of spec.annotations) {
+    // At compact breakpoints, skip annotations unless they opt out with responsive: false
+    if (isCompact && annotation.responsive !== false) {
+      continue;
+    }
     let resolved: ResolvedAnnotation | null = null;
 
     switch (annotation.type) {

packages/engine/src/annotations/resolve-refline.ts

@@ -43,9 +43,11 @@ export function resolveRefLineAnnotation(
     return null;
   }
 
-  // Determine dash pattern from style
+  // Determine dash pattern: strokeDash array wins, then style string
   let strokeDasharray: string | undefined;
-  if (annotation.style === 'dashed' || annotation.style === undefined) {
+  if (annotation.strokeDash && annotation.strokeDash.length > 0) {
+    strokeDasharray = annotation.strokeDash.join(' ');
+  } else if (annotation.style === 'dashed' || annotation.style === undefined) {
     strokeDasharray = DEFAULT_REFLINE_DASH;
   } else if (annotation.style === 'dotted') {
     strokeDasharray = '2 2';

packages/engine/src/charts/bar/labels.ts

@@ -20,6 +20,7 @@ import type {
 import {
   buildD3Formatter,
   estimateTextWidth,
+  findAccessibleColor,
   getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
@@ -137,6 +138,8 @@ export function computeBarLabels(
 
     // Determine if label goes inside or outside the bar
     const isInside = mark.width >= MIN_WIDTH_FOR_INSIDE_LABEL;
+    const isNegative = Number.isFinite(rawNum) ? rawNum < 0 : false;
+    const bgColor = getRepresentativeColor(mark.fill);
 
     let anchorX: number;
     let fill: string;
@@ -145,18 +148,32 @@ export function computeBarLabels(
     if (isStacked && isInside) {
       // Stacked: centered within segment
       anchorX = mark.x + mark.width / 2;
-      fill = '#ffffff';
+      fill = findAccessibleColor('#ffffff', bgColor, 4.5);
       textAnchor = 'middle';
     } else if (isInside) {
-      // Simple: right-aligned within bar
-      anchorX = mark.x + mark.width - LABEL_PADDING;
-      fill = '#ffffff';
-      textAnchor = 'end';
+      if (isNegative) {
+        // Negative bar: left-aligned within bar (bar extends leftward)
+        anchorX = mark.x + LABEL_PADDING;
+        fill = findAccessibleColor('#ffffff', bgColor, 4.5);
+        textAnchor = 'start';
+      } else {
+        // Positive bar: right-aligned within bar
+        anchorX = mark.x + mark.width - LABEL_PADDING;
+        fill = findAccessibleColor('#ffffff', bgColor, 4.5);
+        textAnchor = 'end';
+      }
     } else {
-      // Outside: just past the bar's right edge
-      anchorX = mark.x + mark.width + LABEL_PADDING;
-      fill = getRepresentativeColor(mark.fill);
-      textAnchor = 'start';
+      if (isNegative) {
+        // Outside negative bar: just past the bar's left edge
+        anchorX = mark.x - LABEL_PADDING;
+        fill = getRepresentativeColor(mark.fill);
+        textAnchor = 'end';
+      } else {
+        // Outside positive bar: just past the bar's right edge
+        anchorX = mark.x + mark.width + LABEL_PADDING;
+        fill = getRepresentativeColor(mark.fill);
+        textAnchor = 'start';
+      }
     }
 
     // anchorY = bar vertical center. With dominant-baseline: central,

packages/engine/src/charts/line/__tests__/compute.test.ts

@@ -477,6 +477,34 @@ describe('computeAreaMarks', () => {
     expect(marks[0].fillOpacity).toBeLessThanOrEqual(1);
   });
 
+  it('area with y2 encoding uses y2 field as bottom boundary instead of baseline', () => {
+    const spec: NormalizedChartSpec = {
+      ...makeSingleSeriesSpec(),
+      data: [
+        { date: '2020-01-01', value: 80, value_low: 60 },
+        { date: '2021-01-01', value: 90, value_low: 70 },
+        { date: '2022-01-01', value: 85, value_low: 65 },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        y2: { field: 'value_low', type: 'quantitative' },
+      },
+    };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeAreaMarks(spec, scales, chartArea);
+
+    expect(marks).toHaveLength(1);
+    // Bottom points should NOT all be at the same baseline y coordinate
+    const bottomYValues = marks[0].bottomPoints.map((p) => p.y);
+    const allSame = bottomYValues.every((y) => y === bottomYValues[0]);
+    expect(allSame).toBe(false);
+    // Each bottom point should be between the top point and the chart bottom
+    for (let i = 0; i < marks[0].topPoints.length; i++) {
+      expect(marks[0].bottomPoints[i].y).toBeGreaterThan(marks[0].topPoints[i].y); // SVG coords: larger y = lower on screen
+    }
+  });
+
   it('stacked areas: produces multiple AreaMarks for multi-series', () => {
     const spec = makeMultiSeriesSpec();
     const scales = computeScales(spec, chartArea, spec.data);

packages/engine/src/charts/line/area.ts

@@ -84,16 +84,24 @@ function computeSingleArea(
     // Compute points, filtering out null values
     const validPoints: { x: number; yTop: number; yBottom: number; row: DataRow }[] = [];
 
+    // Check for y2 channel (band between y and y2)
+    const y2Channel = (encoding as Encoding & { y2?: { field: string; type: string } }).y2;
+
     for (const row of sortedRows) {
       const xVal = scaleValue(scales.x.scale, scales.x.type, row[xChannel.field]);
       const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
 
       if (xVal === null || yVal === null) continue;
 
+      const yBottomVal =
+        y2Channel && row[y2Channel.field] != null
+          ? scaleValue(scales.y.scale, scales.y.type, row[y2Channel.field])
+          : null;
+
       validPoints.push({
         x: xVal,
         yTop: yVal,
-        yBottom: baselineY,
+        yBottom: yBottomVal ?? baselineY,
         row,
       });
     }
@@ -127,14 +135,16 @@ function computeSingleArea(
 
     const aria: MarkAria = { label: ariaLabel };
 
+    const fillOpacity = y2Channel ? 0.25 : DEFAULT_FILL_OPACITY;
+
     marks.push({
       type: 'area',
       topPoints,
       bottomPoints,
       path: pathStr,
       topPath: topPathStr,
       fill: color,
-      fillOpacity: DEFAULT_FILL_OPACITY,
+      fillOpacity: fillOpacity,
       stroke: getRepresentativeColor(color),
       strokeWidth: 2,
       seriesKey: seriesKey === '__default__' ? undefined : seriesKey,

packages/engine/src/compiler/normalize.ts

@@ -174,8 +174,10 @@ function normalizeAnnotations(annotations: Annotation[] | undefined): Annotation
           fill: ann.fill ?? '#000000',
         };
       case 'refline':
+      case 'rule':
         return {
           ...ann,
+          type: 'refline' as const,
           style: ann.style ?? 'dashed',
           strokeWidth: ann.strokeWidth ?? 1,
           stroke: ann.stroke ?? '#666666',

packages/engine/src/layout/dimensions.ts

@@ -168,9 +168,14 @@ export function computeDimensions(
   };
 
   // Dynamic right margin for line/area end-of-line labels.
-  // Only reserve space when labels will actually render (density != 'none').
+  // Only reserve space when labels will actually render.
   const labelDensity = spec.labels.density;
-  if ((spec.markType === 'line' || spec.markType === 'area') && labelDensity !== 'none') {
+  const labelsHiddenByStrategy = strategy?.labelMode === 'none';
+  if (
+    (spec.markType === 'line' || spec.markType === 'area') &&
+    labelDensity !== 'none' &&
+    !labelsHiddenByStrategy
+  ) {
     // Estimate label width from longest series name (color encoding domain)
     const colorEnc = encoding.color;
     const colorField = colorEnc && 'field' in colorEnc ? colorEnc.field : undefined;