@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
package/README.md CHANGED
@@ -36,12 +36,16 @@ import '@gopherium/godmin/base.css'
36
36
  import { AdminRoot } from '@gopherium/godmin'
37
37
 
38
38
  createRoot(document.getElementById('app')!).render(
39
- <AdminRoot>
39
+ <AdminRoot writeTimeout={settings.writeTimeout}>
40
40
  <YourApp />
41
41
  </AdminRoot>,
42
42
  )
43
43
  ```
44
44
 
45
+ `writeTimeout` is how long, in milliseconds, a busy dialog waits on its write
46
+ before it gives up. Read it from your app's own settings, here
47
+ `settings.writeTimeout`. GodMin sets no limit of its own.
48
+
45
49
  That is the whole host setup. See [the overview](docs/overview.md) for what
46
50
  those two lines do for you.
47
51
 
@@ -49,11 +53,10 @@ those two lines do for you.
49
53
 
50
54
  | Entry point | Contents |
51
55
  | --- | --- |
52
- | `@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` |
56
+ | `@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` |
53
57
  | `@gopherium/godmin/base.css` | Cascade layer order, design tokens, host rules, frame and screen styles |
54
58
  | `@gopherium/godmin/dates` | `startListDates`, `listDate`, the only entry that loads `@wordpress/date` |
55
- | `@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 |
56
- | `@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 |
59
+ | `@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 |
57
60
  | `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport` and its `TestViewport` type, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR`, `textClasses`, `badgeClasses`, `buttonClasses`, `stubLayout` |
58
61
  | `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy`, `godminStylesheetFirst`, `duplicateCopies`, `hoistStylesheet` |
59
62
  | `@gopherium/godmin/stylelint` | The design system stylelint rules |
@@ -63,11 +66,16 @@ those two lines do for you.
63
66
  GodMin speaks a few words of its own: Back on a sidebar screen, the name of
64
67
  the sidebar column and its phone drawer, the phone menu button and the
65
68
  drawer's close button, which only a screen reader meets, and "No results
66
- found" with the line under it, which `ListNoResults` shows. It
67
- translates them in the WordPress `default` text domain, as `@wordpress/ui`
68
- translates its own, so `@wordpress/i18n` is a required peer. Every app
69
- already has it, since
70
- `@wordpress/ui` depends on it.
69
+ found" with the line under it, which `ListNoResults` shows. It also gives
70
+ the words of the tab title, the screen title then the app name as
71
+ `%1$s ‹ %2$s`, and of the not found screen `routerDefaults` gives, "Route
72
+ not found" with the line "The page you're looking for does not exist". A
73
+ dialog whose write ran past its time limit says WordPress's words, "Could not
74
+ get a valid response from the server.", or "Unable to connect. Please check
75
+ your Internet connection." while the browser is offline. It translates them
76
+ in the WordPress `default` text domain, as `@wordpress/ui` translates its
77
+ own, so `@wordpress/i18n` is a required peer. Every app already has it,
78
+ since `@wordpress/ui` depends on it.
71
79
 
72
80
  `listChromeCatalogFor` returns the catalogue GodMin ships for a language,
73
81
  Spanish and French today. Both hold these words and the list dates, and the
@@ -89,7 +97,8 @@ if (catalogue !== undefined) {
89
97
  Duplicate packages break the application, and nothing points at the cause.
90
98
  Two copies of React throw on the first hook. Two copies of `@wordpress/theme`
91
99
  render unthemed components with no error. Spread `godminDedupe` into
92
- `resolve.dedupe` and add the `godminSingleCopy()` plugin.
100
+ `resolve.dedupe` and add the `godminSingleCopy()` plugin. The list holds
101
+ godmin itself, since a second copy splits the toaster.
93
102
  [Build configuration](docs/build-and-versioning.md) covers both, and lists the
94
103
  design system versions each release supports.
95
104
 
@@ -4,11 +4,13 @@ type ThemeSettings = Pick<ComponentProps<typeof ThemeProvider>, 'color' | 'curso
4
4
  export interface AdminRootProps extends ThemeSettings {
5
5
  children: ReactNode;
6
6
  as?: ElementType;
7
+ /** How long in milliseconds a busy dialog waits on its write, from the app's own settings, Infinity for no limit. */
8
+ writeTimeout: number;
7
9
  }
8
10
  /**
9
11
  * Hosts a design system application in its own stacking context.
10
- * @param props - The theme settings, root element type and children.
12
+ * @param props - The theme settings, the write time limit, the root element type and the children.
11
13
  * @returns The host element wrapping the themed children.
12
14
  */
13
- export declare function AdminRoot({ children, as: Root, color, ...theme }: AdminRootProps): import("react").JSX.Element;
15
+ export declare function AdminRoot({ children, as: Root, color, writeTimeout, ...theme }: AdminRootProps): import("react").JSX.Element;
14
16
  export {};
@@ -2,14 +2,17 @@ import { jsx as _jsx } from "react/jsx-runtime";
2
2
  // SPDX-License-Identifier: Apache-2.0
3
3
  import { ThemeProvider } from '@wordpress/theme';
4
4
  import { useEnableWpCompatOverlaySlot } from '@wordpress/ui';
5
+ import { useAnnouncerHeading } from './announcer-heading.js';
6
+ import { WriteTimeoutContext, checkedWriteTimeout } from './dialog-open.js';
5
7
  /** The design system's own primary color, seeded when an application names none. */
6
8
  const DEFAULT_COLOR = { primary: '#3858e9' };
7
9
  /**
8
10
  * Hosts a design system application in its own stacking context.
9
- * @param props - The theme settings, root element type and children.
11
+ * @param props - The theme settings, the write time limit, the root element type and the children.
10
12
  * @returns The host element wrapping the themed children.
11
13
  */
12
- export function AdminRoot({ children, as: Root = 'div', color = DEFAULT_COLOR, ...theme }) {
14
+ export function AdminRoot({ children, as: Root = 'div', color = DEFAULT_COLOR, writeTimeout, ...theme }) {
13
15
  useEnableWpCompatOverlaySlot();
14
- return (_jsx(Root, { style: { isolation: 'isolate' }, children: _jsx(ThemeProvider, { color: color, ...theme, isRoot: true, children: children }) }));
16
+ useAnnouncerHeading();
17
+ return (_jsx(Root, { style: { isolation: 'isolate' }, children: _jsx(ThemeProvider, { color: color, ...theme, isRoot: true, children: _jsx(WriteTimeoutContext.Provider, { value: checkedWriteTimeout(writeTimeout), children: children }) }) }));
15
18
  }
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Keeps the live region heading in the loaded language while the caller is mounted.
3
+ */
4
+ export declare function useAnnouncerHeading(): void;
@@ -0,0 +1,25 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { __, subscribe } from '@wordpress/i18n';
3
+ import { useEffect } from 'react';
4
+ /** The id `@wordpress/a11y` gives the hidden text it puts before the live regions it adds to the page. */
5
+ const HEADING_ID = 'a11y-speak-intro-text';
6
+ /**
7
+ * Writes the live region heading in the language loaded now, when the page holds one.
8
+ */
9
+ function writeHeading() {
10
+ const heading = document.getElementById(HEADING_ID);
11
+ if (heading !== null) {
12
+ heading.textContent = __('Notifications');
13
+ }
14
+ }
15
+ /**
16
+ * Keeps the live region heading in the loaded language while the caller is mounted.
17
+ */
18
+ export function useAnnouncerHeading() {
19
+ useEffect(() => {
20
+ writeHeading();
21
+ return subscribe(() => {
22
+ writeHeading();
23
+ });
24
+ }, []);
25
+ }
package/dist/base.css CHANGED
@@ -92,7 +92,7 @@ body {
92
92
  @media (width > 782px) {
93
93
  /* Sets where the frozen title starts, the width of the checkbox column. */
94
94
  .godmin-page__list--wide:has(td .dataviews-title-field) .dataviews-view-table.has-bulk-actions {
95
- --godmin-list-frozen-start: calc(var(--wpds-dimension-padding-2xl) + var(--wpds-dimension-size-sm));
95
+ --godmin-list-frozen-start: calc(var(--wpds-dimension-padding-2xl) + var(--wpds-dimension-size-2xs));
96
96
  }
97
97
 
98
98
  /* Sizes the checkbox column to the width where the frozen title starts. */
@@ -156,7 +156,7 @@ body {
156
156
 
157
157
  .godmin-layout {
158
158
  display: flex;
159
- height: 100vh;
159
+ height: 100dvh;
160
160
  background: var(--wpds-color-background-surface-neutral-weak);
161
161
  color: var(--wpds-color-foreground-content-neutral);
162
162
  --wp-ui-drawer-z-index: 2;
@@ -229,6 +229,30 @@ body {
229
229
  cursor: var(--wpds-cursor-control);
230
230
  }
231
231
 
232
+ @media not (prefers-reduced-motion) {
233
+ .godmin-layout__drawer {
234
+ transition-duration: var(--wpds-motion-duration-md);
235
+ transition-timing-function: ease-out;
236
+ }
237
+
238
+ .godmin-layout__drawer[data-ending-style] {
239
+ transition-duration: calc(var(--drawer-swipe-strength) * var(--wpds-motion-duration-md));
240
+ }
241
+
242
+ [role='presentation']:has(+ * > .godmin-layout__drawer) {
243
+ transition-duration: var(--wpds-motion-duration-md);
244
+ transition-timing-function: ease-out;
245
+ }
246
+
247
+ [role='presentation'][data-swiping]:has(+ * > .godmin-layout__drawer) {
248
+ transition-duration: 0ms;
249
+ }
250
+ }
251
+
252
+ .godmin-layout__drawer:dir(rtl) {
253
+ box-shadow: -2px 0 8px rgba(0, 0, 0, 0.2);
254
+ }
255
+
232
256
  .godmin-sidebar__content {
233
257
  flex: 1 1 0;
234
258
  min-height: 0;
@@ -415,6 +439,7 @@ body {
415
439
  }
416
440
 
417
441
  .godmin-toast__action {
442
+ position: relative;
418
443
  flex: none;
419
444
  margin-inline-start: var(--wpds-dimension-gap-2xl);
420
445
  padding: 0;
@@ -429,6 +454,12 @@ body {
429
454
  cursor: var(--wpds-cursor-control);
430
455
  }
431
456
 
457
+ .godmin-toast__action::after {
458
+ content: '';
459
+ position: absolute;
460
+ inset: min(calc(-1 * var(--wpds-dimension-gap-sm)), calc(50% - 12px));
461
+ }
462
+
432
463
  .godmin-toast__action:hover {
433
464
  text-decoration: none;
434
465
  }
@@ -1039,22 +1070,12 @@ body {
1039
1070
  align-self: flex-start;
1040
1071
  }
1041
1072
 
1042
- .godmin-modal-body {
1043
- display: flex;
1044
- flex-direction: column;
1045
- gap: calc(var(--wpds-dimension-gap-lg) + var(--wpds-dimension-gap-xs));
1046
- }
1047
-
1048
- .godmin-modal-body--copy {
1049
- gap: var(--wpds-dimension-gap-md);
1050
- }
1051
-
1052
- .godmin-modal-body--create {
1053
- gap: var(--wpds-dimension-gap-lg);
1073
+ .godmin-dialog-popup {
1074
+ overflow-wrap: break-word;
1054
1075
  }
1055
1076
 
1056
- .godmin-modal-body__question {
1057
- line-height: 1.4;
1077
+ .godmin-dialog-popup > * > h2 {
1078
+ min-inline-size: 0;
1058
1079
  }
1059
1080
 
1060
1081
  .godmin-form__row {
@@ -1193,7 +1214,7 @@ body {
1193
1214
  align-items: center;
1194
1215
  justify-content: center;
1195
1216
  box-sizing: border-box;
1196
- min-block-size: 100vh;
1217
+ min-block-size: 100dvh;
1197
1218
  padding: var(--wpds-dimension-padding-3xl);
1198
1219
  opacity: 0;
1199
1220
  animation: godmin-fade-in 500ms ease 200ms forwards;
@@ -1339,6 +1360,10 @@ body {
1339
1360
  border-radius: 0;
1340
1361
  box-shadow: none;
1341
1362
  }
1363
+
1364
+ .godmin-navigation__screen-wrapper {
1365
+ animation-duration: 0s;
1366
+ }
1342
1367
  }
1343
1368
 
1344
1369
  @media (max-width: 639px) {
@@ -15,7 +15,7 @@ export declare const EDGE_BREAKPOINT = 782;
15
15
  */
16
16
  export declare const DENSE_BREAKPOINT = 640;
17
17
  /**
18
- * The viewport width below which modals rise as sheets and toasts widen to the screen, the WordPress small breakpoint.
18
+ * The viewport width below which toasts widen to the screen, the WordPress small breakpoint.
19
19
  */
20
20
  export declare const SHEET_BREAKPOINT = 600;
21
21
  /**
@@ -15,7 +15,7 @@ export const EDGE_BREAKPOINT = 782;
15
15
  */
16
16
  export const DENSE_BREAKPOINT = 640;
17
17
  /**
18
- * The viewport width below which modals rise as sheets and toasts widen to the screen, the WordPress small breakpoint.
18
+ * The viewport width below which toasts widen to the screen, the WordPress small breakpoint.
19
19
  */
20
20
  export const SHEET_BREAKPOINT = 600;
21
21
  /**
@@ -1,7 +1,10 @@
1
1
  import type { BulkWords } from './bulk.js';
2
+ import type { DialogAnswer } from './dialog-open.js';
2
3
  import type { ListRun } from './list-run.js';
3
4
  /** Runs one call over each item, reports what the run reached in the given words and then reloads the list. */
4
5
  export type BulkRun<Item> = (items: Item[], call: (item: Item) => Promise<unknown>, words: BulkWords<Item>) => Promise<void>;
6
+ /** Runs a dialog's write over one item or several until the dialog's signal fires, and answers what to do next. */
7
+ export type DialogRun<Item> = (items: Item[], call: (item: Item) => Promise<unknown>, words: BulkWords<Item>, signal: AbortSignal) => Promise<DialogAnswer | undefined>;
5
8
  /**
6
9
  * Returns the handler that runs a call per item, marks the list reloading at the first that works, toasts at the last.
7
10
  * @param list - What the list does around a run.
@@ -9,3 +12,10 @@ export type BulkRun<Item> = (items: Item[], call: (item: Item) => Promise<unknow
9
12
  * @returns The run handler, the same while the list run and the refresh stay the same.
10
13
  */
11
14
  export declare function useBulkRun<Item>(list: ListRun, refresh: (items: Item[]) => Promise<unknown>): BulkRun<Item>;
15
+ /**
16
+ * Returns the handler that runs a dialog's write on a list: one item that failed answers its words, else a toast.
17
+ * @param list - What the list does around a run.
18
+ * @param refresh - Reloads the list once the last call ended, given the items the run acted on.
19
+ * @returns The run handler, the same while the list run and the refresh stay the same.
20
+ */
21
+ export declare function useDialogRun<Item>(list: ListRun, refresh: (items: Item[]) => Promise<unknown>): DialogRun<Item>;
package/dist/bulk-run.js CHANGED
@@ -16,6 +16,22 @@ function reloadOnce(list) {
16
16
  end: () => ended?.(),
17
17
  };
18
18
  }
19
+ /**
20
+ * Returns the call on one item that fails with the signal's reason once it fires, never started when it fired already.
21
+ * @param call - The action on one item.
22
+ * @param signal - The signal that stops the run, none for a run that waits for every call.
23
+ * @returns The call that stops on the signal, the given call itself when there is none.
24
+ */
25
+ function stopping(call, signal) {
26
+ if (signal === undefined) {
27
+ return call;
28
+ }
29
+ return async (item) => new Promise((settle, fail) => {
30
+ signal.throwIfAborted();
31
+ signal.addEventListener('abort', () => fail(signal.reason), { once: true });
32
+ void Promise.resolve(call(item)).then(settle, fail);
33
+ });
34
+ }
19
35
  /**
20
36
  * Returns the call on one item that fails as the given call fails, and calls `worked` once it works.
21
37
  * @param call - The action on one item.
@@ -43,28 +59,77 @@ function bulkToast(items, outcome, words) {
43
59
  return notes.notice ?? notes.toast;
44
60
  }
45
61
  /**
46
- * Returns the handler that runs a call per item, marks the list reloading at the first that works, toasts at the last.
62
+ * Returns the action the toast of a run offers, the words' Undo once every item finished, none otherwise.
63
+ * @param items - The items the run was given.
64
+ * @param outcome - What the run reached.
65
+ * @param words - The words of the run.
66
+ * @returns The action, none when an item failed or the words give no Undo.
67
+ */
68
+ function doneAction(items, outcome, words) {
69
+ return outcome.failures.length === 0 ? words.undo?.(items) : undefined;
70
+ }
71
+ /**
72
+ * Shows the one toast a run's outcome reads as, with the words' Undo once every item finished.
73
+ * @param toaster - Where the toast shows.
74
+ * @param items - The items the run was given.
75
+ * @param outcome - What the run reached.
76
+ * @param words - The words of the run.
77
+ */
78
+ function toastOutcome(toaster, items, outcome, words) {
79
+ const message = bulkToast(items, outcome, words);
80
+ if (message !== undefined) {
81
+ toaster.show(message, doneAction(items, outcome, words));
82
+ }
83
+ }
84
+ /**
85
+ * Returns the handler that runs a call per item, marks the list reloading at the first that works, reports at the last.
47
86
  * @param list - What the list does around a run.
48
87
  * @param refresh - Reloads the list once the last call ended, given the items the run acted on.
49
- * @returns The run handler, the same while the list run and the refresh stay the same.
88
+ * @param report - Reports what the run reached and gives what the handler answers.
89
+ * @returns The run handler, the same while the list run, the refresh and the report stay the same.
50
90
  */
51
- export function useBulkRun(list, refresh) {
52
- const toaster = useToaster();
53
- return useCallback(async (items, call, words) => {
91
+ function useListWrite(list, refresh, report) {
92
+ return useCallback(async (given, call, words, signal) => {
93
+ const items = given.filter(() => true);
54
94
  const settle = list.onStart();
55
95
  const reload = reloadOnce(list);
56
- const outcome = await runEach(items, reporting(call, reload.mark));
96
+ const outcome = await runEach(items, reporting(stopping(call, signal), reload.mark));
57
97
  void Promise.resolve()
58
98
  .then(() => refresh(items))
59
99
  .then(reload.end, reload.end);
60
100
  try {
61
- const message = bulkToast(items, outcome, words);
62
- if (message !== undefined) {
63
- toaster.show(message);
64
- }
101
+ return report(items, outcome, words);
65
102
  }
66
103
  finally {
67
104
  settle(outcome.done > 0);
68
105
  }
69
- }, [list, refresh, toaster]);
106
+ }, [list, refresh, report]);
107
+ }
108
+ /**
109
+ * Returns the handler that runs a call per item, marks the list reloading at the first that works, toasts at the last.
110
+ * @param list - What the list does around a run.
111
+ * @param refresh - Reloads the list once the last call ended, given the items the run acted on.
112
+ * @returns The run handler, the same while the list run and the refresh stay the same.
113
+ */
114
+ export function useBulkRun(list, refresh) {
115
+ const toaster = useToaster();
116
+ const report = useCallback((items, outcome, words) => toastOutcome(toaster, items, outcome, words), [toaster]);
117
+ return useListWrite(list, refresh, report);
118
+ }
119
+ /**
120
+ * Returns the handler that runs a dialog's write on a list: one item that failed answers its words, else a toast.
121
+ * @param list - What the list does around a run.
122
+ * @param refresh - Reloads the list once the last call ended, given the items the run acted on.
123
+ * @returns The run handler, the same while the list run and the refresh stay the same.
124
+ */
125
+ export function useDialogRun(list, refresh) {
126
+ const toaster = useToaster();
127
+ const report = useCallback((items, outcome, words) => {
128
+ if (outcome.asked === 1 && outcome.done === 0) {
129
+ return { error: words.failed(outcome.failures, 1) };
130
+ }
131
+ toastOutcome(toaster, items, outcome, words);
132
+ return undefined;
133
+ }, [toaster]);
134
+ return useListWrite(list, refresh, report);
70
135
  }
package/dist/bulk.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { ToastAction } from './toaster.js';
1
2
  /** An item a bulk run could not finish, with the error its call failed with. */
2
3
  export interface BulkFailure<Item> {
3
4
  /** The item the call was made for. */
@@ -27,6 +28,8 @@ export interface BulkWords<Item> {
27
28
  done: (count: number, only: Item | undefined) => string;
28
29
  /** The toast for the items that failed, shown instead of the done one, given each failure and how many were asked. */
29
30
  failed: (failures: BulkFailure<Item>[], asked: number) => string;
31
+ /** The action the done toast offers once every item finished, such as Undo, given the items. */
32
+ undo?: (items: Item[]) => ToastAction;
30
33
  }
31
34
  /** The messages a bulk outcome reads as, each absent when nothing calls for it. */
32
35
  export interface BulkNotes {
@@ -1,24 +1,24 @@
1
- import type { ReactNode } from 'react';
2
- /** The props of a confirmation dialog for an action outside a list. */
1
+ import type { DialogAnswer } from './dialog-open.js';
2
+ /** The props of a dialog that asks one question before an action. */
3
3
  export interface ConfirmDialogProps {
4
- /** The question the dialog asks, its name when it has no title. */
5
- children: ReactNode;
6
- /** The title of a plain confirm, drawn in a header with a close button, none on a confirm that removes something. */
7
- title?: string;
8
- /** The width of the card from 600px up, small at 400px or medium at 560px, the default. */
9
- size?: 'small' | 'medium';
4
+ /** The question the dialog asks, its name. */
5
+ title: string;
6
+ /** What will happen, in plain words. */
7
+ description?: string;
8
+ /** Whether the action cannot be undone, which draws its button red. */
9
+ intent?: 'default' | 'irreversible';
10
10
  /** The label of the button that carries the action out. */
11
11
  confirmLabel: string;
12
12
  /** The label of the button that closes the dialog. */
13
13
  cancelLabel: string;
14
- /** Carries the action out. Return nothing to close at once, or the write's promise to stay busy until it ends. */
15
- onConfirm: () => void | Promise<unknown>;
16
- /** Takes the dialog away after Cancel, Escape, a click outside it, its close button or a confirm that finished. */
14
+ /** Runs the action with the time limit's signal. Return nothing to close, the write to stay busy, or an answer. */
15
+ onConfirm: (signal: AbortSignal) => void | DialogAnswer | PromiseLike<unknown>;
16
+ /** Takes the dialog away, once its card has left the page. */
17
17
  onClose: () => void;
18
18
  }
19
19
  /**
20
- * Renders a confirmation dialog for an action outside a list, as WordPress dialogs ask, Cancel focused.
21
- * @param props - The question, the title, the size, the labels and the handlers.
20
+ * Renders a dialog that asks one question before an action, on the WPDS alert dialog, with Cancel focused.
21
+ * @param props - The question, what will happen, the intent, the labels and the handlers.
22
22
  * @returns The dialog.
23
23
  */
24
- export declare function ConfirmDialog({ children, title, size, confirmLabel, cancelLabel, onConfirm, onClose, }: ConfirmDialogProps): import("react").JSX.Element;
24
+ export declare function ConfirmDialog({ title, description, intent, confirmLabel, cancelLabel, onConfirm, onClose, }: ConfirmDialogProps): import("react").JSX.Element;
@@ -1,34 +1,15 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  // SPDX-License-Identifier: Apache-2.0
3
- import { Modal } from '@wordpress/components';
4
- import { useId, useRef, useState } from 'react';
5
- import { ConfirmBody } from './confirm.js';
3
+ import { AlertDialog } from '@wordpress/ui';
4
+ import { POPUP_CLASS, refuseRepeatedEnter, refuseSecondClick, useAnswering, useDialogOpen, useFinalFocus, } from './dialog-open.js';
6
5
  /**
7
- * Renders a confirmation dialog for an action outside a list, as WordPress dialogs ask, Cancel focused.
8
- * @param props - The question, the title, the size, the labels and the handlers.
6
+ * Renders a dialog that asks one question before an action, on the WPDS alert dialog, with Cancel focused.
7
+ * @param props - The question, what will happen, the intent, the labels and the handlers.
9
8
  * @returns The dialog.
10
9
  */
11
- export function ConfirmDialog({ children, title, size = 'medium', confirmLabel, cancelLabel, onConfirm, onClose, }) {
12
- const [busy, setBusy] = useState(false);
13
- const open = useRef(true);
14
- const question = useId();
15
- const close = () => {
16
- if (open.current) {
17
- open.current = false;
18
- onClose();
19
- }
20
- };
21
- const confirm = () => {
22
- const running = onConfirm();
23
- if (!(running instanceof Promise)) {
24
- close();
25
- return;
26
- }
27
- setBusy(true);
28
- void running.finally(() => {
29
- setBusy(false);
30
- close();
31
- });
32
- };
33
- return (_jsx(Modal, { size: size, focusOnMount: "firstContentElement", title: title, __experimentalHideHeader: title === undefined, aria: { labelledby: question, describedby: title === undefined ? undefined : question }, onRequestClose: close, children: _jsx(ConfirmBody, { confirmLabel: confirmLabel, cancelLabel: cancelLabel, busy: busy, onConfirm: confirm, onCancel: close, children: _jsx("span", { id: question, children: children }) }) }));
10
+ export function ConfirmDialog({ title, description, intent, confirmLabel, cancelLabel, onConfirm, onClose, }) {
11
+ const { open, change, exitWatch } = useDialogOpen(onClose);
12
+ const finalFocus = useFinalFocus();
13
+ const answering = useAnswering();
14
+ return (_jsx(AlertDialog.Root, { open: open, onOpenChange: change, onConfirm: () => answering(onConfirm), children: _jsx(AlertDialog.Popup, { className: POPUP_CLASS, intent: intent, title: title, description: description, confirmButtonText: confirmLabel, cancelButtonText: cancelLabel, finalFocus: finalFocus, onClickCapture: refuseSecondClick, onKeyDownCapture: refuseRepeatedEnter, children: exitWatch }) }));
34
15
  }
@@ -0,0 +1,77 @@
1
+ import type { KeyboardEvent, MouseEvent, ReactNode } from 'react';
2
+ /** The class every dialog's popup carries, so a long word breaks inside the card. */
3
+ export declare const POPUP_CLASS = "godmin-dialog-popup";
4
+ /** The time limit in milliseconds the nearest `AdminRoot` sets on a busy dialog's write, none outside any. */
5
+ export declare const WriteTimeoutContext: import("react").Context<number | undefined>;
6
+ /** What a write may answer a dialog: words to show, or a plain stay. Any other answer closes it. */
7
+ export type DialogAnswer = {
8
+ error: string;
9
+ } | {
10
+ close: false;
11
+ };
12
+ /** What a dialog takes from the hook that holds it open. */
13
+ export interface DialogOpen {
14
+ /** Whether the dialog is open, false on the first render so its entry plays. */
15
+ open: boolean;
16
+ /** Takes the next open state, for the dialog's `onOpenChange`. */
17
+ change: (next: boolean) => void;
18
+ /** A child of the popup that draws nothing and reports when the popup left the page. */
19
+ exitWatch: ReactNode;
20
+ }
21
+ /**
22
+ * Holds a dialog open from its first commit and runs its close once the popup left the page.
23
+ * @param onClose - What runs after a close, once the popup left the page.
24
+ * @returns The open state, what changes it and the child that watches the popup leave.
25
+ */
26
+ export declare function useDialogOpen(onClose: () => void): DialogOpen;
27
+ /**
28
+ * Notes the control that held the focus as a dialog was asked, for the place the focus goes once the popup left.
29
+ * @returns What answers `finalFocus`: that control while the focus sits on the page, otherwise false to leave it.
30
+ */
31
+ export declare function useFinalFocus(): () => HTMLElement | false;
32
+ /**
33
+ * Reads what a write answered a dialog, whatever its shape.
34
+ * @param answer - What the write answered.
35
+ * @returns The words to show or a plain stay, none for a dialog that closes.
36
+ */
37
+ export declare function answerOf(answer: unknown): DialogAnswer | undefined;
38
+ /**
39
+ * Reports whether a value is a write still running, a promise or any object with a `then` method.
40
+ * @param value - What the write's handler returned.
41
+ * @returns Whether the value is one to wait for.
42
+ */
43
+ export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
44
+ /**
45
+ * Keeps a dialog open after a rejection and hands the rejection on to the app as one nobody caught.
46
+ * @param error - What the write rejected with.
47
+ * @returns A plain stay.
48
+ */
49
+ export declare function passRejectionOn(error: unknown): DialogAnswer;
50
+ /**
51
+ * Returns a write time limit a browser timer holds, or Infinity for none, and throws on any other value.
52
+ * @param limit - The time limit in milliseconds the app set.
53
+ * @returns The same time limit.
54
+ */
55
+ export declare function checkedWriteTimeout(limit: number): number;
56
+ /**
57
+ * Carries a dialog's action out and reads what it answers, handing what it throws or rejects with on to the app.
58
+ * @param action - The action, handed the signal that fires once its write ran past the time limit.
59
+ * @param limit - The time limit in milliseconds a write still running gets, Infinity or none for no limit.
60
+ * @returns What the dialog reads, at once unless the action returned a write still running.
61
+ */
62
+ export declare function answered(action: (signal: AbortSignal) => unknown, limit: number | undefined): DialogAnswer | undefined | Promise<DialogAnswer | undefined>;
63
+ /**
64
+ * Returns what carries a dialog's action out under the nearest time limit, its answer held while the dialog is hidden.
65
+ * @returns What runs an action and reads what it answers, as `answered` does.
66
+ */
67
+ export declare function useAnswering(): (action: (signal: AbortSignal) => unknown) => ReturnType<typeof answered>;
68
+ /**
69
+ * Refuses the second click of a double click, while Enter and Space still press.
70
+ * @param event - The click on its way into the popup.
71
+ */
72
+ export declare function refuseSecondClick(event: MouseEvent): void;
73
+ /**
74
+ * Refuses an Enter a held key repeats, so holding it sends once.
75
+ * @param event - The key press on its way into the popup.
76
+ */
77
+ export declare function refuseRepeatedEnter(event: KeyboardEvent): void;