@gopherium/godmin 0.31.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 (88) hide show
  1. package/README.md +19 -10
  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 +42 -17
  7. package/dist/breakpoints.d.ts +1 -1
  8. package/dist/breakpoints.js +1 -1
  9. package/dist/bulk-run.d.ts +10 -0
  10. package/dist/bulk-run.js +76 -11
  11. package/dist/bulk.d.ts +3 -0
  12. package/dist/confirm-dialog.d.ts +14 -14
  13. package/dist/confirm-dialog.js +9 -28
  14. package/dist/dialog-open.d.ts +77 -0
  15. package/dist/dialog-open.js +231 -0
  16. package/dist/drilldown-item.d.ts +5 -2
  17. package/dist/drilldown-item.js +14 -2
  18. package/dist/filter-offer.d.ts +5 -5
  19. package/dist/filter-offer.js +9 -9
  20. package/dist/focus-back.js +12 -2
  21. package/dist/form-dialog.d.ts +14 -16
  22. package/dist/form-dialog.js +54 -13
  23. package/dist/frame.d.ts +8 -4
  24. package/dist/frame.js +16 -6
  25. package/dist/index.d.ts +13 -13
  26. package/dist/index.js +7 -8
  27. package/dist/list-chrome/es-ES.d.ts +1 -1
  28. package/dist/list-chrome/es-ES.js +11 -8
  29. package/dist/list-chrome/fr-FR.d.ts +1 -1
  30. package/dist/list-chrome/fr-FR.js +10 -1
  31. package/dist/list-run.js +25 -44
  32. package/dist/navigation-item.d.ts +4 -2
  33. package/dist/navigation-item.js +2 -2
  34. package/dist/navigation-screen.js +10 -3
  35. package/dist/navigation.js +5 -1
  36. package/dist/page.d.ts +3 -2
  37. package/dist/page.js +23 -4
  38. package/dist/rejected-field.d.ts +25 -0
  39. package/dist/rejected-field.js +121 -0
  40. package/dist/rename-dialog.d.ts +24 -0
  41. package/dist/rename-dialog.js +16 -0
  42. package/dist/route-not-found.d.ts +5 -0
  43. package/dist/route-not-found.js +12 -0
  44. package/dist/router.d.ts +10 -2
  45. package/dist/router.js +11 -2
  46. package/dist/screen-title.d.ts +52 -0
  47. package/dist/screen-title.js +165 -0
  48. package/dist/stylelint.d.ts +1 -4
  49. package/dist/stylelint.js +4 -7
  50. package/dist/testing.d.ts +2 -2
  51. package/dist/testing.js +3 -3
  52. package/dist/toaster.js +21 -2
  53. package/dist/unsaved-changes-dialog.d.ts +19 -0
  54. package/dist/unsaved-changes-dialog.js +33 -0
  55. package/dist/vite.js +1 -0
  56. package/docs/build-and-versioning.md +199 -11
  57. package/docs/design-system/accessibility.md +23 -12
  58. package/docs/design-system/color.md +1 -1
  59. package/docs/design-system/custom-properties.md +3 -3
  60. package/docs/design-system/dialogs.md +302 -0
  61. package/docs/design-system/frame.md +276 -0
  62. package/docs/design-system/layout.md +25 -17
  63. package/docs/design-system/lists.md +20 -12
  64. package/docs/design-system/loading.md +20 -12
  65. package/docs/design-system/motion.md +41 -46
  66. package/docs/design-system/overview.md +11 -3
  67. package/docs/design-system/radius-and-elevation.md +2 -2
  68. package/docs/design-system/record-pages.md +13 -3
  69. package/docs/design-system/toasts.md +18 -8
  70. package/docs/framing-an-application.md +77 -23
  71. package/docs/lists.md +372 -452
  72. package/docs/loading-and-feedback.md +11 -6
  73. package/docs/overview.md +9 -4
  74. package/docs/screens.md +104 -5
  75. package/docs/testing.md +40 -9
  76. package/package.json +27 -27
  77. package/dist/close-while-open.d.ts +0 -6
  78. package/dist/close-while-open.js +0 -21
  79. package/dist/confirm.d.ts +0 -21
  80. package/dist/confirm.js +0 -11
  81. package/dist/dialogs.d.ts +0 -4
  82. package/dist/dialogs.js +0 -3
  83. package/dist/form.d.ts +0 -28
  84. package/dist/form.js +0 -23
  85. package/dist/rename.d.ts +0 -20
  86. package/dist/rename.js +0 -14
  87. package/dist/run-confirm.d.ts +0 -22
  88. package/dist/run-confirm.js +0 -23
package/docs/lists.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: Lists with DataViews
3
- description: Hosting a WordPress DataViews list in a godmin page, its view in the address, paging it on the server, empty states, runs over the picked rows, confirmations, confirms outside a list, renames, forms in a dialog, the focus back on a row, bulk messages, uploads, its Spanish chrome, its dates, and the table look for lists that stay custom.
3
+ description: Hosting a WordPress DataViews list in a godmin page, its view in the address, paging it on the server, empty states, runs over the picked rows, confirms, renames, forms in a dialog, the focus back on a row, bulk messages, uploads, its Spanish chrome, its dates, and the table look for lists that stay custom.
4
4
  ---
5
5
 
6
6
  DataViews is the WordPress list component. It draws the search box,
@@ -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
 
@@ -607,7 +609,7 @@ the row that took its place, unless that control is a primary action.
607
609
  things for you:
608
610
 
609
611
  ```tsx
610
- import { Page, RunConfirm, useBulkRun, useListRun } from '@gopherium/godmin'
612
+ import { ConfirmDialog, Page, useBulkRun, useListRun } from '@gopherium/godmin'
611
613
 
612
614
  function OrdersScreen() {
613
615
  const client = useQueryClient()
@@ -615,37 +617,35 @@ function OrdersScreen() {
615
617
  const { run, region } = useListRun('orders', list.onChangeSelection)
616
618
  const refresh = useCallback(() => client.invalidateQueries({ queryKey: ['orders'] }), [client])
617
619
  const bulk = useBulkRun<Order>(run, refresh)
620
+ const [deleting, setDeleting] = useState<Order[]>()
618
621
  const actions = useMemo<Action<Order>[]>(
619
- () => [
620
- {
621
- id: 'delete',
622
- label: 'Delete…',
623
- supportsBulk: true,
624
- hideModalHeader: true,
625
- modalFocusOnMount: 'firstContentElement',
626
- RenderModal: (props) => (
627
- <RunConfirm {...props} confirmLabel="Delete" cancelLabel="Cancel" run={(orders) => bulk(orders, (order) => deleteOrder(order.id), words)}>
628
- Delete these orders for good?
629
- </RunConfirm>
630
- ),
631
- },
632
- ],
633
- [bulk],
622
+ () => [{ id: 'delete', label: 'Delete', supportsBulk: true, callback: setDeleting }],
623
+ [],
634
624
  )
635
625
  return (
636
626
  <Page title="Orders" list listLabel="Orders" listRef={region}>
637
627
  <DataViews {...props} actions={actions} />
628
+ {deleting ? (
629
+ <ConfirmDialog
630
+ intent="irreversible"
631
+ title={deleting.length === 1 ? `Delete "${deleting[0].name}"?` : `Delete ${deleting.length} orders?`}
632
+ description="This action cannot be undone."
633
+ confirmLabel="Delete"
634
+ cancelLabel="Cancel"
635
+ onConfirm={(signal) => bulk(deleting, (order) => deleteOrder(order.id, signal), words)}
636
+ onClose={() => setDeleting(undefined)}
637
+ />
638
+ ) : null}
638
639
  </Page>
639
640
  )
640
641
  }
641
642
  ```
642
643
 
643
- Build the actions once with `useMemo`, as the example does. A run
644
- renders the screen again, and DataViews draws the confirm of a bulk
645
- action from the actions you pass. A new `RenderModal` would start the
646
- confirm over in the middle of the run: Cancel would work again, and
647
- the confirm button could start a second run. When your words or your
648
- calls change with the screen, list them in the dependencies too.
644
+ The action's `callback` stores the rows to ask about, and the screen
645
+ draws the confirm from them, as
646
+ [confirming an action](#confirming-an-action) explains. DataViews
647
+ calls the same `callback` from a row's actions menu, its primary
648
+ action button and the bulk bar.
649
649
 
650
650
  `useListRun` keeps track of the runs on the list. Once a run moved a
651
651
  row, the list region takes the focus, so a keyboard reader is not
@@ -667,14 +667,14 @@ ends. Pass it to DataViews beside the list's own loading state, as
667
667
  reload as WordPress does
668
668
  [after a write of your own](./design-system/lists.md#after-a-write-of-your-own).
669
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.
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.
678
678
  Pass `refreshing` to DataViews in the render that reads it, never
679
679
  through an effect, so the region can take the focus in time.
680
680
 
@@ -759,27 +759,31 @@ dialog they opened on another row. So the list takes the focus only
759
759
  while the reader is still with the run:
760
760
 
761
761
  - the focus fell to the page,
762
+ - the focus sits on the toast region itself, where a toast leaves it
763
+ as it goes, such as after the reader pressed Undo in it,
762
764
  - the focus sits inside the list,
763
765
  - the focus sits in the dialog the run started in,
764
- - or that dialog closed before the run ended, the focus still sits
765
- where it first went outside that dialog while the dialog was open,
766
- and no dialog holds the focus. A confirm that closes at once gives
767
- the focus back to the button that opened it, and the list then
768
- takes the focus from that button.
769
-
770
- A dialog opened since keeps the focus, so typing still lands in it
771
- and Escape still closes it. A reader who moved on to another control
772
- outside the list keeps their place: during a run started outside
773
- every dialog, while the dialog the run started in is still open, and
774
- after that dialog gave the focus back or closed with nowhere to give
775
- it. One move is the exception. A dialog that lets the focus out,
776
- unlike a WordPress modal, can be left for another control while it
777
- is still open. That control then counts as where the dialog gave the
778
- focus back, since the focus moves the same way in both cases. So when
779
- the dialog closes and the run ends with the focus still there, the
780
- list takes the focus from it. Every list run does this, with nothing
781
- to add to your screen. This needs godmin 0.27.0 or later. Before it,
782
- the list took the focus wherever the focus sat.
766
+ - or that dialog left the page before the run ended, and the focus
767
+ sits on the control that opened it. A confirm that closes at once
768
+ gives the focus back to the button that opened it, and the list then
769
+ takes the focus from that button. This needs the list on the page as
770
+ the dialog opens, and the dialog taking the focus straight from that
771
+ button. Otherwise the focus stays on the button.
772
+
773
+ A dialog opened since keeps the focus, when it draws in its default
774
+ portal as godmin's dialogs do, so typing still lands in it and Escape
775
+ still closes it. The same goes for a dialog whose control
776
+ opened the dialog the run started in. A reader who moved on to
777
+ another control outside the list keeps their place: during a run
778
+ started outside every dialog, while the dialog the run started in is
779
+ still open, and after that dialog left the page. Every list run does
780
+ this, with nothing to add to your screen. This needs godmin 0.27.0 or
781
+ later. Before it, the list took the focus wherever the focus sat.
782
+ Three cases need godmin 0.32.0 or later. Before it, the focus stayed
783
+ on a control outside the list that opened a WPDS dialog, the list took
784
+ the focus from a control the reader moved to out of a dialog that then
785
+ closed, and a run started from a toast left the focus on the toast
786
+ region.
783
787
 
784
788
  `focusInDialog()` tells whether a dialog holds the focus, for a write
785
789
  you finish yourself outside a run. It also needs godmin 0.27.0 or
@@ -817,18 +821,33 @@ state shows the failure, as on any later load. The run resolved
817
821
  before it, so it does not reject. A test that awaits the run and then
818
822
  reads the reloaded rows waits for the rows instead.
819
823
 
820
- `RunConfirm` is the body of the confirm modal. It runs the action
821
- when the reader confirms, shows the confirm button busy and keeps
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.
824
+ Give your words an `undo`, and the done toast offers it once every row
825
+ worked. `undo` gets the rows the run was given and answers the toast's
826
+ action, its `label` and its `onAct`. When any row failed, the toast
827
+ holds your `failed` words and offers nothing:
828
+
829
+ ```tsx
830
+ const restoreWords: BulkWords<Post> = {
831
+ done: (count, only) => (only === undefined ? `${count} posts restored.` : `"${only.title}" restored.`),
832
+ failed: (failures) => `Could not restore ${failures.length} posts.`,
833
+ }
834
+
835
+ callback: (posts) =>
836
+ bulk(posts, (post) => trashPost(post.id), {
837
+ ...trashWords,
838
+ undo: (done) => ({ label: 'Undo', onAct: () => void bulk(done, (post) => restorePost(post.id), restoreWords) }),
839
+ })
840
+ ```
841
+
842
+ Undo is then a run of its own, so the list reloads as after any run.
843
+ A press on Undo leaves the focus on the toast region as the toast
844
+ goes, and the list takes it from there once a row moved. This needs
845
+ godmin 0.32.0 or later.
846
+
847
+ A confirm whose `onConfirm` returns the run stays open until the run
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.
832
851
 
833
852
  `listLabel` and `listRef` make the list a region with a name, which
834
853
  a screen reader announces, and give the focus its target. The region
@@ -851,190 +870,128 @@ takes the focus only if the focus fell to the page or sits inside the
851
870
  list. While the focus is still on your button, or on another control
852
871
  the reader moved to, it stays there. When your button opens a
853
872
  `ConfirmDialog` first, as Empty Trash does, call `run.onStart()`
854
- inside `onConfirm`, as [a confirm outside a list](#a-confirm-outside-a-list)
873
+ inside `onConfirm`, as [confirming an action](#confirming-an-action)
855
874
  explains. The list then takes the focus once the run moved a row,
856
875
  even after the dialog closed, while the focus is still on the button
857
- the dialog gave it back to. A reader who moved to another control by
858
- then keeps their place. This needs godmin 0.27.0 or later.
876
+ that opened it. A reader who moved to another control by then keeps
877
+ their place. This needs godmin 0.27.0 or later.
859
878
 
860
879
  ## Confirming an action
861
880
 
862
- An action that cannot be undone asks first. DataViews opens a modal
863
- for an action that has a `RenderModal`, and `RunConfirm` is the body
864
- of that modal for a
865
- [run over the picked rows](#running-an-action-over-the-picked-rows):
866
-
867
- ```tsx
868
- const trash = useMemo<Action<Post>>(
869
- () => ({
870
- id: 'move-to-trash',
871
- label: 'Move to trash',
872
- supportsBulk: true,
873
- hideModalHeader: true,
874
- modalFocusOnMount: 'firstContentElement',
875
- RenderModal: (props) => (
876
- <RunConfirm {...props} confirmLabel="Move to trash" cancelLabel="Cancel" run={(posts) => bulk(posts, (post) => trashPost(post.id), words)}>
877
- Move the picked posts to the trash?
878
- </RunConfirm>
879
- ),
880
- }),
881
- [bulk],
882
- )
883
- ```
884
-
885
- A confirm that removes something, such as Move to trash or Delete
886
- permanently, has no header, as in WordPress. Give the action
887
- `hideModalHeader: true`, and the question is the only text. A plain
888
- confirm, such as making an item the default, keeps its title through
889
- `modalHeader`. Leave `modalSize` out, so the modal takes the DataViews
890
- width, 560px, as WordPress list confirms do.
891
- `modalFocusOnMount: 'firstContentElement'` puts the focus on Cancel.
892
- Cancel is borderless text in your accent colour, left of the confirm
893
- button.
894
-
895
- For a run you write yourself, `ConfirmBody` is the same body without
896
- the run:
881
+ An action that cannot be undone asks first. `ConfirmDialog` asks the
882
+ question, on the alert dialog of the design system. The same dialog
883
+ asks for a row action, a bulk action and a button outside any list,
884
+ such as Delete permanently in an editor or Empty Trash above a list.
885
+ Render it only while you ask, so each new ask starts fresh:
897
886
 
898
887
  ```tsx
899
- import { ConfirmBody, runEach, useCloseWhileOpen, useToaster } from '@gopherium/godmin'
900
-
901
- function TrashModal({ items, closeModal }: RenderModalProps<Post>) {
902
- const toaster = useToaster()
903
- const close = useCloseWhileOpen(closeModal)
904
- const [busy, setBusy] = useState(false)
905
- const confirm = async () => {
906
- setBusy(true)
907
- const outcome = await runEach(items, (post) => trashPost(post.id))
908
- const moved = outcome.failures.length === 0
909
- toaster.show(moved ? 'Post moved to the trash.' : 'The post could not be moved to the trash.')
910
- close()
911
- }
912
- return (
913
- <ConfirmBody
914
- confirmLabel="Move to trash"
915
- cancelLabel="Cancel"
916
- busy={busy}
917
- onConfirm={() => void confirm()}
918
- onCancel={closeModal}
919
- >
920
- Move the post to the trash?
921
- </ConfirmBody>
922
- )
923
- }
924
- ```
925
-
926
- It draws the question, then Cancel as accent text and the solid
927
- confirm button at the end, 20px under the question. While `busy`,
928
- the confirm button shows a spinner and ignores a second press, and
929
- Cancel closes nothing.
930
-
931
- The body never shows a failure. Close the modal once the write ends,
932
- whether it worked or not, and say how it went in a toast, as the
933
- WordPress list confirms do.
934
-
935
- Close it through `useCloseWhileOpen(closeModal)`, as the example
936
- does. DataViews keeps one dialog for a row's actions menu and another
937
- for its primary action buttons. Every dialog that opens in one of
938
- them gets the same `closeModal`, so a write that ends after the reader
939
- dismissed your modal and opened another one in its place would shut
940
- the new one. The close `useCloseWhileOpen` returns does nothing once
941
- your modal left the screen. `RunConfirm` closes this way already.
942
- This needs godmin 0.27.0 or later.
943
-
944
- ## A confirm outside a list
945
-
946
- Some confirms open from a button outside any list, such as Move to
947
- trash in an editor or Empty Trash above a list. `ConfirmDialog` asks
948
- those, as WordPress dialogs do. A confirm above a list can also start
949
- a [list run](#running-an-action-over-the-picked-rows), as Empty Trash
950
- does. This section says where the focus goes once that run ends.
951
- Here the dialog asks before Move to trash in an editor:
952
-
953
- ```tsx
954
- import { useToaster } from '@gopherium/godmin'
955
- import { ConfirmDialog } from '@gopherium/godmin/dialogs'
888
+ import { ConfirmDialog, useToaster } from '@gopherium/godmin'
956
889
  import { Button } from '@wordpress/ui'
957
890
 
958
- function TrashButton({ post }: { post: Post }) {
891
+ function DeleteButton({ post }: { post: Post }) {
959
892
  const toaster = useToaster()
960
893
  const [asking, setAsking] = useState(false)
961
- const [trashing, setTrashing] = useState(false)
962
- const trash = () => {
963
- setTrashing(true)
964
- trashPost(post.id)
965
- .then(() => toaster.show('Post moved to the trash.'))
894
+ const [deleting, setDeleting] = useState(false)
895
+ const remove = () => {
896
+ setDeleting(true)
897
+ deletePost(post.id)
898
+ .then(() => toaster.show(`"${post.title}" deleted.`))
966
899
  .catch((failure) => toaster.show(failure.message))
967
- .finally(() => setTrashing(false))
900
+ .finally(() => setDeleting(false))
968
901
  }
969
902
  return (
970
903
  <>
971
- <Button variant="outline" loading={trashing} onClick={() => setAsking(true)}>Move to trash</Button>
904
+ <Button variant="outline" loading={deleting} onClick={() => setAsking(true)}>Delete permanently</Button>
972
905
  {asking ? (
973
- <ConfirmDialog size="small" confirmLabel="Move to trash" cancelLabel="Cancel" onConfirm={trash} onClose={() => setAsking(false)}>
974
- Move "Hello" to the trash?
975
- </ConfirmDialog>
906
+ <ConfirmDialog
907
+ intent="irreversible"
908
+ title={`Delete "${post.title}"?`}
909
+ description="This will permanently delete this post. This action cannot be undone."
910
+ confirmLabel="Delete permanently"
911
+ cancelLabel="Cancel"
912
+ onConfirm={remove}
913
+ onClose={() => setAsking(false)}
914
+ />
976
915
  ) : null}
977
916
  </>
978
917
  )
979
918
  }
980
919
  ```
981
920
 
982
- It draws the WordPress modal: a card from 600px up, and a sheet
983
- along the bottom of the screen below 600px, the width
984
- `SHEET_BREAKPOINT` names. `size` picks the card width. `small` draws
985
- it 400px wide, as WordPress does for the Move to trash button in its
986
- editor sidebar, so the example asks for it. `medium`, the default,
987
- is the 560px card WordPress opens for the Trash action of a list or
988
- of an actions menu. Both sizes are the same sheet on a phone.
921
+ `title` is the question, and it names the dialog. `description` says
922
+ what will happen, as plain text. `intent="irreversible"` draws the
923
+ confirm button red, for an action that cannot be undone. `confirmLabel`
924
+ and `cancelLabel` name the two buttons. Every word comes from you, so
925
+ pass them through your translations.
926
+ [The words](./design-system/dialogs.md#the-words) says what to write.
989
927
 
990
- Leave `title` out for a confirm that removes something, so the
991
- question is the only text. Give a plain confirm a `title`, and it
992
- gets a header with a close button. Cancel has the focus when the
993
- dialog opens.
928
+ For a row action or a bulk action, give the action a `callback` that
929
+ stores the rows, and render the dialog from your screen, as
930
+ [running an action over the picked rows](#running-an-action-over-the-picked-rows)
931
+ shows. Name one row in the title and count several.
994
932
 
995
- What `onConfirm` returns decides when the dialog goes:
933
+ What `onConfirm` does decides when the dialog goes, as
934
+ [when a dialog closes](./design-system/dialogs.md#when-a-dialog-closes)
935
+ shows:
996
936
 
997
937
  - Return nothing, and the dialog closes at once while your write
998
- runs. WordPress does this for a confirm that opens from a button or
999
- a screen menu, such as Move to trash in its editor or Empty Trash
1000
- above a list. Show the write as busy on the button that opened the
1001
- dialog, as the example does with `loading`. Make `onConfirm` a
1002
- plain function, as `trash` is. An `async` function always returns
1003
- a promise, so the dialog would stay open until the write ends. When
1004
- the write is a list run, call `run.onStart()` inside `onConfirm`,
1005
- while the dialog still holds the focus. The dialog gives the focus
1006
- back to its button as it closes, and the list takes the focus once
1007
- the run moved a row, while the focus is still on that button. A
1008
- reader who moved to another control or opened another dialog by
1009
- then keeps their place.
938
+ runs. Do this for a write that can take long, such as Empty Trash.
939
+ Show the write as busy on the button that opened the dialog, as the
940
+ example does with `loading`. Make `onConfirm` a plain function, as
941
+ `remove` is. An `async` function always returns a promise, so the
942
+ dialog would stay open until the write ends. When the write is a
943
+ list run, call `run.onStart()` inside `onConfirm`, while the dialog
944
+ still holds the focus. The dialog gives the focus back to its button
945
+ once it has gone, and the list takes the focus once the run moved a
946
+ row, while the focus is still on that button. A reader who moved to
947
+ another control or opened another dialog by then keeps their place.
948
+ No time limit applies, since the dialog no longer waits.
1010
949
  - Return the write's promise, and the dialog stays open while it
1011
- runs. The confirm button shows a spinner and Cancel greys out. When
1012
- the promise ends, worked or failed, the dialog closes. WordPress
1013
- does this for a confirm that opens from a row's own menu, so use it
1014
- for the rows of a list you draw yourself, outside DataViews:
950
+ runs, with a spinner on its confirm button. When the promise ends,
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.
956
+ - Answer `{ error: 'words' }`, at once or as the promise ends, and the
957
+ dialog stays open and shows the words inside. Do this when trying
958
+ again is the next step. Answer `{ close: false }` to stay open and
959
+ say nothing. `DialogAnswer` from `@gopherium/godmin` types both
960
+ answers.
961
+ - A handler that throws, or a promise that rejects, keeps the dialog
962
+ open and hands the error on to your app, as
963
+ [a failure from a dialog](#a-failure-from-a-dialog) explains.
964
+
965
+ Here a plain confirm stays open after a failure, so the reader can
966
+ try again:
1015
967
 
1016
968
  ```tsx
1017
969
  <ConfirmDialog
1018
- confirmLabel="Delete"
970
+ title="Make this the default?"
971
+ description="New items will use it."
972
+ confirmLabel="Make default"
1019
973
  cancelLabel="Cancel"
1020
- onConfirm={() => deleteGroup(group.id).catch((failure) => toaster.show(failure.message))}
974
+ onConfirm={(signal) =>
975
+ makeDefault(item.id, signal).then(
976
+ () => toaster.show(`"${item.name}" is now the default.`),
977
+ (failure: Error) => ({ error: failure.message }),
978
+ )
979
+ }
1021
980
  onClose={() => setAsking(false)}
1022
- >
1023
- Delete "{group.name}"?
1024
- </ConfirmDialog>
981
+ />
1025
982
  ```
1026
983
 
1027
- Either way, show a failure in a toast. The dialog never shows one
1028
- inside. Put the `.catch` inside `onConfirm` and return what it
1029
- answers, as [a failure from a dialog](#a-failure-from-a-dialog)
1030
- explains.
984
+ A dialog that closes says how its write went in a toast.
985
+ [A failed write](./design-system/dialogs.md#a-failed-write) says
986
+ where each failure shows.
1031
987
 
1032
- The dialog calls `onClose` after Cancel, Escape, a click outside it,
1033
- the close button of a titled confirm, or a confirm that finished.
1034
- Escape, a click outside it and its close button work at any time,
1035
- even while the write runs. The write then goes on, and `onClose`
1036
- still runs only once. When the dialog goes away, the focus goes back
1037
- to the button that opened it, unless your action already moved it.
988
+ The dialog calls `onClose` once its card has left the page, after
989
+ Cancel, Escape or a confirm that finished, and only once. Take the
990
+ dialog away there, as the examples do. While the write runs, Cancel
991
+ and Escape close nothing, as
992
+ [while a write runs](./design-system/dialogs.md#while-a-write-runs)
993
+ says. When the dialog goes away, the focus goes back to the control
994
+ that opened it, unless your action already moved it.
1038
995
 
1039
996
  A list run started in `onConfirm` moves the focus to the list once it
1040
997
  moved a row, whether the dialog stayed open until then or closed
@@ -1045,211 +1002,104 @@ the focus is still there. Either way, a reader who moved to another
1045
1002
  control or opened another dialog since keeps their place. This needs
1046
1003
  godmin 0.27.0 or later.
1047
1004
 
1048
- Render the dialog only while you ask, as the example does. Each new
1049
- ask then starts fresh.
1050
-
1051
- `ConfirmDialog` comes from its own entry, `@gopherium/godmin/dialogs`,
1052
- because it needs `@wordpress/components`, a large package the main
1053
- entry never loads. Install `@wordpress/components` and load its
1054
- stylesheet once, `@wordpress/components/build-style/style.css`, as
1055
- DataViews already asks.
1056
-
1057
1005
  ## Renaming an item
1058
1006
 
1059
- A rename asks for one new name. `RenameBody` is the body of that
1060
- modal: a field that starts with the current name, an accent text
1061
- Cancel and the submit button:
1007
+ A rename asks for one new name. `RenameDialog` asks it on a form
1008
+ dialog: a field that starts with the current name, Cancel and Save.
1009
+ Give the action a `callback` that stores the row, and render the
1010
+ dialog from your screen:
1062
1011
 
1063
1012
  ```tsx
1064
- import { RenameBody, markLatest, useToaster, useUnsavedText } from '@gopherium/godmin'
1013
+ import { Page, RenameDialog, useDialogRun, useListRun } from '@gopherium/godmin'
1014
+ import type { BulkWords } from '@gopherium/godmin'
1065
1015
  import type { Action } from '@wordpress/dataviews'
1066
1016
 
1067
- function useRenameAction(): Action<Post> {
1068
- const toaster = useToaster()
1069
- const renames = useUnsavedText()
1070
- return useMemo<Action<Post>>(
1071
- () => ({
1072
- id: 'rename',
1073
- label: 'Rename',
1074
- modalHeader: 'Rename',
1075
- modalFocusOnMount: 'firstContentElement',
1076
- RenderModal: ({ items: [post], closeModal }) => (
1077
- <RenameBody
1078
- name={renames.get(post.id) ?? post.title}
1017
+ const nameWords: BulkWords<Post> = {
1018
+ done: () => 'Name updated.',
1019
+ failed: ([{ error }]) => `Could not save the name. ${(error as Error).message}`,
1020
+ }
1021
+
1022
+ function PostsScreen() {
1023
+ const { run, region } = useListRun('posts', list.onChangeSelection)
1024
+ const write = useDialogRun<Post>(run, refresh)
1025
+ const [renaming, setRenaming] = useState<Post>()
1026
+ const actions = useMemo<Action<Post>[]>(
1027
+ () => [{ id: 'rename', label: 'Rename', callback: ([post]) => setRenaming(post) }],
1028
+ [],
1029
+ )
1030
+ return (
1031
+ <Page title="Posts" list listLabel="Posts" listRef={region}>
1032
+ <DataViews {...props} actions={actions} />
1033
+ {renaming ? (
1034
+ <RenameDialog
1035
+ title="Rename"
1036
+ name={renaming.title}
1079
1037
  fieldLabel="Name"
1080
1038
  submitLabel="Save"
1081
1039
  cancelLabel="Cancel"
1082
- onSubmit={(title) => {
1083
- closeModal?.()
1084
- renames.delete(post.id)
1085
- const stillLatest = markLatest(renames, post.id)
1086
- renamePost(post.id, title)
1087
- .then(() => toaster.show('Name updated.'))
1088
- .catch((failure) => {
1089
- if (stillLatest()) {
1090
- renames.set(post.id, title)
1091
- }
1092
- toaster.show(failure.message)
1093
- })
1094
- }}
1095
- onCancel={closeModal}
1040
+ onSubmit={(title, signal) =>
1041
+ write([renaming], (post) => renamePost(post.id, title, signal), nameWords, signal)
1042
+ }
1043
+ onClose={() => setRenaming(undefined)}
1096
1044
  />
1097
- ),
1098
- }),
1099
- [toaster, renames],
1100
- )
1101
- }
1102
- ```
1103
-
1104
- Leave `modalSize` out, so the rename takes the DataViews width, 560px,
1105
- as the WordPress rename does. WordPress titles it Rename and labels
1106
- its button Save, and the example does the same.
1107
-
1108
- The submit button is off only while the field is blank. A name left
1109
- as it was can still be sent, as in the WordPress rename. Enter in the
1110
- field does what the submit button does. `onSubmit` gets the name
1111
- exactly as typed, and your code does the write and the toast.
1112
-
1113
- A rename closes the moment the reader presses Save, before its write,
1114
- as WordPress closes its rename. So the body is never busy and never
1115
- shows a failure. When the write fails, say so in a toast and keep
1116
- what the reader typed. `name` is the text the field starts with, so
1117
- hand that text back on the next open. The reader then finds the name
1118
- they typed and can try once more.
1119
-
1120
- `useUnsavedText` holds that text, by item id, for as long as the
1121
- screen stays. Keep it in the hook that builds the action, never in the
1122
- modal, which goes the moment the reader saves. Clear the item's text
1123
- before each write, so a save that works leaves nothing behind.
1124
- `markLatest` marks the write as the latest one sent to the item and
1125
- returns a check. Keep the failed text only while the check holds, so
1126
- an earlier save that fails late never overwrites what a later save
1127
- sent, and a later save that works is never undone. The store holds
1128
- any value, so a form with several fields keeps them all, as
1129
- `useUnsavedText<Fields>()`. This needs godmin 0.24.1, or 0.27.0 or
1130
- later. 0.25.0 and 0.26.0 do not have it.
1131
-
1132
- Every word comes from you: the field label, both button labels and
1133
- the toasts. Pass them through your translations.
1134
-
1135
- `modalFocusOnMount: 'firstContentElement'` puts the cursor in the
1136
- field when the modal opens, as the WordPress rename does. Without it,
1137
- the modal window itself takes the focus, and the reader has to press
1138
- Tab to reach the field.
1139
-
1140
- ## A form in a row action
1141
-
1142
- Some row actions ask for more than a yes or a name, such as a copy
1143
- with a title of its own or a new role for a user. `FormBody` is the
1144
- body of that modal: the fields you give it, an accent text Cancel and
1145
- the submit button. It is a real form, so Enter in a field sends it:
1146
-
1147
- ```tsx
1148
- import { FormBody, useCloseWhileOpen, useToaster } from '@gopherium/godmin'
1149
- import type { Action, RenderModalProps } from '@wordpress/dataviews'
1150
- import { InputControl } from '@wordpress/ui'
1151
-
1152
- function DuplicateModal({ items: [post], closeModal }: RenderModalProps<Post>) {
1153
- const toaster = useToaster()
1154
- const close = useCloseWhileOpen(closeModal)
1155
- const [title, setTitle] = useState(`${post.title} (Copy)`)
1156
- const [busy, setBusy] = useState(false)
1157
- const duplicate = () => {
1158
- setBusy(true)
1159
- duplicatePost(post.id, title)
1160
- .then(() => toaster.show(`"${title}" created.`))
1161
- .catch((failure) => toaster.show(failure.message))
1162
- .finally(close)
1163
- }
1164
- return (
1165
- <FormBody
1166
- kind="copy"
1167
- submitLabel="Duplicate"
1168
- cancelLabel="Cancel"
1169
- canSubmit={title.trim() !== ''}
1170
- busy={busy}
1171
- onSubmit={duplicate}
1172
- onCancel={closeModal}
1173
- >
1174
- <InputControl label="Title" value={title} onChange={(event) => setTitle(event.target.value)} />
1175
- </FormBody>
1045
+ ) : null}
1046
+ </Page>
1176
1047
  )
1177
1048
  }
1178
-
1179
- const duplicateAction: Action<Post> = {
1180
- id: 'duplicate',
1181
- label: 'Duplicate',
1182
- modalHeader: 'Duplicate',
1183
- modalFocusOnMount: 'firstContentElement',
1184
- RenderModal: DuplicateModal,
1185
- }
1186
1049
  ```
1187
1050
 
1188
- `submitLabel` and `cancelLabel` name the two buttons. `onSubmit` runs
1189
- from the submit button or from Enter, and `onCancel` from Cancel.
1190
- `canSubmit` turns the submit button off, for example while a needed
1191
- field is empty. The button stays reachable with Tab, so a keyboard
1192
- reader still finds it. While `busy`, the submit button shows a
1193
- spinner and a second send does nothing. Cancel stays live the whole
1194
- time, as in WordPress forms.
1195
-
1196
- `kind` says what the form does, and sets the space above the buttons
1197
- as WordPress spaces it:
1198
-
1199
- | `kind` | For | Space above the buttons |
1200
- | --- | --- | --- |
1201
- | `edit`, the default | A change to one item, such as a new role | 20px |
1202
- | `copy` | A copy of an item, such as Duplicate | 12px |
1203
- | `create` | Something new | 16px |
1204
-
1205
- When the modal closes depends on the action, as in WordPress:
1206
-
1207
- - A change to one item closes the moment the reader sends it, before
1208
- its write, like the [rename](#renaming-an-item). Call `closeModal`
1209
- first, then write.
1210
- - A copy, something new, or a change to several items stays open with
1211
- its button busy, then closes when the write ends, worked or failed.
1212
- Set `busy` while it runs, and close it through
1213
- `useCloseWhileOpen(closeModal)`, as the example does.
1214
- [Confirming an action](#confirming-an-action) says why. This needs
1215
- godmin 0.27.0 or later.
1216
-
1217
- Either way, a failure goes in a toast. `FormBody` never shows one. To
1218
- give the reader back what they typed after a failure, keep it in a
1219
- `useUnsavedText` store outside the modal and pass it in as the first
1220
- value of the fields, as the rename does.
1221
-
1222
- Leave `modalSize` out, so the form takes the DataViews width, 560px,
1223
- as WordPress row forms do. `modalFocusOnMount: 'firstContentElement'`
1224
- puts the cursor in the first field.
1051
+ WordPress titles it Rename and labels its button Save, and the
1052
+ example does the same. Every word comes from you: the title, the
1053
+ field label, both button labels and the toasts. Pass them through
1054
+ your translations.
1055
+
1056
+ Save stays on, even with the field blank, as in the WordPress rename.
1057
+ The field is required and must hold more than spaces, so the browser
1058
+ refuses a blank name in its own words and sends nothing. A name left
1059
+ as it was still sends. Enter in the field does what Save does.
1060
+ `onSubmit` gets the name exactly as typed, then the dialog's signal.
1061
+
1062
+ `onSubmit` answers the dialog as the one of
1063
+ [a form dialog](#a-form-dialog) does. Through `useDialogRun`, the
1064
+ dialog stays open while the write runs, with a spinner on Save and
1065
+ the field read-only. It closes when the write works, and stays with
1066
+ the words of `failed` and the typed name when it fails or runs past
1067
+ the time limit, as
1068
+ [a failure from a dialog](#a-failure-from-a-dialog) shows.
1069
+
1070
+ A rename that closes at once, by returning nothing from `onSubmit`
1071
+ and writing after, loses the typed name when the write fails. Keep it
1072
+ in a `useUnsavedText` store by item id, hand it back as `name` on the
1073
+ next open, and check `markLatest` so an earlier save that fails late
1074
+ never overwrites a later one.
1225
1075
 
1226
1076
  ## A form dialog
1227
1077
 
1228
1078
  Some forms open from a button outside any list, such as Add Project
1229
1079
  in a page header. `FormDialog` asks those, as WordPress opens its Add
1230
- Page dialog: a card with a title and a close button, the cursor in
1231
- the first field, and the same form as `FormBody` inside:
1080
+ Page dialog: a card with a title, a close icon, the cursor in the
1081
+ first field, and Cancel and the send button at the end:
1232
1082
 
1233
1083
  ```tsx
1234
- import { useToaster } from '@gopherium/godmin'
1235
- import { FormDialog } from '@gopherium/godmin/dialogs'
1084
+ import { FormDialog, useToaster } from '@gopherium/godmin'
1236
1085
  import { Button, InputControl } from '@wordpress/ui'
1237
1086
 
1238
1087
  function AddProjectDialog({ onClose }: { onClose: () => void }) {
1239
1088
  const toaster = useToaster()
1240
1089
  const [name, setName] = useState('')
1241
- const add = async () => {
1242
- await addProject(name)
1243
- toaster.show(`"${name}" added.`)
1244
- onClose()
1245
- }
1246
1090
  return (
1247
1091
  <FormDialog
1248
1092
  title="Add Project"
1093
+ description="A project groups your orders."
1249
1094
  submitLabel="Add"
1250
1095
  cancelLabel="Cancel"
1251
1096
  canSubmit={name.trim() !== ''}
1252
- onSubmit={() => add().catch((failure) => toaster.show(failure.message))}
1097
+ onSubmit={(signal) =>
1098
+ addProject(name, signal).then(
1099
+ () => void toaster.show(`"${name}" added.`),
1100
+ (failure: Error) => ({ error: `Could not add the project. ${failure.message}` }),
1101
+ )
1102
+ }
1253
1103
  onClose={onClose}
1254
1104
  >
1255
1105
  <InputControl label="Name" value={name} onChange={(event) => setName(event.target.value)} />
@@ -1274,39 +1124,31 @@ Render the dialog only while you ask, as the example does. Keep the
1274
1124
  state of the fields in the dialog's own component, as
1275
1125
  `AddProjectDialog` does, so each new ask starts with empty fields.
1276
1126
 
1277
- `size` picks the card width from 600px up. `small`, the default,
1278
- draws it 400px wide, as WordPress draws Add Page. `medium` draws it
1279
- 560px wide, for a form whose controls need the room. Below 600px both
1280
- are the same sheet along the bottom of the screen. `title` is the
1281
- heading beside the close button. `submitLabel`, `cancelLabel` and
1282
- `canSubmit` work as in `FormBody`. So does `kind`, but a dialog is a
1283
- `create` by default, 16px above its buttons.
1284
-
1285
- `onSubmit` runs from the submit button or from Enter. Return the
1286
- write's promise, and the submit button shows a spinner until the
1287
- write ends. A second send meanwhile does nothing. The dialog never
1288
- closes itself after a send:
1289
-
1290
- - When the write worked, close it yourself, as `add` does with
1291
- `onClose`.
1292
- - When the write failed, leave it open, as WordPress leaves Add Page.
1293
- The reader keeps what they typed and can try again. Show the
1294
- failure in a toast, with the `.catch` inside `onSubmit`, as
1295
- [a failure from a dialog](#a-failure-from-a-dialog) explains.
1296
-
1297
- A form that opens from a row's own menu, in a list you draw yourself,
1298
- and changes that one item closes before its write, like the
1299
- [rename](#renaming-an-item). Give it `size="medium"`, the width
1300
- WordPress gives its row forms, and `kind="edit"`. In `onSubmit`, take
1301
- the dialog away first, then start the write, and return nothing.
1302
-
1303
- Cancel, Escape, a click outside the dialog and its close button all
1304
- call `onClose`, even while the write runs. When the dialog goes away,
1305
- the focus goes back to the button that opened it.
1306
-
1307
- `FormDialog` comes from `@gopherium/godmin/dialogs`, like
1308
- `ConfirmDialog`, so it needs `@wordpress/components` and its
1309
- stylesheet the same way.
1127
+ `title` is the heading beside the close icon, and `description` an
1128
+ optional help sentence before the fields. `submitLabel` names the
1129
+ send button. `cancelLabel` names Cancel, and a last step with nothing
1130
+ to cancel leaves it out. `canSubmit` greys the send button while a
1131
+ needed field is empty, and it stays reachable with Tab.
1132
+
1133
+ `onSubmit` runs from the send button or from Enter in a field. Return
1134
+ nothing to close at once, or the write's promise to keep the dialog
1135
+ open with a spinner until it ends. Answer `{ error }` to stay open and
1136
+ say why, or `{ close: false }` to stay open with nothing said, as
1137
+ [when a dialog closes](./design-system/dialogs.md#when-a-dialog-closes)
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.
1142
+
1143
+ While the write runs, Cancel, the close icon, Escape and a click on
1144
+ the dimmed page close nothing. Pass a function as the children to
1145
+ read `busy`, such as to set a field `readOnly` until the write ends.
1146
+ When the dialog goes away, the focus goes back to the button that
1147
+ opened it.
1148
+
1149
+ A form over a row or over the picked rows of a list you draw yourself
1150
+ writes through `useDialogRun`, as
1151
+ [a failure from a dialog](#a-failure-from-a-dialog) shows.
1310
1152
 
1311
1153
  ## Putting the focus back on a row
1312
1154
 
@@ -1356,9 +1198,13 @@ layout has no such trigger, such as a title in the phone list, it
1356
1198
  focuses the row's actions menu. When the item left the list, or its
1357
1199
  row has no actions menu, the list region takes the focus.
1358
1200
 
1359
- An action chosen in the bulk bar reads `bulk` from `focusedTrigger()`.
1360
- The bar goes away once the selection clears, so the list region
1361
- 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.
1362
1208
 
1363
1209
  The hook only moves a focus the page lost. When WordPress already put
1364
1210
  the focus back, or the reader moved it, it stays where it is. While
@@ -1382,46 +1228,115 @@ moved to keeps the focus. This needs godmin 0.27.0 or later.
1382
1228
 
1383
1229
  ## A failure from a dialog
1384
1230
 
1385
- A write that fails never shows inside a dialog. It shows in a toast,
1386
- as WordPress shows it in its snackbar. When `onSubmit` or `onConfirm`
1387
- returns a promise, show the toast from inside that same function, and
1388
- return the promise that `.catch` answers:
1231
+ A dialog that stays open after a failure says why inside it. A dialog
1232
+ that closes says how its write went in a toast, as
1233
+ [a failed write](./design-system/dialogs.md#a-failed-write) says. Turn
1234
+ the failure into words and answer them as `{ error }`:
1389
1235
 
1390
1236
  ```tsx
1391
- onSubmit={() => save(values).catch((failure) => toaster.show(failure.message))}
1237
+ onSubmit={(signal) =>
1238
+ save(values, signal).then(
1239
+ () => undefined,
1240
+ (failure: Error) => ({ error: `Could not save the project. ${failure.message}` }),
1241
+ )
1242
+ }
1392
1243
  ```
1393
1244
 
1394
- `.catch` answers a new promise. That one ends with no error once the
1395
- toast shows. The dialog stops its spinner, a `ConfirmDialog` closes,
1396
- and no error goes on to your app. An `async` function that catches
1397
- its own error inside works the same way, as long as you return what
1398
- it answers.
1245
+ The second function of `.then` answers the words, so the promise ends
1246
+ with `{ error }` and the dialog stays with them inside, the typed text
1247
+ kept. An `async` function that catches its own error inside works the
1248
+ same way, as long as you return what it answers. A `ConfirmDialog`
1249
+ reads the same answers. Answer `{ close: false }` when the words go
1250
+ somewhere else, such as a server message about one field under that
1251
+ field.
1252
+
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.
1265
+
1266
+ Many GraphQL clients answer a failed write with an object in `error`
1267
+ instead of rejecting, as [bulk actions](#bulk-actions) says. Only
1268
+ words in `error` keep a dialog open, so turn that answer into words
1269
+ first. Otherwise the dialog takes the write as one that worked.
1270
+
1271
+ A dialog over one row or over the picked rows of a list writes
1272
+ through `useDialogRun`. It takes what `useBulkRun` takes and runs the
1273
+ same way, then answers the dialog:
1399
1274
 
1400
- The line works whatever `save` ends with, the saved item or nothing,
1401
- since the dialog only waits for the promise to end. This needs godmin
1402
- 0.23.1 or later.
1275
+ ```tsx
1276
+ const { run, region } = useListRun('posts', list.onChangeSelection)
1277
+ const write = useDialogRun<Post>(run, refresh)
1278
+
1279
+ const tagWords: BulkWords<Post> = {
1280
+ done: (count) => (count === 1 ? 'Tag added.' : `Tag added to ${count} posts.`),
1281
+ failed: (failures, asked) =>
1282
+ asked === 1
1283
+ ? `Could not add the tag. ${(failures[0].error as Error).message}`
1284
+ : `Could not add the tag to ${failures.length} of ${asked} posts.`,
1285
+ }
1403
1286
 
1404
- `.catch` sees a failure only when the write's promise
1405
- rejects. Many GraphQL clients answer an object with `error` instead,
1406
- as [bulk actions](#bulk-actions) says. With such a client, throw that
1407
- `error` inside your write. Otherwise the dialog takes the write as
1408
- one that worked.
1287
+ <FormDialog
1288
+ title="Add tag"
1289
+ submitLabel="Add"
1290
+ cancelLabel="Cancel"
1291
+ onSubmit={(signal) => write(tagging, (post) => addTag(post.id, tag, signal), tagWords, signal)}
1292
+ onClose={() => setTagging(undefined)}
1293
+ >
1294
+ <InputControl label="Tag" value={tag} onChange={(event) => setTag(event.target.value)} />
1295
+ </FormDialog>
1296
+ ```
1409
1297
 
1410
- Do not add the `.catch` as a separate step and then return the first
1298
+ The action's `callback` stores the rows in `tagging`, as
1299
+ [renaming an item](#renaming-an-item) stores its row.
1300
+
1301
+ - One item that failed: no toast, and the dialog stays with the words
1302
+ of `failed`, the typed text kept.
1303
+ - One item that worked, or several items whatever happened: one toast
1304
+ in your words, and the dialog closes, since a run can half work and
1305
+ a retry would send to every item again.
1306
+ - A call that answers an object with `error`, as a GraphQL client
1307
+ does, counts as a failure, and `failed` gets that object as it came.
1308
+ - The promise ends before the reload ends, so the dialog closes
1309
+ without waiting for the list.
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
+
1320
+ A run moves the focus to the list, so write through `useDialogRun`
1321
+ only from a dialog that closes when its write works. A dialog that
1322
+ stays open after a run that worked would leave the focus behind it.
1323
+
1324
+ Do not catch a failure as a separate step and then return the first
1411
1325
  promise:
1412
1326
 
1413
1327
  ```tsx
1414
- onSubmit={() => {
1415
- const saving = save(values)
1328
+ onSubmit={(signal) => {
1329
+ const saving = save(values, signal)
1416
1330
  saving.catch((failure) => toaster.show(failure.message))
1417
1331
  return saving
1418
1332
  }}
1419
1333
  ```
1420
1334
 
1421
- The toast shows, but `saving` itself still fails. The dialog waits on
1422
- `saving`, so it gets the error too and hands it on to your app as an
1423
- error nobody caught. The same failure reaches your app a second
1424
- time, after you already showed it.
1335
+ The toast shows dimmed under the open dialog, and `saving` itself
1336
+ still fails. The dialog waits on `saving`, so it gets the error too
1337
+ and hands it on to your app as an error nobody caught. The same
1338
+ failure reaches your app a second time, after you already showed it,
1339
+ and the dialog stays open.
1425
1340
 
1426
1341
  That handing on is on purpose. A failure you did not catch is one you
1427
1342
  did not expect, and it should not go quiet. It reaches your app,
@@ -1503,7 +1418,7 @@ It sets it on the document root, so menus and modals that render
1503
1418
  outside your tree follow it too.
1504
1419
 
1505
1420
  ```tsx
1506
- <AdminRoot color={{ primary: '#c9356e' }}>
1421
+ <AdminRoot color={{ primary: '#c9356e' }} writeTimeout={settings.writeTimeout}>
1507
1422
  <App />
1508
1423
  </AdminRoot>
1509
1424
  ```
@@ -1648,7 +1563,12 @@ The Spanish one covers every word DataViews shows around a list: the
1648
1563
  search box, the view options, the filters, the column menus, the
1649
1564
  paging and the bulk bar. It also covers the two words
1650
1565
  `@wordpress/components` shows inside a list, the search reset button
1651
- 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.
1652
1572
 
1653
1573
  The translations are machine made. They stay marked fuzzy in the
1654
1574
  sources, `src/list-chrome/es-ES.po` and `src/list-chrome/fr-FR.po`