[base-ui][docs] Improve Next.js Link docs #39838

oliviertassinari · 2023-11-12T00:02:13Z

My goal here is to fix the "https://nextjs.org/learn/basics/navigate-between-pages/link-component" redirection:

https://app.ahrefs.com/site-audit/3524616/91/data-explorer?columns=pageRating%2Curl%2Ctraffic%2ChttpCode%2CcontentType%2Cdepth%2Credirect%2CincomingAllLinks&filterId=b3b75b6257a370fcf9f1f73befb5deb5&issueId=c64d8847-d0f4-11e7-8ed1-001e67ed4656&sorting=-pageRating

Note that we are working to move out of Google Groups to a system that allows a lot more control. This will allow us to delegate the SEO crawl ownership. I have handled them as high priorities so far. The automation is described in https://www.notion.so/mui-org/Scale-collaborative-inbox-in-Google-Groups-f6f3d7a8a6bd4c24be1fc8b13a8f33f6?pvs=4 the weekly ahrefs crawls for MUI Core will land on the replacement of core@mui.com and assigned to whoever wants to own this duty.

But I went a bit outside of the scope of the initial problem 😇

Notes on things that I can see on Base UI documentation, stuff that surfaces quickly while I was fixing the URL reference:

1. We should trend toward a place where updating the CSS and Tailwind CSS is automated, It feels like a waste of time to manually maintain this. I think we can set the priority of automation higher than adding more Tailwind CSS demos. For example, here, I fixed a few inconsistencies between demos, e.g. border disabled. [docs-infra] Automate generation of CSS demos base-ui#58
2. I think that we can't use :disabled as a CSS selector. Developers might render a div, .Mui-disabled seems to be the solution.
3. Issue created: [base-ui][Button] disabled prop not being passed across Next.js SSR #38943. I noticed 2. because the disable button flashes on each mount

Screen.Recording.2023-11-12.at.06.48.56.mov

https://mui.com/base-ui/react-button/#introduction

@michaldudak I'm afraid of cases where a form may be submitted because disabled isn't set in the DOM yet while that form shouldn't be submittable.

4. The duplication of the introduction demo throughout the page is not great. I think that fixing this duplication is more important than improving the demos of the Base UI docs. The solution can be to rely on demo tab [docs-infra] Support shared source between demos #38911. This will help to have higher-quality demos. Right now, I think that it's a bit demotivating for the community to try to fix them all.
5. There is a strange useIsDarkMode toggle in the Tailwind CSS demo. I don't understand why it's here. I would expect that we rely on the default configuration for dark mode, have it customized for the docs, and be configured for CodeSandbox/StackBlitz exports.
6. Invalid I find it weird to have buttonClasses.active. It doesn't seem to be superior to :active. An API to remove to keep things simple? I noticed this while I added a scale(0.99) to match the box shadow removal depth effect.
7. We still have a good number of legacyBehavior props used for Next.js, even ones that leak to developers' public API. I think this should be a priority to fix since it's about keeping up with the latest dependencies, otherwise, it signals to the developers that we are lagging. [docs] Update docs related to using Next.js's Link with Material UI #38092
8. We have demos in Base UI that depend on box-sizing: content-box. For example, https://mui.com/base-ui/react-slider/#discrete-sliders is broken when you open it in CodeSandbox. An easy way to catch these is by looking at the screenshot taken by Argos CI: https://app.argos-ci.com/mui/material-ui/builds/20856.

9. We didn't configure Tailwind CSS for Argos CI

#39954

10. High resolution screenshot (low-priority) argos-ci/argos#1089 To consider taking a higher resolution screenshot with Argos CI: [Question] Capture "retina" quality screenshot microsoft/playwright#17501 (comment). I'm not sure if this is possible, and the CI speed implication, but to keep in the back of our head. I suspect we are trending toward this becoming the norm on desktop, e.g. in 5 years.

mui-bot · 2023-11-12T00:05:40Z

Netlify deploy preview

docs/data/base/components/button/button.md

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against 5a6d6a3

docs/data/base/components/button/UnstyledButtonCustom.js

oliviertassinari · 2023-11-12T00:04:56Z

docs/data/base/components/button/UnstyledButtonIntroduction/css/index.js

-        <Button className="CustomButton">Button</Button>
-        <Button className="CustomButton" disabled>
+        <Button className="IntroductionButton">Button</Button>
+        <Button className="IntroductionButton" disabled>


This class name was shared between two demos, it was annoying when in the dev tools to have duplication of styles.

oliviertassinari · 2023-11-12T00:05:21Z

docs/data/base/components/button/UnstyledButtonIntroduction/css/index.js

-    cursor: not-allowed;
+    cursor: default;


Overall MUI policy on disabled cursors.

oliviertassinari · 2023-11-12T00:05:43Z

docs/data/base/components/button/UnstyledButtonIntroduction/system/index.js

@@ -58,23 +58,21 @@ const Button = styled(BaseButton)(
  &:active {
    background-color: ${blue[700]};
    box-shadow: none;
+    transform: scale(0.99);


It adds depth to the click interaction 🤤

cc @zanivan to experiment/polish/standardize!

docs/data/base/components/button/UnstyledButtonIntroduction/system/index.js

oliviertassinari · 2023-11-12T00:08:24Z

docs/data/base/components/button/UnstyledLinkButton.js

-      <Button href={'https://mui.com/'}>Standard link</Button>
-      <Link href={'https://mui.com/'}>
-        <Button>Next link</Button>
-      </Link>
+      <Button href="https://mui.com/">Standard link</Button>
+      <Button href="https://mui.com/" slots={{ root: LinkSlot }}>
+        Next.js link
+      </Button>


"Next link" felt confusing, "Next.js link" instead.

oliviertassinari · 2023-11-12T00:08:52Z

docs/data/base/components/button/UnstyledLinkButton.tsx

+const LinkSlot = prepareForSlot(Link);
+
 export default function UnstyledLinkButton() {
  return (
    <Stack spacing={2} direction="row">
-      <Button href={'https://mui.com/'}>Standard link</Button>
-      <Link href={'https://mui.com/'}>
-        <Button>Next link</Button>
-      </Link>
+      <Button href="https://mui.com/">Standard link</Button>
+      <Button href="https://mui.com/" slots={{ root: LinkSlot }}>
+        Next.js link
+      </Button>
    </Stack>


Use the latest recommending API for Next.js

oliviertassinari · 2023-11-12T00:09:34Z

docs/data/base/components/button/button.md

-The following demo illustrates how to use the Button as a link, whether using the Base UI Button itself for the `href`, or with the [Next.js Link component](https://nextjs.org/learn/basics/navigate-between-pages/link-component):
+The following demo illustrates how to use the Button as a link, whether using the Base UI Button itself for the `href`, or with the [Next.js Link component](https://nextjs.org/docs/pages/api-reference/components/link):


Use the same URL as the other references to Next.js's Link we have in the docs.

My goal here is to fix the redirection that "https://nextjs.org/learn/basics/navigate-between-pages/link-component" is. You can find this in https://app.ahrefs.com/site-audit/3524616/91/data-explorer?columns=pageRating%2Curl%2Ctraffic%2ChttpCode%2CcontentType%2Cdepth%2Credirect%2CincomingAllLinks&filterId=b3b75b6257a370fcf9f1f73befb5deb5&issueId=c64d8847-d0f4-11e7-8ed1-001e67ed4656&sorting=-pageRating. Note that we are working to move out of Google Groups to a system that allows a lot more control. This will allow me to delegate the SEO crawl ownership. IMHO these are high priorities. I have always made everything come after. The automation is described in https://www.notion.so/mui-org/Scale-collaborative-inbox-in-Google-Groups-f6f3d7a8a6bd4c24be1fc8b13a8f33f6?pvs=4 the weekly ahrefs crawls for MUI Core will land on the replacement of core@mui.com and assigned to whoever wants to own this duty. --- Notes on things that I can see while I was fixing the URL reference: 1. Updating the CSS and Tailwind CSS should be automated, I think it's a waste of time to manually maintain this. It sounds much faster to automate it. So I think that automate this is a LOT more important than adding more Tailwind CSS demos. For example, here, I fixed a border inconsistency issue. 2. We can't use :disabled. Developers might render a div, .Mui-disabled seems to be the solution. 3. I noticed 2. because the disable button was flashing. And it's not like it flashes because it's a SSR hydration. It consistently flashes on each new mount. I don't think this is possible for production, the DOM output needs to be correct from the first sync. I think we must change the API. 4. The duplication of the introduction demo is not great. I think that fixing this duplication is a LOT more important than improving the demos of the Base UI docs. The solution can be to rely on demo tabs. This will help to have higher quality demos. Right now, I think that it's completly demotivating for the community (e.g. how I felt when fixing this) to try to fix them. 5. There is a strange `useIsDarkMode` toggle in the Tailwind CSS demo. This one doesn't make sense to me. I don't see why we are not relying on the default configuration for dark mode, have it customized for the docs and configured for CodeSandbox/StackBlitz exports. 6. The code export for CodeSandbox/StackBlitz doesn't work with Tailwind CSS. 7. I find it weird to have buttonClasses.active. It doesn't seem to be superior to :active in any way. An API to remove to keep things simple? I noticed this while I added a scale(0.99) to match the box shadow removal depth effect. I find it so satisfiying 🤤, so good. 8. We still have a good number of `legacyBehavior` prop use for Next.js, even ones that leaks to developers public API. I think this should be a priority to fix, we are laggying behind.

michaldudak · 2023-11-12T02:59:18Z

@michaldudak I'm afraid of cases where a form may be submitted because disabled isn't set in the DOM yet while that form shouldn't be submittable.

If I understand it correctly, it should be fixed in #38943 by @mj12albert

I find it weird to have buttonClasses.active. It doesn't seem to be superior to :active

The :active pseudoclass is not applied to non-interactive elements (such as a span) when they are activated with a keyboard.

oliviertassinari · 2023-11-13T03:09:47Z

If I understand it correctly

@michaldudak Ah perfect, we have an open issue for this: #38943

The :active pseudoclass is not applied to non-interactive elements (such as a span) when they are activated with a keyboard.

Oh, I see, I can reproduce this problem in https://codesandbox.io/s/fervent-snyder-vchc6f?file=/src/Demo.tsx.

In https://mui.com/material-ui/react-button/#basic-button we are not supporting this case, we managed to get away from it because the &:active style is only applied with the mouse pointer, when it's triggered by the keyboard, that style is ignored (for both button and non-button host elements). I'm reverting that part then.

oliviertassinari · 2023-11-13T03:58:40Z

docs/data/base/components/button/button.md

-{{"demo": "UnstyledButtonsSimple"}}
+{{"demo": "UnstyledButtonsSimple.js"}}


It's too early, I'm removing these Tailwind CSS and CSS modules extra demos. I think that we only have the bandwidth for one demo per component. We are going to die on the hill if we try to convert everything without automation.

oliviertassinari · 2023-11-13T03:58:58Z

docs/data/base/components/button/button.md

-<button class="BaseButton-root">
+<button class="MuiButton-root">


oliviertassinari added docs Improvements or additions to the documentation component: button This is the name of the generic UI component, not the React module! package: base-ui Specific to @mui/base labels Nov 12, 2023

oliviertassinari commented Nov 12, 2023

View reviewed changes

oliviertassinari force-pushed the base-button-fix-API-link branch from 552a74c to d09691f Compare November 12, 2023 00:19

oliviertassinari mentioned this pull request Nov 13, 2023

[base-ui][Button] disabled prop not being passed across Next.js SSR #38943

Closed

oliviertassinari added 2 commits November 13, 2023 10:46

simplify

835e162

michal review

5a6d6a3

oliviertassinari commented Nov 13, 2023

View reviewed changes

oliviertassinari merged commit 3942945 into mui:master Nov 21, 2023
23 checks passed

oliviertassinari deleted the base-button-fix-API-link branch November 21, 2023 20:49

mnajdova pushed a commit to mnajdova/material-ui that referenced this pull request Dec 6, 2023

[base-ui][docs] Improve Next.js Link docs (mui#39838)

d26998f

mnajdova pushed a commit to mnajdova/material-ui that referenced this pull request Dec 6, 2023

[base-ui][docs] Improve Next.js Link docs (mui#39838)

0bfc06d

mnajdova pushed a commit to mnajdova/material-ui that referenced this pull request Dec 6, 2023

[base-ui][docs] Improve Next.js Link docs (mui#39838)

044f663

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[base-ui][docs] Improve Next.js Link docs #39838

[base-ui][docs] Improve Next.js Link docs #39838

oliviertassinari commented Nov 12, 2023 •

edited

mui-bot commented Nov 12, 2023 •

edited

oliviertassinari Nov 12, 2023

oliviertassinari Nov 12, 2023

oliviertassinari Nov 12, 2023

danilo-leal Nov 12, 2023

oliviertassinari Nov 12, 2023

oliviertassinari Nov 12, 2023

oliviertassinari Nov 12, 2023

michaldudak commented Nov 12, 2023

oliviertassinari commented Nov 13, 2023

oliviertassinari Nov 13, 2023 •

edited

oliviertassinari Nov 13, 2023

		The following demo illustrates how to use the Button as a link, whether using the Base UI Button itself for the `href`, or with the [Next.js Link component](https://nextjs.org/learn/basics/navigate-between-pages/link-component):
		The following demo illustrates how to use the Button as a link, whether using the Base UI Button itself for the `href`, or with the [Next.js Link component](https://nextjs.org/docs/pages/api-reference/components/link):

		{{"demo": "UnstyledButtonsSimple"}}
		{{"demo": "UnstyledButtonsSimple.js"}}

		<button class="BaseButton-root">
		<button class="MuiButton-root">

[base-ui][docs] Improve Next.js Link docs #39838

[base-ui][docs] Improve Next.js Link docs #39838

Conversation

oliviertassinari commented Nov 12, 2023 • edited

mui-bot commented Nov 12, 2023 • edited

Netlify deploy preview

Bundle size report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michaldudak commented Nov 12, 2023

oliviertassinari commented Nov 13, 2023

oliviertassinari Nov 13, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliviertassinari commented Nov 12, 2023 •

edited

mui-bot commented Nov 12, 2023 •

edited

oliviertassinari Nov 13, 2023 •

edited