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.
@@ -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
 
@@ -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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.324.0",
3
+ "version": "1.325.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -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
- startTransition(() => {
34
- addTransitionType(type);
35
- setValue(next);
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
  *
@@ -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, { current: () => nav.current(), transition: _getDirection, equal: _isSamePage });
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
  }
@@ -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, { current: () => nav.current(), transition: _getDirection, equal: _isSamePage });
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
  }
@@ -2,6 +2,7 @@ export * from "./context.js";
2
2
  export * from "./css.js";
3
3
  export * from "./event.js";
4
4
  export * from "./focus.js";
5
+ export * from "./keyboard.js";
5
6
  export * from "./meta.js";
6
7
  export * from "./notice.js";
7
8
  export * from "./props.js";
package/ui/util/index.js CHANGED
@@ -2,6 +2,7 @@ export * from "./context.js";
2
2
  export * from "./css.js";
3
3
  export * from "./event.js";
4
4
  export * from "./focus.js";
5
+ export * from "./keyboard.js";
5
6
  export * from "./meta.js";
6
7
  export * from "./notice.js";
7
8
  export * from "./props.js";
package/ui/util/index.ts CHANGED
@@ -2,6 +2,7 @@ export * from "./context.js";
2
2
  export * from "./css.js";
3
3
  export * from "./event.js";
4
4
  export * from "./focus.js";
5
+ export * from "./keyboard.js";
5
6
  export * from "./meta.js";
6
7
  export * from "./notice.js";
7
8
  export * from "./props.js";
@@ -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"]);