[Doc] Improve left navigation on PageWithNav component

[newoga]

Just following up on discussion from #2421:

@oliviertassinari had the following suggestions:

I just had another idea. I don't know if you are going to like it.
I think that we should group component by type. For instance, we could create a Form group
with the SelectField and the TextField. In this case, Using a List may be more appropriate.
Similary to what google is doing with the material LeftNav https://www.google.com/design/spec/components/tabs.html.
I also think that this left panel should be in a LeftNav, again, using a List over a Menu would probably makes more sens 😁.

Let me know if you want me to give this a go.

[alitaheri]

@newoga We need proposal for how they will be organized. Can you come up with something?

@oliviertassinari Now that we are doing this, should we divide some pages so that each page only document very tightly coupled components instead of similar components. like, toolbar remains as is but Icons get separated into FontIcon and SvgIcon under Icons category.

[newoga]

Sure, I can whip up some thoughts/ideas.

[oliviertassinari]

Icons get separated into FontIcon and SvgIcon under Icons category

That sounds like a great idea.

The goal behind using the LeftNav would be to make the navigation simpler on a mobile phone.
I want to use the documentation as a starting point to support react-native.
We can use this https://github.com/binggg/MaterialReactNative as a source of inspiration.

[newoga]

Okay, these are my thoughts. They may not be popular and I think it's something worth discussing more, but here we go...

1. Reorganize our Component list to closely follow the Component list from Material Design spec

I think this would be a big win. It will encourage contributors and end-user developers that aren't familiar with the spec to become familiar with the spec, and those that are familiar with the spec to feel right at home.

We could go for something like this:

+-- Getting Started
|   +-- Prerequisites
|   +-- Installation and Usage
|   +-- Examples
+-- Customization
|   +-- Themes
|   +-- Inline Styles
|   +-- Colors
+-- Components
|   +-- Buttons
|      +-- Floating action button
|      +-- Raised button
|      +-- Flat button
|   +-- Cards
|   +-- Data tables
|   +-- Dialogs
|      +-- Simple Dialogs
|   +-- Grid lists
|   +-- Icons
|      +-- FontIcon
|      +-- SvgIcon
|   +-- Lists
|      +-- List
|      +-- List controls
|   +-- Menus
|      +-- Simple menu
|      +-- Menu controls
|      +-- Cascading menus
|   +-- Pickers
|      +-- Date pickers
|      +-- Time pickers
|   +-- Progress and activity
|      +-- Linear progress
|      +-- Circular progress
|   +-- Selection controls
|      +-- Checkbox
|      +-- Radio button
|      +-- Switch
|   +-- Sliders
|      +-- Continuous slider
|   +-- Snackbars & toasts 
|   +-- Tabs
|   +-- Text fields
|      +-- Text field
|      +-- Dropdown
|   +-- Toolbars
|      +-- AppBar
|      +-- Toolbar
+-- Resources
|   +-- Github
|   +-- Material Design Spec
--

I recommend that each top level has an overview page, maybe with a link to the spec. For example:

|   +-- Buttons
|      +-- Floating action button 
|      +-- Raised button
|      +-- Flat button
--

Each of the three button types would have their own page, and the category Buttons itself would have an overview page that would be an react-router <IndexRoute /> to /components/buttons.

Note: Theses pages are meant to be component guides, not necessarily API documentation. They are examples of how to use the existing components to implement material design behavior. For documentation on each of the types and their props, events, etc. we should have an API reference, which leads us to...

2. Consider having separate API reference from Components guide

We currently don't have 1-to-1 mapping between material design components and material-ui components. And even though it may be something to strive for, I think it will simply be impossible or impractical. For example, things like tool tips are easier to implement as props of other components and may never really need a publicly exposed React component.

Because of this, it might be nice to have a collapsable API reference that in one flat list shows all the exported Components, regardless of how they were designed to be used.

/* Sample list */
+-- API Reference 
|   +-- <AppBar />
|   +-- <FloatingActionButton />
|   +-- <RaisedButton />
|   +-- <FlatButton />
|   +-- <Menu />
|   +-- <MenuItem />

Notice Menu and MenuItem are not cascaded. This is meant to be used by a developer who knows what they are looking and wants a reference. Links to source code might be useful on these pages.

Note: This is actually how it is done at https://material.angularjs.org/. They have a separate Demos section that would similar to our Component guide and a separate API reference.

3. Implement side navigation content as <SelectableList />

Doing this we should be able to properly categorize components, but still support showing an 'Active' item based on the route.

4. Reimplement side navigation as a <LeftNav /> component

Right now we technically have two side navigations:

1. The first one is implemented as a <Menu /> is always open on left side on desktop, and then moves to the bottom on small devices
2. The second one is available for display on small devices only when the "app bar" icon is clicked.

The two navigations currently do not have the same content.

For now, I recommend that we make a single <LeftNav /> that behaves like the second one now, and put the single route hierarchy on the navigation.

5. Find a way to make a second side navigation visible on desktop

In desktop experiences, I think it would be nice to have the side menu shown by default, and collapses when the resolution is small enough.

An example of this is how Google+ currently works. It is currently also implemented here:
https://material.angularjs.org (just try resizing your browser to see)

6. Consider adding pages for missing components to encourage community contributions

Going through the spec site in more detail, I notice that the project's coverage for spec components is pretty good! I think it may make sense to add options for the missing components even if it just takes you to a page that says something to the sort of: Not yet implemented, follow progress at issue #{github_issue}.

7. For future consideration: Rename components that do not match specification

Many of these components we may be able to just alias or export under a different name to maintain backwards compatibilty until we can remove the old on all together.

Some of the ones I've noticed so far:

1. Toggle -> Switch
2. Table -> DataTable
3. Dropdown Menu, Select Field -> Dropdown

[oliviertassinari]

@newoga Wow, that's really interesting!

[alitaheri]

@newoga Wow indded! You sure spend a lot of time authoring very well structured comments 👍 👍 Give us some time to read and provide feedback. Thanks a lot 😁

[newoga]

No problem! 😃

[alitaheri]

@newoga I can't disagree with any one bit of this. You did good 👍 👍

• Structure 👍
• Separate API Reference 👍
• Using SelectableList 👍
• Using LeftNav 👍
• Make LeftNav visible on desktop by default 👍 But this still has limitations, because we should provide functionality for it to push the content of the page when it opens for desktop. A feature that is requested by many.
• Pages for missing components 👍 👍
• Follow spec more closely 👍

Great job. Now, the first step would be to make that structure.
Then we will have to figure out a way to decouple pages from API reference.

[newoga]

Great! That's a lot of 👍 ! 😄

I'm glad it looks like we're going in the right direction. I can start a branch and start implementing some of the simpler items.

@oliviertassinari, let me know if thoughts or concerns!

[oliviertassinari]

I must say, I agree with all your points!
That's gonna make the doc a lot better and increase our credibility. You could also add a showcase section at some point.

We can also ask callemall @shaurya947 and @hai-cea since they build the doc in the first place.

[oliviertassinari]

@newoga I'm working on the depreciation of the old menu. Hence, I have started 1/ but using List over Menu. stay tuned.

[newoga]

@oliviertassinari , Sounds good to me. Staying tuned!

[oliviertassinari]

Here it's #2443

[mbrookes]

@newoga - is there more left to do for this do you think?

[newoga]

@mbrookes I think we completed the majority of this. The remaining items are probably debatable. I still think an API reference separate from the component guide would be nice but we made enough improvements where this doesn't have to be prioritized anymore.

I'll let you decide what you want to do with this issue 😄

[oliviertassinari]

4 months ago

A lot has been done in 4 months :D. This issue gaved us a good direction 👍.

We haven't done things exactly as they are discribed here.
I think that we can close it. We could open new issues for anything missing.

[mbrookes]

I've extracted the couple of areas that are still up for discussion to separate issues.