@astryxdesign/charts 0.6.2-canary.bfee8a4 → 0.6.2-canary.cb7a565

package/dist/ChartAxis.d.ts

@@ -7,7 +7,7 @@ export interface ChartAxisProps {
     maxTicks?: number;
     /** Custom tick formatter */
     tickFormat?: (value: unknown) => string;
-    /** Truncate labels to this many characters (appends "\u2026"). */
+    /** Truncate labels to this many user-perceived characters (appends "\u2026"). */
     truncate?: number;
     /** Enable smooth transitions for streaming (default: true) */
     animated?: boolean;

package/dist/ChartAxis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartAxis.d.ts","sourceRoot":"","sources":["../src/ChartAxis.tsx"],"names":[],"mappings":"AA0BA,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,SAAa,EACb,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,QAAe,EACf,YAAoC,EACpC,SAAiB,GAClB,EAAE,cAAc,+BAuLhB"}
+{"version":3,"file":"ChartAxis.d.ts","sourceRoot":"","sources":["../src/ChartAxis.tsx"],"names":[],"mappings":"AA4BA,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,QAAQ,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,SAAa,EACb,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,QAAe,EACf,YAAoC,EACpC,SAAiB,GAClB,EAAE,cAAc,+BA4LhB"}

package/dist/ChartAxis.js

@@ -2,6 +2,7 @@
 
 /**
  * @file ChartAxis.tsx (v2)
+ * @input Chart context scales, axis presentation props, and grapheme-safe text utilities
  * @output Renders an axis (top, right, bottom, left) using the chart's scales
  * @position Child of Chart v2; reads scales from chart context
  *
@@ -19,6 +20,7 @@
 
 import { useCallback, useMemo } from 'react';
 import * as stylex from '@stylexjs/stylex';
+import { characterCount, truncateCharacters } from '@astryxdesign/core/utils';
 import '@astryxdesign/core/theme/tokens.stylex';
 import { colorVars } from '@astryxdesign/core/theme/tokens.stylex';
 import { useChart } from "./ChartContext.js";
@@ -85,20 +87,28 @@ export function ChartAxis({
   }, [tickFormat, scale, safeTickCount]);
   const format = useCallback(value => {
     const str = (tickFormat ?? autoFormat ?? String)(value);
-    return truncate && str.length > truncate ? str.slice(0, truncate) + '\u2026' : str;
+    if (!truncate) {
+      return str;
+    }
+    const shortened = truncateCharacters(str, truncate, '');
+    return shortened === str ? str : shortened + '\u2026';
   }, [tickFormat, autoFormat, truncate]);
   const ticks = useMemo(() => {
+    // Format each generated tick once so density and rendering share the same
+    // grapheme-safe label instead of repeating consumer formatting/segmentation.
     let allTicks;
     if (isBandScale(scale)) {
       allTicks = scale.domain().map(d => ({
         value: d,
-        offset: (scale(d) ?? 0) + scale.bandwidth() / 2
+        offset: (scale(d) ?? 0) + scale.bandwidth() / 2,
+        label: format(d)
       }));
     } else {
       const linearScale = scale;
       allTicks = linearScale.ticks(safeTickCount).map(d => ({
         value: d,
-        offset: linearScale(d)
+        offset: linearScale(d),
+        label: format(d)
       }));
     }
 
@@ -111,7 +121,7 @@ export function ChartAxis({
     let cap = maxTicks;
     if (cap == null && allTicks.length > 1) {
       if (isHorizontal && width > 0) {
-        const widestChars = allTicks.reduce((m, t) => Math.max(m, format(t.value).length), 1);
+        const widestChars = allTicks.reduce((m, tick) => Math.max(m, characterCount(tick.label)), 1);
         const approxLabelPx = widestChars * 7 + 16;
         cap = Math.max(1, Math.floor(width / approxLabelPx));
       } else if (!isHorizontal && height > 0) {
@@ -157,9 +167,9 @@ export function ChartAxis({
       }
     }), ticks.map(({
       value,
-      offset
+      offset,
+      label
     }) => {
-      const label = format(value);
       // Key off the raw tick value, not the formatted label: distinct ticks
       // can format (or truncate) to the same string and would collide as keys.
       const key = String(value);

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.bfee8a4",
+  "version": "0.6.2-canary.cb7a565",
   "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.bfee8a4",
+    "@astryxdesign/core": "0.6.2-canary.cb7a565",
     "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.bfee8a4",
+    "@astryxdesign/cli": "0.6.2-canary.cb7a565",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/ChartAxis.doc.mjs

@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'ChartAxis',
+  displayName: 'Chart Axis',
+  group: 'Charts',
+  category: 'Data Visualization',
+  isHiddenFromOverview: true,
+  keywords: ['chart', 'axis', 'ticks', 'labels', 'scale', 'data visualization'],
+
+  usage: {
+    description:
+      'ChartAxis renders tick labels and optional edge and tick lines from the scales owned by a parent Chart. Use it in the Chart axes slot for physical top, right, bottom, or left plot edges.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use ChartAxis inside Chart so its labels, ticks, and edge line share the same scales and plot dimensions as the marks.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use tickFormat for product-specific units or locale formatting, and maxTicks or truncate when dense category labels need a bounded presentation.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use axis labels or a pointer tooltip as the only way to obtain important values. Give Chart an accessible name and preserve an equivalent data view or summary.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hide the edge line while showing tick marks. showTicks intentionally keeps the line visible so each mark has a grounded edge.',
+      },
+    ],
+    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. Tick labels supplement that chart-level alternative rather than replacing it.',
+      },
+      {
+        name: 'Label text integrity',
+        category: 'Content',
+        criterion: 'Unicode grapheme clusters',
+        requirement: 'Required when truncate is set',
+        states: ['Truncated labels'],
+        description:
+          'Truncation keeps emoji, joined emoji sequences, flags, and combining marks intact before appending the ellipsis.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Axis edge line',
+        required: false,
+        description:
+          'Line along the selected plot edge. It is shown by default only on the bottom edge and whenever tick marks are shown.',
+      },
+      {
+        name: 'Tick marks',
+        required: false,
+        description:
+          'Short lines extending outward from each retained tick position.',
+      },
+      {
+        name: 'Tick labels',
+        required: true,
+        description:
+          'Formatted scale values or categories positioned outside the selected plot edge.',
+      },
+    ],
+  },
+
+  props: [
+    {
+      name: 'position',
+      type: "'top' | 'right' | 'bottom' | 'left'",
+      description: 'Physical plot edge on which to render the axis.',
+      required: true,
+    },
+    {
+      name: 'tickCount',
+      type: 'number',
+      description:
+        'Approximate continuous-scale tick count. d3 chooses the final values.',
+      default: '5',
+    },
+    {
+      name: 'maxTicks',
+      type: 'number',
+      description:
+        'Maximum displayed label count. Labels are evenly skipped when the generated set is larger.',
+    },
+    {
+      name: 'tickFormat',
+      type: '(value: unknown) => string',
+      description:
+        'Formats each retained tick. When omitted, continuous scales use d3 formatting and band scales use their category strings.',
+    },
+    {
+      name: 'truncate',
+      type: 'number',
+      description:
+        'Maximum content characters retained before an ellipsis is appended. User-perceived characters remain intact.',
+    },
+    {
+      name: 'animated',
+      type: 'boolean',
+      description:
+        'Whether tick position and visibility changes use the built-in transition.',
+      default: 'true',
+    },
+    {
+      name: 'showAxisLine',
+      type: 'boolean',
+      description:
+        'Whether to draw the edge line. Tick marks force the line on so they remain grounded.',
+      default: 'true for bottom; false for top, right, and left',
+    },
+    {
+      name: 'showTicks',
+      type: 'boolean',
+      description: 'Whether to draw an outward mark at each retained tick.',
+      default: 'false',
+    },
+  ],
+
+  examples: [
+    {
+      label: 'Bottom and left axes',
+      code: `import {Chart, ChartAxis, ChartGrid, bar} from '@astryxdesign/charts';
+
+<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[bar('revenue')]}
+  grid={<ChartGrid horizontal />}
+  axes={
+    <>
+      <ChartAxis position="bottom" />
+      <ChartAxis position="left" tickFormat={value => String(value)} />
+    </>
+  }
+/>;`,
+    },
+    {
+      label: 'Dense category labels',
+      code: `<ChartAxis
+  position="bottom"
+  maxTicks={8}
+  truncate={12}
+  showTicks
+/>;`,
+    },
+  ],
+};