@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.
Files changed (68) hide show
  1. package/README.md +19 -9
  2. package/dist/admin-root.d.ts +4 -2
  3. package/dist/admin-root.js +6 -3
  4. package/dist/announcer-heading.d.ts +4 -0
  5. package/dist/announcer-heading.js +25 -0
  6. package/dist/base.css +36 -4
  7. package/dist/bulk-run.d.ts +2 -2
  8. package/dist/bulk-run.js +18 -2
  9. package/dist/confirm-dialog.d.ts +2 -2
  10. package/dist/confirm-dialog.js +3 -2
  11. package/dist/dialog-open.d.ts +16 -2
  12. package/dist/dialog-open.js +126 -5
  13. package/dist/drilldown-item.d.ts +5 -2
  14. package/dist/drilldown-item.js +14 -2
  15. package/dist/filter-offer.d.ts +5 -5
  16. package/dist/filter-offer.js +9 -9
  17. package/dist/focus-back.js +12 -2
  18. package/dist/form-dialog.d.ts +2 -2
  19. package/dist/form-dialog.js +3 -2
  20. package/dist/frame.d.ts +8 -4
  21. package/dist/frame.js +16 -6
  22. package/dist/index.d.ts +4 -2
  23. package/dist/index.js +3 -2
  24. package/dist/list-chrome/es-ES.d.ts +1 -1
  25. package/dist/list-chrome/es-ES.js +11 -8
  26. package/dist/list-chrome/fr-FR.d.ts +1 -1
  27. package/dist/list-chrome/fr-FR.js +9 -1
  28. package/dist/navigation-item.d.ts +4 -2
  29. package/dist/navigation-item.js +2 -2
  30. package/dist/navigation-screen.js +10 -3
  31. package/dist/navigation.js +5 -1
  32. package/dist/page.d.ts +3 -2
  33. package/dist/page.js +23 -4
  34. package/dist/rejected-field.d.ts +25 -0
  35. package/dist/rejected-field.js +121 -0
  36. package/dist/rename-dialog.d.ts +2 -2
  37. package/dist/rename-dialog.js +1 -1
  38. package/dist/route-not-found.d.ts +5 -0
  39. package/dist/route-not-found.js +12 -0
  40. package/dist/router.d.ts +8 -2
  41. package/dist/router.js +10 -2
  42. package/dist/screen-title.d.ts +52 -0
  43. package/dist/screen-title.js +165 -0
  44. package/dist/stylelint.d.ts +1 -4
  45. package/dist/stylelint.js +4 -7
  46. package/dist/testing.d.ts +2 -2
  47. package/dist/testing.js +3 -3
  48. package/dist/vite.js +1 -0
  49. package/docs/build-and-versioning.md +109 -4
  50. package/docs/design-system/accessibility.md +18 -9
  51. package/docs/design-system/color.md +1 -1
  52. package/docs/design-system/custom-properties.md +3 -3
  53. package/docs/design-system/dialogs.md +71 -9
  54. package/docs/design-system/frame.md +276 -0
  55. package/docs/design-system/layout.md +24 -16
  56. package/docs/design-system/lists.md +17 -11
  57. package/docs/design-system/loading.md +20 -12
  58. package/docs/design-system/motion.md +41 -47
  59. package/docs/design-system/overview.md +8 -3
  60. package/docs/design-system/radius-and-elevation.md +2 -2
  61. package/docs/design-system/record-pages.md +9 -1
  62. package/docs/design-system/toasts.md +7 -1
  63. package/docs/framing-an-application.md +77 -23
  64. package/docs/lists.md +80 -39
  65. package/docs/overview.md +9 -3
  66. package/docs/screens.md +94 -3
  67. package/docs/testing.md +29 -0
  68. 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 20 does:
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 select all box,
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
- 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
+ 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…', supportsBulk: true, callback: setDeleting }],
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 focus in
669
- either, such as on a row or the busy bulk button, would fall to the
670
- page, as it does in WordPress, where no control holds it and no ring
671
- shows. So once DataViews drew the list inert, the list region takes
672
- that focus in the same render, before the browser drops it, and here
673
- too the screen does not scroll. A focus anywhere else, such as in the
674
- search field or outside the list, stays where it is while the calls
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…', callback: ([post]) => setRenaming(post) }],
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) => write([renaming], (post) => renamePost(post.id, title), nameWords)}
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, as
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. godmin closes the dialog itself, so call nothing to close it.
1127
- `onClose` runs once the card has left, and that is where you take the
1128
- dialog away.
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
- The bar goes away once the selection clears, so the list region
1190
- takes the focus.
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 leaves the dialog open,
1237
- with no words, and its error goes on to your app.
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`, `routerDefaults`, `UnsavedChangesDialog`, the `canvas`, `Sidebar` and `capability` route static data |
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.32.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.0.0 <6.0.0",
70
- "@wordpress/dataviews": ">=21.0.0 <22.0.0",
71
- "@wordpress/date": ">=6.0.0 <7.0.0",
72
- "@wordpress/i18n": ">=7.0.0 <8.0.0",
73
- "@wordpress/icons": ">=19.0.0 <20.0.0",
74
- "@wordpress/style-runtime": ">=0.14.0 <0.15.0",
75
- "@wordpress/theme": ">=3.0.0 <4.0.0",
76
- "@wordpress/ui": ">=0.25.0 <0.26.0",
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.0.0",
116
- "@wordpress/components": "43.0.0",
117
- "@wordpress/dataviews": "21.0.0",
118
- "@wordpress/date": "6.0.0",
119
- "@wordpress/element": "10.0.0",
120
- "@wordpress/i18n": "7.0.0",
121
- "@wordpress/icons": "19.0.0",
122
- "@wordpress/style-runtime": "0.14.0",
123
- "@wordpress/theme": "3.0.0",
124
- "@wordpress/ui": "0.25.0",
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",