@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 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: 32px;
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: default;
347
+ cursor: var(--wpds-cursor-control);
324
348
  pointer-events: auto;
325
- animation: godmin-fade-in var(--wpds-motion-duration-md) var(--wpds-motion-easing-balanced);
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: godmin-fade-out var(--wpds-motion-duration-sm) var(--wpds-motion-easing-balanced) forwards;
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
- cursor: var(--wpds-cursor-control);
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-xs) dotted #fff;
377
- outline-offset: 2px;
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 nobody touches stays on screen. */
17
+ /** How many milliseconds a toast with no action stays on screen when nobody touches it. */
20
18
  dismissAfter?: number;
21
- /** The name of the close button, also the hint screen readers hear that a click clears a plain toast. */
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 toast time, the close button name, how many stay and the name length.
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, nameLength, }: ToasterProps): import("react").JSX.Element;
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 nobody touches stays on screen.
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
- * The name of the control clearing a toast.
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 DISMISS_LABEL = 'Dismiss';
14
+ const ACTION_DISMISS_AFTER = 10000;
14
15
  /**
15
- * The cross the WordPress snackbar draws in its close button.
16
+ * The hint telling a screen reader that a click clears a plain toast.
16
17
  */
17
- const DISMISS_GLYPH = '✕';
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 fades running on an element, none where the browser cannot report them.
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 runningFades(element) {
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 element that gives up focus as the toast leaves and drops the toast once faded.
78
- * @param toast - The toast the element draws.
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 toast element.
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 fades = runningFades(element);
96
- if (fades.length === 0) {
76
+ const motion = leavingAtMount.current ? [] : runningMotion(element);
77
+ if (motion.length === 0) {
97
78
  onGone(id);
98
79
  return;
99
80
  }
100
- Promise.allSettled(fades.map((fade) => fade.finished)).then(() => onGone(id));
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, the region and the handlers clearing it.
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, region, onLeave, onGone, }) {
125
+ function PlainToast({ toast, dismissAfter, hint, onLeave }) {
135
126
  useExpiry(toast, dismissAfter, onLeave);
136
- const ref = useDeparture(toast, region, onGone);
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 and a close button beside it.
141
- * @param props - The toast, its action, its time, the close button name, the region and the handlers clearing it.
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, dismissLabel, region, onLeave, onGone, }) {
134
+ function ActionToast({ toast, action, dismissAfter, onLeave }) {
145
135
  useExpiry(toast, dismissAfter, onLeave);
146
- const ref = useDeparture(toast, region, onGone);
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
- }, children: action.label }), _jsx("button", { type: "button", className: "godmin-toast__dismiss", "aria-label": dismissLabel, onClick: () => onLeave(toast.id), children: DISMISS_GLYPH })] }));
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 toast time, the close button name, how many stay and the name length.
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, dismissLabel = DISMISS_LABEL, limit = LIMIT, nameLength = NAME_LENGTH, }) {
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 name = useCallback((title) => cutName(title, nameLength), [nameLength]);
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, region: region, onLeave: leave, onGone: gone }, toast.id)) : (_jsx(ActionToast, { toast: toast, action: toast.action, dismissAfter: dismissAfter, dismissLabel: dismissLabel, region: region, onLeave: leave, onGone: gone }, toast.id))) }), _jsx("span", { id: hint, hidden: true, children: dismissLabel })] }));
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 [toasts](../loading-and-feedback.md#toasts) lists. A plain toast and its close button keep the browser's ring too |
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, because only code ever
52
- focuses it. Draw a ring of your own with the same line, on
53
- `:focus-visible`, so it matches.
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
- [how a toast behaves](../loading-and-feedback.md#how-a-toast-behaves)
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 or a cross, is never the name:
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 buttons | [How a toast behaves](../loading-and-feedback.md#how-a-toast-behaves) |
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 close button of a toast is named
178
- Dismiss until you pass `dismissLabel`, as
179
- [how a toast behaves](../loading-and-feedback.md#how-a-toast-behaves)
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 up to its widest, then wraps, even
191
- inside a long word. The aside of a page and a log list break a long
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
- - The toast box is `rgb(0 0 0 / 0.85)`, a black that lets a blur of the page show through. Its text and its focus lines are `#fff`. These are the colors of the WordPress snackbar. [Toasts](../loading-and-feedback.md#toasts) describes the rest of the toast.
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. So the
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, the drawer and the toast region all follow it.
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](../loading-and-feedback.md#toasts) show. It is the WordPress small breakpoint |
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 fade in and out. Ghosts, the grey shapes shown
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 fades with three
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-md` | 200ms | A toast, a ghost or new content fading in |
27
- | `--wpds-motion-duration-sm` | 100ms | A toast fading out |
28
- | `--wpds-motion-easing-balanced` | `cubic-bezier(0.4, 0, 0.2, 1)` | Every fade |
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
- Two lengths have no token: the sidebar slide and the wait before a
31
- ghost shows. The sections below cover both.
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
- A toast fades in when it arrives. When it leaves, it fades out and
73
- stays hidden at the end. A leaving toast stays on the page until its
74
- fade ends. Nobody can press it in that time. If the browser cuts the
75
- fade short, the toast still goes.
76
- [How a toast behaves](../loading-and-feedback.md#how-a-toast-behaves)
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 toasts, ghosts and new content last 1ms. They still
104
- run and still end. So a leaving toast still goes, and a ghost
105
- still waits its delay and then stays visible.
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 change only how long each animation lasts. They keep
111
- the delay, the animation itself, and the setting that holds a ghost
112
- visible after its fade. Turning the animation off would leave a
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 value that
12
- belongs to one part, such as the size of a
13
- [toast](../loading-and-feedback.md#toasts), sits on the page that
14
- shows how to use that part.
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, the short message near the bottom of the screen |
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, and the focus rings of a page tab and of a toast action |
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. The snackbar is WordPress's own toast. Four layers: `0 1px 2px rgb(0 0 0 / 0.05)`, `0 2px 3px rgb(0 0 0 / 0.04)`, `0 6px 6px rgb(0 0 0 / 0.03)`, `0 8px 8px rgb(0 0 0 / 0.02)` |
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](../loading-and-feedback.md#toasts) and
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 it does in WordPress.
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(`"${toaster.name(title)}" created.`))
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(`"${toaster.name(name)}" added.`)
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: a dark,
80
- slightly see-through box with white 13px text, 32px above the bottom
81
- edge. It sits at the center of the canvas, so beside the sidebar it
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 white link after the
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
- ### How a toast behaves
141
-
142
- - It stays 6 seconds, then fades out. Every toast keeps its own
143
- timer, so a toast a screen raises as it mounts leaves on time even
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
- - `dismissAfter`, how many milliseconds a toast stays. The default
167
- is 6000.
168
- - `limit`, how many toasts stay on screen at once. The default is 3.
169
- - `nameLength`, how many characters of a name a toast shows before
170
- an ellipsis. The default is 45. See
171
- [naming an item in a toast](./lists.md#naming-an-item-in-a-toast).
172
- - `dismissLabel`, the name of the close button. On a toast with no
173
- action it is the hint a screen reader reads after the message. No
174
- tooltip shows when the pointer rests on the toast, as in WordPress.
175
- It defaults to `Dismiss`, and it is the only text godmin puts in a
176
- toast, so set it if your application is not in English.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gopherium/godmin",
3
- "version": "0.27.0",
3
+ "version": "0.28.0",
4
4
  "description": "The admin kit for Gopherium projects: host layer for React admin applications on the WordPress Design System.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",