@gopherium/godmin 0.31.0 → 0.33.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 (88) hide show
  1. package/README.md +19 -10
  2. package/dist/admin-root.d.ts +4 -2
  3. package/dist/admin-root.js +6 -3
  4. package/dist/announcer-heading.d.ts +4 -0
  5. package/dist/announcer-heading.js +25 -0
  6. package/dist/base.css +42 -17
  7. package/dist/breakpoints.d.ts +1 -1
  8. package/dist/breakpoints.js +1 -1
  9. package/dist/bulk-run.d.ts +10 -0
  10. package/dist/bulk-run.js +76 -11
  11. package/dist/bulk.d.ts +3 -0
  12. package/dist/confirm-dialog.d.ts +14 -14
  13. package/dist/confirm-dialog.js +9 -28
  14. package/dist/dialog-open.d.ts +77 -0
  15. package/dist/dialog-open.js +231 -0
  16. package/dist/drilldown-item.d.ts +5 -2
  17. package/dist/drilldown-item.js +14 -2
  18. package/dist/filter-offer.d.ts +5 -5
  19. package/dist/filter-offer.js +9 -9
  20. package/dist/focus-back.js +12 -2
  21. package/dist/form-dialog.d.ts +14 -16
  22. package/dist/form-dialog.js +54 -13
  23. package/dist/frame.d.ts +8 -4
  24. package/dist/frame.js +16 -6
  25. package/dist/index.d.ts +13 -13
  26. package/dist/index.js +7 -8
  27. package/dist/list-chrome/es-ES.d.ts +1 -1
  28. package/dist/list-chrome/es-ES.js +11 -8
  29. package/dist/list-chrome/fr-FR.d.ts +1 -1
  30. package/dist/list-chrome/fr-FR.js +10 -1
  31. package/dist/list-run.js +25 -44
  32. package/dist/navigation-item.d.ts +4 -2
  33. package/dist/navigation-item.js +2 -2
  34. package/dist/navigation-screen.js +10 -3
  35. package/dist/navigation.js +5 -1
  36. package/dist/page.d.ts +3 -2
  37. package/dist/page.js +23 -4
  38. package/dist/rejected-field.d.ts +25 -0
  39. package/dist/rejected-field.js +121 -0
  40. package/dist/rename-dialog.d.ts +24 -0
  41. package/dist/rename-dialog.js +16 -0
  42. package/dist/route-not-found.d.ts +5 -0
  43. package/dist/route-not-found.js +12 -0
  44. package/dist/router.d.ts +10 -2
  45. package/dist/router.js +11 -2
  46. package/dist/screen-title.d.ts +52 -0
  47. package/dist/screen-title.js +165 -0
  48. package/dist/stylelint.d.ts +1 -4
  49. package/dist/stylelint.js +4 -7
  50. package/dist/testing.d.ts +2 -2
  51. package/dist/testing.js +3 -3
  52. package/dist/toaster.js +21 -2
  53. package/dist/unsaved-changes-dialog.d.ts +19 -0
  54. package/dist/unsaved-changes-dialog.js +33 -0
  55. package/dist/vite.js +1 -0
  56. package/docs/build-and-versioning.md +199 -11
  57. package/docs/design-system/accessibility.md +23 -12
  58. package/docs/design-system/color.md +1 -1
  59. package/docs/design-system/custom-properties.md +3 -3
  60. package/docs/design-system/dialogs.md +302 -0
  61. package/docs/design-system/frame.md +276 -0
  62. package/docs/design-system/layout.md +25 -17
  63. package/docs/design-system/lists.md +20 -12
  64. package/docs/design-system/loading.md +20 -12
  65. package/docs/design-system/motion.md +41 -46
  66. package/docs/design-system/overview.md +11 -3
  67. package/docs/design-system/radius-and-elevation.md +2 -2
  68. package/docs/design-system/record-pages.md +13 -3
  69. package/docs/design-system/toasts.md +18 -8
  70. package/docs/framing-an-application.md +77 -23
  71. package/docs/lists.md +372 -452
  72. package/docs/loading-and-feedback.md +11 -6
  73. package/docs/overview.md +9 -4
  74. package/docs/screens.md +104 -5
  75. package/docs/testing.md +40 -9
  76. package/package.json +27 -27
  77. package/dist/close-while-open.d.ts +0 -6
  78. package/dist/close-while-open.js +0 -21
  79. package/dist/confirm.d.ts +0 -21
  80. package/dist/confirm.js +0 -11
  81. package/dist/dialogs.d.ts +0 -4
  82. package/dist/dialogs.js +0 -3
  83. package/dist/form.d.ts +0 -28
  84. package/dist/form.js +0 -23
  85. package/dist/rename.d.ts +0 -20
  86. package/dist/rename.js +0 -14
  87. package/dist/run-confirm.d.ts +0 -22
  88. package/dist/run-confirm.js +0 -23
@@ -43,6 +43,8 @@ decides how it shows:
43
43
  page, under the title, as on a WordPress screen.
44
44
  - Inside a dialog, when nothing of the dialog body is known yet. It
45
45
  shows at once there too.
46
+ [When to ask first](./design-system/dialogs.md#when-to-ask-first)
47
+ says when an action opens a dialog at all.
46
48
  - Alone, when nothing of the screen is known yet, such as while the
47
49
  session loads before the frame is drawn. It then waits a moment, so
48
50
  a fast load shows nothing, and fades in, in the middle of the space
@@ -199,12 +201,15 @@ Name an item in straight double quotes and in full, like
199
201
  snackbar, and godmin does not either.
200
202
  [Size](./design-system/toasts.md#size) says how a long one wraps.
201
203
 
202
- Use a toast for a write that failed too, in a dialog, on a page or in
203
- a run over list rows. WordPress shows those in its snackbar, never
204
- inside the dialog and never above the list, and godmin's dialogs and
205
- list runs do the same. Say what failed, in the words your server sent
206
- when it sent some. A server message about one field goes under that
207
- field. [A failure from a dialog](./lists.md#a-failure-from-a-dialog)
204
+ Use a toast for a write that failed too, on a page or in a run over
205
+ list rows. WordPress shows those in its snackbar, never above the
206
+ list, and godmin's list runs do the same. A dialog that closes says
207
+ how its write went in a toast too. A dialog that stays open says why
208
+ inside, as [a failed write](./design-system/dialogs.md#a-failed-write)
209
+ says.
210
+ Say what failed, in the words your server sent when it sent some. A
211
+ server message about one field goes under that field.
212
+ [A failure from a dialog](./lists.md#a-failure-from-a-dialog)
208
213
  shows how to raise one from a dialog.
209
214
  [Running an action over the picked rows](./lists.md#running-an-action-over-the-picked-rows)
210
215
  raises it for you after a run over a list.
package/docs/overview.md CHANGED
@@ -29,11 +29,10 @@ duplicates something the packages above already ship.
29
29
 
30
30
  | Entry point | Contents |
31
31
  | --- | --- |
32
- | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `PageBreadcrumbs`, `PageBreadcrumb`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ListNoResults`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `useCloseWhileOpen`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
32
+ | `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `PageBreadcrumbs`, `PageBreadcrumb`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ListNoResults`, `ConfirmDialog`, `FormDialog`, `RenameDialog`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `useDialogRun`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `useRejectedField`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
33
33
  | `@gopherium/godmin/base.css` | Cascade layer order, design tokens, host rules, frame and screen styles |
34
34
  | `@gopherium/godmin/dates` | `startListDates`, `listDate`, the only entry that loads `@wordpress/date` |
35
- | `@gopherium/godmin/dialogs` | `ConfirmDialog`, `FormDialog`, the only entry that loads `@wordpress/components`. Load `@wordpress/components/build-style/style.css` once in your app, as DataViews asks |
36
- | `@gopherium/godmin/router` | `Navigation`, `NavigationList`, `NavigationItem`, `DrilldownItem`, `useCanAccess` and the `MenuItem` type with its optional `count`, `useListView`, `listSearch`, `openOnTap`, `useCanvas`, `useFrameLocation`, `routerDefaults`, the `canvas`, `Sidebar` and `capability` route static data |
35
+ | `@gopherium/godmin/router` | `Navigation`, `NavigationList`, `NavigationItem`, `DrilldownItem`, `useCanAccess` and the `MenuItem` type with its optional `count`, `useListView`, `listSearch`, `openOnTap`, `useCanvas`, `useFrameLocation`, `useShownPath`, `routerDefaults` and its not found screen, `UnsavedChangesDialog`, the `canvas`, `Sidebar` and `capability` route static data |
37
36
  | `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport` and its `TestViewport` type, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR`, `textClasses`, `badgeClasses`, `buttonClasses`, `stubLayout` |
38
37
  | `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy`, `godminStylesheetFirst`, `duplicateCopies`, `hoistStylesheet` |
39
38
  | `@gopherium/godmin/stylelint` | The design system stylelint rules |
@@ -63,7 +62,7 @@ import '@gopherium/godmin/base.css'
63
62
  import { AdminRoot } from '@gopherium/godmin'
64
63
 
65
64
  createRoot(document.getElementById('app')!).render(
66
- <AdminRoot>
65
+ <AdminRoot writeTimeout={settings.writeTimeout}>
67
66
  <YourApp />
68
67
  </AdminRoot>,
69
68
  )
@@ -84,6 +83,12 @@ That is the whole setup. Here is what those two lines do for you:
84
83
  - Give the page the design system's own blue as its accent, the
85
84
  color of primary buttons, selected rows and focus rings. Pass
86
85
  your own `color` to use another one.
86
+ - Give every busy dialog a time limit for its write. `writeTimeout`
87
+ is required and takes it in milliseconds. Read it from your app's
88
+ own settings, here `settings.writeTimeout`, since godmin sets no
89
+ limit of its own.
90
+ [While a write runs](./design-system/dialogs.md#while-a-write-runs)
91
+ says what a dialog does when the limit runs out.
87
92
 
88
93
  `AdminRoot` also accepts the `color`, `cursor` and `cornerRadius`
89
94
  theme settings, which it hands to the design system theme provider,
package/docs/screens.md CHANGED
@@ -21,7 +21,10 @@ one in a component of your own.
21
21
 
22
22
  `title` is required and becomes the page's heading, at the size of a
23
23
  WordPress page title. It is an `h1` unless you pass
24
- `headingLevel`, as [heading levels](#heading-levels) explains.
24
+ `headingLevel`, as [heading levels](#heading-levels) explains. It is
25
+ also what a screen reader hears when the screen opens, as
26
+ [what a screen reader hears when the screen changes](./design-system/frame.md#what-a-screen-reader-hears-when-the-screen-changes)
27
+ says.
25
28
  `actions` renders top right,
26
29
  and `className` and `children` do what they always do. When the
27
30
  actions no longer fit beside the title, on a phone for example, they
@@ -85,7 +88,9 @@ hands the same ref to `useFocusBack`, which puts the focus back on
85
88
  the row a dialog opened from.
86
89
 
87
90
  A screen that fills the canvas edge to edge builds its own layout
88
- and uses `PageTitle` directly, so the page still gets its heading:
91
+ and uses `PageTitle` directly, so the page still gets its heading.
92
+ Give it plain text, since that text is also what a screen reader
93
+ hears when the screen opens:
89
94
 
90
95
  ```tsx
91
96
  <PageTitle>Conversations</PageTitle>
@@ -160,7 +165,7 @@ way a WordPress record page names its list:
160
165
  title="Maria Perez"
161
166
  breadcrumbs={
162
167
  <PageBreadcrumbs label="Breadcrumbs">
163
- <PageBreadcrumb render={<Link to="/contacts" />}>Contacts</PageBreadcrumb>
168
+ <PageBreadcrumb render={<Link to="/contacts" activeOptions={{ exact: true }} />}>Contacts</PageBreadcrumb>
164
169
  </PageBreadcrumbs>
165
170
  }
166
171
  aside={<ContactDetails />}
@@ -173,6 +178,13 @@ Each breadcrumb is a link. Pass your router's link element as
173
178
  `render`, or a plain address as `href`, as with `PageTab`. Leave the
174
179
  page on screen out of the list, since its title already names it.
175
180
 
181
+ No breadcrumb is the current page, yet a router link can mark itself
182
+ as one for screen readers. TanStack Router counts a link to
183
+ `/contacts` as active on `/contacts/42` too, so without
184
+ `activeOptions={{ exact: true }}` a screen reader would hear the
185
+ breadcrumb as the page on screen. Pass it on every breadcrumb link, as
186
+ the example does.
187
+
176
188
  `label` names the links for assistive technology. They are a
177
189
  navigation region, and a screen reader lists it beside the sidebar and
178
190
  any tabs, so the name tells them apart. Translate it.
@@ -234,8 +246,19 @@ then the content.
234
246
  `Navigation` it goes to the app's `home`. Pass `back`, a link
235
247
  element from your router, to send it somewhere else. The root
236
248
  screen has no Back.
249
+ - Back draws the link you pass with the chevron in place of anything
250
+ the link holds. Its own class comes first and the link's class
251
+ after it. The link's `onClick` runs first, and Back records its
252
+ move only when that click did not call `preventDefault()`. The
253
+ link's `style` and data attributes stay.
237
254
  - `backLabel` names Back for assistive technology. It defaults to
238
- "Back", translated by godmin.
255
+ "Back", translated by godmin. An `aria-label` on the link you pass
256
+ wins over it.
257
+ - Back is your router's own link, so it carries the mark of the
258
+ current page, which a screen reader hears, while a slow `home`
259
+ loads. Let the loader of `home` answer fast, as
260
+ [the sidebar marks](./design-system/frame.md#the-sidebar-marks)
261
+ says.
239
262
  - `description` renders above the content, and `actions` at the end
240
263
  of the title row.
241
264
  - `footer` stays at the bottom of the screen while the rest scrolls.
@@ -258,7 +281,8 @@ message to screen readers. Use it wherever you would otherwise
258
281
  render a bare error string, such as a screen that failed to load. A
259
282
  write that fails goes in a toast instead, as
260
283
  [what goes in a toast](./loading-and-feedback.md#what-goes-in-a-toast)
261
- explains.
284
+ explains. A dialog that stays open draws its own notice, as
285
+ [a failed write](./design-system/dialogs.md#a-failed-write) says.
262
286
 
263
287
  ## LoadMore
264
288
 
@@ -386,6 +410,81 @@ letters such as ß and ø are spelled in plain a to z. When the key is
386
410
  already in `taken`, the first free number is added, so `birthDate`
387
411
  becomes `birthDate2`.
388
412
 
413
+ ## A server message under a field
414
+
415
+ Some values only the server can reject, such as an email address
416
+ another account already uses. Its words then go under the field they
417
+ are about, the way a check made before sending would.
418
+ `useRejectedField` holds those words for one field.
419
+
420
+ Here `invite` answers the server's words about the email, or nothing
421
+ when it worked.
422
+
423
+ ```tsx
424
+ const [email, setEmail] = useState('')
425
+ const rejectedEmail = useRejectedField(email)
426
+ const toaster = useToaster()
427
+ const send = async () => {
428
+ const sent = email
429
+ const words = await invite(sent.trim())
430
+ if (words === undefined || rejectedEmail.reject(words, sent)) {
431
+ return
432
+ }
433
+ toaster.show(`Could not send the invitation. ${words}`)
434
+ }
435
+
436
+ return (
437
+ <form
438
+ className="godmin-form"
439
+ onSubmit={(event) => {
440
+ event.preventDefault()
441
+ void send()
442
+ }}
443
+ >
444
+ <ValidatedInputControl
445
+ ref={rejectedEmail.ref}
446
+ label="Email"
447
+ type="email"
448
+ value={email}
449
+ onChange={(event) => setEmail(event.target.value)}
450
+ customValidity={rejectedEmail.validity}
451
+ />
452
+ <Button type="submit">Send</Button>
453
+ </form>
454
+ )
455
+ ```
456
+
457
+ - Pass what the words are about. In most forms that is the value of
458
+ the field, as the field holds it. Trim only what goes to the
459
+ server. When the answer also depends on another field, join both
460
+ into one string, such as `${kind}:${value}`, and send the same
461
+ string to `reject`.
462
+ - Hand `ref` to the field's `ref` and `validity` to its
463
+ `customValidity`. Both fit the WPDS validated fields. The hook finds
464
+ the form through the field.
465
+ - `reject(message, sent)` puts the words under the field and answers
466
+ `true`. It answers `false` when there are no words, when the field
467
+ changed while the send was on its way, or when the field is not on
468
+ the page inside a form. Say it another way then, in a toast on a
469
+ page.
470
+ - The focus moves to the first field that fails, and a screen reader
471
+ hears the server's words at once.
472
+ - The words go at the first edit. Typing the rejected value again does
473
+ not bring them back, so the reader may send it again.
474
+ - While the words stand, the browser holds the form back from
475
+ sending. A form with `noValidate` sends anyway, and the words are
476
+ spoken again when the server rejects the value again.
477
+ - Give each field its own hook. When one answer rejects several, the
478
+ focus goes to the first, and only one set of words is spoken.
479
+ - Call `reject` once the answer came, never while rendering, and never
480
+ in an answer that also leaves the screen.
481
+ - In a `FormDialog`, answer `{ close: false }` when `reject` answers
482
+ `true`, so the dialog stays open on the words, and
483
+ `{ error: words }` when it answers `false`.
484
+
485
+ [Announcements](./testing.md#announcements) shows how a test reads
486
+ what was spoken.
487
+
389
488
  ## Stylesheet helpers
390
489
 
391
490
  `base.css` ships a few classes for layout jobs every admin screen
package/docs/testing.md CHANGED
@@ -61,6 +61,12 @@ expect(getAnnouncement()).toBe('Draft saved')
61
61
  `'assertive'` for urgent ones. `clearAnnouncements()` empties both,
62
62
  for a test that must assert nothing was announced.
63
63
 
64
+ A frame given `shownPath` speaks the title of each new screen
65
+ assertively, so a test that moves to another screen and then reads
66
+ `'assertive'` meets that title, as
67
+ [what a screen reader hears when the screen changes](./design-system/frame.md#what-a-screen-reader-hears-when-the-screen-changes)
68
+ says.
69
+
64
70
  ## Rendering inside the host
65
71
 
66
72
  `renderAdmin` renders a tree wrapped in `AdminRoot`, so components
@@ -69,6 +75,29 @@ accepts the usual testing library options plus the host theme
69
75
  settings, and returns the normal render result. It supplies the
70
76
  wrapper itself, so do not pass a `wrapper` of your own.
71
77
 
78
+ It also takes `writeTimeout`, the time limit `AdminRoot` gives a
79
+ busy dialog's write. Leave it out and the test has no limit, so a
80
+ write that never ends keeps its dialog busy for as long as the test
81
+ reads it. Pass a short limit to check what a dialog shows once its
82
+ write runs past it:
83
+
84
+ ```tsx
85
+ import { renderAdmin } from '@gopherium/godmin/testing'
86
+
87
+ const SHORT_LIMIT = 20
88
+
89
+ test('says the server gave no answer when the rename never ends', async () => {
90
+ renderAdmin(<RenamePostDialog post={post} rename={() => new Promise(() => {})} />, { writeTimeout: SHORT_LIMIT })
91
+ await user.click(screen.getByRole('button', { name: 'Save' }))
92
+ expect(await screen.findByText('Could not get a valid response from the server.')).toBeVisible()
93
+ })
94
+ ```
95
+
96
+ The limit runs on the real clock, so keep it short. A test on fake
97
+ timers moves its clock past the limit instead.
98
+ [While a write runs](./design-system/dialogs.md#while-a-write-runs)
99
+ says what the dialog shows and frees.
100
+
72
101
  ## Simulating a small screen
73
102
 
74
103
  jsdom evaluates no media queries, so a component asking "is this a
@@ -135,20 +164,22 @@ setViewport(PHONE)
135
164
  ## Giving elements a layout box
136
165
 
137
166
  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:
167
+ screen. The `Modal` of `@wordpress/components`, such as one your app
168
+ draws itself or one DataViews opens for an action with a
169
+ `RenderModal`, looks for the first element it can focus among those
170
+ on screen, finds none, and leaves the focus where it was.
171
+ A test that checks such a modal put the cursor in its first field
172
+ then fails, though a browser moves the focus there. godmin's own
173
+ dialogs need no box for that. `stubLayout` gives every element one
174
+ small box, as a browser does for an element on screen:
144
175
 
145
176
  ```ts
146
177
  import { stubLayout } from '@gopherium/godmin/testing'
147
178
 
148
- test('focuses Cancel when the dialog opens', async () => {
179
+ test('puts the cursor in the note field when the export modal opens', async () => {
149
180
  stubLayout()
150
- await user.click(screen.getByRole('button', { name: 'Move to trash' }))
151
- await waitFor(() => expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Cancel' })))
181
+ await user.click(screen.getByRole('button', { name: 'Export' }))
182
+ await waitFor(() => expect(document.activeElement).toBe(screen.getByRole('textbox', { name: 'Note' })))
152
183
  })
153
184
  ```
154
185
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gopherium/godmin",
3
- "version": "0.31.0",
3
+ "version": "0.33.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",
@@ -21,6 +21,9 @@
21
21
  "docs",
22
22
  "NOTICE"
23
23
  ],
24
+ "sideEffects": [
25
+ "**/*.css"
26
+ ],
24
27
  "exports": {
25
28
  ".": {
26
29
  "types": "./dist/index.d.ts",
@@ -31,10 +34,6 @@
31
34
  "types": "./dist/dates.d.ts",
32
35
  "default": "./dist/dates.js"
33
36
  },
34
- "./dialogs": {
35
- "types": "./dist/dialogs.d.ts",
36
- "default": "./dist/dialogs.js"
37
- },
38
37
  "./router": {
39
38
  "types": "./dist/router.d.ts",
40
39
  "default": "./dist/router.js"
@@ -70,15 +69,15 @@
70
69
  "peerDependencies": {
71
70
  "@tanstack/react-router": "^1.170.44",
72
71
  "@testing-library/react": "^16.3.2",
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",
72
+ "@wordpress/a11y": ">=5.1.0 <6.0.0",
73
+ "@wordpress/dataviews": ">=22.0.0 <23.0.0",
74
+ "@wordpress/date": ">=6.1.0 <7.0.0",
75
+ "@wordpress/i18n": ">=7.1.0 <8.0.0",
76
+ "@wordpress/icons": ">=20.0.0 <21.0.0",
77
+ "@wordpress/style-runtime": ">=0.15.0 <0.16.0",
78
+ "@wordpress/theme": ">=4.0.0 <5.0.0",
79
+ "@wordpress/theme-build-tools": ">=1.0.0 <2.0.0",
80
+ "@wordpress/ui": ">=0.26.0 <0.27.0",
82
81
  "react": "^19.2.0",
83
82
  "stylelint": "^16 || ^17",
84
83
  "vitest": "^4.1.10 || ^5.0.0"
@@ -90,15 +89,15 @@
90
89
  "@testing-library/react": {
91
90
  "optional": true
92
91
  },
93
- "@wordpress/components": {
94
- "optional": true
95
- },
96
92
  "@wordpress/dataviews": {
97
93
  "optional": true
98
94
  },
99
95
  "@wordpress/date": {
100
96
  "optional": true
101
97
  },
98
+ "@wordpress/theme-build-tools": {
99
+ "optional": true
100
+ },
102
101
  "stylelint": {
103
102
  "optional": true
104
103
  },
@@ -120,16 +119,17 @@
120
119
  "@vitejs/plugin-react": "^6.0.3",
121
120
  "@vitest/browser-playwright": "^5.0.3",
122
121
  "@vitest/coverage-v8": "^5.0.3",
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",
122
+ "@wordpress/a11y": "5.1.0",
123
+ "@wordpress/components": "44.0.0",
124
+ "@wordpress/dataviews": "22.0.0",
125
+ "@wordpress/date": "6.1.0",
126
+ "@wordpress/element": "10.1.0",
127
+ "@wordpress/i18n": "7.1.0",
128
+ "@wordpress/icons": "20.0.0",
129
+ "@wordpress/style-runtime": "0.15.0",
130
+ "@wordpress/theme": "4.0.0",
131
+ "@wordpress/theme-build-tools": "1.0.0",
132
+ "@wordpress/ui": "0.26.0",
133
133
  "eslint": "^10.7.0",
134
134
  "eslint-plugin-jsdoc": "^63.2.0",
135
135
  "eslint-plugin-sonarjs": "^4.2.0",
@@ -1,6 +0,0 @@
1
- /**
2
- * Returns the close of a dialog body that acts only while that body is on screen, never on a dialog opened since.
3
- * @param close - Closes the dialog, none for a body drawn outside a dialog.
4
- * @returns The close, which does nothing once the body left the screen.
5
- */
6
- export declare function useCloseWhileOpen(close: (() => void) | undefined): () => void;
@@ -1,21 +0,0 @@
1
- // SPDX-License-Identifier: Apache-2.0
2
- import { useEffect, useRef } from 'react';
3
- /**
4
- * Returns the close of a dialog body that acts only while that body is on screen, never on a dialog opened since.
5
- * @param close - Closes the dialog, none for a body drawn outside a dialog.
6
- * @returns The close, which does nothing once the body left the screen.
7
- */
8
- export function useCloseWhileOpen(close) {
9
- const open = useRef(true);
10
- useEffect(() => {
11
- open.current = true;
12
- return () => {
13
- open.current = false;
14
- };
15
- }, []);
16
- return () => {
17
- if (open.current) {
18
- close?.();
19
- }
20
- };
21
- }
package/dist/confirm.d.ts DELETED
@@ -1,21 +0,0 @@
1
- import type { ReactNode } from 'react';
2
- export interface ConfirmBodyProps {
3
- /** The question the modal asks. */
4
- children: ReactNode;
5
- /** The label of the button that carries the action out. */
6
- confirmLabel: string;
7
- /** The label of the button that closes the modal. */
8
- cancelLabel: string;
9
- /** Whether the action is running, the confirm button then busy and Cancel greyed out. */
10
- busy?: boolean;
11
- /** Carries the action out. */
12
- onConfirm: () => void;
13
- /** Closes the modal. */
14
- onCancel?: () => void;
15
- }
16
- /**
17
- * Renders a confirmation modal body: the question, an accent text Cancel and the confirm button, 20px apart.
18
- * @param props - The question, the labels, the busy flag and the handlers.
19
- * @returns The confirmation body.
20
- */
21
- export declare function ConfirmBody({ children, confirmLabel, cancelLabel, busy, onConfirm, onCancel, }: ConfirmBodyProps): import("react").JSX.Element;
package/dist/confirm.js DELETED
@@ -1,11 +0,0 @@
1
- import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- // SPDX-License-Identifier: Apache-2.0
3
- import { Button, Stack, Text } from '@wordpress/ui';
4
- /**
5
- * Renders a confirmation modal body: the question, an accent text Cancel and the confirm button, 20px apart.
6
- * @param props - The question, the labels, the busy flag and the handlers.
7
- * @returns The confirmation body.
8
- */
9
- export function ConfirmBody({ children, confirmLabel, cancelLabel, busy = false, onConfirm, onCancel, }) {
10
- return (_jsxs("div", { className: "godmin-modal-body", children: [_jsx(Text, { className: "godmin-modal-body__question", children: children }), _jsxs(Stack, { direction: "row", gap: "sm", justify: "flex-end", children: [_jsx(Button, { variant: "minimal", disabled: busy, onClick: onCancel, children: cancelLabel }), _jsx(Button, { loading: busy, onClick: onConfirm, children: confirmLabel })] })] }));
11
- }
package/dist/dialogs.d.ts DELETED
@@ -1,4 +0,0 @@
1
- export { ConfirmDialog } from './confirm-dialog.js';
2
- export type { ConfirmDialogProps } from './confirm-dialog.js';
3
- export { FormDialog } from './form-dialog.js';
4
- export type { FormDialogProps } from './form-dialog.js';
package/dist/dialogs.js DELETED
@@ -1,3 +0,0 @@
1
- // SPDX-License-Identifier: Apache-2.0
2
- export { ConfirmDialog } from './confirm-dialog.js';
3
- export { FormDialog } from './form-dialog.js';
package/dist/form.d.ts DELETED
@@ -1,28 +0,0 @@
1
- import type { ReactNode } from 'react';
2
- /** What a form does, which sets the space above its buttons as WordPress spaces it. */
3
- export type FormKind = 'edit' | 'copy' | 'create';
4
- /** The props of the body of a form modal. */
5
- export interface FormBodyProps {
6
- /** The fields, and any help sentence before them, in the order the reader meets them. */
7
- children: ReactNode;
8
- /** The label of the button that sends the form. */
9
- submitLabel: string;
10
- /** The label of the button that closes the modal. */
11
- cancelLabel: string;
12
- /** Whether the form may be sent now, false while a needed field is empty, true when left out. */
13
- canSubmit?: boolean;
14
- /** Whether the write runs, the submit button then busy and a second send ignored. */
15
- busy?: boolean;
16
- /** What the form does: 20px above the buttons for an edit, the default, 12px for a copy, 16px for a create. */
17
- kind?: FormKind;
18
- /** Sends the form, from the submit button or Enter in a field. */
19
- onSubmit: () => void;
20
- /** Closes the modal. */
21
- onCancel?: () => void;
22
- }
23
- /**
24
- * Renders the body of a form modal: the fields, an accent text Cancel and the submit button.
25
- * @param props - The fields, the labels, the send gate, the busy flag, the kind and the handlers.
26
- * @returns The form.
27
- */
28
- export declare function FormBody({ children, submitLabel, cancelLabel, canSubmit, busy, kind, onSubmit, onCancel, }: FormBodyProps): import("react").JSX.Element;
package/dist/form.js DELETED
@@ -1,23 +0,0 @@
1
- import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- // SPDX-License-Identifier: Apache-2.0
3
- import { Button, Stack } from '@wordpress/ui';
4
- /** The classes of a form body of each kind. */
5
- const KIND_CLASSES = {
6
- edit: 'godmin-modal-body',
7
- copy: 'godmin-modal-body godmin-modal-body--copy',
8
- create: 'godmin-modal-body godmin-modal-body--create',
9
- };
10
- /**
11
- * Renders the body of a form modal: the fields, an accent text Cancel and the submit button.
12
- * @param props - The fields, the labels, the send gate, the busy flag, the kind and the handlers.
13
- * @returns The form.
14
- */
15
- export function FormBody({ children, submitLabel, cancelLabel, canSubmit = true, busy = false, kind = 'edit', onSubmit, onCancel, }) {
16
- const sendable = canSubmit && !busy;
17
- return (_jsxs("form", { className: KIND_CLASSES[kind], onSubmit: (event) => {
18
- event.preventDefault();
19
- if (sendable) {
20
- onSubmit();
21
- }
22
- }, children: [children, _jsxs(Stack, { direction: "row", gap: "sm", justify: "flex-end", children: [_jsx(Button, { variant: "minimal", onClick: onCancel, children: cancelLabel }), _jsx(Button, { type: "submit", loading: busy, disabled: !sendable, children: submitLabel })] })] }));
23
- }
package/dist/rename.d.ts DELETED
@@ -1,20 +0,0 @@
1
- export interface RenameBodyProps {
2
- /** The text the field starts with: the name the item carries, or the name a failed write turned away. */
3
- name: string;
4
- /** The label of the name field. */
5
- fieldLabel: string;
6
- /** The label of the button that writes the new name. */
7
- submitLabel: string;
8
- /** The label of the button that closes the modal. */
9
- cancelLabel: string;
10
- /** Writes the name as typed, the one the item already has included. */
11
- onSubmit: (name: string) => void;
12
- /** Closes the modal. */
13
- onCancel?: () => void;
14
- }
15
- /**
16
- * Renders the body of a rename modal: the name field, an accent text Cancel and the submit button, off while blank.
17
- * @param props - The first name, the labels and the handlers.
18
- * @returns The rename form.
19
- */
20
- export declare function RenameBody({ name, fieldLabel, submitLabel, cancelLabel, onSubmit, onCancel }: RenameBodyProps): import("react").JSX.Element;
package/dist/rename.js DELETED
@@ -1,14 +0,0 @@
1
- import { jsx as _jsx } from "react/jsx-runtime";
2
- // SPDX-License-Identifier: Apache-2.0
3
- import { InputControl } from '@wordpress/ui';
4
- import { useState } from 'react';
5
- import { FormBody } from './form.js';
6
- /**
7
- * Renders the body of a rename modal: the name field, an accent text Cancel and the submit button, off while blank.
8
- * @param props - The first name, the labels and the handlers.
9
- * @returns The rename form.
10
- */
11
- export function RenameBody({ name, fieldLabel, submitLabel, cancelLabel, onSubmit, onCancel }) {
12
- const [value, setValue] = useState(name);
13
- return (_jsx(FormBody, { submitLabel: submitLabel, cancelLabel: cancelLabel, canSubmit: value.trim() !== '', onSubmit: () => onSubmit(value), onCancel: onCancel, children: _jsx(InputControl, { label: fieldLabel, value: value, onChange: (event) => setValue(event.target.value) }) }));
14
- }
@@ -1,22 +0,0 @@
1
- import type { ReactNode } from 'react';
2
- /** The props of a run confirm, the first two as a DataViews modal hands them. */
3
- export interface RunConfirmProps<Item> {
4
- /** The items the action runs over. */
5
- items: Item[];
6
- /** Closes the modal. */
7
- closeModal?: () => void;
8
- /** The question the modal asks. */
9
- children: ReactNode;
10
- /** The label of the button that starts the run. */
11
- confirmLabel: string;
12
- /** The label of the button that closes the modal. */
13
- cancelLabel: string;
14
- /** Runs the action over the items, settling once the list shows how it went. */
15
- run: (items: Item[]) => Promise<unknown>;
16
- }
17
- /**
18
- * Renders a confirmation that runs the action, keeps Cancel inert while it runs and closes only itself once it settles.
19
- * @param props - The items, the close handler, the question, the labels and the run.
20
- * @returns The confirmation body.
21
- */
22
- export declare function RunConfirm<Item>({ items, closeModal, children, confirmLabel, cancelLabel, run, }: RunConfirmProps<Item>): import("react").JSX.Element;
@@ -1,23 +0,0 @@
1
- import { jsx as _jsx } from "react/jsx-runtime";
2
- // SPDX-License-Identifier: Apache-2.0
3
- import { useState } from 'react';
4
- import { useCloseWhileOpen } from './close-while-open.js';
5
- import { ConfirmBody } from './confirm.js';
6
- /**
7
- * Renders a confirmation that runs the action, keeps Cancel inert while it runs and closes only itself once it settles.
8
- * @param props - The items, the close handler, the question, the labels and the run.
9
- * @returns The confirmation body.
10
- */
11
- export function RunConfirm({ items, closeModal, children, confirmLabel, cancelLabel, run, }) {
12
- const [busy, setBusy] = useState(false);
13
- const close = useCloseWhileOpen(closeModal);
14
- return (_jsx(ConfirmBody, { confirmLabel: confirmLabel, cancelLabel: cancelLabel, busy: busy, onCancel: closeModal, onConfirm: () => {
15
- setBusy(true);
16
- void Promise.resolve()
17
- .then(() => run(items))
18
- .finally(() => {
19
- setBusy(false);
20
- close();
21
- });
22
- }, children: children }));
23
- }