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.

Sign up for GitHub

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] Add section about overriding slots to base concepts #10421

Merged
merged 13 commits into from
Oct 4, 2023
Merged

[docs] Add section about overriding slots to base concepts #10421

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
d9ea3ef
add base concept section for slots
noraleonte Sep 21, 2023
9cdc514
Apply suggestions from code review - Lukas
noraleonte Sep 22, 2023
9df543b
replace colors
noraleonte Sep 22, 2023
ccbbdea
Merge branch 'add-slots-customization-example' of https://github.com/…
noraleonte Sep 22, 2023
3a0afa7
yarn ts
noraleonte Sep 22, 2023
c7276af
review
noraleonte Sep 26, 2023
a6e1982
Apply suggestions from code review - Lukas
noraleonte Sep 27, 2023
20a0ccf
improve color
noraleonte Sep 27, 2023
0421f8a
Merge branch 'master' of https://github.com/noraleonte/mui-x into add…
noraleonte Sep 27, 2023
5ea20ad
Apply suggestions from code review - Sam
noraleonte Sep 28, 2023
a3fc168
rename section
noraleonte Sep 28, 2023
5b6bf1a
rename
noraleonte Sep 28, 2023
e0e89c8
improve wording
noraleonte Oct 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions docs/data/date-pickers/base-concepts/CustomSlots.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import * as React from 'react';
import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
import { PickersDay } from '@mui/x-date-pickers/PickersDay';
import EditCalendarRoundedIcon from '@mui/icons-material/EditCalendarRounded';
import { styled } from '@mui/material/styles';
import IconButton from '@mui/material/IconButton';

const StyledButton = styled(IconButton)(({ theme }) => ({
borderRadius: theme.shape.borderRadius,
}));
const StyledDay = styled(PickersDay)(({ theme }) => ({
borderRadius: theme.shape.borderRadius,
color:
theme.palette.mode === 'light'
? theme.palette.secondary.dark
: theme.palette.secondary.light,
}));

export default function CustomSlots() {
return (
<LocalizationProvider dateAdapter={AdapterDayjs}>
<DemoContainer components={['DatePicker']}>
<DatePicker
label="Styled picker"
slots={{
openPickerIcon: EditCalendarRoundedIcon,
openPickerButton: StyledButton,
day: StyledDay,
}}
slotProps={{
openPickerIcon: { fontSize: 'large' },
openPickerButton: { color: 'secondary' },
textField: {
variant: 'filled',
focused: true,
color: 'secondary',
},
}}
/>
</DemoContainer>
</LocalizationProvider>
);
}
46 changes: 46 additions & 0 deletions docs/data/date-pickers/base-concepts/CustomSlots.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import * as React from 'react';
import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
import { PickersDay } from '@mui/x-date-pickers/PickersDay';
import EditCalendarRoundedIcon from '@mui/icons-material/EditCalendarRounded';
import { styled } from '@mui/material/styles';
import IconButton from '@mui/material/IconButton';

const StyledButton = styled(IconButton)(({ theme }) => ({
borderRadius: theme.shape.borderRadius,
}));
const StyledDay = styled(PickersDay)(({ theme }) => ({
borderRadius: theme.shape.borderRadius,
color:
theme.palette.mode === 'light'
? theme.palette.secondary.dark
: theme.palette.secondary.light,
}));

export default function CustomSlots() {
return (
<LocalizationProvider dateAdapter={AdapterDayjs}>
<DemoContainer components={['DatePicker']}>
<DatePicker
noraleonte marked this conversation as resolved.
Show resolved Hide resolved
label="Styled picker"
slots={{
openPickerIcon: EditCalendarRoundedIcon,
openPickerButton: StyledButton,
day: StyledDay,
}}
slotProps={{
openPickerIcon: { fontSize: 'large' },
openPickerButton: { color: 'secondary' },
textField: {
variant: 'filled',
focused: true,
color: 'secondary',
},
}}
/>
</DemoContainer>
</LocalizationProvider>
);
}
14 changes: 14 additions & 0 deletions docs/data/date-pickers/base-concepts/base-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,3 +174,17 @@ const cleanText = (string) =>
// Example of a test using the helper
expect(cleanText(input.value)).to.equal('04-17-2022');
```

## Overriding slots and slot props

Date and Time Pickers are complex components built using many subcomponents, known as **slots**. Slots are commonly filled by React components and you can easily override them using the `slots` prop. You can also pass additional props to the available `slots`, using the `slotProps` prop. You can explore a more in-depth walkthrough of the mental model of **slots** on [this page](/base-ui/guides/overriding-component-structure/).
noraleonte marked this conversation as resolved.
Show resolved Hide resolved

You can find the list of available `slots` for each component in its respective [API reference](/x/api/date-pickers/date-picker/#slots) doc.
noraleonte marked this conversation as resolved.
Show resolved Hide resolved

Some parts of the pickers' UI are built on several nested slots. For instance, the adornment of the `TextField` on `DatePicker` contains three slots (`inputAdornment`, `openPickerButton`, and `openPickerIcon`) that you can use depending on what you are trying to customize.
noraleonte marked this conversation as resolved.
Show resolved Hide resolved

{{"demo": "CustomSlots.js"}}

:::info
Visit the [dedicated documentation page](/x/react-date-pickers/custom-components/) for more information about overriding `slots`.
noraleonte marked this conversation as resolved.
Show resolved Hide resolved
:::
8 changes: 4 additions & 4 deletions docs/data/date-pickers/custom-components/custom-components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
productId: x-date-pickers
title: Date and Time Pickers - Custom subcomponents
components: DateTimePickerTabs
title: Date and Time Pickers - Custom slots and subcomponents
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about not renaming the menu item and it's heading? 🤔
Technically, almost all the Visual customization pages are about custom slots. 🙈

Maybe it's already time to rename all or most of the components word mentions on this page into slots? 🤔
Or at least only rename the section below to Overriding slot components or Overidding slots?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am somewhat in favor of leaving at least some mention of the word 'subcomponent' 🤔
I am not sure how easy it is for someone who is starting out on this doc to make the connection between slot and subcomponent 🤔
I am open to suggestions on this

Technically, almost all the Visual customization pages are about custom slots

Yeah, that is true. I feel like the other pages are more focused on specific use-cases. This one includes more scenarios and is somewhat of a gateway into understanding slots better. It would still make sense to have the slots mentioned in the menu as well 🤔

rename the section below to Overriding slot components or Overidding slots

totally agree 👍

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you agree that eventually, this page will become an home page for slot customization but all the actual examples will be moved to standalone pages (like we started doing)?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right, it probably will. And I would be in favor of using the term 'components' less and less, but maybe removing 'subcomponents' entirely from the headings is not the way to go 🤔 I feel like it's clear to us that slots are actually building blocks that you can override, but is it clear to users at a first look? So if somebody is on the docs, trying to figure out how to replace the openPickerIcon, which menu item is more self-explanatory 'Custom slots' or 'Custom slots and subcomponents'?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that "slot" is not understandable by people reaching to the doc for the 1st time

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there are no other objections, I'm fine with the suggested renaming. 👌

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about using a verb to describe what the user would actually do with this information? For example, the Base and Joy docs on this topic use the title "Overriding component structure", which IMO gives the reader a much better idea of how to apply this information, and doesn't require any knowledge of MUI-specific terminology.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overriding component structure is definitely a super valid option 💯 But in our case, I feel like it would add a bit of inconsistency, especially since the Visual customization section includes a number of other pages, most of them named like this:
image
I like the idea of introducing the word 'slots' to suggest the link between slots and subcomponents (also helps the search of either of these terms), and revisiting this topic in a broader refactor of the docs structure. WDYT about this?

components: DateTimePickerTabs, PickersActionBar, DatePickerToolbar, TimePickerToolbar, DateTimePickerToolbar, PickersCalendarHeader, PickersShortcuts
---

# Custom subcomponents
# Custom slots and subcomponents

<p class="description">The date picker lets you customize subcomponents.</p>
noraleonte marked this conversation as resolved.
Show resolved Hide resolved

Expand All @@ -13,7 +13,7 @@ The components that can be customized are listed under `slots` section in Date a
For example, available Date Picker slots can be found [here](/x/api/date-pickers/date-picker/#slots).
:::

## Overriding components
## Overriding slot components

You can override the internal elements of the component (known as "slots") using the `slots` prop.

Expand Down
2 changes: 1 addition & 1 deletion docs/data/pages.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,7 +327,7 @@ const pages: MuiPage[] = [
children: [
{
pathname: '/x/react-date-pickers/custom-components',
title: 'Custom subcomponents',
title: 'Custom slots and subcomponents',
},
{ pathname: '/x/react-date-pickers/custom-layout' },
{ pathname: '/x/react-date-pickers/custom-field' },
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/x/api/date-pickers/date-time-picker-tabs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,5 +29,5 @@
],
"styles": { "classes": ["root"], "globalClasses": {}, "name": "MuiDateTimePickerTabs" },
"filename": "/packages/x-date-pickers/src/DateTimePicker/DateTimePickerTabs.tsx",
"demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom subcomponents</a></li></ul>"
"demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li></ul>"
}