@editora/toast 2.0.10 → 2.1.1
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/CHANGELOG.md +33 -0
- package/README.md +158 -38
- package/dist/core/ToastManager.d.ts +1 -1
- package/dist/core/ToastRenderer.d.ts +24 -3
- package/dist/core/ToastStack.d.ts +8 -0
- package/dist/core/icons.d.ts +2 -0
- package/dist/core/types.d.ts +3 -1
- package/dist/index.cjs.js +1 -1
- package/dist/index.d.ts +13 -16
- package/dist/index.esm.js +490 -310
- package/dist/index.umd.js +1 -1
- package/dist/toast.css +499 -744
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,38 @@
|
|
|
1
1
|
# Change Log
|
|
2
2
|
|
|
3
|
+
## 2.1.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 06763f8: A modern look and real accessibility for the code editor's overlays, and contrast preferences for the toast.
|
|
8
|
+
|
|
9
|
+
**`@editora/light-code-editor`**
|
|
10
|
+
- **Accessibility:** the editing surface is a named, multi-line `role="textbox"` (`aria-readonly` when read-only), with a new `ariaLabel` option. The completion popup is a combobox listbox, not an unnamed dialog: the editor carries `aria-activedescendant`, `aria-controls` and `aria-haspopup` while it is open, options have ids, the list is focusable for scrolling and the status line is a polite live region. Find is a named `search` landmark with named inputs and icon buttons, go to line is a named group (its "Go" button's name now contains its visible text), the hover card and the context menu are named, and the fold toggles are buttons with `aria-expanded`.
|
|
11
|
+
- **Contrast:** muted text (gutter, meta, descriptions, shortcuts) was 3.6:1 on the active row in the dark theme; it is 4.5:1 or better in both themes, and the completion match highlight keeps 4.5:1 on the active row.
|
|
12
|
+
- **Look and feel:** one overlay system for find, go to line, completions, the context menu and the hover card (a raised surface, a hairline, a soft shadow, a 120ms pop-in that respects reduced motion, one focus ring). Completions get a coloured kind badge, a highlighted match, an accent bar on the active row, one-line descriptions and a keyboard-hint footer. Find options are toggle chips with a check mark, buttons use icons, fold toggles are chevrons that appear when the gutter is hovered (folded regions always show theirs), and the editor scrolls with a thin scrollbar.
|
|
13
|
+
- **Theme:** `setTheme()` also writes `--editor-surface`, `--editor-surface-hover`, `--editor-border-strong`, `--editor-accent`, `--editor-accent-soft`, `--editor-accent-contrast` and `--editor-shadow` (see the README); the dark gutter foreground is `#a6a6ab` (was `#858585`).
|
|
14
|
+
|
|
15
|
+
**`@editora/toast`**
|
|
16
|
+
- The toast honours `prefers-contrast: more` (a full-strength border, no shadow, full-strength description text, an always-visible close button) and Windows High Contrast / `forced-colors` (system colours for the card, text, actions, close button and progress bar).
|
|
17
|
+
|
|
18
|
+
## 2.1.0
|
|
19
|
+
|
|
20
|
+
### Minor Changes
|
|
21
|
+
|
|
22
|
+
- ba54cae: Toast: a modern look, a stack that opens on hover, keyboard access and a complete `toast` API.
|
|
23
|
+
|
|
24
|
+
**Look.** The card is now opaque and neutral, with a status icon (one shape per level, a spinner for loading), instead of a 6% tint with a coloured stripe. The old tint made the toast 94% transparent, so the page showed through its text, and in dark mode the primary action button was white on white. The `dark` theme is now dark (it was a white card), `richColors` tints the card, `colored` and `glass` meet 4.5:1 contrast, and every theme was checked at 4.5:1 for text and 3:1 for icons in light and dark. `system` follows `prefers-color-scheme` and the app's own switch (a `dark` class or `data-theme`, `data-bs-theme`, `data-color-scheme`, `data-mantine-color-scheme` on `<html>`). `icon` accepts text, a DOM node or `false`; `configure({ icons: false })` turns the built-in icons off.
|
|
25
|
+
|
|
26
|
+
**Stacking.** Several toasts fold into a deck by default (`stack: true, expand: false`): the newest in full, older ones as edges behind it; hover, focus or a tap opens it into a list. The newest toast is now always nearest the edge of the screen (it was farthest). A dismissed toast leaves the layout at once. `configure({ stack: false })` gives a plain list. The layout uses `translate`/`scale`, so the animation types and swipe-to-dismiss still work.
|
|
27
|
+
|
|
28
|
+
**Behaviour.** Timers hold for the whole stack while it is hovered or focused and keep the time that was left (they used to restart from the full duration); a toast that arrives meanwhile is held too. Toasts are Tab stops; Alt+T (`hotkey`) focuses the newest, Escape dismisses the focused one and hands focus on; `pauseOnFocus` is on by default.
|
|
29
|
+
|
|
30
|
+
**API.** `toast('text')` shows a plain toast, and `toast.show`, `.promise`, `.update`, `.dismiss(id?)` (no id clears all), `.clear` and `.configure` complete the simple API; they do nothing on the server. `toast.promise(…, { success: { title, description } })` now replaces the loading text instead of keeping it.
|
|
31
|
+
|
|
32
|
+
**Fixes.** The progress bar had no styling and a zero-width track, so it never showed; it now sits in the text column and survives a message update. The primary action button took its colours from `:root`, so themed toasts got the wrong fill.
|
|
33
|
+
|
|
34
|
+
**Upgrading.** The layout uses the individual `translate` and `scale` CSS properties, so it needs Chrome 104, Safari 14.1 or Firefox 72 or later. If you styled toasts with CSS, the `::before` accent stripe and the tinted `background` of the level classes are gone: use the `--et-*` variables (`--et-bg`, `--et-text`, `--et-success`, …) or restyle `.editora-toast`. `configure({ stack: false })` restores a list; `configure({ icons: false })` removes the icons. The package is 15 KB gzipped JS plus 5 KB CSS (12 KB + 7 KB before); the README's "9 KB" figure was out of date.
|
|
35
|
+
|
|
3
36
|
## 2.0.10
|
|
4
37
|
|
|
5
38
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
4
|
Toast notifications with no dependencies and nothing to mount: call <code>toast.success('Saved')</code> from
|
|
5
|
-
anywhere.
|
|
5
|
+
anywhere. Status icons, a stack that opens on hover, promise toasts, actions, progress, light and dark, keyboard access.
|
|
6
6
|
</p>
|
|
7
7
|
|
|
8
8
|
<p align="center">
|
|
@@ -19,19 +19,24 @@
|
|
|
19
19
|
</p>
|
|
20
20
|
|
|
21
21
|
<p align="center">
|
|
22
|
-
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/themes.png" alt="
|
|
22
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/themes.png" alt="Eleven toasts stacked in the top-right corner, one in each of the light, dark, colored, minimal, glass, neon, retro, ocean, forest, sunset and midnight themes" width="440">
|
|
23
23
|
</p>
|
|
24
24
|
|
|
25
25
|
## Features
|
|
26
26
|
|
|
27
27
|
- **Nothing to mount.** No provider, no container element: the first call creates what it needs. It works from React,
|
|
28
28
|
Vue, plain JavaScript, a service, or an event handler.
|
|
29
|
+
- **A modern card.** An opaque, neutral surface with a status icon (a different shape for each level, so colour is
|
|
30
|
+
never the only cue), in light and dark. Dark follows the system, or your app's own `.dark` switch.
|
|
31
|
+
- **A stack that opens on hover.** Several toasts fold into a deck, the newest in full; hover it or focus it and it
|
|
32
|
+
opens into a list while the timers wait.
|
|
29
33
|
- **Promise toasts.** One toast follows a promise from *loading* to *success* or *error*.
|
|
30
34
|
- **Actions and progress**: buttons in the toast, and a progress bar with an optional percentage.
|
|
31
35
|
- **Thirteen themes and seven positions**, a queue (three toasts show at once by default), duplicate prevention and
|
|
32
36
|
swipe-to-dismiss.
|
|
33
|
-
- **
|
|
34
|
-
|
|
37
|
+
- **Keyboard and screen readers.** Alt+T jumps to the toasts, Escape dismisses one, errors are announced as alerts and
|
|
38
|
+
the rest politely, and `prefers-reduced-motion` is respected.
|
|
39
|
+
- **Small.** 15 KB gzipped plus 5 KB of CSS. No dependencies.
|
|
35
40
|
- **Safe on the server.** The package imports in Node and the calls do nothing there, so a call in shared code does not
|
|
36
41
|
break server rendering.
|
|
37
42
|
- Written in TypeScript. A script tag works too (a UMD build).
|
|
@@ -55,20 +60,23 @@ toast.error('Upload failed');
|
|
|
55
60
|
```
|
|
56
61
|
|
|
57
62
|
<p align="center">
|
|
58
|
-
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/levels.png" alt="Three toasts in the bottom-right corner: Document saved
|
|
63
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/levels.png" alt="Three toasts in the bottom-right corner, each with an icon: Document saved with a green check, A new version is available with a blue i and Storage is almost full with an orange warning triangle" width="440">
|
|
59
64
|
</p>
|
|
60
65
|
|
|
61
66
|
Toasts appear in the bottom-right corner and go away after four seconds. Three are visible at once; the rest wait in a
|
|
62
|
-
queue (a fourth toast, *Upload failed* above, appears when there is room).
|
|
67
|
+
queue (a fourth toast, *Upload failed* above, appears when there is room). With more than one toast showing they fold
|
|
68
|
+
into a deck: see [Stacking](#stacking).
|
|
63
69
|
|
|
64
|
-
`toast` is
|
|
65
|
-
a message and, if you like, an options object or a
|
|
66
|
-
`
|
|
70
|
+
`toast` is all you need. Call it with a message for a plain toast, or use `toast.info`, `toast.success`,
|
|
71
|
+
`toast.warning`, `toast.error` and `toast.loading`, each taking a message and, if you like, an options object or a
|
|
72
|
+
duration in milliseconds. `toast.show`, `toast.promise`, `toast.update`, `toast.dismiss`, `toast.clear` and
|
|
73
|
+
`toast.configure` cover the rest. `toastAdvanced` (also exported as `toastPro`) is the same plus groups, plugins and
|
|
74
|
+
subscriptions.
|
|
67
75
|
|
|
68
76
|
## Titles, actions and progress
|
|
69
77
|
|
|
70
78
|
```ts
|
|
71
|
-
import {
|
|
79
|
+
import { toast } from '@editora/toast';
|
|
72
80
|
import '@editora/toast/toast.css';
|
|
73
81
|
|
|
74
82
|
// A toast with a title, a description, actions and progress. duration: 0 keeps it until it is dismissed.
|
|
@@ -92,18 +100,19 @@ const upload = toast.show({
|
|
|
92
100
|
```
|
|
93
101
|
|
|
94
102
|
<p align="center">
|
|
95
|
-
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/actions.png" alt="A toast titled Report ready with a description and Open and Dismiss buttons, under a toast that says Uploading photos" width="440">
|
|
103
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/actions.png" alt="A toast titled Report ready with a description and Open and Dismiss buttons, under a toast that says Uploading photos with a progress bar at 64 percent" width="440">
|
|
96
104
|
</p>
|
|
97
105
|
|
|
98
106
|
`show()` returns the toast: `dismiss()` removes it and `update(options)` changes it. Pressing an action runs its `onClick`
|
|
99
|
-
and closes the toast; give the action `dismissOnClick: false` to keep the toast open.
|
|
107
|
+
and closes the toast; give the action `dismissOnClick: false` to keep the toast open. The progress bar follows
|
|
108
|
+
`update(id, { progress })`.
|
|
100
109
|
|
|
101
110
|
## Promises and updates
|
|
102
111
|
|
|
103
112
|
`toast.promise()` shows one toast that becomes the result of a promise, and `update()` changes any toast by id:
|
|
104
113
|
|
|
105
114
|
```ts
|
|
106
|
-
import {
|
|
115
|
+
import { toast } from '@editora/toast';
|
|
107
116
|
import '@editora/toast/toast.css';
|
|
108
117
|
|
|
109
118
|
const saveDocument = new Promise<{ name: string }>((resolve) => {
|
|
@@ -126,8 +135,8 @@ setTimeout(() => {
|
|
|
126
135
|
|
|
127
136
|
<table>
|
|
128
137
|
<tr>
|
|
129
|
-
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/promise-loading.png" alt="Two toasts that read Saving document and Syncing"></td>
|
|
130
|
-
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/promise-success.png" alt="The same toasts after the promise resolved and the update: Saved Q3-summary.pdf and Everything is up to date"></td>
|
|
138
|
+
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/promise-loading.png" alt="Two toasts that read Saving document and Syncing, each with a spinner"></td>
|
|
139
|
+
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/promise-success.png" alt="The same toasts after the promise resolved and the update: Saved Q3-summary.pdf and Everything is up to date, each with a green check"></td>
|
|
131
140
|
</tr>
|
|
132
141
|
<tr>
|
|
133
142
|
<td align="center"><sub>While it works</sub></td>
|
|
@@ -136,14 +145,73 @@ setTimeout(() => {
|
|
|
136
145
|
</table>
|
|
137
146
|
|
|
138
147
|
`toast.promise()` returns the promise you gave it, so you can still `await` it. If you only need the message, `success`
|
|
139
|
-
and `error` can be plain strings
|
|
148
|
+
and `error` can be plain strings; they can also be options (`{ title, description, actions }`), which replace the
|
|
149
|
+
loading text.
|
|
150
|
+
|
|
151
|
+
## Stacking
|
|
152
|
+
|
|
153
|
+
```ts
|
|
154
|
+
import { toast } from '@editora/toast';
|
|
155
|
+
import '@editora/toast/toast.css';
|
|
156
|
+
|
|
157
|
+
// By default several toasts fold into a deck: the newest in full, the others as edges behind it.
|
|
158
|
+
// Hover the deck (or press Alt+T) and it opens into a list; the timers wait while it is open.
|
|
159
|
+
toast.success('Document saved');
|
|
160
|
+
toast.info('A new version is available');
|
|
161
|
+
toast.warning('Storage is almost full');
|
|
162
|
+
|
|
163
|
+
// Prefer a plain list that is always open?
|
|
164
|
+
// toast.configure({ stack: false });
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
<table>
|
|
168
|
+
<tr>
|
|
169
|
+
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/deck-closed.png" alt="Three toasts folded into a deck: Storage is almost full in front, with the edges of the two older toasts behind it"></td>
|
|
170
|
+
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/deck-open.png" alt="The same toasts opened into a list, the newest nearest the corner"></td>
|
|
171
|
+
</tr>
|
|
172
|
+
<tr>
|
|
173
|
+
<td align="center"><sub>Folded</sub></td>
|
|
174
|
+
<td align="center"><sub>Hovered or focused</sub></td>
|
|
175
|
+
</tr>
|
|
176
|
+
</table>
|
|
177
|
+
|
|
178
|
+
The newest toast is always the one nearest the edge of the screen. While the deck is open, the timers of its toasts wait,
|
|
179
|
+
and a toast that arrives meanwhile waits with them. A toast that is dismissed leaves at once and the others close the gap.
|
|
180
|
+
`stack: false` keeps a plain list; `stack: true, expand: true` shows a list that is always open.
|
|
181
|
+
|
|
182
|
+
On a touch screen a tap opens the deck; a tap elsewhere closes it.
|
|
183
|
+
|
|
184
|
+
## Icons
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
import { toast } from '@editora/toast';
|
|
188
|
+
import '@editora/toast/toast.css';
|
|
189
|
+
|
|
190
|
+
// A list instead of a deck, so all four are visible at once.
|
|
191
|
+
toast.configure({ maxVisible: 4, stack: false });
|
|
192
|
+
|
|
193
|
+
toast.success('Saved'); // the icon of the level
|
|
194
|
+
toast('Copied to clipboard'); // no level, no icon
|
|
195
|
+
toast.info('Invite sent', { icon: '✉️' }); // your own: text, an emoji or a DOM node
|
|
196
|
+
toast.error('Payment failed', { icon: false }); // none
|
|
197
|
+
|
|
198
|
+
// Or switch the built-in icons off everywhere:
|
|
199
|
+
// toast.configure({ icons: false });
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
<p align="center">
|
|
203
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/icons.png" alt="Four toasts: Saved with a green check, Copied to clipboard without an icon, Invite sent with an envelope emoji and Payment failed without an icon" width="440">
|
|
204
|
+
</p>
|
|
205
|
+
|
|
206
|
+
The built-in icons are drawn in SVG from the level's colour (`--et-success`, `--et-error`, ...) and are hidden from screen
|
|
207
|
+
readers; the message carries the meaning. `icon` takes a string (text or an emoji), a DOM node, or `false`.
|
|
140
208
|
|
|
141
209
|
## In React, and in any framework
|
|
142
210
|
|
|
143
211
|
There is nothing to render. Call `toast` from a handler, an effect or a service:
|
|
144
212
|
|
|
145
213
|
```tsx
|
|
146
|
-
import {
|
|
214
|
+
import { toast } from '@editora/toast';
|
|
147
215
|
import '@editora/toast/toast.css';
|
|
148
216
|
|
|
149
217
|
async function saveDraft() {
|
|
@@ -169,6 +237,9 @@ export default function SaveButton() {
|
|
|
169
237
|
}
|
|
170
238
|
```
|
|
171
239
|
|
|
240
|
+
[`@editora/ui-react`](https://www.npmjs.com/package/@editora/ui-react) also has a `ToastProvider` and a `useToast()` hook
|
|
241
|
+
if you like a provider.
|
|
242
|
+
|
|
172
243
|
## From a script tag
|
|
173
244
|
|
|
174
245
|
The UMD build defines three globals: `toast`, `toastAdvanced` and `toastPro` (the same object as `toastAdvanced`).
|
|
@@ -203,7 +274,7 @@ Pin a version in production, as here:
|
|
|
203
274
|
`configure()` sets the defaults for every toast from then on. A single toast can still override them:
|
|
204
275
|
|
|
205
276
|
```ts
|
|
206
|
-
import {
|
|
277
|
+
import { toast } from '@editora/toast';
|
|
207
278
|
import '@editora/toast/toast.css';
|
|
208
279
|
|
|
209
280
|
// Settings for every toast from now on. A toast can still override them.
|
|
@@ -229,16 +300,18 @@ toast.warning('Your plan renews tomorrow', { theme: 'sunset', duration: 0 });
|
|
|
229
300
|
| `queueStrategy` | `'fifo'` | `'fifo'` or `'lifo'`: which waiting toast comes next. |
|
|
230
301
|
| `theme` | `'system'` | One of the [themes](#themes). |
|
|
231
302
|
| `closeButton` | `false` | Show a close button on every toast. |
|
|
303
|
+
| `icons` | `true` | Show the built-in status icons. |
|
|
232
304
|
| `preventDuplicate` | `false` | Drop a toast whose content is already showing. With `dedupeScope`: `'visible'`, `'queue'` or `'all'` (the default). |
|
|
233
|
-
| `
|
|
305
|
+
| `stack`, `expand`, `gap` | `true`, `false`, `8` | A deck that opens on hover (`stack`), a list that is always open (`expand`, or `stack: false`), and the gap between toasts. |
|
|
306
|
+
| `pauseOnHover`, `pauseOnFocus`, `pauseOnWindowBlur` | `true`, `true`, `false` | Hold the timers while the pointer is over the stack, a toast has keyboard focus, or the window is in the background. The time that was left is kept. |
|
|
307
|
+
| `hotkey` | `'alt+t'` | A shortcut that moves focus to the toasts, for example `'ctrl+shift+k'`; `false` turns it off. |
|
|
234
308
|
| `swipeDismiss`, `swipeDirection`, `dragDismiss` | `true`, `'any'`, `false` | Dismiss by swiping, in which direction, and by dragging. |
|
|
235
|
-
| `stack`, `expand`, `gap` | `false`, `true`, `8` | How several visible toasts are laid out, and the gap between them. |
|
|
236
309
|
| `offset`, `mobileOffset`, `zIndex` | `16`, `16`, none | The distance from the edge of the screen, on desktop and on mobile, and the stacking order. |
|
|
237
310
|
| `rtl` | `false` | Right-to-left layout. |
|
|
238
|
-
| `richColors` | `false` |
|
|
311
|
+
| `richColors` | `false` | Tint each toast with the colour of its level. |
|
|
239
312
|
| `container` | the page body | The element toasts are added to. |
|
|
240
313
|
|
|
241
|
-
`toast.getConfig()` returns the current settings.
|
|
314
|
+
`toast.getConfig()` (on `toastAdvanced`) returns the current settings.
|
|
242
315
|
|
|
243
316
|
## Themes
|
|
244
317
|
|
|
@@ -246,13 +319,14 @@ toast.warning('Your plan renews tomorrow', { theme: 'sunset', duration: 0 });
|
|
|
246
319
|
`custom`. Set one for all toasts with `configure({ theme })`, or for one toast with `{ theme }`:
|
|
247
320
|
|
|
248
321
|
```ts
|
|
249
|
-
import {
|
|
322
|
+
import { toast } from '@editora/toast';
|
|
250
323
|
import '@editora/toast/toast.css';
|
|
251
324
|
|
|
252
|
-
|
|
325
|
+
// A deck would fold these into one; stack: false keeps them in a list.
|
|
326
|
+
toast.configure({ position: 'top-right', maxVisible: 12, stack: false, gap: 8 });
|
|
253
327
|
|
|
254
328
|
const themes = [
|
|
255
|
-
'light', 'colored', 'minimal', 'glass', 'neon', 'retro', 'ocean', 'forest', 'sunset', 'midnight'
|
|
329
|
+
'light', 'dark', 'colored', 'minimal', 'glass', 'neon', 'retro', 'ocean', 'forest', 'sunset', 'midnight'
|
|
256
330
|
] as const;
|
|
257
331
|
|
|
258
332
|
for (const theme of themes) {
|
|
@@ -260,16 +334,32 @@ for (const theme of themes) {
|
|
|
260
334
|
}
|
|
261
335
|
```
|
|
262
336
|
|
|
263
|
-
The picture at the top of this page is that code. `system` (the default) follows the operating system's light or
|
|
264
|
-
|
|
265
|
-
|
|
337
|
+
The picture at the top of this page is that code. `system` (the default) follows the operating system's light or dark
|
|
338
|
+
setting, and your app's own switch: a `dark` class, or `data-theme="dark"`, `data-bs-theme="dark"`,
|
|
339
|
+
`data-color-scheme="dark"` or `data-mantine-color-scheme="dark"` on the `<html>` element (and `light` for an app that is
|
|
340
|
+
light while the system is dark). Each toast carries `data-theme` and level classes (`editora-toast-info`, ...).
|
|
341
|
+
|
|
342
|
+
A theme is a set of CSS variables, so you can make your own with a few lines (the `custom` theme leaves the colours to you):
|
|
343
|
+
|
|
344
|
+
```css
|
|
345
|
+
.editora-toast[data-theme="custom"] {
|
|
346
|
+
--et-bg: #fffbeb;
|
|
347
|
+
--et-text: #292524;
|
|
348
|
+
--et-text-muted: #78716c;
|
|
349
|
+
--et-border: #fcd34d;
|
|
350
|
+
--et-success: #15803d; /* the colour of the success icon; also --et-error, --et-warning, --et-info, --et-loading */
|
|
351
|
+
--et-radius: 16px;
|
|
352
|
+
}
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
`--et-width`, `--et-font`, `--et-shadow`, `--et-action-bg` and `--et-action-ink` (the primary button) are variables too.
|
|
266
356
|
|
|
267
357
|
## Positions
|
|
268
358
|
|
|
269
359
|
`top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right` and `center`:
|
|
270
360
|
|
|
271
361
|
```ts
|
|
272
|
-
import {
|
|
362
|
+
import { toast } from '@editora/toast';
|
|
273
363
|
import '@editora/toast/toast.css';
|
|
274
364
|
|
|
275
365
|
toast.configure({ maxVisible: 10 });
|
|
@@ -297,7 +387,7 @@ Everything `show()` accepts. All of it is optional except a message (or a title)
|
|
|
297
387
|
| --- | --- |
|
|
298
388
|
| `message`, `title`, `description` | The text. |
|
|
299
389
|
| `level` | `'info'`, `'success'`, `'warning'`, `'error'` or `'loading'`. |
|
|
300
|
-
| `icon` |
|
|
390
|
+
| `icon` | Your own icon: a string (text or an emoji) or a DOM node; `false` for none. Left out, the level's icon. |
|
|
301
391
|
| `actions`, `action`, `cancel` | Buttons: `{ label, onClick, primary?, dismissOnClick? }`. |
|
|
302
392
|
| `progress` | `{ value, showPercentage? }`, with `value` from 0 to 100. |
|
|
303
393
|
| `duration`, `persistent` | How long it stays (`0`, or `persistent: true`, keeps it until dismissed). |
|
|
@@ -317,21 +407,34 @@ Everything `show()` accepts. All of it is optional except a message (or a title)
|
|
|
317
407
|
|
|
318
408
|
Toasts live in a region that is announced politely. An **error** toast is a `role="alert"` with `aria-live="assertive"`,
|
|
319
409
|
so a screen reader interrupts to read it; every other level is `role="status"` with `aria-live="polite"`. The close button
|
|
320
|
-
is labelled "Close notification"
|
|
321
|
-
|
|
410
|
+
is labelled "Close notification", and the icons are decorative (a different shape for each level, so a toast is not told
|
|
411
|
+
apart by colour alone). Override the announcement of one toast with `role` and `ariaLive`.
|
|
412
|
+
|
|
413
|
+
**Keyboard.** Every toast is a Tab stop, so its buttons can be reached before it goes away. **Alt+T** (`hotkey`) moves
|
|
414
|
+
focus to the newest toast and opens the stack; **Escape** dismisses the focused toast and moves on to the next one, or back
|
|
415
|
+
to where you were. While a toast has keyboard focus, or the pointer is over the stack, the timers wait. With
|
|
416
|
+
`prefers-reduced-motion` the toasts fade instead of sliding.
|
|
322
417
|
|
|
323
418
|
## API
|
|
324
419
|
|
|
325
|
-
`
|
|
420
|
+
`toast`:
|
|
421
|
+
|
|
422
|
+
| Method | |
|
|
423
|
+
| --- | --- |
|
|
424
|
+
| `toast(message, options?)` | A plain toast, with no level and no icon. |
|
|
425
|
+
| `info`, `success`, `warning`, `error`, `loading` `(message, options?)` | A toast of that level. |
|
|
426
|
+
| `show(options)` | Show a toast from full options; returns `{ id, options, dismiss(), update(options) }`. |
|
|
427
|
+
| `promise(promise, { loading, success, error })` | A toast that follows a promise (also `onSuccess` and `onError`); resolves with the promise's value. |
|
|
428
|
+
| `update(id, options)` | Change a toast. |
|
|
429
|
+
| `dismiss(id?)` / `clear()` | Remove one toast, or (with no id) every toast. |
|
|
430
|
+
| `configure(settings)` | Set the [settings](#configure-it). |
|
|
431
|
+
|
|
432
|
+
`toastAdvanced` (`toastPro`) has all of those and more:
|
|
326
433
|
|
|
327
434
|
| Method | |
|
|
328
435
|
| --- | --- |
|
|
329
|
-
| `show(options)` | Show a toast; returns `{ id, options, dismiss(), update(options) }`. |
|
|
330
|
-
| `info`, `success`, `warning`, `error`, `loading` `(message, options?)` | Shorthands for `show`. |
|
|
331
|
-
| `update(id, options)` / `dismiss(id)` / `clear()` | Change, remove or remove every toast. |
|
|
332
|
-
| `promise(promise, { loading, success, error })` | A toast that follows a promise; also `onSuccess` and `onError` callbacks. |
|
|
333
436
|
| `group(id, options)` | Show a toast that belongs to a group. |
|
|
334
|
-
| `
|
|
437
|
+
| `getConfig()` | Read the settings. |
|
|
335
438
|
| `getToasts()` / `getGroups()` / `getState()` | The toasts, the groups, or both with the queue and the settings. |
|
|
336
439
|
| `subscribe(listener)` | Call `listener(state)` when the toasts change; returns an unsubscribe function. |
|
|
337
440
|
| `use(plugin)` | Install a plugin: `{ name, install(manager), uninstall? }`. |
|
|
@@ -342,6 +445,23 @@ The classes and types are exported too: `ToastManager`, and `ToastOptions`, `Toa
|
|
|
342
445
|
`ToastPosition`, `ToastTheme`, `ToastPromiseOptions` and more. If you are upgrading from 1.x, see the
|
|
343
446
|
[migration guide](https://github.com/ajaykr089/Editora/blob/main/packages/editora-toast/MIGRATION_GUIDE.md).
|
|
344
447
|
|
|
448
|
+
## Upgrading from 2.0
|
|
449
|
+
|
|
450
|
+
2.1 changes how toasts look and where they sit; nothing was removed.
|
|
451
|
+
|
|
452
|
+
- **The look.** The card is opaque and neutral, with a status icon, instead of a see-through tint with a coloured stripe
|
|
453
|
+
(the page showed through the text). The `dark` theme is dark (it was a white card), and the primary button is readable in
|
|
454
|
+
dark mode. `richColors` gives the tinted card back. `configure({ icons: false })` removes the icons.
|
|
455
|
+
- **Stacking.** Several toasts fold into a deck by default, and the newest toast is nearest the edge of the screen (it
|
|
456
|
+
used to be farthest). To get a plain list: `configure({ stack: false })`.
|
|
457
|
+
- **Timers.** Hovering or focusing the stack holds every toast and keeps the time that was left; before, each toast was
|
|
458
|
+
held on its own and started again from the full duration.
|
|
459
|
+
- **Keyboard.** Toasts are Tab stops, Alt+T and Escape work, and `pauseOnFocus` is on. `configure({ hotkey: false })` turns the shortcut off.
|
|
460
|
+
- **The simple API** gained `toast(message)`, `promise`, `update`, `dismiss`, `clear`, `configure` and `show`.
|
|
461
|
+
- **Browsers.** The layout uses the individual `translate` and `scale` properties: Chrome 104, Safari 14.1, Firefox 72 or later.
|
|
462
|
+
- If you styled toasts with CSS, the accent stripe (`::before`) and the tinted `background` of the level classes are gone: set
|
|
463
|
+
`--et-*` variables or `--et-accent`, or restyle `.editora-toast`.
|
|
464
|
+
|
|
345
465
|
## Part of Editora
|
|
346
466
|
|
|
347
467
|
[`@editora/ui-react`](https://www.npmjs.com/package/@editora/ui-react) depends on this package.
|
|
@@ -6,7 +6,6 @@ export declare class ToastManager implements IToastManager {
|
|
|
6
6
|
private lifecycle;
|
|
7
7
|
private config;
|
|
8
8
|
private idCounter;
|
|
9
|
-
private pausedToasts;
|
|
10
9
|
private pendingShows;
|
|
11
10
|
private subscribers;
|
|
12
11
|
private windowFocusHandler?;
|
|
@@ -32,6 +31,7 @@ export declare class ToastManager implements IToastManager {
|
|
|
32
31
|
warning(message: string, duration?: number): ToastInstance;
|
|
33
32
|
loading(message: string, duration?: number): ToastInstance;
|
|
34
33
|
private normalizeOptions;
|
|
34
|
+
private normalizeResult;
|
|
35
35
|
private normalizeConfig;
|
|
36
36
|
private normalizeToastOptions;
|
|
37
37
|
private showToasts;
|
|
@@ -3,21 +3,42 @@ export declare class ToastRenderer {
|
|
|
3
3
|
private containers;
|
|
4
4
|
private config;
|
|
5
5
|
private cssInjected;
|
|
6
|
+
private toastOf;
|
|
7
|
+
private holds;
|
|
8
|
+
private timing;
|
|
9
|
+
private resizeTimer?;
|
|
10
|
+
private returnFocusTo;
|
|
11
|
+
private globalListeners;
|
|
6
12
|
constructor(config: ToastConfig);
|
|
7
13
|
updateConfig(config: ToastConfig): void;
|
|
8
14
|
ensureContainer(position: ToastPosition): HTMLElement;
|
|
15
|
+
private attachContainerListeners;
|
|
16
|
+
private syncOpen;
|
|
17
|
+
private isKeyboardFocus;
|
|
18
|
+
private onContainerKey;
|
|
19
|
+
private restoreFocus;
|
|
20
|
+
private attachGlobalListeners;
|
|
21
|
+
private matchesHotkey;
|
|
22
|
+
private layout;
|
|
23
|
+
private toPx;
|
|
24
|
+
holdAll(container: HTMLElement, reason: string): void;
|
|
25
|
+
releaseAll(container: HTMLElement, reason: string): void;
|
|
9
26
|
createToastElement(toast: ToastInstance): HTMLElement;
|
|
10
27
|
showToast(toast: ToastInstance): Promise<void>;
|
|
11
28
|
hideToast(toast: ToastInstance): Promise<void>;
|
|
12
29
|
updateToast(toast: ToastInstance, updates: Partial<ToastInstance['options']>): Promise<void>;
|
|
13
30
|
private createContent;
|
|
31
|
+
private createProgress;
|
|
14
32
|
private createCloseButton;
|
|
33
|
+
private createIcon;
|
|
15
34
|
private createActionButton;
|
|
16
35
|
private applyContainerStyles;
|
|
17
|
-
private applyStackState;
|
|
18
36
|
private toCssLength;
|
|
19
|
-
private
|
|
20
|
-
private
|
|
37
|
+
private startTimer;
|
|
38
|
+
private arm;
|
|
39
|
+
private stopTimer;
|
|
40
|
+
pauseToast(toast: ToastInstance, reason?: string): void;
|
|
41
|
+
resumeToast(toast: ToastInstance, reason?: string): void;
|
|
21
42
|
private addSwipeDismiss;
|
|
22
43
|
private addDragDismiss;
|
|
23
44
|
private announceToast;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export interface StackSettings {
|
|
2
|
+
stack: boolean;
|
|
3
|
+
expand: boolean;
|
|
4
|
+
gap: number;
|
|
5
|
+
}
|
|
6
|
+
export declare function invalidateHeight(element: HTMLElement): void;
|
|
7
|
+
export declare function isExpanded(container: HTMLElement, settings: StackSettings): boolean;
|
|
8
|
+
export declare function layoutStack(container: HTMLElement, settings: StackSettings, remeasureAll?: boolean): void;
|
package/dist/core/types.d.ts
CHANGED
|
@@ -84,7 +84,7 @@ export interface ToastContent {
|
|
|
84
84
|
message?: string;
|
|
85
85
|
title?: string;
|
|
86
86
|
description?: string;
|
|
87
|
-
icon?: string;
|
|
87
|
+
icon?: string | false | Node;
|
|
88
88
|
actions?: ToastAction[];
|
|
89
89
|
action?: ToastAction;
|
|
90
90
|
cancel?: ToastAction;
|
|
@@ -165,6 +165,8 @@ export interface ToastConfig {
|
|
|
165
165
|
rtl: boolean;
|
|
166
166
|
enableAccessibility: boolean;
|
|
167
167
|
closeButton: boolean;
|
|
168
|
+
icons: boolean;
|
|
169
|
+
hotkey: string | false;
|
|
168
170
|
preventDuplicate: boolean;
|
|
169
171
|
dedupeScope: 'visible' | 'queue' | 'all';
|
|
170
172
|
container?: HTMLElement;
|