@gopherium/godmin 0.30.0 → 0.32.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 (62) hide show
  1. package/README.md +2 -3
  2. package/dist/base.css +159 -29
  3. package/dist/breakpoints.d.ts +1 -1
  4. package/dist/breakpoints.js +1 -1
  5. package/dist/bulk-run.d.ts +10 -0
  6. package/dist/bulk-run.js +59 -10
  7. package/dist/bulk.d.ts +3 -0
  8. package/dist/confirm-dialog.d.ts +14 -14
  9. package/dist/confirm-dialog.js +8 -28
  10. package/dist/dialog-open.d.ts +63 -0
  11. package/dist/dialog-open.js +110 -0
  12. package/dist/focus-back.d.ts +20 -0
  13. package/dist/focus-back.js +36 -12
  14. package/dist/form-dialog.d.ts +14 -16
  15. package/dist/form-dialog.js +53 -13
  16. package/dist/index.d.ts +13 -13
  17. package/dist/index.js +7 -8
  18. package/dist/list-chrome/es-ES.js +3 -3
  19. package/dist/list-chrome/fr-FR.js +1 -0
  20. package/dist/list-run.js +39 -48
  21. package/dist/page-breadcrumbs.d.ts +28 -0
  22. package/dist/page-breadcrumbs.js +18 -0
  23. package/dist/page-tabs.js +18 -6
  24. package/dist/page.d.ts +8 -3
  25. package/dist/page.js +36 -9
  26. package/dist/rename-dialog.d.ts +24 -0
  27. package/dist/rename-dialog.js +16 -0
  28. package/dist/router.d.ts +2 -0
  29. package/dist/router.js +1 -0
  30. package/dist/toaster.js +21 -2
  31. package/dist/unsaved-changes-dialog.d.ts +19 -0
  32. package/dist/unsaved-changes-dialog.js +33 -0
  33. package/docs/build-and-versioning.md +92 -9
  34. package/docs/design-system/accessibility.md +12 -7
  35. package/docs/design-system/custom-properties.md +6 -2
  36. package/docs/design-system/dialogs.md +240 -0
  37. package/docs/design-system/layout.md +5 -3
  38. package/docs/design-system/lists.md +3 -1
  39. package/docs/design-system/loading.md +2 -0
  40. package/docs/design-system/motion.md +3 -2
  41. package/docs/design-system/overview.md +7 -1
  42. package/docs/design-system/record-pages.md +199 -0
  43. package/docs/design-system/toasts.md +13 -10
  44. package/docs/design-system/typography.md +1 -1
  45. package/docs/lists.md +321 -434
  46. package/docs/loading-and-feedback.md +14 -11
  47. package/docs/overview.md +2 -3
  48. package/docs/screens.md +87 -34
  49. package/docs/testing.md +11 -9
  50. package/package.json +20 -28
  51. package/dist/close-while-open.d.ts +0 -6
  52. package/dist/close-while-open.js +0 -21
  53. package/dist/confirm.d.ts +0 -21
  54. package/dist/confirm.js +0 -11
  55. package/dist/dialogs.d.ts +0 -4
  56. package/dist/dialogs.js +0 -3
  57. package/dist/form.d.ts +0 -28
  58. package/dist/form.js +0 -23
  59. package/dist/rename.d.ts +0 -20
  60. package/dist/rename.js +0 -14
  61. package/dist/run-confirm.d.ts +0 -22
  62. package/dist/run-confirm.js +0 -23
@@ -0,0 +1,199 @@
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, ask before a link in the app
175
+ leaves the page, such as a breadcrumb, as
176
+ [leaving with unsaved work](./dialogs.md#leaving-with-unsaved-work)
177
+ says.
178
+
179
+ ## While a record loads
180
+
181
+ - While nothing of the record is known, the page shows its header and
182
+ one `LoadingScreen`, with no `aside`.
183
+ [A screen](./loading.md#a-screen) gives how it looks. Breadcrumbs
184
+ stay, and the title names the kind of record.
185
+ - A part that loads on its own shows its `LoadingScreen` in its
186
+ column, at the top and centred across that column.
187
+ - Show one `LoadingScreen` at a time, since each one speaks.
188
+ - A record that could not load shows an `ErrorNotice` under the
189
+ title, with no `aside`. Breadcrumbs stay, and the title still names
190
+ the kind of record.
191
+
192
+ ## What a screen reader hears
193
+
194
+ - `asideLabel` makes the details a named region, as
195
+ [landmarks and names](./accessibility.md#landmarks-and-names)
196
+ lists.
197
+ - `PageBreadcrumbs` is a navigation region named by its `label`. The
198
+ slash is hidden.
199
+ - The main work comes first in the reading order at every width.
@@ -32,12 +32,12 @@ floats over the list footer, as it does in WordPress. Two things paint
32
32
  above a toast:
33
33
 
34
34
  - The drawer on a small screen.
35
- - An open dialog. On a wide screen a toast shows dimmed under the dark
36
- layer around the dialog. On a phone it sits behind the sheet. Screen
37
- readers still hear it, because every message is also spoken. Most
38
- dialogs close as their write starts or ends, so their toast shows in
39
- full. A [form dialog](../lists.md#a-form-dialog) stays open after a
40
- failure, so its toast shows under it, as in WordPress.
35
+ - An open dialog. A toast shows dimmed under the dark layer around
36
+ the dialog, at every width. Screen readers still hear it, because
37
+ every message is also spoken. A dialog that closes as its write
38
+ starts or ends shows its toast in full. A dialog that stays open
39
+ says why inside, as [a failed write](./dialogs.md#a-failed-write)
40
+ says.
41
41
 
42
42
  ## Size
43
43
 
@@ -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.
@@ -134,7 +133,11 @@ closes after it leaves, so the toasts above slide instead of jumping.
134
133
 
135
134
  - A click anywhere on a toast clears it, with or without an action.
136
135
  The pointer turns to `--wpds-cursor-control` over every toast.
137
- - A click on the action runs it and clears the toast.
136
+ - A click on the action runs it and clears the toast. The action takes
137
+ a press `--wpds-dimension-gap-sm` (8px) past its words on every
138
+ side, and further past a label too short for that to make 24
139
+ pixels, so its press area is at least 24 by 24 pixels, with no
140
+ change to how it looks.
138
141
  - A click on a toast moves focus to the toast region, as WordPress
139
142
  moves it to its snackbar list. The region draws no ring.
140
143
  - A toast has no close button. WordPress draws its cross only on a
@@ -49,7 +49,7 @@ The smallest size, `--wpds-typography-font-size-xs` (11px), is for
49
49
  small labels such as the count beside a sidebar row.
50
50
 
51
51
  Some parts give the size of their text on their own page:
52
- [the page subtitle](../screens.md#page),
52
+ [the page subtitle](./record-pages.md#the-page-header),
53
53
  [the page tabs](../screens.md#pagetabs),
54
54
  [the title and description of a list row](./lists.md#rows),
55
55
  [a table that stays custom](./lists.md#tables-that-stay-custom),