@gopherium/godmin 0.30.0 → 0.32.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 (62) hide show
  1. package/README.md +2 -3
  2. package/dist/base.css +159 -29
  3. package/dist/breakpoints.d.ts +1 -1
  4. package/dist/breakpoints.js +1 -1
  5. package/dist/bulk-run.d.ts +10 -0
  6. package/dist/bulk-run.js +59 -10
  7. package/dist/bulk.d.ts +3 -0
  8. package/dist/confirm-dialog.d.ts +14 -14
  9. package/dist/confirm-dialog.js +8 -28
  10. package/dist/dialog-open.d.ts +63 -0
  11. package/dist/dialog-open.js +110 -0
  12. package/dist/focus-back.d.ts +20 -0
  13. package/dist/focus-back.js +36 -12
  14. package/dist/form-dialog.d.ts +14 -16
  15. package/dist/form-dialog.js +53 -13
  16. package/dist/index.d.ts +13 -13
  17. package/dist/index.js +7 -8
  18. package/dist/list-chrome/es-ES.js +3 -3
  19. package/dist/list-chrome/fr-FR.js +1 -0
  20. package/dist/list-run.js +39 -48
  21. package/dist/page-breadcrumbs.d.ts +28 -0
  22. package/dist/page-breadcrumbs.js +18 -0
  23. package/dist/page-tabs.js +18 -6
  24. package/dist/page.d.ts +8 -3
  25. package/dist/page.js +36 -9
  26. package/dist/rename-dialog.d.ts +24 -0
  27. package/dist/rename-dialog.js +16 -0
  28. package/dist/router.d.ts +2 -0
  29. package/dist/router.js +1 -0
  30. package/dist/toaster.js +21 -2
  31. package/dist/unsaved-changes-dialog.d.ts +19 -0
  32. package/dist/unsaved-changes-dialog.js +33 -0
  33. package/docs/build-and-versioning.md +92 -9
  34. package/docs/design-system/accessibility.md +12 -7
  35. package/docs/design-system/custom-properties.md +6 -2
  36. package/docs/design-system/dialogs.md +240 -0
  37. package/docs/design-system/layout.md +5 -3
  38. package/docs/design-system/lists.md +3 -1
  39. package/docs/design-system/loading.md +2 -0
  40. package/docs/design-system/motion.md +3 -2
  41. package/docs/design-system/overview.md +7 -1
  42. package/docs/design-system/record-pages.md +199 -0
  43. package/docs/design-system/toasts.md +13 -10
  44. package/docs/design-system/typography.md +1 -1
  45. package/docs/lists.md +321 -434
  46. package/docs/loading-and-feedback.md +14 -11
  47. package/docs/overview.md +2 -3
  48. package/docs/screens.md +87 -34
  49. package/docs/testing.md +11 -9
  50. package/package.json +20 -28
  51. package/dist/close-while-open.d.ts +0 -6
  52. package/dist/close-while-open.js +0 -21
  53. package/dist/confirm.d.ts +0 -21
  54. package/dist/confirm.js +0 -11
  55. package/dist/dialogs.d.ts +0 -4
  56. package/dist/dialogs.js +0 -3
  57. package/dist/form.d.ts +0 -28
  58. package/dist/form.js +0 -23
  59. package/dist/rename.d.ts +0 -20
  60. package/dist/rename.js +0 -14
  61. package/dist/run-confirm.d.ts +0 -22
  62. package/dist/run-confirm.js +0 -23
package/dist/list-run.js CHANGED
@@ -1,18 +1,18 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
  import { useLayoutEffect, useRef, useState } from 'react';
3
- import { HOLDERS } from './focus-back.js';
3
+ import { HOLDERS, itemAt, triggerOnItem } from './focus-back.js';
4
4
  /** Finds the dialog or the alert dialog holding the focus. */
5
5
  const DIALOG_IN_FOCUS = '[role="dialog"]:focus-within, [role="alertdialog"]:focus-within';
6
6
  /** Finds a part that turned inert while it holds the focus. */
7
7
  const INERT_IN_FOCUS = '[inert]:focus-within';
8
- /** Finds a dialog or an alert dialog that a control of the list opens. */
8
+ /** Finds a dialog or an alert dialog. */
9
9
  const DIALOG = '[role="dialog"], [role="alertdialog"]';
10
+ /** Finds the toast region, which takes the focus a leaving toast held. */
11
+ const TOAST_REGION = '.godmin-toasts';
10
12
  /** Finds every control a reader can focus inside a card or a row. */
11
13
  const CONTROLS = 'a[href], button, input, select, textarea, [tabindex]';
12
14
  /** Finds a button of a row that runs an action, never the actions menu button, which only opens a menu. */
13
15
  const ACTION_BUTTON = '.dataviews-item-actions button:not(.dataviews-all-actions-button)';
14
- /** Stops nothing, for a run that watches no focus. */
15
- function stopNothing() { }
16
16
  /**
17
17
  * Counts the reloads a list has open, each ended once, and drops them all when the list changes.
18
18
  * @returns Whether a reload is open, and how to start one or drop them all.
@@ -50,33 +50,13 @@ export function focusInDialog() {
50
50
  return document.querySelector(DIALOG_IN_FOCUS) !== null;
51
51
  }
52
52
  /**
53
- * Watches where the focus first lands outside the dialog a run started in while that dialog is still on the page.
53
+ * Reports whether the dialog a run started in has left the page while the focus sits on the control that opened it.
54
54
  * @param startedIn - The dialog that held the focus as the run started, none for a run started outside every dialog.
55
- * @returns The landing, filled in once the focus lands, which watches nothing for a run started outside every dialog.
55
+ * @param openedBy - The control that opened each dialog.
56
+ * @returns Whether that dialog has gone and the focus sits on that control.
56
57
  */
57
- function watchLanding(startedIn) {
58
- const landing = { element: null, stop: stopNothing };
59
- if (startedIn === null) {
60
- return landing;
61
- }
62
- const note = (event) => {
63
- if (startedIn.isConnected && !startedIn.contains(event.target)) {
64
- landing.element = event.target;
65
- landing.stop();
66
- }
67
- };
68
- document.addEventListener('focusin', note, true);
69
- landing.stop = () => document.removeEventListener('focusin', note, true);
70
- return landing;
71
- }
72
- /**
73
- * Reports whether the dialog a run started in has closed while the focus stays where it first landed, in no dialog.
74
- * @param startedIn - The dialog that held the focus as the run started, none for a run started outside every dialog.
75
- * @param landed - The element the focus first landed on outside that dialog, none while it never did.
76
- * @returns Whether that dialog has gone and the focus stays on the element it handed the focus back to.
77
- */
78
- function stillWhereDialogLeftIt(startedIn, landed) {
79
- return startedIn?.isConnected === false && document.activeElement === landed && !focusInDialog();
58
+ function stillWhereDialogLeftIt(startedIn, openedBy) {
59
+ return startedIn?.isConnected === false && document.activeElement === openedBy.get(startedIn);
80
60
  }
81
61
  /**
82
62
  * Moves the focus to the list region, scrolling nothing, when it sits in a part of that list that turned inert.
@@ -98,7 +78,17 @@ function placeOf(list, focused) {
98
78
  return null;
99
79
  }
100
80
  const control = focused;
101
- return { control, row: [...list.querySelectorAll(HOLDERS)].indexOf(control.closest(HOLDERS)) };
81
+ const row = [...list.querySelectorAll(HOLDERS)].indexOf(control.closest(HOLDERS));
82
+ return { control, row, item: itemAt(control) };
83
+ }
84
+ /**
85
+ * Returns the trigger on the item the reader stood on, found wherever its card or row now sits.
86
+ * @param list - The list region.
87
+ * @param place - Where the reader stood.
88
+ * @returns The trigger, none once the item left the list or when the app marks no item there.
89
+ */
90
+ function onSameItem(list, { item }) {
91
+ return item === null ? null : triggerOnItem(list, item);
102
92
  }
103
93
  /**
104
94
  * Returns the first control of the card or row that now sits where the place's sat, the last one when fewer came back.
@@ -112,7 +102,7 @@ function firstInPlace(list, { row }) {
112
102
  return first?.matches(ACTION_BUTTON) ? null : first;
113
103
  }
114
104
  /**
115
- * Gives the focus back from the list region to the pressed control, else to the first control of the row in its place.
105
+ * Gives the focus back from the list region to the pressed control, else the same item, else the row in its place.
116
106
  * @param list - The list region, none while the screen draws no list.
117
107
  * @param place - Where the reader stood as the list took the focus, none when they stood nowhere in it.
118
108
  */
@@ -121,39 +111,45 @@ function putBack(list, place) {
121
111
  return;
122
112
  }
123
113
  const preventScroll = !list.matches(':focus-visible');
124
- for (const control of [place.control, firstInPlace(list, place)]) {
114
+ for (const control of [place.control, onSameItem(list, place), firstInPlace(list, place)]) {
125
115
  if (document.activeElement === list) {
126
116
  control?.focus({ preventScroll });
127
117
  }
128
118
  }
129
119
  }
130
120
  /**
131
- * Notes the place of the control the focus leaves the list from for a dialog, none when it goes elsewhere.
121
+ * Notes what the focus leaves for a dialog: the control that opened it, and its place when it stands in the list.
132
122
  * @param region - The list region, none while the screen draws no list.
133
- * @param opener - Where the note goes.
123
+ * @param opener - Where the place goes, none once the focus leaves the list for anything but a dialog.
124
+ * @param openedBy - Where the control goes, the first one only for each dialog.
134
125
  * @returns What stops noting.
135
126
  */
136
- function noteOpener(region, opener) {
127
+ function noteOpener(region, opener, openedBy) {
137
128
  const note = (event) => {
138
129
  const list = region.current;
130
+ const dialog = event.relatedTarget?.closest(DIALOG);
139
131
  if (list?.contains(event.target)) {
140
- opener.current = event.relatedTarget?.closest(DIALOG) ? placeOf(list, event.target) : null;
132
+ opener.current = dialog ? placeOf(list, event.target) : null;
133
+ }
134
+ if (dialog && !event.target.closest(DIALOG)) {
135
+ openedBy.set(dialog, openedBy.get(dialog) ?? event.target);
141
136
  }
142
137
  };
143
138
  document.addEventListener('focusout', note, true);
144
139
  return () => document.removeEventListener('focusout', note, true);
145
140
  }
146
141
  /**
147
- * Reports whether the focus sits on the page, in the list, in the dialog that ran, or where that dialog left it.
142
+ * Reports whether the focus sits on the page, the toast region, the list, the dialog that ran, or where it left it.
148
143
  * @param list - The list region, none while the screen draws no list.
149
144
  * @param startedIn - The dialog that held the focus as the run started, none for a run started outside every dialog.
150
- * @param landed - The element the focus first landed on outside that dialog, none while it never did.
145
+ * @param openedBy - The control that opened each dialog.
151
146
  * @returns Whether a finished run may move the focus to the list.
152
147
  */
153
- function readerOnList(list, startedIn, landed) {
148
+ function readerOnList(list, startedIn, openedBy) {
154
149
  const active = document.activeElement;
155
150
  const holds = [list, startedIn].some((holder) => holder !== null && holder.contains(active));
156
- return active === document.body || holds || stillWhereDialogLeftIt(startedIn, landed);
151
+ const leftByToast = active?.matches(TOAST_REGION) === true;
152
+ return active === document.body || leftByToast || holds || stillWhereDialogLeftIt(startedIn, openedBy);
157
153
  }
158
154
  /**
159
155
  * Holds the region a run focuses, gives its focus back once the list reloaded, and drops old runs on a list change.
@@ -164,15 +160,14 @@ function readerOnList(list, startedIn, landed) {
164
160
  export function useListRun(scope, onChangeSelection) {
165
161
  const region = useRef(null);
166
162
  const latest = useRef(0);
167
- const watching = useRef(stopNothing);
168
163
  const committed = useRef(scope);
169
164
  const place = useRef(null);
170
165
  const opener = useRef(null);
166
+ const [openedBy] = useState(() => new WeakMap());
171
167
  const [refreshing, reloads] = useReloads();
172
- useLayoutEffect(() => noteOpener(region, opener), []);
168
+ useLayoutEffect(() => noteOpener(region, opener, openedBy), [openedBy]);
173
169
  useLayoutEffect(() => {
174
170
  latest.current += 1;
175
- return () => watching.current();
176
171
  }, [scope]);
177
172
  useLayoutEffect(() => {
178
173
  if (committed.current !== scope) {
@@ -192,15 +187,11 @@ export function useListRun(scope, onChangeSelection) {
192
187
  }, [refreshing]);
193
188
  const [run] = useState(() => ({
194
189
  onStart: () => {
195
- watching.current();
196
190
  latest.current += 1;
197
191
  const id = latest.current;
198
192
  const startedIn = document.querySelector(DIALOG_IN_FOCUS);
199
193
  place.current = startedIn === null ? null : opener.current;
200
- const landing = watchLanding(startedIn);
201
- watching.current = landing.stop;
202
194
  return (moved) => {
203
- landing.stop();
204
195
  if (latest.current !== id) {
205
196
  return;
206
197
  }
@@ -208,7 +199,7 @@ export function useListRun(scope, onChangeSelection) {
208
199
  place.current = null;
209
200
  return;
210
201
  }
211
- if (readerOnList(region.current, startedIn, landing.element)) {
202
+ if (readerOnList(region.current, startedIn, openedBy)) {
212
203
  place.current ??= placeOf(region.current, document.activeElement);
213
204
  region.current?.focus({ preventScroll: true });
214
205
  }
@@ -0,0 +1,28 @@
1
+ import { Link } from '@wordpress/ui';
2
+ import type { ComponentProps, ReactNode } from 'react';
3
+ export interface PageBreadcrumbsProps {
4
+ /** The name of the navigation region, read by assistive technology. */
5
+ label: string;
6
+ /** The links, one PageBreadcrumb each. */
7
+ children: ReactNode;
8
+ }
9
+ /**
10
+ * Renders the links that lead back from a record as a navigation region holding a list, as admin-ui draws its trail.
11
+ * @param props - The navigation name and the links.
12
+ * @returns The navigation element.
13
+ */
14
+ export declare function PageBreadcrumbs({ label, children }: PageBreadcrumbsProps): import("react").JSX.Element;
15
+ export interface PageBreadcrumbProps {
16
+ /** The address the link leads to, when it renders as a plain link. */
17
+ href?: string;
18
+ /** The link element the breadcrumb renders through, such as a router link. */
19
+ render?: ComponentProps<typeof Link>['render'];
20
+ /** The link label. */
21
+ children: ReactNode;
22
+ }
23
+ /**
24
+ * Renders one link of the breadcrumbs as a list item, with the slash after it.
25
+ * @param props - The address or the link element, and the label.
26
+ * @returns The list item element.
27
+ */
28
+ export declare function PageBreadcrumb({ href, render, children }: PageBreadcrumbProps): import("react").JSX.Element;
@@ -0,0 +1,18 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { Link, Text } from '@wordpress/ui';
3
+ /**
4
+ * Renders the links that lead back from a record as a navigation region holding a list, as admin-ui draws its trail.
5
+ * @param props - The navigation name and the links.
6
+ * @returns The navigation element.
7
+ */
8
+ export function PageBreadcrumbs({ label, children }) {
9
+ return (_jsx("nav", { "aria-label": label, className: "godmin-page__breadcrumbs", children: _jsx("ul", { role: "list", children: children }) }));
10
+ }
11
+ /**
12
+ * Renders one link of the breadcrumbs as a list item, with the slash after it.
13
+ * @param props - The address or the link element, and the label.
14
+ * @returns The list item element.
15
+ */
16
+ export function PageBreadcrumb({ href, render, children }) {
17
+ return (_jsxs("li", { children: [_jsx(Text, { variant: "body-lg", render: _jsx(Link, { tone: "neutral", href: href, render: render }), children: children }), _jsx(Text, { variant: "body-lg", "aria-hidden": "true", className: "godmin-page__separator", children: "/" })] }));
18
+ }
package/dist/page-tabs.js CHANGED
@@ -1,10 +1,14 @@
1
- import { jsx as _jsx } from "react/jsx-runtime";
1
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { cloneElement, useLayoutEffect, useRef, useState } from 'react';
3
3
  import { ROUNDING_SLACK, useSizeWatch } from './size-watch.js';
4
4
  /**
5
5
  * The class every tab row carries.
6
6
  */
7
7
  const ROW_CLASS = 'godmin-page-tabs';
8
+ /**
9
+ * The class of a tab row wider than its space.
10
+ */
11
+ const SCROLLS_CLASS = 'godmin-page-tabs--scrolling';
8
12
  /**
9
13
  * The class that fades the start edge of a tab row scrolled past its first tabs.
10
14
  */
@@ -22,7 +26,11 @@ const TAB_CLASS = 'godmin-page-tabs__tab';
22
26
  */
23
27
  const CURRENT_CLASS = 'godmin-page-tabs__tab--current';
24
28
  /**
25
- * Returns the classes of a tab row, fading each edge that tabs lie past.
29
+ * The class of the line under the tab of the page on screen.
30
+ */
31
+ const LINE_CLASS = 'godmin-page-tabs__line';
32
+ /**
33
+ * Returns the classes of a tab row, marking one wider than its space and fading each edge that tabs lie past.
26
34
  * @param row - The tab row element.
27
35
  * @returns The class list.
28
36
  */
@@ -30,6 +38,9 @@ function rowClass(row) {
30
38
  const travelled = Math.abs(row.scrollLeft);
31
39
  const room = row.scrollWidth - row.clientWidth;
32
40
  let classes = ROW_CLASS;
41
+ if (room > 0) {
42
+ classes += ` ${SCROLLS_CLASS}`;
43
+ }
33
44
  if (travelled > ROUNDING_SLACK) {
34
45
  classes += ` ${FADES_START_CLASS}`;
35
46
  }
@@ -79,14 +90,14 @@ function reveal(row, tab) {
79
90
  }
80
91
  }
81
92
  /**
82
- * Scrolls a tab row to its current tab each time a tab becomes current, forgetting the last one while none is.
93
+ * Scrolls a tab row to its current tab as a tab becomes current or the row starts to scroll, forgetting it otherwise.
83
94
  * @param ref - The tab row element.
84
95
  */
85
96
  function useRevealCurrent(ref) {
86
97
  const shown = useRef(null);
87
98
  useLayoutEffect(() => {
88
99
  const row = ref.current;
89
- const tab = row.querySelector(`.${CURRENT_CLASS}`);
100
+ const tab = row.classList.contains(SCROLLS_CLASS) ? row.querySelector(`.${CURRENT_CLASS}`) : null;
90
101
  const last = shown.current;
91
102
  shown.current = tab;
92
103
  if (tab === null || tab === last) {
@@ -115,14 +126,15 @@ export function PageTabs({ label, children }) {
115
126
  function TabLink({ href, render, current = false, children }) {
116
127
  const ariaCurrent = current ? 'page' : undefined;
117
128
  const tabClass = current ? `${TAB_CLASS} ${CURRENT_CLASS}` : TAB_CLASS;
129
+ const label = (_jsxs(_Fragment, { children: [children, current && _jsx("span", { className: LINE_CLASS })] }));
118
130
  if (render === undefined) {
119
- return (_jsx("a", { href: href, className: tabClass, "aria-current": ariaCurrent, children: children }));
131
+ return (_jsx("a", { href: href, className: tabClass, "aria-current": ariaCurrent, children: label }));
120
132
  }
121
133
  const own = render.props.className;
122
134
  return cloneElement(render, {
123
135
  className: own === undefined ? tabClass : `${own} ${tabClass}`,
124
136
  'aria-current': ariaCurrent,
125
- children,
137
+ children: label,
126
138
  });
127
139
  }
128
140
  /**
package/dist/page.d.ts CHANGED
@@ -37,7 +37,12 @@ export interface PageProps {
37
37
  subtitle?: string;
38
38
  actions?: ReactNode;
39
39
  tabs?: ReactNode;
40
+ /** The details of a record, in a fixed column at the end of the page. */
40
41
  aside?: ReactNode;
42
+ /** The name of the details column. */
43
+ asideLabel?: string;
44
+ /** The links back to what a record belongs to, before the title. */
45
+ breadcrumbs?: ReactNode;
41
46
  list?: boolean;
42
47
  /** The name of the list region. */
43
48
  listLabel?: string;
@@ -50,11 +55,11 @@ export interface PageProps {
50
55
  }
51
56
  /**
52
57
  * Renders a screen: a header with the title, actions and subtitle, then optional tabs and the content.
53
- * @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class, title level
54
- * and content.
58
+ * @param props - The title, subtitle, actions, tabs, aside and its name, breadcrumbs, list flag, list name and ref,
59
+ * extra class, title level and content.
55
60
  * @returns The page element.
56
61
  */
57
- export declare function Page({ title, subtitle, actions, tabs, aside, list, listLabel, listRef, className, headingLevel, children, }: PageProps): import("react").JSX.Element;
62
+ export declare function Page({ title, subtitle, actions, tabs, aside, asideLabel, breadcrumbs, list, listLabel, listRef, className, headingLevel, children, }: PageProps): import("react").JSX.Element;
58
63
  /**
59
64
  * Renders a failure message that a screen reader announces.
60
65
  * @param props - The message to announce.
package/dist/page.js CHANGED
@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  /* oxlint-disable react/only-export-components -- the page kit ships its parts
3
3
  beside the type they share. */
4
4
  import { Button, Notice, Stack, Text } from '@wordpress/ui';
5
- import { createContext, useContext, useImperativeHandle, useRef } from 'react';
5
+ import { Children, createContext, useContext, useImperativeHandle, useRef } from 'react';
6
6
  import { useWideList } from './wide-list.js';
7
7
  /** The level of the title of the Page around a section title, 1 outside any Page. */
8
8
  const PageLevelContext = createContext(1);
@@ -41,6 +41,14 @@ export function SectionTitle({ children, level = 2, id, tabIndex, }) {
41
41
  const Heading = headingTag(level + pageLevel - 1);
42
42
  return (_jsx(Text, { variant: level === 2 ? 'heading-lg' : 'heading-md', render: _jsx(Heading, {}), id: id, tabIndex: tabIndex, children: children }));
43
43
  }
44
+ /**
45
+ * Returns the role and the name of a region given a label.
46
+ * @param label - The name of the region.
47
+ * @returns The role and the name, or nothing with no label.
48
+ */
49
+ function namedRegion(label) {
50
+ return label === undefined ? {} : { role: 'region', 'aria-label': label };
51
+ }
44
52
  /**
45
53
  * Returns the props that let code focus a list with a name or a ref, and name a list region given a label.
46
54
  * @param label - The name of the list region.
@@ -49,7 +57,7 @@ export function SectionTitle({ children, level = 2, id, tabIndex, }) {
49
57
  */
50
58
  function regionOf(label, reached) {
51
59
  const focus = label === undefined && !reached ? {} : { tabIndex: -1 };
52
- return label === undefined ? focus : { ...focus, role: 'region', 'aria-label': label };
60
+ return { ...focus, ...namedRegion(label) };
53
61
  }
54
62
  /**
55
63
  * Renders the list region of a page, marked wide while its DataViews table is wider than its space.
@@ -62,26 +70,45 @@ function ListRegion({ label, listRef, children, }) {
62
70
  useImperativeHandle(listRef, () => own.current, []);
63
71
  return (_jsx("div", { className: wide ? 'godmin-page__list godmin-page__list--wide' : 'godmin-page__list', ref: own, ...regionOf(label, listRef !== undefined), children: children }));
64
72
  }
73
+ /**
74
+ * Tells whether a page has breadcrumbs to draw.
75
+ * @param breadcrumbs - What the page was given.
76
+ * @returns Whether it holds anything that renders.
77
+ */
78
+ function hasBreadcrumbs(breadcrumbs) {
79
+ return Children.toArray(breadcrumbs).length > 0;
80
+ }
81
+ /**
82
+ * Renders the title of a page, after its breadcrumbs when it has them.
83
+ * @param props - The title, its heading level and the breadcrumbs.
84
+ * @returns The title, alone or after its breadcrumbs.
85
+ */
86
+ function PageHeading({ title, level, breadcrumbs }) {
87
+ if (!hasBreadcrumbs(breadcrumbs)) {
88
+ return _jsx(PageTitle, { level: level, children: title });
89
+ }
90
+ return (_jsxs("div", { className: "godmin-page__heading", children: [breadcrumbs, _jsx(PageTitle, { level: level, children: title })] }));
91
+ }
65
92
  /**
66
93
  * Renders a screen: a header with the title, actions and subtitle, then optional tabs and the content.
67
- * @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class, title level
68
- * and content.
94
+ * @param props - The title, subtitle, actions, tabs, aside and its name, breadcrumbs, list flag, list name and ref,
95
+ * extra class, title level and content.
69
96
  * @returns The page element.
70
97
  */
71
- export function Page({ title, subtitle, actions, tabs, aside, list = false, listLabel, listRef, className, headingLevel = 1, children, }) {
98
+ export function Page({ title, subtitle, actions, tabs, aside, asideLabel, breadcrumbs, list = false, listLabel, listRef, className, headingLevel = 1, children, }) {
72
99
  const classes = className === undefined ? 'godmin-page' : `godmin-page ${className}`;
73
- return (_jsx(PageLevelContext.Provider, { value: headingLevel, children: _jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "column", render: _jsx("header", {}), className: "godmin-page__header", children: [_jsxs(Stack, { direction: "row", wrap: "wrap", gap: "md", align: "center", justify: "space-between", className: "godmin-page__head", children: [_jsx(PageTitle, { level: headingLevel, children: title }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), subtitle !== undefined && (_jsx(Text, { variant: "body-md", render: _jsx("p", {}), className: "godmin-page__subtitle", children: subtitle }))] }), tabs !== undefined && _jsx("div", { className: "godmin-page__tabs", children: tabs }), _jsx(PageBody, { aside: aside, children: list ? (_jsx(ListRegion, { label: listLabel, listRef: listRef, children: children })) : (children) })] }) }));
100
+ return (_jsx(PageLevelContext.Provider, { value: headingLevel, children: _jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "column", render: _jsx("header", {}), className: "godmin-page__header", children: [_jsxs(Stack, { direction: "row", wrap: "wrap", gap: "md", align: "center", justify: "space-between", className: "godmin-page__head", children: [_jsx(PageHeading, { title: title, level: headingLevel, breadcrumbs: breadcrumbs }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), subtitle !== undefined && (_jsx(Text, { variant: "body-md", render: _jsx("p", {}), className: "godmin-page__subtitle", children: subtitle }))] }), tabs !== undefined && _jsx("div", { className: "godmin-page__tabs", children: tabs }), _jsx(PageBody, { aside: aside, asideLabel: asideLabel, children: list ? (_jsx(ListRegion, { label: listLabel, listRef: listRef, children: children })) : (children) })] }) }));
74
101
  }
75
102
  /**
76
103
  * Renders a page's content, beside its aside when it has one.
77
- * @param props - The content and the optional aside.
104
+ * @param props - The content, the optional aside and the name of the aside.
78
105
  * @returns The content alone, or a main column followed by the aside.
79
106
  */
80
- function PageBody({ aside, children }) {
107
+ function PageBody({ aside, asideLabel, children }) {
81
108
  if (aside === undefined) {
82
109
  return children;
83
110
  }
84
- return (_jsxs("div", { className: "godmin-page__split", children: [_jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__main", children: children }), _jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__aside", children: aside })] }));
111
+ return (_jsxs("div", { className: "godmin-page__split", children: [_jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__main", children: children }), _jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__aside", ...namedRegion(asideLabel), children: aside })] }));
85
112
  }
86
113
  /**
87
114
  * Renders a failure message that a screen reader announces.
@@ -0,0 +1,24 @@
1
+ import type { DialogAnswer } from './dialog-open.js';
2
+ /** The props of a dialog that asks for a new name for one item. */
3
+ export interface RenameDialogProps {
4
+ /** The title in the dialog header, the name of the dialog. */
5
+ title: string;
6
+ /** The text the field starts with, the name the item carries. */
7
+ name: string;
8
+ /** The label of the name field. */
9
+ fieldLabel: string;
10
+ /** The label of the button that writes the new name. */
11
+ submitLabel: string;
12
+ /** The label of the button that closes the dialog. */
13
+ cancelLabel: string;
14
+ /** Writes the name as typed. Return nothing to close at once, the write to hold the dialog, or an answer to stay. */
15
+ onSubmit: (name: string) => void | DialogAnswer | PromiseLike<unknown>;
16
+ /** Takes the dialog away, once its card has left the page. */
17
+ onClose: () => void;
18
+ }
19
+ /**
20
+ * Renders a dialog that asks for a new name, Save on at all times and the browser refusing a blank name.
21
+ * @param props - The title, the current name, the labels and the handlers.
22
+ * @returns The dialog.
23
+ */
24
+ export declare function RenameDialog({ title, name, fieldLabel, submitLabel, cancelLabel, onSubmit, onClose, }: RenameDialogProps): import("react").JSX.Element;
@@ -0,0 +1,16 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { InputControl } from '@wordpress/ui';
4
+ import { useState } from 'react';
5
+ import { FormDialog } from './form-dialog.js';
6
+ /** The pattern a name must match: any text that holds more than spaces. */
7
+ const NOT_ONLY_SPACES = '.*\\S.*';
8
+ /**
9
+ * Renders a dialog that asks for a new name, Save on at all times and the browser refusing a blank name.
10
+ * @param props - The title, the current name, the labels and the handlers.
11
+ * @returns The dialog.
12
+ */
13
+ export function RenameDialog({ title, name, fieldLabel, submitLabel, cancelLabel, onSubmit, onClose, }) {
14
+ const [value, setValue] = useState(name);
15
+ return (_jsx(FormDialog, { title: title, submitLabel: submitLabel, cancelLabel: cancelLabel, onSubmit: () => onSubmit(value), onClose: onClose, children: (busy) => (_jsx(InputControl, { label: fieldLabel, value: value, required: true, pattern: NOT_ONLY_SPACES, readOnly: busy, onChange: (event) => setValue(event.target.value) })) }));
16
+ }
package/dist/router.d.ts CHANGED
@@ -12,6 +12,8 @@ export { NavigationItem } from './navigation-item.js';
12
12
  export type { NavigationItemProps } from './navigation-item.js';
13
13
  export { NavigationList } from './navigation-list.js';
14
14
  export type { NavigationListProps } from './navigation-list.js';
15
+ export { UnsavedChangesDialog } from './unsaved-changes-dialog.js';
16
+ export type { UnsavedChangesDialogProps } from './unsaved-changes-dialog.js';
15
17
  declare module '@tanstack/react-router' {
16
18
  interface StaticDataRouteOption {
17
19
  canvas?: CanvasMode;
package/dist/router.js CHANGED
@@ -6,6 +6,7 @@ export { useCanAccess } from './menu-item.js';
6
6
  export { Navigation } from './navigation.js';
7
7
  export { NavigationItem } from './navigation-item.js';
8
8
  export { NavigationList } from './navigation-list.js';
9
+ export { UnsavedChangesDialog } from './unsaved-changes-dialog.js';
9
10
  /**
10
11
  * Returns the canvas the deepest matching route asks for.
11
12
  * @returns The canvas mode, padded when no route asks for one.
package/dist/toaster.js CHANGED
@@ -117,6 +117,21 @@ function ToastItem({ toast, region, onGone, children }) {
117
117
  const item = toast.leaving ? 'godmin-toasts__item godmin-toasts__item--leaving' : 'godmin-toasts__item';
118
118
  return (_jsx("div", { ref: ref, className: item, children: _jsx("div", { className: "godmin-toasts__item-inner", children: children }) }));
119
119
  }
120
+ /**
121
+ * Keeps a press on a leaving toast from moving the focus onto it.
122
+ * @param event - The press.
123
+ */
124
+ function holdFocus(event) {
125
+ event.preventDefault();
126
+ }
127
+ /**
128
+ * Returns what a toast takes while it fades out.
129
+ * @param leaving - Whether the toast is fading out.
130
+ * @returns The props, none for a toast that stays.
131
+ */
132
+ function leavingProps(leaving) {
133
+ return leaving ? { 'aria-hidden': true, tabIndex: -1, onMouseDown: holdFocus } : {};
134
+ }
120
135
  /**
121
136
  * Renders a toast with no action as one button that clears it, described by the dismiss hint.
122
137
  * @param props - The toast, how long it stays, the id of the dismiss hint and the handler clearing it.
@@ -124,7 +139,7 @@ function ToastItem({ toast, region, onGone, children }) {
124
139
  */
125
140
  function PlainToast({ toast, dismissAfter, hint, onLeave }) {
126
141
  useExpiry(toast, dismissAfter, onLeave);
127
- return (_jsx("button", { type: "button", className: toastClass('godmin-toast godmin-toast--plain', toast.leaving), "aria-describedby": hint, inert: toast.leaving, onClick: () => onLeave(toast.id), children: toast.message }));
142
+ return (_jsx("button", { type: "button", className: toastClass('godmin-toast godmin-toast--plain', toast.leaving), "aria-describedby": hint, ...leavingProps(toast.leaving), onClick: () => onLeave(toast.id), children: toast.message }));
128
143
  }
129
144
  /**
130
145
  * Renders a toast with its action, cleared by a click anywhere on it, the action its only control.
@@ -133,7 +148,11 @@ function PlainToast({ toast, dismissAfter, hint, onLeave }) {
133
148
  */
134
149
  function ActionToast({ toast, action, dismissAfter, onLeave }) {
135
150
  useExpiry(toast, dismissAfter, onLeave);
136
- return (_jsxs("div", { className: toastClass('godmin-toast', toast.leaving), inert: toast.leaving, onClick: () => onLeave(toast.id), children: [_jsx("span", { className: "godmin-toast__message", children: toast.message }), _jsx("button", { type: "button", className: "godmin-toast__action", onClick: () => {
151
+ const { tabIndex, ...hidden } = leavingProps(toast.leaving);
152
+ return (_jsxs("div", { className: toastClass('godmin-toast', toast.leaving), ...hidden, onClick: () => onLeave(toast.id), children: [_jsx("span", { className: "godmin-toast__message", children: toast.message }), _jsx("button", { type: "button", className: "godmin-toast__action", tabIndex: tabIndex, onClick: () => {
153
+ if (toast.leaving) {
154
+ return;
155
+ }
137
156
  onLeave(toast.id);
138
157
  action.onAct();
139
158
  }, children: action.label })] }));
@@ -0,0 +1,19 @@
1
+ /** The props of the dialog that asks before a move leaves a page holding unsaved work. */
2
+ export interface UnsavedChangesDialogProps {
3
+ /** Whether the page holds unsaved work, so a move away asks first. */
4
+ when: boolean;
5
+ /** The question, such as "Discard changes?". */
6
+ title: string;
7
+ /** What the reader loses, such as "Your changes are not saved.". */
8
+ description: string;
9
+ /** The label of the red button that drops the work and leaves. */
10
+ discardLabel: string;
11
+ /** The label of the button that stays with the work. */
12
+ keepLabel: string;
13
+ }
14
+ /**
15
+ * Renders an irreversible confirm while a move away from a page holding unsaved work waits on the reader.
16
+ * @param props - When to ask, and the words of the question and its buttons.
17
+ * @returns The confirm while a move waits, otherwise nothing.
18
+ */
19
+ export declare function UnsavedChangesDialog({ when, title, description, discardLabel, keepLabel }: UnsavedChangesDialogProps): import("react").JSX.Element | null;
@@ -0,0 +1,33 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { useBlocker } from '@tanstack/react-router';
4
+ import { useRef } from 'react';
5
+ import { ConfirmDialog } from './confirm-dialog.js';
6
+ /**
7
+ * Reports whether a move leaves the page, and not only changes its search.
8
+ * @param move - Where the reader is and where the move goes.
9
+ * @returns True when the move goes to another path.
10
+ */
11
+ function leavesPage({ current, next }) {
12
+ return current.pathname !== next.pathname;
13
+ }
14
+ /**
15
+ * Renders an irreversible confirm while a move away from a page holding unsaved work waits on the reader.
16
+ * @param props - When to ask, and the words of the question and its buttons.
17
+ * @returns The confirm while a move waits, otherwise nothing.
18
+ */
19
+ export function UnsavedChangesDialog({ when, title, description, discardLabel, keepLabel }) {
20
+ const discarding = useRef(false);
21
+ const leaving = useBlocker({ shouldBlockFn: leavesPage, disabled: !when, withResolver: true });
22
+ if (leaving.status !== 'blocked') {
23
+ return null;
24
+ }
25
+ const { proceed, reset } = leaving;
26
+ return (_jsx(ConfirmDialog, { intent: "irreversible", title: title, description: description, confirmLabel: discardLabel, cancelLabel: keepLabel, onConfirm: () => {
27
+ discarding.current = true;
28
+ }, onClose: () => {
29
+ const settle = discarding.current ? proceed : reset;
30
+ discarding.current = false;
31
+ settle();
32
+ } }));
33
+ }