@astryxdesign/charts 0.5.2-canary.e4f8e4e → 0.5.2-canary.ea1b9b5

package/README.md

@@ -25,8 +25,8 @@ It ships to npm **only under the `@canary` dist-tag** — there is never a stabl
 ## Status
 
 Under active development. The config-model chart and its marks/chrome are in place;
-API and visuals are still being refined. See the repo-root `CHARTV2_*` docs for the
-plan, design research, and verification checklist.
+API and visuals are still being refined. See [`docs/`](./docs/) for the plan, design research, readiness audit, and
+verification checklist.
 
 ## Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/charts",
-  "version": "0.5.2-canary.e4f8e4e",
+  "version": "0.5.2-canary.ea1b9b5",
   "description": "Astryx charts — a config-model data visualization library (d3-based). Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -45,7 +45,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/core": "0.5.2-canary.ea1b9b5",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0"
   },
@@ -55,7 +55,7 @@
     "d3-shape": "^3.2.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.5.2-canary.e4f8e4e",
+    "@astryxdesign/cli": "0.5.2-canary.ea1b9b5",
     "@types/d3-scale": "^4.0.9",
     "@types/d3-shape": "^3.1.8"
   },

package/src/Chart.test.tsx

@@ -2,15 +2,18 @@
 
 /**
  * @file Chart.test.tsx
- * @input Uses vitest, @testing-library/react, Chart root + bar mark
- * @output Unit tests for Chart accessibility (WCAG 1.1.1)
+ * @input Uses vitest, @testing-library/react, Chart root + bar/line marks
+ * @output Unit tests for Chart accessibility (WCAG 1.1.1) and the chart
+ *         root's functional contract — measurement gate, per-series render
+ *         delegation, event layer geometry, palette assignment, and the
+ *         declarative legend/tooltip slots (issue #4295 viz coverage)
  * @position Testing; validates Chart.tsx accessible name + data-table fallback
  */
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
-import {render, screen, act} from '@testing-library/react';
+import {render, screen, act, within} from '@testing-library/react';
 import {Chart} from './Chart';
-import {bar} from './marks';
+import {bar, line} from './marks';
 
 const data = [
   {month: 'Jan', revenue: 100, profit: 20},
@@ -80,6 +83,25 @@ describe('Chart accessible name', () => {
       screen.getByRole('img', {name: 'Quarterly revenue'}),
     ).toBeInTheDocument();
   });
+
+  it('describes the svg from the subtitle and mirrors the title in an svg <title>', () => {
+    const {container} = render(
+      <Chart
+        data={data}
+        xKey="month"
+        series={[bar('revenue')]}
+        title="Quarterly revenue"
+        subtitle="Revenue per month"
+      />,
+    );
+    reportWidth(600);
+
+    const svg = container.querySelector('svg')!;
+    expect(svg.querySelector('title')!.textContent).toBe('Quarterly revenue');
+    const desc = svg.querySelector('desc')!;
+    expect(desc.textContent).toBe('Revenue per month');
+    expect(svg.getAttribute('aria-describedby')).toBe(desc.id);
+  });
 });
 
 describe('Chart data table fallback', () => {
@@ -127,3 +149,113 @@ describe('Chart data table fallback', () => {
     expect(screen.queryByRole('table')).not.toBeInTheDocument();
   });
 });
+
+describe('Chart measurement gate', () => {
+  it('renders only an empty height-reserving placeholder until the container reports a width', () => {
+    const {container} = render(
+      <Chart data={data} xKey="month" series={[bar('revenue')]} height={300} />,
+    );
+
+    expect(container.querySelector('svg')).toBeNull();
+    const placeholder = container.firstElementChild as HTMLElement;
+    expect(placeholder.tagName).toBe('DIV');
+    expect(placeholder.style.height).toBe('300px');
+    expect(placeholder.childElementCount).toBe(0);
+  });
+});
+
+describe('Chart render delegation', () => {
+  it('renders one clipped group per series', () => {
+    const {container} = render(
+      <Chart
+        data={data}
+        xKey="month"
+        series={[bar('revenue'), line('profit')]}
+      />,
+    );
+    reportWidth(600);
+
+    const plot = container.querySelector('g[clip-path]');
+    expect(plot).not.toBeNull();
+    const seriesGroups = Array.from(plot!.children).filter(
+      el => el.tagName === 'g',
+    );
+    expect(seriesGroups).toHaveLength(2);
+    // Each series' render() output lands in its own group: bar paths in the
+    // first, the line's stroke path in the second.
+    expect(seriesGroups[0].querySelectorAll('path').length).toBeGreaterThan(0);
+    expect(seriesGroups[1].querySelectorAll('path').length).toBeGreaterThan(0);
+  });
+
+  it('sizes the transparent event-capture rect to the plot area inside the default margins', () => {
+    const {container} = render(
+      <Chart data={data} xKey="month" series={[bar('revenue')]} height={300} />,
+    );
+    reportWidth(600);
+
+    // 600 - 48 (left) - 24 (right) = 528; 300 - 24 (top) - 32 (bottom) = 244.
+    const eventRect = container.querySelector(
+      'svg > g > rect[fill="transparent"]',
+    );
+    expect(eventRect).not.toBeNull();
+    expect(eventRect).toHaveAttribute('width', '528');
+    expect(eventRect).toHaveAttribute('height', '244');
+  });
+
+  it('assigns distinct palette colors to series that do not declare one', () => {
+    const {container} = render(
+      <Chart
+        data={data}
+        xKey="month"
+        series={[line('revenue'), line('profit')]}
+      />,
+    );
+    reportWidth(600);
+
+    const strokes = Array.from(
+      container.querySelectorAll('g[clip-path] path[stroke]'),
+    ).map(p => p.getAttribute('stroke'));
+    expect(strokes).toHaveLength(2);
+    expect(strokes[0]).toBeTruthy();
+    expect(strokes[1]).toBeTruthy();
+    expect(strokes[0]).not.toBe(strokes[1]);
+  });
+});
+
+describe('Chart legend slot', () => {
+  it('derives legend items from series labels when legend is enabled', () => {
+    render(
+      <Chart
+        data={data}
+        xKey="month"
+        series={[bar('revenue', {label: 'Revenue'}), line('profit')]}
+        legend
+      />,
+    );
+    reportWidth(600);
+
+    const list = screen.getByRole('list', {name: 'Chart legend'});
+    const rows = within(list).getAllByRole('listitem');
+    expect(rows).toHaveLength(2);
+    expect(within(rows[0]).getByText('Revenue')).toBeInTheDocument();
+    // Label falls back to the dataKey when not provided.
+    expect(within(rows[1]).getByText('profit')).toBeInTheDocument();
+  });
+});
+
+describe('Chart tooltip slot', () => {
+  it('mounts the grouped tooltip portal only when tooltip is enabled', () => {
+    const {unmount} = render(
+      <Chart data={data} xKey="month" series={[bar('revenue')]} />,
+    );
+    reportWidth(600);
+    expect(document.querySelector('[role="tooltip"]')).toBeNull();
+    unmount();
+
+    render(
+      <Chart data={data} xKey="month" series={[bar('revenue')]} tooltip />,
+    );
+    reportWidth(600);
+    expect(document.querySelector('[role="tooltip"]')).not.toBeNull();
+  });
+});

package/src/ChartAxis.test.tsx

@@ -0,0 +1,131 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartAxis.test.tsx
+ * @input Uses vitest, @testing-library/react, Chart, ChartAxis, bar mark
+ * @output Functional tests for axis rendering — group semantics, band/linear
+ *         tick labels, default edge-line rules, custom formatting, truncation,
+ *         and label capping
+ * @position Colocated test for ChartAxis.tsx (issue #4295 viz coverage)
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, screen, act, within} from '@testing-library/react';
+import {Chart} from './Chart';
+import {ChartAxis} from './ChartAxis';
+import {bar} from './marks/bar';
+
+const DATA = [
+  {month: 'Jan', sales: 4},
+  {month: 'Feb', sales: 10},
+  {month: 'Mar', sales: 2},
+];
+
+// Capture the ResizeObserver callback so tests can drive the reported width.
+let resizeCallback: ResizeObserverCallback | undefined;
+
+beforeEach(() => {
+  resizeCallback = undefined;
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      constructor(cb: ResizeObserverCallback) {
+        resizeCallback = cb;
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function reportWidth(width: number) {
+  act(() => {
+    resizeCallback?.(
+      [{contentRect: {width}} as unknown as ResizeObserverEntry],
+      {} as ResizeObserver,
+    );
+  });
+}
+
+function renderChart(axes: React.ReactNode, data = DATA) {
+  const utils = render(
+    <Chart data={data} xKey="month" series={[bar('sales')]} axes={axes} />,
+  );
+  reportWidth(600);
+  return utils;
+}
+
+describe('ChartAxis bottom (band scale)', () => {
+  it('renders a labeled group with one tick label per category', () => {
+    renderChart(<ChartAxis position="bottom" />);
+    const axis = screen.getByRole('group', {name: 'bottom axis'});
+    expect(within(axis).getByText('Jan')).toBeInTheDocument();
+    expect(within(axis).getByText('Feb')).toBeInTheDocument();
+    expect(within(axis).getByText('Mar')).toBeInTheDocument();
+  });
+
+  it('is translated to the bottom edge of the plot and draws its edge line by default', () => {
+    renderChart(<ChartAxis position="bottom" />);
+    const axis = screen.getByRole('group', {name: 'bottom axis'});
+    // Inner height for the default 300px chart: 300 - 24 - 32 = 244.
+    expect(axis).toHaveAttribute('transform', 'translate(0,244)');
+    const edge = axis.querySelector('line')!;
+    expect(edge).not.toBeNull();
+    expect(edge).toHaveAttribute('x2', '528');
+  });
+
+  it('caps labels to maxTicks by evenly skipping categories', () => {
+    renderChart(<ChartAxis position="bottom" maxTicks={2} />);
+    const axis = screen.getByRole('group', {name: 'bottom axis'});
+    // 3 categories capped at 2 → step 2 → indices 0 and 2 survive.
+    expect(within(axis).getByText('Jan')).toBeInTheDocument();
+    expect(within(axis).getByText('Mar')).toBeInTheDocument();
+    expect(within(axis).queryByText('Feb')).not.toBeInTheDocument();
+  });
+
+  it('truncates long category labels with an ellipsis', () => {
+    renderChart(<ChartAxis position="bottom" truncate={4} />, [
+      {month: 'January', sales: 4},
+      {month: 'Feb', sales: 10},
+    ]);
+    const axis = screen.getByRole('group', {name: 'bottom axis'});
+    expect(within(axis).getByText('Janu…')).toBeInTheDocument();
+    // Short labels are left alone.
+    expect(within(axis).getByText('Feb')).toBeInTheDocument();
+  });
+});
+
+describe('ChartAxis left (linear scale)', () => {
+  it('renders d3-formatted value ticks without an edge line by default', () => {
+    renderChart(<ChartAxis position="left" />);
+    const axis = screen.getByRole('group', {name: 'left axis'});
+    // Bar series pins a zero baseline → domain [0, 10] → ticks 0,2,...,10.
+    expect(within(axis).getByText('0')).toBeInTheDocument();
+    expect(within(axis).getByText('4')).toBeInTheDocument();
+    expect(within(axis).getByText('10')).toBeInTheDocument();
+    // Documented default: only the bottom axis draws its edge line.
+    expect(axis.querySelector('line')).toBeNull();
+  });
+
+  it('applies a custom tick formatter', () => {
+    renderChart(
+      <ChartAxis position="left" tickFormat={v => `$${String(v)}`} />,
+    );
+    const axis = screen.getByRole('group', {name: 'left axis'});
+    expect(within(axis).getByText('$0')).toBeInTheDocument();
+    expect(within(axis).getByText('$10')).toBeInTheDocument();
+  });
+
+  it('showTicks draws a perpendicular mark per tick and forces the axis line on', () => {
+    renderChart(<ChartAxis position="left" showTicks />);
+    const axis = screen.getByRole('group', {name: 'left axis'});
+    const lines = axis.querySelectorAll('line');
+    // 6 ticks (0..10 by 2) + the forced edge line.
+    expect(lines).toHaveLength(7);
+  });
+});

package/src/ChartGrid.test.tsx

@@ -0,0 +1,121 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartGrid.test.tsx
+ * @input Uses vitest, @testing-library/react, Chart, ChartGrid, bar mark
+ * @output Functional tests for grid lines — horizontal default, the skipped
+ *         y=0 line, and vertical lines at band centers
+ * @position Colocated test for ChartGrid.tsx (issue #4295 viz coverage)
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, act} from '@testing-library/react';
+import {Chart} from './Chart';
+import {ChartGrid} from './ChartGrid';
+import {bar} from './marks/bar';
+
+const DATA = [
+  {month: 'Jan', sales: 4},
+  {month: 'Feb', sales: 10},
+  {month: 'Mar', sales: 2},
+];
+
+// Capture the ResizeObserver callback so tests can drive the reported width.
+let resizeCallback: ResizeObserverCallback | undefined;
+
+beforeEach(() => {
+  resizeCallback = undefined;
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      constructor(cb: ResizeObserverCallback) {
+        resizeCallback = cb;
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function reportWidth(width: number) {
+  act(() => {
+    resizeCallback?.(
+      [{contentRect: {width}} as unknown as ResizeObserverEntry],
+      {} as ResizeObserver,
+    );
+  });
+}
+
+function renderGrid(grid: React.ReactNode) {
+  const utils = render(
+    <Chart data={DATA} xKey="month" series={[bar('sales')]} grid={grid} />,
+  );
+  reportWidth(600);
+  // Marks render paths and the event layer is a rect, so every <line> in the
+  // svg belongs to the grid (no axes are mounted in these tests).
+  const lines = Array.from(utils.container.querySelectorAll('svg line'));
+  return {...utils, lines};
+}
+
+describe('ChartGrid', () => {
+  it('draws horizontal lines across the plot for every y tick except the y=0 baseline', () => {
+    const {lines} = renderGrid(<ChartGrid />);
+    // Domain [0, 10] → ticks 0,2,4,6,8,10; the 0 line is skipped → 5 lines.
+    expect(lines).toHaveLength(5);
+    for (const l of lines) {
+      expect(l.getAttribute('x1')).toBe('0');
+      expect(l.getAttribute('x2')).toBe('528'); // full plot width
+      expect(l.getAttribute('y1')).toBe(l.getAttribute('y2')); // horizontal
+      // y=0 maps to the plot bottom (244) — never double-drawn over the axis.
+      expect(l.getAttribute('y1')).not.toBe('244');
+    }
+  });
+
+  it('draws a vertical line at each band center when vertical is enabled', () => {
+    const {lines} = renderGrid(<ChartGrid horizontal={false} vertical />);
+    expect(lines).toHaveLength(3); // one per category
+    for (const l of lines) {
+      expect(l.getAttribute('x1')).toBe(l.getAttribute('x2')); // vertical
+      expect(l.getAttribute('y1')).toBe('0');
+      expect(l.getAttribute('y2')).toBe('244'); // full plot height
+    }
+    // Band centers are strictly increasing across categories.
+    const xs = lines.map(l => Number(l.getAttribute('x1')));
+    expect(xs[0]).toBeLessThan(xs[1]);
+    expect(xs[1]).toBeLessThan(xs[2]);
+  });
+
+  it('combines horizontal and vertical lines when both are enabled', () => {
+    const {lines} = renderGrid(<ChartGrid horizontal vertical />);
+    expect(lines).toHaveLength(8); // 5 horizontal + 3 vertical
+  });
+
+  it('places vertical lines at d3 tick values on a linear x scale', () => {
+    const numeric = [
+      {month: 0, sales: 1},
+      {month: 5, sales: 7},
+      {month: 10, sales: 3},
+    ];
+    const utils = render(
+      <Chart
+        data={numeric}
+        xKey="month"
+        series={[bar('sales')]}
+        grid={<ChartGrid horizontal={false} vertical />}
+      />,
+    );
+    reportWidth(600);
+    const lines = Array.from(utils.container.querySelectorAll('svg line'));
+    // Linear domain [0, 10] → ticks 0,2,4,6,8,10 → 6 evenly spaced lines.
+    expect(lines).toHaveLength(6);
+    const xs = lines.map(l => Number(l.getAttribute('x1')));
+    expect(xs[0]).toBe(0);
+    expect(xs[5]).toBe(528);
+    expect(xs[1] - xs[0]).toBeCloseTo(528 / 5);
+  });
+});

package/src/ChartLegend.test.tsx

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartLegend.test.tsx
+ * @input Uses vitest, @testing-library/react, ChartLegend
+ * @output Functional tests for the standalone chart legend
+ * @position Colocated test for ChartLegend.tsx (issue #4295 viz coverage)
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, within} from '@testing-library/react';
+import {ChartLegend} from './ChartLegend';
+
+const items = [
+  {label: 'Revenue', color: '#ff0000', type: 'bar'},
+  {label: 'Profit', color: '#00ff00', type: 'line'},
+];
+
+describe('ChartLegend', () => {
+  it('exposes list semantics with one item per legend entry', () => {
+    render(<ChartLegend items={items} />);
+    const list = screen.getByRole('list', {name: 'Chart legend'});
+    const rows = within(list).getAllByRole('listitem');
+    expect(rows).toHaveLength(2);
+    expect(within(rows[0]).getByText('Revenue')).toBeInTheDocument();
+    expect(within(rows[1]).getByText('Profit')).toBeInTheDocument();
+  });
+
+  it('renders a decorative swatch in each entry with the item color', () => {
+    render(<ChartLegend items={items} />);
+    const rows = screen.getAllByRole('listitem');
+    const firstSwatch = rows[0].querySelector('[aria-hidden="true"]');
+    const secondSwatch = rows[1].querySelector('[aria-hidden="true"]');
+    expect(firstSwatch).not.toBeNull();
+    expect(firstSwatch!.getAttribute('style')).toContain('#ff0000');
+    expect(secondSwatch!.getAttribute('style')).toContain('#00ff00');
+  });
+
+  it('renders nothing when there are no items', () => {
+    const {container} = render(<ChartLegend items={[]} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders nothing when items are omitted entirely', () => {
+    const {container} = render(<ChartLegend />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('keeps list semantics in the vertical (start/end) orientation', () => {
+    render(<ChartLegend items={items} position="end" />);
+    const list = screen.getByRole('list', {name: 'Chart legend'});
+    expect(within(list).getAllByRole('listitem')).toHaveLength(2);
+  });
+});

package/src/ChartSwatch.test.tsx

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartSwatch.test.tsx
+ * @input Uses vitest, @testing-library/react, ChartSwatch
+ * @output Functional tests for the ChartSwatch color primitive
+ * @position Colocated test for ChartSwatch.tsx (issue #4295 viz coverage)
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render} from '@testing-library/react';
+import {ChartSwatch, swatchVariantForType} from './ChartSwatch';
+
+describe('ChartSwatch', () => {
+  it('renders a decorative element hidden from the accessibility tree', () => {
+    const {container} = render(<ChartSwatch color="#ff0000" />);
+    const swatch = container.firstElementChild;
+    expect(swatch).not.toBeNull();
+    expect(swatch).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('applies the given color through a dynamic style', () => {
+    const {container} = render(<ChartSwatch color="#ff0000" />);
+    const swatch = container.firstElementChild as HTMLElement;
+    expect(swatch.getAttribute('style')).toContain('#ff0000');
+  });
+
+  it('styles the square and line variants differently', () => {
+    const {container: square} = render(<ChartSwatch color="#000" />);
+    const {container: line} = render(
+      <ChartSwatch color="#000" variant="line" />,
+    );
+    expect(square.firstElementChild!.className).not.toBe(
+      line.firstElementChild!.className,
+    );
+  });
+});
+
+describe('swatchVariantForType', () => {
+  it('maps bar series to the square chip', () => {
+    expect(swatchVariantForType('bar')).toBe('square');
+  });
+
+  it('maps every non-bar series (and unknown types) to the line stroke', () => {
+    expect(swatchVariantForType('line')).toBe('line');
+    expect(swatchVariantForType('dot')).toBe('line');
+    expect(swatchVariantForType('area')).toBe('line');
+    expect(swatchVariantForType(undefined)).toBe('line');
+  });
+});

package/src/ChartTooltip.test.tsx

@@ -0,0 +1,282 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChartTooltip.test.tsx
+ * @input Uses vitest, @testing-library/react, ChartTooltip, ChartProvider,
+ *        d3-scale
+ * @output Functional tests for the grouped tooltip — portal lifecycle, pointer
+ *         subscription, card content/visibility, hover dots, crosshair vs band
+ *         highlight, and the custom render contract
+ * @position Colocated test for ChartTooltip.tsx (issue #4295 viz coverage).
+ *           Renders under a hand-built ChartProvider so the pointer stream can
+ *           be driven directly (jsdom has no SVG geometry for the real one).
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, act} from '@testing-library/react';
+import {scaleLinear, scaleBand} from 'd3-scale';
+import {ChartTooltip} from './ChartTooltip';
+import {ChartProvider} from './ChartContext';
+import type {
+  ChartContext,
+  ChartPointerEvent,
+  ResolvedPoint,
+  SeriesDef,
+} from './types';
+
+const DATA = [
+  {month: 'Jan', sales: 3, profit: 1},
+  {month: 'Feb', sales: 7, profit: 2},
+  {month: 'Mar', sales: 5, profit: 4},
+];
+
+const SALES_POINTS: ResolvedPoint[] = [
+  {px: 50, py: 120, py0: 200, dataIndex: 0},
+  {px: 250, py: 40, py0: 200, dataIndex: 1},
+  {px: 450, py: 80, py0: 200, dataIndex: 2},
+];
+
+/** Minimal post-layout series def, annotated the way computeLayout would. */
+function makeSeries(overrides: Partial<SeriesDef> = {}): SeriesDef {
+  return {
+    type: 'line',
+    key: 'sales',
+    dataKeys: ['sales'],
+    label: 'Sales',
+    color: '#ff0000',
+    layout: {},
+    resolve: () => [],
+    render: () => null,
+    _uid: '0:sales',
+    ...overrides,
+  } as SeriesDef;
+}
+
+interface Harness {
+  ctx: ChartContext;
+  handlers: Set<(e: ChartPointerEvent) => void>;
+  dispatch: (e: ChartPointerEvent) => void;
+}
+
+function makeHarness(overrides: Partial<ChartContext> = {}): Harness {
+  const handlers = new Set<(e: ChartPointerEvent) => void>();
+  const ctx: ChartContext = {
+    width: 500,
+    height: 200,
+    margin: {top: 24, right: 24, bottom: 32, left: 48},
+    data: DATA,
+    xKey: 'month',
+    xScale: scaleBand<string>()
+      .domain(['Jan', 'Feb', 'Mar'])
+      .range([0, 500])
+      .padding(0.2),
+    yScale: scaleLinear().domain([0, 10]).range([200, 0]),
+    resolved: new Map([['0:sales', SALES_POINTS]]),
+    onPointer: handler => {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    },
+    svgRef: {current: null},
+    ...overrides,
+  };
+  const dispatch = (e: ChartPointerEvent) => {
+    act(() => {
+      for (const h of handlers) {
+        h(e);
+      }
+    });
+  };
+  return {ctx, handlers, dispatch};
+}
+
+function renderTooltip(
+  harness: Harness,
+  props: React.ComponentProps<typeof ChartTooltip> = {},
+) {
+  return render(
+    <ChartProvider value={harness.ctx}>
+      <svg>
+        <g>
+          <ChartTooltip series={[makeSeries()]} {...props} />
+        </g>
+      </svg>
+    </ChartProvider>,
+  );
+}
+
+const hoverAt = (index: number): ChartPointerEvent => ({
+  x: SALES_POINTS[index].px,
+  y: 100,
+  nearest: {...SALES_POINTS[index], seriesKey: 'sales'},
+  active: false,
+});
+
+const pointerLeave: ChartPointerEvent = {
+  x: -1,
+  y: -1,
+  nearest: null,
+  active: false,
+};
+
+const card = () => document.querySelector('[role="tooltip"]') as HTMLElement;
+
+describe('ChartTooltip card', () => {
+  it('portals an initially empty tooltip card into document.body', () => {
+    const harness = makeHarness();
+    const {container} = renderTooltip(harness);
+    expect(card()).not.toBeNull();
+    expect(card().parentElement).toBe(document.body);
+    // The card lives outside the chart subtree.
+    expect(container.querySelector('[role="tooltip"]')).toBeNull();
+    expect(card().textContent).toBe('');
+  });
+
+  it('shows the hovered x value and the bare value for a single series', () => {
+    const harness = makeHarness();
+    renderTooltip(harness);
+    harness.dispatch(hoverAt(1));
+    expect(card().textContent).toContain('Feb');
+    expect(card().textContent).toContain('7');
+  });
+
+  it('lists a labeled row per series for multi-series charts', () => {
+    const profitPoints = SALES_POINTS.map(p => ({...p, py: p.py + 30}));
+    const harness = makeHarness({
+      resolved: new Map([
+        ['0:sales', SALES_POINTS],
+        ['1:profit', profitPoints],
+      ]),
+    });
+    const series = [
+      makeSeries(),
+      makeSeries({
+        key: 'profit',
+        dataKeys: ['profit'],
+        label: 'Profit',
+        _uid: '1:profit',
+      }),
+    ];
+    renderTooltip(harness, {series});
+    harness.dispatch(hoverAt(1));
+    expect(card().textContent).toContain('Sales');
+    expect(card().textContent).toContain('7');
+    expect(card().textContent).toContain('Profit');
+    expect(card().textContent).toContain('2');
+  });
+
+  it('reveals the card on hover and hides it again when the pointer leaves', () => {
+    const svgEl = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    const harness = makeHarness({svgRef: {current: svgEl}});
+    renderTooltip(harness);
+
+    harness.dispatch(hoverAt(0));
+    expect(card().style.display).toBe('block');
+
+    harness.dispatch(pointerLeave);
+    expect(card().style.display).toBe('none');
+  });
+
+  it('pins the card beside the hovered point for placement="right"', () => {
+    const svgEl = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    const harness = makeHarness({svgRef: {current: svgEl}});
+    renderTooltip(harness, {placement: 'right'});
+    harness.dispatch(hoverAt(1));
+    // jsdom rects are zero, so left = svgLeft(0) + margin.left(48) + px(250)
+    // + the 8px gap.
+    expect(card().style.display).toBe('block');
+    expect(card().style.left).toBe('306px');
+  });
+
+  it('hides the card when the hovered index no longer exists in data', () => {
+    const svgEl = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    const harness = makeHarness({svgRef: {current: svgEl}});
+    renderTooltip(harness);
+    harness.dispatch({
+      x: 0,
+      y: 0,
+      nearest: {px: 50, py: 120, py0: 200, dataIndex: 99, seriesKey: 'sales'},
+      active: false,
+    });
+    expect(card().textContent).toBe('');
+    expect(card().style.display).toBe('none');
+  });
+});
+
+describe('ChartTooltip hover indicators', () => {
+  it('marks the hovered point of each series with a dot in the series color', () => {
+    const harness = makeHarness();
+    const {container} = renderTooltip(harness);
+    harness.dispatch(hoverAt(1));
+    const dot = container.querySelector('circle')!;
+    expect(dot).not.toBeNull();
+    expect(dot).toHaveAttribute('cx', '250');
+    expect(dot).toHaveAttribute('cy', '40');
+    expect(dot).toHaveAttribute('stroke', '#ff0000');
+  });
+
+  it('skips the hover dot when the series value is missing at that index', () => {
+    const gappy = SALES_POINTS.map((p, i) => (i === 1 ? {...p, py: NaN} : p));
+    const harness = makeHarness({resolved: new Map([['0:sales', gappy]])});
+    const {container} = renderTooltip(harness);
+    harness.dispatch(hoverAt(1));
+    expect(container.querySelector('circle')).toBeNull();
+  });
+
+  it('draws a vertical crosshair through the hovered x for line charts', () => {
+    const harness = makeHarness();
+    const {container} = renderTooltip(harness);
+    harness.dispatch(hoverAt(1));
+    const crosshair = container.querySelector('line')!;
+    expect(crosshair).not.toBeNull();
+    expect(crosshair.getAttribute('x1')).toBe(crosshair.getAttribute('x2'));
+    expect(crosshair).toHaveAttribute('y1', '0');
+    expect(crosshair).toHaveAttribute('y2', '200');
+  });
+
+  it('draws a soft band-highlight rect instead of a crosshair when the chart has bars', () => {
+    const harness = makeHarness();
+    const {container} = renderTooltip(harness, {
+      series: [makeSeries({type: 'bar'})],
+    });
+    harness.dispatch(hoverAt(1));
+    expect(container.querySelector('line')).toBeNull();
+    const highlight = container.querySelector('rect')!;
+    expect(highlight).not.toBeNull();
+    expect(Number(highlight.getAttribute('width'))).toBeGreaterThan(0);
+  });
+});
+
+describe('ChartTooltip custom render', () => {
+  it('replaces the card body and receives the x value plus one row per series', () => {
+    const renderFn = vi.fn(() => <span>custom body</span>);
+    const harness = makeHarness();
+    renderTooltip(harness, {render: renderFn});
+    harness.dispatch(hoverAt(1));
+    expect(card().textContent).toBe('custom body');
+    expect(renderFn).toHaveBeenCalledWith('Feb', [
+      expect.objectContaining({key: 'sales', label: 'Sales', value: 7}),
+    ]);
+  });
+
+  it('hides the card when the custom render opts out by returning null', () => {
+    const svgEl = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    const harness = makeHarness({svgRef: {current: svgEl}});
+    renderTooltip(harness, {render: () => null});
+    harness.dispatch(hoverAt(1));
+    expect(card().textContent).toBe('');
+    expect(card().style.display).toBe('none');
+  });
+});
+
+describe('ChartTooltip lifecycle', () => {
+  it('removes the portal and unsubscribes from the pointer stream on unmount', () => {
+    const harness = makeHarness();
+    const {unmount} = renderTooltip(harness);
+    expect(harness.handlers.size).toBe(1);
+    unmount();
+    expect(card()).toBeNull();
+    expect(harness.handlers.size).toBe(0);
+  });
+});

package/src/marks/marks.test.tsx

@@ -0,0 +1,443 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file marks/marks.test.tsx
+ * @input Uses vitest, @testing-library/react, Chart, all mark factories
+ * @output Functional tests for the mark renderers — SVG shape output per mark
+ *         type, missing-value gap handling, and GL marks degrading safely when
+ *         WebGL is unavailable (jsdom has no canvas contexts)
+ * @position Colocated test for the marks/ directory (issue #4295 viz coverage)
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, act, screen} from '@testing-library/react';
+import {Chart} from '../Chart';
+import {bar} from './bar';
+import {line} from './line';
+import {dot} from './dot';
+import {area} from './area';
+import {band} from './band';
+import {candlestick} from './candlestick';
+import {errorBar} from './errorBar';
+import {referenceLine} from './referenceLine';
+import {dotGL} from './dotGL';
+import {dotGLInteractive} from './dotGLInteractive';
+import {heatmapGL} from './heatmapGL';
+import {streamGL, type StreamGLHandle} from './streamGL';
+import type {SeriesDef} from '../types';
+
+const DATA = [
+  {m: 'A', v: 4},
+  {m: 'B', v: 7},
+  {m: 'C', v: 2},
+];
+
+// One missing value in the middle — marks must gap, not draw at the baseline.
+const GAPPY = [
+  {m: 'A', v: 4},
+  {m: 'B', v: null},
+  {m: 'C', v: 2},
+];
+
+const BOUNDS = [
+  {m: 'A', hi: 5, lo: 1},
+  {m: 'B', hi: 8, lo: 4},
+  {m: 'C', hi: 6, lo: 2},
+];
+
+// Capture the ResizeObserver callback so tests can drive the reported width.
+let resizeCallback: ResizeObserverCallback | undefined;
+
+beforeEach(() => {
+  resizeCallback = undefined;
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      constructor(cb: ResizeObserverCallback) {
+        resizeCallback = cb;
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function reportWidth(width: number) {
+  act(() => {
+    resizeCallback?.(
+      [{contentRect: {width}} as unknown as ResizeObserverEntry],
+      {} as ResizeObserver,
+    );
+  });
+}
+
+/** Render a chart, report a width, and return the clipped plot group. */
+function renderMarks(
+  series: SeriesDef[],
+  data: Record<string, unknown>[] = DATA,
+  xKey = 'm',
+  extraProps: Partial<React.ComponentProps<typeof Chart>> = {},
+) {
+  const utils = render(
+    <Chart data={data} xKey={xKey} series={series} {...extraProps} />,
+  );
+  reportWidth(600);
+  const plot = utils.container.querySelector('g[clip-path]')!;
+  return {...utils, plot};
+}
+
+describe('bar', () => {
+  it('renders one top-rounded path per datum in the configured color', () => {
+    const {plot} = renderMarks([bar('v', {color: '#123456'})]);
+    const paths = plot.querySelectorAll('path');
+    expect(paths).toHaveLength(3);
+    for (const p of paths) {
+      expect(p).toHaveAttribute('fill', '#123456');
+      expect(p.getAttribute('d')).toMatch(/^M/);
+      // Positive bars round the top corners (default radius 4).
+      expect(p.getAttribute('d')).toContain('Q');
+    }
+  });
+
+  it('skips bars whose value is missing instead of drawing them at the baseline', () => {
+    const {plot} = renderMarks([bar('v')], GAPPY);
+    expect(plot.querySelectorAll('path')).toHaveLength(2);
+  });
+
+  it('stacked bars round only the topmost layer', () => {
+    const stacked = [
+      {m: 'A', a: 2, b: 3},
+      {m: 'B', a: 4, b: 1},
+    ];
+    const {plot} = renderMarks(
+      [bar('a', {stack: 'total'}), bar('b', {stack: 'total'})],
+      stacked,
+    );
+    const groups = Array.from(plot.children).filter(el => el.tagName === 'g');
+    const [lowerPaths, upperPaths] = groups.map(g =>
+      Array.from(g.querySelectorAll('path')),
+    );
+    expect(lowerPaths).toHaveLength(2);
+    expect(upperPaths).toHaveLength(2);
+    // The lower layer is drawn square; only the stack top gets rounded corners.
+    for (const p of lowerPaths) {
+      expect(p.getAttribute('d')).not.toContain('Q');
+    }
+    for (const p of upperPaths) {
+      expect(p.getAttribute('d')).toContain('Q');
+    }
+  });
+
+  it('grouped bars render side by side within the band', () => {
+    const grouped = [
+      {m: 'A', a: 2, b: 3},
+      {m: 'B', a: 4, b: 1},
+    ];
+    const {plot} = renderMarks(
+      [bar('a', {group: 'g'}), bar('b', {group: 'g'})],
+      grouped,
+    );
+    const groups = Array.from(plot.children).filter(el => el.tagName === 'g');
+    const firstX = (g: Element) =>
+      Number(
+        g
+          .querySelector('path')!
+          .getAttribute('d')!
+          .match(/^M([\d.]+)/)![1],
+      );
+    // For the same category, the second group's sub-bar starts further right.
+    expect(firstX(groups[1])).toBeGreaterThan(firstX(groups[0]));
+  });
+});
+
+describe('line', () => {
+  it('renders a single stroke path with the configured color and width', () => {
+    const {plot} = renderMarks([line('v', {color: '#ff0000', strokeWidth: 3})]);
+    const paths = plot.querySelectorAll('path');
+    expect(paths).toHaveLength(1);
+    expect(paths[0]).toHaveAttribute('stroke', '#ff0000');
+    expect(paths[0]).toHaveAttribute('stroke-width', '3');
+    expect(paths[0]).toHaveAttribute('fill', 'none');
+    expect(paths[0].getAttribute('d')).toMatch(/^M/);
+  });
+
+  it('draws per-point dots only where the value is finite', () => {
+    const {plot} = renderMarks([line('v', {dots: true})], GAPPY);
+    expect(plot.querySelectorAll('circle')).toHaveLength(2);
+  });
+});
+
+describe('dot', () => {
+  it('renders one circle per datum with the configured radius', () => {
+    const {plot} = renderMarks([dot('v', {radius: 5})]);
+    const circles = plot.querySelectorAll('circle');
+    expect(circles).toHaveLength(3);
+    for (const c of circles) {
+      expect(c).toHaveAttribute('r', '5');
+      expect(c).toHaveAttribute('opacity', '0.8'); // default
+    }
+  });
+
+  it('skips points whose value is missing', () => {
+    const {plot} = renderMarks([dot('v')], GAPPY);
+    expect(plot.querySelectorAll('circle')).toHaveLength(2);
+  });
+
+  it('dodge spreads coincident points horizontally, centered on the shared x', () => {
+    // Two rows in the same category land on the same band center.
+    const coincident = [
+      {m: 'A', v: 4},
+      {m: 'A', v: 6},
+      {m: 'B', v: 2},
+    ];
+    const {plot} = renderMarks(
+      [dot('v', {dodge: true, radius: 4})],
+      coincident,
+    );
+    const circles = Array.from(plot.querySelectorAll('circle'));
+    expect(circles).toHaveLength(3);
+    const [a1, a2] = circles.slice(0, 2).map(c => Number(c.getAttribute('cx')));
+    // Spacing is radius * 2 + 1 = 9px, split symmetrically around the center.
+    expect(a2 - a1).toBeCloseTo(9);
+    const bandCenter = (a1 + a2) / 2;
+    expect(Number(circles[0].getAttribute('cx'))).toBeCloseTo(bandCenter - 4.5);
+  });
+});
+
+describe('area', () => {
+  it('renders a translucent fill path plus a stroke path by default', () => {
+    const {plot} = renderMarks([area('v', {color: '#00aa00'})]);
+    const paths = plot.querySelectorAll('path');
+    expect(paths).toHaveLength(2);
+    expect(paths[0]).toHaveAttribute('fill', '#00aa00');
+    expect(paths[0]).toHaveAttribute('fill-opacity', '0.3');
+    expect(paths[1]).toHaveAttribute('fill', 'none');
+    expect(paths[1]).toHaveAttribute('stroke', '#00aa00');
+  });
+
+  it('omits the stroke path when stroke is disabled', () => {
+    const {plot} = renderMarks([area('v', {stroke: false})]);
+    expect(plot.querySelectorAll('path')).toHaveLength(1);
+  });
+
+  it('gradient mode defines a per-series gradient and fills with it', () => {
+    const {plot} = renderMarks([area('v', {gradient: true})]);
+    const gradient = plot.querySelector('linearGradient')!;
+    expect(gradient).not.toBeNull();
+    expect(gradient.querySelectorAll('stop')).toHaveLength(2);
+    const fillPath = plot.querySelector('path')!;
+    expect(fillPath.getAttribute('fill')).toBe(`url(#${gradient.id})`);
+  });
+});
+
+describe('band', () => {
+  it('fills the region between the upper and lower bounds', () => {
+    const {plot} = renderMarks([band({upper: 'hi', lower: 'lo'})], BOUNDS);
+    const paths = plot.querySelectorAll('path');
+    expect(paths).toHaveLength(1);
+    expect(paths[0]).toHaveAttribute('fill-opacity', '0.15'); // default
+    expect(paths[0].getAttribute('d')).toMatch(/^M/);
+  });
+
+  it('renders nothing when no point has both bounds', () => {
+    const missing = [
+      {m: 'A', lo: 1},
+      {m: 'B', lo: 4},
+    ];
+    const {plot} = renderMarks([band({upper: 'hi', lower: 'lo'})], missing);
+    expect(plot.querySelectorAll('path')).toHaveLength(0);
+  });
+});
+
+describe('candlestick', () => {
+  const OHLC = [
+    {m: 'A', o: 2, h: 6, l: 1, c: 5}, // up: close >= open
+    {m: 'B', o: 6, h: 7, l: 2, c: 3}, // down
+    {m: 'C', o: 3, h: 5, l: 2, c: 4}, // up
+  ];
+  const series = () =>
+    candlestick({open: 'o', high: 'h', low: 'l', close: 'c'});
+
+  it('renders a wick line and a body rect per candle, colored by direction', () => {
+    const {plot} = renderMarks([series()], OHLC);
+    const rects = plot.querySelectorAll('rect');
+    const wicks = plot.querySelectorAll('line');
+    expect(rects).toHaveLength(3);
+    expect(wicks).toHaveLength(3);
+    expect(rects[0]).toHaveAttribute('fill', 'var(--color-success)');
+    expect(rects[1]).toHaveAttribute('fill', 'var(--color-error)');
+    expect(rects[2]).toHaveAttribute('fill', 'var(--color-success)');
+  });
+
+  it('skips candles missing any OHLC field', () => {
+    const gappy = [OHLC[0], {m: 'B', o: 6, l: 2, c: 3}, OHLC[2]];
+    const {plot} = renderMarks([series()], gappy);
+    expect(plot.querySelectorAll('rect')).toHaveLength(2);
+    expect(plot.querySelectorAll('line')).toHaveLength(2);
+  });
+});
+
+describe('errorBar', () => {
+  it('renders a stem plus two whisker caps per point', () => {
+    const {plot} = renderMarks([errorBar({high: 'hi', low: 'lo'})], BOUNDS);
+    const lines = plot.querySelectorAll('line');
+    expect(lines).toHaveLength(9); // 3 points x (stem + upper cap + lower cap)
+    for (const l of lines) {
+      expect(l).toHaveAttribute('stroke', 'var(--color-text-primary)');
+    }
+  });
+
+  it('skips whiskers missing either bound', () => {
+    const gappy = [BOUNDS[0], {m: 'B', hi: 8}, BOUNDS[2]];
+    const {plot} = renderMarks([errorBar({high: 'hi', low: 'lo'})], gappy);
+    expect(plot.querySelectorAll('line')).toHaveLength(6);
+  });
+});
+
+describe('referenceLine', () => {
+  it('draws a dashed horizontal line across the plot with a label badge', () => {
+    const {plot} = renderMarks([
+      line('v'),
+      referenceLine({y: 5, label: 'Target'}),
+    ]);
+    const dashed = plot.querySelector('line[stroke-dasharray="6 3"]')!;
+    expect(dashed).not.toBeNull();
+    expect(dashed).toHaveAttribute('x1', '0');
+    expect(dashed).toHaveAttribute('x2', '528'); // full plot width
+    expect(dashed.getAttribute('y1')).toBe(dashed.getAttribute('y2'));
+    expect(screen.getByText('Target')).toBeInTheDocument();
+    expect(plot.querySelector('rect[rx="3"]')).not.toBeNull(); // badge chip
+  });
+
+  it('shades a band between y and y2 bounded by two dashed lines', () => {
+    const {plot} = renderMarks([line('v'), referenceLine({y: 2, y2: 6})]);
+    expect(plot.querySelectorAll('line[stroke-dasharray="6 3"]')).toHaveLength(
+      2,
+    );
+    const bandRect = plot.querySelector('rect[opacity="0.1"]')!;
+    expect(bandRect).not.toBeNull();
+    expect(bandRect).toHaveAttribute('width', '528');
+  });
+
+  it('draws a vertical dashed line at a numeric x on a linear scale', () => {
+    const numeric = [
+      {x: 0, v: 1},
+      {x: 5, v: 7},
+      {x: 10, v: 3},
+    ];
+    const {plot} = renderMarks(
+      [line('v'), referenceLine({x: 5})],
+      numeric,
+      'x',
+    );
+    const dashed = plot.querySelector('line[stroke-dasharray="6 3"]')!;
+    expect(dashed).not.toBeNull();
+    expect(dashed.getAttribute('x1')).toBe(dashed.getAttribute('x2'));
+    expect(dashed).toHaveAttribute('y1', '0');
+    expect(dashed).toHaveAttribute('y2', '244'); // full plot height
+  });
+});
+
+describe('GL marks without WebGL', () => {
+  let getContextSpy: ReturnType<typeof vi.fn>;
+  const canvasProto = HTMLCanvasElement.prototype;
+  let originalGetContext: typeof canvasProto.getContext;
+  // jsdom has no SVG geometry API; give markers a null CTM so
+  // mountCanvasOverSVG takes its documented (0,0) fallback.
+  const svgProto = SVGElement.prototype as unknown as {
+    getScreenCTM?: () => unknown;
+  };
+  let hadGetScreenCTM: boolean;
+
+  beforeEach(() => {
+    originalGetContext = canvasProto.getContext;
+    getContextSpy = vi.fn(() => null);
+    canvasProto.getContext =
+      getContextSpy as unknown as typeof canvasProto.getContext;
+    hadGetScreenCTM = 'getScreenCTM' in svgProto;
+    if (!hadGetScreenCTM) {
+      svgProto.getScreenCTM = () => null;
+    }
+  });
+
+  afterEach(() => {
+    canvasProto.getContext = originalGetContext;
+    if (!hadGetScreenCTM) {
+      delete svgProto.getScreenCTM;
+    }
+  });
+
+  it('dotGL mounts an absolutely-positioned canvas overlay and draws nothing', () => {
+    const {container, unmount} = renderMarks([dotGL('v', {color: '#4f46e5'})]);
+    const canvas = container.querySelector('canvas')!;
+    expect(canvas).not.toBeNull();
+    expect(canvas.style.position).toBe('absolute');
+    expect(getContextSpy).toHaveBeenCalledWith(
+      'webgl',
+      expect.objectContaining({alpha: true}),
+    );
+    // Every context request failed → no GL drawing could have happened.
+    expect(getContextSpy.mock.results.every(r => r.value === null)).toBe(true);
+    unmount();
+  });
+
+  it('heatmapGL mounts its cell canvas when both axes are categorical', () => {
+    const heat = [
+      {hour: '0', day: 'Mon', count: 1},
+      {hour: '1', day: 'Mon', count: 5},
+      {hour: '0', day: 'Tue', count: 3},
+      {hour: '1', day: 'Tue', count: 2},
+    ];
+    const {container, unmount} = renderMarks(
+      [
+        heatmapGL({
+          xKey: 'hour',
+          yKey: 'day',
+          valueKey: 'count',
+          colorRange: ['#000000', '#ffffff'],
+        }),
+      ],
+      heat,
+      'hour',
+    );
+    expect(container.querySelector('canvas')).not.toBeNull();
+    expect(getContextSpy.mock.results.every(r => r.value === null)).toBe(true);
+    unmount();
+  });
+
+  it('streamGL exposes an imperative push/clear handle even without WebGL', () => {
+    const handleRef: {current: StreamGLHandle | null} = {current: null};
+    const {container, unmount} = renderMarks(
+      [streamGL({color: '#10b981', handleRef})],
+      [],
+      'x',
+      {xDomain: [0, 10]},
+    );
+    expect(container.querySelector('canvas')).not.toBeNull();
+    expect(handleRef.current).not.toBeNull();
+    // Pushing and clearing must not crash when the GL context is unavailable.
+    act(() => {
+      handleRef.current!.push(1, 2);
+      handleRef.current!.push(2, 4);
+      handleRef.current!.clear();
+    });
+    unmount();
+  });
+
+  it('dotGLInteractive renders its two canvases and hover hit area without crashing', () => {
+    const {plot, unmount} = renderMarks([
+      dotGLInteractive('v', {color: '#111111'}),
+    ]);
+    const foreignObjects = plot.querySelectorAll('foreignObject');
+    expect(foreignObjects).toHaveLength(2); // visible + offscreen pick canvas
+    expect(foreignObjects[0].querySelector('canvas')).not.toBeNull();
+    expect(foreignObjects[1].querySelector('canvas')).not.toBeNull();
+    expect(plot.querySelector('rect[fill="transparent"]')).not.toBeNull();
+    unmount();
+  });
+});

package/src/useChartColors.test.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useChartColors.test.ts
+ * @input Uses vitest, @testing-library/react renderHook, useChartColors
+ * @output Functional tests for the theme-aware chart color palette hook
+ * @position Colocated test for useChartColors.ts (issue #4295 viz coverage)
+ */
+
+import {describe, it, expect} from 'vitest';
+import {renderHook} from '@testing-library/react';
+import {useChartColors} from './useChartColors';
+
+describe('useChartColors', () => {
+  it('returns the requested number of categorical colors', () => {
+    const {result} = renderHook(() => useChartColors());
+    const colors = result.current.categorical(4);
+    expect(colors).toHaveLength(4);
+    for (const c of colors) {
+      expect(typeof c).toBe('string');
+      expect(c.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('assigns distinct colors within the first palette cycle', () => {
+    const {result} = renderHook(() => useChartColors());
+    const colors = result.current.categorical(4);
+    expect(new Set(colors).size).toBe(4);
+  });
+
+  it('wraps around the palette when more series than slots are requested', () => {
+    const {result} = renderHook(() => useChartColors());
+    const colors = result.current.categorical(12);
+    expect(colors).toHaveLength(12);
+    // 10 categorical tokens — slot 10 and 11 reuse slot 0 and 1.
+    expect(colors[10]).toBe(colors[0]);
+    expect(colors[11]).toBe(colors[1]);
+  });
+
+  it('returns an empty palette for a non-positive count', () => {
+    const {result} = renderHook(() => useChartColors());
+    expect(result.current.categorical(0)).toEqual([]);
+  });
+
+  it('returns a referentially stable API across rerenders', () => {
+    const {result, rerender} = renderHook(() => useChartColors());
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});