@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.
Files changed (62) hide show
  1. package/README.md +2 -3
  2. package/dist/base.css +159 -29
  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/focus-back.d.ts +20 -0
  13. package/dist/focus-back.js +36 -12
  14. package/dist/form-dialog.d.ts +14 -16
  15. package/dist/form-dialog.js +53 -13
  16. package/dist/index.d.ts +13 -13
  17. package/dist/index.js +7 -8
  18. package/dist/list-chrome/es-ES.js +3 -3
  19. package/dist/list-chrome/fr-FR.js +1 -0
  20. package/dist/list-run.js +39 -48
  21. package/dist/page-breadcrumbs.d.ts +28 -0
  22. package/dist/page-breadcrumbs.js +18 -0
  23. package/dist/page-tabs.js +18 -6
  24. package/dist/page.d.ts +8 -3
  25. package/dist/page.js +36 -9
  26. package/dist/rename-dialog.d.ts +24 -0
  27. package/dist/rename-dialog.js +16 -0
  28. package/dist/router.d.ts +2 -0
  29. package/dist/router.js +1 -0
  30. package/dist/toaster.js +21 -2
  31. package/dist/unsaved-changes-dialog.d.ts +19 -0
  32. package/dist/unsaved-changes-dialog.js +33 -0
  33. package/docs/build-and-versioning.md +92 -9
  34. package/docs/design-system/accessibility.md +12 -7
  35. package/docs/design-system/custom-properties.md +6 -2
  36. package/docs/design-system/dialogs.md +240 -0
  37. package/docs/design-system/layout.md +5 -3
  38. package/docs/design-system/lists.md +3 -1
  39. package/docs/design-system/loading.md +2 -0
  40. package/docs/design-system/motion.md +3 -2
  41. package/docs/design-system/overview.md +7 -1
  42. package/docs/design-system/record-pages.md +199 -0
  43. package/docs/design-system/toasts.md +13 -10
  44. package/docs/design-system/typography.md +1 -1
  45. package/docs/lists.md +321 -434
  46. package/docs/loading-and-feedback.md +14 -11
  47. package/docs/overview.md +2 -3
  48. package/docs/screens.md +87 -34
  49. package/docs/testing.md +11 -9
  50. package/package.json +20 -28
  51. package/dist/close-while-open.d.ts +0 -6
  52. package/dist/close-while-open.js +0 -21
  53. package/dist/confirm.d.ts +0 -21
  54. package/dist/confirm.js +0 -11
  55. package/dist/dialogs.d.ts +0 -4
  56. package/dist/dialogs.js +0 -3
  57. package/dist/form.d.ts +0 -28
  58. package/dist/form.js +0 -23
  59. package/dist/rename.d.ts +0 -20
  60. package/dist/rename.js +0 -14
  61. package/dist/run-confirm.d.ts +0 -22
  62. 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.24.0 <0.25.0`. The window moves
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`. `@wordpress/components` is
91
- an optional peer too, needed only by `@gopherium/godmin/dialogs`, in
92
- the window `>=42.0.0 <43.0.0`. Install each one next to godmin when
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
- `>=20.0.0 <21.0.0`. No godmin entry imports it, but `offeredView`
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
- [a confirm outside a list](../lists.md#a-confirm-outside-a-list) and
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. The aside of a
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. A form row and the header line of a log list
240
- wrap the same way.
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 bleed canvas, which
62
- `canvas="bleed"` asks for, has no gutter at any width and hides what
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` | 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 |
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. 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
@@ -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 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
- Three 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
@@ -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.