DataGrid - Joy UI integration

[siriwatknp]

Motivation

• The need from the community Tweak GridRootStyles to allow CSS variables (and joy-ui!) #6083
• Joy UI components are in good shape to start the POC
• A good opportunity to explore how DataGrid can handle different design libraries (Material You, @mui/material-next is another design library)

Ideal goals

• ✅ Small breaking changes as much as possible We won't have a breaking change because @mui/material is already a peer dependency. Need to update the build script to add package.json to DataGridJoy folder.

  // to use Joy + DataGrid
  import DataGrid, { ... } from '@mui/x-data-grid/DataGridJoy';

• Extract all of the direct Material UI usages out of DataGrid
• Developers can switch to using Joy UI with the least effort

Direct usage of Material UI

Here is the list of the direct Material UI usage in DataGrid that should be extracted, so that DataGrid does not depend on Material UI:

1. @mui/material/utils

This should be safe to switch to @mui/utils and mark it as a dependency of DataGrid.

Components on top of Material UI

For example, GridMenu is created by Popper, Grow, ...Material UI components.

mui-x/packages/grid/x-data-grid/src/components/menu/GridMenu.tsx

Line 110 in 514ed0d

{({ TransitionProps, placement }) => (

Migration:

Convert these components into slots (DataGrid already provides a React context for doing this, so this should be fine).

Then create the mapping slots that use Material UI or Joy UI components. It could look like this:

import { DataGrid } from '@mui/x-data-grid';
import { components as materialDataGridcomponents } from '@mui/x-data-grid-material';
import { components as joyDataGridcomponents } from '@mui/x-data-grid-joy';

<DataGrid components={materialDataGridcomponents} /> // material design
<DataGrid components={joyDataGridcomponents} /> // joy design

Material UI Adapter package:

import { GridRowCountProps } from '@mui/x-data-grid';
// Material UI adapter

const GridRowCount = React.forwardRef<any, GridRowCountProps>((props, ref) => {
  return ...Material UI components
})

export const components = {
  GridRowCount,
  ...
}

Joy UI Adapter package:

import { GridRowCountProps } from '@mui/x-data-grid';
// Joy UI adapter

const GridRowCount = React.forwardRef<any, GridRowCountProps>((props, ref) => {
  return ...Joy UI components
})

export const components = {
  GridRowCount,
  ...
}

2. Material UI's styled

For example, GridRowCount. These components are design-agnostic, so there is no need for them to move to slots.

mui-x/packages/grid/x-data-grid/src/components/GridRowCount.tsx

Line 33 in 2f186c3

const GridRowCountRoot = styled('div', {

Migration:

-import { styled } from '@mui/material/styles';
+import { styled } from '@mui/system';

Switch to styled from MUI System. The theming API does not differ, except the sx prop which will be fixed from the core repo. mui/material-ui#35150 moves the sx logic to the theme, which allows each adapter to configure its own sx logic.

Meaning, developers can use sx prop for DataGrid components that are not slots:

// For DataGrid - Material UI
<GridRowCount sx={{ borderRadius: 2 }} /> // ✅

// For DataGrid - Joy UI
<GridRowCount sx={{ borderRadius: 'sm' }} /> // ✅

3. Material UI theme tokens

For example, GridOverlay

mui-x/packages/grid/x-data-grid/src/components/containers/GridOverlay.tsx

Line 38 in 2f186c3

backgroundColor: alpha(theme.palette.background.default, theme.palette.action.disabledOpacity),

Migration:

Move palette usage to CSS variables (the values will be defined in the GridRootStyles of each design adapter).

const GridOverlayRoot = styled('div', {
  name: 'MuiDataGrid',
  slot: 'Overlay',
  overridesResolver: (props, styles) => styles.overlay,
})(({ theme }) => ({
  ...,
-  backgroundColor: alpha(theme.palette.background.default, theme.palette.action.disabledOpacity),
+  backgroundColor: 'var(--mui-data-grid-overlay-bg)',
}));

// Material UI adapter
const GridRootStyles = materialStyled('div', { ... })(({ theme }) => ({
  '--mui-data-grid-overlay-bg': theme.vars ?
    `rgba(${theme.vars.palette.background.defaultChannel} / ${theme.vars.palette.action.disabledOpacity})`
    : alpha(theme.palette.background.default, theme.palette.action.disabledOpacity),
}))

// Joy UI adapter
const GridRootStyles = joyStyled('div', { ... })(({ theme }) => ({
  '--mui-data-grid-overlay-bg': theme.vars.palette.background.surface, // or other token
}))

For theme.typography.* usage, we can set the specific typography system for the DataGrid:

const GridEditInputCellRoot = styled(InputBase, {
  name: 'MuiDataGrid',
  slot: 'EditInputCell',
  overridesResolver: (props, styles) => styles.editInputCell,
})(({ theme }) => ({
-  ...theme.typography.body2,
+  ...theme.typography.datagrid?.small, // naming can be different.
  padding: '1px 0',
  '& input': {
    padding: '0 16px',
    height: '100%',
  },
}));

[michaldudak]

As an alternative to 1., assuming that Grid subcomponents work with themes and they have configurable slots, there could be a theme provider setting the default values of slots props:

function MaterialUIThemeProvider({children}) {
  const materialUiTheme = createTheme({
    components: {
      GridPanel: {
        defaultProps: {
          slots: {
            paper: MaterialPaper
            ...
          }
        }
      }
    }
  });

  return <ThemeProvider theme={materialUiTheme}>
    {children}
  </ThemeProvider>
}

[siriwatknp]

Yep, both should be supported.

The components or slots prop on the <DataGrid> is for the adapter to switch between design libraries (Material UI, Joy UI).

The defaultProps.slots is for the developers to customize the slots of the design library (not the DataGrid), take GridPagination as an example:

// DataGrid + Material UI
import { components } from '@mui/x-data-grid/material';

<ThemeProvider theme={createTheme({
  components: {
    GridPagination: {
      defaultProps: {
        slots: {
          ...
        }
      }
    }
  }
})}>
  <DataGrid components={components} />
</ThemeProvider>

Similar to Joy UI:

// DataGrid + Joy UI
import { components } from '@mui/x-data-grid/joy';

<CssVarsProvider theme={extendTheme({
  components: {
    GridPagination: {
      defaultProps: {
        slots: {
          ...
        }
      }
    }
  }
})}>
  <DataGrid components={components} />
</CssVarsProvider>

[cherniavskii]

@siriwatknp I think it will be possible to switch between design libraries on the theme level as well:

// DataGrid + Material UI
import type {} from '@mui/x-data-grid/themeAugmentation';
import { components } from '@mui/x-data-grid/material';

<ThemeProvider theme={createTheme({
  components: {
    MuiDataGrid: {
      defaultProps: { slots: components }
    }
  }
})}>
  <DataGrid />
</ThemeProvider>

// DataGrid + Joy UI
import type {} from '@mui/x-data-grid/themeAugmentation';
import { components } from '@mui/x-data-grid/joy';

<CssVarsProvider theme={extendTheme({
  components: {
    MuiDataGrid: {
      defaultProps: { slots: components }
    }
  }
})}>
  <DataGrid />
</CssVarsProvider>

[siriwatknp]

Then DataGrid does not need to use rootProps.components, right? It can read the default component from the theme.

Take GridHeader as an example:

import * as React from 'react';
- import { useGridRootProps } from '../hooks/utils/useGridRootProps';
+ import { useTheme } from '@mui/system';

export const GridHeader = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
  function GridHeader(props, ref) {
-    const rootProps = useGridRootProps();
+    const theme = useTheme();
+    const { slots, slotProps } = theme.components.MuiDataGrid.defaultProps;
    return (
      <div ref={ref} {...props}>
-        <rootProps.components.PreferencesPanel {...rootProps.componentsProps?.preferencesPanel} />
-          {rootProps.components.Toolbar && (
-        <rootProps.components.Toolbar {...rootProps.componentsProps?.toolbar} />
+        <slots.PreferencesPanel {...slotProps?.preferencesPanel} />
+          {slots.Toolbar && (
+            <slots.Toolbar {...slotProps?.toolbar} />
        )}
      </div>
    );
  },
);

[cherniavskii]

Then DataGrid does not need to use rootProps.components, right?

I think both defaultProps on the theme and rootProps.components are useful.
Consider a situation where you have an app with a custom theme and a DataGrid component being used in multiple places. You can set components on the theme globally for all grids, but you can also use rootProps.components to change some slots on one specific DataGrid instance without using nested themes.
Does it make sense?

[siriwatknp]

Got it! 👍

[cherniavskii]

import { components as materialDataGridcomponents } from '@mui/x-data-grid-material';
import { components as joyDataGridcomponents } from '@mui/x-data-grid-joy';

This would work, but another option would be to keep adapters in the data grid packages and use nested imports:

// Community
import { components as materialDataGridcomponents } from '@mui/x-data-grid/material';
import { components as joyDataGridcomponents } from '@mui/x-data-grid/joy';

// Pro
import { components as materialDataGridcomponents } from '@mui/x-data-grid-pro/material';
import { components as joyDataGridcomponents } from '@mui/x-data-grid-pro/joy';

// Premium
import { components as materialDataGridcomponents } from '@mui/x-data-grid-premium/material';
import { components as joyDataGridcomponents } from '@mui/x-data-grid-premium/joy';

The @mui/material and @mui/joy will be peer dependencies, similar to date libraries in @mui/x-date-pickers:
https://mui.com/x/react-date-pickers/getting-started/#setup

Pros:

• Allows to keep Pro- and Premium-only slots in -pro and -premium packages and license those components under commercial license instead of MIT
• ?

Cons:

• Larger package install size (no impact on the bundle thought)
• ?

What do you think?

[siriwatknp]

@oliviertassinari If I want to use DataGrid with Joy UI, by doing this, do I have to install Material UI?

// If I don't install Material UI, the import below will throw error, right?
import { DataGrid as DataGridMd, DataGridUnstyled } from '@mui/x-data-grid-pro';

import { components } from '@mui/x-data-grid-pro/joy';

<DataGridUnstyled components={components} />

[cherniavskii]

Does it mean that DataGrid would be unstyled in these examples?

I was thinking about using Material UI by default in v6.

[cherniavskii]

@oliviertassinari If I want to use DataGrid with Joy UI, by doing this, do I have to install Material UI?

// If I don't install Material UI, the import below will throw error, right?
import { DataGrid as DataGridMd, DataGridUnstyled } from '@mui/x-data-grid-pro';

import { components } from '@mui/x-data-grid-pro/joy';

<DataGridUnstyled components={components} />

Yes, but you don't need to import DataGrid as DataGridMd if you're using DataGridUnstyled + Joy components, right?
@mui/material and @mui/joy will be peer dependencies, so as long as you don't import code that refers to those packages, it should not throw if those packages are missing.

[oliviertassinari]

If I want to use DataGrid with Joy UI, by doing this, do I have to install Material UI?

@siriwatknp if Material UI isn't installed, it would work in production mode but throw in dev mode because tree shaking isn't applied in dev mode in the current toolings of the community, e.g. webpack. So, great point. My proposal doesn't work.

I would suggest we use a one level deep folder import instead, e.g.

-import { DataGridUnstyled } from '@mui/x-data-grid-pro'; 
+import DataGridUnstyled from '@mui/x-data-grid-pro/DataGridUnstyled'; 

[siriwatknp]

@cherniavskii @oliviertassinari I think I got all answers and looks like we won't have breaking changes to support Joy UI. To reduce the effort and allow the work to continually merge to next, I propose we start moving Material UI related to its own folder.

packages/x-data-grid/src

• /DataGridMaterial (renamed from /DataGrid)
  • /components (new folder)
    • /MaterialGridRootStyles.tsx
    • ...

and keep converting the Material UI usage to GridSlotsComponent.

If this looks okay to you, I will create an issue that lists all the components that need to be extracted and start from there.

[cherniavskii]

Meaning, developers can use sx prop for DataGrid components that are not slots:

// For DataGrid - Material UI
<GridRowCount sx={{ color: 'error.main' }} /> // ✅

// For DataGrid - Joy UI
<GridRowCount sx={{ color: 'danger.solidColor' }} /> // ✅e

Not sure I follow this one.
To use different values for sx prop, GridRowCount should be a slot, right?

[cherniavskii]

Move palette usage to CSS variables (the values will be defined in the GridRootStyles of each design adapter).

const GridOverlayRoot = styled('div', {
  name: 'MuiDataGrid',
  slot: 'Overlay',
  overridesResolver: (props, styles) => styles.overlay,
})(({ theme }) => ({
  ...,
-  backgroundColor: alpha(theme.palette.background.default, theme.palette.action.disabledOpacity),
+  backgroundColor: 'var(--mui-data-grid-overlay-bg)',
}));

Nice, this looks great!

[cherniavskii]

For theme.typography.* usage, we can set the specific typography system for the DataGrid:

const GridEditInputCellRoot = styled(InputBase, {
  name: 'MuiDataGrid',
  slot: 'EditInputCell',
  overridesResolver: (props, styles) => styles.editInputCell,
})(({ theme }) => ({
-  ...theme.typography.body2,
+  ...theme.typography.datagrid?.small, // naming can be different.
  padding: '1px 0',
  '& input': {
    padding: '0 16px',
    height: '100%',
  },
}));

Does it mean that data grid has to export it's own theme?

[oliviertassinari]

I feel that #6811 (comment) solution would be a better fit in this context.

[cherniavskii]

@oliviertassinari Would we have to create a separate variable for each property? Here's what the grid uses

• theme.typography.body2 (fontFamily, fontSize, fontWeight, letterSpacing, lineHeight, scrollMarginTop)
• theme.typography.fontWeightMedium
• theme.typography.caption

[oliviertassinari]

@cherniavskii Yeah, IMHO it's a no-go. It doesn't make sense to extend the general design system tokens for one component. I think that it should be grouped, like under a theme.components.MuiDataGrid.

[oliviertassinari]

This should be safe to switch to @mui/utils and mark it as a dependency of DataGrid.

If we follow https://www.notion.so/mui-org/Weekly-meeting-2022-10-18-0566064ded784ef786b163b1c8dff280#318f195cd796489bb3448cb9772cc1c4. I think that it's also an opportunity to use @mui/base where it's more relevant (keep the use of @mui/utils as low as possible).

[cherniavskii]

Interesting!
Should we add @mui/base to the data grid's dependencies then?
Or peerDependencies, like we currently do with @mui/material to avoid dependency duplication?

[oliviertassinari]

I think that @mui/lab is meant to be the reference to copy. We started by coping it in the beginning https://github.com/mui/mui-x/blame/1ec87da54a79a93d623e95545a90dc1e9441a789/packages/grid/package.json.

@mui/utils/@mui/base have no singletons dependencies, so a direct dependency is better to control when there are API changes, e.g. breaking changes on private @mui/utils's APIs. I'm a bit surprised that @mui/material is a peer dependency. There is no singleton. Maybe we were afraid of duplication. Now, peers can work if we are careful with only using APIs that are compatible with the version range.

The date picker & lab have @emotion/react and @emotion/styled as peer dependencies, the data grid doesn't, this looks like a bug if we subscribe to the idea that mui/material-ui#32623 as valid.

[cherniavskii]

I'm a bit surprised that @mui/material is a peer dependency. There is no singleton. Maybe we were afraid of duplication.

Yes, I think duplication is the main concern here. If @mui/material was a peer dependency, it's really easy to have 2 versions of the library in the bundle.

The date picker & lab have @emotion/react and @emotion/styled as peer dependencies, the data grid doesn't, this looks like a bug if we subscribe to the idea that mui/material-ui#32623 as valid.

Wow, I did not know about this transitive peer dependencies issue. Then indeed, @emotion/react and @emotion/styled should be optional peer dependencies of the data grid.
Although it feels a bit wrong to include peer dependencies of the peer dependency. But I guess we don't have much choice here 🤷🏻‍♂️

[cherniavskii]

One more problem to solve: How to get the theme inside of the DataGrid?
Currently, we import useTheme from @mui/material:

mui-x/packages/grid/x-data-grid-pro/src/hooks/features/columnResize/useGridColumnResize.tsx

Line 141 in b7e10e7

const theme = useTheme();

It won't be possible once we decouple the data grid from the @mui/material package...

[oliviertassinari]

Since it's used for RTL, I think that you could import it from @mui/system and assume that if the theme is undefined, then the value is ltr.

[cherniavskii]

Could you share more details on how this would work?
If I use a theme from @mui/material or @mui/joy with the direction set to RTL, would useTheme from @mui/system allow me to get the proper direction value used in the theme?

[oliviertassinari]

The same theme context is used today.

However, with @mnajdova @siriwatknp we saw many opportunities to have a different theme context. It would solve mui/material-ui#25852, the progressive adoption of Joy UI from Material UI: https://mui.com/joy-ui/guides/using-joy-ui-and-material-ui-together/ is not welcoming (I had a friend who gave up using Joy UI because of it). I have tried to search for an issue on https://github.com/emotion-js/emotion about it but I couldn't.
Once/if this happens, I think that the solution is for the data grid, to use the data grid root props, with a isRtl prop on the unstyled version of the grid.

[cherniavskii]

Got it, thanks for the explanation!