@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.
@@ -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.
@@ -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.26.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",