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

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/dist/ChartTooltip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartTooltip.d.ts","sourceRoot":"","sources":["../src/ChartTooltip.tsx"],"names":[],"mappings":"AA0BA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAaf,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAC,SAAS,EAAoB,MAAM,SAAS,CAAC;AAG1D,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,KAAK,SAAS,CAAC;IAC5E;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,qBAAqB,CAAC;CACnC;AA2DD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAW,EACX,MAAM,EACN,cAAqB,EACrB,aAAoB,EACpB,SAAkB,GACnB,EAAE,iBAAiB,+BA4QnB"}
+{"version":3,"file":"ChartTooltip.d.ts","sourceRoot":"","sources":["../src/ChartTooltip.tsx"],"names":[],"mappings":"AA2BA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAcf,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAC,SAAS,EAAoB,MAAM,SAAS,CAAC;AAG1D,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,KAAK,SAAS,CAAC;IAC5E;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,qBAAqB,CAAC;CACnC;AA4FD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAW,EACX,MAAM,EACN,cAAqB,EACrB,aAAoB,EACpB,SAAkB,GACnB,EAAE,iBAAiB,+BAyRnB"}

package/dist/ChartTooltip.js

@@ -4,7 +4,8 @@
  * @file ChartTooltip.tsx
  * @output Grouped chart tooltip — shows all series values at the hovered x-position.
  *         Composable: drop into `<Chart tooltip>` or render directly inside a chart
- *         to take full control of props.
+ *         to take full control of props. The card stays beside its owning chart
+ *         and uses a manual popover to escape clipping and nested layer stacks.
  * @position Reads from ChartContext — must render inside an <Chart>.
  *
  * @example
@@ -28,7 +29,7 @@ import { memo, useState, useEffect, useMemo, useRef, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import '@astryxdesign/core/theme/tokens.stylex';
-import { colorVars, radiusVars, shadowVars, spacingVars } from '@astryxdesign/core/theme/tokens.stylex';
+import { appearanceVars, colorVars, radiusVars, shadowVars, spacingVars } from '@astryxdesign/core/theme/tokens.stylex';
 import { Text } from '@astryxdesign/core';
 import { VStack, HStack } from '@astryxdesign/core';
 import { useChart } from "./ChartContext.js";
@@ -36,6 +37,33 @@ import { ChartSwatch, swatchVariantForType } from "./ChartSwatch.js";
 import { deriveTooltipSeriesValues, shouldRenderHoverDot } from "./tooltip.js";
 import { isBandScale, xPixel } from "./utils.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+function showCard(card) {
+  // The fallback display must be applied first: showPopover() rejects elements
+  // that are still display:none.
+  card.style.display = 'block';
+  if (typeof card.showPopover === 'function') {
+    try {
+      if (!card.matches(':popover-open')) {
+        card.showPopover();
+      }
+    } catch {
+      // The reduced browser path below still makes the card visible.
+    }
+  }
+}
+function hideCard(card) {
+  if (typeof card.hidePopover === 'function') {
+    try {
+      if (card.matches(':popover-open')) {
+        card.hidePopover();
+      }
+    } catch {
+      // The reduced browser path below still hides the card.
+    }
+  }
+  card.style.display = 'none';
+}
+
 /** Default tooltip body — used when `render` is not provided. */
 const DefaultTooltipContent = /*#__PURE__*/memo(function DefaultTooltipContent({
   xValue,
@@ -97,6 +125,7 @@ export function ChartTooltip({
     height
   } = useChart();
   const [hoveredIndex, setHoveredIndex] = useState(null);
+  const [portalTarget, setPortalTarget] = useState(null);
   const cardRef = useRef(null);
   // Whether the card is currently suppressed (no content, or a custom `render`
   // opted out by returning null). positionCard reads this so a same-index
@@ -108,6 +137,13 @@ export function ChartTooltip({
   // Recomputed only when the resolved map identity changes (per layout pass).
   const resolvedKeys = useMemo(() => new Set(resolved.keys()), [resolved]);
 
+  // Host the manual popover beside the chart rather than at document.body.
+  // Native top-layer promotion still escapes chart clipping, while the DOM
+  // position keeps nested theme variables and the owning Drawer relationship.
+  useEffect(() => {
+    setPortalTarget(svgRef.current?.parentElement ?? null);
+  }, [svgRef]);
+
   // ─── Card positioning ──────────────────────────────────────────────────
   // Imperative — the card is portaled, and we don't want pointer-move to
   // trigger React renders.
@@ -118,9 +154,10 @@ export function ChartTooltip({
       return;
     }
     if (!svg || !e.nearest || cardHiddenRef.current) {
-      card.style.display = 'none';
+      hideCard(card);
       return;
     }
+    showCard(card);
     const svgRect = svg.getBoundingClientRect();
     const screenX = svgRect.left + margin.left + e.nearest.px;
     const screenY = svgRect.top + margin.top;
@@ -157,7 +194,6 @@ export function ChartTooltip({
     y = Math.max(gap, Math.min(y, viewportHeight - cardHeight - gap));
     card.style.left = `${x}px`;
     card.style.top = `${y}px`;
-    card.style.display = 'block';
   }, [svgRef, margin, placement]);
 
   // ─── Subscribe to pointer events ───────────────────────────────────────
@@ -283,7 +319,7 @@ export function ChartTooltip({
     if (hidden) {
       const card = cardRef.current;
       if (card) {
-        card.style.display = 'none';
+        hideCard(card);
       }
     }
   }, [render, hoveredIndex, datum, xValue, seriesValues]);
@@ -304,13 +340,14 @@ export function ChartTooltip({
     rows: seriesValues
   });
   return /*#__PURE__*/_jsxs(_Fragment, {
-    children: [hoverIndicatorElement, dots, /*#__PURE__*/createPortal(/*#__PURE__*/_jsx("div", {
+    children: [hoverIndicatorElement, dots, portalTarget != null && /*#__PURE__*/createPortal(/*#__PURE__*/_jsx("div", {
       ref: cardRef,
       role: "tooltip",
+      popover: "manual",
       ...{
-        className: "xixxii4 x1prclbq x1hviunn xce4md1 xrrkdod x14hfi27 x47corl xuxw1ft x1q2oy4v x1s85apg"
+        className: "xixxii4 x1anvkwx x10im51j xrxpjvj x1prclbq x1hviunn xce4md1 xrrkdod x14hfi27 x47corl xuxw1ft xoqq3by x1s85apg"
       },
       children: cardContent
-    }), document.body)]
+    }), portalTarget)]
   });
 }

package/dist/charts.css

@@ -3,31 +3,34 @@
 
 @layer astryx-base {
   @property --x-backgroundColor { syntax: "*"; inherits: false;}
-  .xbvija:not(#\#){border-radius:1.5px}
-  .x1cum3z5:not(#\#){border-radius:2px}
-  .x1hviunn:not(#\#){border-radius:var(--radius-container)}
-  .x98rzlu:not(#\#){flex:1}
-  .xckhbgb:not(#\#){margin-inline:1px}
-  .xb3r6kr:not(#\#){overflow:hidden}
-  .xce4md1:not(#\#){padding-block:var(--spacing-2)}
-  .xrrkdod:not(#\#){padding-inline:var(--spacing-3)}
-  .x1prclbq:not(#\#):not(#\#){background-color:var(--color-background-popover)}
-  .xl8spv7:not(#\#):not(#\#){background-color:var(--x-backgroundColor)}
-  .x14hfi27:not(#\#):not(#\#){box-shadow:var(--shadow-med)}
-  .x1s85apg:not(#\#):not(#\#){display:none}
-  .x2lah0s:not(#\#):not(#\#){flex-shrink:0}
-  .x47corl:not(#\#):not(#\#){pointer-events:none}
-  .xixxii4:not(#\#):not(#\#){position:fixed}
-  .xnpr05h:not(#\#):not(#\#){stroke-width:1}
-  .x113i6qz:not(#\#):not(#\#){stroke:var(--color-border-emphasized)}
-  .x1lo1t26:not(#\#):not(#\#){stroke:var(--color-text-primary)}
-  .xuxw1ft:not(#\#):not(#\#){white-space:nowrap}
-  .x1q2oy4v:not(#\#):not(#\#){z-index:9999}
-  .xuoj239:not(#\#):not(#\#):not(#\#){height:3px}
-  .xdk7pt:not(#\#):not(#\#):not(#\#){height:8px}
-  .x1yztbdb:not(#\#):not(#\#):not(#\#){margin-bottom:16px}
-  .xeuugli:not(#\#):not(#\#):not(#\#){min-width:0}
-  .xh8yej3:not(#\#):not(#\#):not(#\#){width:100%}
-  .x1fsd2vl:not(#\#):not(#\#):not(#\#){width:10px}
-  .x1xc55vz:not(#\#):not(#\#):not(#\#){width:8px}
+  .x1anvkwx:not(#\#){inset:auto}
+  .xbvija:not(#\#):not(#\#){border-radius:1.5px}
+  .x1cum3z5:not(#\#):not(#\#){border-radius:2px}
+  .x1hviunn:not(#\#):not(#\#){border-radius:var(--radius-container)}
+  .x98rzlu:not(#\#):not(#\#){flex:1}
+  .x10im51j:not(#\#):not(#\#){margin-block:0}
+  .xrxpjvj:not(#\#):not(#\#){margin-inline:0}
+  .xckhbgb:not(#\#):not(#\#){margin-inline:1px}
+  .xb3r6kr:not(#\#):not(#\#){overflow:hidden}
+  .xce4md1:not(#\#):not(#\#){padding-block:var(--spacing-2)}
+  .xrrkdod:not(#\#):not(#\#){padding-inline:var(--spacing-3)}
+  .x1prclbq:not(#\#):not(#\#):not(#\#){background-color:var(--color-background-popover)}
+  .xl8spv7:not(#\#):not(#\#):not(#\#){background-color:var(--x-backgroundColor)}
+  .x14hfi27:not(#\#):not(#\#):not(#\#){box-shadow:var(--shadow-med)}
+  .x1s85apg:not(#\#):not(#\#):not(#\#){display:none}
+  .x2lah0s:not(#\#):not(#\#):not(#\#){flex-shrink:0}
+  .x47corl:not(#\#):not(#\#):not(#\#){pointer-events:none}
+  .xixxii4:not(#\#):not(#\#):not(#\#){position:fixed}
+  .xnpr05h:not(#\#):not(#\#):not(#\#){stroke-width:1}
+  .x113i6qz:not(#\#):not(#\#):not(#\#){stroke:var(--color-border-emphasized)}
+  .x1lo1t26:not(#\#):not(#\#):not(#\#){stroke:var(--color-text-primary)}
+  .xuxw1ft:not(#\#):not(#\#):not(#\#){white-space:nowrap}
+  .xoqq3by:not(#\#):not(#\#):not(#\#){z-index:var(--appearance-layer-nesting)}
+  .xuoj239:not(#\#):not(#\#):not(#\#):not(#\#){height:3px}
+  .xdk7pt:not(#\#):not(#\#):not(#\#):not(#\#){height:8px}
+  .x1yztbdb:not(#\#):not(#\#):not(#\#):not(#\#){margin-bottom:16px}
+  .xeuugli:not(#\#):not(#\#):not(#\#):not(#\#){min-width:0}
+  .xh8yej3:not(#\#):not(#\#):not(#\#):not(#\#){width:100%}
+  .x1fsd2vl:not(#\#):not(#\#):not(#\#):not(#\#){width:10px}
+  .x1xc55vz:not(#\#):not(#\#):not(#\#):not(#\#){width:8px}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/charts",
-  "version": "0.5.2-canary.e4f8e4e",
+  "version": "0.5.2-canary.ea04834",
   "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.ea04834",
     "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.ea04834",
     "@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);
+  });
+});