@astryxdesign/charts 0.6.2-canary.2b2113d → 0.6.2-canary.2fedb82

package/dist/ChartGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartGrid.d.ts","sourceRoot":"","sources":["../src/ChartGrid.tsx"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAiB,EACjB,QAAgB,EAChB,SAAa,GACd,EAAE,cAAc,+BAmEhB"}
+{"version":3,"file":"ChartGrid.d.ts","sourceRoot":"","sources":["../src/ChartGrid.tsx"],"names":[],"mappings":"AAgBA,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAiB,EACjB,QAAgB,EAChB,SAAa,GACd,EAAE,cAAc,+BAmEhB"}

package/dist/ChartGrid.js

@@ -2,6 +2,7 @@
 
 /**
  * @file ChartGrid.tsx (v2)
+ * @input Chart context scales and dimensions, guide visibility, and tick density
  * @output Grid lines behind chart marks
  * @position Child of Chart v2; reads scales from chart context
  */

package/dist/ChartSwatch.js

@@ -2,10 +2,10 @@
 
 /**
  * @file ChartSwatch.tsx
+ * @input Caller-owned CSS color and optional square or line shape
  * @output Color swatch primitive for legends, tooltips, and standalone use
- * @position Composable primitive — used by ChartLegend (and future
- *           ChartTooltip), or independently anywhere a series indicator
- *           is needed.
+ * @position Composable primitive — used by ChartLegend and ChartTooltip, or
+ *           independently anywhere a series indicator is needed.
  *
  * @example
  * ```

package/dist/ChartTooltip.d.ts

@@ -39,8 +39,8 @@ export interface ChartTooltipProps {
  * Composable grouped tooltip for Chart.
  *
  * Subscribes to the chart's pointer event stream and only re-renders when the
- * hovered data index changes (not on every pointer move). Card position is
- * updated imperatively via a ref to keep pointer-move cost ~free.
+ * hovered data index changes (not on every pointer move). Card coordinates retain
+ * their previous state when the resolved point and browser geometry are unchanged.
  */
 export declare function ChartTooltip({ series, render, hoverIndicator, showHoverDots, placement, }: ChartTooltipProps): import("react").JSX.Element;
 //# sourceMappingURL=ChartTooltip.d.ts.map

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":"AA8BA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf,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;AAwDD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAW,EACX,MAAM,EACN,cAAqB,EACrB,aAAoB,EACpB,SAAkB,GACnB,EAAE,iBAAiB,+BAqUnB"}

package/dist/ChartTooltip.js

@@ -17,7 +17,11 @@
  *
  * // Composable — drop into the chart's children for full control
  * <Chart>
- *   <ChartTooltip hoverIndicator={false} placement="top" />
+ *   <ChartTooltip
+ *     series={series}
+ *     hoverIndicator={false}
+ *     placement="top"
+ *   />
  * </Chart>
  * ```
  */
@@ -29,13 +33,25 @@ 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 { Text } from '@astryxdesign/core';
-import { VStack, HStack } from '@astryxdesign/core';
+import { HStack, Text, useLayer, VStack } from '@astryxdesign/core';
 import { useChart } from "./ChartContext.js";
 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";
+const styles = {
+  card: {
+    kWkggS: "x1prclbq",
+    kaIpWk: "x1hviunn",
+    k8WAf4: "xce4md1",
+    kg3NbH: "xrrkdod",
+    kGVxlE: "x14hfi27",
+    kfzvcC: "x47corl",
+    khDVqt: "xuxw1ft",
+    $$css: true
+  }
+};
+
 /** Default tooltip body — used when `render` is not provided. */
 const DefaultTooltipContent = /*#__PURE__*/memo(function DefaultTooltipContent({
   xValue,
@@ -75,8 +91,8 @@ const DefaultTooltipContent = /*#__PURE__*/memo(function DefaultTooltipContent({
  * Composable grouped tooltip for Chart.
  *
  * Subscribes to the chart's pointer event stream and only re-renders when the
- * hovered data index changes (not on every pointer move). Card position is
- * updated imperatively via a ref to keep pointer-move cost ~free.
+ * hovered data index changes (not on every pointer move). Card coordinates retain
+ * their previous state when the resolved point and browser geometry are unchanged.
  */
 export function ChartTooltip({
   series = [],
@@ -97,20 +113,44 @@ export function ChartTooltip({
     height
   } = useChart();
   const [hoveredIndex, setHoveredIndex] = useState(null);
+  const [cardPosition, setCardPosition] = useState({
+    x: 0,
+    y: 0
+  });
+  const [portalTarget, setPortalTarget] = useState(null);
   const cardRef = useRef(null);
+  const lastPointerEventRef = useRef(null);
+  const {
+    hide: hideLayer,
+    isOpen: isLayerOpen,
+    render: renderLayer,
+    show: showLayer
+  } = useLayer({
+    mode: 'fixed'
+  });
   // Whether the card is currently suppressed (no content, or a custom `render`
-  // opted out by returning null). positionCard reads this so a same-index
-  // pointer move — which repositions the card without a React commit — can't
-  // re-reveal a card the visibility effect below has hidden.
-  const cardHiddenRef = useRef(false);
+  // opted out by returning null). Start closed; once present content opens the
+  // Layer, a content-bearing index change keeps it open while React swaps the
+  // content. positionCard also reads this so a same-index pointer move cannot
+  // re-reveal a suppressed card before the visibility effect confirms content.
+  const cardHiddenRef = useRef(true);
+
+  // The Layer host must remain in the chart's nearest HTML subtree so nested
+  // Theme and MediaTheme scopes keep applying. The portal crosses only the SVG
+  // boundary; browser top-layer promotion remains Layer's responsibility.
+  useEffect(() => {
+    const nextTarget = svgRef.current?.parentElement ?? null;
+    setPortalTarget(current => current === nextTarget ? current : nextTarget);
+  }, [svgRef, width]);
 
   // Stable Set of resolved series keys — used by deriveTooltipSeriesValues.
   // Recomputed only when the resolved map identity changes (per layout pass).
   const resolvedKeys = useMemo(() => new Set(resolved.keys()), [resolved]);
 
   // ─── Card positioning ──────────────────────────────────────────────────
-  // Imperative — the card is portaled, and we don't want pointer-move to
-  // trigger React renders.
+  // Layer owns top-layer promotion. Pointer moves update coordinates only when
+  // the hovered point or browser geometry changes, so moves within one point do
+  // not force a React commit.
   const positionCard = useCallback(e => {
     const card = cardRef.current;
     const svg = svgRef.current;
@@ -118,14 +158,19 @@ export function ChartTooltip({
       return;
     }
     if (!svg || !e.nearest || cardHiddenRef.current) {
-      card.style.display = 'none';
+      hideLayer();
+      return;
+    }
+    showLayer();
+    const layerHost = card.parentElement;
+    if (!layerHost) {
       return;
     }
     const svgRect = svg.getBoundingClientRect();
     const screenX = svgRect.left + margin.left + e.nearest.px;
     const screenY = svgRect.top + margin.top;
-    const cardWidth = card.offsetWidth;
-    const cardHeight = card.offsetHeight;
+    const cardWidth = layerHost.offsetWidth;
+    const cardHeight = layerHost.offsetHeight;
     const viewportWidth = window.innerWidth;
     const viewportHeight = window.innerHeight;
     const gap = 8;
@@ -150,27 +195,31 @@ export function ChartTooltip({
         }
     }
 
-    // Clamp to the viewport so the card never clips off-screen — it's
-    // portaled and position:fixed, so this keeps it fully visible for every
-    // placement (pinned placements and the near-edge `auto` flip alike).
+    // Clamp the card coordinates to the viewport. Oversized custom content
+    // keeps its caller-owned dimensions and may extend past the far edge.
     x = Math.max(gap, Math.min(x, viewportWidth - cardWidth - gap));
     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]);
+    setCardPosition(current => current.x === x && current.y === y ? current : {
+      x,
+      y
+    });
+  }, [svgRef, margin, placement, hideLayer, showLayer]);
 
   // ─── Subscribe to pointer events ───────────────────────────────────────
   useEffect(() => {
     let currentIndex = null;
     const unsub = onPointer(e => {
+      lastPointerEventRef.current = e;
       const newIndex = e.nearest?.dataIndex ?? null;
       if (newIndex !== currentIndex) {
         currentIndex = newIndex;
-        // Optimistically treat the new index as showable; the visibility effect
-        // re-hides it after commit if there's no content (e.g. custom `render`
-        // returned null). This keeps the card appearing on the first move.
-        cardHiddenRef.current = false;
+        // Keep a closed/suppressed card closed until React resolves content.
+        // Do not preemptively close an already-visible card for another index:
+        // the visibility effect closes absent content after commit, while
+        // content-bearing transitions keep the same Layer continuously open.
+        if (newIndex == null) {
+          cardHiddenRef.current = true;
+        }
         setHoveredIndex(newIndex);
       }
       positionCard(e);
@@ -269,24 +318,31 @@ export function ChartTooltip({
     });
   }, [hoverIndicator, hoveredIndex, series, xScale, data, xKey, width, height, margin.top]);
 
-  // Single source of truth for whether the card has anything to show. It's
-  // hidden when there's no hover, when the hovered index is stale/out-of-range
-  // (e.g. `data` shrank while hovering, so `datum` is undefined), or when a
-  // custom `render` opts out by returning null — the documented contract, which
-  // still shows the band highlight + dots. The decision is stored in a ref so
-  // the imperative positionCard honors it on subsequent same-index moves
-  // (otherwise it would re-reveal an empty bordered box). Runs after commit, so
-  // `render` (which may return null, or throw) never executes on the SSR path.
+  // Render props are ordinary React content. Resolve them once per commit so a
+  // custom renderer is not invoked separately by the visibility synchronizer.
+  // Keep it browser-only: the layer has no portal target during SSR.
+  const cardContent = typeof document === 'undefined' || hoveredIndex == null || datum == null ? null : render ? render(xValue, seriesValues) : /*#__PURE__*/_jsx(DefaultTooltipContent, {
+    xValue: xValue,
+    rows: seriesValues
+  });
+  const isCardHidden = hoveredIndex == null || datum == null || render != null && cardContent == null;
+  const hasNativePopover = typeof HTMLElement !== 'undefined' && typeof HTMLElement.prototype.showPopover === 'function';
+  const shouldHideLayerHost = isCardHidden || !hasNativePopover && !isLayerOpen;
+
+  // Synchronize the shared Layer's native Popover state after React commits the
+  // new card body. The second positioning pass measures that final body; later
+  // moves within the same data point usually resolve to the existing state.
   useEffect(() => {
-    const hidden = hoveredIndex == null || datum == null || render != null && render(xValue, seriesValues) == null;
-    cardHiddenRef.current = hidden;
-    if (hidden) {
-      const card = cardRef.current;
-      if (card) {
-        card.style.display = 'none';
-      }
+    cardHiddenRef.current = isCardHidden;
+    if (isCardHidden) {
+      hideLayer();
+      return;
+    }
+    const pointerEvent = lastPointerEventRef.current;
+    if (pointerEvent) {
+      positionCard(pointerEvent);
     }
-  }, [render, hoveredIndex, datum, xValue, seriesValues]);
+  }, [isCardHidden, hoveredIndex, xValue, seriesValues, render, hideLayer, positionCard]);
 
   // ─── Render ────────────────────────────────────────────────────────────
   if (typeof document === 'undefined') {
@@ -295,22 +351,21 @@ export function ChartTooltip({
       children: [hoverIndicatorElement, dots]
     });
   }
-
-  // Mirrors the visibility effect's first two conditions: no card when there's
-  // no hover or the hovered datum is stale/out-of-range (so `render` and the
-  // default body are never called with an undefined x-value + empty rows).
-  const cardContent = hoveredIndex == null || datum == null ? null : render ? render(xValue, seriesValues) : /*#__PURE__*/_jsx(DefaultTooltipContent, {
-    xValue: xValue,
-    rows: seriesValues
-  });
   return /*#__PURE__*/_jsxs(_Fragment, {
-    children: [hoverIndicatorElement, dots, /*#__PURE__*/createPortal(/*#__PURE__*/_jsx("div", {
+    children: [hoverIndicatorElement, dots, portalTarget ? /*#__PURE__*/createPortal(renderLayer(/*#__PURE__*/_jsx("div", {
       ref: cardRef,
       role: "tooltip",
-      ...{
-        className: "xixxii4 x1prclbq x1hviunn xce4md1 xrrkdod x14hfi27 x47corl xuxw1ft x1q2oy4v x1s85apg"
-      },
       children: cardContent
-    }), document.body)]
+    }), {
+      x: cardPosition.x,
+      y: cardPosition.y,
+      // Native Popover keeps a closed host out of layout itself, so
+      // remove our guard before showPopover() measures it. Layer's
+      // reduced fallback needs the explicit closed display state.
+      style: shouldHideLayerHost ? {
+        display: 'none'
+      } : undefined,
+      xstyle: styles.card
+    }), portalTarget) : null]
   });
 }

package/dist/charts.css

@@ -14,15 +14,12 @@
   .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}
   .xwh1t77:not(#\#):not(#\#):not(#\#){margin-bottom:var(--spacing-4)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/charts",
-  "version": "0.6.2-canary.2b2113d",
+  "version": "0.6.2-canary.2fedb82",
   "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",
@@ -47,7 +47,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.6.2-canary.2b2113d",
+    "@astryxdesign/core": "0.6.2-canary.2fedb82",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0"
   },
@@ -57,7 +57,7 @@
     "d3-shape": "^3.2.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.6.2-canary.2b2113d",
+    "@astryxdesign/cli": "0.6.2-canary.2fedb82",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/ChartGrid.doc.mjs

@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'ChartGrid',
+  displayName: 'Chart Grid',
+  group: 'Charts',
+  category: 'Data Visualization',
+  isHiddenFromOverview: true,
+  keywords: ['chart', 'grid', 'guides', 'axis', 'ticks', 'data visualization'],
+
+  usage: {
+    description:
+      'ChartGrid draws horizontal and vertical guide lines from the scales owned by a parent Chart. Use it in the Chart grid slot so guides share the plot dimensions and tick values used by the chart.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Pair ChartGrid with ChartAxis when readers need labelled values beside the guide lines.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal guides for value comparison and add vertical guides only when they help readers align categories or continuous x values.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use grid lines as the only way to communicate a value or distinction. Keep meaningful chart information in labels, marks, and the parent Chart alternative.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect tickCount to thin categorical band centers. It requests density only for continuous scales; categorical vertical guides render once per band.',
+      },
+    ],
+    accessibility: [
+      {
+        name: 'Chart alternative',
+        category: 'Content',
+        criterion: '1.1.1 Non-text Content',
+        requirement: 'Required on the parent Chart',
+        states: ['All'],
+        description:
+          'Chart owns the accessible image name and supported small-data table. Grid lines supplement that chart-level alternative rather than replacing it.',
+      },
+      {
+        name: 'Visual-only guides',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: 'Do not carry information alone',
+        states: ['Horizontal', 'Vertical', 'Combined'],
+        description:
+          'Grid lines are supporting guides. Preserve visible labels, marks, or another qualifying cue so understanding does not depend on the grid alone.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Grid lines',
+        required: false,
+        description:
+          'Horizontal lines at continuous y ticks and vertical lines at x ticks or categorical band centers.',
+      },
+    ],
+  },
+
+  props: [
+    {
+      name: 'horizontal',
+      type: 'boolean',
+      description:
+        'Whether to draw horizontal guides at continuous y ticks other than zero.',
+      default: 'true',
+    },
+    {
+      name: 'vertical',
+      type: 'boolean',
+      description:
+        'Whether to draw vertical guides at continuous x ticks or categorical band centers.',
+      default: 'false',
+    },
+    {
+      name: 'tickCount',
+      type: 'number',
+      description:
+        'Approximate guide count requested from continuous scales. It does not thin categorical band centers.',
+      default: '5',
+    },
+  ],
+
+  examples: [
+    {
+      label: 'Horizontal guides',
+      code: `import {Chart, ChartGrid, bar} from '@astryxdesign/charts';
+
+<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[bar('revenue')]}
+  grid={<ChartGrid />}
+/>;`,
+    },
+    {
+      label: 'Horizontal and vertical guides',
+      code: `<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[bar('revenue')]}
+  grid={<ChartGrid horizontal vertical tickCount={6} />}
+/>;`,
+    },
+  ],
+};

package/src/ChartGrid.spec.md

@@ -0,0 +1,184 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChartGrid
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/charts/src/ChartGrid.test.tsx,
+    apps/storybook/stories/charts/ChartGrid.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-test-sufficiency,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: [spec:AST-002, spec:AST-029]
+---
+
+# ChartGrid component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                         |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | No API shape or default changes. This draft records the current horizontal, vertical, and continuous-scale tick-density surface.                                                 |
+| Behavior                | Horizontal guides follow continuous y ticks except zero; vertical guides follow categorical x-band centers or continuous x ticks; both directions remain independently optional. |
+| End-user impact         | Chart readers receive guide lines aligned with the parent Chart's plot scales; this audit changes no rendered behavior.                                                          |
+| Builder impact          | Existing callsites remain valid and gain direct CLI documentation and focused evidence for current density fallbacks.                                                            |
+| Compatibility/readiness | The package remains canary-only. This observational draft is non-authoritative, and exact rendered/accessibility evidence remains pending.                                       |
+| Review checks           | Reject a changed public shape/default, a guide using a scale outside Chart context, a zero baseline drawn twice, or categorical guides no longer centered on their bands.        |
+| Governing rules         | `spec:AST-029/FR3–FR7`, `architecture:component-test-sufficiency/INV1–INV11`, `architecture:component-theming-surface/INV1–INV6`, and `spec:AST-002`.                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChartGrid renders passive Cartesian guide lines inside a Chart. It owns line
+selection and placement from Chart-provided scales and plot dimensions while Chart
+owns the coordinate system, rendering order, and chart-level alternative.
+
+## Compatibility and migration
+
+- Released default preserved: yes at the canary surface; the package has no stable release.
+- Compatibility class: no public API, default, or rendered-behavior change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none; this draft does not authorize a public API change.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Selecting horizontal and vertical guide values from Chart-provided scales.
+- Positioning each guide across the current plot width or height.
+- Omitting the horizontal zero guide that the paired axis may emphasize.
+- Sanitizing continuous-scale tick requests before passing them to d3.
+
+**Does not own / non-goals**
+
+- Data, domains, scale construction, plot dimensions, or paint order — owned by `component:Chart`.
+- Axis labels, tick marks, or plot-edge lines — owned by `component:ChartAxis`.
+- The chart's accessible name, description, or data alternative — owned by `component:Chart` and the product callsite.
+- Product-specific decisions about whether guides are needed.
+
+## Public concepts
+
+| Concept             | Closed values or states                 | Meaning                                                       | Availability by variant/orientation/state | Default   | Owner                 | Stability    | Invalid-value behavior                                                             |
+| ------------------- | --------------------------------------- | ------------------------------------------------------------- | ----------------------------------------- | --------- | --------------------- | ------------ | ---------------------------------------------------------------------------------- |
+| Horizontal guides   | shown or hidden                         | Draws lines at continuous y ticks, excluding zero.            | Every ChartGrid                           | shown     | `component:ChartGrid` | experimental | Not applicable.                                                                    |
+| Vertical guides     | shown or hidden                         | Draws lines at x ticks or categorical x-band centers.         | Every ChartGrid                           | hidden    | `component:ChartGrid` | experimental | Not applicable.                                                                    |
+| Continuous density  | finite non-negative number              | Requests an approximate line count from d3 continuous scales. | Horizontal guides and continuous x guides | `5`       | `component:ChartGrid` | experimental | Fractions floor; values above 1000 cap; negative/non-finite values fall back to 5. |
+| Categorical density | one guide per categorical x-band center | Keeps vertical guides aligned to every band.                  | Categorical x with vertical guides        | all bands | `component:ChartGrid` | experimental | `tickCount` currently has no effect.                                               |
+| Chart context       | inside a parent `Chart`                 | Supplies scales and current plot dimensions.                  | Always                                    | none      | `component:Chart`     | experimental | Rendering outside Chart throws the shared context error.                           |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                | Basis                                                  | Draft review state |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------ |
+| FR1 | ChartGrid MUST consume the current width, height, x scale, and y scale from its parent Chart context.                                              | implementation, package composition, and focused tests | verify             |
+| FR2 | `horizontal` and `vertical` MUST independently enable their guide sets; enabling both MUST render both sets.                                       | implementation, JSDoc, tests, and Storybook            | verify             |
+| FR3 | Horizontal guides MUST use continuous y ticks, span the plot width, and omit y=0 so a paired axis does not receive a duplicate line.               | implementation, JSDoc, and focused tests               | verify             |
+| FR4 | Vertical guides MUST use categorical band centers for band x scales and d3 tick positions for continuous x scales, spanning the plot height.       | implementation and focused tests                       | verify             |
+| FR5 | Continuous tick requests MUST be finite, non-negative integers no greater than 1000; zero yields no continuous guides and invalid values use five. | implementation, crash-prevention rationale, and tests  | verify             |
+| FR6 | Guide paint MUST consume a semantic theme token. Whether grid lines become a public theme target remains unsettled.                                | implementation and current theming architecture        | verify             |
+
+### Allowed variation
+
+- **AV1 — Continuous tick count.** d3 may choose a nearby set of values rather than exactly the requested number.
+- **AV2 — Categorical values.** Each current x-band domain value contributes one centered vertical guide.
+
+### Representative states
+
+| State                      | Required invariant                                               | Allowed variation                              |
+| -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| Default                    | Horizontal guides only; continuous density defaults to five.     | d3 chooses the exact y tick set.               |
+| Horizontal disabled        | No horizontal guides.                                            | Vertical guides may remain enabled.            |
+| Vertical categorical       | One vertical guide at each x-band center.                        | Band width and center follow Chart's x scale.  |
+| Vertical continuous        | One guide at each generated continuous x tick.                   | d3 chooses the exact x tick set.               |
+| Both directions            | Horizontal and vertical sets render together.                    | Their exact counts may differ.                 |
+| Zero continuous tick count | Continuous guide sets are empty.                                 | Categorical vertical guides remain unaffected. |
+| Invalid tick count         | Continuous guide generation falls back to the default request.   | d3 chooses the resulting exact ticks.          |
+| Narrow / RTL               | Guides remain tied to physical data coordinates and plot bounds. | Plot width and data-domain order vary.         |
+
+### Transformation and precedence order
+
+- **ORD1 — Continuous density.** Validate finiteness and non-negativity → floor fractions → cap at 1000 → request d3 ticks.
+- **ORD2 — Placement.** Select enabled directions → choose the scale path → derive tick or band-center positions → span the current opposite plot dimension.
+
+### Performance and resources
+
+- **PR1 — Derived output.** Guide arrays remain render-derived and memoized from enabled directions, scales, dimensions, and sanitized density. ChartGrid owns no listener, observer, timer, or persistent resource.
+- **PR2 — Bounded tick allocation.** A public density value cannot request more than 1000 continuous ticks from d3.
+
+## Accessibility contract
+
+- **AR1 — Chart-level alternative.** ChartGrid renders passive supporting guides inside Chart's named image. Chart owns the accessible chart name and supported data-table alternative.
+- **AR2 — No grid-only information.** Grid lines do not replace visible labels, meaningful marks, or the parent Chart alternative.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                | Representation authority                      | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------- | --------------------------------------------- | -------------- | ------------------ |
+| Grid lines       | Support position comparison without carrying chart meaning alone. | unsettled; no current design record is linked | supporting     | FR2–FR6, AR1–AR2   |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Grid lines": {
+    "none": {
+      "reason": "unsettled: ChartGrid consumes a semantic color token, but no current component or family contract decides whether grid lines are a public theme target."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- No current family or design record governs ChartGrid.
+- `architecture:component-test-sufficiency` owns rational public-state partitions, observable assertions, and audit evidence quality.
+- `architecture:component-theming-surface` owns anatomy-to-target disposition; token consumption alone does not enroll ChartGrid in public component theming.
+- `spec:AST-002` owns public API admission and prevents this audit from adding or reinterpreting a public choice.
+- `spec:AST-029` owns this observational backfill, closed evidence receipt, safe remediation, and fail-closed eligibility report.
+
+## Verification map
+
+| Contract | Verification                                           | Representative states                                       | Mutation or failure expectation                                                    | Audit section                      |
+| -------- | ------------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1–FR2  | `ChartGrid.test.tsx`; `ChartGrid.stories.tsx`          | default, horizontal off, vertical on, both, neither         | A direction stops respecting its input or output escapes the parent Chart context. | `audit:ChartGrid/behavior`         |
+| FR3      | `ChartGrid.test.tsx`                                   | positive and mixed-sign y domains                           | Guides stop spanning the plot or y=0 is drawn twice.                               | `audit:ChartGrid/behavior-layout`  |
+| FR4      | `ChartGrid.test.tsx`; `ChartGrid.stories.tsx`          | categorical and continuous x                                | A band guide leaves its center or a continuous tick lands at the wrong coordinate. | `audit:ChartGrid/behavior-layout`  |
+| FR5, PR2 | focused zero/invalid-density tests and source review   | zero and invalid requests; fractional and capped partitions | Invalid input crashes render or bypasses the bounded fallback.                     | `audit:ChartGrid/behavior-testing` |
+| FR6      | strict lint; Storybook theme matrix remains pending    | light, dark, and supported non-default themes               | A raw color or component-side mode choice replaces semantic token paint.           | `audit:ChartGrid/theming-design`   |
+| AR1–AR2  | Chart accessibility tests; package axe remains pending | named Chart, small-data table, grid enabled                 | Grid content replaces or becomes the only source of required chart information.    | `audit:ChartGrid/accessibility`    |
+
+## Decision log
+
+None. This draft records observed behavior and evidence gaps only.
+
+## Open questions
+
+- **OQ1 — Categorical density.** Should `tickCount` remain continuous-scale-only, or should vertical categorical guides gain a documented thinning contract aligned with ChartAxis? (`human-api`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit results,
+implementation steps, or shared system rules. It links to their owners.