@gopherium/godmin 0.26.0 → 0.28.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 +8 -19
- package/dist/base.css +49 -30
- package/dist/close-while-open.d.ts +6 -0
- package/dist/close-while-open.js +21 -0
- package/dist/focus-back.d.ts +25 -0
- package/dist/focus-back.js +125 -0
- package/dist/index.d.ts +9 -1
- package/dist/index.js +5 -1
- package/dist/list-run.d.ts +7 -2
- package/dist/list-run.js +64 -2
- package/dist/list-view.d.ts +1 -7
- package/dist/list-view.js +1 -16
- package/dist/open-on-tap.d.ts +14 -0
- package/dist/open-on-tap.js +17 -0
- package/dist/run-confirm.d.ts +1 -1
- package/dist/run-confirm.js +4 -2
- package/dist/toaster.d.ts +7 -9
- package/dist/toaster.js +41 -53
- package/dist/unsaved-text.d.ts +14 -0
- package/dist/unsaved-text.js +25 -0
- package/docs/build-and-versioning.md +219 -0
- package/docs/design-system/accessibility.md +200 -0
- package/docs/design-system/color.md +74 -0
- package/docs/design-system/custom-properties.md +60 -0
- package/docs/design-system/layout.md +157 -0
- package/docs/design-system/motion.md +121 -0
- package/docs/design-system/overview.md +107 -0
- package/docs/design-system/radius-and-elevation.md +135 -0
- package/docs/design-system/toasts.md +187 -0
- package/docs/design-system/typography.md +83 -0
- package/docs/framing-an-application.md +386 -0
- package/docs/lists.md +1495 -0
- package/docs/loading-and-feedback.md +165 -0
- package/docs/overview.md +159 -0
- package/docs/screens.md +419 -0
- package/docs/testing.md +193 -0
- package/package.json +6 -1
package/docs/screens.md
ADDED
|
@@ -0,0 +1,419 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Screens and the page kit
|
|
3
|
+
description: Components for the layout every admin screen repeats, a title, some actions, and the content below.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Almost every admin screen has the same top: a title on the left,
|
|
7
|
+
maybe a button or two on the right, and the content below. The page
|
|
8
|
+
kit is that layout as components, so you stop re-typing it.
|
|
9
|
+
|
|
10
|
+
Each component's props interface is exported under its own name,
|
|
11
|
+
such as `PageProps` and `NavigationScreenProps`, for when you wrap
|
|
12
|
+
one in a component of your own.
|
|
13
|
+
|
|
14
|
+
## Page
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
<Page title="Reports" actions={<Button>New report</Button>}>
|
|
18
|
+
<ReportTable />
|
|
19
|
+
</Page>
|
|
20
|
+
```
|
|
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
|
|
24
|
+
`headingLevel`, as [heading levels](#heading-levels) explains.
|
|
25
|
+
`actions` renders top right,
|
|
26
|
+
and `className` and `children` do what they always do. When the
|
|
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.
|
|
36
|
+
|
|
37
|
+
`tabs` renders a row of tabs under the title block. See
|
|
38
|
+
[PageTabs](#pagetabs) below.
|
|
39
|
+
|
|
40
|
+
`aside` adds a second column beside the content, for the details
|
|
41
|
+
that sit next to a record's main work:
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
<Page title="Invoice 1042" aside={<InvoiceDetails />}>
|
|
45
|
+
<InvoiceLines />
|
|
46
|
+
</Page>
|
|
47
|
+
```
|
|
48
|
+
|
|
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
|
+
|
|
57
|
+
`list` marks a page whose content is a list, such as a DataViews
|
|
58
|
+
table. The content then reaches out to the canvas edges, so the
|
|
59
|
+
list's row lines run from edge to edge and its own padding lines up
|
|
60
|
+
with the title. A page with an `aside` keeps its list inside the main
|
|
61
|
+
column. [Lists with DataViews](./lists.md) shows it in full.
|
|
62
|
+
|
|
63
|
+
```tsx
|
|
64
|
+
<Page title="Users" list>
|
|
65
|
+
<UserList />
|
|
66
|
+
</Page>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`listLabel` names the list region, so a screen reader announces it.
|
|
70
|
+
`listRef` hands your code the list, so it can move the focus there.
|
|
71
|
+
With either one, the list can take the focus but stays out of the
|
|
72
|
+
Tab order.
|
|
73
|
+
[Running an action over the picked rows](./lists.md#running-an-action-over-the-picked-rows)
|
|
74
|
+
uses both to move the focus back to the list once a row moved,
|
|
75
|
+
while the reader is still with the run.
|
|
76
|
+
[Putting the focus back on a row](./lists.md#putting-the-focus-back-on-a-row)
|
|
77
|
+
hands the same ref to `useFocusBack`, which puts the focus back on
|
|
78
|
+
the row a dialog opened from.
|
|
79
|
+
|
|
80
|
+
A screen that fills the canvas edge to edge builds its own layout
|
|
81
|
+
and uses `PageTitle` directly, so the page still gets its heading:
|
|
82
|
+
|
|
83
|
+
```tsx
|
|
84
|
+
<PageTitle>Conversations</PageTitle>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
It draws the 15px large heading by default. Pass `variant` to change
|
|
88
|
+
the text size, and `level` to change the heading level.
|
|
89
|
+
|
|
90
|
+
## PageTabs
|
|
91
|
+
|
|
92
|
+
`PageTabs` and `PageTab` split a page into sections that each have
|
|
93
|
+
their own address, like the Subscribers and Settings tabs of a
|
|
94
|
+
WordPress page:
|
|
95
|
+
|
|
96
|
+
```tsx
|
|
97
|
+
<Page
|
|
98
|
+
title="Users"
|
|
99
|
+
list
|
|
100
|
+
tabs={
|
|
101
|
+
<PageTabs label="User sections">
|
|
102
|
+
<PageTab render={<Link to="/users" activeOptions={{ exact: true }} />} current>
|
|
103
|
+
Users
|
|
104
|
+
</PageTab>
|
|
105
|
+
<PageTab render={<Link to="/users/tokens" activeOptions={{ exact: true }} />}>
|
|
106
|
+
API tokens
|
|
107
|
+
</PageTab>
|
|
108
|
+
</PageTabs>
|
|
109
|
+
}
|
|
110
|
+
>
|
|
111
|
+
<UserList />
|
|
112
|
+
</Page>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Each tab is a link. Pass your router's link element as `render`, or
|
|
116
|
+
a plain address as `href`. godmin does not know your router, so it
|
|
117
|
+
renders whatever link you give it and adds its own class. `current`
|
|
118
|
+
marks the tab of the page on screen, and a screen reader hears it as
|
|
119
|
+
the current page.
|
|
120
|
+
|
|
121
|
+
`current` alone decides which tab is underlined. A router link can
|
|
122
|
+
still mark itself as the current page for screen readers. TanStack
|
|
123
|
+
Router counts a link to `/users` as active on `/users/tokens` too,
|
|
124
|
+
so without `activeOptions={{ exact: true }}` a screen reader would
|
|
125
|
+
hear both tabs as the current page. Pass it on every tab link, as the
|
|
126
|
+
example does.
|
|
127
|
+
|
|
128
|
+
`label` names the tab row for assistive technology. The row is a
|
|
129
|
+
navigation region, and a screen reader lists it beside the sidebar,
|
|
130
|
+
so the name tells them apart.
|
|
131
|
+
|
|
132
|
+
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.
|
|
135
|
+
|
|
136
|
+
They are links and not the design system `Tabs` component on
|
|
137
|
+
purpose. `Tabs` switches panels inside one page and moves between
|
|
138
|
+
tabs with the arrow keys. A tab here opens another page, so it is a
|
|
139
|
+
link, reached with Tab and marked with `aria-current`, which is how
|
|
140
|
+
assistive technology expects page navigation to work. godmin copies
|
|
141
|
+
the look of the WordPress tabs and keeps the behavior of links.
|
|
142
|
+
|
|
143
|
+
## SectionTitle
|
|
144
|
+
|
|
145
|
+
`SectionTitle` heads a section inside a page, one size step above
|
|
146
|
+
the field labels, so a section never reads like another label:
|
|
147
|
+
|
|
148
|
+
```tsx
|
|
149
|
+
<SectionTitle>Identities</SectionTitle>
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
It renders an `h2`. Pass `level={3}` for a section inside a section,
|
|
153
|
+
which renders an `h3` a size smaller. `id` and `tabIndex` pass through
|
|
154
|
+
to the heading, so a screen can name a list after it or move focus to
|
|
155
|
+
it.
|
|
156
|
+
|
|
157
|
+
## Heading levels
|
|
158
|
+
|
|
159
|
+
With [the sidebar menu](./framing-an-application.md#the-sidebar-menu),
|
|
160
|
+
the title of the sidebar screen is the `h1`. Then pass
|
|
161
|
+
`headingLevel={2}` to every `Page` beside it:
|
|
162
|
+
|
|
163
|
+
```tsx
|
|
164
|
+
<Page title="Posts" headingLevel={2} list>
|
|
165
|
+
<PostList />
|
|
166
|
+
</Page>
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Every title inside that `Page`, such as a `SectionTitle`, then moves
|
|
170
|
+
down one level. Pass `level={2}` to a `PageTitle` you draw yourself
|
|
171
|
+
beside the sidebar.
|
|
172
|
+
[The heading outline](./design-system/typography.md#the-heading-outline)
|
|
173
|
+
gives the level each title takes, with and without the sidebar.
|
|
174
|
+
|
|
175
|
+
## NavigationScreen
|
|
176
|
+
|
|
177
|
+
`NavigationScreen` draws one screen of
|
|
178
|
+
[the sidebar menu](./framing-an-application.md#the-sidebar-menu),
|
|
179
|
+
the way the WordPress Site Editor draws it: a title row with Back,
|
|
180
|
+
then the content.
|
|
181
|
+
|
|
182
|
+
```tsx
|
|
183
|
+
<NavigationScreen title="Chats" description="Conversations waiting for a reply.">
|
|
184
|
+
<ChatList />
|
|
185
|
+
</NavigationScreen>
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
- `title` is the `h1` of the page, in 20px text. It takes any
|
|
189
|
+
element, so the root screen can hold your brand.
|
|
190
|
+
- Back is a chevron link at the start of the title row. Inside
|
|
191
|
+
`Navigation` it goes to the app's `home`. Pass `back`, a link
|
|
192
|
+
element from your router, to send it somewhere else. The root
|
|
193
|
+
screen has no Back.
|
|
194
|
+
- `backLabel` names Back for assistive technology. It defaults to
|
|
195
|
+
"Back", translated by godmin.
|
|
196
|
+
- `description` renders above the content, and `actions` at the end
|
|
197
|
+
of the title row.
|
|
198
|
+
- `footer` stays at the bottom of the screen while the rest scrolls.
|
|
199
|
+
|
|
200
|
+
A region you leave out renders nothing, not even empty spacing. The
|
|
201
|
+
title row stays at the top while the screen scrolls.
|
|
202
|
+
|
|
203
|
+
The title takes no focus when the screen opens. `Navigation` moves
|
|
204
|
+
the focus itself: to Back when a sub menu opens, and to the row the
|
|
205
|
+
reader came from after Back.
|
|
206
|
+
|
|
207
|
+
## ErrorNotice
|
|
208
|
+
|
|
209
|
+
```tsx
|
|
210
|
+
<ErrorNotice>Reports could not be loaded.</ErrorNotice>
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
It renders the design system's error notice and announces the
|
|
214
|
+
message to screen readers. Use it wherever you would otherwise
|
|
215
|
+
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
|
|
218
|
+
[what goes in a toast](./loading-and-feedback.md#what-goes-in-a-toast)
|
|
219
|
+
explains.
|
|
220
|
+
|
|
221
|
+
## LoadMore
|
|
222
|
+
|
|
223
|
+
`LoadMore` renders a load more button for a paginated list, and
|
|
224
|
+
nothing at all once every page is loaded:
|
|
225
|
+
|
|
226
|
+
```tsx
|
|
227
|
+
<LoadMore query={reports}>Load more reports</LoadMore>
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
`query` needs three members, `hasNextPage`, `isFetchingNextPage`
|
|
231
|
+
and `fetchNextPage`, a shape exported as `LoadMoreQuery`. That is
|
|
232
|
+
what a TanStack Query infinite query looks like, but nothing here
|
|
233
|
+
imports TanStack Query, so any object with those three works. The
|
|
234
|
+
button disables itself while a page is loading.
|
|
235
|
+
|
|
236
|
+
## LogList
|
|
237
|
+
|
|
238
|
+
`LogList` shows items one under the other, such as the dated notes
|
|
239
|
+
kept on a record. Each `LogItem` has a header line, with a label at
|
|
240
|
+
the start and room for actions at the end, then its text, then
|
|
241
|
+
anything else you add:
|
|
242
|
+
|
|
243
|
+
```tsx
|
|
244
|
+
<h3 id="notes-heading">Notes</h3>
|
|
245
|
+
<LogList aria-labelledby="notes-heading">
|
|
246
|
+
{notes.map((note) => (
|
|
247
|
+
<LogItem
|
|
248
|
+
key={note.id}
|
|
249
|
+
aria-label={`Note from ${note.shownAt}`}
|
|
250
|
+
label={<LogTime dateTime={note.at}>{note.shownAt}</LogTime>}
|
|
251
|
+
actions={
|
|
252
|
+
<Button
|
|
253
|
+
variant="minimal"
|
|
254
|
+
size="compact"
|
|
255
|
+
aria-label={`Edit the note from ${note.shownAt}`}
|
|
256
|
+
onClick={() => edit(note.id)}
|
|
257
|
+
>
|
|
258
|
+
Edit
|
|
259
|
+
</Button>
|
|
260
|
+
}
|
|
261
|
+
body={note.text}
|
|
262
|
+
/>
|
|
263
|
+
))}
|
|
264
|
+
</LogList>
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
`aria-labelledby` takes the id of the heading above the list, and
|
|
268
|
+
a screen reader names the list after that heading.
|
|
269
|
+
|
|
270
|
+
`LogTime` shows a date or time as small muted text inside a `time`
|
|
271
|
+
element. Give it the value in machine-readable form as `dateTime`,
|
|
272
|
+
and the words your reader sees as children. godmin formats nothing.
|
|
273
|
+
|
|
274
|
+
The list keeps your order and never sorts, so pass the newest item
|
|
275
|
+
first when the log reads that way. `body` is plain text and keeps its
|
|
276
|
+
line breaks. Put anything richer, such as small "Label: value" lines,
|
|
277
|
+
in the children under it.
|
|
278
|
+
|
|
279
|
+
In a narrow column the actions move under the label and stay at the
|
|
280
|
+
end of the line. No breakpoint decides this, so the list looks right
|
|
281
|
+
in an aside and in the main column alike.
|
|
282
|
+
|
|
283
|
+
A list with no items takes no room, so show your own empty sentence
|
|
284
|
+
beside it. An item with no label and no actions has no header line,
|
|
285
|
+
so you can swap a form in as its only child while someone edits it.
|
|
286
|
+
|
|
287
|
+
An item's `aria-label` names the item, not the buttons inside it. A
|
|
288
|
+
screen reader that lists the buttons on the page still shows every
|
|
289
|
+
one of them as just Edit. So give each action its own name that says
|
|
290
|
+
which item it acts on, as the example does.
|
|
291
|
+
|
|
292
|
+
The list holds no state. Which item is being edited or waiting for a
|
|
293
|
+
confirmation is yours to track, and so is focus.
|
|
294
|
+
|
|
295
|
+
## RepeatRows
|
|
296
|
+
|
|
297
|
+
`RepeatRows` edits a list of rows, such as visits with a date and a
|
|
298
|
+
note each. Every row sets its inputs on one line with a move up
|
|
299
|
+
arrow, a move down arrow and a trash icon at the end, and an add
|
|
300
|
+
button sits under the list. In a narrow list the arrows and the
|
|
301
|
+
trash drop under the inputs, still at the end. Wrap a row's inputs
|
|
302
|
+
in a `godmin-form__row` to set them side by side as well.
|
|
303
|
+
|
|
304
|
+
```tsx
|
|
305
|
+
<RepeatRows
|
|
306
|
+
rows={visits}
|
|
307
|
+
onChange={setVisits}
|
|
308
|
+
blank={() => ({ date: '', note: '' })}
|
|
309
|
+
renderRow={(visit, update) => <VisitFields visit={visit} onChange={update} />}
|
|
310
|
+
rowLabel={(at) => `Visit ${at + 1}`}
|
|
311
|
+
labels={{ add: 'Add visit', empty: 'No visits yet.', moveUp: 'Move up', moveDown: 'Move down', remove: 'Remove' }}
|
|
312
|
+
max={10}
|
|
313
|
+
/>
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
The list stays yours. The editor shows `rows` and hands every change
|
|
317
|
+
to `onChange` as a new array. `min` and `max` only limit remove and
|
|
318
|
+
add. They never trim or pad the rows you pass in.
|
|
319
|
+
|
|
320
|
+
Set the new array right away, not inside `startTransition`. A click
|
|
321
|
+
that lands before your render builds on the rows still shown, so the
|
|
322
|
+
change before it would be lost.
|
|
323
|
+
|
|
324
|
+
Keep each row object `onChange` gives you. The editor tells rows apart
|
|
325
|
+
by identity, so a row rebuilt as a new object counts as a new row and
|
|
326
|
+
its inputs start over.
|
|
327
|
+
|
|
328
|
+
When a keyboard user removes a row, focus moves to the row that took
|
|
329
|
+
its place, or to the row before it when the last row goes. When the
|
|
330
|
+
only row goes, focus moves to the add button. When the add button
|
|
331
|
+
makes a row, focus moves into it.
|
|
332
|
+
|
|
333
|
+
`RowControls` is the move and remove buttons alone, and `useRowKeys`
|
|
334
|
+
is the hook underneath, for a list that needs its own add step. The
|
|
335
|
+
trash sits a little apart from the arrows, so a press that lands
|
|
336
|
+
slightly off does not remove a row.
|
|
337
|
+
|
|
338
|
+
## keyFromLabel
|
|
339
|
+
|
|
340
|
+
`keyFromLabel` turns a label someone typed into a key for code.
|
|
341
|
+
`keyFromLabel('Birth date', { style: 'camel' })` answers `birthDate`,
|
|
342
|
+
and `kebab` style answers `birth-date`. Accents are dropped, and
|
|
343
|
+
letters such as ß and ø are spelled in plain a to z. When the key is
|
|
344
|
+
already in `taken`, the first free number is added, so `birthDate`
|
|
345
|
+
becomes `birthDate2`.
|
|
346
|
+
|
|
347
|
+
## Stylesheet helpers
|
|
348
|
+
|
|
349
|
+
`base.css` ships a few classes for layout jobs every admin screen
|
|
350
|
+
runs into:
|
|
351
|
+
|
|
352
|
+
| Name | For |
|
|
353
|
+
| --- | --- |
|
|
354
|
+
| `godmin-form` | A single column form, up to 560px wide |
|
|
355
|
+
| `godmin-form--inline` | A form that is one row, filling its column |
|
|
356
|
+
| `godmin-form__row` | Short fields side by side inside a form |
|
|
357
|
+
| `godmin-form__grow` | The field of a row that takes most of the free room |
|
|
358
|
+
| `godmin-empty` | A centered empty state with breathing room |
|
|
359
|
+
| `godmin-table` | A full width table with collapsed borders, 13px text on 20px lines |
|
|
360
|
+
| `godmin-table__actions` | The narrow trailing cell holding row actions |
|
|
361
|
+
| `godmin-table__title` | The cell naming the record, bold, its link with no underline |
|
|
362
|
+
| `godmin-table-scroll` | The box a wide table scrolls inside |
|
|
363
|
+
| `godmin-list` | The box around a DataViews list inside a page section, lining its search and cells up with the text around it |
|
|
364
|
+
| `godmin-list-overlay` | An element laid over a list region, such as a drop zone, set after the list |
|
|
365
|
+
|
|
366
|
+
`base.css` also sets a few custom properties, named values such as
|
|
367
|
+
the canvas gutter and the sidebar width.
|
|
368
|
+
[Custom properties](./design-system/custom-properties.md) lists them
|
|
369
|
+
and says which ones your app may read or change.
|
|
370
|
+
|
|
371
|
+
A form row puts short fields and a button on one line:
|
|
372
|
+
|
|
373
|
+
```tsx
|
|
374
|
+
<form className="godmin-form godmin-form--inline">
|
|
375
|
+
<div className="godmin-form__row">
|
|
376
|
+
<InputControl className="godmin-form__grow" label="Title" />
|
|
377
|
+
<InputControl label="Due date" type="date" />
|
|
378
|
+
<Button type="submit">Add</Button>
|
|
379
|
+
</div>
|
|
380
|
+
</form>
|
|
381
|
+
```
|
|
382
|
+
|
|
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.
|
|
389
|
+
|
|
390
|
+
`godmin-table` and `godmin-table-scroll` are a pair, and they solve
|
|
391
|
+
a phone problem: a table wider than the screen drags the whole page
|
|
392
|
+
sideways. Wrapped like this, the table scrolls inside its own box
|
|
393
|
+
instead:
|
|
394
|
+
|
|
395
|
+
```tsx
|
|
396
|
+
<div className="godmin-table-scroll" role="region" aria-label="Reports" tabIndex={0}>
|
|
397
|
+
<table className="godmin-table">…</table>
|
|
398
|
+
</div>
|
|
399
|
+
```
|
|
400
|
+
|
|
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
|
|
404
|
+
desktop the wrapper only draws a focus ring when a keyboard user
|
|
405
|
+
reaches it, so you can mark up every table this way.
|
|
406
|
+
|
|
407
|
+
Every `godmin-table` row takes a light tint under the pointer and
|
|
408
|
+
while keyboard focus is inside it, so a reader can tell which row a
|
|
409
|
+
button belongs to. `RowControls` in the actions cell sit at its right
|
|
410
|
+
edge, so they stay put when the column widens.
|
|
411
|
+
|
|
412
|
+
Two details in that snippet matter:
|
|
413
|
+
|
|
414
|
+
- `tabIndex={0}` makes the box focusable, so a keyboard user can
|
|
415
|
+
scroll to the columns that are out of view. Without it they
|
|
416
|
+
cannot reach them at all.
|
|
417
|
+
- The rule gives the box `position: relative`. Without that,
|
|
418
|
+
absolutely positioned content inside the table escapes the box
|
|
419
|
+
and widens the page, which is the exact bug the wrapper prevents.
|
package/docs/testing.md
ADDED
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Testing
|
|
3
|
+
description: The test setup a design system app needs, and how to assert what it announces.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The design system expects a real browser, and the simulated one
|
|
7
|
+
most test runners use, jsdom, is missing pieces it calls. Without
|
|
8
|
+
help, otherwise fine component tests throw in confusing places.
|
|
9
|
+
`@gopherium/godmin/testing` fills the gaps. Call it once from your
|
|
10
|
+
test setup file:
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
import { installTestEnvironment } from '@gopherium/godmin/testing'
|
|
14
|
+
|
|
15
|
+
installTestEnvironment()
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`@testing-library/react` and `vitest` are optional peer
|
|
19
|
+
dependencies, needed only for this entry point.
|
|
20
|
+
|
|
21
|
+
## What it installs
|
|
22
|
+
|
|
23
|
+
Three browser APIs jsdom leaves out, each of which throws when a
|
|
24
|
+
component calls it:
|
|
25
|
+
|
|
26
|
+
- `window.matchMedia`, used by any component that reads a media
|
|
27
|
+
query.
|
|
28
|
+
- `CSS.supports`, called while a dialog locks body scroll. Without
|
|
29
|
+
it, opening a menu that leads to a dialog throws.
|
|
30
|
+
- `ResizeObserver`, the element resize API.
|
|
31
|
+
|
|
32
|
+
It also clears the rendered tree after each test. A runner
|
|
33
|
+
configured without globals never registers that cleanup itself, so
|
|
34
|
+
trees would pile up and a test could find an element some earlier
|
|
35
|
+
test rendered.
|
|
36
|
+
|
|
37
|
+
## Announcements
|
|
38
|
+
|
|
39
|
+
The design system talks to screen readers through `@wordpress/a11y`,
|
|
40
|
+
which adds two live regions and an intro paragraph to the page
|
|
41
|
+
body. In a test this breaks two things. A query for text that was
|
|
42
|
+
also announced finds two elements instead of one. And the last
|
|
43
|
+
announcement of one test is still in the DOM during the next.
|
|
44
|
+
|
|
45
|
+
`installTestEnvironment` fixes both. Queries skip the announcement
|
|
46
|
+
elements, and they are emptied after each test.
|
|
47
|
+
`WPDS_IGNORE_SELECTOR` is the selector used for the skipping,
|
|
48
|
+
exported in case you configure queries of your own.
|
|
49
|
+
|
|
50
|
+
Since queries can no longer see announcements, read them directly
|
|
51
|
+
when a test needs one:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { getAnnouncement } from '@gopherium/godmin/testing'
|
|
55
|
+
|
|
56
|
+
speak('Draft saved')
|
|
57
|
+
expect(getAnnouncement()).toBe('Draft saved')
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`getAnnouncement()` reads polite announcements, and takes
|
|
61
|
+
`'assertive'` for urgent ones. `clearAnnouncements()` empties both,
|
|
62
|
+
for a test that must assert nothing was announced.
|
|
63
|
+
|
|
64
|
+
## Rendering inside the host
|
|
65
|
+
|
|
66
|
+
`renderAdmin` renders a tree wrapped in `AdminRoot`, so components
|
|
67
|
+
that read design tokens behave like they do in the application. It
|
|
68
|
+
accepts the usual testing library options plus the host theme
|
|
69
|
+
settings, and returns the normal render result. It supplies the
|
|
70
|
+
wrapper itself, so do not pass a `wrapper` of your own.
|
|
71
|
+
|
|
72
|
+
## Simulating a small screen
|
|
73
|
+
|
|
74
|
+
jsdom evaluates no media queries, so a component asking "is this a
|
|
75
|
+
small screen?" always hears no. `setViewport` changes the answer:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
import { setViewport } from '@gopherium/godmin/testing'
|
|
79
|
+
|
|
80
|
+
setViewport({ matches: true })
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Every media query now matches, listeners are told, and components
|
|
84
|
+
re-render. That is how a test renders
|
|
85
|
+
[the narrow shell](./framing-an-application.md). The setting
|
|
86
|
+
resets itself before the next test.
|
|
87
|
+
|
|
88
|
+
## Simulating a width
|
|
89
|
+
|
|
90
|
+
`{ matches: true }` gives every query the same answer, so a test
|
|
91
|
+
cannot sit between two breakpoints with it. Give `setViewport` a
|
|
92
|
+
width instead, and each width query is answered by that number:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
import { SHEET_BREAKPOINT, TITLE_BREAKPOINT } from '@gopherium/godmin'
|
|
96
|
+
import { setViewport } from '@gopherium/godmin/testing'
|
|
97
|
+
|
|
98
|
+
setViewport({ width: 500 })
|
|
99
|
+
|
|
100
|
+
window.matchMedia(`(max-width: ${SHEET_BREAKPOINT - 1}px)`).matches // true
|
|
101
|
+
window.matchMedia(`(max-width: ${TITLE_BREAKPOINT - 1}px)`).matches // false
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
At 500 the test sits between 404 and 599, and at 700 it sits
|
|
105
|
+
between 600 and 781. Listeners are told and components re-render,
|
|
106
|
+
as with `{ matches: true }`.
|
|
107
|
+
|
|
108
|
+
The width answers `min-width` and `max-width` in pixels, the bound
|
|
109
|
+
itself included, as a browser does. A query may join them with
|
|
110
|
+
`and`, and a list of queries parted by commas matches when any of
|
|
111
|
+
them does. The test stands in for a screen, so the media types
|
|
112
|
+
`screen` and `all` hold, with or without `only`. That way the
|
|
113
|
+
queries the WordPress packages ask, such as
|
|
114
|
+
`screen and (max-width: 782px)`, get the answer a browser gives.
|
|
115
|
+
Anything else, such as `print`, `not`, a width in `em` or
|
|
116
|
+
`prefers-reduced-motion`, reports no match while a width is set. The
|
|
117
|
+
width resets before the next test, like the yes or no.
|
|
118
|
+
|
|
119
|
+
At exactly 782 the WordPress packages call the screen narrow, since
|
|
120
|
+
they ask `(max-width: 782px)`, while godmin's breakpoints call it
|
|
121
|
+
wide. A browser shows the same split, so a test at 782 sees it too.
|
|
122
|
+
|
|
123
|
+
A helper of your own can name what it hands on with the
|
|
124
|
+
`TestViewport` type:
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
import { setViewport } from '@gopherium/godmin/testing'
|
|
128
|
+
import type { TestViewport } from '@gopherium/godmin/testing'
|
|
129
|
+
|
|
130
|
+
const PHONE: TestViewport = { width: 390 }
|
|
131
|
+
|
|
132
|
+
setViewport(PHONE)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Giving elements a layout box
|
|
136
|
+
|
|
137
|
+
jsdom lays nothing out, so no element has a size or a place on the
|
|
138
|
+
screen. The WordPress modal looks for the first element it can focus
|
|
139
|
+
among those on screen, finds none, and leaves the focus where it was.
|
|
140
|
+
A test that checks the dialog focused Cancel, or that a form dialog
|
|
141
|
+
put the cursor in its first field, then fails, though a browser
|
|
142
|
+
moves the focus there. `stubLayout` gives every element one small
|
|
143
|
+
box, as a browser does for an element on screen:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
import { stubLayout } from '@gopherium/godmin/testing'
|
|
147
|
+
|
|
148
|
+
test('focuses Cancel when the dialog opens', async () => {
|
|
149
|
+
stubLayout()
|
|
150
|
+
await user.click(screen.getByRole('button', { name: 'Move to trash' }))
|
|
151
|
+
await waitFor(() => expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Cancel' })))
|
|
152
|
+
})
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
The box lasts until the test ends. `installTestEnvironment` takes it
|
|
156
|
+
away after each test, so the next one starts with no layout again.
|
|
157
|
+
Call it only in the tests that check where the focus goes.
|
|
158
|
+
|
|
159
|
+
## Checking a design system look
|
|
160
|
+
|
|
161
|
+
The design system class names change between releases, so a test
|
|
162
|
+
should not type them. `textClasses`, `badgeClasses` and
|
|
163
|
+
`buttonClasses` draw a text, a badge or a button and answer the
|
|
164
|
+
classes it got. Compare your element with them:
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
import { badgeClasses, buttonClasses } from '@gopherium/godmin/testing'
|
|
168
|
+
|
|
169
|
+
expect([...badge.classList]).toEqual(badgeClasses('none'))
|
|
170
|
+
expect([...button.classList]).toEqual(buttonClasses('solid', 'compact'))
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
They take the variant, the intent, and for a button the size and the
|
|
174
|
+
tone.
|
|
175
|
+
|
|
176
|
+
## Checking the element package on React 19
|
|
177
|
+
|
|
178
|
+
`@wordpress/element` 8.4.0 and older do not load on React 19. The
|
|
179
|
+
design system versions godmin supports install a newer one. This
|
|
180
|
+
test fails if an old copy comes back:
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
import { assertElementPatched } from '@gopherium/godmin/testing'
|
|
184
|
+
|
|
185
|
+
test('element works on React 19', async () => {
|
|
186
|
+
await assertElementPatched()
|
|
187
|
+
})
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The assertion checks that the APIs React 19 removed are gone and
|
|
191
|
+
that `createRoot` and `createPortal` are still there. By default it
|
|
192
|
+
imports `@wordpress/element` itself. Pass a loader to point it at a
|
|
193
|
+
specific copy. The name comes from when a patch was needed.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gopherium/godmin",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.28.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",
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
],
|
|
19
19
|
"files": [
|
|
20
20
|
"dist",
|
|
21
|
+
"docs",
|
|
21
22
|
"NOTICE"
|
|
22
23
|
],
|
|
23
24
|
"exports": {
|
|
@@ -106,6 +107,7 @@
|
|
|
106
107
|
"@tanstack/react-router": "1.170.45",
|
|
107
108
|
"@testing-library/react": "^16.3.2",
|
|
108
109
|
"@testing-library/user-event": "^14.6.7",
|
|
110
|
+
"@types/mdast": "4.0.4",
|
|
109
111
|
"@types/node": "^26.1.2",
|
|
110
112
|
"@types/react": "^19.2.17",
|
|
111
113
|
"@vitejs/plugin-react": "^6.0.3",
|
|
@@ -124,7 +126,10 @@
|
|
|
124
126
|
"eslint-plugin-jsdoc": "^63.2.0",
|
|
125
127
|
"eslint-plugin-sonarjs": "^4.2.0",
|
|
126
128
|
"eslint-plugin-tsdoc": "^0.5.2",
|
|
129
|
+
"github-slugger": "2.0.0",
|
|
127
130
|
"jsdom": "^30.1.2",
|
|
131
|
+
"mdast-util-from-markdown": "2.0.3",
|
|
132
|
+
"mdast-util-to-string": "4.0.0",
|
|
128
133
|
"oxlint": "^1.71.0",
|
|
129
134
|
"react": "^19.2.8",
|
|
130
135
|
"react-dom": "^19.2.8",
|