@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,121 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { speak } from '@wordpress/a11y';
3
+ import { useCallback, useEffect, useInsertionEffect, useRef, useState } from 'react';
4
+ /** The server messages each form shows in the current commit, so only one is spoken. */
5
+ const toSpeak = new WeakMap();
6
+ /**
7
+ * Returns the form a field sits in on the page.
8
+ * @param field - The field, null when it never mounted or left.
9
+ * @returns The form, null when the field is not on the page or sits in no form.
10
+ */
11
+ function formOf(field) {
12
+ return field?.isConnected === true ? field.form : null;
13
+ }
14
+ /**
15
+ * Tells whether a server's message can stand under a field.
16
+ * @param field - The field, null when it never mounted or left.
17
+ * @param message - The server's message.
18
+ * @returns True when there are words and the field sits in a form on the page.
19
+ */
20
+ function canStand(field, message) {
21
+ return message !== '' && formOf(field) !== null;
22
+ }
23
+ /**
24
+ * Speaks one server message for a form once every report of the commit ran, the focused field's when it is one.
25
+ * @param form - The form that was reported.
26
+ * @param spoken - The server's message and the field it stands under.
27
+ */
28
+ function speakOnce(form, spoken) {
29
+ const queued = toSpeak.get(form);
30
+ if (queued !== undefined) {
31
+ queued.push(spoken);
32
+ return;
33
+ }
34
+ const all = [spoken];
35
+ toSpeak.set(form, all);
36
+ queueMicrotask(() => {
37
+ toSpeak.delete(form);
38
+ const focused = all.find((entry) => entry.field === document.activeElement) ?? spoken;
39
+ speak(focused.message, 'assertive');
40
+ });
41
+ }
42
+ /**
43
+ * Shows the message of every field of a form that fails and speaks a server's message about one of them.
44
+ * @param field - The field the server's message stands under, null once it left the page.
45
+ * @param validity - The custom validity holding the server's message.
46
+ * @returns The field when its form was reported, undefined when it is not on the page in a form.
47
+ */
48
+ function report(field, validity) {
49
+ const form = formOf(field);
50
+ if (field === null || form === null) {
51
+ return undefined;
52
+ }
53
+ form.reportValidity();
54
+ speakOnce(form, { field, message: validity.message });
55
+ return field;
56
+ }
57
+ /**
58
+ * Holds a server's message about a value, forgetting it once the value changes.
59
+ * @param held - What the message is about now.
60
+ * @returns The message standing and the way to put one.
61
+ */
62
+ function useStanding(held) {
63
+ const [standing, setStanding] = useState();
64
+ if (standing !== undefined && standing.value !== held) {
65
+ setStanding(undefined);
66
+ }
67
+ return [standing, setStanding];
68
+ }
69
+ /**
70
+ * Keeps what a field held in the last commit.
71
+ * @param held - What the field holds now.
72
+ * @returns The ref holding it.
73
+ */
74
+ function useHolding(held) {
75
+ const holding = useRef(held);
76
+ useInsertionEffect(() => {
77
+ holding.current = held;
78
+ });
79
+ return holding;
80
+ }
81
+ /**
82
+ * Reports a server's message once it stands under a field, and takes it off the field once it goes.
83
+ * @param field - The field the message stands under.
84
+ * @param standing - The message standing, none once it went.
85
+ */
86
+ function useReport(field, standing) {
87
+ const shownOn = useRef(undefined);
88
+ useInsertionEffect(() => {
89
+ if (standing === undefined && shownOn.current !== undefined) {
90
+ shownOn.current.setCustomValidity('');
91
+ shownOn.current = undefined;
92
+ }
93
+ });
94
+ useEffect(() => {
95
+ if (standing !== undefined) {
96
+ shownOn.current = report(field.current, standing.validity);
97
+ }
98
+ }, [field, standing]);
99
+ }
100
+ /**
101
+ * Holds a server's message about one field under it, until what the message is about changes.
102
+ * @param held - What the message is about now, the value of the field in most forms.
103
+ * @returns The ref and the custom validity the field takes, and the way to reject what was sent.
104
+ */
105
+ export function useRejectedField(held) {
106
+ const [standing, setStanding] = useStanding(held);
107
+ const holding = useHolding(held);
108
+ const field = useRef(null);
109
+ useReport(field, standing);
110
+ const ref = useCallback((element) => {
111
+ field.current = element;
112
+ }, []);
113
+ const reject = useCallback((message, sent) => {
114
+ if (holding.current !== sent || !canStand(field.current, message)) {
115
+ return false;
116
+ }
117
+ setStanding({ validity: { type: 'invalid', message }, value: sent });
118
+ return true;
119
+ }, [holding, setStanding]);
120
+ return { ref, validity: standing?.validity, reject };
121
+ }
@@ -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 typed name with the time limit's signal. Return nothing to close, the write to hold it, or an answer. */
15
+ onSubmit: (name: string, signal: AbortSignal) => 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: (signal) => onSubmit(value, signal), 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
+ }
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Renders the screen of an address no route serves, in the words of WordPress's new admin.
3
+ * @returns The page element, titled Route not found.
4
+ */
5
+ export declare function RouteNotFound(): import("react").JSX.Element;
@@ -0,0 +1,12 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import { __ } from '@wordpress/i18n';
4
+ import { Text } from '@wordpress/ui';
5
+ import { Page } from './page.js';
6
+ /**
7
+ * Renders the screen of an address no route serves, in the words of WordPress's new admin.
8
+ * @returns The page element, titled Route not found.
9
+ */
10
+ export function RouteNotFound() {
11
+ return (_jsx(Page, { title: __('Route not found'), headingLevel: 2, children: _jsx(Text, { variant: "body-md", render: _jsx("p", {}), children: __("The page you're looking for does not exist") }) }));
12
+ }
package/dist/router.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { ComponentType } from 'react';
1
+ import type { ComponentType, ReactNode } from 'react';
2
2
  import type { CanvasMode } from './frame.js';
3
3
  export { DrilldownItem } from './drilldown-item.js';
4
4
  export type { DrilldownItemProps } from './drilldown-item.js';
@@ -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;
@@ -31,10 +33,16 @@ export declare function useCanvas(): CanvasMode;
31
33
  * @returns The pathname of the active location followed by its search.
32
34
  */
33
35
  export declare function useFrameLocation(): string;
36
+ /**
37
+ * Returns the path the router has finished showing, for a frame to speak the new screen's title on.
38
+ * @returns The pathname of the location the router has drawn, undefined until it has drawn one.
39
+ */
40
+ export declare function useShownPath(): string | undefined;
34
41
  /**
35
42
  * Returns the options a router spreads into createRouter, as WordPress's new admin sets them.
36
- * @returns Preload on intent, and no pending screen.
43
+ * @returns Preload on intent and the Route not found screen, and no pending screen.
37
44
  */
38
45
  export declare function routerDefaults(): {
39
46
  defaultPreload: 'intent';
47
+ defaultNotFoundComponent: () => ReactNode;
40
48
  };
package/dist/router.js CHANGED
@@ -1,11 +1,13 @@
1
1
  import { useRouterState } from '@tanstack/react-router';
2
2
  import { locationAddress } from './path-matching.js';
3
+ import { RouteNotFound } from './route-not-found.js';
3
4
  export { DrilldownItem } from './drilldown-item.js';
4
5
  export { listSearch, openOnTap, useListView } from './list-view.js';
5
6
  export { useCanAccess } from './menu-item.js';
6
7
  export { Navigation } from './navigation.js';
7
8
  export { NavigationItem } from './navigation-item.js';
8
9
  export { NavigationList } from './navigation-list.js';
10
+ export { UnsavedChangesDialog } from './unsaved-changes-dialog.js';
9
11
  /**
10
12
  * Returns the canvas the deepest matching route asks for.
11
13
  * @returns The canvas mode, padded when no route asks for one.
@@ -25,10 +27,17 @@ export function useCanvas() {
25
27
  export function useFrameLocation() {
26
28
  return useRouterState({ select: (state) => locationAddress(state.location) });
27
29
  }
30
+ /**
31
+ * Returns the path the router has finished showing, for a frame to speak the new screen's title on.
32
+ * @returns The pathname of the location the router has drawn, undefined until it has drawn one.
33
+ */
34
+ export function useShownPath() {
35
+ return useRouterState({ select: (state) => state.resolvedLocation?.pathname });
36
+ }
28
37
  /**
29
38
  * Returns the options a router spreads into createRouter, as WordPress's new admin sets them.
30
- * @returns Preload on intent, and no pending screen.
39
+ * @returns Preload on intent and the Route not found screen, and no pending screen.
31
40
  */
32
41
  export function routerDefaults() {
33
- return { defaultPreload: 'intent' };
42
+ return { defaultPreload: 'intent', defaultNotFoundComponent: RouteNotFound };
34
43
  }
@@ -0,0 +1,52 @@
1
+ /** How long in milliseconds a waiting title holds after the shown path changes, before the frame takes it as it is. */
2
+ export declare const TITLE_WAIT = 1000;
3
+ /** The title one mounted screen reports. */
4
+ interface TitleReport {
5
+ /** The title of the screen. */
6
+ title: string;
7
+ /** How many Pages hold the one that reports, 1 for a Page inside no other, 0 for a PageTitle outside any Page. */
8
+ depth: number;
9
+ /** Whether the Page holds nothing but one LoadingScreen, so its title only names the kind of record. */
10
+ waiting: boolean;
11
+ }
12
+ /** The titles the mounted screens of one frame report. */
13
+ export interface ScreenTitles {
14
+ /** Reports a title and returns the function that withdraws it. */
15
+ report: (report: TitleReport) => () => void;
16
+ /** Returns the deepest title, the newest of those as deep, or undefined while no screen reports one. */
17
+ deepest: () => TitleReport | undefined;
18
+ /** Calls a listener whenever a title is reported or withdrawn, and returns the function that stops it. */
19
+ subscribe: (listener: () => void) => () => void;
20
+ }
21
+ /** The titles of the frame around a screen, undefined outside any frame. */
22
+ export declare const ScreenTitleContext: import("react").Context<ScreenTitles | undefined>;
23
+ /**
24
+ * Creates the store of the titles the mounted screens of one frame report.
25
+ * @returns The store, holding no title.
26
+ */
27
+ export declare function createScreenTitles(): ScreenTitles;
28
+ /**
29
+ * Reports a screen title to the frame around it while the screen is mounted.
30
+ * @param title - The title, undefined for a screen that reports none.
31
+ * @param depth - How many Pages hold the one that reports.
32
+ * @param waiting - Whether the title only names the kind of record while the record loads.
33
+ */
34
+ export declare function useReportTitle(title: string | undefined, depth: number, waiting: boolean): void;
35
+ /** What a frame hands the part that speaks its titles. */
36
+ interface TitleWatchProps {
37
+ /** The titles the screens of the frame report. */
38
+ titles: ScreenTitles;
39
+ /** The path the router has finished showing, nothing spoken without it. */
40
+ shownPath?: string;
41
+ /** The address the router moves to. */
42
+ location?: string;
43
+ /** The name of the app the tab title ends with, the tab title left alone without it. */
44
+ appName?: string;
45
+ }
46
+ /**
47
+ * Speaks the title of each new screen of a frame and sets the tab title from it, drawing nothing.
48
+ * @param props - The titles of the frame, the shown path, the address the router moves to and the app name.
49
+ * @returns Nothing.
50
+ */
51
+ export declare function TitleWatch({ titles, shownPath, location, appName }: TitleWatchProps): null;
52
+ export {};
@@ -0,0 +1,165 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ import { speak } from '@wordpress/a11y';
3
+ import { __, sprintf } from '@wordpress/i18n';
4
+ import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
5
+ /** How long in milliseconds a waiting title holds after the shown path changes, before the frame takes it as it is. */
6
+ export const TITLE_WAIT = 1000;
7
+ /** The titles of the frame around a screen, undefined outside any frame. */
8
+ export const ScreenTitleContext = createContext(undefined);
9
+ /**
10
+ * Returns the deepest of the reported titles, the newest of those as deep.
11
+ * @param reports - The reported titles, oldest first.
12
+ * @returns That title, or undefined when there is none.
13
+ */
14
+ function deepestOf(reports) {
15
+ return reports.reduce((found, report) => (found === undefined || report.depth >= found.depth ? report : found), undefined);
16
+ }
17
+ /**
18
+ * Creates the store of the titles the mounted screens of one frame report.
19
+ * @returns The store, holding no title.
20
+ */
21
+ export function createScreenTitles() {
22
+ let reports = [];
23
+ let deepest;
24
+ const listeners = new Set();
25
+ const changed = (next) => {
26
+ reports = next;
27
+ deepest = deepestOf(reports);
28
+ listeners.forEach((listener) => listener());
29
+ };
30
+ return {
31
+ report: (report) => {
32
+ changed([...reports, report]);
33
+ return () => changed(reports.filter((held) => held !== report));
34
+ },
35
+ deepest: () => deepest,
36
+ subscribe: (listener) => {
37
+ listeners.add(listener);
38
+ return () => {
39
+ listeners.delete(listener);
40
+ };
41
+ },
42
+ };
43
+ }
44
+ /**
45
+ * Reports a screen title to the frame around it while the screen is mounted.
46
+ * @param title - The title, undefined for a screen that reports none.
47
+ * @param depth - How many Pages hold the one that reports.
48
+ * @param waiting - Whether the title only names the kind of record while the record loads.
49
+ */
50
+ export function useReportTitle(title, depth, waiting) {
51
+ const titles = useContext(ScreenTitleContext);
52
+ useLayoutEffect(() => {
53
+ if (titles === undefined || title === undefined) {
54
+ return;
55
+ }
56
+ return titles.report({ title, depth, waiting });
57
+ }, [titles, title, depth, waiting]);
58
+ }
59
+ /**
60
+ * Tells whether a waiting title still holds, for at most TITLE_WAIT after the shown path changes.
61
+ * @param waiting - Whether the title only names the kind of record.
62
+ * @param shownPath - The path the router has finished showing.
63
+ * @returns Whether the title waits and the cap has not passed since this wait began.
64
+ */
65
+ function useHeld(waiting, shownPath) {
66
+ const wait = useMemo(() => ({ waiting, shownPath }), [waiting, shownPath]);
67
+ const [capped, setCapped] = useState();
68
+ useEffect(() => {
69
+ if (!wait.waiting) {
70
+ return;
71
+ }
72
+ const timer = setTimeout(() => setCapped(wait), TITLE_WAIT);
73
+ return () => clearTimeout(timer);
74
+ }, [wait]);
75
+ return waiting && capped !== wait;
76
+ }
77
+ /**
78
+ * Notes the path the router shows: a new one replaces the last, and owes its title once the first load is over.
79
+ * @param shown - What the frame keeps of the paths shown.
80
+ * @param path - The path shown now.
81
+ */
82
+ function notePath(shown, path) {
83
+ if (shown.path !== path) {
84
+ shown.path = path;
85
+ shown.owed = shown.firstOver;
86
+ }
87
+ }
88
+ /**
89
+ * Speaks a title assertively two animation frames from now.
90
+ * @param title - The title.
91
+ * @param shown - What the frame keeps of the paths shown, whose title is no longer owed once spoken.
92
+ * @returns The function that cancels both frames.
93
+ */
94
+ function speakLater(title, shown) {
95
+ let second = 0;
96
+ const first = requestAnimationFrame(() => {
97
+ second = requestAnimationFrame(() => {
98
+ shown.owed = false;
99
+ speak(title, 'assertive');
100
+ });
101
+ });
102
+ return () => {
103
+ cancelAnimationFrame(first);
104
+ cancelAnimationFrame(second);
105
+ };
106
+ }
107
+ /**
108
+ * Tells whether a move to another path has started and not shown yet.
109
+ * @param location - The address the router moves to, its path before any search or hash.
110
+ * @param shownPath - The path the router has finished showing.
111
+ * @returns Whether the path of the address differs from the shown path, never without an address.
112
+ */
113
+ function moveInFlight(location, shownPath) {
114
+ return location !== undefined && location.split(/[?#]/)[0] !== shownPath;
115
+ }
116
+ /**
117
+ * Speaks the title of each screen a new path shows, never during the first load, which lasts until the frame
118
+ * first holds a title it would speak with no move in flight.
119
+ * @param title - The title to speak, undefined while no screen reports one or it still waits.
120
+ * @param shownPath - The path the router has finished showing.
121
+ * @param location - The address the router moves to.
122
+ */
123
+ function useSpokenTitle(title, shownPath, location) {
124
+ const shown = useRef({ firstOver: false, owed: false });
125
+ const inFlight = shownPath !== undefined && moveInFlight(location, shownPath);
126
+ useEffect(() => {
127
+ if (shownPath === undefined) {
128
+ return;
129
+ }
130
+ notePath(shown.current, shownPath);
131
+ if (title === undefined) {
132
+ return;
133
+ }
134
+ if (!shown.current.firstOver) {
135
+ shown.current.firstOver = !inFlight;
136
+ return;
137
+ }
138
+ return shown.current.owed ? speakLater(title, shown.current) : undefined;
139
+ }, [title, shownPath, inFlight]);
140
+ }
141
+ /**
142
+ * Sets the tab title to the screen title and the app name, through the translated pattern.
143
+ * @param title - The screen title, undefined while no screen reports one or it still waits.
144
+ * @param appName - The name of the app, undefined to leave the tab title alone.
145
+ */
146
+ function useTabTitle(title, appName) {
147
+ useEffect(() => {
148
+ if (title !== undefined && appName !== undefined) {
149
+ document.title = sprintf(__('%1$s ‹ %2$s'), title, appName);
150
+ }
151
+ }, [title, appName]);
152
+ }
153
+ /**
154
+ * Speaks the title of each new screen of a frame and sets the tab title from it, drawing nothing.
155
+ * @param props - The titles of the frame, the shown path, the address the router moves to and the app name.
156
+ * @returns Nothing.
157
+ */
158
+ export function TitleWatch({ titles, shownPath, location, appName }) {
159
+ const shown = useSyncExternalStore(titles.subscribe, titles.deepest);
160
+ const held = useHeld(shown?.waiting === true, shownPath);
161
+ const title = held ? undefined : shown?.title;
162
+ useTabTitle(title, appName);
163
+ useSpokenTitle(title, shownPath, location);
164
+ return null;
165
+ }
@@ -1,7 +1,4 @@
1
- /**
2
- * The stylelint configuration turning on every design system rule the theme
3
- * package ships.
4
- */
1
+ /** The stylelint configuration turning on every design system rule the build tools package ships. */
5
2
  declare const config: {
6
3
  plugins: string[];
7
4
  rules: {
package/dist/stylelint.js CHANGED
@@ -1,13 +1,10 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
- /**
3
- * The stylelint configuration turning on every design system rule the theme
4
- * package ships.
5
- */
2
+ /** The stylelint configuration turning on every design system rule the build tools package ships. */
6
3
  const config = {
7
4
  plugins: [
8
- '@wordpress/theme/stylelint-plugins/no-unknown-ds-tokens',
9
- '@wordpress/theme/stylelint-plugins/no-setting-wpds-custom-properties',
10
- '@wordpress/theme/stylelint-plugins/no-token-fallback-values',
5
+ '@wordpress/theme-build-tools/stylelint-plugins/no-unknown-ds-tokens',
6
+ '@wordpress/theme-build-tools/stylelint-plugins/no-setting-wpds-custom-properties',
7
+ '@wordpress/theme-build-tools/stylelint-plugins/no-token-fallback-values',
11
8
  ],
12
9
  rules: {
13
10
  'plugin-wpds/no-unknown-ds-tokens': true,
package/dist/testing.d.ts CHANGED
@@ -73,7 +73,7 @@ export declare function buttonClasses(variant: ComponentProps<typeof Button>['va
73
73
  /**
74
74
  * Renders the given tree inside the design system host.
75
75
  * @param ui - The tree to render.
76
- * @param options - The testing library options, plus the host theme settings.
76
+ * @param options - The testing library options, the host theme settings and a write time limit, none when left out.
77
77
  * @returns The testing library render result.
78
78
  */
79
- export declare function renderAdmin(ui: ReactNode, options?: RenderOptions & Omit<AdminRootProps, 'children'>): RenderResult;
79
+ export declare function renderAdmin(ui: ReactNode, options?: RenderOptions & Omit<AdminRootProps, 'children' | 'writeTimeout'> & Partial<Pick<AdminRootProps, 'writeTimeout'>>): RenderResult;
package/dist/testing.js CHANGED
@@ -271,15 +271,15 @@ export function buttonClasses(variant, size, tone) {
271
271
  /**
272
272
  * Renders the given tree inside the design system host.
273
273
  * @param ui - The tree to render.
274
- * @param options - The testing library options, plus the host theme settings.
274
+ * @param options - The testing library options, the host theme settings and a write time limit, none when left out.
275
275
  * @returns The testing library render result.
276
276
  */
277
277
  export function renderAdmin(ui, options = {}) {
278
- const { color, cursor, cornerRadius, as, ...renderOptions } = options;
278
+ const { color, cursor, cornerRadius, as, writeTimeout = Infinity, ...renderOptions } = options;
279
279
  return render(ui, {
280
280
  ...renderOptions,
281
281
  wrapper: function Host({ children }) {
282
- return _jsx(AdminRoot, { color, cursor, cornerRadius, as, children: children });
282
+ return _jsx(AdminRoot, { color, cursor, cornerRadius, as, writeTimeout, children: children });
283
283
  },
284
284
  });
285
285
  }
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
+ }
package/dist/vite.js CHANGED
@@ -12,6 +12,7 @@ export const godminDedupe = [
12
12
  '@wordpress/theme',
13
13
  '@wordpress/ui',
14
14
  '@gopherium/react-auth',
15
+ '@gopherium/godmin',
15
16
  ];
16
17
  /**
17
18
  * Returns the package a resolved module id belongs to.