shelving 1.326.0 → 1.327.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.
@@ -20468,7 +20468,7 @@ The components below are listed in the index following this page; this is the sh
20468
20468
  - [Clickable](ui/Clickable.md): Render an <a href="">, a <button>, or a plain <span>, from the href, onClick and disabled props.
20469
20469
  - [FullscreenButton](ui/FullscreenButton.md): Button to toggle the surrounding <figure> element or <body> element in/out of fullscreen mode.
20470
20470
  - [RetryButton](ui/RetryButton.md): Button that retries the nearest <Catcher> error boundary when clicked.
20471
- - [Dialog](ui/Dialog.md): Modal <dialog> element that opens on mount and includes a close button.
20471
+ - [Dialog](ui/Dialog.md): Modal <dialog> element that opens on mount.
20472
20472
  - [DialogCloseButton](ui/DialogCloseButton.md): Button that closes its wrapping <dialog>, showing an X icon by default.
20473
20473
  - [DialogsContext](ui/DialogsContext.md): Provider that creates a fresh DialogsStore and shares it with its subtree.
20474
20474
  - [Dialogs](ui/Dialogs.md): Render the open dialogs from the current DialogsContext.
@@ -20646,7 +20646,6 @@ The components below are listed in the index following this page; this is the sh
20646
20646
  - [getStrokeClass()](ui/getStrokeClass.md): Get the border-thickness class for a component from its stroke variant prop.
20647
20647
  - [getTypographyClass()](ui/getTypographyClass.md): Get the typography class for a component from its typographic variant props.
20648
20648
  - [getWidthClass()](ui/getWidthClass.md): Get the width class for a component from its width / grow variant props.
20649
- - [useTransitionValue()](ui/useTransitionValue.md): Read a store's value, and re-render inside startTransition() when it changes, so <ViewTransition> boundaries animate.
20650
20649
  - [setTransitionType()](ui/setTransitionType.md): Type-safe passthrough for React's addTransitionType() that checks type is one of our known view-transition types.
20651
20650
  - [useTreeMap()](ui/useTreeMap.md): Use the flattened tree lookup map from context.
20652
20651
  - [getTreeElement()](ui/getTreeElement.md): Resolve a reference string to its tree element — by exact key first, then by a normalised key with the prose display decorations stripped.
@@ -24057,9 +24056,10 @@ Props for `<Dialog>` — optional `children` content and an `onClose` callback.
24057
24056
  - Kind: component
24058
24057
  - Import: `import { Dialog } from "shelving/ui";`
24059
24058
 
24060
- Modal `<dialog>` element that opens on mount and includes a close button.
24059
+ Modal `<dialog>` element that opens on mount.
24061
24060
 
24062
- - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
24061
+ - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, or the Escape key.
24062
+ - It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>`.
24063
24063
  - 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.
24064
24064
  - 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.
24065
24065
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
@@ -24067,11 +24067,12 @@ Modal `<dialog>` element that opens on mount and includes a close button.
24067
24067
  - 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.
24068
24068
  - Wraps content in `<Suspense>` so lazy children can stream in.
24069
24069
 
24070
- A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted and includes a built-in close button, so it works equally well mounted declaratively in the tree or pushed imperatively through a `DialogsStore`.
24070
+ A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted, so it works equally well mounted declaratively in the tree or pushed imperatively through a `DialogsStore`.
24071
24071
 
24072
24072
  **Things to know:**
24073
24073
 
24074
- - Closes on a tap anywhere on it, the Escape key, or the built-in `<DialogCloseButton>` (an X icon, top-right).
24074
+ - Closes on a tap anywhere on it, or the Escape key.
24075
+ - It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>` anywhere inside it. That button is an X icon fixed to the top-right corner.
24075
24076
  - A tap on a control (`<button>`, `<input>`, `<select>`, `<textarea>`, `<label>`) does not close it. A tap anywhere inside a `<Modal>` panel does not close it either, so a form in a `<Modal>` is safe. A tap on a link or a `<nav>` button always closes it.
24076
24077
  - Children render inside a `<Suspense>` boundary, so lazy content can stream in.
24077
24078
  - 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.
@@ -24150,7 +24151,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
24150
24151
 
24151
24152
  ## Styling
24152
24153
 
24153
- `Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. Transparent borders as wide as the screen's safe areas keep the content and the close button clear of the notch, rounded corners and home bar. The inner panel comes from its children, usually `<Modal>`. Override these hooks at `:root` (or any ancestor scope) to retheme.
24154
+ `Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. Transparent borders as wide as the screen's safe areas keep the content and any `<DialogCloseButton>` clear of the notch, rounded corners and home bar. The inner panel comes from its children, usually `<Modal>`. Override these hooks at `:root` (or any ancestor scope) to retheme.
24154
24155
 
24155
24156
  | Variable | Styles | Default |
24156
24157
  | ----------------------- | -------------------------------------------------------------- | ----------------------------- |
@@ -24159,7 +24160,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
24159
24160
  | `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
24160
24161
  | `--dialog-background` | Overlay fill behind the content | `var(--color-backdrop)` |
24161
24162
  | `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
24162
- | `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
24163
+ | `--dialog-close-offset` | Inset of a `<DialogCloseButton>` from the top-right corner | `var(--space-small)` (12px) |
24163
24164
 
24164
24165
  The fade uses the `fade` class from `<FadeTransition>`, so `--fade-transition-duration` sets its length. It runs only as the dialog opens and closes; an open dialog stays still while other dialogs open and close.
24165
24166
 
@@ -24224,8 +24225,10 @@ Props for `<DialogCloseButton>` — button styling variants and optional `childr
24224
24225
  - Import: `import { DialogCloseButton } from "shelving/ui";`
24225
24226
 
24226
24227
  Button that closes its wrapping `<dialog>`, showing an X icon by default.
24227
- - Styled with the shared `Button` classes (positioning comes from the `<Dialog>`'s own `.close` wrapper rules).
24228
- - `plain` by default so only the icon shows until hover or focus — pass `plain={false}` for a solid button.
24228
+ - A `<Dialog>` has no close button of its own. Put this anywhere inside the dialog to add one.
24229
+ - It is fixed to the top-right corner of the screen, clear of the safe areas.
24230
+ - Styled with the shared `Button` classes.
24231
+ - `plain` and `small` by default, so only a small icon shows until hover or focus. Pass `plain={false}` for a solid button, or `small={false}` for a normal size.
24229
24232
 
24230
24233
  ## Signatures
24231
24234
 
@@ -24233,6 +24236,7 @@ Button that closes its wrapping `<dialog>`, showing an X icon by default.
24233
24236
  DialogCloseButton({
24234
24237
  children = <CloseIcon />,
24235
24238
  plain = true,
24239
+ small = true,
24236
24240
  className,
24237
24241
  ...variants
24238
24242
  }: DialogCloseButtonProps): ReactElement
@@ -37388,38 +37392,6 @@ Transition({ children, default: d, forward = d, back = d, overlay = false }: Tra
37388
37392
  | `ReactElement` | A `<ViewTransition>` element wrapping the children. |
37389
37393
 
37390
37394
 
37391
- ---
37392
-
37393
- # useTransitionValue()
37394
-
37395
- - Kind: function
37396
- - Import: `import { useTransitionValue } from "shelving/ui";`
37397
-
37398
- Read a store's value, and re-render inside `startTransition()` when it changes, so `<ViewTransition>` boundaries animate.
37399
-
37400
- - `useStore()` uses `useSyncExternalStore()`, and React always applies those updates synchronously. A synchronous update never starts a view transition.
37401
- - This hook copies the value into React state inside `startTransition()` instead.
37402
- - Internal for now: not exported from the `shelving/ui` barrel.
37403
-
37404
- ## Signatures
37405
-
37406
- ```ts
37407
- useTransitionValue(store: S): S["value"]
37408
- ```
37409
-
37410
- ## Parameters
37411
-
37412
- | Param | Type | Description |
37413
- | --- | --- | --- |
37414
- | `store` | `S` | The store to read. Its value must not be loading or failed. |
37415
-
37416
- ## Returns
37417
-
37418
- | Type | Description |
37419
- | --- | --- |
37420
- | `S["value"]` | The store's current value. |
37421
-
37422
-
37423
37395
  ---
37424
37396
 
37425
37397
  # TransitionClasses
package/docs/ui/Dialog.md CHANGED
@@ -3,9 +3,10 @@
3
3
  - Kind: component
4
4
  - Import: `import { Dialog } from "shelving/ui";`
5
5
 
6
- Modal `<dialog>` element that opens on mount and includes a close button.
6
+ Modal `<dialog>` element that opens on mount.
7
7
 
8
- - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
8
+ - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, or the Escape key.
9
+ - It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>`.
9
10
  - 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.
10
11
  - 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.
11
12
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
@@ -13,11 +14,12 @@ Modal `<dialog>` element that opens on mount and includes a close button.
13
14
  - 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.
14
15
  - Wraps content in `<Suspense>` so lazy children can stream in.
15
16
 
16
- A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted and includes a built-in close button, so it works equally well mounted declaratively in the tree or pushed imperatively through a `DialogsStore`.
17
+ A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted, so it works equally well mounted declaratively in the tree or pushed imperatively through a `DialogsStore`.
17
18
 
18
19
  **Things to know:**
19
20
 
20
- - Closes on a tap anywhere on it, the Escape key, or the built-in `<DialogCloseButton>` (an X icon, top-right).
21
+ - Closes on a tap anywhere on it, or the Escape key.
22
+ - It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>` anywhere inside it. That button is an X icon fixed to the top-right corner.
21
23
  - A tap on a control (`<button>`, `<input>`, `<select>`, `<textarea>`, `<label>`) does not close it. A tap anywhere inside a `<Modal>` panel does not close it either, so a form in a `<Modal>` is safe. A tap on a link or a `<nav>` button always closes it.
22
24
  - Children render inside a `<Suspense>` boundary, so lazy content can stream in.
23
25
  - 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.
@@ -96,7 +98,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
96
98
 
97
99
  ## Styling
98
100
 
99
- `Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. Transparent borders as wide as the screen's safe areas keep the content and the close button clear of the notch, rounded corners and home bar. The inner panel comes from its children, usually `<Modal>`. Override these hooks at `:root` (or any ancestor scope) to retheme.
101
+ `Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. Transparent borders as wide as the screen's safe areas keep the content and any `<DialogCloseButton>` clear of the notch, rounded corners and home bar. The inner panel comes from its children, usually `<Modal>`. Override these hooks at `:root` (or any ancestor scope) to retheme.
100
102
 
101
103
  | Variable | Styles | Default |
102
104
  | ----------------------- | -------------------------------------------------------------- | ----------------------------- |
@@ -105,7 +107,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
105
107
  | `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
106
108
  | `--dialog-background` | Overlay fill behind the content | `var(--color-backdrop)` |
107
109
  | `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
108
- | `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
110
+ | `--dialog-close-offset` | Inset of a `<DialogCloseButton>` from the top-right corner | `var(--space-small)` (12px) |
109
111
 
110
112
  The fade uses the `fade` class from `<FadeTransition>`, so `--fade-transition-duration` sets its length. It runs only as the dialog opens and closes; an open dialog stays still while other dialogs open and close.
111
113
 
@@ -4,8 +4,10 @@
4
4
  - Import: `import { DialogCloseButton } from "shelving/ui";`
5
5
 
6
6
  Button that closes its wrapping `<dialog>`, showing an X icon by default.
7
- - Styled with the shared `Button` classes (positioning comes from the `<Dialog>`'s own `.close` wrapper rules).
8
- - `plain` by default so only the icon shows until hover or focus — pass `plain={false}` for a solid button.
7
+ - A `<Dialog>` has no close button of its own. Put this anywhere inside the dialog to add one.
8
+ - It is fixed to the top-right corner of the screen, clear of the safe areas.
9
+ - Styled with the shared `Button` classes.
10
+ - `plain` and `small` by default, so only a small icon shows until hover or focus. Pass `plain={false}` for a solid button, or `small={false}` for a normal size.
9
11
 
10
12
  ## Signatures
11
13
 
@@ -13,6 +15,7 @@ Button that closes its wrapping `<dialog>`, showing an X icon by default.
13
15
  DialogCloseButton({
14
16
  children = <CloseIcon />,
15
17
  plain = true,
18
+ small = true,
16
19
  className,
17
20
  ...variants
18
21
  }: DialogCloseButtonProps): ReactElement
package/docs/ui.md CHANGED
@@ -105,7 +105,7 @@ The components below are listed in the index following this page; this is the sh
105
105
  - [Clickable](ui/Clickable.md): Render an <a href="">, a <button>, or a plain <span>, from the href, onClick and disabled props.
106
106
  - [FullscreenButton](ui/FullscreenButton.md): Button to toggle the surrounding <figure> element or <body> element in/out of fullscreen mode.
107
107
  - [RetryButton](ui/RetryButton.md): Button that retries the nearest <Catcher> error boundary when clicked.
108
- - [Dialog](ui/Dialog.md): Modal <dialog> element that opens on mount and includes a close button.
108
+ - [Dialog](ui/Dialog.md): Modal <dialog> element that opens on mount.
109
109
  - [DialogCloseButton](ui/DialogCloseButton.md): Button that closes its wrapping <dialog>, showing an X icon by default.
110
110
  - [DialogsContext](ui/DialogsContext.md): Provider that creates a fresh DialogsStore and shares it with its subtree.
111
111
  - [Dialogs](ui/Dialogs.md): Render the open dialogs from the current DialogsContext.
@@ -283,7 +283,6 @@ The components below are listed in the index following this page; this is the sh
283
283
  - [getStrokeClass()](ui/getStrokeClass.md): Get the border-thickness class for a component from its stroke variant prop.
284
284
  - [getTypographyClass()](ui/getTypographyClass.md): Get the typography class for a component from its typographic variant props.
285
285
  - [getWidthClass()](ui/getWidthClass.md): Get the width class for a component from its width / grow variant props.
286
- - [useTransitionValue()](ui/useTransitionValue.md): Read a store's value, and re-render inside startTransition() when it changes, so <ViewTransition> boundaries animate.
287
286
  - [setTransitionType()](ui/setTransitionType.md): Type-safe passthrough for React's addTransitionType() that checks type is one of our known view-transition types.
288
287
  - [useTreeMap()](ui/useTreeMap.md): Use the flattened tree lookup map from context.
289
288
  - [getTreeElement()](ui/getTreeElement.md): Resolve a reference string to its tree element — by exact key first, then by a normalised key with the prose display decorations stripped.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.326.0",
3
+ "version": "1.327.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -12,9 +12,10 @@ export interface DialogProps extends OptionalChildProps {
12
12
  onClose?: Callback;
13
13
  }
14
14
  /**
15
- * Modal `<dialog>` element that opens on mount and includes a close button.
15
+ * Modal `<dialog>` element that opens on mount.
16
16
  *
17
- * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
17
+ * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, or the Escape key.
18
+ * - It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>`.
18
19
  * - 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.
19
20
  * - 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.
20
21
  * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
@@ -47,10 +48,12 @@ export interface DialogCloseButtonProps extends ButtonVariants, OptionalChildPro
47
48
  }
48
49
  /**
49
50
  * Button that closes its wrapping `<dialog>`, showing an X icon by default.
50
- * - Styled with the shared `Button` classes (positioning comes from the `<Dialog>`'s own `.close` wrapper rules).
51
- * - `plain` by default so only the icon shows until hover or focus — pass `plain={false}` for a solid button.
51
+ * - A `<Dialog>` has no close button of its own. Put this anywhere inside the dialog to add one.
52
+ * - It is fixed to the top-right corner of the screen, clear of the safe areas.
53
+ * - Styled with the shared `Button` classes.
54
+ * - `plain` and `small` by default, so only a small icon shows until hover or focus. Pass `plain={false}` for a solid button, or `small={false}` for a normal size.
52
55
  *
53
56
  * @kind component
54
57
  * @see https://shelving.cc/ui/DialogCloseButton
55
58
  */
56
- export declare function DialogCloseButton({ children, plain, className, ...variants }: DialogCloseButtonProps): ReactElement;
59
+ export declare function DialogCloseButton({ children, plain, small, className, ...variants }: DialogCloseButtonProps): ReactElement;
@@ -1,4 +1,4 @@
1
- import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { memo, Suspense, ViewTransition } from "react";
3
3
  import { CloseIcon } from "shelving/icon/CloseIcon";
4
4
  import { getButtonClass } from "../button/Button.js";
@@ -7,9 +7,10 @@ import { getClass, getModuleClass } from "../util/css.js";
7
7
  import styles from "./Dialog.module.css";
8
8
  import modalStyles from "./Modal.module.css";
9
9
  /**
10
- * Modal `<dialog>` element that opens on mount and includes a close button.
10
+ * Modal `<dialog>` element that opens on mount.
11
11
  *
12
- * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
12
+ * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, or the Escape key.
13
+ * - It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>`.
13
14
  * - 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
15
  * - 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
16
  * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
@@ -21,13 +22,13 @@ import modalStyles from "./Modal.module.css";
21
22
  * @see https://shelving.cc/ui/Dialog
22
23
  */
23
24
  export const Dialog = memo(({ children, onClose, ...props }) => {
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
+ return (_jsx(Suspense, { fallback: null, children: _jsx(ViewTransition, { default: "none", enter: FADE_TRANSITION_CLASS, exit: FADE_TRANSITION_CLASS, children: _jsx("dialog", { ref: _showModal, className: getModuleClass(styles, "dialog"), onClick: _closeOnClick, onCancel: e => {
25
26
  // Keep the dialog open until the parent unmounts it. An uncancelable request closes natively and fires `onClose` from the `close` event.
26
27
  if (!onClose || !e.cancelable)
27
28
  return;
28
29
  e.preventDefault();
29
30
  onClose();
30
- }, onClose: onClose, ...props, children: [_jsx("div", { className: getModuleClass(styles, "content"), children: children }), _jsx("div", { className: getModuleClass(styles, "close"), children: _jsx(DialogCloseButton, {}) })] }) }) }));
31
+ }, onClose: onClose, ...props, children: _jsx("div", { className: getModuleClass(styles, "content"), children: children }) }) }) }));
31
32
  });
32
33
  /**
33
34
  * Open a `<dialog>` as a modal when React attaches it.
@@ -69,14 +70,16 @@ export function requestDialogClose(dialog) {
69
70
  }
70
71
  /**
71
72
  * Button that closes its wrapping `<dialog>`, showing an X icon by default.
72
- * - Styled with the shared `Button` classes (positioning comes from the `<Dialog>`'s own `.close` wrapper rules).
73
- * - `plain` by default so only the icon shows until hover or focus — pass `plain={false}` for a solid button.
73
+ * - A `<Dialog>` has no close button of its own. Put this anywhere inside the dialog to add one.
74
+ * - It is fixed to the top-right corner of the screen, clear of the safe areas.
75
+ * - Styled with the shared `Button` classes.
76
+ * - `plain` and `small` by default, so only a small icon shows until hover or focus. Pass `plain={false}` for a solid button, or `small={false}` for a normal size.
74
77
  *
75
78
  * @kind component
76
79
  * @see https://shelving.cc/ui/DialogCloseButton
77
80
  */
78
- export function DialogCloseButton({ children = _jsx(CloseIcon, {}), plain = true, className, ...variants }) {
79
- return (_jsx("button", { type: "button", title: "Close", className: getClass(getButtonClass({ plain, ...variants }), className), onClick: _closeOnButtonClick, children: children }));
81
+ export function DialogCloseButton({ children = _jsx(CloseIcon, {}), plain = true, small = true, className, ...variants }) {
82
+ return (_jsx("button", { type: "button", title: "Close", className: getClass(getModuleClass(styles, "close"), getButtonClass({ plain, small, ...variants }), className), onClick: _closeOnButtonClick, children: children }));
80
83
  }
81
84
  function _closeOnButtonClick({ currentTarget }) {
82
85
  const dialog = currentTarget.closest("dialog");
@@ -1,10 +1,11 @@
1
1
  # Dialog
2
2
 
3
- A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted and includes a built-in close button, so it works equally well mounted declaratively in the tree or pushed imperatively through a `DialogsStore`.
3
+ A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted, so it works equally well mounted declaratively in the tree or pushed imperatively through a `DialogsStore`.
4
4
 
5
5
  **Things to know:**
6
6
 
7
- - Closes on a tap anywhere on it, the Escape key, or the built-in `<DialogCloseButton>` (an X icon, top-right).
7
+ - Closes on a tap anywhere on it, or the Escape key.
8
+ - It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>` anywhere inside it. That button is an X icon fixed to the top-right corner.
8
9
  - A tap on a control (`<button>`, `<input>`, `<select>`, `<textarea>`, `<label>`) does not close it. A tap anywhere inside a `<Modal>` panel does not close it either, so a form in a `<Modal>` is safe. A tap on a link or a `<nav>` button always closes it.
9
10
  - Children render inside a `<Suspense>` boundary, so lazy content can stream in.
10
11
  - 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.
@@ -83,7 +84,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
83
84
 
84
85
  ## Styling
85
86
 
86
- `Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. Transparent borders as wide as the screen's safe areas keep the content and the close button clear of the notch, rounded corners and home bar. The inner panel comes from its children, usually `<Modal>`. Override these hooks at `:root` (or any ancestor scope) to retheme.
87
+ `Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. Transparent borders as wide as the screen's safe areas keep the content and any `<DialogCloseButton>` clear of the notch, rounded corners and home bar. The inner panel comes from its children, usually `<Modal>`. Override these hooks at `:root` (or any ancestor scope) to retheme.
87
88
 
88
89
  | Variable | Styles | Default |
89
90
  | ----------------------- | -------------------------------------------------------------- | ----------------------------- |
@@ -92,7 +93,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
92
93
  | `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
93
94
  | `--dialog-background` | Overlay fill behind the content | `var(--color-backdrop)` |
94
95
  | `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
95
- | `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
96
+ | `--dialog-close-offset` | Inset of a `<DialogCloseButton>` from the top-right corner | `var(--space-small)` (12px) |
96
97
 
97
98
  The fade uses the `fade` class from `<FadeTransition>`, so `--fade-transition-duration` sets its length. It runs only as the dialog opens and closes; an open dialog stays still while other dialogs open and close.
98
99
 
@@ -55,7 +55,7 @@
55
55
  /*
56
56
  * The children, in normal block layout, `--dialog-width` wide.
57
57
  * - `margin: auto` centres it on both axes. When it is taller than the screen, the margins drop to 0, so it starts at the top and the dialog scrolls. (`align-items: center` would push the top out of reach.)
58
- * - A pinned `<Modal>` and the close button are `position: fixed`, so this wrapper does not affect them.
58
+ * - A pinned `<Modal>` and a `<DialogCloseButton>` are `position: fixed`, so this wrapper does not affect them.
59
59
  */
60
60
  .content {
61
61
  margin: auto;
@@ -19,9 +19,10 @@ export interface DialogProps extends OptionalChildProps {
19
19
  }
20
20
 
21
21
  /**
22
- * Modal `<dialog>` element that opens on mount and includes a close button.
22
+ * Modal `<dialog>` element that opens on mount.
23
23
  *
24
- * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
24
+ * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, or the Escape key.
25
+ * - It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>`.
25
26
  * - 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
27
  * - 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
28
  * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
@@ -52,9 +53,6 @@ export const Dialog = memo(({ children, onClose, ...props }: DialogProps) => {
52
53
  {...props}
53
54
  >
54
55
  <div className={getModuleClass(styles, "content")}>{children}</div>
55
- <div className={getModuleClass(styles, "close")}>
56
- <DialogCloseButton />
57
- </div>
58
56
  </dialog>
59
57
  </ViewTransition>
60
58
  </Suspense>
@@ -110,8 +108,10 @@ export interface DialogCloseButtonProps extends ButtonVariants, OptionalChildPro
110
108
 
111
109
  /**
112
110
  * Button that closes its wrapping `<dialog>`, showing an X icon by default.
113
- * - Styled with the shared `Button` classes (positioning comes from the `<Dialog>`'s own `.close` wrapper rules).
114
- * - `plain` by default so only the icon shows until hover or focus — pass `plain={false}` for a solid button.
111
+ * - A `<Dialog>` has no close button of its own. Put this anywhere inside the dialog to add one.
112
+ * - It is fixed to the top-right corner of the screen, clear of the safe areas.
113
+ * - Styled with the shared `Button` classes.
114
+ * - `plain` and `small` by default, so only a small icon shows until hover or focus. Pass `plain={false}` for a solid button, or `small={false}` for a normal size.
115
115
  *
116
116
  * @kind component
117
117
  * @see https://shelving.cc/ui/DialogCloseButton
@@ -119,6 +119,7 @@ export interface DialogCloseButtonProps extends ButtonVariants, OptionalChildPro
119
119
  export function DialogCloseButton({
120
120
  children = <CloseIcon />,
121
121
  plain = true,
122
+ small = true,
122
123
  className,
123
124
  ...variants
124
125
  }: DialogCloseButtonProps): ReactElement {
@@ -126,7 +127,7 @@ export function DialogCloseButton({
126
127
  <button
127
128
  type="button"
128
129
  title="Close"
129
- className={getClass(getButtonClass({ plain, ...variants }), className)}
130
+ className={getClass(getModuleClass(styles, "close"), getButtonClass({ plain, small, ...variants }), className)}
130
131
  onClick={_closeOnButtonClick}
131
132
  >
132
133
  {children}
@@ -1,9 +1,9 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { createContext, use } from "react";
3
3
  import { useInstance } from "../../react/useInstance.js";
4
+ import { useSequenceTransition } from "../../react/useSequenceTransition.js";
4
5
  import { ArrayStore } from "../../store/ArrayStore.js";
5
6
  import { getRandomKey } from "../../util/random.js";
6
- import { useTransitionValue } from "../transition/useTransitionValue.js";
7
7
  import { Dialog } from "./Dialog.js";
8
8
  /**
9
9
  * Store holding the live list of open `<Dialog>` elements.
@@ -69,5 +69,6 @@ export function DialogsContext({ children }) {
69
69
  * @see https://shelving.cc/ui/Dialogs
70
70
  */
71
71
  export function Dialogs() {
72
- return useTransitionValue(requireDialogs());
72
+ const dialogs = requireDialogs();
73
+ return useSequenceTransition(dialogs, { current: () => dialogs.value, transition: "dialog" });
73
74
  }
@@ -1,8 +1,8 @@
1
1
  import { createContext, type ReactElement, type ReactNode, use } from "react";
2
2
  import { useInstance } from "../../react/useInstance.js";
3
+ import { useSequenceTransition } from "../../react/useSequenceTransition.js";
3
4
  import { ArrayStore } from "../../store/ArrayStore.js";
4
5
  import { getRandomKey } from "../../util/random.js";
5
- import { useTransitionValue } from "../transition/useTransitionValue.js";
6
6
  import type { ChildProps } from "../util/props.js";
7
7
  import { Dialog } from "./Dialog.js";
8
8
 
@@ -98,5 +98,6 @@ export function DialogsContext({ children }: DialogsContextProps): ReactElement
98
98
  * @see https://shelving.cc/ui/Dialogs
99
99
  */
100
100
  export function Dialogs(): ReactNode {
101
- return useTransitionValue(requireDialogs());
101
+ const dialogs = requireDialogs();
102
+ return useSequenceTransition(dialogs, { current: () => dialogs.value, transition: "dialog" });
102
103
  }
@@ -1,7 +1,7 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { useEffect, ViewTransition } from "react";
3
+ import { useSequenceTransition } from "../../react/useSequenceTransition.js";
3
4
  import { getFlexClass } from "../style/Flex.js";
4
- import { useTransitionValue } from "../transition/useTransitionValue.js";
5
5
  import { getClass, getModuleClass } from "../util/css.js";
6
6
  import { subscribeNotices } from "../util/notice.js";
7
7
  import { Notice } from "./Notice.js";
@@ -20,7 +20,7 @@ const NOTICES_CLASS = getModuleClass(NOTICES_CSS, "notices");
20
20
  * @see https://shelving.cc/ui/Notices
21
21
  */
22
22
  export function Notices({ position = "bottom-right", className, ...props }) {
23
- const notices = useTransitionValue(NOTICES);
23
+ const notices = useSequenceTransition(NOTICES, { current: () => NOTICES.value, transition: "notice" });
24
24
  useEffect(() => {
25
25
  // Subscribe to global notices.
26
26
  return subscribeNotices((message, status) => NOTICES.show(message, status));
@@ -33,7 +33,7 @@ export function Notices({ position = "bottom-right", className, ...props }) {
33
33
  * - Module-private, but named without the `_` prefix: React and the hooks lint rule only treat a capitalised name as a component.
34
34
  */
35
35
  function NoticeItem({ notice, position }) {
36
- const { children, status } = useTransitionValue(notice);
36
+ const { children, status } = useSequenceTransition(notice, { current: () => notice.value, transition: "notice" });
37
37
  // New and closed notices slide from the side of the corner, or from the edge when centred. A notice that changes in place is drawn from the corner itself.
38
38
  const [vertical, horizontal] = position.split("-");
39
39
  const side = horizontal === "center" ? vertical : horizontal;
@@ -1,7 +1,7 @@
1
1
  import { type ReactElement, useEffect, ViewTransition } from "react";
2
+ import { useSequenceTransition } from "../../react/useSequenceTransition.js";
2
3
  import { type FlexVariants, getFlexClass } from "../style/Flex.js";
3
4
  import type { Status } from "../style/Status.js";
4
- import { useTransitionValue } from "../transition/useTransitionValue.js";
5
5
  import { getClass, getModuleClass } from "../util/css.js";
6
6
  import { subscribeNotices } from "../util/notice.js";
7
7
  import type { ClassProps } from "../util/props.js";
@@ -44,7 +44,7 @@ export interface NoticesProps extends FlexVariants, ClassProps {
44
44
  * @see https://shelving.cc/ui/Notices
45
45
  */
46
46
  export function Notices({ position = "bottom-right", className, ...props }: NoticesProps): ReactElement {
47
- const notices = useTransitionValue(NOTICES);
47
+ const notices = useSequenceTransition(NOTICES, { current: () => NOTICES.value, transition: "notice" });
48
48
  useEffect(() => {
49
49
  // Subscribe to global notices.
50
50
  return subscribeNotices((message, status) => NOTICES.show(message, status));
@@ -64,7 +64,7 @@ export function Notices({ position = "bottom-right", className, ...props }: Noti
64
64
  * - Module-private, but named without the `_` prefix: React and the hooks lint rule only treat a capitalised name as a component.
65
65
  */
66
66
  function NoticeItem({ notice, position }: { notice: NoticeStore<Status>; position: NoticesPosition }): ReactElement {
67
- const { children, status } = useTransitionValue(notice);
67
+ const { children, status } = useSequenceTransition(notice, { current: () => notice.value, transition: "notice" });
68
68
  // New and closed notices slide from the side of the corner, or from the edge when centred. A notice that changes in place is drawn from the corner itself.
69
69
  const [vertical, horizontal] = position.split("-");
70
70
  const side = horizontal === "center" ? vertical : horizontal;
@@ -1,28 +0,0 @@
1
- # useTransitionValue()
2
-
3
- - Kind: function
4
- - Import: `import { useTransitionValue } from "shelving/ui";`
5
-
6
- Read a store's value, and re-render inside `startTransition()` when it changes, so `<ViewTransition>` boundaries animate.
7
-
8
- - `useStore()` uses `useSyncExternalStore()`, and React always applies those updates synchronously. A synchronous update never starts a view transition.
9
- - This hook copies the value into React state inside `startTransition()` instead.
10
- - Internal for now: not exported from the `shelving/ui` barrel.
11
-
12
- ## Signatures
13
-
14
- ```ts
15
- useTransitionValue(store: S): S["value"]
16
- ```
17
-
18
- ## Parameters
19
-
20
- | Param | Type | Description |
21
- | --- | --- | --- |
22
- | `store` | `S` | The store to read. Its value must not be loading or failed. |
23
-
24
- ## Returns
25
-
26
- | Type | Description |
27
- | --- | --- |
28
- | `S["value"]` | The store's current value. |
@@ -1,12 +0,0 @@
1
- import type { AnyStore } from "../../store/Store.js";
2
- /**
3
- * Read a store's value, and re-render inside `startTransition()` when it changes, so `<ViewTransition>` boundaries animate.
4
- *
5
- * - `useStore()` uses `useSyncExternalStore()`, and React always applies those updates synchronously. A synchronous update never starts a view transition.
6
- * - This hook copies the value into React state inside `startTransition()` instead.
7
- * - Internal for now: not exported from the `shelving/ui` barrel.
8
- *
9
- * @param store The store to read. Its value must not be loading or failed.
10
- * @returns The store's current value.
11
- */
12
- export declare function useTransitionValue<S extends AnyStore>(store: S): S["value"];
@@ -1,16 +0,0 @@
1
- import { startTransition, useEffect, useState } from "react";
2
- /**
3
- * Read a store's value, and re-render inside `startTransition()` when it changes, so `<ViewTransition>` boundaries animate.
4
- *
5
- * - `useStore()` uses `useSyncExternalStore()`, and React always applies those updates synchronously. A synchronous update never starts a view transition.
6
- * - This hook copies the value into React state inside `startTransition()` instead.
7
- * - Internal for now: not exported from the `shelving/ui` barrel.
8
- *
9
- * @param store The store to read. Its value must not be loading or failed.
10
- * @returns The store's current value.
11
- */
12
- export function useTransitionValue(store) {
13
- const [value, setValue] = useState(() => store.value);
14
- useEffect(() => store.subscribe((v) => startTransition(() => setValue(() => v))), [store]);
15
- return value;
16
- }
@@ -1,18 +0,0 @@
1
- import { startTransition, useEffect, useState } from "react";
2
- import type { AnyStore } from "../../store/Store.js";
3
-
4
- /**
5
- * Read a store's value, and re-render inside `startTransition()` when it changes, so `<ViewTransition>` boundaries animate.
6
- *
7
- * - `useStore()` uses `useSyncExternalStore()`, and React always applies those updates synchronously. A synchronous update never starts a view transition.
8
- * - This hook copies the value into React state inside `startTransition()` instead.
9
- * - Internal for now: not exported from the `shelving/ui` barrel.
10
- *
11
- * @param store The store to read. Its value must not be loading or failed.
12
- * @returns The store's current value.
13
- */
14
- export function useTransitionValue<S extends AnyStore>(store: S): S["value"] {
15
- const [value, setValue] = useState<S["value"]>(() => store.value);
16
- useEffect(() => store.subscribe((v: S["value"]) => startTransition(() => setValue(() => v))), [store]);
17
- return value;
18
- }