[Joy] Add Sheet doc (#32820)

Co-authored-by: danilo leal <67129314+danilo-leal@users.noreply.github.com>
Co-authored-by: Siriwat K <siriwatkunaporn@gmail.com>

docs/data/joy/components/sheet/SheetUsage.js

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import JoyUsageDemo from 'docs/src/modules/components/JoyUsageDemo';
+import Sheet from '@mui/joy/Sheet';
+
+export default function SheetUsage() {
+  return (
+    <JoyUsageDemo
+      componentName="Sheet"
+      data={[
+        {
+          propName: 'variant',
+          knob: 'select',
+          defaultValue: 'plain',
+          options: ['plain', 'outlined', 'soft', 'solid'],
+        },
+        {
+          propName: 'color',
+          knob: 'color',
+          defaultValue: 'neutral',
+          options: ['neutral', 'primary', 'danger', 'info', 'success', 'warning'],
+        },
+      ]}
+      renderDemo={(props) => (
+        <Sheet
+          {...props}
+          sx={{
+            width: 250,
+            height: 200,
+            m: 1,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+          }}
+        >
+          Sheet
+        </Sheet>
+      )}
+    />
+  );
+}

docs/data/joy/components/sheet/SimpleSheet.js

@@ -0,0 +1,10 @@
+import Sheet from '@mui/joy/Sheet';
+import * as React from 'react';
+
+export default function SimpleSheet() {
+  return (
+    <Sheet variant="outlined" color="neutral" sx={{ p: 4 }}>
+      Hello world!
+    </Sheet>
+  );
+}

docs/data/joy/components/sheet/SimpleSheet.tsx

@@ -0,0 +1,10 @@
+import Sheet from '@mui/joy/Sheet';
+import * as React from 'react';
+
+export default function SimpleSheet() {
+  return (
+    <Sheet variant="outlined" color="neutral" sx={{ p: 4 }}>
+      Hello world!
+    </Sheet>
+  );
+}

docs/data/joy/components/sheet/SimpleSheet.tsx.preview

@@ -0,0 +1,3 @@
+<Sheet variant="outlined" color="neutral" sx={{ p: 4 }}>
+  Hello world!
+</Sheet>

docs/data/joy/components/sheet/sheet.md

@@ -0,0 +1,35 @@
+---
+product: joy-ui
+title: React Sheet component
+---
+
+# Sheet
+
+<p class="description">Sheet is a useful surface component that implements the global variant feature.</p>
+
+## Introduction
+
+The `Sheet` container is a generic container.
+It's a sibling to the `Box` component with the difference being that it supports Joy UI's global variants out of the box.
+
+{{"demo": "SheetUsage.js", "hideToolbar": true, "bg": true}}
+
+{{"component": "modules/components/ComponentLinkHeader.js"}}
+
+## Component
+
+After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements:
+
+```jsx
+import Sheet from '@mui/joy/Sheet';
+
+export default function MyApp() {
+  return <Sheet>Holy sheet!</Sheet>;
+}
+```
+
+### Basic usage
+
+The `Sheet` component, in addition to the variants, also has access to the `color` prop, allowing you to use every palette of the theme.
+
+{{"demo": "SimpleSheet.js"}}

docs/data/joy/pages.ts

@@ -48,7 +48,7 @@ const pages = [
       {
         pathname: '/joy-ui/components/surfaces',
         subheader: 'surfaces',
-        children: [{ pathname: '/joy-ui/react-card' }],
+        children: [{ pathname: '/joy-ui/react-card' }, { pathname: '/joy-ui/react-sheet' }],
       },
       {
         pathname: '/joy-ui/components/navigation',

docs/pages/experiments/joy/sheet.tsx

@@ -1,4 +1,5 @@
 import Moon from '@mui/icons-material/DarkMode';
+import Info from '@mui/icons-material/InfoOutlined';
 import Sun from '@mui/icons-material/LightMode';
 import Box from '@mui/joy/Box';
 import Button from '@mui/joy/Button';
@@ -7,7 +8,6 @@ import { CssVarsProvider, useColorScheme } from '@mui/joy/styles';
 import Typography from '@mui/joy/Typography';
 import { GlobalStyles } from '@mui/system';
 import * as React from 'react';
-import Info from '@mui/icons-material/InfoOutlined';
 
 const ColorSchemePicker = () => {
   const { mode, setMode } = useColorScheme();
@@ -40,7 +40,6 @@ export default function JoySheet() {
   const SheetProps = {
     variant: ['plain', 'outlined', 'soft', 'solid'],
     color: ['primary', 'neutral', 'danger', 'info', 'success', 'warning'],
-    elevation: ['xs', 'sm', 'md', 'lg', 'xl'],
   } as const;
 
   return (
@@ -52,10 +51,7 @@ export default function JoySheet() {
         <Box sx={{ px: 3, pb: 4 }}>
           <ColorSchemePicker />
         </Box>
-        <Sheet
-          elevation="sm"
-          sx={{ p: 2, display: 'flex', gap: 2, borderRadius: 'sm', alignItems: 'center' }}
-        >
+        <Sheet sx={{ p: 2, display: 'flex', gap: 2, borderRadius: 'sm', alignItems: 'center' }}>
           <Sheet variant="soft" color="primary" sx={{ p: 1, borderRadius: 'xs' }}>
             <Sheet
               variant="solid"

docs/pages/joy-ui/react-sheet.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import { demos, docs, demoComponents } from 'docs/data/joy/components/sheet/sheet.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} />;
+}

packages/mui-joy/src/Sheet/Sheet.spec.tsx

@@ -19,18 +19,8 @@ import * as React from 'react';
 <Sheet color="warning" />;
 <Sheet color="neutral" />;
 
-// `elevation`
-<Sheet elevation="xs" />;
-<Sheet elevation="sm" />;
-<Sheet elevation="md" />;
-<Sheet elevation="lg" />;
-<Sheet elevation="xl" />;
-
 // @ts-expect-error there is no variant `filled`
 <Sheet variant="filled" />;
 
 // @ts-expect-error there is no color `secondary`
 <Sheet color="secondary" />;
-
-// @ts-expect-error there is no elevation `xl2`
-<Sheet elevation="xl2" />;

packages/mui-joy/src/Sheet/Sheet.test.js

@@ -59,27 +59,4 @@ describe('<Sheet />', () => {
       });
     });
   });
-
-  describe('prop: elevation', () => {
-    it('undefined by default', () => {
-      const { getByTestId } = render(<Sheet data-testid="root">Hello World</Sheet>);
-
-      expect(getByTestId('root')).not.to.have.class(classes.elevationXs);
-      expect(getByTestId('root')).not.to.have.class(classes.elevationSm);
-      expect(getByTestId('root')).not.to.have.class(classes.elevationMd);
-      expect(getByTestId('root')).not.to.have.class(classes.elevationLg);
-      expect(getByTestId('root')).not.to.have.class(classes.elevationXl);
-    });
-    ['xs', 'sm', 'md', 'lg', 'xl'].forEach((elevation) => {
-      it(`should render ${elevation}`, () => {
-        const { getByTestId } = render(
-          <Sheet data-testid="root" elevation={elevation}>
-            Hello World
-          </Sheet>,
-        );
-
-        expect(getByTestId('root')).to.have.class(classes[`elevation${capitalize(elevation)}`]);
-      });
-    });
-  });
 });

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

@@ -5,20 +5,19 @@ import clsx from 'clsx';
 import PropTypes from 'prop-types';
 import * as React from 'react';
 import { useThemeProps } from '../styles';
-import { resolveSxValue } from '../styles/styleUtils';
 import styled from '../styles/styled';
+import { resolveSxValue } from '../styles/styleUtils';
 import { getSheetUtilityClass } from './sheetClasses';
 import { SheetProps, SheetTypeMap } from './SheetProps';
 
 const useUtilityClasses = (ownerState: SheetProps) => {
-  const { elevation, variant, color } = ownerState;
+  const { variant, color } = ownerState;
 
   const slots = {
     root: [
       'root',
       variant && `variant${capitalize(variant)}`,
       color && `color${capitalize(color)}`,
-      elevation && `elevation${capitalize(elevation)}`,
     ],
   };
 
@@ -43,7 +42,6 @@ const SheetRoot = styled('div', {
       // TODO: discuss the theme transition.
       // This value is copied from mui-material Sheet.
       transition: 'box-shadow 300ms cubic-bezier(0.4, 0, 0.2, 1) 0ms',
-      boxShadow: theme.vars.shadow[ownerState.elevation!],
       backgroundColor: theme.vars.palette.background.body,
       position: 'relative',
     },
@@ -57,20 +55,12 @@ const Sheet = React.forwardRef(function Sheet(inProps, ref) {
     name: 'JoySheet',
   });
 
-  const {
-    className,
-    color = 'neutral',
-    component = 'div',
-    variant = 'plain',
-    elevation,
-    ...other
-  } = props;
+  const { className, color = 'neutral', component = 'div', variant = 'plain', ...other } = props;
 
   const ownerState = {
     ...props,
     color,
     component,
-    elevation,
     variant,
   };
 
@@ -113,14 +103,6 @@ Sheet.propTypes /* remove-proptypes */ = {
    * Either a string to use a HTML element or a component.
    */
   component: PropTypes.elementType,
-  /**
-   * Shadow depth, corresponds to the `theme.shadow` scale.
-   * It accepts theme values between 'xs' and 'xl'.
-   */
-  elevation: PropTypes /* @typescript-to-proptypes-ignore */.oneOfType([
-    PropTypes.oneOf(['lg', 'md', 'sm', 'xl', 'xs']),
-    PropTypes.string,
-  ]),
   /**
    * The system prop that allows defining system overrides as well as additional CSS styles.
    */

packages/mui-joy/src/Sheet/SheetProps.ts

@@ -1,6 +1,6 @@
 import { OverridableStringUnion, OverrideProps } from '@mui/types';
 import * as React from 'react';
-import { ColorPaletteProp, VariantProp, SxProps } from '../styles/types';
+import { ColorPaletteProp, SxProps, VariantProp } from '../styles/types';
 
 export type SheetSlot = 'root';
 
@@ -18,11 +18,6 @@ export interface SheetTypeMap<P = {}, D extends React.ElementType = 'div'> {
      * @default 'neutral'
      */
     color?: OverridableStringUnion<ColorPaletteProp, SheetPropsColorOverrides>;
-    /**
-     * Shadow depth, corresponds to the `theme.shadow` scale.
-     * It accepts theme values between 'xs' and 'xl'.
-     */
-    elevation?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
     /**
      * The system prop that allows defining system overrides as well as additional CSS styles.
      */

packages/mui-joy/src/Sheet/sheetClasses.ts

@@ -23,16 +23,6 @@ export interface SheetClasses {
   variantSoft: string;
   /** Styles applied to the root element if `variant="solid"`. */
   variantSolid: string;
-  /** Styles applied to the root element if `elevation="xs"`. */
-  elevationXs: string;
-  /** Styles applied to the root element if `elevation="sm"`. */
-  elevationSm: string;
-  /** Styles applied to the root element if `elevation="md"`. */
-  elevationMd: string;
-  /** Styles applied to the root element if `elevation="lg"`. */
-  elevationLg: string;
-  /** Styles applied to the root element if `elevation="xl"`. */
-  elevationXl: string;
 }
 
 export type SheetClassKey = keyof SheetClasses;
@@ -53,11 +43,6 @@ const sheetClasses: SheetClasses = generateUtilityClasses('JoySheet', [
   'variantOutlined',
   'variantSoft',
   'variantSolid',
-  'elevationXs',
-  'elevationSm',
-  'elevationMd',
-  'elevationLg',
-  'elevationXl',
 ]);
 
 export default sheetClasses;