@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
@@ -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 as icons.
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 `--wpds-dimension-size-sm`
60
- (24px) wide, 48px, and the title starts there.
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 footer is busy.
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 on the busy
143
- button, the list region takes it as the list starts to reload, so a
144
- keyboard reader stays on the list, and the screen does not scroll.
145
- Here godmin goes beyond WordPress, which drops the focus to the
146
- page. A focus in the search field or the filters stays where it is
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: a quarter circle in the accent color that turns over a light
30
- grey ring.
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 click them
36
- or reach them with Tab until the next rows arrive.
37
- - After 400ms the rows and the footer pulse. Their opacity goes from
38
- 1 to `0.5` and back every 1s, on an `ease-in-out` curve. A load
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 `100vh` tall, the
75
- height of the window, as the frame is. So the spinner sits in the
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 and its footer stay at `0.5`
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. Toasts grow in and fade, and the toasts around them
8
- slide along. A loading screen that fills the canvas or stands outside
9
- the frame waits a moment, then fades in. godmin's stylesheet animates
10
- nothing else. It sets no transitions, so its own hover and focus
11
- looks change at once.
12
-
13
- Parts that WordPress packages draw keep the motion those packages
14
- give them. These include the drawer on a small screen, the spinners
15
- and the pulse of a list that loads. The dialogs move as
16
- [motion](./dialogs.md#motion) on the dialogs page says.
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 three
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 wait and the fade
33
- of a loading screen, and the rest of the toast motion. The sections
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
- The sidebar menu shows one screen at a time. The root screen holds
39
- the main rows, and each sub menu has a screen of its own. A
40
- drilldown row is a row with a chevron that opens a sub menu. Back is
41
- the link in the title row of a sub menu. When a drilldown row or Back
42
- changes the screen, the new screen slides in:
43
-
44
- - It starts `--godmin-navigation-slide-distance` (50px) to one side
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
- three things:
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
- Loading keeps its spinners turning, and a list holds its old rows
107
- still. [Reduced motion](./loading.md#reduced-motion) on the loading
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, and
97
- what changes for a reader who asks for less motion.
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
- Five more pages cover a single part each, how it looks and how it
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` 43.0.0 stays the
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 slides
149
- the sub menu in and moves the focus to Back. Back goes to `home`,
150
- slides the root screen in and puts the focus back on the Chats row.
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 a sub menu.
157
- Both take `icon` and the props of a TanStack `Link`, such as `to`,
158
- `params`, `className` and `onClick`. They draw their own list item,
159
- so put them inside a `NavigationList`. The screens page describes
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 closes when the reader opens another page.
247
- It stays open when a sub menu opens or Back closes one, so the reader
248
- can pick a row in it.
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." godmin translates them in
279
- the WordPress `default` text domain, as the design system does. The
280
- Spanish and French catalogues that `listChromeCatalogFor` returns
281
- hold them, so load it as
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
- With TanStack Router, `@gopherium/godmin/router` gives you the string
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 the declarations back with two hooks:
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 just passes
388
- `location` itself.
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.