@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,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,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](../screens.md#page),
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](../lists.md#the-title-field),
55
- [a table that stays custom](../lists.md#lists-that-stay-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. godmin translates them in the WordPress
277
- `default` text domain, as the design system does. The Spanish and
278
- French catalogues that `listChromeCatalogFor` returns hold them, so
279
- load it as [the list chrome](./lists.md#the-list-chrome-in-spanish)
280
- shows.
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