@gopherium/godmin 0.30.0 → 0.31.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/dist/page.js CHANGED
@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  /* oxlint-disable react/only-export-components -- the page kit ships its parts
3
3
  beside the type they share. */
4
4
  import { Button, Notice, Stack, Text } from '@wordpress/ui';
5
- import { createContext, useContext, useImperativeHandle, useRef } from 'react';
5
+ import { Children, createContext, useContext, useImperativeHandle, useRef } from 'react';
6
6
  import { useWideList } from './wide-list.js';
7
7
  /** The level of the title of the Page around a section title, 1 outside any Page. */
8
8
  const PageLevelContext = createContext(1);
@@ -41,6 +41,14 @@ export function SectionTitle({ children, level = 2, id, tabIndex, }) {
41
41
  const Heading = headingTag(level + pageLevel - 1);
42
42
  return (_jsx(Text, { variant: level === 2 ? 'heading-lg' : 'heading-md', render: _jsx(Heading, {}), id: id, tabIndex: tabIndex, children: children }));
43
43
  }
44
+ /**
45
+ * Returns the role and the name of a region given a label.
46
+ * @param label - The name of the region.
47
+ * @returns The role and the name, or nothing with no label.
48
+ */
49
+ function namedRegion(label) {
50
+ return label === undefined ? {} : { role: 'region', 'aria-label': label };
51
+ }
44
52
  /**
45
53
  * Returns the props that let code focus a list with a name or a ref, and name a list region given a label.
46
54
  * @param label - The name of the list region.
@@ -49,7 +57,7 @@ export function SectionTitle({ children, level = 2, id, tabIndex, }) {
49
57
  */
50
58
  function regionOf(label, reached) {
51
59
  const focus = label === undefined && !reached ? {} : { tabIndex: -1 };
52
- return label === undefined ? focus : { ...focus, role: 'region', 'aria-label': label };
60
+ return { ...focus, ...namedRegion(label) };
53
61
  }
54
62
  /**
55
63
  * Renders the list region of a page, marked wide while its DataViews table is wider than its space.
@@ -62,26 +70,45 @@ function ListRegion({ label, listRef, children, }) {
62
70
  useImperativeHandle(listRef, () => own.current, []);
63
71
  return (_jsx("div", { className: wide ? 'godmin-page__list godmin-page__list--wide' : 'godmin-page__list', ref: own, ...regionOf(label, listRef !== undefined), children: children }));
64
72
  }
73
+ /**
74
+ * Tells whether a page has breadcrumbs to draw.
75
+ * @param breadcrumbs - What the page was given.
76
+ * @returns Whether it holds anything that renders.
77
+ */
78
+ function hasBreadcrumbs(breadcrumbs) {
79
+ return Children.toArray(breadcrumbs).length > 0;
80
+ }
81
+ /**
82
+ * Renders the title of a page, after its breadcrumbs when it has them.
83
+ * @param props - The title, its heading level and the breadcrumbs.
84
+ * @returns The title, alone or after its breadcrumbs.
85
+ */
86
+ function PageHeading({ title, level, breadcrumbs }) {
87
+ if (!hasBreadcrumbs(breadcrumbs)) {
88
+ return _jsx(PageTitle, { level: level, children: title });
89
+ }
90
+ return (_jsxs("div", { className: "godmin-page__heading", children: [breadcrumbs, _jsx(PageTitle, { level: level, children: title })] }));
91
+ }
65
92
  /**
66
93
  * Renders a screen: a header with the title, actions and subtitle, then optional tabs and the content.
67
- * @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class, title level
68
- * and content.
94
+ * @param props - The title, subtitle, actions, tabs, aside and its name, breadcrumbs, list flag, list name and ref,
95
+ * extra class, title level and content.
69
96
  * @returns The page element.
70
97
  */
71
- export function Page({ title, subtitle, actions, tabs, aside, list = false, listLabel, listRef, className, headingLevel = 1, children, }) {
98
+ export function Page({ title, subtitle, actions, tabs, aside, asideLabel, breadcrumbs, list = false, listLabel, listRef, className, headingLevel = 1, children, }) {
72
99
  const classes = className === undefined ? 'godmin-page' : `godmin-page ${className}`;
73
- return (_jsx(PageLevelContext.Provider, { value: headingLevel, children: _jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "column", render: _jsx("header", {}), className: "godmin-page__header", children: [_jsxs(Stack, { direction: "row", wrap: "wrap", gap: "md", align: "center", justify: "space-between", className: "godmin-page__head", children: [_jsx(PageTitle, { level: headingLevel, children: title }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), subtitle !== undefined && (_jsx(Text, { variant: "body-md", render: _jsx("p", {}), className: "godmin-page__subtitle", children: subtitle }))] }), tabs !== undefined && _jsx("div", { className: "godmin-page__tabs", children: tabs }), _jsx(PageBody, { aside: aside, children: list ? (_jsx(ListRegion, { label: listLabel, listRef: listRef, children: children })) : (children) })] }) }));
100
+ return (_jsx(PageLevelContext.Provider, { value: headingLevel, children: _jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "column", render: _jsx("header", {}), className: "godmin-page__header", children: [_jsxs(Stack, { direction: "row", wrap: "wrap", gap: "md", align: "center", justify: "space-between", className: "godmin-page__head", children: [_jsx(PageHeading, { title: title, level: headingLevel, breadcrumbs: breadcrumbs }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), subtitle !== undefined && (_jsx(Text, { variant: "body-md", render: _jsx("p", {}), className: "godmin-page__subtitle", children: subtitle }))] }), tabs !== undefined && _jsx("div", { className: "godmin-page__tabs", children: tabs }), _jsx(PageBody, { aside: aside, asideLabel: asideLabel, children: list ? (_jsx(ListRegion, { label: listLabel, listRef: listRef, children: children })) : (children) })] }) }));
74
101
  }
75
102
  /**
76
103
  * Renders a page's content, beside its aside when it has one.
77
- * @param props - The content and the optional aside.
104
+ * @param props - The content, the optional aside and the name of the aside.
78
105
  * @returns The content alone, or a main column followed by the aside.
79
106
  */
80
- function PageBody({ aside, children }) {
107
+ function PageBody({ aside, asideLabel, children }) {
81
108
  if (aside === undefined) {
82
109
  return children;
83
110
  }
84
- return (_jsxs("div", { className: "godmin-page__split", children: [_jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__main", children: children }), _jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__aside", children: aside })] }));
111
+ return (_jsxs("div", { className: "godmin-page__split", children: [_jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__main", children: children }), _jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__aside", ...namedRegion(asideLabel), children: aside })] }));
85
112
  }
86
113
  /**
87
114
  * Renders a failure message that a screen reader announces.
@@ -70,7 +70,7 @@ fallback values.
70
70
 
71
71
  Each godmin release supports one design system window, written out
72
72
  in full in its peer ranges as the first version it accepts and the
73
- first one it refuses, such as `>=0.24.0 <0.25.0`. The window moves
73
+ first one it refuses, such as `>=0.25.0 <0.26.0`. The window moves
74
74
  forward with the design system and never widens, so no release
75
75
  accepts two incompatible generations at once.
76
76
 
@@ -89,14 +89,14 @@ in the peer ranges of godmin's `package.json`.
89
89
  translates godmin's own words. `@wordpress/date` is an optional peer,
90
90
  needed only by `@gopherium/godmin/dates`. `@wordpress/components` is
91
91
  an optional peer too, needed only by `@gopherium/godmin/dialogs`, in
92
- the window `>=42.0.0 <43.0.0`. Install each one next to godmin when
92
+ the window `>=43.0.0 <44.0.0`. Install each one next to godmin when
93
93
  you use its entry. Load the components stylesheet once in your
94
94
  application, `@wordpress/components/build-style/style.css`, as
95
95
  DataViews already asks. godmin never imports it. Their windows are in
96
96
  the same peer ranges.
97
97
 
98
98
  `@wordpress/dataviews` is an optional peer as well, in the window
99
- `>=20.0.0 <21.0.0`. No godmin entry imports it, but `offeredView`
99
+ `>=21.0.0 <22.0.0`. No godmin entry imports it, but `offeredView`
100
100
  follows the filter rules of that DataViews release. A list built on
101
101
  another release gets a peer warning when it installs godmin.
102
102
 
@@ -145,6 +145,8 @@ jump straight to one.
145
145
  | The drawer on a small screen | `dialog` | "Navigation", whatever `label` says |
146
146
  | The tabs of a page | `navigation` | The `label` of [`PageTabs`](../screens.md#pagetabs) |
147
147
  | The list of a list page | `region` | The `listLabel` of [`Page`](../screens.md#page), when given |
148
+ | The details of a record page | `region` | The `asideLabel` of [`Page`](../screens.md#page), when given |
149
+ | The breadcrumbs of a page | `navigation` | The `label` of [`PageBreadcrumbs`](../screens.md#pagebreadcrumbs) |
148
150
 
149
151
  The sidebar menu draws no landmark of its own, and the drawer holds
150
152
  no region. So a screen reader meets the sidebar under one name only.
@@ -233,11 +235,12 @@ gives no label a fixed width:
233
235
  only a smallest height.
234
236
  - A long title on a sidebar screen breaks onto the next line.
235
237
  - A toast grows with its message, then wraps, as
236
- [size](./toasts.md#size) on the toasts page shows. The aside of a
237
- page and a log list break a long word the same way.
238
+ [size](./toasts.md#size) on the toasts page shows. Both columns of
239
+ a record page and a log list break a long word the same way.
238
240
  - The actions of a page header move under the title once they no
239
- longer fit beside it. A form row and the header line of a log list
240
- wrap the same way.
241
+ longer fit beside it. Beside breadcrumbs the title ends in an
242
+ ellipsis first, and they move once it reaches its smallest width.
243
+ A form row and the header line of a log list wrap the same way.
241
244
  - The page tabs keep each label on one line. A tab row too long for
242
245
  its page scrolls and fades the edge it cuts.
243
246
 
@@ -23,8 +23,8 @@ values. This table says where each one is set and what it changes.
23
23
  | --- | --- | --- |
24
24
  | `--godmin-nav-sidebar-width` | `:root` | The width of the sidebar, and of the drawer that takes its place on a small screen |
25
25
  | `--godmin-canvas-margin` | `:root` | The space around the canvas |
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 |
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 |
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
+ | `--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
28
  | `--godmin-navigation-slide-distance` | `:root` | How far a sidebar screen moves as it slides in |
29
29
  | `--godmin-navigation-slide-duration` | `:root` | How long that slide takes |
30
30
 
@@ -61,3 +61,7 @@ do not read or set them in your app.
61
61
  - `--godmin-list-frozen-start` holds the width of the checkbox column
62
62
  of a wide list table, where its frozen title starts. It is set on
63
63
  the table.
64
+ - `--godmin-page-stacked` tells the columns of a record page whether
65
+ they sit side by side. It stays far below zero while they fit and
66
+ rises far above the height of any record once they do not. It is
67
+ set on the box that holds them.
@@ -58,8 +58,10 @@ is the padding between its edge and the screen inside it.
58
58
  and [Elevation](./radius-and-elevation.md#elevation) give the
59
59
  corners and the shadow.
60
60
 
61
- The canvas scrolls its screen inside itself. A bleed canvas, which
62
- `canvas="bleed"` asks for, has no gutter at any width and hides what
61
+ The canvas scrolls its screen inside itself. A DataViews list page and
62
+ a record page keep their title and scroll a part of their own, as
63
+ [what scrolls](./record-pages.md#what-scrolls) gives for a record. A
64
+ bleed canvas, which `canvas="bleed"` asks for, has no gutter at any width and hides what
63
65
  overflows it, so the screen scrolls its own parts. The default,
64
66
  `padded`, keeps the gutters.
65
67
  [Two canvas modes](../framing-an-application.md#two-canvas-modes)
@@ -55,6 +55,8 @@ When it shows and where it sits depend on what is around it:
55
55
  WordPress screen shows the spinner under its title. The spinner
56
56
  sits at the top of the page content, centred across, with the
57
57
  page's own gap between it and the title. The title stays on screen.
58
+ In a page with an `aside` it sits at the top of its column, centred
59
+ across that column.
58
60
  - Inside a dialog it shows at once too, and takes only the space it
59
61
  gets.
60
62
  - Inside a sidebar screen it shows at once too, under the screen's
@@ -100,7 +100,7 @@ layer.
100
100
  - [Custom properties](./custom-properties.md): every godmin custom
101
101
  property, where it is set and what it changes.
102
102
 
103
- Three more pages cover a single part each, how it looks and how it
103
+ Four more pages cover a single part each, how it looks and how it
104
104
  behaves:
105
105
 
106
106
  - [Toasts](./toasts.md): where a toast sits, how it looks, how long it
@@ -111,3 +111,6 @@ behaves:
111
111
  hears.
112
112
  - [Lists](./lists.md): how a list meets the canvas, its columns, a
113
113
  wide table, its rows, an empty list and what it does after a write.
114
+ - [Record pages](./record-pages.md): how a page that shows one record
115
+ sets its header and its two columns, what scrolls, what its details
116
+ hold, how it saves and what shows while it loads.
@@ -0,0 +1,197 @@
1
+ ---
2
+ title: Record pages
3
+ description: How a page that shows one record sets its header, its main work and its details, which part grows, when the details move under the main work, what scrolls, and what shows while the record loads.
4
+ ---
5
+
6
+ A record page shows one thing, such as one invoice, on a page of its
7
+ own. Its main work takes the room and its details sit in a fixed
8
+ column at the end, as on WordPress's newer screens.
9
+ [Page](../screens.md#page) shows how to set one up. This page gives
10
+ every value of how it looks.
11
+
12
+ ## What goes where
13
+
14
+ - The main work is what grows and what the reader came to do, such as
15
+ the lines of an invoice, its history or its notes. A long text the
16
+ reader writes, such as a description, goes here too.
17
+ - The details are the record's own short fields and facts, such as
18
+ its customer, its dates and its status.
19
+ - One header runs across both columns, on one surface. No line, box
20
+ or shadow marks the details. The space between the columns sets
21
+ them apart.
22
+
23
+ ## The page header
24
+
25
+ - The title row is at least `--wpds-dimension-size-md` (32px) tall,
26
+ even with no actions, so the title sits in the same place on every
27
+ page. A compact button is as tall as the row. A button of the
28
+ default size makes the row taller.
29
+ - The title shows the edited value, so it follows the field as the
30
+ reader types. When the field is empty, fall back to a word such as
31
+ "Untitled".
32
+ - The subtitle is `body-md` in
33
+ `--wpds-color-foreground-content-neutral-weak`, with
34
+ `--wpds-dimension-padding-xs` (4px) under it.
35
+ - Breadcrumbs sit before the title, on its line. Each link is
36
+ `body-lg`. A slash in `--wpds-color-stroke-surface-neutral` follows
37
+ it, `--wpds-dimension-gap-sm` (8px) from the text on each side.
38
+ - Beside breadcrumbs the title stays on one line and ends in an
39
+ ellipsis when it does not fit. The links and the actions keep their
40
+ width.
41
+ - The title keeps half of `--wpds-dimension-surface-width-xs` (240px),
42
+ which is 120px. A trail that leaves it less wraps, as the WordPress
43
+ Forms trail does, and the title moves under it. Actions that leave
44
+ it less move under the title.
45
+ - A breadcrumb link breaks a long word, with `overflow-wrap: anywhere`,
46
+ so a record number with no spaces stays inside the row.
47
+ - Every page opened from a list takes breadcrumbs, a create page too.
48
+ - Save comes last in the row. A menu with Delete, named "More
49
+ options", comes before it.
50
+
51
+ ## The two columns
52
+
53
+ - The main work takes all the room the details leave. It has no cap.
54
+ Beside the details its content is never narrower than
55
+ `--wpds-dimension-surface-width-md` (400px), and its box adds
56
+ `--wpds-dimension-padding-xs` (4px) at each side.
57
+ - The details are `--wpds-dimension-surface-width-md` (400px) wide, at
58
+ the end of the page, which is the right in English. Their box adds
59
+ `--wpds-dimension-padding-xs` (4px) at each side, so it measures
60
+ 408px.
61
+ - The columns sit `--wpds-dimension-gap-xl` (24px) apart, from the
62
+ content of one to the content of the other. The
63
+ `--wpds-dimension-padding-xs` (4px) at each side is part of that gap.
64
+ - Each column keeps `--wpds-dimension-padding-xs` (4px) of room at
65
+ each side, inside its box, since a box that scrolls clips what
66
+ draws past its edge and a focus ring would lose its sides. On a
67
+ padded canvas its content still meets the edges of the page title.
68
+ - Inside each column the parts sit `--wpds-dimension-gap-lg` (16px)
69
+ apart.
70
+ - Both columns break a long word, with `overflow-wrap: anywhere`, so
71
+ it cannot push the page wider. A `godmin-table` keeps its words
72
+ whole.
73
+ - A column clips what runs past its sides, so a wide table goes in a
74
+ `godmin-table-scroll`, which scrolls there at every width.
75
+ - A `godmin-list` in a column stays inside it, so a row and its focus
76
+ ring stay whole. DataViews keeps its own padding, as a list region
77
+ in the main work does.
78
+
79
+ ## When both do not fit
80
+
81
+ - The columns sit side by side while the page is at least 824px wide,
82
+ which is both columns and their gap. No breakpoint decides this,
83
+ only the page's own width.
84
+ - Below that the details move under the main work,
85
+ `--wpds-dimension-gap-xl` (24px) apart, and both fill the page. The
86
+ reading order stays the same.
87
+ - A bleed canvas has no gutter for the room at each side of a column
88
+ to sit in, so that room stays inside the page. The columns fold at
89
+ 832px there, and their content sits 4px in from the title.
90
+ - The page does not narrow steadily as the window does, since the
91
+ sidebar folds at `SIDEBAR_BREAKPOINT` and the canvas drops its
92
+ margin at `EDGE_BREAKPOINT`. So a window just below
93
+ `SIDEBAR_BREAKPOINT` can show two columns where a wider one shows
94
+ one.
95
+ - An `aside` that renders nothing takes no room, and the main work
96
+ fills the page.
97
+ - On a narrow page the details come after everything in the main
98
+ work. Show the first rows of a long list with
99
+ [`LoadMore`](../screens.md#loadmore), so a reader can reach them.
100
+
101
+ ## What scrolls
102
+
103
+ - The page header stays. While the columns sit side by side each one
104
+ scrolls on its own under it, with `overflow: hidden auto`, so the
105
+ details stay beside the row a reader is on.
106
+ - A column stops at the room under the header. A short column stops
107
+ at its own end and shows no scrollbar.
108
+ - Once the details move under the main work, both scroll together as
109
+ one box, and neither scrolls alone, so a phone reader meets one
110
+ scrollbar and not two stacked ones.
111
+ - A line `--wpds-border-width-xs` (1px) wide in
112
+ `--wpds-color-stroke-surface-neutral-weak` runs under the header to
113
+ the canvas edges. Under page tabs their own line takes its place.
114
+ - While the columns sit side by side each one keeps
115
+ `--wpds-dimension-padding-lg` (16px) above its content, inside the
116
+ part that scrolls, so a row scrolls away at the line. Once the
117
+ details move under the main work, only the main work does.
118
+ - The columns reach the foot of the canvas, and each keeps
119
+ `--godmin-canvas-gutter-block` under its last line.
120
+ - A page with no `aside` scrolls the canvas, as
121
+ [the canvas](./layout.md#the-canvas) says.
122
+ - The columns scroll on their own only when the `Page` sits directly
123
+ in the canvas. Inside a wrapper of your own, or outside a frame, the
124
+ record takes its full height and whatever holds it scrolls.
125
+ - A keyboard scrolls a column from a control inside it, so keep one
126
+ there, such as a link or a field.
127
+
128
+ ## What the details hold
129
+
130
+ - A section is a `SectionTitle` and what follows it, with no box
131
+ around it and no line between sections.
132
+ - Fields sit one under the other with their label on top, in a
133
+ `godmin-form`, as in WordPress's media editor.
134
+ - Facts follow the fields, as rows of a label and a value. A
135
+ `DataForm` with the `panel` layout and `readOnly` fields draws them.
136
+ Load the `@wordpress/dataviews` and `@wordpress/components`
137
+ stylesheets. The label takes 38% of the row, and the value shows in
138
+ the weak text color at the default weight.
139
+ - One fact alone, such as the day a record was made, is a muted
140
+ sentence.
141
+ - A long list or a table goes in the main work.
142
+
143
+ ## Forms on a page
144
+
145
+ - A stacked `godmin-form` stops at
146
+ `--wpds-dimension-surface-width-lg` (560px), also in a wider main
147
+ work column, and its fields sit `--wpds-dimension-gap-md` (12px)
148
+ apart.
149
+ - In a `godmin-form__row` each field starts from two thirds of
150
+ `--wpds-dimension-surface-width-xs` (240px), which is 160px, and
151
+ the fields share the rest of the line.
152
+
153
+ ## Saving
154
+
155
+ - On a page with an `aside`, one Save button in the page header
156
+ serves the record's fields in both columns. It is compact and reads
157
+ "Save". A page with no `aside` keeps its Save at the end of the
158
+ form, since its title scrolls away.
159
+ - It stays off until something changes and while the record saves,
160
+ and a keyboard can still reach it. Say both, as in
161
+ `disabled={!changed || saving}`, since `loading` alone turns it off
162
+ only when `disabled` is not given. While the record saves it shows
163
+ its loading state and the fields stay in place, turned off.
164
+ - A change that saved and a write that failed each show a toast, as
165
+ [what goes in a toast](../loading-and-feedback.md#what-goes-in-a-toast)
166
+ says. Name what failed, then give the server's words, as in
167
+ `Could not save the invoice. The customer is closed.`
168
+ - A server message about one field shows under that field.
169
+ - A check made before sending shows under its field. Move the focus
170
+ to the first field that failed, so it comes into view inside its
171
+ column.
172
+ - A row added to a list, such as a note, keeps its own button and
173
+ saves at once.
174
+ - While the record holds unsaved work, warn on `beforeunload`, and
175
+ ask before a link in the app leaves the page, such as a breadcrumb.
176
+
177
+ ## While a record loads
178
+
179
+ - While nothing of the record is known, the page shows its header and
180
+ one `LoadingScreen`, with no `aside`.
181
+ [A screen](./loading.md#a-screen) gives how it looks. Breadcrumbs
182
+ stay, and the title names the kind of record.
183
+ - A part that loads on its own shows its `LoadingScreen` in its
184
+ column, at the top and centred across that column.
185
+ - Show one `LoadingScreen` at a time, since each one speaks.
186
+ - A record that could not load shows an `ErrorNotice` under the
187
+ title, with no `aside`. Breadcrumbs stay, and the title still names
188
+ the kind of record.
189
+
190
+ ## What a screen reader hears
191
+
192
+ - `asideLabel` makes the details a named region, as
193
+ [landmarks and names](./accessibility.md#landmarks-and-names)
194
+ lists.
195
+ - `PageBreadcrumbs` is a navigation region named by its `label`. The
196
+ slash is hidden.
197
+ - The main work comes first in the reading order at every width.
@@ -90,9 +90,8 @@ 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` 42.0.0 still
94
- stays 6 seconds, with or without an action. Its next release keeps
95
- one with an action 10 seconds, as godmin does.
93
+ - WordPress's own snackbar in `@wordpress/components` 43.0.0 stays the
94
+ same 6 seconds with no action and 10 seconds with one.
96
95
  - Each toast keeps its own timer. So a toast a screen raises as it
97
96
  mounts leaves on time even under React strict mode, which mounts the
98
97
  screen twice in development.
@@ -49,7 +49,7 @@ The smallest size, `--wpds-typography-font-size-xs` (11px), is for
49
49
  small labels such as the count beside a sidebar row.
50
50
 
51
51
  Some parts give the size of their text on their own page:
52
- [the page subtitle](../screens.md#page),
52
+ [the page subtitle](./record-pages.md#the-page-header),
53
53
  [the page tabs](../screens.md#pagetabs),
54
54
  [the title and description of a list row](./lists.md#rows),
55
55
  [a table that stays custom](./lists.md#tables-that-stay-custom),
package/docs/lists.md CHANGED
@@ -601,8 +601,9 @@ with the focus moved to the list from a part that turns inert, one
601
601
  toast as the last call ends, the focus moved back to the list once a
602
602
  row moved, while the reader is still with the run, then the list
603
603
  reloaded, and the focus put back on the control the reader pressed,
604
- or on the first control of the row that took its place, unless that
605
- control is a primary action. `useListRun` and `useBulkRun` hold those
604
+ on the same item when the reload moved it, or on the first control of
605
+ the row that took its place, unless that control is a primary action.
606
+ `useListRun` and `useBulkRun` hold those
606
607
  things for you:
607
608
 
608
609
  ```tsx
@@ -683,6 +684,13 @@ Once the list reloaded, while the region still holds the focus,
683
684
  - on the control they pressed, when it is still there and takes the
684
685
  focus, such as the bulk action button while a row stays ticked, or
685
686
  a row's button while its row stays,
687
+ - else on the same item, wherever its card or row now sits, when the
688
+ list marks its cells with `data-item-id` as
689
+ [`useFocusBack`](#putting-the-focus-back-on-a-row) asks. A DataViews grid draws
690
+ a card anew when it moves to another grid row, so after a save that
691
+ sorts a file elsewhere the pressed control is gone. The focus lands
692
+ on the title, media or phone row the reader pressed, else on the
693
+ item's actions menu,
686
694
  - else on the first control of the row that now sits where the row of
687
695
  that control was, its checkbox in a list with bulk actions, such as
688
696
  the next row's checkbox when the row the reader restored left the
@@ -199,22 +199,20 @@ Name an item in straight double quotes and in full, like
199
199
  snackbar, and godmin does not either.
200
200
  [Size](./design-system/toasts.md#size) says how a long one wraps.
201
201
 
202
- Use a toast for a write that failed in a dialog or in a run over list
203
- rows too. WordPress shows those in its snackbar, never inside the
204
- dialog and never above the list, and godmin's dialogs and list runs
205
- do the same. Say what failed, in the words your server sent when it
206
- sent some. [A failure from a dialog](./lists.md#a-failure-from-a-dialog)
202
+ Use a toast for a write that failed too, in a dialog, on a page or in
203
+ a run over list rows. WordPress shows those in its snackbar, never
204
+ inside the dialog and never above the list, and godmin's dialogs and
205
+ list runs do the same. Say what failed, in the words your server sent
206
+ when it sent some. A server message about one field goes under that
207
+ field. [A failure from a dialog](./lists.md#a-failure-from-a-dialog)
207
208
  shows how to raise one from a dialog.
208
209
  [Running an action over the picked rows](./lists.md#running-an-action-over-the-picked-rows)
209
210
  raises it for you after a run over a list.
210
211
 
211
212
  Keep an [`ErrorNotice`](./screens.md#errornotice) for a failure
212
- that has to stay on the screen until the user acts:
213
-
214
- - A screen or a list that failed to load. Show the notice where the
215
- content would be.
216
- - A form on a page of its own, not in a dialog. Show the notice next
217
- to the form, so the user sees what failed while they fix it.
213
+ that has to stay on the screen until the user acts, such as a screen
214
+ or a list that failed to load. Show the notice where the content
215
+ would be.
218
216
 
219
217
  Skip the toast in three more cases:
220
218
 
package/docs/overview.md CHANGED
@@ -29,7 +29,7 @@ duplicates something the packages above already ship.
29
29
 
30
30
  | Entry point | Contents |
31
31
  | --- | --- |
32
- | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ListNoResults`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `useCloseWhileOpen`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
32
+ | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `PageBreadcrumbs`, `PageBreadcrumb`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ListNoResults`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `useCloseWhileOpen`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
33
33
  | `@gopherium/godmin/base.css` | Cascade layer order, design tokens, host rules, frame and screen styles |
34
34
  | `@gopherium/godmin/dates` | `startListDates`, `listDate`, the only entry that loads `@wordpress/date` |
35
35
  | `@gopherium/godmin/dialogs` | `ConfirmDialog`, `FormDialog`, the only entry that loads `@wordpress/components`. Load `@wordpress/components/build-style/style.css` once in your app, as DataViews asks |