@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
@@ -0,0 +1,231 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { __ } from '@wordpress/i18n';
4
+ import { createContext, useCallback, useContext, useLayoutEffect, useRef, useState } from 'react';
5
+ /** The class every dialog's popup carries, so a long word breaks inside the card. */
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);
13
+ /**
14
+ * Renders nothing and reports when it leaves the page.
15
+ * @param props - What it runs as it leaves.
16
+ * @returns Nothing.
17
+ */
18
+ function ExitWatch({ left }) {
19
+ useLayoutEffect(() => left, [left]);
20
+ return null;
21
+ }
22
+ /**
23
+ * Holds a dialog open from its first commit and runs its close once the popup left the page.
24
+ * @param onClose - What runs after a close, once the popup left the page.
25
+ * @returns The open state, what changes it and the child that watches the popup leave.
26
+ */
27
+ export function useDialogOpen(onClose) {
28
+ const [open, setOpen] = useState(false);
29
+ const closing = useRef(false);
30
+ const latest = useRef(onClose);
31
+ useLayoutEffect(() => {
32
+ latest.current = onClose;
33
+ });
34
+ useLayoutEffect(() => {
35
+ setOpen(true);
36
+ }, []);
37
+ const left = useCallback(() => {
38
+ if (closing.current) {
39
+ latest.current();
40
+ }
41
+ }, []);
42
+ const change = (next) => {
43
+ closing.current = !next;
44
+ setOpen(next);
45
+ };
46
+ return { open, change, exitWatch: _jsx(ExitWatch, { left: left }) };
47
+ }
48
+ /**
49
+ * Notes the control that held the focus as a dialog was asked, for the place the focus goes once the popup left.
50
+ * @returns What answers `finalFocus`: that control while the focus sits on the page, otherwise false to leave it.
51
+ */
52
+ export function useFinalFocus() {
53
+ const [opener] = useState(() => document.activeElement);
54
+ return () => (document.activeElement === document.body && opener !== document.body ? opener : false);
55
+ }
56
+ /**
57
+ * Reads what a write answered a dialog, whatever its shape.
58
+ * @param answer - What the write answered.
59
+ * @returns The words to show or a plain stay, none for a dialog that closes.
60
+ */
61
+ export function answerOf(answer) {
62
+ const { error, close } = (answer ?? {});
63
+ if (typeof error === 'string' && error !== '') {
64
+ return { error };
65
+ }
66
+ return close === false ? { close } : undefined;
67
+ }
68
+ /**
69
+ * Reports whether a value is a write still running, a promise or any object with a `then` method.
70
+ * @param value - What the write's handler returned.
71
+ * @returns Whether the value is one to wait for.
72
+ */
73
+ export function isThenable(value) {
74
+ return typeof value?.then === 'function';
75
+ }
76
+ /**
77
+ * Keeps a dialog open after a rejection and hands the rejection on to the app as one nobody caught.
78
+ * @param error - What the write rejected with.
79
+ * @returns A plain stay.
80
+ */
81
+ export function passRejectionOn(error) {
82
+ void Promise.reject(error);
83
+ return { close: false };
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
+ }
156
+ /**
157
+ * Carries a dialog's action out and reads what it answers, handing what it throws or rejects with on to the app.
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.
160
+ * @returns What the dialog reads, at once unless the action returned a write still running.
161
+ */
162
+ export function answered(action, limit) {
163
+ const controller = new AbortController();
164
+ try {
165
+ const running = action(controller.signal);
166
+ return isThenable(running) ? timed(running, controller, limit) : answerOf(running);
167
+ }
168
+ catch (error) {
169
+ return passRejectionOn(error);
170
+ }
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
+ }
213
+ /**
214
+ * Refuses the second click of a double click, while Enter and Space still press.
215
+ * @param event - The click on its way into the popup.
216
+ */
217
+ export function refuseSecondClick(event) {
218
+ if (event.detail > 1) {
219
+ event.preventDefault();
220
+ event.stopPropagation();
221
+ }
222
+ }
223
+ /**
224
+ * Refuses an Enter a held key repeats, so holding it sends once.
225
+ * @param event - The key press on its way into the popup.
226
+ */
227
+ export function refuseRepeatedEnter(event) {
228
+ if (event.repeat && event.key === 'Enter') {
229
+ event.preventDefault();
230
+ }
231
+ }
@@ -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
  */
@@ -12,14 +12,24 @@ const TRIGGERS = {
12
12
  actions: '[aria-haspopup="menu"]',
13
13
  };
14
14
  /** Finds the bar DataViews draws the actions on the ticked items in. */
15
- const BULK_BAR = '.dataviews-bulk-actions-footer__container';
15
+ const BULK_BAR = '.dataviews-bulk-actions';
16
+ /** Finds the open menu button of the bulk bar, whose menu DataViews draws outside the bar on a narrow screen. */
17
+ const BULK_MENU_OPEN = `${BULK_BAR} [aria-haspopup="menu"][aria-expanded="true"]`;
18
+ /**
19
+ * Reports whether a control sits in a menu while the menu button of the bulk bar is open.
20
+ * @param control - The control.
21
+ * @returns Whether it does, as a bulk action chosen on a narrow screen does.
22
+ */
23
+ function inBulkMenu(control) {
24
+ return control.closest('[role="menu"]') !== null && document.querySelector(BULK_MENU_OPEN) !== null;
25
+ }
16
26
  /**
17
27
  * Returns the trigger a control stands for.
18
28
  * @param control - The control.
19
29
  * @returns The bulk bar, the media, the title or the phone row holding the control, the actions menu otherwise.
20
30
  */
21
31
  function triggerAt(control) {
22
- if (control.closest(BULK_BAR) !== null) {
32
+ if (control.closest(BULK_BAR) !== null || inBulkMenu(control)) {
23
33
  return 'bulk';
24
34
  }
25
35
  const triggers = ['media', 'title', 'row'];
@@ -1,29 +1,27 @@
1
1
  import type { ReactNode } from 'react';
2
- import type { FormKind } from './form.js';
2
+ import type { DialogAnswer } from './dialog-open.js';
3
3
  /** The props of a form dialog opened from a button outside a list row. */
4
4
  export interface FormDialogProps {
5
- /** The fields, and any help sentence before them, in the order the reader meets them. */
6
- children: ReactNode;
7
- /** The title in the dialog header, beside its close button. */
5
+ /** The fields in the order the reader meets them, or a function of whether the write runs that draws them. */
6
+ children: ReactNode | ((busy: boolean) => ReactNode);
7
+ /** The title in the dialog header, beside its close icon, the name of the dialog. */
8
8
  title: string;
9
- /** The width from 600px up: small at 400px, the default, or medium at 560px when a control needs the room. */
10
- size?: 'small' | 'medium';
9
+ /** A help sentence before the fields, which describes the dialog. */
10
+ description?: string;
11
11
  /** The label of the button that sends the form. */
12
12
  submitLabel: string;
13
- /** The label of the button that closes the dialog. */
14
- cancelLabel: string;
13
+ /** The label of the button that closes the dialog, none on a last step with nothing to cancel. */
14
+ cancelLabel?: string;
15
15
  /** Whether the form may be sent now, false while a needed field is empty, true when left out. */
16
16
  canSubmit?: boolean;
17
- /** What the form does: 16px above the buttons for a create, the default, 20px for an edit, 12px for a copy. */
18
- kind?: FormKind;
19
- /** Sends the form. Return the write's promise to keep the button busy until it ends. */
20
- onSubmit: () => void | Promise<unknown>;
21
- /** Takes the dialog away after Cancel, Escape, a click on the dimmed page or the close button. */
17
+ /** Sends the form with the time limit's signal. Return nothing to close, the write to hold it, or an answer. */
18
+ onSubmit: (signal: AbortSignal) => void | DialogAnswer | PromiseLike<unknown>;
19
+ /** Takes the dialog away, once its card has left the page. */
22
20
  onClose: () => void;
23
21
  }
24
22
  /**
25
- * Renders a form dialog opened from a button outside a list row, as WordPress opens Add Page, the first field focused.
26
- * @param props - The fields, the title, the size, the labels, the send gate, the kind and the handlers.
23
+ * Renders a form dialog opened from a button outside a list row, on the WPDS dialog, the first field focused.
24
+ * @param props - The fields, the title, the help sentence, the labels, the send gate and the handlers.
27
25
  * @returns The dialog.
28
26
  */
29
- export declare function FormDialog({ children, title, size, submitLabel, cancelLabel, canSubmit, kind, onSubmit, onClose, }: FormDialogProps): import("react").JSX.Element;
27
+ export declare function FormDialog({ children, title, description, submitLabel, cancelLabel, canSubmit, onSubmit, onClose, }: FormDialogProps): import("react").JSX.Element;
@@ -1,21 +1,62 @@
1
- import { jsx as _jsx } from "react/jsx-runtime";
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  // SPDX-License-Identifier: Apache-2.0
3
- import { Modal } from '@wordpress/components';
4
- import { useState } from 'react';
5
- import { FormBody } from './form.js';
3
+ import { speak } from '@wordpress/a11y';
4
+ import { Button, Dialog, Notice, Stack } from '@wordpress/ui';
5
+ import { useId, useLayoutEffect, useRef, useState } from 'react';
6
+ import { POPUP_CLASS, isThenable, refuseSecondClick, useAnswering, useDialogOpen, useFinalFocus, } from './dialog-open.js';
6
7
  /**
7
- * Renders a form dialog opened from a button outside a list row, as WordPress opens Add Page, the first field focused.
8
- * @param props - The fields, the title, the size, the labels, the send gate, the kind and the handlers.
8
+ * Renders a form dialog opened from a button outside a list row, on the WPDS dialog, the first field focused.
9
+ * @param props - The fields, the title, the help sentence, the labels, the send gate and the handlers.
9
10
  * @returns The dialog.
10
11
  */
11
- export function FormDialog({ children, title, size = 'small', submitLabel, cancelLabel, canSubmit, kind = 'create', onSubmit, onClose, }) {
12
+ export function FormDialog({ children, title, description, submitLabel, cancelLabel, canSubmit = true, onSubmit, onClose, }) {
13
+ const { open, change, exitWatch } = useDialogOpen(onClose);
14
+ const finalFocus = useFinalFocus();
15
+ const answering = useAnswering();
12
16
  const [busy, setBusy] = useState(false);
13
- const send = () => {
14
- const sending = onSubmit();
15
- if (sending instanceof Promise) {
16
- setBusy(true);
17
- void sending.finally(() => setBusy(false));
17
+ const [failure, setFailure] = useState();
18
+ const [failures, setFailures] = useState(0);
19
+ const content = useRef(null);
20
+ const form = useId();
21
+ const sendable = canSubmit && !busy && open;
22
+ useLayoutEffect(() => {
23
+ const body = content.current;
24
+ if (failures > 0 && body !== null) {
25
+ body.scrollTop = body.scrollHeight;
18
26
  }
27
+ }, [failures]);
28
+ const guarded = (next) => {
29
+ if (next || !busy) {
30
+ change(next);
31
+ }
32
+ };
33
+ const clear = () => setFailure(undefined);
34
+ const settle = (answer) => {
35
+ if (answer === undefined) {
36
+ change(false);
37
+ }
38
+ else if ('error' in answer) {
39
+ setFailure(answer.error);
40
+ setFailures((count) => count + 1);
41
+ speak(answer.error, 'assertive');
42
+ }
43
+ };
44
+ const submit = (event) => {
45
+ event.preventDefault();
46
+ if (!sendable) {
47
+ return;
48
+ }
49
+ clear();
50
+ const answer = answering(onSubmit);
51
+ if (!isThenable(answer)) {
52
+ settle(answer);
53
+ return;
54
+ }
55
+ setBusy(true);
56
+ void answer.then((reply) => {
57
+ setBusy(false);
58
+ settle(reply);
59
+ });
19
60
  };
20
- return (_jsx(Modal, { title: title, size: size, focusOnMount: "firstContentElement", onRequestClose: onClose, children: _jsx(FormBody, { submitLabel: submitLabel, cancelLabel: cancelLabel, canSubmit: canSubmit, busy: busy, kind: kind, onSubmit: send, onCancel: onClose, children: children }) }));
61
+ return (_jsx(Dialog.Root, { open: open, onOpenChange: guarded, children: _jsxs(Dialog.Popup, { className: POPUP_CLASS, finalFocus: finalFocus, children: [_jsxs(Dialog.Header, { children: [_jsx(Dialog.Title, { children: title }), _jsx(Dialog.CloseIconButton, { disabled: busy })] }), _jsx(Dialog.Content, { ref: content, children: _jsxs(Stack, { render: _jsx("form", { id: form, onSubmit: submit, onChange: clear }), direction: "column", gap: "lg", children: [description === undefined ? null : _jsx(Dialog.Description, { children: description }), typeof children === 'function' ? children(busy) : children, failure === undefined ? null : (_jsx(Notice.Root, { intent: "error", children: _jsx(Notice.Description, { children: failure }) }))] }) }), _jsxs(Dialog.Footer, { children: [cancelLabel === undefined ? null : (_jsx(Dialog.Action, { variant: "outline", tone: "neutral", disabled: busy, children: cancelLabel })), _jsx(Button, { type: "submit", form: form, loading: busy, disabled: !sendable, onClick: refuseSecondClick, children: submitLabel })] }), exitWatch] }) }));
21
62
  }
package/dist/frame.d.ts CHANGED
@@ -4,18 +4,22 @@ type ThemeColor = ComponentProps<typeof ThemeProvider>['color'];
4
4
  export interface FrameRootProps {
5
5
  children: ReactNode;
6
6
  location?: string;
7
+ /** The path the router has finished showing, whose change speaks the new screen's title, nothing without it. */
8
+ shownPath?: string;
9
+ /** The name of the app, which the tab title ends with. The tab title is left alone without it. */
10
+ appName?: string;
7
11
  /** The theme colour of the frame, a #26292b background when absent. */
8
12
  chromeColor?: ThemeColor;
9
13
  /** The theme colour of the canvas, a #fcfcfc background when absent. */
10
14
  canvasColor?: ThemeColor;
11
15
  }
12
16
  /**
13
- * Frames an admin application, folding its sidebar away on a narrow viewport,
14
- * and holds the moves its sidebar parts share.
15
- * @param props - The regions, the current location, and the region colors.
17
+ * Frames an admin application, folding its sidebar away on a narrow viewport, holds the moves its sidebar
18
+ * parts share, and speaks the title of each new screen and sets the tab title from it.
19
+ * @param props - The regions, the current location, the shown path, the app name, and the region colors.
16
20
  * @returns The frame element.
17
21
  */
18
- declare function Root({ children, location, chromeColor, canvasColor }: FrameRootProps): import("react").JSX.Element;
22
+ declare function Root({ children, location, shownPath, appName, chromeColor, canvasColor, }: FrameRootProps): import("react").JSX.Element;
19
23
  export interface FrameSidebarProps {
20
24
  children: ReactNode;
21
25
  brand?: ReactNode;
package/dist/frame.js CHANGED
@@ -8,6 +8,7 @@ import { Drawer, VisuallyHidden } from '@wordpress/ui';
8
8
  import { Children, createContext, useContext, useEffect, useState } from 'react';
9
9
  import { SMALL_VIEWPORT } from './breakpoints.js';
10
10
  import { NavigationStateContext, createNavigationState, takeDrawerStays } from './navigation-state.js';
11
+ import { ScreenTitleContext, TitleWatch, createScreenTitles } from './screen-title.js';
11
12
  import { useMediaQuery } from './use-media-query.js';
12
13
  /**
13
14
  * The chrome background seeded when an application names none.
@@ -24,17 +25,18 @@ const FrameContext = createContext({
24
25
  navigation: createNavigationState(),
25
26
  });
26
27
  /**
27
- * Frames an admin application, folding its sidebar away on a narrow viewport,
28
- * and holds the moves its sidebar parts share.
29
- * @param props - The regions, the current location, and the region colors.
28
+ * Frames an admin application, folding its sidebar away on a narrow viewport, holds the moves its sidebar
29
+ * parts share, and speaks the title of each new screen and sets the tab title from it.
30
+ * @param props - The regions, the current location, the shown path, the app name, and the region colors.
30
31
  * @returns The frame element.
31
32
  */
32
- function Root({ children, location, chromeColor = CHROME_COLOR, canvasColor = CANVAS_COLOR }) {
33
+ function Root({ children, location, shownPath, appName, chromeColor = CHROME_COLOR, canvasColor = CANVAS_COLOR, }) {
33
34
  const small = useMediaQuery(SMALL_VIEWPORT);
34
35
  const [layout, setLayout] = useState(null);
35
36
  const [navigation] = useState(createNavigationState);
37
+ const [titles] = useState(createScreenTitles);
36
38
  const classes = small ? 'godmin-layout godmin-layout--small' : 'godmin-layout';
37
- return (_jsx(ThemeProvider, { color: chromeColor, children: _jsx(FrameContext.Provider, { value: { small, location, layout, navigation }, children: _jsx(NavigationStateContext.Provider, { value: navigation, children: _jsx("div", { ref: setLayout, className: classes, children: _jsx(CanvasColorContext.Provider, { value: canvasColor, children: children }) }) }) }) }));
39
+ return (_jsx(ThemeProvider, { color: chromeColor, children: _jsx(FrameContext.Provider, { value: { small, location, layout, navigation }, children: _jsx(NavigationStateContext.Provider, { value: navigation, children: _jsxs(ScreenTitleContext.Provider, { value: titles, children: [_jsx(TitleWatch, { titles: titles, shownPath: shownPath, location: location, appName: appName }), _jsx("div", { ref: setLayout, className: classes, children: _jsx(CanvasColorContext.Provider, { value: canvasColor, children: children }) })] }) }) }) }));
38
40
  }
39
41
  const CanvasColorContext = createContext(undefined);
40
42
  /**
@@ -62,6 +64,14 @@ function Sidebar({ children, brand, menuLabel = __('Open navigation panel'), lab
62
64
  }
63
65
  return (_jsx(TopBar, { brand: brand, menuLabel: menuLabel, children: content }));
64
66
  }
67
+ /**
68
+ * Returns the edge the drawer opens from and swipes away to, the start edge of the frame.
69
+ * @param layout - The frame element, null before it is drawn.
70
+ * @returns Right in a right-to-left frame, else left.
71
+ */
72
+ function drawerSide(layout) {
73
+ return layout !== null && getComputedStyle(layout).direction === 'rtl' ? 'right' : 'left';
74
+ }
65
75
  /**
66
76
  * Renders the narrow viewport chrome: a menu button opening the sidebar content in
67
77
  * a drawer, beside the brand. The drawer closes on a page change, unless a drilldown row or Back made it,
@@ -77,7 +87,7 @@ function TopBar({ children, brand, menuLabel, }) {
77
87
  setOpen(false);
78
88
  }
79
89
  }, [location, navigation]);
80
- return (_jsxs("div", { className: "godmin-layout__topbar", children: [_jsxs(Drawer.Root, { open: open, onOpenChange: setOpen, children: [_jsx(Drawer.Trigger, { render: _jsx("button", { type: "button", className: "godmin-layout__menu", "aria-label": menuLabel }), children: _jsx(Icon, { icon: menu }) }), _jsxs(Drawer.Popup, { className: "godmin-layout__drawer", portal: _jsx(Drawer.Portal, { container: layout }), children: [_jsx(VisuallyHidden, { render: _jsx(Drawer.Title, {}), children: __('Navigation') }), children, _jsx(VisuallyHidden, { render: _jsx(Drawer.Action, { variant: "unstyled", tabIndex: -1 }), children: __('Close navigation panel') })] })] }), brand] }));
90
+ return (_jsxs("div", { className: "godmin-layout__topbar", children: [_jsxs(Drawer.Root, { open: open, onOpenChange: setOpen, swipeDirection: drawerSide(layout), children: [_jsx(Drawer.Trigger, { render: _jsx("button", { type: "button", className: "godmin-layout__menu", "aria-label": menuLabel }), children: _jsx(Icon, { icon: menu }) }), _jsxs(Drawer.Popup, { className: "godmin-layout__drawer", portal: _jsx(Drawer.Portal, { container: layout }), children: [_jsx(VisuallyHidden, { render: _jsx(Drawer.Title, {}), children: __('Navigation') }), children, _jsx(VisuallyHidden, { render: _jsx(Drawer.Action, { variant: "unstyled", tabIndex: -1 }), children: __('Close navigation panel') })] })] }), brand] }));
81
91
  }
82
92
  /**
83
93
  * Tells whether notices hold anything React draws.