@gopherium/godmin 0.30.0 → 0.32.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -3
- package/dist/base.css +159 -29
- package/dist/breakpoints.d.ts +1 -1
- package/dist/breakpoints.js +1 -1
- package/dist/bulk-run.d.ts +10 -0
- package/dist/bulk-run.js +59 -10
- package/dist/bulk.d.ts +3 -0
- package/dist/confirm-dialog.d.ts +14 -14
- package/dist/confirm-dialog.js +8 -28
- package/dist/dialog-open.d.ts +63 -0
- package/dist/dialog-open.js +110 -0
- package/dist/focus-back.d.ts +20 -0
- package/dist/focus-back.js +36 -12
- package/dist/form-dialog.d.ts +14 -16
- package/dist/form-dialog.js +53 -13
- package/dist/index.d.ts +13 -13
- package/dist/index.js +7 -8
- package/dist/list-chrome/es-ES.js +3 -3
- package/dist/list-chrome/fr-FR.js +1 -0
- package/dist/list-run.js +39 -48
- package/dist/page-breadcrumbs.d.ts +28 -0
- package/dist/page-breadcrumbs.js +18 -0
- package/dist/page-tabs.js +18 -6
- package/dist/page.d.ts +8 -3
- package/dist/page.js +36 -9
- package/dist/rename-dialog.d.ts +24 -0
- package/dist/rename-dialog.js +16 -0
- package/dist/router.d.ts +2 -0
- package/dist/router.js +1 -0
- package/dist/toaster.js +21 -2
- package/dist/unsaved-changes-dialog.d.ts +19 -0
- package/dist/unsaved-changes-dialog.js +33 -0
- package/docs/build-and-versioning.md +92 -9
- package/docs/design-system/accessibility.md +12 -7
- package/docs/design-system/custom-properties.md +6 -2
- package/docs/design-system/dialogs.md +240 -0
- package/docs/design-system/layout.md +5 -3
- package/docs/design-system/lists.md +3 -1
- package/docs/design-system/loading.md +2 -0
- package/docs/design-system/motion.md +3 -2
- package/docs/design-system/overview.md +7 -1
- package/docs/design-system/record-pages.md +199 -0
- package/docs/design-system/toasts.md +13 -10
- package/docs/design-system/typography.md +1 -1
- package/docs/lists.md +321 -434
- package/docs/loading-and-feedback.md +14 -11
- package/docs/overview.md +2 -3
- package/docs/screens.md +87 -34
- package/docs/testing.md +11 -9
- package/package.json +20 -28
- package/dist/close-while-open.d.ts +0 -6
- package/dist/close-while-open.js +0 -21
- package/dist/confirm.d.ts +0 -21
- package/dist/confirm.js +0 -11
- package/dist/dialogs.d.ts +0 -4
- package/dist/dialogs.js +0 -3
- package/dist/form.d.ts +0 -28
- package/dist/form.js +0 -23
- package/dist/rename.d.ts +0 -20
- package/dist/rename.js +0 -14
- package/dist/run-confirm.d.ts +0 -22
- package/dist/run-confirm.js +0 -23
|
@@ -70,7 +70,7 @@ fallback values.
|
|
|
70
70
|
|
|
71
71
|
Each godmin release supports one design system window, written out
|
|
72
72
|
in full in its peer ranges as the first version it accepts and the
|
|
73
|
-
first one it refuses, such as `>=0.
|
|
73
|
+
first one it refuses, such as `>=0.25.0 <0.26.0`. The window moves
|
|
74
74
|
forward with the design system and never widens, so no release
|
|
75
75
|
accepts two incompatible generations at once.
|
|
76
76
|
|
|
@@ -87,19 +87,102 @@ in the peer ranges of godmin's `package.json`.
|
|
|
87
87
|
|
|
88
88
|
`@wordpress/i18n` is a required peer, because the main entry
|
|
89
89
|
translates godmin's own words. `@wordpress/date` is an optional peer,
|
|
90
|
-
needed only by `@gopherium/godmin/dates`.
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
you use its entry. Load the components stylesheet once in your
|
|
94
|
-
application, `@wordpress/components/build-style/style.css`, as
|
|
95
|
-
DataViews already asks. godmin never imports it. Their windows are in
|
|
96
|
-
the same peer ranges.
|
|
90
|
+
needed only by `@gopherium/godmin/dates`. Install it next to godmin
|
|
91
|
+
when you use that entry. Its window is in the same peer ranges.
|
|
92
|
+
godmin never imports `@wordpress/components`.
|
|
97
93
|
|
|
98
94
|
`@wordpress/dataviews` is an optional peer as well, in the window
|
|
99
|
-
`>=
|
|
95
|
+
`>=21.0.0 <22.0.0`. No godmin entry imports it, but `offeredView`
|
|
100
96
|
follows the filter rules of that DataViews release. A list built on
|
|
101
97
|
another release gets a peer warning when it installs godmin.
|
|
102
98
|
|
|
99
|
+
## Upgrading from godmin 0.31.0
|
|
100
|
+
|
|
101
|
+
godmin 0.32.0 draws `ConfirmDialog` on the alert dialog of the design
|
|
102
|
+
system and `FormDialog` on its dialog, a confirm or a form on a list
|
|
103
|
+
becomes a dialog your screen renders, and the dialogs move to the main
|
|
104
|
+
entry. Change your code in these places:
|
|
105
|
+
|
|
106
|
+
- `@gopherium/godmin/dialogs` is gone. Import `ConfirmDialog`,
|
|
107
|
+
`FormDialog`, `DialogAnswer` and their props types from
|
|
108
|
+
`@gopherium/godmin`. godmin no longer has `@wordpress/components` as
|
|
109
|
+
a peer. An app that draws DataViews keeps it, since DataViews needs
|
|
110
|
+
it.
|
|
111
|
+
- `ConfirmDialog` takes the question as `title` and what will happen
|
|
112
|
+
as `description`, in place of `children`. `size` is gone, since a
|
|
113
|
+
confirm has one width and is a card at every width. Pass
|
|
114
|
+
`intent="irreversible"` for an action that cannot be undone, which
|
|
115
|
+
draws its button red.
|
|
116
|
+
- `RunConfirm`, `ConfirmBody`, `RunConfirmProps` and
|
|
117
|
+
`ConfirmBodyProps` are gone. Give the list action a `callback` that
|
|
118
|
+
stores the rows, drop its `RenderModal`, `hideModalHeader` and
|
|
119
|
+
`modalFocusOnMount`, and render a `ConfirmDialog` from your screen
|
|
120
|
+
whose `onConfirm` returns the run, as
|
|
121
|
+
[running an action over the picked rows](./lists.md#running-an-action-over-the-picked-rows)
|
|
122
|
+
shows.
|
|
123
|
+
- `FormBody`, `FormKind`, `RenameBody`, `useCloseWhileOpen`,
|
|
124
|
+
`FormBodyProps` and `RenameBodyProps` are gone. Give the row action a
|
|
125
|
+
`callback` that stores the rows, drop its `RenderModal`,
|
|
126
|
+
`modalHeader`, `modalSize` and `modalFocusOnMount`, and render a
|
|
127
|
+
`FormDialog` or a `RenameDialog` from your screen whose `onSubmit`
|
|
128
|
+
returns the write of `useDialogRun`, as
|
|
129
|
+
[renaming an item](./lists.md#renaming-an-item) shows. Stop closing
|
|
130
|
+
the dialog before its write.
|
|
131
|
+
- A rename keeps Save on with a blank field, and the browser refuses
|
|
132
|
+
the send. A test that read Save off reads that a press on it sends
|
|
133
|
+
nothing.
|
|
134
|
+
- A confirm is now an `alertdialog`. A test that finds it by the role
|
|
135
|
+
`dialog` finds it by `alertdialog`.
|
|
136
|
+
- A confirm has no close button now, even with a `title`. A test that
|
|
137
|
+
pressed its close button presses Cancel instead.
|
|
138
|
+
- `onClose` runs once the card has left the page, not at the press.
|
|
139
|
+
A test that reads the dialog gone, or `onClose` called, right after
|
|
140
|
+
a press waits for it, such as with `waitFor`.
|
|
141
|
+
- Escape and Cancel close nothing while the write runs, and a click on
|
|
142
|
+
the dimmed page never closes a confirm. A test that dismissed a busy
|
|
143
|
+
confirm, or clicked outside one, lets the write end or presses
|
|
144
|
+
Cancel instead. Give a write that can hang a timeout.
|
|
145
|
+
- A promise that rejects, or a handler that throws, leaves the confirm
|
|
146
|
+
open, and the error still goes on to your app. To close it, catch
|
|
147
|
+
the failure inside `onConfirm` and show it in a toast, as
|
|
148
|
+
[a failure from a dialog](./lists.md#a-failure-from-a-dialog) shows.
|
|
149
|
+
- A handler that returns, or a promise that ends with, an object
|
|
150
|
+
whose `error` holds words, or whose `close` is `false`, now keeps
|
|
151
|
+
the confirm open. Turn such an answer into one that closes when your
|
|
152
|
+
app wants it to close.
|
|
153
|
+
- Any object with a `then` method now counts as a promise, so the
|
|
154
|
+
confirm waits for it. Before, it waited only for a real `Promise`
|
|
155
|
+
and closed at once for anything else.
|
|
156
|
+
- A stylesheet that styles `.godmin-modal-body`, its `--copy` and
|
|
157
|
+
`--create` forms, or `.godmin-modal-body__question` styles nothing
|
|
158
|
+
now.
|
|
159
|
+
- `FormDialog` has no `kind` and no `size`. It has one width, it is a
|
|
160
|
+
card at every width, and its footer sets the space above its
|
|
161
|
+
buttons.
|
|
162
|
+
- `FormDialog` closes itself. Return nothing from `onSubmit` to close
|
|
163
|
+
at once, or the write's promise to close when it ends, and stop
|
|
164
|
+
closing it from your handler. Take it away in `onClose`, which runs
|
|
165
|
+
once the card has left the page.
|
|
166
|
+
- A form write that fails shows inside the dialog. Answer `{ error }`
|
|
167
|
+
with words from `onSubmit`, in place of a toast, as
|
|
168
|
+
[a failure from a dialog](./lists.md#a-failure-from-a-dialog) shows.
|
|
169
|
+
A promise that rejects, or a handler that throws, leaves the form
|
|
170
|
+
dialog open, and the error still goes on to your app.
|
|
171
|
+
- Cancel, the close icon, Escape and a click on the dimmed page close
|
|
172
|
+
nothing while a form writes. A test that dismissed a busy form
|
|
173
|
+
dialog lets the write end instead.
|
|
174
|
+
- The close button of a form dialog is now a close icon named "Close"
|
|
175
|
+
beside the title, and Cancel draws an outline.
|
|
176
|
+
- The send button of a form dialog sits in the footer, outside the
|
|
177
|
+
form, and names it. user-event in jsdom finds no send button for
|
|
178
|
+
Enter there, so a test that typed Enter in a field presses the send
|
|
179
|
+
button instead, or runs in a browser.
|
|
180
|
+
|
|
181
|
+
TypeScript points at `children`, `size`, `kind`, `RunConfirm`,
|
|
182
|
+
`ConfirmBody`, `FormBody`, `RenameBody`, `useCloseWhileOpen` and each
|
|
183
|
+
import from `@gopherium/godmin/dialogs`. The rest changes what the
|
|
184
|
+
reader sees and when `onClose` runs.
|
|
185
|
+
|
|
103
186
|
## Upgrading from godmin 0.27.0
|
|
104
187
|
|
|
105
188
|
godmin 0.28.0 draws toasts as WordPress's new admin draws its
|
|
@@ -124,8 +124,8 @@ where they are and a screen reader has a control to name, or stays on
|
|
|
124
124
|
the region when that control is a primary action.
|
|
125
125
|
|
|
126
126
|
Dialogs move focus as they open and close, as
|
|
127
|
-
[
|
|
128
|
-
[a form dialog](../lists.md#a-form-dialog) explain. When the list
|
|
127
|
+
[keyboard and focus](./dialogs.md#keyboard-and-focus) on the dialogs
|
|
128
|
+
page and [a form dialog](../lists.md#a-form-dialog) explain. When the list
|
|
129
129
|
drew the row a dialog opened from anew while the dialog was open,
|
|
130
130
|
`useFocusBack` puts the focus back on that row, or on the list once
|
|
131
131
|
the row left it, as
|
|
@@ -145,6 +145,8 @@ jump straight to one.
|
|
|
145
145
|
| The drawer on a small screen | `dialog` | "Navigation", whatever `label` says |
|
|
146
146
|
| The tabs of a page | `navigation` | The `label` of [`PageTabs`](../screens.md#pagetabs) |
|
|
147
147
|
| The list of a list page | `region` | The `listLabel` of [`Page`](../screens.md#page), when given |
|
|
148
|
+
| The details of a record page | `region` | The `asideLabel` of [`Page`](../screens.md#page), when given |
|
|
149
|
+
| The breadcrumbs of a page | `navigation` | The `label` of [`PageBreadcrumbs`](../screens.md#pagebreadcrumbs) |
|
|
148
150
|
|
|
149
151
|
The sidebar menu draws no landmark of its own, and the drawer holds
|
|
150
152
|
no region. So a screen reader meets the sidebar under one name only.
|
|
@@ -165,7 +167,9 @@ its highlight from that mark, so what the eye sees and what a screen
|
|
|
165
167
|
reader hears always match. A page tab draws its underline from its
|
|
166
168
|
`current` prop, which sets the same mark. A router link can set the
|
|
167
169
|
mark on its own too, so [PageTabs](../screens.md#pagetabs) says how
|
|
168
|
-
to keep the underline and the mark in step.
|
|
170
|
+
to keep the underline and the mark in step. A breadcrumb never carries
|
|
171
|
+
the mark, and [PageBreadcrumbs](../screens.md#pagebreadcrumbs) says how
|
|
172
|
+
to keep a router link from setting it.
|
|
169
173
|
|
|
170
174
|
Some screen readers stop treating a list with no bullets as a list.
|
|
171
175
|
So the sidebar rows, the page tabs and a log list keep
|
|
@@ -233,11 +237,12 @@ gives no label a fixed width:
|
|
|
233
237
|
only a smallest height.
|
|
234
238
|
- A long title on a sidebar screen breaks onto the next line.
|
|
235
239
|
- A toast grows with its message, then wraps, as
|
|
236
|
-
[size](./toasts.md#size) on the toasts page shows.
|
|
237
|
-
page and a log list break a long word the same way.
|
|
240
|
+
[size](./toasts.md#size) on the toasts page shows. Both columns of
|
|
241
|
+
a record page and a log list break a long word the same way.
|
|
238
242
|
- The actions of a page header move under the title once they no
|
|
239
|
-
longer fit beside it.
|
|
240
|
-
|
|
243
|
+
longer fit beside it. Beside breadcrumbs the title ends in an
|
|
244
|
+
ellipsis first, and they move once it reaches its smallest width.
|
|
245
|
+
A form row and the header line of a log list wrap the same way.
|
|
241
246
|
- The page tabs keep each label on one line. A tab row too long for
|
|
242
247
|
its page scrolls and fades the edge it cuts.
|
|
243
248
|
|
|
@@ -23,8 +23,8 @@ values. This table says where each one is set and what it changes.
|
|
|
23
23
|
| --- | --- | --- |
|
|
24
24
|
| `--godmin-nav-sidebar-width` | `:root` | The width of the sidebar, and of the drawer that takes its place on a small screen |
|
|
25
25
|
| `--godmin-canvas-margin` | `:root` | The space around the canvas |
|
|
26
|
-
| `--godmin-canvas-gutter` | the canvas | The canvas padding left and right. A `Page` with `list` and no `aside` reaches out by it to the canvas edges |
|
|
27
|
-
| `--godmin-canvas-gutter-block` | the canvas | The canvas padding above and below. The band of notices above the screen keeps this space under it. A `Page` with `list` and no `aside` reaches down by it to the canvas bottom |
|
|
26
|
+
| `--godmin-canvas-gutter` | the canvas | The canvas padding left and right. A `Page` with `list` and no `aside` reaches out by it to the canvas edges. A record page's columns reach out by it too |
|
|
27
|
+
| `--godmin-canvas-gutter-block` | the canvas | The canvas padding above and below. The band of notices above the screen keeps this space under it. A `Page` with `list` and no `aside` reaches down by it to the canvas bottom. A record page's columns reach down by it too |
|
|
28
28
|
| `--godmin-navigation-slide-distance` | `:root` | How far a sidebar screen moves as it slides in |
|
|
29
29
|
| `--godmin-navigation-slide-duration` | `:root` | How long that slide takes |
|
|
30
30
|
|
|
@@ -61,3 +61,7 @@ do not read or set them in your app.
|
|
|
61
61
|
- `--godmin-list-frozen-start` holds the width of the checkbox column
|
|
62
62
|
of a wide list table, where its frozen title starts. It is set on
|
|
63
63
|
the table.
|
|
64
|
+
- `--godmin-page-stacked` tells the columns of a record page whether
|
|
65
|
+
they sit side by side. It stays far below zero while they fit and
|
|
66
|
+
rises far above the height of any record once they do not. It is
|
|
67
|
+
set on the box that holds them.
|
|
@@ -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`.
|
|
@@ -58,8 +58,10 @@ is the padding between its edge and the screen inside it.
|
|
|
58
58
|
and [Elevation](./radius-and-elevation.md#elevation) give the
|
|
59
59
|
corners and the shadow.
|
|
60
60
|
|
|
61
|
-
The canvas scrolls its screen inside itself. A
|
|
62
|
-
|
|
61
|
+
The canvas scrolls its screen inside itself. A DataViews list page and
|
|
62
|
+
a record page keep their title and scroll a part of their own, as
|
|
63
|
+
[what scrolls](./record-pages.md#what-scrolls) gives for a record. A
|
|
64
|
+
bleed canvas, which `canvas="bleed"` asks for, has no gutter at any width and hides what
|
|
63
65
|
overflows it, so the screen scrolls its own parts. The default,
|
|
64
66
|
`padded`, keeps the gutters.
|
|
65
67
|
[Two canvas modes](../framing-an-application.md#two-canvas-modes)
|
|
@@ -84,7 +86,7 @@ as wide. A rule for the screens below it asks for one pixel less, as
|
|
|
84
86
|
| `SIDEBAR_BREAKPOINT` | `1024` | The sidebar becomes the top bar and the drawer |
|
|
85
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 |
|
|
86
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 |
|
|
87
|
-
| `SHEET_BREAKPOINT` | `600` |
|
|
89
|
+
| `SHEET_BREAKPOINT` | `600` | Toasts widen to the screen, as [toasts](./toasts.md#size) show. It is the WordPress small breakpoint |
|
|
88
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 |
|
|
89
91
|
| `SMALL_VIEWPORT` | `(max-width: 1023px)` | The media query the frame folds its sidebar at |
|
|
90
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
|
|
@@ -55,6 +55,8 @@ When it shows and where it sits depend on what is around it:
|
|
|
55
55
|
WordPress screen shows the spinner under its title. The spinner
|
|
56
56
|
sits at the top of the page content, centred across, with the
|
|
57
57
|
page's own gap between it and the title. The title stays on screen.
|
|
58
|
+
In a page with an `aside` it sits at the top of its column, centred
|
|
59
|
+
across that column.
|
|
58
60
|
- Inside a dialog it shows at once too, and takes only the space it
|
|
59
61
|
gets.
|
|
60
62
|
- Inside a sidebar screen it shows at once too, under the screen's
|
|
@@ -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
|
|
@@ -111,3 +111,9 @@ behaves:
|
|
|
111
111
|
hears.
|
|
112
112
|
- [Lists](./lists.md): how a list meets the canvas, its columns, a
|
|
113
113
|
wide table, its rows, an empty list and what it does after a write.
|
|
114
|
+
- [Record pages](./record-pages.md): how a page that shows one record
|
|
115
|
+
sets its header and its two columns, what scrolls, what its details
|
|
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.
|