shelving 1.323.2 → 1.324.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.
Files changed (84) hide show
  1. package/docs/guides/building-with-shelving.md +3 -3
  2. package/docs/llms-full.txt +345 -149
  3. package/docs/react/SequenceTransitionOptions.md +24 -0
  4. package/docs/react/useSequenceTransition.md +70 -0
  5. package/docs/react.md +2 -0
  6. package/docs/ui/BackButton.md +1 -1
  7. package/docs/ui/Head.md +1 -1
  8. package/docs/ui/HorizontalTransition.md +1 -1
  9. package/docs/ui/Image.md +3 -0
  10. package/docs/ui/Meta.md +2 -0
  11. package/docs/ui/Navigation.md +18 -17
  12. package/docs/ui/NavigationContext.md +2 -2
  13. package/docs/ui/NavigationDirection.md +12 -0
  14. package/docs/ui/NavigationEntryState.md +3 -3
  15. package/docs/ui/NavigationEvent.md +28 -0
  16. package/docs/ui/{NavigationStore → NavigationSequence}/back.md +6 -5
  17. package/docs/ui/NavigationSequence/committed.md +13 -0
  18. package/docs/ui/NavigationSequence/current.md +13 -0
  19. package/docs/ui/{NavigationStore → NavigationSequence}/forward.md +4 -4
  20. package/docs/ui/{NavigationStore → NavigationSequence}/history.md +3 -3
  21. package/docs/ui/{NavigationStore → NavigationSequence}/listen.md +3 -3
  22. package/docs/ui/NavigationSequence/publish.md +14 -0
  23. package/docs/ui/{NavigationStore → NavigationSequence}/replace.md +4 -4
  24. package/docs/ui/NavigationSequence.md +187 -0
  25. package/docs/ui/RouteCache.md +16 -15
  26. package/docs/ui/RouteCacheProps.md +1 -1
  27. package/docs/ui/Router.md +2 -2
  28. package/docs/ui/Transition.md +1 -1
  29. package/docs/ui/VerticalTransition.md +1 -1
  30. package/docs/ui/mergeMeta.md +1 -0
  31. package/docs/ui/requireContext.md +1 -1
  32. package/docs/ui/requireNavigation.md +3 -3
  33. package/docs/ui.md +6 -6
  34. package/package.json +1 -1
  35. package/react/index.d.ts +1 -0
  36. package/react/index.js +1 -0
  37. package/react/useSequenceTransition.d.ts +38 -0
  38. package/react/useSequenceTransition.js +44 -0
  39. package/ui/block/Image.d.ts +3 -0
  40. package/ui/block/Image.js +18 -1
  41. package/ui/block/Image.module.css +27 -0
  42. package/ui/block/Image.tsx +24 -1
  43. package/ui/page/Head.d.ts +1 -1
  44. package/ui/page/Head.js +9 -4
  45. package/ui/page/Head.tsx +8 -4
  46. package/ui/router/BackButton.js +6 -3
  47. package/ui/router/BackButton.md +1 -1
  48. package/ui/router/BackButton.tsx +6 -3
  49. package/ui/router/Navigation.d.ts +5 -5
  50. package/ui/router/Navigation.js +24 -49
  51. package/ui/router/Navigation.md +13 -12
  52. package/ui/router/Navigation.tsx +25 -59
  53. package/ui/router/NavigationContext.d.ts +7 -15
  54. package/ui/router/NavigationContext.js +4 -13
  55. package/ui/router/NavigationContext.tsx +7 -17
  56. package/ui/router/{NavigationStore.d.ts → NavigationSequence.d.ts} +93 -51
  57. package/ui/router/{NavigationStore.js → NavigationSequence.js} +132 -80
  58. package/ui/router/NavigationSequence.md +129 -0
  59. package/ui/router/{NavigationStore.test.ts → NavigationSequence.test.ts} +126 -61
  60. package/ui/router/{NavigationStore.tsx → NavigationSequence.tsx} +160 -92
  61. package/ui/router/RouteCache.d.ts +8 -7
  62. package/ui/router/RouteCache.js +34 -29
  63. package/ui/router/RouteCache.md +9 -8
  64. package/ui/router/RouteCache.tsx +39 -36
  65. package/ui/router/Router.d.ts +2 -2
  66. package/ui/router/Router.js +3 -5
  67. package/ui/router/Router.md +1 -1
  68. package/ui/router/Router.tsx +4 -5
  69. package/ui/router/StackButton.d.ts +1 -1
  70. package/ui/router/StackButton.js +5 -7
  71. package/ui/router/StackButton.tsx +6 -7
  72. package/ui/router/index.d.ts +1 -1
  73. package/ui/router/index.js +1 -1
  74. package/ui/router/index.ts +1 -1
  75. package/ui/transition/HorizontalTransition.md +1 -1
  76. package/ui/transition/Transition.md +1 -1
  77. package/ui/transition/VerticalTransition.md +1 -1
  78. package/ui/util/meta.d.ts +2 -0
  79. package/ui/util/meta.ts +2 -0
  80. package/ui/util/requireContext.md +1 -1
  81. package/docs/ui/NavigationPosition.md +0 -24
  82. package/docs/ui/NavigationPositionContext.md +0 -8
  83. package/docs/ui/NavigationStore.md +0 -164
  84. package/ui/router/NavigationStore.md +0 -110
@@ -1,4 +1,4 @@
1
- import type { ReactElement } from "react";
1
+ import type { AnimationEvent, ReactElement, SyntheticEvent } from "react";
2
2
  import { getBlockClass } from "../style/Block.js";
3
3
  import type { SpaceVariants } from "../style/Space.js";
4
4
  import type { WidthVariants } from "../style/Width.js";
@@ -20,6 +20,9 @@ export interface ImageProps extends SpaceVariants, WidthVariants, ClassProps {
20
20
 
21
21
  /**
22
22
  * Image block — renders an `<img>` with space and width variants applied.
23
+ * - It loads `lazy`, and fades in once when it loads. An image that is already loaded when it mounts shows at once.
24
+ * - It never holds a transition (such as a page change): React waits only for an eager `<img>` with no `onLoad`.
25
+ * - The load state is the `data-loaded` attribute (none, `fade`, then `done`), set on the element directly, so a load never re-renders.
23
26
  *
24
27
  * @kind component
25
28
  * @example <Image src="/logo.png" alt="Logo" width="narrow" />
@@ -30,6 +33,11 @@ export function Image({ src, alt, className, ...props }: ImageProps): ReactEleme
30
33
  <img
31
34
  src={src}
32
35
  alt={alt}
36
+ loading="lazy"
37
+ ref={_refImage}
38
+ onLoad={_onImageLoad}
39
+ onError={_onImageDone}
40
+ onAnimationEnd={_onImageDone}
33
41
  className={getClass(
34
42
  IMAGE_CLASS, //
35
43
  getBlockClass(props),
@@ -38,3 +46,18 @@ export function Image({ src, alt, className, ...props }: ImageProps): ReactEleme
38
46
  />
39
47
  );
40
48
  }
49
+
50
+ /** Show an image that loaded before it mounted (from the cache, or before hydration) at once, with no fade. */
51
+ function _refImage(img: HTMLImageElement | null): void {
52
+ if (img?.complete && !img.dataset.loaded) img.dataset.loaded = "done";
53
+ }
54
+
55
+ /** Fade the image in when it loads. */
56
+ function _onImageLoad({ currentTarget }: SyntheticEvent<HTMLImageElement>): void {
57
+ if (!currentTarget.dataset.loaded) currentTarget.dataset.loaded = "fade";
58
+ }
59
+
60
+ /** End the fade, or show an image that failed to load. */
61
+ function _onImageDone({ currentTarget }: SyntheticEvent<HTMLImageElement> | AnimationEvent<HTMLImageElement>): void {
62
+ currentTarget.dataset.loaded = "done";
63
+ }
package/ui/page/Head.d.ts CHANGED
@@ -3,7 +3,7 @@ import { type ReactElement } from "react";
3
3
  * Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
4
4
  * - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
5
5
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
6
- * - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationStore.replace()` with it. Outside `<Navigation>` it does not touch history.
6
+ * - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationSequence.replace()` with it. It only does this for the page the browser history is on (the same `stack` and `ordinal`), so a page shown ahead of history, such as a swipe-back preview, leaves history alone. Outside `<Navigation>` it does not touch history.
7
7
  *
8
8
  * @kind component
9
9
  * @see https://shelving.cc/ui/Head
package/ui/page/Head.js CHANGED
@@ -10,7 +10,7 @@ const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
10
10
  * Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
11
11
  * - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
12
12
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
13
- * - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationStore.replace()` with it. Outside `<Navigation>` it does not touch history.
13
+ * - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationSequence.replace()` with it. It only does this for the page the browser history is on (the same `stack` and `ordinal`), so a page shown ahead of history, such as a swipe-back preview, leaves history alone. Outside `<Navigation>` it does not touch history.
14
14
  *
15
15
  * @kind component
16
16
  * @see https://shelving.cc/ui/Head
@@ -18,12 +18,17 @@ const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
18
18
  export function Head() {
19
19
  const meta = requireMeta();
20
20
  const { url, title, app, description, links, tags, stylesheets, modules, scripts } = meta;
21
- // A page can set its canonical URL in meta. Replace the browser URL with it, through the navigation store so the history entry keeps its stack.
21
+ // A page can set its canonical URL in meta. Replace the browser URL with it, through the navigation sequence so the history entry keeps its stack.
22
+ // Only for the page history is on: a page shown ahead of history (a swipe-back preview) must not change it.
22
23
  const nav = use(NavigationContext);
24
+ const { stack = null, ordinal } = meta;
23
25
  useEffect(() => {
24
- if (nav && url && url.href !== nav.value.href)
26
+ if (!nav || !url)
27
+ return;
28
+ const current = nav.current();
29
+ if (current.stack === stack && current.ordinal === ordinal && url.href !== current.url.href)
25
30
  nav.replace(url);
26
- }, [nav, url]);
31
+ }, [nav, url, stack, ordinal]);
27
32
  const fullTitle = joinTitles(title, app);
28
33
  return (_jsxs(_Fragment, { children: [fullTitle && _jsx("title", { children: fullTitle }), description && _jsx("meta", { name: "description", content: description }), tags && getProps(tags).map(_renderTag), links && getProps(links).map(_renderLink), stylesheets?.map(_renderStylesheet), modules?.map(_renderModule), scripts?.map(_renderScript)] }));
29
34
  }
package/ui/page/Head.tsx CHANGED
@@ -12,7 +12,7 @@ const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
12
12
  * Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
13
13
  * - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
14
14
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
15
- * - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationStore.replace()` with it. Outside `<Navigation>` it does not touch history.
15
+ * - When the meta `url` differs from the browser URL (a page that knows its canonical URL), calls `NavigationSequence.replace()` with it. It only does this for the page the browser history is on (the same `stack` and `ordinal`), so a page shown ahead of history, such as a swipe-back preview, leaves history alone. Outside `<Navigation>` it does not touch history.
16
16
  *
17
17
  * @kind component
18
18
  * @see https://shelving.cc/ui/Head
@@ -21,11 +21,15 @@ export function Head(): ReactElement {
21
21
  const meta = requireMeta();
22
22
  const { url, title, app, description, links, tags, stylesheets, modules, scripts } = meta;
23
23
 
24
- // A page can set its canonical URL in meta. Replace the browser URL with it, through the navigation store so the history entry keeps its stack.
24
+ // A page can set its canonical URL in meta. Replace the browser URL with it, through the navigation sequence so the history entry keeps its stack.
25
+ // Only for the page history is on: a page shown ahead of history (a swipe-back preview) must not change it.
25
26
  const nav = use(NavigationContext);
27
+ const { stack = null, ordinal } = meta;
26
28
  useEffect(() => {
27
- if (nav && url && url.href !== nav.value.href) nav.replace(url);
28
- }, [nav, url]);
29
+ if (!nav || !url) return;
30
+ const current = nav.current();
31
+ if (current.stack === stack && current.ordinal === ordinal && url.href !== current.url.href) nav.replace(url);
32
+ }, [nav, url, stack, ordinal]);
29
33
 
30
34
  const fullTitle = joinTitles(title, app);
31
35
  return (
@@ -2,8 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { use } from "react";
3
3
  import { LeftIcon } from "../../icon/LeftIcon.js";
4
4
  import { Button } from "../button/Button.js";
5
+ import { requireMeta } from "../misc/MetaContext.js";
5
6
  import { getClass } from "../util/css.js";
6
- import { NavigationPositionContext } from "./NavigationContext.js";
7
+ import { NavigationContext } from "./NavigationContext.js";
7
8
  /**
8
9
  * Back button for the current stack.
9
10
  * - Goes back to the page before this one in the current stack, wherever you came from.
@@ -14,6 +15,8 @@ import { NavigationPositionContext } from "./NavigationContext.js";
14
15
  * @see https://shelving.cc/ui/BackButton
15
16
  */
16
17
  export function BackButton({ href, className, title = "Back", children = _jsx(LeftIcon, {}), ...props }) {
17
- const position = use(NavigationPositionContext);
18
- return (_jsx(Button, { ...props, title: title, href: position?.parent ?? href, className: getClass("back", className), children: children }));
18
+ const nav = use(NavigationContext);
19
+ const { stack = null, ordinal } = requireMeta();
20
+ const parent = nav && ordinal ? nav.history(stack)[ordinal - 1] : undefined;
21
+ return (_jsx(Button, { ...props, title: title, href: parent ?? href, className: getClass("back", className), children: children }));
19
22
  }
@@ -6,7 +6,7 @@ The back button for a page header. It goes back to the page before this one in t
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
8
  - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. 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
- - It is a plain link with `className="back"`. `<Navigation>` turns a click into `NavigationStore.back()`, so the page slides back. A middle-click opens the link in a new browser tab.
9
+ - 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
10
  - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
11
11
  - It takes the usual `<Button>` props, except `onClick`.
12
12
  - Without the browser Navigation API, and in a server render, it links to `href`.
@@ -2,8 +2,9 @@ import { type ReactElement, use } from "react";
2
2
  import { LeftIcon } from "../../icon/LeftIcon.js";
3
3
  import type { AbsolutePath } from "../../util/path.js";
4
4
  import { Button, type ButtonProps } from "../button/Button.js";
5
+ import { requireMeta } from "../misc/MetaContext.js";
5
6
  import { getClass } from "../util/css.js";
6
- import { NavigationPositionContext } from "./NavigationContext.js";
7
+ import { NavigationContext } from "./NavigationContext.js";
7
8
 
8
9
  /**
9
10
  * Props for `<BackButton>`: the `href` to go back to when the stack has no page before this one, plus the usual `Button` props except `onClick`.
@@ -25,9 +26,11 @@ export interface BackButtonProps extends Omit<ButtonProps, "href" | "onClick"> {
25
26
  * @see https://shelving.cc/ui/BackButton
26
27
  */
27
28
  export function BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement {
28
- const position = use(NavigationPositionContext);
29
+ const nav = use(NavigationContext);
30
+ const { stack = null, ordinal } = requireMeta();
31
+ const parent = nav && ordinal ? nav.history(stack)[ordinal - 1] : undefined;
29
32
  return (
30
- <Button {...props} title={title} href={position?.parent ?? href} className={getClass("back", className)}>
33
+ <Button {...props} title={title} href={parent ?? href} className={getClass("back", className)}>
31
34
  {children}
32
35
  </Button>
33
36
  );
@@ -24,13 +24,13 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
24
24
  }
25
25
  /**
26
26
  * Top-level navigation provider, with one stack of pages for each tab.
27
- * - Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
28
- * - Turns clicks on same-origin links into `NavigationStore.forward()`, or `NavigationStore.back()` for a link with `className="back"`, or `NavigationStore.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
- * - Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
30
- * - Publishes each change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition. A replace, or a change the browser already animated (for example a swipe-back), has no transition.
27
+ * - Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
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
+ * - 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
+ * - 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
31
  * - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
32
32
  *
33
- * Exactly one `<Navigation>` per app. Nested routers share its store.
33
+ * Exactly one `<Navigation>` per app. Nested routers share its sequence.
34
34
  *
35
35
  * @kind component
36
36
  * @see https://shelving.cc/ui/Navigation
@@ -1,62 +1,36 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
- import { startTransition, useEffect, useState } from "react";
2
+ import { useEffect, useLayoutEffect } from "react";
3
3
  import { useInstance } from "../../react/useInstance.js";
4
+ import { useSequenceTransition } from "../../react/useSequenceTransition.js";
4
5
  import { MetaContext, requireMeta } from "../misc/MetaContext.js";
5
- import { setTransitionType } from "../transition/util.js";
6
6
  import { mergeMeta } from "../util/index.js";
7
- import { NavigationContext, NavigationPositionContext } from "./NavigationContext.js";
8
- import { NavigationStore } from "./NavigationStore.js";
7
+ import { NavigationContext } from "./NavigationContext.js";
8
+ import { NavigationSequence } from "./NavigationSequence.js";
9
9
  /**
10
10
  * Top-level navigation provider, with one stack of pages for each tab.
11
- * - Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
12
- * - Turns clicks on same-origin links into `NavigationStore.forward()`, or `NavigationStore.back()` for a link with `className="back"`, or `NavigationStore.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
- * - Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
14
- * - Publishes each change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition. A replace, or a change the browser already animated (for example a swipe-back), has no transition.
11
+ * - Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
12
+ * - 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
+ * - Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
14
+ * - 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
15
  * - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
16
16
  *
17
- * Exactly one `<Navigation>` per app. Nested routers share its store.
17
+ * Exactly one `<Navigation>` per app. Nested routers share its sequence.
18
18
  *
19
19
  * @kind component
20
20
  * @see https://shelving.cc/ui/Navigation
21
21
  */
22
22
  export function Navigation({ children, stacks = [], ...meta }) {
23
23
  const current = requireMeta(meta);
24
- const nav = useInstance(NavigationStore, current.url, current.root, current.stack ?? null, ...stacks);
25
- // React runs a `<ViewTransition>` only for a transition update, and `useSyncExternalStore()` always renders a sync update.
26
- // So keep the published values in state, and copy each store change into it inside `startTransition()`.
27
- const [published, setPublished] = useState(() => _getPublished(nav));
24
+ const nav = useInstance(NavigationSequence, current.url, current.root, current.stack ?? null, ...stacks);
25
+ // 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 });
27
+ // Tell a waiting `NavigationSequence.publish()` that its page is committed.
28
+ useLayoutEffect(() => {
29
+ if (page)
30
+ nav.committed();
31
+ }, [nav, page]);
28
32
  useEffect(() => {
29
33
  const stopListening = nav.listen();
30
- // Publish the latest values once for each change, even when the URL and the stack both change.
31
- let last = nav.value.href;
32
- let lastStack = nav.stack.value;
33
- let pending = false;
34
- const publish = () => {
35
- const { value, transition } = nav;
36
- if (value.href === last && nav.stack.value === lastStack)
37
- return;
38
- last = value.href;
39
- lastStack = nav.stack.value;
40
- if (pending)
41
- return;
42
- pending = true;
43
- if (!transition) {
44
- pending = false;
45
- return setPublished(_getPublished(nav));
46
- }
47
- // React renders a transition that starts inside a browser history event as a sync update with no view transition, so leave the event first.
48
- setTimeout(() => {
49
- pending = false;
50
- startTransition(() => {
51
- setTransitionType(transition);
52
- setPublished(_getPublished(nav));
53
- });
54
- });
55
- };
56
- const stopURL = nav.subscribe(publish);
57
- const stopStack = nav.stack.subscribe(publish);
58
- // The first render may have run before the store saw the current history entry.
59
- setPublished(p => (p.url.href === nav.value.href && p.stack === nav.stack.value ? p : _getPublished(nav)));
60
34
  const onClick = (e) => {
61
35
  if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || !(e.target instanceof Element))
62
36
  return;
@@ -79,14 +53,15 @@ export function Navigation({ children, stacks = [], ...meta }) {
79
53
  document.addEventListener("click", onClick);
80
54
  return () => {
81
55
  document.removeEventListener("click", onClick);
82
- stopURL();
83
- stopStack();
84
56
  stopListening();
85
57
  };
86
58
  }, [nav]);
87
- const { url, stack, position } = published;
88
- return (_jsx(NavigationContext, { value: nav, children: _jsx(NavigationPositionContext, { value: position, children: _jsx(MetaContext, { value: mergeMeta(current, { url, stack }, Navigation), children: children }) }) }));
59
+ const { url, stack, ordinal } = page;
60
+ return (_jsx(NavigationContext, { value: nav, children: _jsx(MetaContext, { value: mergeMeta(current, { url, stack, ordinal }, Navigation), children: children }) }));
61
+ }
62
+ function _getDirection({ direction }) {
63
+ return direction;
89
64
  }
90
- function _getPublished(nav) {
91
- return { url: nav.value, stack: nav.stack.value, position: nav.position };
65
+ function _isSamePage(a, b) {
66
+ return a.url.href === b.url.href && a.stack === b.stack && a.ordinal === b.ordinal;
92
67
  }
@@ -1,19 +1,20 @@
1
1
  # Navigation
2
2
 
3
- The top-level navigation provider for a client-side app. It owns one `NavigationStore`, turns link clicks into navigation, and publishes the live URL into `<Meta>`, so each `<Router>` re-renders when the URL changes. Use exactly one `<Navigation>` per app. Nested routers all share its store.
3
+ The top-level navigation provider for a client-side app. It owns one `NavigationSequence`, turns link clicks into navigation, holds the page it shows in its own state, and publishes that page into `<Meta>`, so each `<Router>` re-renders when the page changes. Use exactly one `<Navigation>` per app. Nested routers all share its sequence.
4
4
 
5
5
  Give it `stacks` for an app with a tab bar. Each stack is one tab with its own history of pages, like a phone app: each tab remembers where you left it, and a back button goes back within its tab.
6
6
 
7
7
  **Things to know:**
8
8
 
9
- - Same-origin link clicks become `NavigationStore.forward()`, so the page slides forward.
10
- - A link with `className="back"` calls `NavigationStore.back()`, so the page slides back. `<BackButton>` sets this class for you.
11
- - A link with `className="replace"` calls `NavigationStore.replace()`. It changes the URL with no new history entry and no slide, and keeps the same page mounted. Use it for tabs inside a page.
9
+ - Same-origin link clicks become `NavigationSequence.forward()`, so the page slides forward.
10
+ - A link with `className="back"` calls `NavigationSequence.back()`, so the page slides back. `<BackButton>` sets this class for you.
11
+ - A link with `className="replace"` calls `NavigationSequence.replace()`. It changes the URL with no new history entry and no slide, and keeps the same page mounted. Use it for tabs inside a page.
12
12
  - Clicks with a modifier key (Cmd, Ctrl, Shift, Alt), a middle-click, and links with `download` or a `target` other than `_self` go to the browser as usual.
13
- - It publishes each page change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` such as `<HorizontalTransition>` slides the page. A replace has no transition.
14
- - The browser back and forward buttons slide too. Inside a stack the direction comes from the depth of the page. Across stacks it comes from tab order.
13
+ - It takes each `NavigationEvent` with `useSequenceTransition()`. A move is set inside `startTransition()` with its `"forward"` or `"back"` transition type, so a `<Transition>` such as `<HorizontalTransition>` slides the page. A replace has no transition. An event for the page already shown is skipped.
14
+ - The browser back and forward buttons slide too. Inside a stack the direction comes from the ordinal of the page. Across stacks it comes from tab order.
15
15
  - When the browser already animated the change (for example a swipe-back on a phone), there is no view transition, so the page does not slide twice.
16
- - It publishes `stack` (the root of the current stack) into `<Meta>` beside `url`, so any component can read the current tab with `requireMeta().stack`. On a floating page (outside every stack) `stack` is `null`. With no `stacks`, every page floats.
16
+ - It publishes `url`, `stack` (the root of the current stack) and `ordinal` (the page's place in its stack) into `<Meta>`, so any component can read the page on screen with `requireMeta()`. On a floating page (outside every stack) `stack` is `null`. With no `stacks`, every page floats.
17
+ - When it starts listening it reads the current history entry, so a `replace()` sent before that (for example from a page's first effect) is not lost.
17
18
  - It reads the start URL and root from the surrounding `<Meta>`, so set `url` and `root` on an ancestor `<App>` or `<HTML>`. In the browser the URL falls back to `window.location.href`.
18
19
  - `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
19
20
 
@@ -59,7 +60,7 @@ const TABS = (
59
60
  <App root="https://example.com/">
60
61
  <Navigation stacks={STACKS}>
61
62
  <AppLayout nav={TABS}>
62
- <HorizontalTransition>
63
+ <HorizontalTransition default="none">
63
64
  <RouteCache>
64
65
  <Scroll vertical cover>
65
66
  <PageLoader>
@@ -84,9 +85,9 @@ const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
84
85
  <Navigation stacks={STACKS} stack={stack}>
85
86
  ```
86
87
 
87
- Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
88
+ Put the transition **outside** `<RouteCache>`, around the whole cache, with no `key`. A page change is an update of the transition, and it slides by type. Set `default="none"`, so a change with no type (a replace) does not animate. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`. The app also works with no `<RouteCache>`: put the transition around the `<Router>`.
88
89
 
89
- The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else the page **floats**: its stack is `null`. A floating page, such as a deep link or a login page, is outside every tab: no tab is selected, and links from it stay floating until you tap a tab or name a stack (for example `nav.replace("/home", "/home")` after a login). `/` is a normal stack root, so a Home tab at `/` is never mixed up with floating pages. See `NavigationStore`.
90
+ The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else the page **floats**: its stack is `null`. A floating page, such as a deep link or a login page, is outside every tab: no tab is selected, and links from it stay floating until you tap a tab or name a stack (for example `nav.replace("/home", "/home")` after a login). `/` is a normal stack root, so a Home tab at `/` is never mixed up with floating pages. See `NavigationSequence`.
90
91
 
91
92
  Each link pushes a new page onto the current stack, wherever it points. So a link from `/home` to `/profile/settings` opens the settings page in the Home tab, and the Profile tab stays where it was. Tap a `<StackButton>` to change tab.
92
93
 
@@ -110,7 +111,7 @@ Each link pushes a new page onto the current stack, wherever it points. So a lin
110
111
 
111
112
  ### Imperative navigation
112
113
 
113
- Read the store from anywhere in the tree with `requireNavigation()`:
114
+ Read the sequence from anywhere in the tree with `requireNavigation()`:
114
115
 
115
116
  ```tsx
116
117
  import { requireNavigation } from "shelving/ui";
@@ -121,4 +122,4 @@ nav.back("/home"); // Go back to a page.
121
122
  nav.replace("/login"); // Change the URL of the current page.
122
123
  ```
123
124
 
124
- See `NavigationStore` for what each method does.
125
+ See `NavigationSequence` for what each method does.
@@ -1,13 +1,12 @@
1
- import { type ReactElement, startTransition, useEffect, useState } from "react";
1
+ import { type ReactElement, useEffect, useLayoutEffect } from "react";
2
2
  import { useInstance } from "../../react/useInstance.js";
3
+ import { useSequenceTransition } from "../../react/useSequenceTransition.js";
3
4
  import type { AbsolutePath } from "../../util/path.js";
4
- import type { ImmutableURL } from "../../util/url.js";
5
5
  import { MetaContext, requireMeta } from "../misc/MetaContext.js";
6
- import { setTransitionType } from "../transition/util.js";
7
6
  import { mergeMeta, type PossibleMeta } from "../util/index.js";
8
7
  import type { OptionalChildProps } from "../util/props.js";
9
- import { NavigationContext, NavigationPositionContext } from "./NavigationContext.js";
10
- import { type NavigationPosition, NavigationStore } from "./NavigationStore.js";
8
+ import { NavigationContext } from "./NavigationContext.js";
9
+ import { type NavigationEvent, NavigationSequence } from "./NavigationSequence.js";
11
10
 
12
11
  /**
13
12
  * Props for `<Navigation>`: the initial `Meta` (url, root and stack), the `stacks`, and optional `children`.
@@ -30,67 +29,34 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
30
29
  readonly stack?: AbsolutePath | null | undefined;
31
30
  }
32
31
 
33
- /** What `<Navigation>` publishes on each change. */
34
- interface _Published {
35
- readonly url: ImmutableURL;
36
- readonly stack: AbsolutePath | null;
37
- readonly position: NavigationPosition | undefined;
38
- }
39
-
40
32
  /**
41
33
  * Top-level navigation provider, with one stack of pages for each tab.
42
- * - Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
43
- * - Turns clicks on same-origin links into `NavigationStore.forward()`, or `NavigationStore.back()` for a link with `className="back"`, or `NavigationStore.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.
44
- * - Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
45
- * - Publishes each change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition. A replace, or a change the browser already animated (for example a swipe-back), has no transition.
34
+ * - Owns a single `NavigationSequence` made from the surrounding `<Meta>` url and root.
35
+ * - 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
+ * - Holds the page it shows in its own state, and publishes its `url`, `stack` and `ordinal` into `Meta`. Read the current page from `Meta`.
37
+ * - 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.
46
38
  * - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
47
39
  *
48
- * Exactly one `<Navigation>` per app. Nested routers share its store.
40
+ * Exactly one `<Navigation>` per app. Nested routers share its sequence.
49
41
  *
50
42
  * @kind component
51
43
  * @see https://shelving.cc/ui/Navigation
52
44
  */
53
45
  export function Navigation({ children, stacks = [], ...meta }: NavigationProps): ReactElement {
54
46
  const current = requireMeta(meta);
55
- const nav = useInstance(NavigationStore, current.url, current.root, current.stack ?? null, ...stacks);
47
+ const nav = useInstance(NavigationSequence, current.url, current.root, current.stack ?? null, ...stacks);
56
48
 
57
- // React runs a `<ViewTransition>` only for a transition update, and `useSyncExternalStore()` always renders a sync update.
58
- // So keep the published values in state, and copy each store change into it inside `startTransition()`.
59
- const [published, setPublished] = useState<_Published>(() => _getPublished(nav));
49
+ // 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 });
51
+
52
+ // Tell a waiting `NavigationSequence.publish()` that its page is committed.
53
+ useLayoutEffect(() => {
54
+ if (page) nav.committed();
55
+ }, [nav, page]);
60
56
 
61
57
  useEffect(() => {
62
58
  const stopListening = nav.listen();
63
59
 
64
- // Publish the latest values once for each change, even when the URL and the stack both change.
65
- let last = nav.value.href;
66
- let lastStack = nav.stack.value;
67
- let pending = false;
68
- const publish = () => {
69
- const { value, transition } = nav;
70
- if (value.href === last && nav.stack.value === lastStack) return;
71
- last = value.href;
72
- lastStack = nav.stack.value;
73
- if (pending) return;
74
- pending = true;
75
- if (!transition) {
76
- pending = false;
77
- return setPublished(_getPublished(nav));
78
- }
79
- // React renders a transition that starts inside a browser history event as a sync update with no view transition, so leave the event first.
80
- setTimeout(() => {
81
- pending = false;
82
- startTransition(() => {
83
- setTransitionType(transition);
84
- setPublished(_getPublished(nav));
85
- });
86
- });
87
- };
88
- const stopURL = nav.subscribe(publish);
89
- const stopStack = nav.stack.subscribe(publish);
90
-
91
- // The first render may have run before the store saw the current history entry.
92
- setPublished(p => (p.url.href === nav.value.href && p.stack === nav.stack.value ? p : _getPublished(nav)));
93
-
94
60
  const onClick = (e: MouseEvent) => {
95
61
  if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || !(e.target instanceof Element))
96
62
  return;
@@ -110,22 +76,22 @@ export function Navigation({ children, stacks = [], ...meta }: NavigationProps):
110
76
 
111
77
  return () => {
112
78
  document.removeEventListener("click", onClick);
113
- stopURL();
114
- stopStack();
115
79
  stopListening();
116
80
  };
117
81
  }, [nav]);
118
82
 
119
- const { url, stack, position } = published;
83
+ const { url, stack, ordinal } = page;
120
84
  return (
121
85
  <NavigationContext value={nav}>
122
- <NavigationPositionContext value={position}>
123
- <MetaContext value={mergeMeta(current, { url, stack }, Navigation)}>{children}</MetaContext>
124
- </NavigationPositionContext>
86
+ <MetaContext value={mergeMeta(current, { url, stack, ordinal }, Navigation)}>{children}</MetaContext>
125
87
  </NavigationContext>
126
88
  );
127
89
  }
128
90
 
129
- function _getPublished(nav: NavigationStore): _Published {
130
- return { url: nav.value, stack: nav.stack.value, position: nav.position };
91
+ function _getDirection({ direction }: NavigationEvent): string | undefined {
92
+ return direction;
93
+ }
94
+
95
+ function _isSamePage(a: NavigationEvent, b: NavigationEvent): boolean {
96
+ return a.url.href === b.url.href && a.stack === b.stack && a.ordinal === b.ordinal;
131
97
  }
@@ -1,24 +1,16 @@
1
- import type { NavigationPosition, NavigationStore } from "./NavigationStore.js";
1
+ import type { NavigationSequence } from "./NavigationSequence.js";
2
2
  /**
3
- * React context holding the current `NavigationStore`, provided by `<Navigation>`.
3
+ * React context holding the current `NavigationSequence`, provided by `<Navigation>`.
4
4
  *
5
- * @example <NavigationContext value={store}>…</NavigationContext>
5
+ * @example <NavigationContext value={nav}>…</NavigationContext>
6
6
  * @see https://shelving.cc/ui/NavigationContext
7
7
  */
8
- export declare const NavigationContext: import("react").Context<NavigationStore | undefined>;
8
+ export declare const NavigationContext: import("react").Context<NavigationSequence | undefined>;
9
9
  /**
10
- * Read the current `NavigationStore` from context, throwing if used outside `<Navigation>`.
10
+ * Read the current `NavigationSequence` from context, throwing if used outside `<Navigation>`.
11
11
  *
12
- * @returns The current `NavigationStore`.
12
+ * @returns The current `NavigationSequence`.
13
13
  * @throws RequiredError If no `<Navigation>` provider is present above.
14
14
  * @see https://shelving.cc/ui/requireNavigation
15
15
  */
16
- export declare function requireNavigation(): NavigationStore;
17
- /**
18
- * React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
19
- * - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
20
- * - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
21
- *
22
- * @see https://shelving.cc/ui/NavigationPositionContext
23
- */
24
- export declare const NavigationPositionContext: import("react").Context<NavigationPosition | undefined>;
16
+ export declare function requireNavigation(): NavigationSequence;
@@ -1,29 +1,20 @@
1
1
  import { createContext } from "react";
2
2
  import { requireContext } from "../util/context.js";
3
3
  /**
4
- * React context holding the current `NavigationStore`, provided by `<Navigation>`.
4
+ * React context holding the current `NavigationSequence`, provided by `<Navigation>`.
5
5
  *
6
- * @example <NavigationContext value={store}>…</NavigationContext>
6
+ * @example <NavigationContext value={nav}>…</NavigationContext>
7
7
  * @see https://shelving.cc/ui/NavigationContext
8
8
  */
9
9
  export const NavigationContext = createContext(undefined);
10
10
  NavigationContext.displayName = "NavigationContext";
11
11
  /**
12
- * Read the current `NavigationStore` from context, throwing if used outside `<Navigation>`.
12
+ * Read the current `NavigationSequence` from context, throwing if used outside `<Navigation>`.
13
13
  *
14
- * @returns The current `NavigationStore`.
14
+ * @returns The current `NavigationSequence`.
15
15
  * @throws RequiredError If no `<Navigation>` provider is present above.
16
16
  * @see https://shelving.cc/ui/requireNavigation
17
17
  */
18
18
  export function requireNavigation() {
19
19
  return requireContext(NavigationContext, requireNavigation);
20
20
  }
21
- /**
22
- * React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
23
- * - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
24
- * - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
25
- *
26
- * @see https://shelving.cc/ui/NavigationPositionContext
27
- */
28
- export const NavigationPositionContext = createContext(undefined);
29
- NavigationPositionContext.displayName = "NavigationPositionContext";
@@ -1,33 +1,23 @@
1
1
  import { createContext } from "react";
2
2
  import { requireContext } from "../util/context.js";
3
- import type { NavigationPosition, NavigationStore } from "./NavigationStore.js";
3
+ import type { NavigationSequence } from "./NavigationSequence.js";
4
4
 
5
5
  /**
6
- * React context holding the current `NavigationStore`, provided by `<Navigation>`.
6
+ * React context holding the current `NavigationSequence`, provided by `<Navigation>`.
7
7
  *
8
- * @example <NavigationContext value={store}>…</NavigationContext>
8
+ * @example <NavigationContext value={nav}>…</NavigationContext>
9
9
  * @see https://shelving.cc/ui/NavigationContext
10
10
  */
11
- export const NavigationContext = createContext<NavigationStore | undefined>(undefined);
11
+ export const NavigationContext = createContext<NavigationSequence | undefined>(undefined);
12
12
  NavigationContext.displayName = "NavigationContext";
13
13
 
14
14
  /**
15
- * Read the current `NavigationStore` from context, throwing if used outside `<Navigation>`.
15
+ * Read the current `NavigationSequence` from context, throwing if used outside `<Navigation>`.
16
16
  *
17
- * @returns The current `NavigationStore`.
17
+ * @returns The current `NavigationSequence`.
18
18
  * @throws RequiredError If no `<Navigation>` provider is present above.
19
19
  * @see https://shelving.cc/ui/requireNavigation
20
20
  */
21
- export function requireNavigation(): NavigationStore {
21
+ export function requireNavigation(): NavigationSequence {
22
22
  return requireContext(NavigationContext, requireNavigation);
23
23
  }
24
-
25
- /**
26
- * React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
27
- * - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
28
- * - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
29
- *
30
- * @see https://shelving.cc/ui/NavigationPositionContext
31
- */
32
- export const NavigationPositionContext = createContext<NavigationPosition | undefined>(undefined);
33
- NavigationPositionContext.displayName = "NavigationPositionContext";