shelving 1.320.0 → 1.322.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 (171) hide show
  1. package/docs/guides/building-with-shelving.md +230 -1
  2. package/docs/llms-full.txt +1395 -351
  3. package/docs/ui/App.md +105 -7
  4. package/docs/ui/AppLayout.md +85 -0
  5. package/docs/ui/AppLayoutProps.md +21 -0
  6. package/docs/ui/BackButton.md +75 -0
  7. package/docs/ui/BackButtonProps.md +21 -0
  8. package/docs/ui/Catcher.md +1 -1
  9. package/docs/ui/ClickableProps.md +0 -2
  10. package/docs/ui/ErrorPage.md +2 -1
  11. package/docs/ui/FixedLayout.md +91 -0
  12. package/docs/ui/FixedLayoutProps.md +13 -0
  13. package/docs/ui/GapVariants.md +2 -2
  14. package/docs/ui/Head.md +2 -2
  15. package/docs/ui/HeightVariant.md +30 -0
  16. package/docs/ui/HeightVariants.md +26 -0
  17. package/docs/ui/HorizontalTransition.md +1 -1
  18. package/docs/ui/LinkClickable.md +0 -1
  19. package/docs/ui/Meta.md +3 -1
  20. package/docs/ui/Navigation.md +102 -37
  21. package/docs/ui/NavigationEntryState.md +22 -0
  22. package/docs/ui/NavigationPosition.md +24 -0
  23. package/docs/ui/NavigationPositionContext.md +8 -0
  24. package/docs/ui/NavigationProps.md +12 -2
  25. package/docs/ui/NavigationStore/back.md +6 -4
  26. package/docs/ui/NavigationStore/forward.md +6 -2
  27. package/docs/ui/NavigationStore/history.md +15 -0
  28. package/docs/ui/NavigationStore/listen.md +14 -0
  29. package/docs/ui/NavigationStore/replace.md +15 -0
  30. package/docs/ui/NavigationStore.md +100 -19
  31. package/docs/ui/PaddingVariants.md +2 -2
  32. package/docs/ui/Page.md +12 -8
  33. package/docs/ui/PageLoader.md +2 -1
  34. package/docs/ui/RouteCache.md +77 -36
  35. package/docs/ui/RouteCacheProps.md +3 -3
  36. package/docs/ui/Router.md +12 -6
  37. package/docs/ui/Scroll.md +60 -6
  38. package/docs/ui/ScrollVariants.md +5 -1
  39. package/docs/ui/SidebarLayout.md +17 -8
  40. package/docs/ui/SpaceValue.md +1 -0
  41. package/docs/ui/StackButton.md +64 -0
  42. package/docs/ui/StackButtonProps.md +21 -0
  43. package/docs/ui/TreeApp.md +1 -1
  44. package/docs/ui/VerticalTransition.md +1 -1
  45. package/docs/ui/getBlockClass.md +1 -1
  46. package/docs/ui/getGapClass.md +1 -1
  47. package/docs/ui/getHeightClass.md +64 -0
  48. package/docs/ui/getPaddingClass.md +1 -1
  49. package/docs/ui/getScrollClass.md +4 -2
  50. package/docs/ui/getSpaceClass.md +2 -0
  51. package/docs/ui/mergeMeta.md +2 -1
  52. package/docs/ui.md +25 -17
  53. package/package.json +1 -1
  54. package/ui/README.md +1 -1
  55. package/ui/app/App.md +105 -7
  56. package/ui/button/Clickable.d.ts +1 -3
  57. package/ui/button/Clickable.js +2 -2
  58. package/ui/button/Clickable.tsx +0 -4
  59. package/ui/docs/DocumentationApp.js +4 -1
  60. package/ui/docs/DocumentationApp.tsx +10 -1
  61. package/ui/layout/AppLayout.d.ts +21 -0
  62. package/ui/layout/AppLayout.js +18 -0
  63. package/ui/layout/AppLayout.md +57 -0
  64. package/ui/layout/AppLayout.module.css +106 -0
  65. package/ui/layout/AppLayout.tsx +36 -0
  66. package/ui/layout/FixedLayout.d.ts +18 -0
  67. package/ui/layout/FixedLayout.js +15 -0
  68. package/ui/layout/FixedLayout.md +65 -0
  69. package/ui/layout/FixedLayout.module.css +55 -0
  70. package/ui/layout/FixedLayout.tsx +25 -0
  71. package/ui/layout/SidebarLayout.d.ts +2 -2
  72. package/ui/layout/SidebarLayout.js +3 -4
  73. package/ui/layout/SidebarLayout.md +15 -6
  74. package/ui/layout/SidebarLayout.module.css +11 -16
  75. package/ui/layout/SidebarLayout.tsx +10 -13
  76. package/ui/layout/index.d.ts +2 -1
  77. package/ui/layout/index.js +2 -1
  78. package/ui/layout/index.tsx +2 -1
  79. package/ui/misc/Catcher.d.ts +2 -1
  80. package/ui/misc/Catcher.js +4 -3
  81. package/ui/misc/Catcher.md +1 -1
  82. package/ui/misc/Catcher.tsx +5 -4
  83. package/ui/misc/Loader.d.ts +1 -0
  84. package/ui/misc/Loader.js +6 -2
  85. package/ui/misc/Loader.tsx +11 -2
  86. package/ui/page/Head.d.ts +2 -2
  87. package/ui/page/Head.js +9 -8
  88. package/ui/page/Head.tsx +8 -6
  89. package/ui/page/Page.md +12 -8
  90. package/ui/router/BackButton.d.ts +22 -0
  91. package/ui/router/BackButton.js +19 -0
  92. package/ui/router/BackButton.md +47 -0
  93. package/ui/router/BackButton.tsx +34 -0
  94. package/ui/router/Navigation.d.ts +22 -12
  95. package/ui/router/Navigation.js +67 -51
  96. package/ui/router/Navigation.md +93 -27
  97. package/ui/router/Navigation.test.tsx +27 -7
  98. package/ui/router/Navigation.tsx +90 -53
  99. package/ui/router/NavigationContext.d.ts +9 -1
  100. package/ui/router/NavigationContext.js +9 -0
  101. package/ui/router/NavigationContext.tsx +11 -1
  102. package/ui/router/NavigationStore.d.ts +126 -19
  103. package/ui/router/NavigationStore.js +301 -30
  104. package/ui/router/NavigationStore.md +82 -9
  105. package/ui/router/NavigationStore.test.ts +384 -0
  106. package/ui/router/NavigationStore.tsx +347 -30
  107. package/ui/router/RouteCache.d.ts +16 -22
  108. package/ui/router/RouteCache.js +37 -47
  109. package/ui/router/RouteCache.md +63 -16
  110. package/ui/router/RouteCache.tsx +56 -62
  111. package/ui/router/Router.d.ts +2 -1
  112. package/ui/router/Router.js +9 -14
  113. package/ui/router/Router.md +10 -5
  114. package/ui/router/Router.tsx +9 -20
  115. package/ui/router/StackButton.d.ts +24 -0
  116. package/ui/router/StackButton.js +35 -0
  117. package/ui/router/StackButton.md +34 -0
  118. package/ui/router/StackButton.tsx +44 -0
  119. package/ui/router/index.d.ts +2 -2
  120. package/ui/router/index.js +2 -2
  121. package/ui/router/index.ts +2 -2
  122. package/ui/style/Block.d.ts +3 -2
  123. package/ui/style/Block.js +3 -2
  124. package/ui/style/Block.tsx +4 -2
  125. package/ui/style/Gap.d.ts +1 -1
  126. package/ui/style/Gap.tsx +1 -1
  127. package/ui/style/Height.d.ts +32 -0
  128. package/ui/style/Height.js +13 -0
  129. package/ui/style/Height.module.css +88 -0
  130. package/ui/style/Height.tsx +61 -0
  131. package/ui/style/Padding.d.ts +1 -1
  132. package/ui/style/Padding.tsx +1 -1
  133. package/ui/style/Scroll.d.ts +9 -5
  134. package/ui/style/Scroll.js +6 -4
  135. package/ui/style/Scroll.md +59 -0
  136. package/ui/style/Scroll.module.css +13 -1
  137. package/ui/style/Scroll.tsx +13 -5
  138. package/ui/style/Space.d.ts +1 -1
  139. package/ui/style/Space.module.css +12 -0
  140. package/ui/style/Space.tsx +1 -0
  141. package/ui/style/getHeightClass.md +30 -0
  142. package/ui/style/getSpaceClass.md +2 -0
  143. package/ui/style/index.d.ts +1 -0
  144. package/ui/style/index.js +1 -0
  145. package/ui/style/index.ts +1 -0
  146. package/ui/transition/HorizontalTransition.md +1 -1
  147. package/ui/transition/VerticalTransition.md +1 -1
  148. package/ui/tree/TreeApp.d.ts +1 -1
  149. package/ui/tree/TreeApp.js +5 -2
  150. package/ui/tree/TreeApp.tsx +11 -2
  151. package/ui/util/meta.d.ts +4 -1
  152. package/ui/util/meta.ts +4 -1
  153. package/docs/ui/CenteredLayout.md +0 -66
  154. package/docs/ui/CenteredLayoutProps.md +0 -14
  155. package/docs/ui/NavigationStore/redirect.md +0 -12
  156. package/docs/ui/RouteConfig.md +0 -75
  157. package/docs/ui/RouteConfigProps.md +0 -24
  158. package/docs/ui/RouteContext.md +0 -6
  159. package/docs/ui/RouteState.md +0 -30
  160. package/ui/layout/CenteredLayout.d.ts +0 -21
  161. package/ui/layout/CenteredLayout.js +0 -28
  162. package/ui/layout/CenteredLayout.md +0 -41
  163. package/ui/layout/CenteredLayout.module.css +0 -72
  164. package/ui/layout/CenteredLayout.tsx +0 -56
  165. package/ui/router/RouteConfig.d.ts +0 -28
  166. package/ui/router/RouteConfig.js +0 -30
  167. package/ui/router/RouteConfig.md +0 -42
  168. package/ui/router/RouteConfig.tsx +0 -44
  169. package/ui/router/RouteContext.d.ts +0 -22
  170. package/ui/router/RouteContext.js +0 -8
  171. package/ui/router/RouteContext.tsx +0 -26
@@ -1,9 +1,9 @@
1
1
  import { Component, type ReactElement, type ReactNode } from "react";
2
2
  import { getMessage } from "../../util/error.js";
3
3
  import type { Callback } from "../../util/function.js";
4
+ import { Block } from "../block/Block.js";
4
5
  import { Paragraph } from "../block/Paragraph.js";
5
6
  import { RetryButton, RetryContext } from "../button/RetryButton.js";
6
- import { CenteredLayout } from "../layout/CenteredLayout.js";
7
7
  import { Notice } from "../notice/Notice.js";
8
8
  import { Page } from "../page/Page.js";
9
9
  import type { ChildProps } from "../util/props.js";
@@ -96,7 +96,8 @@ export function PageCatcher({ children }: ChildProps): ReactElement {
96
96
  }
97
97
 
98
98
  /**
99
- * Render a caught error as a full-page `<Page>` with a centered `<ErrorNotice>`.
99
+ * Render a caught error as a `<Page>` with an `<ErrorNotice>` in a narrow column, centred in the middle of the screen.
100
+ * - It renders no layout, so it shows inside whatever layout is around it. Outside every layout (an app-level catcher), wrap it in one, for example `<FixedLayout>` with a `<Scroll vertical cover>`.
100
101
  *
101
102
  * @kind component
102
103
  * @see https://shelving.cc/ui/ErrorPage
@@ -104,9 +105,9 @@ export function PageCatcher({ children }: ChildProps): ReactElement {
104
105
  export function ErrorPage({ reason }: ErrorProps): ReactElement {
105
106
  return (
106
107
  <Page title="Error">
107
- <CenteredLayout>
108
+ <Block height="full" middle width="narrow" padding="xxlarge" indent="normal">
108
109
  <ErrorNotice reason={reason} />
109
- </CenteredLayout>
110
+ </Block>
110
111
  </Page>
111
112
  );
112
113
  }
@@ -24,6 +24,7 @@ export declare function Loader({ children, fallback }: LoaderProps): ReactElemen
24
24
  *
25
25
  * - Wrapped in `<PageCatcher>` so child components can throw errors.
26
26
  * - Wrapped in `<Suspense>` so child components can throw promises.
27
+ * - It renders no layout, so its loading state and error page show inside whatever layout is around it.
27
28
  *
28
29
  * @kind component
29
30
  * @see https://shelving.cc/ui/PageLoader
package/ui/misc/Loader.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { Suspense } from "react";
3
- import { CenteredLayout } from "../layout/CenteredLayout.js";
3
+ import { Block } from "../block/Block.js";
4
+ import { Row } from "../block/Row.js";
4
5
  import { Catcher, PageCatcher } from "./Catcher.js";
5
6
  import { LOADING } from "./Icon.js";
6
7
  /**
@@ -15,15 +16,18 @@ import { LOADING } from "./Icon.js";
15
16
  export function Loader({ children, fallback = LOADING }) {
16
17
  return (_jsx(Catcher, { children: _jsx(Suspense, { fallback: fallback, children: children }) }));
17
18
  }
19
+ /** Default page loading state: the spinner, in the middle of the screen. It renders no layout. */
20
+ const PAGE_LOADING = (_jsx(Block, { height: "full", middle: true, padding: "xxlarge", children: _jsx(Row, { center: true, children: LOADING }) }));
18
21
  /**
19
22
  * Load a page.
20
23
  *
21
24
  * - Wrapped in `<PageCatcher>` so child components can throw errors.
22
25
  * - Wrapped in `<Suspense>` so child components can throw promises.
26
+ * - It renders no layout, so its loading state and error page show inside whatever layout is around it.
23
27
  *
24
28
  * @kind component
25
29
  * @see https://shelving.cc/ui/PageLoader
26
30
  */
27
- export function PageLoader({ children, fallback = _jsx(CenteredLayout, { children: LOADING }) }) {
31
+ export function PageLoader({ children, fallback = PAGE_LOADING }) {
28
32
  return (_jsx(PageCatcher, { children: _jsx(Suspense, { fallback: fallback, children: children }) }));
29
33
  }
@@ -1,5 +1,6 @@
1
1
  import { type ReactElement, type ReactNode, Suspense } from "react";
2
- import { CenteredLayout } from "../layout/CenteredLayout.js";
2
+ import { Block } from "../block/Block.js";
3
+ import { Row } from "../block/Row.js";
3
4
  import type { ChildProps } from "../util/props.js";
4
5
  import { Catcher, PageCatcher } from "./Catcher.js";
5
6
  import { LOADING } from "./Icon.js";
@@ -31,16 +32,24 @@ export function Loader({ children, fallback = LOADING }: LoaderProps): ReactElem
31
32
  );
32
33
  }
33
34
 
35
+ /** Default page loading state: the spinner, in the middle of the screen. It renders no layout. */
36
+ const PAGE_LOADING = (
37
+ <Block height="full" middle padding="xxlarge">
38
+ <Row center>{LOADING}</Row>
39
+ </Block>
40
+ );
41
+
34
42
  /**
35
43
  * Load a page.
36
44
  *
37
45
  * - Wrapped in `<PageCatcher>` so child components can throw errors.
38
46
  * - Wrapped in `<Suspense>` so child components can throw promises.
47
+ * - It renders no layout, so its loading state and error page show inside whatever layout is around it.
39
48
  *
40
49
  * @kind component
41
50
  * @see https://shelving.cc/ui/PageLoader
42
51
  */
43
- export function PageLoader({ children, fallback = <CenteredLayout>{LOADING}</CenteredLayout> }: LoaderProps): ReactElement {
52
+ export function PageLoader({ children, fallback = PAGE_LOADING }: LoaderProps): ReactElement {
44
53
  return (
45
54
  <PageCatcher>
46
55
  <Suspense fallback={fallback}>{children}</Suspense>
package/ui/page/Head.d.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  import { type ReactElement } from "react";
2
2
  /**
3
- * Emit the current page's head metadata and sync browser history to its URL.
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
- * - Updates `window.history` to match the page URL.
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.
7
7
  *
8
8
  * @kind component
9
9
  * @see https://shelving.cc/ui/Head
package/ui/page/Head.js CHANGED
@@ -1,15 +1,16 @@
1
1
  import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { useEffect } from "react";
2
+ import { use, useEffect } from "react";
3
3
  import { getProps } from "../../util/object.js";
4
4
  import { requireMeta } from "../misc/MetaContext.js";
5
+ import { NavigationContext } from "../router/NavigationContext.js";
5
6
  import { joinTitles } from "../util/meta.js";
6
7
  /** Meta tags with a capital first letter and hyphens, e.g. `Content-Security-Policy` or `Accept`, are `http-equiv=""` tags. */
7
8
  const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
8
9
  /**
9
- * Emit the current page's head metadata and sync browser history to its URL.
10
+ * Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
10
11
  * - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
11
12
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
12
- * - Updates `window.history` to match the page URL.
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
14
  *
14
15
  * @kind component
15
16
  * @see https://shelving.cc/ui/Head
@@ -17,12 +18,12 @@ const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
17
18
  export function Head() {
18
19
  const meta = requireMeta();
19
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.
22
+ const nav = use(NavigationContext);
20
23
  useEffect(() => {
21
- if (typeof window === "undefined")
22
- return;
23
- if (url)
24
- window.history.replaceState(null, "", url);
25
- }, [url]);
24
+ if (nav && url && url.href !== nav.value.href)
25
+ nav.replace(url);
26
+ }, [nav, url]);
26
27
  const fullTitle = joinTitles(title, app);
27
28
  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)] }));
28
29
  }
package/ui/page/Head.tsx CHANGED
@@ -1,17 +1,18 @@
1
- import { type ReactElement, useEffect } from "react";
1
+ import { type ReactElement, use, useEffect } from "react";
2
2
  import type { ArrayItem } from "../../util/array.js";
3
3
  import { getProps, type Prop } from "../../util/object.js";
4
4
  import { requireMeta } from "../misc/MetaContext.js";
5
+ import { NavigationContext } from "../router/NavigationContext.js";
5
6
  import { joinTitles, type MetaAssets, type MetaLinks, type MetaTags } from "../util/meta.js";
6
7
 
7
8
  /** Meta tags with a capital first letter and hyphens, e.g. `Content-Security-Policy` or `Accept`, are `http-equiv=""` tags. */
8
9
  const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
9
10
 
10
11
  /**
11
- * Emit the current page's head metadata and sync browser history to its URL.
12
+ * Emit the current page's head metadata, and replace the browser URL with the page's canonical URL.
12
13
  * - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
13
14
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
14
- * - Updates `window.history` to match the page URL.
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
16
  *
16
17
  * @kind component
17
18
  * @see https://shelving.cc/ui/Head
@@ -20,10 +21,11 @@ export function Head(): ReactElement {
20
21
  const meta = requireMeta();
21
22
  const { url, title, app, description, links, tags, stylesheets, modules, scripts } = meta;
22
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.
25
+ const nav = use(NavigationContext);
23
26
  useEffect(() => {
24
- if (typeof window === "undefined") return;
25
- if (url) window.history.replaceState(null, "", url);
26
- }, [url]);
27
+ if (nav && url && url.href !== nav.value.href) nav.replace(url);
28
+ }, [nav, url]);
27
29
 
28
30
  const fullTitle = joinTitles(title, app);
29
31
  return (
package/ui/page/Page.md CHANGED
@@ -22,14 +22,18 @@ function UserPage({ id }: { id: string }) {
22
22
  }
23
23
  ```
24
24
 
25
- Layouts go inside `<Page>`:
25
+ A page renders no layout. The layout goes outside the page, above the router, so every page in it shares one frame. See "Composing an app" on `<App>`.
26
26
 
27
27
  ```tsx
28
- import { Page, CenteredLayout } from "shelving/ui";
29
-
30
- <Page title="Sign in">
31
- <CenteredLayout>
32
- <LoginForm/>
33
- </CenteredLayout>
34
- </Page>
28
+ import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
29
+
30
+ <FixedLayout>
31
+ <Scroll vertical cover>
32
+ <Page title="Sign in">
33
+ <Block height="full" middle width="narrow">
34
+ <LoginForm/>
35
+ </Block>
36
+ </Page>
37
+ </Scroll>
38
+ </FixedLayout>
35
39
  ```
@@ -0,0 +1,22 @@
1
+ import { type ReactElement } from "react";
2
+ import type { AbsolutePath } from "../../util/path.js";
3
+ import { type ButtonProps } from "../button/Button.js";
4
+ /**
5
+ * 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`.
6
+ *
7
+ * @see https://shelving.cc/ui/BackButtonProps
8
+ */
9
+ export interface BackButtonProps extends Omit<ButtonProps, "href" | "onClick"> {
10
+ /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). */
11
+ readonly href: AbsolutePath;
12
+ }
13
+ /**
14
+ * Back button for the current stack.
15
+ * - Goes back to the page before this one in the current stack, wherever you came from.
16
+ * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
17
+ * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
18
+ *
19
+ * @kind component
20
+ * @see https://shelving.cc/ui/BackButton
21
+ */
22
+ export declare function BackButton({ href, className, title, children, ...props }: BackButtonProps): ReactElement;
@@ -0,0 +1,19 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { use } from "react";
3
+ import { LeftIcon } from "../../icon/LeftIcon.js";
4
+ import { Button } from "../button/Button.js";
5
+ import { getClass } from "../util/css.js";
6
+ import { NavigationPositionContext } from "./NavigationContext.js";
7
+ /**
8
+ * Back button for the current stack.
9
+ * - Goes back to the page before this one in the current stack, wherever you came from.
10
+ * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
11
+ * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
12
+ *
13
+ * @kind component
14
+ * @see https://shelving.cc/ui/BackButton
15
+ */
16
+ 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 }));
19
+ }
@@ -0,0 +1,47 @@
1
+ # BackButton
2
+
3
+ The back button for a page header. It goes back to the page before this one in the current stack, wherever you came from.
4
+
5
+ **Things to know:**
6
+
7
+ - It goes to the page before this one in the current stack. If you opened a post from a search, it goes back to the search.
8
+ - It goes to `href` when the stack has no page before this one: for example, when the app was opened at this page. So a back button always has somewhere to go. Set `href` to the page's natural parent. On an unstacked page (for example a deep link), it goes to `href` and stays unstacked. 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.
10
+ - Its default content is a `<LeftIcon>` and its default `title` is "Back". Pass `children` and `title` to change them.
11
+ - It takes the usual `<Button>` props, except `onClick`.
12
+ - Without the browser Navigation API, and in a server render, it links to `href`.
13
+ - In a server-rendered app the server always renders `href`, and the browser may render the page before this one. React then warns about a hydration mismatch on the first render. A client-only app (with `<App>`) has no mismatch.
14
+
15
+ ## Usage
16
+
17
+ ```tsx
18
+ import { BackButton } from "shelving/ui";
19
+
20
+ function PostPage({ id }: { id: string }) {
21
+ return (
22
+ <>
23
+ <header>
24
+ <BackButton href="/home"/>
25
+ <h1>Post</h1>
26
+ </header>
27
+ {/* … */}
28
+ </>
29
+ );
30
+ }
31
+ ```
32
+
33
+ With a label:
34
+
35
+ ```tsx
36
+ <BackButton href="/profile">Back to profile</BackButton>
37
+ ```
38
+
39
+ To go back to one fixed page (not to the page before), use a link with `className="back"`:
40
+
41
+ ```tsx
42
+ <Button href="/profile" className="back">Profile</Button>
43
+ ```
44
+
45
+ ## Styling
46
+
47
+ `<BackButton>` renders a `<Button>`, so it has the same styling hooks. See `<Button>`.
@@ -0,0 +1,34 @@
1
+ import { type ReactElement, use } from "react";
2
+ import { LeftIcon } from "../../icon/LeftIcon.js";
3
+ import type { AbsolutePath } from "../../util/path.js";
4
+ import { Button, type ButtonProps } from "../button/Button.js";
5
+ import { getClass } from "../util/css.js";
6
+ import { NavigationPositionContext } from "./NavigationContext.js";
7
+
8
+ /**
9
+ * 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`.
10
+ *
11
+ * @see https://shelving.cc/ui/BackButtonProps
12
+ */
13
+ export interface BackButtonProps extends Omit<ButtonProps, "href" | "onClick"> {
14
+ /** Where to go back to when the current stack has no page before this one (for example, the app was opened at this page). */
15
+ readonly href: AbsolutePath;
16
+ }
17
+
18
+ /**
19
+ * Back button for the current stack.
20
+ * - Goes back to the page before this one in the current stack, wherever you came from.
21
+ * - Goes to `href` when the stack has no page before this one: the app was opened at this page, or the browser has no Navigation API.
22
+ * - It is a plain link with `className="back"`, so it slides back, and it works in a server render and with a middle-click.
23
+ *
24
+ * @kind component
25
+ * @see https://shelving.cc/ui/BackButton
26
+ */
27
+ export function BackButton({ href, className, title = "Back", children = <LeftIcon />, ...props }: BackButtonProps): ReactElement {
28
+ const position = use(NavigationPositionContext);
29
+ return (
30
+ <Button {...props} title={title} href={position?.parent ?? href} className={getClass("back", className)}>
31
+ {children}
32
+ </Button>
33
+ );
34
+ }
@@ -1,27 +1,37 @@
1
1
  import { type ReactElement } from "react";
2
+ import type { AbsolutePath } from "../../util/path.js";
2
3
  import { type PossibleMeta } from "../util/index.js";
3
4
  import type { OptionalChildProps } from "../util/props.js";
4
5
  /**
5
- * Props for `<Navigation>` — initial `Meta` (url/base) plus optional `children`.
6
+ * Props for `<Navigation>`: the initial `Meta` (url, root and stack), the `stacks`, and optional `children`.
6
7
  *
7
8
  * @see https://shelving.cc/ui/NavigationProps
8
9
  */
9
10
  export interface NavigationProps extends PossibleMeta, OptionalChildProps {
11
+ /**
12
+ * Root path of each stack, in tab order, for an app with a tab bar (for example `["/home", "/discover", "/profile"]`).
13
+ * - Each stack keeps its own pages, so each tab remembers where you left it, and a back button goes back within its tab.
14
+ * - With no stacks, the app has one stack at `"/"`, and `stack` in `Meta` is `"/"`.
15
+ */
16
+ readonly stacks?: readonly AbsolutePath[] | undefined;
17
+ /**
18
+ * Stack of the page the app opens at (for example `"/home"`), like `url` and `root`.
19
+ * - Read from this prop, else from the surrounding `<Meta>`, else `"/"`.
20
+ * - Used only when the opening history entry has no saved stack. A reload keeps the stack it had.
21
+ */
22
+ readonly stack?: AbsolutePath | undefined;
10
23
  }
11
24
  /**
12
- * Top-level navigation provider.
13
- * - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
14
- * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls, or `back()` calls for an anchor with a `data-back` attribute.
15
- * - Listens for `popstate` to sync the store with browser back/forward.
16
- * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
17
- * - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
18
- * - Skips the transition when the browser already animated the change (`PopStateEvent.hasUAVisualTransition`, e.g. a swipe-back gesture).
25
+ * Top-level navigation provider, with one stack of pages for each tab.
26
+ * - Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
27
+ * - 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.
28
+ * - Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
29
+ * - 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.
30
+ * - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
19
31
  *
20
- * Exactly one `<Navigation>` per app — nested routers share this single store.
21
- *
22
- * TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
32
+ * Exactly one `<Navigation>` per app. Nested routers share its store.
23
33
  *
24
34
  * @kind component
25
35
  * @see https://shelving.cc/ui/Navigation
26
36
  */
27
- export declare function Navigation({ children, ...meta }: NavigationProps): ReactElement;
37
+ export declare function Navigation({ children, stacks, ...meta }: NavigationProps): ReactElement;
@@ -4,73 +4,89 @@ import { useInstance } from "../../react/useInstance.js";
4
4
  import { MetaContext, requireMeta } from "../misc/MetaContext.js";
5
5
  import { setTransitionType } from "../transition/util.js";
6
6
  import { mergeMeta } from "../util/index.js";
7
- import { NavigationContext } from "./NavigationContext.js";
7
+ import { NavigationContext, NavigationPositionContext } from "./NavigationContext.js";
8
8
  import { NavigationStore } from "./NavigationStore.js";
9
9
  /**
10
- * Top-level navigation provider.
11
- * - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
12
- * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls, or `back()` calls for an anchor with a `data-back` attribute.
13
- * - Listens for `popstate` to sync the store with browser back/forward.
14
- * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
15
- * - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
16
- * - Skips the transition when the browser already animated the change (`PopStateEvent.hasUAVisualTransition`, e.g. a swipe-back gesture).
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.
15
+ * - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
17
16
  *
18
- * Exactly one `<Navigation>` per app — nested routers share this single store.
19
- *
20
- * TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
17
+ * Exactly one `<Navigation>` per app. Nested routers share its store.
21
18
  *
22
19
  * @kind component
23
20
  * @see https://shelving.cc/ui/Navigation
24
21
  */
25
- export function Navigation({ children, ...meta }) {
22
+ export function Navigation({ children, stacks = [], ...meta }) {
26
23
  const current = requireMeta(meta);
27
- const nav = useInstance(NavigationStore, current.url, current.root);
24
+ const nav = useInstance(NavigationStore, current.url, current.root, current.stack ?? "/", ...stacks);
28
25
  // React runs a `<ViewTransition>` only for a transition update, and `useSyncExternalStore()` always renders a sync update.
29
- // So keep the published URL in state and copy each store change into it inside `startTransition()`.
30
- const [url, setURL] = useState(nav.value);
26
+ // So keep the published values in state, and copy each store change into it inside `startTransition()`.
27
+ const [published, setPublished] = useState(() => _getPublished(nav));
31
28
  useEffect(() => {
32
- if (typeof document === "undefined" || typeof window === "undefined")
33
- return;
34
- // Read the transition type the store set for this change, then reset it.
35
- const stop = nav.subscribe(value => {
36
- const t = nav.transition;
37
- nav.transition = "forward";
38
- if (!t)
39
- return setURL(value);
40
- // React renders a transition that starts inside a `popstate` event as a sync update with no view transition, so leave the event first.
41
- setTimeout(() => startTransition(() => {
42
- setTransitionType(t);
43
- setURL(value);
44
- }));
45
- });
46
- const onClick = (e) => {
47
- if (e.target instanceof Element) {
48
- const anchor = e.target.closest("a") ||
49
- (!e.target.closest("button, label") && e.target.closest(".targeted")?.querySelector("a.target[href]"));
50
- if (anchor instanceof HTMLAnchorElement && anchor.origin === window.location.origin && !anchor.hasAttribute("download")) {
51
- e.preventDefault();
52
- if (anchor.hasAttribute("data-back"))
53
- nav.back(anchor.href);
54
- else
55
- nav.forward(anchor.href);
56
- return false; // `return false` stops iOS web app opening every link in a new window.
57
- }
29
+ 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));
58
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
+ });
59
55
  };
60
- const onPopState = (e) => {
61
- const href = window.location.href;
62
- // `"back"` for a `popstate`. `null` means no transition, because the browser already animated the change (e.g. a swipe-back gesture).
63
- if (href !== nav.value.href)
64
- nav.transition = e.hasUAVisualTransition ? null : "back";
65
- nav.value = href;
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
+ const onClick = (e) => {
61
+ if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || !(e.target instanceof Element))
62
+ return;
63
+ const anchor = e.target.closest("a") ||
64
+ (!e.target.closest("button, label") && e.target.closest(".targeted")?.querySelector("a.target[href]"));
65
+ if (!(anchor instanceof HTMLAnchorElement) || anchor.origin !== window.location.origin)
66
+ return;
67
+ if (anchor.hasAttribute("download") || (anchor.target && anchor.target !== "_self"))
68
+ return;
69
+ e.preventDefault();
70
+ const { classList, href } = anchor;
71
+ if (classList.contains("back"))
72
+ nav.back(href);
73
+ else if (classList.contains("replace"))
74
+ nav.replace(href);
75
+ else
76
+ nav.forward(href);
77
+ return false; // `return false` stops iOS web app opening every link in a new window.
66
78
  };
67
79
  document.addEventListener("click", onClick);
68
- window.addEventListener("popstate", onPopState);
69
80
  return () => {
70
81
  document.removeEventListener("click", onClick);
71
- window.removeEventListener("popstate", onPopState);
72
- stop();
82
+ stopURL();
83
+ stopStack();
84
+ stopListening();
73
85
  };
74
86
  }, [nav]);
75
- return (_jsx(NavigationContext, { value: nav, children: _jsx(MetaContext, { value: mergeMeta(current, { url }, Navigation), children: children }) }));
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 }) }) }));
89
+ }
90
+ function _getPublished(nav) {
91
+ return { url: nav.value, stack: nav.stack.value, position: nav.position };
76
92
  }