Repository: mui/mui-x
Pull request #17309: [charts] Expose axes types
Author: login: bernardobelchior
Labels: name: type: enhancement
description: It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature.
name: scope: charts
description: Changes related to the charts.
Created: 2025-04-10T10:28:07Z | Merged: 2025-04-11T08:07:48Z

Related to https://github.com/mui/mui-x/issues/16802.

Expose axes types for better DX. Reasoning available [here](https://github.com/mui/mui-x/issues/16802).


Diff:
diff --git a/docs/translations/api-docs/charts/axis-config.json b/docs/translations/api-docs/charts/axis-config.json
index 5183dfdab9794..8cd13e8259843 100644
--- a/docs/translations/api-docs/charts/axis-config.json
+++ b/docs/translations/api-docs/charts/axis-config.json
@@ -1,5 +1,5 @@
 {
-  "interfaceDescription": "",
+  "interfaceDescription": "Use this type for advanced typing. For basic usage, use <code>XAxis</code>, <code>YAxis</code>, <code>RotationAxis</code> or <code>RadiusAxis</code>.",
   "propertiesDescriptions": {
     "id": { "description": "Id used to identify the axis." },
     "scaleType": { "description": "" },
diff --git a/packages/x-charts-pro/src/FunnelChart/index.ts b/packages/x-charts-pro/src/FunnelChart/index.ts
index 3cb2d5fe6ef21..ee92522434f61 100644
--- a/packages/x-charts-pro/src/FunnelChart/index.ts
+++ b/packages/x-charts-pro/src/FunnelChart/index.ts
@@ -2,6 +2,7 @@ export { FunnelChart as Unstable_FunnelChart } from './FunnelChart';
 export type { FunnelChartProps } from './FunnelChart';
 export * from './FunnelPlot';
 export * from './funnel.types';
+export * from './categoryAxis.types';
 export * from './funnelSlots.types';
 export { funnelSectionClasses } from './funnelSectionClasses';
 export type { FunnelSectionClasses } from './funnelSectionClasses';
diff --git a/packages/x-charts/src/internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxis.types.ts b/packages/x-charts/src/internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxis.types.ts
index 30e6fefabca31..f84fd79e07385 100644
--- a/packages/x-charts/src/internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxis.types.ts
+++ b/packages/x-charts/src/internals/plugins/featurePlugins/useChartCartesianAxis/useChartCartesianAxis.types.ts
@@ -1,4 +1,3 @@
-import type { MakeOptional } from '@mui/x-internals/types';
 import type { ChartPluginSignature } from '../../models';
 import type { ChartSeriesType, DatasetType } from '../../../../models/seriesType/config';
 import type {
@@ -9,6 +8,8 @@ import type {
   AxisId,
   AxisConfig,
   ChartsAxisData,
+  YAxis,
+  XAxis,
 } from '../../../../models/axis';
 import type { UseChartSeriesSignature } from '../../corePlugins/useChartSeries';
 import type { ZoomData, ZoomOptions } from './zoom.types';
@@ -19,19 +20,19 @@ export type DefaultizedAxisConfig<AxisProps extends ChartsAxisProps> = {
   [axisId: AxisId]: AxisDefaultized<ScaleName, any, AxisProps>;
 };
 
-export interface UseChartCartesianAxisParameters {
+export interface UseChartCartesianAxisParameters<S extends ScaleName = ScaleName> {
   /**
    * The configuration of the x-axes.
    * If not provided, a default axis config is used.
    * An array of [[AxisConfig]] objects.
    */
-  xAxis?: readonly MakeOptional<AxisConfig<ScaleName, any, ChartsXAxisProps>, 'id'>[];
+  xAxis?: ReadonlyArray<XAxis<S>>;
   /**
    * The configuration of the y-axes.
    * If not provided, a default axis config is used.
    * An array of [[AxisConfig]] objects.
    */
-  yAxis?: readonly MakeOptional<AxisConfig<ScaleName, any, ChartsYAxisProps>, 'id'>[];
+  yAxis?: ReadonlyArray<YAxis<S>>;
   /**
    * An array of objects that can be used to populate series and axes data using their `dataKey` property.
    */
@@ -51,10 +52,11 @@ export interface UseChartCartesianAxisParameters {
   disableAxisListener?: boolean;
 }
 
-export type UseChartCartesianAxisDefaultizedParameters = UseChartCartesianAxisParameters & {
-  defaultizedXAxis: AxisConfig<ScaleName, any, ChartsXAxisProps>[];
-  defaultizedYAxis: AxisConfig<ScaleName, any, ChartsYAxisProps>[];
-};
+export type UseChartCartesianAxisDefaultizedParameters<S extends ScaleName = ScaleName> =
+  UseChartCartesianAxisParameters<S> & {
+    defaultizedXAxis: AxisConfig<S, any, ChartsXAxisProps>[];
+    defaultizedYAxis: AxisConfig<S, any, ChartsYAxisProps>[];
+  };
 
 export interface DefaultizedZoomOptions extends Required<ZoomOptions> {
   axisId: AxisId;
diff --git a/packages/x-charts/src/internals/plugins/featurePlugins/useChartPolarAxis/useChartPolarAxis.types.ts b/packages/x-charts/src/internals/plugins/featurePlugins/useChartPolarAxis/useChartPolarAxis.types.ts
index 85d8b15d6aead..d30a7278d8770 100644
--- a/packages/x-charts/src/internals/plugins/featurePlugins/useChartPolarAxis/useChartPolarAxis.types.ts
+++ b/packages/x-charts/src/internals/plugins/featurePlugins/useChartPolarAxis/useChartPolarAxis.types.ts
@@ -6,6 +6,8 @@ import {
   AxisConfig,
   ChartsRotationAxisProps,
   ChartsRadiusAxisProps,
+  RadiusAxis,
+  RotationAxis,
 } from '../../../../models/axis';
 import { UseChartSeriesSignature } from '../../corePlugins/useChartSeries';
 import { DefaultizedAxisConfig } from '../useChartCartesianAxis';
@@ -60,13 +62,13 @@ export interface UseChartPolarAxisParameters {
    * If not provided, a default axis config is used.
    * An array of [[AxisConfig]] objects.
    */
-  rotationAxis?: AxisConfig<ScaleName, any, ChartsRotationAxisProps>[];
+  rotationAxis?: RotationAxis[];
   /**
    * The configuration of the radial-axes.
    * If not provided, a default axis config is used.
    * An array of [[AxisConfig]] objects.
    */
-  radiusAxis?: AxisConfig<'linear', any, ChartsRadiusAxisProps>[];
+  radiusAxis?: RadiusAxis[];
   /**
    * An array of objects that can be used to populate series and axes data using their `dataKey` property.
    */
diff --git a/packages/x-charts/src/models/axis.ts b/packages/x-charts/src/models/axis.ts
index 53dd1283cd9cb..884ec6b5b3e3f 100644
--- a/packages/x-charts/src/models/axis.ts
+++ b/packages/x-charts/src/models/axis.ts
@@ -1,16 +1,16 @@
 import type {
   ScaleBand,
-  ScaleLogarithmic,
-  ScalePower,
-  ScaleTime,
   ScaleLinear,
-  ScalePoint,
+  ScaleLogarithmic,
   ScaleOrdinal,
+  ScalePoint,
+  ScalePower,
   ScaleSequential,
   ScaleThreshold,
+  ScaleTime,
 } from '@mui/x-charts-vendor/d3-scale';
 import { SxProps } from '@mui/system/styleFunctionSx';
-import { MakeRequired } from '@mui/x-internals/types';
+import { type MakeOptional, MakeRequired } from '@mui/x-internals/types';
 import { ChartsAxisClasses } from '../ChartsAxis/axisClasses';
 import type { TickParams } from '../hooks/useTicks';
 import { ChartsTextProps } from '../ChartsText';
@@ -414,6 +414,9 @@ export type PolarAxisConfig<
   Partial<Omit<AxisScaleConfig[S], 'scale'>> &
   AxisConfigExtension;
 
+/**
+ * Use this type for advanced typing. For basic usage, use `XAxis`, `YAxis`, `RotationAxis` or `RadiusAxis`.
+ */
 export type AxisConfig<
   S extends ScaleName = ScaleName,
   V = any,
@@ -493,3 +496,18 @@ export interface ChartsAxisData {
    */
   seriesValues: Record<string, number | null | undefined>;
 }
+
+export type XAxis<S extends ScaleName = ScaleName> = MakeOptional<
+  AxisConfig<S, any, ChartsXAxisProps>,
+  'id'
+>;
+export type YAxis<S extends ScaleName = ScaleName> = MakeOptional<
+  AxisConfig<S, any, ChartsYAxisProps>,
+  'id'
+>;
+export type RotationAxis<S extends ScaleName = ScaleName> = AxisConfig<
+  S,
+  any,
+  ChartsRotationAxisProps
+>;
+export type RadiusAxis<S extends 'linear' = 'linear'> = AxisConfig<S, any, ChartsRadiusAxisProps>;
diff --git a/packages/x-charts/src/models/index.ts b/packages/x-charts/src/models/index.ts
index f44cfe5617bd7..60c9859b4f9d8 100644
--- a/packages/x-charts/src/models/index.ts
+++ b/packages/x-charts/src/models/index.ts
@@ -7,6 +7,10 @@ export type {
   ScaleName,
   ContinuousScaleName,
   ChartsAxisData,
+  XAxis,
+  YAxis,
+  RadiusAxis,
+  RotationAxis,
 } from './axis';
 
 // Utils shared across the X packages
diff --git a/scripts/x-charts-pro.exports.json b/scripts/x-charts-pro.exports.json
index 4f5b283797750..1406ec3e54c46 100644
--- a/scripts/x-charts-pro.exports.json
+++ b/scripts/x-charts-pro.exports.json
@@ -53,6 +53,7 @@
   { "name": "blueberryTwilightPaletteDark", "kind": "Variable" },
   { "name": "blueberryTwilightPaletteLight", "kind": "Variable" },
   { "name": "CartesianSeriesType", "kind": "TypeAlias" },
+  { "name": "CategoryAxis", "kind": "TypeAlias" },
   { "name": "ChartContainerPro", "kind": "Variable" },
   { "name": "ChartContainerProProps", "kind": "TypeAlias" },
   { "name": "ChartDataProvider", "kind": "Function" },
@@ -317,10 +318,12 @@
   { "name": "RadarSeriesPlotClassKey", "kind": "TypeAlias" },
   { "name": "RadarSeriesPlotProps", "kind": "Interface" },
   { "name": "RadarSeriesType", "kind": "Interface" },
+  { "name": "RadiusAxis", "kind": "TypeAlias" },
   { "name": "rainbowSurgePalette", "kind": "Variable" },
   { "name": "rainbowSurgePaletteDark", "kind": "Variable" },
   { "name": "rainbowSurgePaletteLight", "kind": "Variable" },
   { "name": "referenceLineClasses", "kind": "Variable" },
+  { "name": "RotationAxis", "kind": "TypeAlias" },
   { "name": "ScaleName", "kind": "TypeAlias" },
   { "name": "Scatter", "kind": "Function" },
   { "name": "ScatterChart", "kind": "Variable" },
@@ -418,5 +421,7 @@
   { "name": "useYScale", "kind": "Function" },
   { "name": "useZAxes", "kind": "Function" },
   { "name": "useZAxis", "kind": "Function" },
-  { "name": "useZColorScale", "kind": "Function" }
+  { "name": "useZColorScale", "kind": "Function" },
+  { "name": "XAxis", "kind": "TypeAlias" },
+  { "name": "YAxis", "kind": "TypeAlias" }
 ]
diff --git a/scripts/x-charts.exports.json b/scripts/x-charts.exports.json
index 71fee80bfd558..02178f63af0b6 100644
--- a/scripts/x-charts.exports.json
+++ b/scripts/x-charts.exports.json
@@ -286,10 +286,12 @@
   { "name": "RadarSeriesPlotClassKey", "kind": "TypeAlias" },
   { "name": "RadarSeriesPlotProps", "kind": "Interface" },
   { "name": "RadarSeriesType", "kind": "Interface" },
+  { "name": "RadiusAxis", "kind": "TypeAlias" },
   { "name": "rainbowSurgePalette", "kind": "Variable" },
   { "name": "rainbowSurgePaletteDark", "kind": "Variable" },
   { "name": "rainbowSurgePaletteLight", "kind": "Variable" },
   { "name": "referenceLineClasses", "kind": "Variable" },
+  { "name": "RotationAxis", "kind": "TypeAlias" },
   { "name": "ScaleName", "kind": "TypeAlias" },
   { "name": "Scatter", "kind": "Function" },
   { "name": "ScatterChart", "kind": "Variable" },
@@ -382,5 +384,7 @@
   { "name": "useYScale", "kind": "Function" },
   { "name": "useZAxes", "kind": "Function" },
   { "name": "useZAxis", "kind": "Function" },
-  { "name": "useZColorScale", "kind": "Function" }
+  { "name": "useZColorScale", "kind": "Function" },
+  { "name": "XAxis", "kind": "TypeAlias" },
+  { "name": "YAxis", "kind": "TypeAlias" }
 ]


Reviews:
user: login: JCQuintas
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-10T12:09:00Z
user: login: bernardobelchior
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-10T13:22:00Z
user: login: JCQuintas
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-10T13:33:35Z
user: login: alexfauquette
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-10T13:58:14Z
user: login: alexfauquette
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-10T14:00:41Z
user: login: bernardobelchior
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-10T15:27:22Z
user: login: alexfauquette
body: It does not fix the referenced issue because you added the generic but not the union distribution part
``ts
S extends ScaleName ? ... : never
``

But that can be let for further improvement since other parts of the code will need some refinements
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-11T07:56:05Z

Review comments:
diff_hunk: @@ -0,0 +1,8 @@
+import type { MakeOptional } from '@mui/x-internals/types';
+import { ChartsRadiusAxisProps, ChartsRotationAxisProps } from './models/axis';
+import type { AxisConfig, ChartsXAxisProps, ChartsYAxisProps, ScaleName } from './models';
+
+export type XAxis = MakeOptional<AxisConfig<ScaleName, any, ChartsXAxisProps>, 'id'>;
+export type YAxis = MakeOptional<AxisConfig<ScaleName, any, ChartsYAxisProps>, 'id'>;
+export type RotationAxis = AxisConfig<ScaleName, any, ChartsRotationAxisProps>;
+export type RadiusAxis = AxisConfig<'linear', any, ChartsRadiusAxisProps>;
path: packages/x-charts/src/types.ts
user: login: JCQuintas
body: Looking at it, these should be in `./models/axis` and re-exported at the index. Since we store a lot of our types in the models.
created_at: 2025-04-10T12:09:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,8 @@
+import type { MakeOptional } from '@mui/x-internals/types';
+import { ChartsRadiusAxisProps, ChartsRotationAxisProps } from './models/axis';
+import type { AxisConfig, ChartsXAxisProps, ChartsYAxisProps, ScaleName } from './models';
+
+export type XAxis = MakeOptional<AxisConfig<ScaleName, any, ChartsXAxisProps>, 'id'>;
+export type YAxis = MakeOptional<AxisConfig<ScaleName, any, ChartsYAxisProps>, 'id'>;
+export type RotationAxis = AxisConfig<ScaleName, any, ChartsRotationAxisProps>;
+export type RadiusAxis = AxisConfig<'linear', any, ChartsRadiusAxisProps>;
path: packages/x-charts/src/types.ts
user: login: bernardobelchior
body: Good point! Done  
created_at: 2025-04-10T13:22:00Z
author_association: MEMBER
diff_hunk: @@ -493,3 +493,8 @@ export interface ChartsAxisData {
    */
   seriesValues: Record<string, number | null | undefined>;
 }
+
+export type XAxis = MakeOptional<AxisConfig<ScaleName, any, ChartsXAxisProps>, 'id'>;
path: packages/x-charts/src/models/axis.ts
user: login: alexfauquette
body: This should fix #10334

```suggestion
export type XAxis<S extends ScaleName = ScaleName> = S extends ScaleName ? MakeOptional<AxisConfig<S, any, ChartsXAxisProps>, 'id'> : never;
```
created_at: 2025-04-10T13:58:13Z
author_association: MEMBER
diff_hunk: @@ -493,3 +493,8 @@ export interface ChartsAxisData {
    */
   seriesValues: Record<string, number | null | undefined>;
 }
+
+export type XAxis = MakeOptional<AxisConfig<ScaleName, any, ChartsXAxisProps>, 'id'>;
path: packages/x-charts/src/models/axis.ts
user: login: alexfauquette
body: Maybe also adding a comment on `AxisConfig<...>` definition such as "Use this interface for advanced typing. For basic axis, we recomend using `XAxis`, `YAxis`, `RotationAxis`, and `RadiusAxis`"
created_at: 2025-04-10T14:00:41Z
author_association: MEMBER
diff_hunk: @@ -493,3 +493,8 @@ export interface ChartsAxisData {
    */
   seriesValues: Record<string, number | null | undefined>;
 }
+
+export type XAxis = MakeOptional<AxisConfig<ScaleName, any, ChartsXAxisProps>, 'id'>;
path: packages/x-charts/src/models/axis.ts
user: login: bernardobelchior
body: Updated the PR with your feedback, but it doesn't fix the referenced issue.
created_at: 2025-04-10T15:27:22Z
author_association: MEMBER

PR comments:
user: login: github-actions[bot]
created_at: 2025-04-10T10:28:19Z
body: Thanks for adding a type label to the PR! 👍
author_association: CONTRIBUTOR
user: login: mui-bot
created_at: 2025-04-10T10:31:12Z
body: 
<!--
  0 failure: 
  0 warning: 
  
  1 markdown notices
  DangerID: danger-id-Danger;
-->



**Deploy preview:** <a href="https://deploy-preview-17309--material-ui-x.netlify.app/">https://deploy-preview-17309--material-ui-x.netlify.app/</a>
<p align="right">
  Generated by :no_entry_sign: <a href="https://danger.systems/js">dangerJS</a> against 4151798a3a5106f3895da228711f1507071fc2a2
</p>

author_association: NONE
user: login: codspeed-hq[bot]
created_at: 2025-04-10T10:38:09Z
body: <!-- __CODSPEED_PERFORMANCE_REPORT_COMMENT__ -->
<!-- __CODSPEED_INSTRUMENTATION_PERFORMANCE_REPORT_COMMENT__ -->

## [CodSpeed Performance Report](https://codspeed.io/mui/mui-x/branches/bernardobelchior%3Aexpose-axis-types)

### Merging #17309 will **not alter performance**

<sub>Comparing <code>bernardobelchior:expose-axis-types</code> (4151798) with <code>master</code> (ff14626)</sub>



### Summary

`✅ 8` untouched benchmarks  




author_association: NONE
user: login: bernardobelchior
created_at: 2025-04-11T08:10:40Z
body: > It does not fix the referenced issue because you added the generic but not the union distribution part `ts S extends ScaleName ? ... : never `
> 
> But that can be let for further improvement since other parts of the code will need some refinements

I was pretty sure I had tested it and it hadn't worked, but I tested it again and it's working now 🤔 

Opened a PR [here](https://github.com/mui/mui-x/pull/17321).
author_association: MEMBER