diff --git a/packages/x-charts/src/hooks/useChartDimensions.ts b/packages/x-charts/src/hooks/useChartDimensions.ts deleted file mode 100644 index e2e047f2cc99c..0000000000000 --- a/packages/x-charts/src/hooks/useChartDimensions.ts +++ /dev/null @@ -1,34 +0,0 @@ -'use client'; -import * as React from 'react'; -import { DEFAULT_MARGINS } from '../constants'; -import { LayoutConfig } from '../models/layout'; - -const useChartDimensions = (width: number, height: number, margin: LayoutConfig['margin']) => { - const defaultizedMargin = { - ...DEFAULT_MARGINS, - ...margin, - }; - - const drawingArea = React.useMemo( - () => ({ - left: defaultizedMargin.left, - top: defaultizedMargin.top, - right: defaultizedMargin.right, - bottom: defaultizedMargin.bottom, - width: Math.max(0, width - defaultizedMargin.left - defaultizedMargin.right), - height: Math.max(0, height - defaultizedMargin.top - defaultizedMargin.bottom), - }), - [ - width, - height, - defaultizedMargin.top, - defaultizedMargin.bottom, - defaultizedMargin.left, - defaultizedMargin.right, - ], - ); - - return drawingArea; -}; - -export default useChartDimensions; diff --git a/packages/x-charts/src/internals/plugins/models/plugin.ts b/packages/x-charts/src/internals/plugins/models/plugin.ts index 33e9d155a12e5..50d3e9cd11677 100644 --- a/packages/x-charts/src/internals/plugins/models/plugin.ts +++ b/packages/x-charts/src/internals/plugins/models/plugin.ts @@ -5,12 +5,34 @@ import { ChartStore } from '../utils/ChartStore'; import { ChartSeriesConfig } from './seriesConfig'; export interface ChartPluginOptions { + /** + * An imperative api available for internal use. + */ instance: ChartUsedInstance; + /** + * The parameters after being processed with the default values. + */ params: ChartUsedDefaultizedParams; + /** + * The store of controlled properties. + * If they are not controlled by the user, they will be initialized by the plugin. + */ models: ChartUsedControlModels; + /** + * The store that can be used to access the state of other plugins. + */ store: ChartUsedStore; + /** + * Reference to the main svg element. + */ svgRef: React.RefObject; + /** + * All the plugins that are used in the chart. + */ plugins: ChartPlugin[]; + /** + * All the series configurations that are currently loaded. + */ seriesConfig: ChartSeriesConfig; } @@ -40,11 +62,31 @@ export type ChartPluginSignature< optionalDependencies?: readonly ChartAnyPluginSignature[]; }, > = { + /** + * The raw properties that can be passed to the plugin. + */ params: T extends { params: {} } ? T['params'] : {}; + /** + * The params after being processed with the default values. + */ defaultizedParams: T extends { defaultizedParams: {} } ? T['defaultizedParams'] : {}; + /** + * An imperative api available for internal use. + */ instance: T extends { instance: {} } ? T['instance'] : {}; + /** + * The state is the mutable data that will actually be stored in the plugin state and can be accessed by other plugins. + */ state: T extends { state: {} } ? T['state'] : {}; + /** + * The public imperative API that will be exposed to the user. + * Accessed through the `apiRef` property of the plugin. + */ publicAPI: T extends { publicAPI: {} } ? T['publicAPI'] : {}; + /** + * A helper for controlled properties. + * Properties defined here can be controlled by the user. If they are not controlled, they will be initialized by the plugin. + */ models: T extends { defaultizedParams: {}; modelNames: keyof T['defaultizedParams'] } ? { [TControlled in T['modelNames']]-?: ChartControlModel< @@ -52,22 +94,28 @@ export type ChartPluginSignature< >; } : {}; + /** + * Any plugins that this plugin depends on. + */ dependencies: T extends { dependencies: Array } ? T['dependencies'] : []; + /** + * Same as dependencies but the plugin might not have been initialized. + */ optionalDependencies: T extends { optionalDependencies: Array } ? T['optionalDependencies'] : []; }; -export type ChartAnyPluginSignature = { - state: any; - instance: any; +export type ChartAnyPluginSignature = ChartPluginSignature<{ params: any; - models: any; defaultizedParams: any; + instance: any; + publicAPI: any; + state: any; + modelNames: any; dependencies: any; optionalDependencies: any; - publicAPI: any; -}; +}>; type ChartRequiredPlugins = [ ...ChartCorePluginSignatures, @@ -118,14 +166,44 @@ export type ChartUsedStore = ChartSt >; export type ChartPlugin = { + /** + * The main function of the plugin that will be executed by the chart. + * + * This should be a valid React `use` function, as it will be executed in the render phase and can contain hooks. + */ (options: ChartPluginOptions): ChartResponse; + /** + * The initial state is computed after the default values are applied. + * It set up the state for the first render. + * Other state modifications have to be done in effects and so could not be applied on the initial render. + * + * @param {ChartUsedDefaultizedParams} params The parameters after being processed with the default values. + * @param {MergeSignaturesProperty, 'state'>} currentState The current state of the chart. + * @param {ChartSeriesConfig} seriesConfig The series configuration. + * + * @returns {TSignature['state']} The initial state of the plugin. + */ getInitialState?: ( params: ChartUsedDefaultizedParams, currentState: MergeSignaturesProperty, 'state'>, seriesConfig: ChartSeriesConfig, ) => TSignature['state']; + /** + * The configuration of properties that can be controlled by the user. + * If they are not controlled, they will be initialized by the plugin. + */ models?: ChartControlModelsInitializer; + /** + * An object where each property used by the plugin is set to `true`. + */ params: Record; + /** + * A function that receives the parameters and returns the parameters after being processed with the default values. + * + * @param {ChartUsedParams} options The options object. + * @param {ChartUsedParams['params']} options.params The parameters before being processed with the default values. + * @returns {TSignature['defaultizedParams']} The parameters after being processed with the default values. + */ getDefaultizedParams?: (options: { params: ChartUsedParams; }) => TSignature['defaultizedParams']; diff --git a/packages/x-charts/src/internals/store/useCharts.ts b/packages/x-charts/src/internals/store/useCharts.ts index 8d25137a9217a..856b998a7105f 100644 --- a/packages/x-charts/src/internals/store/useCharts.ts +++ b/packages/x-charts/src/internals/store/useCharts.ts @@ -17,24 +17,17 @@ import { ChartSeriesType } from '../../models/seriesType/config'; import { ChartSeriesConfig } from '../plugins/models/seriesConfig'; import { useChartModels } from './useChartModels'; -export function useChartApiInitialization( - inputApiRef: React.RefObject | undefined, -): T { - const fallbackPublicApiRef = React.useRef({}) as React.RefObject; - - if (inputApiRef) { - if (inputApiRef.current == null) { - // eslint-disable-next-line react-compiler/react-compiler - inputApiRef.current = {} as T; - } - return inputApiRef.current; - } - - return fallbackPublicApiRef.current; -} - let globalId = 0; +/** + * This is the main hook that setups the plugin system for the chart. + * + * It manages the data used to create the charts. + * + * @param inPlugins All the plugins that will be used in the chart. + * @param props The props passed to the chart. + * @param seriesConfig The set of helpers used for series-specific computation. + */ export function useCharts< TSeriesType extends ChartSeriesType, TSignatures extends readonly ChartAnyPluginSignature[], @@ -131,3 +124,19 @@ export function useCharts< return { contextValue }; } + +export function useChartApiInitialization( + inputApiRef: React.RefObject | undefined, +): T { + const fallbackPublicApiRef = React.useRef({}) as React.RefObject; + + if (inputApiRef) { + if (inputApiRef.current == null) { + // eslint-disable-next-line react-compiler/react-compiler + inputApiRef.current = {} as T; + } + return inputApiRef.current; + } + + return fallbackPublicApiRef.current; +} diff --git a/packages/x-internals/src/fastObjectShallowCompare/fastObjectShallowCompare.ts b/packages/x-internals/src/fastObjectShallowCompare/fastObjectShallowCompare.ts index d2cb4abc79a83..6e0c8824b772c 100644 --- a/packages/x-internals/src/fastObjectShallowCompare/fastObjectShallowCompare.ts +++ b/packages/x-internals/src/fastObjectShallowCompare/fastObjectShallowCompare.ts @@ -1,5 +1,9 @@ const is = Object.is; +/** + * Fast shallow compare for objects. + * @returns true if objects are equal. + */ export function fastObjectShallowCompare | null>(a: T, b: T) { if (a === b) { return true;