@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/README.md
CHANGED
|
@@ -14,6 +14,9 @@ up hand-writing that glue. GodMin is the glue as a package, and nothing more.
|
|
|
14
14
|
|
|
15
15
|
**[Documentation](https://docs.gopherium.org/admin-ui/overview/)**
|
|
16
16
|
|
|
17
|
+
The same pages ship in this package under [`docs/`](docs/overview.md), so
|
|
18
|
+
you can read the ones that match the version you install.
|
|
19
|
+
|
|
17
20
|
## Install
|
|
18
21
|
|
|
19
22
|
```sh
|
|
@@ -23,11 +26,6 @@ pnpm add @gopherium/godmin
|
|
|
23
26
|
The design system packages are peer dependencies, so your application resolves
|
|
24
27
|
and pins them. GodMin never redistributes them.
|
|
25
28
|
|
|
26
|
-
## Browsers
|
|
27
|
-
|
|
28
|
-
GodMin needs `Intl.Segmenter`, which every browser WordPress supports has:
|
|
29
|
-
Chrome and Edge 87, Safari 14.1 and Firefox 125 or newer.
|
|
30
|
-
|
|
31
29
|
## Setup
|
|
32
30
|
|
|
33
31
|
Import the stylesheet once at your entry point, then mount `AdminRoot` around
|
|
@@ -44,15 +42,14 @@ createRoot(document.getElementById('app')!).render(
|
|
|
44
42
|
)
|
|
45
43
|
```
|
|
46
44
|
|
|
47
|
-
That is the whole host setup. See
|
|
48
|
-
|
|
49
|
-
two lines do for you.
|
|
45
|
+
That is the whole host setup. See [the overview](docs/overview.md) for what
|
|
46
|
+
those two lines do for you.
|
|
50
47
|
|
|
51
48
|
## What is in it
|
|
52
49
|
|
|
53
50
|
| Entry point | Contents |
|
|
54
51
|
| --- | --- |
|
|
55
|
-
| `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `LoadingRows`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
|
|
52
|
+
| `@gopherium/godmin` | `AdminRoot`, `Frame`, `Page`, `PageTitle`, `PageTabs`, `PageTab`, `SectionTitle`, `InitialsAvatar`, `NavigationScreen`, `MenuCount`, `ErrorNotice`, `LoadMore`, `LogList`, `LogItem`, `LogTime`, `LoadingScreen`, `LoadingRows`, `Toaster`, `useToaster`, `RepeatRows`, `RowControls`, `useRowKeys`, `keyFromLabel`, `listChromeCatalogFor`, `LIST_CHROME_DOMAIN`, `ListEmpty`, `ConfirmBody`, `RenameBody`, `FormBody`, `FileButton`, `useServerPaging`, `pageWindow`, `paginationOf`, `runEach`, `bulkNotes`, `useListRun`, `useBulkRun`, `RunConfirm`, `useCloseWhileOpen`, `focusInDialog`, `useFocusBack`, `focusedTrigger`, `openOnTap`, `useUnsavedText`, `markLatest`, `viewNarrows`, `offeredView`, `offeredSize`, `sizedView`, `useMediaQuery`, `useTokenDocument`, the breakpoints `HUGE_BREAKPOINT`, `SIDEBAR_BREAKPOINT`, `EDGE_BREAKPOINT`, `DENSE_BREAKPOINT`, `SHEET_BREAKPOINT`, `TITLE_BREAKPOINT` and `SMALL_VIEWPORT`, `SUPPORTED_WPDS` |
|
|
56
53
|
| `@gopherium/godmin/base.css` | Cascade layer order, design tokens, host rules, frame and screen styles |
|
|
57
54
|
| `@gopherium/godmin/dates` | `startListDates`, `listDate`, the only entry that loads `@wordpress/date` |
|
|
58
55
|
| `@gopherium/godmin/dialogs` | `ConfirmDialog`, `FormDialog`, the only entry that loads `@wordpress/components`. Load `@wordpress/components/build-style/style.css` once in your app, as DataViews asks |
|
|
@@ -89,19 +86,11 @@ if (catalogue !== undefined) {
|
|
|
89
86
|
## Before your first build
|
|
90
87
|
|
|
91
88
|
Duplicate packages break the application, and nothing points at the cause.
|
|
92
|
-
[Build configuration](https://docs.gopherium.org/admin-ui/build-and-versioning/)
|
|
93
|
-
covers it.
|
|
94
|
-
|
|
95
89
|
Two copies of React throw on the first hook. Two copies of `@wordpress/theme`
|
|
96
90
|
render unthemed components with no error. Spread `godminDedupe` into
|
|
97
91
|
`resolve.dedupe` and add the `godminSingleCopy()` plugin.
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
Peer ranges are longhand and single window, for example `>=0.23.0 <0.24.0`.
|
|
102
|
-
The window moves with each design system release train and never widens, so no
|
|
103
|
-
release accepts two breaking generations at once. `SUPPORTED_WPDS` exports the
|
|
104
|
-
window this build was tested against.
|
|
92
|
+
[Build configuration](docs/build-and-versioning.md) covers both, and lists the
|
|
93
|
+
design system versions each release supports.
|
|
105
94
|
|
|
106
95
|
## Status
|
|
107
96
|
|
package/dist/base.css
CHANGED
|
@@ -279,26 +279,50 @@ body {
|
|
|
279
279
|
.godmin-toasts {
|
|
280
280
|
position: fixed;
|
|
281
281
|
inset-inline: 0;
|
|
282
|
-
bottom:
|
|
282
|
+
bottom: var(--wpds-dimension-size-md);
|
|
283
283
|
z-index: 1;
|
|
284
284
|
display: flex;
|
|
285
285
|
flex-direction: column;
|
|
286
|
-
align-items: center;
|
|
287
|
-
gap: var(--wpds-dimension-gap-sm);
|
|
288
286
|
padding-inline: 16px;
|
|
289
287
|
box-sizing: border-box;
|
|
290
288
|
pointer-events: none;
|
|
291
289
|
}
|
|
292
290
|
|
|
293
|
-
:root:has(.godmin-layout__sidebar) .godmin-toasts {
|
|
294
|
-
inset-inline-start: var(--godmin-nav-sidebar-width);
|
|
295
|
-
inset-inline-end: var(--godmin-canvas-margin);
|
|
296
|
-
}
|
|
297
|
-
|
|
298
291
|
.godmin-toasts:focus {
|
|
299
292
|
outline: none;
|
|
300
293
|
}
|
|
301
294
|
|
|
295
|
+
.godmin-toasts__item {
|
|
296
|
+
display: grid;
|
|
297
|
+
grid-template-rows: 1fr;
|
|
298
|
+
animation: godmin-toast-grow var(--wpds-motion-duration-lg) cubic-bezier(0, 0, 0.2, 1);
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
.godmin-toasts__item--leaving {
|
|
302
|
+
animation:
|
|
303
|
+
godmin-toast-grow var(--wpds-motion-duration-lg) cubic-bezier(0, 0, 0.2, 1),
|
|
304
|
+
godmin-toast-shrink 450ms cubic-bezier(0.4, 0, 0.1, 1) var(--wpds-motion-duration-sm) forwards;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
.godmin-toasts__item-inner {
|
|
308
|
+
display: flex;
|
|
309
|
+
flex-direction: column;
|
|
310
|
+
align-items: center;
|
|
311
|
+
min-height: 0;
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
@keyframes godmin-toast-grow {
|
|
315
|
+
0% {
|
|
316
|
+
grid-template-rows: 0fr;
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
@keyframes godmin-toast-shrink {
|
|
321
|
+
100% {
|
|
322
|
+
grid-template-rows: 0fr;
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
|
|
302
326
|
.godmin-toast {
|
|
303
327
|
display: flex;
|
|
304
328
|
align-items: baseline;
|
|
@@ -320,20 +344,25 @@ body {
|
|
|
320
344
|
font-size: var(--wpds-typography-font-size-md);
|
|
321
345
|
line-height: 1.4;
|
|
322
346
|
overflow-wrap: anywhere;
|
|
323
|
-
cursor:
|
|
347
|
+
cursor: var(--wpds-cursor-control);
|
|
324
348
|
pointer-events: auto;
|
|
325
|
-
animation: godmin-fade-in
|
|
349
|
+
animation: godmin-fade-in 250ms cubic-bezier(0, 0, 0.2, 1) var(--wpds-motion-duration-xs) backwards;
|
|
326
350
|
}
|
|
327
351
|
|
|
328
352
|
.godmin-toast--leaving {
|
|
329
|
-
animation:
|
|
353
|
+
animation:
|
|
354
|
+
godmin-fade-in 250ms cubic-bezier(0, 0, 0.2, 1) var(--wpds-motion-duration-xs) backwards,
|
|
355
|
+
godmin-fade-out var(--wpds-motion-duration-sm) cubic-bezier(0, 0, 0.2, 1) forwards;
|
|
330
356
|
}
|
|
331
357
|
|
|
332
358
|
.godmin-toast--plain {
|
|
333
359
|
margin: 0;
|
|
334
360
|
border: 0;
|
|
335
361
|
text-align: start;
|
|
336
|
-
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
.godmin-toasts__item-inner > .godmin-toast {
|
|
365
|
+
margin-block-start: var(--wpds-dimension-gap-sm);
|
|
337
366
|
}
|
|
338
367
|
|
|
339
368
|
.godmin-toast__action {
|
|
@@ -355,17 +384,6 @@ body {
|
|
|
355
384
|
text-decoration: none;
|
|
356
385
|
}
|
|
357
386
|
|
|
358
|
-
.godmin-toast__dismiss {
|
|
359
|
-
flex: none;
|
|
360
|
-
margin-inline-start: var(--wpds-dimension-gap-xl);
|
|
361
|
-
padding: 0;
|
|
362
|
-
border: 0;
|
|
363
|
-
background: none;
|
|
364
|
-
color: inherit;
|
|
365
|
-
font: inherit;
|
|
366
|
-
cursor: var(--wpds-cursor-control);
|
|
367
|
-
}
|
|
368
|
-
|
|
369
387
|
.godmin-toast--plain:focus-visible {
|
|
370
388
|
box-shadow:
|
|
371
389
|
inset 0 0 0 var(--wpds-border-width-xs) #fff,
|
|
@@ -373,8 +391,8 @@ body {
|
|
|
373
391
|
}
|
|
374
392
|
|
|
375
393
|
.godmin-toast__action:focus-visible {
|
|
376
|
-
outline: var(--wpds-border-width-
|
|
377
|
-
outline-offset:
|
|
394
|
+
outline: var(--wpds-border-width-focus) solid #fff;
|
|
395
|
+
outline-offset: var(--wpds-border-width-focus);
|
|
378
396
|
border-radius: var(--wpds-border-radius-sm);
|
|
379
397
|
text-decoration: none;
|
|
380
398
|
}
|
|
@@ -982,10 +1000,6 @@ body {
|
|
|
982
1000
|
}
|
|
983
1001
|
|
|
984
1002
|
@keyframes godmin-fade-out {
|
|
985
|
-
0% {
|
|
986
|
-
opacity: 1;
|
|
987
|
-
}
|
|
988
|
-
|
|
989
1003
|
100% {
|
|
990
1004
|
opacity: 0;
|
|
991
1005
|
}
|
|
@@ -994,9 +1008,14 @@ body {
|
|
|
994
1008
|
@media (prefers-reduced-motion: reduce) {
|
|
995
1009
|
.godmin-loading-screen,
|
|
996
1010
|
.godmin-loading-rows,
|
|
997
|
-
.godmin-arrival
|
|
1011
|
+
.godmin-arrival {
|
|
1012
|
+
animation-duration: 1ms;
|
|
1013
|
+
}
|
|
1014
|
+
|
|
1015
|
+
.godmin-toasts__item,
|
|
998
1016
|
.godmin-toast {
|
|
999
1017
|
animation-duration: 1ms;
|
|
1018
|
+
animation-delay: 0s;
|
|
1000
1019
|
}
|
|
1001
1020
|
|
|
1002
1021
|
.godmin-navigation__screen-wrapper {
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Returns the close of a dialog body that acts only while that body is on screen, never on a dialog opened since.
|
|
3
|
+
* @param close - Closes the dialog, none for a body drawn outside a dialog.
|
|
4
|
+
* @returns The close, which does nothing once the body left the screen.
|
|
5
|
+
*/
|
|
6
|
+
export declare function useCloseWhileOpen(close: (() => void) | undefined): () => void;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { useEffect, useRef } from 'react';
|
|
3
|
+
/**
|
|
4
|
+
* Returns the close of a dialog body that acts only while that body is on screen, never on a dialog opened since.
|
|
5
|
+
* @param close - Closes the dialog, none for a body drawn outside a dialog.
|
|
6
|
+
* @returns The close, which does nothing once the body left the screen.
|
|
7
|
+
*/
|
|
8
|
+
export function useCloseWhileOpen(close) {
|
|
9
|
+
const open = useRef(true);
|
|
10
|
+
useEffect(() => {
|
|
11
|
+
open.current = true;
|
|
12
|
+
return () => {
|
|
13
|
+
open.current = false;
|
|
14
|
+
};
|
|
15
|
+
}, []);
|
|
16
|
+
return () => {
|
|
17
|
+
if (open.current) {
|
|
18
|
+
close?.();
|
|
19
|
+
}
|
|
20
|
+
};
|
|
21
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import type { RefObject } from 'react';
|
|
2
|
+
/** Finds each trigger a dialog on an item opens from, inside the card or the row holding the item. */
|
|
3
|
+
declare const TRIGGERS: {
|
|
4
|
+
title: string;
|
|
5
|
+
media: string;
|
|
6
|
+
row: string;
|
|
7
|
+
actions: string;
|
|
8
|
+
};
|
|
9
|
+
/** A trigger on a card or a row a dialog on its item opens from. */
|
|
10
|
+
type ItemTrigger = keyof typeof TRIGGERS;
|
|
11
|
+
/** The trigger a list dialog opened from: an item's title, media, phone row or actions menu, or the bulk bar. */
|
|
12
|
+
export type Trigger = ItemTrigger | 'bulk';
|
|
13
|
+
/**
|
|
14
|
+
* Returns the trigger a click, a tap or a key opened a dialog from, read from the focus it left there.
|
|
15
|
+
* @returns The bulk bar, the media, the title or the phone row holding the focus, the actions menu otherwise.
|
|
16
|
+
*/
|
|
17
|
+
export declare function focusedTrigger(): Trigger;
|
|
18
|
+
/**
|
|
19
|
+
* Returns the handler putting a focus the page lost back on the trigger a list dialog opened from, once drawn again.
|
|
20
|
+
* @param busy - Whether the list reads its items again, its cards and rows then out of reach of the focus.
|
|
21
|
+
* @param region - The list region, whose cells carry the `data-item-id` mark, none while the screen draws no list.
|
|
22
|
+
* @returns The handler, given the id of the item and the trigger the dialog opened from.
|
|
23
|
+
*/
|
|
24
|
+
export declare function useFocusBack(busy: boolean, region: RefObject<HTMLElement | null>): (id: string, trigger: Trigger) => void;
|
|
25
|
+
export {};
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
import { useCallback, useEffect, useRef, useState } from 'react';
|
|
3
|
+
/** Finds each cell an app marks with the id DataViews keys its item by, the title cell at least. */
|
|
4
|
+
const MARKED = '[data-item-id]';
|
|
5
|
+
/** Finds the card of a grid, the row of a phone list or the row of a table holding an item. */
|
|
6
|
+
const HOLDERS = '.dataviews-view-grid__card, .dataviews-view-list__item-wrapper, .dataviews-view-table__row';
|
|
7
|
+
/** Finds each trigger a dialog on an item opens from, inside the card or the row holding the item. */
|
|
8
|
+
const TRIGGERS = {
|
|
9
|
+
title: '.dataviews-title-field[role="button"]',
|
|
10
|
+
media: '.dataviews-view-grid__media[role="button"], .dataviews-column-primary__media[role="button"]',
|
|
11
|
+
row: '.dataviews-view-list__item',
|
|
12
|
+
actions: '[aria-haspopup="menu"]',
|
|
13
|
+
};
|
|
14
|
+
/** Finds the bar DataViews draws the actions on the ticked items in. */
|
|
15
|
+
const BULK_BAR = '.dataviews-bulk-actions-footer__container';
|
|
16
|
+
/**
|
|
17
|
+
* Returns the trigger a click, a tap or a key opened a dialog from, read from the focus it left there.
|
|
18
|
+
* @returns The bulk bar, the media, the title or the phone row holding the focus, the actions menu otherwise.
|
|
19
|
+
*/
|
|
20
|
+
export function focusedTrigger() {
|
|
21
|
+
const focused = document.activeElement;
|
|
22
|
+
if (focused.closest(BULK_BAR) !== null) {
|
|
23
|
+
return 'bulk';
|
|
24
|
+
}
|
|
25
|
+
const triggers = ['media', 'title', 'row'];
|
|
26
|
+
return triggers.find((trigger) => focused.closest(TRIGGERS[trigger]) !== null) ?? 'actions';
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Returns the card or the row holding an item inside the list, found through the mark on its cells.
|
|
30
|
+
* @param list - The list region.
|
|
31
|
+
* @param id - The id DataViews keys the item by.
|
|
32
|
+
* @returns The card or the row, none once the item left the list or its mark sits outside every card and row.
|
|
33
|
+
*/
|
|
34
|
+
function holderOf(list, id) {
|
|
35
|
+
const marked = [...list.querySelectorAll(MARKED)].find((cell) => cell.dataset.itemId === id);
|
|
36
|
+
return marked?.closest(HOLDERS) ?? null;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Returns the trigger a dialog on an item opened from, found wherever its card or row now sits.
|
|
40
|
+
* @param list - The list region.
|
|
41
|
+
* @param asked - The item and the trigger.
|
|
42
|
+
* @returns The trigger, else the item's actions menu, else the list, which a bulk action always gets.
|
|
43
|
+
*/
|
|
44
|
+
function triggerOf(list, { id, trigger }) {
|
|
45
|
+
const holder = holderOf(list, id);
|
|
46
|
+
if (trigger === 'bulk' || holder === null) {
|
|
47
|
+
return list;
|
|
48
|
+
}
|
|
49
|
+
const found = holder.querySelector(TRIGGERS[trigger]);
|
|
50
|
+
return found ?? holder.querySelector(TRIGGERS.actions) ?? list;
|
|
51
|
+
}
|
|
52
|
+
/** Stops nothing, for a focus put on the list region, which no layout of the list takes off the page. */
|
|
53
|
+
function stopNothing() { }
|
|
54
|
+
/**
|
|
55
|
+
* Reports whether a batch of changes to the list took an element off the page, to draw it anew or to move it.
|
|
56
|
+
* @param records - The changes to the list.
|
|
57
|
+
* @param element - The element.
|
|
58
|
+
* @returns Whether a change removed the element or a node holding it.
|
|
59
|
+
*/
|
|
60
|
+
function tookOff(records, element) {
|
|
61
|
+
return records.some((record) => [...record.removedNodes].some((node) => node.contains(element)));
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Puts the focus on the trigger a dialog on an item opened from, again on each redraw, on the list once the item left.
|
|
65
|
+
* @param list - The list region.
|
|
66
|
+
* @param asked - The item and the trigger.
|
|
67
|
+
* @returns What stops it, which also stops once the reader moves the focus or presses elsewhere, or the list takes it.
|
|
68
|
+
*/
|
|
69
|
+
function keepFocusOn(list, asked) {
|
|
70
|
+
let held = triggerOf(list, asked);
|
|
71
|
+
held.focus();
|
|
72
|
+
if (held === list) {
|
|
73
|
+
return stopNothing;
|
|
74
|
+
}
|
|
75
|
+
const redrawn = new MutationObserver((records) => {
|
|
76
|
+
if (!tookOff(records, held)) {
|
|
77
|
+
return;
|
|
78
|
+
}
|
|
79
|
+
held = triggerOf(list, asked);
|
|
80
|
+
held.focus();
|
|
81
|
+
if (held === list) {
|
|
82
|
+
stop();
|
|
83
|
+
}
|
|
84
|
+
});
|
|
85
|
+
const moved = (event) => {
|
|
86
|
+
if (!held.contains(event.target)) {
|
|
87
|
+
stop();
|
|
88
|
+
}
|
|
89
|
+
};
|
|
90
|
+
const stop = () => {
|
|
91
|
+
redrawn.disconnect();
|
|
92
|
+
document.removeEventListener('focusin', moved, true);
|
|
93
|
+
document.removeEventListener('pointerdown', moved, true);
|
|
94
|
+
};
|
|
95
|
+
redrawn.observe(list, { childList: true, subtree: true });
|
|
96
|
+
document.addEventListener('focusin', moved, true);
|
|
97
|
+
document.addEventListener('pointerdown', moved, true);
|
|
98
|
+
return stop;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Returns the handler putting a focus the page lost back on the trigger a list dialog opened from, once drawn again.
|
|
102
|
+
* @param busy - Whether the list reads its items again, its cards and rows then out of reach of the focus.
|
|
103
|
+
* @param region - The list region, whose cells carry the `data-item-id` mark, none while the screen draws no list.
|
|
104
|
+
* @returns The handler, given the id of the item and the trigger the dialog opened from.
|
|
105
|
+
*/
|
|
106
|
+
export function useFocusBack(busy, region) {
|
|
107
|
+
const [asked, setAsked] = useState();
|
|
108
|
+
const handled = useRef(undefined);
|
|
109
|
+
const keeping = useRef(stopNothing);
|
|
110
|
+
useEffect(() => () => keeping.current(), []);
|
|
111
|
+
useEffect(() => {
|
|
112
|
+
if (busy || asked === handled.current) {
|
|
113
|
+
return;
|
|
114
|
+
}
|
|
115
|
+
handled.current = asked;
|
|
116
|
+
const list = region.current;
|
|
117
|
+
if (list !== null && document.activeElement === document.body) {
|
|
118
|
+
keeping.current = keepFocusOn(list, asked);
|
|
119
|
+
}
|
|
120
|
+
}, [asked, busy, region]);
|
|
121
|
+
return useCallback((id, trigger) => {
|
|
122
|
+
keeping.current();
|
|
123
|
+
setAsked({ id, trigger });
|
|
124
|
+
}, []);
|
|
125
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -7,10 +7,13 @@ export { useBulkRun } from './bulk-run.js';
|
|
|
7
7
|
export type { BulkRun } from './bulk-run.js';
|
|
8
8
|
export { bulkNotes, runEach } from './bulk.js';
|
|
9
9
|
export type { BulkFailure, BulkNotes, BulkOutcome, BulkWords } from './bulk.js';
|
|
10
|
+
export { useCloseWhileOpen } from './close-while-open.js';
|
|
10
11
|
export { ConfirmBody } from './confirm.js';
|
|
11
12
|
export type { ConfirmBodyProps } from './confirm.js';
|
|
12
13
|
export { FileButton } from './file-button.js';
|
|
13
14
|
export type { FileButtonProps } from './file-button.js';
|
|
15
|
+
export { focusedTrigger, useFocusBack } from './focus-back.js';
|
|
16
|
+
export type { Trigger } from './focus-back.js';
|
|
14
17
|
export { FormBody } from './form.js';
|
|
15
18
|
export type { FormBodyProps, FormKind } from './form.js';
|
|
16
19
|
export { Frame } from './frame.js';
|
|
@@ -21,8 +24,9 @@ export { LIST_CHROME_DOMAIN, listChromeCatalogFor } from './list-chrome.js';
|
|
|
21
24
|
export type { ListChromeCatalog } from './list-chrome.js';
|
|
22
25
|
export { ListEmpty } from './list-empty.js';
|
|
23
26
|
export type { ListEmptyProps } from './list-empty.js';
|
|
24
|
-
export { useListRun } from './list-run.js';
|
|
27
|
+
export { focusInDialog, useListRun } from './list-run.js';
|
|
25
28
|
export type { ListRun, ListRunState, RunSettled } from './list-run.js';
|
|
29
|
+
export type { LayoutDefaults, ListDefaults, ListFilter, ListSearch, ListSortDirection, ListView, ListViewShape, } from './list-view.js';
|
|
26
30
|
export { LoadingRows, LoadingScreen } from './loading.js';
|
|
27
31
|
export { LogItem, LogList, LogTime } from './log-list.js';
|
|
28
32
|
export type { LogItemProps, LogListProps, LogTimeProps } from './log-list.js';
|
|
@@ -30,6 +34,8 @@ export { MenuCount } from './menu-count.js';
|
|
|
30
34
|
export type { MenuCountProps } from './menu-count.js';
|
|
31
35
|
export { NavigationScreen } from './navigation-screen.js';
|
|
32
36
|
export type { NavigationScreenProps } from './navigation-screen.js';
|
|
37
|
+
export { openOnTap } from './open-on-tap.js';
|
|
38
|
+
export type { TapList } from './open-on-tap.js';
|
|
33
39
|
export { ErrorNotice, LoadMore, Page, PageTitle, SectionTitle } from './page.js';
|
|
34
40
|
export type { LoadMoreQuery, PageProps } from './page.js';
|
|
35
41
|
export { PageTab, PageTabs } from './page-tabs.js';
|
|
@@ -46,6 +52,8 @@ export { offeredSize, pageWindow, paginationOf, sizedView, useServerPaging } fro
|
|
|
46
52
|
export type { PagedView, PageWindow, PaginationInfo, ServedPage, ServedSize, ServerPaging } from './server-page.js';
|
|
47
53
|
export { Toaster, useToaster } from './toaster.js';
|
|
48
54
|
export type { ToastAction, ToasterHandle, ToasterProps } from './toaster.js';
|
|
55
|
+
export { markLatest, useUnsavedText } from './unsaved-text.js';
|
|
56
|
+
export type { UnsavedText } from './unsaved-text.js';
|
|
49
57
|
export { useMediaQuery } from './use-media-query.js';
|
|
50
58
|
export { useTokenDocument } from './use-token-document.js';
|
|
51
59
|
export { offeredView, viewNarrows } from './view-guard.js';
|
package/dist/index.js
CHANGED
|
@@ -4,18 +4,21 @@ export { InitialsAvatar } from './avatar.js';
|
|
|
4
4
|
export { DENSE_BREAKPOINT, EDGE_BREAKPOINT, HUGE_BREAKPOINT, SHEET_BREAKPOINT, SIDEBAR_BREAKPOINT, SMALL_VIEWPORT, TITLE_BREAKPOINT, } from './breakpoints.js';
|
|
5
5
|
export { useBulkRun } from './bulk-run.js';
|
|
6
6
|
export { bulkNotes, runEach } from './bulk.js';
|
|
7
|
+
export { useCloseWhileOpen } from './close-while-open.js';
|
|
7
8
|
export { ConfirmBody } from './confirm.js';
|
|
8
9
|
export { FileButton } from './file-button.js';
|
|
10
|
+
export { focusedTrigger, useFocusBack } from './focus-back.js';
|
|
9
11
|
export { FormBody } from './form.js';
|
|
10
12
|
export { Frame } from './frame.js';
|
|
11
13
|
export { keyFromLabel } from './keys.js';
|
|
12
14
|
export { LIST_CHROME_DOMAIN, listChromeCatalogFor } from './list-chrome.js';
|
|
13
15
|
export { ListEmpty } from './list-empty.js';
|
|
14
|
-
export { useListRun } from './list-run.js';
|
|
16
|
+
export { focusInDialog, useListRun } from './list-run.js';
|
|
15
17
|
export { LoadingRows, LoadingScreen } from './loading.js';
|
|
16
18
|
export { LogItem, LogList, LogTime } from './log-list.js';
|
|
17
19
|
export { MenuCount } from './menu-count.js';
|
|
18
20
|
export { NavigationScreen } from './navigation-screen.js';
|
|
21
|
+
export { openOnTap } from './open-on-tap.js';
|
|
19
22
|
export { ErrorNotice, LoadMore, Page, PageTitle, SectionTitle } from './page.js';
|
|
20
23
|
export { PageTab, PageTabs } from './page-tabs.js';
|
|
21
24
|
export { RenameBody } from './rename.js';
|
|
@@ -24,6 +27,7 @@ export { RepeatRows, RowControls } from './rows.js';
|
|
|
24
27
|
export { RunConfirm } from './run-confirm.js';
|
|
25
28
|
export { offeredSize, pageWindow, paginationOf, sizedView, useServerPaging } from './server-page.js';
|
|
26
29
|
export { Toaster, useToaster } from './toaster.js';
|
|
30
|
+
export { markLatest, useUnsavedText } from './unsaved-text.js';
|
|
27
31
|
export { useMediaQuery } from './use-media-query.js';
|
|
28
32
|
export { useTokenDocument } from './use-token-document.js';
|
|
29
33
|
export { offeredView, viewNarrows } from './view-guard.js';
|
package/dist/list-run.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { RefObject } from 'react';
|
|
2
|
-
/** Settles a run on its list, focusing the list once an item moved. */
|
|
2
|
+
/** Settles a run on its list, focusing the list 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 {
|
|
@@ -14,7 +14,12 @@ export interface ListRunState {
|
|
|
14
14
|
region: RefObject<HTMLDivElement | null>;
|
|
15
15
|
}
|
|
16
16
|
/**
|
|
17
|
-
*
|
|
17
|
+
* Reports whether a dialog holds the focus, which a write finished in the background leaves where it is.
|
|
18
|
+
* @returns Whether the focus sits inside a dialog or an alert dialog.
|
|
19
|
+
*/
|
|
20
|
+
export declare function focusInDialog(): boolean;
|
|
21
|
+
/**
|
|
22
|
+
* Holds the region a run focuses while the reader stays on it, and drops older runs and ticked rows on a list change.
|
|
18
23
|
* @param scope - Names the list on show.
|
|
19
24
|
* @param onChangeSelection - Replaces the ticked rows, emptied when the list changes.
|
|
20
25
|
* @returns The run and the region.
|
package/dist/list-run.js
CHANGED
|
@@ -1,7 +1,59 @@
|
|
|
1
1
|
// SPDX-License-Identifier: Apache-2.0
|
|
2
2
|
import { useLayoutEffect, useRef, useState } from 'react';
|
|
3
|
+
/** Finds the dialog or the alert dialog holding the focus. */
|
|
4
|
+
const DIALOG_IN_FOCUS = '[role="dialog"]:focus-within, [role="alertdialog"]:focus-within';
|
|
5
|
+
/** Stops nothing, for a run that watches no focus. */
|
|
6
|
+
function stopNothing() { }
|
|
3
7
|
/**
|
|
4
|
-
*
|
|
8
|
+
* Reports whether a dialog holds the focus, which a write finished in the background leaves where it is.
|
|
9
|
+
* @returns Whether the focus sits inside a dialog or an alert dialog.
|
|
10
|
+
*/
|
|
11
|
+
export function focusInDialog() {
|
|
12
|
+
return document.querySelector(DIALOG_IN_FOCUS) !== null;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Watches where the focus first lands outside the dialog a run started in while that dialog is still on the page.
|
|
16
|
+
* @param startedIn - The dialog that held the focus as the run started, none for a run started outside every dialog.
|
|
17
|
+
* @returns The landing, filled in once the focus lands, which watches nothing for a run started outside every dialog.
|
|
18
|
+
*/
|
|
19
|
+
function watchLanding(startedIn) {
|
|
20
|
+
const landing = { element: null, stop: stopNothing };
|
|
21
|
+
if (startedIn === null) {
|
|
22
|
+
return landing;
|
|
23
|
+
}
|
|
24
|
+
const note = (event) => {
|
|
25
|
+
if (startedIn.isConnected && !startedIn.contains(event.target)) {
|
|
26
|
+
landing.element = event.target;
|
|
27
|
+
landing.stop();
|
|
28
|
+
}
|
|
29
|
+
};
|
|
30
|
+
document.addEventListener('focusin', note, true);
|
|
31
|
+
landing.stop = () => document.removeEventListener('focusin', note, true);
|
|
32
|
+
return landing;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Reports whether the dialog a run started in has closed while the focus stays where it first landed, in no dialog.
|
|
36
|
+
* @param startedIn - The dialog that held the focus as the run started, none for a run started outside every dialog.
|
|
37
|
+
* @param landed - The element the focus first landed on outside that dialog, none while it never did.
|
|
38
|
+
* @returns Whether that dialog has gone and the focus stays on the element it handed the focus back to.
|
|
39
|
+
*/
|
|
40
|
+
function stillWhereDialogLeftIt(startedIn, landed) {
|
|
41
|
+
return startedIn?.isConnected === false && document.activeElement === landed && !focusInDialog();
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Reports whether the focus sits on the page, in the list, in the dialog that ran, or where that dialog left it.
|
|
45
|
+
* @param list - The list region, none while the screen draws no list.
|
|
46
|
+
* @param startedIn - The dialog that held the focus as the run started, none for a run started outside every dialog.
|
|
47
|
+
* @param landed - The element the focus first landed on outside that dialog, none while it never did.
|
|
48
|
+
* @returns Whether a finished run may move the focus to the list.
|
|
49
|
+
*/
|
|
50
|
+
function readerOnList(list, startedIn, landed) {
|
|
51
|
+
const active = document.activeElement;
|
|
52
|
+
const holds = [list, startedIn].some((holder) => holder !== null && holder.contains(active));
|
|
53
|
+
return active === document.body || holds || stillWhereDialogLeftIt(startedIn, landed);
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Holds the region a run focuses while the reader stays on it, and drops older runs and ticked rows on a list change.
|
|
5
57
|
* @param scope - Names the list on show.
|
|
6
58
|
* @param onChangeSelection - Replaces the ticked rows, emptied when the list changes.
|
|
7
59
|
* @returns The run and the region.
|
|
@@ -9,9 +61,11 @@ import { useLayoutEffect, useRef, useState } from 'react';
|
|
|
9
61
|
export function useListRun(scope, onChangeSelection) {
|
|
10
62
|
const region = useRef(null);
|
|
11
63
|
const latest = useRef(0);
|
|
64
|
+
const watching = useRef(stopNothing);
|
|
12
65
|
const committed = useRef(scope);
|
|
13
66
|
useLayoutEffect(() => {
|
|
14
67
|
latest.current += 1;
|
|
68
|
+
return () => watching.current();
|
|
15
69
|
}, [scope]);
|
|
16
70
|
useLayoutEffect(() => {
|
|
17
71
|
if (committed.current !== scope) {
|
|
@@ -21,10 +75,18 @@ export function useListRun(scope, onChangeSelection) {
|
|
|
21
75
|
}, [scope, onChangeSelection]);
|
|
22
76
|
const [run] = useState(() => ({
|
|
23
77
|
onStart: () => {
|
|
78
|
+
watching.current();
|
|
24
79
|
latest.current += 1;
|
|
25
80
|
const id = latest.current;
|
|
81
|
+
const startedIn = document.querySelector(DIALOG_IN_FOCUS);
|
|
82
|
+
const landing = watchLanding(startedIn);
|
|
83
|
+
watching.current = landing.stop;
|
|
26
84
|
return (moved) => {
|
|
27
|
-
|
|
85
|
+
landing.stop();
|
|
86
|
+
if (latest.current !== id || !moved) {
|
|
87
|
+
return;
|
|
88
|
+
}
|
|
89
|
+
if (readerOnList(region.current, startedIn, landing.element)) {
|
|
28
90
|
region.current?.focus();
|
|
29
91
|
}
|
|
30
92
|
};
|
package/dist/list-view.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
export { openOnTap } from './open-on-tap.js';
|
|
1
2
|
/** The direction the rows of a list are sorted in. */
|
|
2
3
|
export type ListSortDirection = 'asc' | 'desc';
|
|
3
4
|
/** A filter narrowing the rows of a list, as a DataViews view holds it. */
|
|
@@ -105,10 +106,3 @@ export declare function listSearch(raw: Record<string, unknown>): ListSearch;
|
|
|
105
106
|
* @returns The view beside the controls DataViews takes.
|
|
106
107
|
*/
|
|
107
108
|
export declare function useListView<V extends ListViewShape>(defaults: ListDefaults): ListView<V>;
|
|
108
|
-
/**
|
|
109
|
-
* Returns the selection handler a list hands DataViews, opening the record a tap lands on in the phone layout.
|
|
110
|
-
* @param list - The list view the screen holds.
|
|
111
|
-
* @param open - Opens the record with the given id.
|
|
112
|
-
* @returns The handler.
|
|
113
|
-
*/
|
|
114
|
-
export declare function openOnTap<V extends ListViewShape>(list: ListView<V>, open: (id: string) => void): (selection: string[]) => void;
|
package/dist/list-view.js
CHANGED
|
@@ -3,6 +3,7 @@ import { useMatch, useNavigate, useSearch } from '@tanstack/react-router';
|
|
|
3
3
|
import { useState } from 'react';
|
|
4
4
|
import { DENSE_BREAKPOINT } from './breakpoints.js';
|
|
5
5
|
import { useMediaQuery } from './use-media-query.js';
|
|
6
|
+
export { openOnTap } from './open-on-tap.js';
|
|
6
7
|
/** The layouts a list takes when it names none. */
|
|
7
8
|
const TABLE_AND_LIST = { wide: 'table', phone: 'list' };
|
|
8
9
|
/** The selection a list opens on and the one a phone layout always holds. */
|
|
@@ -228,19 +229,3 @@ export function useListView(defaults) {
|
|
|
228
229
|
...selection,
|
|
229
230
|
};
|
|
230
231
|
}
|
|
231
|
-
/**
|
|
232
|
-
* Returns the selection handler a list hands DataViews, opening the record a tap lands on in the phone layout.
|
|
233
|
-
* @param list - The list view the screen holds.
|
|
234
|
-
* @param open - Opens the record with the given id.
|
|
235
|
-
* @returns The handler.
|
|
236
|
-
*/
|
|
237
|
-
export function openOnTap(list, open) {
|
|
238
|
-
if (!list.phone) {
|
|
239
|
-
return list.onChangeSelection;
|
|
240
|
-
}
|
|
241
|
-
return ([id]) => {
|
|
242
|
-
if (id !== undefined) {
|
|
243
|
-
open(id);
|
|
244
|
-
}
|
|
245
|
-
};
|
|
246
|
-
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/** The part of a list view a tap reads, which `useListView` returns among the rest. */
|
|
2
|
+
export interface TapList {
|
|
3
|
+
/** Whether the viewport takes the phone layout. */
|
|
4
|
+
phone: boolean;
|
|
5
|
+
/** Holds the rows ticked in the wide layout. */
|
|
6
|
+
onChangeSelection: (selection: string[]) => void;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Returns the selection handler a list hands DataViews, opening the record a tap lands on in the phone layout.
|
|
10
|
+
* @param list - The list view the screen holds.
|
|
11
|
+
* @param open - Opens the record with the given id.
|
|
12
|
+
* @returns The handler.
|
|
13
|
+
*/
|
|
14
|
+
export declare function openOnTap(list: TapList, open: (id: string) => void): (selection: string[]) => void;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
/**
|
|
3
|
+
* Returns the selection handler a list hands DataViews, opening the record a tap lands on in the phone layout.
|
|
4
|
+
* @param list - The list view the screen holds.
|
|
5
|
+
* @param open - Opens the record with the given id.
|
|
6
|
+
* @returns The handler.
|
|
7
|
+
*/
|
|
8
|
+
export function openOnTap(list, open) {
|
|
9
|
+
if (!list.phone) {
|
|
10
|
+
return list.onChangeSelection;
|
|
11
|
+
}
|
|
12
|
+
return ([id]) => {
|
|
13
|
+
if (id !== undefined) {
|
|
14
|
+
open(id);
|
|
15
|
+
}
|
|
16
|
+
};
|
|
17
|
+
}
|
package/dist/run-confirm.d.ts
CHANGED
|
@@ -15,7 +15,7 @@ export interface RunConfirmProps<Item> {
|
|
|
15
15
|
run: (items: Item[]) => Promise<unknown>;
|
|
16
16
|
}
|
|
17
17
|
/**
|
|
18
|
-
* Renders a confirmation that runs the action, keeps Cancel inert while it runs and closes once it settles.
|
|
18
|
+
* Renders a confirmation that runs the action, keeps Cancel inert while it runs and closes only itself once it settles.
|
|
19
19
|
* @param props - The items, the close handler, the question, the labels and the run.
|
|
20
20
|
* @returns The confirmation body.
|
|
21
21
|
*/
|