@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.
- package/README.md +4 -3
- package/dist/base.css +223 -13
- package/dist/bulk-run.d.ts +3 -3
- package/dist/bulk-run.js +41 -13
- package/dist/focus-back.d.ts +22 -0
- package/dist/focus-back.js +37 -13
- package/dist/index.d.ts +5 -3
- package/dist/index.js +4 -3
- package/dist/list-chrome/es-ES.d.ts +1 -1
- package/dist/list-chrome/es-ES.js +7 -4
- package/dist/list-chrome/fr-FR.d.ts +1 -1
- package/dist/list-chrome/fr-FR.js +5 -1
- package/dist/list-empty.d.ts +14 -7
- package/dist/list-empty.js +14 -4
- package/dist/list-run.d.ts +8 -4
- package/dist/list-run.js +143 -6
- package/dist/page-breadcrumbs.d.ts +28 -0
- package/dist/page-breadcrumbs.js +18 -0
- package/dist/page-tabs.js +29 -26
- package/dist/page.d.ts +8 -3
- package/dist/page.js +48 -9
- package/dist/size-watch.d.ts +11 -0
- package/dist/size-watch.js +36 -0
- package/dist/wide-list.d.ts +7 -0
- package/dist/wide-list.js +33 -0
- package/docs/build-and-versioning.md +3 -3
- package/docs/design-system/accessibility.md +64 -16
- package/docs/design-system/custom-properties.md +9 -2
- package/docs/design-system/layout.md +5 -3
- package/docs/design-system/lists.md +234 -0
- package/docs/design-system/loading.md +2 -0
- package/docs/design-system/overview.md +6 -1
- package/docs/design-system/radius-and-elevation.md +3 -9
- package/docs/design-system/record-pages.md +197 -0
- package/docs/design-system/toasts.md +2 -3
- package/docs/design-system/typography.md +3 -3
- package/docs/framing-an-application.md +7 -5
- package/docs/lists.md +278 -72
- package/docs/loading-and-feedback.md +9 -11
- package/docs/overview.md +1 -1
- package/docs/screens.md +83 -36
- package/package.json +21 -21
|
@@ -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,10 +49,10 @@ 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
|
-
[the title and description of a list row](
|
|
55
|
-
[a table that stays custom](
|
|
54
|
+
[the title and description of a list row](./lists.md#rows),
|
|
55
|
+
[a table that stays custom](./lists.md#tables-that-stay-custom),
|
|
56
56
|
[a toast](./toasts.md#text) and
|
|
57
57
|
[the letter of an avatar](../lists.md#avatars).
|
|
58
58
|
|
|
@@ -273,11 +273,13 @@ const sheet = useMediaQuery(`(max-width: ${SHEET_BREAKPOINT - 1}px)`)
|
|
|
273
273
|
The frame and the sidebar draw a few words of their own: "Back",
|
|
274
274
|
"Navigation", "Open navigation panel" and "Close navigation panel".
|
|
275
275
|
The last one names a close button at the end of the drawer, which
|
|
276
|
-
only a screen reader meets.
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
276
|
+
only a screen reader meets. `ListNoResults` draws two more: "No
|
|
277
|
+
results found" and the line under it, "Try adjusting your search or
|
|
278
|
+
filters to find what you're looking for." godmin translates them in
|
|
279
|
+
the WordPress `default` text domain, as the design system does. The
|
|
280
|
+
Spanish and French catalogues that `listChromeCatalogFor` returns
|
|
281
|
+
hold them, so load it as
|
|
282
|
+
[the list chrome](./lists.md#the-list-chrome-in-spanish) shows.
|
|
281
283
|
|
|
282
284
|
## Coloring the regions
|
|
283
285
|
|