shelving 1.325.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.
@@ -20824,7 +20823,7 @@ The components below are listed in the index following this page; this is the sh
20824
20823
  - [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
20825
20824
  - [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
20826
20825
  - [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
20827
- - [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: the href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
20826
+ - [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: an optional href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
20828
20827
  - [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
20829
20828
  - [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
20830
20829
  - [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
@@ -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
@@ -33393,13 +33397,13 @@ Page({ children, ...meta }: PageProps): ReactElement
33393
33397
  - Import: `import { BackButtonProps } from "shelving/ui";`
33394
33398
  - Extends: `Omit<ButtonProps, "href" | "onClick">`
33395
33399
 
33396
- Props for `<BackButton>`: the `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
33400
+ Props for `<BackButton>`: an optional `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
33397
33401
 
33398
33402
  ## Signatures
33399
33403
 
33400
33404
  ```ts
33401
33405
  {
33402
- readonly href: AbsolutePath;
33406
+ readonly href?: AbsolutePath | undefined;
33403
33407
  }
33404
33408
  ```
33405
33409
 
@@ -33407,7 +33411,7 @@ Props for `<BackButton>`: the `href` to go back to when the stack has no page be
33407
33411
 
33408
33412
  | Property | Type | Description |
33409
33413
  | --- | --- | --- |
33410
- | `href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
33414
+ | `href` | `AbsolutePath \| undefined` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. Read only. Optional. |
33411
33415
 
33412
33416
 
33413
33417
  ---
@@ -33420,6 +33424,7 @@ Props for `<BackButton>`: the `href` to go back to when the stack has no page be
33420
33424
  Back button for the current stack.
33421
33425
  - Goes back to the page before this one in the current stack, wherever you came from.
33422
33426
  - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
33427
+ - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
33423
33428
  - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
33424
33429
 
33425
33430
  The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
@@ -33427,7 +33432,8 @@ The back button for a page header. It goes back to the page before this one in t
33427
33432
  **Things to know:**
33428
33433
 
33429
33434
  - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
33430
- - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
33435
+ - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
33436
+ - Without `href`, it renders nothing when the stack has no page before this one: for example, at the root of a stack, or on a deep link. Use this for a back button that shows only when there is somewhere to go back to.
33431
33437
  - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationSequence.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
33432
33438
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
33433
33439
  - It takes the usual `<Button>` props, except `onClick`.
@@ -33452,6 +33458,12 @@ function PostPage({ id }: { id: string }) {
33452
33458
  }
33453
33459
  ```
33454
33460
 
33461
+ Only when there is a page to go back to (nothing at the root of a stack):
33462
+
33463
+ ```tsx
33464
+ <BackButton />;
33465
+ ```
33466
+
33455
33467
  With a label:
33456
33468
 
33457
33469
  ```tsx
@@ -33474,7 +33486,7 @@ To go back to one fixed page (not to the page before), use a link with `classNam
33474
33486
  ## Signatures
33475
33487
 
33476
33488
  ```ts
33477
- BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement
33489
+ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement | null
33478
33490
  ```
33479
33491
 
33480
33492
  ## Parameters
@@ -33482,13 +33494,13 @@ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props
33482
33494
  | Param | Type | Description |
33483
33495
  | --- | --- | --- |
33484
33496
  | `props` | `BackButtonProps` | |
33485
- | `.href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
33497
+ | `.href` | `AbsolutePath \| undefined` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. Read only. Optional. |
33486
33498
 
33487
33499
  ## Returns
33488
33500
 
33489
33501
  | Type | Description |
33490
33502
  | --- | --- |
33491
- | `ReactElement` | |
33503
+ | `ReactElement \| null` | |
33492
33504
 
33493
33505
 
33494
33506
  ---
@@ -37380,38 +37392,6 @@ Transition({ children, default: d, forward = d, back = d, overlay = false }: Tra
37380
37392
  | `ReactElement` | A `<ViewTransition>` element wrapping the children. |
37381
37393
 
37382
37394
 
37383
- ---
37384
-
37385
- # useTransitionValue()
37386
-
37387
- - Kind: function
37388
- - Import: `import { useTransitionValue } from "shelving/ui";`
37389
-
37390
- Read a store's value, and re-render inside `startTransition()` when it changes, so `<ViewTransition>` boundaries animate.
37391
-
37392
- - `useStore()` uses `useSyncExternalStore()`, and React always applies those updates synchronously. A synchronous update never starts a view transition.
37393
- - This hook copies the value into React state inside `startTransition()` instead.
37394
- - Internal for now: not exported from the `shelving/ui` barrel.
37395
-
37396
- ## Signatures
37397
-
37398
- ```ts
37399
- useTransitionValue(store: S): S["value"]
37400
- ```
37401
-
37402
- ## Parameters
37403
-
37404
- | Param | Type | Description |
37405
- | --- | --- | --- |
37406
- | `store` | `S` | The store to read. Its value must not be loading or failed. |
37407
-
37408
- ## Returns
37409
-
37410
- | Type | Description |
37411
- | --- | --- |
37412
- | `S["value"]` | The store's current value. |
37413
-
37414
-
37415
37395
  ---
37416
37396
 
37417
37397
  # TransitionClasses
@@ -6,6 +6,7 @@
6
6
  Back button for the current stack.
7
7
  - Goes back to the page before this one in the current stack, wherever you came from.
8
8
  - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
9
+ - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
9
10
  - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
10
11
 
11
12
  The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
@@ -13,7 +14,8 @@ The back button for a page header. It goes back to the page before this one in t
13
14
  **Things to know:**
14
15
 
15
16
  - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
16
- - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
17
+ - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
18
+ - Without `href`, it renders nothing when the stack has no page before this one: for example, at the root of a stack, or on a deep link. Use this for a back button that shows only when there is somewhere to go back to.
17
19
  - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationSequence.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
18
20
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
19
21
  - It takes the usual `<Button>` props, except `onClick`.
@@ -38,6 +40,12 @@ function PostPage({ id }: { id: string }) {
38
40
  }
39
41
  ```
40
42
 
43
+ Only when there is a page to go back to (nothing at the root of a stack):
44
+
45
+ ```tsx
46
+ <BackButton />;
47
+ ```
48
+
41
49
  With a label:
42
50
 
43
51
  ```tsx
@@ -60,7 +68,7 @@ To go back to one fixed page (not to the page before), use a link with `classNam
60
68
  ## Signatures
61
69
 
62
70
  ```ts
63
- BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement
71
+ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement | null
64
72
  ```
65
73
 
66
74
  ## Parameters
@@ -68,10 +76,10 @@ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props
68
76
  | Param | Type | Description |
69
77
  | --- | --- | --- |
70
78
  | `props` | `BackButtonProps` | |
71
- | `.href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
79
+ | `.href` | `AbsolutePath \| undefined` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. Read only. Optional. |
72
80
 
73
81
  ## Returns
74
82
 
75
83
  | Type | Description |
76
84
  | --- | --- |
77
- | `ReactElement` | |
85
+ | `ReactElement \| null` | |
@@ -4,13 +4,13 @@
4
4
  - Import: `import { BackButtonProps } from "shelving/ui";`
5
5
  - Extends: `Omit<ButtonProps, "href" | "onClick">`
6
6
 
7
- Props for `<BackButton>`: the `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
7
+ Props for `<BackButton>`: an optional `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
8
8
 
9
9
  ## Signatures
10
10
 
11
11
  ```ts
12
12
  {
13
- readonly href: AbsolutePath;
13
+ readonly href?: AbsolutePath | undefined;
14
14
  }
15
15
  ```
16
16
 
@@ -18,4 +18,4 @@ Props for `<BackButton>`: the `href` to go back to when the stack has no page be
18
18
 
19
19
  | Property | Type | Description |
20
20
  | --- | --- | --- |
21
- | `href` | `AbsolutePath` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Read only. |
21
+ | `href` | `AbsolutePath \| undefined` | Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. Read only. Optional. |
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.
@@ -461,7 +460,7 @@ The components below are listed in the index following this page; this is the sh
461
460
  - [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
462
461
  - [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
463
462
  - [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
464
- - [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: the href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
463
+ - [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>: an optional href to go back to when the stack has no page before this one, plus the usual Button props except onClick.
465
464
  - [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
466
465
  - [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
467
466
  - [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.325.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;
@@ -2,21 +2,22 @@ import { type ReactElement } from "react";
2
2
  import type { AbsolutePath } from "../../util/path.js";
3
3
  import { type ButtonProps } from "../button/Button.js";
4
4
  /**
5
- * Props for `<BackButton>`: the `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
5
+ * Props for `<BackButton>`: an optional `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
6
6
  *
7
7
  * @see https://shelving.cc/ui/BackButtonProps
8
8
  */
9
9
  export interface BackButtonProps extends Omit<ButtonProps, "href" | "onClick"> {
10
- /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). */
11
- readonly href: AbsolutePath;
10
+ /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. */
11
+ readonly href?: AbsolutePath | undefined;
12
12
  }
13
13
  /**
14
14
  * Back button for the current stack.
15
15
  * - Goes back to the page before this one in the current stack, wherever you came from.
16
16
  * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
17
+ * - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
17
18
  * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
18
19
  *
19
20
  * @kind component
20
21
  * @see https://shelving.cc/ui/BackButton
21
22
  */
22
- export declare function BackButton({ href, className, title, children, ...props }: BackButtonProps): ReactElement;
23
+ export declare function BackButton({ href, className, title, children, ...props }: BackButtonProps): ReactElement | null;
@@ -9,6 +9,7 @@ import { NavigationContext } from "./NavigationContext.js";
9
9
  * Back button for the current stack.
10
10
  * - Goes back to the page before this one in the current stack, wherever you came from.
11
11
  * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
12
+ * - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
12
13
  * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
13
14
  *
14
15
  * @kind component
@@ -18,5 +19,8 @@ export function BackButton({ href, className, title = "Back", children = _jsx(Le
18
19
  const nav = use(NavigationContext);
19
20
  const { stack = null, ordinal } = requireMeta();
20
21
  const parent = nav && ordinal ? nav.history(stack)[ordinal - 1] : undefined;
21
- return (_jsx(Button, { ...props, title: title, href: parent ?? href, className: getClass("back", className), children: children }));
22
+ const target = parent ?? href;
23
+ if (!target)
24
+ return null;
25
+ return (_jsx(Button, { ...props, title: title, href: target, className: getClass("back", className), children: children }));
22
26
  }
@@ -5,7 +5,8 @@ The back button for a page header. It goes back to the page before this one in t
5
5
  **Things to know:**
6
6
 
7
7
  - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
8
- - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
8
+ - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. Set `href` to the page's natural parent. On a floating page (for example a deep link), it goes to `href` and stays floating. To go into a stack, the user taps a `<StackButton>`.
9
+ - Without `href`, it renders nothing when the stack has no page before this one: for example, at the root of a stack, or on a deep link. Use this for a back button that shows only when there is somewhere to go back to.
9
10
  - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationSequence.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
10
11
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
11
12
  - It takes the usual `<Button>` props, except `onClick`.
@@ -30,6 +31,12 @@ function PostPage({ id }: { id: string }) {
30
31
  }
31
32
  ```
32
33
 
34
+ Only when there is a page to go back to (nothing at the root of a stack):
35
+
36
+ ```tsx
37
+ <BackButton />;
38
+ ```
39
+
33
40
  With a label:
34
41
 
35
42
  ```tsx
@@ -7,30 +7,33 @@ import { getClass } from "../util/css.js";
7
7
  import { NavigationContext } from "./NavigationContext.js";
8
8
 
9
9
  /**
10
- * Props for `<BackButton>`: the `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
10
+ * Props for `<BackButton>`: an optional `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
11
11
  *
12
12
  * @see https://shelving.cc/ui/BackButtonProps
13
13
  */
14
14
  export interface BackButtonProps extends Omit<ButtonProps, "href" | "onClick"> {
15
- /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). */
16
- readonly href: AbsolutePath;
15
+ /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). Without it, the button does not show then. */
16
+ readonly href?: AbsolutePath | undefined;
17
17
  }
18
18
 
19
19
  /**
20
20
  * Back button for the current stack.
21
21
  * - Goes back to the page before this one in the current stack, wherever you came from.
22
22
  * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
23
+ * - Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
23
24
  * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
24
25
  *
25
26
  * @kind component
26
27
  * @see https://shelving.cc/ui/BackButton
27
28
  */
28
- export function BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement {
29
+ export function BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement | null {
29
30
  const nav = use(NavigationContext);
30
31
  const { stack = null, ordinal } = requireMeta();
31
32
  const parent = nav && ordinal ? nav.history(stack)[ordinal - 1] : undefined;
33
+ const target = parent ?? href;
34
+ if (!target) return null;
32
35
  return (
33
- <Button {...props} title={title} href={parent ?? href} className={getClass("back", className)}>
36
+ <Button {...props} title={title} href={target} className={getClass("back", className)}>
34
37
  {children}
35
38
  </Button>
36
39
  );
@@ -37,6 +37,15 @@ describe("Navigation", () => {
37
37
  expect(html).toContain('class="back"');
38
38
  });
39
39
 
40
+ test("renders no back button without an href when the stack has no page before this one", () => {
41
+ const html = renderToStaticMarkup(
42
+ <Navigation url="http://x.com/home" stacks={["/home", "/profile"]}>
43
+ <BackButton>Back</BackButton>
44
+ </Navigation>,
45
+ );
46
+ expect(html).toBe("");
47
+ });
48
+
40
49
  test("renders a stack button as a link to its root, selected in the starting stack", () => {
41
50
  const html = renderToStaticMarkup(
42
51
  <Navigation url="http://x.com/profile/settings" stacks={["/home", "/profile"]} stack="/profile">
@@ -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
- }