init project

docs/data/material/migration/upgrade-to-v7/upgrade-to-native-color.md

@@ -0,0 +1,117 @@
+# Upgrade to native color
+
+<p class="description">This guide explains how to upgrade from JavaScript color manipulation to native color.</p>
+
+Native color is an opt-in feature that replaces the JavaScript color manipulation with CSS `color-mix()` and relative colors.
+Check out the [native color documentation](/material-ui/customization/css-theme-variables/native-color/) for more details.
+
+## Prerequisites
+
+Update Material UI to the latest version (or at least v7.3.0).
+
+<!-- #npm-tag-reference -->
+
+<codeblock storageKey="package-manager">
+
+```bash npm
+npm install @mui/material@latest
+```
+
+```bash pnpm
+pnpm add @mui/material@latest
+```
+
+```bash yarn
+yarn add @mui/material@latest
+```
+
+</codeblock>
+
+## Enable native color
+
+Set the `cssVariables.nativeColor` option to `true` in the `createTheme()` function.
+
+```js
+const theme = createTheme({
+  cssVariables: { nativeColor: true },
+});
+```
+
+Once you've enabled native color, Material UI will start using CSS `color-mix()` and relative colors to manipulate colors.
+
+To check that it's working, open the browser's developer tools. On the Elements tab, click the Styles panel and search for "color-mix".
+You should see the Material UI color tokens appear as CSS variables.
+
+## Handling JavaScript color manipulation
+
+Your application might break if you're using the `alpha`, `lighten`, and `darken` functions from `@mui/*` to manipulate colors that have been updated to use native color.
+
+For example, manipulating the `contrastText` token will break the application:
+
+```js
+import { alpha } from '@mui/material/styles';
+
+const theme = createTheme({
+  cssVariables: { nativeColor: true },
+});
+
+// ❌ This will break because `alpha` does not support relative colors.
+console.log(alpha(theme.palette.primary.contrastText, 0.3));
+```
+
+To fix this, you can use the `theme.alpha()` adapter function to manipulate colors.
+
+```js
+const theme = createTheme({
+  cssVariables: { nativeColor: true },
+});
+
+// ✅ This will work because `theme.alpha` supports relative colors.
+console.log(theme.alpha(theme.palette.primary.contrastText, 0.3));
+```
+
+The same applies to the `lighten` and `darken` functions.
+Follow the codemod below to update multiple files at once.
+
+## Remove usage of channel tokens
+
+After enabling the native color, you **should not** rely on the `*Channel` tokens anymore because their values are not guaranteed to be channels (numbers separated by a white space).
+
+Instead, use the theme color functions to manipulate colors like this:
+
+```diff
+- `rgba(${theme.vars.palette.primary.mainChannel} / 0.3)`
++ `theme.alpha((theme.vars || theme).palette.primary.main, 0.3)`
+```
+
+## Codemod
+
+The codemod replaces the `alpha()`, `lighten()`, and `darken()` functions from `@mui/system/colorManipulator` or `@mui/material/styles` with theme color functions.
+
+```bash
+npx @mui/codemod@latest v7.0.0/theme-color-functions <path>
+```
+
+The following transformation example shows what the codemod does:
+
+```diff
+- import { alpha } from '@mui/system/colorManipulator';
+- // or import { alpha } from '@mui/material/styles';
+
+ styled('div')(({ theme }) => ({
+   width: '100%',
+   height: '100%',
+   '&.good': {
+-    backgroundColor: theme.vars
+-      ? `rgba(${theme.vars.palette.success.mainChannel} /  0.3)`
+-      : alpha(theme.palette.success.main, 0.3),
++    backgroundColor: theme.alpha((theme.vars || theme).palette.success.main, 0.3),
+   },
+   '&.bad': {
+-    backgroundColor: theme.vars
+-      ? `rgba(${theme.vars.palette.error.mainChannel} /  0.3)`
+-      : alpha(theme.palette.error.main, 0.3),
++    backgroundColor: theme.alpha((theme.vars || theme).palette.error.main, 0.3),
+   },
+ }));
+```

docs/data/material/migration/upgrade-to-v7/upgrade-to-v7.md

@@ -0,0 +1,571 @@
+# Upgrade to v7
+
+<p class="description">This guide explains how to upgrade from Material UI v6 to v7.</p>
+
+## Why you should upgrade to Material UI v7
+
+### Improved ESM support
+
+The package layout has been updated, and now unambiguously supports both valid ESM and CommonJS through the `exports` field in `package.json`.
+You can read more about package exports in the [Node.js documentation](https://nodejs.org/api/packages.html#packages_exports).
+
+This update fixes several issues with popular bundlers like Vite and webpack, and makes it possible to load MUI packages from ES modules under Node.js.
+
+### Quality-of-life improvements
+
+Material UI v7 features other quality-of-life improvements, including:
+
+- Standardization of the slot pattern across all components
+- CSS layers support via the `enableCssLayer` prop in `StyledEngineProvider` for client-side apps, and `AppRouterCacheProvider` for Next.js App Router apps
+- Removed deprecated APIs to reduce the API surface and make the docs easier to navigate
+
+If you're using any of these packages, you should also update their versions to `"7.0.0"`:
+
+- `@mui/icons-material`
+- `@mui/system`
+- `@mui/lab`
+- `@mui/material-nextjs`
+- `@mui/styled-engine`
+- `@mui/styled-engine-sc`
+- `@mui/utils`
+
+Note that MUI X packages _do not_ follow the same versioning strategy as Material UI.
+If you're using any of the following packages, they should remain unchanged during the upgrade process:
+
+- `@mui/x-data-grid`
+- `@mui/x-data-grid-pro`
+- `@mui/x-data-grid-premium`
+- `@mui/x-date-pickers`
+- `@mui/x-date-pickers-pro`
+- `@mui/x-charts`
+- `@mui/x-tree-view`
+- `@mui/x-tree-view-pro`
+
+## Minimum TypeScript version
+
+The minimum supported version of TypeScript has been increased from v4.7 to 4.9.
+
+:::info
+We align with [support window](https://github.com/DefinitelyTyped/DefinitelyTyped?tab=readme-ov-file#support-window) by [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) (published on npm under the `@types` namespace).
+
+We will not change the minimum supported version in a minor version of Material UI.
+However, we recommend not using a TypeScript version older than the lowest supported version by DefinitelyTyped.
+:::
+
+For `@types/react*` packages, make sure they are the same major version as the `react` you are using.
+Use the snippet below to update your project if needed (replace the `<version>` with the major version of `react` you are using):
+
+<codeblock storageKey="package-manager">
+
+```bash npm
+npm install @types/react@<version> @types/react-dom@<version>
+```
+
+```bash pnpm
+pnpm add @types/react@<version> @types/react-dom@<version>
+```
+
+```bash yarn
+yarn add @types/react@<version> @types/react-dom@<version>
+```
+
+</codeblock>
+
+:::warning
+Make sure that your application is still running without errors, and commit the changes before continuing to the next step.
+:::
+
+## React 18 and below
+
+If you are using React 18 or below, you need to set up a resolution of `react-is` package to the same version as the `react` you are using.
+
+For example, if you are using `react@18.3.1`, do the following steps:
+
+1. Install `react-is@18.3.1`.
+
+<codeblock storageKey="package-manager">
+
+```bash npm
+npm install react-is@18.3.1
+```
+
+```bash pnpm
+pnpm add react-is@18.3.1
+```
+
+```bash yarn
+yarn add react-is@18.3.1
+```
+
+</codeblock>
+
+2. Set the resolutions or overrides in the `package.json`.
+
+<codeblock storageKey="package-manager">
+
+```json npm
+{
+  …
+  "overrides": {
+    "react-is": "^18.3.1"
+  }
+}
+```
+
+```json pnpm
+{
+  …
+  "overrides": {
+    "react-is": "^18.3.1"
+  }
+}
+```
+
+```json yarn
+{
+  …
+  "resolutions": {
+    "react-is": "^18.3.1"
+  }
+}
+```
+
+</codeblock>
+
+### Why is this needed?
+
+Material UI v7 uses `react-is@19`, which changed how React elements are identified.
+
+If you're on React 18 or below, mismatched versions of `react-is` can cause runtime errors in prop type checks.
+Forcing `react-is` to match your React version prevents these errors.
+
+## Breaking changes
+
+Since v7 is a new major release, it contains some changes that affect the public API.
+The steps you need to take to migrate from Material UI v6 to v7 are described below.
+
+### Package layout updated
+
+The package layout has been updated to use the Node.js exports field. This brings several changes:
+
+Deep imports with more than one level are no longer working, at all (they were already considered private API). For example:
+
+```diff
+-import createTheme from '@mui/material/styles/createTheme';
++import { createTheme } from '@mui/material/styles';
+```
+
+This was never officially supported, but now it will be restricted by bundlers and runtimes.
+
+Modern bundles have also been removed, as the potential for a smaller bundle size is no longer significant.
+If you've configured aliases for these bundles, you must remove them now.
+
+```diff
+ {
+   resolve: {
+     alias: {
+-      '@mui/material': '@mui/material/modern',
+-      '@mui/styled-engine': '@mui/styled-engine/modern',
+-      '@mui/system': '@mui/system/modern',
+-      '@mui/base': '@mui/base/modern',
+-      '@mui/utils': '@mui/utils/modern',
+-      '@mui/lab': '@mui/lab/modern',
+     }
+   }
+ }
+```
+
+:::info
+Earlier versions of this guide mention the existence of a `mui-modern` conditional exports.
+This has since been removed.
+This is a non-breaking change, and your bundler will fall back to the ESM bundle.
+:::
+
+If you are using a Vite alias to force ESM imports for the icons package, you should remove it as it's no longer necessary:
+
+```diff
+ // vite.config.js
+   resolve: {
+     alias: [
+-      {
+-        find: /^@mui\/icons-material\/(.*)/,
+-        replacement: "@mui/icons-material/esm/$1",
+-      },
+     ],
+   },
+```
+
+If you are augmenting the theme and using declarations for nested imports, you should replace them with `@mui/material/styles`. You may also have to rename an interface as some are exported from `@mui/material/styles` under a different name:
+
+```diff
+-declare module '@mui/material/styles/createTypography' {
++declare module '@mui/material/styles' {
+-  interface TypographyOptions {
++  interface TypographyVariantsOptions {
+     // ...
+   }
+
+-  interface Typography {
++  interface TypographyVariants {
+     // ...
+   }
+ }
+```
+
+### Grid and Grid2 renamed
+
+The deprecated `Grid` component has been renamed to `GridLegacy`.
+The `Grid2` component has been moved to the `Grid` namespace.
+Depending on your project, you may follow one of the following approaches:
+
+1. **If you are using the deprecated grid and wish to upgrade,** run the following codemod:
+
+   <!-- #npm-tag-reference -->
+
+   ```bash
+   npx @mui/codemod v7.0.0/grid-props <path/to/folder>
+   ```
+
+   See the [Grid upgrade guide](/material-ui/migration/upgrade-to-grid-v2/) for more information.
+
+2. **If you are using the deprecated grid and wish to continue using it,** update the `Grid` references as follows:
+
+   ```diff
+    // imports
+   -import Grid, { gridClasses, GridProps } from '@mui/material/Grid';
+   +import Grid, { gridLegacyClasses, GridLegacyProps } from '@mui/material/GridLegacy';
+
+   -import { Grid } from '@mui/material';
+   +import { GridLegacy as Grid } from '@mui/material';
+
+    // theme
+    const theme = createTheme({
+      components: {
+   -    MuiGrid: {
+   +    MuiGridLegacy: {
+          // ...
+        },
+      },
+    });
+
+    // CSS classes
+   -.MuiGrid-root
+   +.MuiGridLegacy-root
+   ```
+
+3. **If you are using Grid2,** update the `Grid2` references as follows:
+
+   ```diff
+    // imports
+   -import Grid, { grid2Classes as gridClasses, Grid2Props as GridProps } from '@mui/material/Grid2';
+   +import Grid, { gridClasses, GridProps } from '@mui/material/Grid';
+
+   -import { Grid2 as Grid } from '@mui/material';
+   +import { Grid } from '@mui/material';
+
+    // theme
+    const theme = createTheme({
+      components: {
+   -    MuiGrid2: {
+   +    MuiGrid: {
+          // ...
+        },
+      },
+    });
+
+    // CSS classes
+   -.MuiGrid2-root
+   +.MuiGrid-root
+   ```
+
+### InputLabel size prop standardized
+
+The `size` prop for `InputLabel` now follows the standard naming convention used across other components like `Button` and `TextField`. `'normal'` has been replaced with `'medium'` for consistency.
+
+If you were using `size="normal"`, update it to `size="medium"`:
+
+```diff
+-<InputLabel size="normal">Label</InputLabel>
++<InputLabel size="medium">Label</InputLabel>
+```
+
+The default behavior remains unchanged, so no updates are needed unless you explicitly set `size="normal"`.
+
+Use this codemod to automatically update the `size` value:
+
+<!-- #npm-tag-reference -->
+
+```bash
+npx @mui/codemod v7.0.0/input-label-size-normal-medium <path/to/folder>
+```
+
+**Note:** Because the default size of `InputLabel` was changed from `normal` to `medium`, the class `MuiInputLabel‑sizeMedium` is no longer added. If you relied on this class for custom styling, use a different class.
+
+### SvgIcon's data-testid removed
+
+The default `data-testid` prop has been removed from the icons in `@mui/icons-material` in production bundles. This change ensures that the `data-testid` prop is only defined where needed, reducing the potential for naming clashes and removing unnecessary properties in production.
+
+### TablePaginationActions types import path changed
+
+The import path for the types has changed from `@mui/material/TablePagination/TablePaginationActions` to `@mui/material/TablePaginationActions`.
+
+```diff
+- import type { TablePaginationActionsProps } from '@mui/material/TablePagination/TablePaginationActions';
++ import type { TablePaginationActionsProps } from '@mui/material/TablePaginationActions';
+```
+
+### Theme behavior changes
+
+When CSS theme variables is enabled with built-in light and dark color schemes, the theme no longer changes between modes.
+The snippet below demonstrates this behavior when users toggle the dark mode, the `mode` state from `useColorScheme` changes, but the theme object no longer changes:
+
+```js
+import {
+  ThemeProvider,
+  createTheme,
+  useTheme,
+  useColorScheme,
+} from '@mui/material/styles';
+
+const theme = createTheme({
+  cssVariables: {
+    colorSchemeSelector: 'class',
+  },
+  colorSchemes: {
+    light: true,
+    dark: true,
+  },
+});
+console.log(theme.palette.mode); // 'light' is the default mode
+
+function ColorModeToggle() {
+  const { setMode, mode } = useColorScheme();
+  const theme = useTheme();
+
+  React.useEffect(() => {
+    console.log(mode); // logged 'light' at first render, and 'dark' after the button click
+  }, [mode]);
+
+  React.useEffect(() => {
+    // logged 'light' at first render, no log after the button click
+    console.log(theme.palette.mode);
+  }, [theme]);
+
+  return <button onClick={() => setMode('dark')}>Toggle dark mode</button>;
+}
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <ColorModeToggle />
+    </ThemeProvider>
+  );
+}
+```
+
+This default behavior was made to improve performance by avoiding unnecessary re-renders when the mode changes.
+
+It's recommended to use the `theme.vars.*` as values in your styles to refer to the CSS variables directly:
+
+```js
+const Custom = styled('div')(({ theme }) => ({
+  color: theme.vars.palette.text.primary,
+  background: theme.vars.palette.primary.main,
+}));
+```
+
+If you need to do runtime calculations, we recommend using CSS instead of JavaScript whenever possible.
+For example, adjusting the alpha channel of a color can be done using the [`color-mix` function](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix):
+
+```js
+const Custom = styled('div')(({ theme }) => ({
+  color: `color-mix(in srgb, ${theme.vars.palette.text.primary}, transparent 50%)`,
+}));
+```
+
+However, if CSS approach is not possible, you can access the value directly from the `theme.colorSchemes` object, then apply both light and dark styles:
+
+```js
+const Custom = styled('div')(({ theme }) => ({
+  color: alpha(theme.colorSchemes.light.palette.text.primary, 0.5),
+  ...theme.applyStyles('dark', {
+    color: alpha(theme.colorSchemes.dark.palette.text.primary, 0.5),
+  }),
+}));
+```
+
+If any of the methods above do not suit your project, you can opt out from this behavior by passing the `forceThemeRerender` prop to the ThemeProvider component:
+
+```js
+<ThemeProvider forceThemeRerender />
+```
+
+### Deprecated APIs removed
+
+APIs that were deprecated in v5 have been removed in v7.
+
+#### createMuiTheme function
+
+The deprecated `createMuiTheme` function has been removed.
+Use `createTheme` instead.
+
+```diff
+-import { createMuiTheme } from '@mui/material/styles';
++import { createTheme } from '@mui/material/styles';
+```
+
+#### Dialog's onBackdropClick prop
+
+The deprecated `onBackdropClick` prop has been removed from the `Dialog` component.
+Please use the [`onClose`](/material-ui/api/dialog/#dialog-prop-onClose) callback instead, which receives the event and the reason for the dialog closing.
+Here's an example of how to use it:
+
+```jsx
+function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  const handleClose = (event, reason) => {
+    if (reason === 'backdropClick') {
+      // Handle the backdrop click
+    }
+    setOpen(false);
+  };
+
+  return (
+    <Dialog open={open} onClose={handleClose}>
+      {/* Dialog content */}
+    </Dialog>
+  );
+}
+```
+
+#### experimentalStyled function
+
+The deprecated `experimentalStyled` function has been removed.
+Use `styled` instead.
+
+```diff
+-import { experimentalStyled as styled } from '@mui/material/styles';
++import { styled } from '@mui/material/styles';
+```
+
+#### Hidden and PigmentHidden components
+
+The deprecated `Hidden` and `PigmentHidden` components have been removed.
+
+Use the `sx` prop to replace `implementation="css"`:
+
+```diff
+-<Hidden implementation="css" xlUp><Paper /></Hidden>
++<Paper sx={{ display: { xl: 'none', xs: 'block' } }} />
+```
+
+```diff
+-<Hidden implementation="css" mdDown><Paper /></Hidden>
++<Paper sx={{ display: { xs: 'none', md: 'block' } }} />
+```
+
+Use the `useMediaQuery` hook to replace `implementation="js"`:
+
+```diff
+-<Hidden implementation="js" xlUp><Paper /></Hidden>
++const hidden = useMediaQuery(theme => theme.breakpoints.up('xl'));
++return hidden ? null : <Paper />;
+```
+
+#### Modal's onBackdropClick prop
+
+The deprecated `onBackdropClick` prop has been removed from the `Modal` component.
+Please use the [`onClose`](/material-ui/api/modal/#modal-prop-onClose) callback instead, which receives the event and the reason for the modal closing.
+Here's an example of how to use it:
+
+```jsx
+function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  const handleClose = (event, reason) => {
+    if (reason === 'backdropClick') {
+      // Handle the backdrop click
+    }
+    setOpen(false);
+  };
+
+  return (
+    <Modal open={open} onClose={handleClose}>
+      {/* Modal content */}
+    </Modal>
+  );
+}
+```
+
+#### Rating's MuiRating-readOnly CSS class
+
+The deprecated `MuiRating-readOnly` class was removed in favor of `Mui-readOnly` global class.
+
+```diff
+-.MuiRating-readOnly
++.Mui-readOnly
+```
+
+#### StepButtonIcon type
+
+The deprecated `StepButtonIcon` type has been removed. Use `StepButtonProps['icon']` instead.
+
+```diff
+-import { StepButtonIcon } from '@mui/material/StepButton';
++import { StepButtonProps } from '@mui/material/StepButton';
+
+-StepButtonIcon
++StepButtonProps['icon']
+```
+
+#### StyledEngineProvider import path
+
+Importing `StyledEngineProvider` from `'@mui/material'` was deprecated and now has been removed.
+Import it from `'@mui/material/styles'` instead:
+
+```diff
+-import { StyledEngineProvider } from '@mui/material';
++import { StyledEngineProvider } from '@mui/material/styles';
+```
+
+#### Lab components moved to the main package
+
+The following `@mui/lab` components and hook have been moved to `@mui/material`:
+
+- Alert
+- AlertTitle
+- Autocomplete
+- AvatarGroup
+- Pagination
+- PaginationItem
+- Rating
+- Skeleton
+- SpeedDial
+- SpeedDialAction
+- SpeedDialIcon
+- ToggleButton
+- ToggleButtonGroup
+- usePagination
+
+To keep using these components and hook, import them from `@mui/material` instead of `@mui/lab`.
+
+```diff
+-import Alert from '@mui/lab/Alert';
++import Alert from '@mui/material/Alert';
+
+-import { Alert } from '@mui/lab';
++import { Alert } from '@mui/material';
+```
+
+Use this codemod to automatically update the imports:
+
+<!-- #npm-tag-reference -->
+
+```bash
+npx @mui/codemod v7.0.0/lab-removed-components <path/to/folder>
+```
+
+:::warning
+The codemod doesn't cover type imports associated with the components.
+:::