@gopherium/godmin 0.31.0 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +2 -3
  2. package/dist/base.css +9 -16
  3. package/dist/breakpoints.d.ts +1 -1
  4. package/dist/breakpoints.js +1 -1
  5. package/dist/bulk-run.d.ts +10 -0
  6. package/dist/bulk-run.js +59 -10
  7. package/dist/bulk.d.ts +3 -0
  8. package/dist/confirm-dialog.d.ts +14 -14
  9. package/dist/confirm-dialog.js +8 -28
  10. package/dist/dialog-open.d.ts +63 -0
  11. package/dist/dialog-open.js +110 -0
  12. package/dist/form-dialog.d.ts +14 -16
  13. package/dist/form-dialog.js +53 -13
  14. package/dist/index.d.ts +9 -11
  15. package/dist/index.js +4 -6
  16. package/dist/list-chrome/fr-FR.js +1 -0
  17. package/dist/list-run.js +25 -44
  18. package/dist/rename-dialog.d.ts +24 -0
  19. package/dist/rename-dialog.js +16 -0
  20. package/dist/router.d.ts +2 -0
  21. package/dist/router.js +1 -0
  22. package/dist/toaster.js +21 -2
  23. package/dist/unsaved-changes-dialog.d.ts +19 -0
  24. package/dist/unsaved-changes-dialog.js +33 -0
  25. package/docs/build-and-versioning.md +90 -7
  26. package/docs/design-system/accessibility.md +5 -3
  27. package/docs/design-system/dialogs.md +240 -0
  28. package/docs/design-system/layout.md +1 -1
  29. package/docs/design-system/lists.md +3 -1
  30. package/docs/design-system/motion.md +3 -2
  31. package/docs/design-system/overview.md +4 -1
  32. package/docs/design-system/record-pages.md +4 -2
  33. package/docs/design-system/toasts.md +11 -7
  34. package/docs/lists.md +311 -432
  35. package/docs/loading-and-feedback.md +11 -6
  36. package/docs/overview.md +2 -3
  37. package/docs/screens.md +10 -2
  38. package/docs/testing.md +11 -9
  39. package/package.json +1 -9
  40. package/dist/close-while-open.d.ts +0 -6
  41. package/dist/close-while-open.js +0 -21
  42. package/dist/confirm.d.ts +0 -21
  43. package/dist/confirm.js +0 -11
  44. package/dist/dialogs.d.ts +0 -4
  45. package/dist/dialogs.js +0 -3
  46. package/dist/form.d.ts +0 -28
  47. package/dist/form.js +0 -23
  48. package/dist/rename.d.ts +0 -20
  49. package/dist/rename.js +0 -14
  50. package/dist/run-confirm.d.ts +0 -22
  51. package/dist/run-confirm.js +0 -23
@@ -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` | Dialogs rise as sheets along the bottom of the screen and toasts widen to the screen, as [a form dialog](../lists.md#a-form-dialog) and [toasts](./toasts.md#size) show. It is the WordPress small breakpoint |
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. Once a row moved, the list region takes the focus,
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 dialogs, the drawer on a small screen,
15
- the spinners and the pulse of a list that loads.
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
- Four more pages cover a single part each, how it looks and how it
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, warn on `beforeunload`, and
175
- ask before a link in the app leaves the page, such as a breadcrumb.
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. On a wide screen a toast shows dimmed under the dark
36
- layer around the dialog. On a phone it sits behind the sheet. Screen
37
- readers still hear it, because every message is also spoken. Most
38
- dialogs close as their write starts or ends, so their toast shows in
39
- full. A [form dialog](../lists.md#a-form-dialog) stays open after a
40
- failure, so its toast shows under it, as in WordPress.
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