@gopherium/godmin 0.27.0 → 0.28.0
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 +0 -5
- package/dist/base.css +49 -30
- package/dist/toaster.d.ts +7 -9
- package/dist/toaster.js +41 -53
- package/docs/build-and-versioning.md +29 -0
- package/docs/design-system/accessibility.md +15 -21
- package/docs/design-system/color.md +1 -1
- package/docs/design-system/custom-properties.md +2 -5
- package/docs/design-system/layout.md +1 -1
- package/docs/design-system/motion.md +26 -21
- package/docs/design-system/overview.md +10 -4
- package/docs/design-system/radius-and-elevation.md +10 -4
- package/docs/design-system/toasts.md +187 -0
- package/docs/design-system/typography.md +1 -1
- package/docs/lists.md +4 -20
- package/docs/loading-and-feedback.md +27 -69
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -26,11 +26,6 @@ pnpm add @gopherium/godmin
|
|
|
26
26
|
The design system packages are peer dependencies, so your application resolves
|
|
27
27
|
and pins them. GodMin never redistributes them.
|
|
28
28
|
|
|
29
|
-
## Browsers
|
|
30
|
-
|
|
31
|
-
GodMin needs `Intl.Segmenter`, which every browser WordPress supports has:
|
|
32
|
-
Chrome and Edge 87, Safari 14.1 and Firefox 125 or newer.
|
|
33
|
-
|
|
34
29
|
## Setup
|
|
35
30
|
|
|
36
31
|
Import the stylesheet once at your entry point, then mount `AdminRoot` around
|
package/dist/base.css
CHANGED
|
@@ -279,26 +279,50 @@ body {
|
|
|
279
279
|
.godmin-toasts {
|
|
280
280
|
position: fixed;
|
|
281
281
|
inset-inline: 0;
|
|
282
|
-
bottom:
|
|
282
|
+
bottom: var(--wpds-dimension-size-md);
|
|
283
283
|
z-index: 1;
|
|
284
284
|
display: flex;
|
|
285
285
|
flex-direction: column;
|
|
286
|
-
align-items: center;
|
|
287
|
-
gap: var(--wpds-dimension-gap-sm);
|
|
288
286
|
padding-inline: 16px;
|
|
289
287
|
box-sizing: border-box;
|
|
290
288
|
pointer-events: none;
|
|
291
289
|
}
|
|
292
290
|
|
|
293
|
-
:root:has(.godmin-layout__sidebar) .godmin-toasts {
|
|
294
|
-
inset-inline-start: var(--godmin-nav-sidebar-width);
|
|
295
|
-
inset-inline-end: var(--godmin-canvas-margin);
|
|
296
|
-
}
|
|
297
|
-
|
|
298
291
|
.godmin-toasts:focus {
|
|
299
292
|
outline: none;
|
|
300
293
|
}
|
|
301
294
|
|
|
295
|
+
.godmin-toasts__item {
|
|
296
|
+
display: grid;
|
|
297
|
+
grid-template-rows: 1fr;
|
|
298
|
+
animation: godmin-toast-grow var(--wpds-motion-duration-lg) cubic-bezier(0, 0, 0.2, 1);
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
.godmin-toasts__item--leaving {
|
|
302
|
+
animation:
|
|
303
|
+
godmin-toast-grow var(--wpds-motion-duration-lg) cubic-bezier(0, 0, 0.2, 1),
|
|
304
|
+
godmin-toast-shrink 450ms cubic-bezier(0.4, 0, 0.1, 1) var(--wpds-motion-duration-sm) forwards;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
.godmin-toasts__item-inner {
|
|
308
|
+
display: flex;
|
|
309
|
+
flex-direction: column;
|
|
310
|
+
align-items: center;
|
|
311
|
+
min-height: 0;
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
@keyframes godmin-toast-grow {
|
|
315
|
+
0% {
|
|
316
|
+
grid-template-rows: 0fr;
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
@keyframes godmin-toast-shrink {
|
|
321
|
+
100% {
|
|
322
|
+
grid-template-rows: 0fr;
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
|
|
302
326
|
.godmin-toast {
|
|
303
327
|
display: flex;
|
|
304
328
|
align-items: baseline;
|
|
@@ -320,20 +344,25 @@ body {
|
|
|
320
344
|
font-size: var(--wpds-typography-font-size-md);
|
|
321
345
|
line-height: 1.4;
|
|
322
346
|
overflow-wrap: anywhere;
|
|
323
|
-
cursor:
|
|
347
|
+
cursor: var(--wpds-cursor-control);
|
|
324
348
|
pointer-events: auto;
|
|
325
|
-
animation: godmin-fade-in
|
|
349
|
+
animation: godmin-fade-in 250ms cubic-bezier(0, 0, 0.2, 1) var(--wpds-motion-duration-xs) backwards;
|
|
326
350
|
}
|
|
327
351
|
|
|
328
352
|
.godmin-toast--leaving {
|
|
329
|
-
animation:
|
|
353
|
+
animation:
|
|
354
|
+
godmin-fade-in 250ms cubic-bezier(0, 0, 0.2, 1) var(--wpds-motion-duration-xs) backwards,
|
|
355
|
+
godmin-fade-out var(--wpds-motion-duration-sm) cubic-bezier(0, 0, 0.2, 1) forwards;
|
|
330
356
|
}
|
|
331
357
|
|
|
332
358
|
.godmin-toast--plain {
|
|
333
359
|
margin: 0;
|
|
334
360
|
border: 0;
|
|
335
361
|
text-align: start;
|
|
336
|
-
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
.godmin-toasts__item-inner > .godmin-toast {
|
|
365
|
+
margin-block-start: var(--wpds-dimension-gap-sm);
|
|
337
366
|
}
|
|
338
367
|
|
|
339
368
|
.godmin-toast__action {
|
|
@@ -355,17 +384,6 @@ body {
|
|
|
355
384
|
text-decoration: none;
|
|
356
385
|
}
|
|
357
386
|
|
|
358
|
-
.godmin-toast__dismiss {
|
|
359
|
-
flex: none;
|
|
360
|
-
margin-inline-start: var(--wpds-dimension-gap-xl);
|
|
361
|
-
padding: 0;
|
|
362
|
-
border: 0;
|
|
363
|
-
background: none;
|
|
364
|
-
color: inherit;
|
|
365
|
-
font: inherit;
|
|
366
|
-
cursor: var(--wpds-cursor-control);
|
|
367
|
-
}
|
|
368
|
-
|
|
369
387
|
.godmin-toast--plain:focus-visible {
|
|
370
388
|
box-shadow:
|
|
371
389
|
inset 0 0 0 var(--wpds-border-width-xs) #fff,
|
|
@@ -373,8 +391,8 @@ body {
|
|
|
373
391
|
}
|
|
374
392
|
|
|
375
393
|
.godmin-toast__action:focus-visible {
|
|
376
|
-
outline: var(--wpds-border-width-
|
|
377
|
-
outline-offset:
|
|
394
|
+
outline: var(--wpds-border-width-focus) solid #fff;
|
|
395
|
+
outline-offset: var(--wpds-border-width-focus);
|
|
378
396
|
border-radius: var(--wpds-border-radius-sm);
|
|
379
397
|
text-decoration: none;
|
|
380
398
|
}
|
|
@@ -982,10 +1000,6 @@ body {
|
|
|
982
1000
|
}
|
|
983
1001
|
|
|
984
1002
|
@keyframes godmin-fade-out {
|
|
985
|
-
0% {
|
|
986
|
-
opacity: 1;
|
|
987
|
-
}
|
|
988
|
-
|
|
989
1003
|
100% {
|
|
990
1004
|
opacity: 0;
|
|
991
1005
|
}
|
|
@@ -994,9 +1008,14 @@ body {
|
|
|
994
1008
|
@media (prefers-reduced-motion: reduce) {
|
|
995
1009
|
.godmin-loading-screen,
|
|
996
1010
|
.godmin-loading-rows,
|
|
997
|
-
.godmin-arrival
|
|
1011
|
+
.godmin-arrival {
|
|
1012
|
+
animation-duration: 1ms;
|
|
1013
|
+
}
|
|
1014
|
+
|
|
1015
|
+
.godmin-toasts__item,
|
|
998
1016
|
.godmin-toast {
|
|
999
1017
|
animation-duration: 1ms;
|
|
1018
|
+
animation-delay: 0s;
|
|
1000
1019
|
}
|
|
1001
1020
|
|
|
1002
1021
|
.godmin-navigation__screen-wrapper {
|
package/dist/toaster.d.ts
CHANGED
|
@@ -5,8 +5,6 @@ export interface ToastAction {
|
|
|
5
5
|
}
|
|
6
6
|
export interface ToasterHandle {
|
|
7
7
|
show: (message: string, action?: ToastAction) => void;
|
|
8
|
-
/** The title cut to the toaster's name length, with an ellipsis when cut. */
|
|
9
|
-
name: (title: string) => string;
|
|
10
8
|
}
|
|
11
9
|
/**
|
|
12
10
|
* Returns the handle raising messages in the toast region.
|
|
@@ -16,18 +14,18 @@ export declare function useToaster(): ToasterHandle;
|
|
|
16
14
|
export interface ToasterProps {
|
|
17
15
|
/** The tree the toast region wraps. */
|
|
18
16
|
children: ReactNode;
|
|
19
|
-
/** How many milliseconds a toast
|
|
17
|
+
/** How many milliseconds a toast with no action stays on screen when nobody touches it. */
|
|
20
18
|
dismissAfter?: number;
|
|
21
|
-
/**
|
|
19
|
+
/** How many milliseconds a toast with an action stays on screen when nobody touches it. */
|
|
20
|
+
actionDismissAfter?: number;
|
|
21
|
+
/** The hint screen readers hear after the message of a plain toast, that a click clears it. */
|
|
22
22
|
dismissLabel?: string;
|
|
23
23
|
/** How many toasts stay on screen at once, the oldest leaving first. */
|
|
24
24
|
limit?: number;
|
|
25
|
-
/** How many characters of a name a toast shows before the ellipsis. */
|
|
26
|
-
nameLength?: number;
|
|
27
25
|
}
|
|
28
26
|
/**
|
|
29
|
-
* Renders the region holding raised messages around the given tree.
|
|
30
|
-
* @param props - The tree the region wraps, the
|
|
27
|
+
* Renders the region holding raised messages around the given tree, under the snackbar corners at every preset.
|
|
28
|
+
* @param props - The tree the region wraps, the time of each kind of toast, the plain toast hint and how many stay.
|
|
31
29
|
* @returns The wrapped tree with its region.
|
|
32
30
|
*/
|
|
33
|
-
export declare function Toaster({ children, dismissAfter, dismissLabel, limit,
|
|
31
|
+
export declare function Toaster({ children, dismissAfter, actionDismissAfter, dismissLabel, limit, }: ToasterProps): import("react").JSX.Element;
|
package/dist/toaster.js
CHANGED
|
@@ -2,45 +2,24 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
|
2
2
|
/* oxlint-disable react/only-export-components -- the region ships beside the
|
|
3
3
|
hook that reaches it. */
|
|
4
4
|
import { speak } from '@wordpress/a11y';
|
|
5
|
+
import { ThemeProvider } from '@wordpress/theme';
|
|
5
6
|
import { createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, } from 'react';
|
|
6
7
|
/**
|
|
7
|
-
* How long a toast
|
|
8
|
+
* How long a toast with no action stays on screen when nobody touches it.
|
|
8
9
|
*/
|
|
9
10
|
const DISMISS_AFTER = 6000;
|
|
10
11
|
/**
|
|
11
|
-
*
|
|
12
|
+
* How long a toast with an action stays on screen when nobody touches it, time to read it and then act.
|
|
12
13
|
*/
|
|
13
|
-
const
|
|
14
|
+
const ACTION_DISMISS_AFTER = 10000;
|
|
14
15
|
/**
|
|
15
|
-
* The
|
|
16
|
+
* The hint telling a screen reader that a click clears a plain toast.
|
|
16
17
|
*/
|
|
17
|
-
const
|
|
18
|
+
const DISMISS_LABEL = 'Dismiss this notice';
|
|
18
19
|
/**
|
|
19
20
|
* How many toasts stay on screen at once.
|
|
20
21
|
*/
|
|
21
22
|
const LIMIT = 3;
|
|
22
|
-
/**
|
|
23
|
-
* How many characters of a name a toast shows before the ellipsis.
|
|
24
|
-
*/
|
|
25
|
-
const NAME_LENGTH = 45;
|
|
26
|
-
/**
|
|
27
|
-
* The mark that ends a name a toast cut short.
|
|
28
|
-
*/
|
|
29
|
-
const ELLIPSIS = '…';
|
|
30
|
-
/**
|
|
31
|
-
* Returns a title cut to the given number of characters, its trailing spaces trimmed and an ellipsis added.
|
|
32
|
-
* @param title - The title to name.
|
|
33
|
-
* @param length - How many characters to keep.
|
|
34
|
-
* @returns The title whole when it fits, the cut title otherwise.
|
|
35
|
-
*/
|
|
36
|
-
function cutName(title, length) {
|
|
37
|
-
const characters = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
|
|
38
|
-
const parts = Array.from(characters.segment(title), (part) => part.segment);
|
|
39
|
-
if (parts.length <= length) {
|
|
40
|
-
return title;
|
|
41
|
-
}
|
|
42
|
-
return `${parts.slice(0, length).join('').trimEnd()}${ELLIPSIS}`;
|
|
43
|
-
}
|
|
44
23
|
const ToasterContext = createContext(null);
|
|
45
24
|
/**
|
|
46
25
|
* Returns the handle raising messages in the toast region.
|
|
@@ -66,23 +45,25 @@ function admit(held, arriving, limit) {
|
|
|
66
45
|
return [...held.map((toast) => (pushed.has(toast.id) ? { ...toast, leaving: true } : toast)), arriving];
|
|
67
46
|
}
|
|
68
47
|
/**
|
|
69
|
-
* Returns the
|
|
48
|
+
* Returns the animations running on an element and inside it, none where the browser cannot report them.
|
|
70
49
|
* @param element - The element to ask.
|
|
71
50
|
* @returns The running animations.
|
|
72
51
|
*/
|
|
73
|
-
function
|
|
74
|
-
return typeof element.getAnimations === 'function' ? element.getAnimations() : [];
|
|
52
|
+
function runningMotion(element) {
|
|
53
|
+
return typeof element.getAnimations === 'function' ? element.getAnimations({ subtree: true }) : [];
|
|
75
54
|
}
|
|
76
55
|
/**
|
|
77
|
-
* Returns the ref of a toast
|
|
78
|
-
*
|
|
56
|
+
* Returns the ref of a toast item that gives up focus as the toast leaves and drops the toast once its motion ends,
|
|
57
|
+
* or at once when the toast was already leaving as it first showed.
|
|
58
|
+
* @param toast - The toast the item holds.
|
|
79
59
|
* @param region - The toast region taking the focus a leaving toast held.
|
|
80
60
|
* @param onGone - The handler dropping a toast that finished leaving.
|
|
81
|
-
* @returns The ref to attach to the
|
|
61
|
+
* @returns The ref to attach to the item element.
|
|
82
62
|
*/
|
|
83
63
|
function useDeparture(toast, region, onGone) {
|
|
84
64
|
const ref = useRef(null);
|
|
85
65
|
const { id, leaving } = toast;
|
|
66
|
+
const leavingAtMount = useRef(leaving);
|
|
86
67
|
useLayoutEffect(() => {
|
|
87
68
|
if (!leaving) {
|
|
88
69
|
return;
|
|
@@ -92,12 +73,12 @@ function useDeparture(toast, region, onGone) {
|
|
|
92
73
|
if (element.contains(document.activeElement)) {
|
|
93
74
|
holder.focus();
|
|
94
75
|
}
|
|
95
|
-
const
|
|
96
|
-
if (
|
|
76
|
+
const motion = leavingAtMount.current ? [] : runningMotion(element);
|
|
77
|
+
if (motion.length === 0) {
|
|
97
78
|
onGone(id);
|
|
98
79
|
return;
|
|
99
80
|
}
|
|
100
|
-
Promise.allSettled(
|
|
81
|
+
Promise.allSettled(motion.map((animation) => animation.finished)).then(() => onGone(id));
|
|
101
82
|
}, [id, leaving, region, onGone]);
|
|
102
83
|
return ref;
|
|
103
84
|
}
|
|
@@ -126,35 +107,43 @@ function useExpiry(toast, dismissAfter, onLeave) {
|
|
|
126
107
|
function toastClass(base, leaving) {
|
|
127
108
|
return leaving ? `${base} godmin-toast--leaving` : base;
|
|
128
109
|
}
|
|
110
|
+
/**
|
|
111
|
+
* Renders the item that holds a toast in the region, its space growing as the toast arrives and closing once it left.
|
|
112
|
+
* @param props - The toast, the region, the handler dropping a toast that finished leaving, and the toast element.
|
|
113
|
+
* @returns The item element.
|
|
114
|
+
*/
|
|
115
|
+
function ToastItem({ toast, region, onGone, children }) {
|
|
116
|
+
const ref = useDeparture(toast, region, onGone);
|
|
117
|
+
const item = toast.leaving ? 'godmin-toasts__item godmin-toasts__item--leaving' : 'godmin-toasts__item';
|
|
118
|
+
return (_jsx("div", { ref: ref, className: item, children: _jsx("div", { className: "godmin-toasts__item-inner", children: children }) }));
|
|
119
|
+
}
|
|
129
120
|
/**
|
|
130
121
|
* Renders a toast with no action as one button that clears it, described by the dismiss hint.
|
|
131
|
-
* @param props - The toast, how long it stays, the id of the dismiss hint
|
|
122
|
+
* @param props - The toast, how long it stays, the id of the dismiss hint and the handler clearing it.
|
|
132
123
|
* @returns The toast element.
|
|
133
124
|
*/
|
|
134
|
-
function PlainToast({ toast, dismissAfter, hint,
|
|
125
|
+
function PlainToast({ toast, dismissAfter, hint, onLeave }) {
|
|
135
126
|
useExpiry(toast, dismissAfter, onLeave);
|
|
136
|
-
|
|
137
|
-
return (_jsx("button", { ref: ref, type: "button", className: toastClass('godmin-toast godmin-toast--plain', toast.leaving), "aria-describedby": hint, inert: toast.leaving, onClick: () => onLeave(toast.id), children: toast.message }));
|
|
127
|
+
return (_jsx("button", { type: "button", className: toastClass('godmin-toast godmin-toast--plain', toast.leaving), "aria-describedby": hint, inert: toast.leaving, onClick: () => onLeave(toast.id), children: toast.message }));
|
|
138
128
|
}
|
|
139
129
|
/**
|
|
140
|
-
* Renders a toast with its action
|
|
141
|
-
* @param props - The toast, its action, its time
|
|
130
|
+
* Renders a toast with its action, cleared by a click anywhere on it, the action its only control.
|
|
131
|
+
* @param props - The toast, its action, its time and the handler clearing it.
|
|
142
132
|
* @returns The toast element.
|
|
143
133
|
*/
|
|
144
|
-
function ActionToast({ toast, action, dismissAfter,
|
|
134
|
+
function ActionToast({ toast, action, dismissAfter, onLeave }) {
|
|
145
135
|
useExpiry(toast, dismissAfter, onLeave);
|
|
146
|
-
|
|
147
|
-
return (_jsxs("div", { ref: ref, className: toastClass('godmin-toast', toast.leaving), inert: toast.leaving, children: [_jsx("span", { className: "godmin-toast__message", children: toast.message }), _jsx("button", { type: "button", className: "godmin-toast__action", onClick: () => {
|
|
148
|
-
action.onAct();
|
|
136
|
+
return (_jsxs("div", { className: toastClass('godmin-toast', toast.leaving), inert: toast.leaving, onClick: () => onLeave(toast.id), children: [_jsx("span", { className: "godmin-toast__message", children: toast.message }), _jsx("button", { type: "button", className: "godmin-toast__action", onClick: () => {
|
|
149
137
|
onLeave(toast.id);
|
|
150
|
-
|
|
138
|
+
action.onAct();
|
|
139
|
+
}, children: action.label })] }));
|
|
151
140
|
}
|
|
152
141
|
/**
|
|
153
|
-
* Renders the region holding raised messages around the given tree.
|
|
154
|
-
* @param props - The tree the region wraps, the
|
|
142
|
+
* Renders the region holding raised messages around the given tree, under the snackbar corners at every preset.
|
|
143
|
+
* @param props - The tree the region wraps, the time of each kind of toast, the plain toast hint and how many stay.
|
|
155
144
|
* @returns The wrapped tree with its region.
|
|
156
145
|
*/
|
|
157
|
-
export function Toaster({ children, dismissAfter = DISMISS_AFTER,
|
|
146
|
+
export function Toaster({ children, dismissAfter = DISMISS_AFTER, actionDismissAfter = ACTION_DISMISS_AFTER, dismissLabel = DISMISS_LABEL, limit = LIMIT, }) {
|
|
158
147
|
const [toasts, setToasts] = useState([]);
|
|
159
148
|
const nextId = useRef(0);
|
|
160
149
|
const region = useRef(null);
|
|
@@ -180,8 +169,7 @@ export function Toaster({ children, dismissAfter = DISMISS_AFTER, dismissLabel =
|
|
|
180
169
|
speak(message, 'polite');
|
|
181
170
|
setToasts((held) => admit(held, { id, message, action, leaving: false }, limit));
|
|
182
171
|
}, [limit]);
|
|
183
|
-
const
|
|
184
|
-
const handle = useMemo(() => ({ show, name }), [show, name]);
|
|
172
|
+
const handle = useMemo(() => ({ show }), [show]);
|
|
185
173
|
const hint = useId();
|
|
186
|
-
return (_jsxs(ToasterContext.Provider, { value: handle, children: [children, _jsx("div", { ref: region, className: "godmin-toasts", tabIndex: -1, children: toasts.map((toast) => toast.action === undefined ? (_jsx(PlainToast, { toast: toast, dismissAfter: dismissAfter, hint: hint,
|
|
174
|
+
return (_jsxs(ToasterContext.Provider, { value: handle, children: [children, _jsx(ThemeProvider, { cornerRadius: "subtle", children: _jsx("div", { ref: region, className: "godmin-toasts", tabIndex: -1, children: toasts.map((toast) => (_jsx(ToastItem, { toast: toast, region: region, onGone: gone, children: toast.action === undefined ? (_jsx(PlainToast, { toast: toast, dismissAfter: dismissAfter, hint: hint, onLeave: leave })) : (_jsx(ActionToast, { toast: toast, action: toast.action, dismissAfter: actionDismissAfter, onLeave: leave })) }, toast.id))) }) }), _jsx("span", { id: hint, hidden: true, children: dismissLabel })] }));
|
|
187
175
|
}
|
|
@@ -100,6 +100,35 @@ the same peer ranges.
|
|
|
100
100
|
follows the filter rules of that DataViews release. A list built on
|
|
101
101
|
another release gets a peer warning when it installs godmin.
|
|
102
102
|
|
|
103
|
+
## Upgrading from godmin 0.27.0
|
|
104
|
+
|
|
105
|
+
godmin 0.28.0 draws toasts as WordPress's new admin draws its
|
|
106
|
+
snackbars. Change your code in these places:
|
|
107
|
+
|
|
108
|
+
- `useToaster().name` and the `nameLength` prop of `Toaster` are gone.
|
|
109
|
+
Put the name in the message as it is. A long name wraps.
|
|
110
|
+
- `dismissAfter` now times only a toast with no action. Pass
|
|
111
|
+
`actionDismissAfter` to time a toast with an action. It stays 10
|
|
112
|
+
seconds when you pass nothing.
|
|
113
|
+
- A toast with an action has no close button. A click anywhere on it
|
|
114
|
+
clears it, so a test that pressed the close button clicks the toast
|
|
115
|
+
instead. A stylesheet that styles `.godmin-toast__dismiss` styles
|
|
116
|
+
nothing now.
|
|
117
|
+
- `dismissLabel` is now only the hint of a toast with no action, and
|
|
118
|
+
its default is `Dismiss this notice`, WordPress's words. A test that
|
|
119
|
+
reads the old hint, `Dismiss`, reads the new one.
|
|
120
|
+
- A toast now sits in a `.godmin-toasts__item` element inside
|
|
121
|
+
`.godmin-toasts`. A selector such as `.godmin-toasts > .godmin-toast`,
|
|
122
|
+
or code that reads the children of the region as toasts, reaches the
|
|
123
|
+
toast through that element.
|
|
124
|
+
- A toast now rises into place as it arrives, as
|
|
125
|
+
[Motion](./design-system/toasts.md#motion) shows. A browser test that
|
|
126
|
+
measures where a toast sits waits for that motion to end, or runs
|
|
127
|
+
with a reduced motion preference.
|
|
128
|
+
|
|
129
|
+
TypeScript points at each call to `name` and at `nameLength`. The rest
|
|
130
|
+
changes only what the reader sees.
|
|
131
|
+
|
|
103
132
|
## Upgrading from godmin 0.24.0
|
|
104
133
|
|
|
105
134
|
godmin 0.25.0 gives the sidebar parts the names WordPress gives them.
|
|
@@ -44,13 +44,14 @@ Except on a toast, every ring godmin draws is the same line,
|
|
|
44
44
|
| The menu button of the top bar | Inside the button |
|
|
45
45
|
| The title link of a `godmin-table`, a `godmin-table-scroll` box and a row of `RepeatRows` | 2px outside the part |
|
|
46
46
|
| A page tab | Around its label, not around the whole height of the tab |
|
|
47
|
-
| A toast | Its own rings, as [
|
|
47
|
+
| A toast | Its own rings, as [keyboard](./toasts.md#keyboard) on the toasts page shows. A plain toast keeps the browser's ring too |
|
|
48
48
|
|
|
49
49
|
godmin turns the browser's own ring off in three places only. A page
|
|
50
50
|
tab draws its own ring around the label instead. Back draws none on a
|
|
51
|
-
mouse focus. The toast region draws none
|
|
52
|
-
|
|
53
|
-
`:focus-visible`, so it
|
|
51
|
+
mouse focus. The toast region draws none. Tab never stops on it, and
|
|
52
|
+
only a toast that leaves or a click on a toast focuses it. Draw a
|
|
53
|
+
ring of your own with the same line, on `:focus-visible`, so it
|
|
54
|
+
matches.
|
|
54
55
|
|
|
55
56
|
## Where focus goes
|
|
56
57
|
|
|
@@ -70,9 +71,8 @@ The title of a sidebar screen never takes focus.
|
|
|
70
71
|
Some parts go away while they hold focus. godmin then moves focus to
|
|
71
72
|
a part that stays, so the keyboard reader keeps their place:
|
|
72
73
|
|
|
73
|
-
- A toast that leaves, as
|
|
74
|
-
|
|
75
|
-
says.
|
|
74
|
+
- A toast that leaves, as [keyboard](./toasts.md#keyboard) on the
|
|
75
|
+
toasts page says.
|
|
76
76
|
- A list row that a run moved, as
|
|
77
77
|
[running an action over the picked rows](../lists.md#running-an-action-over-the-picked-rows)
|
|
78
78
|
says.
|
|
@@ -108,13 +108,11 @@ no region. So a screen reader meets the sidebar under one name only.
|
|
|
108
108
|
pass `label`.
|
|
109
109
|
|
|
110
110
|
Every control godmin draws is named in words. A glyph, a small
|
|
111
|
-
picture such as an icon
|
|
111
|
+
picture such as an icon, is never the name:
|
|
112
112
|
|
|
113
113
|
- Every icon godmin draws itself, such as a row icon, a chevron, the
|
|
114
114
|
Back glyph or the menu glyph, is hidden from screen readers. The
|
|
115
115
|
control around it carries the name.
|
|
116
|
-
- The cross on a toast is named by `dismissLabel`, never read as a
|
|
117
|
-
cross.
|
|
118
116
|
- The initials avatar is hidden, because the name beside it already
|
|
119
117
|
says who it is.
|
|
120
118
|
|
|
@@ -140,7 +138,7 @@ aloud when it changes.
|
|
|
140
138
|
|
|
141
139
|
| Part | What a screen reader hears | Set up in |
|
|
142
140
|
| --- | --- | --- |
|
|
143
|
-
| A toast | Its message, politely. Never its
|
|
141
|
+
| A toast | Its message, politely. Never its action | [What a screen reader hears](./toasts.md#what-a-screen-reader-hears) |
|
|
144
142
|
| A loading ghost | The `label` sentence, from a visually hidden status. The grey shapes are hidden | [The ghosts](../loading-and-feedback.md#the-ghosts) |
|
|
145
143
|
| A count beside a row | The `label` sentence, in place of the bare number | [A count beside a row](../framing-an-application.md#a-count-beside-a-row) |
|
|
146
144
|
| An `ErrorNotice` | Its message, at once, as an alert | [ErrorNotice](../screens.md#errornotice) |
|
|
@@ -174,9 +172,9 @@ translates them.
|
|
|
174
172
|
[godmin's own words](../framing-an-application.md#godmins-own-words)
|
|
175
173
|
lists them and the languages they ship in. The props `label`,
|
|
176
174
|
`menuLabel` and `backLabel` put your own words in their place. One
|
|
177
|
-
default stays in English: the
|
|
178
|
-
|
|
179
|
-
[
|
|
175
|
+
default stays in English: the hint a toast with no action gives a
|
|
176
|
+
screen reader, until you pass `dismissLabel`, as
|
|
177
|
+
[what a screen reader hears](./toasts.md#what-a-screen-reader-hears)
|
|
180
178
|
says. Every other word comes from your app, such as the `label` of a
|
|
181
179
|
loading ghost or a count. Pass each one through your translations.
|
|
182
180
|
|
|
@@ -187,18 +185,14 @@ gives no label a fixed width:
|
|
|
187
185
|
leave. A longer label wraps, and the row grows, since the row sets
|
|
188
186
|
only a smallest height.
|
|
189
187
|
- A long title on a sidebar screen breaks onto the next line.
|
|
190
|
-
- A toast grows with its message
|
|
191
|
-
|
|
192
|
-
word the same way.
|
|
188
|
+
- A toast grows with its message, then wraps, as
|
|
189
|
+
[size](./toasts.md#size) on the toasts page shows. The aside of a
|
|
190
|
+
page and a log list break a long word the same way.
|
|
193
191
|
- The actions of a page header move under the title once they no
|
|
194
192
|
longer fit beside it. A form row and the header line of a log list
|
|
195
193
|
wrap the same way.
|
|
196
194
|
- The page tabs keep each label on one line. A tab row too long for
|
|
197
195
|
its page scrolls and fades the edge it cuts.
|
|
198
|
-
- Where a toast cuts a name, it counts the characters a reader sees,
|
|
199
|
-
so an emoji is never split.
|
|
200
|
-
[Naming an item in a toast](../lists.md#naming-an-item-in-a-toast)
|
|
201
|
-
shows it.
|
|
202
196
|
|
|
203
197
|
In a right-to-left language the chevrons, the sub menu slide and the
|
|
204
198
|
fade of the tab row turn around, as
|
|
@@ -61,7 +61,7 @@ The theme provider also checks contrast when it works out colors from a seed. It
|
|
|
61
61
|
|
|
62
62
|
A raw color is a value written out, such as `#fff`, in place of a token. It stays the same whatever the seeds. `base.css` writes a few on purpose:
|
|
63
63
|
|
|
64
|
-
-
|
|
64
|
+
- A toast paints raw colors too: a see-through black box, white text and a white focus line, the colors of the WordPress snackbar. [Colors, corners and shadow](./toasts.md#colors-corners-and-shadow) gives each value.
|
|
65
65
|
- The backdrop is the dark layer behind the open drawer. It is `#000` at 0.5 opacity, as in the new WordPress admin. godmin sets the opacity through `--backdrop-opacity`. The `@wordpress/ui` drawer fades its black backdrop to that value, so the fade in and out still run.
|
|
66
66
|
- Shadows are black at a low opacity. [Elevation](./radius-and-elevation.md#elevation) lists them.
|
|
67
67
|
- The `#000` in `--godmin-page-tabs-fade` and `--godmin-page-tabs-fade-both` is a mask. The mask fades the ends of a long row of tabs. It paints nothing.
|
|
@@ -30,10 +30,7 @@ values. This table says where each one is set and what it changes.
|
|
|
30
30
|
|
|
31
31
|
## Where each one is set
|
|
32
32
|
|
|
33
|
-
A value set on `:root` reaches every element on the page.
|
|
34
|
-
toast region reads the sidebar width and the canvas margin too. When
|
|
35
|
-
the sidebar is on screen, the region starts after it and ends where
|
|
36
|
-
the canvas ends, so the toasts stay centered on the canvas.
|
|
33
|
+
A value set on `:root` reaches every element on the page.
|
|
37
34
|
|
|
38
35
|
To change one of the four on `:root`, write a plain rule in your own
|
|
39
36
|
stylesheet. For example, a wider sidebar:
|
|
@@ -44,7 +41,7 @@ stylesheet. For example, a wider sidebar:
|
|
|
44
41
|
|
|
45
42
|
Your rule wins over godmin's, as
|
|
46
43
|
[changing the page appearance](../overview.md#changing-the-page-appearance)
|
|
47
|
-
explains. The sidebar
|
|
44
|
+
explains. The sidebar and the drawer both follow it.
|
|
48
45
|
|
|
49
46
|
The canvas sets its two gutters on itself. So a gutter set on `:root`
|
|
50
47
|
changes nothing inside the canvas. Read them inside the canvas, for
|
|
@@ -84,7 +84,7 @@ as wide. A rule for the screens below it asks for one pixel less, as
|
|
|
84
84
|
| `SIDEBAR_BREAKPOINT` | `1024` | The sidebar becomes the top bar and the drawer |
|
|
85
85
|
| `EDGE_BREAKPOINT` | `782` | The canvas meets the screen edges. It is the WordPress medium breakpoint |
|
|
86
86
|
| `DENSE_BREAKPOINT` | `640` | The canvas side gutter narrows to 16px. A list from `useListView` takes its phone layout, as [the view in the address](../lists.md#the-view-in-the-address) shows. A table inside `godmin-table-scroll` scrolls sideways, as [stylesheet helpers](../screens.md#stylesheet-helpers) shows |
|
|
87
|
-
| `SHEET_BREAKPOINT` | `600` | Dialogs rise as sheets along the bottom of the screen and toasts widen to the screen, as [a form dialog](../lists.md#a-form-dialog) and [toasts](
|
|
87
|
+
| `SHEET_BREAKPOINT` | `600` | Dialogs rise as sheets along the bottom of the screen and toasts widen to the screen, as [a form dialog](../lists.md#a-form-dialog) and [toasts](./toasts.md#size) show. It is the WordPress small breakpoint |
|
|
88
88
|
| `TITLE_BREAKPOINT` | `404` | Nothing in the frame. The WordPress editor drops the document title from its header here, for an editor header of your own |
|
|
89
89
|
| `SMALL_VIEWPORT` | `(max-width: 1023px)` | The media query the frame folds its sidebar at |
|
|
90
90
|
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Motion
|
|
3
|
-
description: The sidebar slide and the fades of a godmin admin, the design tokens that time them, and what changes when a reader asks for less motion.
|
|
3
|
+
description: The sidebar slide, the toast motion and the fades of a godmin admin, the design tokens that time them, and what changes when a reader asks for less motion.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
godmin's own motion is short and small. The sidebar slides a new
|
|
7
|
-
menu screen in. Toasts
|
|
7
|
+
menu screen in. Toasts grow in and fade, and the toasts around them
|
|
8
|
+
slide along. Ghosts, the grey shapes shown
|
|
8
9
|
while data loads, fade in, and so does the content that replaces
|
|
9
10
|
them. godmin's stylesheet animates nothing else. It sets no
|
|
10
11
|
transitions, so its own hover and focus looks change at once.
|
|
@@ -18,17 +19,20 @@ and the bars inside a ghost.
|
|
|
18
19
|
A design token is a value the WordPress Design System names, written
|
|
19
20
|
as a CSS custom property. A custom property is a CSS variable. A
|
|
20
21
|
duration is how long an animation takes. An easing is the curve its
|
|
21
|
-
speed follows from start to end. godmin times its
|
|
22
|
+
speed follows from start to end. godmin times its motion with five
|
|
22
23
|
design tokens:
|
|
23
24
|
|
|
24
25
|
| Token | Value | What it times |
|
|
25
26
|
| --- | --- | --- |
|
|
26
|
-
| `--wpds-motion-duration-
|
|
27
|
-
| `--wpds-motion-duration-
|
|
28
|
-
| `--wpds-motion-
|
|
27
|
+
| `--wpds-motion-duration-lg` | 300ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
28
|
+
| `--wpds-motion-duration-md` | 200ms | A ghost or new content fading in |
|
|
29
|
+
| `--wpds-motion-duration-sm` | 100ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
30
|
+
| `--wpds-motion-duration-xs` | 50ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
31
|
+
| `--wpds-motion-easing-balanced` | `cubic-bezier(0.4, 0, 0.2, 1)` | The fades of ghosts and new content |
|
|
29
32
|
|
|
30
|
-
|
|
31
|
-
|
|
33
|
+
Some values have no token: the sidebar slide, the wait before a ghost
|
|
34
|
+
shows, and the rest of the toast motion. The sections below cover
|
|
35
|
+
them.
|
|
32
36
|
|
|
33
37
|
## The sidebar slide
|
|
34
38
|
|
|
@@ -69,12 +73,11 @@ shows how.
|
|
|
69
73
|
|
|
70
74
|
## Toasts
|
|
71
75
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
says how long a toast stays before it leaves.
|
|
76
|
+
Toasts move as the WordPress snackbar does. An arriving toast grows
|
|
77
|
+
its space in the column and fades in. A leaving toast fades out, then
|
|
78
|
+
its space closes. So the other toasts slide instead of jumping.
|
|
79
|
+
[Motion](./toasts.md#motion) on the toasts page gives every duration
|
|
80
|
+
and curve, and says what a leaving toast does.
|
|
78
81
|
|
|
79
82
|
## Loading
|
|
80
83
|
|
|
@@ -100,17 +103,19 @@ A reader can ask their system for less motion. The browser then
|
|
|
100
103
|
reports `prefers-reduced-motion: reduce` to CSS, and godmin changes
|
|
101
104
|
two things:
|
|
102
105
|
|
|
103
|
-
- The fades of
|
|
104
|
-
|
|
105
|
-
|
|
106
|
+
- The fades of ghosts and new content last 1ms. They still run and
|
|
107
|
+
still end. So a ghost still waits its delay and then stays visible.
|
|
108
|
+
- Every toast animation lasts 1ms and starts at once, with no wait.
|
|
109
|
+
It still runs and still ends, so a leaving toast still goes. A toast
|
|
110
|
+
shows in its place at once and goes at once, and the toasts above
|
|
111
|
+
move in one step, as in WordPress.
|
|
106
112
|
- The sidebar slide lasts 0s, as in the WordPress Site Editor, even
|
|
107
113
|
when you set your own slide duration. It does not play, and the new
|
|
108
114
|
screen shows at once in its place.
|
|
109
115
|
|
|
110
|
-
These rules
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
ghost transparent for good.
|
|
116
|
+
These rules keep each animation itself and the setting that holds a
|
|
117
|
+
ghost visible after its fade. They keep the delay of a ghost too.
|
|
118
|
+
Turning an animation off would leave a ghost transparent for good.
|
|
114
119
|
|
|
115
120
|
The bars inside a ghost stop their pulse too. Their WordPress
|
|
116
121
|
package does that on its own.
|
|
@@ -8,10 +8,10 @@ godmin looks. It says where each part of the screen sits, how big
|
|
|
8
8
|
things are, how they move and which colors they take. A new product
|
|
9
9
|
can follow these pages without reading any godmin code.
|
|
10
10
|
|
|
11
|
-
These pages hold the values the whole admin shares. A
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
11
|
+
These pages hold the values the whole admin shares. A part with a
|
|
12
|
+
page of its own, such as [toasts](./toasts.md), keeps its values
|
|
13
|
+
there. Every other part keeps its values on the page that shows how
|
|
14
|
+
to use it.
|
|
15
15
|
|
|
16
16
|
godmin builds on the WordPress Design System, WPDS for short. For
|
|
17
17
|
layout, sizes and motion it follows WordPress's new admin and the
|
|
@@ -99,3 +99,9 @@ layer.
|
|
|
99
99
|
landmarks, what a screen reader hears, and text length.
|
|
100
100
|
- [Custom properties](./custom-properties.md): every godmin custom
|
|
101
101
|
property, where it is set and what it changes.
|
|
102
|
+
|
|
103
|
+
One more page covers a single part, how it looks and how it behaves:
|
|
104
|
+
|
|
105
|
+
- [Toasts](./toasts.md): where a toast sits, how it looks, how long it
|
|
106
|
+
stays, how a reader clears it, and what a keyboard or a screen reader
|
|
107
|
+
meets.
|
|
@@ -23,8 +23,8 @@ presets.
|
|
|
23
23
|
| --- | --- | --- |
|
|
24
24
|
| `--wpds-border-radius-xl` (12px) | Page and app shell surfaces | The canvas, the panel that shows the active screen |
|
|
25
25
|
| `--wpds-border-radius-lg` (8px) | Cards, dialogs, notices and other larger containers | A `LogList`, the box of items shown one under the other |
|
|
26
|
-
| `--wpds-border-radius-md` (4px) | Menus, popovers and other small overlays | A toast,
|
|
27
|
-
| `--wpds-border-radius-sm` (2px) | Buttons, inputs and compact controls | A sidebar row, the Back button of a sidebar screen, the grey bars of a loading ghost,
|
|
26
|
+
| `--wpds-border-radius-md` (4px) | Menus, popovers and other small overlays | A toast, which keeps its corners at every preset, as [toasts](./toasts.md#colors-corners-and-shadow) shows |
|
|
27
|
+
| `--wpds-border-radius-sm` (2px) | Buttons, inputs and compact controls | A sidebar row, the Back button of a sidebar screen, the grey bars of a loading ghost, the focus ring of a page tab, and the focus ring of a toast action, which keeps its corners at every preset |
|
|
28
28
|
| `--wpds-border-radius-xs` (1px) | Elements nested inside controls | Nothing of godmin's own |
|
|
29
29
|
|
|
30
30
|
A surface inside another takes a smaller step than the one around
|
|
@@ -88,6 +88,11 @@ notices take the same preset as the canvas around them.
|
|
|
88
88
|
application](../framing-an-application.md#notices-for-the-whole-application)
|
|
89
89
|
shows how to pass them.
|
|
90
90
|
|
|
91
|
+
The toast region keeps the corners of the WordPress snackbar at every
|
|
92
|
+
preset `AdminRoot` sets.
|
|
93
|
+
[Colors, corners and shadow](./toasts.md#colors-corners-and-shadow)
|
|
94
|
+
gives them.
|
|
95
|
+
|
|
91
96
|
`renderAdmin` from `@gopherium/godmin/testing` takes the same
|
|
92
97
|
`cornerRadius`, so a test can draw a screen under any preset.
|
|
93
98
|
|
|
@@ -101,7 +106,7 @@ show depth:
|
|
|
101
106
|
| Surface | Shadow |
|
|
102
107
|
| --- | --- |
|
|
103
108
|
| The canvas | `0 1px 2px rgb(0 0 0 / 0.08)`. None below `EDGE_BREAKPOINT` |
|
|
104
|
-
| A toast | The WordPress small elevation, the one the snackbar uses.
|
|
109
|
+
| A toast | The WordPress small elevation, the one the snackbar uses. [Colors, corners and shadow](./toasts.md#colors-corners-and-shadow) writes out its four layers |
|
|
105
110
|
| The navigation drawer | `2px 0 8px rgba(0, 0, 0, 0.2)`, the shadow of the phone sidebar in WordPress's new admin |
|
|
106
111
|
|
|
107
112
|
A bleed canvas keeps the canvas shadow. The sidebar has no shadow.
|
|
@@ -119,7 +124,8 @@ Two more shadows draw a line, not depth:
|
|
|
119
124
|
merges the borders of its cells, and a merged border paints badly
|
|
120
125
|
on a pinned cell. [Stylesheet helpers](../screens.md#stylesheet-helpers)
|
|
121
126
|
shows the table markup.
|
|
122
|
-
- A focused toast with no action draws its focus ring as a shadow
|
|
127
|
+
- A focused toast with no action draws its focus ring as a shadow, as
|
|
128
|
+
[keyboard](./toasts.md#keyboard) on the toasts page shows.
|
|
123
129
|
[The focus ring](./accessibility.md#the-focus-ring) covers the
|
|
124
130
|
other focus rings.
|
|
125
131
|
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Toasts
|
|
3
|
+
description: Where a toast sits, how it looks, how long it stays, how a reader clears it, and what a keyboard or a screen reader meets.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
A toast is a short message near the bottom of the window. It says how
|
|
7
|
+
something went, then goes away on its own. godmin draws it as
|
|
8
|
+
WordPress's new admin draws its snackbar.
|
|
9
|
+
[Toasts](../loading-and-feedback.md#toasts) shows how to raise one and
|
|
10
|
+
what to write in it. This page gives every value of how a toast looks
|
|
11
|
+
and behaves.
|
|
12
|
+
|
|
13
|
+
## Where a toast sits
|
|
14
|
+
|
|
15
|
+
Toasts stack in one column fixed to the window. The column spans the
|
|
16
|
+
whole width of the window, the sidebar included, and centers each
|
|
17
|
+
toast in it. So a toast sits at the center of the window, as in
|
|
18
|
+
WordPress's new admin. The sidebar and the drawer never move it.
|
|
19
|
+
|
|
20
|
+
- The column sits `--wpds-dimension-size-md` (32px) above the bottom
|
|
21
|
+
edge of the window.
|
|
22
|
+
- It keeps 16px free on each side, so a toast never touches the edge.
|
|
23
|
+
- Two toasts sit `--wpds-dimension-gap-sm` (8px) apart, the newest at
|
|
24
|
+
the bottom. The gap sits above each toast, inside the space that
|
|
25
|
+
grows and closes with the toast, as in the snackbar. So an arriving
|
|
26
|
+
toast starts one gap below the bottom of the column, then rises by
|
|
27
|
+
the gap and its own height.
|
|
28
|
+
- A click on the column between toasts reaches the page under it.
|
|
29
|
+
|
|
30
|
+
A toast paints above the canvas and the sidebar. On a list page it
|
|
31
|
+
floats over the list footer, as it does in WordPress. Two things paint
|
|
32
|
+
above a toast:
|
|
33
|
+
|
|
34
|
+
- The drawer on a small screen.
|
|
35
|
+
- An open dialog. On a wide screen a toast shows dimmed under the dark
|
|
36
|
+
layer around the dialog. On a phone it sits behind the sheet. Screen
|
|
37
|
+
readers still hear it, because every message is also spoken. Most
|
|
38
|
+
dialogs close as their write starts or ends, so their toast shows in
|
|
39
|
+
full. A [form dialog](../lists.md#a-form-dialog) stays open after a
|
|
40
|
+
failure, so its toast shows under it, as in WordPress.
|
|
41
|
+
|
|
42
|
+
## Size
|
|
43
|
+
|
|
44
|
+
- A toast is as wide as its message, up to
|
|
45
|
+
`--wpds-dimension-surface-width-lg` (560px), its padding included.
|
|
46
|
+
- Below `SHEET_BREAKPOINT` (600px) it spans the column, so it keeps
|
|
47
|
+
16px from each side of the window. It still stops at 560px.
|
|
48
|
+
- It keeps `--wpds-dimension-padding-md` (12px) above and below its
|
|
49
|
+
text and `--wpds-dimension-padding-xl` (20px) on each side. A toast
|
|
50
|
+
of one line is 42px tall, with or without an action.
|
|
51
|
+
- A long message wraps, even inside a long word. godmin never cuts a
|
|
52
|
+
message or a name in it.
|
|
53
|
+
|
|
54
|
+
## Colors, corners and shadow
|
|
55
|
+
|
|
56
|
+
These are the colors of the WordPress snackbar. They stay the same
|
|
57
|
+
whatever seeds you pick.
|
|
58
|
+
|
|
59
|
+
- The box is `rgb(0 0 0 / 0.85)`, a black that lets the page show
|
|
60
|
+
through. The page behind it is blurred 16px and saturated to 180%.
|
|
61
|
+
- The text and the action are `#fff`, and so is the ring around a
|
|
62
|
+
focused action.
|
|
63
|
+
- A focused toast with no action has a `#fff` line
|
|
64
|
+
`--wpds-border-width-xs` (1px) wide inside its edge. Outside it sits
|
|
65
|
+
the usual focus ring, `--wpds-border-width-focus` (2px) of
|
|
66
|
+
`--wpds-color-stroke-focus`.
|
|
67
|
+
- The corners take `--wpds-border-radius-md` under the `subtle`
|
|
68
|
+
preset, so they are 4px. The toast region keeps `subtle` whatever
|
|
69
|
+
[corner radius setting](./radius-and-elevation.md#the-corner-radius-setting)
|
|
70
|
+
your app picks, as WordPress keeps the corners of its snackbar.
|
|
71
|
+
- The shadow is the WordPress small elevation, in four layers:
|
|
72
|
+
`0 1px 2px rgb(0 0 0 / 0.05)`, `0 2px 3px rgb(0 0 0 / 0.04)`,
|
|
73
|
+
`0 6px 6px rgb(0 0 0 / 0.03)` and `0 8px 8px rgb(0 0 0 / 0.02)`.
|
|
74
|
+
|
|
75
|
+
## Text
|
|
76
|
+
|
|
77
|
+
- The message takes `--wpds-typography-font-family-body` at
|
|
78
|
+
`--wpds-typography-font-size-md` (13px), on a line 1.4 times its
|
|
79
|
+
size.
|
|
80
|
+
- The action is a link in the same text, underlined 0.2em below the
|
|
81
|
+
letters at the thickness the font sets. It loses its underline under
|
|
82
|
+
the pointer.
|
|
83
|
+
- The action sits on the first line of the message, at least
|
|
84
|
+
`--wpds-dimension-gap-2xl` (32px) after it. On a phone, where the
|
|
85
|
+
toast spans the column, the spare room goes between the message and
|
|
86
|
+
the action, as in the snackbar.
|
|
87
|
+
|
|
88
|
+
## How long a toast stays
|
|
89
|
+
|
|
90
|
+
- A toast with no action stays 6 seconds. `dismissAfter` changes it.
|
|
91
|
+
- A toast with an action stays 10 seconds, time to read the message
|
|
92
|
+
and then act. `actionDismissAfter` changes it.
|
|
93
|
+
- WordPress's own snackbar in `@wordpress/components` 42.0.0 still
|
|
94
|
+
stays 6 seconds, with or without an action. Its next release keeps
|
|
95
|
+
one with an action 10 seconds, as godmin does.
|
|
96
|
+
- Each toast keeps its own timer. So a toast a screen raises as it
|
|
97
|
+
mounts leaves on time even under React strict mode, which mounts the
|
|
98
|
+
screen twice in development.
|
|
99
|
+
- At most three toasts show at once. When a fourth arrives, the oldest
|
|
100
|
+
leaves. `limit` changes the three. A toast pushed out in the same
|
|
101
|
+
moment it is raised never shows, as WordPress shows only its newest
|
|
102
|
+
three.
|
|
103
|
+
- Every toast leaves on its own. WordPress also has a snackbar that
|
|
104
|
+
waits for the reader, with no timer and a close button. godmin
|
|
105
|
+
raises none.
|
|
106
|
+
|
|
107
|
+
## Motion
|
|
108
|
+
|
|
109
|
+
A toast moves as the WordPress snackbar does. Each toast takes a space
|
|
110
|
+
of its own in the column. The space grows as the toast arrives and
|
|
111
|
+
closes after it leaves, so the toasts above slide instead of jumping.
|
|
112
|
+
|
|
113
|
+
- An arriving toast grows its space from no height over
|
|
114
|
+
`--wpds-motion-duration-lg` (300ms) on `cubic-bezier(0, 0, 0.2, 1)`.
|
|
115
|
+
The toast rises into place as its space grows, and the toasts above
|
|
116
|
+
slide up. When a toast leaves, its space closes over 450ms on
|
|
117
|
+
`cubic-bezier(0.4, 0, 0.1, 1)`, so the toasts above slide down. The
|
|
118
|
+
closing waits `--wpds-motion-duration-sm` (100ms) for the toast to
|
|
119
|
+
fade out first. A space that is still growing closes from the height
|
|
120
|
+
it has reached.
|
|
121
|
+
- The toast fades in over 250ms on `cubic-bezier(0, 0, 0.2, 1)`, after
|
|
122
|
+
a wait of `--wpds-motion-duration-xs` (50ms). So the fade ends with
|
|
123
|
+
the growth. A leaving toast fades out over
|
|
124
|
+
`--wpds-motion-duration-sm` on the same curve and stays hidden at the
|
|
125
|
+
end. A toast that is still fading in fades out from where it got to.
|
|
126
|
+
- A leaving toast stays on the page until its space has closed, and
|
|
127
|
+
nobody can press it in that time. If the browser cuts the motion
|
|
128
|
+
short, the toast still goes.
|
|
129
|
+
- [Reduced motion](./motion.md#reduced-motion) says what changes for a
|
|
130
|
+
reader who asks for less motion. Then a toast shows and goes at
|
|
131
|
+
once, and nothing grows, slides or fades, as in WordPress.
|
|
132
|
+
|
|
133
|
+
## Clearing a toast
|
|
134
|
+
|
|
135
|
+
- A click anywhere on a toast clears it, with or without an action.
|
|
136
|
+
The pointer turns to `--wpds-cursor-control` over every toast.
|
|
137
|
+
- A click on the action runs it and clears the toast.
|
|
138
|
+
- A click on a toast moves focus to the toast region, as WordPress
|
|
139
|
+
moves it to its snackbar list. The region draws no ring.
|
|
140
|
+
- A toast has no close button. WordPress draws its cross only on a
|
|
141
|
+
snackbar with no timer, and godmin raises none.
|
|
142
|
+
|
|
143
|
+
## Keyboard
|
|
144
|
+
|
|
145
|
+
- A toast with no action is one button. Tab reaches it, and Enter or
|
|
146
|
+
Space clears it. Its focus ring is a white line
|
|
147
|
+
`--wpds-border-width-xs` wide inside the toast and a ring of
|
|
148
|
+
`--wpds-color-stroke-focus` `--wpds-border-width-focus` wide around
|
|
149
|
+
it, both drawn as a shadow. The browser's own ring shows too.
|
|
150
|
+
- In a toast with an action, only the action takes focus. The rest of
|
|
151
|
+
the toast is no tab stop and no button. A keyboard reader runs the
|
|
152
|
+
action, or lets the toast leave on its own when its time is up. So
|
|
153
|
+
offer the same action somewhere else on the screen too, as
|
|
154
|
+
[Toasts](../loading-and-feedback.md#toasts) says.
|
|
155
|
+
- The focus ring of the action is the design system ring in white: a
|
|
156
|
+
solid `#fff` outline `--wpds-border-width-focus` wide, set
|
|
157
|
+
`--wpds-border-width-focus` away from the text, with
|
|
158
|
+
`--wpds-border-radius-sm` corners. They are 2px, because the toast
|
|
159
|
+
region keeps the `subtle` preset, as on the snackbar. The underline
|
|
160
|
+
goes while the ring shows.
|
|
161
|
+
- When a toast that holds focus leaves, focus moves to the toast
|
|
162
|
+
region instead of falling back to the top of the page. The region
|
|
163
|
+
draws no ring, and Tab never stops on it. The region comes after the
|
|
164
|
+
rest of the page, so the next Tab reaches any other toast still on
|
|
165
|
+
screen and then leaves the page for the browser's own controls.
|
|
166
|
+
Shift+Tab goes back to the last control before the region.
|
|
167
|
+
|
|
168
|
+
WordPress makes its whole snackbar a button the keyboard reaches, with
|
|
169
|
+
the action button inside it. godmin never puts a button inside another
|
|
170
|
+
button. So it keeps the click on the whole toast, and leaves the
|
|
171
|
+
keyboard with the action.
|
|
172
|
+
|
|
173
|
+
## What a screen reader hears
|
|
174
|
+
|
|
175
|
+
- Each message once, politely, through `speak` from `@wordpress/a11y`.
|
|
176
|
+
Polite means the screen reader first finishes what it is saying.
|
|
177
|
+
The region itself is not a live region, so nothing is read twice.
|
|
178
|
+
- Never the action. A reader who moves into the toast finds the action
|
|
179
|
+
by its label.
|
|
180
|
+
- A toast with no action is a button named by its message. After the
|
|
181
|
+
name the screen reader reads the hint `dismissLabel`, which says
|
|
182
|
+
"Dismiss this notice" unless your app passes its own words. No
|
|
183
|
+
tooltip shows when the pointer rests on it.
|
|
184
|
+
|
|
185
|
+
WordPress names its whole snackbar "Dismiss this notice", so a screen
|
|
186
|
+
reader hears those words in place of the message. godmin keeps the
|
|
187
|
+
message as the name of a plain toast and reads the words after it.
|
|
@@ -53,7 +53,7 @@ Some parts give the size of their text on their own page:
|
|
|
53
53
|
[the page tabs](../screens.md#pagetabs),
|
|
54
54
|
[the title and description of a list row](../lists.md#the-title-field),
|
|
55
55
|
[a table that stays custom](../lists.md#lists-that-stay-custom),
|
|
56
|
-
[a toast](
|
|
56
|
+
[a toast](./toasts.md#text) and
|
|
57
57
|
[the letter of an avatar](../lists.md#avatars).
|
|
58
58
|
|
|
59
59
|
## The heading outline
|
package/docs/lists.md
CHANGED
|
@@ -213,7 +213,8 @@ The next line is the footer's own, at the bottom.
|
|
|
213
213
|
When the list is longer than the screen, only the rows scroll. The
|
|
214
214
|
title, the tabs, the search box and the column headers stay where
|
|
215
215
|
they are, and the footer stays on the bottom edge. A toast floats
|
|
216
|
-
over the footer, as
|
|
216
|
+
over the footer, as
|
|
217
|
+
[where a toast sits](./design-system/toasts.md#where-a-toast-sits) shows.
|
|
217
218
|
|
|
218
219
|
A list that is not DataViews, such as a `godmin-table`, grows the
|
|
219
220
|
page instead, and the canvas scrolls as it does for any other page.
|
|
@@ -889,7 +890,7 @@ function DuplicateModal({ items: [post], closeModal }: RenderModalProps<Post>) {
|
|
|
889
890
|
const duplicate = () => {
|
|
890
891
|
setBusy(true)
|
|
891
892
|
duplicatePost(post.id, title)
|
|
892
|
-
.then(() => toaster.show(`"${
|
|
893
|
+
.then(() => toaster.show(`"${title}" created.`))
|
|
893
894
|
.catch((failure) => toaster.show(failure.message))
|
|
894
895
|
.finally(close)
|
|
895
896
|
}
|
|
@@ -972,7 +973,7 @@ function AddProjectDialog({ onClose }: { onClose: () => void }) {
|
|
|
972
973
|
const [name, setName] = useState('')
|
|
973
974
|
const add = async () => {
|
|
974
975
|
await addProject(name)
|
|
975
|
-
toaster.show(`"${
|
|
976
|
+
toaster.show(`"${name}" added.`)
|
|
976
977
|
onClose()
|
|
977
978
|
}
|
|
978
979
|
return (
|
|
@@ -1216,23 +1217,6 @@ every other one is an outline compact button:
|
|
|
1216
1217
|
</Page>
|
|
1217
1218
|
```
|
|
1218
1219
|
|
|
1219
|
-
## Naming an item in a toast
|
|
1220
|
-
|
|
1221
|
-
A toast that names an item, such as `"Hello" moved to the trash.`,
|
|
1222
|
-
can get long. `name` on the toaster handle cuts a long name and ends
|
|
1223
|
-
it with an ellipsis:
|
|
1224
|
-
|
|
1225
|
-
```tsx
|
|
1226
|
-
const toaster = useToaster()
|
|
1227
|
-
|
|
1228
|
-
toaster.show(`"${toaster.name(post.title)}" moved to the trash.`)
|
|
1229
|
-
```
|
|
1230
|
-
|
|
1231
|
-
A name of 45 characters or fewer shows in full. A longer one keeps
|
|
1232
|
-
its first 45, drops the spaces left at its end, and gets `…`. An
|
|
1233
|
-
emoji counts as one character and is never split. `Toaster` takes
|
|
1234
|
-
`nameLength` to change the 45.
|
|
1235
|
-
|
|
1236
1220
|
## The canvas colour
|
|
1237
1221
|
|
|
1238
1222
|
The frame seeds the canvas with the design system default background,
|
|
@@ -76,43 +76,9 @@ route a `pendingComponent`. Then:
|
|
|
76
76
|
## Toasts
|
|
77
77
|
|
|
78
78
|
A toast is a short message that says how something went, then
|
|
79
|
-
removes itself. godmin draws it like the WordPress snackbar
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
lines up with your content, and it sits at the center of the window
|
|
83
|
-
when no sidebar is on screen.
|
|
84
|
-
|
|
85
|
-
The numbers are the snackbar's own:
|
|
86
|
-
|
|
87
|
-
- 12px of padding above and below the text and 20px on each side.
|
|
88
|
-
A one line toast is 42px tall, with or without an action.
|
|
89
|
-
- 4px rounded corners and the small WordPress shadow under it.
|
|
90
|
-
- As wide as its message, up to 560px. On a screen narrower than
|
|
91
|
-
600px it spans the width, with a 16px gap on each side, and still
|
|
92
|
-
stops at 560px.
|
|
93
|
-
- 8px between two toasts on screen at once.
|
|
94
|
-
- On a toast with an action, the action sits at least 32px after the
|
|
95
|
-
message and the close button at least 24px after the action. On a
|
|
96
|
-
phone, where the toast spans the width, the snackbar spreads the
|
|
97
|
-
spare room between the three, and godmin does the same.
|
|
98
|
-
- The close button is the snackbar's own cross, the ✕ character in
|
|
99
|
-
the toast's text. When a message wraps, the action and the cross
|
|
100
|
-
stay on its first line.
|
|
101
|
-
- The action is a white underlined link that loses its underline
|
|
102
|
-
under the pointer. Keyboard focus draws a dotted white line around
|
|
103
|
-
it, and a white inner line with a blue ring around a plain toast,
|
|
104
|
-
as the snackbar does.
|
|
105
|
-
|
|
106
|
-
On a list page the toast floats over the list footer, as it does in
|
|
107
|
-
WordPress.
|
|
108
|
-
|
|
109
|
-
An open dialog covers the toasts, as WordPress covers its snackbar.
|
|
110
|
-
On a wide screen a toast shows dimmed under the dark layer around the
|
|
111
|
-
dialog, and on a phone it sits behind the sheet. Screen readers still
|
|
112
|
-
hear it, because every message is also spoken. Most dialogs close as
|
|
113
|
-
their write starts or ends, so their toast shows in full. A
|
|
114
|
-
[form dialog](./lists.md#a-form-dialog) stays open after a
|
|
115
|
-
failure, so its toast shows under it, as in WordPress.
|
|
79
|
+
removes itself. godmin draws it like the WordPress snackbar.
|
|
80
|
+
[Toasts](./design-system/toasts.md) in the Design System gives where
|
|
81
|
+
it sits, how it looks, how long it stays and how a reader clears it.
|
|
116
82
|
|
|
117
83
|
`Toaster` renders the region that holds the toasts. Wrap your tree
|
|
118
84
|
once:
|
|
@@ -132,48 +98,35 @@ toaster.show('Post moved to trash.', { label: 'Undo', onAct: restore })
|
|
|
132
98
|
```
|
|
133
99
|
|
|
134
100
|
The second argument is optional and adds one action, given as a
|
|
135
|
-
`label` and an `onAct` callback. It shows as a
|
|
101
|
+
`label` and an `onAct` callback. It shows as a link after the
|
|
136
102
|
message. That covers undo, the main reason to offer an action at
|
|
137
103
|
all. The handle's type is exported as `ToasterHandle`, for holding
|
|
138
104
|
one in a context or a test.
|
|
139
105
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
under React strict mode, which mounts the screen twice in
|
|
145
|
-
development.
|
|
146
|
-
- At most three are on screen at once. The newest sits at the
|
|
147
|
-
bottom, and when a fourth arrives the oldest leaves.
|
|
148
|
-
- A toast with no action goes away when you click anywhere on it.
|
|
149
|
-
A toast with an action shows a small close button instead, so
|
|
150
|
-
there is never a button inside another button.
|
|
151
|
-
- Screen readers hear each message once, politely, through `speak`
|
|
152
|
-
from `@wordpress/a11y`. The toast region itself is not a live
|
|
153
|
-
region, so nothing is read twice.
|
|
154
|
-
- When a toast that holds keyboard focus goes away, focus moves to
|
|
155
|
-
the toast region instead of falling back to the top of the page.
|
|
156
|
-
The next Tab carries on from there.
|
|
157
|
-
- The fades stop when the system asks for reduced motion.
|
|
106
|
+
Offer the same action somewhere else on the screen too, such as a
|
|
107
|
+
Restore row action in the trash. The toast leaves on its own, and a
|
|
108
|
+
keyboard reader may not reach its action in time. WordPress asks the
|
|
109
|
+
same of its snackbar.
|
|
158
110
|
|
|
159
111
|
`@wordpress/a11y` is a peer dependency, so install it next to
|
|
160
112
|
godmin. `godminDedupe` lists it, which makes `godminSingleCopy` stop
|
|
161
113
|
the build if a second copy slips into your bundle. One copy means
|
|
162
114
|
one live region on the page.
|
|
163
115
|
|
|
164
|
-
`Toaster` takes four props
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
toast, so set it if your application is not
|
|
116
|
+
`Toaster` takes four props.
|
|
117
|
+
[How long a toast stays](./design-system/toasts.md#how-long-a-toast-stays)
|
|
118
|
+
gives the defaults of the first three, and
|
|
119
|
+
[what a screen reader hears](./design-system/toasts.md#what-a-screen-reader-hears)
|
|
120
|
+
gives the default of the last:
|
|
121
|
+
|
|
122
|
+
- `dismissAfter`, how many milliseconds a toast with no action stays.
|
|
123
|
+
- `actionDismissAfter`, how many milliseconds a toast with an action
|
|
124
|
+
stays.
|
|
125
|
+
- `limit`, how many toasts stay on screen at once.
|
|
126
|
+
- `dismissLabel`, the hint a screen reader reads after the message of
|
|
127
|
+
a toast with no action, to say a click clears it. It is the only
|
|
128
|
+
text godmin puts in a toast, so set it if your application is not
|
|
129
|
+
in English.
|
|
177
130
|
|
|
178
131
|
### What goes in a toast
|
|
179
132
|
|
|
@@ -181,6 +134,11 @@ Use a toast to confirm a change that worked and could otherwise go
|
|
|
181
134
|
unnoticed: a record saved, a task completed, a file uploaded. Keep
|
|
182
135
|
the message short and in the past tense, like `Post moved to trash.`
|
|
183
136
|
|
|
137
|
+
Name an item in straight double quotes and in full, like
|
|
138
|
+
`"Hello" moved to the trash.` WordPress never cuts a name in its
|
|
139
|
+
snackbar, and godmin does not either.
|
|
140
|
+
[Size](./design-system/toasts.md#size) says how a long one wraps.
|
|
141
|
+
|
|
184
142
|
Use a toast for a write that failed in a dialog or in a run over list
|
|
185
143
|
rows too. WordPress shows those in its snackbar, never inside the
|
|
186
144
|
dialog and never above the list, and godmin's dialogs and list runs
|
package/package.json
CHANGED