@mui/x-charts 9.11.1 → 9.12.0

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

@@ -1,4 +1,6 @@
 import type { ChartPluginSignature } from "../../models/index.mjs";
+import type { SeriesItemIdentifierWithType } from "../../../../models/seriesType/index.mjs";
+import type { ChartSeriesType } from "../../../../models/seriesType/config.mjs";
 export type Coordinate = {
   x: number;
   y: number;
@@ -21,6 +23,17 @@ export interface UseChartInteractionInstance {
    * @returns {void}
    */
   setLastUpdateSource: (interaction: InteractionUpdateSource) => void;
+  /**
+   * Set the item the pointer is over.
+   * @param {SeriesItemIdentifierWithType} item The item under the pointer.
+   */
+  setHoveredItem: (item: SeriesItemIdentifierWithType<ChartSeriesType>) => void;
+  /**
+   * Remove the item the pointer was over.
+   * @param {SeriesItemIdentifierWithType} itemToRemove Only clears the item when it is the current
+   * one. Omit to clear unconditionally.
+   */
+  clearHoveredItem: (itemToRemove?: SeriesItemIdentifierWithType<ChartSeriesType>) => void;
   /**
    * Handle pointer enter event on the chart Surface.
    */
@@ -46,6 +59,13 @@ export interface UseChartInteractionState {
      * Used to decide if highlight should be based on pointer position or keyboard navigation.
      */
     lastUpdate: InteractionUpdateSource;
+    /**
+     * The item the pointer is currently over.
+     *
+     * Unlike the highlighted and the tooltip items, this one is never controlled, so it always
+     * reflects the pointer. That is what makes it usable to resolve what a click landed on.
+     */
+    hoveredItem: SeriesItemIdentifierWithType<ChartSeriesType> | null;
   };
 }
 export type UseChartInteractionSignature = ChartPluginSignature<{

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

@@ -1,4 +1,6 @@
 import type { ChartPluginSignature } from "../../models/index.js";
+import type { SeriesItemIdentifierWithType } from "../../../../models/seriesType/index.js";
+import type { ChartSeriesType } from "../../../../models/seriesType/config.js";
 export type Coordinate = {
   x: number;
   y: number;
@@ -21,6 +23,17 @@ export interface UseChartInteractionInstance {
    * @returns {void}
    */
   setLastUpdateSource: (interaction: InteractionUpdateSource) => void;
+  /**
+   * Set the item the pointer is over.
+   * @param {SeriesItemIdentifierWithType} item The item under the pointer.
+   */
+  setHoveredItem: (item: SeriesItemIdentifierWithType<ChartSeriesType>) => void;
+  /**
+   * Remove the item the pointer was over.
+   * @param {SeriesItemIdentifierWithType} itemToRemove Only clears the item when it is the current
+   * one. Omit to clear unconditionally.
+   */
+  clearHoveredItem: (itemToRemove?: SeriesItemIdentifierWithType<ChartSeriesType>) => void;
   /**
    * Handle pointer enter event on the chart Surface.
    */
@@ -46,6 +59,13 @@ export interface UseChartInteractionState {
      * Used to decide if highlight should be based on pointer position or keyboard navigation.
      */
     lastUpdate: InteractionUpdateSource;
+    /**
+     * The item the pointer is currently over.
+     *
+     * Unlike the highlighted and the tooltip items, this one is never controlled, so it always
+     * reflects the pointer. That is what makes it usable to resolve what a click landed on.
+     */
+    hoveredItem: SeriesItemIdentifierWithType<ChartSeriesType> | null;
   };
 }
 export type UseChartInteractionSignature = ChartPluginSignature<{

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

@@ -10,18 +10,158 @@ exports.useChartKeyboardNavigation = void 0;
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
 var React = _interopRequireWildcard(require("react"));
 var _useEnhancedEffect = _interopRequireDefault(require("@mui/utils/useEnhancedEffect"));
+var _useEventCallback = _interopRequireDefault(require("@mui/utils/useEventCallback"));
+var _fastObjectShallowCompare = require("@mui/x-internals/fastObjectShallowCompare");
 var _useChartSeries = require("../../corePlugins/useChartSeries/useChartSeries.selectors");
 var _useChartSeriesConfig = require("../../corePlugins/useChartSeriesConfig");
+var _cleanIdentifier = require("../../corePlugins/useChartSeriesConfig/utils/cleanIdentifier");
+var _focusAccessibilityProxy = require("../../../components/ChartsAccessibilityProxy/focusAccessibilityProxy");
+var _useChartSeries2 = require("../../corePlugins/useChartSeries");
+var _useChartCartesianAxisRendering = require("../useChartCartesianAxis/useChartCartesianAxisRendering.selectors");
+var _getChartPoint = require("../../../getChartPoint");
+var _getItemAtAxisPosition = require("./utils/getItemAtAxisPosition");
 var _itemActivation = require("./itemActivation");
 var _useChartKeyboardNavigation = require("./useChartKeyboardNavigation.selectors");
+/**
+ * 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);
+}
 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 = (0, _useEventCallback.default)((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((0, _extends2.default)({}, followsFocus && store.state.highlight && {
+      highlight: (0, _extends2.default)({}, store.state.highlight, {
+        lastUpdate: 'keyboard'
+      })
+    }, followsFocus && store.state.interaction && {
+      interaction: (0, _extends2.default)({}, store.state.interaction, {
+        lastUpdate: 'keyboard'
+      })
+    }, {
+      keyboardNavigation: (0, _extends2.default)({}, 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 = (0, _useEventCallback.default)((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.
+      (0, _focusAccessibilityProxy.focusAccessibilityProxy)(chartsAccessibilityProxyRef.current);
+    }
+
+    // Read after focusing, `restoreFocus` already ran.
+    const keyboardNavigation = store.state.keyboardNavigation;
+    const isSameItem = item === undefined || keyboardNavigation.item != null && (0, _fastObjectShallowCompare.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 = (0, _useEventCallback.default)((item, options) => {
+    const seriesConfig = (0, _useChartSeriesConfig.selectorChartSeriesConfig)(store.state);
+    if (!seriesConfig[item.type]?.keyboardFocusHandler) {
+      // The series type is not part of the keyboard navigation.
+      return false;
+    }
+    const cleanedItem = (0, _cleanIdentifier.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 = (0, _useEventCallback.default)(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 : (0, _getChartPoint.getChartPoint)(element, event);
+    const item = point && instance.isPointInside?.(point.x, point.y) ? (0, _getItemAtAxisPosition.getItemAtAxisPosition)({
+      point,
+      xAxis: (0, _useChartCartesianAxisRendering.selectorChartXAxis)(store.state),
+      yAxis: (0, _useChartCartesianAxisRendering.selectorChartYAxis)(store.state),
+      processedSeries: (0, _useChartSeries2.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) => {
@@ -53,34 +193,43 @@ const useChartKeyboardNavigation = ({
       }
       if (store.state.keyboardNavigation.isFocused) {
         store.set('keyboardNavigation', (0, _extends2.default)({}, 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((0, _extends2.default)({}, store.state.highlight && {
-          highlight: (0, _extends2.default)({}, store.state.highlight, {
-            lastUpdate: 'keyboard'
-          })
-        }, store.state.interaction && {
-          interaction: (0, _extends2.default)({}, store.state.interaction, {
-            lastUpdate: 'keyboard'
-          })
-        }, {
-          keyboardNavigation: (0, _extends2.default)({}, 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 || !(0, _itemActivation.isItemActivationKey)(event) || !(0, _useChartKeyboardNavigation.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 || !(0, _useChartKeyboardNavigation.selectorChartsIsFocusVisible)(store.state)) {
         return;
       }
       const handler = (0, _itemActivation.findItemActivationHandler)(activationRegistrationsRef.current.values(), focusedItem);
@@ -105,34 +254,56 @@ const useChartKeyboardNavigation = ({
         return;
       }
       newFocusedItem = calculateFocusedItem(newFocusedItem, store.state);
-      if (newFocusedItem !== store.state.keyboardNavigation.item) {
-        event.preventDefault();
-        store.update((0, _extends2.default)({}, store.state.highlight && {
-          highlight: (0, _extends2.default)({}, store.state.highlight, {
-            lastUpdate: 'keyboard'
-          })
-        }, store.state.interaction && {
-          interaction: (0, _extends2.default)({}, store.state.interaction, {
-            lastUpdate: 'keyboard'
-          })
-        }, {
-          keyboardNavigation: (0, _extends2.default)({}, 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]);
   (0, _useEnhancedEffect.default)(() => {
     store.set('keyboardNavigation', (0, _extends2.default)({}, store.state.keyboardNavigation, {
       enabled: !params.disableKeyboardNavigation
@@ -140,6 +311,7 @@ const useChartKeyboardNavigation = ({
   }, [store, params.disableKeyboardNavigation]);
   return {
     instance: {
+      focusItem,
       registerItemActivationHandler
     }
   };
@@ -149,9 +321,11 @@ useChartKeyboardNavigation.getInitialState = params => ({
   keyboardNavigation: {
     item: null,
     isFocused: false,
+    isFocusVisible: false,
     enabled: !params.disableKeyboardNavigation
   }
 });
 useChartKeyboardNavigation.params = {
-  disableKeyboardNavigation: true
+  disableKeyboardNavigation: true,
+  focusItemOnClick: true
 };