@gopherium/godmin 0.32.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 (68) hide show
  1. package/README.md +19 -9
  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 +36 -4
  7. package/dist/bulk-run.d.ts +2 -2
  8. package/dist/bulk-run.js +18 -2
  9. package/dist/confirm-dialog.d.ts +2 -2
  10. package/dist/confirm-dialog.js +3 -2
  11. package/dist/dialog-open.d.ts +16 -2
  12. package/dist/dialog-open.js +126 -5
  13. package/dist/drilldown-item.d.ts +5 -2
  14. package/dist/drilldown-item.js +14 -2
  15. package/dist/filter-offer.d.ts +5 -5
  16. package/dist/filter-offer.js +9 -9
  17. package/dist/focus-back.js +12 -2
  18. package/dist/form-dialog.d.ts +2 -2
  19. package/dist/form-dialog.js +3 -2
  20. package/dist/frame.d.ts +8 -4
  21. package/dist/frame.js +16 -6
  22. package/dist/index.d.ts +4 -2
  23. package/dist/index.js +3 -2
  24. package/dist/list-chrome/es-ES.d.ts +1 -1
  25. package/dist/list-chrome/es-ES.js +11 -8
  26. package/dist/list-chrome/fr-FR.d.ts +1 -1
  27. package/dist/list-chrome/fr-FR.js +9 -1
  28. package/dist/navigation-item.d.ts +4 -2
  29. package/dist/navigation-item.js +2 -2
  30. package/dist/navigation-screen.js +10 -3
  31. package/dist/navigation.js +5 -1
  32. package/dist/page.d.ts +3 -2
  33. package/dist/page.js +23 -4
  34. package/dist/rejected-field.d.ts +25 -0
  35. package/dist/rejected-field.js +121 -0
  36. package/dist/rename-dialog.d.ts +2 -2
  37. package/dist/rename-dialog.js +1 -1
  38. package/dist/route-not-found.d.ts +5 -0
  39. package/dist/route-not-found.js +12 -0
  40. package/dist/router.d.ts +8 -2
  41. package/dist/router.js +10 -2
  42. package/dist/screen-title.d.ts +52 -0
  43. package/dist/screen-title.js +165 -0
  44. package/dist/stylelint.d.ts +1 -4
  45. package/dist/stylelint.js +4 -7
  46. package/dist/testing.d.ts +2 -2
  47. package/dist/testing.js +3 -3
  48. package/dist/vite.js +1 -0
  49. package/docs/build-and-versioning.md +109 -4
  50. package/docs/design-system/accessibility.md +18 -9
  51. package/docs/design-system/color.md +1 -1
  52. package/docs/design-system/custom-properties.md +3 -3
  53. package/docs/design-system/dialogs.md +71 -9
  54. package/docs/design-system/frame.md +276 -0
  55. package/docs/design-system/layout.md +24 -16
  56. package/docs/design-system/lists.md +17 -11
  57. package/docs/design-system/loading.md +20 -12
  58. package/docs/design-system/motion.md +41 -47
  59. package/docs/design-system/overview.md +8 -3
  60. package/docs/design-system/radius-and-elevation.md +2 -2
  61. package/docs/design-system/record-pages.md +9 -1
  62. package/docs/design-system/toasts.md +7 -1
  63. package/docs/framing-an-application.md +77 -23
  64. package/docs/lists.md +80 -39
  65. package/docs/overview.md +9 -3
  66. package/docs/screens.md +94 -3
  67. package/docs/testing.md +29 -0
  68. package/package.json +27 -19
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,10 +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`, `ConfirmDialog`, `FormDialog`, `RenameDialog`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `useDialogRun`, `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/router` | `Navigation`, `NavigationList`, `NavigationItem`, `DrilldownItem`, `useCanAccess` and the `MenuItem` type with its optional `count`, `useListView`, `listSearch`, `openOnTap`, `useCanvas`, `useFrameLocation`, `routerDefaults`, `UnsavedChangesDialog`, 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 |
56
60
  | `@gopherium/godmin/testing` | `installTestEnvironment`, `renderAdmin`, `setViewport` and its `TestViewport` type, `getAnnouncement`, `clearAnnouncements`, `assertElementPatched`, `WPDS_IGNORE_SELECTOR`, `textClasses`, `badgeClasses`, `buttonClasses`, `stubLayout` |
57
61
  | `@gopherium/godmin/vite` | `godminDedupe`, `godminSingleCopy`, `godminStylesheetFirst`, `duplicateCopies`, `hoistStylesheet` |
58
62
  | `@gopherium/godmin/stylelint` | The design system stylelint rules |
@@ -62,11 +66,16 @@ those two lines do for you.
62
66
  GodMin speaks a few words of its own: Back on a sidebar screen, the name of
63
67
  the sidebar column and its phone drawer, the phone menu button and the
64
68
  drawer's close button, which only a screen reader meets, and "No results
65
- found" with the line under it, which `ListNoResults` shows. It
66
- translates them in the WordPress `default` text domain, as `@wordpress/ui`
67
- translates its own, so `@wordpress/i18n` is a required peer. Every app
68
- already has it, since
69
- `@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.
70
79
 
71
80
  `listChromeCatalogFor` returns the catalogue GodMin ships for a language,
72
81
  Spanish and French today. Both hold these words and the list dates, and the
@@ -88,7 +97,8 @@ if (catalogue !== undefined) {
88
97
  Duplicate packages break the application, and nothing points at the cause.
89
98
  Two copies of React throw on the first hook. Two copies of `@wordpress/theme`
90
99
  render unthemed components with no error. Spread `godminDedupe` into
91
- `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.
92
102
  [Build configuration](docs/build-and-versioning.md) covers both, and lists the
93
103
  design system versions each release supports.
94
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;
@@ -1047,7 +1071,11 @@ body {
1047
1071
  }
1048
1072
 
1049
1073
  .godmin-dialog-popup {
1050
- overflow-wrap: anywhere;
1074
+ overflow-wrap: break-word;
1075
+ }
1076
+
1077
+ .godmin-dialog-popup > * > h2 {
1078
+ min-inline-size: 0;
1051
1079
  }
1052
1080
 
1053
1081
  .godmin-form__row {
@@ -1186,7 +1214,7 @@ body {
1186
1214
  align-items: center;
1187
1215
  justify-content: center;
1188
1216
  box-sizing: border-box;
1189
- min-block-size: 100vh;
1217
+ min-block-size: 100dvh;
1190
1218
  padding: var(--wpds-dimension-padding-3xl);
1191
1219
  opacity: 0;
1192
1220
  animation: godmin-fade-in 500ms ease 200ms forwards;
@@ -1332,6 +1360,10 @@ body {
1332
1360
  border-radius: 0;
1333
1361
  box-shadow: none;
1334
1362
  }
1363
+
1364
+ .godmin-navigation__screen-wrapper {
1365
+ animation-duration: 0s;
1366
+ }
1335
1367
  }
1336
1368
 
1337
1369
  @media (max-width: 639px) {
@@ -3,8 +3,8 @@ import type { DialogAnswer } from './dialog-open.js';
3
3
  import type { ListRun } from './list-run.js';
4
4
  /** Runs one call over each item, reports what the run reached in the given words and then reloads the list. */
5
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, and answers the dialog what to do next. */
7
- export type DialogRun<Item> = (items: Item[], call: (item: Item) => Promise<unknown>, words: BulkWords<Item>) => Promise<DialogAnswer | undefined>;
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>;
8
8
  /**
9
9
  * Returns the handler that runs a call per item, marks the list reloading at the first that works, toasts at the last.
10
10
  * @param list - What the list does around a run.
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.
@@ -73,11 +89,11 @@ function toastOutcome(toaster, items, outcome, words) {
73
89
  * @returns The run handler, the same while the list run, the refresh and the report stay the same.
74
90
  */
75
91
  function useListWrite(list, refresh, report) {
76
- return useCallback(async (given, call, words) => {
92
+ return useCallback(async (given, call, words, signal) => {
77
93
  const items = given.filter(() => true);
78
94
  const settle = list.onStart();
79
95
  const reload = reloadOnce(list);
80
- const outcome = await runEach(items, reporting(call, reload.mark));
96
+ const outcome = await runEach(items, reporting(stopping(call, signal), reload.mark));
81
97
  void Promise.resolve()
82
98
  .then(() => refresh(items))
83
99
  .then(reload.end, reload.end);
@@ -11,8 +11,8 @@ export interface ConfirmDialogProps {
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, the write to stay busy, or an answer to stay open. */
15
- onConfirm: () => void | DialogAnswer | PromiseLike<unknown>;
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
16
  /** Takes the dialog away, once its card has left the page. */
17
17
  onClose: () => void;
18
18
  }
@@ -1,7 +1,7 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  // SPDX-License-Identifier: Apache-2.0
3
3
  import { AlertDialog } from '@wordpress/ui';
4
- import { POPUP_CLASS, answered, refuseRepeatedEnter, refuseSecondClick, useDialogOpen, useFinalFocus, } from './dialog-open.js';
4
+ import { POPUP_CLASS, refuseRepeatedEnter, refuseSecondClick, useAnswering, useDialogOpen, useFinalFocus, } from './dialog-open.js';
5
5
  /**
6
6
  * Renders a dialog that asks one question before an action, on the WPDS alert dialog, with Cancel focused.
7
7
  * @param props - The question, what will happen, the intent, the labels and the handlers.
@@ -10,5 +10,6 @@ import { POPUP_CLASS, answered, refuseRepeatedEnter, refuseSecondClick, useDialo
10
10
  export function ConfirmDialog({ title, description, intent, confirmLabel, cancelLabel, onConfirm, onClose, }) {
11
11
  const { open, change, exitWatch } = useDialogOpen(onClose);
12
12
  const finalFocus = useFinalFocus();
13
- return (_jsx(AlertDialog.Root, { open: open, onOpenChange: change, onConfirm: () => answered(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 }) }));
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 }) }));
14
15
  }
@@ -1,6 +1,8 @@
1
1
  import type { KeyboardEvent, MouseEvent, ReactNode } from 'react';
2
2
  /** The class every dialog's popup carries, so a long word breaks inside the card. */
3
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>;
4
6
  /** What a write may answer a dialog: words to show, or a plain stay. Any other answer closes it. */
5
7
  export type DialogAnswer = {
6
8
  error: string;
@@ -45,12 +47,24 @@ export declare function isThenable(value: unknown): value is PromiseLike<unknown
45
47
  * @returns A plain stay.
46
48
  */
47
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;
48
56
  /**
49
57
  * Carries a dialog's action out and reads what it answers, handing what it throws or rejects with on to the app.
50
- * @param action - The action.
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.
51
60
  * @returns What the dialog reads, at once unless the action returned a write still running.
52
61
  */
53
- export declare function answered(action: () => unknown): DialogAnswer | undefined | Promise<DialogAnswer | undefined>;
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>;
54
68
  /**
55
69
  * Refuses the second click of a double click, while Enter and Space still press.
56
70
  * @param event - The click on its way into the popup.
@@ -1,8 +1,15 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  // SPDX-License-Identifier: Apache-2.0
3
- import { useCallback, useLayoutEffect, useRef, useState } from 'react';
3
+ import { __ } from '@wordpress/i18n';
4
+ import { createContext, useCallback, useContext, useLayoutEffect, useRef, useState } from 'react';
4
5
  /** The class every dialog's popup carries, so a long word breaks inside the card. */
5
6
  export const POPUP_CLASS = 'godmin-dialog-popup';
7
+ /** The longest delay in milliseconds a browser timer holds, past which it fires at the wrong time. */
8
+ const LONGEST_TIMER = 2 ** 31 - 1;
9
+ /** The name of the abort reason of a write past its time limit, the one `AbortSignal.timeout` gives. */
10
+ const TIMEOUT_ERROR = 'TimeoutError';
11
+ /** The time limit in milliseconds the nearest `AdminRoot` sets on a busy dialog's write, none outside any. */
12
+ export const WriteTimeoutContext = createContext(undefined);
6
13
  /**
7
14
  * Renders nothing and reports when it leaves the page.
8
15
  * @param props - What it runs as it leaves.
@@ -75,20 +82,134 @@ export function passRejectionOn(error) {
75
82
  void Promise.reject(error);
76
83
  return { close: false };
77
84
  }
85
+ /**
86
+ * Returns the words a write past its time limit shows, WordPress's own, picked by whether the browser is online.
87
+ * @returns The words, in the language the app loaded.
88
+ */
89
+ function timeOutWords() {
90
+ return navigator.onLine
91
+ ? __('Could not get a valid response from the server.')
92
+ : __('Unable to connect. Please check your Internet connection.');
93
+ }
94
+ /**
95
+ * Returns a write time limit a browser timer holds, or Infinity for none, and throws on any other value.
96
+ * @param limit - The time limit in milliseconds the app set.
97
+ * @returns The same time limit.
98
+ */
99
+ export function checkedWriteTimeout(limit) {
100
+ const holds = Number.isFinite(limit) ? limit > 0 && limit <= LONGEST_TIMER : limit === Number.POSITIVE_INFINITY;
101
+ if (!holds) {
102
+ const range = `above 0 and up to ${LONGEST_TIMER}, or Infinity for no limit`;
103
+ throw new RangeError(`godmin: writeTimeout takes milliseconds ${range}, not ${String(limit)}.`);
104
+ }
105
+ return limit;
106
+ }
107
+ /**
108
+ * Returns what a dialog reads once its write ran past the time limit.
109
+ * @param signal - The signal aborted at the limit.
110
+ * @returns The time-out words picked at the limit.
111
+ */
112
+ function timedOut(signal) {
113
+ return { error: signal.reason.message };
114
+ }
115
+ /**
116
+ * Reads a rejection of a write: the time-out once the dialog fired the signal, else handed on to the app.
117
+ * @param error - What the write rejected with.
118
+ * @param signal - The signal the write was handed.
119
+ * @returns The time-out words, or a plain stay.
120
+ */
121
+ function rejectionOf(error, signal) {
122
+ return signal.aborted ? timedOut(signal) : passRejectionOn(error);
123
+ }
124
+ /**
125
+ * Aborts a write past its time limit, then gives it until the next task to answer before the time-out shows.
126
+ * @param controller - What aborts the signal the write was handed.
127
+ * @param show - What gives the dialog its answer.
128
+ * @returns The timer of the next task.
129
+ */
130
+ function runOut(controller, show) {
131
+ controller.abort(new DOMException(timeOutWords(), TIMEOUT_ERROR));
132
+ return setTimeout(() => show(timedOut(controller.signal)), 0);
133
+ }
134
+ /**
135
+ * Waits for a write still running, aborting it at the time limit and showing the time-out once it ran past.
136
+ * @param running - The write.
137
+ * @param controller - What aborts the signal the write was handed.
138
+ * @param limit - The time limit in milliseconds, Infinity or none for no limit.
139
+ * @returns What the dialog reads, the first answer only.
140
+ */
141
+ function timed(running, controller, limit) {
142
+ return new Promise((resolve) => {
143
+ let timer;
144
+ const show = (answer) => {
145
+ clearTimeout(timer);
146
+ resolve(answer);
147
+ };
148
+ if (Number.isFinite(limit)) {
149
+ timer = setTimeout(() => {
150
+ timer = runOut(controller, show);
151
+ }, limit);
152
+ }
153
+ void Promise.resolve(running).then((value) => show(answerOf(value)), (error) => show(rejectionOf(error, controller.signal)));
154
+ });
155
+ }
78
156
  /**
79
157
  * Carries a dialog's action out and reads what it answers, handing what it throws or rejects with on to the app.
80
- * @param action - The action.
158
+ * @param action - The action, handed the signal that fires once its write ran past the time limit.
159
+ * @param limit - The time limit in milliseconds a write still running gets, Infinity or none for no limit.
81
160
  * @returns What the dialog reads, at once unless the action returned a write still running.
82
161
  */
83
- export function answered(action) {
162
+ export function answered(action, limit) {
163
+ const controller = new AbortController();
84
164
  try {
85
- const running = action();
86
- return isThenable(running) ? Promise.resolve(running).then(answerOf, passRejectionOn) : answerOf(running);
165
+ const running = action(controller.signal);
166
+ return isThenable(running) ? timed(running, controller, limit) : answerOf(running);
87
167
  }
88
168
  catch (error) {
89
169
  return passRejectionOn(error);
90
170
  }
91
171
  }
172
+ /**
173
+ * Gives a dialog what its action answered while it shows, and holds it while it is hidden.
174
+ * @param answer - What the action answered.
175
+ * @param gate - Where answers wait while the dialog is hidden.
176
+ * @returns The answer, given at once or once the dialog shows again, never once it left the page.
177
+ */
178
+ function gated(answer, gate) {
179
+ if (!(answer instanceof Promise)) {
180
+ return answer;
181
+ }
182
+ return new Promise((resolve) => {
183
+ void answer.then((value) => {
184
+ const give = () => resolve(value);
185
+ if (gate.shown) {
186
+ give();
187
+ }
188
+ else {
189
+ gate.held.push(give);
190
+ }
191
+ });
192
+ });
193
+ }
194
+ /**
195
+ * Returns what carries a dialog's action out under the nearest time limit, its answer held while the dialog is hidden.
196
+ * @returns What runs an action and reads what it answers, as `answered` does.
197
+ */
198
+ export function useAnswering() {
199
+ const limit = useContext(WriteTimeoutContext);
200
+ const gate = useRef({ shown: false, held: [] });
201
+ useLayoutEffect(() => {
202
+ const shown = gate.current;
203
+ shown.shown = true;
204
+ const held = shown.held;
205
+ shown.held = [];
206
+ held.forEach((give) => give());
207
+ return () => {
208
+ shown.shown = false;
209
+ };
210
+ }, []);
211
+ return (action) => gated(answered(action, limit), gate.current);
212
+ }
92
213
  /**
93
214
  * Refuses the second click of a double click, while Enter and Space still press.
94
215
  * @param event - The click on its way into the popup.
@@ -1,7 +1,9 @@
1
- import type { AnyRouter, LinkComponentProps, RegisteredRouter } from '@tanstack/react-router';
1
+ import type { AnyRouter, LinkComponentProps, NavigateOptions, RegisteredRouter } from '@tanstack/react-router';
2
2
  import type { ReactElement, ReactNode } from 'react';
3
+ /** The TanStack Link props besides the address that a drilldown row takes, all but those of the current page. */
4
+ type OtherLinkProps = Omit<LinkComponentProps, 'activeProps' | 'activeOptions' | keyof NavigateOptions>;
3
5
  /** A row whose address opens a route that declares a Sidebar. Draws the chevron. Sits inside a NavigationList. */
4
- export type DrilldownItemProps<TRouter extends AnyRouter = RegisteredRouter, TFrom extends string = string, TTo extends string | undefined = undefined, TMaskFrom extends string = TFrom, TMaskTo extends string = ''> = LinkComponentProps<'a', TRouter, TFrom, TTo, TMaskFrom, TMaskTo> & {
6
+ export type DrilldownItemProps<TRouter extends AnyRouter = RegisteredRouter, TFrom extends string = string, TTo extends string | undefined = undefined, TMaskFrom extends string = TFrom, TMaskTo extends string = ''> = NavigateOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo> & OtherLinkProps & {
5
7
  /** None, since the row takes its id from its address. */
6
8
  id?: never;
7
9
  /** A glyph from `@wordpress/icons`, drawn at 24px. */
@@ -17,3 +19,4 @@ export type DrilldownItemProps<TRouter extends AnyRouter = RegisteredRouter, TFr
17
19
  * @returns The row element, or null when its address opens a route the reader may not open.
18
20
  */
19
21
  export declare function DrilldownItem<TRouter extends AnyRouter = RegisteredRouter, const TFrom extends string = string, const TTo extends string | undefined = undefined, const TMaskFrom extends string = TFrom, const TMaskTo extends string = ''>({ icon, suffix, children, ...link }: DrilldownItemProps<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>): import("react").JSX.Element;
22
+ export {};
@@ -1,6 +1,6 @@
1
1
  import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  // SPDX-License-Identifier: Apache-2.0
3
- import { useRouter } from '@tanstack/react-router';
3
+ import { createLink, useRouter } from '@tanstack/react-router';
4
4
  import { isRTL } from '@wordpress/i18n';
5
5
  import { Icon, chevronLeftSmall, chevronRightSmall } from '@wordpress/icons';
6
6
  import { useContext } from 'react';
@@ -9,6 +9,18 @@ import { NavigationStateContext, isPlainClick, recordDrilldown } from './navigat
9
9
  import { findMoveTarget, findRowRoutes } from './path-matching.js';
10
10
  /** The start of the id a drilldown row takes from its address. */
11
11
  const ID_PREFIX = 'godmin-drilldown-item-';
12
+ /**
13
+ * Renders the anchor of a drilldown row without the marks of the current page.
14
+ * @param props - The props TanStack's Link hands the anchor.
15
+ * @returns The anchor element.
16
+ */
17
+ function UnmarkedAnchor({ 'aria-current': _current, 'data-status': _status, disabled: _disabled, ...anchor }) {
18
+ return _jsx("a", { ...anchor });
19
+ }
20
+ /** The router link of a drilldown row, never marked current. */
21
+ const DrilldownLink = createLink(UnmarkedAnchor);
22
+ /** The props TanStack adds to a drilldown row on its own address, none. */
23
+ const NO_ACTIVE_PROPS = {};
12
24
  /**
13
25
  * Renders a sidebar row that opens a sub menu: its icon, label, suffix and chevron, with an id taken from its address.
14
26
  * A plain click inside a frame records a forward move from this row to its address.
@@ -27,5 +39,5 @@ export function DrilldownItem({ icon, suffix, children, ...link }) {
27
39
  recordDrilldown(state, id, findMoveTarget(router, address));
28
40
  }
29
41
  };
30
- return (_jsx(Row, { link: { ...address, onClick }, routes: routes, icon: icon, className: ROW_CLASS, id: id, end: _jsxs(_Fragment, { children: [suffix === undefined ? null : _jsx(RowSuffix, { children: suffix }), _jsx(Icon, { icon: isRTL() ? chevronLeftSmall : chevronRightSmall, size: 24, className: "godmin-navigation-item__drilldown-indicator" })] }), children: children }));
42
+ return (_jsx(Row, { link: { ...address, onClick, activeProps: NO_ACTIVE_PROPS }, linkComponent: DrilldownLink, routes: routes, icon: icon, className: ROW_CLASS, id: id, end: _jsxs(_Fragment, { children: [suffix === undefined ? null : _jsx(RowSuffix, { children: suffix }), _jsx(Icon, { icon: isRTL() ? chevronLeftSmall : chevronRightSmall, size: 24, className: "godmin-navigation-item__drilldown-indicator" })] }), children: children }));
31
43
  }
@@ -1,4 +1,4 @@
1
- /** How DataViews 20 filters a field of one type. */
1
+ /** How DataViews 22 filters a field of one type. */
2
2
  export interface TypeOffer {
3
3
  /** The operators a field of the type filters with when it names none. */
4
4
  defaults: readonly string[];
@@ -7,14 +7,14 @@ export interface TypeOffer {
7
7
  /** Whether the type draws a control of its own. */
8
8
  control: boolean;
9
9
  }
10
- /** The operators DataViews 20 picks one value with. */
10
+ /** The operators DataViews 22 picks one value with. */
11
11
  export declare const SINGLE_OPERATORS: readonly string[];
12
- /** The field types DataViews 20 knows. */
12
+ /** The field types DataViews 22 knows. */
13
13
  export declare const TYPE_NAMES: (string | undefined)[];
14
- /** The controls DataViews 20 draws, by the name a field's Edit gives. */
14
+ /** The controls DataViews 22 draws, by the name a field's Edit gives. */
15
15
  export declare const CONTROLS: readonly string[];
16
16
  /**
17
- * Returns how DataViews 20 filters a field of the given type.
17
+ * Returns how DataViews 22 filters a field of the given type.
18
18
  * @param type - The field type, none when undefined.
19
19
  * @returns The offer of the type, the untyped one for a type DataViews does not know.
20
20
  */
@@ -1,5 +1,5 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
- /** The operators DataViews 20 picks one value with. */
2
+ /** The operators DataViews 22 picks one value with. */
3
3
  export const SINGLE_OPERATORS = [
4
4
  'is',
5
5
  'isNot',
@@ -17,7 +17,7 @@ export const SINGLE_OPERATORS = [
17
17
  'on',
18
18
  'notOn',
19
19
  ];
20
- /** Every operator DataViews 20 knows. */
20
+ /** Every operator DataViews 22 knows. */
21
21
  const ALL_OPERATORS = ['isAny', 'isNone', 'isAll', 'isNotAll', 'between', 'inThePast', 'over', ...SINGLE_OPERATORS];
22
22
  /** The operators a text field may name. */
23
23
  const TEXT_VALID = ['is', 'isNot', 'contains', 'notContains', 'startsWith', 'isAny', 'isNone', 'isNotAll'];
@@ -27,15 +27,15 @@ const NUMBER_DEFAULTS = ['is', 'isNot', 'lessThan', 'greaterThan', 'lessThanOrEq
27
27
  const MOMENT = ['on', 'notOn', 'before', 'after', 'beforeInc', 'afterInc'];
28
28
  /** The operators a date and time field takes. */
29
29
  const DATETIME = [...MOMENT, 'inThePast', 'over'];
30
- /** How DataViews 20 filters a text field. */
30
+ /** How DataViews 22 filters a text field. */
31
31
  const TEXT = { defaults: ['isAny', 'isNone'], valid: TEXT_VALID, control: true };
32
- /** How DataViews 20 filters a number field. */
32
+ /** How DataViews 22 filters a number field. */
33
33
  const NUMBER = {
34
34
  defaults: NUMBER_DEFAULTS,
35
35
  valid: [...NUMBER_DEFAULTS, 'isAny', 'isNone', 'isNotAll'],
36
36
  control: true,
37
37
  };
38
- /** How DataViews 20 filters each field type it knows, by type name. */
38
+ /** How DataViews 22 filters each field type it knows, by type name. */
39
39
  const TYPE_OFFERS = new Map([
40
40
  ['text', TEXT],
41
41
  ['email', TEXT],
@@ -52,11 +52,11 @@ const TYPE_OFFERS = new Map([
52
52
  ['media', { defaults: [], valid: [], control: false }],
53
53
  ['password', { defaults: [], valid: [], control: true }],
54
54
  ]);
55
- /** How DataViews 20 filters a field of no type, or of a type it does not know. */
55
+ /** How DataViews 22 filters a field of no type, or of a type it does not know. */
56
56
  const UNTYPED = { defaults: ['is', 'isNot'], valid: ALL_OPERATORS, control: false };
57
- /** The field types DataViews 20 knows. */
57
+ /** The field types DataViews 22 knows. */
58
58
  export const TYPE_NAMES = [...TYPE_OFFERS.keys()];
59
- /** The controls DataViews 20 draws, by the name a field's Edit gives. */
59
+ /** The controls DataViews 22 draws, by the name a field's Edit gives. */
60
60
  export const CONTROLS = [
61
61
  'adaptiveSelect',
62
62
  'array',
@@ -80,7 +80,7 @@ export const CONTROLS = [
80
80
  'toggleGroup',
81
81
  ];
82
82
  /**
83
- * Returns how DataViews 20 filters a field of the given type.
83
+ * Returns how DataViews 22 filters a field of the given type.
84
84
  * @param type - The field type, none when undefined.
85
85
  * @returns The offer of the type, the untyped one for a type DataViews does not know.
86
86
  */