@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.
@@ -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
- closeModal?.();
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 nobody touches stays on screen. */
17
+ /** How many milliseconds a toast with no action stays on screen when nobody touches it. */
20
18
  dismissAfter?: number;
21
- /** The name of the close button, also the hint screen readers hear that a click clears a plain toast. */
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 toast time, the close button name, how many stay and the name length.
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, nameLength, }: ToasterProps): import("react").JSX.Element;
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 nobody touches stays on screen.
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
- * The name of the control clearing a toast.
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 DISMISS_LABEL = 'Dismiss';
14
+ const ACTION_DISMISS_AFTER = 10000;
14
15
  /**
15
- * The cross the WordPress snackbar draws in its close button.
16
+ * The hint telling a screen reader that a click clears a plain toast.
16
17
  */
17
- const DISMISS_GLYPH = '✕';
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 fades running on an element, none where the browser cannot report them.
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 runningFades(element) {
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 element that gives up focus as the toast leaves and drops the toast once faded.
78
- * @param toast - The toast the element draws.
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 toast element.
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 fades = runningFades(element);
96
- if (fades.length === 0) {
76
+ const motion = leavingAtMount.current ? [] : runningMotion(element);
77
+ if (motion.length === 0) {
97
78
  onGone(id);
98
79
  return;
99
80
  }
100
- Promise.allSettled(fades.map((fade) => fade.finished)).then(() => onGone(id));
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, the region and the handlers clearing it.
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, region, onLeave, onGone, }) {
125
+ function PlainToast({ toast, dismissAfter, hint, onLeave }) {
135
126
  useExpiry(toast, dismissAfter, onLeave);
136
- const ref = useDeparture(toast, region, onGone);
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 and a close button beside it.
141
- * @param props - The toast, its action, its time, the close button name, the region and the handlers clearing it.
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, dismissLabel, region, onLeave, onGone, }) {
134
+ function ActionToast({ toast, action, dismissAfter, onLeave }) {
145
135
  useExpiry(toast, dismissAfter, onLeave);
146
- const ref = useDeparture(toast, region, onGone);
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
- }, children: action.label }), _jsx("button", { type: "button", className: "godmin-toast__dismiss", "aria-label": dismissLabel, onClick: () => onLeave(toast.id), children: DISMISS_GLYPH })] }));
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 toast time, the close button name, how many stay and the name length.
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, dismissLabel = DISMISS_LABEL, limit = LIMIT, nameLength = NAME_LENGTH, }) {
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 name = useCallback((title) => cutName(title, nameLength), [nameLength]);
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, region: region, onLeave: leave, onGone: gone }, toast.id)) : (_jsx(ActionToast, { toast: toast, action: toast.action, dismissAfter: dismissAfter, dismissLabel: dismissLabel, region: region, onLeave: leave, onGone: gone }, toast.id))) }), _jsx("span", { id: hint, hidden: true, children: dismissLabel })] }));
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.