[docs] Add themeable component guide #37908

siriwatknp · 2023-07-11T06:55:18Z

Material UI guide: https://deploy-preview-37908--material-ui.netlify.app/material-ui/guides/themeable-component/
Joy UI guide: https://deploy-preview-37908--material-ui.netlify.app/joy-ui/guides/themeable-component/

All of the APIs are public but we've never published the docs. I think it's time to do it. Once the content is stable, I will add the same to Joy UI.

closes #32967

Further improvements in v6 (breaking changes)

The case transforming logic can be removed completely to make the API more intuitive (what you pass in is what you get). Existing usage on Material UI and Joy UI needs to be updated accordingly.

// as an example, Joy UI Button.tsx
export const ButtonRoot = styled('button', {
  name: 'JoyButton',
+  slot: 'root',
-  slot: 'Root',
-  overridesResolver: (props, styles) => styles.root,
})(…)

I have followed (at least) the PR section of the contributing guide.

mui-bot · 2023-07-11T06:58:02Z

Netlify deploy preview

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against 8e1b63f

siriwatknp · 2023-07-11T08:39:48Z

@mnajdova I think the styled can be simplified a bit.

At this point, the overridesResolver is required to make the component themable but I think 99% of the custom component does not need custom overridesResolver (I think overridesResolver exists to make v4 -> v5 possible)

I think developers should provide just name and slot:

const StatSlot = styled('div', {
  name: 'MuiStat',
  slot: 'Root',
})(…)

I think it will be better to use slot as a lower case or camel case. Basically whatever the slot value that you provide will be the key that the users will have to use.

Right now it's kinda confusing why I have to use Root in the slot but the users will use root in the theme.

I think both points won't be a breaking change.

cc @DiegoAndai

siriwatknp · 2023-07-11T08:41:20Z

@samuelsycamore I put this in the how-to guide, not the customization. What do you think?

DiegoAndai

Nice example! Easy to follow and understand 😊🎉

Regarding overridesResolver, what do you propose? if nothing is provided, then the style override slot styles won't be added. Should we default to styleOverrides[slotName]?
Regarding the slot casing, I agree we could use camelCase in this guide so it's the same as the key the users will use. Should we do that from now on in our own codebase?

DiegoAndai · 2023-07-11T19:42:10Z

docs/data/material/guides/custom-component/custom-component.md

+
+Finally, you have to add the Stat component the theme types.
+
+```ts


This example was confusing to me. I didn't understand what each override and change did. I think it would be better if each line is explained with a comment.

Sure, I will add a comment to it.

docs/data/material/guides/custom-component/custom-component.md

siriwatknp · 2023-07-12T02:48:04Z

Regarding overridesResolver, what do you propose? if nothing is provided, then the style override slot styles won't be added. Should we default to styleOverrides[slotName]?

I have the same thought. It should default to styleOverrides[slotName]. I don't have a use case to customize it in Joy UI so I expect the others will be the same.

Regarding the slot casing, I agree we could use camelCase in this guide so it's the same as the key the users will use. Should we do that from now on in our own codebase?

We should but we have to update the implementation because some code is checking the upper first letter like Root. If @mnajdova agrees with this, I will update it in this PR (no breaking change).

DiegoAndai · 2023-07-12T11:37:37Z

I agree with both changes proposed by @siriwatknp in the comment above 😊

mnajdova · 2023-07-17T11:30:10Z

At this point, the overridesResolver is required to make the component themable but I think 99% of the custom component does not need custom overridesResolver (I think overridesResolver exists to make v4 -> v5 possible)
I think developers should provide just name and slot:
const StatSlot = styled('div', {
  name: 'MuiStat',
  slot: 'Root',
})(…)

We can make it optional 👍

I think it will be better to use slot as a lower case or camel case. Basically whatever the slot value that you provide will be the key that the users will have to use.
Right now it's kinda confusing why I have to use Root in the slot but the users will use root in the theme.

The slot is used for the display name - the name of the components, this is why initially it was uppercased. The overrides resolver is the thing that decides which key will be used in the style overrides. It could depend on the state and other factors, not just the slot name.

docs/data/material/guides/custom-component/custom-component.md

…/custom-component

omerman · 2023-07-18T21:25:04Z

This looks great! Im looking forward to work using these Apis 🙌

siriwatknp · 2023-07-20T03:01:59Z

packages/mui-system/src/createStyled.js

@@ -219,7 +233,7 @@ export default function createStyled(input = {}) {
      if (process.env.NODE_ENV !== 'production') {
        let displayName;
        if (componentName) {
-          displayName = `${componentName}${componentSlot || ''}`;
+          displayName = `${componentName}${capitalize(componentSlot || '')}`;


@mnajdova based on your comment, I think the logic can be the other way around.

I believe that using slotName directly is easier to understand for developers. The capitalize I added is to preserve the previous behavior. In fact, it can be removed because it is for debugging and it won't be used in production.

We could remove it in the next major release?

I think we can keep using capitalize it in the displayName

siriwatknp · 2023-07-20T03:07:23Z

Nice example! Easy to follow and understand 😊🎉

Regarding overridesResolver, what do you propose? if nothing is provided, then the style override slot styles won't be added. Should we default to styleOverrides[slotName]?

Regarding the slot casing, I agree we could use camelCase in this guide so it's the same as the key the users will use. Should we do that from now on in our own codebase?

I have updated:

added default overridesResolver, so it will use styleOverrides[slotName] as you suggested.
Now, the slot casing can be anything, we should let developers own this part (from the code, it won't have an impact on the theming logic, meaning whatever slot name they define the styleOverrides will have to be that name)

mnajdova

The implementation looks good. Let's clarify in the TODO which version we are talking about, so that we can search easily. The copy-writing can be reviewed by @samuelsycamore

samuelsycamore · 2023-07-20T21:58:42Z

I'm on it! Thanks for being patient! 🫡

samuelsycamore

I'm so sorry it took me so long to get back to this @siriwatknp !! 😭 I assume that most of my comments here apply to the Material UI doc as well.

docs/data/joy/guides/themeable-component/themeable-component.md

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>

…/custom-component

siriwatknp · 2023-08-03T02:44:03Z

@samuelsycamore all fixed, including Material UI guide.

oliviertassinari · 2024-03-10T16:55:26Z

I'm late to the party, but this change makes a lot of sense, great to see steps made here 👍

add custom component to Material UI guide

b5fdadc

siriwatknp added docs Improvements or additions to the documentation customization: theme Centered around the theming features labels Jul 11, 2023

siriwatknp added 2 commits July 11, 2023 15:31

add the page to nav and update content

e8d0475

fix diff

0b51704

siriwatknp requested review from mnajdova, DiegoAndai and samuelsycamore July 11, 2023 08:34

siriwatknp marked this pull request as ready for review July 11, 2023 08:40

siriwatknp mentioned this pull request Jul 11, 2023

Give the possibility to create new Components using the Material theming system for unique behavior #32967

Closed

2 tasks

DiegoAndai reviewed Jul 11, 2023

View reviewed changes

mnajdova reviewed Jul 17, 2023

View reviewed changes

docs/data/material/guides/custom-component/custom-component.md Outdated Show resolved Hide resolved

siriwatknp added 4 commits July 18, 2023 16:31

Merge branch 'master' of https://github.com/mui/material-ui into docs…

87f45ef

…/custom-component

support lower case root

c6b608b

refactor content to themable-component

c74178e

add test

7024d69

siriwatknp commented Jul 20, 2023

View reviewed changes

mnajdova approved these changes Jul 20, 2023

View reviewed changes

siriwatknp changed the title ~~[docs] Add custom component guide~~ [docs] Add themable component guide Jul 20, 2023

siriwatknp changed the title ~~[docs] Add themable component guide~~ [docs] Add themeable component guide Jul 20, 2023

siriwatknp added 2 commits July 20, 2023 17:46

fix typo

fde8300

add content for Joy UI

8c0224a

siriwatknp added 4 commits July 20, 2023 18:32

fix content

b575228

update content

fc6a868

run scripts

e98c745

update comment

db081f0

siriwatknp added the package: system Specific to @mui/system label Jul 21, 2023

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Jul 29, 2023

samuelsycamore reviewed Aug 1, 2023

View reviewed changes

siriwatknp and others added 4 commits August 3, 2023 08:38

Apply suggestions from code review

f2fa384

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Siriwat K <siriwatkunaporn@gmail.com>

Merge branch 'master' of https://github.com/mui/material-ui into docs…

277c637

…/custom-component

fix content from Sam's suggestion

131ed99

fix typography level usage

cc1c22a

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Aug 3, 2023

siriwatknp requested a review from DiegoAndai August 3, 2023 02:44

run docs:i18n

8e1b63f

mnajdova merged commit b97f61f into mui:master Aug 7, 2023
21 checks passed

richbustos pushed a commit that referenced this pull request Aug 7, 2023

[docs] Add themeable component guide (#37908)

c608949

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Add themeable component guide #37908

[docs] Add themeable component guide #37908

siriwatknp commented Jul 11, 2023 •

edited

mui-bot commented Jul 11, 2023 •

edited

siriwatknp commented Jul 11, 2023

siriwatknp commented Jul 11, 2023

DiegoAndai left a comment •

edited

DiegoAndai Jul 11, 2023

siriwatknp Jul 12, 2023

siriwatknp commented Jul 12, 2023

DiegoAndai commented Jul 12, 2023

mnajdova commented Jul 17, 2023

omerman commented Jul 18, 2023

siriwatknp Jul 20, 2023

mnajdova Jul 31, 2023

siriwatknp commented Jul 20, 2023

mnajdova left a comment

samuelsycamore commented Jul 20, 2023

samuelsycamore left a comment

siriwatknp commented Aug 3, 2023

oliviertassinari commented Mar 10, 2024 •

edited


		Finally, you have to add the Stat component the theme types.

		```ts

[docs] Add themeable component guide #37908

[docs] Add themeable component guide #37908

Conversation

siriwatknp commented Jul 11, 2023 • edited

Further improvements in v6 (breaking changes)

mui-bot commented Jul 11, 2023 • edited

Netlify deploy preview

Bundle size report

siriwatknp commented Jul 11, 2023

siriwatknp commented Jul 11, 2023

DiegoAndai left a comment • edited

Choose a reason for hiding this comment

DiegoAndai Jul 11, 2023

Choose a reason for hiding this comment

siriwatknp Jul 12, 2023

Choose a reason for hiding this comment

siriwatknp commented Jul 12, 2023

DiegoAndai commented Jul 12, 2023

mnajdova commented Jul 17, 2023

omerman commented Jul 18, 2023

siriwatknp Jul 20, 2023

Choose a reason for hiding this comment

mnajdova Jul 31, 2023

Choose a reason for hiding this comment

siriwatknp commented Jul 20, 2023

mnajdova left a comment

Choose a reason for hiding this comment

samuelsycamore commented Jul 20, 2023

samuelsycamore left a comment

Choose a reason for hiding this comment

siriwatknp commented Aug 3, 2023

oliviertassinari commented Mar 10, 2024 • edited

siriwatknp commented Jul 11, 2023 •

edited

mui-bot commented Jul 11, 2023 •

edited

DiegoAndai left a comment •

edited

oliviertassinari commented Mar 10, 2024 •

edited