Skip to content

Commit 7c96b79

Browse files
[docs] Various documentation improvements (mui#9403)
1 parent a4e922c commit 7c96b79

File tree

29 files changed

+262
-278
lines changed

29 files changed

+262
-278
lines changed

.flowconfig

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ module.file_ext=.js
2828
module.file_ext=.md
2929
module.name_mapper='.*\.\(html\|css\|svg\|png\|jpg\|gif\)$' -> '<PROJECT_ROOT>/flow/stubs/url-loader.js'
3030
module.name_mapper='^material-ui\/\(.*\)$' -> '<PROJECT_ROOT>/src/\1'
31-
module.name_mapper='^material-ui-docs\/\(.*\)$' -> '<PROJECT_ROOT>/docs/\1'
3231
module.name_mapper='^material-ui-icons\/\(.*\)$' -> '<PROJECT_ROOT>/packages/material-ui-icons/src/\1'
3332

3433
module.ignore_non_literal_requires=true

.github/ISSUE_TEMPLATE.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,27 +9,27 @@
99
- [ ] I have searched the [issues](https://github.com/mui-org/material-ui/issues) of this repository and believe that this is not a duplicate.
1010

1111
## Expected Behavior
12-
<!---
12+
<!---
1313
If you're describing a bug, tell us what should happen.
14-
If you're suggesting a change/improvement, tell us how it should work.
14+
If you're suggesting a change/improvement, tell us how it should work.
1515
-->
1616

1717
## Current Behavior
18-
<!---
18+
<!---
1919
If describing a bug, tell us what happens instead of the expected behavior.
20-
If suggesting a change/improvement, explain the difference from current behavior.
20+
If suggesting a change/improvement, explain the difference from current behavior.
2121
-->
2222

2323
## Steps to Reproduce (for bugs)
24-
<!---
25-
Provide a link to a live example (you can use codesandbox.io) and an unambiguous set of steps to reproduce this bug.
26-
Include code to reproduce, if relevant (which it most likely is).
24+
<!---
25+
Provide a link to a live example (you can use codesandbox.io) and an unambiguous set of steps to reproduce this bug.
26+
Include code to reproduce, if relevant (which it most likely is).
2727
28-
This codesandbox.io template _may_ be a good starting point:
28+
This codesandbox.io template _may_ be a good starting point:
2929
https://codesandbox.io/s/github/mui-org/material-ui/tree/v1-beta/examples/create-react-app
3030
3131
32-
If YOU DO NOT take time to provide a codesandbox.io reproduction, should the COMMUNITY take time to help you?
32+
If YOU DO NOT take time to provide a codesandbox.io reproduction, should the COMMUNITY take time to help you?
3333
3434
-->
3535

@@ -39,10 +39,10 @@
3939
4.
4040

4141
## Context
42-
<!---
43-
How has this issue affected you? What are you trying to accomplish?
42+
<!---
43+
How has this issue affected you? What are you trying to accomplish?
4444
Providing context helps us come up with a solution that is most useful in the real world.
45-
-->
45+
-->
4646

4747
## Your Environment
4848
<!--- Include as many relevant details about the environment with which you experienced the bug. -->

.gitignore

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ node_modules
2020
package-lock.json
2121
*.log
2222

23-
# Editor files
23+
# The best pattern people should follow is ignoring the editors' files in their
24+
# global .gitignore configuration file.
25+
# However, in order to prevent issues. We also ignore editors' files here.
2426
.idea
2527
.vscode
26-

CHANGELOG.md

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Changes. Changes everywhere!
99

1010
- [TextField] Input/TextField API disamiguation/consistency (#9382) @rosskevin
1111

12-
Some of the convenience properties exposed were confusing and have been removed (`inputProps | InputClassName`). For advanced configuration
12+
Some of the convenience properties exposed were confusing and have been removed (`inputProps | InputClassName`). For advanced configuration
1313
any `Input` through `TextField`, use `TextField.InputProps` to pass any property accepted by the `Input`.
1414

1515

@@ -29,6 +29,13 @@ Here are some highlights ✨:
2929
### Breaking change
3030

3131
- [Select] Remove InputClasses (#9159) @oliviertassinari
32+
It's a revert. I have made the unwise call of adding the InputClasses property in an unrelated refactorization pull-request #8942. It was not taking the input classes property into account. It was a breaking change and not needed.
33+
- [core] Reduce bundle size by 2kB gzipped (#9129) @oliviertassinari
34+
We have removed some jss plugins from the default bundle:
35+
- [jss-expand](https://github.com/cssinjs/jss-expand) (1.3 kB)
36+
- [jss-compose](https://github.com/cssinjs/jss-compose) (426 B)
37+
- [jss-extend](https://github.com/cssinjs/jss-extend) (702 B)
38+
- [jss-template](https://github.com/cssinjs/jss-template) (330 B)
3239

3340
It's a revert.
3441
I have made the unwise call of adding the InputClasses property in an unrelated refactorization pull-request #8942.
@@ -1613,7 +1620,7 @@ You now have two way to customize absolutely all the CSS injected by Material-UI
16131620
Either the instance level with the `classes` property or the class level with the
16141621
`overrides` theme property.
16151622

1616-
To [learn more about it](https://material-ui-next.com/customization/overrides), have a look at the documentation. Also, these options are automatically [documented](http://0.0.0.0:3000/component-api/button#classes).
1623+
To learn more about it, have a look at the documentation.
16171624

16181625
### Breaking changes
16191626

README.md

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,13 @@ that you can use to tag your questions.
88

99
# [Material-UI@v1-beta](https://material-ui-next.com/)
1010
[![npm package](https://img.shields.io/npm/v/material-ui/next.svg)](https://www.npmjs.org/package/material-ui)
11+
[![npm download](https://img.shields.io/npm/dm/material-ui.svg)](https://www.npmjs.org/package/material-ui)
1112
[![CircleCI](https://img.shields.io/circleci/project/github/mui-org/material-ui/v1-beta.svg)](https://circleci.com/gh/mui-org/material-ui/tree/v1-beta)
1213
[![Gitter](https://img.shields.io/badge/gitter-join%20chat-f81a65.svg)](https://gitter.im/callemall/material-ui?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
1314
[![Coverage Status](https://img.shields.io/codecov/c/github/mui-org/material-ui/v1-beta.svg)](https://codecov.io/gh/mui-org/material-ui/branch/v1-beta)
1415
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1320/badge)](https://bestpractices.coreinfrastructure.org/projects/1320)
16+
![Code style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)
17+
[![Follow on Twitter](https://img.shields.io/twitter/follow/MaterialUI.svg?label=follow+Material-UI)](https://twitter.com/MaterialUI)
1518

1619
[![PeerDependencies](https://img.shields.io/david/peer/mui-org/material-ui.svg)](https://david-dm.org/mui-org/material-ui#info=peerDependencies&view=list)
1720
[![Dependencies](https://img.shields.io/david/mui-org/material-ui.svg)](https://david-dm.org/mui-org/material-ui)
@@ -30,19 +33,19 @@ Material-UI is available as an [npm package](https://www.npmjs.org/package/mater
3033

3134
**Stable channel**
3235
```sh
33-
npm install material-ui
36+
npm install --save material-ui
3437
```
3538

3639
**Pre-release channel**
3740
```sh
38-
npm install material-ui@next
41+
npm install --save material-ui@next
3942
```
4043

4144
Please note that `@next` will only point to pre-releases; to get the latest stable release use `@latest` instead.
4245

4346
## Usage
4447

45-
Here is a quick example to get you started, it's all you need:
48+
Here is a quick example to get you started, **it's all you need**:
4649

4750
```jsx
4851
import React from 'react';
@@ -60,6 +63,10 @@ function App() {
6063
render(<App />, document.querySelector('#app'));
6164
```
6265

66+
Yes, it's really all you need to get started as you can see in this live and interactive demo:
67+
68+
[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/4j7m47vlm4)
69+
6370
## Examples
6471

6572
Are you looking for an example project to get started?

ROADMAP.md

Lines changed: 19 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,28 @@
22

33
The roadmap is a living document, and it is likely that priorities will change, but the list below should give some indication of our plans for the next major release, and for the future.
44

5-
⚠️ New features based on `v0.19.x` have low priority and will most likely not be reviewed nor merged. We want to focus on bug fixes.
6-
75
## Version 1 (published on NPM under the `next` tag)
86

9-
Version 1 release is going to be huge ✨.
10-
We host a temporary [documentation site](https://material-ui-next.com) for the pre-releases.
7+
Releasing stable v1 is our top priority. It's going to be huge ✨.
8+
We are just at the beginning, we hope to make it:
9+
- the **simplest** React UI library available for new Front-End developers to start with.
10+
- **very customizable** so highly UI demanding production applications can save time building on top of it.
1111

1212
Material-UI was started [3 years ago](https://github.com/mui-org/material-ui/commit/28b768913b75752ecf9b6bb32766e27c241dbc46).
1313
The ecosystem has evolved a lot since then, we have also learned a lot.
1414
[@nathanmarks](https://github.com/nathanmarks/) started an ambitious task, rebuilding Material-UI from the **ground-up**
1515
taking advantage of this knowledge to address long-standing issues.
1616
Expect various **breaking changes**.
1717

18-
The core team is now helping him in the [v1-beta](https://github.com/mui-org/material-ui/tree/v1-beta) branch.
18+
The core team has been dedicated to the rewrite effort for one and a half years.
1919
If you are interested in following our progress or if you want to help us reach that goal faster, you can have a look at the following milestones:
20-
- ~~[v1.0.0-beta](https://github.com/mui-org/material-ui/milestone/22)~~ - complete!
20+
- ~~[v1.0.0-beta](https://github.com/mui-org/material-ui/milestone/22?closed=1)~~ - reached!
2121
- [v1.0.0-prerelease](https://github.com/mui-org/material-ui/milestone/14)
22+
- [v1.0.0](https://github.com/mui-org/material-ui/milestone/23)
2223

2324
## Q&A with the v1 version
2425

25-
The `v1-beta` branch has become more mature, so we think that it's a good time to communicate more on this effort.
26-
We have a lot of people opening PRs and getting them closed, this is not a good thing.
27-
This Q&A tries to answer some of your questions.
26+
The v1-beta version has matured, so we think that it's time to communicate more on this effort. The following Q&A is an attempt at answering some of your questions.
2827

2928
### Summarizing, what are our main problems with CSS?
3029

@@ -58,50 +57,21 @@ Computing the inline-style at each render with no caching isn't really efficient
5857

5958
Yes, it does. You can have a look at [this presentation](https://github.com/oliviertassinari/a-journey-toward-better-style) for more details.
6059

61-
## What does it mean to migrate a component? Should we discuss each one of them first?
62-
63-
Migrating a component to the `v1-beta` branch isn't just a style migration.
64-
We think that it's our best opportunity to clear the API and improve the implementation of the components.
65-
@nathanmarks ended up fixing a lot of long standing issues in the process.
66-
67-
Yes, it would much better to discuss an action plan for each of them that would save us considerable time compared to blindly following a wrong path.
68-
We should answer the following questions:
69-
- What will the API look like?
70-
- What trade-offs are we going to make?
71-
- What features will be implemented?
72-
73-
That conversation could start on one of the following [issues](https://github.com/mui-org/material-ui/issues?q=is%3Aissue+is%3Aopen+label%3ARefactoring+label%3Anext).
74-
75-
### How do I know if a component still needs to be migrated `v1-beta`?
76-
77-
We have [some open issues](https://github.com/mui-org/material-ui/issues?q=is%3Aopen+is%3Aissue+label%3ARefactoring+label%3Av1) to **coordinate** the work toward the `v1.0.0` release.
78-
79-
### How do I start migrating components to the `v1-beta` branch?
80-
81-
Once we agree on the migration plan you're going to have to get your hands dirty.
82-
That's really up to you. At least, you going to have to:
83-
- clone the `v1-beta` branch
84-
- install the npm dependencies
85-
- play with the documentation site
86-
- write some documentation
87-
- write some tests (unit, integration, visual)
88-
89-
### When do we intend to release `v1`?
60+
### When do we intend to release stable v1?
9061

91-
We don't have an ETA for the release of the `v1`, however, we are going to try to follow this plan:
62+
We don't have an ETA for the release of the `v1`, however, we are going to try to follow this plan and hope for a Q1-Q2 2018 release:
9263

9364
1. ~~We completely address the styling issue before moving from *alpha* to [*beta*](https://github.com/mui-org/material-ui/milestone/22).~~
9465
2. ~~We publish our first beta releases.~~
95-
3. We fix the last API inconsistencies (as we can make breaking changes without having to worry much).
96-
4. We merge the beta branch into master
66+
3. We merge the v1-beta branch into master
9767
5. We publish our first pre-releases, if all goes well, we move to the next step.
9868
6. We publish v1 🎉
9969

100-
At that point, some features and components from the v0.x will be missing in the v1.
70+
At that point, some features and components from Material-UI v0.x will be missing in the v1.
10171
So, what about them?
10272
- First, both versions can be used at the same time, people can progressively migrate, one component at the time.
10373
- Then, **with the help of the community** and over time, we will support more and more components.
104-
- We would rather **support few use-cases very well and allow people to build on top of it** than many poorly.
74+
- We would rather **support few use-cases very well** and allow people to build on top of it **than many poorly**.
10575

10676
### Have we ever considered using the best libraries for each piece of functionality and provide only a wrapper for the UI?
10777

@@ -117,8 +87,10 @@ We think that it should be done the other way around, i.e. providing a low-level
11787

11888
On the other hand, using a smart date library for the DatePicker / TimePicker would probably be much better as date management is tricky and not a core business.
11989

120-
## Future
90+
## After stable v1
12191

122-
- Add missing components, and missing features from current ones
123-
- [[#7721](https://github.com/mui-org/material-ui/issues/7721)] Preact support
124-
- [[#593](https://github.com/mui-org/material-ui/issues/593)] Support React Native
92+
- **Theming**. We will invest in the theming solution. We would love to see **non Material Design UI** built with Material-UI. [@oliviertassinari](https://github.com/oliviertassinari/) is working on a proof of concept.
93+
- **Type checking**. We need to improve TypeScript and Flow coverage of the library.
94+
- **Bundle size**. We need the library to be as small as possible. We already monitor the bundle size with size-limit. We need to think of the solutions. For instance, supporting preact can help.
95+
- **Performance**. We can't optimize something we can't measure. We don't have any CI performance benchmark. We will need to build one and start investigating bottlenecks.
96+
- **Learning materials**. The documentation is equally as important as the quality of the implementation. We could be authoring a [learning tutorial](https://learnnextjs.com/) like Next.js is doing, or some [egghead.io](https://egghead.io/) courses.

docs/src/modules/components/AppDrawerNavItem.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ const styles = theme => ({
3636
},
3737
navLinkButton: {
3838
color: theme.palette.text.secondary,
39-
textIndent: theme.spacing.unit * 3,
39+
paddingLeft: theme.spacing.unit * 5,
4040
fontSize: theme.typography.pxToRem(13),
4141
},
4242
activeButton: {

docs/src/modules/components/AppWrapper.js

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import getContext, { getTheme } from 'docs/src/modules/styles/getContext';
99
import JssProvider from 'react-jss/lib/JssProvider';
1010
import AppFrame from 'docs/src/modules/components/AppFrame';
1111
import { lightTheme, darkTheme, setPrismTheme } from 'docs/src/modules/utils/prism';
12-
import config from 'docs/src/config';
12+
import GoogleTag from 'docs/src/modules/components/GoogleTag';
1313

1414
// Inject the insertion-point-jss after docssearch
1515
if (process.browser && !global.__INSERTION_POINT__) {
@@ -43,13 +43,6 @@ class AppWrapper extends React.Component<any, any> {
4343
if (document.body) {
4444
document.body.dir = this.props.uiTheme.direction;
4545
}
46-
47-
// Wait for the title to be updated.
48-
this.googleTimer = setTimeout(() => {
49-
window.gtag('config', config.google.id, {
50-
page_path: window.location.pathname,
51-
});
52-
});
5346
}
5447

5548
componentWillReceiveProps(nextProps) {
@@ -71,12 +64,7 @@ class AppWrapper extends React.Component<any, any> {
7164
}
7265
}
7366

74-
componentWillUnmount() {
75-
clearTimeout(this.googleTimer);
76-
}
77-
7867
styleContext = null;
79-
googleTimer = null;
8068

8169
render() {
8270
const { children, sheetsRegistry } = this.props;
@@ -92,6 +80,7 @@ class AppWrapper extends React.Component<any, any> {
9280
sheetsManager={this.styleContext.sheetsManager}
9381
>
9482
<AppFrame>{children}</AppFrame>
83+
<GoogleTag />
9584
</MuiThemeProvider>
9685
</JssProvider>
9786
);
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import React from 'react';
2+
import config from 'docs/src/config';
3+
4+
class GoogleTag extends React.Component {
5+
componentDidMount() {
6+
// Wait for the title to be updated.
7+
this.googleTimer = setTimeout(() => {
8+
window.gtag('config', config.google.id, {
9+
page_path: window.location.pathname,
10+
});
11+
});
12+
}
13+
14+
componentWillUnmount() {
15+
clearTimeout(this.googleTimer);
16+
}
17+
18+
googleTimer = null;
19+
20+
render() {
21+
return null;
22+
}
23+
}
24+
25+
export default GoogleTag;

0 commit comments

Comments
 (0)