@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
|
@@ -27,6 +27,11 @@ up. This page gives every value of how a list looks.
|
|
|
27
27
|
`--wpds-dimension-gap-lg`, so the two do not add up.
|
|
28
28
|
- The footer rests on the bottom edge of the canvas. Only the rows
|
|
29
29
|
scroll. The title, the tabs, the toolbar and the column headers stay.
|
|
30
|
+
- The footer holds the item count and the page buttons. The select
|
|
31
|
+
all box sits in the table head. While a row is ticked, the bulk bar
|
|
32
|
+
covers the table head: the select all box, how many items are
|
|
33
|
+
ticked, the bulk actions and Cancel. In a grid the bar sits above
|
|
34
|
+
the cards. DataViews draws it.
|
|
30
35
|
|
|
31
36
|
## Columns
|
|
32
37
|
|
|
@@ -36,7 +41,7 @@ up. This page gives every value of how a list looks.
|
|
|
36
41
|
columns in View options.
|
|
37
42
|
- From `DENSE_BREAKPOINT` (640px) up to `EDGE_BREAKPOINT` itself the
|
|
38
43
|
table keeps them too. There DataViews shows each row's actions in
|
|
39
|
-
its Actions menu only, and its bulk actions
|
|
44
|
+
its Actions menu only, and its bulk actions in one Actions menu.
|
|
40
45
|
- Below `DENSE_BREAKPOINT` a list from `useListView` shows its phone
|
|
41
46
|
layout, the DataViews list layout, with the fields `phoneFields`
|
|
42
47
|
names.
|
|
@@ -55,9 +60,10 @@ are. `Page` marks such a list region `godmin-page__list--wide`.
|
|
|
55
60
|
DataViews draws both.
|
|
56
61
|
- Wider than `EDGE_BREAKPOINT`, a table with checkboxes keeps the
|
|
57
62
|
checkbox column and the title column frozen at the start edge, as
|
|
58
|
-
in Jetpack Forms. The checkbox column is
|
|
59
|
-
`--wpds-dimension-padding-2xl` plus
|
|
60
|
-
(
|
|
63
|
+
in Jetpack Forms. The checkbox column is 40px wide, as DataViews
|
|
64
|
+
draws it: `--wpds-dimension-padding-2xl` (24px) plus
|
|
65
|
+
`--wpds-dimension-size-2xs` (16px). The title starts there, so it
|
|
66
|
+
lines up with the title of a table that fits.
|
|
61
67
|
- The title column keeps at least 280px and
|
|
62
68
|
`--wpds-dimension-padding-2xl` free at its end, where a line
|
|
63
69
|
`--wpds-border-width-xs` (1px) wide in
|
|
@@ -130,7 +136,7 @@ When a run over the picked rows changes them, as
|
|
|
130
136
|
[running an action over the picked rows](../lists.md#running-an-action-over-the-picked-rows)
|
|
131
137
|
shows:
|
|
132
138
|
|
|
133
|
-
- While the calls run, the bulk action button in the
|
|
139
|
+
- While the calls run, the bulk action button in the bulk bar is busy.
|
|
134
140
|
A row action with no dialog shows nothing yet, as in the WordPress
|
|
135
141
|
Site Editor.
|
|
136
142
|
- As the first call that works ends, the list starts to reload, as
|
|
@@ -139,12 +145,12 @@ shows:
|
|
|
139
145
|
nobody can click them. If the reload takes longer than a moment,
|
|
140
146
|
the rows pulse as on a later load. [A list](./loading.md#a-list)
|
|
141
147
|
gives how long the list waits and how the pulse looks.
|
|
142
|
-
- When the focus sat in the table or the footer, such as
|
|
143
|
-
button, the list region takes it as the list starts to
|
|
144
|
-
keyboard reader stays on the list, and the screen does
|
|
145
|
-
Here godmin goes beyond WordPress, which drops the focus
|
|
146
|
-
page. A focus in the search field or the filters stays where
|
|
147
|
-
while the calls run.
|
|
148
|
+
- When the focus sat in the table, the bulk bar or the footer, such as
|
|
149
|
+
on the busy button, the list region takes it as the list starts to
|
|
150
|
+
reload, so a keyboard reader stays on the list, and the screen does
|
|
151
|
+
not scroll. Here godmin goes beyond WordPress, which drops the focus
|
|
152
|
+
to the page. A focus in the search field or the filters stays where
|
|
153
|
+
it is while the calls run.
|
|
148
154
|
- As the last call ends, the toast shows, the busy button ends and a
|
|
149
155
|
confirm closes, as
|
|
150
156
|
[when a dialog closes](./dialogs.md#when-a-dialog-closes) says.
|
|
@@ -26,17 +26,17 @@ On the first load:
|
|
|
26
26
|
and the bottom of the canvas. The search box and the filters stay
|
|
27
27
|
on screen. The footer stays away until the first rows arrive.
|
|
28
28
|
- This spinner is the one of `@wordpress/components`, which DataViews
|
|
29
|
-
draws
|
|
30
|
-
|
|
29
|
+
draws. It draws the `Spinner` of `@wordpress/ui`, the same half
|
|
30
|
+
circle a loading screen shows, as [a screen](#a-screen) gives.
|
|
31
31
|
- The first rows replace the spinner at once.
|
|
32
32
|
|
|
33
33
|
On a later load, such as another page, a search or a new sort:
|
|
34
34
|
|
|
35
|
-
- The old rows and the footer stay on screen. Nobody can
|
|
36
|
-
or reach them with Tab until the next rows arrive.
|
|
37
|
-
- After 400ms the rows and the footer pulse
|
|
38
|
-
1 to `0.5` and back every 1s, on an
|
|
39
|
-
that ends sooner shows no pulse.
|
|
35
|
+
- The old rows, the bulk bar and the footer stay on screen. Nobody can
|
|
36
|
+
click them or reach them with Tab until the next rows arrive.
|
|
37
|
+
- After 400ms the rows and the footer pulse, and in a table the bulk
|
|
38
|
+
bar too. Their opacity goes from 1 to `0.5` and back every 1s, on an
|
|
39
|
+
`ease-in-out` curve. A load that ends sooner shows no pulse.
|
|
40
40
|
- When the last answer was empty, there are no old rows to keep. The
|
|
41
41
|
empty state stays on screen and pulses the same way after 400ms.
|
|
42
42
|
- The next rows replace the old ones at once.
|
|
@@ -71,9 +71,9 @@ When it shows and where it sits depend on what is around it:
|
|
|
71
71
|
in the middle, and it keeps `--wpds-dimension-padding-3xl` (32px)
|
|
72
72
|
free on every side.
|
|
73
73
|
- Outside the frame, before the sidebar and the canvas are drawn, it
|
|
74
|
-
waits and fades in the same way. It is at least `
|
|
75
|
-
|
|
76
|
-
middle of the window.
|
|
74
|
+
waits and fades in the same way. It is at least `100dvh` tall, the
|
|
75
|
+
window the browser shows, as the frame is. So the spinner sits in
|
|
76
|
+
the middle of the window.
|
|
77
77
|
|
|
78
78
|
## Before the script runs
|
|
79
79
|
|
|
@@ -130,6 +130,9 @@ These follow
|
|
|
130
130
|
screen loading, as above.
|
|
131
131
|
- The next page replaces the old one at once, with no fade and no
|
|
132
132
|
slide.
|
|
133
|
+
- Once the next page shows, a screen reader hears its title, as
|
|
134
|
+
[what a screen reader hears when the screen changes](./frame.md#what-a-screen-reader-hears-when-the-screen-changes)
|
|
135
|
+
says.
|
|
133
136
|
|
|
134
137
|
## What a screen reader hears
|
|
135
138
|
|
|
@@ -137,6 +140,11 @@ These follow
|
|
|
137
140
|
screen reader reads it politely. In the canvas and outside the
|
|
138
141
|
frame the status is there during the wait too. The spinner itself
|
|
139
142
|
is hidden.
|
|
143
|
+
- A `Page` that holds nothing but one `LoadingScreen`, with no
|
|
144
|
+
`aside`, waits a moment for its record before a screen reader hears
|
|
145
|
+
its title, as
|
|
146
|
+
[what a screen reader hears when the screen changes](./frame.md#what-a-screen-reader-hears-when-the-screen-changes)
|
|
147
|
+
says.
|
|
140
148
|
- A list says nothing while it loads for the first time, as in
|
|
141
149
|
WordPress. Its spinner is hidden from screen readers.
|
|
142
150
|
- During a later load a table or a grid is marked busy. A screen
|
|
@@ -150,8 +158,8 @@ reader who asks for less motion. While a list or a screen loads:
|
|
|
150
158
|
|
|
151
159
|
- Both spinners keep turning, as WordPress keeps them. A spinner that
|
|
152
160
|
stood still would look like a page that froze.
|
|
153
|
-
- A list does not pulse. Its old rows
|
|
154
|
-
opacity until the next rows arrive.
|
|
161
|
+
- A list does not pulse. Its old rows, its footer and the bulk bar of
|
|
162
|
+
a table stay at `0.5` opacity until the next rows arrive.
|
|
155
163
|
- A loading screen in the canvas or outside the frame keeps its wait,
|
|
156
164
|
since a wait is no motion, and then shows at once with no fade.
|
|
157
165
|
Inside a `Page`, a sidebar screen or a dialog nothing changes, since
|
|
@@ -1,75 +1,66 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Motion
|
|
3
|
-
description: The sidebar slide, the toast motion and the fade of a loading screen in a godmin admin, the design tokens that time them, and what changes when a reader asks for less motion.
|
|
3
|
+
description: The sidebar slide, the phone drawer, the toast motion and the fade of a loading screen in a godmin admin, the design tokens that time them, and what changes when a reader asks for less motion.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
godmin's own motion is short and small. The sidebar slides a new
|
|
7
|
-
menu screen in
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
[
|
|
7
|
+
menu screen in, and the drawer on a small screen slides in and out.
|
|
8
|
+
Toasts grow in and fade, and the toasts around them slide along. A
|
|
9
|
+
loading screen that fills the canvas or stands outside the frame
|
|
10
|
+
waits a moment, then fades in. godmin's stylesheet animates nothing
|
|
11
|
+
else. Besides the drawer, only the shade and the focus ring of a page
|
|
12
|
+
tab fade, over 0.1s. Every other hover and focus look changes at
|
|
13
|
+
once.
|
|
14
|
+
|
|
15
|
+
godmin times the drawer itself, as
|
|
16
|
+
[the drawer](./frame.md#the-drawer) on the frame page gives. Other
|
|
17
|
+
parts that WordPress packages draw keep the motion those packages
|
|
18
|
+
give them, such as the spinners and the pulse of a list that loads.
|
|
19
|
+
The dialogs move as [motion](./dialogs.md#motion) on the dialogs page
|
|
20
|
+
says.
|
|
17
21
|
|
|
18
22
|
## The tokens
|
|
19
23
|
|
|
20
24
|
A design token is a value the WordPress Design System names, written
|
|
21
25
|
as a CSS custom property. A custom property is a CSS variable. A
|
|
22
26
|
duration is how long an animation takes. An easing is the curve its
|
|
23
|
-
speed follows from start to end. godmin times its motion with
|
|
27
|
+
speed follows from start to end. godmin times its motion with four
|
|
24
28
|
design tokens:
|
|
25
29
|
|
|
26
30
|
| Token | Value | What it times |
|
|
27
31
|
| --- | --- | --- |
|
|
28
32
|
| `--wpds-motion-duration-lg` | 300ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
33
|
+
| `--wpds-motion-duration-md` | 200ms | The phone drawer, see [The drawer](./frame.md#the-drawer) |
|
|
29
34
|
| `--wpds-motion-duration-sm` | 100ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
30
35
|
| `--wpds-motion-duration-xs` | 50ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
31
36
|
|
|
32
|
-
Some values have no token: the sidebar slide, the
|
|
33
|
-
of a loading screen, and the rest of
|
|
37
|
+
Some values have no token: the sidebar slide, the curve of the
|
|
38
|
+
drawer, the wait and the fade of a loading screen, and the rest of
|
|
39
|
+
the toast motion. The sections
|
|
34
40
|
below cover them.
|
|
35
41
|
|
|
36
42
|
## The sidebar slide
|
|
37
43
|
|
|
38
|
-
|
|
39
|
-
the
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
and moves into place. As it moves, it fades from transparent to
|
|
46
|
-
fully visible.
|
|
47
|
-
- It takes `--godmin-navigation-slide-duration` (140ms). Its speed
|
|
48
|
-
follows the CSS `ease-in-out` curve, which starts slow and ends
|
|
49
|
-
slow. It plays once, with no delay.
|
|
50
|
-
- A sub menu comes in from the side the text ends on. That is the
|
|
51
|
-
right in a left-to-right language and the left in a right-to-left
|
|
52
|
-
one. Back brings the screen in from the other side.
|
|
53
|
-
[Right-to-left languages](./layout.md#right-to-left-languages) says
|
|
54
|
-
where godmin reads the direction from.
|
|
55
|
-
|
|
56
|
-
These are the numbers the WordPress Site Editor uses for its own
|
|
57
|
-
sidebar slide.
|
|
58
|
-
|
|
59
|
-
The slide plays only after a drilldown row or Back. It does not play
|
|
60
|
-
on the first load, after a row that keeps the same screen, after a
|
|
61
|
-
link elsewhere on the page, or after the browser's Back button. A
|
|
62
|
-
sub menu whose code loads late slides in once that code has arrived.
|
|
63
|
-
|
|
64
|
-
Only the screen moves. The sidebar footer stays still under it, and
|
|
65
|
-
the sidebar hides anything that slides past its sides.
|
|
66
|
-
[Where focus goes](./accessibility.md#where-focus-goes) says where
|
|
67
|
-
the focus lands after the slide.
|
|
44
|
+
When a drilldown row or Back in the sidebar changes the menu screen,
|
|
45
|
+
the new screen slides in from one side and fades in, as in the
|
|
46
|
+
sidebar of the WordPress Site Editor. It plays on a
|
|
47
|
+
wide window only, and never after the browser's Back button.
|
|
48
|
+
[The sidebar slide](./frame.md#the-sidebar-slide) on the frame page
|
|
49
|
+
gives how far it moves, how long it takes, its curve and when it
|
|
50
|
+
plays.
|
|
68
51
|
|
|
69
52
|
You may change the slide through its two custom properties.
|
|
70
53
|
[Where each one is set](./custom-properties.md#where-each-one-is-set)
|
|
71
54
|
shows how.
|
|
72
55
|
|
|
56
|
+
## The phone drawer
|
|
57
|
+
|
|
58
|
+
On a small screen the sidebar sits in a drawer. It slides in from
|
|
59
|
+
the start edge and back out, and its backdrop fades with it. A swipe
|
|
60
|
+
ends as fast as the finger let go.
|
|
61
|
+
[The drawer](./frame.md#the-drawer) on the frame page gives its time
|
|
62
|
+
and its curve.
|
|
63
|
+
|
|
73
64
|
## Toasts
|
|
74
65
|
|
|
75
66
|
Toasts move as the WordPress snackbar does. An arriving toast grows
|
|
@@ -90,7 +81,7 @@ long each one waits and how it moves.
|
|
|
90
81
|
|
|
91
82
|
A reader can ask their system for less motion. The browser then
|
|
92
83
|
reports `prefers-reduced-motion: reduce` to CSS, and godmin changes
|
|
93
|
-
|
|
84
|
+
five things:
|
|
94
85
|
|
|
95
86
|
- A loading screen that fills the canvas or stands outside the frame
|
|
96
87
|
shows at once when its wait ends, with no fade. Its wait stays, so
|
|
@@ -102,7 +93,10 @@ three things:
|
|
|
102
93
|
- The sidebar slide lasts 0s, as in the WordPress Site Editor, even
|
|
103
94
|
when you set your own slide duration. It does not play, and the new
|
|
104
95
|
screen shows at once in its place.
|
|
96
|
+
- The phone drawer and its backdrop open and close at once.
|
|
97
|
+
- The shade and the focus ring of a page tab show at once.
|
|
105
98
|
|
|
106
|
-
|
|
107
|
-
|
|
99
|
+
[Reduced motion](./frame.md#reduced-motion) on the frame page says
|
|
100
|
+
what the frame does. Loading keeps its spinners turning, and a list
|
|
101
|
+
holds its old rows still. [Reduced motion](./loading.md#reduced-motion) on the loading
|
|
108
102
|
page says what loading does.
|
|
@@ -93,14 +93,15 @@ layer.
|
|
|
93
93
|
raised.
|
|
94
94
|
- [Typography](./typography.md): the font, the text sizes and
|
|
95
95
|
weights, and the heading outline.
|
|
96
|
-
- [Motion](./motion.md): the motion tokens, the sidebar slide
|
|
97
|
-
what changes for a reader who asks
|
|
96
|
+
- [Motion](./motion.md): the motion tokens, the sidebar slide and
|
|
97
|
+
the phone drawer in short, and what changes for a reader who asks
|
|
98
|
+
for less motion.
|
|
98
99
|
- [Accessibility](./accessibility.md): focus rings, where focus goes,
|
|
99
100
|
landmarks, what a screen reader hears, and text length.
|
|
100
101
|
- [Custom properties](./custom-properties.md): every godmin custom
|
|
101
102
|
property, where it is set and what it changes.
|
|
102
103
|
|
|
103
|
-
|
|
104
|
+
Six more pages cover a single part each, how it looks and how it
|
|
104
105
|
behaves:
|
|
105
106
|
|
|
106
107
|
- [Toasts](./toasts.md): where a toast sits, how it looks, how long it
|
|
@@ -117,3 +118,7 @@ behaves:
|
|
|
117
118
|
- [Dialogs](./dialogs.md): when an action asks first, how a confirm
|
|
118
119
|
looks and moves, what happens while its write runs, where a failure
|
|
119
120
|
shows, and what a keyboard or a screen reader meets.
|
|
121
|
+
- [Frame](./frame.md): how the frame changes as the reader moves
|
|
122
|
+
between screens, the sidebar slide, the drawer, what a screen reader
|
|
123
|
+
hears, the sidebar marks, the frame on a phone, and why there is no
|
|
124
|
+
full canvas.
|
|
@@ -69,7 +69,7 @@ roundness. One preset sets all five radius steps:
|
|
|
69
69
|
Without the prop the preset is `subtle`.
|
|
70
70
|
|
|
71
71
|
```tsx
|
|
72
|
-
<AdminRoot cornerRadius="moderate">
|
|
72
|
+
<AdminRoot cornerRadius="moderate" writeTimeout={settings.writeTimeout}>
|
|
73
73
|
<YourApp />
|
|
74
74
|
</AdminRoot>
|
|
75
75
|
```
|
|
@@ -107,7 +107,7 @@ show depth:
|
|
|
107
107
|
| --- | --- |
|
|
108
108
|
| The canvas | `0 1px 2px rgb(0 0 0 / 0.08)`. None below `EDGE_BREAKPOINT` |
|
|
109
109
|
| A toast | The WordPress small elevation, the one the snackbar uses. [Colors, corners and shadow](./toasts.md#colors-corners-and-shadow) writes out its four layers |
|
|
110
|
-
| The navigation drawer | `2px 0 8px rgba(0, 0, 0, 0.2)`, the shadow of the phone sidebar in WordPress's new admin |
|
|
110
|
+
| The navigation drawer | `2px 0 8px rgba(0, 0, 0, 0.2)`, the shadow of the phone sidebar in WordPress's new admin. In a right-to-left language it turns to `-2px 0 8px rgba(0, 0, 0, 0.2)`, so it falls on the inner edge of the drawer, which opens at the right as [the drawer](./frame.md#the-drawer) says |
|
|
111
111
|
|
|
112
112
|
A bleed canvas keeps the canvas shadow. The sidebar has no shadow.
|
|
113
113
|
Dialogs, menus and popovers keep the shadow their design system
|
|
@@ -165,7 +165,9 @@ every value of how it looks.
|
|
|
165
165
|
[what goes in a toast](../loading-and-feedback.md#what-goes-in-a-toast)
|
|
166
166
|
says. Name what failed, then give the server's words, as in
|
|
167
167
|
`Could not save the invoice. The customer is closed.`
|
|
168
|
-
- A server message about one field shows under that field
|
|
168
|
+
- A server message about one field shows under that field, as
|
|
169
|
+
[a server message under a field](../screens.md#a-server-message-under-a-field)
|
|
170
|
+
shows.
|
|
169
171
|
- A check made before sending shows under its field. Move the focus
|
|
170
172
|
to the first field that failed, so it comes into view inside its
|
|
171
173
|
column.
|
|
@@ -182,6 +184,12 @@ every value of how it looks.
|
|
|
182
184
|
one `LoadingScreen`, with no `aside`.
|
|
183
185
|
[A screen](./loading.md#a-screen) gives how it looks. Breadcrumbs
|
|
184
186
|
stay, and the title names the kind of record.
|
|
187
|
+
- Make that `LoadingScreen` the `Page`'s own child, not one inside a
|
|
188
|
+
wrapper. Only then does the page hold its title while the record
|
|
189
|
+
loads, so a screen reader hears the record's name once it loads, or
|
|
190
|
+
the kind of record when it takes too long, as
|
|
191
|
+
[what a screen reader hears when the screen changes](./frame.md#what-a-screen-reader-hears-when-the-screen-changes)
|
|
192
|
+
says.
|
|
185
193
|
- A part that loads on its own shows its `LoadingScreen` in its
|
|
186
194
|
column, at the top and centred across that column.
|
|
187
195
|
- Show one `LoadingScreen` at a time, since each one speaks.
|
|
@@ -90,7 +90,7 @@ whatever seeds you pick.
|
|
|
90
90
|
- A toast with no action stays 6 seconds. `dismissAfter` changes it.
|
|
91
91
|
- A toast with an action stays 10 seconds, time to read the message
|
|
92
92
|
and then act. `actionDismissAfter` changes it.
|
|
93
|
-
- WordPress's own snackbar in `@wordpress/components`
|
|
93
|
+
- WordPress's own snackbar in `@wordpress/components` 44.0.0 stays the
|
|
94
94
|
same 6 seconds with no action and 10 seconds with one.
|
|
95
95
|
- Each toast keeps its own timer. So a toast a screen raises as it
|
|
96
96
|
mounts leaves on time even under React strict mode, which mounts the
|
|
@@ -182,6 +182,12 @@ keyboard with the action.
|
|
|
182
182
|
The region itself is not a live region, so nothing is read twice.
|
|
183
183
|
- Never the action. A reader who moves into the toast finds the action
|
|
184
184
|
by its label.
|
|
185
|
+
- A click that raises a toast and opens another screen puts the
|
|
186
|
+
toast's message in the polite live region of `speak` first. Two
|
|
187
|
+
animation frames later the title of the new screen takes its place,
|
|
188
|
+
as
|
|
189
|
+
[what a screen reader hears when the screen changes](./frame.md#what-a-screen-reader-hears-when-the-screen-changes)
|
|
190
|
+
says.
|
|
185
191
|
- A toast with no action is a button named by its message. After the
|
|
186
192
|
name the screen reader reads the hint `dismissLabel`, which says
|
|
187
193
|
"Dismiss this notice" unless your app passes its own words. No
|
|
@@ -20,7 +20,8 @@ same two names.
|
|
|
20
20
|
|
|
21
21
|
A region exists because you render its element. There is no
|
|
22
22
|
`showSidebar` flag, so an application without navigation simply does
|
|
23
|
-
not render a `Frame.Sidebar`.
|
|
23
|
+
not render a `Frame.Sidebar`. That frame is still not a full canvas,
|
|
24
|
+
as [no full canvas](./design-system/frame.md#no-full-canvas) says.
|
|
24
25
|
|
|
25
26
|
Every component's props interface is exported under its own name,
|
|
26
27
|
`FrameRootProps`, `FrameSidebarProps` and `FrameCanvasProps`, for when
|
|
@@ -64,7 +65,7 @@ Put `Navigation` in the sidebar and give it your rows as data:
|
|
|
64
65
|
```tsx
|
|
65
66
|
import { Link, Outlet } from '@tanstack/react-router'
|
|
66
67
|
import { Frame } from '@gopherium/godmin'
|
|
67
|
-
import { Navigation, useCanvas, useFrameLocation } from '@gopherium/godmin/router'
|
|
68
|
+
import { Navigation, useCanvas, useFrameLocation, useShownPath } from '@gopherium/godmin/router'
|
|
68
69
|
import type { MenuItem } from '@gopherium/godmin/router'
|
|
69
70
|
import { can, useSession } from '@gopherium/react-auth'
|
|
70
71
|
import { AccountPanel } from '@gopherium/react-auth/wpds'
|
|
@@ -79,7 +80,7 @@ const menu: MenuItem[] = [
|
|
|
79
80
|
function Layout() {
|
|
80
81
|
const user = useSession().data
|
|
81
82
|
return (
|
|
82
|
-
<Frame.Root location={useFrameLocation()}>
|
|
83
|
+
<Frame.Root location={useFrameLocation()} shownPath={useShownPath()} appName="MyApp">
|
|
83
84
|
<Frame.Sidebar footer={<AccountPanel />}>
|
|
84
85
|
<Navigation
|
|
85
86
|
title="MyApp"
|
|
@@ -103,11 +104,17 @@ function Layout() {
|
|
|
103
104
|
- `can` tells whether the reader holds a capability. See
|
|
104
105
|
[hiding rows](#hiding-rows-a-reader-cannot-open).
|
|
105
106
|
|
|
107
|
+
`shownPath` and `appName` on `Frame.Root` make the frame speak the
|
|
108
|
+
title of each new screen and set the browser tab title, as
|
|
109
|
+
[routes and the frame](#routes-and-the-frame) says.
|
|
110
|
+
|
|
106
111
|
Each row is a link with its icon, a glyph from `@wordpress/icons`,
|
|
107
112
|
then its label. A row with no icon keeps a blank in its place when
|
|
108
113
|
other rows have one, so the labels line up. The row of the page on
|
|
109
114
|
screen is highlighted, and it stays highlighted on every address
|
|
110
|
-
under it, so Posts stays highlighted on `/posts/new`.
|
|
115
|
+
under it, so Posts stays highlighted on `/posts/new`. A row that
|
|
116
|
+
opens a sub menu never is, as
|
|
117
|
+
[the sidebar marks](./design-system/frame.md#the-sidebar-marks) says.
|
|
111
118
|
|
|
112
119
|
`Navigation` needs a `Frame.Root` above it, which holds what the
|
|
113
120
|
sidebar parts share.
|
|
@@ -145,18 +152,28 @@ function ChatsMenu() {
|
|
|
145
152
|
```
|
|
146
153
|
|
|
147
154
|
Nothing else is needed. The Chats row of `menu` opens that route, so
|
|
148
|
-
it draws as a `DrilldownItem`, with a chevron. A click on it
|
|
149
|
-
the sub menu
|
|
150
|
-
|
|
155
|
+
it draws as a `DrilldownItem`, with a chevron. A click on it opens
|
|
156
|
+
the sub menu and moves the focus to Back. Back goes to `home`, brings
|
|
157
|
+
the root screen back and puts the focus back on the Chats row. On a
|
|
158
|
+
wide window each new sidebar screen slides in, as
|
|
159
|
+
[the sidebar slide](./design-system/frame.md#the-sidebar-slide) says.
|
|
151
160
|
In a right-to-left language the chevrons and the slide turn around.
|
|
152
161
|
The slide does not play when the system asks for reduced motion.
|
|
153
162
|
|
|
163
|
+
Point a drilldown row at the address its sub menu lands on. A row
|
|
164
|
+
whose address sends the reader on to another one, such as `/chats`
|
|
165
|
+
sending on to `/chats/inbox`, plays no slide and gives Back no focus.
|
|
166
|
+
|
|
154
167
|
`NavigationList` draws the rows of `items` first, then the rows you
|
|
155
168
|
draw yourself as its children. Draw a row yourself with
|
|
156
|
-
`NavigationItem`, or with `DrilldownItem` when it opens
|
|
157
|
-
|
|
158
|
-
`
|
|
159
|
-
|
|
169
|
+
`NavigationItem`, or with `DrilldownItem` when it opens another sub
|
|
170
|
+
menu. A row that points at the sub menu already shown is a
|
|
171
|
+
`NavigationItem`, since a drilldown row never shows as current. Both
|
|
172
|
+
take `icon` and the props of a TanStack `Link`, such as `to`,
|
|
173
|
+
`params`, `className` and `onClick`. `DrilldownItem` takes neither
|
|
174
|
+
`activeProps` nor `activeOptions`, since it is never current. They
|
|
175
|
+
draw their own list item, so put them inside a `NavigationList`. The
|
|
176
|
+
screens page describes
|
|
160
177
|
[`NavigationScreen`](./screens.md#navigationscreen).
|
|
161
178
|
|
|
162
179
|
### Hiding rows a reader cannot open
|
|
@@ -243,9 +260,12 @@ the top bar and the drawer, and
|
|
|
243
260
|
[the canvas](./design-system/layout.md#the-canvas) gives its padding.
|
|
244
261
|
|
|
245
262
|
The drawer looks like the phone sidebar of WordPress's new admin and
|
|
246
|
-
dims the page under it. It
|
|
247
|
-
|
|
248
|
-
|
|
263
|
+
dims the page under it. It slides in from the start edge and back
|
|
264
|
+
out, on a timing of its own, as
|
|
265
|
+
[the drawer](./design-system/frame.md#the-drawer) gives. It closes
|
|
266
|
+
when the reader opens another page. It stays open when a sub menu
|
|
267
|
+
opens or Back closes one, so the reader can pick a row in it. On a
|
|
268
|
+
phone a sub menu shows at once inside it, with no slide.
|
|
249
269
|
|
|
250
270
|
Two `Frame.Sidebar` props exist for the top bar:
|
|
251
271
|
|
|
@@ -275,10 +295,16 @@ The frame and the sidebar draw a few words of their own: "Back",
|
|
|
275
295
|
The last one names a close button at the end of the drawer, which
|
|
276
296
|
only a screen reader meets. `ListNoResults` draws two more: "No
|
|
277
297
|
results found" and the line under it, "Try adjusting your search or
|
|
278
|
-
filters to find what you're looking for."
|
|
279
|
-
the
|
|
280
|
-
|
|
281
|
-
|
|
298
|
+
filters to find what you're looking for." The tab title puts the
|
|
299
|
+
screen title and the app name together as `%1$s ‹ %2$s`, and the not
|
|
300
|
+
found screen of `routerDefaults()` says "Route not found" with the
|
|
301
|
+
line "The page you're looking for does not exist". A dialog whose
|
|
302
|
+
write ran past its time limit says WordPress's words, "Could not get
|
|
303
|
+
a valid response from the server.", or "Unable to connect. Please
|
|
304
|
+
check your Internet connection." while the browser is offline.
|
|
305
|
+
godmin translates them in the WordPress `default` text domain, as the design system
|
|
306
|
+
does. The Spanish and French catalogues that `listChromeCatalogFor`
|
|
307
|
+
returns hold them, so load it as
|
|
282
308
|
[the list chrome](./lists.md#the-list-chrome-in-spanish) shows.
|
|
283
309
|
|
|
284
310
|
## Coloring the regions
|
|
@@ -315,6 +341,9 @@ values:
|
|
|
315
341
|
- `bleed` removes it, for a screen that manages its own edges, such
|
|
316
342
|
as a full-height table or a two-pane chat view.
|
|
317
343
|
|
|
344
|
+
There is no full canvas mode, as
|
|
345
|
+
[no full canvas](./design-system/frame.md#no-full-canvas) says.
|
|
346
|
+
|
|
318
347
|
## Notices for the whole application
|
|
319
348
|
|
|
320
349
|
`Frame.Canvas` takes `notices`, for messages that belong to the whole
|
|
@@ -346,18 +375,35 @@ drawer closes. It works for links a plugin added too, because nothing
|
|
|
346
375
|
has to be registered. This is also why the main entry point imports
|
|
347
376
|
no router.
|
|
348
377
|
|
|
349
|
-
|
|
378
|
+
Two more props of `Frame.Root` tell the reader where they are:
|
|
379
|
+
|
|
380
|
+
- `shownPath` is the path the router has finished showing, once the
|
|
381
|
+
new screen has been drawn. When it changes, the frame speaks the
|
|
382
|
+
title of the new screen, as
|
|
383
|
+
[what a screen reader hears when the screen changes](./design-system/frame.md#what-a-screen-reader-hears-when-the-screen-changes)
|
|
384
|
+
says. Without it the frame speaks nothing.
|
|
385
|
+
- `appName` is the name of your app. The frame sets the browser tab
|
|
386
|
+
title to the screen title and that name, as
|
|
387
|
+
[the tab title](./design-system/frame.md#the-tab-title) says.
|
|
388
|
+
Without it the frame leaves the tab title alone.
|
|
389
|
+
|
|
390
|
+
The frame compares the path of `location` with `shownPath`. While the
|
|
391
|
+
two differ, the reader is still on the way to the next screen, so the
|
|
392
|
+
first load does not end then.
|
|
393
|
+
|
|
394
|
+
With TanStack Router, `@gopherium/godmin/router` gives you the strings
|
|
350
395
|
and lets each route declare the canvas it wants:
|
|
351
396
|
|
|
352
397
|
```tsx
|
|
353
398
|
createRoute({ getParentRoute: () => rootRoute, path: 'threads/$id', staticData: { canvas: 'bleed' } })
|
|
354
399
|
```
|
|
355
400
|
|
|
356
|
-
Read
|
|
401
|
+
Read them back with three hooks:
|
|
357
402
|
|
|
358
403
|
```tsx
|
|
359
404
|
const mode = useCanvas() // hand this to Frame.Canvas
|
|
360
405
|
const pathname = useFrameLocation() // hand this to Frame.Root
|
|
406
|
+
const shownPath = useShownPath() // hand this to Frame.Root
|
|
361
407
|
```
|
|
362
408
|
|
|
363
409
|
When routes nest, the deepest match that declares a canvas wins,
|
|
@@ -368,7 +414,8 @@ out. Only when no matched route declares anything does `useCanvas`
|
|
|
368
414
|
fall back to `padded`.
|
|
369
415
|
|
|
370
416
|
`useFrameLocation` answers the path followed by the search, so the
|
|
371
|
-
drawer also closes when only the search changes.
|
|
417
|
+
drawer also closes when only the search changes. `useShownPath`
|
|
418
|
+
answers the path alone, so no title is spoken then.
|
|
372
419
|
|
|
373
420
|
`routerDefaults()` returns the options WordPress's new admin gives
|
|
374
421
|
the same router. Spread them into `createRouter`:
|
|
@@ -382,7 +429,14 @@ keyboard reaches it.
|
|
|
382
429
|
[Moving between pages](./design-system/loading.md#moving-between-pages)
|
|
383
430
|
says what the reader sees while it loads.
|
|
384
431
|
|
|
432
|
+
An address no route serves then shows the not found screen of
|
|
433
|
+
WordPress's new admin, a `Page` titled "Route not found" with the
|
|
434
|
+
line "The page you're looking for does not exist". Its title is an
|
|
435
|
+
`h2`, the level a `Page` takes beside the sidebar menu. A route's own
|
|
436
|
+
`notFoundComponent` still wins.
|
|
437
|
+
|
|
385
438
|
`@tanstack/react-router` is an optional peer dependency, any 1.x
|
|
386
439
|
release from 1.170.44, needed only for this entry point. The main entry point
|
|
387
|
-
never imports it, so an application on another router
|
|
388
|
-
`location`
|
|
440
|
+
never imports it, so an application on another router passes the
|
|
441
|
+
strings itself: in `location` the address it is moving to, and in
|
|
442
|
+
`shownPath` the path it shows once the new screen has drawn.
|