@gopherium/godmin 0.26.0 → 0.28.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 +8 -19
- package/dist/base.css +49 -30
- package/dist/close-while-open.d.ts +6 -0
- package/dist/close-while-open.js +21 -0
- package/dist/focus-back.d.ts +25 -0
- package/dist/focus-back.js +125 -0
- package/dist/index.d.ts +9 -1
- package/dist/index.js +5 -1
- package/dist/list-run.d.ts +7 -2
- package/dist/list-run.js +64 -2
- package/dist/list-view.d.ts +1 -7
- package/dist/list-view.js +1 -16
- package/dist/open-on-tap.d.ts +14 -0
- package/dist/open-on-tap.js +17 -0
- package/dist/run-confirm.d.ts +1 -1
- package/dist/run-confirm.js +4 -2
- package/dist/toaster.d.ts +7 -9
- package/dist/toaster.js +41 -53
- package/dist/unsaved-text.d.ts +14 -0
- package/dist/unsaved-text.js +25 -0
- package/docs/build-and-versioning.md +219 -0
- package/docs/design-system/accessibility.md +200 -0
- package/docs/design-system/color.md +74 -0
- package/docs/design-system/custom-properties.md +60 -0
- package/docs/design-system/layout.md +157 -0
- package/docs/design-system/motion.md +121 -0
- package/docs/design-system/overview.md +107 -0
- package/docs/design-system/radius-and-elevation.md +135 -0
- package/docs/design-system/toasts.md +187 -0
- package/docs/design-system/typography.md +83 -0
- package/docs/framing-an-application.md +386 -0
- package/docs/lists.md +1495 -0
- package/docs/loading-and-feedback.md +165 -0
- package/docs/overview.md +159 -0
- package/docs/screens.md +419 -0
- package/docs/testing.md +193 -0
- package/package.json +6 -1
package/dist/run-confirm.js
CHANGED
|
@@ -1,21 +1,23 @@
|
|
|
1
1
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
2
|
// SPDX-License-Identifier: Apache-2.0
|
|
3
3
|
import { useState } from 'react';
|
|
4
|
+
import { useCloseWhileOpen } from './close-while-open.js';
|
|
4
5
|
import { ConfirmBody } from './confirm.js';
|
|
5
6
|
/**
|
|
6
|
-
* Renders a confirmation that runs the action, keeps Cancel inert while it runs and closes once it settles.
|
|
7
|
+
* Renders a confirmation that runs the action, keeps Cancel inert while it runs and closes only itself once it settles.
|
|
7
8
|
* @param props - The items, the close handler, the question, the labels and the run.
|
|
8
9
|
* @returns The confirmation body.
|
|
9
10
|
*/
|
|
10
11
|
export function RunConfirm({ items, closeModal, children, confirmLabel, cancelLabel, run, }) {
|
|
11
12
|
const [busy, setBusy] = useState(false);
|
|
13
|
+
const close = useCloseWhileOpen(closeModal);
|
|
12
14
|
return (_jsx(ConfirmBody, { confirmLabel: confirmLabel, cancelLabel: cancelLabel, busy: busy, onCancel: closeModal, onConfirm: () => {
|
|
13
15
|
setBusy(true);
|
|
14
16
|
void Promise.resolve()
|
|
15
17
|
.then(() => run(items))
|
|
16
18
|
.finally(() => {
|
|
17
19
|
setBusy(false);
|
|
18
|
-
|
|
20
|
+
close();
|
|
19
21
|
});
|
|
20
22
|
}, children: children }));
|
|
21
23
|
}
|
package/dist/toaster.d.ts
CHANGED
|
@@ -5,8 +5,6 @@ export interface ToastAction {
|
|
|
5
5
|
}
|
|
6
6
|
export interface ToasterHandle {
|
|
7
7
|
show: (message: string, action?: ToastAction) => void;
|
|
8
|
-
/** The title cut to the toaster's name length, with an ellipsis when cut. */
|
|
9
|
-
name: (title: string) => string;
|
|
10
8
|
}
|
|
11
9
|
/**
|
|
12
10
|
* Returns the handle raising messages in the toast region.
|
|
@@ -16,18 +14,18 @@ export declare function useToaster(): ToasterHandle;
|
|
|
16
14
|
export interface ToasterProps {
|
|
17
15
|
/** The tree the toast region wraps. */
|
|
18
16
|
children: ReactNode;
|
|
19
|
-
/** How many milliseconds a toast
|
|
17
|
+
/** How many milliseconds a toast with no action stays on screen when nobody touches it. */
|
|
20
18
|
dismissAfter?: number;
|
|
21
|
-
/**
|
|
19
|
+
/** How many milliseconds a toast with an action stays on screen when nobody touches it. */
|
|
20
|
+
actionDismissAfter?: number;
|
|
21
|
+
/** The hint screen readers hear after the message of a plain toast, that a click clears it. */
|
|
22
22
|
dismissLabel?: string;
|
|
23
23
|
/** How many toasts stay on screen at once, the oldest leaving first. */
|
|
24
24
|
limit?: number;
|
|
25
|
-
/** How many characters of a name a toast shows before the ellipsis. */
|
|
26
|
-
nameLength?: number;
|
|
27
25
|
}
|
|
28
26
|
/**
|
|
29
|
-
* Renders the region holding raised messages around the given tree.
|
|
30
|
-
* @param props - The tree the region wraps, the
|
|
27
|
+
* Renders the region holding raised messages around the given tree, under the snackbar corners at every preset.
|
|
28
|
+
* @param props - The tree the region wraps, the time of each kind of toast, the plain toast hint and how many stay.
|
|
31
29
|
* @returns The wrapped tree with its region.
|
|
32
30
|
*/
|
|
33
|
-
export declare function Toaster({ children, dismissAfter, dismissLabel, limit,
|
|
31
|
+
export declare function Toaster({ children, dismissAfter, actionDismissAfter, dismissLabel, limit, }: ToasterProps): import("react").JSX.Element;
|
package/dist/toaster.js
CHANGED
|
@@ -2,45 +2,24 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
|
2
2
|
/* oxlint-disable react/only-export-components -- the region ships beside the
|
|
3
3
|
hook that reaches it. */
|
|
4
4
|
import { speak } from '@wordpress/a11y';
|
|
5
|
+
import { ThemeProvider } from '@wordpress/theme';
|
|
5
6
|
import { createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, } from 'react';
|
|
6
7
|
/**
|
|
7
|
-
* How long a toast
|
|
8
|
+
* How long a toast with no action stays on screen when nobody touches it.
|
|
8
9
|
*/
|
|
9
10
|
const DISMISS_AFTER = 6000;
|
|
10
11
|
/**
|
|
11
|
-
*
|
|
12
|
+
* How long a toast with an action stays on screen when nobody touches it, time to read it and then act.
|
|
12
13
|
*/
|
|
13
|
-
const
|
|
14
|
+
const ACTION_DISMISS_AFTER = 10000;
|
|
14
15
|
/**
|
|
15
|
-
* The
|
|
16
|
+
* The hint telling a screen reader that a click clears a plain toast.
|
|
16
17
|
*/
|
|
17
|
-
const
|
|
18
|
+
const DISMISS_LABEL = 'Dismiss this notice';
|
|
18
19
|
/**
|
|
19
20
|
* How many toasts stay on screen at once.
|
|
20
21
|
*/
|
|
21
22
|
const LIMIT = 3;
|
|
22
|
-
/**
|
|
23
|
-
* How many characters of a name a toast shows before the ellipsis.
|
|
24
|
-
*/
|
|
25
|
-
const NAME_LENGTH = 45;
|
|
26
|
-
/**
|
|
27
|
-
* The mark that ends a name a toast cut short.
|
|
28
|
-
*/
|
|
29
|
-
const ELLIPSIS = '…';
|
|
30
|
-
/**
|
|
31
|
-
* Returns a title cut to the given number of characters, its trailing spaces trimmed and an ellipsis added.
|
|
32
|
-
* @param title - The title to name.
|
|
33
|
-
* @param length - How many characters to keep.
|
|
34
|
-
* @returns The title whole when it fits, the cut title otherwise.
|
|
35
|
-
*/
|
|
36
|
-
function cutName(title, length) {
|
|
37
|
-
const characters = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
|
|
38
|
-
const parts = Array.from(characters.segment(title), (part) => part.segment);
|
|
39
|
-
if (parts.length <= length) {
|
|
40
|
-
return title;
|
|
41
|
-
}
|
|
42
|
-
return `${parts.slice(0, length).join('').trimEnd()}${ELLIPSIS}`;
|
|
43
|
-
}
|
|
44
23
|
const ToasterContext = createContext(null);
|
|
45
24
|
/**
|
|
46
25
|
* Returns the handle raising messages in the toast region.
|
|
@@ -66,23 +45,25 @@ function admit(held, arriving, limit) {
|
|
|
66
45
|
return [...held.map((toast) => (pushed.has(toast.id) ? { ...toast, leaving: true } : toast)), arriving];
|
|
67
46
|
}
|
|
68
47
|
/**
|
|
69
|
-
* Returns the
|
|
48
|
+
* Returns the animations running on an element and inside it, none where the browser cannot report them.
|
|
70
49
|
* @param element - The element to ask.
|
|
71
50
|
* @returns The running animations.
|
|
72
51
|
*/
|
|
73
|
-
function
|
|
74
|
-
return typeof element.getAnimations === 'function' ? element.getAnimations() : [];
|
|
52
|
+
function runningMotion(element) {
|
|
53
|
+
return typeof element.getAnimations === 'function' ? element.getAnimations({ subtree: true }) : [];
|
|
75
54
|
}
|
|
76
55
|
/**
|
|
77
|
-
* Returns the ref of a toast
|
|
78
|
-
*
|
|
56
|
+
* Returns the ref of a toast item that gives up focus as the toast leaves and drops the toast once its motion ends,
|
|
57
|
+
* or at once when the toast was already leaving as it first showed.
|
|
58
|
+
* @param toast - The toast the item holds.
|
|
79
59
|
* @param region - The toast region taking the focus a leaving toast held.
|
|
80
60
|
* @param onGone - The handler dropping a toast that finished leaving.
|
|
81
|
-
* @returns The ref to attach to the
|
|
61
|
+
* @returns The ref to attach to the item element.
|
|
82
62
|
*/
|
|
83
63
|
function useDeparture(toast, region, onGone) {
|
|
84
64
|
const ref = useRef(null);
|
|
85
65
|
const { id, leaving } = toast;
|
|
66
|
+
const leavingAtMount = useRef(leaving);
|
|
86
67
|
useLayoutEffect(() => {
|
|
87
68
|
if (!leaving) {
|
|
88
69
|
return;
|
|
@@ -92,12 +73,12 @@ function useDeparture(toast, region, onGone) {
|
|
|
92
73
|
if (element.contains(document.activeElement)) {
|
|
93
74
|
holder.focus();
|
|
94
75
|
}
|
|
95
|
-
const
|
|
96
|
-
if (
|
|
76
|
+
const motion = leavingAtMount.current ? [] : runningMotion(element);
|
|
77
|
+
if (motion.length === 0) {
|
|
97
78
|
onGone(id);
|
|
98
79
|
return;
|
|
99
80
|
}
|
|
100
|
-
Promise.allSettled(
|
|
81
|
+
Promise.allSettled(motion.map((animation) => animation.finished)).then(() => onGone(id));
|
|
101
82
|
}, [id, leaving, region, onGone]);
|
|
102
83
|
return ref;
|
|
103
84
|
}
|
|
@@ -126,35 +107,43 @@ function useExpiry(toast, dismissAfter, onLeave) {
|
|
|
126
107
|
function toastClass(base, leaving) {
|
|
127
108
|
return leaving ? `${base} godmin-toast--leaving` : base;
|
|
128
109
|
}
|
|
110
|
+
/**
|
|
111
|
+
* Renders the item that holds a toast in the region, its space growing as the toast arrives and closing once it left.
|
|
112
|
+
* @param props - The toast, the region, the handler dropping a toast that finished leaving, and the toast element.
|
|
113
|
+
* @returns The item element.
|
|
114
|
+
*/
|
|
115
|
+
function ToastItem({ toast, region, onGone, children }) {
|
|
116
|
+
const ref = useDeparture(toast, region, onGone);
|
|
117
|
+
const item = toast.leaving ? 'godmin-toasts__item godmin-toasts__item--leaving' : 'godmin-toasts__item';
|
|
118
|
+
return (_jsx("div", { ref: ref, className: item, children: _jsx("div", { className: "godmin-toasts__item-inner", children: children }) }));
|
|
119
|
+
}
|
|
129
120
|
/**
|
|
130
121
|
* Renders a toast with no action as one button that clears it, described by the dismiss hint.
|
|
131
|
-
* @param props - The toast, how long it stays, the id of the dismiss hint
|
|
122
|
+
* @param props - The toast, how long it stays, the id of the dismiss hint and the handler clearing it.
|
|
132
123
|
* @returns The toast element.
|
|
133
124
|
*/
|
|
134
|
-
function PlainToast({ toast, dismissAfter, hint,
|
|
125
|
+
function PlainToast({ toast, dismissAfter, hint, onLeave }) {
|
|
135
126
|
useExpiry(toast, dismissAfter, onLeave);
|
|
136
|
-
|
|
137
|
-
return (_jsx("button", { ref: ref, type: "button", className: toastClass('godmin-toast godmin-toast--plain', toast.leaving), "aria-describedby": hint, inert: toast.leaving, onClick: () => onLeave(toast.id), children: toast.message }));
|
|
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 }));
|
|
138
128
|
}
|
|
139
129
|
/**
|
|
140
|
-
* Renders a toast with its action
|
|
141
|
-
* @param props - The toast, its action, its time
|
|
130
|
+
* Renders a toast with its action, cleared by a click anywhere on it, the action its only control.
|
|
131
|
+
* @param props - The toast, its action, its time and the handler clearing it.
|
|
142
132
|
* @returns The toast element.
|
|
143
133
|
*/
|
|
144
|
-
function ActionToast({ toast, action, dismissAfter,
|
|
134
|
+
function ActionToast({ toast, action, dismissAfter, onLeave }) {
|
|
145
135
|
useExpiry(toast, dismissAfter, onLeave);
|
|
146
|
-
|
|
147
|
-
return (_jsxs("div", { ref: ref, className: toastClass('godmin-toast', toast.leaving), inert: toast.leaving, children: [_jsx("span", { className: "godmin-toast__message", children: toast.message }), _jsx("button", { type: "button", className: "godmin-toast__action", onClick: () => {
|
|
148
|
-
action.onAct();
|
|
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: () => {
|
|
149
137
|
onLeave(toast.id);
|
|
150
|
-
|
|
138
|
+
action.onAct();
|
|
139
|
+
}, children: action.label })] }));
|
|
151
140
|
}
|
|
152
141
|
/**
|
|
153
|
-
* Renders the region holding raised messages around the given tree.
|
|
154
|
-
* @param props - The tree the region wraps, the
|
|
142
|
+
* Renders the region holding raised messages around the given tree, under the snackbar corners at every preset.
|
|
143
|
+
* @param props - The tree the region wraps, the time of each kind of toast, the plain toast hint and how many stay.
|
|
155
144
|
* @returns The wrapped tree with its region.
|
|
156
145
|
*/
|
|
157
|
-
export function Toaster({ children, dismissAfter = DISMISS_AFTER,
|
|
146
|
+
export function Toaster({ children, dismissAfter = DISMISS_AFTER, actionDismissAfter = ACTION_DISMISS_AFTER, dismissLabel = DISMISS_LABEL, limit = LIMIT, }) {
|
|
158
147
|
const [toasts, setToasts] = useState([]);
|
|
159
148
|
const nextId = useRef(0);
|
|
160
149
|
const region = useRef(null);
|
|
@@ -180,8 +169,7 @@ export function Toaster({ children, dismissAfter = DISMISS_AFTER, dismissLabel =
|
|
|
180
169
|
speak(message, 'polite');
|
|
181
170
|
setToasts((held) => admit(held, { id, message, action, leaving: false }, limit));
|
|
182
171
|
}, [limit]);
|
|
183
|
-
const
|
|
184
|
-
const handle = useMemo(() => ({ show, name }), [show, name]);
|
|
172
|
+
const handle = useMemo(() => ({ show }), [show]);
|
|
185
173
|
const hint = useId();
|
|
186
|
-
return (_jsxs(ToasterContext.Provider, { value: handle, children: [children, _jsx("div", { ref: region, className: "godmin-toasts", tabIndex: -1, children: toasts.map((toast) => toast.action === undefined ? (_jsx(PlainToast, { toast: toast, dismissAfter: dismissAfter, hint: hint,
|
|
174
|
+
return (_jsxs(ToasterContext.Provider, { value: handle, children: [children, _jsx(ThemeProvider, { cornerRadius: "subtle", children: _jsx("div", { ref: region, className: "godmin-toasts", tabIndex: -1, children: toasts.map((toast) => (_jsx(ToastItem, { toast: toast, region: region, onGone: gone, children: toast.action === undefined ? (_jsx(PlainToast, { toast: toast, dismissAfter: dismissAfter, hint: hint, onLeave: leave })) : (_jsx(ActionToast, { toast: toast, action: toast.action, dismissAfter: actionDismissAfter, onLeave: leave })) }, toast.id))) }) }), _jsx("span", { id: hint, hidden: true, children: dismissLabel })] }));
|
|
187
175
|
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/** What a failed write left unsaved, by the id of the item it was typed for, the text of one field unless named. */
|
|
2
|
+
export type UnsavedText<Value = string> = Map<string, Value>;
|
|
3
|
+
/**
|
|
4
|
+
* Returns what failed writes left unsaved, the same store for as long as the screen stays.
|
|
5
|
+
* @returns The store a row form takes its first value from when it opens again.
|
|
6
|
+
*/
|
|
7
|
+
export declare function useUnsavedText<Value = string>(): UnsavedText<Value>;
|
|
8
|
+
/**
|
|
9
|
+
* Marks a write as the latest one sent for an item, the only one that may keep its text.
|
|
10
|
+
* @param unsaved - The store the latest writes of the item are marked on.
|
|
11
|
+
* @param id - The item the write goes to.
|
|
12
|
+
* @returns The check telling whether no later write went to the item since.
|
|
13
|
+
*/
|
|
14
|
+
export declare function markLatest(unsaved: UnsavedText<unknown>, id: string): () => boolean;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { useState } from 'react';
|
|
3
|
+
/**
|
|
4
|
+
* Returns what failed writes left unsaved, the same store for as long as the screen stays.
|
|
5
|
+
* @returns The store a row form takes its first value from when it opens again.
|
|
6
|
+
*/
|
|
7
|
+
export function useUnsavedText() {
|
|
8
|
+
const [held] = useState(() => new Map());
|
|
9
|
+
return held;
|
|
10
|
+
}
|
|
11
|
+
/** The latest write each store sent, by the id of the item it went to. */
|
|
12
|
+
const latestWrites = new WeakMap();
|
|
13
|
+
/**
|
|
14
|
+
* Marks a write as the latest one sent for an item, the only one that may keep its text.
|
|
15
|
+
* @param unsaved - The store the latest writes of the item are marked on.
|
|
16
|
+
* @param id - The item the write goes to.
|
|
17
|
+
* @returns The check telling whether no later write went to the item since.
|
|
18
|
+
*/
|
|
19
|
+
export function markLatest(unsaved, id) {
|
|
20
|
+
const writes = latestWrites.get(unsaved) ?? new Map();
|
|
21
|
+
latestWrites.set(unsaved, writes);
|
|
22
|
+
const write = Symbol(id);
|
|
23
|
+
writes.set(id, write);
|
|
24
|
+
return () => writes.get(id) === write;
|
|
25
|
+
}
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Build configuration and versioning
|
|
3
|
+
description: The Vite config godmin needs and the design system versions it supports.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Most of what godmin needs from your build is this config:
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { godminDedupe, godminSingleCopy, godminStylesheetFirst } from '@gopherium/godmin/vite'
|
|
10
|
+
|
|
11
|
+
export default defineConfig({
|
|
12
|
+
resolve: { dedupe: godminDedupe },
|
|
13
|
+
plugins: [godminSingleCopy(), godminStylesheetFirst()],
|
|
14
|
+
})
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
This page explains what each part does, then covers stylesheet
|
|
18
|
+
linting and versioning.
|
|
19
|
+
|
|
20
|
+
## One copy of each shared package
|
|
21
|
+
|
|
22
|
+
Your bundle must contain exactly one copy of React and of each
|
|
23
|
+
package `godminDedupe` lists. Two copies of React crash on the first
|
|
24
|
+
hook. Two copies of these fail with no error:
|
|
25
|
+
|
|
26
|
+
- `@wordpress/theme` renders components unthemed.
|
|
27
|
+
- `@wordpress/i18n` renders English. [One copy of the
|
|
28
|
+
runtime](https://docs.gopherium.org/translations/health/#one-copy-of-the-runtime) explains why.
|
|
29
|
+
- `@wordpress/date` leaves the DataViews date filters in English, on
|
|
30
|
+
the wrong clock. The [list dates](./lists.md#dates-in-a-list)
|
|
31
|
+
set up one copy, and the filters read the other.
|
|
32
|
+
- `@gopherium/react-auth` keeps a
|
|
33
|
+
[configured transport](https://docs.gopherium.org/authentication/react-integration/#one-setting-for-the-whole-module)
|
|
34
|
+
that half the app cannot see.
|
|
35
|
+
|
|
36
|
+
The config handles this twice:
|
|
37
|
+
|
|
38
|
+
- `godminDedupe` makes Vite resolve each listed package once.
|
|
39
|
+
- `godminSingleCopy()` fails the build, naming the package and both
|
|
40
|
+
paths, if a duplicate got through anyway.
|
|
41
|
+
|
|
42
|
+
## Paint sooner
|
|
43
|
+
|
|
44
|
+
Nothing renders until your stylesheet arrives, and bundlers request
|
|
45
|
+
it after the JavaScript. `godminStylesheetFirst()` moves it first.
|
|
46
|
+
|
|
47
|
+
How much that helps depends on how much JavaScript competes with it.
|
|
48
|
+
In one app with eight preloads it cut the blank page from 1.9s to
|
|
49
|
+
1.3s. In another with two preloads it changed nothing, because
|
|
50
|
+
nothing was queueing. It costs nothing at runtime, so leave it on
|
|
51
|
+
and let it matter as your bundle grows.
|
|
52
|
+
|
|
53
|
+
On a bundler that is not Vite or Rollup, the underlying functions
|
|
54
|
+
`duplicateCopies` and `hoistStylesheet` are exported so you can wire
|
|
55
|
+
both checks into whatever hooks it offers.
|
|
56
|
+
|
|
57
|
+
## Lint your stylesheets
|
|
58
|
+
|
|
59
|
+
`@wordpress/theme` ships three stylelint rules. This turns them on:
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
export default { extends: ['@gopherium/godmin/stylelint'] }
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
They catch design tokens that do not exist (a typo renders nothing,
|
|
66
|
+
with no error), redefined `--wpds-` properties, and hand-typed
|
|
67
|
+
fallback values.
|
|
68
|
+
|
|
69
|
+
## Design system versions
|
|
70
|
+
|
|
71
|
+
Each godmin release supports one design system window, written out
|
|
72
|
+
in full in its peer ranges as the first version it accepts and the
|
|
73
|
+
first one it refuses, such as `>=0.24.0 <0.25.0`. The window moves
|
|
74
|
+
forward with the design system and never widens, so no release
|
|
75
|
+
accepts two incompatible generations at once.
|
|
76
|
+
|
|
77
|
+
The window is exported for your tests:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { SUPPORTED_WPDS } from '@gopherium/godmin'
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`SUPPORTED_WPDS` names the `@wordpress/ui` and `@wordpress/theme`
|
|
84
|
+
windows only. The other design system peers, `@wordpress/icons`,
|
|
85
|
+
`@wordpress/a11y` and `@wordpress/style-runtime`, have their windows
|
|
86
|
+
in the peer ranges of godmin's `package.json`.
|
|
87
|
+
|
|
88
|
+
`@wordpress/i18n` is a required peer, because the main entry
|
|
89
|
+
translates godmin's own words. `@wordpress/date` is an optional peer,
|
|
90
|
+
needed only by `@gopherium/godmin/dates`. `@wordpress/components` is
|
|
91
|
+
an optional peer too, needed only by `@gopherium/godmin/dialogs`, in
|
|
92
|
+
the window `>=42.0.0 <43.0.0`. Install each one next to godmin when
|
|
93
|
+
you use its entry. Load the components stylesheet once in your
|
|
94
|
+
application, `@wordpress/components/build-style/style.css`, as
|
|
95
|
+
DataViews already asks. godmin never imports it. Their windows are in
|
|
96
|
+
the same peer ranges.
|
|
97
|
+
|
|
98
|
+
`@wordpress/dataviews` is an optional peer as well, in the window
|
|
99
|
+
`>=20.0.0 <21.0.0`. No godmin entry imports it, but `offeredView`
|
|
100
|
+
follows the filter rules of that DataViews release. A list built on
|
|
101
|
+
another release gets a peer warning when it installs godmin.
|
|
102
|
+
|
|
103
|
+
## Upgrading from godmin 0.27.0
|
|
104
|
+
|
|
105
|
+
godmin 0.28.0 draws toasts as WordPress's new admin draws its
|
|
106
|
+
snackbars. Change your code in these places:
|
|
107
|
+
|
|
108
|
+
- `useToaster().name` and the `nameLength` prop of `Toaster` are gone.
|
|
109
|
+
Put the name in the message as it is. A long name wraps.
|
|
110
|
+
- `dismissAfter` now times only a toast with no action. Pass
|
|
111
|
+
`actionDismissAfter` to time a toast with an action. It stays 10
|
|
112
|
+
seconds when you pass nothing.
|
|
113
|
+
- A toast with an action has no close button. A click anywhere on it
|
|
114
|
+
clears it, so a test that pressed the close button clicks the toast
|
|
115
|
+
instead. A stylesheet that styles `.godmin-toast__dismiss` styles
|
|
116
|
+
nothing now.
|
|
117
|
+
- `dismissLabel` is now only the hint of a toast with no action, and
|
|
118
|
+
its default is `Dismiss this notice`, WordPress's words. A test that
|
|
119
|
+
reads the old hint, `Dismiss`, reads the new one.
|
|
120
|
+
- A toast now sits in a `.godmin-toasts__item` element inside
|
|
121
|
+
`.godmin-toasts`. A selector such as `.godmin-toasts > .godmin-toast`,
|
|
122
|
+
or code that reads the children of the region as toasts, reaches the
|
|
123
|
+
toast through that element.
|
|
124
|
+
- A toast now rises into place as it arrives, as
|
|
125
|
+
[Motion](./design-system/toasts.md#motion) shows. A browser test that
|
|
126
|
+
measures where a toast sits waits for that motion to end, or runs
|
|
127
|
+
with a reduced motion preference.
|
|
128
|
+
|
|
129
|
+
TypeScript points at each call to `name` and at `nameLength`. The rest
|
|
130
|
+
changes only what the reader sees.
|
|
131
|
+
|
|
132
|
+
## Upgrading from godmin 0.24.0
|
|
133
|
+
|
|
134
|
+
godmin 0.25.0 gives the sidebar parts the names WordPress gives them.
|
|
135
|
+
TypeScript points at each old name, and
|
|
136
|
+
[the changelog](https://github.com/gopherium/godmin/blob/main/CHANGELOG.md)
|
|
137
|
+
lists every new one. Change your code in these places too:
|
|
138
|
+
|
|
139
|
+
- Install `@wordpress/i18n` next to godmin, and take
|
|
140
|
+
`@tanstack/react-router` 1.170.44 or a newer 1.x release.
|
|
141
|
+
- `NavigationScreen` draws its title as an `h1` and no longer moves
|
|
142
|
+
the focus to it. Pass `headingLevel={2}` to every `Page` beside it,
|
|
143
|
+
as [heading levels](./screens.md#heading-levels) explains.
|
|
144
|
+
- The sidebar and the drawer have no padding of their own. A sidebar
|
|
145
|
+
screen pads its rows.
|
|
146
|
+
- A stylesheet that reads the sidebar width reads
|
|
147
|
+
`--godmin-nav-sidebar-width`.
|
|
148
|
+
- A stylesheet that styles the sidebar slot or a sidebar screen reads
|
|
149
|
+
`.godmin-layout__sidebar` and the `.godmin-navigation-screen`
|
|
150
|
+
classes.
|
|
151
|
+
- The phone menu button is named "Open navigation panel" by default.
|
|
152
|
+
A test that finds it by its old name, "Open navigation", finds it by
|
|
153
|
+
the new one.
|
|
154
|
+
- `PageTabs` draws its tabs as a `ul` list, one `li` per tab, and its
|
|
155
|
+
`.godmin-page-tabs` class sits on that list. A stylesheet that
|
|
156
|
+
styles the tabs by the `nav` reads the list.
|
|
157
|
+
- `useUnsavedText` and `markLatest` came in 0.24.1 and come back in
|
|
158
|
+
0.27.0. 0.25.0 and 0.26.0 do not have them, so an app that uses them
|
|
159
|
+
on 0.24.1 moves straight to 0.27.0 or later.
|
|
160
|
+
|
|
161
|
+
## Upgrading from godmin 0.22.0
|
|
162
|
+
|
|
163
|
+
godmin 0.23.0 shows every failed write in a toast, never inside a
|
|
164
|
+
dialog or above the list, as WordPress does. Take 0.23.1 or later,
|
|
165
|
+
which lets a dialog take a write's promise whether the write
|
|
166
|
+
succeeds or fails. Change your code in these places:
|
|
167
|
+
|
|
168
|
+
- `ConfirmDialog`'s `onConfirm` no longer answers a failure to show.
|
|
169
|
+
To close the dialog at once, make it a plain function that returns
|
|
170
|
+
nothing, and drop the `async` your old handler needed. An `async`
|
|
171
|
+
function always returns a promise. Return the write's promise to
|
|
172
|
+
keep the dialog busy until the write ends. Escape, a click outside
|
|
173
|
+
it and its close button now close it even while it works.
|
|
174
|
+
- `ConfirmBody` and `RenameBody` no longer take `failure`, and
|
|
175
|
+
`RenameBody` no longer takes `busy`. Close a rename when the reader
|
|
176
|
+
presses Save, then write. `RenameBody` also sends a name left as it
|
|
177
|
+
was, and stops only a blank one.
|
|
178
|
+
- `useListRun` no longer answers `failure`, so drop the notice you
|
|
179
|
+
showed above the list. The function that `run.onStart()` answers
|
|
180
|
+
now takes only whether a row moved.
|
|
181
|
+
- `useBulkRun` toasts your `failed` words when a row failed, in place
|
|
182
|
+
of the `done` words.
|
|
183
|
+
|
|
184
|
+
TypeScript points at each prop and field that went away, at an
|
|
185
|
+
`onConfirm` that answers a failure and at a run settled with a
|
|
186
|
+
failure. The rest changes only what the reader sees. In each case,
|
|
187
|
+
show the failure in a toast, as
|
|
188
|
+
[a failure from a dialog](./lists.md#a-failure-from-a-dialog)
|
|
189
|
+
shows.
|
|
190
|
+
|
|
191
|
+
## Upgrading from godmin 0.19.0
|
|
192
|
+
|
|
193
|
+
`startListDates` and `listDate` left the main entry. Import them from
|
|
194
|
+
`@gopherium/godmin/dates`:
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
import { listDate, startListDates } from '@gopherium/godmin/dates'
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Keep `@wordpress/date` and `@wordpress/i18n` installed next to godmin
|
|
201
|
+
while you use them.
|
|
202
|
+
|
|
203
|
+
## Upgrading from godmin 0.7.0
|
|
204
|
+
|
|
205
|
+
godmin 0.7.0 and older asked you to copy a patch for
|
|
206
|
+
`@wordpress/element`. Newer releases support design system versions
|
|
207
|
+
that bring `@wordpress/element` 8.7.0 or newer, which needs no patch.
|
|
208
|
+
|
|
209
|
+
Delete the patch file, its `patchedDependencies` entry and any build
|
|
210
|
+
step that copies it. If your `package.json` lists
|
|
211
|
+
`@wordpress/element`, move it to 8.7.0 too. A leftover entry makes
|
|
212
|
+
`pnpm install` stop with `ERR_PNPM_UNUSED_PATCH`.
|
|
213
|
+
|
|
214
|
+
## License
|
|
215
|
+
|
|
216
|
+
godmin is Apache-2.0. The design system packages are
|
|
217
|
+
GPL-2.0-or-later and are peer dependencies: your application
|
|
218
|
+
installs them, godmin never redistributes them. Your built bundle
|
|
219
|
+
combines both and is conveyed under the WordPress packages' terms.
|