shelving 1.327.0 → 1.328.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 +385 -1
- package/docs/ui/BackSwipe.md +50 -0
- package/docs/ui/Dialog.md +2 -0
- package/docs/ui/DialogControl.md +25 -0
- package/docs/ui/DialogControlContext.md +6 -0
- package/docs/ui/Modal.md +5 -1
- package/docs/ui/Notice.md +2 -0
- package/docs/ui/NoticeProps.md +2 -0
- package/docs/ui/Notices.md +1 -0
- package/docs/ui/SwipeDirection.md +12 -0
- package/docs/ui/SwipeOptions.md +34 -0
- package/docs/ui/TransitionScrub/cancel.md +14 -0
- package/docs/ui/TransitionScrub/finish.md +12 -0
- package/docs/ui/TransitionScrub/seek.md +13 -0
- package/docs/ui/TransitionScrub.md +68 -0
- package/docs/ui/useSwipe.md +92 -0
- package/docs/ui.md +7 -0
- package/package.json +1 -1
- package/ui/dialog/Dialog.d.ts +1 -0
- package/ui/dialog/Dialog.js +34 -8
- package/ui/dialog/Dialog.md +1 -0
- package/ui/dialog/Dialog.tsx +68 -22
- package/ui/dialog/DialogControl.d.ts +14 -0
- package/ui/dialog/DialogControl.js +4 -0
- package/ui/dialog/DialogControl.ts +18 -0
- package/ui/dialog/Modal.d.ts +2 -1
- package/ui/dialog/Modal.js +18 -2
- package/ui/dialog/Modal.md +4 -1
- package/ui/dialog/Modal.module.css +42 -0
- package/ui/dialog/Modal.tsx +19 -1
- package/ui/notice/Notice.d.ts +4 -2
- package/ui/notice/Notice.js +2 -2
- package/ui/notice/Notice.tsx +5 -1
- package/ui/notice/Notices.js +12 -2
- package/ui/notice/Notices.md +1 -0
- package/ui/notice/Notices.tsx +15 -2
- package/ui/router/BackSwipe.d.ts +13 -0
- package/ui/router/BackSwipe.js +61 -0
- package/ui/router/BackSwipe.md +26 -0
- package/ui/router/BackSwipe.ts +61 -0
- package/ui/router/index.d.ts +1 -0
- package/ui/router/index.js +1 -0
- package/ui/router/index.ts +1 -0
- package/ui/transition/TransitionScrub.d.ts +51 -0
- package/ui/transition/TransitionScrub.js +151 -0
- package/ui/transition/TransitionScrub.md +25 -0
- package/ui/transition/TransitionScrub.test.ts +28 -0
- package/ui/transition/TransitionScrub.ts +158 -0
- package/ui/transition/index.d.ts +2 -0
- package/ui/transition/index.js +2 -0
- package/ui/transition/index.tsx +2 -0
- package/ui/transition/useSwipe.d.ts +57 -0
- package/ui/transition/useSwipe.js +188 -0
- package/ui/transition/useSwipe.md +59 -0
- package/ui/transition/useSwipe.ts +240 -0
package/docs/ui/Notice.md
CHANGED
|
@@ -62,6 +62,7 @@ Notice({
|
|
|
62
62
|
children, //
|
|
63
63
|
icon,
|
|
64
64
|
className,
|
|
65
|
+
ref,
|
|
65
66
|
...props
|
|
66
67
|
}: NoticeProps): void
|
|
67
68
|
```
|
|
@@ -72,3 +73,4 @@ Notice({
|
|
|
72
73
|
| --- | --- | --- |
|
|
73
74
|
| `props` | `NoticeProps` | |
|
|
74
75
|
| `.icon` | `ReactElement \| false \| undefined` | Icon for the notice (or `null` or `false` to hide the icon, defaults to `<StatusIcon>`). Optional. |
|
|
76
|
+
| `.ref` | `Ref<HTMLElement> \| undefined` | Ref to the notice's `<aside>` element. Optional. |
|
package/docs/ui/NoticeProps.md
CHANGED
|
@@ -11,6 +11,7 @@ Props for `<Notice>` — flex/colour/status styling variants, optional `children
|
|
|
11
11
|
```ts
|
|
12
12
|
{
|
|
13
13
|
icon?: ReactElement | false | undefined;
|
|
14
|
+
ref?: Ref<HTMLElement> | undefined;
|
|
14
15
|
}
|
|
15
16
|
```
|
|
16
17
|
|
|
@@ -19,3 +20,4 @@ Props for `<Notice>` — flex/colour/status styling variants, optional `children
|
|
|
19
20
|
| Property | Type | Description |
|
|
20
21
|
| --- | --- | --- |
|
|
21
22
|
| `icon` | `ReactElement \| false \| undefined` | Icon for the notice (or `null` or `false` to hide the icon, defaults to `<StatusIcon>`). Optional. |
|
|
23
|
+
| `ref` | `Ref<HTMLElement> \| undefined` | Ref to the notice's `<aside>` element. Optional. |
|
package/docs/ui/Notices.md
CHANGED
|
@@ -19,6 +19,7 @@ Renders the global list of active notices and subscribes to incoming `"notice"`
|
|
|
19
19
|
- The list shows in the bottom-right corner. Set `position` to `"top-left"`, `"top-center"`, `"top-right"`, `"bottom-left"`, `"bottom-center"`, or `"bottom-right"` to choose a different place.
|
|
20
20
|
- Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). `Notices` renders the store inside transitions, so a notice animates with no `startTransition()` of your own. A single `<Notice>` knows nothing about transitions, the same as `<Dialog>`. A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
|
|
21
21
|
- The list has its own layer in every view transition, so it stays still above a page that slides under it.
|
|
22
|
+
- Swipe a notice toward the side it slides out to (up or down in a centred list) to close it. The swipe scrubs the slide-out with the finger, through `useSwipe()`. A swipe that goes back adds the notice back.
|
|
22
23
|
- With reduced motion, notices fade in and out in place, and the others move at once. A browser without view transitions shows the changes at once.
|
|
23
24
|
|
|
24
25
|
## Usage
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# SwipeOptions
|
|
2
|
+
|
|
3
|
+
- Kind: interface
|
|
4
|
+
- Import: `import { SwipeOptions } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Options for `useSwipe()`.
|
|
7
|
+
|
|
8
|
+
## Signatures
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
{
|
|
12
|
+
readonly direction: SwipeDirection;
|
|
13
|
+
readonly start: () => unknown;
|
|
14
|
+
readonly cancel: () => PromiseLike<void> | void;
|
|
15
|
+
readonly commit?: (() => void) | undefined;
|
|
16
|
+
readonly edge?: number | undefined;
|
|
17
|
+
readonly distance?: number | undefined;
|
|
18
|
+
readonly ignore?: string | undefined;
|
|
19
|
+
readonly disabled?: boolean | undefined;
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Properties
|
|
24
|
+
|
|
25
|
+
| Property | Type | Description |
|
|
26
|
+
| --- | --- | --- |
|
|
27
|
+
| `direction` | `SwipeDirection` | Which way the finger moves to complete the swipe. Read only. |
|
|
28
|
+
| `start` | `() => unknown` | Make the change that starts the view transition, for example close a dialog inside `startTransition()`. - Return `false` to start no swipe (for example when there is nothing to go back to). Read only. |
|
|
29
|
+
| `cancel` | `() => PromiseLike<void> \| void` | Put back the state from before `start()`, when the swipe is cancelled. - Return a promise that resolves after React commits, so the transition ends on the right page. Read only. |
|
|
30
|
+
| `commit` | `(() => void) \| undefined` | Finish the change for real, after the slide reaches the end. Read only. Optional. |
|
|
31
|
+
| `edge` | `number \| undefined` | Start only when the finger goes down this close to the screen edge it moves away from, in pixels (for example `24` for swipe-back). - Leave it out to start anywhere on the target. Read only. Optional. |
|
|
32
|
+
| `distance` | `number \| undefined` | Part of the target's size a slow drag must pass to complete. Read only. Defaults to `0.35`. |
|
|
33
|
+
| `ignore` | `string \| undefined` | Never start a swipe on an element inside one that matches this selector, for example `"nav"`. Read only. Optional. |
|
|
34
|
+
| `disabled` | `boolean \| undefined` | Turn the swipe off. Read only. Optional. |
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# TransitionScrub.cancel()
|
|
2
|
+
|
|
3
|
+
- Kind: method
|
|
4
|
+
- Member of: `TransitionScrub`
|
|
5
|
+
|
|
6
|
+
Play the transition back to the start, run `undo()`, and then end the transition.
|
|
7
|
+
- `undo()` must put back the state from before the update, so the page matches the start of the transition when it ends.
|
|
8
|
+
- If `undo()` returns a promise (for example one that resolves after React commits), it waits for it before it ends the transition.
|
|
9
|
+
|
|
10
|
+
## Signatures
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
cancel(undo: () => PromiseLike<void> | void): Promise<void>
|
|
14
|
+
```
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# TransitionScrub.seek()
|
|
2
|
+
|
|
3
|
+
- Kind: method
|
|
4
|
+
- Member of: `TransitionScrub`
|
|
5
|
+
|
|
6
|
+
Move the transition to a point, from `0` (start) to `1` (end).
|
|
7
|
+
- Safe to call before the transition is ready: it moves there as soon as it is.
|
|
8
|
+
|
|
9
|
+
## Signatures
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
seek(progress: number): void
|
|
13
|
+
```
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# TransitionScrub
|
|
2
|
+
|
|
3
|
+
- Kind: class
|
|
4
|
+
- Import: `import { TransitionScrub } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Take manual control of the view transition that an update starts.
|
|
7
|
+
|
|
8
|
+
- The constructor runs `update()` at once and catches the next view transition that starts (for example the one React starts for a state change inside `startTransition()`).
|
|
9
|
+
- When the transition is ready, it pauses every animation of the transition, so `seek()` can move it by hand.
|
|
10
|
+
- `finish()` plays it to the end. `cancel()` plays it back to the start, runs an undo, and ends it.
|
|
11
|
+
- Without view transitions (older browsers), or if `update()` starts none, the update still happens: `seek()` does nothing, `finish()` ends at once, and `cancel()` just runs the undo.
|
|
12
|
+
- If `update()` returns `false`, nothing is caught, and `started` is `false`.
|
|
13
|
+
- Only one view transition runs at a time. A new one skips this one, which ends it at its end state.
|
|
14
|
+
|
|
15
|
+
Take manual control of the view transition that an update starts: move it to any point, then play it to the end, or play it back and undo the update.
|
|
16
|
+
|
|
17
|
+
**Things to know:**
|
|
18
|
+
|
|
19
|
+
- The constructor runs the update at once and catches the next view transition that starts. With React, that is the transition React starts for a state change inside `startTransition()`.
|
|
20
|
+
- When the transition is ready, every animation in it is paused. `TransitionScrub.seek()` moves them, from `0` (start) to `1` (end).
|
|
21
|
+
- `TransitionScrub.finish()` plays from where it is to the end. `TransitionScrub.cancel()` plays back to the start, runs your undo, waits for it, and then ends the transition. The undo must put the page back as it was before the update.
|
|
22
|
+
- If the update returns `false`, nothing is caught and `TransitionScrub.started` is `false`.
|
|
23
|
+
- Without view transitions, or when the update starts none within a second, the update still happens: `seek()` does nothing, `finish()` ends at once, and `cancel()` only runs the undo.
|
|
24
|
+
- Only one view transition runs at a time. Another one that starts skips this one to its end.
|
|
25
|
+
- `useSwipe()` drives a `TransitionScrub` from a finger. Use the class directly for other inputs, such as a slider.
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { TransitionScrub } from "shelving/ui";
|
|
31
|
+
|
|
32
|
+
const scrub = new TransitionScrub(() => dialogs.delete(dialog));
|
|
33
|
+
scrub.seek(0.4); // 40% of the way through the close.
|
|
34
|
+
await scrub.finish(); // Play to the end.
|
|
35
|
+
// Or play back to the start and undo the change:
|
|
36
|
+
await scrub.cancel(() => dialogs.add(dialog));
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## Signatures
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
new TransitionScrub(update: () => unknown)
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Parameters
|
|
47
|
+
|
|
48
|
+
| Param | Type | Description |
|
|
49
|
+
| --- | --- | --- |
|
|
50
|
+
| `update` | `() => unknown` | A change that starts a view transition. Return `false` to start nothing. |
|
|
51
|
+
|
|
52
|
+
## Returns
|
|
53
|
+
|
|
54
|
+
| Type | Description |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| `TransitionScrub` | |
|
|
57
|
+
|
|
58
|
+
## Properties
|
|
59
|
+
|
|
60
|
+
| Property | Type | Description |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| `started` | `boolean` | `false` if `update()` returned `false`, so there is nothing to scrub. Read only. |
|
|
63
|
+
|
|
64
|
+
## Methods
|
|
65
|
+
|
|
66
|
+
- [TransitionScrub.seek()](TransitionScrub/seek.md): Move the transition to a point, from 0 (start) to 1 (end).
|
|
67
|
+
- [TransitionScrub.finish()](TransitionScrub/finish.md): Play the transition from where it is to the end, then end it.
|
|
68
|
+
- [TransitionScrub.cancel()](TransitionScrub/cancel.md): Play the transition back to the start, run undo(), and then end the transition.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# useSwipe()
|
|
2
|
+
|
|
3
|
+
- Kind: function
|
|
4
|
+
- Import: `import { useSwipe } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Swipe a target to complete a change, and scrub the change's view transition with the finger.
|
|
7
|
+
|
|
8
|
+
- When the finger moves the right way, it calls `start()` and catches the view transition that starts, with `TransitionScrub`.
|
|
9
|
+
- While the finger moves, the transition follows it. Progress is the drag distance divided by the target's size in that direction (the screen size for `document`).
|
|
10
|
+
- On release, past `distance` or after a flick, it plays the transition to the end and calls `commit()`. Otherwise it plays it back and calls `cancel()`.
|
|
11
|
+
- It does not start when the finger is on a field, inside an element that can still scroll that way, or inside a `<dialog>` that does not hold the target.
|
|
12
|
+
- Only one swipe runs at a time. A swipe on `document` listens first, so an edge swipe wins over a swipe on an element below it.
|
|
13
|
+
|
|
14
|
+
Swipe an element (or the whole page) to make a change, and scrub the change's view transition with the finger.
|
|
15
|
+
|
|
16
|
+
**Things to know:**
|
|
17
|
+
|
|
18
|
+
- Give it three functions. `start` makes the change, inside a transition, so React starts a view transition. `cancel` puts back the state from before. `commit` finishes the change for real after the slide ends.
|
|
19
|
+
- `start` runs when the finger has moved a few pixels in `direction`. Return `false` from it to start no swipe.
|
|
20
|
+
- While the finger moves, the transition follows it through `TransitionScrub`. Progress is the drag distance divided by the target's size in that direction (the screen size for `document`).
|
|
21
|
+
- On release past `distance` (default 35%), or after a flick, the slide plays to the end and `commit` runs. Otherwise the slide plays back and `cancel` runs. Return a promise from `cancel` that resolves after React commits, so the slide ends on the right state.
|
|
22
|
+
- It does not start on a field, inside an element that can still scroll the other way, or inside a `<dialog>` that does not hold the target.
|
|
23
|
+
- `edge` limits the start to a strip along the screen edge the finger moves away from, for example `24` for swipe-back from the left edge.
|
|
24
|
+
- Only one swipe runs at a time. A swipe on `document` decides first, so an edge swipe wins over a swipe on an element below it.
|
|
25
|
+
- The swipe keeps working when `start` takes the touched element out of the page. If the content can keep state, hide it in a React `<Activity>` instead of unmounting it, so `cancel` can show it again as it was.
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
### Swipe a panel down to close it
|
|
30
|
+
|
|
31
|
+
`<Modal>` does this for every pinned panel in a `<Dialog>`:
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
const ref = useRef<HTMLElement>(null);
|
|
35
|
+
useSwipe(ref, {
|
|
36
|
+
direction: "down",
|
|
37
|
+
start: () => dialog.hide(), // Hide in a transition.
|
|
38
|
+
cancel: () => dialog.show(), // Show again at once.
|
|
39
|
+
commit: () => dialog.close(),
|
|
40
|
+
});
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Swipe a notice away
|
|
44
|
+
|
|
45
|
+
A notice holds no state, so removing it and adding it back is enough:
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
useSwipe(ref, {
|
|
49
|
+
direction: "right",
|
|
50
|
+
start: () => notice.close(),
|
|
51
|
+
cancel: () => NOTICES.add(notice),
|
|
52
|
+
});
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Swipe between tabs
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
useSwipe(ref, {
|
|
59
|
+
direction: "left",
|
|
60
|
+
start: () => {
|
|
61
|
+
if (!next) return false;
|
|
62
|
+
startTransition(() => {
|
|
63
|
+
addTransitionType("tab-forward");
|
|
64
|
+
setShown(next);
|
|
65
|
+
});
|
|
66
|
+
},
|
|
67
|
+
cancel: () => flushSync(() => setShown(current)),
|
|
68
|
+
commit: () => setTab(next),
|
|
69
|
+
});
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
## Signatures
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
useSwipe(target: RefObject<Element | null> | Document, options: SwipeOptions): void
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Parameters
|
|
80
|
+
|
|
81
|
+
| Param | Type | Description |
|
|
82
|
+
| --- | --- | --- |
|
|
83
|
+
| `target` | `RefObject<Element \| null> \| Document` | The element to swipe, or `document` for the whole page. |
|
|
84
|
+
| `options` | `SwipeOptions` | What the swipe does. |
|
|
85
|
+
| `.direction` | `SwipeDirection` | Which way the finger moves to complete the swipe. Read only. |
|
|
86
|
+
| `.start` | `() => unknown` | Make the change that starts the view transition, for example close a dialog inside `startTransition()`. - Return `false` to start no swipe (for example when there is nothing to go back to). Read only. |
|
|
87
|
+
| `.cancel` | `() => PromiseLike<void> \| void` | Put back the state from before `start()`, when the swipe is cancelled. - Return a promise that resolves after React commits, so the transition ends on the right page. Read only. |
|
|
88
|
+
| `.commit` | `(() => void) \| undefined` | Finish the change for real, after the slide reaches the end. Read only. Optional. |
|
|
89
|
+
| `.edge` | `number \| undefined` | Start only when the finger goes down this close to the screen edge it moves away from, in pixels (for example `24` for swipe-back). - Leave it out to start anywhere on the target. Read only. Optional. |
|
|
90
|
+
| `.distance` | `number \| undefined` | Part of the target's size a slow drag must pass to complete. Read only. Defaults to `0.35`. |
|
|
91
|
+
| `.ignore` | `string \| undefined` | Never start a swipe on an element inside one that matches this selector, for example `"nav"`. Read only. Optional. |
|
|
92
|
+
| `.disabled` | `boolean \| undefined` | Turn the swipe off. Read only. Optional. |
|
package/docs/ui.md
CHANGED
|
@@ -198,6 +198,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
198
198
|
- [HTML](ui/HTML.md): Render the full <html> document shell wrapping <head> and <body>.
|
|
199
199
|
- [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
|
|
200
200
|
- [BackButton](ui/BackButton.md): Back button for the current stack.
|
|
201
|
+
- [BackSwipe](ui/BackSwipe.md): Swipe from the left edge of the screen to go back one page in the current stack, by scrubbing the normal back slide.
|
|
201
202
|
- [Navigation](ui/Navigation.md): Top-level navigation provider, with one stack of pages for each tab.
|
|
202
203
|
- [RouteCache](ui/RouteCache.md): Keep-alive page cache for the pages in the navigation stacks. Put it in a layout's content slot, around a <Scroll vertical cover> box.
|
|
203
204
|
- [Router](ui/Router.md): Match the current URL against routes and render the matched element.
|
|
@@ -283,6 +284,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
283
284
|
- [getStrokeClass()](ui/getStrokeClass.md): Get the border-thickness class for a component from its stroke variant prop.
|
|
284
285
|
- [getTypographyClass()](ui/getTypographyClass.md): Get the typography class for a component from its typographic variant props.
|
|
285
286
|
- [getWidthClass()](ui/getWidthClass.md): Get the width class for a component from its width / grow variant props.
|
|
287
|
+
- [useSwipe()](ui/useSwipe.md): Swipe a target to complete a change, and scrub the change's view transition with the finger.
|
|
286
288
|
- [setTransitionType()](ui/setTransitionType.md): Type-safe passthrough for React's addTransitionType() that checks type is one of our known view-transition types.
|
|
287
289
|
- [useTreeMap()](ui/useTreeMap.md): Use the flattened tree lookup map from context.
|
|
288
290
|
- [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.
|
|
@@ -326,6 +328,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
326
328
|
- [NoticesStore](ui/NoticesStore.md): Store holding the live list of NoticeStore notices currently shown.
|
|
327
329
|
- [NoticeStore](ui/NoticeStore.md): Store holding a single notice's content and status, owned by a NoticesStore.
|
|
328
330
|
- [NavigationSequence](ui/NavigationSequence.md): Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
|
|
331
|
+
- [TransitionScrub](ui/TransitionScrub.md): Take manual control of the view transition that an update starts.
|
|
329
332
|
|
|
330
333
|
## Interfaces
|
|
331
334
|
|
|
@@ -362,6 +365,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
362
365
|
- [SubmitButtonProps](ui/SubmitButtonProps.md): Component props for <SubmitButton>, a form submit button.
|
|
363
366
|
- [DialogProps](ui/DialogProps.md): Props for <Dialog> — optional children content and an onClose callback.
|
|
364
367
|
- [DialogCloseButtonProps](ui/DialogCloseButtonProps.md): Props for <DialogCloseButton> — button styling variants and optional children to override the X icon.
|
|
368
|
+
- [DialogControl](ui/DialogControl.md): Controls for the nearest <Dialog>, so a <Modal> inside it can swipe it away.
|
|
365
369
|
- [DialogsContextProps](ui/DialogsContextProps.md): Props for <DialogsContext> — the children subtree the dialogs store is provided to.
|
|
366
370
|
- [DialogsProps](ui/DialogsProps.md): Props for <Dialogs> — takes no props (branded empty interface).
|
|
367
371
|
- [ModalVariants](ui/ModalVariants.md): Variant props for <Modal> — pin the panel to one edge of the screen.
|
|
@@ -492,6 +496,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
492
496
|
- [HorizontalTransitionProps](ui/HorizontalTransitionProps.md): Props for the HorizontalTransition component — the shared transition variant props.
|
|
493
497
|
- [TransitionVariants](ui/TransitionVariants.md): Variant props shared by every transition component.
|
|
494
498
|
- [TransitionProps](ui/TransitionProps.md): React props for <Transition> component.
|
|
499
|
+
- [SwipeOptions](ui/SwipeOptions.md): Options for useSwipe().
|
|
495
500
|
- [VerticalTransitionProps](ui/VerticalTransitionProps.md): Props for the VerticalTransition component — the shared transition variant props.
|
|
496
501
|
- [TreeAppProps](ui/TreeAppProps.md): Props for the TreeApp component — the tree to render plus optional extra routes and app meta.
|
|
497
502
|
- [TreeBreadcrumbsProps](ui/TreeBreadcrumbsProps.md): Props for the TreeBreadcrumbs component — typography, space, and flex variant props.
|
|
@@ -540,6 +545,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
540
545
|
- [CaseVariant](ui/CaseVariant.md): Allowed values for text case for components that support TypographyVariants
|
|
541
546
|
- [FontVariant](ui/FontVariant.md): Allowed values for font family for components that support TypographyVariants
|
|
542
547
|
- [WidthVariant](ui/WidthVariant.md): Enumerated width selectable via the width variant prop.
|
|
548
|
+
- [SwipeDirection](ui/SwipeDirection.md): Which way the finger moves to complete a swipe.
|
|
543
549
|
- [TransitionClasses](ui/TransitionClasses.md): Map of view-transition types to their CSS class names in { type: className } format.
|
|
544
550
|
- [TransitionType](ui/TransitionType.md): Known view-transition type names that all transitions support — the keys of TransitionClasses.
|
|
545
551
|
- [Classes](ui/Classes.md): Set of classnames that can be joined into a single className string.
|
|
@@ -555,6 +561,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
555
561
|
## Constants
|
|
556
562
|
|
|
557
563
|
- [RetryContext](ui/RetryContext.md): Context for providing a "retry" callback to descendant <RetryButton> elements.
|
|
564
|
+
- [DialogControlContext](ui/DialogControlContext.md): Context with the controls for the nearest <Dialog>, or undefined outside one (or in a <Dialog> with no onClose).
|
|
558
565
|
- [DOCUMENTATION_LIVE_RULE](ui/DOCUMENTATION_LIVE_RULE.md): Markup rule that renders a fenced code block with a live flag as a <DocumentationLive> example, e.g. tsx live "Card with a link" `.
|
|
559
566
|
- [DOCUMENTATION_MARKUP_RULES](ui/DOCUMENTATION_MARKUP_RULES.md): Markup rules for docs site content: DOCUMENTATION_LIVE_RULE then TREE_MARKUP_RULES, so fenced code blocks with a live flag run.
|
|
560
567
|
- [PLAYGROUND_FRAME_PATH](ui/PLAYGROUND_FRAME_PATH.md): Path of the frame page that runs playground code, relative to the docs site root.
|
package/package.json
CHANGED
package/ui/dialog/Dialog.d.ts
CHANGED
|
@@ -22,6 +22,7 @@ export interface DialogProps extends OptionalChildProps {
|
|
|
22
22
|
* - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
|
|
23
23
|
* - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
|
|
24
24
|
* - Wraps content in `<Suspense>` so lazy children can stream in.
|
|
25
|
+
* - With `onClose`, a `<Modal>` pinned to an edge can swipe it away. During the swipe the dialog is hidden in an `<Activity>`, not unmounted, so a cancelled swipe keeps its state.
|
|
25
26
|
*
|
|
26
27
|
* @kind component
|
|
27
28
|
* @see https://shelving.cc/ui/Dialog
|
package/ui/dialog/Dialog.js
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
|
-
|
|
2
|
+
/// <reference types="react/canary" />
|
|
3
|
+
import { Activity, addTransitionType, memo, Suspense, startTransition, useLayoutEffect, useMemo, useRef, useState, ViewTransition, } from "react";
|
|
3
4
|
import { CloseIcon } from "shelving/icon/CloseIcon";
|
|
4
5
|
import { getButtonClass } from "../button/Button.js";
|
|
5
6
|
import { FADE_TRANSITION_CLASS } from "../transition/FadeTransition.js";
|
|
6
7
|
import { getClass, getModuleClass } from "../util/css.js";
|
|
7
8
|
import styles from "./Dialog.module.css";
|
|
9
|
+
import { DialogControlContext } from "./DialogControl.js";
|
|
8
10
|
import modalStyles from "./Modal.module.css";
|
|
9
11
|
/**
|
|
10
12
|
* Modal `<dialog>` element that opens on mount.
|
|
@@ -17,18 +19,42 @@ import modalStyles from "./Modal.module.css";
|
|
|
17
19
|
* - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
|
|
18
20
|
* - 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.
|
|
19
21
|
* - Wraps content in `<Suspense>` so lazy children can stream in.
|
|
22
|
+
* - With `onClose`, a `<Modal>` pinned to an edge can swipe it away. During the swipe the dialog is hidden in an `<Activity>`, not unmounted, so a cancelled swipe keeps its state.
|
|
20
23
|
*
|
|
21
24
|
* @kind component
|
|
22
25
|
* @see https://shelving.cc/ui/Dialog
|
|
23
26
|
*/
|
|
24
27
|
export const Dialog = memo(({ children, onClose, ...props }) => {
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
28
|
+
const [hidden, setHidden] = useState(false);
|
|
29
|
+
const hiddenRef = useRef(hidden);
|
|
30
|
+
hiddenRef.current = hidden;
|
|
31
|
+
const waiting = useRef([]);
|
|
32
|
+
// Resolve `show()` calls once React has committed the shown dialog.
|
|
33
|
+
useLayoutEffect(() => {
|
|
34
|
+
if (!hidden)
|
|
35
|
+
for (const resolve of waiting.current.splice(0))
|
|
36
|
+
resolve();
|
|
37
|
+
}, [hidden]);
|
|
38
|
+
const control = useMemo(() => onClose && {
|
|
39
|
+
hide: () => startTransition(() => {
|
|
40
|
+
addTransitionType("dialog");
|
|
41
|
+
setHidden(true);
|
|
42
|
+
}),
|
|
43
|
+
show: () => new Promise(resolve => {
|
|
44
|
+
if (!hiddenRef.current)
|
|
45
|
+
return resolve();
|
|
46
|
+
waiting.current.push(resolve);
|
|
47
|
+
setHidden(false);
|
|
48
|
+
}),
|
|
49
|
+
close: onClose,
|
|
50
|
+
}, [onClose]);
|
|
51
|
+
return (_jsx(Activity, { mode: hidden ? "hidden" : "visible", children: _jsx(DialogControlContext, { value: control, children: _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 => {
|
|
52
|
+
// Keep the dialog open until the parent unmounts it. An uncancelable request closes natively and fires `onClose` from the `close` event.
|
|
53
|
+
if (!onClose || !e.cancelable)
|
|
54
|
+
return;
|
|
55
|
+
e.preventDefault();
|
|
56
|
+
onClose();
|
|
57
|
+
}, onClose: onClose, ...props, children: _jsx("div", { className: getModuleClass(styles, "content"), children: children }) }) }) }) }) }));
|
|
32
58
|
});
|
|
33
59
|
/**
|
|
34
60
|
* Open a `<dialog>` as a modal when React attaches it.
|
package/ui/dialog/Dialog.md
CHANGED
|
@@ -21,6 +21,7 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
|
|
|
21
21
|
- A `Dialog` you mount from a store read with `useStore()` never animates. `useStore()` applies each change at once, so `startTransition()` around the store write does not help.
|
|
22
22
|
- To open a dialog from app code, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
|
|
23
23
|
- A browser without view transitions shows and hides the dialog at once.
|
|
24
|
+
- With `onClose`, a pinned `<Modal>` inside can swipe the dialog away. During the swipe, the dialog is hidden in a React `<Activity>`, not unmounted, so a swipe that goes back shows it again with its state (typed text, scroll place).
|
|
24
25
|
- Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
|
|
25
26
|
|
|
26
27
|
## Usage
|
package/ui/dialog/Dialog.tsx
CHANGED
|
@@ -1,4 +1,18 @@
|
|
|
1
|
-
|
|
1
|
+
/// <reference types="react/canary" />
|
|
2
|
+
import {
|
|
3
|
+
Activity,
|
|
4
|
+
addTransitionType,
|
|
5
|
+
type MouseEvent,
|
|
6
|
+
memo,
|
|
7
|
+
type ReactElement,
|
|
8
|
+
Suspense,
|
|
9
|
+
startTransition,
|
|
10
|
+
useLayoutEffect,
|
|
11
|
+
useMemo,
|
|
12
|
+
useRef,
|
|
13
|
+
useState,
|
|
14
|
+
ViewTransition,
|
|
15
|
+
} from "react";
|
|
2
16
|
import { CloseIcon } from "shelving/icon/CloseIcon";
|
|
3
17
|
import type { Callback } from "../../util/function.js";
|
|
4
18
|
import { type ButtonVariants, getButtonClass } from "../button/Button.js";
|
|
@@ -6,6 +20,7 @@ import { FADE_TRANSITION_CLASS } from "../transition/FadeTransition.js";
|
|
|
6
20
|
import { getClass, getModuleClass } from "../util/css.js";
|
|
7
21
|
import type { ClassProps, OptionalChildProps } from "../util/props.js";
|
|
8
22
|
import styles from "./Dialog.module.css";
|
|
23
|
+
import { type DialogControl, DialogControlContext } from "./DialogControl.js";
|
|
9
24
|
import modalStyles from "./Modal.module.css";
|
|
10
25
|
|
|
11
26
|
/**
|
|
@@ -29,33 +44,64 @@ export interface DialogProps extends OptionalChildProps {
|
|
|
29
44
|
* - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
|
|
30
45
|
* - 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.
|
|
31
46
|
* - Wraps content in `<Suspense>` so lazy children can stream in.
|
|
47
|
+
* - With `onClose`, a `<Modal>` pinned to an edge can swipe it away. During the swipe the dialog is hidden in an `<Activity>`, not unmounted, so a cancelled swipe keeps its state.
|
|
32
48
|
*
|
|
33
49
|
* @kind component
|
|
34
50
|
* @see https://shelving.cc/ui/Dialog
|
|
35
51
|
*/
|
|
36
52
|
export const Dialog = memo(({ children, onClose, ...props }: DialogProps) => {
|
|
53
|
+
const [hidden, setHidden] = useState(false);
|
|
54
|
+
const hiddenRef = useRef(hidden);
|
|
55
|
+
hiddenRef.current = hidden;
|
|
56
|
+
const waiting = useRef<(() => void)[]>([]);
|
|
57
|
+
// Resolve `show()` calls once React has committed the shown dialog.
|
|
58
|
+
useLayoutEffect(() => {
|
|
59
|
+
if (!hidden) for (const resolve of waiting.current.splice(0)) resolve();
|
|
60
|
+
}, [hidden]);
|
|
61
|
+
const control = useMemo<DialogControl | undefined>(
|
|
62
|
+
() =>
|
|
63
|
+
onClose && {
|
|
64
|
+
hide: () =>
|
|
65
|
+
startTransition(() => {
|
|
66
|
+
addTransitionType("dialog");
|
|
67
|
+
setHidden(true);
|
|
68
|
+
}),
|
|
69
|
+
show: () =>
|
|
70
|
+
new Promise<void>(resolve => {
|
|
71
|
+
if (!hiddenRef.current) return resolve();
|
|
72
|
+
waiting.current.push(resolve);
|
|
73
|
+
setHidden(false);
|
|
74
|
+
}),
|
|
75
|
+
close: onClose,
|
|
76
|
+
},
|
|
77
|
+
[onClose],
|
|
78
|
+
);
|
|
37
79
|
return (
|
|
38
|
-
<
|
|
39
|
-
{
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
80
|
+
<Activity mode={hidden ? "hidden" : "visible"}>
|
|
81
|
+
<DialogControlContext value={control}>
|
|
82
|
+
<Suspense fallback={null}>
|
|
83
|
+
{/* The transition must wrap the `<dialog>`: React only animates a `<ViewTransition>` that comes before any DOM element in the inserted or deleted tree. Fade only on enter and exit, so an open dialog stays still while another dialog opens or closes. No update transition: the page ignores taps while a view transition runs, so a change inside an open dialog must not start one. */}
|
|
84
|
+
<ViewTransition default="none" enter={FADE_TRANSITION_CLASS} exit={FADE_TRANSITION_CLASS}>
|
|
85
|
+
{/** biome-ignore lint/a11y/useKeyWithClickEvents: Dialogs also show a close button. */}
|
|
86
|
+
<dialog
|
|
87
|
+
ref={_showModal}
|
|
88
|
+
className={getModuleClass(styles, "dialog")}
|
|
89
|
+
onClick={_closeOnClick}
|
|
90
|
+
onCancel={e => {
|
|
91
|
+
// Keep the dialog open until the parent unmounts it. An uncancelable request closes natively and fires `onClose` from the `close` event.
|
|
92
|
+
if (!onClose || !e.cancelable) return;
|
|
93
|
+
e.preventDefault();
|
|
94
|
+
onClose();
|
|
95
|
+
}}
|
|
96
|
+
onClose={onClose}
|
|
97
|
+
{...props}
|
|
98
|
+
>
|
|
99
|
+
<div className={getModuleClass(styles, "content")}>{children}</div>
|
|
100
|
+
</dialog>
|
|
101
|
+
</ViewTransition>
|
|
102
|
+
</Suspense>
|
|
103
|
+
</DialogControlContext>
|
|
104
|
+
</Activity>
|
|
59
105
|
);
|
|
60
106
|
});
|
|
61
107
|
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Controls for the nearest `<Dialog>`, so a `<Modal>` inside it can swipe it away.
|
|
3
|
+
* - Internal: not exported from the `shelving/ui` barrel.
|
|
4
|
+
*/
|
|
5
|
+
export interface DialogControl {
|
|
6
|
+
/** Hide the dialog in a `"dialog"` transition, so its exit transition runs. It stays mounted, with its state. */
|
|
7
|
+
readonly hide: () => void;
|
|
8
|
+
/** Show the hidden dialog again at once, with no transition. Resolves after React commits it. */
|
|
9
|
+
readonly show: () => Promise<void>;
|
|
10
|
+
/** Close the dialog for real (calls its `onClose`). */
|
|
11
|
+
readonly close: () => void;
|
|
12
|
+
}
|
|
13
|
+
/** Context with the controls for the nearest `<Dialog>`, or `undefined` outside one (or in a `<Dialog>` with no `onClose`). */
|
|
14
|
+
export declare const DialogControlContext: import("react").Context<DialogControl | undefined>;
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { createContext } from "react";
|
|
2
|
+
/** Context with the controls for the nearest `<Dialog>`, or `undefined` outside one (or in a `<Dialog>` with no `onClose`). */
|
|
3
|
+
export const DialogControlContext = createContext(undefined);
|
|
4
|
+
DialogControlContext.displayName = "DialogControlContext";
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { createContext } from "react";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Controls for the nearest `<Dialog>`, so a `<Modal>` inside it can swipe it away.
|
|
5
|
+
* - Internal: not exported from the `shelving/ui` barrel.
|
|
6
|
+
*/
|
|
7
|
+
export interface DialogControl {
|
|
8
|
+
/** Hide the dialog in a `"dialog"` transition, so its exit transition runs. It stays mounted, with its state. */
|
|
9
|
+
readonly hide: () => void;
|
|
10
|
+
/** Show the hidden dialog again at once, with no transition. Resolves after React commits it. */
|
|
11
|
+
readonly show: () => Promise<void>;
|
|
12
|
+
/** Close the dialog for real (calls its `onClose`). */
|
|
13
|
+
readonly close: () => void;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Context with the controls for the nearest `<Dialog>`, or `undefined` outside one (or in a `<Dialog>` with no `onClose`). */
|
|
17
|
+
export const DialogControlContext = createContext<DialogControl | undefined>(undefined);
|
|
18
|
+
DialogControlContext.displayName = "DialogControlContext";
|
package/ui/dialog/Modal.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
1
|
+
import { type ReactElement } from "react";
|
|
2
2
|
import { type IndentVariants } from "../style/Indent.js";
|
|
3
3
|
import { type PaddingVariants } from "../style/Padding.js";
|
|
4
4
|
import { type RadiusVariants } from "../style/Radius.js";
|
|
@@ -35,6 +35,7 @@ export interface ModalProps extends ModalVariants, PaddingVariants, IndentVarian
|
|
|
35
35
|
* - Centred by default. It fades in and out with its `<Dialog>`.
|
|
36
36
|
* - Has a `--shadow-large` drop shadow by default. Set `shadow="none"`, `shadow="small"` or `shadow="normal"` to change it.
|
|
37
37
|
* - `top`, `right`, `bottom`, or `left` pins it to that edge. It then takes its own layer in the `<Dialog>` view transition, and slides in from that edge and out to it.
|
|
38
|
+
* - A pinned panel in a `<Dialog>` with `onClose` can be swiped toward its edge to close the dialog. The swipe scrubs the same slide, and shows a grab handle on the inner side. A swipe that goes back closes nothing, and the dialog keeps its state.
|
|
38
39
|
*
|
|
39
40
|
* @kind component
|
|
40
41
|
* @see https://shelving.cc/ui/Modal
|