@gopherium/godmin 0.31.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/README.md +19 -10
  2. package/dist/admin-root.d.ts +4 -2
  3. package/dist/admin-root.js +6 -3
  4. package/dist/announcer-heading.d.ts +4 -0
  5. package/dist/announcer-heading.js +25 -0
  6. package/dist/base.css +42 -17
  7. package/dist/breakpoints.d.ts +1 -1
  8. package/dist/breakpoints.js +1 -1
  9. package/dist/bulk-run.d.ts +10 -0
  10. package/dist/bulk-run.js +76 -11
  11. package/dist/bulk.d.ts +3 -0
  12. package/dist/confirm-dialog.d.ts +14 -14
  13. package/dist/confirm-dialog.js +9 -28
  14. package/dist/dialog-open.d.ts +77 -0
  15. package/dist/dialog-open.js +231 -0
  16. package/dist/drilldown-item.d.ts +5 -2
  17. package/dist/drilldown-item.js +14 -2
  18. package/dist/filter-offer.d.ts +5 -5
  19. package/dist/filter-offer.js +9 -9
  20. package/dist/focus-back.js +12 -2
  21. package/dist/form-dialog.d.ts +14 -16
  22. package/dist/form-dialog.js +54 -13
  23. package/dist/frame.d.ts +8 -4
  24. package/dist/frame.js +16 -6
  25. package/dist/index.d.ts +13 -13
  26. package/dist/index.js +7 -8
  27. package/dist/list-chrome/es-ES.d.ts +1 -1
  28. package/dist/list-chrome/es-ES.js +11 -8
  29. package/dist/list-chrome/fr-FR.d.ts +1 -1
  30. package/dist/list-chrome/fr-FR.js +10 -1
  31. package/dist/list-run.js +25 -44
  32. package/dist/navigation-item.d.ts +4 -2
  33. package/dist/navigation-item.js +2 -2
  34. package/dist/navigation-screen.js +10 -3
  35. package/dist/navigation.js +5 -1
  36. package/dist/page.d.ts +3 -2
  37. package/dist/page.js +23 -4
  38. package/dist/rejected-field.d.ts +25 -0
  39. package/dist/rejected-field.js +121 -0
  40. package/dist/rename-dialog.d.ts +24 -0
  41. package/dist/rename-dialog.js +16 -0
  42. package/dist/route-not-found.d.ts +5 -0
  43. package/dist/route-not-found.js +12 -0
  44. package/dist/router.d.ts +10 -2
  45. package/dist/router.js +11 -2
  46. package/dist/screen-title.d.ts +52 -0
  47. package/dist/screen-title.js +165 -0
  48. package/dist/stylelint.d.ts +1 -4
  49. package/dist/stylelint.js +4 -7
  50. package/dist/testing.d.ts +2 -2
  51. package/dist/testing.js +3 -3
  52. package/dist/toaster.js +21 -2
  53. package/dist/unsaved-changes-dialog.d.ts +19 -0
  54. package/dist/unsaved-changes-dialog.js +33 -0
  55. package/dist/vite.js +1 -0
  56. package/docs/build-and-versioning.md +199 -11
  57. package/docs/design-system/accessibility.md +23 -12
  58. package/docs/design-system/color.md +1 -1
  59. package/docs/design-system/custom-properties.md +3 -3
  60. package/docs/design-system/dialogs.md +302 -0
  61. package/docs/design-system/frame.md +276 -0
  62. package/docs/design-system/layout.md +25 -17
  63. package/docs/design-system/lists.md +20 -12
  64. package/docs/design-system/loading.md +20 -12
  65. package/docs/design-system/motion.md +41 -46
  66. package/docs/design-system/overview.md +11 -3
  67. package/docs/design-system/radius-and-elevation.md +2 -2
  68. package/docs/design-system/record-pages.md +13 -3
  69. package/docs/design-system/toasts.md +18 -8
  70. package/docs/framing-an-application.md +77 -23
  71. package/docs/lists.md +372 -452
  72. package/docs/loading-and-feedback.md +11 -6
  73. package/docs/overview.md +9 -4
  74. package/docs/screens.md +104 -5
  75. package/docs/testing.md +40 -9
  76. package/package.json +27 -27
  77. package/dist/close-while-open.d.ts +0 -6
  78. package/dist/close-while-open.js +0 -21
  79. package/dist/confirm.d.ts +0 -21
  80. package/dist/confirm.js +0 -11
  81. package/dist/dialogs.d.ts +0 -4
  82. package/dist/dialogs.js +0 -3
  83. package/dist/form.d.ts +0 -28
  84. package/dist/form.js +0 -23
  85. package/dist/rename.d.ts +0 -20
  86. package/dist/rename.js +0 -14
  87. package/dist/run-confirm.d.ts +0 -22
  88. package/dist/run-confirm.js +0 -23
@@ -0,0 +1,302 @@
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 and when it runs out of time, 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
+ - An action label carries no ellipsis, as DataViews asks, whether it
38
+ opens a dialog, such as "Delete", or 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 or a file name in the title, breaks at the card's edge, and
87
+ the close icon stays in the card. Every other word stays whole,
88
+ so the labels of a grid or a row of fields keep their words.
89
+ - A button wraps as WordPress's buttons do. On a narrow phone a long
90
+ label takes two lines, and a word wider than its button breaks
91
+ inside it, so keep button labels short.
92
+
93
+ ## Motion
94
+
95
+ - The dimmed layer appears at once, and fades out over
96
+ `--wpds-motion-duration-md` (200ms) on `--wpds-motion-easing-subtle`.
97
+ - The card fades and grows from 0.9 of its size over the same time on
98
+ `--wpds-motion-easing-expressive`.
99
+ - The card leaves the same way backwards. `onClose` runs once it has
100
+ left.
101
+ - [Reduced motion](./motion.md#reduced-motion) shows it and takes it
102
+ away at once.
103
+
104
+ ## While a write runs
105
+
106
+ When `onConfirm` or `onSubmit` returns a promise, the dialog stays
107
+ open until it ends, or until the time limit runs out.
108
+
109
+ - The main button shows a spinner over its hidden label and keeps its
110
+ width. No dialog shows a word such as "Deleting…" or "Saving…".
111
+ - Cancel and the close icon turn grey and stay reachable with Tab.
112
+ - Escape and the dimmed page close nothing, wherever the focus sits,
113
+ so a failure always has a place to show.
114
+ - The fields stay as you drew them. If one must wait, pass a function
115
+ as the children of `FormDialog`. It gets `busy`, so set the field
116
+ `readOnly` while the write runs. Never set it `disabled`, since a
117
+ field that holds the focus would drop it out of the dialog.
118
+ - The main button ignores the second click of a double click, so a
119
+ fast write is not sent twice. On a confirm a held Enter presses it
120
+ once. A press or an Enter after the dialog started to close sends
121
+ nothing.
122
+
123
+ The time limit is the `writeTimeout` of `AdminRoot`, in milliseconds.
124
+ Your app sets it once, from its own settings. godmin holds no limit
125
+ of its own, and a dialog outside any `AdminRoot` waits as long as the
126
+ write takes. A handler that returns nothing, or answers at once,
127
+ starts no clock. `writeTimeout` takes a number above 0 and up to
128
+ 2147483647, about 25 days, the longest a browser timer waits. Pass
129
+ `Infinity` to set no limit. Any other value makes `AdminRoot` throw as
130
+ it renders, in every build, so a broken setting shows the first time
131
+ the admin loads. That includes 0, which is what `Number('')` gives for
132
+ a setting left empty.
133
+
134
+ The handler gets an `AbortSignal` as its last argument:
135
+ `onConfirm(signal)` on a confirm, `onSubmit(signal)` on a form dialog
136
+ and `onSubmit(name, signal)` on a rename. A signal is how the browser
137
+ tells a request to stop. Pass it to your write, such as
138
+ `fetch(url, { signal })`, so the request stops once the time limit runs
139
+ out. That stops only the browser's side. The server may still finish a
140
+ write it already received, so make a write safe to send twice, or
141
+ cancel it on the server. A handler that takes no argument still works.
142
+
143
+ When the time limit runs out:
144
+
145
+ - godmin fires the signal and stops waiting. The write has until the
146
+ browser's next task to answer. A write that stops on the signal and
147
+ answers, such as a run of `useDialogRun`, keeps its own answer.
148
+ - Otherwise the dialog shows "Could not get a valid response from the
149
+ server.", or "Unable to connect. Please check your Internet
150
+ connection." when the browser is offline at that moment. These are
151
+ the words of WordPress's `apiFetch`, and godmin's Spanish and French
152
+ catalogues translate them.
153
+ - The words show where `{ error }` shows, as
154
+ [a failed write](#a-failed-write) says, and they are spoken at once.
155
+ - The spinner ends. Cancel, the close icon and Escape close the dialog
156
+ again, and so does the dimmed page on a form dialog. The main button
157
+ sends again, with a new signal.
158
+ - The fields keep what the reader typed, and the focus stays where it
159
+ was.
160
+ - An answer that comes later changes nothing. Once the signal fired,
161
+ any rejection counts as the time-out and does not reach your app,
162
+ whatever error it carries. So a write through `apiFetch`, or through
163
+ a wrapper of your own that turns the abort into an error of its own,
164
+ shows the time-out words too.
165
+
166
+ When your app takes a dialog off the page while its write runs, the
167
+ write keeps its time limit, and the signal still fires once it runs
168
+ out. Nothing the write answers is shown or spoken. A rejection before
169
+ the limit still goes on to your app. A dialog that React hides and
170
+ shows again, such as inside `<Activity>`, shows what the write
171
+ answered while it was hidden.
172
+
173
+ ## When a dialog closes
174
+
175
+ | What `onConfirm` or `onSubmit` does | The dialog |
176
+ | --- | --- |
177
+ | Returns nothing | Closes at once, and the write runs behind it |
178
+ | Returns a promise | Shows the spinner, then closes when the promise ends |
179
+ | Returns a promise still running at the time limit | Fires the signal, then stays and shows the time-out, unless the write answers the signal at once |
180
+ | Answers `{ error }`, at once or when its promise ends | Stays and says why |
181
+ | Answers `{ close: false }`, at once or when its promise ends | Stays and says nothing |
182
+ | Throws, or returns a promise that rejects before the limit runs out | Stays, and the error goes on to your app |
183
+
184
+ Any other answer, such as the saved item, closes the dialog. godmin
185
+ closes it itself, so call nothing from your handler to close it, and
186
+ take it away in `onClose`. Close first for a long write, and show it
187
+ busy on the button that opened the dialog.
188
+
189
+ Of what `error` may hold, only words keep a dialog open. An empty
190
+ string or an object there closes it, unless `close` is `false`. Many
191
+ GraphQL clients answer a failed write with an object in `error`, and
192
+ the dialog then closes with nothing said. Turn that answer into words
193
+ first, or write through `useDialogRun`, as
194
+ [a failure from a dialog](../lists.md#a-failure-from-a-dialog) shows.
195
+
196
+ ## A failed write
197
+
198
+ Does the dialog stay open? Then it says why inside. Otherwise a toast
199
+ does.
200
+
201
+ - In a form dialog `{ error }` draws a notice at the end of the form,
202
+ above the buttons, and scrolls the body to it. What the reader typed
203
+ stays. The notice goes on the next send or the first edit.
204
+ - In a confirm `{ error }` draws the words under the buttons, at the
205
+ end, in `--wpds-typography-font-size-sm` (12px). They go on the next
206
+ press of the confirm button.
207
+ - A write past the time limit shows the time-out in the same place,
208
+ and it goes the same way.
209
+ - A form dialog over several items closes, and one toast says how the
210
+ run went, since a run can half work. A form over one item that
211
+ failed stays and says why. `useDialogRun` does both.
212
+ - A server message about one field goes under that field, as on a
213
+ [record page](./record-pages.md#saving). Answer `{ close: false }`
214
+ so the dialog stays with nothing more said.
215
+ - A confirm that closes, such as a run over the picked rows, says how
216
+ it went in a toast.
217
+ - Never raise a toast for a dialog that stays open. It would show
218
+ dimmed under the dialog, as
219
+ [where a toast sits](./toasts.md#where-a-toast-sits) says.
220
+
221
+ ## Leaving with unsaved work
222
+
223
+ - `UnsavedChangesDialog` from `@gopherium/godmin/router` asks before a
224
+ move in the app leaves a page that holds unsaved work: a link, the
225
+ sidebar, Back and Forward. Its `when` is true while the page holds
226
+ such work.
227
+ - It is an irreversible confirm in your words, `title`, `description`,
228
+ `discardLabel` and `keepLabel`, such as "Discard changes?",
229
+ "Discard" and "Keep editing".
230
+ - A change of the search alone, such as a sort of a list inside the
231
+ page, does not ask, since the page and its edits stay.
232
+ - Closing the tab, reloading, or Back off the app's first page shows
233
+ the browser's own box.
234
+ - Keep editing, or Escape, stays on the page with the edits. After
235
+ Back the address moves back too.
236
+ - Discard lets the card leave as any confirm does, then the page
237
+ leaves.
238
+ - A handler that saves and then leaves in one go passes
239
+ `ignoreBlocker: true` to its `navigate`, since the page counts as
240
+ unsaved until the save has drawn. Delete on a record does the same.
241
+
242
+ ## Keyboard and focus
243
+
244
+ - A confirm opens with the focus on Cancel. A form dialog opens with
245
+ the focus on its first field, past the close icon. A form dialog
246
+ with no field opens on Cancel.
247
+ - Enter in a field sends the form. On a button it presses that button,
248
+ so an Enter right after a confirm opens closes it.
249
+ - Enter in a blank field the form marks `required` sends nothing.
250
+ - Tab stays inside the dialog.
251
+ - Escape closes an idle dialog, wherever the focus sits, a greyed
252
+ button included.
253
+ - A click on the dimmed page closes an idle form dialog, never a
254
+ confirm.
255
+ - When a dialog goes, the focus goes back to the control that opened
256
+ it. A row menu hands the focus to its Actions button before the
257
+ dialog opens, so a dialog from a row menu returns there. When that
258
+ control left the page, see
259
+ [putting the focus back on a row](../lists.md#putting-the-focus-back-on-a-row).
260
+ - When your steps swap inside one form dialog, move the focus
261
+ yourself, such as to the field the next step shows.
262
+ - A focus your code or the reader moved out of the dialog stays
263
+ there.
264
+ - After Undo in the toast of a run, the focus goes to the list, as it
265
+ does after any run.
266
+
267
+ ## What paints above what
268
+
269
+ - A toast sits under a dialog, as
270
+ [where a toast sits](./toasts.md#where-a-toast-sits) says.
271
+ - A select, a menu or a confirm from the design system opened inside
272
+ a dialog paints above it. Draw a confirm inside the dialog in your
273
+ component tree, so the dimmed layer does not double.
274
+ - A `Modal`, `Popover`, `Dropdown` or `Tooltip` from
275
+ `@wordpress/components` opened inside a dialog sits under it, and a
276
+ press on it can close the dialog with the typed work. Keep to design
277
+ system parts.
278
+ - A form dialog holds no part from `@wordpress/components` that opens
279
+ over it. A `DataForm` in one uses the regular layout, where a date
280
+ field is an inline calendar. A `color` field opens a `Dropdown`, so
281
+ leave it out.
282
+ - A screen that truly needs such a part draws the design system's
283
+ dialog parts itself, with `Popover.Slot` after the footer and
284
+ outside the form, under a `SlotFillProvider`. A press in the card
285
+ then leaves the panel open, and Escape with the focus in a field
286
+ closes the dialog with the panel still showing.
287
+
288
+ ## What a screen reader hears
289
+
290
+ - A confirm is an `alertdialog` and a form dialog a `dialog`. The
291
+ title names it, and its description describes it.
292
+ - A busy button says "Loading" once.
293
+ - A failure inside a dialog, the time-out included, is spoken at once.
294
+ - A toast under a dialog is still spoken, politely. Its action cannot
295
+ be reached until the dialog goes.
296
+ - A dialog that stays open while the screen under it changes, such as
297
+ after the browser's Back button, does not stop the title of the new
298
+ screen from being spoken, as
299
+ [what a screen reader hears when the screen changes](./frame.md#what-a-screen-reader-hears-when-the-screen-changes)
300
+ says.
301
+ - While a dialog is open, a `role="alert"` of your own with no
302
+ `aria-live` is hidden. Use `speak`.
@@ -0,0 +1,276 @@
1
+ ---
2
+ title: Frame
3
+ description: How the frame changes as the reader moves between screens, with the sidebar slide, the drawer, what a screen reader hears, the frame on a phone, and why there is no full canvas.
4
+ ---
5
+
6
+ The frame is the outer layout of a godmin admin, a sidebar and a
7
+ canvas. [Layout](./layout.md#the-frame) gives its areas and their
8
+ sizes, and [Framing an application](../framing-an-application.md)
9
+ shows how to set it up. This page gives every value of how the frame
10
+ changes as the reader moves between screens, and where godmin differs
11
+ from WordPress on purpose.
12
+
13
+ ## The sidebar slide
14
+
15
+ The sidebar menu shows one screen at a time. The root screen holds
16
+ the main rows, and each sub menu has a screen of its own. A
17
+ drilldown row is a row with a chevron that opens a sub menu. Back is
18
+ the link in the title row of a sub menu. When a drilldown row or Back
19
+ changes the screen, the new screen slides in:
20
+
21
+ - It starts `--godmin-navigation-slide-distance` (50px) to one side
22
+ and moves into place. As it moves, it fades from transparent to
23
+ fully visible.
24
+ - It takes `--godmin-navigation-slide-duration` (140ms). Its speed
25
+ follows the CSS `ease-in-out` curve, which starts slow and ends
26
+ slow. It plays once, with no delay.
27
+ - A sub menu comes in from the side the text ends on. That is the
28
+ right in a left-to-right language and the left in a right-to-left
29
+ one. Back brings the screen in from the other side.
30
+ [Right-to-left languages](./layout.md#right-to-left-languages) says
31
+ where godmin reads the direction from.
32
+ - It plays on a window `EDGE_BREAKPOINT` (782px) wide or wider. On a
33
+ narrower window a sub menu shows at once, as the WordPress Site
34
+ Editor holds its sidebar still on a phone.
35
+
36
+ The distance, the time and the curve are the ones the WordPress Site
37
+ Editor uses for its own sidebar slide. The Site Editor also holds
38
+ still at exactly 782px, since its script tests `max-width: 782px`.
39
+ godmin follows WordPress's stylesheets, which count 782px as wide.
40
+
41
+ The slide plays only after a drilldown row or Back. It does not play
42
+ on the first load, after a row that keeps the same screen, after a
43
+ link elsewhere on the page, or after the browser's Back and Forward
44
+ buttons. A sub menu whose code loads late slides in once that code
45
+ has arrived.
46
+
47
+ A drilldown row whose address sends the reader on to another one,
48
+ such as `/settings` sending on to `/settings/general`, plays no
49
+ slide. Back takes no focus then, and on a small screen the drawer
50
+ closes, since the frame looks for the exact address the row opened.
51
+ Point such a row at the address its sub menu lands on.
52
+
53
+ Only the screen moves. The sidebar footer stays still under it, and
54
+ the sidebar hides anything that slides past its sides.
55
+ [Where focus goes](./accessibility.md#where-focus-goes) says where
56
+ the focus lands after the slide. You may change the slide through
57
+ its two custom properties.
58
+ [Where each one is set](./custom-properties.md#where-each-one-is-set)
59
+ shows how.
60
+
61
+ ## The drawer
62
+
63
+ Below `SIDEBAR_BREAKPOINT` (1024px) the sidebar folds into a drawer,
64
+ a panel that the menu button of the top bar opens.
65
+ [The frame](./layout.md#the-frame) gives its size.
66
+
67
+ - It slides in from the start edge over `--wpds-motion-duration-md`
68
+ (200ms). Its speed follows the CSS `ease-out` curve, which starts
69
+ fast and ends slow. It leaves the same way.
70
+ - The dark backdrop under it fades in and out over the same time, on
71
+ the same curve.
72
+ - The reader can swipe the drawer back to its edge. While the finger
73
+ drags, the drawer and the backdrop follow it at once, since the
74
+ backdrop's fade takes `0ms` then.
75
+ - When the finger lets go, the drawer ends its move as fast as the
76
+ finger went. It takes `--wpds-motion-duration-md` times the swipe
77
+ strength, a number from 0.1 for a fast flick to 1 for a slow drag.
78
+ So a flick ends in about 20ms, and a slow drag in 200ms at most.
79
+ - In a right-to-left language the drawer opens at the right edge,
80
+ under the menu button, and leaves to the right. Its shadow turns to
81
+ fall on its inner edge, as [elevation](./radius-and-elevation.md#elevation)
82
+ gives. The drawer reads the direction from the `dir="rtl"` your app
83
+ sets on the page, as the stylesheet does.
84
+ - Escape and the close button close it while the focus is inside it,
85
+ and the focus goes back to the menu button. A tap on the backdrop
86
+ closes it too.
87
+ - It closes when the reader opens another page. It stays open when a
88
+ drilldown row or Back changes the sidebar screen, so the reader can
89
+ pick a row in it.
90
+ - Inside the drawer a sub menu slides in on a window from
91
+ `EDGE_BREAKPOINT` up, and shows at once on a narrower one, as
92
+ [the sidebar slide](#the-sidebar-slide) says.
93
+
94
+ These are the times and the curve of the phone sidebar in WordPress's
95
+ new admin. That sidebar has no swipe. The swipe comes from the
96
+ `@wordpress/ui` drawer godmin draws.
97
+
98
+ ## Reduced motion
99
+
100
+ A reader can ask their system for less motion, as
101
+ [reduced motion](./motion.md#reduced-motion) explains. The frame then
102
+ changes two things:
103
+
104
+ - The sidebar slide lasts 0s, as in the WordPress Site Editor, even
105
+ when you set your own slide duration. The new screen shows at once
106
+ in its place.
107
+ - The drawer and its backdrop open and close at once.
108
+
109
+ ## What a screen reader hears when the screen changes
110
+
111
+ A single page app swaps the screen without loading a new page, so a
112
+ screen reader hears nothing unless the app speaks. The frame speaks
113
+ the title of each new screen, as WordPress's new admin does, once your
114
+ app passes `shownPath` to `Frame.Root`.
115
+ [Routes and the frame](../framing-an-application.md#routes-and-the-frame)
116
+ shows how.
117
+
118
+ - When the path changes, a screen reader hears the new screen's
119
+ title. That is the `title` of its `Page`, or the text of a
120
+ `PageTitle` drawn outside any `Page`. When one `Page` holds
121
+ another, the inner one wins. The path is the part of the address
122
+ before any `?` or `#`, such as `/contacts`.
123
+ - It is spoken assertively, so it breaks in at once. It comes two
124
+ animation frames after the new screen shows. An animation frame is
125
+ one turn of the browser's drawing. The wait lets a toast from the
126
+ same click show first.
127
+ - Nothing is spoken on the first load. The first load lasts until the
128
+ first screen shows a title. So a landing screen that shows a
129
+ `LoadingScreen` and then sends the reader on stays silent, and so
130
+ does a route that checks access and sends the reader home.
131
+ - A move the reader makes before the first screen shows a title is
132
+ silent too. The next move speaks.
133
+ - Nothing is spoken when only the search or the hash changes, such as
134
+ a search, a filter, a sort or another page of a list. A move that
135
+ ends on the same path is silent too.
136
+ - A page tab whose address changes the path, such as `/users/tokens`,
137
+ counts as a new screen.
138
+ - A record page that loads after it opens holds its title while its
139
+ `Page` holds nothing but one `LoadingScreen`, as its own child, and
140
+ has no `aside`. A screen reader then hears the record's name once
141
+ the `LoadingScreen` leaves. When that takes longer than 1 second, it
142
+ hears the title the page shows by then, such as the kind of record,
143
+ and the name that comes later is not spoken.
144
+ [While a record loads](./record-pages.md#while-a-record-loads) shows
145
+ that layout.
146
+ - A `LoadingScreen` inside a wrapper of your own, or beside other
147
+ content, holds nothing, so that page's title is spoken at once.
148
+ - A screen with no `Page` of its own says the title of the `Page`
149
+ around it, if there is one, and nothing more once its own `Page`
150
+ shows. With no `Page` around it, it says nothing until its own
151
+ `Page` shows. A bare `LoadingScreen` has no title to give, so a
152
+ screen that loads draws its `Page` with the `LoadingScreen` as its
153
+ own child, as above.
154
+ - The not found screen that `routerDefaults()` gives says "Route not
155
+ found".
156
+ - Two screens that show less than two animation frames apart, such as
157
+ after two fast presses of the browser's Back button, say only the
158
+ second. Two screens further apart are each spoken, in order.
159
+ - The same title on two paths is spoken twice, since the path
160
+ changed.
161
+ - No focus moves. The focus stays where it was, as in WordPress, and
162
+ the title tells the reader where they are.
163
+
164
+ ## The tab title
165
+
166
+ With `appName` on `Frame.Root`, the frame sets the browser tab title
167
+ to the screen title, then `‹`, then the app name, such as "Contacts ‹
168
+ MyApp". It is the shape the WordPress admin gives its tab title,
169
+ without the word WordPress at the end.
170
+
171
+ - It is set on the first load too, unlike the spoken title.
172
+ - It follows the title a screen reader hears. While a screen shows no
173
+ title yet, or its title waits for its record, the tab keeps the
174
+ last one. After 1 second the tab takes the title the page shows
175
+ then, such as the kind of record.
176
+ - godmin translates the pattern `%1$s ‹ %2$s`, so a right-to-left
177
+ translation can turn it around.
178
+ - Without `appName` godmin leaves the tab title alone.
179
+
180
+ ## The sidebar marks
181
+
182
+ A sidebar row draws its highlight from `aria-current="page"`, the mark
183
+ of the current page, as
184
+ [landmarks and names](./accessibility.md#landmarks-and-names) says.
185
+
186
+ - A plain row carries the mark on its own address and on every
187
+ address under it.
188
+ - A drilldown row never carries the mark, not even on its own
189
+ address, as in WordPress. Draw a row that points at the sub menu
190
+ already shown as a plain row, a `NavigationItem`.
191
+ - While a slow sub menu loads, the old page and the root list stay on
192
+ screen, and no row is current until the sub menu shows. WordPress's
193
+ new admin marks its rows the same way. The Site Editor keeps the old
194
+ row current instead.
195
+ - Back is your router's own link. While a slow `home` loads, Back
196
+ carries the mark until the root screen shows. godmin paints nothing
197
+ for it, but a screen reader hears Back as the current page. So let
198
+ the route loader of `home` answer fast.
199
+ - Back draws its focus ring for the keyboard only, as
200
+ [the focus ring](./accessibility.md#the-focus-ring) says. A mouse
201
+ click draws none.
202
+
203
+ ## The frame on a phone
204
+
205
+ - The frame is `100dvh` tall, the height the browser leaves for the
206
+ page right now. On a phone that is the screen less the browser's
207
+ own bars, so the canvas ends where the screen ends, and the list
208
+ footer stays in view.
209
+ - The page itself never scrolls. The canvas and the menus scroll
210
+ inside the frame, so the browser bar stays where it is, and every
211
+ part that sticks to the canvas edge stays put.
212
+ - Put nothing in the page above or below `Frame.Root`, or the page
213
+ scrolls by that much.
214
+ - WordPress's frames take `100vh`, the height with the browser bar
215
+ hidden, so on a phone their bottom sits under the bar. Its newer
216
+ dialogs and drawers take `100dvh`, as the frame does here.
217
+ - godmin writes no fallback for a browser without `dvh`, as
218
+ `@wordpress/ui` writes none. Every browser WordPress supports today
219
+ has it.
220
+
221
+ ## No full canvas
222
+
223
+ godmin has no full canvas. In WordPress a full canvas is the mode
224
+ where an editor takes the whole window. The sidebar goes, and the
225
+ canvas loses its margin, its corners and its shadow. godmin offers
226
+ the `padded` and `bleed` canvas modes only, as
227
+ [two canvas modes](../framing-an-application.md#two-canvas-modes)
228
+ says. A screen that needs more room takes `bleed`.
229
+
230
+ A frame drawn without `Frame.Sidebar` is not a full canvas either.
231
+ Its canvas keeps its margin on every side, as
232
+ [the canvas](./layout.md#the-canvas) says.
233
+
234
+ ## Where godmin differs from WordPress
235
+
236
+ godmin follows WordPress's new admin and the Site Editor, and parts
237
+ from them on purpose in these places:
238
+
239
+ - Browser Back and Forward play no slide. WordPress slides such a
240
+ move the way the last click went, so half of them slide the wrong
241
+ way, and the Site Editor also pulls the focus into the sidebar.
242
+ godmin slides only after a drilldown row or Back, where it knows
243
+ the way.
244
+ - Escape closes the drawer from inside it. In WordPress's new admin
245
+ Escape closes the drawer only from its backdrop, which the keyboard
246
+ never reaches, so a keyboard reader cannot close it.
247
+ - In a right-to-left language the drawer slides in and out at its own
248
+ side, the right. WordPress's new admin rests its drawer at the
249
+ right, but slides it in from the left, across the page, and keeps
250
+ its shadow on the left.
251
+ - Nothing is spoken on the first load. The Site Editor and
252
+ WordPress's new admin both mean to stay silent there, and speak
253
+ anyway.
254
+ - Nothing is spoken when only the search or the hash changes.
255
+ WordPress's new admin speaks on every change of the address.
256
+ - Only the new screen's title is spoken. WordPress's new admin speaks
257
+ the old screen's title first, as a move starts, then the new one.
258
+ - The title waits two animation frames, so a toast from the same
259
+ click shows first. In WordPress's new admin the title replaces the
260
+ toast before the browser draws it.
261
+ - A screen reader hears the screen's heading alone. The Site Editor
262
+ speaks a trail, such as "Index ‹ Template". WordPress's new admin
263
+ speaks the title alone, and a godmin record page already names its
264
+ kind in its breadcrumbs.
265
+ - The not found screen says "Route not found". WordPress's new admin
266
+ draws the same screen but speaks nothing there, or the last
267
+ screen's title, since it speaks only a title its route loader gives.
268
+ The Site Editor speaks an error at an address it does not know, and
269
+ godmin is closer to that.
270
+ - A record holds its title for 1 second at most. The Site Editor and
271
+ WordPress's new admin wait as long as the record takes, so a request
272
+ that hangs leaves the reader in silence, or with the last screen's
273
+ name.
274
+ - While a slow `home` loads, Back carries the mark of the current
275
+ page. WordPress's Back is never marked, since it is not a link.
276
+ godmin's Back is your router's own link.
@@ -11,9 +11,11 @@ a right-to-left language.
11
11
 
12
12
  ## The frame
13
13
 
14
- The frame is as tall as the window. On a wide screen it sets two
15
- areas side by side, with the names the WordPress Site Editor gives
16
- them:
14
+ The frame is as tall as the window the browser shows, and the page
15
+ itself never scrolls, as
16
+ [the frame on a phone](./frame.md#the-frame-on-a-phone) says. On a
17
+ wide screen it sets two areas side by side, with the names the
18
+ WordPress Site Editor gives them:
17
19
 
18
20
  - The sidebar holds the menu. It is `--godmin-nav-sidebar-width`
19
21
  (300px) wide and never shrinks. Its menu scrolls on its own, above a
@@ -33,11 +35,13 @@ top bar takes the place of the sidebar, above the canvas:
33
35
  52px wide and 46px tall. The `brand` you give `Frame.Sidebar` comes
34
36
  8px after the button. The bar keeps 16px free at its end.
35
37
  - The menu button opens the drawer, a panel that slides in over the
36
- page. It holds the same menu and footer as the sidebar. It runs the
37
- full height of the window, as wide as the sidebar but never more
38
- than 85% of the window width. A dark backdrop dims the page under
39
- it. [Raw colors on purpose](./color.md#raw-colors-on-purpose) gives
40
- its color.
38
+ page from the start edge. [The drawer](./frame.md#the-drawer) gives
39
+ how it moves. It holds the same menu and footer as the sidebar. It
40
+ runs the full height the browser shows, as wide as the sidebar but
41
+ never more than 85% of the window width. A dark backdrop dims the
42
+ page under it.
43
+ [Raw colors on purpose](./color.md#raw-colors-on-purpose) gives its
44
+ color.
41
45
 
42
46
  ## The canvas
43
47
 
@@ -58,8 +62,10 @@ is the padding between its edge and the screen inside it.
58
62
  and [Elevation](./radius-and-elevation.md#elevation) give the
59
63
  corners and the shadow.
60
64
 
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
65
+ The canvas scrolls its screen inside itself. The page never scrolls,
66
+ so on a phone the browser's bar stays where it is. A DataViews list
67
+ page and a record page keep their title and scroll a part of their
68
+ own, as
63
69
  [what scrolls](./record-pages.md#what-scrolls) gives for a record. A
64
70
  bleed canvas, which `canvas="bleed"` asks for, has no gutter at any width and hides what
65
71
  overflows it, so the screen scrolls its own parts. The default,
@@ -84,9 +90,9 @@ as wide. A rule for the screens below it asks for one pixel less, as
84
90
  | --- | --- | --- |
85
91
  | `HUGE_BREAKPOINT` | `1440` | Nothing in the frame. It is the WordPress huge breakpoint, for rules of your own |
86
92
  | `SIDEBAR_BREAKPOINT` | `1024` | The sidebar becomes the top bar and the drawer |
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 |
93
+ | `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. A sub menu shows at once, with no slide, as [the sidebar slide](./frame.md#the-sidebar-slide) shows |
88
94
  | `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 |
95
+ | `SHEET_BREAKPOINT` | `600` | Toasts widen to the screen, as [toasts](./toasts.md#size) show. It is the WordPress small breakpoint |
90
96
  | `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
97
  | `SMALL_VIEWPORT` | `(max-width: 1023px)` | The media query the frame folds its sidebar at |
92
98
 
@@ -144,9 +150,11 @@ CSS has no logical form of a sideways slide, a gradient direction or a
144
150
  sideways shadow. Where godmin draws one that must turn around, a
145
151
  second rule under `:dir(rtl)`, the CSS selector for right-to-left
146
152
  text, turns it. That covers
147
- [the sidebar slide](./motion.md#the-sidebar-slide), the fade on the
148
- page tabs where a tab is cut off, and the edge line of a pinned
149
- actions column in a `godmin-table`.
153
+ [the sidebar slide](./frame.md#the-sidebar-slide), the shadow of the
154
+ drawer, the fade on the page tabs where a tab is cut off, and the
155
+ edge line of a pinned actions column in a `godmin-table`. The drawer
156
+ itself opens at the right edge, under the menu button, as
157
+ [the drawer](./frame.md#the-drawer) says.
150
158
 
151
159
  Chevrons turn around too. A row that opens a sub menu ends in a
152
160
  chevron that points to the end, right in English and left in a
@@ -155,5 +163,5 @@ chevron with `isRTL()` from `@wordpress/i18n`, as WordPress does.
155
163
 
156
164
  The stylesheet and the chevrons read the direction from two places.
157
165
  The stylesheet follows the `dir="rtl"` your app sets on the page, such
158
- as on the `html` element. The chevrons follow the translation your app
159
- loads. Set both.
166
+ as on the `html` element, and so does the side the drawer opens at.
167
+ The chevrons follow the translation your app loads. Set both.