@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
package/docs/screens.md CHANGED
@@ -19,40 +19,47 @@ one in a component of your own.
19
19
  </Page>
20
20
  ```
21
21
 
22
- `title` is required and becomes the page's heading, at 15px like the
23
- title of a WordPress page. It is an `h1` unless you pass
22
+ `title` is required and becomes the page's heading, at the size of a
23
+ WordPress page title. It is an `h1` unless you pass
24
24
  `headingLevel`, as [heading levels](#heading-levels) explains.
25
25
  `actions` renders top right,
26
26
  and `className` and `children` do what they always do. When the
27
27
  actions no longer fit beside the title, on a phone for example, they
28
- move to a line of their own under it.
29
-
30
- `subtitle` renders as one 13px grey line under the title and the
31
- actions, the way WordPress sets the sentence under a page title. The
32
- title row is 40px tall even with no actions, so the title and the
33
- subtitle sit in the same place on every page. Give the page compact
34
- buttons, `size="compact"`, to match the 32px buttons of a WordPress
35
- page header.
28
+ move to a line of their own under it. Beside breadcrumbs the title
29
+ gives way first, and the actions move only once it reaches its
30
+ smallest width.
31
+
32
+ `subtitle` renders as one grey line under the title and the actions,
33
+ the way WordPress sets the sentence under a page title. The title row
34
+ keeps its height even with no actions, so the title and the subtitle
35
+ sit in the same place on every page. Give the page compact buttons,
36
+ `size="compact"`, to match the buttons of a WordPress page header. A
37
+ button of the default size makes the row taller.
38
+ [The page header](./design-system/record-pages.md#the-page-header)
39
+ gives the values.
36
40
 
37
41
  `tabs` renders a row of tabs under the title block. See
38
42
  [PageTabs](#pagetabs) below.
39
43
 
40
- `aside` adds a second column beside the content, for the details
41
- that sit next to a record's main work:
44
+ `breadcrumbs` renders links back to what a record belongs to, before
45
+ the title. See [PageBreadcrumbs](#pagebreadcrumbs) below.
46
+
47
+ `aside` adds the details of a record in a fixed column at the end of
48
+ the page. `asideLabel` names that column for a screen reader:
42
49
 
43
50
  ```tsx
44
- <Page title="Invoice 1042" aside={<InvoiceDetails />}>
51
+ <Page title="Invoice 1042" aside={<InvoiceDetails />} asideLabel="Invoice details">
45
52
  <InvoiceLines />
46
53
  </Page>
47
54
  ```
48
55
 
49
- On a wide page the content keeps a 560px column and the aside takes
50
- the rest of the width, so the aside is the part that grows with the
51
- screen. Put the record's own details in the content and its longer
52
- lists, such as a history, in the aside. When the page is too narrow
53
- for both, the aside moves below the content and both fill the page.
54
- No breakpoint decides this, only the page's own width. An aside that
55
- renders nothing takes no room.
56
+ Put what grows, such as the invoice lines or a history, in the
57
+ content, and the record's own short fields and facts in the aside.
58
+ When the page is too narrow for both, the aside moves under the
59
+ content. An aside that renders nothing takes no room. A page with an
60
+ aside keeps its title in view while the content scrolls under it.
61
+ [Record pages](./design-system/record-pages.md) gives every value, and
62
+ what goes where.
56
63
 
57
64
  `list` marks a page whose content is a list, such as a DataViews
58
65
  table. The content then reaches out to the canvas edges, so the
@@ -84,7 +91,7 @@ and uses `PageTitle` directly, so the page still gets its heading:
84
91
  <PageTitle>Conversations</PageTitle>
85
92
  ```
86
93
 
87
- It draws the 15px large heading by default. Pass `variant` to change
94
+ It draws the large heading by default. Pass `variant` to change
88
95
  the text size, and `level` to change the heading level.
89
96
 
90
97
  ## PageTabs
@@ -130,8 +137,10 @@ navigation region, and a screen reader lists it beside the sidebar,
130
137
  so the name tells them apart.
131
138
 
132
139
  The tabs look like the WordPress tabs: 13px labels 16px apart, the
133
- current one underlined by a 2px grey line as wide as its label, and a
134
- 1px light line under the row that runs to the canvas edges.
140
+ current one underlined by a 2px dark line as wide as its label, and a
141
+ 1px light line under the row that runs to the canvas edges. A tab
142
+ under the pointer or the keyboard gets a soft shade that reaches 4px
143
+ past its label. The current tab keeps its plain look under the pointer.
135
144
 
136
145
  They are links and not the design system `Tabs` component on
137
146
  purpose. `Tabs` switches panels inside one page and moves between
@@ -140,6 +149,40 @@ link, reached with Tab and marked with `aria-current`, which is how
140
149
  assistive technology expects page navigation to work. godmin copies
141
150
  the look of the WordPress tabs and keeps the behavior of links.
142
151
 
152
+ ## PageBreadcrumbs
153
+
154
+ `PageBreadcrumbs` and `PageBreadcrumb` lead the title of a record with
155
+ links back to what it belongs to, like `Contacts / Maria Perez`, the
156
+ way a WordPress record page names its list:
157
+
158
+ ```tsx
159
+ <Page
160
+ title="Maria Perez"
161
+ breadcrumbs={
162
+ <PageBreadcrumbs label="Breadcrumbs">
163
+ <PageBreadcrumb render={<Link to="/contacts" />}>Contacts</PageBreadcrumb>
164
+ </PageBreadcrumbs>
165
+ }
166
+ aside={<ContactDetails />}
167
+ >
168
+ <ContactTasks />
169
+ </Page>
170
+ ```
171
+
172
+ Each breadcrumb is a link. Pass your router's link element as
173
+ `render`, or a plain address as `href`, as with `PageTab`. Leave the
174
+ page on screen out of the list, since its title already names it.
175
+
176
+ `label` names the links for assistive technology. They are a
177
+ navigation region, and a screen reader lists it beside the sidebar and
178
+ any tabs, so the name tells them apart. Translate it.
179
+
180
+ Every page opened from a list takes breadcrumbs, a create page too,
181
+ as in `Contacts / New contact`. Beside breadcrumbs the title stays on
182
+ one line, so a long one ends in an ellipsis.
183
+ [The page header](./design-system/record-pages.md#the-page-header)
184
+ gives the values.
185
+
143
186
  ## SectionTitle
144
187
 
145
188
  `SectionTitle` heads a section inside a page, one size step above
@@ -213,8 +256,7 @@ reader came from after Back.
213
256
  It renders the design system's error notice and announces the
214
257
  message to screen readers. Use it wherever you would otherwise
215
258
  render a bare error string, such as a screen that failed to load. A
216
- write that fails in a dialog or in a run over list rows goes in a
217
- toast instead, as
259
+ write that fails goes in a toast instead, as
218
260
  [what goes in a toast](./loading-and-feedback.md#what-goes-in-a-toast)
219
261
  explains.
220
262
 
@@ -351,12 +393,12 @@ runs into:
351
393
 
352
394
  | Name | For |
353
395
  | --- | --- |
354
- | `godmin-form` | A single column form, up to 560px wide |
396
+ | `godmin-form` | A single column form |
355
397
  | `godmin-form--inline` | A form that is one row, filling its column |
356
398
  | `godmin-form__row` | Short fields side by side inside a form |
357
399
  | `godmin-form__grow` | The field of a row that takes most of the free room |
358
400
  | `godmin-empty` | A centered empty state with breathing room |
359
- | `godmin-table` | A full width table with collapsed borders, 13px text on 20px lines |
401
+ | `godmin-table` | A full width table with collapsed borders, drawn like the DataViews table |
360
402
  | `godmin-table__actions` | The narrow trailing cell holding row actions |
361
403
  | `godmin-table__title` | The cell naming the record, bold, its link with no underline |
362
404
  | `godmin-table-scroll` | The box a wide table scrolls inside |
@@ -380,12 +422,14 @@ A form row puts short fields and a button on one line:
380
422
  </form>
381
423
  ```
382
424
 
383
- Each field starts from 160px and they share the rest of the line. The
384
- button keeps its own width. When the line is too narrow, the fields
385
- wrap onto the next line, and a button left alone sits at the end of
386
- its line. A form that is only one row takes `godmin-form--inline`, so
387
- it fills its column instead of stopping at 560px. In a stacked form,
388
- a button keeps its own width instead of stretching across the form.
425
+ Each field takes a share of the line. The button keeps its own width.
426
+ When the line is too narrow, the fields wrap onto the next line, and
427
+ a button left alone sits at the end of its line. A form that is only
428
+ one row takes `godmin-form--inline`, so it fills its column instead
429
+ of stopping at its width. In a stacked form, a button keeps its own
430
+ width instead of stretching across the form.
431
+ [Forms on a page](./design-system/record-pages.md#forms-on-a-page)
432
+ gives the values.
389
433
 
390
434
  `godmin-table` and `godmin-table-scroll` are a pair, and they solve
391
435
  a phone problem: a table wider than the screen drags the whole page
@@ -398,9 +442,12 @@ instead:
398
442
  </div>
399
443
  ```
400
444
 
401
- The scroll rule only activates below 640px. There the actions
402
- column, the cell marked `godmin-table__actions`, stays pinned to the
403
- right edge, so a row's buttons are in view before any scroll. On a
445
+ The scroll rule only activates on a phone, as
446
+ [tables that stay custom](./design-system/lists.md#tables-that-stay-custom)
447
+ gives, and in a column of a record page at every width. On a phone
448
+ the actions column, the cell marked
449
+ `godmin-table__actions`, stays pinned to the right edge, so a row's
450
+ buttons are in view before any scroll. On a
404
451
  desktop the wrapper only draws a focus ring when a keyboard user
405
452
  reaches it, so you can mark up every table this way.
406
453
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gopherium/godmin",
3
- "version": "0.29.1",
3
+ "version": "0.31.0",
4
4
  "description": "The admin kit for Gopherium projects: host layer for React admin applications on the WordPress Design System.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -60,7 +60,7 @@
60
60
  "lint:css": "stylelint 'src/**/*.css'",
61
61
  "storybook:dev": "storybook dev",
62
62
  "storybook:test": "vitest run --project storybook",
63
- "test:browser": "vitest run --project browser",
63
+ "test:browser": "vitest run --project browser --project scrollbars",
64
64
  "typecheck": "tsc --noEmit",
65
65
  "prepublishOnly": "pnpm run build"
66
66
  },
@@ -70,15 +70,15 @@
70
70
  "peerDependencies": {
71
71
  "@tanstack/react-router": "^1.170.44",
72
72
  "@testing-library/react": "^16.3.2",
73
- "@wordpress/a11y": ">=4.57.0 <5.0.0",
74
- "@wordpress/components": ">=42.0.0 <43.0.0",
75
- "@wordpress/dataviews": ">=20.0.0 <21.0.0",
76
- "@wordpress/date": ">=5.57.0 <6.0.0",
77
- "@wordpress/i18n": ">=6.30.0 <7.0.0",
78
- "@wordpress/icons": ">=18.0.0 <19.0.0",
79
- "@wordpress/style-runtime": ">=0.13.0 <0.14.0",
80
- "@wordpress/theme": ">=2.3.0 <3.0.0",
81
- "@wordpress/ui": ">=0.24.0 <0.25.0",
73
+ "@wordpress/a11y": ">=5.0.0 <6.0.0",
74
+ "@wordpress/components": ">=43.0.0 <44.0.0",
75
+ "@wordpress/dataviews": ">=21.0.0 <22.0.0",
76
+ "@wordpress/date": ">=6.0.0 <7.0.0",
77
+ "@wordpress/i18n": ">=7.0.0 <8.0.0",
78
+ "@wordpress/icons": ">=19.0.0 <20.0.0",
79
+ "@wordpress/style-runtime": ">=0.14.0 <0.15.0",
80
+ "@wordpress/theme": ">=3.0.0 <4.0.0",
81
+ "@wordpress/ui": ">=0.25.0 <0.26.0",
82
82
  "react": "^19.2.0",
83
83
  "stylelint": "^16 || ^17",
84
84
  "vitest": "^4.1.10 || ^5.0.0"
@@ -120,16 +120,16 @@
120
120
  "@vitejs/plugin-react": "^6.0.3",
121
121
  "@vitest/browser-playwright": "^5.0.3",
122
122
  "@vitest/coverage-v8": "^5.0.3",
123
- "@wordpress/a11y": "4.57.0",
124
- "@wordpress/components": "42.0.0",
125
- "@wordpress/dataviews": "20.0.0",
126
- "@wordpress/date": "5.57.0",
127
- "@wordpress/element": "9.0.0",
128
- "@wordpress/i18n": "6.30.0",
129
- "@wordpress/icons": "18.0.0",
130
- "@wordpress/style-runtime": "0.13.0",
131
- "@wordpress/theme": "2.3.0",
132
- "@wordpress/ui": "0.24.0",
123
+ "@wordpress/a11y": "5.0.0",
124
+ "@wordpress/components": "43.0.0",
125
+ "@wordpress/dataviews": "21.0.0",
126
+ "@wordpress/date": "6.0.0",
127
+ "@wordpress/element": "10.0.0",
128
+ "@wordpress/i18n": "7.0.0",
129
+ "@wordpress/icons": "19.0.0",
130
+ "@wordpress/style-runtime": "0.14.0",
131
+ "@wordpress/theme": "3.0.0",
132
+ "@wordpress/ui": "0.25.0",
133
133
  "eslint": "^10.7.0",
134
134
  "eslint-plugin-jsdoc": "^63.2.0",
135
135
  "eslint-plugin-sonarjs": "^4.2.0",