[docs] Group picker pages #6369

flaviendelangle · 2022-10-03T13:12:12Z

Part of #5565
Doc preview: https://deploy-preview-6369--material-ui-x.netlify.app/x/react-date-pickers/date-picker/

Follow up

Create one page per "Calendar" component

mui-bot · 2022-10-03T13:19:08Z

	Messages
📖	Netlify deploy preview: https://deploy-preview-6369--material-ui-x.netlify.app/

These are the results for the performance tests:

Test case	Unit	Min	Max	Median	Mean	σ
Filter 100k rows	ms	631.3	1,069.8	639.7	788.88	180.138
Sort 100k rows	ms	669.7	1,005.5	737.8	837.76	132.147
Select 100k rows	ms	269.7	350.7	276	291.46	30.175
Deselect 100k rows	ms	189.5	218.8	195.1	199.52	10.211

Generated by 🚫 dangerJS against 7a32bc8

samuelsycamore · 2022-10-03T14:54:14Z

I went for Picker components as the title of the group instead of Pickers to be more explicit.

Why not simply "Components" for this section? This would match the pattern of the Core docs.

Also, given our recent discussions about formatting component names, I would expect these to be capitalized like proper nouns: Date Picker, Date Range Picker, etc.

flaviendelangle · 2022-10-03T15:06:39Z

Why not simply "Components" for this section? This would match the pattern of the Core docs.

Because it is only pickers (components with an input and a modal / popper).
The fields (only an input) would be in a different group (see #5565)

Unless we decide to put everything together but that's a lot of components.

samuelsycamore · 2022-10-03T15:16:09Z

Oh I see, I forgot about the original context for this. What about calling the section "Components" and then adding subheaders inside to organize the different kinds of components (like in the screenshot from your comment here)? I don't think it would be too many, especially when compared to Material UI for example which has 50+ pages in the "Components" section.

In general, I would prefer to try to follow the structure we're already using in the Core docs as best as we can, because I think it's safe to assume that most X users start with Core first, and so we should try to maintain continuity with regards to the overall experience to make the jump from one product to the next as smooth as possible.

flaviendelangle · 2022-10-04T05:41:13Z

@samuelsycamore another question if we do that: how do we avoid confusion between "Components" and "Custom components" ?

github-actions · 2022-10-10T06:39:29Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

github-actions · 2022-10-13T08:24:09Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

samuelsycamore · 2022-10-25T00:59:09Z

@samuelsycamore another question if we do that: how do we avoid confusion between "Components" and "Custom components" ?

I think the "Custom components" page should be renamed 😛 to make it more clear what's in that doc. I'm actually planning to create docs on this same info for the Core libraries, so I'll add that X page to that project.

As for the main topic, I see your point about going too deep with the groupings. I think the way you have it arranged here works well. 👍

joserodolfofreitas

I mean, users will click and know what's inside the menu, but I was wondering if "Picker components" doesn't lead to thinking that it's about the components used to build the pickers.

Another consideration: to establish a clear difference from the group of pickers that are coming soon (based on the new fields), would it make sense to rename this group and the next to something like:

=> Legacy Pickers
=> Next Pickers
=> Date and time fields
=> Custom sub-components

=> Masked Pickers
=> Pickers
=> Date and time fields
=> Custom sub-components

=> Masked Pickers
=> Rich keyboard Pickers
=> Rich keyboard Fields
=> Custom sub-components

flaviendelangle · 2022-10-26T10:18:15Z

I would avoid to use Masked Pickers because I think most people won't know what "masked" mean.

I would prefer Legacy Pickers / New Pickers, or event Legacy Pickers (v5) / New Pickers (v6) to be very explicit.

Renaming "Custom components" into "Custom sub-components" is fine for me, it think it makes it clear enough.

joserodolfofreitas · 2022-10-26T20:04:34Z

I would avoid to use Masked Pickers because I think most people won't know what "masked" mean.

I would prefer Legacy Pickers / New Pickers, or event Legacy Pickers (v5) / New Pickers (v6) to be very explicit.

Renaming "Custom components" into "Custom sub-components" is fine for me, it think it makes it clear enough.

Right.
One of my reasonings for trying to establish a clear difference based on how they work, is that we still need more community validation to "ditch" the pickers based on the masked approach.

oliviertassinari · 2022-10-30T12:06:55Z

I think that the first thing that developers will search for is the type of field that they need: time, date, date time, and only then they will consider the type of UX they need, standalone, keyboard only, integrated, mobile only.

So, I suspect that reversing the grouping could work better. I mean, this is how we structure the URLs/names already:

/x/react-date-pickers/date-field/
/x/react-date-pickers/date-picker/

flaviendelangle · 2022-10-31T07:06:44Z

You could go for the following ?

Date
- Date Field
- Date Picker
Time
- Time Field
- Time Picker
Date Time
- Date Time Field
- Date Time Picker
Date Range
- Date Range Field
- Date Range Picker
Time Range
- Time Range Field
- Time Range Picker
Date Time Range
- Date Time Range Field
- Date Time Range Picker

If so, I feel like it's a lot of folders and in the case I would indeed go with headers like @samuelsycamore proposed.

oliviertassinari · 2022-10-31T10:45:07Z

@flaviendelangle I was wondering about something like this indeed. I like the idea of Sam using the menu item subheaders to avoid too much nesting.

flaviendelangle · 2022-10-31T10:52:17Z

@oliviertassinari if we do that, where would you put the "Getting started" page of the field ?

oliviertassinari · 2022-10-31T13:56:40Z

@flaviendelangle I guess we could remove what is duplicated content with the other pages, move the content for advanced use cases to a guide, and move the introduction content to an overall pickers introduction page.

But I didn't/can't look close enough to judge whether this could be better. Take more this as an initial confusion of somebody (me) that isn't familiar with the evaluation of the component. I landed on https://deploy-preview-6369--material-ui-x.netlify.app/x/react-date-pickers/getting-started/ and wondered "wait, I'm looking for a date picker, no time, no ranges, where can I find this?" The docs felt a bit overwhelming. I like how https://reactdatepicker.com/ is simple, it shows the demos & code upfront rather than telling (they could tell more though, but after the demos).

github-actions · 2022-10-31T15:20:10Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

alexfauquette · 2022-11-15T10:33:39Z

docs/data/pages.ts

+      { pathname: '/x/react-date-pickers/validation' },
+      { pathname: '/x/react-date-pickers/localization' },
+      { pathname: '/x/react-date-pickers/fields', title: 'Keyboard editing' },


I'm wondering if those should not be on top of the components, because by priority of reading, I think it's:

Common usage (validation, localization)

Specific usage (Date picker special props)

Customization (slots)

components API

IMHO—the current order makes a tiny bit more sense.
From DX PoV I'd firstly be looking at which component to (can I) use. And only after that consider localisation and validation. 🤔

The only section to me that sounds and looks off is the Keyboard editing... 🙈

I think that we should either update the page title/contents a bit or use a different name.

Maybe going with Field components would make more sense?
And, IMO, this section could use a newFeature: true prop 🤔

With the new grouping by type, I feel like we are pushing the user to first find its component page and use it as the entry-point for the rest.

I don't think you come to the doc looking for information about the Localization / Validation before first checking how to use the component you need.

On nuance, the Localization pages will contain very basic topic on how to install and use the adapters after #6625 (which is probably even more early-stage in the user needs), but the needed sections will be linked from the getting started.

The only section to me that sounds and looks off is the Keyboard editing... see_no_evil

I think that we should either update the page title/contents a bit or use a different name.

Maybe going with Field components would make more sense? And, IMO, this section could use a newFeature: true prop thinking

@LukasTy

This page contains two quite different kind of content

Basic topics about what fields are. This could probably be moved to the Getting Started page on a new sections explaining that we have 3 type of components: the Pickers, the Fields and the Calendar / Clock. It could also be in a Components page that would be a summary of the available components if we feel that it's to much for the Getting Started/

Advanced topics (the current Advanced section)? This could be moved in an Advanced folder like on the grid with a Field behaviors page. Or if we don't want to create a folder, directly at the root.

I had to put the current page somewhere but I do agree that it is not great.
I can name it Field components (as the alpha only have power users who can take the time to look what "Field" mean) and work on a better split on a follow up PR.

Yes, I agree that we can simply name it Field components for now and re-work the whole structure and content in a follow-up PR leaving this one with single responsibility. 😉

LukasTy · 2022-11-15T12:32:16Z

docs/data/pages.ts

+      { pathname: '/x/react-date-pickers/validation' },
+      { pathname: '/x/react-date-pickers/localization' },
+      { pathname: '/x/react-date-pickers/fields', title: 'Keyboard editing' },


IMHO—the current order makes a tiny bit more sense.
From DX PoV I'd firstly be looking at which component to (can I) use. And only after that consider localisation and validation. 🤔

The only section to me that sounds and looks off is the Keyboard editing... 🙈

I think that we should either update the page title/contents a bit or use a different name.

Maybe going with Field components would make more sense?
And, IMO, this section could use a newFeature: true prop 🤔

oliviertassinari

It more clearly separates the MIT and Pro features, nice 👍

Off-topic

A few opportunities that I could notice while trying the preview link for how it feels to consume the docs:

The static mode isn't static, it forces the focus: https://deploy-preview-6369--material-ui-x.netlify.app/x/react-date-pickers/date-picker/. It's why the scroll bar is broken on this page when loading it. This happens on 4-5 of the pages. It makes it hard to read the docs.
We could disable the ads on some of the pages, e.g. https://deploy-preview-6369--material-ui-x.netlify.app/x/react-date-pickers/date-range-field/.
The live edit demo https://deploy-preview-6369--material-ui-x.netlify.app/x/react-date-pickers/localization/#date-library-locale is broken.

We need to update the logic in the docs-infra of how we extract imports. This https://github.com/mui/material-ui/blob/04d2a26389c8ca299d5d5ab18da3e95a506f7332/docs/packages/markdown/extractImports.js#L1 is too simple. It should be like https://github.com/mui/material-ui/blob/04d2a26389c8ca299d5d5ab18da3e95a506f7332/docs/src/modules/sandbox/Dependencies.ts#L117.
Now, it uses the v1 of the live edit, the v2 makes the demo work when no edits are done. So, the bug will be less visible. TL:DR updating the @mui/monorepo will fix a large chunk of the issue. cc @bharatkashyap if it's a problem you would enjoy working on.

flaviendelangle · 2022-11-15T19:41:58Z

@oliviertassinari
Concerning the dayjs error, #6625 should solve the issue
Could you confirm using the preview ?

[docs] Group picker pages

81911cf

flaviendelangle added docs Improvements or additions to the documentation component: pickers This is the name of the generic UI component, not the React module! labels Oct 3, 2022

flaviendelangle requested review from joserodolfofreitas and samuelsycamore October 3, 2022 13:12

flaviendelangle self-assigned this Oct 3, 2022

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

Work

3e18459

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

Prettier

07f3aab

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

Work

71aeed1

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

Work

10ebed9

joserodolfofreitas reviewed Oct 26, 2022

View reviewed changes

Merge branch 'next' into doc-group-pickers

fc55500

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

Merge

df38384

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

flaviendelangle requested review from joserodolfofreitas, LukasTy, oliviertassinari and alexfauquette November 15, 2022 08:13

alexfauquette reviewed Nov 15, 2022

View reviewed changes

LukasTy approved these changes Nov 15, 2022

View reviewed changes

oliviertassinari reviewed Nov 15, 2022

View reviewed changes

oliviertassinari mentioned this pull request Nov 16, 2022

[docs] Support demos with side effect imports mui/material-ui#35177

Merged

1 task

flaviendelangle added 2 commits November 17, 2022 13:19

Merge branch 'next' into doc-group-pickers

0819cc3

Code review: Lukas

7a32bc8

flaviendelangle requested review from alexfauquette and oliviertassinari November 17, 2022 12:20

joserodolfofreitas approved these changes Nov 17, 2022

View reviewed changes

flaviendelangle merged commit 2e54cb9 into mui:next Nov 17, 2022

flaviendelangle deleted the doc-group-pickers branch November 17, 2022 12:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Group picker pages #6369

[docs] Group picker pages #6369

flaviendelangle commented Oct 3, 2022 •

edited by oliviertassinari

Loading

mui-bot commented Oct 3, 2022 •

edited

Loading

samuelsycamore commented Oct 3, 2022

flaviendelangle commented Oct 3, 2022

samuelsycamore commented Oct 3, 2022 •

edited

Loading

flaviendelangle commented Oct 4, 2022

github-actions bot commented Oct 10, 2022

github-actions bot commented Oct 13, 2022

samuelsycamore commented Oct 25, 2022

joserodolfofreitas left a comment

flaviendelangle commented Oct 26, 2022 •

edited

Loading

joserodolfofreitas commented Oct 26, 2022 •

edited

Loading

oliviertassinari commented Oct 30, 2022 •

edited

Loading

flaviendelangle commented Oct 31, 2022

oliviertassinari commented Oct 31, 2022 •

edited

Loading

flaviendelangle commented Oct 31, 2022

oliviertassinari commented Oct 31, 2022 •

edited

Loading

github-actions bot commented Oct 31, 2022

alexfauquette Nov 15, 2022

LukasTy Nov 15, 2022

flaviendelangle Nov 17, 2022

flaviendelangle Nov 17, 2022 •

edited

Loading

LukasTy Nov 17, 2022

LukasTy Nov 15, 2022

oliviertassinari left a comment •

edited

Loading

flaviendelangle commented Nov 15, 2022

[docs] Group picker pages #6369

[docs] Group picker pages #6369

Conversation

flaviendelangle commented Oct 3, 2022 • edited by oliviertassinari Loading

Follow up

mui-bot commented Oct 3, 2022 • edited Loading

samuelsycamore commented Oct 3, 2022

flaviendelangle commented Oct 3, 2022

samuelsycamore commented Oct 3, 2022 • edited Loading

flaviendelangle commented Oct 4, 2022

github-actions bot commented Oct 10, 2022

github-actions bot commented Oct 13, 2022

samuelsycamore commented Oct 25, 2022

joserodolfofreitas left a comment

Choose a reason for hiding this comment

flaviendelangle commented Oct 26, 2022 • edited Loading

joserodolfofreitas commented Oct 26, 2022 • edited Loading

oliviertassinari commented Oct 30, 2022 • edited Loading

flaviendelangle commented Oct 31, 2022

oliviertassinari commented Oct 31, 2022 • edited Loading

flaviendelangle commented Oct 31, 2022

oliviertassinari commented Oct 31, 2022 • edited Loading

github-actions bot commented Oct 31, 2022

alexfauquette Nov 15, 2022

Choose a reason for hiding this comment

LukasTy Nov 15, 2022

Choose a reason for hiding this comment

flaviendelangle Nov 17, 2022

Choose a reason for hiding this comment

flaviendelangle Nov 17, 2022 • edited Loading

Choose a reason for hiding this comment

LukasTy Nov 17, 2022

Choose a reason for hiding this comment

LukasTy Nov 15, 2022

Choose a reason for hiding this comment

oliviertassinari left a comment • edited Loading

Choose a reason for hiding this comment

flaviendelangle commented Nov 15, 2022

flaviendelangle commented Oct 3, 2022 •

edited by oliviertassinari

Loading

mui-bot commented Oct 3, 2022 •

edited

Loading

samuelsycamore commented Oct 3, 2022 •

edited

Loading

flaviendelangle commented Oct 26, 2022 •

edited

Loading

joserodolfofreitas commented Oct 26, 2022 •

edited

Loading

oliviertassinari commented Oct 30, 2022 •

edited

Loading

oliviertassinari commented Oct 31, 2022 •

edited

Loading

oliviertassinari commented Oct 31, 2022 •

edited

Loading

flaviendelangle Nov 17, 2022 •

edited

Loading

oliviertassinari left a comment •

edited

Loading