Skip to content

Commit

Permalink
[docs] Update MUI Base docs with latest style conventions (#35034)
Browse files Browse the repository at this point in the history
  • Loading branch information
@samuelsycamore
samuelsycamore committed Nov 28, 2022
1 parent b8aa397 commit 35c57de
Show file tree
Hide file tree
Showing 25 changed files with 181 additions and 237 deletions.
10 changes: 5 additions & 5 deletions docs/data/base/components/badge/badge.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ githubLabel: 'component: badge'

# Unstyled badge

<p class="description">The BadgeUnstyled component generates a small label that is attached to its child element.</p>
<p class="description">The Unstyled Badge component generates a small label that is attached to its child element.</p>

## Introduction

A badge is a small descriptor for UI elements.
It typically sits on or near an element and indicates the status of that element by displaying a number, icon, or other short set of characters.

The `BadgeUnstyled` component creates a badge that is applied to its child element.
The Unstyled Badge component creates a badge that is applied to its child element.

{{"demo": "UnstyledBadgeIntroduction.tsx", "defaultCodeOpen": false, "bg": "gradient"}}

Expand All @@ -38,7 +38,7 @@ export default function MyApp() {

### Basics

`BadgeUnstyled` wraps around the UI element that it's attached to.
The Unstyled Badge wraps around the UI element that it's attached to.
For instance, if the badge indicates the number of emails in an inbox, then the component will be structured like this:

```jsx
Expand All @@ -49,7 +49,7 @@ For instance, if the badge indicates the number of emails in an inbox, then the

### Anatomy

The `BadgeUnstyled` component is composed of a root `<span>` that houses the element that the badge is attached to, followed by a `<span>` slot to represent the badge itself:
The Unstyled Badge component is composed of a root `<span>` that houses the element that the badge is attached to, followed by a `<span>` slot to represent the badge itself:

```html
<span class="BaseBadge-root">
Expand Down Expand Up @@ -94,7 +94,7 @@ The following code snippet applies a CSS class called `my-badge` to the badge sl
import { useBadge } from '@mui/base/BadgeUnstyled';
```

The `useBadge` hook lets you apply the functionality of `BadgeUnstyled` to a fully custom component.
The `useBadge` hook lets you apply the functionality of a badge to a fully custom component.
It returns props to be placed on the custom component, along with fields representing the component's internal state.

Hooks _do not_ support [slot props](#slot-props), but they do support [customization props](#customization).
Expand Down
37 changes: 10 additions & 27 deletions docs/data/base/components/button/button.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/button/

## Introduction

`ButtonUnstyled` replaces the native HTML `<button>` element.
The Unstyled Button component replaces the native HTML `<button>` element, and offers expanded options for styling and accessibility.

{{"demo": "UnstyledButtonIntroduction.tsx", "defaultCodeOpen": false, "bg": "gradient"}}

Expand All @@ -34,7 +34,7 @@ export default function MyApp() {

### Basics

`ButtonUnstyled` behaves similar to the native HTML `<button>`, so it wraps around the text that will be displayed on its surface.
The Unstyled Button behaves similar to the native HTML `<button>`, so it wraps around the text that will be displayed on its surface.

The following demo shows how to create and style two basic buttons.
Notice that the second button cannot be clicked due to the `disabled` prop:
Expand All @@ -43,7 +43,7 @@ Notice that the second button cannot be clicked due to the `disabled` prop:

### Anatomy

The `ButtonUnstyled` component is composed of a root `<button>` slot with no interior slots:
The Unstyled Button component is composed of a root `<button>` slot with no interior slots:

```html
<button class="BaseButton-root">
Expand All @@ -64,31 +64,14 @@ Use the `component` prop to override the root slot with a custom element:
<ButtonUnstyled component="div" />
```

If you provide a non-interactive element such as a `<span>`, the `ButtonUnstyled` component will automatically add the necessary accessibility attributes.
If you provide a non-interactive element such as a `<span>`, the Unstyled Button component will automatically add the necessary accessibility attributes.

Use the `slots` prop to override any interior slots in addition to the root:

```jsx
<ButtonUnstyled slots={{ root: 'div' }} />
```

:::warning
If the root element is customized with both the `component` and `slots` props, then `component` will take precedence.
:::

Use the `slotProps` prop to pass custom props to internal slots.
The following code snippet applies a CSS class called `my-button` to the root slot:

```jsx
<ButtonUnstyled slotProps={{ root: { className: 'my-button' } }} />
```

Compare the attributes on the `<span>` in this demo with the `ButtonUnstyled` from the previous demo:
Compare the attributes on the `<span>` in this demo with the Button from the previous demo—try inspecting them both with your brower's dev tools:

{{"demo": "UnstyledButtonsSpan.js"}}

:::warning
If a `ButtonUnstyled` is customized with a non-button element (i.e. `<ButtonUnstyled component="span" />`), it will not submit the form it's in when clicked.
If an Unstyled Button is customized with a non-button element (i.e. `<ButtonUnstyled component="span" />`), it will not submit the form it's in when clicked.
Similarly, `<ButtonUnstyled component="span" type="reset">` will not reset its parent form.
:::

Expand All @@ -98,7 +81,7 @@ Similarly, `<ButtonUnstyled component="span" type="reset">` will not reset its p
import { useButton } from '@mui/base/ButtonUnstyled';
```

The `useButton` hook lets you apply the functionality of `ButtonUnstyled` to a fully custom component.
The `useButton` hook lets you apply the functionality of a button to a fully custom component.
It returns props to be placed on the custom component, along with fields representing the component's internal state.

Hooks _do not_ support [slot props](#slot-props), but they do support [customization props](#customization).
Expand All @@ -112,7 +95,7 @@ You may not need to use hooks unless you find that you're limited by the customi

The `useButton` hook requires the `ref` of the element it's used on.

The following demo shows how to build the same buttons as those found in the [Basic usage section](#basic-usage), but with the `useButton` hook:
The following demo shows how to build the same buttons as those found in the [Basics](#basics) section above, but with the `useButton` hook:

{{"demo": "UseButton.js", "defaultCodeOpen": true}}

Expand All @@ -125,14 +108,14 @@ For the sake of simplicity, demos and code snippets primarily feature components

### Custom elements

`ButtonUnstyled` accepts a wide range of custom elements beyond HTML elements.
The Unstyled Button accepts a wide range of custom elements beyond HTML elements.
You can even use SVGs, as the following demo illustrates:

{{"demo": "UnstyledButtonCustom.js", "defaultCodeOpen": false}}

### Focus on disabled buttons

Similarly to the native HTML `<button>` element, the `ButtonUnstyled` component can't receive focus when it's disabled.
Similarly to the native HTML `<button>` element, the Unstyled Button component can't receive focus when it's disabled.
This may reduce its accessibility, as screen readers won't be able to announce the existence and state of the button.

The `focusableWhenDisabled` prop lets you change this behavior.
Expand Down
14 changes: 7 additions & 7 deletions docs/data/base/components/click-away-listener/click-away-listener.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,16 @@ githubLabel: 'component: ClickAwayListener'

# Click-Away Listener

<p class="description">The ClickAwayListener component detects when a click event happens outside of its child element.</p>
<p class="description">The Click-Away Listener component detects when a click event happens outside of its child element.</p>

## Introduction

`ClickAwayListener` is a utility component that listens for click events outside of its child.
Click-Away Listener is a utility component that listens for click events outside of its child.
(Note that it only accepts _one_ child element.)

This is useful for components like [`PopperUnstyled`](/base/react-popper/) which should close when the user clicks anywhere else in the document.
This is useful for components like the [Unstyled Popper](/base/react-popper/) which should close when the user clicks anywhere else in the document.

`ClickAwayListener` also supports the [`Portal` component](/base/react-portal/).
Click-Away Listener also supports the [Portal](/base/react-portal/) component.

{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}

Expand Down Expand Up @@ -46,15 +46,15 @@ The following demo shows how to hide a menu dropdown when users click anywhere e

### Usage with Portal

The following demo uses the [`Portal` component](/base/react-portal/) to render the dropdown into a new subtree outside of the current DOM hierarchy:
The following demo uses the [Portal](/base/react-portal/) component to render the dropdown into a new subtree outside of the current DOM hierarchy:

{{"demo": "PortalClickAway.js"}}

## Customization

### Listening for leading events

By default, the `ClickAwayListener` component responds to **trailing events**—the _end_ of a click or touch.
By default, the Click-Away Listener component responds to **trailing events**—the _end_ of a click or touch.

You can set the component to listen for **leading events** (the start of a click or touch) using the `mouseEvent` and `touchEvent` props, as shown in the following demo:

Expand All @@ -66,7 +66,7 @@ When the component is set to listen for leading events, interactions with the sc

## Accessibility

By default, `ClickAwayListener` will add an `onClick` handler to its child.
By default, Click-Away Listener will add an `onClick` handler to its child.
This can result in screen readers announcing that the child is clickable, even though this `onClick` handler has no effect on the child itself.

To prevent this behavior, add `role="presentation"` to the child element:
Expand Down
30 changes: 15 additions & 15 deletions docs/data/base/components/focus-trap/focus-trap.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ githubLabel: 'component: FocusTrap'

# Focus Trap

<p class="description">The FocusTrap component prevents the user's focus from escaping its children components.</p>
<p class="description">The Focus Trap component prevents the user's focus from escaping its children components.</p>

## Introduction

`FocusTrap` is a utility component that is useful when implementing an overlay such as a [modal dialog](/base/react-modal/), which should block all interactions outside of it while open.
Focus Trap is a utility component that's useful when implementing an overlay such as a [modal dialog](/base/react-modal/), which should block all interactions outside of it while open.

{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}

Expand All @@ -31,8 +31,8 @@ export default function MyApp() {

### Basics

`FocusTrap` wraps around the UI elements that should hold the user's focus.
For instance, if the focus needs to stay inside of a [`MenuUnstyled`](/base/react-menu/), then the component will be structured like this:
Focus Trap wraps around the UI elements that should hold the user's focus.
For instance, if the focus needs to stay inside of an [Unstyled Menu](/base/react-menu/), then the component will be structured like this:

```jsx
<FocusTrap>
Expand All @@ -43,15 +43,15 @@ For instance, if the focus needs to stay inside of a [`MenuUnstyled`](/base/reac
</FocusTrap>
```

The following demo shows a `<button>` that opens a [`Box`](/material-ui/react-box/) component nested inside of a `FocusTrap`.
As long as the `Box` is open, the user's keyboard cannot interact with the rest of the app.
Press the **Open** button and then use the <kbd class="key">Tab</kbd> key to move the focus—notice that it will not leave the `Box`:
The following demo shows a `<button>` that opens a [Box](/material-ui/react-box/) component nested inside of a Focus Trap.
As long as the Box is open, the user's keyboard cannot interact with the rest of the app.
Press the **Open** button and then use the <kbd class="key">Tab</kbd> key to move the focus—notice that it will not leave the Box:

{{"demo": "BasicFocusTrap.js"}}

:::error
Because the `FocusTrap` component blocks interaction with the rest of the app by default, the demo above also behaves this way.
If you leave the `Box` open in the demo, you won't be able to click on other buttons in this document.
Because the Focus Trap component blocks interaction with the rest of the app by default, the demo above also behaves this way.
If you leave the Box open in the demo, you won't be able to click on other buttons in this document.
Click **Close** in the demo to resolve this.

The next section explains how to change this default behavior.
Expand All @@ -61,17 +61,17 @@ The next section explains how to change this default behavior.

### Disable enforced focus

By default, clicks outside of the `FocusTrap` component are blocked.
By default, clicks outside of the Focus Trap component are blocked.

You can disable this behavior with the `disableEnforceFocus` prop.

Compare the following demo with the demo from the [Basics section](#basics)—notice how that demo prevents you from clicking outside of it, while this one allows it:
Compare the following demo with the demo from the [Basics](#basics) section—notice how that demo prevents you from clicking outside of it, while this one allows it:

{{"demo": "DisableEnforceFocus.js"}}

### Lazy activation

By default, the `FocusTrap` component automatically moves the focus to the first of its children when the `open` prop is present.
By default, the Focus Trap component automatically moves the focus to the first of its children when the `open` prop is present.

You can disable this behavior and make it lazy with the `disableAutoFocus` prop.
When auto focus is disabled—as in the demo below—the component only traps the focus once the user moves it there:
Expand All @@ -80,13 +80,13 @@ When auto focus is disabled—as in the demo below—the component only traps th

### Escape the focus loop

The following demo uses the [`Portal`](/base/react-portal/) component to render a subset of the `FocusTrap` children into a new "subtree" outside of the current DOM hierarchy, so they are no longer part of the focus loop:
The following demo uses the [Portal](/base/react-portal/) component to render a subset of the Focus Trap children into a new "subtree" outside of the current DOM hierarchy, so they are no longer part of the focus loop:

{{"demo": "PortalFocusTrap.js"}}

### Using a toggle inside the trap

The most common use case for the `FocusTrap` component is to maintain focus within a [modal](/base/react-modal/) component that is entirely separate from the element that opens the modal.
But you can also create a toggle button for the `open` prop of the `FocusTrap` component that is stored inside of the component itself, as shown in the following demo:
The most common use case for the Focus Trap component is to maintain focus within an [Unstyled Modal](/base/react-modal/) component that is entirely separate from the element that opens the modal.
But you can also create a toggle button for the `open` prop of the Focus Trap component that is stored inside of the component itself, as shown in the following demo:

{{"demo": "ContainedToggleTrappedFocus.js"}}

0 comments on commit 35c57de

Please sign in to comment.