@gopherium/godmin 0.32.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +19 -9
  2. package/dist/admin-root.d.ts +4 -2
  3. package/dist/admin-root.js +6 -3
  4. package/dist/announcer-heading.d.ts +4 -0
  5. package/dist/announcer-heading.js +25 -0
  6. package/dist/base.css +36 -4
  7. package/dist/bulk-run.d.ts +2 -2
  8. package/dist/bulk-run.js +18 -2
  9. package/dist/confirm-dialog.d.ts +2 -2
  10. package/dist/confirm-dialog.js +3 -2
  11. package/dist/dialog-open.d.ts +16 -2
  12. package/dist/dialog-open.js +126 -5
  13. package/dist/drilldown-item.d.ts +5 -2
  14. package/dist/drilldown-item.js +14 -2
  15. package/dist/filter-offer.d.ts +5 -5
  16. package/dist/filter-offer.js +9 -9
  17. package/dist/focus-back.js +12 -2
  18. package/dist/form-dialog.d.ts +2 -2
  19. package/dist/form-dialog.js +3 -2
  20. package/dist/frame.d.ts +8 -4
  21. package/dist/frame.js +16 -6
  22. package/dist/index.d.ts +4 -2
  23. package/dist/index.js +3 -2
  24. package/dist/list-chrome/es-ES.d.ts +1 -1
  25. package/dist/list-chrome/es-ES.js +11 -8
  26. package/dist/list-chrome/fr-FR.d.ts +1 -1
  27. package/dist/list-chrome/fr-FR.js +9 -1
  28. package/dist/navigation-item.d.ts +4 -2
  29. package/dist/navigation-item.js +2 -2
  30. package/dist/navigation-screen.js +10 -3
  31. package/dist/navigation.js +5 -1
  32. package/dist/page.d.ts +3 -2
  33. package/dist/page.js +23 -4
  34. package/dist/rejected-field.d.ts +25 -0
  35. package/dist/rejected-field.js +121 -0
  36. package/dist/rename-dialog.d.ts +2 -2
  37. package/dist/rename-dialog.js +1 -1
  38. package/dist/route-not-found.d.ts +5 -0
  39. package/dist/route-not-found.js +12 -0
  40. package/dist/router.d.ts +8 -2
  41. package/dist/router.js +10 -2
  42. package/dist/screen-title.d.ts +52 -0
  43. package/dist/screen-title.js +165 -0
  44. package/dist/stylelint.d.ts +1 -4
  45. package/dist/stylelint.js +4 -7
  46. package/dist/testing.d.ts +2 -2
  47. package/dist/testing.js +3 -3
  48. package/dist/vite.js +1 -0
  49. package/docs/build-and-versioning.md +109 -4
  50. package/docs/design-system/accessibility.md +18 -9
  51. package/docs/design-system/color.md +1 -1
  52. package/docs/design-system/custom-properties.md +3 -3
  53. package/docs/design-system/dialogs.md +71 -9
  54. package/docs/design-system/frame.md +276 -0
  55. package/docs/design-system/layout.md +24 -16
  56. package/docs/design-system/lists.md +17 -11
  57. package/docs/design-system/loading.md +20 -12
  58. package/docs/design-system/motion.md +41 -47
  59. package/docs/design-system/overview.md +8 -3
  60. package/docs/design-system/radius-and-elevation.md +2 -2
  61. package/docs/design-system/record-pages.md +9 -1
  62. package/docs/design-system/toasts.md +7 -1
  63. package/docs/framing-an-application.md +77 -23
  64. package/docs/lists.md +80 -39
  65. package/docs/overview.md +9 -3
  66. package/docs/screens.md +94 -3
  67. package/docs/testing.md +29 -0
  68. package/package.json +27 -19
@@ -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
+ }
@@ -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 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>;
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
  }
@@ -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,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';
@@ -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
+ }
@@ -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/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.
@@ -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. This turns them on:
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 refuses, such as `>=0.25.0 <0.26.0`. The window moves
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
- `>=21.0.0 <22.0.0`. No godmin entry imports it, but `offeredView`
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