shelving 1.319.0 → 1.320.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/docs/llms-full.txt +171 -20
  2. package/docs/ui/Dialog.md +11 -8
  3. package/docs/ui/DialogProps.md +1 -1
  4. package/docs/ui/FADE_TRANSITION_CLASS.md +9 -0
  5. package/docs/ui/FadeTransition.md +13 -0
  6. package/docs/ui/Form.md +1 -1
  7. package/docs/ui/HorizontalTransition.md +20 -4
  8. package/docs/ui/Modal.md +1 -1
  9. package/docs/ui/Notices.md +1 -1
  10. package/docs/ui/SLIDE_DOWN_TRANSITION_CLASS.md +9 -0
  11. package/docs/ui/SLIDE_LEFT_TRANSITION_CLASS.md +9 -0
  12. package/docs/ui/SLIDE_RIGHT_TRANSITION_CLASS.md +9 -0
  13. package/docs/ui/SLIDE_UP_TRANSITION_CLASS.md +9 -0
  14. package/docs/ui/VerticalTransition.md +20 -4
  15. package/docs/ui/requestDialogClose.md +28 -0
  16. package/docs/ui.md +6 -0
  17. package/package.json +1 -1
  18. package/ui/dialog/Dialog.d.ts +15 -4
  19. package/ui/dialog/Dialog.js +19 -12
  20. package/ui/dialog/Dialog.md +9 -6
  21. package/ui/dialog/Dialog.tsx +20 -13
  22. package/ui/dialog/Modal.md +1 -1
  23. package/ui/form/Form.js +4 -3
  24. package/ui/form/Form.md +1 -1
  25. package/ui/form/Form.tsx +3 -2
  26. package/ui/notice/Notices.md +1 -1
  27. package/ui/notice/NoticesTransition.module.css +1 -1
  28. package/ui/transition/FadeTransition.d.ts +9 -1
  29. package/ui/transition/FadeTransition.js +12 -2
  30. package/ui/transition/FadeTransition.md +13 -0
  31. package/ui/transition/{FadeTransition.css → FadeTransition.module.css} +9 -2
  32. package/ui/transition/FadeTransition.tsx +13 -2
  33. package/ui/transition/HorizontalTransition.d.ts +18 -1
  34. package/ui/transition/HorizontalTransition.js +21 -2
  35. package/ui/transition/HorizontalTransition.md +20 -4
  36. package/ui/transition/{HorizontalTransition.css → HorizontalTransition.module.css} +17 -5
  37. package/ui/transition/HorizontalTransition.tsx +30 -2
  38. package/ui/transition/VerticalTransition.d.ts +18 -1
  39. package/ui/transition/VerticalTransition.js +21 -2
  40. package/ui/transition/VerticalTransition.md +20 -4
  41. package/ui/transition/{VerticalTransition.css → VerticalTransition.module.css} +17 -5
  42. package/ui/transition/VerticalTransition.tsx +25 -2
package/docs/ui.md CHANGED
@@ -231,6 +231,7 @@ The components below are listed in the index following this page; this is the sh
231
231
  - [ButtonClickable()](ui/ButtonClickable.md): Render a <button> element that runs its onClick handler through a BusyStore and shows a loading spinner while busy.
232
232
  - [SpanClickable()](ui/SpanClickable.md): Render a non-interactive <span> element, used as the fallback when none of href, onClick or disabled is provided, e.g. a plain tag.
233
233
  - [SubmitButton()](ui/SubmitButton.md): Submit button for a form that disables itself and shows a spinner while the form is busy.
234
+ - [requestDialogClose()](ui/requestDialogClose.md): Ask a <dialog> element to close, the same way as the Escape key.
234
235
  - [requireDialogs()](ui/requireDialogs.md): Read the current DialogsStore from the nearest <DialogsContext>.
235
236
  - [getDocumentationKindColor()](ui/getDocumentationKindColor.md): Get the raw colour variant for a documented symbol's kind, or undefined for an unknown kind.
236
237
  - [splitType()](ui/splitType.md): Split a type expression on | into its individual union members.
@@ -562,6 +563,11 @@ The components below are listed in the index following this page; this is the sh
562
563
  - [RouteContext](ui/RouteContext.md): React context holding the RouteState of the current page, provided by <Router> and <RouteCache>.
563
564
  - [STATUSES](ui/STATUSES.md): Tuple of the status names selectable via the status variant prop.
564
565
  - [TINT_CLASS](ui/TINT_CLASS.md): CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
566
+ - [FADE_TRANSITION_CLASS](ui/FADE_TRANSITION_CLASS.md): View transition class that fades content in and out.
567
+ - [SLIDE_RIGHT_TRANSITION_CLASS](ui/SLIDE_RIGHT_TRANSITION_CLASS.md): View transition class that slides content right: the new content comes in from the right and the old content leaves to the left.
568
+ - [SLIDE_LEFT_TRANSITION_CLASS](ui/SLIDE_LEFT_TRANSITION_CLASS.md): View transition class that slides content left: the new content comes in from the left and the old content leaves to the right.
569
+ - [SLIDE_DOWN_TRANSITION_CLASS](ui/SLIDE_DOWN_TRANSITION_CLASS.md): View transition class that slides content down: the new content comes in from the top and the old content leaves to the bottom.
570
+ - [SLIDE_UP_TRANSITION_CLASS](ui/SLIDE_UP_TRANSITION_CLASS.md): View transition class that slides content up: the new content comes in from the bottom and the old content leaves to the top.
565
571
  - [TreeContext](ui/TreeContext.md): React context holding a flattened key → element map of the surrounding tree(s).
566
572
  - [TREE_CODE_RULE](ui/TREE_CODE_RULE.md): Markup rule that renders an inline code span as a tree-resolved <TreeLink> instead of a plain <code>.
567
573
  - [TREE_MARKUP_RULES](ui/TREE_MARKUP_RULES.md): Default markup rules with the inline-code rule swapped for TREE_CODE_RULE — every backtick span auto-links to its documented token.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.319.0",
3
+ "version": "1.320.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -2,14 +2,13 @@ import { type ReactElement } from "react";
2
2
  import type { Callback } from "../../util/function.js";
3
3
  import { type ButtonVariants } from "../button/Button.js";
4
4
  import type { ClassProps, OptionalChildProps } from "../util/props.js";
5
- import "../transition/FadeTransition.css";
6
5
  /**
7
6
  * Props for `<Dialog>` — optional `children` content and an `onClose` callback.
8
7
  *
9
8
  * @see https://shelving.cc/ui/DialogProps
10
9
  */
11
10
  export interface DialogProps extends OptionalChildProps {
12
- /** Called when the user closes the dialog. It must unmount the `<Dialog>`, and it runs inside `startTransition()` so the dialog animates out. */
11
+ /** Called when the user asks to close the dialog. It must unmount the `<Dialog>`. Unmount it inside `startTransition()` to animate it out (`<Dialogs>` does this for you). */
13
12
  onClose?: Callback;
14
13
  }
15
14
  /**
@@ -17,9 +16,9 @@ export interface DialogProps extends OptionalChildProps {
17
16
  *
18
17
  * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
19
18
  * - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
20
- * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
19
+ * - It knows nothing about transitions. It fades in and out only when the update that mounts or unmounts it is a transition, e.g. from `<Dialogs>` or your own `startTransition()`. A `<Modal>` pinned to an edge then slides in its own layer.
21
20
  * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
22
- * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
21
+ * - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
23
22
  * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
24
23
  * - Wraps content in `<Suspense>` so lazy children can stream in.
25
24
  *
@@ -27,6 +26,18 @@ export interface DialogProps extends OptionalChildProps {
27
26
  * @see https://shelving.cc/ui/Dialog
28
27
  */
29
28
  export declare const Dialog: import("react").MemoExoticComponent<({ children, onClose, ...props }: DialogProps) => import("react").JSX.Element>;
29
+ /**
30
+ * Ask a `<dialog>` element to close, the same way as the Escape key.
31
+ * - Fires a cancelable `cancel` event, so a `<Dialog>` keeps itself open and calls its `onClose`. Its parent then unmounts it, and it can animate out.
32
+ * - Closes the dialog at once only if nothing cancels the event.
33
+ * - Use it instead of `dialog.close()`, which closes at once and fires no `cancel` event, so the dialog vanishes with no transition.
34
+ * - Not `requestClose()`: some browsers lack it, and Safari fires its `cancel` event as not cancelable. Both close the dialog at once.
35
+ *
36
+ * @param dialog The `<dialog>` element to close.
37
+ * @example requestDialogClose(dialog) // Like pressing Escape.
38
+ * @see https://shelving.cc/ui/requestDialogClose
39
+ */
40
+ export declare function requestDialogClose(dialog: HTMLDialogElement): void;
30
41
  /**
31
42
  * Props for `<DialogCloseButton>` — button styling variants and optional `children` to override the X icon.
32
43
  *
@@ -1,9 +1,9 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { memo, Suspense, startTransition, ViewTransition } from "react";
2
+ import { memo, Suspense, ViewTransition } from "react";
3
3
  import { CloseIcon } from "shelving/icon/CloseIcon";
4
4
  import { getButtonClass } from "../button/Button.js";
5
+ import { FADE_TRANSITION_CLASS } from "../transition/FadeTransition.js";
5
6
  import { getClass, getModuleClass } from "../util/css.js";
6
- import "../transition/FadeTransition.css";
7
7
  import styles from "./Dialog.module.css";
8
8
  import modalStyles from "./Modal.module.css";
9
9
  /**
@@ -11,9 +11,9 @@ import modalStyles from "./Modal.module.css";
11
11
  *
12
12
  * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
13
13
  * - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
14
- * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
14
+ * - It knows nothing about transitions. It fades in and out only when the update that mounts or unmounts it is a transition, e.g. from `<Dialogs>` or your own `startTransition()`. A `<Modal>` pinned to an edge then slides in its own layer.
15
15
  * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
16
- * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
16
+ * - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
17
17
  * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
18
18
  * - Wraps content in `<Suspense>` so lazy children can stream in.
19
19
  *
@@ -21,12 +21,12 @@ import modalStyles from "./Modal.module.css";
21
21
  * @see https://shelving.cc/ui/Dialog
22
22
  */
23
23
  export const Dialog = memo(({ children, onClose, ...props }) => {
24
- return (_jsx(Suspense, { fallback: null, children: _jsx(ViewTransition, { default: "none", enter: "fade", exit: "fade", children: _jsxs("dialog", { ref: _showModal, className: getModuleClass(styles, "dialog"), onClick: _closeOnClick, onCancel: e => {
25
- // Keep the dialog open and let the parent unmount it in a transition. An uncancelable request closes natively and fires `onClose` from the `close` event.
24
+ return (_jsx(Suspense, { fallback: null, children: _jsx(ViewTransition, { default: "none", enter: FADE_TRANSITION_CLASS, exit: FADE_TRANSITION_CLASS, children: _jsxs("dialog", { ref: _showModal, className: getModuleClass(styles, "dialog"), onClick: _closeOnClick, onCancel: e => {
25
+ // Keep the dialog open until the parent unmounts it. An uncancelable request closes natively and fires `onClose` from the `close` event.
26
26
  if (!onClose || !e.cancelable)
27
27
  return;
28
28
  e.preventDefault();
29
- startTransition(() => onClose());
29
+ onClose();
30
30
  }, onClose: onClose, ...props, children: [_jsx("div", { className: getModuleClass(styles, "content"), children: children }), _jsx("div", { className: getModuleClass(styles, "close"), children: _jsx(DialogCloseButton, {}) })] }) }) }));
31
31
  });
32
32
  /**
@@ -50,13 +50,20 @@ function _closeOnClick({ currentTarget, target }) {
50
50
  if (target.closest("dialog") !== currentTarget)
51
51
  return;
52
52
  if (target.closest(CLOSE_SELECTOR) || !target.closest(KEEP_SELECTOR))
53
- _requestClose(currentTarget);
53
+ requestDialogClose(currentTarget);
54
54
  }
55
55
  /**
56
- * Ask a `<dialog>` to close: fire a cancelable `cancel` event, so `<Dialog>` can run `onClose` in a transition. Close it at once only when nothing cancels the event.
57
- * - Not `requestClose()`: some browsers lack it, and Safari fires its `cancel` event as not cancelable. Both close the dialog at once, so it vanishes with no fade.
56
+ * Ask a `<dialog>` element to close, the same way as the Escape key.
57
+ * - Fires a cancelable `cancel` event, so a `<Dialog>` keeps itself open and calls its `onClose`. Its parent then unmounts it, and it can animate out.
58
+ * - Closes the dialog at once only if nothing cancels the event.
59
+ * - Use it instead of `dialog.close()`, which closes at once and fires no `cancel` event, so the dialog vanishes with no transition.
60
+ * - Not `requestClose()`: some browsers lack it, and Safari fires its `cancel` event as not cancelable. Both close the dialog at once.
61
+ *
62
+ * @param dialog The `<dialog>` element to close.
63
+ * @example requestDialogClose(dialog) // Like pressing Escape.
64
+ * @see https://shelving.cc/ui/requestDialogClose
58
65
  */
59
- function _requestClose(dialog) {
66
+ export function requestDialogClose(dialog) {
60
67
  if (dialog.dispatchEvent(new Event("cancel", { cancelable: true })))
61
68
  dialog.close();
62
69
  }
@@ -74,5 +81,5 @@ export function DialogCloseButton({ children = _jsx(CloseIcon, {}), plain = true
74
81
  function _closeOnButtonClick({ currentTarget }) {
75
82
  const dialog = currentTarget.closest("dialog");
76
83
  if (dialog)
77
- _requestClose(dialog);
84
+ requestDialogClose(dialog);
78
85
  }
@@ -10,10 +10,13 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
10
10
  - Children sit in one wrapper in normal block layout, so several children stack as they would on the page. The wrapper is `--dialog-width` wide (never wider than the screen) and centred on the screen. A centred `<Modal>` fills it. Content taller than the screen starts at the top, and the dialog scrolls.
11
11
  - While a dialog is open, the page behind it does not scroll. A scroll inside the dialog never passes on to the page.
12
12
  - `Dialog` only dims the page. Its text is white (`--tint-100`) so it reads on the dark overlay. Wrap the content in `<Modal>` to give it a panel with dark text on a light surface.
13
- - `onClose` fires when the user closes the dialog. It must unmount the `Dialog`: clear the React state that mounts it, or (when pushed via a store) remove it from the list. `Dialog` calls `onClose` inside `startTransition()`, and the dialog stays open until it unmounts.
14
- - The dialog animates with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
13
+ - `Dialog` is declarative. While it is mounted, it is open. When the user asks to close it, it calls `onClose` and stays open until it unmounts. `onClose` must unmount it: clear the React state that mounts it, or (when pushed via a store) remove it from the list.
14
+ - To close a dialog from your own code, call `requestDialogClose()` on the `<dialog>` element, not `dialog.close()`. `requestDialogClose()` goes through `onClose` like the Escape key, so the dialog can animate out. `dialog.close()` closes it at once. A successful `<Form>` submit inside a dialog uses `requestDialogClose()`.
15
+ - The dialog can animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
15
16
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition, so the dialog never ignores a tap while its content changes. The page ignores taps while a view transition runs.
16
- - A view transition only runs for a React transition update. `DialogsStore` and `onClose` do this for you. To animate a declarative `Dialog` as it opens, set the state that mounts it inside `startTransition()`.
17
+ - `Dialog` knows nothing about transitions. React runs a view transition only for an update made inside `startTransition()`, so the code that mounts and unmounts the dialog decides if it animates:
18
+ - `<Dialogs>` renders a `DialogsStore` inside transitions, so a dialog opened with `DialogsStore.show()` animates in and out for you.
19
+ - A `Dialog` you mount yourself appears and goes at once, unless you set the state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
17
20
  - A browser without view transitions shows and hides the dialog at once.
18
21
  - Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
19
22
 
@@ -37,9 +40,9 @@ function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose:
37
40
  );
38
41
  }
39
42
 
40
- // In the parent. Open inside `startTransition()` so the dialog animates in.
43
+ // In the parent. Open and close inside `startTransition()` so the dialog animates in and out.
41
44
  <button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>Delete</button>
42
- {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => setShowConfirm(false)} />}
45
+ {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => startTransition(() => setShowConfirm(false))} />}
43
46
  ```
44
47
 
45
48
  ### Imperative
@@ -62,7 +65,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
62
65
  }
63
66
  ```
64
67
 
65
- `dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel.
68
+ `dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel. `<Dialogs>` renders the list inside transitions, so the dialog animates in and out with no `startTransition()` of your own.
66
69
 
67
70
  ## Styling
68
71
 
@@ -1,10 +1,10 @@
1
- import { type MouseEvent, memo, type ReactElement, Suspense, startTransition, ViewTransition } from "react";
1
+ import { type MouseEvent, memo, type ReactElement, Suspense, ViewTransition } from "react";
2
2
  import { CloseIcon } from "shelving/icon/CloseIcon";
3
3
  import type { Callback } from "../../util/function.js";
4
4
  import { type ButtonVariants, getButtonClass } from "../button/Button.js";
5
+ import { FADE_TRANSITION_CLASS } from "../transition/FadeTransition.js";
5
6
  import { getClass, getModuleClass } from "../util/css.js";
6
7
  import type { ClassProps, OptionalChildProps } from "../util/props.js";
7
- import "../transition/FadeTransition.css";
8
8
  import styles from "./Dialog.module.css";
9
9
  import modalStyles from "./Modal.module.css";
10
10
 
@@ -14,7 +14,7 @@ import modalStyles from "./Modal.module.css";
14
14
  * @see https://shelving.cc/ui/DialogProps
15
15
  */
16
16
  export interface DialogProps extends OptionalChildProps {
17
- /** Called when the user closes the dialog. It must unmount the `<Dialog>`, and it runs inside `startTransition()` so the dialog animates out. */
17
+ /** Called when the user asks to close the dialog. It must unmount the `<Dialog>`. Unmount it inside `startTransition()` to animate it out (`<Dialogs>` does this for you). */
18
18
  onClose?: Callback;
19
19
  }
20
20
 
@@ -23,9 +23,9 @@ export interface DialogProps extends OptionalChildProps {
23
23
  *
24
24
  * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
25
25
  * - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
26
- * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
26
+ * - It knows nothing about transitions. It fades in and out only when the update that mounts or unmounts it is a transition, e.g. from `<Dialogs>` or your own `startTransition()`. A `<Modal>` pinned to an edge then slides in its own layer.
27
27
  * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
28
- * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
28
+ * - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
29
29
  * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
30
30
  * - Wraps content in `<Suspense>` so lazy children can stream in.
31
31
  *
@@ -36,17 +36,17 @@ export const Dialog = memo(({ children, onClose, ...props }: DialogProps) => {
36
36
  return (
37
37
  <Suspense fallback={null}>
38
38
  {/* The transition must wrap the `<dialog>`: React only animates a `<ViewTransition>` that comes before any DOM element in the inserted or deleted tree. Fade only on enter and exit, so an open dialog stays still while another dialog opens or closes. No update transition: the page ignores taps while a view transition runs, so a change inside an open dialog must not start one. */}
39
- <ViewTransition default="none" enter="fade" exit="fade">
39
+ <ViewTransition default="none" enter={FADE_TRANSITION_CLASS} exit={FADE_TRANSITION_CLASS}>
40
40
  {/** biome-ignore lint/a11y/useKeyWithClickEvents: Dialogs also show a close button. */}
41
41
  <dialog
42
42
  ref={_showModal}
43
43
  className={getModuleClass(styles, "dialog")}
44
44
  onClick={_closeOnClick}
45
45
  onCancel={e => {
46
- // Keep the dialog open and let the parent unmount it in a transition. An uncancelable request closes natively and fires `onClose` from the `close` event.
46
+ // Keep the dialog open until the parent unmounts it. An uncancelable request closes natively and fires `onClose` from the `close` event.
47
47
  if (!onClose || !e.cancelable) return;
48
48
  e.preventDefault();
49
- startTransition(() => onClose());
49
+ onClose();
50
50
  }}
51
51
  onClose={onClose}
52
52
  {...props}
@@ -83,14 +83,21 @@ function _closeOnClick({ currentTarget, target }: MouseEvent<HTMLDialogElement>)
83
83
  // Ignore taps in a nested dialog. React events bubble through the React tree, so they can reach an outer dialog.
84
84
  if (target.closest("dialog") !== currentTarget) return;
85
85
 
86
- if (target.closest(CLOSE_SELECTOR) || !target.closest(KEEP_SELECTOR)) _requestClose(currentTarget);
86
+ if (target.closest(CLOSE_SELECTOR) || !target.closest(KEEP_SELECTOR)) requestDialogClose(currentTarget);
87
87
  }
88
88
 
89
89
  /**
90
- * Ask a `<dialog>` to close: fire a cancelable `cancel` event, so `<Dialog>` can run `onClose` in a transition. Close it at once only when nothing cancels the event.
91
- * - Not `requestClose()`: some browsers lack it, and Safari fires its `cancel` event as not cancelable. Both close the dialog at once, so it vanishes with no fade.
90
+ * Ask a `<dialog>` element to close, the same way as the Escape key.
91
+ * - Fires a cancelable `cancel` event, so a `<Dialog>` keeps itself open and calls its `onClose`. Its parent then unmounts it, and it can animate out.
92
+ * - Closes the dialog at once only if nothing cancels the event.
93
+ * - Use it instead of `dialog.close()`, which closes at once and fires no `cancel` event, so the dialog vanishes with no transition.
94
+ * - Not `requestClose()`: some browsers lack it, and Safari fires its `cancel` event as not cancelable. Both close the dialog at once.
95
+ *
96
+ * @param dialog The `<dialog>` element to close.
97
+ * @example requestDialogClose(dialog) // Like pressing Escape.
98
+ * @see https://shelving.cc/ui/requestDialogClose
92
99
  */
93
- function _requestClose(dialog: HTMLDialogElement): void {
100
+ export function requestDialogClose(dialog: HTMLDialogElement): void {
94
101
  if (dialog.dispatchEvent(new Event("cancel", { cancelable: true }))) dialog.close();
95
102
  }
96
103
 
@@ -129,5 +136,5 @@ export function DialogCloseButton({
129
136
 
130
137
  function _closeOnButtonClick({ currentTarget }: MouseEvent<HTMLButtonElement>): void {
131
138
  const dialog = currentTarget.closest("dialog");
132
- if (dialog) _requestClose(dialog);
139
+ if (dialog) requestDialogClose(dialog);
133
140
  }
@@ -14,7 +14,7 @@ The panel inside a `<Dialog>`. `<Dialog>` dims the page; `Modal` gives the conte
14
14
  - The `radius` variant sets the corner radius. On a pinned panel, corners that touch a screen edge stay square.
15
15
  - It has a `--shadow-large` drop shadow by default. Set `shadow="none"`, `shadow="small"` or `shadow="normal"` to change it, the same as on `<Card>`.
16
16
  - Set `top`, `right`, `bottom`, or `left` to pin the panel to that edge of the screen. A top or bottom panel is full width up to `--modal-width`, and centred on a wider screen. A left or right panel is full height. Use these for mobile menus, bottom sheets, and side menus.
17
- - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place.
17
+ - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place. `Modal` has no transition of its own: it animates only when its `<Dialog>` does (see `Dialog`).
18
18
 
19
19
  ## Usage
20
20
 
package/ui/form/Form.js CHANGED
@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
2
2
  import { useInstance } from "../../react/useInstance.js";
3
3
  import { useStore } from "../../react/useStore.js";
4
4
  import { isAsync } from "../../util/async.js";
5
+ import { requestDialogClose } from "../dialog/Dialog.js";
5
6
  import { getBlockClass } from "../style/Block.js";
6
7
  import { getClass } from "../util/css.js";
7
8
  import { notifySuccess, notifyThrown } from "../util/notice.js";
@@ -21,9 +22,9 @@ export function Form({ schema, data: initialData, onSubmit, submit, messages, cl
21
22
  const dialog = form.closest("dialog");
22
23
  // Submit the form to the callback.
23
24
  const result = await store.submit(callNotifiedForm, store, form, onSubmit, e);
24
- // Close the parent dialog on successful submit.
25
- if (result)
26
- dialog?.close();
25
+ // Close the parent dialog on successful submit, through its `cancel` event so a `<Dialog>` can animate out.
26
+ if (result && dialog)
27
+ requestDialogClose(dialog);
27
28
  }, className: getClass(getBlockClass(props), className), noValidate: true, children: _jsx("fieldset", { className: getBlockClass({}), disabled: busy, children: _jsx(FormContext, { value: store, children: children }) }) }, store.key));
28
29
  }
29
30
  /**
package/ui/form/Form.md CHANGED
@@ -7,7 +7,7 @@ The entry point for shelving forms. `Form` creates a `FormStore` from a `schema`
7
7
  - If you provide no `children`, `Form` renders `<FormFields>` (one auto-input per schema property) followed by `<FormFooter>` (submit button + error message), so a usable form is one prop away.
8
8
  - Pass `data` to pre-populate an edit form. Pass `messages` (a string or dictionary) to seed initial field errors — useful when a server returns validation failures.
9
9
  - The whole `<fieldset>` is disabled while a submit is in flight, so inputs and buttons lock automatically.
10
- - A successful submit inside a `<dialog>` closes the dialog automatically.
10
+ - A successful submit inside a `<dialog>` closes the dialog automatically, through `requestDialogClose()`, so a `<Dialog>` can animate out.
11
11
  - Notices are surfaced from the `onSubmit` return/throw — see [Notices and error surfacing](#notices-and-error-surfacing) below.
12
12
 
13
13
  ## Usage
package/ui/form/Form.tsx CHANGED
@@ -6,6 +6,7 @@ import { isAsync } from "../../util/async.js";
6
6
  import type { Data, PartialData } from "../../util/data.js";
7
7
  import type { ImmutableDictionary } from "../../util/dictionary.js";
8
8
  import type { Arguments } from "../../util/function.js";
9
+ import { requestDialogClose } from "../dialog/Dialog.js";
9
10
  import { type BlockVariants, getBlockClass } from "../style/Block.js";
10
11
  import { getClass } from "../util/css.js";
11
12
  import { type NoticeCallback, notifySuccess, notifyThrown } from "../util/notice.js";
@@ -89,8 +90,8 @@ export function Form({
89
90
  // Submit the form to the callback.
90
91
  const result = await store.submit(callNotifiedForm, store, form, onSubmit, e);
91
92
 
92
- // Close the parent dialog on successful submit.
93
- if (result) dialog?.close();
93
+ // Close the parent dialog on successful submit, through its `cancel` event so a `<Dialog>` can animate out.
94
+ if (result && dialog) requestDialogClose(dialog);
94
95
  }}
95
96
  className={getClass(getBlockClass(props), className)}
96
97
  noValidate={true}
@@ -8,7 +8,7 @@ Renders the global list of active notices and subscribes to incoming `"notice"`
8
8
  - Notices auto-dismiss after a short delay unless they carry a `"loading"` status.
9
9
  - Backed by the `NOTICES` store singleton; for advanced use you can keep a reference to a notice to update or close it manually.
10
10
  - The list shows in the bottom-right corner. Set `position` to `"top-left"`, `"top-center"`, `"top-right"`, `"bottom-left"`, `"bottom-center"`, or `"bottom-right"` to choose a different place.
11
- - Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
11
+ - Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). `Notices` renders the store inside transitions, so a notice animates with no `startTransition()` of your own. A single `<Notice>` knows nothing about transitions, the same as `<Dialog>`. A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
12
12
  - With reduced motion, notices fade in and out in place, and the others move at once. A browser without view transitions shows the changes at once.
13
13
 
14
14
  ## Usage
@@ -44,7 +44,7 @@
44
44
 
45
45
  /*
46
46
  * A new notice slides in from the side of its corner (or from the edge for a centred list), and a closed notice slides out the same way.
47
- * - `:only-child` stops Safari from also starting the animation on the missing image, which stops it later on the real one (see `FadeTransition.css`).
47
+ * - `:only-child` stops Safari from also starting the animation on the missing image, which stops it later on the real one (see `FadeTransition.module.css`).
48
48
  * - Longhands, not the `animation` shorthand: Bun rewrites `animation-name` to the hashed keyframes name but leaves a shorthand that holds a `var()` untouched.
49
49
  */
50
50
  ::view-transition-new(.notice-left):only-child {
@@ -1,6 +1,14 @@
1
1
  import type { ReactElement } from "react";
2
- import "./FadeTransition.css";
3
2
  import { type TransitionProps } from "./Transition.js";
3
+ /**
4
+ * View transition class that fades content in and out.
5
+ *
6
+ * - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
7
+ * - Also adds the plain global `fade` class, so app CSS can target it with `::view-transition-group(.fade)`.
8
+ *
9
+ * @see https://shelving.cc/ui/FADE_TRANSITION_CLASS
10
+ */
11
+ export declare const FADE_TRANSITION_CLASS: string;
4
12
  /**
5
13
  * Props for the `FadeTransition` component — the shared transition variant props.
6
14
  *
@@ -1,6 +1,16 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
- import "./FadeTransition.css";
2
+ import { getClass, getModuleClass } from "../util/css.js";
3
+ import FADE_TRANSITION_CSS from "./FadeTransition.module.css";
3
4
  import { Transition } from "./Transition.js";
5
+ /**
6
+ * View transition class that fades content in and out.
7
+ *
8
+ * - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
9
+ * - Also adds the plain global `fade` class, so app CSS can target it with `::view-transition-group(.fade)`.
10
+ *
11
+ * @see https://shelving.cc/ui/FADE_TRANSITION_CLASS
12
+ */
13
+ export const FADE_TRANSITION_CLASS = getClass("fade", getModuleClass(FADE_TRANSITION_CSS, "fade"));
4
14
  /**
5
15
  * Transition that fades its children in and out by animating their opacity.
6
16
  *
@@ -8,5 +18,5 @@ import { Transition } from "./Transition.js";
8
18
  * @see https://shelving.cc/ui/FadeTransition
9
19
  */
10
20
  export function FadeTransition(props) {
11
- return _jsx(Transition, { default: "fade", ...props });
21
+ return _jsx(Transition, { default: FADE_TRANSITION_CLASS, ...props });
12
22
  }
@@ -22,6 +22,19 @@ function Panel({ visible }: { visible: boolean }) {
22
22
  }
23
23
  ```
24
24
 
25
+ ## Use the class without the component
26
+
27
+ The CSS is a CSS module, so its class names are hashed. To use the same animation on your own `<ViewTransition>`, import `FADE_TRANSITION_CLASS`. Each one also holds a plain global class name, so your CSS can still target it.
28
+
29
+ ```tsx
30
+ import { ViewTransition } from "react";
31
+ import { FADE_TRANSITION_CLASS } from "shelving/ui";
32
+
33
+ <ViewTransition enter={FADE_TRANSITION_CLASS} exit={FADE_TRANSITION_CLASS}>
34
+ <div className="panel">…</div>
35
+ </ViewTransition>
36
+ ```
37
+
25
38
  ## Styling
26
39
 
27
40
  | Variable | Styles | Default |
@@ -21,13 +21,20 @@
21
21
  /*
22
22
  * Enter and exit: an image with no partner fades in or out.
23
23
  * - `:only-child` is necessary. Without it, Safari also starts the animation on the missing image (for example `fade-out` on the old image when the element enters). Then it does not start that animation again on the same image name, so the element does not fade out when it leaves.
24
+ * - Longhands, not the `animation` shorthand: Bun rewrites `animation-name` to the hashed keyframes name but leaves a shorthand that holds a `var()` untouched.
24
25
  */
25
26
  ::view-transition-new(.fade):only-child {
26
- animation: fade-in var(--fade-transition-duration, var(--duration-fast)) ease-in-out both;
27
+ animation-name: fade-in;
28
+ animation-duration: var(--fade-transition-duration, var(--duration-fast));
29
+ animation-timing-function: ease-in-out;
30
+ animation-fill-mode: both;
27
31
  }
28
32
 
29
33
  ::view-transition-old(.fade):only-child {
30
- animation: fade-out var(--fade-transition-duration, var(--duration-fast)) ease-in-out both;
34
+ animation-name: fade-out;
35
+ animation-duration: var(--fade-transition-duration, var(--duration-fast));
36
+ animation-timing-function: ease-in-out;
37
+ animation-fill-mode: both;
31
38
  }
32
39
 
33
40
  /* Update: the old and new images use the browser's own crossfade. Its images take their duration from the group. */
@@ -1,7 +1,18 @@
1
1
  import type { ReactElement } from "react";
2
- import "./FadeTransition.css";
2
+ import { getClass, getModuleClass } from "../util/css.js";
3
+ import FADE_TRANSITION_CSS from "./FadeTransition.module.css";
3
4
  import { Transition, type TransitionProps } from "./Transition.js";
4
5
 
6
+ /**
7
+ * View transition class that fades content in and out.
8
+ *
9
+ * - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
10
+ * - Also adds the plain global `fade` class, so app CSS can target it with `::view-transition-group(.fade)`.
11
+ *
12
+ * @see https://shelving.cc/ui/FADE_TRANSITION_CLASS
13
+ */
14
+ export const FADE_TRANSITION_CLASS = getClass("fade", getModuleClass(FADE_TRANSITION_CSS, "fade"));
15
+
5
16
  /**
6
17
  * Props for the `FadeTransition` component — the shared transition variant props.
7
18
  *
@@ -16,5 +27,5 @@ export interface FadeTransitionProps extends TransitionProps {}
16
27
  * @see https://shelving.cc/ui/FadeTransition
17
28
  */
18
29
  export function FadeTransition(props: FadeTransitionProps): ReactElement {
19
- return <Transition default="fade" {...props} />;
30
+ return <Transition default={FADE_TRANSITION_CLASS} {...props} />;
20
31
  }
@@ -1,6 +1,23 @@
1
1
  import type { ReactElement } from "react";
2
- import "./HorizontalTransition.css";
3
2
  import { type TransitionProps } from "./Transition.js";
3
+ /**
4
+ * View transition class that slides content right: the new content comes in from the right and the old content leaves to the left.
5
+ *
6
+ * - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
7
+ * - Also adds the plain global `slide-right` class, so app CSS can target it with `::view-transition-group(.slide-right)`.
8
+ *
9
+ * @see https://shelving.cc/ui/SLIDE_RIGHT_TRANSITION_CLASS
10
+ */
11
+ export declare const SLIDE_RIGHT_TRANSITION_CLASS: string;
12
+ /**
13
+ * View transition class that slides content left: the new content comes in from the left and the old content leaves to the right.
14
+ *
15
+ * - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
16
+ * - Also adds the plain global `slide-left` class, so app CSS can target it with `::view-transition-group(.slide-left)`.
17
+ *
18
+ * @see https://shelving.cc/ui/SLIDE_LEFT_TRANSITION_CLASS
19
+ */
20
+ export declare const SLIDE_LEFT_TRANSITION_CLASS: string;
4
21
  /**
5
22
  * Props for the `HorizontalTransition` component — the shared transition variant props.
6
23
  *
@@ -1,6 +1,25 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
- import "./HorizontalTransition.css";
2
+ import { getClass, getModuleClass } from "../util/css.js";
3
+ import HORIZONTAL_TRANSITION_CSS from "./HorizontalTransition.module.css";
3
4
  import { Transition } from "./Transition.js";
5
+ /**
6
+ * View transition class that slides content right: the new content comes in from the right and the old content leaves to the left.
7
+ *
8
+ * - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
9
+ * - Also adds the plain global `slide-right` class, so app CSS can target it with `::view-transition-group(.slide-right)`.
10
+ *
11
+ * @see https://shelving.cc/ui/SLIDE_RIGHT_TRANSITION_CLASS
12
+ */
13
+ export const SLIDE_RIGHT_TRANSITION_CLASS = getClass("slide-right", getModuleClass(HORIZONTAL_TRANSITION_CSS, "slide-right"));
14
+ /**
15
+ * View transition class that slides content left: the new content comes in from the left and the old content leaves to the right.
16
+ *
17
+ * - Pass it to React's `<ViewTransition>` (for example `enter` or `exit`) to use this animation without the component.
18
+ * - Also adds the plain global `slide-left` class, so app CSS can target it with `::view-transition-group(.slide-left)`.
19
+ *
20
+ * @see https://shelving.cc/ui/SLIDE_LEFT_TRANSITION_CLASS
21
+ */
22
+ export const SLIDE_LEFT_TRANSITION_CLASS = getClass("slide-left", getModuleClass(HORIZONTAL_TRANSITION_CSS, "slide-left"));
4
23
  /**
5
24
  * Transition that slides its children horizontally — right when moving forward, left when moving back.
6
25
  *
@@ -8,5 +27,5 @@ import { Transition } from "./Transition.js";
8
27
  * @see https://shelving.cc/ui/HorizontalTransition
9
28
  */
10
29
  export function HorizontalTransition(props) {
11
- return _jsx(Transition, { default: "slide-right", forward: "slide-right", back: "slide-left", ...props });
30
+ return (_jsx(Transition, { default: SLIDE_RIGHT_TRANSITION_CLASS, forward: SLIDE_RIGHT_TRANSITION_CLASS, back: SLIDE_LEFT_TRANSITION_CLASS, ...props }));
12
31
  }
@@ -9,12 +9,15 @@ A direction-aware `<Transition>` preset that slides its children horizontally
9
9
  - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
10
10
  - The old and new content slide a full width apart, so they sit edge to edge and never overlap.
11
11
  - The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
12
- - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
12
+ - During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and raise its group:
13
13
 
14
14
  ```css
15
- ::view-transition-group(.slide-right),
16
- ::view-transition-group(.slide-left) {
17
- z-index: -1;
15
+ .bottom-bar {
16
+ view-transition-name: bottom-bar;
17
+ }
18
+
19
+ ::view-transition-group(bottom-bar) {
20
+ z-index: 1;
18
21
  }
19
22
  ```
20
23
 
@@ -33,6 +36,19 @@ import { HorizontalTransition, Navigation, Router } from "shelving/ui";
33
36
  </Navigation>
34
37
  ```
35
38
 
39
+ ## Use the class without the component
40
+
41
+ The CSS is a CSS module, so its class names are hashed. To use the same animation on your own `<ViewTransition>`, import `SLIDE_RIGHT_TRANSITION_CLASS` and `SLIDE_LEFT_TRANSITION_CLASS`. Each one also holds a plain global class name, so your CSS can still target it.
42
+
43
+ ```tsx
44
+ import { ViewTransition } from "react";
45
+ import { SLIDE_RIGHT_TRANSITION_CLASS } from "shelving/ui";
46
+
47
+ <ViewTransition enter={SLIDE_RIGHT_TRANSITION_CLASS} exit={SLIDE_RIGHT_TRANSITION_CLASS}>
48
+ <div className="panel">…</div>
49
+ </ViewTransition>
50
+ ```
51
+
36
52
  ## Styling
37
53
 
38
54
  | Variable | Styles | Default |