Skip to content

Commit

Permalink
feat(sheet): Add Sheet component (#7561)
Browse files Browse the repository at this point in the history 
**Related Issue:** #6391

## Summary

- Adds new `calcite-sheet` component.
- Adds e2e tests
- Adds screenshot tests
- Adds html page with examples
- Modeled after the Modal component.
- Added to index page
- Added to stencil config

## After merged

- [Shell] Add "Sheet" Slot
  - Will try to do for this release if it gets merged in time 
  - Issue: #7154 
  - PR: #7579

## Future

- Resizable (need issue) @macandcheese 

## API

### Example

```html
<calcite-sheet open label="libero nunc" position="inline-start">
  <calcite-panel closable heading="Ultrices neque"
    ><p>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
      magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
      Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
    </p>
    <calcite-button slot="footer" width="half" appearance="outline">tincidunt lobortis</calcite-button>
    <calcite-button slot="footer" width="half" appearance="outline">amet porttitor</calcite-button>
  </calcite-panel>
  <script>
    document.addEventListener("calcitePanelClose", () => {
      document.querySelector("calcite-sheet").open = false;
    });
  </script>
</calcite-sheet>
```

## Properties

| Property | Attribute | Description | Type | Default |
| ---------------------- | ------------------------ |
---------------------------------------------------------------------------------------------------------------------------
| ---------------------------------------------------------------- |
---------------- |
| `beforeClose` | -- | Passes a function to run before the component
closes. | `(el: HTMLCalciteSheetElement) => Promise<void>` | `undefined`
|
| `displayMode` | `display-mode` | Specifies the display mode -
`"float"` (content is separated detached), or `"overlay"` (displays on
top of center content). | `"float" \| "overlay"` | `"overlay"` |
| `escapeDisabled` | `escape-disabled` | When `true`, disables the
default close on escape behavior. | `boolean` | `false` |
| `focusTrapDisabled` | `focus-trap-disabled` | When `true`, prevents
focus trapping. | `boolean` | `false` |
| `heightScale` | `height-scale` | When `position` is `"block-start"` or
`"block-end"`, specifies the height of the component. | `"l" \| "m" \|
"s"` | `"m"` |
| `label` _(required)_ | `label` | Specifies the label of the component.
| `string` | `undefined` |
| `open` | `open` | When `true`, displays and positions the component. |
`boolean` | `false` |
| `outsideCloseDisabled` | `outside-close-disabled` | When `true`,
disables the closing of the component when clicked outside. | `boolean`
| `false` |
| `position` | `position` | When `true`, disables the closing of the
component when clicked outside. | `"block-end" \| "block-start" \|
"inline-end" \| "inline-start"` | `"inline-start"` |
| `widthScale` | `width-scale` | When `position` is `"inline-start"` or
`"inline-end"`, specifies the width of the component. | `"l" \| "m" \|
"s"` | `"m"` |


## Events

| Event | Description | Type |
| ------------------------- |
--------------------------------------------------------------------------------------------------------
| ------------------- |
| `calciteSheetBeforeClose` | Fires when the component is requested to
be closed and before the closing transition begins. |
`CustomEvent<void>` |
| `calciteSheetBeforeOpen` | Fires when the component is added to the
DOM but not rendered, and before the opening transition begins. |
`CustomEvent<void>` |
| `calciteSheetClose` | Fires when the component is closed and animation
is complete. | `CustomEvent<void>` |
| `calciteSheetOpen` | Fires when the component is open and animation is
complete. | `CustomEvent<void>` |


## Methods

### `setFocus() => Promise<void>`

Sets focus on the component's "close" button (the first focusable item).

#### Returns

Type: `Promise<void>`



### `updateFocusTrapElements() => Promise<void>`

Updates the element(s) that are used within the focus-trap of the
component.

#### Returns

Type: `Promise<void>`




## CSS Custom Properties

| Name | Description |
| ---------------------------------- |
----------------------------------------------------------------------------------------------------
|
| `--calcite-sheet-height` | When `position` is `"block-start"` or
`"block-end"`, specifies the height of the component. |
| `--calcite-sheet-max-height` | When `position` is `"block-start"` or
`"block-end"`, specifies the maximum height of the component. |
| `--calcite-sheet-max-width` | When `position` is `"inline-start"` or
`"inline-end"`, specifies the maximum width of the component. |
| `--calcite-sheet-min-height` | When `position` is `"block-start"` or
`"block-end"`, specifies the minimum height of the component. |
| `--calcite-sheet-min-width` | When `position` is `"inline-start"` or
`"inline-end"`, specifies the minimum width of the component. |
| `--calcite-sheet-scrim-background` | Specifies the background color of
the sheet scrim. |
| `--calcite-sheet-width` | When `position` is `"inline-start"` or
`"inline-end"`, specifies the width of the component. |

---------

Co-authored-by: Adam <adam@tirel.la>
  • Loading branch information
@driskull @macandcheese @benelan
2 people authored and benelan committed Aug 28, 2023
1 parent 4b73eab commit 4de00e1
Show file tree
Hide file tree
Showing 14 changed files with 1,473 additions and 0 deletions.
1 change: 1 addition & 0 deletions packages/calcite-components/src/components/sheet/interfaces.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export type DisplayMode = "float" | "overlay";
142 changes: 142 additions & 0 deletions packages/calcite-components/src/components/sheet/readme.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# calcite-sheet

<!-- Auto Generated Below -->

## Usage

### Basic

```html
<calcite-sheet open label="libero nunc" position="inline-start">
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur
sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</p>
</calcite-sheet>
```

### Open

To open a sheet, add the `open` prop. Once the opening animation is complete, the `calciteSheetOpen` event will be fired.

To close the sheet, simply remove the attribute. This will run your before close method (if provided, see below) and fire the `calciteSheetClose` event after the animation and teardown is complete.

```html
<calcite-sheet open
>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et
dolore</calcite-sheet
>
```

### Panel

```html
<calcite-sheet open label="libero nunc" position="inline-start">
<calcite-panel closable heading="Ultrices neque"
><p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</p>
<calcite-button slot="footer" width="half" appearance="outline">tincidunt lobortis</calcite-button>
<calcite-button slot="footer" width="half" appearance="outline">amet porttitor</calcite-button>
</calcite-panel>
<script>
document.addEventListener("calcitePanelClose", () => {
document.querySelector("calcite-sheet").open = false;
});
</script>
</calcite-sheet>
```

### Reacting-before-close

If you'd like to perform some actions prior to closing (ie. warning users they will lose their changes) you can pass a function to the `beforeClose` property. This method will be called prior to close and should return a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise):

```js
function beforeClose() {
return new Promise((resolve) => {
// do something async
resolve(); // this will trigger the close animation
});
}

const sheet = document.getElementById("my-sheet");
sheet.beforeClose = beforeClose;
```

## Properties

| Property | Attribute | Description | Type | Default |
| ---------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------- |
| `beforeClose` | -- | Passes a function to run before the component closes. | `(el: HTMLCalciteSheetElement) => Promise<void>` | `undefined` |
| `displayMode` | `display-mode` | Specifies the display mode - `"float"` (content is separated detached), or `"overlay"` (displays on top of center content). | `"float" \| "overlay"` | `"overlay"` |
| `escapeDisabled` | `escape-disabled` | When `true`, disables the default close on escape behavior. | `boolean` | `false` |
| `focusTrapDisabled` | `focus-trap-disabled` | When `true`, prevents focus trapping. | `boolean` | `false` |
| `heightScale` | `height-scale` | When `position` is `"block-start"` or `"block-end"`, specifies the height of the component. | `"l" \| "m" \| "s"` | `"m"` |
| `label` _(required)_ | `label` | Specifies the label of the component. | `string` | `undefined` |
| `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` |
| `outsideCloseDisabled` | `outside-close-disabled` | When `true`, disables the closing of the component when clicked outside. | `boolean` | `false` |
| `position` | `position` | When `true`, disables the closing of the component when clicked outside. | `"block-end" \| "block-start" \| "inline-end" \| "inline-start"` | `"inline-start"` |
| `widthScale` | `width-scale` | When `position` is `"inline-start"` or `"inline-end"`, specifies the width of the component. | `"l" \| "m" \| "s"` | `"m"` |

## Events

| Event | Description | Type |
| ------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
| `calciteSheetBeforeClose` | Fires when the component is requested to be closed and before the closing transition begins. | `CustomEvent<void>` |
| `calciteSheetBeforeOpen` | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | `CustomEvent<void>` |
| `calciteSheetClose` | Fires when the component is closed and animation is complete. | `CustomEvent<void>` |
| `calciteSheetOpen` | Fires when the component is open and animation is complete. | `CustomEvent<void>` |

## Methods

### `setFocus() => Promise<void>`

Sets focus on the component's "close" button (the first focusable item).

#### Returns

Type: `Promise<void>`

### `updateFocusTrapElements() => Promise<void>`

Updates the element(s) that are used within the focus-trap of the component.

#### Returns

Type: `Promise<void>`

## CSS Custom Properties

| Name | Description |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--calcite-sheet-height` | When `position` is `"block-start"` or `"block-end"`, specifies the height of the component. |
| `--calcite-sheet-max-height` | When `position` is `"block-start"` or `"block-end"`, specifies the maximum height of the component. |
| `--calcite-sheet-max-width` | When `position` is `"inline-start"` or `"inline-end"`, specifies the maximum width of the component. |
| `--calcite-sheet-min-height` | When `position` is `"block-start"` or `"block-end"`, specifies the minimum height of the component. |
| `--calcite-sheet-min-width` | When `position` is `"inline-start"` or `"inline-end"`, specifies the minimum width of the component. |
| `--calcite-sheet-scrim-background` | Specifies the background color of the sheet scrim. |
| `--calcite-sheet-width` | When `position` is `"inline-start"` or `"inline-end"`, specifies the width of the component. |

## Dependencies

### Depends on

- [calcite-scrim](../scrim)

### Graph

```mermaid
graph TD;
calcite-sheet --> calcite-scrim
calcite-scrim --> calcite-loader
style calcite-sheet fill:#f9f,stroke:#333,stroke-width:4px
```

---

_Built with [StencilJS](https://stenciljs.com/)_
7 changes: 7 additions & 0 deletions packages/calcite-components/src/components/sheet/resources.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
export const CSS = {
scrim: "scrim",
container: "container",
containerOpen: "container--open",
content: "content",
containerSlottedInShell: "container--slotted-in-shell",
};

0 comments on commit 4de00e1

Please sign in to comment.