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