feat: responsive layout improvements for narrow viewports

Tighten spacing on small screens so charts maximize data area:
- Consolidate legend gap logic into shared legendGap() helper
- Extract COMPACT_WIDTH constant (420px) to eliminate magic numbers
- Clamp y-axis label margins so long categories don't starve chart area
- Truncate overflowing y-axis labels with ellipsis + title for a11y
- Clamp dot chart baseline to scale range when domain excludes zero
- Allow tick thinning even with explicit tickCount (D3 log scales overshoot)
- Order legend entries by explicit domain for author-controlled truncation
- Move applyTextStyle to inline styles so engine values override CSS defaults
- Document mark properties and gradients in spec reference

Author: rileyhilliard

docs/spec-reference.md

@@ -8,6 +8,7 @@ All types are importable from `@opendata-ai/openchart-core` or from the convenie
 
 - [VizSpec](#vizspec) (top-level union type)
 - [ChartSpec](#chartspec) (line, area, bar, column, pie, donut, dot, scatter)
+  - [Mark properties](#mark-properties) (fill, gradient, point, interpolate, opacity)
 - [LayerSpec](#layerspec) (overlay multiple chart types)
 - [Encoding](#encoding) (x, y, color, size, detail channels)
 - [Annotations](#annotations) (refline, text, range)
@@ -67,6 +68,65 @@ type DataRow = Record<string, unknown>;
 
 A plain object with string keys. Values can be numbers, strings, dates, nulls, arrays (for sparklines), or booleans. The engine inspects values at runtime to validate encoding types.
 
+### Mark properties
+
+The `type` field on ChartSpec accepts either a string (`'line'`) or an object with additional mark configuration. In LayerSpec children, this field is called `mark`.
+
+```ts
+// String shorthand
+{ type: 'area', data: [...], encoding: {...} }
+
+// Object form with mark properties
+{
+  type: { type: 'area', point: true, fill: { gradient: 'linear', ... } },
+  data: [...],
+  encoding: {...}
+}
+```
+
+| Field          | Type                    | Default     | Applies to     | Description                                                              |
+| -------------- | ----------------------- | ----------- | -------------- | ------------------------------------------------------------------------ |
+| `type`         | `MarkType`              | (required)  | all            | Mark type: `'bar'`, `'line'`, `'area'`, `'point'`, `'arc'`, `'text'`, etc. |
+| `point`        | `boolean \| 'transparent'` | `false`  | line, area     | Show point markers at data positions. `true` = filled circles. |
+| `interpolate`  | `string`                | `'linear'`  | line, area     | Curve: `'linear'`, `'monotone'`, `'step'`, `'step-before'`, `'step-after'`, `'basis'`, `'cardinal'`, `'natural'`. |
+| `orient`       | `'horizontal' \| 'vertical'` | auto   | bar            | Explicit orientation override. |
+| `innerRadius`  | `number`                | `0`         | arc            | Inner radius. >0 produces a donut. |
+| `outerRadius`  | `number`                | auto        | arc            | Outer radius. |
+| `cornerRadius` | `number`                | `0`         | bar, arc       | Corner rounding in pixels. |
+| `filled`       | `boolean`               | `true`      | all            | Whether the mark is filled vs stroked only. |
+| `opacity`      | `number`                | `1`         | all            | Overall mark opacity (0-1). |
+| `fill`         | `string \| GradientDef` | theme color | all            | Fill color or gradient. See [Gradients](#gradients). |
+| `stroke`       | `string`                | `undefined` | all            | Stroke color. |
+| `strokeWidth`  | `number`                | varies      | all            | Stroke width in pixels. |
+| `tooltip`      | `boolean \| null`       | `true`      | all            | Tooltip behavior. `null` disables tooltips. |
+| `clip`         | `boolean`               | `false`     | all            | Clip marks to the chart area. |
+
+#### Gradients
+
+The `fill` property accepts a `GradientDef` object for linear or radial gradients. Source: `core/src/types/spec.ts`.
+
+```ts
+// Linear gradient (top-to-bottom opacity fade)
+fill: {
+  gradient: 'linear',
+  x1: 0, y1: 1,  // start (bottom)
+  x2: 0, y2: 0,  // end (top)
+  stops: [
+    { offset: 0, color: '#38bdf8', opacity: 0 },
+    { offset: 1, color: '#38bdf8', opacity: 1 },
+  ],
+}
+```
+
+| Field    | Type             | Default | Description                                    |
+| -------- | ---------------- | ------- | ---------------------------------------------- |
+| `gradient` | `'linear' \| 'radial'` | (required) | Gradient type.                        |
+| `stops`  | `GradientStop[]` | (required) | Color stops with offset (0-1), color, and optional opacity. |
+| `x1`, `y1` | `number`      | `0`, `0` | Start point in [0,1] normalized space.        |
+| `x2`, `y2` | `number`      | `0`, `1` | End point. Default is top-to-bottom.           |
+
+**Area chart fill behavior:** Single-series area charts apply a default `fillOpacity` of 0.15 to the area fill (the stroke is drawn at full opacity). Stacked areas use 0.7. The gradient stop `opacity` values multiply with this default, so a stop at `opacity: 1` with the area default produces an effective opacity of 0.15. Design gradient stops accordingly, or use a LayerSpec with separate line and area marks for full control.
+
 ---
 
 ## LayerSpec

packages/core/src/index.ts

@@ -56,6 +56,7 @@ export {
   BRAND_FONT_SIZE,
   BRAND_MIN_WIDTH,
   BRAND_RESERVE_WIDTH,
+  COMPACT_WIDTH,
   computeChrome,
   estimateTextWidth,
   wrapText,

packages/core/src/layout/chrome.ts

@@ -26,6 +26,7 @@ import {
   BRAND_FONT_SIZE,
   BRAND_MIN_WIDTH,
   BRAND_RESERVE_WIDTH,
+  COMPACT_WIDTH,
   estimateCharWidth,
   estimateTextHeight,
 } from './text-measure';
@@ -236,9 +237,12 @@ export function computeChrome(
     topY += estimateTextHeight(style.fontSize, lineCount, style.lineHeight) + chromeGap;
   }
 
-  // Add chromeToChart gap if there are any top elements
+  // Add chromeToChart gap if there are any top elements. Tighten on narrow
+  // viewports so the subtitle doesn't float far above a legend or chart area.
   const hasTopChrome = titleNorm || subtitleNorm;
-  const topHeight = hasTopChrome ? topY - pad + theme.spacing.chromeToChart - chromeGap : 0;
+  const chromeToChart =
+    width < COMPACT_WIDTH ? Math.min(theme.spacing.chromeToChart, 2) : theme.spacing.chromeToChart;
+  const topHeight = hasTopChrome ? topY - pad + chromeToChart - chromeGap : 0;
 
   // Bottom chrome text hidden in compact mode, but brand watermark still
   // renders for wide-enough charts. Reserve space so it doesn't overflow.

packages/core/src/layout/index.ts

@@ -7,6 +7,7 @@ export {
   BRAND_FONT_SIZE,
   BRAND_MIN_WIDTH,
   BRAND_RESERVE_WIDTH,
+  COMPACT_WIDTH,
   estimateCharWidth,
   estimateTextHeight,
   estimateTextWidth,

packages/core/src/layout/text-measure.ts

@@ -73,6 +73,16 @@ export const BRAND_FONT_SIZE = 12;
 /** Minimum chart width to render the brand watermark (px). */
 export const BRAND_MIN_WIDTH = 120;
 
+// ---------------------------------------------------------------------------
+// Responsive breakpoints
+// ---------------------------------------------------------------------------
+
+/**
+ * Width threshold below which layout tightens spacing (legend gaps, chrome
+ * padding, label gaps) to maximize data area on small screens.
+ */
+export const COMPACT_WIDTH = 420;
+
 /**
  * Estimate the rendered height of a text block.
  *

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

@@ -418,7 +418,7 @@ describe('text-aware tick density', () => {
     expect(axesNarrow.x!.ticks.length).toBeLessThanOrEqual(axesWide.x!.ticks.length);
   });
 
-  it('does not thin x-axis ticks when explicit tickCount is set', () => {
+  it('still thins x-axis ticks when tickCount is set but D3 overshoots', () => {
     const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
     const specWithTickCount: NormalizedChartSpec = {
       ...lineSpec,
@@ -431,12 +431,33 @@ describe('text-aware tick density', () => {
     const scales = computeScales(specWithTickCount, narrowArea, specWithTickCount.data);
     const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
 
-    // With explicit tickCount, the engine should not thin
-    // D3 may return fewer than 8 for this small dataset, but the point is
-    // thinTicksUntilFit should not be called
+    // tickCount is advisory for D3 - if it overshoots, thinning still applies
+    // to prevent overlap. The result should still have ticks, just not more
+    // than the narrow area can display without overlap.
     expect(axes.x!.ticks.length).toBeGreaterThan(0);
   });
 
+  it('does not thin x-axis ticks when explicit values are set', () => {
+    const narrowArea = { x: 50, y: 50, width: 200, height: 300 };
+    const specWithValues: NormalizedChartSpec = {
+      ...lineSpec,
+      encoding: {
+        x: {
+          field: 'date',
+          type: 'temporal',
+          axis: { values: ['2020-01-01', '2021-01-01', '2022-01-01'] },
+        },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    const scales = computeScales(specWithValues, narrowArea, specWithValues.data);
+    const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
+
+    // Explicit values should be preserved exactly as specified
+    expect(axes.x!.ticks.length).toBe(3);
+  });
+
   it('band scale shows all categories regardless of width', () => {
     const categories = ['Alpha', 'Bravo', 'Charlie', 'Delta', 'Echo'];
     const barSpec: NormalizedChartSpec = {

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

@@ -265,4 +265,52 @@ describe('computeDimensions', () => {
     // Tooltip-only should NOT reserve extra margin (annotations are hidden)
     expect(dimsTooltipOnly.margins.right).toBe(dimsNoAnnotations.margins.right);
   });
+
+  it('clamps y-axis label margin on narrow containers to preserve chart area', () => {
+    const longLabelSpec: NormalizedChartSpec = {
+      ...baseSpec,
+      markType: 'bar',
+      markDef: { type: 'bar' },
+      data: [
+        {
+          category: 'This is a very long category label that would consume lots of space',
+          value: 10,
+        },
+        { category: 'Another extremely verbose category name', value: 20 },
+      ],
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'category', type: 'nominal' },
+      },
+    };
+
+    const narrowDims = computeDimensions(
+      longLabelSpec,
+      { width: 350, height: 300 },
+      emptyLegend,
+      lightTheme,
+    );
+
+    // On narrow viewports, left margin should be clamped so the chart area
+    // retains at least ~45% of the container width
+    expect(narrowDims.chartArea.width).toBeGreaterThanOrEqual(350 * 0.4);
+  });
+
+  it('tightens legend gap on narrow viewports', () => {
+    const wideDims = computeDimensions(
+      baseSpec,
+      { width: 600, height: 400 },
+      topLegend,
+      lightTheme,
+    );
+    const narrowDims = computeDimensions(
+      baseSpec,
+      { width: 360, height: 400 },
+      topLegend,
+      lightTheme,
+    );
+
+    // Narrow viewport should have more chart height available (smaller legend gap)
+    expect(narrowDims.chartArea.height).toBeGreaterThanOrEqual(wideDims.chartArea.height - 10);
+  });
 });

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

@@ -276,6 +276,30 @@ describe('computeLegend', () => {
     expect(deEntry.color).toBe('#00ff00');
   });
 
+  it('orders legend entries by explicit domain, not data order', () => {
+    const specExplicit: NormalizedChartSpec = {
+      ...specWithColor,
+      data: [
+        { date: '2020', value: 10, country: 'Germany' },
+        { date: '2021', value: 20, country: 'UK' },
+        { date: '2022', value: 30, country: 'US' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: {
+          field: 'country',
+          type: 'nominal',
+          scale: {
+            domain: ['US', 'UK', 'Germany'],
+          },
+        },
+      },
+    };
+    const legend = computeLegend(specExplicit, compactStrategy, theme, chartArea);
+    expect(legend.entries.map((e) => e.label)).toEqual(['US', 'UK', 'Germany']);
+  });
+
   it('uses correct swatch shape for chart type', () => {
     const lineLegend = computeLegend(specWithColor, fullStrategy, theme, chartArea);
     expect(lineLegend.entries[0].shape).toBe('line');
@@ -395,41 +419,44 @@ describe('computeLegend', () => {
     });
   });
 
-  // ---------------------------------------------------------------------------
-  // Characterization test (refactor/v7-cohesion step 1):
-  // Pins the 4px gap between a top-positioned legend and the chart area,
-  // as enforced at packages/engine/src/compile.ts:331. Refactor step 4 will
-  // consolidate legend row-wrapping geometry; this test guards the spacing
-  // invariant through that change.
-  // ---------------------------------------------------------------------------
   describe('top legend spacing', () => {
-    it('places the legend exactly 4px above the chart area', () => {
-      const spec = {
-        mark: 'bar' as const,
-        data: [
-          { name: 'A', value: 10, group: 'X' },
-          { name: 'A', value: 20, group: 'Y' },
-          { name: 'B', value: 30, group: 'X' },
-          { name: 'B', value: 25, group: 'Y' },
-        ],
-        encoding: {
-          x: { field: 'name', type: 'nominal' as const },
-          y: { field: 'value', type: 'quantitative' as const },
-          color: { field: 'group', type: 'nominal' as const },
-        },
-        legend: { position: 'top' as const },
-      };
+    const topLegendSpec = {
+      mark: 'bar' as const,
+      data: [
+        { name: 'A', value: 10, group: 'X' },
+        { name: 'A', value: 20, group: 'Y' },
+        { name: 'B', value: 30, group: 'X' },
+        { name: 'B', value: 25, group: 'Y' },
+      ],
+      encoding: {
+        x: { field: 'name', type: 'nominal' as const },
+        y: { field: 'value', type: 'quantitative' as const },
+        color: { field: 'group', type: 'nominal' as const },
+      },
+      legend: { position: 'top' as const },
+    };
 
-      const layout = compileChart(spec, { width: 600, height: 400 });
+    it('places the legend exactly 4px above the chart area at standard width', () => {
+      const layout = compileChart(topLegendSpec, { width: 600, height: 400 });
 
       expect(layout.legend.position).toBe('top');
       expect(layout.legend.entries.length).toBeGreaterThan(0);
       expect(layout.legend.bounds.height).toBeGreaterThan(0);
 
       const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
       const gap = layout.area.y - legendBottom;
-      // Pin value matches the literal at compile.ts:331 (legendArea.y -= legendLayout.bounds.height + 4)
       expect(gap).toBe(4);
     });
+
+    it('eliminates legend gap on narrow viewports (< 420px)', () => {
+      const layout = compileChart(topLegendSpec, { width: 360, height: 400 });
+
+      expect(layout.legend.position).toBe('top');
+      expect(layout.legend.entries.length).toBeGreaterThan(0);
+
+      const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
+      const gap = layout.area.y - legendBottom;
+      expect(gap).toBe(0);
+    });
   });
 });

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

@@ -264,6 +264,37 @@ describe('computeDotMarks', () => {
     });
   });
 
+  describe('baseline clamping', () => {
+    it('clamps stems to the plot area when domain does not include zero', () => {
+      const spec: NormalizedChartSpec = {
+        markType: 'circle',
+        markDef: { type: 'circle' },
+        data: [
+          { country: 'USA', score: 50 },
+          { country: 'UK', score: 80 },
+        ],
+        encoding: {
+          x: { field: 'score', type: 'quantitative', scale: { domain: [40, 100] } },
+          y: { field: 'country', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeDotMarks(spec, scales, chartArea, fullStrategy);
+
+      const stems = marks.filter((m): m is RectMark => m.type === 'rect');
+      for (const stem of stems) {
+        expect(stem.x).toBeGreaterThanOrEqual(chartArea.x);
+        expect(stem.x + stem.width).toBeLessThanOrEqual(chartArea.x + chartArea.width);
+      }
+    });
+  });
+
   describe('edge cases', () => {
     it('returns empty array when no x encoding', () => {
       const spec: NormalizedChartSpec = {

packages/engine/src/charts/dot/compute.ts

@@ -67,7 +67,12 @@ export function computeDotMarks(
   }
 
   const bandwidth = yScale.bandwidth();
-  const baseline = xScale(0);
+  // Clamp baseline to the scale range so stems never extend past the plot area
+  // (e.g., when domain doesn't include zero, xScale(0) would land outside).
+  const [rangeStart, rangeEnd] = xScale.range();
+  const rangeMin = Math.min(rangeStart, rangeEnd);
+  const rangeMax = Math.max(rangeStart, rangeEnd);
+  const baseline = Math.max(rangeMin, Math.min(rangeMax, xScale(0)));
   const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
   const isSequentialColor = colorEnc?.type === 'quantitative';
   const colorField = isSequentialColor ? undefined : colorEnc?.field;