@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.
- package/README.md +19 -9
- package/dist/admin-root.d.ts +4 -2
- package/dist/admin-root.js +6 -3
- package/dist/announcer-heading.d.ts +4 -0
- package/dist/announcer-heading.js +25 -0
- package/dist/base.css +36 -4
- package/dist/bulk-run.d.ts +2 -2
- package/dist/bulk-run.js +18 -2
- package/dist/confirm-dialog.d.ts +2 -2
- package/dist/confirm-dialog.js +3 -2
- package/dist/dialog-open.d.ts +16 -2
- package/dist/dialog-open.js +126 -5
- package/dist/drilldown-item.d.ts +5 -2
- package/dist/drilldown-item.js +14 -2
- package/dist/filter-offer.d.ts +5 -5
- package/dist/filter-offer.js +9 -9
- package/dist/focus-back.js +12 -2
- package/dist/form-dialog.d.ts +2 -2
- package/dist/form-dialog.js +3 -2
- package/dist/frame.d.ts +8 -4
- package/dist/frame.js +16 -6
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -2
- package/dist/list-chrome/es-ES.d.ts +1 -1
- package/dist/list-chrome/es-ES.js +11 -8
- package/dist/list-chrome/fr-FR.d.ts +1 -1
- package/dist/list-chrome/fr-FR.js +9 -1
- package/dist/navigation-item.d.ts +4 -2
- package/dist/navigation-item.js +2 -2
- package/dist/navigation-screen.js +10 -3
- package/dist/navigation.js +5 -1
- package/dist/page.d.ts +3 -2
- package/dist/page.js +23 -4
- package/dist/rejected-field.d.ts +25 -0
- package/dist/rejected-field.js +121 -0
- package/dist/rename-dialog.d.ts +2 -2
- package/dist/rename-dialog.js +1 -1
- package/dist/route-not-found.d.ts +5 -0
- package/dist/route-not-found.js +12 -0
- package/dist/router.d.ts +8 -2
- package/dist/router.js +10 -2
- package/dist/screen-title.d.ts +52 -0
- package/dist/screen-title.js +165 -0
- package/dist/stylelint.d.ts +1 -4
- package/dist/stylelint.js +4 -7
- package/dist/testing.d.ts +2 -2
- package/dist/testing.js +3 -3
- package/dist/vite.js +1 -0
- package/docs/build-and-versioning.md +109 -4
- package/docs/design-system/accessibility.md +18 -9
- package/docs/design-system/color.md +1 -1
- package/docs/design-system/custom-properties.md +3 -3
- package/docs/design-system/dialogs.md +71 -9
- package/docs/design-system/frame.md +276 -0
- package/docs/design-system/layout.md +24 -16
- package/docs/design-system/lists.md +17 -11
- package/docs/design-system/loading.md +20 -12
- package/docs/design-system/motion.md +41 -47
- package/docs/design-system/overview.md +8 -3
- package/docs/design-system/radius-and-elevation.md +2 -2
- package/docs/design-system/record-pages.md +9 -1
- package/docs/design-system/toasts.md +7 -1
- package/docs/framing-an-application.md +77 -23
- package/docs/lists.md +80 -39
- package/docs/overview.md +9 -3
- package/docs/screens.md +94 -3
- package/docs/testing.md +29 -0
- 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
|
|
87
|
-
action button, which turn inert as a run reloads the
|
|
88
|
-
region takes the focus at once, where WordPress drops
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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](./
|
|
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
|
-
-
|
|
38
|
-
"Delete
|
|
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.
|
|
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
|
|
15
|
-
|
|
16
|
-
|
|
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
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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.
|
|
62
|
-
|
|
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](./
|
|
148
|
-
page tabs where a tab is cut off, and the
|
|
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
|
|
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.
|