shelving 1.326.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 +377 -21
- package/docs/ui/BackSwipe.md +50 -0
- package/docs/ui/Dialog.md +10 -6
- package/docs/ui/DialogCloseButton.md +5 -2
- 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 +8 -2
- package/package.json +1 -1
- package/ui/dialog/Dialog.d.ts +9 -5
- package/ui/dialog/Dialog.js +44 -15
- package/ui/dialog/Dialog.md +6 -4
- package/ui/dialog/Dialog.module.css +1 -1
- package/ui/dialog/Dialog.tsx +77 -30
- 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/Dialogs.js +3 -2
- package/ui/dialog/Dialogs.tsx +3 -2
- 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 +15 -5
- package/ui/notice/Notices.md +1 -0
- package/ui/notice/Notices.tsx +18 -5
- 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/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.
|
|
@@ -20561,6 +20561,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20561
20561
|
- [HTML](ui/HTML.md): Render the full <html> document shell wrapping <head> and <body>.
|
|
20562
20562
|
- [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
|
|
20563
20563
|
- [BackButton](ui/BackButton.md): Back button for the current stack.
|
|
20564
|
+
- [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.
|
|
20564
20565
|
- [Navigation](ui/Navigation.md): Top-level navigation provider, with one stack of pages for each tab.
|
|
20565
20566
|
- [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.
|
|
20566
20567
|
- [Router](ui/Router.md): Match the current URL against routes and render the matched element.
|
|
@@ -20646,7 +20647,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20646
20647
|
- [getStrokeClass()](ui/getStrokeClass.md): Get the border-thickness class for a component from its stroke variant prop.
|
|
20647
20648
|
- [getTypographyClass()](ui/getTypographyClass.md): Get the typography class for a component from its typographic variant props.
|
|
20648
20649
|
- [getWidthClass()](ui/getWidthClass.md): Get the width class for a component from its width / grow variant props.
|
|
20649
|
-
- [
|
|
20650
|
+
- [useSwipe()](ui/useSwipe.md): Swipe a target to complete a change, and scrub the change's view transition with the finger.
|
|
20650
20651
|
- [setTransitionType()](ui/setTransitionType.md): Type-safe passthrough for React's addTransitionType() that checks type is one of our known view-transition types.
|
|
20651
20652
|
- [useTreeMap()](ui/useTreeMap.md): Use the flattened tree lookup map from context.
|
|
20652
20653
|
- [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.
|
|
@@ -20690,6 +20691,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20690
20691
|
- [NoticesStore](ui/NoticesStore.md): Store holding the live list of NoticeStore notices currently shown.
|
|
20691
20692
|
- [NoticeStore](ui/NoticeStore.md): Store holding a single notice's content and status, owned by a NoticesStore.
|
|
20692
20693
|
- [NavigationSequence](ui/NavigationSequence.md): Sequence of navigation events that drives browser history and keeps a stack of pages for each tab.
|
|
20694
|
+
- [TransitionScrub](ui/TransitionScrub.md): Take manual control of the view transition that an update starts.
|
|
20693
20695
|
|
|
20694
20696
|
## Interfaces
|
|
20695
20697
|
|
|
@@ -20726,6 +20728,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20726
20728
|
- [SubmitButtonProps](ui/SubmitButtonProps.md): Component props for <SubmitButton>, a form submit button.
|
|
20727
20729
|
- [DialogProps](ui/DialogProps.md): Props for <Dialog> — optional children content and an onClose callback.
|
|
20728
20730
|
- [DialogCloseButtonProps](ui/DialogCloseButtonProps.md): Props for <DialogCloseButton> — button styling variants and optional children to override the X icon.
|
|
20731
|
+
- [DialogControl](ui/DialogControl.md): Controls for the nearest <Dialog>, so a <Modal> inside it can swipe it away.
|
|
20729
20732
|
- [DialogsContextProps](ui/DialogsContextProps.md): Props for <DialogsContext> — the children subtree the dialogs store is provided to.
|
|
20730
20733
|
- [DialogsProps](ui/DialogsProps.md): Props for <Dialogs> — takes no props (branded empty interface).
|
|
20731
20734
|
- [ModalVariants](ui/ModalVariants.md): Variant props for <Modal> — pin the panel to one edge of the screen.
|
|
@@ -20856,6 +20859,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20856
20859
|
- [HorizontalTransitionProps](ui/HorizontalTransitionProps.md): Props for the HorizontalTransition component — the shared transition variant props.
|
|
20857
20860
|
- [TransitionVariants](ui/TransitionVariants.md): Variant props shared by every transition component.
|
|
20858
20861
|
- [TransitionProps](ui/TransitionProps.md): React props for <Transition> component.
|
|
20862
|
+
- [SwipeOptions](ui/SwipeOptions.md): Options for useSwipe().
|
|
20859
20863
|
- [VerticalTransitionProps](ui/VerticalTransitionProps.md): Props for the VerticalTransition component — the shared transition variant props.
|
|
20860
20864
|
- [TreeAppProps](ui/TreeAppProps.md): Props for the TreeApp component — the tree to render plus optional extra routes and app meta.
|
|
20861
20865
|
- [TreeBreadcrumbsProps](ui/TreeBreadcrumbsProps.md): Props for the TreeBreadcrumbs component — typography, space, and flex variant props.
|
|
@@ -20904,6 +20908,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20904
20908
|
- [CaseVariant](ui/CaseVariant.md): Allowed values for text case for components that support TypographyVariants
|
|
20905
20909
|
- [FontVariant](ui/FontVariant.md): Allowed values for font family for components that support TypographyVariants
|
|
20906
20910
|
- [WidthVariant](ui/WidthVariant.md): Enumerated width selectable via the width variant prop.
|
|
20911
|
+
- [SwipeDirection](ui/SwipeDirection.md): Which way the finger moves to complete a swipe.
|
|
20907
20912
|
- [TransitionClasses](ui/TransitionClasses.md): Map of view-transition types to their CSS class names in { type: className } format.
|
|
20908
20913
|
- [TransitionType](ui/TransitionType.md): Known view-transition type names that all transitions support — the keys of TransitionClasses.
|
|
20909
20914
|
- [Classes](ui/Classes.md): Set of classnames that can be joined into a single className string.
|
|
@@ -20919,6 +20924,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20919
20924
|
## Constants
|
|
20920
20925
|
|
|
20921
20926
|
- [RetryContext](ui/RetryContext.md): Context for providing a "retry" callback to descendant <RetryButton> elements.
|
|
20927
|
+
- [DialogControlContext](ui/DialogControlContext.md): Context with the controls for the nearest <Dialog>, or undefined outside one (or in a <Dialog> with no onClose).
|
|
20922
20928
|
- [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" `.
|
|
20923
20929
|
- [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.
|
|
20924
20930
|
- [PLAYGROUND_FRAME_PATH](ui/PLAYGROUND_FRAME_PATH.md): Path of the frame page that runs playground code, relative to the docs site root.
|
|
@@ -24057,21 +24063,24 @@ Props for `<Dialog>` — optional `children` content and an `onClose` callback.
|
|
|
24057
24063
|
- Kind: component
|
|
24058
24064
|
- Import: `import { Dialog } from "shelving/ui";`
|
|
24059
24065
|
|
|
24060
|
-
Modal `<dialog>` element that opens on mount
|
|
24066
|
+
Modal `<dialog>` element that opens on mount.
|
|
24061
24067
|
|
|
24062
|
-
- Opens via `showModal()` when mounted, and closes on a tap anywhere on it,
|
|
24068
|
+
- Opens via `showModal()` when mounted, and closes on a tap anywhere on it, or the Escape key.
|
|
24069
|
+
- It has no close button. Give the content an explicit button that closes it (for example "OK"), or add a `<DialogCloseButton>`.
|
|
24063
24070
|
- 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
24071
|
- 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
24072
|
- A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
|
|
24066
24073
|
- 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.
|
|
24067
24074
|
- 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
24075
|
- Wraps content in `<Suspense>` so lazy children can stream in.
|
|
24076
|
+
- 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.
|
|
24069
24077
|
|
|
24070
|
-
A native `<dialog>` element opened in modal mode. It opens via `showModal()` when mounted
|
|
24078
|
+
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
24079
|
|
|
24072
24080
|
**Things to know:**
|
|
24073
24081
|
|
|
24074
|
-
- Closes on a tap anywhere on it, the Escape key
|
|
24082
|
+
- Closes on a tap anywhere on it, or the Escape key.
|
|
24083
|
+
- 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
24084
|
- 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
24085
|
- Children render inside a `<Suspense>` boundary, so lazy content can stream in.
|
|
24077
24086
|
- 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.
|
|
@@ -24087,6 +24096,7 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
|
|
|
24087
24096
|
- 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.
|
|
24088
24097
|
- To open a dialog from app code, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
|
|
24089
24098
|
- A browser without view transitions shows and hides the dialog at once.
|
|
24099
|
+
- 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).
|
|
24090
24100
|
- Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
|
|
24091
24101
|
|
|
24092
24102
|
## Usage
|
|
@@ -24150,7 +24160,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
|
|
|
24150
24160
|
|
|
24151
24161
|
## Styling
|
|
24152
24162
|
|
|
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
|
|
24163
|
+
`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
24164
|
|
|
24155
24165
|
| Variable | Styles | Default |
|
|
24156
24166
|
| ----------------------- | -------------------------------------------------------------- | ----------------------------- |
|
|
@@ -24159,7 +24169,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
|
|
|
24159
24169
|
| `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
|
|
24160
24170
|
| `--dialog-background` | Overlay fill behind the content | `var(--color-backdrop)` |
|
|
24161
24171
|
| `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
|
|
24162
|
-
| `--dialog-close-offset` | Inset of
|
|
24172
|
+
| `--dialog-close-offset` | Inset of a `<DialogCloseButton>` from the top-right corner | `var(--space-small)` (12px) |
|
|
24163
24173
|
|
|
24164
24174
|
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
24175
|
|
|
@@ -24224,8 +24234,10 @@ Props for `<DialogCloseButton>` — button styling variants and optional `childr
|
|
|
24224
24234
|
- Import: `import { DialogCloseButton } from "shelving/ui";`
|
|
24225
24235
|
|
|
24226
24236
|
Button that closes its wrapping `<dialog>`, showing an X icon by default.
|
|
24227
|
-
-
|
|
24228
|
-
-
|
|
24237
|
+
- A `<Dialog>` has no close button of its own. Put this anywhere inside the dialog to add one.
|
|
24238
|
+
- It is fixed to the top-right corner of the screen, clear of the safe areas.
|
|
24239
|
+
- Styled with the shared `Button` classes.
|
|
24240
|
+
- `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
24241
|
|
|
24230
24242
|
## Signatures
|
|
24231
24243
|
|
|
@@ -24233,6 +24245,7 @@ Button that closes its wrapping `<dialog>`, showing an X icon by default.
|
|
|
24233
24245
|
DialogCloseButton({
|
|
24234
24246
|
children = <CloseIcon />,
|
|
24235
24247
|
plain = true,
|
|
24248
|
+
small = true,
|
|
24236
24249
|
className,
|
|
24237
24250
|
...variants
|
|
24238
24251
|
}: DialogCloseButtonProps): ReactElement
|
|
@@ -24251,6 +24264,45 @@ DialogCloseButton({
|
|
|
24251
24264
|
| `ReactElement` | |
|
|
24252
24265
|
|
|
24253
24266
|
|
|
24267
|
+
---
|
|
24268
|
+
|
|
24269
|
+
# DialogControl
|
|
24270
|
+
|
|
24271
|
+
- Kind: interface
|
|
24272
|
+
- Import: `import { DialogControl } from "shelving/ui";`
|
|
24273
|
+
|
|
24274
|
+
Controls for the nearest `<Dialog>`, so a `<Modal>` inside it can swipe it away.
|
|
24275
|
+
- Internal: not exported from the `shelving/ui` barrel.
|
|
24276
|
+
|
|
24277
|
+
## Signatures
|
|
24278
|
+
|
|
24279
|
+
```ts
|
|
24280
|
+
{
|
|
24281
|
+
readonly hide: () => void;
|
|
24282
|
+
readonly show: () => Promise<void>;
|
|
24283
|
+
readonly close: () => void;
|
|
24284
|
+
}
|
|
24285
|
+
```
|
|
24286
|
+
|
|
24287
|
+
## Properties
|
|
24288
|
+
|
|
24289
|
+
| Property | Type | Description |
|
|
24290
|
+
| --- | --- | --- |
|
|
24291
|
+
| `hide` | `() => void` | Hide the dialog in a `"dialog"` transition, so its exit transition runs. It stays mounted, with its state. Read only. |
|
|
24292
|
+
| `show` | `() => Promise<void>` | Show the hidden dialog again at once, with no transition. Resolves after React commits it. Read only. |
|
|
24293
|
+
| `close` | `() => void` | Close the dialog for real (calls its `onClose`). Read only. |
|
|
24294
|
+
|
|
24295
|
+
|
|
24296
|
+
---
|
|
24297
|
+
|
|
24298
|
+
# DialogControlContext
|
|
24299
|
+
|
|
24300
|
+
- Kind: constant
|
|
24301
|
+
- Import: `import { DialogControlContext } from "shelving/ui";`
|
|
24302
|
+
|
|
24303
|
+
Context with the controls for the nearest `<Dialog>`, or `undefined` outside one (or in a `<Dialog>` with no `onClose`).
|
|
24304
|
+
|
|
24305
|
+
|
|
24254
24306
|
---
|
|
24255
24307
|
|
|
24256
24308
|
# DialogsStore
|
|
@@ -24470,6 +24522,7 @@ Styled `<aside>` panel for content inside a `<Dialog>`, with dark text on a ligh
|
|
|
24470
24522
|
- Centred by default. It fades in and out with its `<Dialog>`.
|
|
24471
24523
|
- Has a `--shadow-large` drop shadow by default. Set `shadow="none"`, `shadow="small"` or `shadow="normal"` to change it.
|
|
24472
24524
|
- `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.
|
|
24525
|
+
- 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.
|
|
24473
24526
|
|
|
24474
24527
|
The panel inside a `<Dialog>`. `<Dialog>` dims the page; `Modal` gives the content a shadowed surface with dark text on a light fill.
|
|
24475
24528
|
|
|
@@ -24486,6 +24539,8 @@ The panel inside a `<Dialog>`. `<Dialog>` dims the page; `Modal` gives the conte
|
|
|
24486
24539
|
- It has a `--shadow-large` drop shadow by default. Set `shadow="none"`, `shadow="small"` or `shadow="normal"` to change it, the same as on `<Card>`.
|
|
24487
24540
|
- Set `top`, `right`, `bottom`, or `left` to pin the panel to that edge of the screen. A top or bottom panel is full width up to `--modal-width`, and centred on a wider screen. A left or right panel is full height. Use these for mobile menus, bottom sheets, and side menus.
|
|
24488
24541
|
- A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place. `Modal` has no transition of its own: it animates only when its `<Dialog>` does (see `Dialog`).
|
|
24542
|
+
- In a `<Dialog>` with `onClose` (every dialog from `DialogsStore.show()`), a pinned panel can be swiped toward its edge to close the dialog: down for `bottom`, up for `top`, and so on. The swipe scrubs the same slide-out with the finger, through `useSwipe()`. Release past about a third, or flick, to close. Otherwise the panel slides back, and the dialog keeps its state.
|
|
24543
|
+
- A swipeable panel shows a grab handle: a short rounded bar on the side away from its edge.
|
|
24489
24544
|
|
|
24490
24545
|
## Usage
|
|
24491
24546
|
|
|
@@ -24595,8 +24650,9 @@ A link click inside a `<Dialog>` closes it, so the menu slides out as the page c
|
|
|
24595
24650
|
| `--modal-max-height` | Maximum height of a `top` or `bottom` panel (it scrolls past this) | `100%` |
|
|
24596
24651
|
| `--modal-transition-duration` | Length of the slide for a pinned panel. Keep it the same as `--fade-transition-duration`, so the panel and the `<Dialog>` overlay finish together | `var(--duration-fast)` (150ms) |
|
|
24597
24652
|
| `--modal-shadow` | Drop shadow (the `shadow` variant wins over it) | `var(--shadow-large)` |
|
|
24653
|
+
| `--modal-handle-color` | Colour of the grab handle on a swipeable pinned panel | `var(--tint-80)` |
|
|
24598
24654
|
|
|
24599
|
-
**Global tokens it reads** — move these to retheme broadly: the tint ladder `--tint-00` / `--tint-80` / `--tint-100`, plus `--width-narrow`, `--space-normal`, `--radius-normal`, `--shadow-large`, and `--duration-fast`.
|
|
24655
|
+
**Global tokens it reads** — move these to retheme broadly: the tint ladder `--tint-00` / `--tint-80` / `--tint-100`, plus `--width-narrow`, `--space-xsmall`, `--space-normal`, `--radius-normal`, `--shadow-large`, and `--duration-fast`.
|
|
24600
24656
|
|
|
24601
24657
|
|
|
24602
24658
|
## Signatures
|
|
@@ -32771,6 +32827,7 @@ Props for `<Notice>` — flex/colour/status styling variants, optional `children
|
|
|
32771
32827
|
```ts
|
|
32772
32828
|
{
|
|
32773
32829
|
icon?: ReactElement | false | undefined;
|
|
32830
|
+
ref?: Ref<HTMLElement> | undefined;
|
|
32774
32831
|
}
|
|
32775
32832
|
```
|
|
32776
32833
|
|
|
@@ -32779,6 +32836,7 @@ Props for `<Notice>` — flex/colour/status styling variants, optional `children
|
|
|
32779
32836
|
| Property | Type | Description |
|
|
32780
32837
|
| --- | --- | --- |
|
|
32781
32838
|
| `icon` | `ReactElement \| false \| undefined` | Icon for the notice (or `null` or `false` to hide the icon, defaults to `<StatusIcon>`). Optional. |
|
|
32839
|
+
| `ref` | `Ref<HTMLElement> \| undefined` | Ref to the notice's `<aside>` element. Optional. |
|
|
32782
32840
|
|
|
32783
32841
|
|
|
32784
32842
|
---
|
|
@@ -32847,6 +32905,7 @@ Notice({
|
|
|
32847
32905
|
children, //
|
|
32848
32906
|
icon,
|
|
32849
32907
|
className,
|
|
32908
|
+
ref,
|
|
32850
32909
|
...props
|
|
32851
32910
|
}: NoticeProps): void
|
|
32852
32911
|
```
|
|
@@ -32857,6 +32916,7 @@ Notice({
|
|
|
32857
32916
|
| --- | --- | --- |
|
|
32858
32917
|
| `props` | `NoticeProps` | |
|
|
32859
32918
|
| `.icon` | `ReactElement \| false \| undefined` | Icon for the notice (or `null` or `false` to hide the icon, defaults to `<StatusIcon>`). Optional. |
|
|
32919
|
+
| `.ref` | `Ref<HTMLElement> \| undefined` | Ref to the notice's `<aside>` element. Optional. |
|
|
32860
32920
|
|
|
32861
32921
|
|
|
32862
32922
|
---
|
|
@@ -32933,6 +32993,7 @@ Renders the global list of active notices and subscribes to incoming `"notice"`
|
|
|
32933
32993
|
- 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.
|
|
32934
32994
|
- 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.
|
|
32935
32995
|
- The list has its own layer in every view transition, so it stays still above a page that slides under it.
|
|
32996
|
+
- 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.
|
|
32936
32997
|
- 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.
|
|
32937
32998
|
|
|
32938
32999
|
## Usage
|
|
@@ -33499,6 +33560,60 @@ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props
|
|
|
33499
33560
|
| `ReactElement \| null` | |
|
|
33500
33561
|
|
|
33501
33562
|
|
|
33563
|
+
---
|
|
33564
|
+
|
|
33565
|
+
# BackSwipe
|
|
33566
|
+
|
|
33567
|
+
- Kind: component
|
|
33568
|
+
- Import: `import { BackSwipe } from "shelving/ui";`
|
|
33569
|
+
|
|
33570
|
+
Swipe from the left edge of the screen to go back one page in the current stack, by scrubbing the normal back slide.
|
|
33571
|
+
|
|
33572
|
+
- It renders nothing. Put it inside `<Navigation>`, next to the pages.
|
|
33573
|
+
- When the swipe starts, it publishes the page below as a `"back"` event with `NavigationSequence.publish()`. History does not change. `<Navigation>` shows that page in a back transition, and `useSwipe()` scrubs it.
|
|
33574
|
+
- On release it plays the slide to the end and calls `NavigationSequence.back()`, which publishes the same page again (skipped, so no second slide). Or it plays the slide back and publishes the page it started on again. A cancelled swipe never changes the URL.
|
|
33575
|
+
- On the bottom page of a stack, or on a floating page, it does nothing, so it never goes back into another tab.
|
|
33576
|
+
- It ignores touches in a `<nav>` and in dialogs.
|
|
33577
|
+
|
|
33578
|
+
Swipe from the left edge of the screen to go back one page in the current stack, by scrubbing the normal back slide with the finger.
|
|
33579
|
+
|
|
33580
|
+
**Things to know:**
|
|
33581
|
+
|
|
33582
|
+
- It renders nothing. Put it inside `<Navigation>`, next to the pages.
|
|
33583
|
+
- It is built on `useSwipe()`. When the swipe starts, it publishes the page below as a `"back"` event with `NavigationSequence.publish()`. History does not change yet. `<Navigation>` shows that page in a back transition, with every transition the layout has, and the finger scrubs it.
|
|
33584
|
+
- On release past about a third, or after a flick, the slide ends and it calls `NavigationSequence.back()`. That publishes the same page again, which `<Navigation>` skips, so there is no second slide.
|
|
33585
|
+
- A swipe that goes back plays the slide back and publishes the page it started on again. The URL never changes.
|
|
33586
|
+
- On the bottom page of a stack, or on a floating page, it does nothing, so it never goes back into another tab.
|
|
33587
|
+
- It ignores touches in a `<nav>` and in dialogs.
|
|
33588
|
+
- Browsers and web apps on iOS have their own edge swipe. Render `BackSwipe` only where the app owns the gesture, for example in a native wrapper.
|
|
33589
|
+
|
|
33590
|
+
## Usage
|
|
33591
|
+
|
|
33592
|
+
```tsx
|
|
33593
|
+
import { BackSwipe, Navigation, RouteCache, Router } from "shelving/ui";
|
|
33594
|
+
|
|
33595
|
+
<Navigation>
|
|
33596
|
+
<BackSwipe />
|
|
33597
|
+
<RouteCache>
|
|
33598
|
+
<Router routes={ROUTES} />
|
|
33599
|
+
</RouteCache>
|
|
33600
|
+
</Navigation>;
|
|
33601
|
+
```
|
|
33602
|
+
|
|
33603
|
+
|
|
33604
|
+
## Signatures
|
|
33605
|
+
|
|
33606
|
+
```ts
|
|
33607
|
+
BackSwipe(): null
|
|
33608
|
+
```
|
|
33609
|
+
|
|
33610
|
+
## Returns
|
|
33611
|
+
|
|
33612
|
+
| Type | Description |
|
|
33613
|
+
| --- | --- |
|
|
33614
|
+
| `null` | |
|
|
33615
|
+
|
|
33616
|
+
|
|
33502
33617
|
---
|
|
33503
33618
|
|
|
33504
33619
|
# NavigationProps
|
|
@@ -37390,34 +37505,275 @@ Transition({ children, default: d, forward = d, back = d, overlay = false }: Tra
|
|
|
37390
37505
|
|
|
37391
37506
|
---
|
|
37392
37507
|
|
|
37393
|
-
#
|
|
37508
|
+
# TransitionScrub
|
|
37394
37509
|
|
|
37395
|
-
- Kind:
|
|
37396
|
-
- Import: `import {
|
|
37510
|
+
- Kind: class
|
|
37511
|
+
- Import: `import { TransitionScrub } from "shelving/ui";`
|
|
37397
37512
|
|
|
37398
|
-
|
|
37513
|
+
Take manual control of the view transition that an update starts.
|
|
37514
|
+
|
|
37515
|
+
- 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()`).
|
|
37516
|
+
- When the transition is ready, it pauses every animation of the transition, so `seek()` can move it by hand.
|
|
37517
|
+
- `finish()` plays it to the end. `cancel()` plays it back to the start, runs an undo, and ends it.
|
|
37518
|
+
- 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.
|
|
37519
|
+
- If `update()` returns `false`, nothing is caught, and `started` is `false`.
|
|
37520
|
+
- Only one view transition runs at a time. A new one skips this one, which ends it at its end state.
|
|
37521
|
+
|
|
37522
|
+
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.
|
|
37523
|
+
|
|
37524
|
+
**Things to know:**
|
|
37525
|
+
|
|
37526
|
+
- 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()`.
|
|
37527
|
+
- When the transition is ready, every animation in it is paused. `TransitionScrub.seek()` moves them, from `0` (start) to `1` (end).
|
|
37528
|
+
- `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.
|
|
37529
|
+
- If the update returns `false`, nothing is caught and `TransitionScrub.started` is `false`.
|
|
37530
|
+
- 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.
|
|
37531
|
+
- Only one view transition runs at a time. Another one that starts skips this one to its end.
|
|
37532
|
+
- `useSwipe()` drives a `TransitionScrub` from a finger. Use the class directly for other inputs, such as a slider.
|
|
37533
|
+
|
|
37534
|
+
## Usage
|
|
37535
|
+
|
|
37536
|
+
```ts
|
|
37537
|
+
import { TransitionScrub } from "shelving/ui";
|
|
37538
|
+
|
|
37539
|
+
const scrub = new TransitionScrub(() => dialogs.delete(dialog));
|
|
37540
|
+
scrub.seek(0.4); // 40% of the way through the close.
|
|
37541
|
+
await scrub.finish(); // Play to the end.
|
|
37542
|
+
// Or play back to the start and undo the change:
|
|
37543
|
+
await scrub.cancel(() => dialogs.add(dialog));
|
|
37544
|
+
```
|
|
37399
37545
|
|
|
37400
|
-
- `useStore()` uses `useSyncExternalStore()`, and React always applies those updates synchronously. A synchronous update never starts a view transition.
|
|
37401
|
-
- This hook copies the value into React state inside `startTransition()` instead.
|
|
37402
|
-
- Internal for now: not exported from the `shelving/ui` barrel.
|
|
37403
37546
|
|
|
37404
37547
|
## Signatures
|
|
37405
37548
|
|
|
37406
37549
|
```ts
|
|
37407
|
-
|
|
37550
|
+
new TransitionScrub(update: () => unknown)
|
|
37408
37551
|
```
|
|
37409
37552
|
|
|
37410
37553
|
## Parameters
|
|
37411
37554
|
|
|
37412
37555
|
| Param | Type | Description |
|
|
37413
37556
|
| --- | --- | --- |
|
|
37414
|
-
| `
|
|
37557
|
+
| `update` | `() => unknown` | A change that starts a view transition. Return `false` to start nothing. |
|
|
37415
37558
|
|
|
37416
37559
|
## Returns
|
|
37417
37560
|
|
|
37418
37561
|
| Type | Description |
|
|
37419
37562
|
| --- | --- |
|
|
37420
|
-
| `
|
|
37563
|
+
| `TransitionScrub` | |
|
|
37564
|
+
|
|
37565
|
+
## Properties
|
|
37566
|
+
|
|
37567
|
+
| Property | Type | Description |
|
|
37568
|
+
| --- | --- | --- |
|
|
37569
|
+
| `started` | `boolean` | `false` if `update()` returned `false`, so there is nothing to scrub. Read only. |
|
|
37570
|
+
|
|
37571
|
+
## Methods
|
|
37572
|
+
|
|
37573
|
+
- [TransitionScrub.seek()](ui/TransitionScrub/seek.md): Move the transition to a point, from 0 (start) to 1 (end).
|
|
37574
|
+
- [TransitionScrub.finish()](ui/TransitionScrub/finish.md): Play the transition from where it is to the end, then end it.
|
|
37575
|
+
- [TransitionScrub.cancel()](ui/TransitionScrub/cancel.md): Play the transition back to the start, run undo(), and then end the transition.
|
|
37576
|
+
|
|
37577
|
+
|
|
37578
|
+
---
|
|
37579
|
+
|
|
37580
|
+
# TransitionScrub.seek()
|
|
37581
|
+
|
|
37582
|
+
- Kind: method
|
|
37583
|
+
- Member of: `TransitionScrub`
|
|
37584
|
+
|
|
37585
|
+
Move the transition to a point, from `0` (start) to `1` (end).
|
|
37586
|
+
- Safe to call before the transition is ready: it moves there as soon as it is.
|
|
37587
|
+
|
|
37588
|
+
## Signatures
|
|
37589
|
+
|
|
37590
|
+
```ts
|
|
37591
|
+
seek(progress: number): void
|
|
37592
|
+
```
|
|
37593
|
+
|
|
37594
|
+
|
|
37595
|
+
---
|
|
37596
|
+
|
|
37597
|
+
# TransitionScrub.finish()
|
|
37598
|
+
|
|
37599
|
+
- Kind: method
|
|
37600
|
+
- Member of: `TransitionScrub`
|
|
37601
|
+
|
|
37602
|
+
Play the transition from where it is to the end, then end it.
|
|
37603
|
+
|
|
37604
|
+
## Signatures
|
|
37605
|
+
|
|
37606
|
+
```ts
|
|
37607
|
+
finish(): Promise<void>
|
|
37608
|
+
```
|
|
37609
|
+
|
|
37610
|
+
|
|
37611
|
+
---
|
|
37612
|
+
|
|
37613
|
+
# TransitionScrub.cancel()
|
|
37614
|
+
|
|
37615
|
+
- Kind: method
|
|
37616
|
+
- Member of: `TransitionScrub`
|
|
37617
|
+
|
|
37618
|
+
Play the transition back to the start, run `undo()`, and then end the transition.
|
|
37619
|
+
- `undo()` must put back the state from before the update, so the page matches the start of the transition when it ends.
|
|
37620
|
+
- If `undo()` returns a promise (for example one that resolves after React commits), it waits for it before it ends the transition.
|
|
37621
|
+
|
|
37622
|
+
## Signatures
|
|
37623
|
+
|
|
37624
|
+
```ts
|
|
37625
|
+
cancel(undo: () => PromiseLike<void> | void): Promise<void>
|
|
37626
|
+
```
|
|
37627
|
+
|
|
37628
|
+
|
|
37629
|
+
---
|
|
37630
|
+
|
|
37631
|
+
# SwipeDirection
|
|
37632
|
+
|
|
37633
|
+
- Kind: type
|
|
37634
|
+
- Import: `import { SwipeDirection } from "shelving/ui";`
|
|
37635
|
+
|
|
37636
|
+
Which way the finger moves to complete a swipe.
|
|
37637
|
+
|
|
37638
|
+
## Signatures
|
|
37639
|
+
|
|
37640
|
+
```ts
|
|
37641
|
+
"up" | "down" | "left" | "right"
|
|
37642
|
+
```
|
|
37643
|
+
|
|
37644
|
+
|
|
37645
|
+
---
|
|
37646
|
+
|
|
37647
|
+
# SwipeOptions
|
|
37648
|
+
|
|
37649
|
+
- Kind: interface
|
|
37650
|
+
- Import: `import { SwipeOptions } from "shelving/ui";`
|
|
37651
|
+
|
|
37652
|
+
Options for `useSwipe()`.
|
|
37653
|
+
|
|
37654
|
+
## Signatures
|
|
37655
|
+
|
|
37656
|
+
```ts
|
|
37657
|
+
{
|
|
37658
|
+
readonly direction: SwipeDirection;
|
|
37659
|
+
readonly start: () => unknown;
|
|
37660
|
+
readonly cancel: () => PromiseLike<void> | void;
|
|
37661
|
+
readonly commit?: (() => void) | undefined;
|
|
37662
|
+
readonly edge?: number | undefined;
|
|
37663
|
+
readonly distance?: number | undefined;
|
|
37664
|
+
readonly ignore?: string | undefined;
|
|
37665
|
+
readonly disabled?: boolean | undefined;
|
|
37666
|
+
}
|
|
37667
|
+
```
|
|
37668
|
+
|
|
37669
|
+
## Properties
|
|
37670
|
+
|
|
37671
|
+
| Property | Type | Description |
|
|
37672
|
+
| --- | --- | --- |
|
|
37673
|
+
| `direction` | `SwipeDirection` | Which way the finger moves to complete the swipe. Read only. |
|
|
37674
|
+
| `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. |
|
|
37675
|
+
| `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. |
|
|
37676
|
+
| `commit` | `(() => void) \| undefined` | Finish the change for real, after the slide reaches the end. Read only. Optional. |
|
|
37677
|
+
| `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. |
|
|
37678
|
+
| `distance` | `number \| undefined` | Part of the target's size a slow drag must pass to complete. Read only. Defaults to `0.35`. |
|
|
37679
|
+
| `ignore` | `string \| undefined` | Never start a swipe on an element inside one that matches this selector, for example `"nav"`. Read only. Optional. |
|
|
37680
|
+
| `disabled` | `boolean \| undefined` | Turn the swipe off. Read only. Optional. |
|
|
37681
|
+
|
|
37682
|
+
|
|
37683
|
+
---
|
|
37684
|
+
|
|
37685
|
+
# useSwipe()
|
|
37686
|
+
|
|
37687
|
+
- Kind: function
|
|
37688
|
+
- Import: `import { useSwipe } from "shelving/ui";`
|
|
37689
|
+
|
|
37690
|
+
Swipe a target to complete a change, and scrub the change's view transition with the finger.
|
|
37691
|
+
|
|
37692
|
+
- When the finger moves the right way, it calls `start()` and catches the view transition that starts, with `TransitionScrub`.
|
|
37693
|
+
- 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`).
|
|
37694
|
+
- 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()`.
|
|
37695
|
+
- 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.
|
|
37696
|
+
- 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.
|
|
37697
|
+
|
|
37698
|
+
Swipe an element (or the whole page) to make a change, and scrub the change's view transition with the finger.
|
|
37699
|
+
|
|
37700
|
+
**Things to know:**
|
|
37701
|
+
|
|
37702
|
+
- 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.
|
|
37703
|
+
- `start` runs when the finger has moved a few pixels in `direction`. Return `false` from it to start no swipe.
|
|
37704
|
+
- 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`).
|
|
37705
|
+
- 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.
|
|
37706
|
+
- 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.
|
|
37707
|
+
- `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.
|
|
37708
|
+
- 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.
|
|
37709
|
+
- 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.
|
|
37710
|
+
|
|
37711
|
+
## Usage
|
|
37712
|
+
|
|
37713
|
+
### Swipe a panel down to close it
|
|
37714
|
+
|
|
37715
|
+
`<Modal>` does this for every pinned panel in a `<Dialog>`:
|
|
37716
|
+
|
|
37717
|
+
```tsx
|
|
37718
|
+
const ref = useRef<HTMLElement>(null);
|
|
37719
|
+
useSwipe(ref, {
|
|
37720
|
+
direction: "down",
|
|
37721
|
+
start: () => dialog.hide(), // Hide in a transition.
|
|
37722
|
+
cancel: () => dialog.show(), // Show again at once.
|
|
37723
|
+
commit: () => dialog.close(),
|
|
37724
|
+
});
|
|
37725
|
+
```
|
|
37726
|
+
|
|
37727
|
+
### Swipe a notice away
|
|
37728
|
+
|
|
37729
|
+
A notice holds no state, so removing it and adding it back is enough:
|
|
37730
|
+
|
|
37731
|
+
```tsx
|
|
37732
|
+
useSwipe(ref, {
|
|
37733
|
+
direction: "right",
|
|
37734
|
+
start: () => notice.close(),
|
|
37735
|
+
cancel: () => NOTICES.add(notice),
|
|
37736
|
+
});
|
|
37737
|
+
```
|
|
37738
|
+
|
|
37739
|
+
### Swipe between tabs
|
|
37740
|
+
|
|
37741
|
+
```tsx
|
|
37742
|
+
useSwipe(ref, {
|
|
37743
|
+
direction: "left",
|
|
37744
|
+
start: () => {
|
|
37745
|
+
if (!next) return false;
|
|
37746
|
+
startTransition(() => {
|
|
37747
|
+
addTransitionType("tab-forward");
|
|
37748
|
+
setShown(next);
|
|
37749
|
+
});
|
|
37750
|
+
},
|
|
37751
|
+
cancel: () => flushSync(() => setShown(current)),
|
|
37752
|
+
commit: () => setTab(next),
|
|
37753
|
+
});
|
|
37754
|
+
```
|
|
37755
|
+
|
|
37756
|
+
|
|
37757
|
+
## Signatures
|
|
37758
|
+
|
|
37759
|
+
```ts
|
|
37760
|
+
useSwipe(target: RefObject<Element | null> | Document, options: SwipeOptions): void
|
|
37761
|
+
```
|
|
37762
|
+
|
|
37763
|
+
## Parameters
|
|
37764
|
+
|
|
37765
|
+
| Param | Type | Description |
|
|
37766
|
+
| --- | --- | --- |
|
|
37767
|
+
| `target` | `RefObject<Element \| null> \| Document` | The element to swipe, or `document` for the whole page. |
|
|
37768
|
+
| `options` | `SwipeOptions` | What the swipe does. |
|
|
37769
|
+
| `.direction` | `SwipeDirection` | Which way the finger moves to complete the swipe. Read only. |
|
|
37770
|
+
| `.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. |
|
|
37771
|
+
| `.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. |
|
|
37772
|
+
| `.commit` | `(() => void) \| undefined` | Finish the change for real, after the slide reaches the end. Read only. Optional. |
|
|
37773
|
+
| `.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. |
|
|
37774
|
+
| `.distance` | `number \| undefined` | Part of the target's size a slow drag must pass to complete. Read only. Defaults to `0.35`. |
|
|
37775
|
+
| `.ignore` | `string \| undefined` | Never start a swipe on an element inside one that matches this selector, for example `"nav"`. Read only. Optional. |
|
|
37776
|
+
| `.disabled` | `boolean \| undefined` | Turn the swipe off. Read only. Optional. |
|
|
37421
37777
|
|
|
37422
37778
|
|
|
37423
37779
|
---
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# BackSwipe
|
|
2
|
+
|
|
3
|
+
- Kind: component
|
|
4
|
+
- Import: `import { BackSwipe } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Swipe from the left edge of the screen to go back one page in the current stack, by scrubbing the normal back slide.
|
|
7
|
+
|
|
8
|
+
- It renders nothing. Put it inside `<Navigation>`, next to the pages.
|
|
9
|
+
- When the swipe starts, it publishes the page below as a `"back"` event with `NavigationSequence.publish()`. History does not change. `<Navigation>` shows that page in a back transition, and `useSwipe()` scrubs it.
|
|
10
|
+
- On release it plays the slide to the end and calls `NavigationSequence.back()`, which publishes the same page again (skipped, so no second slide). Or it plays the slide back and publishes the page it started on again. A cancelled swipe never changes the URL.
|
|
11
|
+
- On the bottom page of a stack, or on a floating page, it does nothing, so it never goes back into another tab.
|
|
12
|
+
- It ignores touches in a `<nav>` and in dialogs.
|
|
13
|
+
|
|
14
|
+
Swipe from the left edge of the screen to go back one page in the current stack, by scrubbing the normal back slide with the finger.
|
|
15
|
+
|
|
16
|
+
**Things to know:**
|
|
17
|
+
|
|
18
|
+
- It renders nothing. Put it inside `<Navigation>`, next to the pages.
|
|
19
|
+
- It is built on `useSwipe()`. When the swipe starts, it publishes the page below as a `"back"` event with `NavigationSequence.publish()`. History does not change yet. `<Navigation>` shows that page in a back transition, with every transition the layout has, and the finger scrubs it.
|
|
20
|
+
- On release past about a third, or after a flick, the slide ends and it calls `NavigationSequence.back()`. That publishes the same page again, which `<Navigation>` skips, so there is no second slide.
|
|
21
|
+
- A swipe that goes back plays the slide back and publishes the page it started on again. The URL never changes.
|
|
22
|
+
- On the bottom page of a stack, or on a floating page, it does nothing, so it never goes back into another tab.
|
|
23
|
+
- It ignores touches in a `<nav>` and in dialogs.
|
|
24
|
+
- Browsers and web apps on iOS have their own edge swipe. Render `BackSwipe` only where the app owns the gesture, for example in a native wrapper.
|
|
25
|
+
|
|
26
|
+
## Usage
|
|
27
|
+
|
|
28
|
+
```tsx
|
|
29
|
+
import { BackSwipe, Navigation, RouteCache, Router } from "shelving/ui";
|
|
30
|
+
|
|
31
|
+
<Navigation>
|
|
32
|
+
<BackSwipe />
|
|
33
|
+
<RouteCache>
|
|
34
|
+
<Router routes={ROUTES} />
|
|
35
|
+
</RouteCache>
|
|
36
|
+
</Navigation>;
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## Signatures
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
BackSwipe(): null
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Returns
|
|
47
|
+
|
|
48
|
+
| Type | Description |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| `null` | |
|