@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 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
- [the overview](https://docs.gopherium.org/admin-ui/overview/) for what those
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
- ## Design system versions
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: 32px;
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: default;
347
+ cursor: var(--wpds-cursor-control);
324
348
  pointer-events: auto;
325
- animation: godmin-fade-in var(--wpds-motion-duration-md) var(--wpds-motion-easing-balanced);
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: godmin-fade-out var(--wpds-motion-duration-sm) var(--wpds-motion-easing-balanced) forwards;
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
- cursor: var(--wpds-cursor-control);
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-xs) dotted #fff;
377
- outline-offset: 2px;
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';
@@ -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
- * Holds the region a finished run focuses, and drops older runs and the ticked rows when the list changes.
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
- * Holds the region a finished run focuses, and drops older runs and the ticked rows when the list changes.
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
- if (latest.current === id && moved) {
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
  };
@@ -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
+ }
@@ -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
  */