@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.
@@ -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](../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
@@ -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-and-feedback.md#moving-between-pages)
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 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.
@@ -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(`"${toaster.name(title)}" created.`))
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(`"${toaster.name(name)}" added.`)
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: Ghost placeholders while data loads, a fade for the content that replaces them, and toasts for messages.
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, show a ghost: grey shapes where
7
- the content is about to appear. When the data arrives, fade the
8
- real content in. godmin ships both halves, plus the toast region
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
- ## The ghosts
13
+ ## A list that loads
12
14
 
13
- `LoadingScreen` stands in for a whole screen. `LoadingRows` stands
14
- in for a list inside a screen whose surroundings are already
15
- visible:
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 (reports.isPending) {
19
- return <LoadingRows label="Loading reports." rows={8} />
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
- `label` is required on both. Write the sentence you would have
25
- shown as text, like `Loading reports.` Sighted users see the
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
- ## Why a ghost does not appear immediately
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
- A ghost stays invisible for its first 150ms. If the data arrives
36
- faster, which it usually does, the user never sees it. Without that
37
- delay every fast load would flash grey for a moment, and the flash
38
- reads as something being wrong.
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
- The delay lives in the stylesheet, so there is nothing to manage in
41
- your code. Render the ghost from the pending flag and you are done.
42
- No timers, no extra state.
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
- If you are coming from 0.4.0: the `useLoadingGate` hook is gone as
45
- of 0.5.0. It held ghosts on screen for a minimum time after the
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
- ## Fading the content in
66
+ ## A preview whose shape is known
50
67
 
51
- Give the content that replaces a ghost the `godmin-arrival` class
52
- and it fades in instead of snapping in:
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
- return <ReportTable className="godmin-arrival" />
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 fade is a short opacity ramp with no delay, so the content
59
- starts appearing the moment it is ready. Together with the ghost's
60
- own fade, the swap reads as one motion.
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`. Then:
69
-
70
- - The page on screen stays until the next one has its code and data.
71
- - A page starts to load when the pointer rests on its link or the
72
- keyboard reaches it, so the wait is often over before the click.
73
- - A page that fetches its own data after it opens draws its ghost, as
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: 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.
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 white link after the
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
- ### 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.
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
- - `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.
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