@automattic/charts 1.3.1 → 1.4.1

package/AGENTS.md

@@ -1,78 +0,0 @@
-# AGENTS.md
-
-Package-specific guidance for AI agents working in `projects/js-packages/charts`.
-
-## CRITICAL Rules
-
-- Do not invent behavior in docs. If unsure, verify implementation and stories first.
-- Do not assume wildcard exports like `./*` or `./providers/*` — they don't exist. Check the explicit exports in `package.json`.
-
-## Changelog
-
-Run from monorepo root:
-
-```bash
-jp changelog add js-packages/charts -s patch -t changed -e "Charts: <user-facing change>."
-```
-
-## Architecture Decisions (Do Not "Fix" These)
-
-- Accessibility behavior (keyboard navigation, accessible tooltips) is core chart behavior, not optional polish.
-- Charts are responsive by default — do not add external responsive wrappers that conflict with built-in sizing semantics.
-
-## WordPress UI + Theme Integration
-
-The package is migrating to WordPress UI and Theme as its defaults. When adding or changing code, follow these defaults unless the task explicitly says otherwise:
-
-- **Design tokens (WPDS).** In SCSS, use `var(--wpds-dimension-*, <fallback>)`, `var(--wpds-border-*, <fallback>)`, and `var(--wpds-typography-*, <fallback>)` instead of hardcoded px values for spacing, padding, margins, border radius, border width, font size, and font weight. Fallbacks must match the WPDS spec value for that token — do not invent fallback values.
-- **UI primitives.** Prefer `Stack` and the stable `Text` from `@wordpress/ui` over ad-hoc flexbox or raw `<span>`/`<div>` for layout and text. Do not use `__experimental*` exports from `@wordpress/components` (e.g. `__experimentalText`, `__experimentalHStack`) — use the stable `@wordpress/ui` equivalents. Exception: `__experimentalGrid` has no stable alternative yet and is acceptable to use for now.
-- **Theming.** Theming flows through `@wordpress/theme`'s `ThemeProvider` (unlocked via private APIs in Storybook; see `src/stories/chart-decorator.tsx`). Do not manually override DS tokens in stories or components to achieve theming — pass a color through `ThemeProvider` instead.
-- **Chart element styles.** Read chart element styles via `getElementStyles` from `GlobalChartsProvider`, not directly from `theme`. This is the supported path for color/style resolution across themes.
-
-## Documentation Workflow
-
-- For docs tasks agents should use the skill at `.agents/skills/charts-docs.md`.
-- For public chart/component docs, maintain the standard set when applicable: `[feature-name].stories.tsx` + `.docs.mdx` + `.api.mdx`. Some docs are intentionally guide-only and skip the full triplet.
-- Only include animation docs when the component actually supports an `animation` prop.
-
-## Conventions
-
-- Preserve backward compatibility for existing public APIs unless a breaking change is explicitly requested.
-- Prefer extending existing chart components/patterns over introducing new surface area.
-- Reuse existing hooks/providers/utilities before adding new abstractions.
-- Avoid `!important` unless there is no viable alternative and the rationale is documented.
-- Add focused behavioral tests for changed behavior; avoid speculative tests for unimplemented behavior.
-- Verify behavior/UI changes in Storybook using browser automation, not only unit tests.
-- Prefer charts-scoped PR titles (e.g. `Charts: ...`, `CHARTS-###: ...`).
-- Include test steps and visual evidence (screenshots/GIFs) in PR descriptions for UI changes.
-
-## Common Pitfalls
-
-- Claiming Rollup is used for builds (it's tsup).
-- Documenting props or behavior not present in stories and implementation.
-- Refactoring core composition/provider patterns as if they are accidental complexity.
-- Defining new chart prop interfaces that diverge from established base chart contracts (for example, not aligning with `BaseChartProps` when appropriate).
-- Using ad-hoc flexbox layouts where established layout primitives (e.g. `Stack` from `@wordpress/ui`) should be preferred.
-- Accessing colors/styles directly from `theme` rather than using `getElementStyles` from `GlobalChartsProvider`.
-- Hardcoding px values in SCSS for spacing, borders, or typography where a WPDS token (`--wpds-dimension-*`, `--wpds-border-*`, `--wpds-typography-*`) exists.
-- CSS variable fallback values that diverge from the WPDS spec for that token.
-- Using `__experimental*` exports from `@wordpress/components` (e.g. `__experimentalText`, `__experimentalHStack`) instead of the stable `@wordpress/ui` equivalents. (`__experimentalGrid` is excepted — no stable alternative exists yet.)
-- Manually overriding DS tokens in stories or components to achieve theming instead of passing a color through `@wordpress/theme`'s `ThemeProvider`.
-- Responsive wrappers that conflict with component sizing semantics (fixed-height charts, resize behavior, aspect-ratio assumptions).
-- Updating `.docs.mdx` without the corresponding `.api.mdx` when API docs are affected.
-- Not checking CSF file references in `.docs.mdx` when changing or removing stories.
-- Stories that don't visibly demonstrate documented behavior/props, or render clipped due to container sizing.
-- Breaking MDX `<Source code={\`...\` } />` rendering by malformed/flattened indentation inside template literals.
-- Tooltip styles/positioning that only work on default backgrounds or fail at chart edges.
-- Using mock/placeholder series data in production code.
-- Avoidable multi-pass data transformations in render paths when a single pass suffices.
-- CSS layout/overflow workarounds without documenting why they're needed.
-
-## Definition of Done
-
-- Behavior verified in Storybook and/or tests, not only by static checks.
-- Edits remain in package boundaries; avoid unrelated refactors.
-
-## References
-
-- Published Storybook: `https://automattic.github.io/jetpack-storybook/?path=/docs/js-packages-charts-library`

package/src/hooks/test/use-tooltip-portal-relocator.test.ts

@@ -1,216 +0,0 @@
-/* eslint-disable testing-library/no-node-access */
-import { renderHook } from '@testing-library/react';
-import { useTooltipPortalRelocator } from '../use-tooltip-portal-relocator';
-
-// In the production build, CSS module class names are hashed (e.g. "a8ccharts-abc123").
-// In jest, the SCSS module import is stubbed to a filename string, so
-// styles.relocatedPortal resolves to undefined and classList.add() is a no-op.
-// We mock the module to return a proper class map so we can assert on class names.
-jest.mock( '../use-tooltip-portal-relocator.module.scss', () => ( {
-	__esModule: true,
-	default: { relocatedPortal: 'relocatedPortal' },
-} ) );
-
-/**
- * Create a mock visx tooltip portal node for testing.
- * @return {HTMLDivElement} A div mimicking a visx tooltip portal.
- */
-function createVisxPortalNode(): HTMLDivElement {
-	const portal = document.createElement( 'div' );
-	const child = document.createElement( 'div' );
-	child.className = 'visx-tooltip';
-	portal.appendChild( child );
-	return portal;
-}
-
-/**
- * Sets up a container, ref, and renders the hook.
- * Optionally appends a visx portal node to document.body before rendering.
- * @param options            - Setup options.
- * @param options.withPortal - If true, creates and appends a visx portal before rendering.
- * @return                      Setup result with container, ref, unmount, and optionally the portal node.
- */
-function setupHook( { withPortal = false } = {} ) {
-	const container = document.createElement( 'div' );
-	document.body.appendChild( container );
-
-	let portal: HTMLDivElement | undefined;
-	if ( withPortal ) {
-		portal = createVisxPortalNode();
-		document.body.appendChild( portal );
-	}
-
-	const ref = { current: container };
-	const { unmount } = renderHook( () => useTooltipPortalRelocator( ref ) );
-
-	return { container, ref, unmount, portal };
-}
-
-describe( 'useTooltipPortalRelocator', () => {
-	let nativeRemoveChild: typeof document.body.removeChild;
-
-	beforeAll( () => {
-		nativeRemoveChild = document.body.removeChild;
-	} );
-
-	afterEach( () => {
-		// Restore native removeChild and clear all body children to prevent
-		// leaked portals from interfering with subsequent tests.
-		document.body.removeChild = nativeRemoveChild;
-		while ( document.body.firstChild ) {
-			nativeRemoveChild.call( document.body, document.body.firstChild );
-		}
-	} );
-
-	test( 'does nothing when containerRef is undefined', () => {
-		const { unmount } = renderHook( () => useTooltipPortalRelocator( undefined ) );
-		const portal = createVisxPortalNode();
-		document.body.appendChild( portal );
-		expect( portal.parentNode ).toBe( document.body );
-		unmount();
-	} );
-
-	test( 'does nothing when containerRef.current is null', () => {
-		const nullRef = { current: null };
-		const { unmount } = renderHook( () => useTooltipPortalRelocator( nullRef ) );
-		const portal = createVisxPortalNode();
-		document.body.appendChild( portal );
-		expect( portal.parentNode ).toBe( document.body );
-		unmount();
-	} );
-
-	test( 'relocates existing visx portal nodes into the container', () => {
-		const { container, unmount, portal } = setupHook( { withPortal: true } );
-		expect( portal!.parentNode ).toBe( container );
-		unmount();
-	} );
-
-	test( 'applies relocated-portal class to relocated portals', () => {
-		const { unmount, portal } = setupHook( { withPortal: true } );
-		expect( portal! ).toHaveClass( 'relocatedPortal' );
-		unmount();
-	} );
-
-	test( 'does not relocate newly added non-visx nodes', async () => {
-		const { unmount } = setupHook();
-
-		const regularDiv = document.createElement( 'div' );
-		regularDiv.id = 'some-id';
-		document.body.appendChild( regularDiv );
-
-		// MutationObserver is async — wait for microtask
-		await new Promise( resolve => setTimeout( resolve, 0 ) );
-
-		expect( regularDiv.parentNode ).toBe( document.body );
-		unmount();
-	} );
-
-	test( 'observes and relocates newly added portal nodes', async () => {
-		const { container, unmount } = setupHook();
-
-		const portal = createVisxPortalNode();
-		document.body.appendChild( portal );
-
-		// MutationObserver is async — wait for microtask
-		await new Promise( resolve => setTimeout( resolve, 0 ) );
-
-		expect( portal.parentNode ).toBe( container );
-		unmount();
-	} );
-
-	test( 'patched removeChild handles relocated nodes without throwing', () => {
-		const { unmount, portal } = setupHook( { withPortal: true } );
-
-		// Portal is now in container, but visx will call document.body.removeChild(portal)
-		expect( () => document.body.removeChild( portal! ) ).not.toThrow();
-		expect( portal!.parentNode ).toBeNull();
-		unmount();
-	} );
-
-	test( 'patched removeChild delegates to original for non-relocated nodes', () => {
-		const { unmount } = setupHook();
-
-		const regularDiv = document.createElement( 'div' );
-		document.body.appendChild( regularDiv );
-		expect( () => document.body.removeChild( regularDiv ) ).not.toThrow();
-		expect( regularDiv.parentNode ).toBeNull();
-		unmount();
-	} );
-
-	test( 'cleanup restores removeChild when it has not been wrapped by others', () => {
-		const originalRemoveChild = document.body.removeChild;
-		const { unmount } = setupHook();
-
-		// removeChild should be patched
-		expect( document.body.removeChild ).not.toBe( originalRemoveChild );
-
-		unmount();
-
-		// Should be restored
-		expect( document.body.removeChild ).toBe( originalRemoveChild );
-	} );
-
-	test( 'cleanup leaves removeChild when another wrapper was installed after ours', () => {
-		const { unmount } = setupHook();
-
-		// Simulate another library wrapping removeChild after our patch
-		const ourPatch = document.body.removeChild;
-		const thirdPartyWrapper = function < T extends Node >( child: T ): T {
-			return ourPatch.call( document.body, child );
-		};
-		document.body.removeChild = thirdPartyWrapper;
-
-		unmount();
-
-		// Should NOT restore — third party wrapper is still in place
-		expect( document.body.removeChild ).toBe( thirdPartyWrapper );
-	} );
-
-	test( 'cleanup moves relocated nodes back to document.body', () => {
-		const { container, unmount, portal } = setupHook( { withPortal: true } );
-
-		expect( portal!.parentNode ).toBe( container );
-
-		unmount();
-
-		// Node should be moved back to body on cleanup
-		expect( portal!.parentNode ).toBe( document.body );
-	} );
-
-	test( 'cleanup removes relocated-portal class from nodes', () => {
-		const { unmount, portal } = setupHook( { withPortal: true } );
-
-		expect( portal! ).toHaveClass( 'relocatedPortal' );
-
-		unmount();
-
-		expect( portal! ).not.toHaveClass( 'relocatedPortal' );
-	} );
-
-	test( 'ref-counting allows multiple instances to share the patch', () => {
-		const container1 = document.createElement( 'div' );
-		const container2 = document.createElement( 'div' );
-		document.body.appendChild( container1 );
-		document.body.appendChild( container2 );
-
-		const ref1 = { current: container1 };
-		const ref2 = { current: container2 };
-
-		const originalRemoveChild = document.body.removeChild;
-
-		const { unmount: unmountFirst } = renderHook( () => useTooltipPortalRelocator( ref1 ) );
-		const patchedFn = document.body.removeChild;
-		const { unmount: unmountSecond } = renderHook( () => useTooltipPortalRelocator( ref2 ) );
-
-		// Both should share the same patched removeChild
-		expect( document.body.removeChild ).toBe( patchedFn );
-
-		// Unmounting the first should keep the patch (ref count > 0)
-		unmountFirst();
-		expect( document.body.removeChild ).toBe( patchedFn );
-
-		// Unmounting the second should restore the original
-		unmountSecond();
-		expect( document.body.removeChild ).toBe( originalRemoveChild );
-	} );
-} );

package/src/hooks/use-tooltip-portal-relocator.module.scss

@@ -1,7 +0,0 @@
-.relocatedPortal {
-	position: fixed;
-	inset: 0;
-	overflow: visible;
-	z-index: 1;
-	pointer-events: none;
-}

package/src/hooks/use-tooltip-portal-relocator.ts

@@ -1,188 +0,0 @@
-import { useEffect } from 'react';
-import styles from './use-tooltip-portal-relocator.module.scss';
-import type { RefObject } from 'react';
-
-/**
- * Detects whether a DOM node is a visx chart tooltip portal.
- *
- * visx renders tooltips via `ReactDOM.createPortal` into plain `<div>` elements
- * appended to `document.body`. These portals have no id or className and contain
- * a child element with the class `visx-tooltip`.
- * @param node - The DOM node to check.
- * @return Whether the node is a visx tooltip portal div.
- */
-function isVisxPortalNode( node: Node ): node is HTMLDivElement {
-	return (
-		node instanceof HTMLDivElement &&
-		node.parentElement === document.body &&
-		! node.id &&
-		! node.className &&
-		node.querySelector( '.visx-tooltip' ) !== null
-	);
-}
-
-// Shared state for the document.body.removeChild patch.
-// Reference-counted so multiple hook instances can coexist safely.
-let patchRefCount = 0;
-let origRemoveChild: typeof document.body.removeChild | null = null;
-let patchedRemoveChild: typeof document.body.removeChild | null = null;
-const relocatedNodes = new WeakSet< Node >();
-
-/**
- * Installs (or increments the ref count of) the shared removeChild patch.
- */
-function installRemoveChildPatch() {
-	if ( patchRefCount++ > 0 ) {
-		return;
-	}
-	origRemoveChild = document.body.removeChild;
-	patchedRemoveChild = function < T extends Node >( this: HTMLElement, child: T ): T {
-		if ( relocatedNodes.has( child ) && child.parentNode !== this ) {
-			relocatedNodes.delete( child );
-			child.parentNode?.removeChild( child );
-			return child;
-		}
-		return origRemoveChild!.call( this, child );
-	};
-	document.body.removeChild = patchedRemoveChild;
-}
-
-/**
- * Decrements the ref count and removes the patch when no instances remain.
- * If another library has since wrapped our patch, we leave it in place to
- * avoid breaking their chain — our function becomes a transparent pass-through
- * once all relocated nodes have been cleaned up.
- */
-function uninstallRemoveChildPatch() {
-	if ( --patchRefCount > 0 ) {
-		return;
-	}
-	// Only revert if removeChild is still our function. If something else
-	// has wrapped it, reverting would break their patch.
-	if ( document.body.removeChild === patchedRemoveChild ) {
-		document.body.removeChild = origRemoveChild!;
-	}
-	origRemoveChild = null;
-	patchedRemoveChild = null;
-}
-
-/**
- * Relocates visx chart tooltip portals from `document.body` into a target
- * container element. This allows the tooltips to participate in the same CSS
- * stacking context as other elements in the container (e.g. a sticky header),
- * so z-index ordering works correctly between them.
- *
- * The relocated portal divs use `position: fixed` at the viewport origin to
- * preserve the tooltip coordinate system (visx calculates positions relative
- * to the viewport).
- *
- * Because the visx Portal class calls `document.body.removeChild(node)` during
- * unmount, we patch `document.body.removeChild` to gracefully handle nodes that
- * were moved out of body. Without this, React throws a "not a child of this
- * node" error when tooltips unmount.
- *
- * **Important:** The container and its ancestors must not have CSS `transform`,
- * `perspective`, or `filter` properties set, as these create a new containing
- * block for `position: fixed` children, breaking viewport-relative positioning.
- *
- * @param containerRef - Ref to the element that portals should be relocated into.
- *                     The element referenced here, or one of its ancestors,
- *                     should establish the desired stacking context (for example
- *                     by using position and z-index).
- */
-export function useTooltipPortalRelocator(
-	containerRef: RefObject< HTMLElement | null > | undefined
-) {
-	useEffect( () => {
-		const container = containerRef?.current;
-		if ( ! container ) {
-			return;
-		}
-
-		// Track nodes relocated by this instance so we can move them back on cleanup.
-		const instanceNodes = new Set< Node >();
-
-		const relocateNode = ( node: Node ) => {
-			if ( ! isVisxPortalNode( node ) ) {
-				return;
-			}
-
-			// Hide the portal immediately to prevent the tooltip from
-			// flashing at (0,0) before visx calculates the correct position.
-			node.style.opacity = '0';
-
-			// Position the portal at the viewport origin so visx's
-			// absolute-positioned tooltip coordinates remain correct.
-			// Zero-size with overflow: visible so it doesn't affect layout
-			// but tooltip content still renders. pointerEvents: none on the
-			// wrapper is intentional — tooltip inner elements manage their own.
-			node.classList.add( styles.relocatedPortal );
-
-			// Remember the focused element before moving the node — relocating
-			// a DOM subtree causes the browser to blur any focused descendants.
-			const { activeElement } = node.ownerDocument;
-			const focusedElement =
-				activeElement instanceof HTMLElement && node.contains( activeElement )
-					? activeElement
-					: null;
-
-			// Insert at the start of the container (before header and content).
-			container.insertBefore( node, container.firstChild );
-			relocatedNodes.add( node );
-			instanceNodes.add( node );
-
-			// Restore focus that was lost due to the DOM move.
-			if ( focusedElement ) {
-				focusedElement.focus();
-			}
-
-			// Reveal after two animation frames so visx has positioned the tooltip.
-			requestAnimationFrame( () => {
-				requestAnimationFrame( () => {
-					node.style.opacity = '';
-				} );
-			} );
-		};
-
-		// Patch document.body.removeChild so visx Portal unmount doesn't throw
-		// when it tries to remove a node we already moved out of body.
-		installRemoveChildPatch();
-
-		// Relocate any portals that already exist.
-		for ( const child of Array.from( document.body.children ) ) {
-			relocateNode( child );
-		}
-
-		// Watch for new portals being appended to body.
-		const observer = new MutationObserver( mutations => {
-			for ( const mutation of mutations ) {
-				for ( const node of mutation.addedNodes ) {
-					relocateNode( node );
-				}
-			}
-		} );
-
-		observer.observe( document.body, { childList: true } );
-
-		return () => {
-			// Disconnect first to avoid the observer re-relocating nodes
-			// as we move them back to body.
-			observer.disconnect();
-
-			// Move relocated nodes back to body so visx can clean them up
-			// normally with the original removeChild.
-			for ( const node of instanceNodes ) {
-				if ( node instanceof HTMLElement ) {
-					node.classList.remove( styles.relocatedPortal );
-				}
-				if ( node.parentNode === container ) {
-					document.body.appendChild( node );
-				}
-				relocatedNodes.delete( node );
-			}
-			instanceNodes.clear();
-
-			uninstallRemoveChildPatch();
-		};
-	}, [ containerRef ] );
-}