@gopherium/godmin 0.31.0 → 0.32.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 (51) hide show
  1. package/README.md +2 -3
  2. package/dist/base.css +9 -16
  3. package/dist/breakpoints.d.ts +1 -1
  4. package/dist/breakpoints.js +1 -1
  5. package/dist/bulk-run.d.ts +10 -0
  6. package/dist/bulk-run.js +59 -10
  7. package/dist/bulk.d.ts +3 -0
  8. package/dist/confirm-dialog.d.ts +14 -14
  9. package/dist/confirm-dialog.js +8 -28
  10. package/dist/dialog-open.d.ts +63 -0
  11. package/dist/dialog-open.js +110 -0
  12. package/dist/form-dialog.d.ts +14 -16
  13. package/dist/form-dialog.js +53 -13
  14. package/dist/index.d.ts +9 -11
  15. package/dist/index.js +4 -6
  16. package/dist/list-chrome/fr-FR.js +1 -0
  17. package/dist/list-run.js +25 -44
  18. package/dist/rename-dialog.d.ts +24 -0
  19. package/dist/rename-dialog.js +16 -0
  20. package/dist/router.d.ts +2 -0
  21. package/dist/router.js +1 -0
  22. package/dist/toaster.js +21 -2
  23. package/dist/unsaved-changes-dialog.d.ts +19 -0
  24. package/dist/unsaved-changes-dialog.js +33 -0
  25. package/docs/build-and-versioning.md +90 -7
  26. package/docs/design-system/accessibility.md +5 -3
  27. package/docs/design-system/dialogs.md +240 -0
  28. package/docs/design-system/layout.md +1 -1
  29. package/docs/design-system/lists.md +3 -1
  30. package/docs/design-system/motion.md +3 -2
  31. package/docs/design-system/overview.md +4 -1
  32. package/docs/design-system/record-pages.md +4 -2
  33. package/docs/design-system/toasts.md +11 -7
  34. package/docs/lists.md +311 -432
  35. package/docs/loading-and-feedback.md +11 -6
  36. package/docs/overview.md +2 -3
  37. package/docs/screens.md +10 -2
  38. package/docs/testing.md +11 -9
  39. package/package.json +1 -9
  40. package/dist/close-while-open.d.ts +0 -6
  41. package/dist/close-while-open.js +0 -21
  42. package/dist/confirm.d.ts +0 -21
  43. package/dist/confirm.js +0 -11
  44. package/dist/dialogs.d.ts +0 -4
  45. package/dist/dialogs.js +0 -3
  46. package/dist/form.d.ts +0 -28
  47. package/dist/form.js +0 -23
  48. package/dist/rename.d.ts +0 -20
  49. package/dist/rename.js +0 -14
  50. package/dist/run-confirm.d.ts +0 -22
  51. 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,
@@ -607,7 +607,7 @@ the row that took its place, unless that control is a primary action.
607
607
  things for you:
608
608
 
609
609
  ```tsx
610
- import { Page, RunConfirm, useBulkRun, useListRun } from '@gopherium/godmin'
610
+ import { ConfirmDialog, Page, useBulkRun, useListRun } from '@gopherium/godmin'
611
611
 
612
612
  function OrdersScreen() {
613
613
  const client = useQueryClient()
@@ -615,37 +615,35 @@ function OrdersScreen() {
615
615
  const { run, region } = useListRun('orders', list.onChangeSelection)
616
616
  const refresh = useCallback(() => client.invalidateQueries({ queryKey: ['orders'] }), [client])
617
617
  const bulk = useBulkRun<Order>(run, refresh)
618
+ const [deleting, setDeleting] = useState<Order[]>()
618
619
  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],
620
+ () => [{ id: 'delete', label: 'Delete…', supportsBulk: true, callback: setDeleting }],
621
+ [],
634
622
  )
635
623
  return (
636
624
  <Page title="Orders" list listLabel="Orders" listRef={region}>
637
625
  <DataViews {...props} actions={actions} />
626
+ {deleting ? (
627
+ <ConfirmDialog
628
+ intent="irreversible"
629
+ title={deleting.length === 1 ? `Delete "${deleting[0].name}"?` : `Delete ${deleting.length} orders?`}
630
+ description="This action cannot be undone."
631
+ confirmLabel="Delete"
632
+ cancelLabel="Cancel"
633
+ onConfirm={() => bulk(deleting, (order) => deleteOrder(order.id), words)}
634
+ onClose={() => setDeleting(undefined)}
635
+ />
636
+ ) : null}
638
637
  </Page>
639
638
  )
640
639
  }
641
640
  ```
642
641
 
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.
642
+ The action's `callback` stores the rows to ask about, and the screen
643
+ draws the confirm from them, as
644
+ [confirming an action](#confirming-an-action) explains. DataViews
645
+ calls the same `callback` from a row's actions menu, its primary
646
+ action button and the bulk bar.
649
647
 
650
648
  `useListRun` keeps track of the runs on the list. Once a run moved a
651
649
  row, the list region takes the focus, so a keyboard reader is not
@@ -759,27 +757,31 @@ dialog they opened on another row. So the list takes the focus only
759
757
  while the reader is still with the run:
760
758
 
761
759
  - the focus fell to the page,
760
+ - the focus sits on the toast region itself, where a toast leaves it
761
+ as it goes, such as after the reader pressed Undo in it,
762
762
  - the focus sits inside the list,
763
763
  - 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.
764
+ - or that dialog left the page before the run ended, and the focus
765
+ sits on the control that opened it. A confirm that closes at once
766
+ gives the focus back to the button that opened it, and the list then
767
+ takes the focus from that button. This needs the list on the page as
768
+ the dialog opens, and the dialog taking the focus straight from that
769
+ button. Otherwise the focus stays on the button.
770
+
771
+ A dialog opened since keeps the focus, when it draws in its default
772
+ portal as godmin's dialogs do, so typing still lands in it and Escape
773
+ still closes it. The same goes for a dialog whose control
774
+ opened the dialog the run started in. A reader who moved on to
775
+ another control outside the list keeps their place: during a run
776
+ started outside every dialog, while the dialog the run started in is
777
+ still open, and after that dialog left the page. Every list run does
778
+ this, with nothing to add to your screen. This needs godmin 0.27.0 or
779
+ later. Before it, the list took the focus wherever the focus sat.
780
+ Three cases need godmin 0.32.0 or later. Before it, the focus stayed
781
+ on a control outside the list that opened a WPDS dialog, the list took
782
+ the focus from a control the reader moved to out of a dialog that then
783
+ closed, and a run started from a toast left the focus on the toast
784
+ region.
783
785
 
784
786
  `focusInDialog()` tells whether a dialog holds the focus, for a write
785
787
  you finish yourself outside a run. It also needs godmin 0.27.0 or
@@ -817,18 +819,31 @@ state shows the failure, as on any later load. The run resolved
817
819
  before it, so it does not reject. A test that awaits the run and then
818
820
  reads the reloaded rows waits for the rows instead.
819
821
 
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.
822
+ Give your words an `undo`, and the done toast offers it once every row
823
+ worked. `undo` gets the rows the run was given and answers the toast's
824
+ action, its `label` and its `onAct`. When any row failed, the toast
825
+ holds your `failed` words and offers nothing:
826
+
827
+ ```tsx
828
+ const restoreWords: BulkWords<Post> = {
829
+ done: (count, only) => (only === undefined ? `${count} posts restored.` : `"${only.title}" restored.`),
830
+ failed: (failures) => `Could not restore ${failures.length} posts.`,
831
+ }
832
+
833
+ callback: (posts) =>
834
+ bulk(posts, (post) => trashPost(post.id), {
835
+ ...trashWords,
836
+ undo: (done) => ({ label: 'Undo', onAct: () => void bulk(done, (post) => restorePost(post.id), restoreWords) }),
837
+ })
838
+ ```
839
+
840
+ Undo is then a run of its own, so the list reloads as after any run.
841
+ A press on Undo leaves the focus on the toast region as the toast
842
+ goes, and the list takes it from there once a row moved. This needs
843
+ godmin 0.32.0 or later.
844
+
845
+ A confirm whose `onConfirm` returns the run stays open until the run
846
+ ends, then closes as the toast shows.
832
847
 
833
848
  `listLabel` and `listRef` make the list a region with a name, which
834
849
  a screen reader announces, and give the focus its target. The region
@@ -851,190 +866,123 @@ takes the focus only if the focus fell to the page or sits inside the
851
866
  list. While the focus is still on your button, or on another control
852
867
  the reader moved to, it stays there. When your button opens a
853
868
  `ConfirmDialog` first, as Empty Trash does, call `run.onStart()`
854
- inside `onConfirm`, as [a confirm outside a list](#a-confirm-outside-a-list)
869
+ inside `onConfirm`, as [confirming an action](#confirming-an-action)
855
870
  explains. The list then takes the focus once the run moved a row,
856
871
  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.
872
+ that opened it. A reader who moved to another control by then keeps
873
+ their place. This needs godmin 0.27.0 or later.
859
874
 
860
875
  ## Confirming an action
861
876
 
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:
897
-
898
- ```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:
877
+ An action that cannot be undone asks first. `ConfirmDialog` asks the
878
+ question, on the alert dialog of the design system. The same dialog
879
+ asks for a row action, a bulk action and a button outside any list,
880
+ such as Delete permanently in an editor or Empty Trash above a list.
881
+ Render it only while you ask, so each new ask starts fresh:
952
882
 
953
883
  ```tsx
954
- import { useToaster } from '@gopherium/godmin'
955
- import { ConfirmDialog } from '@gopherium/godmin/dialogs'
884
+ import { ConfirmDialog, useToaster } from '@gopherium/godmin'
956
885
  import { Button } from '@wordpress/ui'
957
886
 
958
- function TrashButton({ post }: { post: Post }) {
887
+ function DeleteButton({ post }: { post: Post }) {
959
888
  const toaster = useToaster()
960
889
  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.'))
890
+ const [deleting, setDeleting] = useState(false)
891
+ const remove = () => {
892
+ setDeleting(true)
893
+ deletePost(post.id)
894
+ .then(() => toaster.show(`"${post.title}" deleted.`))
966
895
  .catch((failure) => toaster.show(failure.message))
967
- .finally(() => setTrashing(false))
896
+ .finally(() => setDeleting(false))
968
897
  }
969
898
  return (
970
899
  <>
971
- <Button variant="outline" loading={trashing} onClick={() => setAsking(true)}>Move to trash</Button>
900
+ <Button variant="outline" loading={deleting} onClick={() => setAsking(true)}>Delete permanently</Button>
972
901
  {asking ? (
973
- <ConfirmDialog size="small" confirmLabel="Move to trash" cancelLabel="Cancel" onConfirm={trash} onClose={() => setAsking(false)}>
974
- Move "Hello" to the trash?
975
- </ConfirmDialog>
902
+ <ConfirmDialog
903
+ intent="irreversible"
904
+ title={`Delete "${post.title}"?`}
905
+ description="This will permanently delete this post. This action cannot be undone."
906
+ confirmLabel="Delete permanently"
907
+ cancelLabel="Cancel"
908
+ onConfirm={remove}
909
+ onClose={() => setAsking(false)}
910
+ />
976
911
  ) : null}
977
912
  </>
978
913
  )
979
914
  }
980
915
  ```
981
916
 
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.
917
+ `title` is the question, and it names the dialog. `description` says
918
+ what will happen, as plain text. `intent="irreversible"` draws the
919
+ confirm button red, for an action that cannot be undone. `confirmLabel`
920
+ and `cancelLabel` name the two buttons. Every word comes from you, so
921
+ pass them through your translations.
922
+ [The words](./design-system/dialogs.md#the-words) says what to write.
989
923
 
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.
924
+ For a row action or a bulk action, give the action a `callback` that
925
+ stores the rows, and render the dialog from your screen, as
926
+ [running an action over the picked rows](#running-an-action-over-the-picked-rows)
927
+ shows. Name one row in the title and count several.
994
928
 
995
- What `onConfirm` returns decides when the dialog goes:
929
+ What `onConfirm` does decides when the dialog goes, as
930
+ [when a dialog closes](./design-system/dialogs.md#when-a-dialog-closes)
931
+ shows:
996
932
 
997
933
  - 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.
934
+ runs. Do this for a write that can take long, such as Empty Trash.
935
+ Show the write as busy on the button that opened the dialog, as the
936
+ example does with `loading`. Make `onConfirm` a plain function, as
937
+ `remove` is. An `async` function always returns a promise, so the
938
+ dialog would stay open until the write ends. When the write is a
939
+ list run, call `run.onStart()` inside `onConfirm`, while the dialog
940
+ still holds the focus. The dialog gives the focus back to its button
941
+ once it has gone, and the list takes the focus once the run moved a
942
+ row, while the focus is still on that button. A reader who moved to
943
+ another control or opened another dialog by then keeps their place.
1010
944
  - 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:
945
+ runs, with a spinner on its confirm button. When the promise ends,
946
+ the dialog closes. A run over the picked rows works this way.
947
+ - Answer `{ error: 'words' }`, at once or as the promise ends, and the
948
+ dialog stays open and shows the words inside. Do this when trying
949
+ again is the next step. Answer `{ close: false }` to stay open and
950
+ say nothing. `DialogAnswer` from `@gopherium/godmin` types both
951
+ answers.
952
+ - A handler that throws, or a promise that rejects, keeps the dialog
953
+ open and hands the error on to your app, as
954
+ [a failure from a dialog](#a-failure-from-a-dialog) explains.
955
+
956
+ Here a plain confirm stays open after a failure, so the reader can
957
+ try again:
1015
958
 
1016
959
  ```tsx
1017
960
  <ConfirmDialog
1018
- confirmLabel="Delete"
961
+ title="Make this the default?"
962
+ description="New items will use it."
963
+ confirmLabel="Make default"
1019
964
  cancelLabel="Cancel"
1020
- onConfirm={() => deleteGroup(group.id).catch((failure) => toaster.show(failure.message))}
965
+ onConfirm={() =>
966
+ makeDefault(item.id).then(
967
+ () => toaster.show(`"${item.name}" is now the default.`),
968
+ (failure: Error) => ({ error: failure.message }),
969
+ )
970
+ }
1021
971
  onClose={() => setAsking(false)}
1022
- >
1023
- Delete "{group.name}"?
1024
- </ConfirmDialog>
972
+ />
1025
973
  ```
1026
974
 
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.
975
+ A dialog that closes says how its write went in a toast.
976
+ [A failed write](./design-system/dialogs.md#a-failed-write) says
977
+ where each failure shows.
1031
978
 
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.
979
+ The dialog calls `onClose` once its card has left the page, after
980
+ Cancel, Escape or a confirm that finished, and only once. Take the
981
+ dialog away there, as the examples do. While the write runs, Cancel
982
+ and Escape close nothing, as
983
+ [while a write runs](./design-system/dialogs.md#while-a-write-runs)
984
+ says. When the dialog goes away, the focus goes back to the control
985
+ that opened it, unless your action already moved it.
1038
986
 
1039
987
  A list run started in `onConfirm` moves the focus to the list once it
1040
988
  moved a row, whether the dialog stayed open until then or closed
@@ -1045,211 +993,101 @@ the focus is still there. Either way, a reader who moved to another
1045
993
  control or opened another dialog since keeps their place. This needs
1046
994
  godmin 0.27.0 or later.
1047
995
 
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
996
  ## Renaming an item
1058
997
 
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:
998
+ A rename asks for one new name. `RenameDialog` asks it on a form
999
+ dialog: a field that starts with the current name, Cancel and Save.
1000
+ Give the action a `callback` that stores the row, and render the
1001
+ dialog from your screen:
1062
1002
 
1063
1003
  ```tsx
1064
- import { RenameBody, markLatest, useToaster, useUnsavedText } from '@gopherium/godmin'
1004
+ import { Page, RenameDialog, useDialogRun, useListRun } from '@gopherium/godmin'
1005
+ import type { BulkWords } from '@gopherium/godmin'
1065
1006
  import type { Action } from '@wordpress/dataviews'
1066
1007
 
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}
1008
+ const nameWords: BulkWords<Post> = {
1009
+ done: () => 'Name updated.',
1010
+ failed: ([{ error }]) => `Could not save the name. ${(error as Error).message}`,
1011
+ }
1012
+
1013
+ function PostsScreen() {
1014
+ const { run, region } = useListRun('posts', list.onChangeSelection)
1015
+ const write = useDialogRun<Post>(run, refresh)
1016
+ const [renaming, setRenaming] = useState<Post>()
1017
+ const actions = useMemo<Action<Post>[]>(
1018
+ () => [{ id: 'rename', label: 'Rename…', callback: ([post]) => setRenaming(post) }],
1019
+ [],
1020
+ )
1021
+ return (
1022
+ <Page title="Posts" list listLabel="Posts" listRef={region}>
1023
+ <DataViews {...props} actions={actions} />
1024
+ {renaming ? (
1025
+ <RenameDialog
1026
+ title="Rename"
1027
+ name={renaming.title}
1079
1028
  fieldLabel="Name"
1080
1029
  submitLabel="Save"
1081
1030
  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}
1031
+ onSubmit={(title) => write([renaming], (post) => renamePost(post.id, title), nameWords)}
1032
+ onClose={() => setRenaming(undefined)}
1096
1033
  />
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>
1034
+ ) : null}
1035
+ </Page>
1176
1036
  )
1177
1037
  }
1178
-
1179
- const duplicateAction: Action<Post> = {
1180
- id: 'duplicate',
1181
- label: 'Duplicate',
1182
- modalHeader: 'Duplicate',
1183
- modalFocusOnMount: 'firstContentElement',
1184
- RenderModal: DuplicateModal,
1185
- }
1186
1038
  ```
1187
1039
 
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.
1040
+ WordPress titles it Rename and labels its button Save, and the
1041
+ example does the same. Every word comes from you: the title, the
1042
+ field label, both button labels and the toasts. Pass them through
1043
+ your translations.
1044
+
1045
+ Save stays on, even with the field blank, as in the WordPress rename.
1046
+ The field is required and must hold more than spaces, so the browser
1047
+ refuses a blank name in its own words and sends nothing. A name left
1048
+ as it was still sends. Enter in the field does what Save does.
1049
+ `onSubmit` gets the name exactly as typed.
1050
+
1051
+ `onSubmit` answers the dialog as the one of
1052
+ [a form dialog](#a-form-dialog) does. Through `useDialogRun`, the
1053
+ dialog stays open while the write runs, with a spinner on Save and
1054
+ 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
1056
+ [a failure from a dialog](#a-failure-from-a-dialog) shows.
1057
+
1058
+ A rename that closes at once, by returning nothing from `onSubmit`
1059
+ and writing after, loses the typed name when the write fails. Keep it
1060
+ in a `useUnsavedText` store by item id, hand it back as `name` on the
1061
+ next open, and check `markLatest` so an earlier save that fails late
1062
+ never overwrites a later one.
1225
1063
 
1226
1064
  ## A form dialog
1227
1065
 
1228
1066
  Some forms open from a button outside any list, such as Add Project
1229
1067
  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:
1068
+ Page dialog: a card with a title, a close icon, the cursor in the
1069
+ first field, and Cancel and the send button at the end:
1232
1070
 
1233
1071
  ```tsx
1234
- import { useToaster } from '@gopherium/godmin'
1235
- import { FormDialog } from '@gopherium/godmin/dialogs'
1072
+ import { FormDialog, useToaster } from '@gopherium/godmin'
1236
1073
  import { Button, InputControl } from '@wordpress/ui'
1237
1074
 
1238
1075
  function AddProjectDialog({ onClose }: { onClose: () => void }) {
1239
1076
  const toaster = useToaster()
1240
1077
  const [name, setName] = useState('')
1241
- const add = async () => {
1242
- await addProject(name)
1243
- toaster.show(`"${name}" added.`)
1244
- onClose()
1245
- }
1246
1078
  return (
1247
1079
  <FormDialog
1248
1080
  title="Add Project"
1081
+ description="A project groups your orders."
1249
1082
  submitLabel="Add"
1250
1083
  cancelLabel="Cancel"
1251
1084
  canSubmit={name.trim() !== ''}
1252
- onSubmit={() => add().catch((failure) => toaster.show(failure.message))}
1085
+ onSubmit={() =>
1086
+ addProject(name).then(
1087
+ () => void toaster.show(`"${name}" added.`),
1088
+ (failure: Error) => ({ error: `Could not add the project. ${failure.message}` }),
1089
+ )
1090
+ }
1253
1091
  onClose={onClose}
1254
1092
  >
1255
1093
  <InputControl label="Name" value={name} onChange={(event) => setName(event.target.value)} />
@@ -1274,39 +1112,30 @@ Render the dialog only while you ask, as the example does. Keep the
1274
1112
  state of the fields in the dialog's own component, as
1275
1113
  `AddProjectDialog` does, so each new ask starts with empty fields.
1276
1114
 
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.
1115
+ `title` is the heading beside the close icon, and `description` an
1116
+ optional help sentence before the fields. `submitLabel` names the
1117
+ send button. `cancelLabel` names Cancel, and a last step with nothing
1118
+ to cancel leaves it out. `canSubmit` greys the send button while a
1119
+ needed field is empty, and it stays reachable with Tab.
1120
+
1121
+ `onSubmit` runs from the send button or from Enter in a field. Return
1122
+ nothing to close at once, or the write's promise to keep the dialog
1123
+ open with a spinner until it ends. Answer `{ error }` to stay open and
1124
+ say why, or `{ close: false }` to stay open with nothing said, as
1125
+ [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.
1129
+
1130
+ While the write runs, Cancel, the close icon, Escape and a click on
1131
+ the dimmed page close nothing. Pass a function as the children to
1132
+ read `busy`, such as to set a field `readOnly` until the write ends.
1133
+ When the dialog goes away, the focus goes back to the button that
1134
+ opened it.
1135
+
1136
+ A form over a row or over the picked rows of a list you draw yourself
1137
+ writes through `useDialogRun`, as
1138
+ [a failure from a dialog](#a-failure-from-a-dialog) shows.
1310
1139
 
1311
1140
  ## Putting the focus back on a row
1312
1141
 
@@ -1382,32 +1211,81 @@ moved to keeps the focus. This needs godmin 0.27.0 or later.
1382
1211
 
1383
1212
  ## A failure from a dialog
1384
1213
 
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:
1214
+ A dialog that stays open after a failure says why inside it. A dialog
1215
+ that closes says how its write went in a toast, as
1216
+ [a failed write](./design-system/dialogs.md#a-failed-write) says. Turn
1217
+ the failure into words and answer them as `{ error }`:
1389
1218
 
1390
1219
  ```tsx
1391
- onSubmit={() => save(values).catch((failure) => toaster.show(failure.message))}
1220
+ onSubmit={() =>
1221
+ save(values).then(
1222
+ () => undefined,
1223
+ (failure: Error) => ({ error: `Could not save the project. ${failure.message}` }),
1224
+ )
1225
+ }
1226
+ ```
1227
+
1228
+ The second function of `.then` answers the words, so the promise ends
1229
+ with `{ error }` and the dialog stays with them inside, the typed text
1230
+ kept. An `async` function that catches its own error inside works the
1231
+ same way, as long as you return what it answers. A `ConfirmDialog`
1232
+ reads the same answers. Answer `{ close: false }` when the words go
1233
+ somewhere else, such as a server message about one field under that
1234
+ field.
1235
+
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.
1238
+
1239
+ Many GraphQL clients answer a failed write with an object in `error`
1240
+ instead of rejecting, as [bulk actions](#bulk-actions) says. Only
1241
+ words in `error` keep a dialog open, so turn that answer into words
1242
+ first. Otherwise the dialog takes the write as one that worked.
1243
+
1244
+ A dialog over one row or over the picked rows of a list writes
1245
+ through `useDialogRun`. It takes what `useBulkRun` takes and runs the
1246
+ same way, then answers the dialog:
1247
+
1248
+ ```tsx
1249
+ const { run, region } = useListRun('posts', list.onChangeSelection)
1250
+ const write = useDialogRun<Post>(run, refresh)
1251
+
1252
+ const tagWords: BulkWords<Post> = {
1253
+ done: (count) => (count === 1 ? 'Tag added.' : `Tag added to ${count} posts.`),
1254
+ failed: (failures, asked) =>
1255
+ asked === 1
1256
+ ? `Could not add the tag. ${(failures[0].error as Error).message}`
1257
+ : `Could not add the tag to ${failures.length} of ${asked} posts.`,
1258
+ }
1259
+
1260
+ <FormDialog
1261
+ title="Add tag"
1262
+ submitLabel="Add"
1263
+ cancelLabel="Cancel"
1264
+ onSubmit={() => write(tagging, (post) => addTag(post.id, tag), tagWords)}
1265
+ onClose={() => setTagging(undefined)}
1266
+ >
1267
+ <InputControl label="Tag" value={tag} onChange={(event) => setTag(event.target.value)} />
1268
+ </FormDialog>
1392
1269
  ```
1393
1270
 
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.
1271
+ The action's `callback` stores the rows in `tagging`, as
1272
+ [renaming an item](#renaming-an-item) stores its row.
1399
1273
 
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.
1274
+ - One item that failed: no toast, and the dialog stays with the words
1275
+ of `failed`, the typed text kept.
1276
+ - One item that worked, or several items whatever happened: one toast
1277
+ in your words, and the dialog closes, since a run can half work and
1278
+ a retry would send to every item again.
1279
+ - A call that answers an object with `error`, as a GraphQL client
1280
+ does, counts as a failure, and `failed` gets that object as it came.
1281
+ - The promise ends before the reload ends, so the dialog closes
1282
+ without waiting for the list.
1403
1283
 
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.
1284
+ A run moves the focus to the list, so write through `useDialogRun`
1285
+ only from a dialog that closes when its write works. A dialog that
1286
+ stays open after a run that worked would leave the focus behind it.
1409
1287
 
1410
- Do not add the `.catch` as a separate step and then return the first
1288
+ Do not catch a failure as a separate step and then return the first
1411
1289
  promise:
1412
1290
 
1413
1291
  ```tsx
@@ -1418,10 +1296,11 @@ onSubmit={() => {
1418
1296
  }}
1419
1297
  ```
1420
1298
 
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.
1299
+ The toast shows dimmed under the open dialog, and `saving` itself
1300
+ still fails. The dialog waits on `saving`, so it gets the error too
1301
+ and hands it on to your app as an error nobody caught. The same
1302
+ failure reaches your app a second time, after you already showed it,
1303
+ and the dialog stays open.
1425
1304
 
1426
1305
  That handing on is on purpose. A failure you did not catch is one you
1427
1306
  did not expect, and it should not go quiet. It reaches your app,