@gopherium/godmin 0.31.0 → 0.32.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -3
- package/dist/base.css +9 -16
- 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/form-dialog.d.ts +14 -16
- package/dist/form-dialog.js +53 -13
- package/dist/index.d.ts +9 -11
- package/dist/index.js +4 -6
- package/dist/list-chrome/fr-FR.js +1 -0
- package/dist/list-run.js +25 -44
- 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 +90 -7
- package/docs/design-system/accessibility.md +5 -3
- package/docs/design-system/dialogs.md +240 -0
- package/docs/design-system/layout.md +1 -1
- package/docs/design-system/lists.md +3 -1
- package/docs/design-system/motion.md +3 -2
- package/docs/design-system/overview.md +4 -1
- package/docs/design-system/record-pages.md +4 -2
- package/docs/design-system/toasts.md +11 -7
- package/docs/lists.md +311 -432
- package/docs/loading-and-feedback.md +11 -6
- package/docs/overview.md +2 -3
- package/docs/screens.md +10 -2
- package/docs/testing.md +11 -9
- package/package.json +1 -9
- 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
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Dialogs
|
|
3
|
+
description: When an action asks first, how a confirm and a form dialog look and move, what happens while a write runs, where a failure shows, and what a keyboard or a screen reader meets.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
A dialog stops the page to ask one thing. godmin draws two kinds on
|
|
7
|
+
the design system's own parts. A confirm asks one question before an
|
|
8
|
+
action, on the alert dialog. A form dialog holds a short form, on the
|
|
9
|
+
dialog. [Confirming an action](../lists.md#confirming-an-action) and
|
|
10
|
+
[a form dialog](../lists.md#a-form-dialog) show how to open them. This
|
|
11
|
+
page gives every value of how they look and behave.
|
|
12
|
+
|
|
13
|
+
## When to ask first
|
|
14
|
+
|
|
15
|
+
- An action that can be undone asks nothing. It runs at once and its
|
|
16
|
+
toast offers Undo, such as moving an item to the trash.
|
|
17
|
+
[Running an action over the picked rows](../lists.md#running-an-action-over-the-picked-rows)
|
|
18
|
+
shows how a run offers it.
|
|
19
|
+
- An action that cannot be undone asks first, in a confirm with
|
|
20
|
+
`intent="irreversible"`, and offers no Undo.
|
|
21
|
+
- A plain confirm asks before a large change that can be changed
|
|
22
|
+
back, such as making an item the default.
|
|
23
|
+
- A dialog holds one task and one main button. A longer form belongs
|
|
24
|
+
on a page.
|
|
25
|
+
- The steps of one task swap inside one dialog. Open a dialog from a
|
|
26
|
+
dialog only when a confirm has to ask about a part of it.
|
|
27
|
+
|
|
28
|
+
## The words
|
|
29
|
+
|
|
30
|
+
- Every confirm has a title, the action as a short question, such as
|
|
31
|
+
`Delete "Hello"?`, or `Delete 3 orders?` for several.
|
|
32
|
+
- The description says what will happen. When the action cannot be
|
|
33
|
+
undone it ends with "This action cannot be undone."
|
|
34
|
+
- The confirm button names the action, such as "Delete permanently".
|
|
35
|
+
The other button reads "Cancel".
|
|
36
|
+
- Never write "Are you sure" on an action that cannot be undone.
|
|
37
|
+
- A menu label ends with an ellipsis when it opens a dialog, such as
|
|
38
|
+
"Delete…", and has none when it runs at once, such as "Trash".
|
|
39
|
+
|
|
40
|
+
## Size and place
|
|
41
|
+
|
|
42
|
+
- A dialog is a card in the middle of the window at every width. It
|
|
43
|
+
never turns into a sheet on a phone.
|
|
44
|
+
- It keeps `--wpds-dimension-padding-2xl` (24px) from each window edge
|
|
45
|
+
while it can.
|
|
46
|
+
- A confirm is at most `--wpds-dimension-surface-width-lg` (560px)
|
|
47
|
+
wide, and it has no other width.
|
|
48
|
+
- A form dialog takes the same width, and it has no other width
|
|
49
|
+
either.
|
|
50
|
+
- It is never narrower than `--wpds-dimension-surface-width-sm`
|
|
51
|
+
(320px), so on a 320px window it touches both edges.
|
|
52
|
+
- From 480px wide its floor is `--wpds-dimension-surface-width-md`
|
|
53
|
+
(400px).
|
|
54
|
+
- It is at most as tall as the window less that same space twice.
|
|
55
|
+
Only the body scrolls. The title and the buttons stay, and a 1px
|
|
56
|
+
line shows beside them while text is hidden.
|
|
57
|
+
|
|
58
|
+
## Inside the card
|
|
59
|
+
|
|
60
|
+
- The corners take `--wpds-border-radius-lg` (8px), which follows
|
|
61
|
+
[the corner radius setting](./radius-and-elevation.md#the-corner-radius-setting).
|
|
62
|
+
- A `--wpds-border-width-xs` (1px) border sits inside the width, and
|
|
63
|
+
it is transparent over the dimmed page.
|
|
64
|
+
- A shadow of four layers sits under the card: `0 5px 15px` at 8%
|
|
65
|
+
black, `0 15px 27px` at 7%, `0 30px 36px` at 4% and `0 50px 43px` at
|
|
66
|
+
2%.
|
|
67
|
+
- The page behind is dimmed with `rgba(0, 0, 0, 0.35)`.
|
|
68
|
+
- The card keeps `--wpds-dimension-padding-2xl` (24px) inside that
|
|
69
|
+
border at each edge.
|
|
70
|
+
- The title is `heading-xl`, at `--wpds-typography-font-size-xl`
|
|
71
|
+
(20px). The body text is at `--wpds-typography-font-size-md` (13px).
|
|
72
|
+
- `--wpds-dimension-gap-lg` (16px) sits between the title and the
|
|
73
|
+
body, and between the body and the buttons.
|
|
74
|
+
- The fields of a form dialog sit `--wpds-dimension-gap-lg` (16px)
|
|
75
|
+
apart, its help sentence first.
|
|
76
|
+
- The buttons sit at the end, Cancel first,
|
|
77
|
+
`--wpds-dimension-gap-sm` (8px) apart.
|
|
78
|
+
- In a confirm Cancel has no border and takes the neutral tone. The
|
|
79
|
+
confirm button is solid in your accent color, or red with
|
|
80
|
+
`intent="irreversible"`. No prop changes that red, as
|
|
81
|
+
[the three seeds](./color.md#the-three-seeds) says.
|
|
82
|
+
- In a form dialog Cancel has an outline and takes the neutral tone,
|
|
83
|
+
and the send button is solid in your accent color. A close icon
|
|
84
|
+
sits beside the title. A confirm has no close icon.
|
|
85
|
+
- A word too long for the card, such as a long link in a server
|
|
86
|
+
message, breaks at the card's edge.
|
|
87
|
+
|
|
88
|
+
## Motion
|
|
89
|
+
|
|
90
|
+
- The dimmed layer appears at once, and fades out over
|
|
91
|
+
`--wpds-motion-duration-md` (200ms) on `--wpds-motion-easing-subtle`.
|
|
92
|
+
- The card fades and grows from 0.9 of its size over the same time on
|
|
93
|
+
`--wpds-motion-easing-expressive`.
|
|
94
|
+
- The card leaves the same way backwards. `onClose` runs once it has
|
|
95
|
+
left.
|
|
96
|
+
- [Reduced motion](./motion.md#reduced-motion) shows it and takes it
|
|
97
|
+
away at once.
|
|
98
|
+
|
|
99
|
+
## While a write runs
|
|
100
|
+
|
|
101
|
+
When `onConfirm` or `onSubmit` returns a promise, the dialog stays
|
|
102
|
+
open until it ends.
|
|
103
|
+
|
|
104
|
+
- The main button shows a spinner over its hidden label and keeps its
|
|
105
|
+
width. No dialog shows a word such as "Deleting…" or "Saving…".
|
|
106
|
+
- Cancel and the close icon turn grey and stay reachable with Tab.
|
|
107
|
+
- Escape and the dimmed page close nothing, wherever the focus sits,
|
|
108
|
+
so a failure always has a place to show. Give a write that can hang
|
|
109
|
+
a timeout.
|
|
110
|
+
- The fields stay as you drew them. If one must wait, pass a function
|
|
111
|
+
as the children of `FormDialog`. It gets `busy`, so set the field
|
|
112
|
+
`readOnly` while the write runs. Never set it `disabled`, since a
|
|
113
|
+
field that holds the focus would drop it out of the dialog.
|
|
114
|
+
- The main button ignores the second click of a double click, so a
|
|
115
|
+
fast write is not sent twice. On a confirm a held Enter presses it
|
|
116
|
+
once. A press or an Enter after the dialog started to close sends
|
|
117
|
+
nothing.
|
|
118
|
+
|
|
119
|
+
## When a dialog closes
|
|
120
|
+
|
|
121
|
+
| What `onConfirm` or `onSubmit` does | The dialog |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| Returns nothing | Closes at once, and the write runs behind it |
|
|
124
|
+
| Returns a promise | Shows the spinner, then closes when the promise ends |
|
|
125
|
+
| Answers `{ error }`, at once or when its promise ends | Stays and says why |
|
|
126
|
+
| Answers `{ close: false }`, at once or when its promise ends | Stays and says nothing |
|
|
127
|
+
| Throws, or returns a promise that rejects | Stays, and the error goes on to your app |
|
|
128
|
+
|
|
129
|
+
Any other answer, such as the saved item, closes the dialog. godmin
|
|
130
|
+
closes it itself, so call nothing from your handler to close it, and
|
|
131
|
+
take it away in `onClose`. Close first for a long write, and show it
|
|
132
|
+
busy on the button that opened the dialog.
|
|
133
|
+
|
|
134
|
+
Of what `error` may hold, only words keep a dialog open. An empty
|
|
135
|
+
string or an object there closes it, unless `close` is `false`. Many
|
|
136
|
+
GraphQL clients answer a failed write with an object in `error`, and
|
|
137
|
+
the dialog then closes with nothing said. Turn that answer into words
|
|
138
|
+
first, or write through `useDialogRun`, as
|
|
139
|
+
[a failure from a dialog](../lists.md#a-failure-from-a-dialog) shows.
|
|
140
|
+
|
|
141
|
+
## A failed write
|
|
142
|
+
|
|
143
|
+
Does the dialog stay open? Then it says why inside. Otherwise a toast
|
|
144
|
+
does.
|
|
145
|
+
|
|
146
|
+
- In a form dialog `{ error }` draws a notice at the end of the form,
|
|
147
|
+
above the buttons, and scrolls the body to it. What the reader typed
|
|
148
|
+
stays. The notice goes on the next send or the first edit.
|
|
149
|
+
- In a confirm `{ error }` draws the words under the buttons, at the
|
|
150
|
+
end, in `--wpds-typography-font-size-sm` (12px). They go on the next
|
|
151
|
+
press of the confirm button.
|
|
152
|
+
- A form dialog over several items closes, and one toast says how the
|
|
153
|
+
run went, since a run can half work. A form over one item that
|
|
154
|
+
failed stays and says why. `useDialogRun` does both.
|
|
155
|
+
- A server message about one field goes under that field, as on a
|
|
156
|
+
[record page](./record-pages.md#saving). Answer `{ close: false }`
|
|
157
|
+
so the dialog stays with nothing more said.
|
|
158
|
+
- A confirm that closes, such as a run over the picked rows, says how
|
|
159
|
+
it went in a toast.
|
|
160
|
+
- Never raise a toast for a dialog that stays open. It would show
|
|
161
|
+
dimmed under the dialog, as
|
|
162
|
+
[where a toast sits](./toasts.md#where-a-toast-sits) says.
|
|
163
|
+
|
|
164
|
+
## Leaving with unsaved work
|
|
165
|
+
|
|
166
|
+
- `UnsavedChangesDialog` from `@gopherium/godmin/router` asks before a
|
|
167
|
+
move in the app leaves a page that holds unsaved work: a link, the
|
|
168
|
+
sidebar, Back and Forward. Its `when` is true while the page holds
|
|
169
|
+
such work.
|
|
170
|
+
- It is an irreversible confirm in your words, `title`, `description`,
|
|
171
|
+
`discardLabel` and `keepLabel`, such as "Discard changes?",
|
|
172
|
+
"Discard" and "Keep editing".
|
|
173
|
+
- A change of the search alone, such as a sort of a list inside the
|
|
174
|
+
page, does not ask, since the page and its edits stay.
|
|
175
|
+
- Closing the tab, reloading, or Back off the app's first page shows
|
|
176
|
+
the browser's own box.
|
|
177
|
+
- Keep editing, or Escape, stays on the page with the edits. After
|
|
178
|
+
Back the address moves back too.
|
|
179
|
+
- Discard lets the card leave as any confirm does, then the page
|
|
180
|
+
leaves.
|
|
181
|
+
- A handler that saves and then leaves in one go passes
|
|
182
|
+
`ignoreBlocker: true` to its `navigate`, since the page counts as
|
|
183
|
+
unsaved until the save has drawn. Delete on a record does the same.
|
|
184
|
+
|
|
185
|
+
## Keyboard and focus
|
|
186
|
+
|
|
187
|
+
- A confirm opens with the focus on Cancel. A form dialog opens with
|
|
188
|
+
the focus on its first field, past the close icon. A form dialog
|
|
189
|
+
with no field opens on Cancel.
|
|
190
|
+
- Enter in a field sends the form. On a button it presses that button,
|
|
191
|
+
so an Enter right after a confirm opens closes it.
|
|
192
|
+
- Enter in a blank field the form marks `required` sends nothing.
|
|
193
|
+
- Tab stays inside the dialog.
|
|
194
|
+
- Escape closes an idle dialog, wherever the focus sits, a greyed
|
|
195
|
+
button included.
|
|
196
|
+
- A click on the dimmed page closes an idle form dialog, never a
|
|
197
|
+
confirm.
|
|
198
|
+
- When a dialog goes, the focus goes back to the control that opened
|
|
199
|
+
it. A row menu hands the focus to its Actions button before the
|
|
200
|
+
dialog opens, so a dialog from a row menu returns there. When that
|
|
201
|
+
control left the page, see
|
|
202
|
+
[putting the focus back on a row](../lists.md#putting-the-focus-back-on-a-row).
|
|
203
|
+
- When your steps swap inside one form dialog, move the focus
|
|
204
|
+
yourself, such as to the field the next step shows.
|
|
205
|
+
- A focus your code or the reader moved out of the dialog stays
|
|
206
|
+
there.
|
|
207
|
+
- After Undo in the toast of a run, the focus goes to the list, as it
|
|
208
|
+
does after any run.
|
|
209
|
+
|
|
210
|
+
## What paints above what
|
|
211
|
+
|
|
212
|
+
- A toast sits under a dialog, as
|
|
213
|
+
[where a toast sits](./toasts.md#where-a-toast-sits) says.
|
|
214
|
+
- A select, a menu or a confirm from the design system opened inside
|
|
215
|
+
a dialog paints above it. Draw a confirm inside the dialog in your
|
|
216
|
+
component tree, so the dimmed layer does not double.
|
|
217
|
+
- A `Modal`, `Popover`, `Dropdown` or `Tooltip` from
|
|
218
|
+
`@wordpress/components` opened inside a dialog sits under it, and a
|
|
219
|
+
press on it can close the dialog with the typed work. Keep to design
|
|
220
|
+
system parts.
|
|
221
|
+
- A form dialog holds no part from `@wordpress/components` that opens
|
|
222
|
+
over it. A `DataForm` in one uses the regular layout, where a date
|
|
223
|
+
field is an inline calendar. A `color` field opens a `Dropdown`, so
|
|
224
|
+
leave it out.
|
|
225
|
+
- A screen that truly needs such a part draws the design system's
|
|
226
|
+
dialog parts itself, with `Popover.Slot` after the footer and
|
|
227
|
+
outside the form, under a `SlotFillProvider`. A press in the card
|
|
228
|
+
then leaves the panel open, and Escape with the focus in a field
|
|
229
|
+
closes the dialog with the panel still showing.
|
|
230
|
+
|
|
231
|
+
## What a screen reader hears
|
|
232
|
+
|
|
233
|
+
- A confirm is an `alertdialog` and a form dialog a `dialog`. The
|
|
234
|
+
title names it, and its description describes it.
|
|
235
|
+
- A busy button says "Loading" once.
|
|
236
|
+
- A failure inside a dialog is spoken at once.
|
|
237
|
+
- A toast under a dialog is still spoken, politely. Its action cannot
|
|
238
|
+
be reached until the dialog goes.
|
|
239
|
+
- While a dialog is open, a `role="alert"` of your own with no
|
|
240
|
+
`aria-live` is hidden. Use `speak`.
|
|
@@ -86,7 +86,7 @@ as wide. A rule for the screens below it asks for one pixel less, as
|
|
|
86
86
|
| `SIDEBAR_BREAKPOINT` | `1024` | The sidebar becomes the top bar and the drawer |
|
|
87
87
|
| `EDGE_BREAKPOINT` | `782` | The canvas meets the screen edges. It is the WordPress medium breakpoint. A wide list table freezes its checkbox and title only above this width, as [a wide table](./lists.md#a-wide-table) shows |
|
|
88
88
|
| `DENSE_BREAKPOINT` | `640` | The canvas side gutter narrows to 16px. A list from `useListView` takes its phone layout, as [the view in the address](../lists.md#the-view-in-the-address) shows. A table inside `godmin-table-scroll` scrolls sideways, as [stylesheet helpers](../screens.md#stylesheet-helpers) shows |
|
|
89
|
-
| `SHEET_BREAKPOINT` | `600` |
|
|
89
|
+
| `SHEET_BREAKPOINT` | `600` | Toasts widen to the screen, as [toasts](./toasts.md#size) show. It is the WordPress small breakpoint |
|
|
90
90
|
| `TITLE_BREAKPOINT` | `404` | Nothing in the frame. The WordPress editor drops the document title from its header here, for an editor header of your own |
|
|
91
91
|
| `SMALL_VIEWPORT` | `(max-width: 1023px)` | The media query the frame folds its sidebar at |
|
|
92
92
|
|
|
@@ -146,7 +146,9 @@ shows:
|
|
|
146
146
|
page. A focus in the search field or the filters stays where it is
|
|
147
147
|
while the calls run.
|
|
148
148
|
- As the last call ends, the toast shows, the busy button ends and a
|
|
149
|
-
confirm closes
|
|
149
|
+
confirm closes, as
|
|
150
|
+
[when a dialog closes](./dialogs.md#when-a-dialog-closes) says.
|
|
151
|
+
Once a row moved, the list region takes the focus,
|
|
150
152
|
as [where focus goes](./accessibility.md#where-focus-goes) says,
|
|
151
153
|
and here too the screen does not scroll. A reader who ran the action
|
|
152
154
|
from a row near the bottom of the list, or from a confirm, still
|
|
@@ -11,8 +11,9 @@ nothing else. It sets no transitions, so its own hover and focus
|
|
|
11
11
|
looks change at once.
|
|
12
12
|
|
|
13
13
|
Parts that WordPress packages draw keep the motion those packages
|
|
14
|
-
give them. These include the
|
|
15
|
-
|
|
14
|
+
give them. These include the drawer on a small screen, the spinners
|
|
15
|
+
and the pulse of a list that loads. The dialogs move as
|
|
16
|
+
[motion](./dialogs.md#motion) on the dialogs page says.
|
|
16
17
|
|
|
17
18
|
## The tokens
|
|
18
19
|
|
|
@@ -100,7 +100,7 @@ layer.
|
|
|
100
100
|
- [Custom properties](./custom-properties.md): every godmin custom
|
|
101
101
|
property, where it is set and what it changes.
|
|
102
102
|
|
|
103
|
-
|
|
103
|
+
Five more pages cover a single part each, how it looks and how it
|
|
104
104
|
behaves:
|
|
105
105
|
|
|
106
106
|
- [Toasts](./toasts.md): where a toast sits, how it looks, how long it
|
|
@@ -114,3 +114,6 @@ behaves:
|
|
|
114
114
|
- [Record pages](./record-pages.md): how a page that shows one record
|
|
115
115
|
sets its header and its two columns, what scrolls, what its details
|
|
116
116
|
hold, how it saves and what shows while it loads.
|
|
117
|
+
- [Dialogs](./dialogs.md): when an action asks first, how a confirm
|
|
118
|
+
looks and moves, what happens while its write runs, where a failure
|
|
119
|
+
shows, and what a keyboard or a screen reader meets.
|
|
@@ -171,8 +171,10 @@ every value of how it looks.
|
|
|
171
171
|
column.
|
|
172
172
|
- A row added to a list, such as a note, keeps its own button and
|
|
173
173
|
saves at once.
|
|
174
|
-
- While the record holds unsaved work,
|
|
175
|
-
|
|
174
|
+
- While the record holds unsaved work, ask before a link in the app
|
|
175
|
+
leaves the page, such as a breadcrumb, as
|
|
176
|
+
[leaving with unsaved work](./dialogs.md#leaving-with-unsaved-work)
|
|
177
|
+
says.
|
|
176
178
|
|
|
177
179
|
## While a record loads
|
|
178
180
|
|
|
@@ -32,12 +32,12 @@ floats over the list footer, as it does in WordPress. Two things paint
|
|
|
32
32
|
above a toast:
|
|
33
33
|
|
|
34
34
|
- The drawer on a small screen.
|
|
35
|
-
- An open dialog.
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
35
|
+
- An open dialog. A toast shows dimmed under the dark layer around
|
|
36
|
+
the dialog, at every width. Screen readers still hear it, because
|
|
37
|
+
every message is also spoken. A dialog that closes as its write
|
|
38
|
+
starts or ends shows its toast in full. A dialog that stays open
|
|
39
|
+
says why inside, as [a failed write](./dialogs.md#a-failed-write)
|
|
40
|
+
says.
|
|
41
41
|
|
|
42
42
|
## Size
|
|
43
43
|
|
|
@@ -133,7 +133,11 @@ closes after it leaves, so the toasts above slide instead of jumping.
|
|
|
133
133
|
|
|
134
134
|
- A click anywhere on a toast clears it, with or without an action.
|
|
135
135
|
The pointer turns to `--wpds-cursor-control` over every toast.
|
|
136
|
-
- A click on the action runs it and clears the toast.
|
|
136
|
+
- A click on the action runs it and clears the toast. The action takes
|
|
137
|
+
a press `--wpds-dimension-gap-sm` (8px) past its words on every
|
|
138
|
+
side, and further past a label too short for that to make 24
|
|
139
|
+
pixels, so its press area is at least 24 by 24 pixels, with no
|
|
140
|
+
change to how it looks.
|
|
137
141
|
- A click on a toast moves focus to the toast region, as WordPress
|
|
138
142
|
moves it to its snackbar list. The region draws no ring.
|
|
139
143
|
- A toast has no close button. WordPress draws its cross only on a
|