Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs] Fix various issues with heading structure #20389

Merged
merged 4 commits into from
Apr 6, 2020
Merged

[docs] Fix various issues with heading structure #20389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a638cd5
[docs] Improve heading structure
eps1lon Apr 2, 2020
7dd73f0
[docs] Fix incorrect heading structure for /styles/api
eps1lon Apr 2, 2020
e2c371c
[docs] Reduce /customization/breakpoints demos
eps1lon Apr 2, 2020
f5f8f87
[docs] Improve a11y story of /customization/color#color-tool
eps1lon Apr 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/pages/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ export default function LandingPage() {
>
{'MATERIAL-UI'}
</Typography>
<Typography variant="h5" component="h2" color="inherit">
<Typography variant="h5" component="p" color="inherit">
{t('strapline')}
</Typography>
<Button
Expand Down
6 changes: 3 additions & 3 deletions docs/src/pages/customization/breakpoints/MediaQuery.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ export default function MediaQuery() {
const classes = useStyles();
return (
<div className={classes.root}>
<Typography variant="subtitle1">{'down(sm): red'}</Typography>
<Typography variant="subtitle1">{'up(md): blue'}</Typography>
<Typography variant="subtitle1">{'up(lg): green'}</Typography>
<Typography>{'down(sm): red'}</Typography>
<Typography>{'up(md): blue'}</Typography>
<Typography>{'up(lg): green'}</Typography>
</div>
);
}
6 changes: 3 additions & 3 deletions docs/src/pages/customization/breakpoints/MediaQuery.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ export default function MediaQuery() {
const classes = useStyles();
return (
<div className={classes.root}>
<Typography variant="subtitle1">{'down(sm): red'}</Typography>
<Typography variant="subtitle1">{'up(md): blue'}</Typography>
<Typography variant="subtitle1">{'up(lg): green'}</Typography>
<Typography>{'down(sm): red'}</Typography>
<Typography>{'up(md): blue'}</Typography>
<Typography>{'up(lg): green'}</Typography>
</div>
);
}
2 changes: 1 addition & 1 deletion docs/src/pages/customization/breakpoints/WithWidth.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ function WithWidth(props) {
const Component = components[width] || 'span';

return (
<Typography variant="subtitle1">
<Typography>
<Component>{`Current width: ${width}`}</Component>
</Typography>
);
Expand Down
2 changes: 1 addition & 1 deletion docs/src/pages/customization/breakpoints/WithWidth.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ function WithWidth(props: { width: Breakpoint }) {
const Component = components[width] || 'span';

return (
<Typography variant="subtitle1">
<Typography>
<Component>{`Current width: ${width}`}</Component>
</Typography>
);
Expand Down
2 changes: 1 addition & 1 deletion docs/src/pages/customization/color/ColorDemo.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ function ColorDemo(props) {
>
<MenuIcon />
</IconButton>
<Typography variant="h6" color="inherit">
<Typography component="div" variant="h6" color="inherit">
Color
</Typography>
</Toolbar>
Expand Down
12 changes: 2 additions & 10 deletions docs/src/pages/customization/color/ColorTool.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,18 +186,10 @@ function ColorTool(props) {

return (
<Grid item xs={12} sm={6} md={4}>
<Typography gutterBottom variant="h6">
<Typography component="label" gutterBottom htmlFor={intent} variant="h6">
{capitalize(intent)}
</Typography>
<Input
id={intent}
value={intentInput}
onChange={handleChangeColor(intent)}
inputProps={{
'aria-label': `${capitalize(intent)} color`,
}}
fullWidth
/>
<Input id={intent} value={intentInput} onChange={handleChangeColor(intent)} fullWidth />
<div className={classes.sliderContainer}>
<Typography id={`${intent}ShadeSliderLabel`}>Shade:</Typography>
<Slider
Expand Down
4 changes: 2 additions & 2 deletions docs/src/pages/landing/Steps.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ function HomeSteps() {
<Grid item xs={12} md={6} className={clsx(classes.step, classes.leftStep)}>
<div className={classes.stepTitle}>
<FileDownloadIcon className={classes.stepIcon} />
<Typography variant="h6" component="h3">
<Typography variant="h6" component="h2">
{t('installation')}
</Typography>
</div>
Expand Down Expand Up @@ -132,7 +132,7 @@ $ npm install @material-ui/core
<Grid item xs={12} md={6} className={clsx(classes.step, classes.rightStep)}>
<div className={classes.stepTitle}>
<BuildIcon className={classes.stepIcon} />
<Typography variant="h6" component="h3">
<Typography variant="h6" component="h2">
{t('usage')}
</Typography>
</div>
Expand Down
48 changes: 24 additions & 24 deletions docs/src/pages/styles/api/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,18 @@

A function which returns [a class name generator function](https://cssinjs.org/jss-api/#generate-your-class-names).

#### Arguments
### Arguments
Copy link
Member

@oliviertassinari oliviertassinari Apr 2, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The motivation was to remove these values from the table of contents to make it easier to navigate. What about?

Suggested change
### Arguments
**Arguments**

Copy link
Member Author

@eps1lon eps1lon Apr 2, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do you want them removed from the TOC? There obviously a sub-item of the method.

Copy link
Member

@oliviertassinari oliviertassinari Apr 2, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think of the difference of experience between

A.
Capture d’écran 2020-04-02 à 18 56 31
…

more content truncated

B.
Capture d’écran 2020-04-02 à 18 56 40

Are "Arguments", "Returns", "Example" important enough to be included in the TOCs? It comes with the assumption that the longest the TOCs is, the harder it's to scan and find interesting content.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On a side note, the change goes against the other header structure in the documentation. So far The #### Arguments level was used exclusively. It would be awesome to uniformized it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not able to follow. You obviously want to group the content and describe it with a single word. That is a heading. Not sure what we're discussing here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be awesome to uniformized it.

I was wrong, the header structure in the other pages that have Arguments as a header already have a continuous <hx> structure.


1. `options` (*Object* [optional]):
- `options.disableGlobal` (*Boolean* [optional]): Defaults to `false`. Disable the generation of deterministic class names.
- `options.productionPrefix` (*String* [optional]): Defaults to `'jss'`. The string used to prefix the class names in production.
- `options.seed` (*String* [optional]): Defaults to `''`. The string used to uniquely identify the generator. It can be used to avoid class name collisions when using multiple generators in the same document.

#### Returns
### Returns

`class name generator`: The generator should be provided to JSS.

#### Examples
### Examples

```jsx
import React from 'react';
Expand All @@ -40,15 +40,15 @@ This function doesn't really "do anything" at runtime, it's just the identity
function. Its only purpose is to defeat **TypeScript**'s type widening when providing
style rules to `makeStyles`/`withStyles` which are a function of the `Theme`.

#### Arguments
### Arguments

1. `styles` (*Function | Object*): A function generating the styles or a styles object.

#### Returns
### Returns

`styles`: A function generating the styles or a styles object.

#### Examples
### Examples

```jsx
import { makeStyles, createStyles } from '@material-ui/core/styles';
Expand All @@ -69,7 +69,7 @@ export default function MyComponent {

Link a style sheet with a function component using the **hook** pattern.

#### Arguments
### Arguments

1. `styles` (*Function | Object*): A function generating the styles or a styles object.
It will be linked to the component.
Expand All @@ -80,13 +80,13 @@ Use the function signature if you need to have access to the theme. It's provide
- `options.flip` (*Boolean* [optional]): When set to `false`, this sheet will opt-out the `rtl` transformation. When set to `true`, the styles are inversed. When set to `null`, it follows `theme.direction`.
- The other keys are forwarded to the options argument of [jss.createStyleSheet([styles], [options])](https://cssinjs.org/jss-api/#create-style-sheet).

#### Returns
### Returns

`hook`: A hook. This hook can be used in a function component. The documentation often calls this returned hook `useStyles`.
It accepts one argument: the properties that will be used for "interpolation" in
the style sheet.

#### Examples
### Examples

```jsx
import React from 'react';
Expand Down Expand Up @@ -155,7 +155,7 @@ The method is an alternative to `.toString()` when you are rendering the whole p

Link a style sheet with a function component using the **styled components** pattern.

#### Arguments
### Arguments

1. `Component`: The component that will be wrapped.
2. `styles` (*Function | Object*): A function generating the styles or a styles object.
Expand All @@ -169,11 +169,11 @@ Use the function signature if you need to have access to the theme. It's provide
- `options.flip` (*Boolean* [optional]): When set to `false`, this sheet will opt-out the `rtl` transformation. When set to `true`, the styles are inversed. When set to `null`, it follows `theme.direction`.
- The other keys are forwarded to the options argument of [jss.createStyleSheet([styles], [options])](https://cssinjs.org/jss-api/#create-style-sheet).

#### Returns
### Returns

`Component`: The new component created.

#### Examples
### Examples

```jsx
import React from 'react';
Expand Down Expand Up @@ -204,7 +204,7 @@ This component allows you to change the behavior of the styling solution. It mak

It should preferably be used at **the root of your component tree**.

#### Props
### Props

| Name | Type | Default | Description |
|:-----|:-----|:--------|:------------|
Expand All @@ -214,7 +214,7 @@ It should preferably be used at **the root of your component tree**.
| injectFirst | bool | false | By default, the styles are injected last in the `<head>` element of the page. As a result, they gain more specificity than any other style sheet. If you want to override Material-UI's styles, set this prop. |
| jss | object | | JSS's instance. |

#### Examples
### Examples

```jsx
import React from 'react';
Expand All @@ -235,14 +235,14 @@ ReactDOM.render(<App />, document.querySelector('#app'));
This component takes a `theme` property, and makes it available down the React tree thanks to the context.
It should preferably be used at **the root of your component tree**.

#### Props
### Props

| Name | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| children&nbsp;* | node | | Your component tree. |
| theme&nbsp;* | union:&nbsp;object&nbsp;&#124;&nbsp;func | | A theme object. You can provide a function to extend the outer theme. |

#### Examples
### Examples

```jsx
import React from 'react';
Expand All @@ -264,11 +264,11 @@ ReactDOM.render(<App />, document.querySelector('#app'));

This hook returns the `theme` object so it can be used inside a function component.

#### Returns
### Returns

`theme`: The theme object previously injected in the context.

#### Examples
### Examples

```jsx
import React from 'react';
Expand All @@ -294,7 +294,7 @@ Some implementation details that might be interesting to being aware of:
- It does **not** copy over statics.
For instance, it can be used to defined a `getInitialProps()` static method (next.js).

#### Arguments
### Arguments

1. `styles` (*Function | Object*): A function generating the styles or a styles object.
It will be linked to the component.
Expand All @@ -307,11 +307,11 @@ Use the function signature if you need to have access to the theme. It's provide
- `options.flip` (*Boolean* [optional]): When set to `false`, this sheet will opt-out the `rtl` transformation. When set to `true`, the styles are inversed. When set to `null`, it follows `theme.direction`.
- The other keys are forwarded to the options argument of [jss.createStyleSheet([styles], [options])](https://cssinjs.org/jss-api/#create-style-sheet).

#### Returns
### Returns

`higher-order component`: Should be used to wrap a component.

#### Examples
### Examples

```jsx
import React from 'react';
Expand Down Expand Up @@ -357,15 +357,15 @@ export default MyComponent
Provide the `theme` object as a property of the input component so it can be used
in the render method.

#### Arguments
### Arguments

1. `Component`: The component that will be wrapped.

#### Returns
### Returns

`Component`: The new component created. Does forward refs to the inner component.

#### Examples
### Examples

```jsx
import React from 'react';
Expand Down