@gopherium/godmin 0.30.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.
- package/README.md +2 -3
- package/dist/base.css +159 -29
- package/dist/breakpoints.d.ts +1 -1
- package/dist/breakpoints.js +1 -1
- package/dist/bulk-run.d.ts +10 -0
- package/dist/bulk-run.js +59 -10
- package/dist/bulk.d.ts +3 -0
- package/dist/confirm-dialog.d.ts +14 -14
- package/dist/confirm-dialog.js +8 -28
- package/dist/dialog-open.d.ts +63 -0
- package/dist/dialog-open.js +110 -0
- package/dist/focus-back.d.ts +20 -0
- package/dist/focus-back.js +36 -12
- package/dist/form-dialog.d.ts +14 -16
- package/dist/form-dialog.js +53 -13
- package/dist/index.d.ts +13 -13
- package/dist/index.js +7 -8
- package/dist/list-chrome/es-ES.js +3 -3
- package/dist/list-chrome/fr-FR.js +1 -0
- package/dist/list-run.js +39 -48
- package/dist/page-breadcrumbs.d.ts +28 -0
- package/dist/page-breadcrumbs.js +18 -0
- package/dist/page-tabs.js +18 -6
- package/dist/page.d.ts +8 -3
- package/dist/page.js +36 -9
- package/dist/rename-dialog.d.ts +24 -0
- package/dist/rename-dialog.js +16 -0
- package/dist/router.d.ts +2 -0
- package/dist/router.js +1 -0
- package/dist/toaster.js +21 -2
- package/dist/unsaved-changes-dialog.d.ts +19 -0
- package/dist/unsaved-changes-dialog.js +33 -0
- package/docs/build-and-versioning.md +92 -9
- package/docs/design-system/accessibility.md +12 -7
- package/docs/design-system/custom-properties.md +6 -2
- package/docs/design-system/dialogs.md +240 -0
- package/docs/design-system/layout.md +5 -3
- package/docs/design-system/lists.md +3 -1
- package/docs/design-system/loading.md +2 -0
- package/docs/design-system/motion.md +3 -2
- package/docs/design-system/overview.md +7 -1
- package/docs/design-system/record-pages.md +199 -0
- package/docs/design-system/toasts.md +13 -10
- package/docs/design-system/typography.md +1 -1
- package/docs/lists.md +321 -434
- package/docs/loading-and-feedback.md +14 -11
- package/docs/overview.md +2 -3
- package/docs/screens.md +87 -34
- package/docs/testing.md +11 -9
- package/package.json +20 -28
- package/dist/close-while-open.d.ts +0 -6
- package/dist/close-while-open.js +0 -21
- package/dist/confirm.d.ts +0 -21
- package/dist/confirm.js +0 -11
- package/dist/dialogs.d.ts +0 -4
- package/dist/dialogs.js +0 -3
- package/dist/form.d.ts +0 -28
- package/dist/form.js +0 -23
- package/dist/rename.d.ts +0 -20
- package/dist/rename.js +0 -14
- package/dist/run-confirm.d.ts +0 -22
- 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,
|
|
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,
|
|
@@ -601,12 +601,13 @@ with the focus moved to the list from a part that turns inert, one
|
|
|
601
601
|
toast as the last call ends, the focus moved back to the list once a
|
|
602
602
|
row moved, while the reader is still with the run, then the list
|
|
603
603
|
reloaded, and the focus put back on the control the reader pressed,
|
|
604
|
-
|
|
605
|
-
control is a primary action.
|
|
604
|
+
on the same item when the reload moved it, or on the first control of
|
|
605
|
+
the row that took its place, unless that control is a primary action.
|
|
606
|
+
`useListRun` and `useBulkRun` hold those
|
|
606
607
|
things for you:
|
|
607
608
|
|
|
608
609
|
```tsx
|
|
609
|
-
import {
|
|
610
|
+
import { ConfirmDialog, Page, useBulkRun, useListRun } from '@gopherium/godmin'
|
|
610
611
|
|
|
611
612
|
function OrdersScreen() {
|
|
612
613
|
const client = useQueryClient()
|
|
@@ -614,37 +615,35 @@ function OrdersScreen() {
|
|
|
614
615
|
const { run, region } = useListRun('orders', list.onChangeSelection)
|
|
615
616
|
const refresh = useCallback(() => client.invalidateQueries({ queryKey: ['orders'] }), [client])
|
|
616
617
|
const bulk = useBulkRun<Order>(run, refresh)
|
|
618
|
+
const [deleting, setDeleting] = useState<Order[]>()
|
|
617
619
|
const actions = useMemo<Action<Order>[]>(
|
|
618
|
-
() => [
|
|
619
|
-
|
|
620
|
-
id: 'delete',
|
|
621
|
-
label: 'Delete…',
|
|
622
|
-
supportsBulk: true,
|
|
623
|
-
hideModalHeader: true,
|
|
624
|
-
modalFocusOnMount: 'firstContentElement',
|
|
625
|
-
RenderModal: (props) => (
|
|
626
|
-
<RunConfirm {...props} confirmLabel="Delete" cancelLabel="Cancel" run={(orders) => bulk(orders, (order) => deleteOrder(order.id), words)}>
|
|
627
|
-
Delete these orders for good?
|
|
628
|
-
</RunConfirm>
|
|
629
|
-
),
|
|
630
|
-
},
|
|
631
|
-
],
|
|
632
|
-
[bulk],
|
|
620
|
+
() => [{ id: 'delete', label: 'Delete…', supportsBulk: true, callback: setDeleting }],
|
|
621
|
+
[],
|
|
633
622
|
)
|
|
634
623
|
return (
|
|
635
624
|
<Page title="Orders" list listLabel="Orders" listRef={region}>
|
|
636
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}
|
|
637
637
|
</Page>
|
|
638
638
|
)
|
|
639
639
|
}
|
|
640
640
|
```
|
|
641
641
|
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
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.
|
|
648
647
|
|
|
649
648
|
`useListRun` keeps track of the runs on the list. Once a run moved a
|
|
650
649
|
row, the list region takes the focus, so a keyboard reader is not
|
|
@@ -683,6 +682,13 @@ Once the list reloaded, while the region still holds the focus,
|
|
|
683
682
|
- on the control they pressed, when it is still there and takes the
|
|
684
683
|
focus, such as the bulk action button while a row stays ticked, or
|
|
685
684
|
a row's button while its row stays,
|
|
685
|
+
- else on the same item, wherever its card or row now sits, when the
|
|
686
|
+
list marks its cells with `data-item-id` as
|
|
687
|
+
[`useFocusBack`](#putting-the-focus-back-on-a-row) asks. A DataViews grid draws
|
|
688
|
+
a card anew when it moves to another grid row, so after a save that
|
|
689
|
+
sorts a file elsewhere the pressed control is gone. The focus lands
|
|
690
|
+
on the title, media or phone row the reader pressed, else on the
|
|
691
|
+
item's actions menu,
|
|
686
692
|
- else on the first control of the row that now sits where the row of
|
|
687
693
|
that control was, its checkbox in a list with bulk actions, such as
|
|
688
694
|
the next row's checkbox when the row the reader restored left the
|
|
@@ -751,27 +757,31 @@ dialog they opened on another row. So the list takes the focus only
|
|
|
751
757
|
while the reader is still with the run:
|
|
752
758
|
|
|
753
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,
|
|
754
762
|
- the focus sits inside the list,
|
|
755
763
|
- the focus sits in the dialog the run started in,
|
|
756
|
-
- or that dialog
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
the focus
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
the
|
|
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.
|
|
775
785
|
|
|
776
786
|
`focusInDialog()` tells whether a dialog holds the focus, for a write
|
|
777
787
|
you finish yourself outside a run. It also needs godmin 0.27.0 or
|
|
@@ -809,18 +819,31 @@ state shows the failure, as on any later load. The run resolved
|
|
|
809
819
|
before it, so it does not reject. A test that awaits the run and then
|
|
810
820
|
reads the reloaded rows waits for the rows instead.
|
|
811
821
|
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
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.
|
|
824
847
|
|
|
825
848
|
`listLabel` and `listRef` make the list a region with a name, which
|
|
826
849
|
a screen reader announces, and give the focus its target. The region
|
|
@@ -843,190 +866,123 @@ takes the focus only if the focus fell to the page or sits inside the
|
|
|
843
866
|
list. While the focus is still on your button, or on another control
|
|
844
867
|
the reader moved to, it stays there. When your button opens a
|
|
845
868
|
`ConfirmDialog` first, as Empty Trash does, call `run.onStart()`
|
|
846
|
-
inside `onConfirm`, as [
|
|
869
|
+
inside `onConfirm`, as [confirming an action](#confirming-an-action)
|
|
847
870
|
explains. The list then takes the focus once the run moved a row,
|
|
848
871
|
even after the dialog closed, while the focus is still on the button
|
|
849
|
-
|
|
850
|
-
|
|
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.
|
|
851
874
|
|
|
852
875
|
## Confirming an action
|
|
853
876
|
|
|
854
|
-
An action that cannot be undone asks first.
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
```tsx
|
|
860
|
-
const trash = useMemo<Action<Post>>(
|
|
861
|
-
() => ({
|
|
862
|
-
id: 'move-to-trash',
|
|
863
|
-
label: 'Move to trash',
|
|
864
|
-
supportsBulk: true,
|
|
865
|
-
hideModalHeader: true,
|
|
866
|
-
modalFocusOnMount: 'firstContentElement',
|
|
867
|
-
RenderModal: (props) => (
|
|
868
|
-
<RunConfirm {...props} confirmLabel="Move to trash" cancelLabel="Cancel" run={(posts) => bulk(posts, (post) => trashPost(post.id), words)}>
|
|
869
|
-
Move the picked posts to the trash?
|
|
870
|
-
</RunConfirm>
|
|
871
|
-
),
|
|
872
|
-
}),
|
|
873
|
-
[bulk],
|
|
874
|
-
)
|
|
875
|
-
```
|
|
876
|
-
|
|
877
|
-
A confirm that removes something, such as Move to trash or Delete
|
|
878
|
-
permanently, has no header, as in WordPress. Give the action
|
|
879
|
-
`hideModalHeader: true`, and the question is the only text. A plain
|
|
880
|
-
confirm, such as making an item the default, keeps its title through
|
|
881
|
-
`modalHeader`. Leave `modalSize` out, so the modal takes the DataViews
|
|
882
|
-
width, 560px, as WordPress list confirms do.
|
|
883
|
-
`modalFocusOnMount: 'firstContentElement'` puts the focus on Cancel.
|
|
884
|
-
Cancel is borderless text in your accent colour, left of the confirm
|
|
885
|
-
button.
|
|
886
|
-
|
|
887
|
-
For a run you write yourself, `ConfirmBody` is the same body without
|
|
888
|
-
the run:
|
|
889
|
-
|
|
890
|
-
```tsx
|
|
891
|
-
import { ConfirmBody, runEach, useCloseWhileOpen, useToaster } from '@gopherium/godmin'
|
|
892
|
-
|
|
893
|
-
function TrashModal({ items, closeModal }: RenderModalProps<Post>) {
|
|
894
|
-
const toaster = useToaster()
|
|
895
|
-
const close = useCloseWhileOpen(closeModal)
|
|
896
|
-
const [busy, setBusy] = useState(false)
|
|
897
|
-
const confirm = async () => {
|
|
898
|
-
setBusy(true)
|
|
899
|
-
const outcome = await runEach(items, (post) => trashPost(post.id))
|
|
900
|
-
const moved = outcome.failures.length === 0
|
|
901
|
-
toaster.show(moved ? 'Post moved to the trash.' : 'The post could not be moved to the trash.')
|
|
902
|
-
close()
|
|
903
|
-
}
|
|
904
|
-
return (
|
|
905
|
-
<ConfirmBody
|
|
906
|
-
confirmLabel="Move to trash"
|
|
907
|
-
cancelLabel="Cancel"
|
|
908
|
-
busy={busy}
|
|
909
|
-
onConfirm={() => void confirm()}
|
|
910
|
-
onCancel={closeModal}
|
|
911
|
-
>
|
|
912
|
-
Move the post to the trash?
|
|
913
|
-
</ConfirmBody>
|
|
914
|
-
)
|
|
915
|
-
}
|
|
916
|
-
```
|
|
917
|
-
|
|
918
|
-
It draws the question, then Cancel as accent text and the solid
|
|
919
|
-
confirm button at the end, 20px under the question. While `busy`,
|
|
920
|
-
the confirm button shows a spinner and ignores a second press, and
|
|
921
|
-
Cancel closes nothing.
|
|
922
|
-
|
|
923
|
-
The body never shows a failure. Close the modal once the write ends,
|
|
924
|
-
whether it worked or not, and say how it went in a toast, as the
|
|
925
|
-
WordPress list confirms do.
|
|
926
|
-
|
|
927
|
-
Close it through `useCloseWhileOpen(closeModal)`, as the example
|
|
928
|
-
does. DataViews keeps one dialog for a row's actions menu and another
|
|
929
|
-
for its primary action buttons. Every dialog that opens in one of
|
|
930
|
-
them gets the same `closeModal`, so a write that ends after the reader
|
|
931
|
-
dismissed your modal and opened another one in its place would shut
|
|
932
|
-
the new one. The close `useCloseWhileOpen` returns does nothing once
|
|
933
|
-
your modal left the screen. `RunConfirm` closes this way already.
|
|
934
|
-
This needs godmin 0.27.0 or later.
|
|
935
|
-
|
|
936
|
-
## A confirm outside a list
|
|
937
|
-
|
|
938
|
-
Some confirms open from a button outside any list, such as Move to
|
|
939
|
-
trash in an editor or Empty Trash above a list. `ConfirmDialog` asks
|
|
940
|
-
those, as WordPress dialogs do. A confirm above a list can also start
|
|
941
|
-
a [list run](#running-an-action-over-the-picked-rows), as Empty Trash
|
|
942
|
-
does. This section says where the focus goes once that run ends.
|
|
943
|
-
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:
|
|
944
882
|
|
|
945
883
|
```tsx
|
|
946
|
-
import { useToaster } from '@gopherium/godmin'
|
|
947
|
-
import { ConfirmDialog } from '@gopherium/godmin/dialogs'
|
|
884
|
+
import { ConfirmDialog, useToaster } from '@gopherium/godmin'
|
|
948
885
|
import { Button } from '@wordpress/ui'
|
|
949
886
|
|
|
950
|
-
function
|
|
887
|
+
function DeleteButton({ post }: { post: Post }) {
|
|
951
888
|
const toaster = useToaster()
|
|
952
889
|
const [asking, setAsking] = useState(false)
|
|
953
|
-
const [
|
|
954
|
-
const
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
.then(() => toaster.show(
|
|
890
|
+
const [deleting, setDeleting] = useState(false)
|
|
891
|
+
const remove = () => {
|
|
892
|
+
setDeleting(true)
|
|
893
|
+
deletePost(post.id)
|
|
894
|
+
.then(() => toaster.show(`"${post.title}" deleted.`))
|
|
958
895
|
.catch((failure) => toaster.show(failure.message))
|
|
959
|
-
.finally(() =>
|
|
896
|
+
.finally(() => setDeleting(false))
|
|
960
897
|
}
|
|
961
898
|
return (
|
|
962
899
|
<>
|
|
963
|
-
<Button variant="outline" loading={
|
|
900
|
+
<Button variant="outline" loading={deleting} onClick={() => setAsking(true)}>Delete permanently</Button>
|
|
964
901
|
{asking ? (
|
|
965
|
-
<ConfirmDialog
|
|
966
|
-
|
|
967
|
-
|
|
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
|
+
/>
|
|
968
911
|
) : null}
|
|
969
912
|
</>
|
|
970
913
|
)
|
|
971
914
|
}
|
|
972
915
|
```
|
|
973
916
|
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
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.
|
|
981
923
|
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
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.
|
|
986
928
|
|
|
987
|
-
What `onConfirm`
|
|
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:
|
|
988
932
|
|
|
989
933
|
- Return nothing, and the dialog closes at once while your write
|
|
990
|
-
runs.
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
the
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
reader who moved to another control or opened another dialog by
|
|
1001
|
-
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.
|
|
1002
944
|
- Return the write's promise, and the dialog stays open while it
|
|
1003
|
-
runs
|
|
1004
|
-
the
|
|
1005
|
-
|
|
1006
|
-
|
|
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:
|
|
1007
958
|
|
|
1008
959
|
```tsx
|
|
1009
960
|
<ConfirmDialog
|
|
1010
|
-
|
|
961
|
+
title="Make this the default?"
|
|
962
|
+
description="New items will use it."
|
|
963
|
+
confirmLabel="Make default"
|
|
1011
964
|
cancelLabel="Cancel"
|
|
1012
|
-
onConfirm={() =>
|
|
965
|
+
onConfirm={() =>
|
|
966
|
+
makeDefault(item.id).then(
|
|
967
|
+
() => toaster.show(`"${item.name}" is now the default.`),
|
|
968
|
+
(failure: Error) => ({ error: failure.message }),
|
|
969
|
+
)
|
|
970
|
+
}
|
|
1013
971
|
onClose={() => setAsking(false)}
|
|
1014
|
-
|
|
1015
|
-
Delete "{group.name}"?
|
|
1016
|
-
</ConfirmDialog>
|
|
972
|
+
/>
|
|
1017
973
|
```
|
|
1018
974
|
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
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.
|
|
1023
978
|
|
|
1024
|
-
The dialog calls `onClose`
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
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.
|
|
1030
986
|
|
|
1031
987
|
A list run started in `onConfirm` moves the focus to the list once it
|
|
1032
988
|
moved a row, whether the dialog stayed open until then or closed
|
|
@@ -1037,211 +993,101 @@ the focus is still there. Either way, a reader who moved to another
|
|
|
1037
993
|
control or opened another dialog since keeps their place. This needs
|
|
1038
994
|
godmin 0.27.0 or later.
|
|
1039
995
|
|
|
1040
|
-
Render the dialog only while you ask, as the example does. Each new
|
|
1041
|
-
ask then starts fresh.
|
|
1042
|
-
|
|
1043
|
-
`ConfirmDialog` comes from its own entry, `@gopherium/godmin/dialogs`,
|
|
1044
|
-
because it needs `@wordpress/components`, a large package the main
|
|
1045
|
-
entry never loads. Install `@wordpress/components` and load its
|
|
1046
|
-
stylesheet once, `@wordpress/components/build-style/style.css`, as
|
|
1047
|
-
DataViews already asks.
|
|
1048
|
-
|
|
1049
996
|
## Renaming an item
|
|
1050
997
|
|
|
1051
|
-
A rename asks for one new name. `
|
|
1052
|
-
|
|
1053
|
-
|
|
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:
|
|
1054
1002
|
|
|
1055
1003
|
```tsx
|
|
1056
|
-
import {
|
|
1004
|
+
import { Page, RenameDialog, useDialogRun, useListRun } from '@gopherium/godmin'
|
|
1005
|
+
import type { BulkWords } from '@gopherium/godmin'
|
|
1057
1006
|
import type { Action } from '@wordpress/dataviews'
|
|
1058
1007
|
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
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}
|
|
1071
1028
|
fieldLabel="Name"
|
|
1072
1029
|
submitLabel="Save"
|
|
1073
1030
|
cancelLabel="Cancel"
|
|
1074
|
-
onSubmit={(title) =>
|
|
1075
|
-
|
|
1076
|
-
renames.delete(post.id)
|
|
1077
|
-
const stillLatest = markLatest(renames, post.id)
|
|
1078
|
-
renamePost(post.id, title)
|
|
1079
|
-
.then(() => toaster.show('Name updated.'))
|
|
1080
|
-
.catch((failure) => {
|
|
1081
|
-
if (stillLatest()) {
|
|
1082
|
-
renames.set(post.id, title)
|
|
1083
|
-
}
|
|
1084
|
-
toaster.show(failure.message)
|
|
1085
|
-
})
|
|
1086
|
-
}}
|
|
1087
|
-
onCancel={closeModal}
|
|
1031
|
+
onSubmit={(title) => write([renaming], (post) => renamePost(post.id, title), nameWords)}
|
|
1032
|
+
onClose={() => setRenaming(undefined)}
|
|
1088
1033
|
/>
|
|
1089
|
-
)
|
|
1090
|
-
|
|
1091
|
-
[toaster, renames],
|
|
1092
|
-
)
|
|
1093
|
-
}
|
|
1094
|
-
```
|
|
1095
|
-
|
|
1096
|
-
Leave `modalSize` out, so the rename takes the DataViews width, 560px,
|
|
1097
|
-
as the WordPress rename does. WordPress titles it Rename and labels
|
|
1098
|
-
its button Save, and the example does the same.
|
|
1099
|
-
|
|
1100
|
-
The submit button is off only while the field is blank. A name left
|
|
1101
|
-
as it was can still be sent, as in the WordPress rename. Enter in the
|
|
1102
|
-
field does what the submit button does. `onSubmit` gets the name
|
|
1103
|
-
exactly as typed, and your code does the write and the toast.
|
|
1104
|
-
|
|
1105
|
-
A rename closes the moment the reader presses Save, before its write,
|
|
1106
|
-
as WordPress closes its rename. So the body is never busy and never
|
|
1107
|
-
shows a failure. When the write fails, say so in a toast and keep
|
|
1108
|
-
what the reader typed. `name` is the text the field starts with, so
|
|
1109
|
-
hand that text back on the next open. The reader then finds the name
|
|
1110
|
-
they typed and can try once more.
|
|
1111
|
-
|
|
1112
|
-
`useUnsavedText` holds that text, by item id, for as long as the
|
|
1113
|
-
screen stays. Keep it in the hook that builds the action, never in the
|
|
1114
|
-
modal, which goes the moment the reader saves. Clear the item's text
|
|
1115
|
-
before each write, so a save that works leaves nothing behind.
|
|
1116
|
-
`markLatest` marks the write as the latest one sent to the item and
|
|
1117
|
-
returns a check. Keep the failed text only while the check holds, so
|
|
1118
|
-
an earlier save that fails late never overwrites what a later save
|
|
1119
|
-
sent, and a later save that works is never undone. The store holds
|
|
1120
|
-
any value, so a form with several fields keeps them all, as
|
|
1121
|
-
`useUnsavedText<Fields>()`. This needs godmin 0.24.1, or 0.27.0 or
|
|
1122
|
-
later. 0.25.0 and 0.26.0 do not have it.
|
|
1123
|
-
|
|
1124
|
-
Every word comes from you: the field label, both button labels and
|
|
1125
|
-
the toasts. Pass them through your translations.
|
|
1126
|
-
|
|
1127
|
-
`modalFocusOnMount: 'firstContentElement'` puts the cursor in the
|
|
1128
|
-
field when the modal opens, as the WordPress rename does. Without it,
|
|
1129
|
-
the modal window itself takes the focus, and the reader has to press
|
|
1130
|
-
Tab to reach the field.
|
|
1131
|
-
|
|
1132
|
-
## A form in a row action
|
|
1133
|
-
|
|
1134
|
-
Some row actions ask for more than a yes or a name, such as a copy
|
|
1135
|
-
with a title of its own or a new role for a user. `FormBody` is the
|
|
1136
|
-
body of that modal: the fields you give it, an accent text Cancel and
|
|
1137
|
-
the submit button. It is a real form, so Enter in a field sends it:
|
|
1138
|
-
|
|
1139
|
-
```tsx
|
|
1140
|
-
import { FormBody, useCloseWhileOpen, useToaster } from '@gopherium/godmin'
|
|
1141
|
-
import type { Action, RenderModalProps } from '@wordpress/dataviews'
|
|
1142
|
-
import { InputControl } from '@wordpress/ui'
|
|
1143
|
-
|
|
1144
|
-
function DuplicateModal({ items: [post], closeModal }: RenderModalProps<Post>) {
|
|
1145
|
-
const toaster = useToaster()
|
|
1146
|
-
const close = useCloseWhileOpen(closeModal)
|
|
1147
|
-
const [title, setTitle] = useState(`${post.title} (Copy)`)
|
|
1148
|
-
const [busy, setBusy] = useState(false)
|
|
1149
|
-
const duplicate = () => {
|
|
1150
|
-
setBusy(true)
|
|
1151
|
-
duplicatePost(post.id, title)
|
|
1152
|
-
.then(() => toaster.show(`"${title}" created.`))
|
|
1153
|
-
.catch((failure) => toaster.show(failure.message))
|
|
1154
|
-
.finally(close)
|
|
1155
|
-
}
|
|
1156
|
-
return (
|
|
1157
|
-
<FormBody
|
|
1158
|
-
kind="copy"
|
|
1159
|
-
submitLabel="Duplicate"
|
|
1160
|
-
cancelLabel="Cancel"
|
|
1161
|
-
canSubmit={title.trim() !== ''}
|
|
1162
|
-
busy={busy}
|
|
1163
|
-
onSubmit={duplicate}
|
|
1164
|
-
onCancel={closeModal}
|
|
1165
|
-
>
|
|
1166
|
-
<InputControl label="Title" value={title} onChange={(event) => setTitle(event.target.value)} />
|
|
1167
|
-
</FormBody>
|
|
1034
|
+
) : null}
|
|
1035
|
+
</Page>
|
|
1168
1036
|
)
|
|
1169
1037
|
}
|
|
1170
|
-
|
|
1171
|
-
const duplicateAction: Action<Post> = {
|
|
1172
|
-
id: 'duplicate',
|
|
1173
|
-
label: 'Duplicate',
|
|
1174
|
-
modalHeader: 'Duplicate',
|
|
1175
|
-
modalFocusOnMount: 'firstContentElement',
|
|
1176
|
-
RenderModal: DuplicateModal,
|
|
1177
|
-
}
|
|
1178
1038
|
```
|
|
1179
1039
|
|
|
1180
|
-
|
|
1181
|
-
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
|
-
|
|
1185
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
its button busy, then closes when the write ends, worked or failed.
|
|
1204
|
-
Set `busy` while it runs, and close it through
|
|
1205
|
-
`useCloseWhileOpen(closeModal)`, as the example does.
|
|
1206
|
-
[Confirming an action](#confirming-an-action) says why. This needs
|
|
1207
|
-
godmin 0.27.0 or later.
|
|
1208
|
-
|
|
1209
|
-
Either way, a failure goes in a toast. `FormBody` never shows one. To
|
|
1210
|
-
give the reader back what they typed after a failure, keep it in a
|
|
1211
|
-
`useUnsavedText` store outside the modal and pass it in as the first
|
|
1212
|
-
value of the fields, as the rename does.
|
|
1213
|
-
|
|
1214
|
-
Leave `modalSize` out, so the form takes the DataViews width, 560px,
|
|
1215
|
-
as WordPress row forms do. `modalFocusOnMount: 'firstContentElement'`
|
|
1216
|
-
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.
|
|
1217
1063
|
|
|
1218
1064
|
## A form dialog
|
|
1219
1065
|
|
|
1220
1066
|
Some forms open from a button outside any list, such as Add Project
|
|
1221
1067
|
in a page header. `FormDialog` asks those, as WordPress opens its Add
|
|
1222
|
-
Page dialog: a card with a title
|
|
1223
|
-
|
|
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:
|
|
1224
1070
|
|
|
1225
1071
|
```tsx
|
|
1226
|
-
import { useToaster } from '@gopherium/godmin'
|
|
1227
|
-
import { FormDialog } from '@gopherium/godmin/dialogs'
|
|
1072
|
+
import { FormDialog, useToaster } from '@gopherium/godmin'
|
|
1228
1073
|
import { Button, InputControl } from '@wordpress/ui'
|
|
1229
1074
|
|
|
1230
1075
|
function AddProjectDialog({ onClose }: { onClose: () => void }) {
|
|
1231
1076
|
const toaster = useToaster()
|
|
1232
1077
|
const [name, setName] = useState('')
|
|
1233
|
-
const add = async () => {
|
|
1234
|
-
await addProject(name)
|
|
1235
|
-
toaster.show(`"${name}" added.`)
|
|
1236
|
-
onClose()
|
|
1237
|
-
}
|
|
1238
1078
|
return (
|
|
1239
1079
|
<FormDialog
|
|
1240
1080
|
title="Add Project"
|
|
1081
|
+
description="A project groups your orders."
|
|
1241
1082
|
submitLabel="Add"
|
|
1242
1083
|
cancelLabel="Cancel"
|
|
1243
1084
|
canSubmit={name.trim() !== ''}
|
|
1244
|
-
onSubmit={() =>
|
|
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
|
+
}
|
|
1245
1091
|
onClose={onClose}
|
|
1246
1092
|
>
|
|
1247
1093
|
<InputControl label="Name" value={name} onChange={(event) => setName(event.target.value)} />
|
|
@@ -1266,39 +1112,30 @@ Render the dialog only while you ask, as the example does. Keep the
|
|
|
1266
1112
|
state of the fields in the dialog's own component, as
|
|
1267
1113
|
`AddProjectDialog` does, so each new ask starts with empty fields.
|
|
1268
1114
|
|
|
1269
|
-
`
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
`
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
closes itself
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
|
-
the dialog away first, then start the write, and return nothing.
|
|
1294
|
-
|
|
1295
|
-
Cancel, Escape, a click outside the dialog and its close button all
|
|
1296
|
-
call `onClose`, even while the write runs. When the dialog goes away,
|
|
1297
|
-
the focus goes back to the button that opened it.
|
|
1298
|
-
|
|
1299
|
-
`FormDialog` comes from `@gopherium/godmin/dialogs`, like
|
|
1300
|
-
`ConfirmDialog`, so it needs `@wordpress/components` and its
|
|
1301
|
-
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.
|
|
1302
1139
|
|
|
1303
1140
|
## Putting the focus back on a row
|
|
1304
1141
|
|
|
@@ -1374,32 +1211,81 @@ moved to keeps the focus. This needs godmin 0.27.0 or later.
|
|
|
1374
1211
|
|
|
1375
1212
|
## A failure from a dialog
|
|
1376
1213
|
|
|
1377
|
-
A
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
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 }`:
|
|
1381
1218
|
|
|
1382
1219
|
```tsx
|
|
1383
|
-
onSubmit={() =>
|
|
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>
|
|
1384
1269
|
```
|
|
1385
1270
|
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
and no error goes on to your app. An `async` function that catches
|
|
1389
|
-
its own error inside works the same way, as long as you return what
|
|
1390
|
-
it answers.
|
|
1271
|
+
The action's `callback` stores the rows in `tagging`, as
|
|
1272
|
+
[renaming an item](#renaming-an-item) stores its row.
|
|
1391
1273
|
|
|
1392
|
-
|
|
1393
|
-
|
|
1394
|
-
|
|
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.
|
|
1395
1283
|
|
|
1396
|
-
|
|
1397
|
-
|
|
1398
|
-
|
|
1399
|
-
`error` inside your write. Otherwise the dialog takes the write as
|
|
1400
|
-
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.
|
|
1401
1287
|
|
|
1402
|
-
Do not
|
|
1288
|
+
Do not catch a failure as a separate step and then return the first
|
|
1403
1289
|
promise:
|
|
1404
1290
|
|
|
1405
1291
|
```tsx
|
|
@@ -1410,10 +1296,11 @@ onSubmit={() => {
|
|
|
1410
1296
|
}}
|
|
1411
1297
|
```
|
|
1412
1298
|
|
|
1413
|
-
The toast shows,
|
|
1414
|
-
`saving`, so it gets the error too
|
|
1415
|
-
error nobody caught. The same
|
|
1416
|
-
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.
|
|
1417
1304
|
|
|
1418
1305
|
That handing on is on purpose. A failure you did not catch is one you
|
|
1419
1306
|
did not expect, and it should not go quiet. It reaches your app,
|