Skip to content

docs(react-drawer): update drawer spec to be inline with changes to component #28934

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

Merged
marcosmoura merged 1 commit into from
Aug 24, 2023
Merged

docs(react-drawer): update drawer spec to be inline with changes to component #28934

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
137 changes: 92 additions & 45 deletions packages/react-components/react-drawer/docs/Spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,11 @@ There is not prior implementation for this component in v0

### Type

`overlay`:
`DrawerOverlay`:
Opens on top of everything like a dialog and blocks all the page content. Can be dismissed.
![Example of Drawer as overlay](assets/overlay.png)

`inline`:
`DrawerInline`:
Push the siblings content when open and it is non-blocking. Can be hidden to bring focus to the main content of the page.
![Example of Drawer as inline content](assets/inline.png)

Expand All @@ -61,55 +61,98 @@ Push the siblings content when open and it is non-blocking. Can be hidden to bri
- `medium`: 592px
- `large`: 940px
- `full`: 100vw
- `custom`: Can be freely customized by providing a number. It cannot be extended beyond screen limits. If the size is larger than the screen size, it'll act as a `full` Drawer.

### Modal
For any custom size, a style can be provided overriding the `width` of drawer. Drawer can never be extended beyond screen limits and in case the size is larger than the screen size, it'll act as a `full` Drawer.

By default, the `overlay` acts as a modal, rendering an overlay scrim behind the drawer surface. This can be toggled off. \*
### Modal

<small>\* This prop DO NOT affect `inline` Drawers in any way.</small>
By default, the `DrawerOverlay` acts as a modal, rendering an overlay scrim behind the drawer surface. This can be toggled off.

## API

### Drawer

| Property | Values | Default | Description |
| ------------ | ------------------------------------------ | --------- | ------------------------------------------------------- |
| type | `overlay`, `inline` | `overlay` | Set the [type](#type) of Drawer |
| position | `start`, `end` | `start` | Set the position of the Drawer |
| size | `small`, `medium`, `large`, `full`, number | `small` | The drawer width [size](#size) |
| modal | boolean | `true` | Set the visibility of the `overlay` scrim |
| open | boolean | `false` | Define the Drawer visibility |
| defaultOpen | boolean | `false` | Define the Drawer visibility on first render |
| onOpenChange | function | undefined | Callback called when drawer changes its visibility |
| separator | boolean | `false` | Define if the `inline` drawer should render a separator |

| Slots | Values | Default | Description |
| ------------- | --------------- | --------------- | ------------------------------------------------- |
| root | `div` | `div` | The root drawer element |
| dialog | `Dialog` | `Dialog` | The dialog element for the `overlay` type |
| dialogSurface | `DialogSurface` | `DialogSurface` | The dialog surface element for the `overlay` type |
This component is a combination of both `DrawerInline` and `DrawerOverlay`

| Property | Values | Default | Description |
| -------------- | ---------------------------------- | --------- | -------------------------------------------------------------------------------------- |
| type | `overlay`, `inline` | `overlay` | Set the [type](#type) of Drawer |
| position | `start`, `end` | `start` | Set the position of the Drawer |
| size | `small`, `medium`, `large`, `full` | `small` | The drawer width [size](#size) |
| modalType | boolean | `true` | Set the visibility of the backdrop scrim. Only for `type="overlay"` |
| inertTrapFocus | boolean | `true` | Enables standard behavior according to the HTML dialog spec. Only for `type="overlay"` |
| open | boolean | `false` | Define the Drawer visibility |
| defaultOpen | boolean | `false` | Define the Drawer visibility on first render |
| onOpenChange | function | undefined | Callback called when drawer changes its visibility. Only for `type="overlay"` |
| separator | boolean | `false` | Define if the `type="inline"` drawer should render a separator |

| Slots | Values | Default | Description |
| ----- | ------ | ------- | ----------------------- |
| root | `div` | `div` | The root drawer element |

### DrawerOverlay

| Property | Values | Default | Description |
| -------------- | ---------------------------------- | --------- | ----------------------------------------------------------- |
| position | `start`, `end` | `start` | Set the position of the Drawer |
| size | `small`, `medium`, `large`, `full` | `small` | The drawer width [size](#size) |
| modalType | boolean | `true` | Set the visibility of the backdrop scrim |
| inertTrapFocus | boolean | `true` | Enables standard behavior according to the HTML dialog spec |
| open | boolean | `false` | Define the Drawer visibility |
| defaultOpen | boolean | `false` | Define the Drawer visibility on first render |
| onOpenChange | function | undefined | Callback called when drawer changes its visibility |

| Slots | Values | Default | Description |
| ----- | ------ | ------- | ------------------------------- |
| root | `div` | `div` | The root overlay drawer element |

### DrawerInline

| Property | Values | Default | Description |
| ----------- | ---------------------------------- | ------- | ------------------------------------------------------- |
| position | `start`, `end` | `start` | Set the position of the Drawer |
| size | `small`, `medium`, `large`, `full` | `small` | The drawer width [size](#size) |
| open | boolean | `false` | Define the Drawer visibility |
| defaultOpen | boolean | `false` | Define the Drawer visibility on first render |
| separator | boolean | `false` | Define if the `inline` drawer should render a separator |

| Slots | Values | Default | Description |
| ----- | ------ | ------- | ------------------------------ |
| root | `div` | `div` | The root inline drawer element |

### DrawerHeader

| Slots | Values | Default | Description |
| ---------- | -------- | -------- | -------------------------------------------------------- |
| root | `header` | `header` | The root drawer element |
| title | `div` | `div` | The drawer title |
| navigation | `div` | `div` | The drawer top navigation |
| actions | `div` | `div` | The drawer actions to be rendered side-by-side the title |
| Slots | Values | Default | Description |
| ----- | -------- | -------- | ----------------------- |
| root | `header` | `header` | The root drawer element |

### DrawerHeaderNavigation

| Slots | Values | Default | Description |
| ----- | ------ | ------- | ---------------------------------- |
| root | `nav` | `nav` | The root drawer navigation element |

- [DrawerHeaderNavigation types](../src/components/DrawerHeaderNavigation/DrawerHeaderNavigation.types.ts)

### DrawerHeaderTitle

| Slots | Values | Default | Description |
| ------- | ----------------------------------------- | ------- | ------------------------------------- |
| root | `div` | `div` | The root drawer title element |
| heading | `h2`, `h1`, `h3`, `h4`, `h5`, `h6`, `div` | `h2` | The root drawer title heading element |
| action | `div` | `div` | Action slot for the close button |

- [DrawerHeader types](../src/components/DrawerHeader/DrawerHeader.types.ts)
- [DrawerHeaderTitle types](../src/components/DrawerHeaderTitle/DrawerHeaderTitle.types.ts)

### DrawerContent
### DrawerBody

No props

| Slots | Values | Default | Description |
| ----- | ------ | ------- | ------------------------------- |
| root | `div` | `div` | The root drawer content element |

- [DrawerContent types](../src/components/DrawerContent/DrawerContent.types.ts)
- [DrawerBody types](../src/components/DrawerBody/DrawerBody.types.ts)

### DrawerFooter

Expand All @@ -125,29 +168,33 @@ No props

### Components

| Component | Purpose |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Drawer | Renders a plain Drawer and render its children |
| DrawerHeader | Renders a `header` in a structured way. Ideal to display title and actions |
| DrawerContent | Renders a scrollable `div` that holds the drawer main content |
| DrawerFooter | Renders a `footer` element that holds the drawer main actions. Often used to have buttons such as confirmation actions |
| Component | Purpose |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Drawer | Renders a plain inline or overlay Drawer and render its children |
| DrawerInline | Renders a plain inline Drawer and render its children |
| DrawerOverlay | Renders a plain overlay Drawer and render its children |
| DrawerHeader | Renders a `header` in a structured way. Ideal to display title and actions |
| DrawerHeaderNavigation | Renders a `header` in a structured way. Ideal to display title and actions |
| DrawerHeaderTitle | Renders a `header` in a structured way. Ideal to display title and actions |
| DrawerBody | Renders a scrollable `div` that holds the drawer main content |
| DrawerFooter | Renders a `footer` element that holds the drawer main actions. Often used to have buttons such as confirmation actions |

#### Drawer component

![Drawer Anatomy](assets/drawer-anatomy.png)

- `overlay` type:
- DrawerOverlay or Drawer with `type="overlay"`:

```html
<div class="fui-Drawer" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="the-title-element-id">
<div class="fui-DrawerOverlay" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="the-title-element-id">
<!-- Content rendered here -->
</div>
```

- `inline` type:
- DrawerInline or Drawer with `type="inline"`:

```html
<div class="fui-Drawer" tabindex="-1" aria-labelledby="the-title-element-id">
<div class="fui-DrawerInline" tabindex="-1" aria-labelledby="the-title-element-id">
<!-- Content rendered here -->
</div>
```
Expand Down Expand Up @@ -196,12 +243,12 @@ No props
</header>
```

#### DrawerContent component
#### DrawerBody component

![DrawerContent Anatomy](assets/drawer-content-anatomy.png)
![DrawerBody Anatomy](assets/drawer-content-anatomy.png)

```html
<div class="fui-DrawerContent">
<div class="fui-DrawerBody">
<!-- Content rendered here -->
</div>
```
Expand All @@ -221,7 +268,7 @@ No props

### `Drawer`

A drawer can be triggered by any button on the screen. When invoked, it slides in from either the left or right side of the screen. How they will behave depends from its `type`:
A drawer can be triggered by any button on the screen. When invoked, it slides in from either the start or end sides of the screen. How they behave depends from its `type`:

#### `overlay`

Expand Down