@gopherium/godmin 0.29.1 → 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.
Files changed (42) hide show
  1. package/README.md +4 -3
  2. package/dist/base.css +223 -13
  3. package/dist/bulk-run.d.ts +3 -3
  4. package/dist/bulk-run.js +41 -13
  5. package/dist/focus-back.d.ts +22 -0
  6. package/dist/focus-back.js +37 -13
  7. package/dist/index.d.ts +5 -3
  8. package/dist/index.js +4 -3
  9. package/dist/list-chrome/es-ES.d.ts +1 -1
  10. package/dist/list-chrome/es-ES.js +7 -4
  11. package/dist/list-chrome/fr-FR.d.ts +1 -1
  12. package/dist/list-chrome/fr-FR.js +5 -1
  13. package/dist/list-empty.d.ts +14 -7
  14. package/dist/list-empty.js +14 -4
  15. package/dist/list-run.d.ts +8 -4
  16. package/dist/list-run.js +143 -6
  17. package/dist/page-breadcrumbs.d.ts +28 -0
  18. package/dist/page-breadcrumbs.js +18 -0
  19. package/dist/page-tabs.js +29 -26
  20. package/dist/page.d.ts +8 -3
  21. package/dist/page.js +48 -9
  22. package/dist/size-watch.d.ts +11 -0
  23. package/dist/size-watch.js +36 -0
  24. package/dist/wide-list.d.ts +7 -0
  25. package/dist/wide-list.js +33 -0
  26. package/docs/build-and-versioning.md +3 -3
  27. package/docs/design-system/accessibility.md +64 -16
  28. package/docs/design-system/custom-properties.md +9 -2
  29. package/docs/design-system/layout.md +5 -3
  30. package/docs/design-system/lists.md +234 -0
  31. package/docs/design-system/loading.md +2 -0
  32. package/docs/design-system/overview.md +6 -1
  33. package/docs/design-system/radius-and-elevation.md +3 -9
  34. package/docs/design-system/record-pages.md +197 -0
  35. package/docs/design-system/toasts.md +2 -3
  36. package/docs/design-system/typography.md +3 -3
  37. package/docs/framing-an-application.md +7 -5
  38. package/docs/lists.md +278 -72
  39. package/docs/loading-and-feedback.md +9 -11
  40. package/docs/overview.md +1 -1
  41. package/docs/screens.md +83 -36
  42. package/package.json +21 -21
@@ -0,0 +1,36 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { useLayoutEffect, useRef } from 'react';
3
+ /** The pixels a box may run past an edge and still rest on it, for sub-pixel rounding. */
4
+ export const ROUNDING_SLACK = 1;
5
+ /**
6
+ * Measures once, then again whenever the element or a box it names resizes, or its children change.
7
+ * @param ref - The element to watch.
8
+ * @param boxesOf - Names the boxes whose size the measure reads, given the element.
9
+ * @param measure - Reads the element, the one given on the latest render.
10
+ * @param subtree - Whether a change deeper than the element's own children wires the boxes again.
11
+ */
12
+ export function useSizeWatch(ref, boxesOf, measure, subtree) {
13
+ const latest = useRef(measure);
14
+ useLayoutEffect(() => {
15
+ latest.current = measure;
16
+ });
17
+ useLayoutEffect(() => {
18
+ const element = ref.current;
19
+ const measureNow = () => latest.current(element);
20
+ const resizes = new ResizeObserver(measureNow);
21
+ const watch = () => {
22
+ resizes.disconnect();
23
+ for (const box of boxesOf(element)) {
24
+ resizes.observe(box);
25
+ }
26
+ measureNow();
27
+ };
28
+ const mutations = new MutationObserver(watch);
29
+ mutations.observe(element, { childList: true, subtree });
30
+ watch();
31
+ return () => {
32
+ mutations.disconnect();
33
+ resizes.disconnect();
34
+ };
35
+ }, [ref, boxesOf, subtree]);
36
+ }
@@ -0,0 +1,7 @@
1
+ import type { RefObject } from 'react';
2
+ /**
3
+ * Watches the DataViews list inside a list region and reports while its content is wider than its space.
4
+ * @param region - The list region.
5
+ * @returns Whether the list is wider than its space, false until it is first measured.
6
+ */
7
+ export declare function useWideList(region: RefObject<HTMLElement | null>): boolean;
@@ -0,0 +1,33 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { useState } from 'react';
3
+ import { ROUNDING_SLACK, useSizeWatch } from './size-watch.js';
4
+ /** The box DataViews scrolls its rows in, both ways. */
5
+ const SCROLL_BOX = '.dataviews-layout__container';
6
+ /**
7
+ * Returns the boxes whose size decides whether a list is wide: the region, its scroll box and what the box holds.
8
+ * @param region - The list region.
9
+ * @returns The region, then the scroll box and its children when the region holds one.
10
+ */
11
+ function listBoxes(region) {
12
+ const box = region.querySelector(SCROLL_BOX);
13
+ return box === null ? [region] : [region, box, ...box.children];
14
+ }
15
+ /**
16
+ * Reports whether the DataViews scroll box inside a region holds content wider than itself.
17
+ * @param region - The list region.
18
+ * @returns Whether the content runs past the box by more than the rounding slack.
19
+ */
20
+ function overflows(region) {
21
+ const box = region.querySelector(SCROLL_BOX);
22
+ return box !== null && box.scrollWidth - box.clientWidth > ROUNDING_SLACK;
23
+ }
24
+ /**
25
+ * Watches the DataViews list inside a list region and reports while its content is wider than its space.
26
+ * @param region - The list region.
27
+ * @returns Whether the list is wider than its space, false until it is first measured.
28
+ */
29
+ export function useWideList(region) {
30
+ const [wide, setWide] = useState(false);
31
+ useSizeWatch(region, listBoxes, (element) => setWide(overflows(element)), true);
32
+ return wide;
33
+ }
@@ -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
 
@@ -25,11 +25,14 @@ letters.
25
25
  ## The focus ring
26
26
 
27
27
  Focus marks the control the keyboard acts on. The reader moves it
28
- with Tab, and Enter presses the control that holds it. godmin rings
29
- the focused control only when the reader uses the keyboard, the state
30
- CSS calls `:focus-visible`. A mouse click draws no ring.
31
-
32
- Except on a toast, every ring godmin draws is the same line,
28
+ with Tab, and Enter presses the control that holds it. godmin draws
29
+ its own rings only when the reader uses the keyboard, the state CSS
30
+ calls `:focus-visible`. A mouse click draws none of them. A checkbox
31
+ or a button from `@wordpress/components` draws WordPress's own focus
32
+ style on any focus, a mouse click included.
33
+
34
+ Except on a toast and a list region, every ring godmin draws is the
35
+ same line,
33
36
  `outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus)`.
34
37
 
35
38
  - `--wpds-border-width-focus` (2px) sets the width. On a high density
@@ -45,13 +48,15 @@ Except on a toast, every ring godmin draws is the same line,
45
48
  | The title link of a `godmin-table`, a `godmin-table-scroll` box and a row of `RepeatRows` | 2px outside the part |
46
49
  | A page tab | Around its label, not around the whole height of the tab |
47
50
  | A toast | Its own rings, as [keyboard](./toasts.md#keyboard) on the toasts page shows. A plain toast keeps the browser's ring too |
51
+ | A list region a run focuses | Inside its edge, twice as wide, the ring WordPress draws on a region it focuses, as [after a write of your own](./lists.md#after-a-write-of-your-own) shows. The browser's ring is off, as in wp-admin |
48
52
 
49
- godmin turns the browser's own ring off in three places only. A page
53
+ godmin turns the browser's own ring off in four places only. A page
50
54
  tab draws its own ring around the label instead. Back draws none on a
51
55
  mouse focus. The toast region draws none. Tab never stops on it, and
52
- only a toast that leaves or a click on a toast focuses it. Draw a
53
- ring of your own with the same line, on `:focus-visible`, so it
54
- matches.
56
+ only a toast that leaves or a click on a toast focuses it. A list
57
+ region draws the WordPress region ring instead, as wp-admin turns the
58
+ browser's ring off on every `div`. Draw a ring of your own with the
59
+ same line, on `:focus-visible`, so it matches.
55
60
 
56
61
  ## Where focus goes
57
62
 
@@ -68,17 +73,56 @@ sidebar moves focus in these cases only:
68
73
 
69
74
  The title of a sidebar screen never takes focus.
70
75
 
71
- Some parts go away while they hold focus. godmin then moves focus to
72
- a part that stays, so the keyboard reader keeps their place:
76
+ Some parts go away, or turn inert, while they hold focus. godmin then
77
+ moves focus to a part that stays, so the keyboard reader keeps their
78
+ place:
73
79
 
74
80
  - A toast that leaves, as [keyboard](./toasts.md#keyboard) on the
75
81
  toasts page says.
76
- - A list row that a run moved, as
82
+ - A list row that a run moved. The list region takes the focus and
83
+ the screen does not scroll, as
77
84
  [running an action over the picked rows](../lists.md#running-an-action-over-the-picked-rows)
78
85
  says.
86
+ - The table or the footer of a list, with its rows and the busy bulk
87
+ action button, which turn inert as a run reloads the list. The list
88
+ region takes the focus at once, where WordPress drops it to the
89
+ page, and the screen does not scroll either, as
90
+ [after a write of your own](./lists.md#after-a-write-of-your-own)
91
+ says. While the list reloads, the next Tab from the list region
92
+ goes to the first control of the list, such as its search field.
79
93
  - A row of `RepeatRows` that the reader removed, as
80
94
  [RepeatRows](../screens.md#repeatrows) says.
81
95
 
96
+ Once a list reloaded after a run, while its region still holds the
97
+ focus, the focus goes back to the control the reader pressed, or to
98
+ the one that opened the confirm or the row's actions menu. When that
99
+ control left with its row, the focus goes to the first control of the
100
+ row now in its place, its checkbox in a list with bulk actions. It
101
+ stays on the region when no such control is left, or when that control
102
+ is a primary action from `actions`. DataViews names that checkbox after
103
+ the view's `titleField`, so a screen reader says the title of the row
104
+ now in that place, then checkbox and its state, checked or not
105
+ checked, and a second Enter does nothing. The next Tab then goes on
106
+ from that control, as
107
+ [running an action over the picked rows](../lists.md#running-an-action-over-the-picked-rows)
108
+ says.
109
+
110
+ A list with no bulk actions draws no checkbox. Its title takes the
111
+ focus when the title opens the item, and a screen reader says the
112
+ title of that row. The row's actions menu button takes it when that
113
+ comes first, since Enter there only opens a menu. The button of a
114
+ primary action, such as a Trash, says the action and not the row,
115
+ so a screen reader would say "Trash, button", and a second Enter
116
+ would act on a row the reader never picked. So the region keeps the
117
+ focus there. The focus does not move, so a screen reader has no new
118
+ name to say. A second Enter writes nothing, and the next Tab goes to
119
+ the first control of the list, such as its search field.
120
+
121
+ WordPress leaves the focus on the page, where nothing shows and no
122
+ control is named. godmin goes beyond it so a keyboard reader sees
123
+ where they are and a screen reader has a control to name, or stays on
124
+ the region when that control is a primary action.
125
+
82
126
  Dialogs move focus as they open and close, as
83
127
  [a confirm outside a list](../lists.md#a-confirm-outside-a-list) and
84
128
  [a form dialog](../lists.md#a-form-dialog) explain. When the list
@@ -101,6 +145,8 @@ jump straight to one.
101
145
  | The drawer on a small screen | `dialog` | "Navigation", whatever `label` says |
102
146
  | The tabs of a page | `navigation` | The `label` of [`PageTabs`](../screens.md#pagetabs) |
103
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) |
104
150
 
105
151
  The sidebar menu draws no landmark of its own, and the drawer holds
106
152
  no region. So a screen reader meets the sidebar under one name only.
@@ -142,6 +188,7 @@ aloud when it changes.
142
188
  | A toast | Its message, politely. Never its action | [What a screen reader hears](./toasts.md#what-a-screen-reader-hears) |
143
189
  | A loading screen | The `label` sentence, from a visually hidden status. The spinner is hidden | [What a screen reader hears](./loading.md#what-a-screen-reader-hears) |
144
190
  | A list that loads | Nothing on its first load, as in WordPress. A table or a grid is marked busy on a later load | [What a screen reader hears](./loading.md#what-a-screen-reader-hears) |
191
+ | A list after a run | The control the focus went back to. After the pressed row left, the checkbox of the row now in its place, by that row's title. With no checkbox, that row's title or actions menu button, and nothing new when the region keeps the focus | [Where focus goes](#where-focus-goes) |
145
192
  | A count beside a row | The `label` sentence, in place of the bare number | [A count beside a row](../framing-an-application.md#a-count-beside-a-row) |
146
193
  | An `ErrorNotice` | Its message, at once, as an alert | [ErrorNotice](../screens.md#errornotice) |
147
194
 
@@ -188,11 +235,12 @@ gives no label a fixed width:
188
235
  only a smallest height.
189
236
  - A long title on a sidebar screen breaks onto the next line.
190
237
  - A toast grows with its message, then wraps, as
191
- [size](./toasts.md#size) on the toasts page shows. The aside of a
192
- 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.
193
240
  - The actions of a page header move under the title once they no
194
- longer fit beside it. A form row and the header line of a log list
195
- 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.
196
244
  - The page tabs keep each label on one line. A tab row too long for
197
245
  its page scrolls and fades the edge it cuts.
198
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
 
@@ -58,3 +58,10 @@ do not read or set them in your app.
58
58
  `--godmin-page-tabs-fade-width`, `--godmin-page-tabs-fade` and
59
59
  `--godmin-page-tabs-fade-both` fade an end of a `PageTabs` row where
60
60
  more tabs sit out of view. They are set on the row itself.
61
+ - `--godmin-list-frozen-start` holds the width of the checkbox column
62
+ of a wide list table, where its frozen title starts. It is set on
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)
@@ -82,7 +84,7 @@ as wide. A rule for the screens below it asks for one pixel less, as
82
84
  | --- | --- | --- |
83
85
  | `HUGE_BREAKPOINT` | `1440` | Nothing in the frame. It is the WordPress huge breakpoint, for rules of your own |
84
86
  | `SIDEBAR_BREAKPOINT` | `1024` | The sidebar becomes the top bar and the drawer |
85
- | `EDGE_BREAKPOINT` | `782` | The canvas meets the screen edges. It is the WordPress medium breakpoint |
87
+ | `EDGE_BREAKPOINT` | `782` | The canvas meets the screen edges. It is the WordPress medium breakpoint. A wide list table freezes its checkbox and title only above this width, as [a wide table](./lists.md#a-wide-table) shows |
86
88
  | `DENSE_BREAKPOINT` | `640` | The canvas side gutter narrows to 16px. A list from `useListView` takes its phone layout, as [the view in the address](../lists.md#the-view-in-the-address) shows. A table inside `godmin-table-scroll` scrolls sideways, as [stylesheet helpers](../screens.md#stylesheet-helpers) shows |
87
89
  | `SHEET_BREAKPOINT` | `600` | Dialogs rise as sheets along the bottom of the screen and toasts widen to the screen, as [a form dialog](../lists.md#a-form-dialog) and [toasts](./toasts.md#size) show. It is the WordPress small breakpoint |
88
90
  | `TITLE_BREAKPOINT` | `404` | Nothing in the frame. The WordPress editor drops the document title from its header here, for an editor header of your own |
@@ -0,0 +1,234 @@
1
+ ---
2
+ title: Lists
3
+ description: How a list meets the canvas edges, which columns it shows at each width, how a wide table scrolls, how its rows look, what an empty list shows, and what a list does after a write of your own.
4
+ ---
5
+
6
+ A list page holds a DataViews list, as WordPress's new admin holds
7
+ its lists. [Lists with DataViews](../lists.md) shows how to set one
8
+ up. This page gives every value of how a list looks.
9
+
10
+ ## A list page
11
+
12
+ - The list reaches the left, right and bottom edges of the canvas.
13
+ DataViews pads its toolbar, its table and its footer by
14
+ `--wpds-dimension-padding-2xl` (24px) on each side, so the rows
15
+ start where the page title starts and the row lines run from edge
16
+ to edge, as in WordPress.
17
+ - The title row of a list page pads by `--wpds-dimension-padding-2xl`
18
+ less the canvas gutter. Where the gutter is narrower than the list's
19
+ own padding, the title still lines up with the list.
20
+ [The canvas](./layout.md#the-canvas) gives the gutter.
21
+ - A notice or any other part before the list lines up with the title,
22
+ `--wpds-dimension-padding-2xl` in from the canvas edge.
23
+ - The list region keeps `--wpds-dimension-gap-lg` (16px) between a
24
+ notice and the list.
25
+ - Under page tabs the search box sits 16px under the tab line, the top
26
+ padding of the DataViews toolbar. The list takes back the page gap,
27
+ `--wpds-dimension-gap-lg`, so the two do not add up.
28
+ - The footer rests on the bottom edge of the canvas. Only the rows
29
+ scroll. The title, the tabs, the toolbar and the column headers stay.
30
+
31
+ ## Columns
32
+
33
+ - A list opens on the same columns at every width from
34
+ `EDGE_BREAKPOINT` (782px), as WordPress lists do. godmin hides no
35
+ column because the window is narrow. A reader adds and removes
36
+ columns in View options.
37
+ - From `DENSE_BREAKPOINT` (640px) up to `EDGE_BREAKPOINT` itself the
38
+ table keeps them too. There DataViews shows each row's actions in
39
+ its Actions menu only, and its bulk actions as icons.
40
+ - Below `DENSE_BREAKPOINT` a list from `useListView` shows its phone
41
+ layout, the DataViews list layout, with the fields `phoneFields`
42
+ names.
43
+ - In a table the title column takes the free room. DataViews sets
44
+ every other column as wide as its content, on one line.
45
+
46
+ ## A wide table
47
+
48
+ When its columns need more room than the list has, a table scrolls
49
+ sideways inside the list. The toolbar and the footer stay where they
50
+ are. `Page` marks such a list region `godmin-page__list--wide`.
51
+
52
+ - The actions column stays pinned to the end edge. While a column
53
+ hides under it, a 1px line in
54
+ `--wpds-color-stroke-surface-neutral-weak` marks its other side.
55
+ DataViews draws both.
56
+ - Wider than `EDGE_BREAKPOINT`, a table with checkboxes keeps the
57
+ 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.
61
+ - The title column keeps at least 280px and
62
+ `--wpds-dimension-padding-2xl` free at its end, where a line
63
+ `--wpds-border-width-xs` (1px) wide in
64
+ `--wpds-color-stroke-surface-neutral-weak` marks it.
65
+ - The frozen cells paint the list background,
66
+ `--wpds-color-background-surface-neutral-strong` unless your app
67
+ sets `--wp-dataviews-color-background`, and on a selected row its
68
+ tint, `--wpds-color-background-interactive-brand-weak-active`. So
69
+ the cells that scroll pass under them.
70
+ - The frozen header cells stay over the rest of the header row, and
71
+ the header row stays over the frozen cells of the rows that scroll
72
+ up under it.
73
+ - A table that fits freezes nothing and draws no line after its title,
74
+ as a WordPress table that fits. Nor does a table with no checkbox
75
+ column, or one whose title the reader hid in View options.
76
+ - In a right-to-left page the frozen columns hold the right edge and
77
+ the actions the left.
78
+
79
+ ## Rows
80
+
81
+ DataViews draws the rows. On a list page godmin sets the title and
82
+ the description under it as the WordPress subscriber list does:
83
+
84
+ - The title is 13px and bold, on a line
85
+ `--wpds-typography-line-height-sm` (20px) high.
86
+ - The description is a muted line in
87
+ `--wpds-typography-font-size-sm` (12px), on
88
+ `--wpds-typography-line-height-xs` (16px),
89
+ `--wpds-dimension-gap-xs` (4px) under the title. A row with both is
90
+ 64px tall.
91
+ - A title on its own stays in the middle of a line
92
+ `--wpds-dimension-size-md` (32px) high, level with the other cells
93
+ of its row.
94
+ - The media of a row sits in the middle of the row.
95
+
96
+ ## An empty list
97
+
98
+ - `ListEmpty` draws the design system empty state: an icon in a
99
+ circle, the title, the description and the buttons, in a centred
100
+ column at most `--wpds-dimension-surface-width-sm` (320px) wide,
101
+ its parts `--wpds-dimension-gap-xs` (4px) apart. Its title is a
102
+ `heading-lg` heading one level under the page title, as
103
+ [the heading outline](./typography.md#the-heading-outline) shows.
104
+ - The icon sits in a circle filled with
105
+ `--wpds-color-background-surface-neutral-weak`, ringed by a 1px
106
+ `--wpds-color-stroke-surface-neutral-weak` line, with
107
+ `--wpds-dimension-gap-xs` more space under it.
108
+ - Its buttons sit `--wpds-dimension-gap-md` (12px) under the
109
+ description and `--wpds-dimension-gap-xs` apart, side by side from
110
+ 480px wide and one above the other below that. The add button keeps
111
+ its default size.
112
+ - In a DataViews list it sits in the middle of the space between the
113
+ toolbar and the bottom of the canvas, as DataViews centres what it
114
+ shows in place of rows. The footer goes away while the list is
115
+ empty. The search box and the filters stay.
116
+ - Anywhere else godmin keeps 48px free above and below it, a value of
117
+ its own.
118
+ - A title of one short phrase ends with no full stop, such as "No
119
+ reports yet". A description is a sentence and ends with one. A
120
+ title of two sentences keeps its full stops, such as "You're set
121
+ up. No reports yet."
122
+ - `ListNoResults` shows the search icon, "No results found" and "Try
123
+ adjusting your search or filters to find what you're looking for."
124
+ - A status tab that holds nothing, such as Trash, shows words of its
125
+ own, such as "Trash is empty", and no add button.
126
+
127
+ ## After a write of your own
128
+
129
+ When a run over the picked rows changes them, as
130
+ [running an action over the picked rows](../lists.md#running-an-action-over-the-picked-rows)
131
+ shows:
132
+
133
+ - While the calls run, the bulk action button in the footer is busy.
134
+ A row action with no dialog shows nothing yet, as in the WordPress
135
+ Site Editor.
136
+ - As the first call that works ends, the list starts to reload, as
137
+ in the WordPress Site Editor, while the other calls still run and
138
+ the bulk action button stays busy. The old rows stay on screen and
139
+ nobody can click them. If the reload takes longer than a moment,
140
+ the rows pulse as on a later load. [A list](./loading.md#a-list)
141
+ 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
+ - As the last call ends, the toast shows, the busy button ends and a
149
+ confirm closes. Once a row moved, the list region takes the focus,
150
+ as [where focus goes](./accessibility.md#where-focus-goes) says,
151
+ and here too the screen does not scroll. A reader who ran the action
152
+ from a row near the bottom of the list, or from a confirm, still
153
+ sees the rows they were on. While the list reloads, the next Tab
154
+ from the list region goes to the first control of the list, such as
155
+ its search field.
156
+ - When the reader started the run from the keyboard, the list region
157
+ draws the ring WordPress draws on a region it focuses, from the
158
+ moment it takes the focus: a line in `--wpds-color-stroke-focus`
159
+ along the inside of its edge, twice as wide as
160
+ `--wpds-border-width-focus` (2px), so 4px, or 3px on a high density
161
+ screen, and a `--wpds-border-width-xs` (1px) line in
162
+ `--wpds-color-background-surface-neutral-strong` just inside that.
163
+ The ring paints over the table, its frozen cells and its pinned
164
+ actions, and under every toast, menu and dialog. The region turns
165
+ the browser's own ring off, `outline: none`, as wp-admin does on
166
+ every `div`, so only this ring shows. A run started with a mouse
167
+ click draws no ring on the region, since this ring shows only on a
168
+ keyboard focus.
169
+ - The list asks for its new rows once the last call ended, as
170
+ WordPress does. When they land, they replace the old ones at once.
171
+ - Once the new rows show, while the list region still holds the
172
+ focus, the focus goes back to the control the reader pressed, or to
173
+ the one that opened the confirm or the row's actions menu. When that
174
+ control left with its row, the focus goes to the first control of the
175
+ row now in its place, its checkbox in a list with bulk actions, such
176
+ as the next row's checkbox, or the last row's when fewer came back.
177
+ In a grid it goes to the first control of the card in that place.
178
+ DataViews names the checkbox after its row, so a screen reader says
179
+ the title of that row. In a list with no bulk actions the row draws
180
+ no checkbox. Its title takes the focus when the title opens the
181
+ item, and its actions menu button takes it when that comes first,
182
+ since Enter there only opens a menu. When the first control of the
183
+ row is a primary action from `actions`, such as a primary Trash, the
184
+ region keeps the focus, whether or not the action opens a confirm.
185
+ That button says the action and not the row, so a second Enter there
186
+ would act on a row the reader never picked. From the region a second
187
+ Enter writes nothing, and the next Tab goes to the first control of
188
+ the list, such as its search field. The region also keeps the focus
189
+ when no row came back, or the pressed button sat in a bulk bar that
190
+ went with the ticked rows.
191
+ After a run from the keyboard the ring shows on the control and the
192
+ rows scroll to it when it is out of view. After a mouse click the
193
+ region shows no ring and the rows stay where the reader left them.
194
+ A checkbox, a `Button`, a title or a grid card's media button still
195
+ draws WordPress's own focus style, which it draws on any focus. An
196
+ item of the list layout shows only its row tint and a table media
197
+ button shows nothing, since those two show a focus style only on a
198
+ keyboard focus. Here godmin goes beyond WordPress, which leaves the
199
+ focus on the page, where nothing shows. So the reader keeps their
200
+ place and a keyboard reader sees it.
201
+ - When every call failed, the list shows no reload, as WordPress
202
+ reloads only after a write that worked.
203
+ - No toast says that a write is still running. WordPress shows none
204
+ for a list.
205
+
206
+ ## Tables that stay custom
207
+
208
+ A `godmin-table` is drawn like the DataViews table, with two values of
209
+ godmin's own:
210
+
211
+ - Text in `--wpds-typography-font-size-md` (13px) on
212
+ `--wpds-typography-line-height-sm` (20px) lines.
213
+ - Every cell pads by `--wpds-dimension-padding-md` (12px).
214
+ - A header cell pads by `--wpds-dimension-padding-sm` (8px) above and
215
+ below, in `--wpds-typography-font-size-xs` (11px) capitals at
216
+ `--wpds-typography-font-weight-emphasis`.
217
+ - A body cell is at least `--wpds-dimension-size-md` (32px) tall
218
+ inside its padding.
219
+ - A line `--wpds-border-width-xs` (1px) wide in
220
+ `--wpds-color-stroke-surface-neutral-weak` runs above each row.
221
+ - On a list page the first and last cells pad by
222
+ `--wpds-dimension-padding-2xl` at their outer side, as DataViews
223
+ does.
224
+ - godmin's own: a row takes
225
+ `--wpds-color-background-surface-neutral-weak` under the pointer
226
+ and while keyboard focus is inside it. DataViews tints no row.
227
+ - godmin's own: below `DENSE_BREAKPOINT` a table inside
228
+ `godmin-table-scroll` scrolls sideways inside it. Its actions column
229
+ stays pinned to the end edge, and an inset shadow
230
+ `--wpds-border-width-xs` wide of `--wpds-color-stroke-surface-neutral`
231
+ marks its other side at rest too. DataViews draws its own line in a
232
+ weaker color, and only while a column hides under the actions, as
233
+ [a wide table](#a-wide-table) shows. The table merges the borders of
234
+ its cells, and a merged border paints badly on a pinned cell.
@@ -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
- Two 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
@@ -109,3 +109,8 @@ behaves:
109
109
  - [Loading](./loading.md): what a list, a screen and a preview show
110
110
  while their data loads, how long each waits and what a screen reader
111
111
  hears.
112
+ - [Lists](./lists.md): how a list meets the canvas, its columns, a
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.
@@ -115,15 +115,9 @@ package draws, because godmin sets none for them.
115
115
 
116
116
  Two more shadows draw a line, not depth:
117
117
 
118
- - Below `DENSE_BREAKPOINT` the actions column of a `godmin-table`
119
- inside a `godmin-table-scroll` box stays pinned while the other
120
- cells scroll. Its edge is an inset shadow, one drawn inside the
121
- box: `--wpds-border-width-xs` (1px) of
122
- `--wpds-color-stroke-surface-neutral`. It sits on the side that
123
- faces the other cells, in a right-to-left page too. The table
124
- merges the borders of its cells, and a merged border paints badly
125
- on a pinned cell. [Stylesheet helpers](../screens.md#stylesheet-helpers)
126
- shows the table markup.
118
+ - The pinned actions column of a `godmin-table` inside
119
+ `godmin-table-scroll` draws its edge as an inset shadow, as
120
+ [Tables that stay custom](./lists.md#tables-that-stay-custom) gives.
127
121
  - A focused toast with no action draws its focus ring as a shadow, as
128
122
  [keyboard](./toasts.md#keyboard) on the toasts page shows.
129
123
  [The focus ring](./accessibility.md#the-focus-ring) covers the