Skip to content

Commit 3b0da3a

Browse files
TechQueryTechQuery
committed
[add] Popover & Toast documents
1 parent 2c66faf commit 3b0da3a

6 files changed

Lines changed: 354 additions & 22 deletions

File tree

‎document/source/components/Popover.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
layout: docs
3+
title: Popover
4+
description: Documentation and examples for adding Bootstrap popovers, like those found in iOS, to any element on your site.
5+
group: Components
6+
---
7+
8+
import { PopoverBox } from 'boot-cell/source/Prompt/Popover';
9+
import { Button } from 'boot-cell/source/Form/Button';
10+
11+
import { Example } from '../../../source/component/Example';
12+
13+
## Example
14+
15+
<Example>
16+
<PopoverBox
17+
header="Popover title"
18+
body="And here's some amazing content. It's very engaging. Right?"
19+
>
20+
<Button kind="danger" size="lg">
21+
Click to toggle popover
22+
</Button>
23+
</PopoverBox>
24+
</Example>
25+
26+
```JavaScript
27+
<PopoverBox
28+
header="Popover title"
29+
body="And here's some amazing content. It's very engaging. Right?"
30+
>
31+
<Button kind="danger" size="lg">
32+
Click to toggle popover
33+
</Button>
34+
</PopoverBox>
35+
```
36+
37+
### Four directions
38+
39+
<Example>
40+
<PopoverBox body="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
41+
<Button kind="secondary">Popover on top</Button>
42+
</PopoverBox>
43+
<PopoverBox
44+
position="right"
45+
body="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."
46+
>
47+
<Button kind="secondary">Popover on right</Button>
48+
</PopoverBox>
49+
<PopoverBox
50+
position="bottom"
51+
body="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."
52+
>
53+
<Button kind="secondary">Popover on bottom</Button>
54+
</PopoverBox>
55+
<PopoverBox
56+
position="left"
57+
body="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."
58+
>
59+
<Button kind="secondary">Popover on left</Button>
60+
</PopoverBox>
61+
</Example>
62+
63+
```JavaScript
64+
<PopoverBox body="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
65+
<Button kind="secondary">Popover on top</Button>
66+
</PopoverBox>
67+
<PopoverBox
68+
position="right"
69+
body="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."
70+
>
71+
<Button kind="secondary">Popover on right</Button>
72+
</PopoverBox>
73+
<PopoverBox
74+
position="bottom"
75+
body="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."
76+
>
77+
<Button kind="secondary">Popover on bottom</Button>
78+
</PopoverBox>
79+
<PopoverBox
80+
position="left"
81+
body="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."
82+
>
83+
<Button kind="secondary">Popover on left</Button>
84+
</PopoverBox>
85+
```

‎document/source/components/Toast.mdx‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
---
2+
layout: docs
3+
title: Toast
4+
description: Push notifications to your visitors with a toast, a lightweight and easily customizable alert message.
5+
group: Components
6+
---
7+
8+
import { ToastBox } from 'boot-cell/source/Prompt/Toast';
9+
10+
import { Example } from '../../../source/component/Example';
11+
12+
## Examples
13+
14+
### Basic
15+
16+
To encourage extensible and predictable toasts, we recommend a header and body. Toast headers use `display: flex`, allowing easy alignment of content thanks to our margin and flexbox utilities.
17+
18+
Toasts are as flexible as you need and have very little required markup. At a minimum, we require a single element to contain your “toasted” content and strongly encourage a dismiss button.
19+
20+
<Example className="bg-light">
21+
<ToastBox
22+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
23+
title="Bootstrap"
24+
time="11 mins ago"
25+
>
26+
Hello, world! This is a toast message.
27+
</ToastBox>
28+
</Example>
29+
30+
```JavaScript
31+
<ToastBox
32+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
33+
title="Bootstrap"
34+
time="11 mins ago"
35+
>
36+
Hello, world! This is a toast message.
37+
</ToastBox>
38+
```
39+
40+
### Translucent
41+
42+
Toasts are slightly translucent, too, so they blend over whatever they might appear over. For browsers that support the `backdrop-filter` CSS property, we’ll also attempt to blur the elements under a toast.
43+
44+
<Example className="bg-dark">
45+
<ToastBox
46+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
47+
title="Bootstrap"
48+
time="11 mins ago"
49+
>
50+
Hello, world! This is a toast message.
51+
</ToastBox>
52+
</Example>
53+
54+
```JavaScript
55+
<ToastBox
56+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
57+
title="Bootstrap"
58+
time="11 mins ago"
59+
>
60+
Hello, world! This is a toast message.
61+
</ToastBox>
62+
```
63+
64+
### Stacking
65+
66+
When you have multiple toasts, we default to vertically stacking them in a readable manner.
67+
68+
<Example className="bg-light">
69+
<ToastBox
70+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
71+
title="Bootstrap"
72+
time="just now"
73+
>
74+
See? Just like this.
75+
</ToastBox>
76+
<ToastBox
77+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
78+
title="Bootstrap"
79+
time="2 seconds ago"
80+
>
81+
Heads up, toasts will stack automatically
82+
</ToastBox>
83+
</Example>
84+
85+
```JavaScript
86+
<ToastBox
87+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
88+
title="Bootstrap"
89+
time="just now"
90+
>
91+
See? Just like this.
92+
</ToastBox>
93+
<ToastBox
94+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
95+
title="Bootstrap"
96+
time="2 seconds ago"
97+
>
98+
Heads up, toasts will stack automatically
99+
</ToastBox>
100+
```
101+
102+
## Placement
103+
104+
Place toasts with custom CSS as you need them. The top right is often used for notifications, as is the top middle. If you’re only ever going to show one toast at a time, put the positioning styles right on the `.toast`.
105+
106+
<Example className="bg-dark">
107+
<div
108+
className="position-relative vh-50"
109+
aria-live="polite"
110+
aria-atomic="true"
111+
>
112+
<ToastBox
113+
className="position-absolute right-0"
114+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
115+
title="Bootstrap"
116+
time="11 mins ago"
117+
>
118+
Hello, world! This is a toast message.
119+
</ToastBox>
120+
</div>
121+
</Example>
122+
123+
```JavaScript
124+
<div className="position-relative vh-50" aria-live="polite" aria-atomic="true">
125+
<ToastBox
126+
className="position-absolute right-0"
127+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
128+
title="Bootstrap"
129+
time="11 mins ago"
130+
>
131+
Hello, world! This is a toast message.
132+
</ToastBox>
133+
</div>
134+
```
135+
136+
For systems that generate more notifications, consider using a wrapping element so they can easily stack.
137+
138+
<Example className="bg-dark">
139+
<div
140+
className="position-relative vh-50"
141+
aria-live="polite"
142+
aria-atomic="true"
143+
>
144+
<div className="position-absolute right-0">
145+
<ToastBox
146+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
147+
title="Bootstrap"
148+
time="just now"
149+
>
150+
See? Just like this.
151+
</ToastBox>
152+
<ToastBox
153+
className="position-absolute right-0"
154+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
155+
title="Bootstrap"
156+
time="2 seconds ago"
157+
>
158+
Heads up, toasts will stack automatically
159+
</ToastBox>
160+
</div>
161+
</div>
162+
</Example>
163+
164+
```JavaScript
165+
<div className="position-relative vh-50" aria-live="polite" aria-atomic="true">
166+
<div className="position-absolute right-0">
167+
<ToastBox
168+
className="position-absolute right-0"
169+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
170+
title="Bootstrap"
171+
time="just now"
172+
>
173+
See? Just like this.
174+
</ToastBox>
175+
<ToastBox
176+
className="position-absolute right-0"
177+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
178+
title="Bootstrap"
179+
time="2 seconds ago"
180+
>
181+
Heads up, toasts will stack automatically
182+
</ToastBox>
183+
</div>
184+
</div>
185+
```
186+
187+
You can also get fancy with flexbox utilities to align toasts horizontally and/or vertically.
188+
189+
<Example className="bg-dark">
190+
<div
191+
className="d-flex justify-content-center align-items-center vh-50"
192+
aria-live="polite"
193+
aria-atomic="true"
194+
>
195+
<ToastBox
196+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
197+
title="Bootstrap"
198+
time="11 mins ago"
199+
>
200+
Hello, world! This is a toast message.
201+
</ToastBox>
202+
</div>
203+
</Example>
204+
205+
```JavaScript
206+
<div
207+
className="d-flex justify-content-center align-items-center vh-50"
208+
aria-live="polite"
209+
aria-atomic="true"
210+
>
211+
<ToastBox
212+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
213+
title="Bootstrap"
214+
time="11 mins ago"
215+
>
216+
Hello, world! This is a toast message.
217+
</ToastBox>
218+
</div>
219+
```
220+
221+
## Accessibility
222+
223+
Toasts are intended to be small interruptions to your visitors or users, so to help those with screen readers and similar assistive technologies, you should wrap your toasts in an [aria-live region][1]. Changes to live regions (such as injecting/updating a toast component) are automatically announced by screen readers without needing to move the user’s focus or otherwise interrupt the user. Additionally, include `aria-atomic="true"` to ensure that the entire toast is always announced as a single (atomic) unit, rather than announcing what was changed (which could lead to problems if you only update part of the toast’s content, or if displaying the same toast content at a later point in time). If the information needed is important for the process, e.g. for a list of errors in a form, then use the [alert component][2] instead of toast.
224+
225+
Note that the live region needs to be present in the markup before the toast is generated or updated. If you dynamically generate both at the same time and inject them into the page, they will generally not be announced by assistive technologies.
226+
227+
You also need to adapt the `role` and `aria-live` level depending on the content. If it’s an important message like an error, use `role="alert" aria-live="assertive"`, otherwise use `role="status" aria-live="polite"` attributes.
228+
229+
As the content you’re displaying changes, be sure to update the `delay` timeout to ensure people have enough time to read the toast.
230+
231+
```JavaScript
232+
<ToastBox
233+
icon="https://getbootstrap.com/docs/4.4/assets/img/favicons/favicon-16x16.png"
234+
title="Bootstrap"
235+
time="just now"
236+
delay={10000}
237+
>
238+
I'll disappear in 10 seconds.
239+
</ToastBox>
240+
```
241+
242+
[1]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions
243+
[2]: https://web-cell.dev/#alerts

‎package.json‎

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
22
"name": "bootcell-document",
3-
"version": "0.5.0",
3+
"version": "0.7.0",
44
"description": "Re-implemented Official Web-site of BootStrap based on WebCell, BootCell & MarkCell",
55
"dependencies": {
6-
"boot-cell": "^0.28.0",
6+
"boot-cell": "^0.30.0",
77
"cell-router": "^2.0.0-rc.6",
88
"classnames": "^2.2.6",
99
"lodash.groupby": "^4.6.0",
@@ -12,25 +12,16 @@
1212
"web-cell": "^2.0.0-rc.18"
1313
},
1414
"devDependencies": {
15+
"@types/classnames": "^2.2.9",
1516
"@types/lodash.groupby": "^4.6.6",
16-
"autoprefixer": "^9.7.4",
17-
"husky": "^4.2.1",
18-
"less": "^3.10.3",
17+
"husky": "^4.2.3",
18+
"less": "^3.11.1",
1919
"lint-staged": "^10.0.7",
2020
"mark-cell": "^0.2.3",
2121
"parcel": "^1.12.4",
22-
"postcss-modules": "^1.5.0",
2322
"prettier": "^1.19.1",
2423
"typescript": "^3.7.5"
2524
},
26-
"postcss": {
27-
"modules": true,
28-
"plugins": {
29-
"autoprefixer": {
30-
"grid": true
31-
}
32-
}
33-
},
3425
"prettier": {
3526
"singleQuote": true,
3627
"tabWidth": 4

‎source/component/Example.module.css‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎source/component/Example.tsx‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
11
import { createCell } from 'web-cell';
2-
import { WebCellProps } from 'boot-cell/source/utility/type';
2+
import { HTMLProps, WebCellProps } from 'boot-cell/source/utility/type';
3+
import classNames from 'classnames';
34

4-
import style from './Example.module.css';
5-
6-
export function Example({ defaultSlot }: WebCellProps) {
5+
export function Example({ className, defaultSlot }: HTMLProps & WebCellProps) {
76
return (
8-
<div className={`border border-light p-4 ${style.box}`}>
7+
<div
8+
className={classNames(
9+
'border',
10+
'border-light',
11+
'p-4',
12+
'bd-example',
13+
className
14+
)}
15+
>
916
{defaultSlot}
1017
</div>
1118
);

0 commit comments

Comments
 (0)