@mui/x-charts 9.11.1 → 9.12.0

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/useChartKeyboardNavigation.mjs

@@ -3,18 +3,159 @@
 import _extends from "@babel/runtime/helpers/esm/extends";
 import * as React from 'react';
 import useEnhancedEffect from '@mui/utils/useEnhancedEffect';
+import useEventCallback from '@mui/utils/useEventCallback';
+import { fastObjectShallowCompare } from '@mui/x-internals/fastObjectShallowCompare';
 import { selectorChartDefaultizedSeries } from "../../corePlugins/useChartSeries/useChartSeries.selectors.mjs";
 import { selectorChartSeriesConfig } from "../../corePlugins/useChartSeriesConfig/index.mjs";
+import { cleanIdentifier } from "../../corePlugins/useChartSeriesConfig/utils/cleanIdentifier.mjs";
+import { focusAccessibilityProxy } from "../../../components/ChartsAccessibilityProxy/focusAccessibilityProxy.mjs";
+import { selectorChartSeriesProcessed } from "../../corePlugins/useChartSeries/index.mjs";
+import { selectorChartXAxis, selectorChartYAxis } from "../useChartCartesianAxis/useChartCartesianAxisRendering.selectors.mjs";
+import { getChartPoint } from "../../../getChartPoint.mjs";
+import { getItemAtAxisPosition } from "./utils/getItemAtAxisPosition.mjs";
 import { findItemActivationHandler, isItemActivationKey } from "./itemActivation.mjs";
-import { selectorChartsIsKeyboardActivationEnabled } from "./useChartKeyboardNavigation.selectors.mjs";
+import { selectorChartsIsFocusVisible, selectorChartsIsKeyboardActivationEnabled } from "./useChartKeyboardNavigation.selectors.mjs";
+
+/**
+ * Identifier cleaners always emit every key their series type uses, leaving the missing ones
+ * `undefined`. A line or area path only knows its series, so it produces a `dataIndex`-less
+ * identifier that can not be focused.
+ */
+function isCompleteFocusIdentifier(identifier) {
+  return Object.values(identifier).every(value => value !== undefined);
+}
 export const useChartKeyboardNavigation = ({
   params,
   store,
   instance
 }) => {
   const {
-    chartsLayerContainerRef
+    chartsLayerContainerRef,
+    chartsAccessibilityProxyRef
   } = instance;
+
+  /**
+   * Whether the next focus change should render the focus.
+   * Pointer interactions set it to `false` so that clicking an item sets the item keyboard
+   * navigation resumes from, without revealing the focus indicator.
+   */
+  const focusVisibleIntentRef = React.useRef(true);
+
+  /**
+   * Whether the last interaction came from the keyboard.
+   * Only then do the highlight and the tooltip follow the focused item: after a click the pointer
+   * is still on the chart, and they must keep following it.
+   */
+  const isKeyboardModalityRef = React.useRef(true);
+
+  /**
+   * The item a tap resolved, waiting for the click to focus it.
+   *
+   * The two steps cannot be merged. Touch clears the pointer item on `pointerleave`, right after
+   * the tap, so the item has to be read early. But touch also emits its compatibility `mousedown`
+   * after that, which moves the focus to the body, so the focus has to be taken late, on the click
+   * that closes the sequence.
+   */
+  const pendingFocusItemRef = React.useRef(null);
+
+  /**
+   * Writes the focus state, only switching the highlight and tooltip to keyboard when visible.
+   * An `undefined` item leaves the focused item untouched, `null` clears it.
+   *
+   * `isFocused` is read from the DOM rather than assumed: a composition may not render the
+   * accessibility proxy, and claiming a focus the chart does not hold would render an indicator
+   * that no blur can ever clear. The item is still stored, so it is restored on the next focus.
+   */
+  const updateFocus = useEventCallback((item, isFocusVisible) => {
+    const keyboardNavigation = store.state.keyboardNavigation;
+    const isFocused = chartsLayerContainerRef.current?.contains(document.activeElement) ?? false;
+    // Only the keyboard hands the highlight and the tooltip over to the focused item. A click
+    // moves the focus, but the pointer is still there and they must keep following it.
+    const followsFocus = isFocused && isFocusVisible && isKeyboardModalityRef.current;
+    store.update(_extends({}, followsFocus && store.state.highlight && {
+      highlight: _extends({}, store.state.highlight, {
+        lastUpdate: 'keyboard'
+      })
+    }, followsFocus && store.state.interaction && {
+      interaction: _extends({}, store.state.interaction, {
+        lastUpdate: 'keyboard'
+      })
+    }, {
+      keyboardNavigation: _extends({}, keyboardNavigation, item !== undefined && {
+        item
+      }, {
+        isFocused,
+        isFocusVisible: isFocused && isFocusVisible
+      })
+    }));
+  });
+
+  /**
+   * Moves the DOM focus into the chart and writes the focus state.
+   * An `undefined` item focuses the chart without changing the focused item.
+   * @returns `true` when the state changed.
+   */
+  const applyFocus = useEventCallback((item, options) => {
+    if (!store.state.keyboardNavigation.enabled) {
+      return false;
+    }
+    const isFocusVisible = options?.visible ?? focusVisibleIntentRef.current;
+    focusVisibleIntentRef.current = isFocusVisible;
+    const container = chartsLayerContainerRef.current;
+    if (!container?.contains(document.activeElement)) {
+      // Focusing fires `focusin` synchronously, which runs `restoreFocus` with the intent above.
+      focusAccessibilityProxy(chartsAccessibilityProxyRef.current);
+    }
+
+    // Read after focusing, `restoreFocus` already ran.
+    const keyboardNavigation = store.state.keyboardNavigation;
+    const isSameItem = item === undefined || keyboardNavigation.item != null && fastObjectShallowCompare(keyboardNavigation.item, item);
+    if (keyboardNavigation.isFocused && keyboardNavigation.isFocusVisible === isFocusVisible && isSameItem) {
+      // Nothing to do: two click paths can resolve the same item, a line mark over its line.
+      return false;
+    }
+    updateFocus(item, isFocusVisible);
+    return true;
+  });
+  const focusItem = useEventCallback((item, options) => {
+    const seriesConfig = selectorChartSeriesConfig(store.state);
+    if (!seriesConfig[item.type]?.keyboardFocusHandler) {
+      // The series type is not part of the keyboard navigation.
+      return false;
+    }
+    const cleanedItem = cleanIdentifier(seriesConfig, item);
+    if (!isCompleteFocusIdentifier(cleanedItem)) {
+      return false;
+    }
+    return applyFocus(cleanedItem, options);
+  });
+
+  /**
+   * The item a click landed on, read from the item the pointer is over. Falls back to the axis
+   * under the pointer, which covers the line and area paths, whose hovered item only knows its
+   * series.
+   *
+   * A click that resolves nothing is left alone rather than focusing the chart. The drawing area
+   * is a rectangle, but the data rarely fills it: taking the focus from a click next to a pie,
+   * outside its circle, reads as the chart grabbing clicks that were not meant for it.
+   */
+  const resolveItemAtPointer = useEventCallback(event => {
+    // Every series reports the item under the pointer, so the click itself needs no wiring.
+    const hoveredItem = store.state.interaction?.hoveredItem;
+    if (hoveredItem != null) {
+      return hoveredItem;
+    }
+    const element = chartsLayerContainerRef.current;
+    const point = element === null ? null : getChartPoint(element, event);
+    const item = point && instance.isPointInside?.(point.x, point.y) ? getItemAtAxisPosition({
+      point,
+      xAxis: selectorChartXAxis(store.state),
+      yAxis: selectorChartYAxis(store.state),
+      processedSeries: selectorChartSeriesProcessed(store.state),
+      focusedItem: store.state.keyboardNavigation.item
+    }) : null;
+    return item;
+  });
   const activationRegistrationsRef = React.useRef(new Map());
   const nextRegistrationIdRef = React.useRef(0);
   const registerItemActivationHandler = React.useCallback((scope, handler) => {
@@ -46,34 +187,43 @@ export const useChartKeyboardNavigation = ({
       }
       if (store.state.keyboardNavigation.isFocused) {
         store.set('keyboardNavigation', _extends({}, store.state.keyboardNavigation, {
-          isFocused: false
+          isFocused: false,
+          isFocusVisible: false
         }));
       }
     }
+
+    // The focus already moved into the chart, so `applyFocus` only reconciles the state with the
+    // current intent: its own focusing step is a no-op here.
     function restoreFocus() {
-      if (!store.state.keyboardNavigation.isFocused) {
-        store.update(_extends({}, store.state.highlight && {
-          highlight: _extends({}, store.state.highlight, {
-            lastUpdate: 'keyboard'
-          })
-        }, store.state.interaction && {
-          interaction: _extends({}, store.state.interaction, {
-            lastUpdate: 'keyboard'
-          })
-        }, {
-          keyboardNavigation: _extends({}, store.state.keyboardNavigation, {
-            isFocused: true
-          })
-        }));
-      }
+      applyFocus(undefined);
+    }
+
+    // A pointer interaction hides the focus, unless it is already visible or `focusItemOnClick`
+    // is set. Read on `pointerdown`, before the click can blur the proxy.
+    function trackPointerIntent() {
+      // A click keeps the focus visible only if it already was, or if the chart opts in.
+      focusVisibleIntentRef.current = params.focusItemOnClick === true || store.state.keyboardNavigation.isFocusVisible;
+      isKeyboardModalityRef.current = false;
+      pendingFocusItemRef.current = null;
+    }
+
+    // Any key press means the user switched to the keyboard, wherever the focus currently is.
+    // Listening on the document also covers tabbing in from outside the chart.
+    function trackKeyboardIntent() {
+      focusVisibleIntentRef.current = true;
+      isKeyboardModalityRef.current = true;
     }
     function activationHandler(event) {
       // Ignore the auto-repeat while the key is held: a pointer click does not repeat either.
       if (event.repeat || !isItemActivationKey(event) || !selectorChartsIsKeyboardActivationEnabled(store.state)) {
         return;
       }
+
+      // The focus has to be visible, not merely held: a click sets the item without revealing it,
+      // and activating an item the user cannot see would be a surprise.
       const focusedItem = store.state.keyboardNavigation.item;
-      if (focusedItem === null || !store.state.keyboardNavigation.isFocused) {
+      if (focusedItem === null || !selectorChartsIsFocusVisible(store.state)) {
         return;
       }
       const handler = findItemActivationHandler(activationRegistrationsRef.current.values(), focusedItem);
@@ -98,34 +248,56 @@ export const useChartKeyboardNavigation = ({
         return;
       }
       newFocusedItem = calculateFocusedItem(newFocusedItem, store.state);
-      if (newFocusedItem !== store.state.keyboardNavigation.item) {
-        event.preventDefault();
-        store.update(_extends({}, store.state.highlight && {
-          highlight: _extends({}, store.state.highlight, {
-            lastUpdate: 'keyboard'
-          })
-        }, store.state.interaction && {
-          interaction: _extends({}, store.state.interaction, {
-            lastUpdate: 'keyboard'
-          })
-        }, {
-          keyboardNavigation: _extends({}, store.state.keyboardNavigation, {
-            item: newFocusedItem
-          })
-        }));
+      const keyboardNavigation = store.state.keyboardNavigation;
+      // The item does not move at the edges of a series that does not cycle, but the key was still
+      // handled, so a focus set by a click must become visible.
+      if (newFocusedItem === keyboardNavigation.item && keyboardNavigation.isFocusVisible) {
+        return;
       }
+      event.preventDefault();
+      updateFocus(newFocusedItem, true);
     }
     element.addEventListener('keydown', activationHandler);
     element.addEventListener('keydown', keyboardHandler);
     element.addEventListener('focusout', removeFocus);
     element.addEventListener('focusin', restoreFocus);
+    element.addEventListener('pointerdown', trackPointerIntent, true);
+    document.addEventListener('keydown', trackKeyboardIntent, true);
     return () => {
       element.removeEventListener('keydown', activationHandler);
       element.removeEventListener('keydown', keyboardHandler);
       element.removeEventListener('focusout', removeFocus);
       element.removeEventListener('focusin', restoreFocus);
+      element.removeEventListener('pointerdown', trackPointerIntent, true);
+      document.removeEventListener('keydown', trackKeyboardIntent, true);
+    };
+  }, [chartsLayerContainerRef, params.disableKeyboardNavigation, store, updateFocus, applyFocus, params.focusItemOnClick]);
+  React.useEffect(() => {
+    if (params.disableKeyboardNavigation) {
+      return undefined;
+    }
+    const tapHandler = instance.addInteractionListener?.('tap', event => {
+      pendingFocusItemRef.current = resolveItemAtPointer(event.detail.srcEvent);
+    });
+    function focusPendingItem(event) {
+      const item = pendingFocusItemRef.current;
+      pendingFocusItemRef.current = null;
+
+      // A handler stopping the propagation keeps the click from reaching this listener, leaving
+      // the item pending. Checking the target stops it from landing on an unrelated later click.
+      if (item !== null && chartsLayerContainerRef.current?.contains(event.target)) {
+        focusItem(item);
+      }
+    }
+
+    // Listens on the document so it runs after the React handlers, which are attached to the
+    // React root above the chart container.
+    document.addEventListener('click', focusPendingItem);
+    return () => {
+      tapHandler?.cleanup();
+      document.removeEventListener('click', focusPendingItem);
     };
-  }, [chartsLayerContainerRef, params.disableKeyboardNavigation, store]);
+  }, [instance, params.disableKeyboardNavigation, resolveItemAtPointer, focusItem, chartsLayerContainerRef]);
   useEnhancedEffect(() => {
     store.set('keyboardNavigation', _extends({}, store.state.keyboardNavigation, {
       enabled: !params.disableKeyboardNavigation
@@ -133,6 +305,7 @@ export const useChartKeyboardNavigation = ({
   }, [store, params.disableKeyboardNavigation]);
   return {
     instance: {
+      focusItem,
       registerItemActivationHandler
     }
   };
@@ -141,9 +314,11 @@ useChartKeyboardNavigation.getInitialState = params => ({
   keyboardNavigation: {
     item: null,
     isFocused: false,
+    isFocusVisible: false,
     enabled: !params.disableKeyboardNavigation
   }
 });
 useChartKeyboardNavigation.params = {
-  disableKeyboardNavigation: true
+  disableKeyboardNavigation: true,
+  focusItemOnClick: true
 };

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/useChartKeyboardNavigation.selectors.d.mts

@@ -1,5 +1,8 @@
 import type { FocusedItemIdentifier } from "../../../../models/seriesType/index.mjs";
 import type { AxisItemIdentifier } from "../../../../models/axis.mjs";
+export declare const selectorChartsIsFocusVisible: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<import("./useChartKeyboardNavigation.types.mjs").UseChartKeyboardNavigationState> & {
+  cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
+}) => boolean;
 export declare const selectorChartsItemIsFocused: (args_0: import("../../corePlugins/useChartId/useChartId.types.mjs").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.mjs").UseChartSeriesConfigState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.mjs").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.mjs").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.mjs").UseChartSeriesState<keyof import("../../../index.mjs").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.mjs").UseChartAnimationState & import("../../../index.mjs").UseChartInteractionListenerState & Partial<import("./useChartKeyboardNavigation.types.mjs").UseChartKeyboardNavigationState> & {
   cacheKey: import("../../models/index.mjs").ChartStateCacheKey;
 }, item: FocusedItemIdentifier<keyof import("../../../index.mjs").ChartsSeriesConfig>) => boolean;

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/useChartKeyboardNavigation.selectors.d.ts

@@ -1,5 +1,8 @@
 import type { FocusedItemIdentifier } from "../../../../models/seriesType/index.js";
 import type { AxisItemIdentifier } from "../../../../models/axis.js";
+export declare const selectorChartsIsFocusVisible: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<import("./useChartKeyboardNavigation.types.js").UseChartKeyboardNavigationState> & {
+  cacheKey: import("../../models/index.js").ChartStateCacheKey;
+}) => boolean;
 export declare const selectorChartsItemIsFocused: (args_0: import("../../corePlugins/useChartId/useChartId.types.js").UseChartIdState & import("../../corePlugins/useChartSeriesConfig/useChartSeriesConfig.types.js").UseChartSeriesConfigState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartExperimentalFeature/useChartExperimentalFeature.types.js").UseChartExperimentalFeaturesState & import("../../corePlugins/useChartDimensions/useChartDimensions.types.js").UseChartDimensionsState & import("../../corePlugins/useChartSeries/useChartSeries.types.js").UseChartSeriesState<keyof import("../../../index.js").ChartsSeriesConfig> & import("../../corePlugins/useChartAnimation/useChartAnimation.types.js").UseChartAnimationState & import("../../../index.js").UseChartInteractionListenerState & Partial<import("./useChartKeyboardNavigation.types.js").UseChartKeyboardNavigationState> & {
   cacheKey: import("../../models/index.js").ChartStateCacheKey;
 }, item: FocusedItemIdentifier<keyof import("../../../index.js").ChartsSeriesConfig>) => boolean;

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/useChartKeyboardNavigation.selectors.js

@@ -3,15 +3,22 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.selectorChartsKeyboardYAxisIndex = exports.selectorChartsKeyboardXAxisIndex = exports.selectorChartsKeyboardItem = exports.selectorChartsItemIsFocused = exports.selectorChartsIsKeyboardNavigationEnabled = exports.selectorChartsIsKeyboardActivationEnabled = exports.selectorChartsHasFocusedItem = exports.selectorChartsFocusedOrToFocusedItem = exports.selectorChartsFocusedItem = void 0;
+exports.selectorChartsKeyboardYAxisIndex = exports.selectorChartsKeyboardXAxisIndex = exports.selectorChartsKeyboardItem = exports.selectorChartsItemIsFocused = exports.selectorChartsIsKeyboardNavigationEnabled = exports.selectorChartsIsKeyboardActivationEnabled = exports.selectorChartsIsFocusVisible = exports.selectorChartsHasFocusedItem = exports.selectorChartsFocusedOrToFocusedItem = exports.selectorChartsFocusedItem = void 0;
 var _store = require("@mui/x-internals/store");
 var _fastObjectShallowCompare = require("@mui/x-internals/fastObjectShallowCompare");
 var _useChartSeries = require("../../corePlugins/useChartSeries");
 var _useChartCartesianAxisRendering = require("../useChartCartesianAxis/useChartCartesianAxisRendering.selectors");
 const selectKeyboardNavigation = state => state.keyboardNavigation;
-const selectorChartsItemIsFocused = exports.selectorChartsItemIsFocused = (0, _store.createSelector)(selectKeyboardNavigation, (keyboardNavigationState, item) => keyboardNavigationState?.isFocused === true && keyboardNavigationState?.item != null && (0, _fastObjectShallowCompare.fastObjectShallowCompare)(keyboardNavigationState.item, item));
-const selectorChartsHasFocusedItem = exports.selectorChartsHasFocusedItem = (0, _store.createSelector)(selectKeyboardNavigation, keyboardNavigationState => keyboardNavigationState?.isFocused === true && keyboardNavigationState?.item != null);
-const selectorChartsFocusedItem = exports.selectorChartsFocusedItem = (0, _store.createSelector)(selectKeyboardNavigation, keyboardNavigationState => keyboardNavigationState?.isFocused === true ? keyboardNavigationState?.item ?? null : null);
+
+/**
+ * The chart owns the DOM focus AND the focus should be rendered.
+ * A pointer-driven focus is `isFocused` without being visible.
+ */
+const isFocusVisible = keyboardNavigationState => keyboardNavigationState?.isFocused === true && keyboardNavigationState.isFocusVisible === true;
+const selectorChartsIsFocusVisible = exports.selectorChartsIsFocusVisible = (0, _store.createSelector)(selectKeyboardNavigation, isFocusVisible);
+const selectorChartsItemIsFocused = exports.selectorChartsItemIsFocused = (0, _store.createSelector)(selectKeyboardNavigation, (keyboardNavigationState, item) => isFocusVisible(keyboardNavigationState) && keyboardNavigationState?.item != null && (0, _fastObjectShallowCompare.fastObjectShallowCompare)(keyboardNavigationState.item, item));
+const selectorChartsHasFocusedItem = exports.selectorChartsHasFocusedItem = (0, _store.createSelector)(selectKeyboardNavigation, keyboardNavigationState => isFocusVisible(keyboardNavigationState) && keyboardNavigationState?.item != null);
+const selectorChartsFocusedItem = exports.selectorChartsFocusedItem = (0, _store.createSelector)(selectKeyboardNavigation, keyboardNavigationState => isFocusVisible(keyboardNavigationState) ? keyboardNavigationState?.item ?? null : null);
 
 /**
  * The item that is either
@@ -47,7 +54,7 @@ const createSelectAxisHighlight = direction => (item, axis, series) => {
 const selectorChartsKeyboardXAxisIndex = exports.selectorChartsKeyboardXAxisIndex = (0, _store.createSelector)(selectorChartsFocusedItem, _useChartCartesianAxisRendering.selectorChartXAxis, _useChartSeries.selectorChartSeriesProcessed, createSelectAxisHighlight('x'));
 const selectorChartsKeyboardYAxisIndex = exports.selectorChartsKeyboardYAxisIndex = (0, _store.createSelector)(selectorChartsFocusedItem, _useChartCartesianAxisRendering.selectorChartYAxis, _useChartSeries.selectorChartSeriesProcessed, createSelectAxisHighlight('y'));
 const selectorChartsKeyboardItem = exports.selectorChartsKeyboardItem = (0, _store.createSelectorMemoized)(selectKeyboardNavigation, function selectorChartsKeyboardItem(keyboardState) {
-  if (keyboardState?.isFocused !== true || keyboardState?.item == null) {
+  if (!isFocusVisible(keyboardState) || keyboardState?.item == null) {
     return null;
   }
   const {

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/useChartKeyboardNavigation.selectors.mjs

@@ -3,9 +3,16 @@ import { fastObjectShallowCompare } from '@mui/x-internals/fastObjectShallowComp
 import { selectorChartSeriesProcessed } from "../../corePlugins/useChartSeries/index.mjs";
 import { selectorChartXAxis, selectorChartYAxis } from "../useChartCartesianAxis/useChartCartesianAxisRendering.selectors.mjs";
 const selectKeyboardNavigation = state => state.keyboardNavigation;
-export const selectorChartsItemIsFocused = createSelector(selectKeyboardNavigation, (keyboardNavigationState, item) => keyboardNavigationState?.isFocused === true && keyboardNavigationState?.item != null && fastObjectShallowCompare(keyboardNavigationState.item, item));
-export const selectorChartsHasFocusedItem = createSelector(selectKeyboardNavigation, keyboardNavigationState => keyboardNavigationState?.isFocused === true && keyboardNavigationState?.item != null);
-export const selectorChartsFocusedItem = createSelector(selectKeyboardNavigation, keyboardNavigationState => keyboardNavigationState?.isFocused === true ? keyboardNavigationState?.item ?? null : null);
+
+/**
+ * The chart owns the DOM focus AND the focus should be rendered.
+ * A pointer-driven focus is `isFocused` without being visible.
+ */
+const isFocusVisible = keyboardNavigationState => keyboardNavigationState?.isFocused === true && keyboardNavigationState.isFocusVisible === true;
+export const selectorChartsIsFocusVisible = createSelector(selectKeyboardNavigation, isFocusVisible);
+export const selectorChartsItemIsFocused = createSelector(selectKeyboardNavigation, (keyboardNavigationState, item) => isFocusVisible(keyboardNavigationState) && keyboardNavigationState?.item != null && fastObjectShallowCompare(keyboardNavigationState.item, item));
+export const selectorChartsHasFocusedItem = createSelector(selectKeyboardNavigation, keyboardNavigationState => isFocusVisible(keyboardNavigationState) && keyboardNavigationState?.item != null);
+export const selectorChartsFocusedItem = createSelector(selectKeyboardNavigation, keyboardNavigationState => isFocusVisible(keyboardNavigationState) ? keyboardNavigationState?.item ?? null : null);
 
 /**
  * The item that is either
@@ -41,7 +48,7 @@ const createSelectAxisHighlight = direction => (item, axis, series) => {
 export const selectorChartsKeyboardXAxisIndex = createSelector(selectorChartsFocusedItem, selectorChartXAxis, selectorChartSeriesProcessed, createSelectAxisHighlight('x'));
 export const selectorChartsKeyboardYAxisIndex = createSelector(selectorChartsFocusedItem, selectorChartYAxis, selectorChartSeriesProcessed, createSelectAxisHighlight('y'));
 export const selectorChartsKeyboardItem = createSelectorMemoized(selectKeyboardNavigation, function selectorChartsKeyboardItem(keyboardState) {
-  if (keyboardState?.isFocused !== true || keyboardState?.item == null) {
+  if (!isFocusVisible(keyboardState) || keyboardState?.item == null) {
     return null;
   }
   const {

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/useChartKeyboardNavigation.types.d.mts

@@ -4,6 +4,13 @@ import type { UseChartCartesianAxisSignature } from "../useChartCartesianAxis/in
 import type { UseChartHighlightSignature } from "../useChartHighlight/index.mjs";
 import type { FocusedItemIdentifier, SeriesId } from "../../../../models/seriesType/index.mjs";
 import type { ChartSeriesType } from "../../../../models/seriesType/config.mjs";
+export interface FocusItemOptions {
+  /**
+   * Whether the focus indicator should be rendered.
+   * Defaults to `focusItemOnClick || <the focus is already visible>`.
+   */
+  visible?: boolean;
+}
 /**
  * Called when the focused item is activated with the keyboard.
  * @param {KeyboardEvent} event The keyboard event that triggered the activation.
@@ -32,6 +39,16 @@ export interface ItemActivationScope {
   canActivate?: (item: FocusedItemIdentifier<ChartSeriesType>) => boolean;
 }
 export interface UseChartKeyboardNavigationInstance {
+  /**
+   * Makes an item the one keyboard navigation starts from, moving the DOM focus into the chart
+   * when it is not already there.
+   * Does nothing when keyboard navigation is disabled, when the series type does not support it,
+   * or when the identifier is not complete enough to be focused.
+   * @param {FocusedItemIdentifier} item The item to focus.
+   * @param {FocusItemOptions} options Options to override the focus visibility.
+   * @returns {boolean} `true` when the focus state was updated.
+   */
+  focusItem: (item: FocusedItemIdentifier<ChartSeriesType>, options?: FocusItemOptions) => boolean;
   /**
    * Registers a handler triggered when the focused item is activated with the keyboard.
    * Only the handler with the most specific matching scope runs, so plots sharing a series
@@ -52,6 +69,11 @@ export interface UseChartKeyboardNavigationState {
      * If `false` the focus is ignored, but we keep the item in the state to be able to restore it when focus is active again.
      */
     isFocused: boolean;
+    /**
+     * If `false` the focused item is not rendered as focused, and does not drive the highlight and tooltip.
+     * Set when the focus was moved by a pointer instead of the keyboard. Implies `isFocused`.
+     */
+    isFocusVisible: boolean;
     /**
      * Indicates whether keyboard navigation is enabled or not.
      */
@@ -63,6 +85,13 @@ type UseChartKeyboardNavigationParameters = {
    * If `true`, disables keyboard navigation for the chart.
    */
   disableKeyboardNavigation?: boolean;
+  /**
+   * If `true`, clicking an item immediately shows the keyboard focus indicator on it.
+   * By default, clicking sets the item that keyboard navigation starts from, but the focus
+   * indicator stays hidden until the user presses a key.
+   * @default false
+   */
+  focusItemOnClick?: boolean;
 };
 export type UseChartKeyboardNavigationSignature = ChartPluginSignature<{
   params: UseChartKeyboardNavigationParameters;

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/useChartKeyboardNavigation.types.d.ts

@@ -4,6 +4,13 @@ import type { UseChartCartesianAxisSignature } from "../useChartCartesianAxis/in
 import type { UseChartHighlightSignature } from "../useChartHighlight/index.js";
 import type { FocusedItemIdentifier, SeriesId } from "../../../../models/seriesType/index.js";
 import type { ChartSeriesType } from "../../../../models/seriesType/config.js";
+export interface FocusItemOptions {
+  /**
+   * Whether the focus indicator should be rendered.
+   * Defaults to `focusItemOnClick || <the focus is already visible>`.
+   */
+  visible?: boolean;
+}
 /**
  * Called when the focused item is activated with the keyboard.
  * @param {KeyboardEvent} event The keyboard event that triggered the activation.
@@ -32,6 +39,16 @@ export interface ItemActivationScope {
   canActivate?: (item: FocusedItemIdentifier<ChartSeriesType>) => boolean;
 }
 export interface UseChartKeyboardNavigationInstance {
+  /**
+   * Makes an item the one keyboard navigation starts from, moving the DOM focus into the chart
+   * when it is not already there.
+   * Does nothing when keyboard navigation is disabled, when the series type does not support it,
+   * or when the identifier is not complete enough to be focused.
+   * @param {FocusedItemIdentifier} item The item to focus.
+   * @param {FocusItemOptions} options Options to override the focus visibility.
+   * @returns {boolean} `true` when the focus state was updated.
+   */
+  focusItem: (item: FocusedItemIdentifier<ChartSeriesType>, options?: FocusItemOptions) => boolean;
   /**
    * Registers a handler triggered when the focused item is activated with the keyboard.
    * Only the handler with the most specific matching scope runs, so plots sharing a series
@@ -52,6 +69,11 @@ export interface UseChartKeyboardNavigationState {
      * If `false` the focus is ignored, but we keep the item in the state to be able to restore it when focus is active again.
      */
     isFocused: boolean;
+    /**
+     * If `false` the focused item is not rendered as focused, and does not drive the highlight and tooltip.
+     * Set when the focus was moved by a pointer instead of the keyboard. Implies `isFocused`.
+     */
+    isFocusVisible: boolean;
     /**
      * Indicates whether keyboard navigation is enabled or not.
      */
@@ -63,6 +85,13 @@ type UseChartKeyboardNavigationParameters = {
    * If `true`, disables keyboard navigation for the chart.
    */
   disableKeyboardNavigation?: boolean;
+  /**
+   * If `true`, clicking an item immediately shows the keyboard focus indicator on it.
+   * By default, clicking sets the item that keyboard navigation starts from, but the focus
+   * indicator stays hidden until the user presses a key.
+   * @default false
+   */
+  focusItemOnClick?: boolean;
 };
 export type UseChartKeyboardNavigationSignature = ChartPluginSignature<{
   params: UseChartKeyboardNavigationParameters;

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/utils/getItemAtAxisPosition.d.mts

@@ -0,0 +1,28 @@
+import type { ChartSeriesType } from "../../../../../models/seriesType/config.mjs";
+import type { FocusedItemIdentifier } from "../../../../../models/seriesType/index.mjs";
+import type { ProcessedSeries } from "../../../corePlugins/useChartSeries/useChartSeries.types.mjs";
+import type { ComputeResult } from "../../useChartCartesianAxis/computeAxisValue.mjs";
+import type { ChartsXAxisProps, ChartsYAxisProps } from "../../../../../models/axis.mjs";
+/**
+ * Resolves the item a click falls on when it hit no item, by looking at the axis under the
+ * pointer. Keeps the focused series when there is one, so clicking the empty space above a bar
+ * moves along the series the user was already navigating.
+ *
+ * Returns `null` for charts without a cartesian axis, and when the axis resolves no index.
+ */
+export declare function getItemAtAxisPosition({
+  point,
+  xAxis,
+  yAxis,
+  processedSeries,
+  focusedItem
+}: {
+  point: {
+    x: number;
+    y: number;
+  };
+  xAxis: ComputeResult<ChartsXAxisProps> | undefined;
+  yAxis: ComputeResult<ChartsYAxisProps> | undefined;
+  processedSeries: ProcessedSeries<ChartSeriesType>;
+  focusedItem: FocusedItemIdentifier<ChartSeriesType> | null;
+}): FocusedItemIdentifier<ChartSeriesType> | null;

package/internals/plugins/featurePlugins/useChartKeyboardNavigation/utils/getItemAtAxisPosition.d.ts

@@ -0,0 +1,28 @@
+import type { ChartSeriesType } from "../../../../../models/seriesType/config.js";
+import type { FocusedItemIdentifier } from "../../../../../models/seriesType/index.js";
+import type { ProcessedSeries } from "../../../corePlugins/useChartSeries/useChartSeries.types.js";
+import type { ComputeResult } from "../../useChartCartesianAxis/computeAxisValue.js";
+import type { ChartsXAxisProps, ChartsYAxisProps } from "../../../../../models/axis.js";
+/**
+ * Resolves the item a click falls on when it hit no item, by looking at the axis under the
+ * pointer. Keeps the focused series when there is one, so clicking the empty space above a bar
+ * moves along the series the user was already navigating.
+ *
+ * Returns `null` for charts without a cartesian axis, and when the axis resolves no index.
+ */
+export declare function getItemAtAxisPosition({
+  point,
+  xAxis,
+  yAxis,
+  processedSeries,
+  focusedItem
+}: {
+  point: {
+    x: number;
+    y: number;
+  };
+  xAxis: ComputeResult<ChartsXAxisProps> | undefined;
+  yAxis: ComputeResult<ChartsYAxisProps> | undefined;
+  processedSeries: ProcessedSeries<ChartSeriesType>;
+  focusedItem: FocusedItemIdentifier<ChartSeriesType> | null;
+}): FocusedItemIdentifier<ChartSeriesType> | null;