@gopherium/godmin 0.32.0 → 0.33.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -9
- package/dist/admin-root.d.ts +4 -2
- package/dist/admin-root.js +6 -3
- package/dist/announcer-heading.d.ts +4 -0
- package/dist/announcer-heading.js +25 -0
- package/dist/base.css +36 -4
- package/dist/bulk-run.d.ts +2 -2
- package/dist/bulk-run.js +18 -2
- package/dist/confirm-dialog.d.ts +2 -2
- package/dist/confirm-dialog.js +3 -2
- package/dist/dialog-open.d.ts +16 -2
- package/dist/dialog-open.js +126 -5
- package/dist/drilldown-item.d.ts +5 -2
- package/dist/drilldown-item.js +14 -2
- package/dist/filter-offer.d.ts +5 -5
- package/dist/filter-offer.js +9 -9
- package/dist/focus-back.js +12 -2
- package/dist/form-dialog.d.ts +2 -2
- package/dist/form-dialog.js +3 -2
- package/dist/frame.d.ts +8 -4
- package/dist/frame.js +16 -6
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -2
- package/dist/list-chrome/es-ES.d.ts +1 -1
- package/dist/list-chrome/es-ES.js +11 -8
- package/dist/list-chrome/fr-FR.d.ts +1 -1
- package/dist/list-chrome/fr-FR.js +9 -1
- package/dist/navigation-item.d.ts +4 -2
- package/dist/navigation-item.js +2 -2
- package/dist/navigation-screen.js +10 -3
- package/dist/navigation.js +5 -1
- package/dist/page.d.ts +3 -2
- package/dist/page.js +23 -4
- package/dist/rejected-field.d.ts +25 -0
- package/dist/rejected-field.js +121 -0
- package/dist/rename-dialog.d.ts +2 -2
- package/dist/rename-dialog.js +1 -1
- package/dist/route-not-found.d.ts +5 -0
- package/dist/route-not-found.js +12 -0
- package/dist/router.d.ts +8 -2
- package/dist/router.js +10 -2
- package/dist/screen-title.d.ts +52 -0
- package/dist/screen-title.js +165 -0
- package/dist/stylelint.d.ts +1 -4
- package/dist/stylelint.js +4 -7
- package/dist/testing.d.ts +2 -2
- package/dist/testing.js +3 -3
- package/dist/vite.js +1 -0
- package/docs/build-and-versioning.md +109 -4
- package/docs/design-system/accessibility.md +18 -9
- package/docs/design-system/color.md +1 -1
- package/docs/design-system/custom-properties.md +3 -3
- package/docs/design-system/dialogs.md +71 -9
- package/docs/design-system/frame.md +276 -0
- package/docs/design-system/layout.md +24 -16
- package/docs/design-system/lists.md +17 -11
- package/docs/design-system/loading.md +20 -12
- package/docs/design-system/motion.md +41 -47
- package/docs/design-system/overview.md +8 -3
- package/docs/design-system/radius-and-elevation.md +2 -2
- package/docs/design-system/record-pages.md +9 -1
- package/docs/design-system/toasts.md +7 -1
- package/docs/framing-an-application.md +77 -23
- package/docs/lists.md +80 -39
- package/docs/overview.md +9 -3
- package/docs/screens.md +94 -3
- package/docs/testing.md +29 -0
- package/package.json +27 -19
|
@@ -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
|
+
}
|
package/dist/rename-dialog.d.ts
CHANGED
|
@@ -11,8 +11,8 @@ export interface RenameDialogProps {
|
|
|
11
11
|
submitLabel: string;
|
|
12
12
|
/** The label of the button that closes the dialog. */
|
|
13
13
|
cancelLabel: string;
|
|
14
|
-
/** Writes the name
|
|
15
|
-
onSubmit: (name: string) => void | DialogAnswer | PromiseLike<unknown>;
|
|
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
16
|
/** Takes the dialog away, once its card has left the page. */
|
|
17
17
|
onClose: () => void;
|
|
18
18
|
}
|
package/dist/rename-dialog.js
CHANGED
|
@@ -12,5 +12,5 @@ const NOT_ONLY_SPACES = '.*\\S.*';
|
|
|
12
12
|
*/
|
|
13
13
|
export function RenameDialog({ title, name, fieldLabel, submitLabel, cancelLabel, onSubmit, onClose, }) {
|
|
14
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) })) }));
|
|
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
16
|
}
|
|
@@ -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';
|
|
@@ -33,10 +33,16 @@ export declare function useCanvas(): CanvasMode;
|
|
|
33
33
|
* @returns The pathname of the active location followed by its search.
|
|
34
34
|
*/
|
|
35
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;
|
|
36
41
|
/**
|
|
37
42
|
* Returns the options a router spreads into createRouter, as WordPress's new admin sets them.
|
|
38
|
-
* @returns Preload on intent, and no pending screen.
|
|
43
|
+
* @returns Preload on intent and the Route not found screen, and no pending screen.
|
|
39
44
|
*/
|
|
40
45
|
export declare function routerDefaults(): {
|
|
41
46
|
defaultPreload: 'intent';
|
|
47
|
+
defaultNotFoundComponent: () => ReactNode;
|
|
42
48
|
};
|
package/dist/router.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
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';
|
|
@@ -26,10 +27,17 @@ export function useCanvas() {
|
|
|
26
27
|
export function useFrameLocation() {
|
|
27
28
|
return useRouterState({ select: (state) => locationAddress(state.location) });
|
|
28
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
|
+
}
|
|
29
37
|
/**
|
|
30
38
|
* Returns the options a router spreads into createRouter, as WordPress's new admin sets them.
|
|
31
|
-
* @returns Preload on intent, and no pending screen.
|
|
39
|
+
* @returns Preload on intent and the Route not found screen, and no pending screen.
|
|
32
40
|
*/
|
|
33
41
|
export function routerDefaults() {
|
|
34
|
-
return { defaultPreload: 'intent' };
|
|
42
|
+
return { defaultPreload: 'intent', defaultNotFoundComponent: RouteNotFound };
|
|
35
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
|
+
}
|
package/dist/stylelint.d.ts
CHANGED
|
@@ -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,
|
|
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,
|
|
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/vite.js
CHANGED
|
@@ -33,6 +33,10 @@ hook. Two copies of these fail with no error:
|
|
|
33
33
|
[configured transport](https://docs.gopherium.org/authentication/react-integration/#one-setting-for-the-whole-module)
|
|
34
34
|
that half the app cannot see.
|
|
35
35
|
|
|
36
|
+
`godminDedupe` lists godmin itself too, since two workspace packages
|
|
37
|
+
of your app can install it twice, and a `useToaster` in one copy then
|
|
38
|
+
finds no `Toaster` from the other.
|
|
39
|
+
|
|
36
40
|
The config handles this twice:
|
|
37
41
|
|
|
38
42
|
- `godminDedupe` makes Vite resolve each listed package once.
|
|
@@ -50,13 +54,19 @@ In one app with eight preloads it cut the blank page from 1.9s to
|
|
|
50
54
|
nothing was queueing. It costs nothing at runtime, so leave it on
|
|
51
55
|
and let it matter as your bundle grows.
|
|
52
56
|
|
|
57
|
+
godmin marks only its stylesheets as having side effects, so your
|
|
58
|
+
bundler leaves out every part you do not import, such as the dialogs
|
|
59
|
+
on a screen that opens none.
|
|
60
|
+
|
|
53
61
|
On a bundler that is not Vite or Rollup, the underlying functions
|
|
54
62
|
`duplicateCopies` and `hoistStylesheet` are exported so you can wire
|
|
55
63
|
both checks into whatever hooks it offers.
|
|
56
64
|
|
|
57
65
|
## Lint your stylesheets
|
|
58
66
|
|
|
59
|
-
`@wordpress/theme` ships three stylelint rules.
|
|
67
|
+
`@wordpress/theme-build-tools` ships three stylelint rules. Add it
|
|
68
|
+
to your `devDependencies`, next to `stylelint`. Then this turns the
|
|
69
|
+
rules on:
|
|
60
70
|
|
|
61
71
|
```js
|
|
62
72
|
export default { extends: ['@gopherium/godmin/stylelint'] }
|
|
@@ -64,13 +74,14 @@ export default { extends: ['@gopherium/godmin/stylelint'] }
|
|
|
64
74
|
|
|
65
75
|
They catch design tokens that do not exist (a typo renders nothing,
|
|
66
76
|
with no error), redefined `--wpds-` properties, and hand-typed
|
|
67
|
-
fallback values.
|
|
77
|
+
fallback values. The rule on tokens that do not exist reads its list
|
|
78
|
+
from the `@wordpress/theme` your app installs.
|
|
68
79
|
|
|
69
80
|
## Design system versions
|
|
70
81
|
|
|
71
82
|
Each godmin release supports one design system window, written out
|
|
72
83
|
in full in its peer ranges as the first version it accepts and the
|
|
73
|
-
first one it
|
|
84
|
+
first one it rejects, such as `>=0.26.0 <0.27.0`. The window moves
|
|
74
85
|
forward with the design system and never widens, so no release
|
|
75
86
|
accepts two incompatible generations at once.
|
|
76
87
|
|
|
@@ -91,11 +102,105 @@ needed only by `@gopherium/godmin/dates`. Install it next to godmin
|
|
|
91
102
|
when you use that entry. Its window is in the same peer ranges.
|
|
92
103
|
godmin never imports `@wordpress/components`.
|
|
93
104
|
|
|
105
|
+
`@wordpress/theme-build-tools` is an optional peer too, needed only
|
|
106
|
+
by `@gopherium/godmin/stylelint`. Its window is in the same peer
|
|
107
|
+
ranges.
|
|
108
|
+
|
|
94
109
|
`@wordpress/dataviews` is an optional peer as well, in the window
|
|
95
|
-
`>=
|
|
110
|
+
`>=22.0.0 <23.0.0`. No godmin entry imports it, but `offeredView`
|
|
96
111
|
follows the filter rules of that DataViews release. A list built on
|
|
97
112
|
another release gets a peer warning when it installs godmin.
|
|
98
113
|
|
|
114
|
+
## Upgrading from godmin 0.32.0
|
|
115
|
+
|
|
116
|
+
godmin 0.33.0 gives the write a busy dialog waits on a time limit, and
|
|
117
|
+
moves to the WordPress packages of 4 November. Change your code in
|
|
118
|
+
these places:
|
|
119
|
+
|
|
120
|
+
- `AdminRoot` takes a required `writeTimeout`, how long in
|
|
121
|
+
milliseconds a busy dialog waits on its write before it gives up.
|
|
122
|
+
Read it from your app's own settings and pass it where you render
|
|
123
|
+
`AdminRoot`, such as
|
|
124
|
+
`<AdminRoot writeTimeout={settings.writeTimeout}>`. godmin sets no
|
|
125
|
+
limit of its own. Pass `Infinity` for no limit. The value may change
|
|
126
|
+
after the first render, such as `Infinity` while your settings still
|
|
127
|
+
load, and each write takes the value in force when it starts. 0, a
|
|
128
|
+
negative number, `NaN` or more than 2147483647 makes `AdminRoot`
|
|
129
|
+
throw as it renders. Once a write runs past it, the dialog stops
|
|
130
|
+
waiting, shows WordPress's words for a write with no answer and
|
|
131
|
+
frees Cancel, the close icon and Escape, as
|
|
132
|
+
[while a write runs](./design-system/dialogs.md#while-a-write-runs)
|
|
133
|
+
says.
|
|
134
|
+
- `onConfirm` and `onSubmit` get an `AbortSignal` as their last
|
|
135
|
+
argument, and the `onSubmit` of `RenameDialog` gets it after the
|
|
136
|
+
name. It fires once the limit runs out. Pass it to the write the
|
|
137
|
+
dialog waits on, such as `fetch(url, { signal })`, so the request
|
|
138
|
+
stops too. The server may still finish a write it already received,
|
|
139
|
+
so make a write safe to send twice. A wrapper around your writes
|
|
140
|
+
that turns a failure into `{ error }` shows its own words even when
|
|
141
|
+
the limit ran out. Have it reject once `signal.aborted` is true, so
|
|
142
|
+
the dialog shows WordPress's words for the time-out. A wrapper that
|
|
143
|
+
rejects gets them already.
|
|
144
|
+
- The write that `useDialogRun` hands out takes the dialog's signal as
|
|
145
|
+
its fourth argument, as `write(items, call, words, signal)`. A call
|
|
146
|
+
still running when the signal fires counts as failed. The run does
|
|
147
|
+
not hand the signal to `call`, so pass it on to each write yourself.
|
|
148
|
+
- `renderAdmin` from `@gopherium/godmin/testing` takes `writeTimeout`
|
|
149
|
+
too, and sets no limit when you leave it out. A test harness of your
|
|
150
|
+
own that renders `AdminRoot` passes one.
|
|
151
|
+
- A test that waits on a write that never ends, such as to read a busy
|
|
152
|
+
dialog, now meets the time-out once the limit runs out. The words
|
|
153
|
+
show, and Escape and Cancel close the dialog again. Leave
|
|
154
|
+
`writeTimeout` out of `renderAdmin`, give your own harness a limit
|
|
155
|
+
longer than the test, or read the busy dialog before the limit runs
|
|
156
|
+
out. A test on fake timers that moves its clock past the limit meets
|
|
157
|
+
the time-out too.
|
|
158
|
+
- Move the `@wordpress` packages your app installs to the releases of
|
|
159
|
+
4 November: `@wordpress/dataviews` 22, `@wordpress/icons` 20,
|
|
160
|
+
`@wordpress/style-runtime` 0.15, `@wordpress/theme` 4 and
|
|
161
|
+
`@wordpress/ui` 0.26. Move `@wordpress/a11y` to 5.1 or later,
|
|
162
|
+
`@wordpress/date` to 6.1 or later and `@wordpress/i18n` to 7.1 or
|
|
163
|
+
later too, since DataViews 22 and ui 0.26 ask for them.
|
|
164
|
+
[Design system versions](#design-system-versions) gives each window.
|
|
165
|
+
DataViews 22 asks for an action label with no ellipsis, so write
|
|
166
|
+
"Delete" in place of "Delete…".
|
|
167
|
+
- DataViews 22 changes what a test of a list meets. The bulk actions
|
|
168
|
+
sit in `.dataviews-bulk-actions__actions`, and at 782px and below
|
|
169
|
+
they all move into an Actions menu. Sort by is no longer a native
|
|
170
|
+
`select`, and ArrowDown opens its list. The count reads "1 item
|
|
171
|
+
selected", in lowercase. A row checkbox is a `span` with the
|
|
172
|
+
checkbox role, so read its `aria-checked`, not `checked`. An idle
|
|
173
|
+
bulk button carries `aria-disabled="false"`, and the spinner draws
|
|
174
|
+
on a 24 `viewBox`. On screen, the footer drops its select all
|
|
175
|
+
checkbox and reads "N items", or "20 of 45 items" when the list has
|
|
176
|
+
more than one page. A grid gains a Select all row above its cards,
|
|
177
|
+
and the checkbox of a row that takes no bulk action no longer looks
|
|
178
|
+
greyed out. godmin keeps each of these as WordPress draws it.
|
|
179
|
+
- `@gopherium/godmin/stylelint` loads its rules from
|
|
180
|
+
`@wordpress/theme-build-tools`, a new optional peer. Add it to your
|
|
181
|
+
`devDependencies`, next to `stylelint`, as
|
|
182
|
+
[lint your stylesheets](#lint-your-stylesheets) shows.
|
|
183
|
+
- `@wordpress/theme` 4 no longer exports its Vite plugin. An app that
|
|
184
|
+
imports `vite-ds-token-fallbacks` from `@wordpress/theme` imports it
|
|
185
|
+
from `@wordpress/theme-build-tools/vite-plugins/vite-ds-token-fallbacks`
|
|
186
|
+
now, with `@wordpress/theme-build-tools` in its `devDependencies`.
|
|
187
|
+
The old path stops the build.
|
|
188
|
+
- `DrilldownItem` no longer takes `activeProps` or `activeOptions`,
|
|
189
|
+
since a drilldown row is never current. Drop them. A row that points
|
|
190
|
+
at the sub menu already shown is a `NavigationItem`, as
|
|
191
|
+
[sub menus](./framing-an-application.md#sub-menus) says.
|
|
192
|
+
- Back draws its chevron in place of anything inside the `back` link
|
|
193
|
+
you pass, so drop any icon or words you put there. Name it with
|
|
194
|
+
`backLabel`, or with an `aria-label` on the link, as
|
|
195
|
+
[`NavigationScreen`](./screens.md#navigationscreen) says.
|
|
196
|
+
|
|
197
|
+
TypeScript points at each `AdminRoot` without `writeTimeout`, each
|
|
198
|
+
`write` of `useDialogRun` with three arguments, and each `activeProps`
|
|
199
|
+
or `activeOptions` on a `DrilldownItem`. A handler that takes no
|
|
200
|
+
signal still type checks, so find each write a dialog waits on
|
|
201
|
+
yourself. The rest changes what the reader sees, what a test meets and
|
|
202
|
+
what your app installs.
|
|
203
|
+
|
|
99
204
|
## Upgrading from godmin 0.31.0
|
|
100
205
|
|
|
101
206
|
godmin 0.32.0 draws `ConfirmDialog` on the alert dialog of the design
|