shelving 1.324.0 → 1.325.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 +70 -0
- package/docs/react/SequenceTransitionOptions.md +2 -0
- package/docs/react/useSequenceTransition.md +1 -0
- 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 +2 -0
- package/package.json +1 -1
- package/react/useSequenceTransition.d.ts +7 -0
- package/react/useSequenceTransition.js +17 -5
- package/ui/router/Navigation.d.ts +1 -0
- package/ui/router/Navigation.js +13 -1
- 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.
|
|
@@ -33524,6 +33529,7 @@ Top-level navigation provider, with one stack of pages for each tab.
|
|
|
33524
33529
|
- Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
|
|
33525
33530
|
- 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
33531
|
- Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
|
|
33532
|
+
- 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
33533
|
- 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
33534
|
- Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
|
|
33529
33535
|
|
|
@@ -38953,6 +38959,70 @@ eventLoopFocus({ currentTarget, relatedTarget }: { currentTarget: Element; relat
|
|
|
38953
38959
|
```
|
|
38954
38960
|
|
|
38955
38961
|
|
|
38962
|
+
---
|
|
38963
|
+
|
|
38964
|
+
# isKeyboardOpen()
|
|
38965
|
+
|
|
38966
|
+
- Kind: function
|
|
38967
|
+
- Import: `import { isKeyboardOpen } from "shelving/ui";`
|
|
38968
|
+
|
|
38969
|
+
Is the on-screen keyboard open (or still closing)?
|
|
38970
|
+
- On iOS (Safari, home-screen web apps and `WKWebView`) the keyboard makes the visual viewport shorter than the window.
|
|
38971
|
+
- Returns `false` when the page is zoomed in, because a zoomed visual viewport is also shorter than the window.
|
|
38972
|
+
- Returns `false` where the keyboard resizes the whole page (Android Chrome by default), and with no on-screen keyboard.
|
|
38973
|
+
|
|
38974
|
+
## Signatures
|
|
38975
|
+
|
|
38976
|
+
```ts
|
|
38977
|
+
isKeyboardOpen(): boolean
|
|
38978
|
+
```
|
|
38979
|
+
|
|
38980
|
+
## Returns
|
|
38981
|
+
|
|
38982
|
+
| Type | Description |
|
|
38983
|
+
| --- | --- |
|
|
38984
|
+
| `boolean` | `true` when the visual viewport is much shorter than the window. |
|
|
38985
|
+
|
|
38986
|
+
## Examples
|
|
38987
|
+
|
|
38988
|
+
```ts
|
|
38989
|
+
if (isKeyboardOpen()) await waitForKeyboard();
|
|
38990
|
+
```
|
|
38991
|
+
|
|
38992
|
+
|
|
38993
|
+
---
|
|
38994
|
+
|
|
38995
|
+
# waitForKeyboard()
|
|
38996
|
+
|
|
38997
|
+
- Kind: function
|
|
38998
|
+
- Import: `import { waitForKeyboard } from "shelving/ui";`
|
|
38999
|
+
|
|
39000
|
+
Lower the on-screen keyboard, and wait until it is down.
|
|
39001
|
+
- Blurs the focused text field, if there is one, so the keyboard starts to close.
|
|
39002
|
+
- When the keyboard is open (`isKeyboardOpen()`) or a field was just blurred, it waits until the keyboard is down and the
|
|
39003
|
+
viewport has stopped changing size, for at most half a second.
|
|
39004
|
+
- Returns nothing when there is nothing to wait for, so a caller can go on at once without a promise.
|
|
39005
|
+
- Use it before a page slide: a keyboard that closes during a view transition resizes the page in the middle of it.
|
|
39006
|
+
|
|
39007
|
+
## Signatures
|
|
39008
|
+
|
|
39009
|
+
```ts
|
|
39010
|
+
waitForKeyboard(): Promise<void> | void
|
|
39011
|
+
```
|
|
39012
|
+
|
|
39013
|
+
## Returns
|
|
39014
|
+
|
|
39015
|
+
| Type | Description |
|
|
39016
|
+
| --- | --- |
|
|
39017
|
+
| `Promise<void> \| void` | A promise that resolves when the keyboard is down, or nothing when it is down already. |
|
|
39018
|
+
|
|
39019
|
+
## Examples
|
|
39020
|
+
|
|
39021
|
+
```ts
|
|
39022
|
+
const waiting = waitForKeyboard(); if (waiting) await waiting;
|
|
39023
|
+
```
|
|
39024
|
+
|
|
39025
|
+
|
|
38956
39026
|
---
|
|
38957
39027
|
|
|
38958
39028
|
# 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/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.
|
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);
|
|
@@ -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
|
}
|
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"]);
|