@gopherium/godmin 0.29.1 → 0.31.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.
Files changed (42) hide show
  1. package/README.md +4 -3
  2. package/dist/base.css +223 -13
  3. package/dist/bulk-run.d.ts +3 -3
  4. package/dist/bulk-run.js +41 -13
  5. package/dist/focus-back.d.ts +22 -0
  6. package/dist/focus-back.js +37 -13
  7. package/dist/index.d.ts +5 -3
  8. package/dist/index.js +4 -3
  9. package/dist/list-chrome/es-ES.d.ts +1 -1
  10. package/dist/list-chrome/es-ES.js +7 -4
  11. package/dist/list-chrome/fr-FR.d.ts +1 -1
  12. package/dist/list-chrome/fr-FR.js +5 -1
  13. package/dist/list-empty.d.ts +14 -7
  14. package/dist/list-empty.js +14 -4
  15. package/dist/list-run.d.ts +8 -4
  16. package/dist/list-run.js +143 -6
  17. package/dist/page-breadcrumbs.d.ts +28 -0
  18. package/dist/page-breadcrumbs.js +18 -0
  19. package/dist/page-tabs.js +29 -26
  20. package/dist/page.d.ts +8 -3
  21. package/dist/page.js +48 -9
  22. package/dist/size-watch.d.ts +11 -0
  23. package/dist/size-watch.js +36 -0
  24. package/dist/wide-list.d.ts +7 -0
  25. package/dist/wide-list.js +33 -0
  26. package/docs/build-and-versioning.md +3 -3
  27. package/docs/design-system/accessibility.md +64 -16
  28. package/docs/design-system/custom-properties.md +9 -2
  29. package/docs/design-system/layout.md +5 -3
  30. package/docs/design-system/lists.md +234 -0
  31. package/docs/design-system/loading.md +2 -0
  32. package/docs/design-system/overview.md +6 -1
  33. package/docs/design-system/radius-and-elevation.md +3 -9
  34. package/docs/design-system/record-pages.md +197 -0
  35. package/docs/design-system/toasts.md +2 -3
  36. package/docs/design-system/typography.md +3 -3
  37. package/docs/framing-an-application.md +7 -5
  38. package/docs/lists.md +278 -72
  39. package/docs/loading-and-feedback.md +9 -11
  40. package/docs/overview.md +1 -1
  41. package/docs/screens.md +83 -36
  42. package/package.json +21 -21
package/docs/lists.md CHANGED
@@ -43,17 +43,10 @@ its paging reads. For a list you hold whole, `filterSortAndPaginate`
43
43
  searches, sorts and pages it, and answers the page of rows with those
44
44
  totals. `defaultLayouts` names the layouts a reader may switch to.
45
45
 
46
- DataViews pads its toolbar, its table and its footer by 24px on each
47
- side. The canvas pads its content by 24px as well. Without help the
48
- list starts 48px in, while the title starts at 24px. `list` takes the
49
- content out to the canvas edges, so the list's own 24px lines up with
50
- the title and its row lines run from edge to edge, as they do in
51
- WordPress.
52
-
53
- Below 640px the canvas pads by 16px and the list reaches out by 16px.
54
- DataViews keeps its own 24px there, so on a phone a list page pads its
55
- title row by the 8px between the two, and the title still lines up
56
- with the list.
46
+ `list` takes the content out to the canvas edges, so the list's own
47
+ padding lines up with the title and its row lines run from edge to
48
+ edge, as they do in WordPress.
49
+ [A list page](./design-system/lists.md#a-list-page) gives the values.
57
50
 
58
51
  A page with an `aside` keeps its list inside the main column, because
59
52
  the aside needs its own room.
@@ -120,8 +113,10 @@ leaves the list.
120
113
  route holds a key of its own, add it:
121
114
  `validateSearch: (raw) => ({ ...listSearch(raw), status: raw.status })`.
122
115
 
123
- A list shows one layout at a time and no Layout menu: the table from
124
- 640px and the list below. `layouts: { wide: 'grid', phone: 'list' }`
116
+ A list shows one layout at a time and no Layout menu: the table on a
117
+ wide screen and the list on a phone, as
118
+ [columns](./design-system/lists.md#columns) gives.
119
+ `layouts: { wide: 'grid', phone: 'list' }`
125
120
  names others, and `layoutSettings` says what a layout opens on, such
126
121
  as `{ grid: { layout: { previewSize: 230 } } }`. `phoneFields` names
127
122
  the fields the phone list shows. The columns a reader picks stay in
@@ -131,11 +126,12 @@ the next, the list forgets the picked columns and the ticked rows.
131
126
 
132
127
  A tap on a phone list selects nothing. `openOnTap(list, open)` gives
133
128
  you a handler that opens the record instead. Pass it as
134
- `onChangeSelection`. `list.phone` tells you which side of 640px the
135
- screen is on. `openOnTap` comes from `@gopherium/godmin/router`, like
136
- `useListView`, and from the main entry too, so a package that draws a
137
- list without TanStack Router can call it with the `list` an app hands
138
- it. It reads only `phone` and `onChangeSelection`. The list view
129
+ `onChangeSelection`. `list.phone` tells you which side of
130
+ `DENSE_BREAKPOINT` the screen is on. `openOnTap` comes from
131
+ `@gopherium/godmin/router`, like `useListView`, and from the main
132
+ entry too, so a package that draws a list without TanStack Router can
133
+ call it with the `list` an app hands it. It reads only `phone` and
134
+ `onChangeSelection`. The list view
139
135
  types, such as `ListView` and `ListDefaults`, come from the main entry
140
136
  too, so such a package can type that `list` and its defaults without
141
137
  the router. This needs godmin 0.27.0 or later.
@@ -219,21 +215,46 @@ over the footer, as
219
215
  A list that is not DataViews, such as a `godmin-table`, grows the
220
216
  page instead, and the canvas scrolls as it does for any other page.
221
217
 
218
+ ## Columns
219
+
220
+ Name the columns a list opens on in the view's `fields`, one set for
221
+ every width. Never hide a column because the window is narrow, as no
222
+ WordPress list does. A reader adds and removes columns in View
223
+ options.
224
+
225
+ When the columns need more room than the list has, the table scrolls
226
+ sideways inside the list. A table with checkboxes keeps its checkbox
227
+ and title columns frozen at the start edge while the other columns
228
+ scroll under them, as
229
+ [a wide table](./design-system/lists.md#a-wide-table) shows. You add
230
+ nothing for it.
231
+
232
+ Draw a muted cell with a weak text color, such as
233
+ `--wpds-color-foreground-content-neutral-weak`, never with `opacity`.
234
+ A cell with less than full opacity paints over the frozen columns as
235
+ it scrolls under them.
236
+
237
+ Give every bulk action an `icon`. At `EDGE_BREAKPOINT` and below,
238
+ DataViews shows bulk actions as icon buttons and leaves out an action
239
+ with no icon.
240
+
222
241
  ## Tabs above a list
223
242
 
224
243
  Give the page `tabs` to show [page tabs](./screens.md#pagetabs)
225
244
  between the title and the list. On a list page the tab labels line up
226
245
  with the title, the light line under them runs from edge to edge, and
227
- the search box sits 16px under that line, as on a WordPress list. A
228
- notice or a `godmin-table` right under the tabs keeps the same 16px
229
- from that line.
246
+ the search box sits under that line as on a WordPress list. A notice
247
+ or a `godmin-table` right under the tabs keeps the same space from
248
+ that line. [A list page](./design-system/lists.md#a-list-page) gives
249
+ the values.
230
250
 
231
251
  ## Notices above a list
232
252
 
233
253
  Anything you put in a list page before the list itself, such as an
234
254
  `ErrorNotice` for a list that failed to load, lines up with the title
235
- rather than the canvas edge, and keeps 16px between itself and the
236
- list:
255
+ rather than the canvas edge, and keeps the page gap between itself
256
+ and the list, as [a list page](./design-system/lists.md#a-list-page)
257
+ gives:
237
258
 
238
259
  ```tsx
239
260
  <Page title="Users" list>
@@ -272,32 +293,61 @@ DataViews as `empty`:
272
293
  ```tsx
273
294
  import { ListEmpty } from '@gopherium/godmin'
274
295
  import { people } from '@wordpress/icons'
296
+ import { Button } from '@wordpress/ui'
275
297
 
276
298
  <DataViews
277
299
  {...props}
278
- empty={<ListEmpty icon={people} title="No users yet." hint="Add one with New user." />}
300
+ empty={
301
+ <ListEmpty
302
+ icon={people}
303
+ title="No users yet"
304
+ description="Users you add show up here."
305
+ actions={<Button onClick={addUser}>Add User</Button>}
306
+ />
307
+ }
279
308
  />
280
309
  ```
281
310
 
282
311
  It draws the design system empty state, centred: the icon, the title
283
- as a heading and the hint under it. `hint` is optional. Leave it out
284
- when a search narrowed the list, as in `No users found.`
285
-
312
+ as a heading, the description under it and the buttons under that.
313
+ `description` and `actions` are optional. Put the add button of the
314
+ list header in `actions`, with the same words, at its default size
315
+ rather than compact. The title is one short phrase with no full stop,
316
+ and the description a sentence that ends with one, as
317
+ [an empty list](./design-system/lists.md#an-empty-list) gives.
318
+
319
+ When a search or a filter finds nothing, show `ListNoResults` in its
320
+ place. It says "No results found" and "Try adjusting your search or
321
+ filters to find what you're looking for." under the search icon, in
322
+ [godmin's own words](./framing-an-application.md#godmins-own-words),
323
+ and holds no button, since the DataViews filters already offer Reset.
286
324
  `viewNarrows(view)` tells you whether a search, or a filter holding a
287
- value, narrows the list. Use it to pick between the two messages:
325
+ value, narrows the list. Use it to pick between the two:
288
326
 
289
327
  ```tsx
290
- import { ListEmpty, viewNarrows } from '@gopherium/godmin'
328
+ import { ListEmpty, ListNoResults, viewNarrows } from '@gopherium/godmin'
291
329
 
292
330
  const empty = viewNarrows(view) ? (
293
- <ListEmpty icon={people} title="No users found." />
331
+ <ListNoResults />
294
332
  ) : (
295
- <ListEmpty icon={people} title="No users yet." hint="Add one with New user." />
333
+ <ListEmpty
334
+ icon={people}
335
+ title="No users yet"
336
+ description="Users you add show up here."
337
+ actions={<Button onClick={addUser}>Add User</Button>}
338
+ />
296
339
  )
297
340
  ```
298
341
 
299
342
  A filter with an empty pick, or one still waiting for its value,
300
- narrows nothing.
343
+ narrows nothing. A status tab narrows nothing either. A tab that holds
344
+ nothing, such as Trash, shows words of its own and no add button:
345
+
346
+ ```tsx
347
+ import { trash } from '@wordpress/icons'
348
+
349
+ <ListEmpty icon={trash} title="Trash is empty" />
350
+ ```
301
351
 
302
352
  ## A list that loads
303
353
 
@@ -309,19 +359,51 @@ gives how long each step waits.
309
359
 
310
360
  Pass true while the list waits for rows it does not hold yet: from
311
361
  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:
362
+ waits for something else, while a new page, search or sort waits
363
+ for its answer, and while the list reloads after a write of your
364
+ own. With TanStack Query:
314
365
 
315
366
  ```tsx
316
- <DataViews {...props} data={orders.data?.items ?? []} isLoading={orders.isPending || orders.isPlaceholderData} />
367
+ const { run, region, refreshing } = useListRun('orders', list.onChangeSelection)
368
+
369
+ <DataViews
370
+ {...props}
371
+ data={orders.data?.items ?? []}
372
+ isLoading={orders.isPending || orders.isPlaceholderData || refreshing}
373
+ />
317
374
  ```
318
375
 
376
+ `refreshing` comes from `useListRun`, as
377
+ [running an action over the picked rows](#running-an-action-over-the-picked-rows)
378
+ shows. It is true while a run reloads its list after its own write,
379
+ which the query's own flags leave false.
380
+
319
381
  Do not pass `isFetching`. TanStack Query sets it on the very first
320
382
  render of a list whose stored rows are stale, and DataViews then hides
321
383
  those rows behind its spinner until the fetch ends.
322
384
 
323
385
  With urql, pass
324
- `result.fetching || (result.data === undefined && result.error === undefined)`.
386
+ `result.fetching || (result.data === undefined && result.error === undefined) || refreshing`.
387
+ A rerun of the list's query that something else starts marks the
388
+ result `stale` and leaves `fetching` false. So after a write of your
389
+ own, reload the list with an awaited network-only query inside
390
+ `run.onRefresh()`:
391
+
392
+ ```tsx
393
+ const ended = run.onRefresh()
394
+ try {
395
+ await client.query(ContactsQuery, variables, { requestPolicy: 'network-only' }).toPromise()
396
+ } finally {
397
+ ended()
398
+ }
399
+ ```
400
+
401
+ Never pass `stale` as the flag. A `cache-and-network` query sets it
402
+ on every reopen that finds rows in the cache.
403
+
404
+ A write of your own outside a run, such as a rename, looks the same
405
+ as a run over one row: show its toast as the call ends, then call
406
+ `run.onRefresh()` around its awaited reload.
325
407
 
326
408
  When the page already holds the first rows, such as data the server
327
409
  put in the page, give them to TanStack Query as `initialData`. The
@@ -514,9 +596,15 @@ example does, so the reader sees one toast.
514
596
  ## Running an action over the picked rows
515
597
 
516
598
  Every list action that changes rows does the same things around the
517
- calls: the list reloaded, one toast, and the focus moved back to the
518
- list once a row moved, while the reader is still with the run.
519
- `useListRun` and `useBulkRun` hold those things for you:
599
+ calls: the list marked reloading as the first call that works ends,
600
+ with the focus moved to the list from a part that turns inert, one
601
+ toast as the last call ends, the focus moved back to the list once a
602
+ row moved, while the reader is still with the run, then the list
603
+ reloaded, and the focus put back on the control the reader pressed,
604
+ on the same item when the reload moved it, or on the first control of
605
+ the row that took its place, unless that control is a primary action.
606
+ `useListRun` and `useBulkRun` hold those
607
+ things for you:
520
608
 
521
609
  ```tsx
522
610
  import { Page, RunConfirm, useBulkRun, useListRun } from '@gopherium/godmin'
@@ -561,9 +649,110 @@ calls change with the screen, list them in the dependencies too.
561
649
 
562
650
  `useListRun` keeps track of the runs on the list. Once a run moved a
563
651
  row, the list region takes the focus, so a keyboard reader is not
564
- left on a button that went away with its row. When two runs overlap,
565
- only the latest one moves the focus. The list holds no failure. A run
566
- shows how it went in its toast.
652
+ left on a button that went away with its row while the list reloads.
653
+ The screen does not scroll as the region takes the focus, so a reader
654
+ who ran an action near the bottom of a long list, from a row or from
655
+ a confirm, still sees the rows they were on. While the list reloads,
656
+ the next Tab from the region goes to the first control of the list,
657
+ such as its search field. After a run started from the keyboard, the
658
+ region then draws the ring WordPress draws on a region it focuses, as
659
+ [after a write of your own](./design-system/lists.md#after-a-write-of-your-own)
660
+ shows. When two runs overlap, only the latest one moves the focus.
661
+ The list holds no failure. A run shows how it went in its toast.
662
+
663
+ `useListRun` also hands out `refreshing`, true from the moment the
664
+ first call of a run works until the list's reload after the run
665
+ ends. Pass it to DataViews beside the list's own loading state, as
666
+ [a list that loads](#a-list-that-loads) shows, so the list shows that
667
+ reload as WordPress does
668
+ [after a write of your own](./design-system/lists.md#after-a-write-of-your-own).
669
+
670
+ DataViews then makes the table and the footer inert. A focus in
671
+ either, such as on a row or the busy bulk button, would fall to the
672
+ page, as it does in WordPress, where no control holds it and no ring
673
+ shows. So once DataViews drew the list inert, the list region takes
674
+ that focus in the same render, before the browser drops it, and here
675
+ too the screen does not scroll. A focus anywhere else, such as in the
676
+ search field or outside the list, stays where it is while the calls
677
+ run.
678
+ Pass `refreshing` to DataViews in the render that reads it, never
679
+ through an effect, so the region can take the focus in time.
680
+
681
+ Once the list reloaded, while the region still holds the focus,
682
+ `useListRun` puts the focus back where the reader was:
683
+
684
+ - on the control they pressed, when it is still there and takes the
685
+ focus, such as the bulk action button while a row stays ticked, or
686
+ a row's button while its row stays,
687
+ - else on the same item, wherever its card or row now sits, when the
688
+ list marks its cells with `data-item-id` as
689
+ [`useFocusBack`](#putting-the-focus-back-on-a-row) asks. A DataViews grid draws
690
+ a card anew when it moves to another grid row, so after a save that
691
+ sorts a file elsewhere the pressed control is gone. The focus lands
692
+ on the title, media or phone row the reader pressed, else on the
693
+ item's actions menu,
694
+ - else on the first control of the row that now sits where the row of
695
+ that control was, its checkbox in a list with bulk actions, such as
696
+ the next row's checkbox when the row the reader restored left the
697
+ list, or the last row's when fewer rows came back. In a grid, or in
698
+ the list layout on a phone, it is the first control of the card or
699
+ item in that place,
700
+ - else on the region still, such as when no row came back, when the
701
+ pressed button sat in the bulk bar and the bar went with the ticked
702
+ rows, or when the first control of the row is a primary action from
703
+ `actions`.
704
+
705
+ DataViews names a row's checkbox after the field the view names as its
706
+ `titleField`, and with no `titleField` every checkbox says "(no title)".
707
+ So after a row left, a screen reader says the title of the row now in
708
+ its place, then checkbox and its state, checked or not checked, and a
709
+ second Enter does nothing, since Enter does not tick a checkbox.
710
+
711
+ In a list with no bulk actions the row draws no checkbox, so the first
712
+ control in the row decides. A title that opens the item takes the
713
+ focus, and a second Enter opens that item. The row's actions menu
714
+ button takes the focus when it comes first, since Enter there only
715
+ opens a menu. A primary action from `actions`, such as a Trash with
716
+ `isPrimary`, does not take it, whether or not the action opens a
717
+ confirm. Its button says the action and not the row, so a second
718
+ Enter there would act on a row the reader never picked. So the region
719
+ keeps the focus, a second Enter writes nothing, and the next Tab goes
720
+ to the first control of the list, such as its search field. A button
721
+ that a field's `render` draws takes the focus as any first control
722
+ does, so keep a write in `actions`.
723
+
724
+ For a run from a confirm, the control they pressed is the one that
725
+ opened the confirm, such as the bulk action button or the row's
726
+ actions menu. For an action in a row's actions menu, it is the menu
727
+ button, which the menu gives the focus back to as it closes. After a
728
+ run started from the keyboard, while the region shows its ring, the
729
+ rows scroll to that control when it is out of view. After a mouse
730
+ click the region shows no ring and the rows stay where the reader left
731
+ them. A checkbox, a `Button`, a title or a grid card's media button
732
+ still draws WordPress's own focus style, which it draws on any focus,
733
+ a mouse click included. An item of the list layout shows only its row
734
+ tint and a table media button shows nothing, since those two show a
735
+ focus style only on a keyboard focus. Once a control takes the focus,
736
+ a screen reader has a name to say, and the next Tab goes on from it.
737
+ A reload that fails leaves the old rows, so
738
+ the focus goes back to the control they pressed. A focus the reader
739
+ moved while the list reloaded stays where they put it, and a change
740
+ of the list on show forgets where they were. A reload that also moves
741
+ the view to another page, such as one page back once the last row of
742
+ the last page left, keeps the same rule when it ends after the rows
743
+ of that page show, so the row in that place on the page now on show
744
+ takes the focus as above. When your app moves the page only once the
745
+ reload ended with no rows, the focus stays on the region. A run that
746
+ started with the focus on the page, such as a click that left no
747
+ focus on the button, has nothing to put back, so the focus stays on
748
+ the region.
749
+
750
+ WordPress drops the focus to the page there. No control holds it and
751
+ nothing shows. godmin goes further and keeps the focus on a control,
752
+ or on the region when no control is safe to land on, so the reader
753
+ keeps their place and a keyboard reader sees where they are.
754
+ End the reload only once the list holds its new rows, as an awaited
755
+ reload does, so the focus goes back among the new rows.
567
756
 
568
757
  A run can end while the reader works somewhere else, such as in a
569
758
  dialog they opened on another row. So the list takes the focus only
@@ -604,30 +793,42 @@ your `refresh` does.
604
793
  Its first argument names the list on show. Put the list and its tab
605
794
  in it, such as `'orders trash'`. When that name changes, the list
606
795
  clears the ticked rows and ignores any run started on the list
607
- before. The second argument replaces the ticked
608
- rows. Pass the setter that holds them, such as
796
+ before, with one exception. When the first call of such a run that
797
+ works ends only after the change, the run marks the new list
798
+ reloading until its `refresh` ends, as WordPress reloads every list
799
+ of the same kind of rows after a write. The second argument replaces
800
+ the ticked rows. Pass the setter that holds them, such as
609
801
  `list.onChangeSelection`, or a setter from a parent component. The
610
802
  rows clear in the same frame the new list appears.
611
803
 
612
- `useBulkRun` makes one call per row with `runEach`, waits for
613
- `refresh`, shows one toast in your [bulk words](#bulk-messages) and
614
- then settles the run. The toast holds your `failed` words when any
615
- row failed, and your `done` words when every row worked. Wrap
616
- `refresh` in `useCallback`, or the handler changes on every render.
617
- `refresh` gets the rows the run acted on, so it can also forget each
618
- row's own cached copy. If `refresh` rejects, the run still shows its
619
- toast and settles, then rejects with that error.
804
+ `useBulkRun` makes one call per row with `runEach`. As the first call
805
+ that works ends, it marks the list reloading, while the other calls
806
+ still run. As the last call ends it shows one toast in your
807
+ [bulk words](#bulk-messages), settles the run and resolves, then calls
808
+ `refresh`, and the list stays marked until `refresh` ends. So your app
809
+ never reloads while its own calls still run. When every row failed,
810
+ it still calls `refresh` but marks no reload, since nothing changed.
811
+ The toast holds your `failed` words when any row failed, and your
812
+ `done` words when every row worked. Wrap `refresh` in `useCallback`,
813
+ or the handler changes on every render. `refresh` gets the rows the
814
+ run acted on, so it can also forget each row's own cached copy. A
815
+ `refresh` that rejects ends the reload, and the list's own loading
816
+ state shows the failure, as on any later load. The run resolved
817
+ before it, so it does not reject. A test that awaits the run and then
818
+ reads the reloaded rows waits for the rows instead.
620
819
 
621
820
  `RunConfirm` is the body of the confirm modal. It runs the action
622
821
  when the reader confirms, shows the confirm button busy and keeps
623
- Cancel inert while the run goes, and closes once the run settles. A
624
- failure shows in the run's toast, never inside the modal. It also
625
- closes when the run rejects, and the error still reaches your app.
626
- It closes only itself. DataViews keeps one dialog for a row's actions
627
- menu and another for its primary action buttons. A reader can dismiss
628
- a busy confirm by clicking the dimmed page and open another dialog in
629
- its place, from the same menu or the same buttons. When the run then
630
- ends, that other dialog stays open, with what the reader typed in it.
822
+ Cancel inert while the run goes, and closes once the run settles. So
823
+ it stays open while a call still runs, even once the list started to
824
+ reload, and closes as the toast shows. A failure shows in the run's
825
+ toast, never inside the modal. It also closes when the run rejects,
826
+ and the error still reaches your app. It closes only itself.
827
+ DataViews keeps one dialog for a row's actions menu and another for
828
+ its primary action buttons. A reader can dismiss a busy confirm by
829
+ clicking the dimmed page and open another dialog in its place, from
830
+ the same menu or the same buttons. When the run then ends, that other
831
+ dialog stays open, with what the reader typed in it.
631
832
 
632
833
  `listLabel` and `listRef` make the list a region with a name, which
633
834
  a screen reader announces, and give the focus its target. The region
@@ -637,7 +838,13 @@ still takes the focus, but a screen reader has no name to announce.
637
838
  A button outside the list, such as one in the page header, can share
638
839
  the same run. Call `run.onStart()` as its write starts. It answers a
639
840
  function, typed `RunSettled`. Call that function once the write ends,
640
- with whether a row moved, and show how it went in a toast.
841
+ with whether a row moved, and show how it went in a toast. Then call
842
+ `run.onRefresh()` and reload the list. It answers a function that ends
843
+ the reload. Call it once the reload ends, whether it worked or not,
844
+ as [a list that loads](#a-list-that-loads) shows. The list region
845
+ then takes a focus from a control in the parts DataViews makes inert,
846
+ as in a run, and gives it back the same way once the list reloaded.
847
+ A `ListRun` you build yourself needs an `onRefresh` too.
641
848
 
642
849
  Such a run starts outside every dialog. So when it ends, the list
643
850
  takes the focus only if the focus fell to the page or sits inside the
@@ -1321,10 +1528,7 @@ const view = { type: 'table', titleField: 'name', descriptionField: 'email', fie
1321
1528
  ```
1322
1529
 
1323
1530
  In a list page godmin sets the pair the way the WordPress subscriber
1324
- list does. The title is 13px and bold, and the
1325
- description is a 12px muted line 4px under it. A row with both is
1326
- 64px tall. A title on its own stays centered in a 32px line, level
1327
- with the other cells of its row.
1531
+ list does, as [rows](./design-system/lists.md#rows) gives.
1328
1532
 
1329
1533
  ## Avatars
1330
1534
 
@@ -1388,11 +1592,12 @@ a picture, so no address leaves your application.
1388
1592
 
1389
1593
  Some lists cannot be DataViews, such as a list the user orders by
1390
1594
  hand with arrows. Keep those a `godmin-table`. It looks like the
1391
- DataViews table: 13px text on 20px lines, small capital headers, 12px
1392
- of padding in every cell but only 8px above and below a header,
1393
- rows as tall as the DataViews rows, and a
1394
- light line between rows. Rows also tint under the pointer and while
1395
- keyboard focus is inside them, which DataViews does not do.
1595
+ DataViews table, with small capital headers, rows as tall as the
1596
+ DataViews rows and a light line between rows. Rows also tint under
1597
+ the pointer and while keyboard focus is inside them, which DataViews
1598
+ does not do.
1599
+ [Tables that stay custom](./design-system/lists.md#tables-that-stay-custom)
1600
+ gives every value.
1396
1601
 
1397
1602
  Mark the cell that names the record `godmin-table__title`. It draws
1398
1603
  the name bold, as DataViews draws its titles. A link inside it has no
@@ -1406,7 +1611,7 @@ DataViews title field:
1406
1611
  ```
1407
1612
 
1408
1613
  Inside a `list` page the table reaches the canvas edges too, and its
1409
- first and last cells pad by 24px, as DataViews does. A custom list
1614
+ first and last cells pad as DataViews pads its own. A custom list
1410
1615
  and a DataViews list then line up with each other and with the title.
1411
1616
 
1412
1617
  While its first rows load, show `LoadingScreen` in place of the
@@ -1433,7 +1638,8 @@ await startLocale(resolveLocale, [
1433
1638
  `listChromeCatalogFor` answers the catalogue for `es-ES`, and one
1434
1639
  for `fr-FR` with the loading words, the [list date](#dates-in-a-list)
1435
1640
  words and
1436
- [godmin's own words](./framing-an-application.md#godmins-own-words).
1641
+ [godmin's own words](./framing-an-application.md#godmins-own-words),
1642
+ the words of `ListNoResults` among them.
1437
1643
  For any other language it answers `undefined`. French readers and
1438
1644
  those others keep the English chrome. Each catalogue is its own small
1439
1645
  module, so a bundler loads it only for a reader who needs it.
@@ -199,22 +199,20 @@ Name an item in straight double quotes and in full, like
199
199
  snackbar, and godmin does not either.
200
200
  [Size](./design-system/toasts.md#size) says how a long one wraps.
201
201
 
202
- Use a toast for a write that failed in a dialog or in a run over list
203
- rows too. WordPress shows those in its snackbar, never inside the
204
- dialog and never above the list, and godmin's dialogs and list runs
205
- do the same. Say what failed, in the words your server sent when it
206
- sent some. [A failure from a dialog](./lists.md#a-failure-from-a-dialog)
202
+ Use a toast for a write that failed too, in a dialog, on a page or in
203
+ a run over list rows. WordPress shows those in its snackbar, never
204
+ inside the dialog and never above the list, and godmin's dialogs and
205
+ list runs do the same. Say what failed, in the words your server sent
206
+ when it sent some. A server message about one field goes under that
207
+ field. [A failure from a dialog](./lists.md#a-failure-from-a-dialog)
207
208
  shows how to raise one from a dialog.
208
209
  [Running an action over the picked rows](./lists.md#running-an-action-over-the-picked-rows)
209
210
  raises it for you after a run over a list.
210
211
 
211
212
  Keep an [`ErrorNotice`](./screens.md#errornotice) for a failure
212
- that has to stay on the screen until the user acts:
213
-
214
- - A screen or a list that failed to load. Show the notice where the
215
- content would be.
216
- - A form on a page of its own, not in a dialog. Show the notice next
217
- to the form, so the user sees what failed while they fix it.
213
+ that has to stay on the screen until the user acts, such as a screen
214
+ or a list that failed to load. Show the notice where the content
215
+ would be.
218
216
 
219
217
  Skip the toast in three more cases:
220
218
 
package/docs/overview.md CHANGED
@@ -29,7 +29,7 @@ duplicates something the packages above already ship.
29
29
 
30
30
  | Entry point | Contents |
31
31
  | --- | --- |
32
- | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `useCloseWhileOpen`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
32
+ | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `PageBreadcrumbs`, `PageBreadcrumb`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ListNoResults`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `useCloseWhileOpen`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
33
33
  | `@gopherium/godmin/base.css` | Cascade layer order, design tokens, host rules, frame and screen styles |
34
34
  | `@gopherium/godmin/dates` | `startListDates`, `listDate`, the only entry that loads `@wordpress/date` |
35
35
  | `@gopherium/godmin/dialogs` | `ConfirmDialog`, `FormDialog`, the only entry that loads `@wordpress/components`. Load `@wordpress/components/build-style/style.css` once in your app, as DataViews asks |