@gopherium/godmin 0.32.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 (68) hide show
  1. package/README.md +19 -9
  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 +36 -4
  7. package/dist/bulk-run.d.ts +2 -2
  8. package/dist/bulk-run.js +18 -2
  9. package/dist/confirm-dialog.d.ts +2 -2
  10. package/dist/confirm-dialog.js +3 -2
  11. package/dist/dialog-open.d.ts +16 -2
  12. package/dist/dialog-open.js +126 -5
  13. package/dist/drilldown-item.d.ts +5 -2
  14. package/dist/drilldown-item.js +14 -2
  15. package/dist/filter-offer.d.ts +5 -5
  16. package/dist/filter-offer.js +9 -9
  17. package/dist/focus-back.js +12 -2
  18. package/dist/form-dialog.d.ts +2 -2
  19. package/dist/form-dialog.js +3 -2
  20. package/dist/frame.d.ts +8 -4
  21. package/dist/frame.js +16 -6
  22. package/dist/index.d.ts +4 -2
  23. package/dist/index.js +3 -2
  24. package/dist/list-chrome/es-ES.d.ts +1 -1
  25. package/dist/list-chrome/es-ES.js +11 -8
  26. package/dist/list-chrome/fr-FR.d.ts +1 -1
  27. package/dist/list-chrome/fr-FR.js +9 -1
  28. package/dist/navigation-item.d.ts +4 -2
  29. package/dist/navigation-item.js +2 -2
  30. package/dist/navigation-screen.js +10 -3
  31. package/dist/navigation.js +5 -1
  32. package/dist/page.d.ts +3 -2
  33. package/dist/page.js +23 -4
  34. package/dist/rejected-field.d.ts +25 -0
  35. package/dist/rejected-field.js +121 -0
  36. package/dist/rename-dialog.d.ts +2 -2
  37. package/dist/rename-dialog.js +1 -1
  38. package/dist/route-not-found.d.ts +5 -0
  39. package/dist/route-not-found.js +12 -0
  40. package/dist/router.d.ts +8 -2
  41. package/dist/router.js +10 -2
  42. package/dist/screen-title.d.ts +52 -0
  43. package/dist/screen-title.js +165 -0
  44. package/dist/stylelint.d.ts +1 -4
  45. package/dist/stylelint.js +4 -7
  46. package/dist/testing.d.ts +2 -2
  47. package/dist/testing.js +3 -3
  48. package/dist/vite.js +1 -0
  49. package/docs/build-and-versioning.md +109 -4
  50. package/docs/design-system/accessibility.md +18 -9
  51. package/docs/design-system/color.md +1 -1
  52. package/docs/design-system/custom-properties.md +3 -3
  53. package/docs/design-system/dialogs.md +71 -9
  54. package/docs/design-system/frame.md +276 -0
  55. package/docs/design-system/layout.md +24 -16
  56. package/docs/design-system/lists.md +17 -11
  57. package/docs/design-system/loading.md +20 -12
  58. package/docs/design-system/motion.md +41 -47
  59. package/docs/design-system/overview.md +8 -3
  60. package/docs/design-system/radius-and-elevation.md +2 -2
  61. package/docs/design-system/record-pages.md +9 -1
  62. package/docs/design-system/toasts.md +7 -1
  63. package/docs/framing-an-application.md +77 -23
  64. package/docs/lists.md +80 -39
  65. package/docs/overview.md +9 -3
  66. package/docs/screens.md +94 -3
  67. package/docs/testing.md +29 -0
  68. package/package.json +27 -19
@@ -71,7 +71,11 @@ sidebar moves focus in these cases only:
71
71
  | Opens a page with any other link | Nowhere. The sidebar moves no focus |
72
72
  | Closes the drawer with Escape or its close button | The menu button |
73
73
 
74
- The title of a sidebar screen never takes focus.
74
+ The title of a sidebar screen never takes focus. A move to another
75
+ screen moves no focus either. A screen reader hears the new screen's
76
+ title instead, as
77
+ [what a screen reader hears when the screen changes](./frame.md#what-a-screen-reader-hears-when-the-screen-changes)
78
+ says.
75
79
 
76
80
  Some parts go away, or turn inert, while they hold focus. godmin then
77
81
  moves focus to a part that stays, so the keyboard reader keeps their
@@ -83,10 +87,10 @@ place:
83
87
  the screen does not scroll, as
84
88
  [running an action over the picked rows](../lists.md#running-an-action-over-the-picked-rows)
85
89
  says.
86
- - The table or the footer of a list, with its rows and the busy bulk
87
- action button, which turn inert as a run reloads the list. The list
88
- region takes the focus at once, where WordPress drops it to the
89
- page, and the screen does not scroll either, as
90
+ - The table, the bulk bar or the footer of a list, with its rows and
91
+ the busy bulk action button, which turn inert as a run reloads the
92
+ list. The list region takes the focus at once, where WordPress drops
93
+ it to the page, and the screen does not scroll either, as
90
94
  [after a write of your own](./lists.md#after-a-write-of-your-own)
91
95
  says. While the list reloads, the next Tab from the list region
92
96
  goes to the first control of the list, such as its search field.
@@ -164,7 +168,9 @@ picture such as an icon, is never the name:
164
168
 
165
169
  The current page carries `aria-current="page"`. A sidebar row draws
166
170
  its highlight from that mark, so what the eye sees and what a screen
167
- reader hears always match. A page tab draws its underline from its
171
+ reader hears always match. A drilldown row never carries it, as
172
+ [the sidebar marks](./frame.md#the-sidebar-marks) says. A page tab
173
+ draws its underline from its
168
174
  `current` prop, which sets the same mark. A router link can set the
169
175
  mark on its own too, so [PageTabs](../screens.md#pagetabs) says how
170
176
  to keep the underline and the mark in step. A breadcrumb never carries
@@ -187,15 +193,18 @@ aloud when it changes.
187
193
 
188
194
  | Part | What a screen reader hears | Set up in |
189
195
  | --- | --- | --- |
196
+ | A new screen | Its title, assertively, once the path changes. Nothing on the first load | [What a screen reader hears when the screen changes](./frame.md#what-a-screen-reader-hears-when-the-screen-changes) |
190
197
  | A toast | Its message, politely. Never its action | [What a screen reader hears](./toasts.md#what-a-screen-reader-hears) |
191
198
  | A loading screen | The `label` sentence, from a visually hidden status. The spinner is hidden | [What a screen reader hears](./loading.md#what-a-screen-reader-hears) |
192
199
  | A list that loads | Nothing on its first load, as in WordPress. A table or a grid is marked busy on a later load | [What a screen reader hears](./loading.md#what-a-screen-reader-hears) |
193
200
  | A list after a run | The control the focus went back to. After the pressed row left, the checkbox of the row now in its place, by that row's title. With no checkbox, that row's title or actions menu button, and nothing new when the region keeps the focus | [Where focus goes](#where-focus-goes) |
194
201
  | A count beside a row | The `label` sentence, in place of the bare number | [A count beside a row](../framing-an-application.md#a-count-beside-a-row) |
195
202
  | An `ErrorNotice` | Its message, at once, as an alert | [ErrorNotice](../screens.md#errornotice) |
203
+ | A server message under a field | The server's words, at once, as the focus moves to the first field that fails | [A server message under a field](../screens.md#a-server-message-under-a-field) |
196
204
 
197
205
  Polite means the screen reader first finishes what it is saying. An
198
- alert breaks in at once. Keep `ErrorNotice` for a failure that has to
206
+ alert breaks in at once, and so does an assertive title. Keep
207
+ `ErrorNotice` for a failure that has to
199
208
  stay on screen until the reader acts, as
200
209
  [what goes in a toast](../loading-and-feedback.md#what-goes-in-a-toast)
201
210
  explains. [Announcements](../testing.md#announcements) shows how a
@@ -246,7 +255,7 @@ gives no label a fixed width:
246
255
  - The page tabs keep each label on one line. A tab row too long for
247
256
  its page scrolls and fades the edge it cuts.
248
257
 
249
- In a right-to-left language the chevrons, the sub menu slide and the
250
- fade of the tab row turn around, as
258
+ In a right-to-left language the chevrons, the sub menu slide, the
259
+ phone drawer and the fade of the tab row turn around, as
251
260
  [right-to-left languages](./layout.md#right-to-left-languages)
252
261
  explains.
@@ -62,7 +62,7 @@ The theme provider also checks contrast when it works out colors from a seed. It
62
62
  A raw color is a value written out, such as `#fff`, in place of a token. It stays the same whatever the seeds. `base.css` writes a few on purpose:
63
63
 
64
64
  - A toast paints raw colors too: a see-through black box, white text and a white focus line, the colors of the WordPress snackbar. [Colors, corners and shadow](./toasts.md#colors-corners-and-shadow) gives each value.
65
- - The backdrop is the dark layer behind the open drawer. It is `#000` at 0.5 opacity, as in the new WordPress admin. godmin sets the opacity through `--backdrop-opacity`. The `@wordpress/ui` drawer fades its black backdrop to that value, so the fade in and out still run.
65
+ - The backdrop is the dark layer behind the open drawer. It is `#000` at 0.5 opacity, as in the new WordPress admin. godmin sets the opacity through `--backdrop-opacity`, and fades the backdrop to it and back with the drawer, as [the drawer](./frame.md#the-drawer) times it.
66
66
  - Shadows are black at a low opacity. [Elevation](./radius-and-elevation.md#elevation) lists them.
67
67
  - The `#000` in `--godmin-page-tabs-fade` and `--godmin-page-tabs-fade-both` is a mask. The mask fades the ends of a long row of tabs. It paints nothing.
68
68
 
@@ -16,7 +16,7 @@ to change. The internal ones are not yours to read or change.
16
16
  The canvas is the panel that shows the current screen.
17
17
  [The frame](./layout.md#the-frame) and [the canvas](./layout.md#the-canvas)
18
18
  give the four sizes below, and
19
- [the sidebar slide](./motion.md#the-sidebar-slide) gives the two slide
19
+ [the sidebar slide](./frame.md#the-sidebar-slide) gives the two slide
20
20
  values. This table says where each one is set and what it changes.
21
21
 
22
22
  | Name | Set on | What it changes |
@@ -25,8 +25,8 @@ values. This table says where each one is set and what it changes.
25
25
  | `--godmin-canvas-margin` | `:root` | The space around the canvas |
26
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
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
- | `--godmin-navigation-slide-distance` | `:root` | How far a sidebar screen moves as it slides in |
29
- | `--godmin-navigation-slide-duration` | `:root` | How long that slide takes |
28
+ | `--godmin-navigation-slide-distance` | `:root` | How far a sidebar screen moves as it slides in, on a window `EDGE_BREAKPOINT` wide or wider |
29
+ | `--godmin-navigation-slide-duration` | `:root` | How long that slide takes, on the same windows |
30
30
 
31
31
  ## Where each one is set
32
32
 
@@ -1,6 +1,6 @@
1
1
  ---
2
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.
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
4
  ---
5
5
 
6
6
  A dialog stops the page to ask one thing. godmin draws two kinds on
@@ -34,8 +34,8 @@ page gives every value of how they look and behave.
34
34
  - The confirm button names the action, such as "Delete permanently".
35
35
  The other button reads "Cancel".
36
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".
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
39
 
40
40
  ## Size and place
41
41
 
@@ -83,7 +83,12 @@ page gives every value of how they look and behave.
83
83
  and the send button is solid in your accent color. A close icon
84
84
  sits beside the title. A confirm has no close icon.
85
85
  - A word too long for the card, such as a long link in a server
86
- message, breaks at the card's edge.
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.
87
92
 
88
93
  ## Motion
89
94
 
@@ -99,14 +104,13 @@ page gives every value of how they look and behave.
99
104
  ## While a write runs
100
105
 
101
106
  When `onConfirm` or `onSubmit` returns a promise, the dialog stays
102
- open until it ends.
107
+ open until it ends, or until the time limit runs out.
103
108
 
104
109
  - The main button shows a spinner over its hidden label and keeps its
105
110
  width. No dialog shows a word such as "Deleting…" or "Saving…".
106
111
  - Cancel and the close icon turn grey and stay reachable with Tab.
107
112
  - 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.
113
+ so a failure always has a place to show.
110
114
  - The fields stay as you drew them. If one must wait, pass a function
111
115
  as the children of `FormDialog`. It gets `busy`, so set the field
112
116
  `readOnly` while the write runs. Never set it `disabled`, since a
@@ -116,15 +120,66 @@ open until it ends.
116
120
  once. A press or an Enter after the dialog started to close sends
117
121
  nothing.
118
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
+
119
173
  ## When a dialog closes
120
174
 
121
175
  | What `onConfirm` or `onSubmit` does | The dialog |
122
176
  | --- | --- |
123
177
  | Returns nothing | Closes at once, and the write runs behind it |
124
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 |
125
180
  | Answers `{ error }`, at once or when its promise ends | Stays and says why |
126
181
  | 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 |
182
+ | Throws, or returns a promise that rejects before the limit runs out | Stays, and the error goes on to your app |
128
183
 
129
184
  Any other answer, such as the saved item, closes the dialog. godmin
130
185
  closes it itself, so call nothing from your handler to close it, and
@@ -149,6 +204,8 @@ does.
149
204
  - In a confirm `{ error }` draws the words under the buttons, at the
150
205
  end, in `--wpds-typography-font-size-sm` (12px). They go on the next
151
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.
152
209
  - A form dialog over several items closes, and one toast says how the
153
210
  run went, since a run can half work. A form over one item that
154
211
  failed stays and says why. `useDialogRun` does both.
@@ -233,8 +290,13 @@ does.
233
290
  - A confirm is an `alertdialog` and a form dialog a `dialog`. The
234
291
  title names it, and its description describes it.
235
292
  - A busy button says "Loading" once.
236
- - A failure inside a dialog is spoken at once.
293
+ - A failure inside a dialog, the time-out included, is spoken at once.
237
294
  - A toast under a dialog is still spoken, politely. Its action cannot
238
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.
239
301
  - While a dialog is open, a `role="alert"` of your own with no
240
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,7 +90,7 @@ 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
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 |
@@ -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.