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
@@ -3,78 +3,141 @@
3
3
  - Kind: component
4
4
  - Import: `import { Navigation } from "shelving/ui";`
5
5
 
6
- Top-level navigation provider.
7
- - Owns a single `NavigationStore` initialised from the surrounding `<Meta>` url/base.
8
- - 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.
9
- - Listens for `popstate` to sync the store with browser back/forward.
10
- - 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).
11
- - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
12
- - Skips the transition when the browser already animated the change (`PopStateEvent.hasUAVisualTransition`, e.g. a swipe-back gesture).
6
+ Top-level navigation provider, with one stack of pages for each tab.
7
+ - Owns a single `NavigationStore` made from the surrounding `<Meta>` url and root.
8
+ - 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.
9
+ - Publishes the URL and the current `stack` into `Meta`, and the position in the stacks into `NavigationPositionContext`, all in one render.
10
+ - 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
+ - Uses the browser Navigation API. Without it (older browsers, server renders) there are no stacks and no transitions.
13
12
 
14
- Exactly one `<Navigation>` per app — nested routers share this single store.
13
+ Exactly one `<Navigation>` per app. Nested routers share its store.
15
14
 
16
- TODO: switch click/popstate handling to the browser Navigation API when broadly supported.
15
+ 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.
17
16
 
18
- The top-level navigation provider for a client-side app. It owns a single `NavigationStore`, publishes the live URL into the `<Meta>` context so descendant `<Router>`s re-render on navigation, and wires up browser history. Use exactly one `<Navigation>` per app — nested routers all share its single store.
17
+ 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.
19
18
 
20
19
  **Things to know:**
21
20
 
22
- - Same-origin anchor clicks are intercepted automatically and turned into `forward()` calls. Add a `download` attribute to an anchor to opt out.
23
- - An anchor with a `data-back` attribute calls `back()` instead, so the page slides back. Set it with the `back` prop on `<Button>` or `<Link>`, e.g. on a "Back to profile" button.
24
- - It listens for `popstate` so the store stays in sync with browser back/forward.
25
- - It publishes each page change inside `startTransition()`, so a `<Transition>` around the routes animates it. A link click, `NavigationStore.forward()` or `NavigationStore.redirect()` sets the `"forward"` transition type. A `data-back` link click, `NavigationStore.back()`, and the browser back or forward button set `"back"` (`popstate` does not say which way it went).
26
- - When the browser already animated the change, for example a swipe-back gesture on a phone, there is no view transition, so the page does not slide twice. The browser says so with `hasUAVisualTransition` on the `popstate` event. Other browsers still slide.
27
- - The `popstate` update waits for the next task (`setTimeout()`). React renders a transition that starts inside `popstate` as a sync update with no view transition.
28
- - It initialises the store from the surrounding `<Meta>` url/base, so set those on an ancestor `<App>` / `<HTML>` / `<Page>`. In the browser the store falls back to `window.location.href` when no url is set.
29
- - The meta it publishes always has a `root` — when none is set anywhere, `root` defaults to the live URL's origin. Setting `root` explicitly on `<App>` / `<HTML>` is still strongly recommended, especially for apps served under a sub-path.
30
- - `<Router>` works with no `<Navigation>` at all (SSR, static rendering, tests) — `<Navigation>` is only what makes the URL *live* on the client.
21
+ - Same-origin link clicks become `NavigationStore.forward()`, so the page slides forward.
22
+ - A link with `className="back"` calls `NavigationStore.back()`, so the page slides back. `<BackButton>` sets this class for you.
23
+ - 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.
24
+ - 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.
25
+ - 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.
26
+ - 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.
27
+ - 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.
28
+ - It publishes `stack` (the root of the current stack) into `<Meta>` beside `url`, so any component can read the current tab with `requireMeta().stack`. With no `stacks`, the app has one stack, and `stack` is `"/"`.
29
+ - 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`.
30
+ - `<Router>` works with no `<Navigation>` (server renders, static renders, tests). `<Navigation>` only makes the URL live on the client.
31
+
32
+ ### Browser support
33
+
34
+ Stacks and slides use the browser [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API). Without it (older browsers, a server render, or a sandboxed frame), `<Navigation>` falls back to plain navigation:
35
+
36
+ - Links still go through the app with no page reload, and the browser back button works.
37
+ - There are no stacks, no slides and no `<RouteCache>`. Each page mounts fresh.
38
+ - `<StackButton>` is a plain link to its stack's root. `<BackButton>` is a plain link to its `href`.
31
39
 
32
40
  ## Usage
33
41
 
42
+ ### Basic setup
43
+
34
44
  ```tsx
35
- import { HTML, Navigation, Router } from "shelving/ui";
45
+ import { App, Navigation, Router } from "shelving/ui";
36
46
 
37
- <HTML url={initialUrl} root="https://example.com/">
47
+ <App root="https://example.com/">
38
48
  <Navigation>
39
49
  <Router routes={ROUTES}/>
40
50
  </Navigation>
41
- </HTML>
51
+ </App>
42
52
  ```
43
53
 
44
- ### Page transitions
54
+ ### App with a tab bar
55
+
56
+ List the root path of each stack in tab order. Put a `<StackButton>` for each stack in the tab bar.
45
57
 
46
58
  ```tsx
47
- import { HorizontalTransition, Navigation, Router } from "shelving/ui";
59
+ import { App, AppLayout, HorizontalTransition, Navigation, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
60
+
61
+ const STACKS = ["/home", "/discover", "/profile"] as const;
62
+
63
+ const TABS = <>
64
+ <StackButton stack="/home">Home</StackButton>
65
+ <StackButton stack="/discover">Discover</StackButton>
66
+ <StackButton stack="/profile">Profile</StackButton>
67
+ </>;
68
+
69
+ <App root="https://example.com/">
70
+ <Navigation stacks={STACKS}>
71
+ <AppLayout nav={TABS}>
72
+ <HorizontalTransition>
73
+ <RouteCache>
74
+ <Scroll vertical cover>
75
+ <PageLoader>
76
+ <Router routes={ROUTES}/>
77
+ </PageLoader>
78
+ </Scroll>
79
+ </RouteCache>
80
+ </HorizontalTransition>
81
+ </AppLayout>
82
+ </Navigation>
83
+ </App>
84
+ ```
48
85
 
49
- // Links slide right. Back links and the browser back button slide left.
50
- <Navigation>
51
- <HorizontalTransition>
52
- <Router routes={ROUTES}/>
53
- </HorizontalTransition>
54
- </Navigation>
86
+ The tab bar is in the layout, outside the cache, so it stays still while pages slide. See "Composing an app" on `<App>` for the full nesting rules.
87
+
88
+ To select a tab when the app starts, pass the starting `stack`. The app decides which stack the opening URL belongs to, for example:
89
+
90
+ ```tsx
91
+ const path = window.location.pathname;
92
+ const stack = STACKS.find(s => path === s || path.startsWith(`${s}/`));
55
93
 
56
- // A "back to" link slides left too.
57
- <Button href="/profile" back>Back to profile</Button>
94
+ <Navigation stacks={STACKS} stack={stack}>
95
+ ```
96
+
97
+ Put the transition **outside** `<RouteCache>`, around the whole cache. Safari (iOS 18) loses the exit animation when each page has its own `<ViewTransition>`.
98
+
99
+ The app opens in the `stack` you set on `<Navigation>` (or on the surrounding `<Meta>`, like `url` and `root`), else in the `/` stack. A page in the `/` stack, such as a deep link or a login page, is **unstacked**: no tab is selected, and links from it stay unstacked until you tap a tab or name a stack (for example `nav.replace("/home", "/home")` after a login). See `NavigationStore`.
100
+
101
+ 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.
102
+
103
+ ### Links
104
+
105
+ ```tsx
106
+ // Opens a new page in the current stack. Slides forward.
107
+ <Button href="/home/post/1">Open post</Button>
108
+
109
+ // Goes back to a page. Slides back.
110
+ // If the page is already in the stack, the stack goes back to it.
111
+ <Button href="/home" className="back">Back to home</Button>
112
+
113
+ // The back button for a page header. Goes to the page before this one in the stack, or to `href`.
114
+ <BackButton href="/home"/>
115
+
116
+ // Changes the URL but keeps the same page. No slide, no new history entry.
117
+ <Button href="/profile/posts" className="replace">Posts</Button>
118
+ <Button href="/profile/likes" className="replace">Likes</Button>
58
119
  ```
59
120
 
60
121
  ### Imperative navigation
61
122
 
62
- Read the navigation store from anywhere in the tree with `requireNavigation()` for imperative URL changes:
123
+ Read the store from anywhere in the tree with `requireNavigation()`:
63
124
 
64
125
  ```tsx
65
126
  import { requireNavigation } from "shelving/ui";
66
127
 
67
128
  const nav = requireNavigation();
68
- nav.forward("/users/123"); // push a new history entry
69
- nav.redirect("/login"); // replace the current history entry
70
- nav.back("/users"); // push a new history entry that slides back
129
+ nav.forward("/home/post/1"); // Open a page in the current stack.
130
+ nav.back("/home"); // Go back to a page.
131
+ nav.replace("/login"); // Change the URL of the current page.
71
132
  ```
72
133
 
134
+ See `NavigationStore` for what each method does.
135
+
73
136
 
74
137
  ## Signatures
75
138
 
76
139
  ```ts
77
- Navigation({ children, ...meta }: NavigationProps): ReactElement
140
+ Navigation({ children, stacks = [], ...meta }: NavigationProps): ReactElement
78
141
  ```
79
142
 
80
143
  ## Parameters
@@ -82,6 +145,8 @@ Navigation({ children, ...meta }: NavigationProps): ReactElement
82
145
  | Param | Type | Description |
83
146
  | --- | --- | --- |
84
147
  | `meta` | `NavigationProps` | |
148
+ | `.stacks` | `readonly AbsolutePath[] \| undefined` | Root path of each stack, in tab order, for an app with a tab bar (for example `["/home", "/discover", "/profile"]`). - Each stack keeps its own pages, so each tab remembers where you left it, and a back button goes back within its tab. - With no stacks, the app has one stack at `"/"`, and `stack` in `Meta` is `"/"`. Read only. Optional. |
149
+ | `.stack` | `AbsolutePath \| undefined` | Stack of the page the app opens at (for example `"/home"`), like `url` and `root`. - Read from this prop, else from the surrounding `<Meta>`, else `"/"`. - Used only when the opening history entry has no saved stack. A reload keeps the stack it had. Read only. Optional. |
85
150
 
86
151
  ## Returns
87
152
 
@@ -0,0 +1,22 @@
1
+ # NavigationEntryState
2
+
3
+ - Kind: interface
4
+ - Import: `import { NavigationEntryState } from "shelving/ui";`
5
+
6
+ State that `NavigationStore` saves on each browser history entry.
7
+
8
+ ## Signatures
9
+
10
+ ```ts
11
+ {
12
+ readonly stack: AbsolutePath;
13
+ readonly depth: number;
14
+ }
15
+ ```
16
+
17
+ ## Properties
18
+
19
+ | Property | Type | Description |
20
+ | --- | --- | --- |
21
+ | `stack` | `AbsolutePath` | Root path of the stack this page is in. Read only. |
22
+ | `depth` | `number` | Position of this page in its stack, where `0` is the root. Read only. |
@@ -0,0 +1,24 @@
1
+ # NavigationPosition
2
+
3
+ - Kind: interface
4
+ - Import: `import { NavigationPosition } from "shelving/ui";`
5
+ - Extends: `NavigationEntryState`
6
+
7
+ Where the app is now in its stacks: the current stack and depth, the top depth of each stack, and the page before the current one.
8
+ - `undefined` when the browser has no Navigation API, or during a server render.
9
+
10
+ ## Signatures
11
+
12
+ ```ts
13
+ {
14
+ readonly tops: { readonly [stack: AbsolutePath]: number };
15
+ readonly parent: AbsolutePath | undefined;
16
+ }
17
+ ```
18
+
19
+ ## Properties
20
+
21
+ | Property | Type | Description |
22
+ | --- | --- | --- |
23
+ | `tops` | `{ readonly [stack: AbsolutePath]: number }` | Depth of the top page of each stack that has pages. Read only. |
24
+ | `parent` | `AbsolutePath \| undefined` | The page before the current one in its stack, or `undefined` at the bottom of the stack. Read only. |
@@ -0,0 +1,8 @@
1
+ # NavigationPositionContext
2
+
3
+ - Kind: constant
4
+ - Import: `import { NavigationPositionContext } from "shelving/ui";`
5
+
6
+ React context holding where the app is in its stacks, published by `<Navigation>` with each URL change.
7
+ - `undefined` without the browser Navigation API, during a server render, or outside `<Navigation>`.
8
+ - `<RouteCache>`, `<Router>` and `<BackButton>` read it, so they change in the same render as the URL.
@@ -4,10 +4,20 @@
4
4
  - Import: `import { NavigationProps } from "shelving/ui";`
5
5
  - Extends: `PossibleMeta`
6
6
 
7
- Props for `<Navigation>` — initial `Meta` (url/base) plus optional `children`.
7
+ Props for `<Navigation>`: the initial `Meta` (url, root and stack), the `stacks`, and optional `children`.
8
8
 
9
9
  ## Signatures
10
10
 
11
11
  ```ts
12
- {}
12
+ {
13
+ readonly stacks?: readonly AbsolutePath[] | undefined;
14
+ readonly stack?: AbsolutePath | undefined;
15
+ }
13
16
  ```
17
+
18
+ ## Properties
19
+
20
+ | Property | Type | Description |
21
+ | --- | --- | --- |
22
+ | `stacks` | `readonly AbsolutePath[] \| undefined` | Root path of each stack, in tab order, for an app with a tab bar (for example `["/home", "/discover", "/profile"]`). - Each stack keeps its own pages, so each tab remembers where you left it, and a back button goes back within its tab. - With no stacks, the app has one stack at `"/"`, and `stack` in `Meta` is `"/"`. Read only. Optional. |
23
+ | `stack` | `AbsolutePath \| undefined` | Stack of the page the app opens at (for example `"/home"`), like `url` and `root`. - Read from this prop, else from the surrounding `<Meta>`, else `"/"`. - Used only when the opening history entry has no saved stack. A reload keeps the stack it had. Read only. Optional. |
@@ -3,12 +3,14 @@
3
3
  - Kind: method
4
4
  - Member of: `NavigationStore`
5
5
 
6
- Navigate back to a URL, pushing a new browser history entry with the `"back"` transition type.
7
- - Use it for a "back to" link, so the page slides back, not forward.
8
- - It does not go back in the browser history, so it also works when the page was opened directly.
6
+ Go back to a URL, as a back button does.
7
+ - The URL is an earlier page in `stack`: go back to it. When it is the entry just before the current one, this goes back in the browser history. Else it pushes the URL again at that page's depth.
8
+ - The URL is the root of `stack`: push it at depth 0.
9
+ - Else push the URL in place of the top page of `stack`.
10
+ - It works when the app was opened at the current page, so a back button always has somewhere to go.
9
11
 
10
12
  ## Signatures
11
13
 
12
14
  ```ts
13
- back(possible: PossibleURL): void
15
+ back(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
14
16
  ```
@@ -3,10 +3,14 @@
3
3
  - Kind: method
4
4
  - Member of: `NavigationStore`
5
5
 
6
- Navigate forward to a URL, pushing a new browser history entry.
6
+ Go forward to a URL, as a link does.
7
+ - The URL is the top page of `stack`: switch to that stack, at the same depth. This is a tab switch.
8
+ - Else push the URL onto `stack`, one level deeper than its top page.
9
+ - The URL you are already on: replace it instead.
10
+ - A change of stack slides by tab order. Else it slides forward.
7
11
 
8
12
  ## Signatures
9
13
 
10
14
  ```ts
11
- forward(possible: PossibleURL): void
15
+ forward(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
12
16
  ```
@@ -0,0 +1,15 @@
1
+ # NavigationStore.history()
2
+
3
+ - Kind: method
4
+ - Member of: `NavigationStore`
5
+
6
+ Get the pages in a stack, root first, or every page in every stack.
7
+ - Read from the browser history entries up to the current one.
8
+ - A stack whose root entry is gone (the browser keeps a limited history) still starts with its root.
9
+ - Without the Navigation API this is always empty.
10
+
11
+ ## Signatures
12
+
13
+ ```ts
14
+ history(stack: AbsolutePath = this.stack.value): AbsolutePath[]
15
+ ```
@@ -0,0 +1,14 @@
1
+ # NavigationStore.listen()
2
+
3
+ - Kind: method
4
+ - Member of: `NavigationStore`
5
+
6
+ Start listening to the browser (back, forward and swipe).
7
+ - Saves the current stack and depth on the current history entry, if it has none.
8
+ - `<Navigation>` calls it once, when it mounts.
9
+
10
+ ## Signatures
11
+
12
+ ```ts
13
+ listen(): () => void
14
+ ```
@@ -0,0 +1,15 @@
1
+ # NavigationStore.replace()
2
+
3
+ - Kind: method
4
+ - Member of: `NavigationStore`
5
+
6
+ Replace the current URL, with no transition.
7
+ - The page stays in the same stack, at the same depth, so a cached page stays mounted.
8
+ - Use it for a page that knows its canonical URL, or for in-page tabs.
9
+ - Pass a `stack` to move the page into that stack: at its root if the URL is the root, else on top of its pages. For example, a login page calls `replace("/home", "/home")`.
10
+
11
+ ## Signatures
12
+
13
+ ```ts
14
+ replace(possible: PossibleURL, stack: AbsolutePath = this.stack.value): void
15
+ ```
@@ -4,46 +4,120 @@
4
4
  - Import: `import { NavigationStore } from "shelving/ui";`
5
5
  - Extends: `URLStore`
6
6
 
7
- Store holding the current navigation URL and driving browser history.
7
+ Store that holds the current navigation URL, drives browser history, and keeps a stack of pages for each tab.
8
8
 
9
- - Extends `URLStore`; the current location is its `value`.
10
- - `forward()` pushes a new history entry; `redirect()` replaces the current one.
11
- - `back()` pushes a new history entry like `forward()`, but `<Navigation>` animates it as a back transition.
12
- - TODO: switch to the browser Navigation API when broadly supported.
9
+ - Extends `URLStore`, so its `value` is the current URL.
10
+ - With the browser Navigation API, each history entry saves a `NavigationEntryState`, and each stack is read from `navigation.entries()` when it is needed. Nothing else is kept.
11
+ - `stack` is a sub-store that holds the root of the current stack. It only changes when the stack changes.
12
+ - Without the Navigation API (older browsers and server renders) there are no stacks: `stack` stays the starting stack, `history()` is empty, and `stack` arguments are ignored.
13
+ - Owned by `<Navigation>`. Read it with `requireNavigation()`.
13
14
 
14
- The store holding the current navigation URL and driving browser history. It extends `URLStore` — the current location is its `value` — and is owned by `<Navigation>`. Reach for it via `requireNavigation()` rather than constructing your own.
15
+ The store that holds the current URL, drives browser history, and keeps one stack of pages for each tab. It extends `URLStore`, so its `value` is the current URL. `<Navigation>` owns it. Read it with `requireNavigation()`, and do not make your own.
15
16
 
16
17
  **Things to know:**
17
18
 
18
- - `forward()` pushes a new browser history entry; `redirect()` replaces the current one. Both resolve the destination against the store's `base`.
19
- - `back()` pushes a new browser history entry like `forward()`, but `<Navigation>` gives it the `"back"` transition type, so the page slides back. It does not go back in the browser history, so it works when the page was opened directly.
20
- - It is a `shelving/store` `URLStore`, so components can subscribe to it for re-renders.
19
+ - `NavigationStore.stacks` is the root path of each stack, in tab order, from the `stacks` prop on `<Navigation>`. With no stacks the app has one stack at `/`.
20
+ - A page that is not in a listed stack is **unstacked**: it is in the `/` stack. See [Unstacked pages](#unstacked-pages).
21
+ - `NavigationStore.stack` is a sub-store that holds the root of the current stack. It is always set: with no stacks it is `"/"`. It changes only when the stack changes, so `useStore(nav.stack)` re-renders only on a tab change.
22
+ - `NavigationStore.history()` returns the pages in the current stack (or a given stack), root first.
23
+ - `NavigationStore.position` is the current stack and depth, the depth of the top page of each stack, and the page before this one. `<RouteCache>` and `<BackButton>` use it.
24
+ - All URLs resolve against the store's `base`. Each method also takes a full same-origin URL.
25
+ - Without the browser Navigation API there is no stack history: `stack` stays the starting stack, `history()` returns `[]`, `position` is `undefined`, and every `stack` argument is ignored. `forward()` and `back()` push a history entry, and `replace()` replaces it.
26
+
27
+ ## Methods
28
+
29
+ | Method | What it does | Slide |
30
+ |---|---|---|
31
+ | `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace. | Forward. Across stacks, by tab order. |
32
+ | `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. | Back |
33
+ | `replace(href, stack?)` | Changes the URL of the current page. The stack, the depth and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages. | None |
34
+ | `history(stack?)` | Returns the pages in `stack`, root first. | — |
35
+
36
+ `stack` defaults to the current stack.
37
+
38
+ ## Unstacked pages
39
+
40
+ A page changes stack only when you say so: with a `<StackButton>`, or with a `stack` argument to `forward()`, `back()` or `replace()`. Links never change stack. The page the app opens at starts in the `stack` set on `<Navigation>` (or the surrounding `<Meta>`), else in the `/` stack. A page in the `/` stack is **unstacked**. For example: a deep link into the app, a fresh open of `/post/9`, or a login page.
41
+
42
+ - On an unstacked page, no `<StackButton>` is selected.
43
+ - Links from an unstacked page push deeper in the `/` stack, even a link to a stack root.
44
+ - To leave the `/` stack, tap a `<StackButton>`, or name the stack.
45
+ - To select a tab when the app starts, set `stack` on `<Navigation>`. The app decides which stack the opening URL belongs to. After a reload, each history entry keeps the stack it had.
46
+ - If you list `/` as one of the `stacks`, it is a normal tab, and unstacked pages open in it.
47
+
48
+ For example, a login page sends the user home after they log in, and names the Home stack:
49
+
50
+ ```tsx
51
+ const nav = requireNavigation();
52
+ nav.replace("/home", "/home");
53
+ ```
54
+
55
+ ## How stacks work
56
+
57
+ The store saves a small state on each browser history entry: the `stack` the page is in, and its `depth` in that stack (`0` is the root). See `NavigationEntryState`. To read a stack, the store walks back through the browser history from the current entry. It takes the newest entry in that stack, then the newest earlier entry with a lower depth, and so on down to depth `0`.
58
+
59
+ Why depth? A browser history entry cannot be changed or removed. So when you go back in one stack while another stack's pages are after it in the history, the store cannot go back in the browser. It pushes a new entry for the page you went back to, at that page's depth. The pages that were above it now have a higher depth than the newest entry, so they are no longer in the stack.
60
+
61
+ For example, with tabs `/home` and `/profile`:
62
+
63
+ | Step | New history entry | Home stack | Profile stack |
64
+ |---|---|---|---|
65
+ | Start at `/home` | `/home` (depth 0) | `/home` | — |
66
+ | Open a post | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | — |
67
+ | Tap the Profile tab | `/profile` (depth 0) | `/home`, `/home/post/1` | `/profile` |
68
+ | Tap the Home tab | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | `/profile` |
69
+ | Tap the back button | `/home` (depth 0) | `/home` | `/profile` |
70
+
71
+ When the page you go back to is the entry just before the current one, `back()` goes back in the browser history and pushes nothing.
72
+
73
+ The browser back and forward buttons walk the history entries one at a time, as usual. Each entry knows its stack and depth, so the stacks are always right and the slide goes the right way.
21
74
 
22
75
  ## Usage
23
76
 
24
77
  ```tsx
25
- import { requireNavigation } from "shelving/ui";
78
+ import { Button, requireNavigation } from "shelving/ui";
26
79
 
27
80
  function LogoutButton() {
28
81
  const nav = requireNavigation();
29
- return <Button onClick={() => nav.redirect("/login")}>Log out</Button>;
82
+ return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
30
83
  }
31
84
  ```
32
85
 
33
- Constructed directly only when wiring navigation by hand (e.g. tests):
86
+ Read the current stack in a component:
87
+
88
+ ```tsx
89
+ import { useStore } from "shelving/react";
90
+ import { requireNavigation } from "shelving/ui";
91
+
92
+ function TabTitle() {
93
+ const nav = requireNavigation();
94
+ const stack = useStore(nav.stack).value;
95
+ return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
96
+ }
97
+ ```
98
+
99
+ List the pages in a stack (for example, for breadcrumbs):
100
+
101
+ ```tsx
102
+ const nav = requireNavigation();
103
+ nav.history("/home"); // ["/home", "/home/post/1", "/home/post/1/comments"]
104
+ ```
105
+
106
+ Make a store by hand only in tests:
34
107
 
35
108
  ```tsx
36
109
  import { NavigationStore } from "shelving/ui";
37
110
 
38
- const nav = new NavigationStore("/");
39
- nav.forward("/home");
111
+ // URL, root, starting stack, then the stacks in tab order.
112
+ const nav = new NavigationStore("https://example.com/home", "https://example.com/", "/home", "/home", "/profile");
113
+ nav.forward("/home/post/1");
40
114
  ```
41
115
 
42
116
 
43
117
  ## Signatures
44
118
 
45
119
  ```ts
46
- new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL)
120
+ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : window.location.href, base?: PossibleURL, stack: AbsolutePath = "/", ...stacks: AbsolutePath[])
47
121
  ```
48
122
 
49
123
  ## Parameters
@@ -52,6 +126,8 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
52
126
  | --- | --- | --- |
53
127
  | `url` | `PossibleURL` | Defaults to `typeof window === "undefined" ? "/" : window.location.href`. |
54
128
  | `base` | `PossibleURL` | Optional. |
129
+ | `stack` | `AbsolutePath` | Defaults to `"/"`. |
130
+ | `stacks` | `AbsolutePath[]` | |
55
131
 
56
132
  ## Returns
57
133
 
@@ -63,10 +139,15 @@ new NavigationStore(url: PossibleURL = typeof window === "undefined" ? "/" : win
63
139
 
64
140
  | Property | Type | Description |
65
141
  | --- | --- | --- |
66
- | `transition` | `TransitionType \| null` | Transition type of the next URL change. `null` means no transition. `<Navigation>` reads it, then sets it back to `"forward"`. Defaults to `"forward"`. |
142
+ | `stacks` | `readonly AbsolutePath[]` | Root path of each stack, in tab order. A single-stack app has one root. Read only. |
143
+ | `stack` | `Store<AbsolutePath>` | Root path of the current stack. - Always set. With no `stacks`, it is `"/"`. - It starts at the `stack` given to the constructor (default `"/"`). Without the Navigation API, it stays there. Read only. |
144
+ | `transition` | `TransitionType \| null` | Transition type of the most recent change, read by `<Navigation>` when the value changes. - `null` means no transition: a replace, a change the browser already animated (for example a swipe-back), or no Navigation API. Defaults to `null`. |
145
+ | `position` | `NavigationPosition \| undefined` | Where the app is now: the current stack and depth, and the top depth of each stack. Read only. |
67
146
 
68
147
  ## Methods
69
148
 
70
- - [NavigationStore.forward()](NavigationStore/forward.md): Navigate forward to a URL, pushing a new browser history entry.
71
- - [NavigationStore.redirect()](NavigationStore/redirect.md): Redirect to a URL, replacing the current browser history entry.
72
- - [NavigationStore.back()](NavigationStore/back.md): Navigate back to a URL, pushing a new browser history entry with the "back" transition type.
149
+ - [NavigationStore.listen()](NavigationStore/listen.md): Start listening to the browser (back, forward and swipe).
150
+ - [NavigationStore.history()](NavigationStore/history.md): Get the pages in a stack, root first, or every page in every stack.
151
+ - [NavigationStore.forward()](NavigationStore/forward.md): Go forward to a URL, as a link does.
152
+ - [NavigationStore.back()](NavigationStore/back.md): Go back to a URL, as a back button does.
153
+ - [NavigationStore.replace()](NavigationStore/replace.md): Replace the current URL, with no transition.
@@ -9,7 +9,7 @@ Variant props for the block-padding (top + bottom) of a component, e.g. `padding
9
9
 
10
10
  ```ts
11
11
  {
12
- padding?: SpaceValue | undefined;
12
+ padding?: Exclude<SpaceValue, "auto"> | undefined;
13
13
  }
14
14
  ```
15
15
 
@@ -17,4 +17,4 @@ Variant props for the block-padding (top + bottom) of a component, e.g. `padding
17
17
 
18
18
  | Property | Type | Description |
19
19
  | --- | --- | --- |
20
- | `padding` | `SpaceValue \| undefined` | Block-padding (top + bottom) of the element. Optional. |
20
+ | `padding` | `Exclude<SpaceValue, "auto"> \| undefined` | Block-padding (top + bottom) of the element. Optional. |
package/docs/ui/Page.md CHANGED
@@ -29,16 +29,20 @@ function UserPage({ id }: { id: string }) {
29
29
  }
30
30
  ```
31
31
 
32
- Layouts go inside `<Page>`:
32
+ 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>`.
33
33
 
34
34
  ```tsx
35
- import { Page, CenteredLayout } from "shelving/ui";
36
-
37
- <Page title="Sign in">
38
- <CenteredLayout>
39
- <LoginForm/>
40
- </CenteredLayout>
41
- </Page>
35
+ import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
36
+
37
+ <FixedLayout>
38
+ <Scroll vertical cover>
39
+ <Page title="Sign in">
40
+ <Block height="full" middle width="narrow">
41
+ <LoginForm/>
42
+ </Block>
43
+ </Page>
44
+ </Scroll>
45
+ </FixedLayout>
42
46
  ```
43
47
 
44
48
 
@@ -7,11 +7,12 @@ Load a page.
7
7
 
8
8
  - Wrapped in `<PageCatcher>` so child components can throw errors.
9
9
  - Wrapped in `<Suspense>` so child components can throw promises.
10
+ - It renders no layout, so its loading state and error page show inside whatever layout is around it.
10
11
 
11
12
  ## Signatures
12
13
 
13
14
  ```ts
14
- PageLoader({ children, fallback = <CenteredLayout>{LOADING}</CenteredLayout> }: LoaderProps): ReactElement
15
+ PageLoader({ children, fallback = PAGE_LOADING }: LoaderProps): ReactElement
15
16
  ```
16
17
 
17
18
  ## Parameters