[Joy] Add zIndex to theme

packages/mui-joy/src/AutocompleteListbox/AutocompleteListbox.tsx

@@ -60,7 +60,7 @@ export const StyledAutocompleteListbox = styled(StyledList)<{
     ...(!variantStyle?.backgroundColor && {
       backgroundColor: theme.vars.palette.background.popup,
     }),
-    zIndex: 1200,
+    zIndex: theme.vars.zIndex.popup,
     overflow: 'auto',
     maxHeight: '40vh',
     position: 'relative', // to make sure that the listbox is positioned for grouped options to work.

packages/mui-joy/src/Badge/Badge.tsx

@@ -121,7 +121,7 @@ const BadgeBadge = styled('span', {
     minHeight: 'var(--Badge-minHeight)',
     minWidth: 'var(--Badge-minHeight)',
     borderRadius: 'var(--Badge-radius, var(--Badge-minHeight))',
-    zIndex: 1,
+    zIndex: theme.vars.zIndex.badge,
     backgroundColor: theme.vars.palette.background.surface,
     [ownerState.anchorOrigin!.vertical]: inset[ownerState.anchorOrigin!.vertical],
     [ownerState.anchorOrigin!.horizontal]: inset[ownerState.anchorOrigin!.horizontal],

packages/mui-joy/src/Menu/Menu.tsx

@@ -45,7 +45,7 @@ const MenuRoot = styled(StyledList, {
     ...scopedVariables,
     boxShadow: theme.shadow.md,
     overflow: 'auto',
-    zIndex: 1300, // the same value as Material UI Menu. TODO: revisit the appropriate value later.
+    zIndex: theme.vars.zIndex.popup,
     ...(!variantStyle?.backgroundColor && {
       backgroundColor: theme.vars.palette.background.popup,
     }),

packages/mui-joy/src/Modal/Modal.tsx

@@ -49,9 +49,9 @@ const ModalRoot = styled('div', {
   name: 'JoyModal',
   slot: 'Root',
   overridesResolver: (props, styles) => styles.root,
-})<{ ownerState: ModalOwnerState }>(({ ownerState }) => ({
+})<{ ownerState: ModalOwnerState }>(({ ownerState, theme }) => ({
   position: 'fixed',
-  zIndex: 9999,
+  zIndex: theme.vars.zIndex.modal,
   right: 0,
   bottom: 0,
   top: 0,

packages/mui-joy/src/Select/Select.tsx

@@ -242,7 +242,7 @@ const SelectListbox = styled(StyledList, {
     minWidth: 'max-content', // prevent options from shrinking if some of them is wider than the Select's root.
     outline: 0,
     boxShadow: theme.shadow.md,
-    zIndex: 1000,
+    zIndex: theme.vars.zIndex.popup,
     ...(!variantStyle?.backgroundColor && {
       backgroundColor: theme.vars.palette.background.popup,
     }),

packages/mui-joy/src/Table/Table.tsx

@@ -259,7 +259,7 @@ const TableRoot = styled('table', {
         top: 0,
       },
       [tableSelector.getHeaderCell()]: {
-        zIndex: 10,
+        zIndex: theme.vars.zIndex.table,
       },
       [tableSelector.getHeaderCellOfRow(2)]: {
         // support upto 2 rows for the sticky header

packages/mui-joy/src/Tooltip/Tooltip.tsx

@@ -68,7 +68,7 @@ const TooltipRoot = styled('div', {
       padding: theme.spacing(0.75, 1),
       fontSize: theme.vars.fontSize.md,
     }),
-    zIndex: 1500,
+    zIndex: theme.vars.zIndex.tooltip,
     pointerEvents: 'none',
     borderRadius: theme.vars.radius.xs,
     boxShadow: theme.shadow.sm,

packages/mui-joy/src/styles/CssVarsProvider.test.tsx

@@ -464,6 +464,35 @@ describe('[Joy] CssVarsProvider', () => {
       expect(screen.getByTestId('shadow-ring').textContent).to.equal('var(--joy-shadowRing)');
       expect(screen.getByTestId('shadow-channel').textContent).to.equal('var(--joy-shadowChannel)');
     });
+
+    it('zIndex', () => {
+      function Vars() {
+        const theme = useTheme();
+        return (
+          <div>
+            <div data-testid="zIndex-badge">{theme.vars.zIndex.badge}</div>
+            <div data-testid="zIndex-table">{theme.vars.zIndex.table}</div>
+            <div data-testid="zIndex-popup">{theme.vars.zIndex.popup}</div>
+            <div data-testid="zIndex-modal">{theme.vars.zIndex.modal}</div>
+            <div data-testid="zIndex-tooltip">{theme.vars.zIndex.tooltip}</div>
+          </div>
+        );
+      }
+
+      render(
+        <CssVarsProvider>
+          <Vars />
+        </CssVarsProvider>,
+      );
+
+      expect(screen.getByTestId('zIndex-badge').textContent).to.equal('var(--joy-zIndex-badge)');
+      expect(screen.getByTestId('zIndex-table').textContent).to.equal('var(--joy-zIndex-table)');
+      expect(screen.getByTestId('zIndex-popup').textContent).to.equal('var(--joy-zIndex-popup)');
+      expect(screen.getByTestId('zIndex-modal').textContent).to.equal('var(--joy-zIndex-modal)');
+      expect(screen.getByTestId('zIndex-tooltip').textContent).to.equal(
+        'var(--joy-zIndex-tooltip)',
+      );
+    });
   });
 
   describe('Color Inversion', () => {

packages/mui-joy/src/styles/defaultTheme.test.js

@@ -22,6 +22,7 @@ describe('defaultTheme', () => {
         'spacing',
         'radius',
         'shadow',
+        'zIndex',
         'typography',
         'variants',
         'colorInversion',

packages/mui-joy/src/styles/defaultTheme.ts

@@ -17,6 +17,7 @@ export const getThemeWithVars = (
     lineHeight,
     radius,
     shadow,
+    zIndex,
     palette: paletteInput,
     colorInversion: colorInversionInput,
     ...restTheme
@@ -40,6 +41,7 @@ export const getThemeWithVars = (
     lineHeight,
     radius,
     shadow,
+    zIndex,
     ...restTheme,
     colorSchemes: {
       ...colorSchemes,
@@ -60,6 +62,7 @@ export const getThemeWithVars = (
       radius,
       shadow,
       palette,
+      zIndex,
     },
     getColorSchemeSelector: () => '&',
   } as unknown as Theme;

packages/mui-joy/src/styles/extendTheme.test.js

@@ -21,6 +21,7 @@ describe('extendTheme', () => {
         'spacing',
         'radius',
         'shadow',
+        'zIndex',
         'typography',
         'colorInversionConfig',
         'variants',

packages/mui-joy/src/styles/extendTheme.ts

@@ -428,6 +428,13 @@ export default function extendTheme(themeOptions?: CssVarsThemeOptions): Theme {
         'shadowChannel',
       )} / 0.27), 21px 52.3px 74px -1.2px rgba(${getCssVar('shadowChannel')} / 0.29)`,
     },
+    zIndex: {
+      badge: 1,
+      table: 10,
+      popup: 1000,
+      modal: 1300,
+      tooltip: 1500,
+    },
     typography: {
       display1: {
         fontFamily: getCssVar('fontFamily-display'),

packages/mui-joy/src/styles/types/theme.ts

@@ -21,6 +21,7 @@ import {
   TypographySystem,
 } from './typography';
 import { Variants, ColorInversion, ColorInversionConfig } from './variants';
+import { ZIndex } from './zIndex';
 
 type Split<T, K extends keyof T = keyof T> = K extends string | number
   ? { [k in K]: Exclude<T[K], undefined> }
@@ -58,6 +59,7 @@ export interface ThemeScales {
   fontWeight: FontWeight;
   lineHeight: LineHeight;
   letterSpacing: LetterSpacing;
+  zIndex: ZIndex;
 }
 
 interface ColorSystemVars extends Omit<ColorSystem, 'palette'> {

packages/mui-joy/src/styles/types/zIndex.ts

@@ -0,0 +1,16 @@
+/**
+ * From lowest to highest value
+ */
+export interface ZIndex {
+  badge: number;
+  /**
+   * For sticky `th` cells
+   */
+  table: number;
+  /**
+   * Including `Menu`, `Autocomplete`, `Select`
+   */
+  popup: number;
+  modal: number;
+  tooltip: number;
+}

test/e2e-website/joy-docs.spec.ts

@@ -0,0 +1,29 @@
+import { test as base, expect } from '@playwright/test';
+import kebabCase from 'lodash/kebabCase';
+import { TestFixture } from './playwright.config';
+
+const test = base.extend<TestFixture>({});
+
+test.describe('Joy docs', () => {
+  test('should have correct link with hash in the TOC', async ({ page }) => {
+    await page.goto('/joy-ui/getting-started/installation/');
+
+    const anchors = page.locator('[aria-label="Page table of contents"] ul a');
+
+    const firstAnchor = anchors.first();
+    const textContent = await firstAnchor.textContent();
+
+    await expect(firstAnchor).toHaveAttribute(
+      'href',
+      `/joy-ui/getting-started/installation/#${kebabCase(textContent || '')}`,
+    );
+  });
+
+  test('should be able to see demos', async ({ page }) => {
+    await page.goto('/joy-ui/react-button/');
+
+    const headline = page.locator('main h1');
+
+    await expect(headline).toHaveText('Button');
+  });
+});