@gopherium/godmin 0.27.0 → 0.29.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 +11 -6
- package/dist/base.css +71 -76
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/loading.d.ts +1 -10
- package/dist/loading.js +3 -12
- 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 +21 -25
- 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/loading.md +149 -0
- package/docs/design-system/motion.md +37 -46
- package/docs/design-system/overview.md +14 -4
- package/docs/design-system/radius-and-elevation.md +10 -4
- package/docs/design-system/toasts.md +189 -0
- package/docs/design-system/typography.md +1 -1
- package/docs/framing-an-application.md +1 -1
- package/docs/lists.md +70 -22
- package/docs/loading-and-feedback.md +129 -115
- package/docs/overview.md +1 -1
- package/package.json +13 -2
|
@@ -0,0 +1,189 @@
|
|
|
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. In
|
|
150
|
+
Chrome it is a dark ring that mostly covers the white line and the
|
|
151
|
+
focus ring, as it does on the WordPress snackbar.
|
|
152
|
+
- In a toast with an action, only the action takes focus. The rest of
|
|
153
|
+
the toast is no tab stop and no button. A keyboard reader runs the
|
|
154
|
+
action, or lets the toast leave on its own when its time is up. So
|
|
155
|
+
offer the same action somewhere else on the screen too, as
|
|
156
|
+
[Toasts](../loading-and-feedback.md#toasts) says.
|
|
157
|
+
- The focus ring of the action is the design system ring in white: a
|
|
158
|
+
solid `#fff` outline `--wpds-border-width-focus` wide, set
|
|
159
|
+
`--wpds-border-width-focus` away from the text, with
|
|
160
|
+
`--wpds-border-radius-sm` corners. They are 2px, because the toast
|
|
161
|
+
region keeps the `subtle` preset, as on the snackbar. The underline
|
|
162
|
+
goes while the ring shows.
|
|
163
|
+
- When a toast that holds focus leaves, focus moves to the toast
|
|
164
|
+
region instead of falling back to the top of the page. The region
|
|
165
|
+
draws no ring, and Tab never stops on it. The region comes after the
|
|
166
|
+
rest of the page, so the next Tab reaches any other toast still on
|
|
167
|
+
screen and then leaves the page for the browser's own controls.
|
|
168
|
+
Shift+Tab goes back to the last control before the region.
|
|
169
|
+
|
|
170
|
+
WordPress makes its whole snackbar a button the keyboard reaches, with
|
|
171
|
+
the action button inside it. godmin never puts a button inside another
|
|
172
|
+
button. So it keeps the click on the whole toast, and leaves the
|
|
173
|
+
keyboard with the action.
|
|
174
|
+
|
|
175
|
+
## What a screen reader hears
|
|
176
|
+
|
|
177
|
+
- Each message once, politely, through `speak` from `@wordpress/a11y`.
|
|
178
|
+
Polite means the screen reader first finishes what it is saying.
|
|
179
|
+
The region itself is not a live region, so nothing is read twice.
|
|
180
|
+
- Never the action. A reader who moves into the toast finds the action
|
|
181
|
+
by its label.
|
|
182
|
+
- A toast with no action is a button named by its message. After the
|
|
183
|
+
name the screen reader reads the hint `dismissLabel`, which says
|
|
184
|
+
"Dismiss this notice" unless your app passes its own words. No
|
|
185
|
+
tooltip shows when the pointer rests on it.
|
|
186
|
+
|
|
187
|
+
WordPress names its whole snackbar "Dismiss this notice", so a screen
|
|
188
|
+
reader hears those words in place of the message. godmin keeps the
|
|
189
|
+
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
|
|
@@ -377,7 +377,7 @@ const router = createRouter({ routeTree, ...routerDefaults() })
|
|
|
377
377
|
|
|
378
378
|
A page then starts to load when the pointer rests on its link or the
|
|
379
379
|
keyboard reaches it.
|
|
380
|
-
[Moving between pages](./loading
|
|
380
|
+
[Moving between pages](./design-system/loading.md#moving-between-pages)
|
|
381
381
|
says what the reader sees while it loads.
|
|
382
382
|
|
|
383
383
|
`@tanstack/react-router` is an optional peer dependency, any 1.x
|
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.
|
|
@@ -298,6 +299,63 @@ const empty = viewNarrows(view) ? (
|
|
|
298
299
|
A filter with an empty pick, or one still waiting for its value,
|
|
299
300
|
narrows nothing.
|
|
300
301
|
|
|
302
|
+
## A list that loads
|
|
303
|
+
|
|
304
|
+
Pass the loading state of the list to DataViews as `isLoading`.
|
|
305
|
+
DataViews then shows what every WordPress list shows: nothing at
|
|
306
|
+
first, a spinner while the first rows load, and the old rows, dimmed,
|
|
307
|
+
while the next ones load. [A list](./design-system/loading.md#a-list)
|
|
308
|
+
gives how long each step waits.
|
|
309
|
+
|
|
310
|
+
Pass true while the list waits for rows it does not hold yet: from
|
|
311
|
+
the first render until the first answer, even while the request still
|
|
312
|
+
waits for something else, and while a new page, search or sort waits
|
|
313
|
+
for its answer. With TanStack Query:
|
|
314
|
+
|
|
315
|
+
```tsx
|
|
316
|
+
<DataViews {...props} data={orders.data?.items ?? []} isLoading={orders.isPending || orders.isPlaceholderData} />
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
Do not pass `isFetching`. TanStack Query sets it on the very first
|
|
320
|
+
render of a list whose stored rows are stale, and DataViews then hides
|
|
321
|
+
those rows behind its spinner until the fetch ends.
|
|
322
|
+
|
|
323
|
+
With urql, pass
|
|
324
|
+
`result.fetching || (result.data === undefined && result.error === undefined)`.
|
|
325
|
+
|
|
326
|
+
When the page already holds the first rows, such as data the server
|
|
327
|
+
put in the page, give them to TanStack Query as `initialData`. The
|
|
328
|
+
list then shows them at once, with no spinner, as WordPress does with
|
|
329
|
+
the data it preloads.
|
|
330
|
+
|
|
331
|
+
The flag has to be true on the very first render. DataViews decides
|
|
332
|
+
on that render whether the list has loaded. A list that starts with
|
|
333
|
+
`false` never shows the spinner. It shows its empty state, which dims
|
|
334
|
+
after a moment until the rows arrive.
|
|
335
|
+
|
|
336
|
+
Keep DataViews on screen while it loads, and never swap it for
|
|
337
|
+
`LoadingScreen`. DataViews keeps the search box and the filters in
|
|
338
|
+
place, and keeps the old rows during a later load.
|
|
339
|
+
|
|
340
|
+
Never give DataViews a `key` that changes with the view, such as the
|
|
341
|
+
layout, a status or a category. A new key mounts a new DataViews.
|
|
342
|
+
When the new view then loads, it starts over as on a first load: the
|
|
343
|
+
rows go, nothing shows for a moment, then the spinner, where a later
|
|
344
|
+
load would keep the rows on screen.
|
|
345
|
+
|
|
346
|
+
In a route, let the loader wait only for the small data the screen
|
|
347
|
+
needs before it can draw, and start the rows without waiting. The old
|
|
348
|
+
page then stays only that long, and the list shows its own loading.
|
|
349
|
+
With TanStack Query, `ensureQueryData` waits and `prefetchQuery`
|
|
350
|
+
with no `await` starts:
|
|
351
|
+
|
|
352
|
+
```tsx
|
|
353
|
+
loader: () => {
|
|
354
|
+
void queryClient.prefetchQuery(ordersQuery)
|
|
355
|
+
return queryClient.ensureQueryData(orderStatusesQuery)
|
|
356
|
+
},
|
|
357
|
+
```
|
|
358
|
+
|
|
301
359
|
## Paging on the server
|
|
302
360
|
|
|
303
361
|
`filterSortAndPaginate` needs every row in the browser. A long list
|
|
@@ -311,7 +369,7 @@ import { Page, paginationOf, useServerPaging } from '@gopherium/godmin'
|
|
|
311
369
|
export function OrdersScreen() {
|
|
312
370
|
const [view, setView] = useState<View>({ type: 'table', page: 1, perPage: 20, fields: ['total'] })
|
|
313
371
|
const paging = useServerPaging(view, 100)
|
|
314
|
-
const { page, asked } = useOrderPage(paging.window)
|
|
372
|
+
const { page, asked, loading } = useOrderPage(paging.window)
|
|
315
373
|
paging.record(page, asked)
|
|
316
374
|
return (
|
|
317
375
|
<Page title="Orders" list>
|
|
@@ -322,6 +380,7 @@ export function OrdersScreen() {
|
|
|
322
380
|
view={view}
|
|
323
381
|
onChangeView={setView}
|
|
324
382
|
defaultLayouts={{ table: {} }}
|
|
383
|
+
isLoading={loading}
|
|
325
384
|
/>
|
|
326
385
|
</Page>
|
|
327
386
|
)
|
|
@@ -341,7 +400,9 @@ not arrived. `paginationOf` turns it into the totals DataViews shows.
|
|
|
341
400
|
`useOrderPage` also gives back `asked`, the limit of the request that
|
|
342
401
|
got this page. With urql, that is `result.operation?.variables.limit`.
|
|
343
402
|
Call `paging.record(page, asked)` in the same component, right after
|
|
344
|
-
your request, as the example does.
|
|
403
|
+
your request, as the example does. It also gives back `loading`, true
|
|
404
|
+
until its first answer and while a new page waits for its answer, as
|
|
405
|
+
[a list that loads](#a-list-that-loads) asks.
|
|
345
406
|
|
|
346
407
|
`paging.record` remembers the page size the server used for that
|
|
347
408
|
request. When the server used another size than you asked for, the
|
|
@@ -889,7 +950,7 @@ function DuplicateModal({ items: [post], closeModal }: RenderModalProps<Post>) {
|
|
|
889
950
|
const duplicate = () => {
|
|
890
951
|
setBusy(true)
|
|
891
952
|
duplicatePost(post.id, title)
|
|
892
|
-
.then(() => toaster.show(`"${
|
|
953
|
+
.then(() => toaster.show(`"${title}" created.`))
|
|
893
954
|
.catch((failure) => toaster.show(failure.message))
|
|
894
955
|
.finally(close)
|
|
895
956
|
}
|
|
@@ -972,7 +1033,7 @@ function AddProjectDialog({ onClose }: { onClose: () => void }) {
|
|
|
972
1033
|
const [name, setName] = useState('')
|
|
973
1034
|
const add = async () => {
|
|
974
1035
|
await addProject(name)
|
|
975
|
-
toaster.show(`"${
|
|
1036
|
+
toaster.show(`"${name}" added.`)
|
|
976
1037
|
onClose()
|
|
977
1038
|
}
|
|
978
1039
|
return (
|
|
@@ -1216,23 +1277,6 @@ every other one is an outline compact button:
|
|
|
1216
1277
|
</Page>
|
|
1217
1278
|
```
|
|
1218
1279
|
|
|
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
1280
|
## The canvas colour
|
|
1237
1281
|
|
|
1238
1282
|
The frame seeds the canvas with the design system default background,
|
|
@@ -1365,6 +1409,10 @@ Inside a `list` page the table reaches the canvas edges too, and its
|
|
|
1365
1409
|
first and last cells pad by 24px, as DataViews does. A custom list
|
|
1366
1410
|
and a DataViews list then line up with each other and with the title.
|
|
1367
1411
|
|
|
1412
|
+
While its first rows load, show `LoadingScreen` in place of the
|
|
1413
|
+
table, as
|
|
1414
|
+
[a list that loads](./loading-and-feedback.md#a-list-that-loads) says.
|
|
1415
|
+
|
|
1368
1416
|
## The list chrome in Spanish
|
|
1369
1417
|
|
|
1370
1418
|
DataViews speaks English until you load its translations. Its words,
|
|
@@ -1,63 +1,120 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Loading and feedback
|
|
3
|
-
description:
|
|
3
|
+
description: What a list, a screen and a preview show while their data loads, and toasts for messages.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
While a screen waits for its data,
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
for short messages.
|
|
6
|
+
While a screen waits for its data, it shows that it is loading, the
|
|
7
|
+
way WordPress does. A list leaves that to DataViews. Any other screen
|
|
8
|
+
shows `LoadingScreen`, a spinner. godmin also ships the toast region
|
|
9
|
+
for short messages. [Loading](./design-system/loading.md) in the
|
|
10
|
+
Design System gives how long each one waits, where it sits and what a
|
|
11
|
+
reader sees.
|
|
10
12
|
|
|
11
|
-
##
|
|
13
|
+
## A list that loads
|
|
12
14
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
15
|
+
Pass the loading state of a DataViews list to its `isLoading`.
|
|
16
|
+
DataViews then shows the loading itself.
|
|
17
|
+
[A list that loads](./lists.md#a-list-that-loads) says which flag to
|
|
18
|
+
pass.
|
|
19
|
+
|
|
20
|
+
A list that is not DataViews, such as a `godmin-table`, shows
|
|
21
|
+
`LoadingScreen` in its place until its first rows arrive.
|
|
22
|
+
|
|
23
|
+
## A screen that loads
|
|
24
|
+
|
|
25
|
+
`LoadingScreen` stands in for a screen, or for the part of a screen
|
|
26
|
+
whose data has not arrived:
|
|
16
27
|
|
|
17
28
|
```tsx
|
|
18
|
-
if (
|
|
19
|
-
return
|
|
29
|
+
if (report.isPending) {
|
|
30
|
+
return (
|
|
31
|
+
<Page title="Report">
|
|
32
|
+
<LoadingScreen label="Loading the report." />
|
|
33
|
+
</Page>
|
|
34
|
+
)
|
|
20
35
|
}
|
|
21
|
-
return <ReportTable className="godmin-arrival" />
|
|
22
36
|
```
|
|
23
37
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
shapes, and screen reader users hear the label, announced from a
|
|
27
|
-
visually hidden status region. The shapes themselves are hidden
|
|
28
|
-
from assistive technology.
|
|
29
|
-
|
|
30
|
-
`LoadingRows` takes `rows`, which defaults to 5. `LoadingScreen`
|
|
31
|
-
draws a title bar and three text lines, with no count to set.
|
|
38
|
+
Render it from the pending flag of your request. Where you put it
|
|
39
|
+
decides how it shows:
|
|
32
40
|
|
|
33
|
-
|
|
41
|
+
- Inside the `Page`, when you know the title. The title stays while
|
|
42
|
+
the data loads, and the spinner shows at once at the top of the
|
|
43
|
+
page, under the title, as on a WordPress screen.
|
|
44
|
+
- Inside a dialog, when nothing of the dialog body is known yet. It
|
|
45
|
+
shows at once there too.
|
|
46
|
+
- Alone, when nothing of the screen is known yet, such as while the
|
|
47
|
+
session loads before the frame is drawn. It then waits a moment, so
|
|
48
|
+
a fast load shows nothing, and fades in, in the middle of the space
|
|
49
|
+
it gets. The wait lives in the stylesheet, so your code needs no
|
|
50
|
+
timer.
|
|
34
51
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
52
|
+
Inside a `Page` a load that is often fast can show the spinner for a
|
|
53
|
+
moment. To keep the old page on screen instead, let the route loader
|
|
54
|
+
wait for the small data the screen needs, as
|
|
55
|
+
[a list that loads](./lists.md#a-list-that-loads) shows. Data the
|
|
56
|
+
page already holds can go to TanStack Query as `initialData`.
|
|
39
57
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
58
|
+
`label` is required. Write the sentence you would have shown as text,
|
|
59
|
+
like `Loading the report.` A screen reader hears it, as
|
|
60
|
+
[what a screen reader hears](./design-system/loading.md#what-a-screen-reader-hears)
|
|
61
|
+
says. Pass it through your translations.
|
|
43
62
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
data arrived, which made fast screens feel slow. Render from the
|
|
47
|
-
pending flag and let the stylesheet do the rest.
|
|
63
|
+
Show the content as soon as it arrives. It replaces the spinner at
|
|
64
|
+
once.
|
|
48
65
|
|
|
49
|
-
##
|
|
66
|
+
## A preview whose shape is known
|
|
50
67
|
|
|
51
|
-
|
|
52
|
-
and it
|
|
68
|
+
When a part knows its size before its data arrives, such as an image
|
|
69
|
+
whose width and height you hold, it may show the `Skeleton` of
|
|
70
|
+
`@wordpress/ui` in its place until the image arrives:
|
|
53
71
|
|
|
54
72
|
```tsx
|
|
55
|
-
|
|
73
|
+
const [loadedUrl, setLoadedUrl] = useState<string>()
|
|
74
|
+
const loaded = loadedUrl === coverUrl
|
|
75
|
+
|
|
76
|
+
return (
|
|
77
|
+
<figure className="cover" aria-busy={!loaded}>
|
|
78
|
+
{loaded ? null : <Skeleton style={{ inlineSize: 320, blockSize: 180 }} />}
|
|
79
|
+
<img
|
|
80
|
+
src={coverUrl}
|
|
81
|
+
alt=""
|
|
82
|
+
width={320}
|
|
83
|
+
height={180}
|
|
84
|
+
className={loaded ? undefined : 'is-loading'}
|
|
85
|
+
onLoad={() => setLoadedUrl(coverUrl)}
|
|
86
|
+
onError={() => setLoadedUrl(coverUrl)}
|
|
87
|
+
/>
|
|
88
|
+
</figure>
|
|
89
|
+
)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The image is in the page from the start, so the browser loads it.
|
|
93
|
+
Until then your own `is-loading` class lays it over the skeleton,
|
|
94
|
+
out of the flow and transparent, as WordPress does:
|
|
95
|
+
|
|
96
|
+
```css
|
|
97
|
+
.cover {
|
|
98
|
+
position: relative;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
.cover .is-loading {
|
|
102
|
+
position: absolute;
|
|
103
|
+
inset-block-start: 0;
|
|
104
|
+
inset-inline-start: 0;
|
|
105
|
+
opacity: 0;
|
|
106
|
+
}
|
|
56
107
|
```
|
|
57
108
|
|
|
58
|
-
The
|
|
59
|
-
|
|
60
|
-
|
|
109
|
+
The skeleton goes when the image loads, or fails, so it never pulses
|
|
110
|
+
for good. It comes back for a new `coverUrl` until that image loads.
|
|
111
|
+
|
|
112
|
+
Keep it for such a preview. A list or a screen shows a spinner, as
|
|
113
|
+
above. When the image arrives you may fade it in, the one fade
|
|
114
|
+
WordPress gives loaded content.
|
|
115
|
+
[A preview whose shape is known](./design-system/loading.md#a-preview-whose-shape-is-known)
|
|
116
|
+
says how to size the skeleton, how to hide the image and fade it in,
|
|
117
|
+
and what a screen reader needs.
|
|
61
118
|
|
|
62
119
|
## Moving between pages
|
|
63
120
|
|
|
@@ -65,54 +122,19 @@ A router can draw a loading screen while the next page loads.
|
|
|
65
122
|
WordPress's new admin draws none. To do the same, spread
|
|
66
123
|
[`routerDefaults()`](./framing-an-application.md#routes-and-the-frame)
|
|
67
124
|
into your router, and give it no `defaultPendingComponent` and no
|
|
68
|
-
route a `pendingComponent`.
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
above.
|
|
125
|
+
route a `pendingComponent`. The old page then stays until the route
|
|
126
|
+
loader is done, so let the loader wait only for the small data the
|
|
127
|
+
screen needs, as [a list that loads](./lists.md#a-list-that-loads)
|
|
128
|
+
shows.
|
|
129
|
+
[Moving between pages](./design-system/loading.md#moving-between-pages)
|
|
130
|
+
says what the reader sees then.
|
|
75
131
|
|
|
76
132
|
## Toasts
|
|
77
133
|
|
|
78
134
|
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.
|
|
135
|
+
removes itself. godmin draws it like the WordPress snackbar.
|
|
136
|
+
[Toasts](./design-system/toasts.md) in the Design System gives where
|
|
137
|
+
it sits, how it looks, how long it stays and how a reader clears it.
|
|
116
138
|
|
|
117
139
|
`Toaster` renders the region that holds the toasts. Wrap your tree
|
|
118
140
|
once:
|
|
@@ -132,48 +154,35 @@ toaster.show('Post moved to trash.', { label: 'Undo', onAct: restore })
|
|
|
132
154
|
```
|
|
133
155
|
|
|
134
156
|
The second argument is optional and adds one action, given as a
|
|
135
|
-
`label` and an `onAct` callback. It shows as a
|
|
157
|
+
`label` and an `onAct` callback. It shows as a link after the
|
|
136
158
|
message. That covers undo, the main reason to offer an action at
|
|
137
159
|
all. The handle's type is exported as `ToasterHandle`, for holding
|
|
138
160
|
one in a context or a test.
|
|
139
161
|
|
|
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.
|
|
162
|
+
Offer the same action somewhere else on the screen too, such as a
|
|
163
|
+
Restore row action in the trash. The toast leaves on its own, and a
|
|
164
|
+
keyboard reader may not reach its action in time. WordPress asks the
|
|
165
|
+
same of its snackbar.
|
|
158
166
|
|
|
159
167
|
`@wordpress/a11y` is a peer dependency, so install it next to
|
|
160
168
|
godmin. `godminDedupe` lists it, which makes `godminSingleCopy` stop
|
|
161
169
|
the build if a second copy slips into your bundle. One copy means
|
|
162
170
|
one live region on the page.
|
|
163
171
|
|
|
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
|
|
172
|
+
`Toaster` takes four props.
|
|
173
|
+
[How long a toast stays](./design-system/toasts.md#how-long-a-toast-stays)
|
|
174
|
+
gives the defaults of the first three, and
|
|
175
|
+
[what a screen reader hears](./design-system/toasts.md#what-a-screen-reader-hears)
|
|
176
|
+
gives the default of the last:
|
|
177
|
+
|
|
178
|
+
- `dismissAfter`, how many milliseconds a toast with no action stays.
|
|
179
|
+
- `actionDismissAfter`, how many milliseconds a toast with an action
|
|
180
|
+
stays.
|
|
181
|
+
- `limit`, how many toasts stay on screen at once.
|
|
182
|
+
- `dismissLabel`, the hint a screen reader reads after the message of
|
|
183
|
+
a toast with no action, to say a click clears it. It is the only
|
|
184
|
+
text godmin puts in a toast, so set it if your application is not
|
|
185
|
+
in English.
|
|
177
186
|
|
|
178
187
|
### What goes in a toast
|
|
179
188
|
|
|
@@ -181,6 +190,11 @@ Use a toast to confirm a change that worked and could otherwise go
|
|
|
181
190
|
unnoticed: a record saved, a task completed, a file uploaded. Keep
|
|
182
191
|
the message short and in the past tense, like `Post moved to trash.`
|
|
183
192
|
|
|
193
|
+
Name an item in straight double quotes and in full, like
|
|
194
|
+
`"Hello" moved to the trash.` WordPress never cuts a name in its
|
|
195
|
+
snackbar, and godmin does not either.
|
|
196
|
+
[Size](./design-system/toasts.md#size) says how a long one wraps.
|
|
197
|
+
|
|
184
198
|
Use a toast for a write that failed in a dialog or in a run over list
|
|
185
199
|
rows too. WordPress shows those in its snackbar, never inside the
|
|
186
200
|
dialog and never above the list, and godmin's dialogs and list runs
|