@automattic/charts 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -5,13 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.31.0] - 2025-09-01
+### Added
+- Charts: adds an agents.md file to project root [#44954]
+- Charts: Refactor shared components, hooks and utils [#44971]
+- Charts: Stable colors for series groups [#44730]
+- Refactor Pie Chart to improve readability. [#44989]
+
+### Changed
+- Enhanced ConversionFunnelChart with render props and TooltipInPortal [#45019]
+
+### Fixed
+- Charts: fix label background colour and text colour [#44990]
+- Refactored leaderboard chart to remove progressbar. [#44982]
+
+## [0.30.0] - 2025-08-27
+### Added
+- Export ConversionFunnelChart for usage outside. [#44952]
+
+### Changed
+- Consolidate sample data across Storybook stories for consistency and maintainability [#44903]
+
 ## [0.29.0] - 2025-08-25
 ### Changed
-- Charts: consolidate and clean up pie chart composition api. [#44856]
+- Charts: Consolidate and clean up pie chart composition API. [#44856]
 
 ## [0.28.0] - 2025-08-21
 ### Added
-- Charts: adds composition legend to pie family charts [#44796]
+- Charts: Add composition legend to pie family charts. [#44796]
 - Charts: Add theme to global context and use instead of that from theme provider [#44809]
 
 ## [0.27.0] - 2025-08-18
@@ -384,6 +405,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed lints following ESLint rule changes for TS [#40584]
 - Fixing a bug in Chart storybook data. [#40640]
 
+[0.31.0]: https://github.com/Automattic/charts/compare/v0.30.0...v0.31.0
+[0.30.0]: https://github.com/Automattic/charts/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/Automattic/charts/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/Automattic/charts/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/Automattic/charts/compare/v0.26.0...v0.27.0

package/agents.md

@@ -0,0 +1,155 @@
+# AGENTS.md
+
+This file provides AI coding agents with specific instructions and context for working on the @automattic/charts library.
+
+## Project Overview
+
+**@automattic/charts** is a React/TypeScript charting library built for interactive data visualizations within Automattic products. The library is built on visx and emphasizes accessibility, responsiveness, and developer experience through a component composition API.
+
+**Key Technologies:**
+- React 18+ with TypeScript (strict mode)
+- visx for chart primitives
+- PostCSS/Sass with BEM naming convention
+- Jest + Testing Library for testing
+- Storybook for documentation and development
+
+## Essential Commands
+
+```bash
+# Development
+pnpm run build:dev          # Development build with source maps
+pnpm run storybook          # Start Storybook development server
+pnpm run typecheck          # TypeScript type checking
+
+# Testing & Quality
+pnpm run test               # Run Jest test suite (TZ=UTC)
+pnpm run test-coverage      # Run tests with coverage report
+
+# Production
+pnpm run build:prod         # Production build (clean + optimized)
+```
+
+## Documentation Standards
+
+**IMPORTANT:** This project has comprehensive documentation standards. Before creating or modifying any components, agents must reference:
+
+- **[docs/ai-documentation-guide.md](docs/ai-documentation-guide.md)** - Comprehensive guide covering documentation standards, writing patterns, and quality requirements for chart components
+- **[docs/feature-documentation.mdx.template](docs/feature-documentation.mdx.template)** - Standard MDX template for new component documentation
+- **[Storybook Documentation](https://automattic.github.io/jetpack-storybook/?path=/docs/js-packages-charts)** - Live examples and API references
+
+## Code Standards & Architecture
+
+### Component Architecture
+- **Compound Components**: Follow established patterns where parent components provide context and child components handle specific functionality
+- **Theme System**: Use the centralized theme system for colors, spacing, and styling
+- **Accessibility First**: Ensure WCAG 2.1 AA compliance for all chart components
+
+### TypeScript Standards
+- Strict TypeScript mode enabled
+- Export types for all public APIs
+- Use proper generic constraints for data types
+- Define clear prop interfaces with JSDoc comments
+
+### Styling Standards
+- **BEM CSS naming convention** (per global guidelines)
+- PostCSS with Sass support
+- CSS custom properties for theming
+- **Never use `!important`** (per global guidelines)
+- Responsive design patterns
+
+### Testing Requirements
+- Jest configuration: `tests/jest.config.cjs`
+- UTC timezone for consistent test results
+- @testing-library/react for component testing
+- Test both interaction and visual rendering
+- Maintain existing coverage standards
+
+## Development Workflow
+
+### For New Components
+1. **Check existing components** - Determine if functionality can be added to existing components rather than creating new ones
+2. **Use the template** - Start with `docs/feature-documentation.mdx.template`
+3. **Follow compound patterns** - Study existing chart components for composition patterns
+4. **Integrate with providers** - Ensure compatibility with existing context providers
+
+### For Component Modifications
+1. **Study surrounding code** - Understand existing patterns and conventions
+2. **Maintain backward compatibility** - Breaking changes to public APIs only when necessary
+3. **Update documentation** - Follow the ai-documentation-guide.md standards
+4. **Test thoroughly** - Verify existing functionality remains intact
+
+### For New Chart Types
+1. **Use visx primitives** - Build on established visx patterns
+2. **Follow theme system** - Integrate with existing color and styling systems
+3. **Accessibility review** - Ensure screen reader compatibility and keyboard navigation
+
+## Build System
+
+- **Rollup** for production builds (CJS/ESM/Types)
+- **Multiple export patterns** in package.json:
+  - `./` - Main library entry
+  - `./*` - Individual components
+  - `./providers/*` - Context providers
+  - `./visx/*` - visx-related utilities
+
+## Security & Compliance
+
+- GPL-2.0-or-later license
+- No secrets or sensitive data in components
+- WordPress security standards where applicable
+- Report security issues via [automattic.com/security](https://automattic.com/security)
+
+## Pull Request Guidelines
+
+When contributing to the Charts library, follow the Jetpack monorepo's standard PR process:
+
+### Required Elements
+- **PR Title**: Use format "Charts: [clear description of change]"
+- **Changelog Entry**: Run `pnpm changelog add` in the charts directory
+- **Testing Instructions**: Include specific steps for testing chart components
+- **Visual Changes**: Provide screenshots/GIFs for any UI modifications
+
+### Charts-Specific Considerations
+- **Storybook Links**: Include links to new/modified component stories
+- **Accessibility Notes**: Document accessibility features and testing approach
+- **Performance Impact**: Note any considerations for large datasets or complex visualizations
+- **Browser Compatibility**: Highlight any browser-specific concerns
+- **Theme Integration**: Verify changes work across different theme configurations
+
+### Reference Documentation
+- [Jetpack Contributing Guide](../../../../docs/CONTRIBUTING.md) - Main contribution standards
+- [PR Lifecycle Documentation](../../../../docs/pull-request.md) - Detailed PR process
+- [Changelog Guidelines](../../../../docs/writing-a-good-changelog-entry.md) - Required changelog format
+
+**Note**: All PRs automatically use the monorepo-wide PR template from `.github/PULL_REQUEST_TEMPLATE.md`.
+
+## Agent-Specific Guidelines
+
+### Before Making Changes
+- Read existing component documentation and stories
+- Check Storybook for usage patterns and examples
+- Verify TypeScript types compile without errors
+- Run tests to ensure no regressions
+
+### When Adding Features
+- Prefer extending existing components over creating new ones
+- Use established theme and provider patterns
+- Follow the documentation template for new features
+- Consider performance impact on large datasets
+
+### Quality Checklist
+- [ ] TypeScript compiles without errors (`pnpm run typecheck`)
+- [ ] Tests pass (`pnpm run test`)
+- [ ] Documentation follows ai-documentation-guide.md standards
+- [ ] Component works with existing providers and themes
+- [ ] Accessibility requirements met
+- [ ] Storybook stories updated/created
+
+## Getting Help
+
+- **Documentation**: Start with `docs/ai-documentation-guide.md`
+- **Examples**: Review existing chart components and their stories
+- **Build Issues**: Check package.json scripts and build configurations
+- **Testing**: Follow patterns in existing test files
+
+This library prioritizes maintainability, accessibility, and developer experience. Always consider how changes affect the broader ecosystem and existing users.

package/dist/cjs/components/bar-chart/bar-chart.js

@@ -9,25 +9,30 @@ var i18n = require('@wordpress/i18n');
 var clsx = require('clsx');
 var react = require('react');
 require('fast-deep-equal');
-var useGlobalChartTheme = require('../../hooks/use-global-chart-theme.js');
 require('@visx/event');
 require('@visx/tooltip');
 var useXychartTheme = require('../../hooks/use-xychart-theme.js');
+var useChartDataTransform = require('../../hooks/use-chart-data-transform.js');
+var useChartMargin = require('../../hooks/use-chart-margin.js');
+var useElementHeight = require('../../hooks/use-element-height.js');
+var useZeroValueDisplay = require('../../hooks/use-zero-value-display.js');
 var globalChartsProvider = require('../../providers/chart-context/global-charts-provider.js');
-var utils = require('../../providers/chart-context/utils.js');
+var useGlobalChartsContext = require('../../providers/chart-context/hooks/use-global-charts-context.js');
+var useChartId = require('../../providers/chart-context/hooks/use-chart-id.js');
+var useChartRegistration = require('../../providers/chart-context/hooks/use-chart-registration.js');
 var createComposition = require('../../utils/create-composition.js');
+require('date-fns');
+require('@automattic/number-formatters');
+require('@visx/text');
+require('deepmerge');
+require('../../providers/theme/theme-provider.js');
 var legend = require('../legend/legend.js');
-require('../legend/base-legend.js');
-var useChartLegendData = require('../legend/use-chart-legend-data.js');
-var singleChartContext = require('../shared/single-chart-context.js');
-var useChartDataTransform = require('../shared/use-chart-data-transform.js');
-var useChartMargin = require('../shared/use-chart-margin.js');
-var useElementHeight = require('../shared/use-element-height.js');
-var useZeroValueDisplay = require('../shared/use-zero-value-display.js');
-var withResponsive = require('../shared/with-responsive.js');
+var useChartLegendItems = require('../legend/hooks/use-chart-legend-items.js');
+var singleChartContext = require('../private/single-chart-context/single-chart-context.js');
+var withResponsive = require('../private/with-responsive/with-responsive.js');
 var accessibleTooltip = require('../tooltip/accessible-tooltip.js');
 var barChart_module = require('./bar-chart.module.scss.js');
-var useBarChartOptions = require('./use-bar-chart-options.js');
+var useBarChartOptions = require('./private/use-bar-chart-options.js');
 
 // Validation function similar to LineChart
 const validateData = (data) => {
@@ -45,8 +50,7 @@ const validateData = (data) => {
 const getPatternId = (chartId, index) => `bar-pattern-${chartId}-${index}`;
 const BarChartInternal = ({ data, chartId: providedChartId, width, height = 400, className, margin, withTooltips = false, showLegend = false, legendOrientation = 'horizontal', legendPosition = 'bottom', legendAlignment = 'center', legendShape = 'rect', gridVisibility: gridVisibilityProp, renderTooltip, options = {}, orientation = 'vertical', withPatterns = false, showZeroValues = false, children, }) => {
     const horizontal = orientation === 'horizontal';
-    const chartId = utils.useChartId(providedChartId);
-    const providerTheme = useGlobalChartTheme.useGlobalChartTheme();
+    const chartId = useChartId.useChartId(providedChartId);
     const theme = useXychartTheme.useXYChartTheme(data);
     const dataSorted = useChartDataTransform.useChartDataTransform(data);
     // Transform data to add a small value for zero bars to make them visible
@@ -54,7 +58,7 @@ const BarChartInternal = ({ data, chartId: providedChartId, width, height = 400,
         enabled: showZeroValues,
     });
     // Create legend items using the reusable hook
-    const legendItems = useChartLegendData.useChartLegendData(dataSorted);
+    const legendItems = useChartLegendItems.useChartLegendItems(dataSorted);
     const chartOptions = useBarChartOptions.useBarChartOptions(dataWithVisibleZeros, horizontal, options);
     const defaultMargin = useChartMargin.useChartMargin(height, chartOptions, dataSorted, theme, horizontal);
     const [legendRef, legendHeight] = useElementHeight.useElementHeight();
@@ -71,7 +75,12 @@ const BarChartInternal = ({ data, chartId: providedChartId, width, height = 400,
         chartRef,
         totalPoints,
     });
-    const getColor = react.useCallback((seriesData, index) => seriesData?.options?.stroke || providerTheme.colors[index % providerTheme.colors.length], [providerTheme]);
+    const { resolveGroupColor } = useGlobalChartsContext.useGlobalChartsContext();
+    const getColor = react.useCallback((seriesData, index) => resolveGroupColor({
+        group: seriesData.group,
+        index,
+        overrideColor: seriesData.options?.stroke,
+    }), [resolveGroupColor]);
     const getBarBackground = react.useCallback((index) => () => withPatterns
         ? `url(#${getPatternId(chartId, index)})`
         : getColor(dataSorted[index], index), [withPatterns, getColor, dataSorted, chartId]);
@@ -150,7 +159,7 @@ const BarChartInternal = ({ data, chartId: providedChartId, width, height = 400,
         withPatterns,
     }), [orientation, withPatterns]);
     // Register chart with context only if data is valid
-    utils.useChartRegistration({
+    useChartRegistration.useChartRegistration({
         chartId,
         legendItems,
         chartType: 'bar',
@@ -177,7 +186,7 @@ const BarChartInternal = ({ data, chartId: providedChartId, width, height = 400,
                         ...(showLegend && legendPosition === 'top'
                             ? { top: (defaultMargin.top || 0) + legendHeight }
                             : {}),
-                    }, xScale: chartOptions.xScale, yScale: chartOptions.yScale, horizontal: horizontal, pointerEventsDataKey: "nearest", children: [jsxRuntime.jsx(xychart.Grid, { columns: gridVisibility.includes('y'), rows: gridVisibility.includes('x'), numTicks: 4 }), withPatterns && (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("defs", { "data-testid": "bar-chart-patterns", children: dataSorted.map((seriesData, index) => renderPattern(index, getColor(seriesData, index))) }), jsxRuntime.jsx("style", { children: dataSorted.map((seriesData, index) => createPatternBorderStyle(index, getColor(seriesData, index))) })] })), highlightedBarStyle && jsxRuntime.jsx("style", { children: highlightedBarStyle }), jsxRuntime.jsx(xychart.BarGroup, { padding: chartOptions.barGroup.padding, children: dataWithVisibleZeros.map((seriesData, index) => (jsxRuntime.jsx(xychart.BarSeries, { dataKey: seriesData?.label, data: seriesData.data, yAccessor: chartOptions.accessors.yAccessor, xAccessor: chartOptions.accessors.xAccessor, colorAccessor: getBarBackground(index) }, seriesData?.label))) }), jsxRuntime.jsx(xychart.Axis, { ...chartOptions.axis.x }), jsxRuntime.jsx(xychart.Axis, { ...chartOptions.axis.y }), withTooltips && (jsxRuntime.jsx(accessibleTooltip.AccessibleTooltip, { detectBounds: true, snapTooltipToDatumX: true, snapTooltipToDatumY: true, renderTooltip: renderTooltip || renderDefaultTooltip, selectedIndex: selectedIndex, tooltipRef: tooltipRef, keyboardFocusedClassName: barChart_module.default['bar-chart__tooltip--keyboard-focused'], series: data, mode: "individual" }))] }), showLegend && (jsxRuntime.jsx(legend.Legend, { items: legendItems, orientation: legendOrientation, position: legendPosition, alignment: legendAlignment, className: barChart_module.default['bar-chart__legend'], shape: legendShape, ref: legendRef, chartId: chartId })), children] }) }));
+                    }, xScale: chartOptions.xScale, yScale: chartOptions.yScale, horizontal: horizontal, pointerEventsDataKey: "nearest", children: [jsxRuntime.jsx(xychart.Grid, { columns: gridVisibility.includes('y'), rows: gridVisibility.includes('x'), numTicks: 4 }), withPatterns && (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("defs", { "data-testid": "bar-chart-patterns", children: dataSorted.map((seriesData, index) => renderPattern(index, getColor(seriesData, index))) }), jsxRuntime.jsx("style", { children: dataSorted.map((seriesData, index) => createPatternBorderStyle(index, getColor(seriesData, index))) })] })), highlightedBarStyle && jsxRuntime.jsx("style", { children: highlightedBarStyle }), jsxRuntime.jsx(xychart.BarGroup, { padding: chartOptions.barGroup.padding, children: dataWithVisibleZeros.map((seriesData, index) => (jsxRuntime.jsx(xychart.BarSeries, { dataKey: seriesData?.label, data: seriesData.data, yAccessor: chartOptions.accessors.yAccessor, xAccessor: chartOptions.accessors.xAccessor, colorAccessor: getBarBackground(index) }, seriesData?.label))) }), jsxRuntime.jsx(xychart.Axis, { ...chartOptions.axis.x }), jsxRuntime.jsx(xychart.Axis, { ...chartOptions.axis.y }), withTooltips && (jsxRuntime.jsx(accessibleTooltip.AccessibleTooltip, { detectBounds: true, snapTooltipToDatumX: true, snapTooltipToDatumY: true, renderTooltip: renderTooltip || renderDefaultTooltip, selectedIndex: selectedIndex, tooltipRef: tooltipRef, keyboardFocusedClassName: barChart_module.default['bar-chart__tooltip--keyboard-focused'], series: data, mode: "individual" }))] }), showLegend && (jsxRuntime.jsx(legend.Legend, { orientation: legendOrientation, position: legendPosition, alignment: legendAlignment, className: barChart_module.default['bar-chart__legend'], shape: legendShape, ref: legendRef, chartId: chartId })), children] }) }));
 };
 const BarChartWithProvider = props => {
     const existingContext = react.useContext(globalChartsProvider.GlobalChartsContext);

package/dist/cjs/components/bar-list-chart/bar-list-chart.js

@@ -8,8 +8,16 @@ var group = require('@visx/group');
 var scale = require('@visx/scale');
 var text = require('@visx/text');
 var react = require('react');
+var globalChartsProvider = require('../../providers/chart-context/global-charts-provider.js');
+require('fast-deep-equal');
+require('@visx/event');
+require('@visx/tooltip');
+require('@visx/xychart');
+require('date-fns');
+require('deepmerge');
+require('../../providers/theme/theme-provider.js');
 var barChart = require('../bar-chart/bar-chart.js');
-var withResponsive = require('../shared/with-responsive.js');
+var withResponsive = require('../private/with-responsive/with-responsive.js');
 
 /**
  * Get the bandwidth of a scale
@@ -72,7 +80,7 @@ const getDefaultYOffset = (data, yScaleConfig, height, isMultiSeries) => {
     // Use negative value to move the label up.
     return -(barThickness + GAP_BETWEEN_BARS);
 };
-const BarListChart = ({ data, width, height, options = {}, margin = {
+const BarListChartInternal = ({ data, width, height, options = {}, margin = {
     left: 0,
     right: 20,
     bottom: 0,
@@ -120,6 +128,17 @@ const BarListChart = ({ data, width, height, options = {}, margin = {
             yScale: chartOptions.yScale,
         }, ...rest }));
 };
-var barListChart = withResponsive.withResponsive(BarListChart);
+const BarListChart = props => {
+    const existingContext = react.useContext(globalChartsProvider.GlobalChartsContext);
+    // If we're already in a GlobalChartsProvider context, render the core component directly
+    if (existingContext) {
+        return jsxRuntime.jsx(BarListChartInternal, { ...props });
+    }
+    // Otherwise, wrap with our own GlobalChartsProvider
+    return (jsxRuntime.jsx(globalChartsProvider.GlobalChartsProvider, { children: jsxRuntime.jsx(BarListChartInternal, { ...props }) }));
+};
+BarListChart.displayName = 'BarListChart';
+const BarListChartResponsive = withResponsive.withResponsive(BarListChart);
 
-exports.default = barListChart;
+exports.BarListChartUnresponsive = BarListChart;
+exports.default = BarListChartResponsive;

package/dist/cjs/components/conversion-funnel-chart/conversion-funnel-chart.js

@@ -0,0 +1,245 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var jsxRuntime = require('react/jsx-runtime');
+var event = require('@visx/event');
+var tooltip = require('@visx/tooltip');
+var clsx = require('clsx');
+var react = require('react');
+require('../../providers/chart-context/global-charts-provider.js');
+require('fast-deep-equal');
+require('@visx/xychart');
+require('date-fns');
+require('@automattic/number-formatters');
+require('@visx/text');
+require('deepmerge');
+var colorUtils = require('../../utils/color-utils.js');
+require('@visx/scale');
+var useGlobalChartsTheme = require('../../providers/chart-context/hooks/use-global-charts-theme.js');
+var conversionFunnelChart_module = require('./conversion-funnel-chart.module.scss.js');
+var useFunnelSelection = require('./private/use-funnel-selection.js');
+
+/**
+ * Default settings for ConversionFunnelChart component
+ */
+const DEFAULT_FUNNEL_SETTINGS = {
+    primaryColor: '#4F46E5',
+    backgroundColor: '#F3F4F6',
+    positiveChangeColor: '#10B981',
+    negativeChangeColor: '#EF4444',
+};
+/**
+ * ConversionFunnelChart component displays a conversion funnel with main metric and visualization
+ *
+ * @param props                  - Component props
+ * @param props.mainRate         - Main conversion rate to highlight
+ * @param props.changeIndicator  - Change indicator (e.g., +2%, -1.5%)
+ * @param props.steps            - Array of funnel steps
+ * @param props.loading          - Whether the chart is in loading state
+ * @param props.className        - Additional CSS class name
+ * @param props.style            - Custom styling
+ * @param props.renderStepLabel  - Custom render function for step labels
+ * @param props.renderStepRate   - Custom render function for step rates
+ * @param props.renderMainMetric - Custom render function for the entire main metric section
+ * @param props.renderTooltip    - Custom render function for tooltip content
+ * @return JSX element representing the conversion funnel chart
+ */
+const ConversionFunnelChart = ({ mainRate, changeIndicator, steps, loading = false, className, style, renderStepLabel, renderStepRate, renderMainMetric, renderTooltip, }) => {
+    const theme = useGlobalChartsTheme.useGlobalChartsTheme();
+    const chartRef = react.useRef(null);
+    const selectedBarRef = react.useRef(null);
+    // Use @visx/tooltip hooks for tooltip positioning
+    const { tooltipData, tooltipLeft, tooltipTop, tooltipOpen, showTooltip, hideTooltip } = tooltip.useTooltip();
+    // Use custom hook for selection management
+    const { handleBarClick, handleBarKeyDown, clearSelection, getStepState } = useFunnelSelection.useFunnelSelection(hideTooltip);
+    const { containerRef: portalContainerRef, TooltipInPortal } = tooltip.useTooltipInPortal({
+        // use TooltipWithBounds for boundary detection
+        detectBounds: true,
+        // when tooltip containers are scrolled, this will correctly update the Tooltip position
+        scroll: true,
+    });
+    // Wrapper to clear selectedBarRef after clearing selection
+    const clearSelectionAndRef = react.useCallback(() => {
+        clearSelection();
+        selectedBarRef.current = null;
+        hideTooltip();
+    }, [clearSelection, hideTooltip]);
+    // Helper function to show tooltip at specific coordinates
+    const showTooltipAt = react.useCallback((step, x, y) => {
+        showTooltip({
+            tooltipData: step,
+            tooltipLeft: x,
+            tooltipTop: y - 10,
+        });
+    }, [showTooltip]);
+    // Helper function to get tooltip coordinates for mouse events
+    const getMouseTooltipCoords = react.useCallback((event$1) => {
+        const containerElement = chartRef.current;
+        if (containerElement) {
+            const coords = event.localPoint(containerElement, event$1.nativeEvent);
+            if (coords) {
+                return { x: coords.x, y: coords.y };
+            }
+        }
+        return null;
+    }, []);
+    // Helper function to get tooltip coordinates for keyboard events
+    const getKeyboardTooltipCoords = react.useCallback((event) => {
+        const rect = event.currentTarget.getBoundingClientRect();
+        const containerElement = chartRef.current;
+        if (containerElement) {
+            const containerRect = containerElement.getBoundingClientRect();
+            const x = rect.left + rect.width / 2 - containerRect.left;
+            const y = rect.top - containerRect.top;
+            return { x, y };
+        }
+        return null;
+    }, []);
+    // Helper function to handle step interaction (both click and keyboard)
+    const handleStepInteraction = react.useCallback((step, event, interactionType) => {
+        // Store reference to the interacted element
+        selectedBarRef.current = event.currentTarget;
+        // Check if deselecting the same step
+        const { isClicked } = getStepState(step.id);
+        if (isClicked) {
+            // Deselecting - clear selection (tooltip will be hidden by hook)
+            if (interactionType === 'click') {
+                handleBarClick(step.id);
+            }
+            else {
+                handleBarKeyDown(step.id, event);
+            }
+            return;
+        }
+        // Selecting - handle selection and show tooltip
+        if (interactionType === 'click') {
+            handleBarClick(step.id);
+            const coords = getMouseTooltipCoords(event);
+            if (coords) {
+                showTooltipAt(step, coords.x, coords.y);
+            }
+        }
+        else {
+            handleBarKeyDown(step.id, event);
+            const coords = getKeyboardTooltipCoords(event);
+            if (coords) {
+                showTooltipAt(step, coords.x, coords.y);
+            }
+        }
+    }, [
+        getStepState,
+        handleBarClick,
+        handleBarKeyDown,
+        showTooltipAt,
+        getMouseTooltipCoords,
+        getKeyboardTooltipCoords,
+    ]);
+    // Create handler factories to avoid arrow functions in JSX
+    const stepHandlers = react.useMemo(() => {
+        const handlers = new Map();
+        steps.forEach(step => {
+            const onClick = (event) => {
+                event.stopPropagation();
+                handleStepInteraction(step, event, 'click');
+            };
+            const onKeyDown = (event) => {
+                if (event.key === 'Enter' || event.key === ' ') {
+                    handleStepInteraction(step, event, 'keyboard');
+                }
+                else {
+                    // For other keys (like Escape), just handle the selection
+                    selectedBarRef.current = event.currentTarget;
+                    handleBarKeyDown(step.id, event);
+                }
+            };
+            handlers.set(step.id, { onClick, onKeyDown });
+        });
+        return handlers;
+    }, [steps, handleStepInteraction, handleBarKeyDown]);
+    // Handle document-level click to clear selection when clicking outside selected bar
+    react.useEffect(() => {
+        const handleDocumentClick = (event) => {
+            // Only clear selection if there's an active selection and click is outside the selected bar
+            if (selectedBarRef.current && !selectedBarRef.current.contains(event.target)) {
+                clearSelectionAndRef();
+            }
+        };
+        document.addEventListener('mousedown', handleDocumentClick);
+        return () => {
+            document.removeEventListener('mousedown', handleDocumentClick);
+        };
+    }, [clearSelectionAndRef]);
+    // Get component settings from theme with fallbacks
+    const funnelSettings = theme.conversionFunnelChart;
+    const primaryColor = funnelSettings?.primaryColor || DEFAULT_FUNNEL_SETTINGS.primaryColor;
+    const positiveChangeColor = funnelSettings?.positiveChangeColor || DEFAULT_FUNNEL_SETTINGS.positiveChangeColor;
+    const negativeChangeColor = funnelSettings?.negativeChangeColor || DEFAULT_FUNNEL_SETTINGS.negativeChangeColor;
+    // Determine change indicator color
+    const isPositiveChange = changeIndicator?.startsWith('+');
+    const changeColor = isPositiveChange ? positiveChangeColor : negativeChangeColor;
+    // Create light background version of primary color
+    const lightBackgroundColor = colorUtils.hexToRgba(primaryColor, 0.08);
+    const chartStyle = {
+        '--primary-color': primaryColor,
+        '--light-background-color': lightBackgroundColor,
+        '--change-indicator-color': changeColor,
+        ...style,
+    };
+    // Default main metric rendering function
+    const renderDefaultMainMetric = () => (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsxs("span", { className: conversionFunnelChart_module.default['main-rate'], children: [mainRate.toFixed(1), "%"] }), changeIndicator && (jsxRuntime.jsx("span", { className: conversionFunnelChart_module.default['change-indicator'], children: changeIndicator }))] }));
+    // Default tooltip rendering function
+    const renderDefaultTooltip = (step) => (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("div", { className: conversionFunnelChart_module.default['tooltip-title'], children: step.label }), jsxRuntime.jsxs("div", { className: conversionFunnelChart_module.default['tooltip-content'], children: [step.rate.toFixed(1), "%", step.count && ` • ${step.count.toLocaleString()} items`] })] }));
+    // Handle empty or undefined data
+    if (!steps || steps.length === 0) {
+        return (jsxRuntime.jsx("div", { className: clsx(conversionFunnelChart_module.default.conversionFunnelChart, loading && conversionFunnelChart_module.default.loading, className), style: chartStyle, children: jsxRuntime.jsx("div", { className: conversionFunnelChart_module.default['empty-state'], children: loading ? 'Loading...' : 'No data available' }) }));
+    }
+    // Calculate bar heights relative to the maximum (first step)
+    const maxRate = Math.max(...steps.map(step => step.rate));
+    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsxs("div", { ref: node => {
+                    // Set containerRef for @visx coordinate system
+                    portalContainerRef(node);
+                    chartRef.current = node;
+                }, className: clsx(conversionFunnelChart_module.default.conversionFunnelChart, loading && conversionFunnelChart_module.default.loading, className), style: chartStyle, children: [renderMainMetric ? (renderMainMetric({
+                        mainRate,
+                        changeIndicator,
+                        className: conversionFunnelChart_module.default['main-metric'],
+                        changeColor,
+                    })) : (jsxRuntime.jsx("div", { className: conversionFunnelChart_module.default['main-metric'], children: renderDefaultMainMetric() })), jsxRuntime.jsx("div", { className: conversionFunnelChart_module.default['funnel-container'], children: steps.map((step, index) => {
+                            const barHeight = (step.rate / maxRate) * 100;
+                            const { isClicked, isBlurred } = getStepState(step.id);
+                            return (jsxRuntime.jsxs("div", { className: clsx(conversionFunnelChart_module.default['funnel-step'], isBlurred && conversionFunnelChart_module.default.blurred), children: [jsxRuntime.jsxs("div", { className: conversionFunnelChart_module.default['step-header'], children: [renderStepLabel ? (renderStepLabel({
+                                                step,
+                                                index,
+                                                className: conversionFunnelChart_module.default['step-label'],
+                                            })) : (jsxRuntime.jsx("span", { className: conversionFunnelChart_module.default['step-label'], children: step.label })), renderStepRate ? (renderStepRate({
+                                                step,
+                                                index,
+                                                className: conversionFunnelChart_module.default['step-rate'],
+                                            })) : (jsxRuntime.jsxs("span", { className: conversionFunnelChart_module.default['step-rate'], children: [step.rate.toFixed(1), "%"] }))] }), jsxRuntime.jsx("div", { className: clsx(conversionFunnelChart_module.default['bar-container'], isClicked && conversionFunnelChart_module.default.selected, isBlurred && conversionFunnelChart_module.default.disabled), onClick: stepHandlers.get(step.id)?.onClick, onKeyDown: stepHandlers.get(step.id)?.onKeyDown, role: "button", tabIndex: isBlurred ? -1 : 0, "aria-label": step.label, children: jsxRuntime.jsx("div", { className: clsx(conversionFunnelChart_module.default['funnel-bar'], isClicked && conversionFunnelChart_module.default.selected), style: {
+                                                height: `${barHeight}%`,
+                                                backgroundColor: primaryColor,
+                                            } }) })] }, step.id));
+                        }) })] }), tooltipOpen &&
+                tooltipData &&
+                (() => {
+                    const tooltipContent = renderTooltip
+                        ? renderTooltip({
+                            step: tooltipData,
+                            index: steps.findIndex(s => s.id === tooltipData.id),
+                            top: tooltipTop,
+                            left: tooltipLeft,
+                            className: conversionFunnelChart_module.default['tooltip-wrapper'],
+                        })
+                        : renderDefaultTooltip(tooltipData);
+                    // Don't render tooltip if renderTooltip returns falsy
+                    if (!tooltipContent)
+                        return null;
+                    return (jsxRuntime.jsx(TooltipInPortal
+                    // set this to random so it correctly updates with parent bounds
+                    , { top: tooltipTop, left: tooltipLeft, className: conversionFunnelChart_module.default['tooltip-wrapper'], children: tooltipContent }, Math.random()));
+                })()] }));
+};
+
+exports.ConversionFunnelChart = ConversionFunnelChart;
+exports.default = ConversionFunnelChart;

package/dist/cjs/components/conversion-funnel-chart/conversion-funnel-chart.module.scss.js

@@ -0,0 +1,7 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var styles = {"conversionFunnelChart":"conversion-funnel-chart-module_conversionFunnelChart__-9Qsb","loading":"conversion-funnel-chart-module_loading__Kw-iZ","main-metric":"conversion-funnel-chart-module_main-metric__8mIwV","main-rate":"conversion-funnel-chart-module_main-rate__D93Ub","change-indicator":"conversion-funnel-chart-module_change-indicator__QWypV","funnel-container":"conversion-funnel-chart-module_funnel-container__RR7xa","funnel-step":"conversion-funnel-chart-module_funnel-step__VIVzt","blurred":"conversion-funnel-chart-module_blurred__Ax4cu","step-header":"conversion-funnel-chart-module_step-header__bUrZ0","step-label":"conversion-funnel-chart-module_step-label__SCy8F","step-rate":"conversion-funnel-chart-module_step-rate__A0irB","bar-container":"conversion-funnel-chart-module_bar-container__5Dl5-","selected":"conversion-funnel-chart-module_selected__W40FY","disabled":"conversion-funnel-chart-module_disabled__Reovk","funnel-bar":"conversion-funnel-chart-module_funnel-bar__tG5m3","tooltip-wrapper":"conversion-funnel-chart-module_tooltip-wrapper__NohPt","tooltip-title":"conversion-funnel-chart-module_tooltip-title__hjZr3","tooltip-content":"conversion-funnel-chart-module_tooltip-content__ocwAP","empty-state":"conversion-funnel-chart-module_empty-state__9c0ps"};
+
+exports.default = styles;