From c842de662c5560045bcea79b79c2c2b501b5f1fd Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Fri, 18 Nov 2022 19:18:31 +0000 Subject: [PATCH] [docs] Iterating on recent Joy UI Component page updates (#35162) Co-authored-by: Olivier Tassinari --- docs/data/joy/components/alert/AlertColors.js | 25 ++---- .../data/joy/components/alert/AlertColors.tsx | 25 ++---- docs/data/joy/components/alert/alert.md | 61 ++++++--------- .../components/aspect-ratio/aspect-ratio.md | 77 ++++++------------- .../joy/components/avatar/AvatarVariants.js | 2 +- .../joy/components/avatar/AvatarVariants.tsx | 2 +- .../avatar/AvatarVariants.tsx.preview | 2 +- .../data/joy/components/avatar/BasicAvatar.js | 6 ++ .../components/avatar/BasicAvatar.tsx.preview | 1 + .../joy/components/avatar/BasicAvatars.js | 13 ++++ .../joy/components/avatar/BasicAvatars.tsx | 13 ++++ .../avatar/BasicAvatars.tsx.preview | 3 + docs/data/joy/components/avatar/avatar.md | 67 ++++++++-------- 13 files changed, 131 insertions(+), 166 deletions(-) create mode 100644 docs/data/joy/components/avatar/BasicAvatar.js create mode 100644 docs/data/joy/components/avatar/BasicAvatar.tsx.preview create mode 100644 docs/data/joy/components/avatar/BasicAvatars.js create mode 100644 docs/data/joy/components/avatar/BasicAvatars.tsx create mode 100644 docs/data/joy/components/avatar/BasicAvatars.tsx.preview diff --git a/docs/data/joy/components/alert/AlertColors.js b/docs/data/joy/components/alert/AlertColors.js index 42d37cc6db85a7..1425c169eab282 100644 --- a/docs/data/joy/components/alert/AlertColors.js +++ b/docs/data/joy/components/alert/AlertColors.js @@ -1,11 +1,12 @@ +import * as React from 'react'; import Alert from '@mui/joy/Alert'; +import Stack from '@mui/joy/Stack'; import Box from '@mui/joy/Box'; import Radio from '@mui/joy/Radio'; import RadioGroup from '@mui/joy/RadioGroup'; import Sheet from '@mui/joy/Sheet'; import Typography from '@mui/joy/Typography'; -import * as React from 'react'; export default function AlertColors() { const [variant, setVariant] = React.useState('solid'); @@ -14,16 +15,11 @@ export default function AlertColors() { sx={{ display: 'flex', alignItems: 'center', - gap: 3, + justifyContent: 'center', + width: '100%', }} > - + Primary @@ -42,15 +38,8 @@ export default function AlertColors() { Warning - - + + ('solid'); @@ -14,16 +15,11 @@ export default function AlertColors() { sx={{ display: 'flex', alignItems: 'center', - gap: 3, + justifyContent: 'center', + width: '100%', }} > - + Primary @@ -42,15 +38,8 @@ export default function AlertColors() { Warning - - + + ; -} ``` -## Basics - The Alert component wraps around its content, and stretches to fill its enclosing container, as shown below: {{"demo": "AlertBasic.js"}} -## Anatomy - -The Alert component is composed of a single root `
` element with its `role` set to `alert`: - -```html - -``` - -### Overriding the root slot +## Customization -Use the `component` prop to override the root slot with a custom element. -For example, the following code snippet replaces the default `
` with a ``: +### Variants -```jsx -Alert content +The Alert component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. -// renders as: - - Alert content - -``` +{{"demo": "AlertVariants.js"}} -## Customization +:::success +To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +Note that you lose the global variants when you add custom variants. +::: -### Variants +### Sizes -The Alert component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `soft` (default), `solid`, `outlined`, and `plain`. +The Alert component comes in three sizes: `sm`, `md` (default), and `lg`: -{{"demo": "AlertVariants.js"}} +{{"demo": "AlertSizes.js"}} ### Colors @@ -79,12 +58,6 @@ The demo below shows how the values for the `color` prop are affected by the glo {{"demo": "AlertColors.js"}} -### Sizes - -The Alert component comes with three sizes out of the box: `sm`, `md` (the default), and `lg`: - -{{"demo": "AlertSizes.js"}} - ### Decorators Use the `startDecorator` and `endDecorator` props to append actions and icons to either side of the Alert: @@ -111,3 +84,13 @@ Here are some factors to consider to ensure that your Alert is accessible: - Alerts that occur too frequently can [inhibit the usability](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-postponed.html) of your app. - Dynamically rendered alerts are announced by screen readers; alerts that are already present on the page when it loads are _not_ announced. - Color does not add meaning to the UI for users who require assistive technology. You must ensure that any information conveyed through color is also denoted in other ways, such as within the text of the alert itself, or with additional hidden text that's read by screen readers. + +## Anatomy + +The Alert component is composed of a single root `
` element with its `role` set to `alert`: + +```html + +``` diff --git a/docs/data/joy/components/aspect-ratio/aspect-ratio.md b/docs/data/joy/components/aspect-ratio/aspect-ratio.md index bb6b4d694d8dbc..f92f7056a29639 100644 --- a/docs/data/joy/components/aspect-ratio/aspect-ratio.md +++ b/docs/data/joy/components/aspect-ratio/aspect-ratio.md @@ -18,76 +18,31 @@ As of Q4 2022, compatibility is at 90%. Source: [Can I use…](https://caniuse.com/?search=aspect-ratio) ::: -## Usage - -After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements: +## Basics ```jsx import AspectRatio from '@mui/joy/AspectRatio'; - -export default function MyApp() { - return ; -} ``` -## Basics - The Aspect Ratio component wraps around the content that it resizes. The element to be resized must be the first direct child. The default ratio is `16/9`. {{"demo": "BasicRatio.js"}} -## Anatomy - -The Aspect Ratio component is composed of a root `
` with a content `
` nested inside; the child component is given a `data-first-child` attribute for styling purposes: - -```html -
-
- - This is how an Aspect Ratio component renders in the DOM. - -
-
-``` - -### Overriding the root slot - -Use the `component` prop to override the root slot with a custom element. -For example, the following code snippet replaces the default `
` with a `
`: - -```jsx - -``` - -### Overriding interior slots - -Use the `components` prop to override any interior slots in addition to the root: - - - -:::warning -If the root element is customized with both the `component` and `components` props, then `component` will take precedence. -::: - -Use the `componentsProps` prop to pass custom props to internal slots. -The following code snippet applies a CSS class called `my-content` to the content slot: - - - -:::warning -Note that `componentsProps` slot names are written in lowercase (root) while `components` slot names are capitalized (Root). -::: - ## Customization ### Variants -The Aspect Ratio component supports the four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. +The Aspect Ratio component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. {{"demo": "VariantsRatio.js"}} +:::success +To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +Note that you lose the global variants when you add custom variants. +::: + ### Ratio Use the `ratio` prop to change the aspect ratio, following the pattern `height/width`. @@ -120,13 +75,13 @@ This is useful when the Aspect Ratio component wraps dynamic-width content, as s {{"demo": "MinMaxRatio.js"}} -### Usage inside a flex row +## Usage inside a flex row When the Aspect Ratio component is a child of a flexbox `row` container, use `flex-basis` to set the ideal width of the content: {{"demo": "FlexRowRatio.js"}} -### Usage with Next.js Image component +## Usage with Next.js Image The Aspect Ratio component can be used with a [Next.js Image](https://nextjs.org/docs/basic-features/image-optimization) component as a child. The Image should always include the `layout="fill"` property—otherwise it requires `height` and `width` values, which would defeat the purpose of the Aspect Ratio component. @@ -161,3 +116,17 @@ In designs like this, make sure to assign a `minWidth` value to prevent the Aspe This is a simple illustration of how to use Aspect Ratio with list components: {{"demo": "ListStackRatio.js"}} + +## Anatomy + +The Aspect Ratio component is composed of a root `
` with a content `
` nested inside; the child component is given a `data-first-child` attribute for styling purposes: + +```html +
+
+ + + +
+
+``` diff --git a/docs/data/joy/components/avatar/AvatarVariants.js b/docs/data/joy/components/avatar/AvatarVariants.js index 1bc80bcf652dc7..6193bafcb947c9 100644 --- a/docs/data/joy/components/avatar/AvatarVariants.js +++ b/docs/data/joy/components/avatar/AvatarVariants.js @@ -5,8 +5,8 @@ import Box from '@mui/joy/Box'; export default function AvatarVariants() { return ( - + diff --git a/docs/data/joy/components/avatar/AvatarVariants.tsx b/docs/data/joy/components/avatar/AvatarVariants.tsx index 1bc80bcf652dc7..6193bafcb947c9 100644 --- a/docs/data/joy/components/avatar/AvatarVariants.tsx +++ b/docs/data/joy/components/avatar/AvatarVariants.tsx @@ -5,8 +5,8 @@ import Box from '@mui/joy/Box'; export default function AvatarVariants() { return ( - + diff --git a/docs/data/joy/components/avatar/AvatarVariants.tsx.preview b/docs/data/joy/components/avatar/AvatarVariants.tsx.preview index fa5e66d9f5ae97..0570a58cf0989f 100644 --- a/docs/data/joy/components/avatar/AvatarVariants.tsx.preview +++ b/docs/data/joy/components/avatar/AvatarVariants.tsx.preview @@ -1,4 +1,4 @@ - + \ No newline at end of file diff --git a/docs/data/joy/components/avatar/BasicAvatar.js b/docs/data/joy/components/avatar/BasicAvatar.js new file mode 100644 index 00000000000000..e2ac407dfae025 --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatar.js @@ -0,0 +1,6 @@ +import * as React from 'react'; +import Avatar from '@mui/joy/Avatar'; + +export default function BasicAvatar() { + return ; +} diff --git a/docs/data/joy/components/avatar/BasicAvatar.tsx.preview b/docs/data/joy/components/avatar/BasicAvatar.tsx.preview new file mode 100644 index 00000000000000..23517495fdf8ab --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatar.tsx.preview @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/data/joy/components/avatar/BasicAvatars.js b/docs/data/joy/components/avatar/BasicAvatars.js new file mode 100644 index 00000000000000..92ce23634a12de --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatars.js @@ -0,0 +1,13 @@ +import * as React from 'react'; +import Avatar from '@mui/joy/Avatar'; +import Box from '@mui/joy/Box'; + +export default function BasicAvatars() { + return ( + + + JG + + + ); +} diff --git a/docs/data/joy/components/avatar/BasicAvatars.tsx b/docs/data/joy/components/avatar/BasicAvatars.tsx new file mode 100644 index 00000000000000..92ce23634a12de --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatars.tsx @@ -0,0 +1,13 @@ +import * as React from 'react'; +import Avatar from '@mui/joy/Avatar'; +import Box from '@mui/joy/Box'; + +export default function BasicAvatars() { + return ( + + + JG + + + ); +} diff --git a/docs/data/joy/components/avatar/BasicAvatars.tsx.preview b/docs/data/joy/components/avatar/BasicAvatars.tsx.preview new file mode 100644 index 00000000000000..39b1405e527ec3 --- /dev/null +++ b/docs/data/joy/components/avatar/BasicAvatars.tsx.preview @@ -0,0 +1,3 @@ + +JG + \ No newline at end of file diff --git a/docs/data/joy/components/avatar/avatar.md b/docs/data/joy/components/avatar/avatar.md index efb136b051115c..f482e46f564ade 100644 --- a/docs/data/joy/components/avatar/avatar.md +++ b/docs/data/joy/components/avatar/avatar.md @@ -16,34 +16,16 @@ The Avatar component can be used to display graphical information about a user i {{"component": "modules/components/ComponentLinkHeader.js", "design": false}} -## Component - -After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements: +## Basics ```jsx import Avatar from '@mui/joy/Avatar'; - -export default function MyApp() { - return ; -} ``` -## Basics - By default, the Avatar component displays a generic Person Icon. -Wrap it around a string to display plain text, or use the `src` prop to display an image. - -## Anatomy +You can replace this icon with a text string or an image. -The Avatar component is composed of a root `
` that may wrap around an ``, an ``, or a string: - -```html -
- -
-``` - -## Customization +{{"demo": "BasicAvatars.js"}} ### Text Avatar @@ -59,7 +41,7 @@ Make sure to to write a meaningful description for the `alt` prop. {{"demo": "ImageAvatars.js"}} -### Image fallbacks +#### Image fallbacks If an error occurs while loading the Avatar's image, it will fall back to the following alternatives (in this order): @@ -69,19 +51,22 @@ If an error occurs while loading the Avatar's image, it will fall back to the fo {{"demo": "FallbackAvatars.js"}} +## Customization + ### Variants -The Avatar component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `soft` (default), `solid`, `outlined`, and `plain`. +The Avatar component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid`, `soft` (default), `outlined`, and `plain`. {{"demo": "AvatarVariants.js"}} :::success -To learn how to add more variants to the component, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants). +Note that you lose the global variants when you add custom variants. ::: ### Sizes -The Avatar component comes in three sizes: `sm`, `md` (the default), and `lg`: +The Avatar component comes in three sizes: `sm`, `md` (default), and `lg`: {{"demo": "AvatarSizes.js"}} @@ -89,20 +74,14 @@ The Avatar component comes in three sizes: `sm`, `md` (the default), and `lg`: To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes). ::: -## Usage with the Badge - -Combine the Avatar component with the [Badge](/joy-ui/react-badge/) to visually communicate more complex information about a user's status: - -{{"demo": "BadgeAvatars.js"}} - -## Usage with the Avatar Group - -Use the Avatar Group component to group multiple Avatars together. +## Usage with Avatar Group ```jsx import AvatarGroup from '@mui/joy/AvatarGroup'; ``` +Use the Avatar Group component to group multiple Avatars together. + {{"demo": "GroupedAvatars.js"}} ### Quantity within a group @@ -141,9 +120,29 @@ This approach is preferable because it preserves the overlapping offset between {{"demo": "VerticalAvatarGroup.js"}} +## Usage with Badge + +```jsx +import Badge from '@mui/joy/Badge'; +``` + +Combine the Avatar component with the [Badge](/joy-ui/react-badge/) to visually communicate more complex information about a user's status: + +{{"demo": "BadgeAvatars.js"}} + ## CSS variable playground Play around with the CSS variables available to the Avatar component to see how the design changes. You can use these to customize the component with both the `sx` prop and the theme. {{"demo": "AvatarGroupVariables.js", "hideToolbar": true }} + +## Anatomy + +The Avatar component is composed of a root `
` that may wrap around an ``, an ``, or a string: + +```html +
+ +
+```