[charts] Add typedocs to pubic hooks and improve types

packages/x-charts-pro/src/Heatmap/HeatmapPlot.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import { useXScale, useYScale, useZColorScale } from '@mui/x-charts/hooks';
-import { useHeatmapSeries } from '../hooks/useSeries';
+import { useHeatmapSeries } from '../hooks/useHeatmapSeries';
 import { HeatmapItem, HeatmapItemProps } from './HeatmapItem';
 
 export interface HeatmapPlotProps extends Pick<HeatmapItemProps, 'slots' | 'slotProps'> {}

packages/x-charts-pro/src/Heatmap/HeatmapTooltip.tsx

@@ -16,7 +16,7 @@ import {
 } from '@mui/x-charts/ChartsTooltip';
 import { useXAxis, useYAxis } from '@mui/x-charts/hooks';
 import { getLabel, ChartsLabelMark } from '@mui/x-charts/internals';
-import { useHeatmapSeries } from '../hooks/useSeries';
+import { useHeatmapSeries } from '../hooks/useHeatmapSeries';
 
 export interface HeatmapTooltipProps
   extends Omit<ChartsTooltipContainerProps, 'trigger' | 'children'> {}

packages/x-charts-pro/src/hooks/index.ts

@@ -1,2 +1,2 @@
-export { useHeatmapSeries } from './useSeries';
+export { useHeatmapSeries } from './useHeatmapSeries';
 export * from './zoom';

packages/x-charts-pro/src/hooks/useHeatmapSeries.test.ts

@@ -0,0 +1,72 @@
+import { renderHook } from '@mui/internal-test-utils';
+import { expect } from 'chai';
+import { stub, restore } from 'sinon';
+import type { SeriesId, ProcessedSeries } from '@mui/x-charts/internals';
+import * as series from '@mui/x-charts/hooks/useSeries';
+import { useHeatmapSeries } from './useHeatmapSeries';
+
+describe('useHeatmapSeries', () => {
+  const defaultProps = {
+    valueFormatter: (v: any) => v,
+    color: 'red',
+    layout: 'vertical',
+    type: 'heatmap',
+  } as const;
+
+  const mockSeries: ProcessedSeries = {
+    heatmap: {
+      series: {
+        '1': {
+          ...defaultProps,
+          id: '1',
+          data: [
+            [0, 0, 10],
+            [0, 1, 20],
+            [0, 2, 40],
+          ],
+        },
+        '2': {
+          ...defaultProps,
+          id: '2',
+          data: [
+            [3, 2, 20],
+            [3, 3, 70],
+            [3, 4, 90],
+          ],
+        },
+      },
+      seriesOrder: ['1', '2'],
+    },
+  };
+
+  beforeEach(() => {
+    stub(series, 'useSeries').returns(mockSeries);
+  });
+
+  afterEach(() => {
+    restore();
+  });
+
+  it('should return all heatmap series when no seriesIds are provided', () => {
+    const { result } = renderHook(() => useHeatmapSeries());
+    expect(result.current).to.deep.equal(mockSeries.heatmap);
+  });
+
+  it('should return the specific heatmap series when a single seriesId is provided', () => {
+    const { result } = renderHook(() => useHeatmapSeries('1' as SeriesId));
+    expect(result.current).to.deep.equal(mockSeries!.heatmap!.series['1']);
+  });
+
+  it('should return the specific heatmap series when multiple seriesIds are provided', () => {
+    const { result } = renderHook(() => useHeatmapSeries('1' as SeriesId, '2' as SeriesId));
+    expect(result.current).to.deep.equal([
+      mockSeries!.heatmap!.series['1'],
+      mockSeries!.heatmap!.series['2'],
+    ]);
+  });
+
+  it('should filter out undefined series when invalid seriesIds are provided', () => {
+    const { result } = renderHook(() => useHeatmapSeries('1' as SeriesId, '3' as SeriesId));
+    expect(result.current).to.deep.equal([mockSeries!.heatmap!.series['1']]);
+  });
+});

packages/x-charts-pro/src/hooks/useHeatmapSeries.ts

@@ -0,0 +1,33 @@
+'use client';
+import {
+  useSeriesOfType,
+  ProcessedSeries,
+  SeriesId,
+  ChartSeriesDefaultized,
+} from '@mui/x-charts/internals';
+
+/**
+ * Get access to the internal state of heatmap series.
+ * The returned object contains:
+ * - series: a mapping from ids to series attributes.
+ * - seriesOrder: the array of series ids.
+ * @returns { series: Record<SeriesId, DefaultizedHeatmapSeriesType>; seriesOrder: SeriesId[]; } | undefined heatmapSeries
+ */
+export function useHeatmapSeries(): ProcessedSeries['heatmap'];
+/**
+ * Get access to the internal state of heatmap series.
+ *
+ * @param {SeriesId} seriesId The id of the series to get.
+ * @returns {ChartSeriesDefaultized<'heatmap'> | undefined}  heatmapSeries
+ */
+export function useHeatmapSeries(seriesId: SeriesId): ChartSeriesDefaultized<'heatmap'>;
+/**
+ * Get access to the internal state of heatmap series.
+ *
+ * @param {SeriesId[]} seriesIds The ids of the series to get. Order is preserved.
+ * @returns {ChartSeriesDefaultized<'heatmap'>[] | undefined}  heatmapSeries
+ */
+export function useHeatmapSeries(...seriesIds: SeriesId[]): ChartSeriesDefaultized<'heatmap'>[];
+export function useHeatmapSeries(...seriesIds: SeriesId[]): any {
+  return useSeriesOfType('heatmap', ...seriesIds);
+}

packages/x-charts/src/BarChart/BarPlot.tsx

@@ -13,7 +13,7 @@ import { BarClipPath } from './BarClipPath';
 import { BarLabelItemProps, BarLabelSlotProps, BarLabelSlots } from './BarLabel/BarLabelItem';
 import { BarLabelPlot } from './BarLabel/BarLabelPlot';
 import { checkScaleErrors } from './checkScaleErrors';
-import { useBarSeries } from '../hooks/useSeries';
+import { useBarSeries } from '../hooks/useBarSeries';
 import { useSkipAnimation } from '../context/AnimationProvider';
 import { SeriesProcessorResult } from '../internals/plugins/models/seriesConfig/seriesProcessor.types';
 

packages/x-charts/src/ChartsVoronoiHandler/ChartsVoronoiHandler.tsx

@@ -8,7 +8,7 @@ import { useStore } from '../internals/store/useStore';
 import { getSVGPoint } from '../internals/getSVGPoint';
 import { ScatterItemIdentifier } from '../models';
 import { SeriesId } from '../models/seriesType/common';
-import { useScatterSeries } from '../hooks/useSeries';
+import { useScatterSeries } from '../hooks/useScatterSeries';
 import { useChartContext } from '../context/ChartProvider/useChartContext';
 import { useDrawingArea } from '../hooks/useDrawingArea';
 import { useSvgRef } from '../hooks/useSvgRef';

packages/x-charts/src/LineChart/AreaPlot.tsx

@@ -15,7 +15,7 @@ import { getCurveFactory } from '../internals/getCurve';
 import { isBandScale } from '../internals/isBandScale';
 import { DEFAULT_X_AXIS_KEY } from '../constants';
 import { LineItemIdentifier } from '../models/seriesType/line';
-import { useLineSeries } from '../hooks/useSeries';
+import { useLineSeries } from '../hooks/useLineSeries';
 import { useSkipAnimation } from '../context/AnimationProvider';
 import { useChartGradientIdBuilder } from '../hooks/useChartGradientId';
 import { useXAxes, useYAxes } from '../hooks/useAxis';

packages/x-charts/src/LineChart/LineHighlightPlot.tsx

@@ -8,7 +8,7 @@ import { LineHighlightElement, LineHighlightElementProps } from './LineHighlight
 import { getValueToPositionMapper } from '../hooks/useScale';
 import { DEFAULT_X_AXIS_KEY } from '../constants';
 import getColor from './getColor';
-import { useLineSeries } from '../hooks/useSeries';
+import { useLineSeries } from '../hooks/useLineSeries';
 import { useChartContext } from '../context/ChartProvider';
 import { selectorChartsInteractionXAxis } from '../internals/plugins/featurePlugins/useChartInteraction';
 import { useXAxes, useYAxes } from '../hooks/useAxis';

packages/x-charts/src/LineChart/LinePlot.tsx

@@ -15,7 +15,7 @@ import { getCurveFactory } from '../internals/getCurve';
 import { isBandScale } from '../internals/isBandScale';
 import { DEFAULT_X_AXIS_KEY } from '../constants';
 import { LineItemIdentifier } from '../models/seriesType/line';
-import { useLineSeries } from '../hooks/useSeries';
+import { useLineSeries } from '../hooks/useLineSeries';
 import { useSkipAnimation } from '../context/AnimationProvider';
 import { useChartGradientIdBuilder } from '../hooks/useChartGradientId';
 import { useXAxes, useYAxes } from '../hooks';

packages/x-charts/src/LineChart/MarkPlot.tsx

@@ -5,7 +5,7 @@ import { DEFAULT_X_AXIS_KEY } from '../constants';
 import { useSkipAnimation } from '../context/AnimationProvider';
 import { useChartId } from '../hooks/useChartId';
 import { getValueToPositionMapper } from '../hooks/useScale';
-import { useLineSeries } from '../hooks/useSeries';
+import { useLineSeries } from '../hooks/useLineSeries';
 import { cleanId } from '../internals/cleanId';
 import { LineItemIdentifier } from '../models/seriesType/line';
 import { CircleMarkElement } from './CircleMarkElement';

packages/x-charts/src/PieChart/PiePlot.tsx

@@ -5,7 +5,7 @@ import { PieArcPlot, PieArcPlotProps, PieArcPlotSlotProps, PieArcPlotSlots } fro
 import { PieArcLabelPlotSlots, PieArcLabelPlotSlotProps, PieArcLabelPlot } from './PieArcLabelPlot';
 import { getPercentageValue } from '../internals/getPercentageValue';
 import { getPieCoordinates } from './getPieCoordinates';
-import { usePieSeries } from '../hooks/useSeries';
+import { usePieSeries } from '../hooks/usePieSeries';
 import { useSkipAnimation } from '../context/AnimationProvider';
 import { useDrawingArea } from '../hooks';
 

packages/x-charts/src/ScatterChart/ScatterPlot.tsx

@@ -3,7 +3,7 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import { Scatter, ScatterProps } from './Scatter';
 import getColor from './getColor';
-import { useScatterSeries } from '../hooks/useSeries';
+import { useScatterSeries } from '../hooks/useScatterSeries';
 import { useXAxes, useYAxes } from '../hooks';
 import { useZAxes } from '../hooks/useZAxis';
 

packages/x-charts/src/hooks/index.ts

@@ -5,14 +5,12 @@ export * from './useAxis';
 export * from './useZAxis';
 export * from './useColorScale';
 export * from './useSvgRef';
+export * from './useSeries';
+export * from './useScatterSeries';
+export * from './usePieSeries';
+export * from './useBarSeries';
+export * from './useLineSeries';
 export * from './useItemHighlighted';
 export * from './useItemHighlightedGetter';
-export {
-  useSeries,
-  usePieSeries,
-  useLineSeries,
-  useBarSeries,
-  useScatterSeries,
-} from './useSeries';
 export * from './useLegend';
 export { useChartGradientId, useChartGradientIdObjectBound } from './useChartGradientId';

packages/x-charts/src/hooks/useAxis.ts

@@ -6,35 +6,66 @@ import {
 } from '../internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxis.selectors';
 import { useSelector } from '../internals/store/useSelector';
 import { useStore } from '../internals/store/useStore';
+import { AxisId } from '../models/axis';
 
+/**
+ * Get all the X axes.
+ *
+ * - `xAxis` is an object with the shape `{ [axisId]: axis }`.
+ * - `xAxisIds` is an array of axis IDs.
+ *
+ * If access to a specific X axis is needed, use the `useXAxis` hook instead.
+ *
+ * @returns `{ xAxis, xAxisIds }` - The X axes and their IDs.
+ */
 export function useXAxes() {
   const store = useStore<[UseChartCartesianAxisSignature]>();
   const { axis: xAxis, axisIds: xAxisIds } = useSelector(store, selectorChartXAxis);
 
   return { xAxis, xAxisIds };
 }
 
+/**
+ * Get all the Y axes.
+ *
+ * - `yAxis` is an object with the shape `{ [axisId]: axis }`.
+ * - `yAxisIds` is an array of axis IDs.
+ *
+ * If access to a specific Y axis is needed, use the `useYAxis` hook instead.
+ *
+ * @returns `{ yAxis, yAxisIds }` - The Y axes and their IDs.
+ */
 export function useYAxes() {
   const store = useStore<[UseChartCartesianAxisSignature]>();
   const { axis: yAxis, axisIds: yAxisIds } = useSelector(store, selectorChartYAxis);
 
   return { yAxis, yAxisIds };
 }
 
-export function useXAxis(identifier?: number | string) {
+/**
+ * Get the X axis.
+ * @param {AxisId | undefined} axisId - If provided returns the x axis with axisId, else returns the values for the default x axis.
+ * @returns The X axis.
+ */
+export function useXAxis(axisId?: AxisId) {
   const store = useStore<[UseChartCartesianAxisSignature]>();
   const { axis: xAxis, axisIds: xAxisIds } = useSelector(store, selectorChartXAxis);
 
-  const id = typeof identifier === 'string' ? identifier : xAxisIds[identifier ?? 0];
+  const id = axisId ?? xAxisIds[0];
 
   return xAxis[id];
 }
 
-export function useYAxis(identifier?: number | string) {
+/**
+ * Get the Y axis.
+ * @param {AxisId | undefined} axisId - If provided returns the y axis with axisId, else returns the values for the default y axis.
+ * @returns The Y axis.
+ */
+export function useYAxis(axisId?: AxisId) {
   const store = useStore<[UseChartCartesianAxisSignature]>();
   const { axis: yAxis, axisIds: yAxisIds } = useSelector(store, selectorChartYAxis);
 
-  const id = typeof identifier === 'string' ? identifier : yAxisIds[identifier ?? 0];
+  const id = axisId ?? yAxisIds[0];
 
   return yAxis[id];
 }

packages/x-charts/src/hooks/useBarSeries.test.ts

@@ -0,0 +1,59 @@
+import { renderHook } from '@mui/internal-test-utils';
+import { expect } from 'chai';
+import { stub, restore } from 'sinon';
+import { useBarSeries } from './useBarSeries';
+import * as series from './useSeries';
+import { SeriesId } from '../models/seriesType/common';
+import { ProcessedSeries } from '../internals/plugins/corePlugins/useChartSeries/useChartSeries.types';
+
+describe('useBarSeries', () => {
+  const defaultProps = {
+    valueFormatter: (v: any) => v,
+    color: 'red',
+    layout: 'vertical',
+    type: 'bar',
+    stackedData: [] as [number, number][],
+  } as const;
+
+  const mockSeries: ProcessedSeries = {
+    bar: {
+      series: {
+        '1': { ...defaultProps, id: '1', data: [1, 2, 3] },
+        '2': { ...defaultProps, id: '2', data: [4, 5, 6] },
+      },
+      seriesOrder: ['1', '2'],
+      stackingGroups: [],
+    },
+  };
+
+  beforeEach(() => {
+    stub(series, 'useSeries').returns(mockSeries);
+  });
+
+  afterEach(() => {
+    restore();
+  });
+
+  it('should return all bar series when no seriesIds are provided', () => {
+    const { result } = renderHook(() => useBarSeries());
+    expect(result.current).to.deep.equal(mockSeries.bar);
+  });
+
+  it('should return the specific bar series when a single seriesId is provided', () => {
+    const { result } = renderHook(() => useBarSeries('1' as SeriesId));
+    expect(result.current).to.deep.equal(mockSeries!.bar!.series['1']);
+  });
+
+  it('should return the specific bar series when multiple seriesIds are provided', () => {
+    const { result } = renderHook(() => useBarSeries('1' as SeriesId, '2' as SeriesId));
+    expect(result.current).to.deep.equal([
+      mockSeries!.bar!.series['1'],
+      mockSeries!.bar!.series['2'],
+    ]);
+  });
+
+  it('should filter out undefined series when invalid seriesIds are provided', () => {
+    const { result } = renderHook(() => useBarSeries('1' as SeriesId, '3' as SeriesId));
+    expect(result.current).to.deep.equal([mockSeries!.bar!.series['1']]);
+  });
+});