@justeattakeaway/pie-modal 1.7.2 → 1.7.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +113 -16
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,38 +1,135 @@
|
|
|
1
|
-
|
|
2
|
-
<img align="center" src="../../../readme_image.png" height="200" alt="">
|
|
3
|
-
</p>
|
|
1
|
+
# @justeattakeaway/pie-modal
|
|
4
2
|
|
|
5
|
-
|
|
3
|
+
[Source Code](https://github.com/justeattakeaway/pie/tree/main/packages/components/pie-modal) | [Design Documentation](https://pie.design/components/link) | [NPM](https://www.npmjs.com/package/@justeattakeaway/pie-modal)
|
|
4
|
+
<p>
|
|
6
5
|
<a href="https://www.npmjs.com/@justeattakeaway/pie-modal">
|
|
7
6
|
<img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-modal.svg">
|
|
8
7
|
</a>
|
|
9
8
|
</p>
|
|
10
9
|
|
|
10
|
+
`@justeattakeaway/pie-modal` is a Web Component built using the Lit library. It offers a simple and accessible modal component for web applications.
|
|
11
11
|
|
|
12
|
-
##
|
|
12
|
+
## Table of Contents
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
- [Installation](#installation)
|
|
15
|
+
- [Documentation](#documentation)
|
|
16
|
+
- [Properties](#properties)
|
|
17
|
+
- [Slots](#slots)
|
|
18
|
+
- [CSS Variables](#css-variables)
|
|
19
|
+
- [Events](#events)
|
|
20
|
+
- [Legacy browser support](#legacy-browser-support)
|
|
21
|
+
- [Usage Examples](#usage-examples)
|
|
22
|
+
- [Questions and Support](#questions-and-support)
|
|
23
|
+
- [Contributing](#contributing)
|
|
15
24
|
|
|
16
|
-
|
|
25
|
+
## Installation
|
|
17
26
|
|
|
27
|
+
> To install any of our web components in your application, we would suggest following the [getting started guide](https://webc.pie.design/?path=/docs/introduction-getting-started--docs) to set up your project.
|
|
18
28
|
|
|
19
|
-
|
|
29
|
+
Ideally, you should install the component using the **`@justeattakeaway/pie-webc`** package, which includes all of the components. Or you can install the individual component package.
|
|
20
30
|
|
|
21
|
-
|
|
31
|
+
## Documentation
|
|
22
32
|
|
|
23
|
-
|
|
24
|
-
|
|
33
|
+
### Properties
|
|
34
|
+
| Prop | Options | Description | Default |
|
|
35
|
+
|----------------------------------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
|
|
36
|
+
| `aria` | — | An object representing the aria labels for the `close` and `back` buttons within the modal as well as the `isLoading` state labels (`aria-label` & `aria-busy`). | — |
|
|
37
|
+
| `hasBackButton` | `true`, `false` | If true, the modal includes a back button which closes the modal when clicked. | `false` |
|
|
38
|
+
| `hasStackedActions` | `true`, `false` | If true, the action buttons will be stacked (full width) at narrow breakpoints. | `false` |
|
|
39
|
+
| `heading` | — | The heading text of the modal. | — |
|
|
40
|
+
| `headingLevel` | `h1`, `h2`, `h3`, `h4`, `h5`, `h6` | The HTML tag to use for the modal's heading. | `h2` |
|
|
41
|
+
| `isDismissible` | `true`, `false` | If true, the modal includes a close button and can be dismissed by clicking on the backdrop or pressing the `Esc` key. | `false` |
|
|
42
|
+
| `isFooterPinned` | `true`, `false` | When false, the modal footer will scroll with the content inside the modal body. | `true` |
|
|
43
|
+
| `isFullWidthBelowMid` | `true`, `false` | If true and the page is narrower than the mid breakpoint, a **medium-sized** modal will take up the full width of the screen. | `false` |
|
|
44
|
+
| `isLoading` | `true`, `false` | When true, displays a loading spinner in the modal. | `false` |
|
|
45
|
+
| `isOpen` | `true`, `false` | Controls if the modal element is open or closed. | `false` |
|
|
46
|
+
| `leadingAction.text` | — | The text to display inside the leading action button. The button won't render without this. | — |
|
|
47
|
+
| `leadingAction.variant` | See pie-button's variants | The variant of the leading action button. | `"primary"` |
|
|
48
|
+
| `supportingAction.text` | — | The text to display inside the supporting action button. The button won't render without this. | — |
|
|
49
|
+
| `supportingAction.variant` | See pie-button's variants | The variant of the supporting action button. | `"ghost"` |
|
|
50
|
+
| `position` | `"center"`, `"top"` | The position of the modal; this controls where it will appear on the page. | `"center"` |
|
|
51
|
+
| `returnFocusAfterCloseSelector` | — | If provided, focus will be sent to the first element that matches this selector when the modal is closed. If not provided, the `dialog` element will return focus to the element that opened the modal. | — |
|
|
52
|
+
| `size` | `"small"`, `"medium"`, `"large"` | Determines the maximum width of the modal. Large modals will expand to fill the entire page at narrow viewports. | `"medium"` |
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
### Slots
|
|
56
|
+
| Slot | Description |
|
|
57
|
+
|-----------|--------------------------------------------------------------------|
|
|
58
|
+
| `default` | The default slot is used to pass content into the modal component. |
|
|
59
|
+
| `footer` | Used to pass optional content to the modal component footer area. |
|
|
60
|
+
|
|
61
|
+
### CSS Variables
|
|
62
|
+
This component does not expose any CSS variables for style overrides.
|
|
63
|
+
|
|
64
|
+
### Events
|
|
65
|
+
| Event | Type | Description |
|
|
66
|
+
|---------------------------------------|---------------|-----------------------------------------------------------|
|
|
67
|
+
| `pie-modal-open` | `CustomEvent` | Triggered when the modal is opened. |
|
|
68
|
+
| `pie-modal-close` | `CustomEvent` | Triggered when the modal is closed. |
|
|
69
|
+
| `pie-modal-back` | `CustomEvent` | Triggered when the modal back button is clicked. |
|
|
70
|
+
| `pie-modal-leading-action-click` | `CustomEvent` | Triggered when the modal leading action is clicked. |
|
|
71
|
+
| `pie-modal-supporting-action-click` | `CustomEvent` | Triggered when the modal supporting action is clicked. |
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
## Legacy browser support
|
|
75
|
+
|
|
76
|
+
`pie-modal` uses the Dialog element which might not be supported by legacy browsers.
|
|
77
|
+
|
|
78
|
+
To support them, `pie-modal` uses the [dialog-polyfill](https://github.com/justeattakeaway/pie/blob/main/packages/components/pie-modal/README.md#:~:text=modal%20uses%20the-,dialog%2Dpolyfill,-package.%20It%20works) package. It works automatically and doesn't need any setup.
|
|
79
|
+
|
|
80
|
+
The polyfill comes with a few limitations, as noted on its [documentation page](https://github.com/justeattakeaway/pie/blob/main/packages/components/pie-modal/README.md#:~:text=noted%20on%20its-,documentation%20page,-%3A):
|
|
81
|
+
|
|
82
|
+
Dialogs should not be contained by parents that create a stacking context
|
|
83
|
+
- The browser's chrome may not always be accessible via the tab key
|
|
84
|
+
- Changes to the CSS top/bottom values while open aren't retained
|
|
85
|
+
- For more details, check the package documentation mentioned above.
|
|
86
|
+
|
|
87
|
+
## Usage Examples
|
|
88
|
+
|
|
89
|
+
**For HTML:**
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
// import as module into a js file e.g. main.js
|
|
93
|
+
import '@justeattakeaway/pie-webc/components/modal.js'
|
|
94
|
+
```
|
|
25
95
|
|
|
26
|
-
|
|
96
|
+
```html
|
|
97
|
+
<!-- pass js file into <script> tag -->
|
|
98
|
+
<pie-modal heading='My Awesome Heading' headingLevel='h3'>Click me!</pie-modal>
|
|
99
|
+
<script type="module" src="/main.js"></script>
|
|
27
100
|
```
|
|
28
101
|
|
|
29
|
-
|
|
102
|
+
With a custom footer slot:
|
|
103
|
+
|
|
104
|
+
```html
|
|
105
|
+
<pie-modal heading='My Awesome Heading' headingLevel='h3'>
|
|
106
|
+
<p>Click me!</p>
|
|
107
|
+
<div slot="footer">
|
|
108
|
+
<p>Custom footer content!</p>
|
|
109
|
+
</div>
|
|
110
|
+
</pie-modal>
|
|
111
|
+
```
|
|
30
112
|
|
|
31
|
-
|
|
113
|
+
**For Native JS Applications, Vue, Angular, Svelte etc.:**
|
|
114
|
+
|
|
115
|
+
```js
|
|
116
|
+
// Vue templates (using Nuxt 3)
|
|
117
|
+
import '@justeattakeaway/pie-webc/components/modal.js';
|
|
118
|
+
|
|
119
|
+
<pie-modal heading="My Awesome Heading" headingLevel="h3">Click me!</pie-modal>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
**For React Applications:**
|
|
123
|
+
|
|
124
|
+
```jsx
|
|
125
|
+
import { PieModal } from '@justeattakeaway/pie-webc/react/modal.js';
|
|
126
|
+
|
|
127
|
+
<PieModal heading='My Awesome Heading' headingLevel='h3'>Click me!</PieModal>
|
|
128
|
+
```
|
|
32
129
|
|
|
33
|
-
## Questions
|
|
130
|
+
## Questions and Support
|
|
34
131
|
|
|
35
|
-
|
|
132
|
+
If you work at Just Eat Takeaway.com, please contact us on **#help-designsystem**. Otherwise, please raise an issue on [Github](https://github.com/justeattakeaway/pie/issues).
|
|
36
133
|
|
|
37
134
|
## Contributing
|
|
38
135
|
|
package/dist/index.js
CHANGED