@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/README.md +1 -1
- package/dist/base.css +150 -13
- package/dist/focus-back.d.ts +20 -0
- package/dist/focus-back.js +36 -12
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -2
- package/dist/list-chrome/es-ES.js +3 -3
- package/dist/list-run.js +14 -4
- package/dist/page-breadcrumbs.d.ts +28 -0
- package/dist/page-breadcrumbs.js +18 -0
- package/dist/page-tabs.js +18 -6
- package/dist/page.d.ts +8 -3
- package/dist/page.js +36 -9
- package/docs/build-and-versioning.md +3 -3
- package/docs/design-system/accessibility.md +7 -4
- package/docs/design-system/custom-properties.md +6 -2
- package/docs/design-system/layout.md +4 -2
- package/docs/design-system/loading.md +2 -0
- package/docs/design-system/overview.md +4 -1
- package/docs/design-system/record-pages.md +197 -0
- package/docs/design-system/toasts.md +2 -3
- package/docs/design-system/typography.md +1 -1
- package/docs/lists.md +10 -2
- package/docs/loading-and-feedback.md +9 -11
- package/docs/overview.md +1 -1
- package/docs/screens.md +78 -33
- package/package.json +21 -21
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
|
|
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,
|
|
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(
|
|
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
|
|
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.
|
|
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 `>=
|
|
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
|
-
`>=
|
|
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.
|
|
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.
|
|
240
|
-
|
|
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
|
|
62
|
-
|
|
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
|
-
|
|
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`
|
|
94
|
-
|
|
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](
|
|
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
|
-
|
|
605
|
-
control is a primary action.
|
|
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
|
|
203
|
-
rows
|
|
204
|
-
dialog and never above the list, and godmin's dialogs and
|
|
205
|
-
do the same. Say what failed, in the words your server sent
|
|
206
|
-
sent some.
|
|
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
|
-
|
|
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 |
|