shelving 1.324.0 → 1.326.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 +86 -8
- package/docs/react/SequenceTransitionOptions.md +2 -0
- package/docs/react/useSequenceTransition.md +1 -0
- package/docs/ui/BackButton.md +12 -4
- package/docs/ui/BackButtonProps.md +3 -3
- package/docs/ui/Navigation.md +1 -0
- package/docs/ui/isKeyboardOpen.md +27 -0
- package/docs/ui/waitForKeyboard.md +29 -0
- package/docs/ui.md +3 -1
- package/package.json +1 -1
- package/react/useSequenceTransition.d.ts +7 -0
- package/react/useSequenceTransition.js +17 -5
- 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.d.ts +1 -0
- package/ui/router/Navigation.js +13 -1
- package/ui/router/Navigation.test.tsx +9 -0
- package/ui/router/Navigation.tsx +13 -1
- package/ui/util/index.d.ts +1 -0
- package/ui/util/index.js +1 -0
- package/ui/util/index.ts +1 -0
- package/ui/util/keyboard.d.ts +24 -0
- package/ui/util/keyboard.js +82 -0
- package/ui/util/keyboard.test.ts +12 -0
- package/ui/util/keyboard.ts +81 -0
package/docs/llms-full.txt
CHANGED
|
@@ -12072,6 +12072,7 @@ Options for `useSequenceTransition()`.
|
|
|
12072
12072
|
readonly current: () => T;
|
|
12073
12073
|
readonly transition?: string | ((value: T) => string | null | undefined) | undefined;
|
|
12074
12074
|
readonly equal?: ((a: T, b: T) => boolean) | undefined;
|
|
12075
|
+
readonly wait?: ((value: T) => PromiseLike<void> | void) | undefined;
|
|
12075
12076
|
}
|
|
12076
12077
|
```
|
|
12077
12078
|
|
|
@@ -12082,6 +12083,7 @@ Options for `useSequenceTransition()`.
|
|
|
12082
12083
|
| `current` | `() => T` | Read the current value. - Called for the first render, and again when the subscription starts, to catch up on values sent before it started. Read only. |
|
|
12083
12084
|
| `transition` | `string \| ((value: T) => string \| null \| undefined) \| undefined` | Transition type for a value, or a fixed type for every value. - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it. - A value with no type (`undefined` or `null`) is set at once, with no transition. Read only. Optional. |
|
|
12084
12085
|
| `equal` | `((a: T, b: T) => boolean) \| undefined` | Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition. Read only. Defaults to `Object.is`. |
|
|
12086
|
+
| `wait` | `((value: T) => PromiseLike<void> \| void) \| undefined` | Wait before a value with a transition type is set, for example until the on-screen keyboard is down. - Return a promise to wait for it, or nothing to set the value at once. - A newer value that arrives while it waits wins: the older value is never set. - Values with no transition type never wait. Read only. Optional. |
|
|
12085
12087
|
|
|
12086
12088
|
|
|
12087
12089
|
---
|
|
@@ -12144,6 +12146,7 @@ useSequenceTransition(sequence: AsyncIterable<T>, options: SequenceTransitionOpt
|
|
|
12144
12146
|
| `.current` | `() => T` | Read the current value. - Called for the first render, and again when the subscription starts, to catch up on values sent before it started. Read only. |
|
|
12145
12147
|
| `.transition` | `string \| ((value: T) => string \| null \| undefined) \| undefined` | Transition type for a value, or a fixed type for every value. - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it. - A value with no type (`undefined` or `null`) is set at once, with no transition. Read only. Optional. |
|
|
12146
12148
|
| `.equal` | `((a: T, b: T) => boolean) \| undefined` | Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition. Read only. Defaults to `Object.is`. |
|
|
12149
|
+
| `.wait` | `((value: T) => PromiseLike<void> \| void) \| undefined` | Wait before a value with a transition type is set, for example until the on-screen keyboard is down. - Return a promise to wait for it, or nothing to set the value at once. - A newer value that arrives while it waits wins: the older value is never set. - Values with no transition type never wait. Read only. Optional. |
|
|
12147
12150
|
|
|
12148
12151
|
## Returns
|
|
12149
12152
|
|
|
@@ -20655,6 +20658,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20655
20658
|
- [focusFirstFocusable()](ui/focusFirstFocusable.md): Focus on the first focusable element inside an element.
|
|
20656
20659
|
- [loopFocus()](ui/loopFocus.md): Loop focus inside an element so it can't escape — refocus the first focusable child when focus moves out.
|
|
20657
20660
|
- [eventLoopFocus()](ui/eventLoopFocus.md): Loop focus inside an element in response to a blur event — a ready-made onBlur handler that traps focus.
|
|
20661
|
+
- [isKeyboardOpen()](ui/isKeyboardOpen.md): Is the on-screen keyboard open (or still closing)?
|
|
20662
|
+
- [waitForKeyboard()](ui/waitForKeyboard.md): Lower the on-screen keyboard, and wait until it is down.
|
|
20658
20663
|
- [joinMetaCSP()](ui/joinMetaCSP.md): Turn a deconstructed MetaCSP into a Content-Security-Policy string.
|
|
20659
20664
|
- [joinTitles()](ui/joinTitles.md): Join several page or site titles together with - , skipping empty values.
|
|
20660
20665
|
- [mergeMeta()](ui/mergeMeta.md): Merge a PossibleMeta onto an existing Meta, resolving URLs and assets in the process.
|
|
@@ -20819,7 +20824,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20819
20824
|
- [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
|
|
20820
20825
|
- [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
|
|
20821
20826
|
- [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
|
|
20822
|
-
- [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>:
|
|
20827
|
+
- [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.
|
|
20823
20828
|
- [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
|
|
20824
20829
|
- [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
|
|
20825
20830
|
- [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
|
|
@@ -33388,13 +33393,13 @@ Page({ children, ...meta }: PageProps): ReactElement
|
|
|
33388
33393
|
- Import: `import { BackButtonProps } from "shelving/ui";`
|
|
33389
33394
|
- Extends: `Omit<ButtonProps, "href" | "onClick">`
|
|
33390
33395
|
|
|
33391
|
-
Props for `<BackButton>`:
|
|
33396
|
+
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`.
|
|
33392
33397
|
|
|
33393
33398
|
## Signatures
|
|
33394
33399
|
|
|
33395
33400
|
```ts
|
|
33396
33401
|
{
|
|
33397
|
-
readonly href
|
|
33402
|
+
readonly href?: AbsolutePath | undefined;
|
|
33398
33403
|
}
|
|
33399
33404
|
```
|
|
33400
33405
|
|
|
@@ -33402,7 +33407,7 @@ Props for `<BackButton>`: the `href` to go back to when the stack has no page be
|
|
|
33402
33407
|
|
|
33403
33408
|
| Property | Type | Description |
|
|
33404
33409
|
| --- | --- | --- |
|
|
33405
|
-
| `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. |
|
|
33410
|
+
| `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. |
|
|
33406
33411
|
|
|
33407
33412
|
|
|
33408
33413
|
---
|
|
@@ -33415,6 +33420,7 @@ Props for `<BackButton>`: the `href` to go back to when the stack has no page be
|
|
|
33415
33420
|
Back button for the current stack.
|
|
33416
33421
|
- Goes back to the page before this one in the current stack, wherever you came from.
|
|
33417
33422
|
- 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.
|
|
33423
|
+
- Renders nothing when the stack has no page before this one and there is no `href` (for example, at the root of a stack).
|
|
33418
33424
|
- It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
|
|
33419
33425
|
|
|
33420
33426
|
The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
|
|
@@ -33422,7 +33428,8 @@ The back button for a page header. It goes back to the page before this one in t
|
|
|
33422
33428
|
**Things to know:**
|
|
33423
33429
|
|
|
33424
33430
|
- 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.
|
|
33425
|
-
- It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page.
|
|
33431
|
+
- 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>`.
|
|
33432
|
+
- 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.
|
|
33426
33433
|
- 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.
|
|
33427
33434
|
- Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
|
|
33428
33435
|
- It takes the usual `<Button>` props, except `onClick`.
|
|
@@ -33447,6 +33454,12 @@ function PostPage({ id }: { id: string }) {
|
|
|
33447
33454
|
}
|
|
33448
33455
|
```
|
|
33449
33456
|
|
|
33457
|
+
Only when there is a page to go back to (nothing at the root of a stack):
|
|
33458
|
+
|
|
33459
|
+
```tsx
|
|
33460
|
+
<BackButton />;
|
|
33461
|
+
```
|
|
33462
|
+
|
|
33450
33463
|
With a label:
|
|
33451
33464
|
|
|
33452
33465
|
```tsx
|
|
@@ -33469,7 +33482,7 @@ To go back to one fixed page (not to the page before), use a link with `classNam
|
|
|
33469
33482
|
## Signatures
|
|
33470
33483
|
|
|
33471
33484
|
```ts
|
|
33472
|
-
BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement
|
|
33485
|
+
BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement | null
|
|
33473
33486
|
```
|
|
33474
33487
|
|
|
33475
33488
|
## Parameters
|
|
@@ -33477,13 +33490,13 @@ BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props
|
|
|
33477
33490
|
| Param | Type | Description |
|
|
33478
33491
|
| --- | --- | --- |
|
|
33479
33492
|
| `props` | `BackButtonProps` | |
|
|
33480
|
-
| `.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. |
|
|
33493
|
+
| `.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. |
|
|
33481
33494
|
|
|
33482
33495
|
## Returns
|
|
33483
33496
|
|
|
33484
33497
|
| Type | Description |
|
|
33485
33498
|
| --- | --- |
|
|
33486
|
-
| `ReactElement` | |
|
|
33499
|
+
| `ReactElement \| null` | |
|
|
33487
33500
|
|
|
33488
33501
|
|
|
33489
33502
|
---
|
|
@@ -33524,6 +33537,7 @@ Top-level navigation provider, with one stack of pages for each tab.
|
|
|
33524
33537
|
- Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
|
|
33525
33538
|
- Turns clicks on same-origin links into `NavigationSequence.forward()`, or `NavigationSequence.back()` for a link with `className="back"`, or `NavigationSequence.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
|
|
33526
33539
|
- Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
|
|
33540
|
+
- Before a move slides, it lowers the on-screen keyboard and waits until it is down (`waitForKeyboard()`), because a keyboard that closes during the slide resizes the page in the middle of it.
|
|
33527
33541
|
- Takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` type, so a `<Transition>` around the routes runs a view transition. A replace has no transition. An event for the page already shown is skipped.
|
|
33528
33542
|
- Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
33529
33543
|
|
|
@@ -38953,6 +38967,70 @@ eventLoopFocus({ currentTarget, relatedTarget }: { currentTarget: Element; relat
|
|
|
38953
38967
|
```
|
|
38954
38968
|
|
|
38955
38969
|
|
|
38970
|
+
---
|
|
38971
|
+
|
|
38972
|
+
# isKeyboardOpen()
|
|
38973
|
+
|
|
38974
|
+
- Kind: function
|
|
38975
|
+
- Import: `import { isKeyboardOpen } from "shelving/ui";`
|
|
38976
|
+
|
|
38977
|
+
Is the on-screen keyboard open (or still closing)?
|
|
38978
|
+
- On iOS (Safari, home-screen web apps and `WKWebView`) the keyboard makes the visual viewport shorter than the window.
|
|
38979
|
+
- Returns `false` when the page is zoomed in, because a zoomed visual viewport is also shorter than the window.
|
|
38980
|
+
- Returns `false` where the keyboard resizes the whole page (Android Chrome by default), and with no on-screen keyboard.
|
|
38981
|
+
|
|
38982
|
+
## Signatures
|
|
38983
|
+
|
|
38984
|
+
```ts
|
|
38985
|
+
isKeyboardOpen(): boolean
|
|
38986
|
+
```
|
|
38987
|
+
|
|
38988
|
+
## Returns
|
|
38989
|
+
|
|
38990
|
+
| Type | Description |
|
|
38991
|
+
| --- | --- |
|
|
38992
|
+
| `boolean` | `true` when the visual viewport is much shorter than the window. |
|
|
38993
|
+
|
|
38994
|
+
## Examples
|
|
38995
|
+
|
|
38996
|
+
```ts
|
|
38997
|
+
if (isKeyboardOpen()) await waitForKeyboard();
|
|
38998
|
+
```
|
|
38999
|
+
|
|
39000
|
+
|
|
39001
|
+
---
|
|
39002
|
+
|
|
39003
|
+
# waitForKeyboard()
|
|
39004
|
+
|
|
39005
|
+
- Kind: function
|
|
39006
|
+
- Import: `import { waitForKeyboard } from "shelving/ui";`
|
|
39007
|
+
|
|
39008
|
+
Lower the on-screen keyboard, and wait until it is down.
|
|
39009
|
+
- Blurs the focused text field, if there is one, so the keyboard starts to close.
|
|
39010
|
+
- When the keyboard is open (`isKeyboardOpen()`) or a field was just blurred, it waits until the keyboard is down and the
|
|
39011
|
+
viewport has stopped changing size, for at most half a second.
|
|
39012
|
+
- Returns nothing when there is nothing to wait for, so a caller can go on at once without a promise.
|
|
39013
|
+
- Use it before a page slide: a keyboard that closes during a view transition resizes the page in the middle of it.
|
|
39014
|
+
|
|
39015
|
+
## Signatures
|
|
39016
|
+
|
|
39017
|
+
```ts
|
|
39018
|
+
waitForKeyboard(): Promise<void> | void
|
|
39019
|
+
```
|
|
39020
|
+
|
|
39021
|
+
## Returns
|
|
39022
|
+
|
|
39023
|
+
| Type | Description |
|
|
39024
|
+
| --- | --- |
|
|
39025
|
+
| `Promise<void> \| void` | A promise that resolves when the keyboard is down, or nothing when it is down already. |
|
|
39026
|
+
|
|
39027
|
+
## Examples
|
|
39028
|
+
|
|
39029
|
+
```ts
|
|
39030
|
+
const waiting = waitForKeyboard(); if (waiting) await waiting;
|
|
39031
|
+
```
|
|
39032
|
+
|
|
39033
|
+
|
|
38956
39034
|
---
|
|
38957
39035
|
|
|
38958
39036
|
# MetaTags
|
|
@@ -12,6 +12,7 @@ Options for `useSequenceTransition()`.
|
|
|
12
12
|
readonly current: () => T;
|
|
13
13
|
readonly transition?: string | ((value: T) => string | null | undefined) | undefined;
|
|
14
14
|
readonly equal?: ((a: T, b: T) => boolean) | undefined;
|
|
15
|
+
readonly wait?: ((value: T) => PromiseLike<void> | void) | undefined;
|
|
15
16
|
}
|
|
16
17
|
```
|
|
17
18
|
|
|
@@ -22,3 +23,4 @@ Options for `useSequenceTransition()`.
|
|
|
22
23
|
| `current` | `() => T` | Read the current value. - Called for the first render, and again when the subscription starts, to catch up on values sent before it started. Read only. |
|
|
23
24
|
| `transition` | `string \| ((value: T) => string \| null \| undefined) \| undefined` | Transition type for a value, or a fixed type for every value. - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it. - A value with no type (`undefined` or `null`) is set at once, with no transition. Read only. Optional. |
|
|
24
25
|
| `equal` | `((a: T, b: T) => boolean) \| undefined` | Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition. Read only. Defaults to `Object.is`. |
|
|
26
|
+
| `wait` | `((value: T) => PromiseLike<void> \| void) \| undefined` | Wait before a value with a transition type is set, for example until the on-screen keyboard is down. - Return a promise to wait for it, or nothing to set the value at once. - A newer value that arrives while it waits wins: the older value is never set. - Values with no transition type never wait. Read only. Optional. |
|
|
@@ -56,6 +56,7 @@ useSequenceTransition(sequence: AsyncIterable<T>, options: SequenceTransitionOpt
|
|
|
56
56
|
| `.current` | `() => T` | Read the current value. - Called for the first render, and again when the subscription starts, to catch up on values sent before it started. Read only. |
|
|
57
57
|
| `.transition` | `string \| ((value: T) => string \| null \| undefined) \| undefined` | Transition type for a value, or a fixed type for every value. - A value with a type is set inside `startTransition()` with that type, so a `<ViewTransition>` can animate it. - A value with no type (`undefined` or `null`) is set at once, with no transition. Read only. Optional. |
|
|
58
58
|
| `.equal` | `((a: T, b: T) => boolean) \| undefined` | Is a new value the same as the shown value? A value that is the same is skipped, so it starts no second transition. Read only. Defaults to `Object.is`. |
|
|
59
|
+
| `.wait` | `((value: T) => PromiseLike<void> \| void) \| undefined` | Wait before a value with a transition type is set, for example until the on-screen keyboard is down. - Return a promise to wait for it, or nothing to set the value at once. - A newer value that arrives while it waits wins: the older value is never set. - Values with no transition type never wait. Read only. Optional. |
|
|
59
60
|
|
|
60
61
|
## Returns
|
|
61
62
|
|
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/Navigation.md
CHANGED
|
@@ -7,6 +7,7 @@ Top-level navigation provider, with one stack of pages for each tab.
|
|
|
7
7
|
- Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
|
|
8
8
|
- Turns clicks on same-origin links into `NavigationSequence.forward()`, or `NavigationSequence.back()` for a link with `className="back"`, or `NavigationSequence.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
|
|
9
9
|
- Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
|
|
10
|
+
- Before a move slides, it lowers the on-screen keyboard and waits until it is down (`waitForKeyboard()`), because a keyboard that closes during the slide resizes the page in the middle of it.
|
|
10
11
|
- Takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` type, so a `<Transition>` around the routes runs a view transition. A replace has no transition. An event for the page already shown is skipped.
|
|
11
12
|
- Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
12
13
|
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# isKeyboardOpen()
|
|
2
|
+
|
|
3
|
+
- Kind: function
|
|
4
|
+
- Import: `import { isKeyboardOpen } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Is the on-screen keyboard open (or still closing)?
|
|
7
|
+
- On iOS (Safari, home-screen web apps and `WKWebView`) the keyboard makes the visual viewport shorter than the window.
|
|
8
|
+
- Returns `false` when the page is zoomed in, because a zoomed visual viewport is also shorter than the window.
|
|
9
|
+
- Returns `false` where the keyboard resizes the whole page (Android Chrome by default), and with no on-screen keyboard.
|
|
10
|
+
|
|
11
|
+
## Signatures
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
isKeyboardOpen(): boolean
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Returns
|
|
18
|
+
|
|
19
|
+
| Type | Description |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| `boolean` | `true` when the visual viewport is much shorter than the window. |
|
|
22
|
+
|
|
23
|
+
## Examples
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
if (isKeyboardOpen()) await waitForKeyboard();
|
|
27
|
+
```
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# waitForKeyboard()
|
|
2
|
+
|
|
3
|
+
- Kind: function
|
|
4
|
+
- Import: `import { waitForKeyboard } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Lower the on-screen keyboard, and wait until it is down.
|
|
7
|
+
- Blurs the focused text field, if there is one, so the keyboard starts to close.
|
|
8
|
+
- When the keyboard is open (`isKeyboardOpen()`) or a field was just blurred, it waits until the keyboard is down and the
|
|
9
|
+
viewport has stopped changing size, for at most half a second.
|
|
10
|
+
- Returns nothing when there is nothing to wait for, so a caller can go on at once without a promise.
|
|
11
|
+
- Use it before a page slide: a keyboard that closes during a view transition resizes the page in the middle of it.
|
|
12
|
+
|
|
13
|
+
## Signatures
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
waitForKeyboard(): Promise<void> | void
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Returns
|
|
20
|
+
|
|
21
|
+
| Type | Description |
|
|
22
|
+
| --- | --- |
|
|
23
|
+
| `Promise<void> \| void` | A promise that resolves when the keyboard is down, or nothing when it is down already. |
|
|
24
|
+
|
|
25
|
+
## Examples
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
const waiting = waitForKeyboard(); if (waiting) await waiting;
|
|
29
|
+
```
|
package/docs/ui.md
CHANGED
|
@@ -295,6 +295,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
295
295
|
- [focusFirstFocusable()](ui/focusFirstFocusable.md): Focus on the first focusable element inside an element.
|
|
296
296
|
- [loopFocus()](ui/loopFocus.md): Loop focus inside an element so it can't escape — refocus the first focusable child when focus moves out.
|
|
297
297
|
- [eventLoopFocus()](ui/eventLoopFocus.md): Loop focus inside an element in response to a blur event — a ready-made onBlur handler that traps focus.
|
|
298
|
+
- [isKeyboardOpen()](ui/isKeyboardOpen.md): Is the on-screen keyboard open (or still closing)?
|
|
299
|
+
- [waitForKeyboard()](ui/waitForKeyboard.md): Lower the on-screen keyboard, and wait until it is down.
|
|
298
300
|
- [joinMetaCSP()](ui/joinMetaCSP.md): Turn a deconstructed MetaCSP into a Content-Security-Policy string.
|
|
299
301
|
- [joinTitles()](ui/joinTitles.md): Join several page or site titles together with - , skipping empty values.
|
|
300
302
|
- [mergeMeta()](ui/mergeMeta.md): Merge a PossibleMeta onto an existing Meta, resolving URLs and assets in the process.
|
|
@@ -459,7 +461,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
459
461
|
- [NoticesProps](ui/NoticesProps.md): Props for <Notices> — the place for the list, and flex styling variants for the notices container.
|
|
460
462
|
- [HTMLProps](ui/HTMLProps.md): Props for <HTML> — initial Meta (language/root/app) plus the page children.
|
|
461
463
|
- [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
|
|
462
|
-
- [BackButtonProps](ui/BackButtonProps.md): Props for <BackButton>:
|
|
464
|
+
- [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.
|
|
463
465
|
- [NavigationProps](ui/NavigationProps.md): Props for <Navigation>: the initial Meta (url, root and stack), the stacks, and optional children.
|
|
464
466
|
- [NavigationEntryState](ui/NavigationEntryState.md): State that NavigationSequence saves on each browser history entry.
|
|
465
467
|
- [NavigationEvent](ui/NavigationEvent.md): One change of page, published by NavigationSequence.
|
package/package.json
CHANGED
|
@@ -21,6 +21,13 @@ export interface SequenceTransitionOptions<T> {
|
|
|
21
21
|
* @default Object.is
|
|
22
22
|
*/
|
|
23
23
|
readonly equal?: ((a: T, b: T) => boolean) | undefined;
|
|
24
|
+
/**
|
|
25
|
+
* Wait before a value with a transition type is set, for example until the on-screen keyboard is down.
|
|
26
|
+
* - Return a promise to wait for it, or nothing to set the value at once.
|
|
27
|
+
* - A newer value that arrives while it waits wins: the older value is never set.
|
|
28
|
+
* - Values with no transition type never wait.
|
|
29
|
+
*/
|
|
30
|
+
readonly wait?: ((value: T) => PromiseLike<void> | void) | undefined;
|
|
24
31
|
}
|
|
25
32
|
/**
|
|
26
33
|
* Subscribe to an async iterable, and set each value it yields inside a React transition.
|
|
@@ -22,18 +22,30 @@ export function useSequenceTransition(sequence, options) {
|
|
|
22
22
|
optionsRef.current = options;
|
|
23
23
|
const valueRef = useRef(value);
|
|
24
24
|
useEffect(() => {
|
|
25
|
+
// Counts the values, so a value that waited is set only when no newer value came in while it waited.
|
|
26
|
+
let count = 0;
|
|
25
27
|
const set = (next) => {
|
|
26
|
-
const { transition, equal = Object.is } = optionsRef.current;
|
|
28
|
+
const { transition, equal = Object.is, wait } = optionsRef.current;
|
|
27
29
|
if (equal(valueRef.current, next))
|
|
28
30
|
return;
|
|
29
31
|
valueRef.current = next;
|
|
32
|
+
const n = ++count;
|
|
30
33
|
const type = typeof transition === "function" ? transition(next) : transition;
|
|
31
34
|
if (!type)
|
|
32
35
|
return setValue(next);
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
36
|
+
const show = () => {
|
|
37
|
+
if (n !== count)
|
|
38
|
+
return;
|
|
39
|
+
startTransition(() => {
|
|
40
|
+
addTransitionType(type);
|
|
41
|
+
setValue(next);
|
|
42
|
+
});
|
|
43
|
+
};
|
|
44
|
+
const waiting = wait?.(next);
|
|
45
|
+
if (waiting)
|
|
46
|
+
waiting.then(show, show);
|
|
47
|
+
else
|
|
48
|
+
show();
|
|
37
49
|
};
|
|
38
50
|
set(optionsRef.current.current());
|
|
39
51
|
return runSequence(sequence, set, setError);
|
|
@@ -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
|
);
|
|
@@ -27,6 +27,7 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
|
|
|
27
27
|
* - Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
|
|
28
28
|
* - Turns clicks on same-origin links into `NavigationSequence.forward()`, or `NavigationSequence.back()` for a link with `className="back"`, or `NavigationSequence.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
|
|
29
29
|
* - Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
|
|
30
|
+
* - Before a move slides, it lowers the on-screen keyboard and waits until it is down (`waitForKeyboard()`), because a keyboard that closes during the slide resizes the page in the middle of it.
|
|
30
31
|
* - Takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` type, so a `<Transition>` around the routes runs a view transition. A replace has no transition. An event for the page already shown is skipped.
|
|
31
32
|
* - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
32
33
|
*
|
package/ui/router/Navigation.js
CHANGED
|
@@ -4,6 +4,7 @@ import { useInstance } from "../../react/useInstance.js";
|
|
|
4
4
|
import { useSequenceTransition } from "../../react/useSequenceTransition.js";
|
|
5
5
|
import { MetaContext, requireMeta } from "../misc/MetaContext.js";
|
|
6
6
|
import { mergeMeta } from "../util/index.js";
|
|
7
|
+
import { waitForKeyboard } from "../util/keyboard.js";
|
|
7
8
|
import { NavigationContext } from "./NavigationContext.js";
|
|
8
9
|
import { NavigationSequence } from "./NavigationSequence.js";
|
|
9
10
|
/**
|
|
@@ -11,6 +12,7 @@ import { NavigationSequence } from "./NavigationSequence.js";
|
|
|
11
12
|
* - Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
|
|
12
13
|
* - Turns clicks on same-origin links into `NavigationSequence.forward()`, or `NavigationSequence.back()` for a link with `className="back"`, or `NavigationSequence.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
|
|
13
14
|
* - Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
|
|
15
|
+
* - Before a move slides, it lowers the on-screen keyboard and waits until it is down (`waitForKeyboard()`), because a keyboard that closes during the slide resizes the page in the middle of it.
|
|
14
16
|
* - Takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` type, so a `<Transition>` around the routes runs a view transition. A replace has no transition. An event for the page already shown is skipped.
|
|
15
17
|
* - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
16
18
|
*
|
|
@@ -23,7 +25,12 @@ export function Navigation({ children, stacks = [], ...meta }) {
|
|
|
23
25
|
const current = requireMeta(meta);
|
|
24
26
|
const nav = useInstance(NavigationSequence, current.url, current.root, current.stack ?? null, ...stacks);
|
|
25
27
|
// Keep the page shown in state, set inside a transition for each move.
|
|
26
|
-
const page = useSequenceTransition(nav, {
|
|
28
|
+
const page = useSequenceTransition(nav, {
|
|
29
|
+
current: () => nav.current(),
|
|
30
|
+
transition: _getDirection,
|
|
31
|
+
equal: _isSamePage,
|
|
32
|
+
wait: _waitForMove,
|
|
33
|
+
});
|
|
27
34
|
// Tell a waiting `NavigationSequence.publish()` that its page is committed.
|
|
28
35
|
useLayoutEffect(() => {
|
|
29
36
|
if (page)
|
|
@@ -62,6 +69,11 @@ export function Navigation({ children, stacks = [], ...meta }) {
|
|
|
62
69
|
function _getDirection({ direction }) {
|
|
63
70
|
return direction;
|
|
64
71
|
}
|
|
72
|
+
/** Before a move slides, lower the on-screen keyboard and wait until it is down, so the page does not resize during the slide. */
|
|
73
|
+
function _waitForMove({ direction }) {
|
|
74
|
+
if (direction)
|
|
75
|
+
return waitForKeyboard();
|
|
76
|
+
}
|
|
65
77
|
function _isSamePage(a, b) {
|
|
66
78
|
return a.url.href === b.url.href && a.stack === b.stack && a.ordinal === b.ordinal;
|
|
67
79
|
}
|
|
@@ -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">
|
package/ui/router/Navigation.tsx
CHANGED
|
@@ -4,6 +4,7 @@ import { useSequenceTransition } from "../../react/useSequenceTransition.js";
|
|
|
4
4
|
import type { AbsolutePath } from "../../util/path.js";
|
|
5
5
|
import { MetaContext, requireMeta } from "../misc/MetaContext.js";
|
|
6
6
|
import { mergeMeta, type PossibleMeta } from "../util/index.js";
|
|
7
|
+
import { waitForKeyboard } from "../util/keyboard.js";
|
|
7
8
|
import type { OptionalChildProps } from "../util/props.js";
|
|
8
9
|
import { NavigationContext } from "./NavigationContext.js";
|
|
9
10
|
import { type NavigationEvent, NavigationSequence } from "./NavigationSequence.js";
|
|
@@ -34,6 +35,7 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
|
|
|
34
35
|
* - Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
|
|
35
36
|
* - Turns clicks on same-origin links into `NavigationSequence.forward()`, or `NavigationSequence.back()` for a link with `className="back"`, or `NavigationSequence.replace()` for a link with `className="replace"`. Clicks with a modifier key, or on links with `download` or a `target`, are left to the browser.
|
|
36
37
|
* - Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
|
|
38
|
+
* - Before a move slides, it lowers the on-screen keyboard and waits until it is down (`waitForKeyboard()`), because a keyboard that closes during the slide resizes the page in the middle of it.
|
|
37
39
|
* - Takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` type, so a `<Transition>` around the routes runs a view transition. A replace has no transition. An event for the page already shown is skipped.
|
|
38
40
|
* - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
39
41
|
*
|
|
@@ -47,7 +49,12 @@ export function Navigation({ children, stacks = [], ...meta }: NavigationProps):
|
|
|
47
49
|
const nav = useInstance(NavigationSequence, current.url, current.root, current.stack ?? null, ...stacks);
|
|
48
50
|
|
|
49
51
|
// Keep the page shown in state, set inside a transition for each move.
|
|
50
|
-
const page = useSequenceTransition(nav, {
|
|
52
|
+
const page = useSequenceTransition(nav, {
|
|
53
|
+
current: () => nav.current(),
|
|
54
|
+
transition: _getDirection,
|
|
55
|
+
equal: _isSamePage,
|
|
56
|
+
wait: _waitForMove,
|
|
57
|
+
});
|
|
51
58
|
|
|
52
59
|
// Tell a waiting `NavigationSequence.publish()` that its page is committed.
|
|
53
60
|
useLayoutEffect(() => {
|
|
@@ -92,6 +99,11 @@ function _getDirection({ direction }: NavigationEvent): string | undefined {
|
|
|
92
99
|
return direction;
|
|
93
100
|
}
|
|
94
101
|
|
|
102
|
+
/** Before a move slides, lower the on-screen keyboard and wait until it is down, so the page does not resize during the slide. */
|
|
103
|
+
function _waitForMove({ direction }: NavigationEvent): Promise<void> | void {
|
|
104
|
+
if (direction) return waitForKeyboard();
|
|
105
|
+
}
|
|
106
|
+
|
|
95
107
|
function _isSamePage(a: NavigationEvent, b: NavigationEvent): boolean {
|
|
96
108
|
return a.url.href === b.url.href && a.stack === b.stack && a.ordinal === b.ordinal;
|
|
97
109
|
}
|
package/ui/util/index.d.ts
CHANGED
package/ui/util/index.js
CHANGED
package/ui/util/index.ts
CHANGED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Is the on-screen keyboard open (or still closing)?
|
|
3
|
+
* - On iOS (Safari, home-screen web apps and `WKWebView`) the keyboard makes the visual viewport shorter than the window.
|
|
4
|
+
* - Returns `false` when the page is zoomed in, because a zoomed visual viewport is also shorter than the window.
|
|
5
|
+
* - Returns `false` where the keyboard resizes the whole page (Android Chrome by default), and with no on-screen keyboard.
|
|
6
|
+
*
|
|
7
|
+
* @returns `true` when the visual viewport is much shorter than the window.
|
|
8
|
+
* @example if (isKeyboardOpen()) await waitForKeyboard();
|
|
9
|
+
* @see https://shelving.cc/ui/isKeyboardOpen
|
|
10
|
+
*/
|
|
11
|
+
export declare function isKeyboardOpen(): boolean;
|
|
12
|
+
/**
|
|
13
|
+
* Lower the on-screen keyboard, and wait until it is down.
|
|
14
|
+
* - Blurs the focused text field, if there is one, so the keyboard starts to close.
|
|
15
|
+
* - When the keyboard is open (`isKeyboardOpen()`) or a field was just blurred, it waits until the keyboard is down and the
|
|
16
|
+
* viewport has stopped changing size, for at most half a second.
|
|
17
|
+
* - Returns nothing when there is nothing to wait for, so a caller can go on at once without a promise.
|
|
18
|
+
* - Use it before a page slide: a keyboard that closes during a view transition resizes the page in the middle of it.
|
|
19
|
+
*
|
|
20
|
+
* @returns A promise that resolves when the keyboard is down, or nothing when it is down already.
|
|
21
|
+
* @example const waiting = waitForKeyboard(); if (waiting) await waiting;
|
|
22
|
+
* @see https://shelving.cc/ui/waitForKeyboard
|
|
23
|
+
*/
|
|
24
|
+
export declare function waitForKeyboard(): Promise<void> | void;
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/** How much shorter the visual viewport must be than the window before the on-screen keyboard counts as open, in pixels. */
|
|
2
|
+
const _GAP = 100;
|
|
3
|
+
/** How long the viewport must stay the same size before the keyboard counts as still, in milliseconds. */
|
|
4
|
+
const _QUIET = 100;
|
|
5
|
+
/** The longest `waitForKeyboard()` waits, in milliseconds. */
|
|
6
|
+
const _MAX = 500;
|
|
7
|
+
/**
|
|
8
|
+
* Is the on-screen keyboard open (or still closing)?
|
|
9
|
+
* - On iOS (Safari, home-screen web apps and `WKWebView`) the keyboard makes the visual viewport shorter than the window.
|
|
10
|
+
* - Returns `false` when the page is zoomed in, because a zoomed visual viewport is also shorter than the window.
|
|
11
|
+
* - Returns `false` where the keyboard resizes the whole page (Android Chrome by default), and with no on-screen keyboard.
|
|
12
|
+
*
|
|
13
|
+
* @returns `true` when the visual viewport is much shorter than the window.
|
|
14
|
+
* @example if (isKeyboardOpen()) await waitForKeyboard();
|
|
15
|
+
* @see https://shelving.cc/ui/isKeyboardOpen
|
|
16
|
+
*/
|
|
17
|
+
export function isKeyboardOpen() {
|
|
18
|
+
if (typeof window === "undefined")
|
|
19
|
+
return false;
|
|
20
|
+
const viewport = window.visualViewport;
|
|
21
|
+
if (!viewport || Math.abs(viewport.scale - 1) > 0.01)
|
|
22
|
+
return false;
|
|
23
|
+
return window.innerHeight - viewport.height > _GAP;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Lower the on-screen keyboard, and wait until it is down.
|
|
27
|
+
* - Blurs the focused text field, if there is one, so the keyboard starts to close.
|
|
28
|
+
* - When the keyboard is open (`isKeyboardOpen()`) or a field was just blurred, it waits until the keyboard is down and the
|
|
29
|
+
* viewport has stopped changing size, for at most half a second.
|
|
30
|
+
* - Returns nothing when there is nothing to wait for, so a caller can go on at once without a promise.
|
|
31
|
+
* - Use it before a page slide: a keyboard that closes during a view transition resizes the page in the middle of it.
|
|
32
|
+
*
|
|
33
|
+
* @returns A promise that resolves when the keyboard is down, or nothing when it is down already.
|
|
34
|
+
* @example const waiting = waitForKeyboard(); if (waiting) await waiting;
|
|
35
|
+
* @see https://shelving.cc/ui/waitForKeyboard
|
|
36
|
+
*/
|
|
37
|
+
export function waitForKeyboard() {
|
|
38
|
+
if (typeof window === "undefined")
|
|
39
|
+
return;
|
|
40
|
+
const blurred = _blurTextField();
|
|
41
|
+
if (!blurred && !isKeyboardOpen())
|
|
42
|
+
return;
|
|
43
|
+
return new Promise(resolve => {
|
|
44
|
+
const viewport = window.visualViewport;
|
|
45
|
+
const start = performance.now();
|
|
46
|
+
let changed = start;
|
|
47
|
+
const onResize = () => {
|
|
48
|
+
changed = performance.now();
|
|
49
|
+
};
|
|
50
|
+
const done = () => {
|
|
51
|
+
viewport?.removeEventListener("resize", onResize);
|
|
52
|
+
window.removeEventListener("resize", onResize);
|
|
53
|
+
resolve();
|
|
54
|
+
};
|
|
55
|
+
const check = (now) => {
|
|
56
|
+
if (now - start >= _MAX || (!isKeyboardOpen() && now - changed >= _QUIET))
|
|
57
|
+
return done();
|
|
58
|
+
requestAnimationFrame(check);
|
|
59
|
+
};
|
|
60
|
+
viewport?.addEventListener("resize", onResize);
|
|
61
|
+
window.addEventListener("resize", onResize);
|
|
62
|
+
requestAnimationFrame(check);
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
/** Blur the focused element when it takes typed text (and so shows the on-screen keyboard), and say if it did. */
|
|
66
|
+
function _blurTextField() {
|
|
67
|
+
const el = document.activeElement;
|
|
68
|
+
if (!(el instanceof HTMLElement) || !_isTextField(el))
|
|
69
|
+
return false;
|
|
70
|
+
el.blur();
|
|
71
|
+
return true;
|
|
72
|
+
}
|
|
73
|
+
/** Does an element take typed text? */
|
|
74
|
+
function _isTextField(el) {
|
|
75
|
+
if (el.isContentEditable || el instanceof HTMLTextAreaElement)
|
|
76
|
+
return true;
|
|
77
|
+
if (el instanceof HTMLSelectElement)
|
|
78
|
+
return false;
|
|
79
|
+
return el instanceof HTMLInputElement && !_NO_KEYBOARD.has(el.type);
|
|
80
|
+
}
|
|
81
|
+
/** Input types that show no on-screen keyboard. */
|
|
82
|
+
const _NO_KEYBOARD = new Set(["button", "checkbox", "color", "file", "hidden", "image", "radio", "range", "reset", "submit"]);
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { describe, expect, test } from "bun:test";
|
|
2
|
+
import { isKeyboardOpen, waitForKeyboard } from "shelving/ui";
|
|
3
|
+
|
|
4
|
+
describe("keyboard", () => {
|
|
5
|
+
test("isKeyboardOpen() is false with no window", () => {
|
|
6
|
+
expect(isKeyboardOpen()).toBe(false);
|
|
7
|
+
});
|
|
8
|
+
|
|
9
|
+
test("waitForKeyboard() returns nothing with no window, so a caller goes on at once", () => {
|
|
10
|
+
expect(waitForKeyboard()).toBeUndefined();
|
|
11
|
+
});
|
|
12
|
+
});
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/** How much shorter the visual viewport must be than the window before the on-screen keyboard counts as open, in pixels. */
|
|
2
|
+
const _GAP = 100;
|
|
3
|
+
|
|
4
|
+
/** How long the viewport must stay the same size before the keyboard counts as still, in milliseconds. */
|
|
5
|
+
const _QUIET = 100;
|
|
6
|
+
|
|
7
|
+
/** The longest `waitForKeyboard()` waits, in milliseconds. */
|
|
8
|
+
const _MAX = 500;
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Is the on-screen keyboard open (or still closing)?
|
|
12
|
+
* - On iOS (Safari, home-screen web apps and `WKWebView`) the keyboard makes the visual viewport shorter than the window.
|
|
13
|
+
* - Returns `false` when the page is zoomed in, because a zoomed visual viewport is also shorter than the window.
|
|
14
|
+
* - Returns `false` where the keyboard resizes the whole page (Android Chrome by default), and with no on-screen keyboard.
|
|
15
|
+
*
|
|
16
|
+
* @returns `true` when the visual viewport is much shorter than the window.
|
|
17
|
+
* @example if (isKeyboardOpen()) await waitForKeyboard();
|
|
18
|
+
* @see https://shelving.cc/ui/isKeyboardOpen
|
|
19
|
+
*/
|
|
20
|
+
export function isKeyboardOpen(): boolean {
|
|
21
|
+
if (typeof window === "undefined") return false;
|
|
22
|
+
const viewport = window.visualViewport;
|
|
23
|
+
if (!viewport || Math.abs(viewport.scale - 1) > 0.01) return false;
|
|
24
|
+
return window.innerHeight - viewport.height > _GAP;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Lower the on-screen keyboard, and wait until it is down.
|
|
29
|
+
* - Blurs the focused text field, if there is one, so the keyboard starts to close.
|
|
30
|
+
* - When the keyboard is open (`isKeyboardOpen()`) or a field was just blurred, it waits until the keyboard is down and the
|
|
31
|
+
* viewport has stopped changing size, for at most half a second.
|
|
32
|
+
* - Returns nothing when there is nothing to wait for, so a caller can go on at once without a promise.
|
|
33
|
+
* - Use it before a page slide: a keyboard that closes during a view transition resizes the page in the middle of it.
|
|
34
|
+
*
|
|
35
|
+
* @returns A promise that resolves when the keyboard is down, or nothing when it is down already.
|
|
36
|
+
* @example const waiting = waitForKeyboard(); if (waiting) await waiting;
|
|
37
|
+
* @see https://shelving.cc/ui/waitForKeyboard
|
|
38
|
+
*/
|
|
39
|
+
export function waitForKeyboard(): Promise<void> | void {
|
|
40
|
+
if (typeof window === "undefined") return;
|
|
41
|
+
const blurred = _blurTextField();
|
|
42
|
+
if (!blurred && !isKeyboardOpen()) return;
|
|
43
|
+
return new Promise<void>(resolve => {
|
|
44
|
+
const viewport = window.visualViewport;
|
|
45
|
+
const start = performance.now();
|
|
46
|
+
let changed = start;
|
|
47
|
+
const onResize = () => {
|
|
48
|
+
changed = performance.now();
|
|
49
|
+
};
|
|
50
|
+
const done = () => {
|
|
51
|
+
viewport?.removeEventListener("resize", onResize);
|
|
52
|
+
window.removeEventListener("resize", onResize);
|
|
53
|
+
resolve();
|
|
54
|
+
};
|
|
55
|
+
const check = (now: number) => {
|
|
56
|
+
if (now - start >= _MAX || (!isKeyboardOpen() && now - changed >= _QUIET)) return done();
|
|
57
|
+
requestAnimationFrame(check);
|
|
58
|
+
};
|
|
59
|
+
viewport?.addEventListener("resize", onResize);
|
|
60
|
+
window.addEventListener("resize", onResize);
|
|
61
|
+
requestAnimationFrame(check);
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Blur the focused element when it takes typed text (and so shows the on-screen keyboard), and say if it did. */
|
|
66
|
+
function _blurTextField(): boolean {
|
|
67
|
+
const el = document.activeElement;
|
|
68
|
+
if (!(el instanceof HTMLElement) || !_isTextField(el)) return false;
|
|
69
|
+
el.blur();
|
|
70
|
+
return true;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** Does an element take typed text? */
|
|
74
|
+
function _isTextField(el: HTMLElement): boolean {
|
|
75
|
+
if (el.isContentEditable || el instanceof HTMLTextAreaElement) return true;
|
|
76
|
+
if (el instanceof HTMLSelectElement) return false;
|
|
77
|
+
return el instanceof HTMLInputElement && !_NO_KEYBOARD.has(el.type);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Input types that show no on-screen keyboard. */
|
|
81
|
+
const _NO_KEYBOARD = new Set(["button", "checkbox", "color", "file", "hidden", "image", "radio", "range", "reset", "submit"]);
|