@gopherium/godmin 0.32.0 → 0.33.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 +19 -9
- package/dist/admin-root.d.ts +4 -2
- package/dist/admin-root.js +6 -3
- package/dist/announcer-heading.d.ts +4 -0
- package/dist/announcer-heading.js +25 -0
- package/dist/base.css +36 -4
- package/dist/bulk-run.d.ts +2 -2
- package/dist/bulk-run.js +18 -2
- package/dist/confirm-dialog.d.ts +2 -2
- package/dist/confirm-dialog.js +3 -2
- package/dist/dialog-open.d.ts +16 -2
- package/dist/dialog-open.js +126 -5
- package/dist/drilldown-item.d.ts +5 -2
- package/dist/drilldown-item.js +14 -2
- package/dist/filter-offer.d.ts +5 -5
- package/dist/filter-offer.js +9 -9
- package/dist/focus-back.js +12 -2
- package/dist/form-dialog.d.ts +2 -2
- package/dist/form-dialog.js +3 -2
- package/dist/frame.d.ts +8 -4
- package/dist/frame.js +16 -6
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -2
- package/dist/list-chrome/es-ES.d.ts +1 -1
- package/dist/list-chrome/es-ES.js +11 -8
- package/dist/list-chrome/fr-FR.d.ts +1 -1
- package/dist/list-chrome/fr-FR.js +9 -1
- package/dist/navigation-item.d.ts +4 -2
- package/dist/navigation-item.js +2 -2
- package/dist/navigation-screen.js +10 -3
- package/dist/navigation.js +5 -1
- package/dist/page.d.ts +3 -2
- package/dist/page.js +23 -4
- package/dist/rejected-field.d.ts +25 -0
- package/dist/rejected-field.js +121 -0
- package/dist/rename-dialog.d.ts +2 -2
- package/dist/rename-dialog.js +1 -1
- package/dist/route-not-found.d.ts +5 -0
- package/dist/route-not-found.js +12 -0
- package/dist/router.d.ts +8 -2
- package/dist/router.js +10 -2
- package/dist/screen-title.d.ts +52 -0
- package/dist/screen-title.js +165 -0
- package/dist/stylelint.d.ts +1 -4
- package/dist/stylelint.js +4 -7
- package/dist/testing.d.ts +2 -2
- package/dist/testing.js +3 -3
- package/dist/vite.js +1 -0
- package/docs/build-and-versioning.md +109 -4
- package/docs/design-system/accessibility.md +18 -9
- package/docs/design-system/color.md +1 -1
- package/docs/design-system/custom-properties.md +3 -3
- package/docs/design-system/dialogs.md +71 -9
- package/docs/design-system/frame.md +276 -0
- package/docs/design-system/layout.md +24 -16
- package/docs/design-system/lists.md +17 -11
- package/docs/design-system/loading.md +20 -12
- package/docs/design-system/motion.md +41 -47
- package/docs/design-system/overview.md +8 -3
- package/docs/design-system/radius-and-elevation.md +2 -2
- package/docs/design-system/record-pages.md +9 -1
- package/docs/design-system/toasts.md +7 -1
- package/docs/framing-an-application.md +77 -23
- package/docs/lists.md +80 -39
- package/docs/overview.md +9 -3
- package/docs/screens.md +94 -3
- package/docs/testing.md +29 -0
- package/package.json +27 -19
package/docs/lists.md
CHANGED
|
@@ -164,7 +164,7 @@ field of type `media` or `password` sorts only when it says
|
|
|
164
164
|
`enableSorting: true`.
|
|
165
165
|
|
|
166
166
|
A filter stays when DataViews offers it. `offeredView` reads the
|
|
167
|
-
field as DataViews
|
|
167
|
+
field as DataViews 22 does:
|
|
168
168
|
|
|
169
169
|
- The field does not say `filterBy: false`.
|
|
170
170
|
- The operator is one the field names in `filterBy.operators` and its
|
|
@@ -200,12 +200,15 @@ empty when nothing stayed.
|
|
|
200
200
|
## The list fills the page
|
|
201
201
|
|
|
202
202
|
A list page fills the canvas from the title down to the bottom edge.
|
|
203
|
-
The DataViews footer, with the item count and the
|
|
203
|
+
The DataViews footer, with the item count and the page buttons,
|
|
204
204
|
rests on the bottom edge of the canvas, the way the list already
|
|
205
205
|
reaches the side edges. With a few rows, the rows sit at the top,
|
|
206
206
|
the empty space sits under them, and no line closes the last row.
|
|
207
207
|
The next line is the footer's own, at the bottom.
|
|
208
208
|
|
|
209
|
+
The select all box and the bulk actions sit at the top of the list,
|
|
210
|
+
as [a list page](./design-system/lists.md#a-list-page) shows.
|
|
211
|
+
|
|
209
212
|
When the list is longer than the screen, only the rows scroll. The
|
|
210
213
|
title, the tabs, the search box and the column headers stay where
|
|
211
214
|
they are, and the footer stays on the bottom edge. A toast floats
|
|
@@ -234,9 +237,8 @@ Draw a muted cell with a weak text color, such as
|
|
|
234
237
|
A cell with less than full opacity paints over the frozen columns as
|
|
235
238
|
it scrolls under them.
|
|
236
239
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
with no icon.
|
|
240
|
+
At `EDGE_BREAKPOINT` and below, DataViews puts the bulk actions in
|
|
241
|
+
one Actions menu, each by its label. A bulk action needs no `icon`.
|
|
240
242
|
|
|
241
243
|
## Tabs above a list
|
|
242
244
|
|
|
@@ -617,7 +619,7 @@ function OrdersScreen() {
|
|
|
617
619
|
const bulk = useBulkRun<Order>(run, refresh)
|
|
618
620
|
const [deleting, setDeleting] = useState<Order[]>()
|
|
619
621
|
const actions = useMemo<Action<Order>[]>(
|
|
620
|
-
() => [{ id: 'delete', label: 'Delete
|
|
622
|
+
() => [{ id: 'delete', label: 'Delete', supportsBulk: true, callback: setDeleting }],
|
|
621
623
|
[],
|
|
622
624
|
)
|
|
623
625
|
return (
|
|
@@ -630,7 +632,7 @@ function OrdersScreen() {
|
|
|
630
632
|
description="This action cannot be undone."
|
|
631
633
|
confirmLabel="Delete"
|
|
632
634
|
cancelLabel="Cancel"
|
|
633
|
-
onConfirm={() => bulk(deleting, (order) => deleteOrder(order.id), words)}
|
|
635
|
+
onConfirm={(signal) => bulk(deleting, (order) => deleteOrder(order.id, signal), words)}
|
|
634
636
|
onClose={() => setDeleting(undefined)}
|
|
635
637
|
/>
|
|
636
638
|
) : null}
|
|
@@ -665,14 +667,14 @@ ends. Pass it to DataViews beside the list's own loading state, as
|
|
|
665
667
|
reload as WordPress does
|
|
666
668
|
[after a write of your own](./design-system/lists.md#after-a-write-of-your-own).
|
|
667
669
|
|
|
668
|
-
DataViews then makes the table and the footer inert. A
|
|
669
|
-
|
|
670
|
-
page, as it does in WordPress, where no control holds it
|
|
671
|
-
shows. So once DataViews drew the list inert, the list
|
|
672
|
-
that focus in the same render, before the browser drops
|
|
673
|
-
too the screen does not scroll. A focus anywhere else,
|
|
674
|
-
search field or outside the list, stays where it is
|
|
675
|
-
run.
|
|
670
|
+
DataViews then makes the table, the bulk bar and the footer inert. A
|
|
671
|
+
focus in any of them, such as on a row or the busy bulk button, would
|
|
672
|
+
fall to the page, as it does in WordPress, where no control holds it
|
|
673
|
+
and no ring shows. So once DataViews drew the list inert, the list
|
|
674
|
+
region takes that focus in the same render, before the browser drops
|
|
675
|
+
it, and here too the screen does not scroll. A focus anywhere else,
|
|
676
|
+
such as in the search field or outside the list, stays where it is
|
|
677
|
+
while the calls run.
|
|
676
678
|
Pass `refreshing` to DataViews in the render that reads it, never
|
|
677
679
|
through an effect, so the region can take the focus in time.
|
|
678
680
|
|
|
@@ -843,7 +845,9 @@ goes, and the list takes it from there once a row moved. This needs
|
|
|
843
845
|
godmin 0.32.0 or later.
|
|
844
846
|
|
|
845
847
|
A confirm whose `onConfirm` returns the run stays open until the run
|
|
846
|
-
ends, then closes as the toast shows.
|
|
848
|
+
ends, then closes as the toast shows. `onConfirm` gets the dialog's
|
|
849
|
+
signal, so hand it to each call, as `deleteOrder` takes it. A call
|
|
850
|
+
that stops on it fails, and the run reports it in the toast.
|
|
847
851
|
|
|
848
852
|
`listLabel` and `listRef` make the list a region with a name, which
|
|
849
853
|
a screen reader announces, and give the focus its target. The region
|
|
@@ -941,9 +945,14 @@ shows:
|
|
|
941
945
|
once it has gone, and the list takes the focus once the run moved a
|
|
942
946
|
row, while the focus is still on that button. A reader who moved to
|
|
943
947
|
another control or opened another dialog by then keeps their place.
|
|
948
|
+
No time limit applies, since the dialog no longer waits.
|
|
944
949
|
- Return the write's promise, and the dialog stays open while it
|
|
945
950
|
runs, with a spinner on its confirm button. When the promise ends,
|
|
946
951
|
the dialog closes. A run over the picked rows works this way.
|
|
952
|
+
`onConfirm` gets the dialog's signal. Pass it to your write, so the
|
|
953
|
+
request stops once the time limit of `AdminRoot` runs out, as
|
|
954
|
+
[while a write runs](./design-system/dialogs.md#while-a-write-runs)
|
|
955
|
+
says.
|
|
947
956
|
- Answer `{ error: 'words' }`, at once or as the promise ends, and the
|
|
948
957
|
dialog stays open and shows the words inside. Do this when trying
|
|
949
958
|
again is the next step. Answer `{ close: false }` to stay open and
|
|
@@ -962,8 +971,8 @@ try again:
|
|
|
962
971
|
description="New items will use it."
|
|
963
972
|
confirmLabel="Make default"
|
|
964
973
|
cancelLabel="Cancel"
|
|
965
|
-
onConfirm={() =>
|
|
966
|
-
makeDefault(item.id).then(
|
|
974
|
+
onConfirm={(signal) =>
|
|
975
|
+
makeDefault(item.id, signal).then(
|
|
967
976
|
() => toaster.show(`"${item.name}" is now the default.`),
|
|
968
977
|
(failure: Error) => ({ error: failure.message }),
|
|
969
978
|
)
|
|
@@ -1015,7 +1024,7 @@ function PostsScreen() {
|
|
|
1015
1024
|
const write = useDialogRun<Post>(run, refresh)
|
|
1016
1025
|
const [renaming, setRenaming] = useState<Post>()
|
|
1017
1026
|
const actions = useMemo<Action<Post>[]>(
|
|
1018
|
-
() => [{ id: 'rename', label: 'Rename
|
|
1027
|
+
() => [{ id: 'rename', label: 'Rename', callback: ([post]) => setRenaming(post) }],
|
|
1019
1028
|
[],
|
|
1020
1029
|
)
|
|
1021
1030
|
return (
|
|
@@ -1028,7 +1037,9 @@ function PostsScreen() {
|
|
|
1028
1037
|
fieldLabel="Name"
|
|
1029
1038
|
submitLabel="Save"
|
|
1030
1039
|
cancelLabel="Cancel"
|
|
1031
|
-
onSubmit={(title
|
|
1040
|
+
onSubmit={(title, signal) =>
|
|
1041
|
+
write([renaming], (post) => renamePost(post.id, title, signal), nameWords, signal)
|
|
1042
|
+
}
|
|
1032
1043
|
onClose={() => setRenaming(undefined)}
|
|
1033
1044
|
/>
|
|
1034
1045
|
) : null}
|
|
@@ -1046,13 +1057,14 @@ Save stays on, even with the field blank, as in the WordPress rename.
|
|
|
1046
1057
|
The field is required and must hold more than spaces, so the browser
|
|
1047
1058
|
refuses a blank name in its own words and sends nothing. A name left
|
|
1048
1059
|
as it was still sends. Enter in the field does what Save does.
|
|
1049
|
-
`onSubmit` gets the name exactly as typed.
|
|
1060
|
+
`onSubmit` gets the name exactly as typed, then the dialog's signal.
|
|
1050
1061
|
|
|
1051
1062
|
`onSubmit` answers the dialog as the one of
|
|
1052
1063
|
[a form dialog](#a-form-dialog) does. Through `useDialogRun`, the
|
|
1053
1064
|
dialog stays open while the write runs, with a spinner on Save and
|
|
1054
1065
|
the field read-only. It closes when the write works, and stays with
|
|
1055
|
-
the words of `failed` and the typed name when it fails
|
|
1066
|
+
the words of `failed` and the typed name when it fails or runs past
|
|
1067
|
+
the time limit, as
|
|
1056
1068
|
[a failure from a dialog](#a-failure-from-a-dialog) shows.
|
|
1057
1069
|
|
|
1058
1070
|
A rename that closes at once, by returning nothing from `onSubmit`
|
|
@@ -1082,8 +1094,8 @@ function AddProjectDialog({ onClose }: { onClose: () => void }) {
|
|
|
1082
1094
|
submitLabel="Add"
|
|
1083
1095
|
cancelLabel="Cancel"
|
|
1084
1096
|
canSubmit={name.trim() !== ''}
|
|
1085
|
-
onSubmit={() =>
|
|
1086
|
-
addProject(name).then(
|
|
1097
|
+
onSubmit={(signal) =>
|
|
1098
|
+
addProject(name, signal).then(
|
|
1087
1099
|
() => void toaster.show(`"${name}" added.`),
|
|
1088
1100
|
(failure: Error) => ({ error: `Could not add the project. ${failure.message}` }),
|
|
1089
1101
|
)
|
|
@@ -1123,9 +1135,10 @@ nothing to close at once, or the write's promise to keep the dialog
|
|
|
1123
1135
|
open with a spinner until it ends. Answer `{ error }` to stay open and
|
|
1124
1136
|
say why, or `{ close: false }` to stay open with nothing said, as
|
|
1125
1137
|
[when a dialog closes](./design-system/dialogs.md#when-a-dialog-closes)
|
|
1126
|
-
says.
|
|
1127
|
-
|
|
1128
|
-
dialog
|
|
1138
|
+
says. `onSubmit` gets the dialog's signal, and `addProject` takes it,
|
|
1139
|
+
so the request stops once the time limit of `AdminRoot` runs out. godmin
|
|
1140
|
+
closes the dialog itself, so call nothing to close it. `onClose` runs
|
|
1141
|
+
once the card has left, and that is where you take the dialog away.
|
|
1129
1142
|
|
|
1130
1143
|
While the write runs, Cancel, the close icon, Escape and a click on
|
|
1131
1144
|
the dimmed page close nothing. Pass a function as the children to
|
|
@@ -1185,9 +1198,13 @@ layout has no such trigger, such as a title in the phone list, it
|
|
|
1185
1198
|
focuses the row's actions menu. When the item left the list, or its
|
|
1186
1199
|
row has no actions menu, the list region takes the focus.
|
|
1187
1200
|
|
|
1188
|
-
An action chosen in the bulk bar reads `bulk` from `focusedTrigger()
|
|
1189
|
-
|
|
1190
|
-
|
|
1201
|
+
An action chosen in the bulk bar reads `bulk` from `focusedTrigger()`
|
|
1202
|
+
at every width. At `EDGE_BREAKPOINT` and below, DataViews puts the
|
|
1203
|
+
bulk actions in one Actions menu, and an action picked there reads
|
|
1204
|
+
`bulk` too. While the bar still shows, the dialog gives the focus back
|
|
1205
|
+
to the button that opened it, such as that Actions menu button. The
|
|
1206
|
+
bar goes away once the selection clears, so the list region takes the
|
|
1207
|
+
focus.
|
|
1191
1208
|
|
|
1192
1209
|
The hook only moves a focus the page lost. When WordPress already put
|
|
1193
1210
|
the focus back, or the reader moved it, it stays where it is. While
|
|
@@ -1217,8 +1234,8 @@ that closes says how its write went in a toast, as
|
|
|
1217
1234
|
the failure into words and answer them as `{ error }`:
|
|
1218
1235
|
|
|
1219
1236
|
```tsx
|
|
1220
|
-
onSubmit={() =>
|
|
1221
|
-
save(values).then(
|
|
1237
|
+
onSubmit={(signal) =>
|
|
1238
|
+
save(values, signal).then(
|
|
1222
1239
|
() => undefined,
|
|
1223
1240
|
(failure: Error) => ({ error: `Could not save the project. ${failure.message}` }),
|
|
1224
1241
|
)
|
|
@@ -1233,8 +1250,18 @@ reads the same answers. Answer `{ close: false }` when the words go
|
|
|
1233
1250
|
somewhere else, such as a server message about one field under that
|
|
1234
1251
|
field.
|
|
1235
1252
|
|
|
1236
|
-
A write that rejects with nothing caught also
|
|
1237
|
-
with no words, and its error goes on to your
|
|
1253
|
+
A write that rejects before the time limit with nothing caught also
|
|
1254
|
+
leaves the dialog open, with no words, and its error goes on to your
|
|
1255
|
+
app.
|
|
1256
|
+
|
|
1257
|
+
Hand the dialog's signal to your write, as `save` takes it here. Once
|
|
1258
|
+
the time limit of `AdminRoot` runs out, the signal fires and the write
|
|
1259
|
+
rejects. `fetch` rejects with the signal's own reason, and `apiFetch`
|
|
1260
|
+
from `@wordpress/api-fetch` with an error of its own, and the
|
|
1261
|
+
`message` of both holds the time-out words. Caught as here, those
|
|
1262
|
+
words follow yours. Left uncaught, the dialog shows them alone, as
|
|
1263
|
+
[while a write runs](./design-system/dialogs.md#while-a-write-runs)
|
|
1264
|
+
says, whatever error the write rejects with.
|
|
1238
1265
|
|
|
1239
1266
|
Many GraphQL clients answer a failed write with an object in `error`
|
|
1240
1267
|
instead of rejecting, as [bulk actions](#bulk-actions) says. Only
|
|
@@ -1261,7 +1288,7 @@ const tagWords: BulkWords<Post> = {
|
|
|
1261
1288
|
title="Add tag"
|
|
1262
1289
|
submitLabel="Add"
|
|
1263
1290
|
cancelLabel="Cancel"
|
|
1264
|
-
onSubmit={() => write(tagging, (post) => addTag(post.id, tag), tagWords)}
|
|
1291
|
+
onSubmit={(signal) => write(tagging, (post) => addTag(post.id, tag, signal), tagWords, signal)}
|
|
1265
1292
|
onClose={() => setTagging(undefined)}
|
|
1266
1293
|
>
|
|
1267
1294
|
<InputControl label="Tag" value={tag} onChange={(event) => setTag(event.target.value)} />
|
|
@@ -1281,6 +1308,15 @@ The action's `callback` stores the rows in `tagging`, as
|
|
|
1281
1308
|
- The promise ends before the reload ends, so the dialog closes
|
|
1282
1309
|
without waiting for the list.
|
|
1283
1310
|
|
|
1311
|
+
Pass the dialog's signal as the fourth argument of `write`. A call
|
|
1312
|
+
still running when the signal fires counts as failed at once, and its
|
|
1313
|
+
error is the signal's reason, whose `message` holds the time-out
|
|
1314
|
+
words. So one item stays with your `failed` words, and several items
|
|
1315
|
+
close the dialog with the toast. The run does not hand the signal to
|
|
1316
|
+
`call`, so pass it on yourself, as `addTag` takes it. A call that
|
|
1317
|
+
ignores the signal still counts as failed, but its write may still
|
|
1318
|
+
reach your server.
|
|
1319
|
+
|
|
1284
1320
|
A run moves the focus to the list, so write through `useDialogRun`
|
|
1285
1321
|
only from a dialog that closes when its write works. A dialog that
|
|
1286
1322
|
stays open after a run that worked would leave the focus behind it.
|
|
@@ -1289,8 +1325,8 @@ Do not catch a failure as a separate step and then return the first
|
|
|
1289
1325
|
promise:
|
|
1290
1326
|
|
|
1291
1327
|
```tsx
|
|
1292
|
-
onSubmit={() => {
|
|
1293
|
-
const saving = save(values)
|
|
1328
|
+
onSubmit={(signal) => {
|
|
1329
|
+
const saving = save(values, signal)
|
|
1294
1330
|
saving.catch((failure) => toaster.show(failure.message))
|
|
1295
1331
|
return saving
|
|
1296
1332
|
}}
|
|
@@ -1382,7 +1418,7 @@ It sets it on the document root, so menus and modals that render
|
|
|
1382
1418
|
outside your tree follow it too.
|
|
1383
1419
|
|
|
1384
1420
|
```tsx
|
|
1385
|
-
<AdminRoot color={{ primary: '#c9356e' }}>
|
|
1421
|
+
<AdminRoot color={{ primary: '#c9356e' }} writeTimeout={settings.writeTimeout}>
|
|
1386
1422
|
<App />
|
|
1387
1423
|
</AdminRoot>
|
|
1388
1424
|
```
|
|
@@ -1527,7 +1563,12 @@ The Spanish one covers every word DataViews shows around a list: the
|
|
|
1527
1563
|
search box, the view options, the filters, the column menus, the
|
|
1528
1564
|
paging and the bulk bar. It also covers the two words
|
|
1529
1565
|
`@wordpress/components` shows inside a list, the search reset button
|
|
1530
|
-
and the modal close button. It does not cover DataForm.
|
|
1566
|
+
and the modal close button. It does not cover DataForm. Both
|
|
1567
|
+
catalogues also cover Notifications, the hidden text `@wordpress/a11y`
|
|
1568
|
+
puts before the live regions that godmin's announcements fill. That
|
|
1569
|
+
text is written before your app loads any catalogue, so `AdminRoot`
|
|
1570
|
+
writes it again in the loaded language, and again each time the
|
|
1571
|
+
language changes.
|
|
1531
1572
|
|
|
1532
1573
|
The translations are machine made. They stay marked fuzzy in the
|
|
1533
1574
|
sources, `src/list-chrome/es-ES.po` and `src/list-chrome/fr-FR.po`
|
package/docs/overview.md
CHANGED
|
@@ -29,10 +29,10 @@ 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`, `PageBreadcrumbs`, `PageBreadcrumb`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ListNoResults`, `ConfirmDialog`, `FormDialog`, `RenameDialog`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `useDialogRun`, `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`, `ConfirmDialog`, `FormDialog`, `RenameDialog`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `useDialogRun`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `useRejectedField`, `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
|
-
| `@gopherium/godmin/router` | `Navigation`, `NavigationList`, `NavigationItem`, `DrilldownItem`, `useCanAccess` and the `MenuItem` type with its optional `count`, `useListView`, `listSearch`, `openOnTap`, `useCanvas`, `useFrameLocation`, `
|
|
35
|
+
| `@gopherium/godmin/router` | `Navigation`, `NavigationList`, `NavigationItem`, `DrilldownItem`, `useCanAccess` and the `MenuItem` type with its optional `count`, `useListView`, `listSearch`, `openOnTap`, `useCanvas`, `useFrameLocation`, `useShownPath`, `routerDefaults` and its not found screen, `UnsavedChangesDialog`, the `canvas`, `Sidebar` and `capability` route static data |
|
|
36
36
|
| `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport` and its `TestViewport` type, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR`, `textClasses`, `badgeClasses`, `buttonClasses`, `stubLayout` |
|
|
37
37
|
| `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy`, `godminStylesheetFirst`, `duplicateCopies`, `hoistStylesheet` |
|
|
38
38
|
| `@gopherium/godmin/stylelint` | The design system stylelint rules |
|
|
@@ -62,7 +62,7 @@ import '@gopherium/godmin/base.css'
|
|
|
62
62
|
import { AdminRoot } from '@gopherium/godmin'
|
|
63
63
|
|
|
64
64
|
createRoot(document.getElementById('app')!).render(
|
|
65
|
-
<AdminRoot>
|
|
65
|
+
<AdminRoot writeTimeout={settings.writeTimeout}>
|
|
66
66
|
<YourApp />
|
|
67
67
|
</AdminRoot>,
|
|
68
68
|
)
|
|
@@ -83,6 +83,12 @@ That is the whole setup. Here is what those two lines do for you:
|
|
|
83
83
|
- Give the page the design system's own blue as its accent, the
|
|
84
84
|
color of primary buttons, selected rows and focus rings. Pass
|
|
85
85
|
your own `color` to use another one.
|
|
86
|
+
- Give every busy dialog a time limit for its write. `writeTimeout`
|
|
87
|
+
is required and takes it in milliseconds. Read it from your app's
|
|
88
|
+
own settings, here `settings.writeTimeout`, since godmin sets no
|
|
89
|
+
limit of its own.
|
|
90
|
+
[While a write runs](./design-system/dialogs.md#while-a-write-runs)
|
|
91
|
+
says what a dialog does when the limit runs out.
|
|
86
92
|
|
|
87
93
|
`AdminRoot` also accepts the `color`, `cursor` and `cornerRadius`
|
|
88
94
|
theme settings, which it hands to the design system theme provider,
|
package/docs/screens.md
CHANGED
|
@@ -21,7 +21,10 @@ one in a component of your own.
|
|
|
21
21
|
|
|
22
22
|
`title` is required and becomes the page's heading, at the size of a
|
|
23
23
|
WordPress page title. It is an `h1` unless you pass
|
|
24
|
-
`headingLevel`, as [heading levels](#heading-levels) explains.
|
|
24
|
+
`headingLevel`, as [heading levels](#heading-levels) explains. It is
|
|
25
|
+
also what a screen reader hears when the screen opens, as
|
|
26
|
+
[what a screen reader hears when the screen changes](./design-system/frame.md#what-a-screen-reader-hears-when-the-screen-changes)
|
|
27
|
+
says.
|
|
25
28
|
`actions` renders top right,
|
|
26
29
|
and `className` and `children` do what they always do. When the
|
|
27
30
|
actions no longer fit beside the title, on a phone for example, they
|
|
@@ -85,7 +88,9 @@ hands the same ref to `useFocusBack`, which puts the focus back on
|
|
|
85
88
|
the row a dialog opened from.
|
|
86
89
|
|
|
87
90
|
A screen that fills the canvas edge to edge builds its own layout
|
|
88
|
-
and uses `PageTitle` directly, so the page still gets its heading
|
|
91
|
+
and uses `PageTitle` directly, so the page still gets its heading.
|
|
92
|
+
Give it plain text, since that text is also what a screen reader
|
|
93
|
+
hears when the screen opens:
|
|
89
94
|
|
|
90
95
|
```tsx
|
|
91
96
|
<PageTitle>Conversations</PageTitle>
|
|
@@ -241,8 +246,19 @@ then the content.
|
|
|
241
246
|
`Navigation` it goes to the app's `home`. Pass `back`, a link
|
|
242
247
|
element from your router, to send it somewhere else. The root
|
|
243
248
|
screen has no Back.
|
|
249
|
+
- Back draws the link you pass with the chevron in place of anything
|
|
250
|
+
the link holds. Its own class comes first and the link's class
|
|
251
|
+
after it. The link's `onClick` runs first, and Back records its
|
|
252
|
+
move only when that click did not call `preventDefault()`. The
|
|
253
|
+
link's `style` and data attributes stay.
|
|
244
254
|
- `backLabel` names Back for assistive technology. It defaults to
|
|
245
|
-
"Back", translated by godmin.
|
|
255
|
+
"Back", translated by godmin. An `aria-label` on the link you pass
|
|
256
|
+
wins over it.
|
|
257
|
+
- Back is your router's own link, so it carries the mark of the
|
|
258
|
+
current page, which a screen reader hears, while a slow `home`
|
|
259
|
+
loads. Let the loader of `home` answer fast, as
|
|
260
|
+
[the sidebar marks](./design-system/frame.md#the-sidebar-marks)
|
|
261
|
+
says.
|
|
246
262
|
- `description` renders above the content, and `actions` at the end
|
|
247
263
|
of the title row.
|
|
248
264
|
- `footer` stays at the bottom of the screen while the rest scrolls.
|
|
@@ -394,6 +410,81 @@ letters such as ß and ø are spelled in plain a to z. When the key is
|
|
|
394
410
|
already in `taken`, the first free number is added, so `birthDate`
|
|
395
411
|
becomes `birthDate2`.
|
|
396
412
|
|
|
413
|
+
## A server message under a field
|
|
414
|
+
|
|
415
|
+
Some values only the server can reject, such as an email address
|
|
416
|
+
another account already uses. Its words then go under the field they
|
|
417
|
+
are about, the way a check made before sending would.
|
|
418
|
+
`useRejectedField` holds those words for one field.
|
|
419
|
+
|
|
420
|
+
Here `invite` answers the server's words about the email, or nothing
|
|
421
|
+
when it worked.
|
|
422
|
+
|
|
423
|
+
```tsx
|
|
424
|
+
const [email, setEmail] = useState('')
|
|
425
|
+
const rejectedEmail = useRejectedField(email)
|
|
426
|
+
const toaster = useToaster()
|
|
427
|
+
const send = async () => {
|
|
428
|
+
const sent = email
|
|
429
|
+
const words = await invite(sent.trim())
|
|
430
|
+
if (words === undefined || rejectedEmail.reject(words, sent)) {
|
|
431
|
+
return
|
|
432
|
+
}
|
|
433
|
+
toaster.show(`Could not send the invitation. ${words}`)
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
return (
|
|
437
|
+
<form
|
|
438
|
+
className="godmin-form"
|
|
439
|
+
onSubmit={(event) => {
|
|
440
|
+
event.preventDefault()
|
|
441
|
+
void send()
|
|
442
|
+
}}
|
|
443
|
+
>
|
|
444
|
+
<ValidatedInputControl
|
|
445
|
+
ref={rejectedEmail.ref}
|
|
446
|
+
label="Email"
|
|
447
|
+
type="email"
|
|
448
|
+
value={email}
|
|
449
|
+
onChange={(event) => setEmail(event.target.value)}
|
|
450
|
+
customValidity={rejectedEmail.validity}
|
|
451
|
+
/>
|
|
452
|
+
<Button type="submit">Send</Button>
|
|
453
|
+
</form>
|
|
454
|
+
)
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
- Pass what the words are about. In most forms that is the value of
|
|
458
|
+
the field, as the field holds it. Trim only what goes to the
|
|
459
|
+
server. When the answer also depends on another field, join both
|
|
460
|
+
into one string, such as `${kind}:${value}`, and send the same
|
|
461
|
+
string to `reject`.
|
|
462
|
+
- Hand `ref` to the field's `ref` and `validity` to its
|
|
463
|
+
`customValidity`. Both fit the WPDS validated fields. The hook finds
|
|
464
|
+
the form through the field.
|
|
465
|
+
- `reject(message, sent)` puts the words under the field and answers
|
|
466
|
+
`true`. It answers `false` when there are no words, when the field
|
|
467
|
+
changed while the send was on its way, or when the field is not on
|
|
468
|
+
the page inside a form. Say it another way then, in a toast on a
|
|
469
|
+
page.
|
|
470
|
+
- The focus moves to the first field that fails, and a screen reader
|
|
471
|
+
hears the server's words at once.
|
|
472
|
+
- The words go at the first edit. Typing the rejected value again does
|
|
473
|
+
not bring them back, so the reader may send it again.
|
|
474
|
+
- While the words stand, the browser holds the form back from
|
|
475
|
+
sending. A form with `noValidate` sends anyway, and the words are
|
|
476
|
+
spoken again when the server rejects the value again.
|
|
477
|
+
- Give each field its own hook. When one answer rejects several, the
|
|
478
|
+
focus goes to the first, and only one set of words is spoken.
|
|
479
|
+
- Call `reject` once the answer came, never while rendering, and never
|
|
480
|
+
in an answer that also leaves the screen.
|
|
481
|
+
- In a `FormDialog`, answer `{ close: false }` when `reject` answers
|
|
482
|
+
`true`, so the dialog stays open on the words, and
|
|
483
|
+
`{ error: words }` when it answers `false`.
|
|
484
|
+
|
|
485
|
+
[Announcements](./testing.md#announcements) shows how a test reads
|
|
486
|
+
what was spoken.
|
|
487
|
+
|
|
397
488
|
## Stylesheet helpers
|
|
398
489
|
|
|
399
490
|
`base.css` ships a few classes for layout jobs every admin screen
|
package/docs/testing.md
CHANGED
|
@@ -61,6 +61,12 @@ expect(getAnnouncement()).toBe('Draft saved')
|
|
|
61
61
|
`'assertive'` for urgent ones. `clearAnnouncements()` empties both,
|
|
62
62
|
for a test that must assert nothing was announced.
|
|
63
63
|
|
|
64
|
+
A frame given `shownPath` speaks the title of each new screen
|
|
65
|
+
assertively, so a test that moves to another screen and then reads
|
|
66
|
+
`'assertive'` meets that title, as
|
|
67
|
+
[what a screen reader hears when the screen changes](./design-system/frame.md#what-a-screen-reader-hears-when-the-screen-changes)
|
|
68
|
+
says.
|
|
69
|
+
|
|
64
70
|
## Rendering inside the host
|
|
65
71
|
|
|
66
72
|
`renderAdmin` renders a tree wrapped in `AdminRoot`, so components
|
|
@@ -69,6 +75,29 @@ accepts the usual testing library options plus the host theme
|
|
|
69
75
|
settings, and returns the normal render result. It supplies the
|
|
70
76
|
wrapper itself, so do not pass a `wrapper` of your own.
|
|
71
77
|
|
|
78
|
+
It also takes `writeTimeout`, the time limit `AdminRoot` gives a
|
|
79
|
+
busy dialog's write. Leave it out and the test has no limit, so a
|
|
80
|
+
write that never ends keeps its dialog busy for as long as the test
|
|
81
|
+
reads it. Pass a short limit to check what a dialog shows once its
|
|
82
|
+
write runs past it:
|
|
83
|
+
|
|
84
|
+
```tsx
|
|
85
|
+
import { renderAdmin } from '@gopherium/godmin/testing'
|
|
86
|
+
|
|
87
|
+
const SHORT_LIMIT = 20
|
|
88
|
+
|
|
89
|
+
test('says the server gave no answer when the rename never ends', async () => {
|
|
90
|
+
renderAdmin(<RenamePostDialog post={post} rename={() => new Promise(() => {})} />, { writeTimeout: SHORT_LIMIT })
|
|
91
|
+
await user.click(screen.getByRole('button', { name: 'Save' }))
|
|
92
|
+
expect(await screen.findByText('Could not get a valid response from the server.')).toBeVisible()
|
|
93
|
+
})
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The limit runs on the real clock, so keep it short. A test on fake
|
|
97
|
+
timers moves its clock past the limit instead.
|
|
98
|
+
[While a write runs](./design-system/dialogs.md#while-a-write-runs)
|
|
99
|
+
says what the dialog shows and frees.
|
|
100
|
+
|
|
72
101
|
## Simulating a small screen
|
|
73
102
|
|
|
74
103
|
jsdom evaluates no media queries, so a component asking "is this a
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gopherium/godmin",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.33.0",
|
|
4
4
|
"description": "The admin kit for Gopherium projects: host layer for React admin applications on the WordPress Design System.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
@@ -21,6 +21,9 @@
|
|
|
21
21
|
"docs",
|
|
22
22
|
"NOTICE"
|
|
23
23
|
],
|
|
24
|
+
"sideEffects": [
|
|
25
|
+
"**/*.css"
|
|
26
|
+
],
|
|
24
27
|
"exports": {
|
|
25
28
|
".": {
|
|
26
29
|
"types": "./dist/index.d.ts",
|
|
@@ -66,14 +69,15 @@
|
|
|
66
69
|
"peerDependencies": {
|
|
67
70
|
"@tanstack/react-router": "^1.170.44",
|
|
68
71
|
"@testing-library/react": "^16.3.2",
|
|
69
|
-
"@wordpress/a11y": ">=5.
|
|
70
|
-
"@wordpress/dataviews": ">=
|
|
71
|
-
"@wordpress/date": ">=6.
|
|
72
|
-
"@wordpress/i18n": ">=7.
|
|
73
|
-
"@wordpress/icons": ">=
|
|
74
|
-
"@wordpress/style-runtime": ">=0.
|
|
75
|
-
"@wordpress/theme": ">=
|
|
76
|
-
"@wordpress/
|
|
72
|
+
"@wordpress/a11y": ">=5.1.0 <6.0.0",
|
|
73
|
+
"@wordpress/dataviews": ">=22.0.0 <23.0.0",
|
|
74
|
+
"@wordpress/date": ">=6.1.0 <7.0.0",
|
|
75
|
+
"@wordpress/i18n": ">=7.1.0 <8.0.0",
|
|
76
|
+
"@wordpress/icons": ">=20.0.0 <21.0.0",
|
|
77
|
+
"@wordpress/style-runtime": ">=0.15.0 <0.16.0",
|
|
78
|
+
"@wordpress/theme": ">=4.0.0 <5.0.0",
|
|
79
|
+
"@wordpress/theme-build-tools": ">=1.0.0 <2.0.0",
|
|
80
|
+
"@wordpress/ui": ">=0.26.0 <0.27.0",
|
|
77
81
|
"react": "^19.2.0",
|
|
78
82
|
"stylelint": "^16 || ^17",
|
|
79
83
|
"vitest": "^4.1.10 || ^5.0.0"
|
|
@@ -91,6 +95,9 @@
|
|
|
91
95
|
"@wordpress/date": {
|
|
92
96
|
"optional": true
|
|
93
97
|
},
|
|
98
|
+
"@wordpress/theme-build-tools": {
|
|
99
|
+
"optional": true
|
|
100
|
+
},
|
|
94
101
|
"stylelint": {
|
|
95
102
|
"optional": true
|
|
96
103
|
},
|
|
@@ -112,16 +119,17 @@
|
|
|
112
119
|
"@vitejs/plugin-react": "^6.0.3",
|
|
113
120
|
"@vitest/browser-playwright": "^5.0.3",
|
|
114
121
|
"@vitest/coverage-v8": "^5.0.3",
|
|
115
|
-
"@wordpress/a11y": "5.
|
|
116
|
-
"@wordpress/components": "
|
|
117
|
-
"@wordpress/dataviews": "
|
|
118
|
-
"@wordpress/date": "6.
|
|
119
|
-
"@wordpress/element": "10.
|
|
120
|
-
"@wordpress/i18n": "7.
|
|
121
|
-
"@wordpress/icons": "
|
|
122
|
-
"@wordpress/style-runtime": "0.
|
|
123
|
-
"@wordpress/theme": "
|
|
124
|
-
"@wordpress/
|
|
122
|
+
"@wordpress/a11y": "5.1.0",
|
|
123
|
+
"@wordpress/components": "44.0.0",
|
|
124
|
+
"@wordpress/dataviews": "22.0.0",
|
|
125
|
+
"@wordpress/date": "6.1.0",
|
|
126
|
+
"@wordpress/element": "10.1.0",
|
|
127
|
+
"@wordpress/i18n": "7.1.0",
|
|
128
|
+
"@wordpress/icons": "20.0.0",
|
|
129
|
+
"@wordpress/style-runtime": "0.15.0",
|
|
130
|
+
"@wordpress/theme": "4.0.0",
|
|
131
|
+
"@wordpress/theme-build-tools": "1.0.0",
|
|
132
|
+
"@wordpress/ui": "0.26.0",
|
|
125
133
|
"eslint": "^10.7.0",
|
|
126
134
|
"eslint-plugin-jsdoc": "^63.2.0",
|
|
127
135
|
"eslint-plugin-sonarjs": "^4.2.0",
|