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.
- package/docs/llms-full.txt +30 -50
- package/docs/ui/BackButton.md +12 -4
- package/docs/ui/BackButtonProps.md +3 -3
- package/docs/ui/Dialog.md +8 -6
- package/docs/ui/DialogCloseButton.md +5 -2
- package/docs/ui.md +2 -3
- package/package.json +1 -1
- package/ui/dialog/Dialog.d.ts +8 -5
- package/ui/dialog/Dialog.js +12 -9
- package/ui/dialog/Dialog.md +5 -4
- package/ui/dialog/Dialog.module.css +1 -1
- package/ui/dialog/Dialog.tsx +9 -8
- package/ui/dialog/Dialogs.js +3 -2
- package/ui/dialog/Dialogs.tsx +3 -2
- package/ui/notice/Notices.js +3 -3
- package/ui/notice/Notices.tsx +3 -3
- package/ui/router/BackButton.d.ts +5 -4
- package/ui/router/BackButton.js +5 -1
- package/ui/router/BackButton.md +8 -1
- package/ui/router/BackButton.tsx +8 -5
- package/ui/router/Navigation.test.tsx +9 -0
- package/docs/ui/useTransitionValue.md +0 -28
- package/ui/transition/useTransitionValue.d.ts +0 -12
- package/ui/transition/useTransitionValue.js +0 -16
- package/ui/transition/useTransitionValue.ts +0 -18
package/docs/llms-full.txt
CHANGED
|
@@ -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
|
|
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>:
|
|
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
|
|
24059
|
+
Modal `<dialog>` element that opens on mount.
|
|
24061
24060
|
|
|
24062
|
-
- Opens via `showModal()` when mounted, and closes on a tap anywhere on it,
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
-
|
|
24228
|
-
-
|
|
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>`:
|
|
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
|
|
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.
|
|
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
|
package/docs/ui/BackButton.md
CHANGED
|
@@ -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.
|
|
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>`:
|
|
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
|
|
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
|
|
6
|
+
Modal `<dialog>` element that opens on mount.
|
|
7
7
|
|
|
8
|
-
- Opens via `showModal()` when mounted, and closes on a tap anywhere on it,
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
-
|
|
8
|
-
-
|
|
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
|
|
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>:
|
|
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
package/ui/dialog/Dialog.d.ts
CHANGED
|
@@ -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
|
|
15
|
+
* Modal `<dialog>` element that opens on mount.
|
|
16
16
|
*
|
|
17
|
-
* - Opens via `showModal()` when mounted, and closes on a tap anywhere on it,
|
|
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
|
-
* -
|
|
51
|
-
* -
|
|
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;
|
package/ui/dialog/Dialog.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { jsx as _jsx
|
|
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
|
|
10
|
+
* Modal `<dialog>` element that opens on mount.
|
|
11
11
|
*
|
|
12
|
-
* - Opens via `showModal()` when mounted, and closes on a tap anywhere on it,
|
|
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:
|
|
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:
|
|
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
|
-
* -
|
|
73
|
-
* -
|
|
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");
|
package/ui/dialog/Dialog.md
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
# Dialog
|
|
2
2
|
|
|
3
|
-
A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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;
|
package/ui/dialog/Dialog.tsx
CHANGED
|
@@ -19,9 +19,10 @@ export interface DialogProps extends OptionalChildProps {
|
|
|
19
19
|
}
|
|
20
20
|
|
|
21
21
|
/**
|
|
22
|
-
* Modal `<dialog>` element that opens on mount
|
|
22
|
+
* Modal `<dialog>` element that opens on mount.
|
|
23
23
|
*
|
|
24
|
-
* - Opens via `showModal()` when mounted, and closes on a tap anywhere on it,
|
|
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
|
-
* -
|
|
114
|
-
* -
|
|
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}
|
package/ui/dialog/Dialogs.js
CHANGED
|
@@ -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
|
-
|
|
72
|
+
const dialogs = requireDialogs();
|
|
73
|
+
return useSequenceTransition(dialogs, { current: () => dialogs.value, transition: "dialog" });
|
|
73
74
|
}
|
package/ui/dialog/Dialogs.tsx
CHANGED
|
@@ -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
|
-
|
|
101
|
+
const dialogs = requireDialogs();
|
|
102
|
+
return useSequenceTransition(dialogs, { current: () => dialogs.value, transition: "dialog" });
|
|
102
103
|
}
|
package/ui/notice/Notices.js
CHANGED
|
@@ -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 =
|
|
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 } =
|
|
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;
|
package/ui/notice/Notices.tsx
CHANGED
|
@@ -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 =
|
|
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 } =
|
|
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>`:
|
|
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
|
|
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;
|
package/ui/router/BackButton.js
CHANGED
|
@@ -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
|
-
|
|
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
|
}
|
package/ui/router/BackButton.md
CHANGED
|
@@ -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.
|
|
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
|
package/ui/router/BackButton.tsx
CHANGED
|
@@ -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>`:
|
|
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
|
|
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={
|
|
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
|
-
}
|