@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.
- package/README.md +4 -3
- package/dist/base.css +223 -13
- package/dist/bulk-run.d.ts +3 -3
- package/dist/bulk-run.js +41 -13
- package/dist/focus-back.d.ts +22 -0
- package/dist/focus-back.js +37 -13
- package/dist/index.d.ts +5 -3
- package/dist/index.js +4 -3
- package/dist/list-chrome/es-ES.d.ts +1 -1
- package/dist/list-chrome/es-ES.js +7 -4
- package/dist/list-chrome/fr-FR.d.ts +1 -1
- package/dist/list-chrome/fr-FR.js +5 -1
- package/dist/list-empty.d.ts +14 -7
- package/dist/list-empty.js +14 -4
- package/dist/list-run.d.ts +8 -4
- package/dist/list-run.js +143 -6
- package/dist/page-breadcrumbs.d.ts +28 -0
- package/dist/page-breadcrumbs.js +18 -0
- package/dist/page-tabs.js +29 -26
- package/dist/page.d.ts +8 -3
- package/dist/page.js +48 -9
- package/dist/size-watch.d.ts +11 -0
- package/dist/size-watch.js +36 -0
- package/dist/wide-list.d.ts +7 -0
- package/dist/wide-list.js +33 -0
- package/docs/build-and-versioning.md +3 -3
- package/docs/design-system/accessibility.md +64 -16
- package/docs/design-system/custom-properties.md +9 -2
- package/docs/design-system/layout.md +5 -3
- package/docs/design-system/lists.md +234 -0
- package/docs/design-system/loading.md +2 -0
- package/docs/design-system/overview.md +6 -1
- package/docs/design-system/radius-and-elevation.md +3 -9
- package/docs/design-system/record-pages.md +197 -0
- package/docs/design-system/toasts.md +2 -3
- package/docs/design-system/typography.md +3 -3
- package/docs/framing-an-application.md +7 -5
- package/docs/lists.md +278 -72
- package/docs/loading-and-feedback.md +9 -11
- package/docs/overview.md +1 -1
- package/docs/screens.md +83 -36
- 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
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
|
124
|
-
|
|
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
|
|
135
|
-
screen is on. `openOnTap` comes from
|
|
136
|
-
`useListView`, and from the main
|
|
137
|
-
|
|
138
|
-
it. It reads only `phone` and
|
|
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
|
|
228
|
-
|
|
229
|
-
|
|
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
|
|
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={
|
|
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
|
|
284
|
-
|
|
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
|
|
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
|
-
<
|
|
331
|
+
<ListNoResults />
|
|
294
332
|
) : (
|
|
295
|
-
<ListEmpty
|
|
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,
|
|
313
|
-
for its answer
|
|
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
|
-
|
|
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
|
|
518
|
-
|
|
519
|
-
|
|
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
|
|
565
|
-
|
|
566
|
-
|
|
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
|
|
608
|
-
|
|
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
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
`refresh
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
toast
|
|
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.
|
|
624
|
-
|
|
625
|
-
closes
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
its
|
|
630
|
-
|
|
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
|
|
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
|
|
1392
|
-
|
|
1393
|
-
|
|
1394
|
-
|
|
1395
|
-
|
|
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
|
|
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
|
|
203
|
-
rows
|
|
204
|
-
dialog and never above the list, and godmin's dialogs and
|
|
205
|
-
do the same. Say what failed, in the words your server sent
|
|
206
|
-
sent some.
|
|
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
|
-
|
|
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 |
|