Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs-infra][joy-ui] Polish the usage and CSS vars playgrounds #38600

Merged
merged 12 commits into from
Aug 23, 2023
12 changes: 6 additions & 6 deletions docs/data/joy/components/autocomplete/autocomplete.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,12 @@ const filterOptions = (options, { inputValue }) => matchSorter(options, inputVal
<Autocomplete filterOptions={filterOptions} />;
```

## CSS variables playground

The Autocomplete component reuses CSS variables from the Input component to give you the consistent customization experience.

{{"demo": "AutocompleteVariables.js", "hideToolbar": true, "bg": "gradient"}}

## Common examples

### Hint
Expand Down Expand Up @@ -307,12 +313,6 @@ If you would like to prevent the default key handler behavior, you can set the e
/>
```

## CSS Variables

The Autocomplete component reuses CSS variables from the Input component to give you the consistent customization experience.

{{"demo": "AutocompleteVariables.js", "hideToolbar": true}}

## Limitations

### autocomplete/autofill
Expand Down
4 changes: 2 additions & 2 deletions docs/data/joy/components/avatar/avatar.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,12 +131,12 @@ Combine the Avatar component with the [Badge](/joy-ui/react-badge/) to visually

{{"demo": "BadgeAvatars.js"}}

## CSS variable playground
## CSS variables 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 }}
{{"demo": "AvatarGroupVariables.js", "hideToolbar": true, "bg": "gradient"}}

## Anatomy

Expand Down
14 changes: 7 additions & 7 deletions docs/data/joy/components/breadcrumbs/breadcrumbs.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,13 @@ The demo below shows how to add an icon to the Link with `startDecorator` and ch

{{"demo": "BreadcrumbsWithIcon.js"}}

## CSS variables playground

Play around with the CSS variables available to the Breadcrumbs component to see how the design changes.
You can use these to customize the component with both the `sx` prop and the theme.

{{"demo": "BreadcrumbsVariables.js", "hideToolbar": true, "bg": "gradient"}}

## Common examples

### Condensed Breadcrumbs
Expand All @@ -84,13 +91,6 @@ As an alternative to the behavior of the condensed demo above, consider adding a

{{"demo": "BreadcrumbsWithMenu.js"}}

## CSS variable playground

Play around with the CSS variables available to the Breadcrumbs component to see how the design changes.
You can use these to customize the component with both the `sx` prop and the theme.

{{"demo": "BreadcrumbsVariables.js", "hideToolbar": true}}

## Accessibility

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)
Expand Down
6 changes: 3 additions & 3 deletions docs/data/joy/components/button/button.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,18 +124,18 @@ Use the Icon Button component for a square button to house an icon with no text

{{"demo": "IconButtons.js"}}

## CSS variable playground
## CSS variables playground

Play around with the CSS variables available to the Button and Icon Button components to see how the design changes.
You can use these to customize the components with both the `sx` prop and the theme.

### Button

{{"demo": "ButtonVariables.js", "hideToolbar": true}}
{{"demo": "ButtonVariables.js", "hideToolbar": true, "bg": "gradient"}}

### Icon Button

{{"demo": "IconButtonVariables.js", "hideToolbar": true}}
{{"demo": "IconButtonVariables.js", "hideToolbar": true, "bg": "gradient"}}

## Accessibility

Expand Down
238 changes: 22 additions & 216 deletions docs/data/joy/components/card/CardVariables.js
Original file line number Diff line number Diff line change
@@ -1,239 +1,45 @@
import * as React from 'react';
import AspectRatio from '@mui/joy/AspectRatio';
import Box from '@mui/joy/Box';
import Button from '@mui/joy/Button';
import Sheet from '@mui/joy/Sheet';
import Card from '@mui/joy/Card';
import CardActions from '@mui/joy/CardActions';
import CardCover from '@mui/joy/CardCover';
import CardContent from '@mui/joy/CardContent';
import CardOverflow from '@mui/joy/CardOverflow';
import CircularProgress from '@mui/joy/CircularProgress';
import IconButton from '@mui/joy/IconButton';
import Link from '@mui/joy/Link';
import FormControl from '@mui/joy/FormControl';
import FormLabel from '@mui/joy/FormLabel';
import FormHelperText from '@mui/joy/FormHelperText';
import Input from '@mui/joy/Input';
import Typography from '@mui/joy/Typography';
import BookmarkBorderIcon from '@mui/icons-material/BookmarkBorder';
import BrandingProvider from 'docs/src/BrandingProvider';
import HighlightedCode from 'docs/src/modules/components/HighlightedCode';

function formatSx(sx) {
const lines = Object.keys(sx);
if (!lines.length) {
return '';
}
if (lines.length === 1) {
return ` sx={${JSON.stringify(sx)
.replace('{', '{ ')
.replace('}', ' }')
.replace(':', ': ')}}`;
}
return ` sx={${JSON.stringify(sx, null, 2)}}`;
}

const vars = [
{
var: '--Card-padding',
defaultValue: '16px',
type: 'number',
},
{
var: '--Card-radius',
defaultValue: '12px',
type: 'number',
},
];
import JoyVariablesDemo from 'docs/src/modules/components/JoyVariablesDemo';

export default function CardVariables() {
const [sx, setSx] = React.useState({});
return (
<Box
sx={{
width: '100%',
display: 'grid',
gridTemplateColumns: { xs: '1fr', md: '1fr auto' },
gridTemplateRows: '1fr auto',
gap: 2,
mt: 2,
'& .markdown-body pre': {
margin: 0,
borderRadius: 'xs',
<JoyVariablesDemo
componentName="Card"
data={[
{
var: '--Card-padding',
defaultValue: '16px',
type: 'number',
},
{
var: '--Card-radius',
defaultValue: '12px',
type: 'number',
},
}}
>
<Box
sx={{
alignSelf: 'center',
justifyContent: 'center',
mx: 'auto',
display: 'flex',
placeSelf: 'center',
gap: 2,
flexWrap: 'wrap',
}}
>
]}
renderDemo={(sx) => (
<Card variant="outlined" sx={{ maxWidth: 240, boxShadow: 'none', ...sx }}>
<CardOverflow>
<AspectRatio>
<img
src="https://images.unsplash.com/photo-1523404343994-489a5eefd760?auto=format&fit=crop&w=198"
srcSet="https://images.unsplash.com/photo-1523404343994-489a5eefd760?auto=format&fit=crop&w=198&dpr=2 2x"
loading="lazy"
alt=""
/>
</AspectRatio>
</CardOverflow>
<AspectRatio
variant="outlined"
ratio="1"
sx={{
width: 48,
mt: -5,
'& > div': {
'--variant-borderWidth': '2px',
borderColor: 'background.surface',
},
}}
>
<img src="/static/images/avatar/6.jpg" loading="lazy" alt="" />
</AspectRatio>
<CardContent>
<Typography fontWeight="lg">
<Link
href="#card-variables"
overlay
underline="none"
textColor="text.primary"
>
Card title
</Link>
</Typography>
<Typography level="body-sm">A very very long description.</Typography>
<Typography fontWeight="lg">Card title</Typography>
<Typography level="body-sm">An interesting description.</Typography>
</CardContent>
<CardActions buttonFlex="1">
<IconButton variant="outlined" color="neutral" size="sm">
<BookmarkBorderIcon />
</IconButton>
<Button variant="solid" color="primary" size="sm">
Buy
</Button>
<IconButton variant="outlined" color="neutral" size="sm">
<BookmarkBorderIcon />
</IconButton>
</CardActions>
</Card>
<Card
variant="solid"
color="neutral"
invertedColors
sx={{ minWidth: 200, maxWidth: 240, boxShadow: 'none', ...sx }}
>
<CardCover>
<img
src="https://images.unsplash.com/photo-1523262297412-fafbd40c6aa4?auto=format&fit=crop&w=198"
srcSet="https://images.unsplash.com/photo-1523262297412-fafbd40c6aa4?auto=format&fit=crop&w=198&dpr=2 2x"
loading="lazy"
alt=""
/>
</CardCover>
<CardCover
sx={{
background:
'linear-gradient(to top, rgba(0,0,0,0.4), rgba(0,0,0,0) 200px), linear-gradient(to top, rgba(0,0,0,0.8), rgba(0,0,0,0) 300px)',
backdropFilter: 'blur(4px)',
}}
/>
<CardContent>
<CircularProgress
determinate
value={70}
sx={{
'--CircularProgress-size': '100px',
'--CircularProgress-progressThickness': '8px',
'--CircularProgress-trackThickness': '8px',
m: 'auto',
}}
>
<Typography>70%</Typography>
</CircularProgress>
</CardContent>
<CardContent sx={{ textAlign: 'center', justifyContent: 'center' }}>
<Typography fontWeight="lg" textColor="#fff">
Card title
</Typography>
<Typography level="body-sm" textColor="neutral.300">
Long description.
</Typography>
</CardContent>
<CardActions>
<Button variant="outlined">Get started</Button>
</CardActions>
</Card>
</Box>
<Sheet
variant="outlined"
sx={{
gridRow: 'span 2',
display: 'flex',
flexWrap: 'wrap',
gap: 2,
p: 2,
borderRadius: 'sm',
}}
>
<Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
<Typography fontWeight="xl" level="body-sm" textColor="text.primary">
CSS variables
</Typography>
{vars.map((data) => (
<FormControl key={data.var}>
<FormLabel sx={{ '--FormLabel-fontSize': 'var(--joy-fontSize-xs)' }}>
{data.var}
</FormLabel>
<Input
size="sm"
variant="outlined"
defaultValue={
Number(data.defaultValue.replace('px', '')) || undefined
}
endDecorator={<Typography level="body-xs">px</Typography>}
type={data.type}
sx={{
maxWidth: 160,
'& .JoyInput-root': { '--Input-paddingInline': '0.5rem' },
}}
onChange={(event) => {
const { value } = event.target;
setSx((prevSx) => {
if (!value) {
const newSx = { ...prevSx };
// @ts-ignore
delete newSx[data.var];
return newSx;
}
return {
...prevSx,
[data.var]: `${value}px`,
};
});
}}
/>
{data.defaultValue ? (
<FormHelperText
sx={{ '--FormHelperText-fontSize': 'var(--joy-fontSize-xs)' }}
>{`Default as ${data.defaultValue}`}</FormHelperText>
) : null}
</FormControl>
))}
</Box>
</Sheet>
<BrandingProvider mode="dark">
<HighlightedCode
code={`<Card${formatSx(sx)}>`}
language="jsx"
sx={{ display: { xs: 'none', md: 'initial' } }}
/>
</BrandingProvider>
</Box>
)}
/>
);
}
6 changes: 3 additions & 3 deletions docs/data/joy/components/card/card.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,18 +158,18 @@ Learn more about this and other best practices for accessible cards in the [Incl

{{"demo": "InteractiveCard.js"}}

## CSS variable playground
## CSS variables playground

Play around with the CSS variables available to the Card component to see how the design changes.
You can use these to customize the component with both the `sx` prop and the theme.

{{"demo": "CardVariables.js", "hideToolbar": true, "bg": "gradient"}}

:::success
If you need to adjust a Card's padding or border radius, it's preferable to do so using these variables rather than plain CSS properties.
This is because the variables are also used to calculate a proper radius for the Card's children, to prevent a mismatch between their relative proportions.
:::

{{"demo": "CardVariables.js" , "hideToolbar": true}}

## Common examples

### Bio card
Expand Down
4 changes: 2 additions & 2 deletions docs/data/joy/components/chip/chip.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,10 +91,10 @@ Use checkboxes when you want to enable multiple selection.

{{"demo": "CheckboxChip.js"}}

## CSS variables
## CSS variables playground

Play around with all the CSS variables available in the slider component to see how the design changes.

You can use those to customize the component on both the `sx` prop and the theme.

{{"demo": "ChipVariables.js", "hideToolbar": true}}
{{"demo": "ChipVariables.js", "hideToolbar": true, "bg": "gradient"}}
Loading