@gopherium/godmin 0.29.1 → 0.31.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 (42) hide show
  1. package/README.md +4 -3
  2. package/dist/base.css +223 -13
  3. package/dist/bulk-run.d.ts +3 -3
  4. package/dist/bulk-run.js +41 -13
  5. package/dist/focus-back.d.ts +22 -0
  6. package/dist/focus-back.js +37 -13
  7. package/dist/index.d.ts +5 -3
  8. package/dist/index.js +4 -3
  9. package/dist/list-chrome/es-ES.d.ts +1 -1
  10. package/dist/list-chrome/es-ES.js +7 -4
  11. package/dist/list-chrome/fr-FR.d.ts +1 -1
  12. package/dist/list-chrome/fr-FR.js +5 -1
  13. package/dist/list-empty.d.ts +14 -7
  14. package/dist/list-empty.js +14 -4
  15. package/dist/list-run.d.ts +8 -4
  16. package/dist/list-run.js +143 -6
  17. package/dist/page-breadcrumbs.d.ts +28 -0
  18. package/dist/page-breadcrumbs.js +18 -0
  19. package/dist/page-tabs.js +29 -26
  20. package/dist/page.d.ts +8 -3
  21. package/dist/page.js +48 -9
  22. package/dist/size-watch.d.ts +11 -0
  23. package/dist/size-watch.js +36 -0
  24. package/dist/wide-list.d.ts +7 -0
  25. package/dist/wide-list.js +33 -0
  26. package/docs/build-and-versioning.md +3 -3
  27. package/docs/design-system/accessibility.md +64 -16
  28. package/docs/design-system/custom-properties.md +9 -2
  29. package/docs/design-system/layout.md +5 -3
  30. package/docs/design-system/lists.md +234 -0
  31. package/docs/design-system/loading.md +2 -0
  32. package/docs/design-system/overview.md +6 -1
  33. package/docs/design-system/radius-and-elevation.md +3 -9
  34. package/docs/design-system/record-pages.md +197 -0
  35. package/docs/design-system/toasts.md +2 -3
  36. package/docs/design-system/typography.md +3 -3
  37. package/docs/framing-an-application.md +7 -5
  38. package/docs/lists.md +278 -72
  39. package/docs/loading-and-feedback.md +9 -11
  40. package/docs/overview.md +1 -1
  41. package/docs/screens.md +83 -36
  42. package/package.json +21 -21
@@ -1,5 +1,5 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
- /** The French list dates, dialog words and sidebar words, compiled from the fr-FR.po source beside it. */
2
+ /** The French list dates, dialog, sidebar and no results words, compiled from the fr-FR.po source beside it. */
3
3
  const catalog = {
4
4
  '': { lang: 'fr-FR', 'plural-forms': 'nplurals=2; plural=(n > 1);' },
5
5
  AM: ['AM'],
@@ -31,6 +31,7 @@ const catalog = {
31
31
  Mon: ['Lun'],
32
32
  Monday: ['lundi'],
33
33
  Navigation: ['Navigation'],
34
+ 'No results found': ['Aucun résultat trouvé'],
34
35
  November: ['novembre'],
35
36
  'November abbreviation\u0004Nov': ['Nov'],
36
37
  October: ['octobre'],
@@ -46,6 +47,9 @@ const catalog = {
46
47
  Sunday: ['dimanche'],
47
48
  Thu: ['Jeu'],
48
49
  Thursday: ['jeudi'],
50
+ "Try adjusting your search or filters to find what you're looking for.": [
51
+ "Essayez d'ajuster votre recherche ou vos filtres pour trouver ce que vous cherchez.",
52
+ ],
49
53
  Tue: ['Mar'],
50
54
  Tuesday: ['mardi'],
51
55
  Wed: ['Mer'],
@@ -1,16 +1,23 @@
1
1
  import { EmptyState } from '@wordpress/ui';
2
- import type { ComponentProps } from 'react';
2
+ import type { ComponentProps, ReactNode } from 'react';
3
3
  export interface ListEmptyProps {
4
4
  /** The icon drawn above the title, from `@wordpress/icons`. */
5
5
  icon: ComponentProps<typeof EmptyState.Icon>['icon'];
6
- /** The sentence saying the list is empty. */
6
+ /** The words saying the list is empty, one short phrase. */
7
7
  title: string;
8
- /** The line under the title, such as what to do to fill the list. */
9
- hint?: string;
8
+ /** The sentence under the title, such as what fills the list. */
9
+ description?: string;
10
+ /** The buttons under the description, such as the add button of the list at its default size. */
11
+ actions?: ReactNode;
10
12
  }
11
13
  /**
12
- * Renders what a list shows when it has no rows: an icon, a title one level under the page title and an optional hint.
13
- * @param props - The icon, the title and the hint.
14
+ * Renders what a list with no rows shows: an icon, a title one level under the page title, a description and buttons.
15
+ * @param props - The icon, the title, the description and the buttons.
14
16
  * @returns The empty state element.
15
17
  */
16
- export declare function ListEmpty({ icon, title, hint }: ListEmptyProps): import("react").JSX.Element;
18
+ export declare function ListEmpty({ icon, title, description, actions }: ListEmptyProps): import("react").JSX.Element;
19
+ /**
20
+ * Renders what a list shows when a search or a filter finds no rows, as Jetpack Forms says it.
21
+ * @returns The empty state element with the search icon and no buttons.
22
+ */
23
+ export declare function ListNoResults(): import("react").JSX.Element;
@@ -1,13 +1,23 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  // SPDX-License-Identifier: Apache-2.0
3
+ import { __ } from '@wordpress/i18n';
4
+ import { search } from '@wordpress/icons';
3
5
  import { EmptyState } from '@wordpress/ui';
4
6
  import { useHeadingUnderPage } from './page.js';
5
7
  /**
6
- * Renders what a list shows when it has no rows: an icon, a title one level under the page title and an optional hint.
7
- * @param props - The icon, the title and the hint.
8
+ * Renders what a list with no rows shows: an icon, a title one level under the page title, a description and buttons.
9
+ * @param props - The icon, the title, the description and the buttons.
8
10
  * @returns The empty state element.
9
11
  */
10
- export function ListEmpty({ icon, title, hint }) {
12
+ export function ListEmpty({ icon, title, description, actions }) {
11
13
  const Heading = useHeadingUnderPage();
12
- return (_jsxs(EmptyState.Root, { className: "godmin-empty", children: [_jsx(EmptyState.Icon, { icon: icon }), _jsx(EmptyState.Title, { render: _jsx(Heading, {}), children: title }), hint === undefined ? null : _jsx(EmptyState.Description, { children: hint })] }));
14
+ const buttons = actions ?? false;
15
+ return (_jsxs(EmptyState.Root, { className: "godmin-empty", children: [_jsx(EmptyState.Icon, { icon: icon }), _jsx(EmptyState.Title, { render: _jsx(Heading, {}), children: title }), description === undefined ? null : _jsx(EmptyState.Description, { children: description }), buttons === false ? null : _jsx(EmptyState.Actions, { children: buttons })] }));
16
+ }
17
+ /**
18
+ * Renders what a list shows when a search or a filter finds no rows, as Jetpack Forms says it.
19
+ * @returns The empty state element with the search icon and no buttons.
20
+ */
21
+ export function ListNoResults() {
22
+ return (_jsx(ListEmpty, { icon: search, title: __('No results found'), description: __("Try adjusting your search or filters to find what you're looking for.") }));
13
23
  }
@@ -1,17 +1,21 @@
1
1
  import type { RefObject } from 'react';
2
- /** Settles a run on its list, focusing the list once an item moved while the reader is still on it. */
2
+ /** Settles a run on its list, focusing the list with no scroll once an item moved while the reader is still on it. */
3
3
  export type RunSettled = (moved: boolean) => void;
4
4
  /** What a list does around a run over its items. */
5
5
  export interface ListRun {
6
6
  /** Starts a run on this list and returns what settles it. */
7
7
  onStart: () => RunSettled;
8
+ /** Marks the list as reloading after its own write and returns what ends that reload. */
9
+ onRefresh: () => () => void;
8
10
  }
9
- /** The run a list's actions start and the region a finished run focuses. */
11
+ /** The run a list's actions start, the region a finished run focuses, and whether the list reloads. */
10
12
  export interface ListRunState {
11
13
  /** What the list does around a run, the same object for as long as the screen stays. */
12
14
  run: ListRun;
13
15
  /** The list region a finished run focuses, handed to `Page` as `listRef`. */
14
16
  region: RefObject<HTMLDivElement | null>;
17
+ /** Whether a run reloads the list after its own write, to pass to DataViews `isLoading`. */
18
+ refreshing: boolean;
15
19
  }
16
20
  /**
17
21
  * Reports whether a dialog holds the focus, which a write finished in the background leaves where it is.
@@ -19,9 +23,9 @@ export interface ListRunState {
19
23
  */
20
24
  export declare function focusInDialog(): boolean;
21
25
  /**
22
- * Holds the region a run focuses while the reader stays on it, and drops older runs and ticked rows on a list change.
26
+ * Holds the region a run focuses, gives its focus back once the list reloaded, and drops old runs on a list change.
23
27
  * @param scope - Names the list on show.
24
28
  * @param onChangeSelection - Replaces the ticked rows, emptied when the list changes.
25
- * @returns The run and the region.
29
+ * @returns The run, the region and whether the list reloads.
26
30
  */
27
31
  export declare function useListRun(scope: string, onChangeSelection: (selection: string[]) => void): ListRunState;
package/dist/list-run.js CHANGED
@@ -1,9 +1,47 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
  import { useLayoutEffect, useRef, useState } from 'react';
3
+ import { HOLDERS, itemAt, triggerOnItem } from './focus-back.js';
3
4
  /** Finds the dialog or the alert dialog holding the focus. */
4
5
  const DIALOG_IN_FOCUS = '[role="dialog"]:focus-within, [role="alertdialog"]:focus-within';
6
+ /** Finds a part that turned inert while it holds the focus. */
7
+ const INERT_IN_FOCUS = '[inert]:focus-within';
8
+ /** Finds a dialog or an alert dialog that a control of the list opens. */
9
+ const DIALOG = '[role="dialog"], [role="alertdialog"]';
10
+ /** Finds every control a reader can focus inside a card or a row. */
11
+ const CONTROLS = 'a[href], button, input, select, textarea, [tabindex]';
12
+ /** Finds a button of a row that runs an action, never the actions menu button, which only opens a menu. */
13
+ const ACTION_BUTTON = '.dataviews-item-actions button:not(.dataviews-all-actions-button)';
5
14
  /** Stops nothing, for a run that watches no focus. */
6
15
  function stopNothing() { }
16
+ /**
17
+ * Counts the reloads a list has open, each ended once, and drops them all when the list changes.
18
+ * @returns Whether a reload is open, and how to start one or drop them all.
19
+ */
20
+ function useReloads() {
21
+ const [open, setOpen] = useState(0);
22
+ const [reloads] = useState(() => {
23
+ let generation = 0;
24
+ return {
25
+ start: () => {
26
+ const startedIn = generation;
27
+ let ended = false;
28
+ setOpen((count) => count + 1);
29
+ return () => {
30
+ if (ended || startedIn !== generation) {
31
+ return;
32
+ }
33
+ ended = true;
34
+ setOpen((count) => count - 1);
35
+ };
36
+ },
37
+ drop: () => {
38
+ generation += 1;
39
+ setOpen(0);
40
+ },
41
+ };
42
+ });
43
+ return [open !== 0, reloads];
44
+ }
7
45
  /**
8
46
  * Reports whether a dialog holds the focus, which a write finished in the background leaves where it is.
9
47
  * @returns Whether the focus sits inside a dialog or an alert dialog.
@@ -40,6 +78,81 @@ function watchLanding(startedIn) {
40
78
  function stillWhereDialogLeftIt(startedIn, landed) {
41
79
  return startedIn?.isConnected === false && document.activeElement === landed && !focusInDialog();
42
80
  }
81
+ /**
82
+ * Moves the focus to the list region, scrolling nothing, when it sits in a part of that list that turned inert.
83
+ * @param list - The list region, none while the screen draws no list.
84
+ */
85
+ function keepOnList(list) {
86
+ if (list?.querySelector(INERT_IN_FOCUS)) {
87
+ list.focus({ preventScroll: true });
88
+ }
89
+ }
90
+ /**
91
+ * Returns where a control stands in the list, its card or row, none for the region or outside it.
92
+ * @param list - The list region, none while the screen draws no list.
93
+ * @param focused - The element that holds the focus or just lost it.
94
+ * @returns The place, none when the element is the list region itself or sits outside it.
95
+ */
96
+ function placeOf(list, focused) {
97
+ if (focused === list || !list?.contains(focused)) {
98
+ return null;
99
+ }
100
+ const control = focused;
101
+ const row = [...list.querySelectorAll(HOLDERS)].indexOf(control.closest(HOLDERS));
102
+ return { control, row, item: itemAt(control) };
103
+ }
104
+ /**
105
+ * Returns the trigger on the item the reader stood on, found wherever its card or row now sits.
106
+ * @param list - The list region.
107
+ * @param place - Where the reader stood.
108
+ * @returns The trigger, none once the item left the list or when the app marks no item there.
109
+ */
110
+ function onSameItem(list, { item }) {
111
+ return item === null ? null : triggerOnItem(list, item);
112
+ }
113
+ /**
114
+ * Returns the first control of the card or row that now sits where the place's sat, the last one when fewer came back.
115
+ * @param list - The list region.
116
+ * @param place - Where the reader stood.
117
+ * @returns The control, its box in a list with bulk actions, none for an action button or with no row in that place.
118
+ */
119
+ function firstInPlace(list, { row }) {
120
+ const rows = list.querySelectorAll(HOLDERS);
121
+ const first = rows.item(Math.min(row, rows.length - 1))?.querySelector(CONTROLS);
122
+ return first?.matches(ACTION_BUTTON) ? null : first;
123
+ }
124
+ /**
125
+ * Gives the focus back from the list region to the pressed control, else the same item, else the row in its place.
126
+ * @param list - The list region, none while the screen draws no list.
127
+ * @param place - Where the reader stood as the list took the focus, none when they stood nowhere in it.
128
+ */
129
+ function putBack(list, place) {
130
+ if (list === null || place === null) {
131
+ return;
132
+ }
133
+ const preventScroll = !list.matches(':focus-visible');
134
+ for (const control of [place.control, onSameItem(list, place), firstInPlace(list, place)]) {
135
+ if (document.activeElement === list) {
136
+ control?.focus({ preventScroll });
137
+ }
138
+ }
139
+ }
140
+ /**
141
+ * Notes the place of the control the focus leaves the list from for a dialog, none when it goes elsewhere.
142
+ * @param region - The list region, none while the screen draws no list.
143
+ * @param opener - Where the note goes.
144
+ * @returns What stops noting.
145
+ */
146
+ function noteOpener(region, opener) {
147
+ const note = (event) => {
148
+ const list = region.current;
149
+ if (list?.contains(event.target)) {
150
+ opener.current = event.relatedTarget?.closest(DIALOG) ? placeOf(list, event.target) : null;
151
+ }
152
+ };
153
+ document.addEventListener('focusout', note, true);
154
+ return () => document.removeEventListener('focusout', note, true);
155
+ }
43
156
  /**
44
157
  * Reports whether the focus sits on the page, in the list, in the dialog that ran, or where that dialog left it.
45
158
  * @param list - The list region, none while the screen draws no list.
@@ -53,16 +166,20 @@ function readerOnList(list, startedIn, landed) {
53
166
  return active === document.body || holds || stillWhereDialogLeftIt(startedIn, landed);
54
167
  }
55
168
  /**
56
- * Holds the region a run focuses while the reader stays on it, and drops older runs and ticked rows on a list change.
169
+ * Holds the region a run focuses, gives its focus back once the list reloaded, and drops old runs on a list change.
57
170
  * @param scope - Names the list on show.
58
171
  * @param onChangeSelection - Replaces the ticked rows, emptied when the list changes.
59
- * @returns The run and the region.
172
+ * @returns The run, the region and whether the list reloads.
60
173
  */
61
174
  export function useListRun(scope, onChangeSelection) {
62
175
  const region = useRef(null);
63
176
  const latest = useRef(0);
64
177
  const watching = useRef(stopNothing);
65
178
  const committed = useRef(scope);
179
+ const place = useRef(null);
180
+ const opener = useRef(null);
181
+ const [refreshing, reloads] = useReloads();
182
+ useLayoutEffect(() => noteOpener(region, opener), []);
66
183
  useLayoutEffect(() => {
67
184
  latest.current += 1;
68
185
  return () => watching.current();
@@ -70,27 +187,47 @@ export function useListRun(scope, onChangeSelection) {
70
187
  useLayoutEffect(() => {
71
188
  if (committed.current !== scope) {
72
189
  committed.current = scope;
190
+ place.current = null;
191
+ reloads.drop();
73
192
  onChangeSelection([]);
74
193
  }
75
- }, [scope, onChangeSelection]);
194
+ }, [scope, onChangeSelection, reloads]);
195
+ useLayoutEffect(() => {
196
+ if (refreshing) {
197
+ keepOnList(region.current);
198
+ return;
199
+ }
200
+ putBack(region.current, place.current);
201
+ place.current = null;
202
+ }, [refreshing]);
76
203
  const [run] = useState(() => ({
77
204
  onStart: () => {
78
205
  watching.current();
79
206
  latest.current += 1;
80
207
  const id = latest.current;
81
208
  const startedIn = document.querySelector(DIALOG_IN_FOCUS);
209
+ place.current = startedIn === null ? null : opener.current;
82
210
  const landing = watchLanding(startedIn);
83
211
  watching.current = landing.stop;
84
212
  return (moved) => {
85
213
  landing.stop();
86
- if (latest.current !== id || !moved) {
214
+ if (latest.current !== id) {
215
+ return;
216
+ }
217
+ if (!moved) {
218
+ place.current = null;
87
219
  return;
88
220
  }
89
221
  if (readerOnList(region.current, startedIn, landing.element)) {
90
- region.current?.focus();
222
+ place.current ??= placeOf(region.current, document.activeElement);
223
+ region.current?.focus({ preventScroll: true });
91
224
  }
92
225
  };
93
226
  },
227
+ onRefresh: () => {
228
+ place.current = placeOf(region.current, document.activeElement) ?? place.current;
229
+ return reloads.start();
230
+ },
94
231
  }));
95
- return { run, region };
232
+ return { run, region, refreshing };
96
233
  }
@@ -0,0 +1,28 @@
1
+ import { Link } from '@wordpress/ui';
2
+ import type { ComponentProps, ReactNode } from 'react';
3
+ export interface PageBreadcrumbsProps {
4
+ /** The name of the navigation region, read by assistive technology. */
5
+ label: string;
6
+ /** The links, one PageBreadcrumb each. */
7
+ children: ReactNode;
8
+ }
9
+ /**
10
+ * Renders the links that lead back from a record as a navigation region holding a list, as admin-ui draws its trail.
11
+ * @param props - The navigation name and the links.
12
+ * @returns The navigation element.
13
+ */
14
+ export declare function PageBreadcrumbs({ label, children }: PageBreadcrumbsProps): import("react").JSX.Element;
15
+ export interface PageBreadcrumbProps {
16
+ /** The address the link leads to, when it renders as a plain link. */
17
+ href?: string;
18
+ /** The link element the breadcrumb renders through, such as a router link. */
19
+ render?: ComponentProps<typeof Link>['render'];
20
+ /** The link label. */
21
+ children: ReactNode;
22
+ }
23
+ /**
24
+ * Renders one link of the breadcrumbs as a list item, with the slash after it.
25
+ * @param props - The address or the link element, and the label.
26
+ * @returns The list item element.
27
+ */
28
+ export declare function PageBreadcrumb({ href, render, children }: PageBreadcrumbProps): import("react").JSX.Element;
@@ -0,0 +1,18 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { Link, Text } from '@wordpress/ui';
3
+ /**
4
+ * Renders the links that lead back from a record as a navigation region holding a list, as admin-ui draws its trail.
5
+ * @param props - The navigation name and the links.
6
+ * @returns The navigation element.
7
+ */
8
+ export function PageBreadcrumbs({ label, children }) {
9
+ return (_jsx("nav", { "aria-label": label, className: "godmin-page__breadcrumbs", children: _jsx("ul", { role: "list", children: children }) }));
10
+ }
11
+ /**
12
+ * Renders one link of the breadcrumbs as a list item, with the slash after it.
13
+ * @param props - The address or the link element, and the label.
14
+ * @returns The list item element.
15
+ */
16
+ export function PageBreadcrumb({ href, render, children }) {
17
+ return (_jsxs("li", { children: [_jsx(Text, { variant: "body-lg", render: _jsx(Link, { tone: "neutral", href: href, render: render }), children: children }), _jsx(Text, { variant: "body-lg", "aria-hidden": "true", className: "godmin-page__separator", children: "/" })] }));
18
+ }
package/dist/page-tabs.js CHANGED
@@ -1,9 +1,14 @@
1
- import { jsx as _jsx } from "react/jsx-runtime";
1
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { cloneElement, useLayoutEffect, useRef, useState } from 'react';
3
+ import { ROUNDING_SLACK, useSizeWatch } from './size-watch.js';
3
4
  /**
4
5
  * The class every tab row carries.
5
6
  */
6
7
  const ROW_CLASS = 'godmin-page-tabs';
8
+ /**
9
+ * The class of a tab row wider than its space.
10
+ */
11
+ const SCROLLS_CLASS = 'godmin-page-tabs--scrolling';
7
12
  /**
8
13
  * The class that fades the start edge of a tab row scrolled past its first tabs.
9
14
  */
@@ -21,11 +26,11 @@ const TAB_CLASS = 'godmin-page-tabs__tab';
21
26
  */
22
27
  const CURRENT_CLASS = 'godmin-page-tabs__tab--current';
23
28
  /**
24
- * The scroll in pixels a tab row may sit off an edge and still rest on it, for sub-pixel rounding.
29
+ * The class of the line under the tab of the page on screen.
25
30
  */
26
- const SCROLL_EPSILON = 1;
31
+ const LINE_CLASS = 'godmin-page-tabs__line';
27
32
  /**
28
- * Returns the classes of a tab row, fading each edge that tabs lie past.
33
+ * Returns the classes of a tab row, marking one wider than its space and fading each edge that tabs lie past.
29
34
  * @param row - The tab row element.
30
35
  * @returns The class list.
31
36
  */
@@ -33,14 +38,25 @@ function rowClass(row) {
33
38
  const travelled = Math.abs(row.scrollLeft);
34
39
  const room = row.scrollWidth - row.clientWidth;
35
40
  let classes = ROW_CLASS;
36
- if (travelled > SCROLL_EPSILON) {
41
+ if (room > 0) {
42
+ classes += ` ${SCROLLS_CLASS}`;
43
+ }
44
+ if (travelled > ROUNDING_SLACK) {
37
45
  classes += ` ${FADES_START_CLASS}`;
38
46
  }
39
- if (travelled < room - SCROLL_EPSILON) {
47
+ if (travelled < room - ROUNDING_SLACK) {
40
48
  classes += ` ${FADES_END_CLASS}`;
41
49
  }
42
50
  return classes;
43
51
  }
52
+ /**
53
+ * Returns the boxes whose size decides the fades of a tab row: the row and each tab in it.
54
+ * @param row - The tab row element.
55
+ * @returns The row and its tabs.
56
+ */
57
+ function rowBoxes(row) {
58
+ return [row, ...row.children];
59
+ }
44
60
  /**
45
61
  * Returns the classes of a tab row, measured again as the row scrolls, resizes or gains and loses tabs.
46
62
  * @param ref - The tab row element.
@@ -48,26 +64,12 @@ function rowClass(row) {
48
64
  */
49
65
  function useRowClass(ref) {
50
66
  const [className, setClassName] = useState(ROW_CLASS);
67
+ useSizeWatch(ref, rowBoxes, (row) => setClassName(rowClass(row)), false);
51
68
  useLayoutEffect(() => {
52
69
  const row = ref.current;
53
70
  const measure = () => setClassName(rowClass(row));
54
- const resizes = new ResizeObserver(measure);
55
- const watch = () => {
56
- resizes.disconnect();
57
- for (const box of [row, ...row.children]) {
58
- resizes.observe(box);
59
- }
60
- measure();
61
- };
62
- const mutations = new MutationObserver(watch);
63
- mutations.observe(row, { childList: true });
64
71
  row.addEventListener('scroll', measure, { passive: true });
65
- watch();
66
- return () => {
67
- row.removeEventListener('scroll', measure);
68
- mutations.disconnect();
69
- resizes.disconnect();
70
- };
72
+ return () => row.removeEventListener('scroll', measure);
71
73
  }, [ref]);
72
74
  return className;
73
75
  }
@@ -88,14 +90,14 @@ function reveal(row, tab) {
88
90
  }
89
91
  }
90
92
  /**
91
- * Scrolls a tab row to its current tab each time a tab becomes current, forgetting the last one while none is.
93
+ * Scrolls a tab row to its current tab as a tab becomes current or the row starts to scroll, forgetting it otherwise.
92
94
  * @param ref - The tab row element.
93
95
  */
94
96
  function useRevealCurrent(ref) {
95
97
  const shown = useRef(null);
96
98
  useLayoutEffect(() => {
97
99
  const row = ref.current;
98
- const tab = row.querySelector(`.${CURRENT_CLASS}`);
100
+ const tab = row.classList.contains(SCROLLS_CLASS) ? row.querySelector(`.${CURRENT_CLASS}`) : null;
99
101
  const last = shown.current;
100
102
  shown.current = tab;
101
103
  if (tab === null || tab === last) {
@@ -124,14 +126,15 @@ export function PageTabs({ label, children }) {
124
126
  function TabLink({ href, render, current = false, children }) {
125
127
  const ariaCurrent = current ? 'page' : undefined;
126
128
  const tabClass = current ? `${TAB_CLASS} ${CURRENT_CLASS}` : TAB_CLASS;
129
+ const label = (_jsxs(_Fragment, { children: [children, current && _jsx("span", { className: LINE_CLASS })] }));
127
130
  if (render === undefined) {
128
- return (_jsx("a", { href: href, className: tabClass, "aria-current": ariaCurrent, children: children }));
131
+ return (_jsx("a", { href: href, className: tabClass, "aria-current": ariaCurrent, children: label }));
129
132
  }
130
133
  const own = render.props.className;
131
134
  return cloneElement(render, {
132
135
  className: own === undefined ? tabClass : `${own} ${tabClass}`,
133
136
  'aria-current': ariaCurrent,
134
- children,
137
+ children: label,
135
138
  });
136
139
  }
137
140
  /**
package/dist/page.d.ts CHANGED
@@ -37,7 +37,12 @@ export interface PageProps {
37
37
  subtitle?: string;
38
38
  actions?: ReactNode;
39
39
  tabs?: ReactNode;
40
+ /** The details of a record, in a fixed column at the end of the page. */
40
41
  aside?: ReactNode;
42
+ /** The name of the details column. */
43
+ asideLabel?: string;
44
+ /** The links back to what a record belongs to, before the title. */
45
+ breadcrumbs?: ReactNode;
41
46
  list?: boolean;
42
47
  /** The name of the list region. */
43
48
  listLabel?: string;
@@ -50,11 +55,11 @@ export interface PageProps {
50
55
  }
51
56
  /**
52
57
  * Renders a screen: a header with the title, actions and subtitle, then optional tabs and the content.
53
- * @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class, title level
54
- * and content.
58
+ * @param props - The title, subtitle, actions, tabs, aside and its name, breadcrumbs, list flag, list name and ref,
59
+ * extra class, title level and content.
55
60
  * @returns The page element.
56
61
  */
57
- export declare function Page({ title, subtitle, actions, tabs, aside, list, listLabel, listRef, className, headingLevel, children, }: PageProps): import("react").JSX.Element;
62
+ export declare function Page({ title, subtitle, actions, tabs, aside, asideLabel, breadcrumbs, list, listLabel, listRef, className, headingLevel, children, }: PageProps): import("react").JSX.Element;
58
63
  /**
59
64
  * Renders a failure message that a screen reader announces.
60
65
  * @param props - The message to announce.
package/dist/page.js CHANGED
@@ -2,7 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  /* oxlint-disable react/only-export-components -- the page kit ships its parts
3
3
  beside the type they share. */
4
4
  import { Button, Notice, Stack, Text } from '@wordpress/ui';
5
- import { createContext, useContext } from 'react';
5
+ import { Children, createContext, useContext, useImperativeHandle, useRef } from 'react';
6
+ import { useWideList } from './wide-list.js';
6
7
  /** The level of the title of the Page around a section title, 1 outside any Page. */
7
8
  const PageLevelContext = createContext(1);
8
9
  /**
@@ -40,6 +41,14 @@ export function SectionTitle({ children, level = 2, id, tabIndex, }) {
40
41
  const Heading = headingTag(level + pageLevel - 1);
41
42
  return (_jsx(Text, { variant: level === 2 ? 'heading-lg' : 'heading-md', render: _jsx(Heading, {}), id: id, tabIndex: tabIndex, children: children }));
42
43
  }
44
+ /**
45
+ * Returns the role and the name of a region given a label.
46
+ * @param label - The name of the region.
47
+ * @returns The role and the name, or nothing with no label.
48
+ */
49
+ function namedRegion(label) {
50
+ return label === undefined ? {} : { role: 'region', 'aria-label': label };
51
+ }
43
52
  /**
44
53
  * Returns the props that let code focus a list with a name or a ref, and name a list region given a label.
45
54
  * @param label - The name of the list region.
@@ -48,28 +57,58 @@ export function SectionTitle({ children, level = 2, id, tabIndex, }) {
48
57
  */
49
58
  function regionOf(label, reached) {
50
59
  const focus = label === undefined && !reached ? {} : { tabIndex: -1 };
51
- return label === undefined ? focus : { ...focus, role: 'region', 'aria-label': label };
60
+ return { ...focus, ...namedRegion(label) };
61
+ }
62
+ /**
63
+ * Renders the list region of a page, marked wide while its DataViews table is wider than its space.
64
+ * @param props - The name of the region, the ref code holds to it, and the list.
65
+ * @returns The list region element.
66
+ */
67
+ function ListRegion({ label, listRef, children, }) {
68
+ const own = useRef(null);
69
+ const wide = useWideList(own);
70
+ useImperativeHandle(listRef, () => own.current, []);
71
+ return (_jsx("div", { className: wide ? 'godmin-page__list godmin-page__list--wide' : 'godmin-page__list', ref: own, ...regionOf(label, listRef !== undefined), children: children }));
72
+ }
73
+ /**
74
+ * Tells whether a page has breadcrumbs to draw.
75
+ * @param breadcrumbs - What the page was given.
76
+ * @returns Whether it holds anything that renders.
77
+ */
78
+ function hasBreadcrumbs(breadcrumbs) {
79
+ return Children.toArray(breadcrumbs).length > 0;
80
+ }
81
+ /**
82
+ * Renders the title of a page, after its breadcrumbs when it has them.
83
+ * @param props - The title, its heading level and the breadcrumbs.
84
+ * @returns The title, alone or after its breadcrumbs.
85
+ */
86
+ function PageHeading({ title, level, breadcrumbs }) {
87
+ if (!hasBreadcrumbs(breadcrumbs)) {
88
+ return _jsx(PageTitle, { level: level, children: title });
89
+ }
90
+ return (_jsxs("div", { className: "godmin-page__heading", children: [breadcrumbs, _jsx(PageTitle, { level: level, children: title })] }));
52
91
  }
53
92
  /**
54
93
  * Renders a screen: a header with the title, actions and subtitle, then optional tabs and the content.
55
- * @param props - The title, subtitle, actions, tabs, aside, list flag, list name and ref, extra class, title level
56
- * and content.
94
+ * @param props - The title, subtitle, actions, tabs, aside and its name, breadcrumbs, list flag, list name and ref,
95
+ * extra class, title level and content.
57
96
  * @returns The page element.
58
97
  */
59
- export function Page({ title, subtitle, actions, tabs, aside, list = false, listLabel, listRef, className, headingLevel = 1, children, }) {
98
+ export function Page({ title, subtitle, actions, tabs, aside, asideLabel, breadcrumbs, list = false, listLabel, listRef, className, headingLevel = 1, children, }) {
60
99
  const classes = className === undefined ? 'godmin-page' : `godmin-page ${className}`;
61
- return (_jsx(PageLevelContext.Provider, { value: headingLevel, children: _jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "column", render: _jsx("header", {}), className: "godmin-page__header", children: [_jsxs(Stack, { direction: "row", wrap: "wrap", gap: "md", align: "center", justify: "space-between", className: "godmin-page__head", children: [_jsx(PageTitle, { level: headingLevel, children: title }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), subtitle !== undefined && (_jsx(Text, { variant: "body-md", render: _jsx("p", {}), className: "godmin-page__subtitle", children: subtitle }))] }), tabs !== undefined && _jsx("div", { className: "godmin-page__tabs", children: tabs }), _jsx(PageBody, { aside: aside, children: list ? (_jsx("div", { className: "godmin-page__list", ref: listRef, ...regionOf(listLabel, listRef !== undefined), children: children })) : (children) })] }) }));
100
+ return (_jsx(PageLevelContext.Provider, { value: headingLevel, children: _jsxs(Stack, { direction: "column", gap: "lg", className: classes, children: [_jsxs(Stack, { direction: "column", render: _jsx("header", {}), className: "godmin-page__header", children: [_jsxs(Stack, { direction: "row", wrap: "wrap", gap: "md", align: "center", justify: "space-between", className: "godmin-page__head", children: [_jsx(PageHeading, { title: title, level: headingLevel, breadcrumbs: breadcrumbs }), actions !== undefined && (_jsx(Stack, { direction: "row", gap: "sm", align: "center", children: actions }))] }), subtitle !== undefined && (_jsx(Text, { variant: "body-md", render: _jsx("p", {}), className: "godmin-page__subtitle", children: subtitle }))] }), tabs !== undefined && _jsx("div", { className: "godmin-page__tabs", children: tabs }), _jsx(PageBody, { aside: aside, asideLabel: asideLabel, children: list ? (_jsx(ListRegion, { label: listLabel, listRef: listRef, children: children })) : (children) })] }) }));
62
101
  }
63
102
  /**
64
103
  * Renders a page's content, beside its aside when it has one.
65
- * @param props - The content and the optional aside.
104
+ * @param props - The content, the optional aside and the name of the aside.
66
105
  * @returns The content alone, or a main column followed by the aside.
67
106
  */
68
- function PageBody({ aside, children }) {
107
+ function PageBody({ aside, asideLabel, children }) {
69
108
  if (aside === undefined) {
70
109
  return children;
71
110
  }
72
- return (_jsxs("div", { className: "godmin-page__split", children: [_jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__main", children: children }), _jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__aside", children: aside })] }));
111
+ return (_jsxs("div", { className: "godmin-page__split", children: [_jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__main", children: children }), _jsx(Stack, { direction: "column", gap: "lg", className: "godmin-page__aside", ...namedRegion(asideLabel), children: aside })] }));
73
112
  }
74
113
  /**
75
114
  * Renders a failure message that a screen reader announces.
@@ -0,0 +1,11 @@
1
+ import type { RefObject } from 'react';
2
+ /** The pixels a box may run past an edge and still rest on it, for sub-pixel rounding. */
3
+ export declare const ROUNDING_SLACK = 1;
4
+ /**
5
+ * Measures once, then again whenever the element or a box it names resizes, or its children change.
6
+ * @param ref - The element to watch.
7
+ * @param boxesOf - Names the boxes whose size the measure reads, given the element.
8
+ * @param measure - Reads the element, the one given on the latest render.
9
+ * @param subtree - Whether a change deeper than the element's own children wires the boxes again.
10
+ */
11
+ export declare function useSizeWatch(ref: RefObject<HTMLElement | null>, boxesOf: (element: HTMLElement) => Element[], measure: (element: HTMLElement) => void, subtree: boolean): void;