shelving 1.313.0 → 1.314.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/llms-full.txt +93 -66
- package/docs/ui/RouteCache.md +5 -2
- package/docs/ui/RouteConfig.md +75 -0
- package/docs/ui/RouteConfigProps.md +24 -0
- package/docs/ui/RouteState.md +8 -5
- package/docs/ui/Router.md +1 -1
- package/docs/ui.md +3 -3
- package/package.json +1 -1
- package/ui/router/RouteCache.d.ts +2 -1
- package/ui/router/RouteCache.js +8 -3
- package/ui/router/RouteCache.md +3 -1
- package/ui/router/RouteCache.tsx +7 -3
- package/ui/router/RouteConfig.d.ts +28 -0
- package/ui/router/RouteConfig.js +30 -0
- package/ui/router/RouteConfig.md +42 -0
- package/ui/router/RouteConfig.tsx +44 -0
- package/ui/router/RouteContext.d.ts +6 -4
- package/ui/router/RouteContext.tsx +6 -4
- package/ui/router/Router.d.ts +1 -1
- package/ui/router/Router.js +4 -4
- package/ui/router/Router.tsx +4 -4
- package/ui/router/index.d.ts +1 -1
- package/ui/router/index.js +1 -1
- package/ui/router/index.ts +1 -1
- package/docs/ui/RoutePath.md +0 -56
- package/docs/ui/RoutePathProps.md +0 -22
- package/ui/router/RoutePath.d.ts +0 -24
- package/ui/router/RoutePath.js +0 -21
- package/ui/router/RoutePath.md +0 -26
- package/ui/router/RoutePath.tsx +0 -34
package/docs/llms-full.txt
CHANGED
|
@@ -19656,7 +19656,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
19656
19656
|
- [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
|
|
19657
19657
|
- [Navigation](ui/Navigation.md): Top-level navigation provider.
|
|
19658
19658
|
- [RouteCache](ui/RouteCache.md): Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
|
|
19659
|
-
- [
|
|
19659
|
+
- [RouteConfig](ui/RouteConfig.md): Configure the current page for the surrounding <Router> (and <RouteCache>).
|
|
19660
19660
|
- [Router](ui/Router.md): Match the current URL against routes and render the matched element.
|
|
19661
19661
|
- [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
19662
19662
|
- [Cell](ui/Cell.md): Table cell.
|
|
@@ -19903,8 +19903,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
19903
19903
|
- [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
|
|
19904
19904
|
- [NavigationProps](ui/NavigationProps.md): Props for <Navigation> — initial Meta (url/base) plus optional children.
|
|
19905
19905
|
- [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache> — the maxCached size and the content children to keep alive per URL.
|
|
19906
|
-
- [
|
|
19907
|
-
- [
|
|
19906
|
+
- [RouteConfigProps](ui/RouteConfigProps.md): Props for <RouteConfig> — the settings of a page for the surrounding <Router> and <RouteCache>, and the page content.
|
|
19907
|
+
- [RouteState](ui/RouteState.md): The route state of one page, shared by <Router>, <RouteCache> and <RouteConfig>.
|
|
19908
19908
|
- [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
|
|
19909
19909
|
- [BlockVariants](ui/BlockVariants.md): Variants for block level elements.
|
|
19910
19910
|
- [ColorVariants](ui/ColorVariants.md): Variant props for colouring an element, e.g. color="purple".
|
|
@@ -31683,7 +31683,8 @@ Keep-alive page cache keyed by the current URL — drop it into a layout around
|
|
|
31683
31683
|
pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
|
|
31684
31684
|
entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
|
|
31685
31685
|
- Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
|
|
31686
|
-
- A page that owns other paths with `<
|
|
31686
|
+
- A page that owns other paths with `<RouteConfig path>` stays mounted when the URL changes to one of them.
|
|
31687
|
+
- A page with `<RouteConfig cache={false}>` is dropped as soon as you leave it, so the next visit shows a new page.
|
|
31687
31688
|
- Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
|
|
31688
31689
|
different page per path and a hidden page never re-renders for someone else's URL.
|
|
31689
31690
|
- `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
|
|
@@ -31700,7 +31701,9 @@ Shelving's `<SidebarLayout>` and `<CenteredLayout>` already wrap their scrollabl
|
|
|
31700
31701
|
**Things to know:**
|
|
31701
31702
|
|
|
31702
31703
|
- Pages are kept in a least-recently-used map keyed by `path`. Once `maxCached` pages are retained the least-recently-visited one is unmounted (and loses its state). A never-seen or evicted page mounts fresh at the top.
|
|
31703
|
-
- A page can own other paths with `<
|
|
31704
|
+
- A page can own other paths with `<RouteConfig path>`, for example its tabs (`/dave/{tab}`). A navigation to one of those paths keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide.
|
|
31705
|
+
- A page with `<RouteConfig cache={false}>` is not kept: it unmounts as you leave it, so the next visit starts again. Use it for a form that makes or edits something, so it never shows old input.
|
|
31706
|
+
- The cache key is the path only, not the `?query`. So `/new?from=a` and `/new?from=b` are one page.
|
|
31704
31707
|
- Pass `maxCached={0}` (or less) to disable caching entirely — the page renders directly and unmounts as soon as you leave it.
|
|
31705
31708
|
- `<Activity mode="hidden">` preserves a hidden page's *state* while unmounting its *effects*, so subscriptions, observers (e.g. infinite-scroll), and timers pause and resume cleanly as the page is hidden and shown.
|
|
31706
31709
|
- Each snapshot is frozen under its own `<Meta>` context, so the same single `children` element resolves a different page per path and a hidden page never re-renders for someone else's URL.
|
|
@@ -31742,59 +31745,19 @@ RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
|
|
|
31742
31745
|
|
|
31743
31746
|
---
|
|
31744
31747
|
|
|
31745
|
-
#
|
|
31746
|
-
|
|
31747
|
-
- Kind: interface
|
|
31748
|
-
- Import: `import { RouteState } from "shelving/ui";`
|
|
31749
|
-
|
|
31750
|
-
The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RoutePath>`.
|
|
31751
|
-
- `path` is the template of the paths the page owns, set by `<RoutePath>`.
|
|
31752
|
-
- `cache` is the page's `<RouteCache>` entry, so `<RoutePath>` in a top-level page also tells the cache.
|
|
31753
|
-
- `router` marks a state made by `<Router>`, so a nested router does not pass the cache entry on.
|
|
31754
|
-
|
|
31755
|
-
## Signatures
|
|
31756
|
-
|
|
31757
|
-
```ts
|
|
31758
|
-
{
|
|
31759
|
-
path?: AbsolutePath | undefined;
|
|
31760
|
-
readonly cache?: RouteState | undefined;
|
|
31761
|
-
readonly router?: true | undefined;
|
|
31762
|
-
}
|
|
31763
|
-
```
|
|
31764
|
-
|
|
31765
|
-
## Properties
|
|
31766
|
-
|
|
31767
|
-
| Property | Type | Description |
|
|
31768
|
-
| --- | --- | --- |
|
|
31769
|
-
| `path` | `AbsolutePath \| undefined` | Optional. |
|
|
31770
|
-
| `cache` | `RouteState \| undefined` | Read only. Optional. |
|
|
31771
|
-
| `router` | `true \| undefined` | Read only. Optional. |
|
|
31772
|
-
|
|
31773
|
-
|
|
31774
|
-
---
|
|
31775
|
-
|
|
31776
|
-
# RouteContext
|
|
31777
|
-
|
|
31778
|
-
- Kind: constant
|
|
31779
|
-
- Import: `import { RouteContext } from "shelving/ui";`
|
|
31780
|
-
|
|
31781
|
-
React context holding the `RouteState` of the current page, provided by `<Router>` and `<RouteCache>`.
|
|
31782
|
-
|
|
31783
|
-
|
|
31784
|
-
---
|
|
31785
|
-
|
|
31786
|
-
# RoutePathProps
|
|
31748
|
+
# RouteConfigProps
|
|
31787
31749
|
|
|
31788
31750
|
- Kind: interface
|
|
31789
|
-
- Import: `import {
|
|
31751
|
+
- Import: `import { RouteConfigProps } from "shelving/ui";`
|
|
31790
31752
|
|
|
31791
|
-
Props for `<
|
|
31753
|
+
Props for `<RouteConfig>` — the settings of a page for the surrounding `<Router>` and `<RouteCache>`, and the page content.
|
|
31792
31754
|
|
|
31793
31755
|
## Signatures
|
|
31794
31756
|
|
|
31795
31757
|
```ts
|
|
31796
31758
|
{
|
|
31797
|
-
readonly path
|
|
31759
|
+
readonly path?: AbsolutePath | undefined;
|
|
31760
|
+
readonly cache?: boolean | undefined;
|
|
31798
31761
|
readonly children?: ReactNode;
|
|
31799
31762
|
}
|
|
31800
31763
|
```
|
|
@@ -31803,44 +31766,63 @@ Props for `<RoutePath>` — the path template the page owns, and the page conten
|
|
|
31803
31766
|
|
|
31804
31767
|
| Property | Type | Description |
|
|
31805
31768
|
| --- | --- | --- |
|
|
31806
|
-
| `path` | `AbsolutePath` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. |
|
|
31769
|
+
| `path` | `AbsolutePath \| undefined` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. Optional. |
|
|
31770
|
+
| `cache` | `boolean \| undefined` | Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. Read only. Optional. |
|
|
31807
31771
|
| `children` | `ReactNode` | The page content. Read only. Optional. |
|
|
31808
31772
|
|
|
31809
31773
|
|
|
31810
31774
|
---
|
|
31811
31775
|
|
|
31812
|
-
#
|
|
31776
|
+
# RouteConfig
|
|
31813
31777
|
|
|
31814
31778
|
- Kind: component
|
|
31815
|
-
- Import: `import {
|
|
31779
|
+
- Import: `import { RouteConfig } from "shelving/ui";`
|
|
31816
31780
|
|
|
31817
|
-
|
|
31818
|
-
- A navigation to a path the page owns keeps the same
|
|
31819
|
-
and a `<ViewTransition>` around the page does not run an enter or
|
|
31820
|
-
|
|
31781
|
+
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`).
|
|
31782
|
+
- `path` says the page owns every path that matches a template. A navigation to a path the page owns keeps the same
|
|
31783
|
+
page mounted, so it keeps its scroll and state, and a `<ViewTransition>` around the page does not run an enter or
|
|
31784
|
+
exit. The page updates for the new URL. Use it for a page whose tabs each have their own path: `path="/dave/{tab}"`.
|
|
31821
31785
|
- Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
31786
|
+
- `cache={false}` makes `<RouteCache>` drop the page when you leave it, so the next visit starts again with no old
|
|
31787
|
+
state. Use it for a form that makes or edits something, for example a "New challenge" page.
|
|
31788
|
+
|
|
31789
|
+
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`, if there is one). It has one prop for each setting, so a page wraps itself in one `<RouteConfig>` for all its settings.
|
|
31822
31790
|
|
|
31823
|
-
|
|
31791
|
+
- `path` says the page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
|
|
31792
|
+
- `cache={false}` tells `<RouteCache>` to drop the page when you leave it. The next visit starts again, with no old state. Use it for a form that makes or edits something, so it never shows old input.
|
|
31824
31793
|
|
|
31825
31794
|
**Things to know:**
|
|
31826
31795
|
|
|
31827
|
-
- Without
|
|
31796
|
+
- Without `path`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
|
|
31828
31797
|
- Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
|
|
31829
31798
|
- The page still renders for the new URL, so it reads the tab from the URL as usual.
|
|
31799
|
+
- The cache key is the path only, not the `?query`. A page that reads its `?query` once (for example `/new?from=123`) should use `cache={false}`, so a visit with another `?query` does not show the old page.
|
|
31830
31800
|
- It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
|
|
31831
31801
|
|
|
31832
31802
|
## Usage
|
|
31833
31803
|
|
|
31834
31804
|
```tsx
|
|
31835
|
-
import { Page,
|
|
31805
|
+
import { Page, RouteConfig } from "shelving/ui";
|
|
31836
31806
|
|
|
31807
|
+
// Each tab has its own path, and all of them are the same page.
|
|
31837
31808
|
function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
31838
31809
|
return (
|
|
31839
|
-
<
|
|
31810
|
+
<RouteConfig path={`/${name}/{tab}`}>
|
|
31840
31811
|
<Page title={name}>
|
|
31841
31812
|
<ProfileTabs tab={tab} />
|
|
31842
31813
|
</Page>
|
|
31843
|
-
</
|
|
31814
|
+
</RouteConfig>
|
|
31815
|
+
);
|
|
31816
|
+
}
|
|
31817
|
+
|
|
31818
|
+
// A new form on each visit.
|
|
31819
|
+
function NewChallengePage({ from }: { from?: string }) {
|
|
31820
|
+
return (
|
|
31821
|
+
<RouteConfig cache={false}>
|
|
31822
|
+
<Page title="New challenge">
|
|
31823
|
+
<ChallengeForm from={from} />
|
|
31824
|
+
</Page>
|
|
31825
|
+
</RouteConfig>
|
|
31844
31826
|
);
|
|
31845
31827
|
}
|
|
31846
31828
|
```
|
|
@@ -31849,15 +31831,16 @@ function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
|
31849
31831
|
## Signatures
|
|
31850
31832
|
|
|
31851
31833
|
```ts
|
|
31852
|
-
|
|
31834
|
+
RouteConfig({ path, cache, children }: RouteConfigProps): ReactNode
|
|
31853
31835
|
```
|
|
31854
31836
|
|
|
31855
31837
|
## Parameters
|
|
31856
31838
|
|
|
31857
31839
|
| Param | Type | Description |
|
|
31858
31840
|
| --- | --- | --- |
|
|
31859
|
-
| `props` | `
|
|
31860
|
-
| `.path` | `AbsolutePath` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. |
|
|
31841
|
+
| `props` | `RouteConfigProps` | |
|
|
31842
|
+
| `.path` | `AbsolutePath \| undefined` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. Optional. |
|
|
31843
|
+
| `.cache` | `boolean \| undefined` | Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. Read only. Optional. |
|
|
31861
31844
|
| `.children` | `ReactNode` | The page content. Read only. Optional. |
|
|
31862
31845
|
|
|
31863
31846
|
## Returns
|
|
@@ -31867,6 +31850,50 @@ RoutePath({ path, children }: RoutePathProps): ReactNode
|
|
|
31867
31850
|
| `ReactNode` | |
|
|
31868
31851
|
|
|
31869
31852
|
|
|
31853
|
+
---
|
|
31854
|
+
|
|
31855
|
+
# RouteState
|
|
31856
|
+
|
|
31857
|
+
- Kind: interface
|
|
31858
|
+
- Import: `import { RouteState } from "shelving/ui";`
|
|
31859
|
+
|
|
31860
|
+
The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RouteConfig>`.
|
|
31861
|
+
- `path` is the template of the paths the page owns, set by `<RouteConfig path>`.
|
|
31862
|
+
- `cache` is `false` when `<RouteCache>` drops the page as you leave it, set by `<RouteConfig cache>`.
|
|
31863
|
+
- `entry` is the page's `<RouteCache>` entry, so `<RouteConfig>` in a top-level page also tells the cache.
|
|
31864
|
+
- `router` marks a state made by `<Router>`, so a nested router does not pass the cache entry on.
|
|
31865
|
+
|
|
31866
|
+
## Signatures
|
|
31867
|
+
|
|
31868
|
+
```ts
|
|
31869
|
+
{
|
|
31870
|
+
path?: AbsolutePath | undefined;
|
|
31871
|
+
cache?: boolean | undefined;
|
|
31872
|
+
readonly entry?: RouteState | undefined;
|
|
31873
|
+
readonly router?: true | undefined;
|
|
31874
|
+
}
|
|
31875
|
+
```
|
|
31876
|
+
|
|
31877
|
+
## Properties
|
|
31878
|
+
|
|
31879
|
+
| Property | Type | Description |
|
|
31880
|
+
| --- | --- | --- |
|
|
31881
|
+
| `path` | `AbsolutePath \| undefined` | Optional. |
|
|
31882
|
+
| `cache` | `boolean \| undefined` | Optional. |
|
|
31883
|
+
| `entry` | `RouteState \| undefined` | Read only. Optional. |
|
|
31884
|
+
| `router` | `true \| undefined` | Read only. Optional. |
|
|
31885
|
+
|
|
31886
|
+
|
|
31887
|
+
---
|
|
31888
|
+
|
|
31889
|
+
# RouteContext
|
|
31890
|
+
|
|
31891
|
+
- Kind: constant
|
|
31892
|
+
- Import: `import { RouteContext } from "shelving/ui";`
|
|
31893
|
+
|
|
31894
|
+
React context holding the `RouteState` of the current page, provided by `<Router>` and `<RouteCache>`.
|
|
31895
|
+
|
|
31896
|
+
|
|
31870
31897
|
---
|
|
31871
31898
|
|
|
31872
31899
|
# RouterProps
|
|
@@ -31906,7 +31933,7 @@ Match the current URL against `routes` and render the matched element.
|
|
|
31906
31933
|
- When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
31907
31934
|
- Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
31908
31935
|
- Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
31909
|
-
- Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<
|
|
31936
|
+
- Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RouteConfig path>` stays mounted when the path changes to one of them.
|
|
31910
31937
|
- Returns `null` when there's no URL in context or the URL is outside the base.
|
|
31911
31938
|
|
|
31912
31939
|
A pure URL matcher: it reads the current URL from the surrounding `<Meta>` context, matches it against a `routes` table, and renders the matched element. It has no client requirements, so it works for SSR, static rendering, and tests with no `<Navigation>` at all — wrap it in `<Navigation>` on the client to get live URL updates.
|
package/docs/ui/RouteCache.md
CHANGED
|
@@ -9,7 +9,8 @@ Keep-alive page cache keyed by the current URL — drop it into a layout around
|
|
|
9
9
|
pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
|
|
10
10
|
entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
|
|
11
11
|
- Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
|
|
12
|
-
- A page that owns other paths with `<
|
|
12
|
+
- A page that owns other paths with `<RouteConfig path>` stays mounted when the URL changes to one of them.
|
|
13
|
+
- A page with `<RouteConfig cache={false}>` is dropped as soon as you leave it, so the next visit shows a new page.
|
|
13
14
|
- Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
|
|
14
15
|
different page per path and a hidden page never re-renders for someone else's URL.
|
|
15
16
|
- `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
|
|
@@ -26,7 +27,9 @@ Shelving's `<SidebarLayout>` and `<CenteredLayout>` already wrap their scrollabl
|
|
|
26
27
|
**Things to know:**
|
|
27
28
|
|
|
28
29
|
- Pages are kept in a least-recently-used map keyed by `path`. Once `maxCached` pages are retained the least-recently-visited one is unmounted (and loses its state). A never-seen or evicted page mounts fresh at the top.
|
|
29
|
-
- A page can own other paths with `<
|
|
30
|
+
- A page can own other paths with `<RouteConfig path>`, for example its tabs (`/dave/{tab}`). A navigation to one of those paths keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide.
|
|
31
|
+
- A page with `<RouteConfig cache={false}>` is not kept: it unmounts as you leave it, so the next visit starts again. Use it for a form that makes or edits something, so it never shows old input.
|
|
32
|
+
- The cache key is the path only, not the `?query`. So `/new?from=a` and `/new?from=b` are one page.
|
|
30
33
|
- Pass `maxCached={0}` (or less) to disable caching entirely — the page renders directly and unmounts as soon as you leave it.
|
|
31
34
|
- `<Activity mode="hidden">` preserves a hidden page's *state* while unmounting its *effects*, so subscriptions, observers (e.g. infinite-scroll), and timers pause and resume cleanly as the page is hidden and shown.
|
|
32
35
|
- Each snapshot is frozen under its own `<Meta>` context, so the same single `children` element resolves a different page per path and a hidden page never re-renders for someone else's URL.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# RouteConfig
|
|
2
|
+
|
|
3
|
+
- Kind: component
|
|
4
|
+
- Import: `import { RouteConfig } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`).
|
|
7
|
+
- `path` says the page owns every path that matches a template. A navigation to a path the page owns keeps the same
|
|
8
|
+
page mounted, so it keeps its scroll and state, and a `<ViewTransition>` around the page does not run an enter or
|
|
9
|
+
exit. The page updates for the new URL. Use it for a page whose tabs each have their own path: `path="/dave/{tab}"`.
|
|
10
|
+
- Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
11
|
+
- `cache={false}` makes `<RouteCache>` drop the page when you leave it, so the next visit starts again with no old
|
|
12
|
+
state. Use it for a form that makes or edits something, for example a "New challenge" page.
|
|
13
|
+
|
|
14
|
+
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`, if there is one). It has one prop for each setting, so a page wraps itself in one `<RouteConfig>` for all its settings.
|
|
15
|
+
|
|
16
|
+
- `path` says the page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
|
|
17
|
+
- `cache={false}` tells `<RouteCache>` to drop the page when you leave it. The next visit starts again, with no old state. Use it for a form that makes or edits something, so it never shows old input.
|
|
18
|
+
|
|
19
|
+
**Things to know:**
|
|
20
|
+
|
|
21
|
+
- Without `path`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
|
|
22
|
+
- Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
|
|
23
|
+
- The page still renders for the new URL, so it reads the tab from the URL as usual.
|
|
24
|
+
- The cache key is the path only, not the `?query`. A page that reads its `?query` once (for example `/new?from=123`) should use `cache={false}`, so a visit with another `?query` does not show the old page.
|
|
25
|
+
- It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
import { Page, RouteConfig } from "shelving/ui";
|
|
31
|
+
|
|
32
|
+
// Each tab has its own path, and all of them are the same page.
|
|
33
|
+
function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
34
|
+
return (
|
|
35
|
+
<RouteConfig path={`/${name}/{tab}`}>
|
|
36
|
+
<Page title={name}>
|
|
37
|
+
<ProfileTabs tab={tab} />
|
|
38
|
+
</Page>
|
|
39
|
+
</RouteConfig>
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// A new form on each visit.
|
|
44
|
+
function NewChallengePage({ from }: { from?: string }) {
|
|
45
|
+
return (
|
|
46
|
+
<RouteConfig cache={false}>
|
|
47
|
+
<Page title="New challenge">
|
|
48
|
+
<ChallengeForm from={from} />
|
|
49
|
+
</Page>
|
|
50
|
+
</RouteConfig>
|
|
51
|
+
);
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
## Signatures
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
RouteConfig({ path, cache, children }: RouteConfigProps): ReactNode
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Parameters
|
|
63
|
+
|
|
64
|
+
| Param | Type | Description |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| `props` | `RouteConfigProps` | |
|
|
67
|
+
| `.path` | `AbsolutePath \| undefined` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. Optional. |
|
|
68
|
+
| `.cache` | `boolean \| undefined` | Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. Read only. Optional. |
|
|
69
|
+
| `.children` | `ReactNode` | The page content. Read only. Optional. |
|
|
70
|
+
|
|
71
|
+
## Returns
|
|
72
|
+
|
|
73
|
+
| Type | Description |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `ReactNode` | |
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# RouteConfigProps
|
|
2
|
+
|
|
3
|
+
- Kind: interface
|
|
4
|
+
- Import: `import { RouteConfigProps } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Props for `<RouteConfig>` — the settings of a page for the surrounding `<Router>` and `<RouteCache>`, and the page content.
|
|
7
|
+
|
|
8
|
+
## Signatures
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
{
|
|
12
|
+
readonly path?: AbsolutePath | undefined;
|
|
13
|
+
readonly cache?: boolean | undefined;
|
|
14
|
+
readonly children?: ReactNode;
|
|
15
|
+
}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Properties
|
|
19
|
+
|
|
20
|
+
| Property | Type | Description |
|
|
21
|
+
| --- | --- | --- |
|
|
22
|
+
| `path` | `AbsolutePath \| undefined` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. Optional. |
|
|
23
|
+
| `cache` | `boolean \| undefined` | Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. Read only. Optional. |
|
|
24
|
+
| `children` | `ReactNode` | The page content. Read only. Optional. |
|
package/docs/ui/RouteState.md
CHANGED
|
@@ -3,9 +3,10 @@
|
|
|
3
3
|
- Kind: interface
|
|
4
4
|
- Import: `import { RouteState } from "shelving/ui";`
|
|
5
5
|
|
|
6
|
-
The route state of one page, shared by `<Router>`, `<RouteCache>` and `<
|
|
7
|
-
- `path` is the template of the paths the page owns, set by `<
|
|
8
|
-
- `cache` is
|
|
6
|
+
The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RouteConfig>`.
|
|
7
|
+
- `path` is the template of the paths the page owns, set by `<RouteConfig path>`.
|
|
8
|
+
- `cache` is `false` when `<RouteCache>` drops the page as you leave it, set by `<RouteConfig cache>`.
|
|
9
|
+
- `entry` is the page's `<RouteCache>` entry, so `<RouteConfig>` in a top-level page also tells the cache.
|
|
9
10
|
- `router` marks a state made by `<Router>`, so a nested router does not pass the cache entry on.
|
|
10
11
|
|
|
11
12
|
## Signatures
|
|
@@ -13,7 +14,8 @@ The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RoutePat
|
|
|
13
14
|
```ts
|
|
14
15
|
{
|
|
15
16
|
path?: AbsolutePath | undefined;
|
|
16
|
-
|
|
17
|
+
cache?: boolean | undefined;
|
|
18
|
+
readonly entry?: RouteState | undefined;
|
|
17
19
|
readonly router?: true | undefined;
|
|
18
20
|
}
|
|
19
21
|
```
|
|
@@ -23,5 +25,6 @@ The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RoutePat
|
|
|
23
25
|
| Property | Type | Description |
|
|
24
26
|
| --- | --- | --- |
|
|
25
27
|
| `path` | `AbsolutePath \| undefined` | Optional. |
|
|
26
|
-
| `cache` | `
|
|
28
|
+
| `cache` | `boolean \| undefined` | Optional. |
|
|
29
|
+
| `entry` | `RouteState \| undefined` | Read only. Optional. |
|
|
27
30
|
| `router` | `true \| undefined` | Read only. Optional. |
|
package/docs/ui/Router.md
CHANGED
|
@@ -8,7 +8,7 @@ Match the current URL against `routes` and render the matched element.
|
|
|
8
8
|
- When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
9
9
|
- Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
10
10
|
- Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
11
|
-
- Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<
|
|
11
|
+
- Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RouteConfig path>` stays mounted when the path changes to one of them.
|
|
12
12
|
- Returns `null` when there's no URL in context or the URL is outside the base.
|
|
13
13
|
|
|
14
14
|
A pure URL matcher: it reads the current URL from the surrounding `<Meta>` context, matches it against a `routes` table, and renders the matched element. It has no client requirements, so it works for SSR, static rendering, and tests with no `<Navigation>` at all — wrap it in `<Navigation>` on the client to get live URL updates.
|
package/docs/ui.md
CHANGED
|
@@ -191,7 +191,7 @@ The components below are listed in the index following this page; this is the sh
|
|
|
191
191
|
- [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
|
|
192
192
|
- [Navigation](ui/Navigation.md): Top-level navigation provider.
|
|
193
193
|
- [RouteCache](ui/RouteCache.md): Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
|
|
194
|
-
- [
|
|
194
|
+
- [RouteConfig](ui/RouteConfig.md): Configure the current page for the surrounding <Router> (and <RouteCache>).
|
|
195
195
|
- [Router](ui/Router.md): Match the current URL against routes and render the matched element.
|
|
196
196
|
- [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
|
|
197
197
|
- [Cell](ui/Cell.md): Table cell.
|
|
@@ -438,8 +438,8 @@ The components below are listed in the index following this page; this is the sh
|
|
|
438
438
|
- [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
|
|
439
439
|
- [NavigationProps](ui/NavigationProps.md): Props for <Navigation> — initial Meta (url/base) plus optional children.
|
|
440
440
|
- [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache> — the maxCached size and the content children to keep alive per URL.
|
|
441
|
-
- [
|
|
442
|
-
- [
|
|
441
|
+
- [RouteConfigProps](ui/RouteConfigProps.md): Props for <RouteConfig> — the settings of a page for the surrounding <Router> and <RouteCache>, and the page content.
|
|
442
|
+
- [RouteState](ui/RouteState.md): The route state of one page, shared by <Router>, <RouteCache> and <RouteConfig>.
|
|
443
443
|
- [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
|
|
444
444
|
- [BlockVariants](ui/BlockVariants.md): Variants for block level elements.
|
|
445
445
|
- [ColorVariants](ui/ColorVariants.md): Variant props for colouring an element, e.g. color="purple".
|
package/package.json
CHANGED
|
@@ -23,7 +23,8 @@ export interface RouteCacheProps {
|
|
|
23
23
|
* pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
|
|
24
24
|
* entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
|
|
25
25
|
* - Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
|
|
26
|
-
* - A page that owns other paths with `<
|
|
26
|
+
* - A page that owns other paths with `<RouteConfig path>` stays mounted when the URL changes to one of them.
|
|
27
|
+
* - A page with `<RouteConfig cache={false}>` is dropped as soon as you leave it, so the next visit shows a new page.
|
|
27
28
|
* - Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
|
|
28
29
|
* different page per path and a hidden page never re-renders for someone else's URL.
|
|
29
30
|
* - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
|
package/ui/router/RouteCache.js
CHANGED
|
@@ -10,7 +10,8 @@ import { RouteContext } from "./RouteContext.js";
|
|
|
10
10
|
* pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
|
|
11
11
|
* entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
|
|
12
12
|
* - Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
|
|
13
|
-
* - A page that owns other paths with `<
|
|
13
|
+
* - A page that owns other paths with `<RouteConfig path>` stays mounted when the URL changes to one of them.
|
|
14
|
+
* - A page with `<RouteConfig cache={false}>` is dropped as soon as you leave it, so the next visit shows a new page.
|
|
14
15
|
* - Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
|
|
15
16
|
* different page per path and a hidden page never re-renders for someone else's URL.
|
|
16
17
|
* - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
|
|
@@ -31,7 +32,7 @@ export function RouteCache({ maxCached = 10, children }) {
|
|
|
31
32
|
// Caching disabled — render the page directly so it unmounts as soon as you leave it.
|
|
32
33
|
if (maxCached <= 0)
|
|
33
34
|
return _jsx(MetaContext, { value: meta, children: children });
|
|
34
|
-
// Find the page for this path: its own entry, else the most recent page that owns the path with `<
|
|
35
|
+
// Find the page for this path: its own entry, else the most recent page that owns the path with `<RouteConfig path>`.
|
|
35
36
|
const map = (mapRef.current ??= new Map());
|
|
36
37
|
const key = map.has(meta.path) ? meta.path : (_findOwner(map, meta.path) ?? meta.path);
|
|
37
38
|
const entry = map.get(key) ?? { node: null, used: 0, state: {} };
|
|
@@ -40,13 +41,17 @@ export function RouteCache({ maxCached = 10, children }) {
|
|
|
40
41
|
// it was captured at — the same `children` element resolves a different page per path.
|
|
41
42
|
entry.node = (_jsx(RouteContext, { value: entry.state, children: _jsx(MetaContext, { value: meta, children: children }) }));
|
|
42
43
|
entry.used = ++usedRef.current;
|
|
44
|
+
// Drop the pages that ask not to be cached (`<RouteConfig cache={false}>`) once they are not the current page.
|
|
45
|
+
for (const [k, { state }] of map)
|
|
46
|
+
if (k !== key && state.cache === false)
|
|
47
|
+
map.delete(k);
|
|
43
48
|
// Evict the least-recently-used pages beyond the limit.
|
|
44
49
|
while (map.size > maxCached)
|
|
45
50
|
map.delete(_findLeastRecentlyUsed(map));
|
|
46
51
|
// Render every cached page; only the current one is visible, the rest are kept alive but hidden.
|
|
47
52
|
return Array.from(map, ([k, cached]) => (_jsx(Activity, { mode: k === key ? "visible" : "hidden", children: cached.node }, k)));
|
|
48
53
|
}
|
|
49
|
-
/** Find the key of the most-recently-used entry whose `<
|
|
54
|
+
/** Find the key of the most-recently-used entry whose `<RouteConfig path>` owns a path, or `undefined` if none does. */
|
|
50
55
|
function _findOwner(map, path) {
|
|
51
56
|
let ownerKey;
|
|
52
57
|
let ownerUsed = Number.NEGATIVE_INFINITY;
|
package/ui/router/RouteCache.md
CHANGED
|
@@ -7,7 +7,9 @@ Shelving's `<SidebarLayout>` and `<CenteredLayout>` already wrap their scrollabl
|
|
|
7
7
|
**Things to know:**
|
|
8
8
|
|
|
9
9
|
- Pages are kept in a least-recently-used map keyed by `path`. Once `maxCached` pages are retained the least-recently-visited one is unmounted (and loses its state). A never-seen or evicted page mounts fresh at the top.
|
|
10
|
-
- A page can own other paths with `<
|
|
10
|
+
- A page can own other paths with `<RouteConfig path>`, for example its tabs (`/dave/{tab}`). A navigation to one of those paths keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide.
|
|
11
|
+
- A page with `<RouteConfig cache={false}>` is not kept: it unmounts as you leave it, so the next visit starts again. Use it for a form that makes or edits something, so it never shows old input.
|
|
12
|
+
- The cache key is the path only, not the `?query`. So `/new?from=a` and `/new?from=b` are one page.
|
|
11
13
|
- Pass `maxCached={0}` (or less) to disable caching entirely — the page renders directly and unmounts as soon as you leave it.
|
|
12
14
|
- `<Activity mode="hidden">` preserves a hidden page's *state* while unmounting its *effects*, so subscriptions, observers (e.g. infinite-scroll), and timers pause and resume cleanly as the page is hidden and shown.
|
|
13
15
|
- Each snapshot is frozen under its own `<Meta>` context, so the same single `children` element resolves a different page per path and a hidden page never re-renders for someone else's URL.
|
package/ui/router/RouteCache.tsx
CHANGED
|
@@ -36,7 +36,8 @@ export interface RouteCacheProps {
|
|
|
36
36
|
* pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
|
|
37
37
|
* entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
|
|
38
38
|
* - Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
|
|
39
|
-
* - A page that owns other paths with `<
|
|
39
|
+
* - A page that owns other paths with `<RouteConfig path>` stays mounted when the URL changes to one of them.
|
|
40
|
+
* - A page with `<RouteConfig cache={false}>` is dropped as soon as you leave it, so the next visit shows a new page.
|
|
40
41
|
* - Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
|
|
41
42
|
* different page per path and a hidden page never re-renders for someone else's URL.
|
|
42
43
|
* - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
|
|
@@ -58,7 +59,7 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
|
|
|
58
59
|
// Caching disabled — render the page directly so it unmounts as soon as you leave it.
|
|
59
60
|
if (maxCached <= 0) return <MetaContext value={meta}>{children}</MetaContext>;
|
|
60
61
|
|
|
61
|
-
// Find the page for this path: its own entry, else the most recent page that owns the path with `<
|
|
62
|
+
// Find the page for this path: its own entry, else the most recent page that owns the path with `<RouteConfig path>`.
|
|
62
63
|
const map = (mapRef.current ??= new Map());
|
|
63
64
|
const key = map.has(meta.path) ? meta.path : (_findOwner(map, meta.path) ?? meta.path);
|
|
64
65
|
const entry = map.get(key) ?? { node: null, used: 0, state: {} };
|
|
@@ -73,6 +74,9 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
|
|
|
73
74
|
);
|
|
74
75
|
entry.used = ++usedRef.current;
|
|
75
76
|
|
|
77
|
+
// Drop the pages that ask not to be cached (`<RouteConfig cache={false}>`) once they are not the current page.
|
|
78
|
+
for (const [k, { state }] of map) if (k !== key && state.cache === false) map.delete(k);
|
|
79
|
+
|
|
76
80
|
// Evict the least-recently-used pages beyond the limit.
|
|
77
81
|
while (map.size > maxCached) map.delete(_findLeastRecentlyUsed(map));
|
|
78
82
|
|
|
@@ -84,7 +88,7 @@ export function RouteCache({ maxCached = 10, children }: RouteCacheProps): React
|
|
|
84
88
|
));
|
|
85
89
|
}
|
|
86
90
|
|
|
87
|
-
/** Find the key of the most-recently-used entry whose `<
|
|
91
|
+
/** Find the key of the most-recently-used entry whose `<RouteConfig path>` owns a path, or `undefined` if none does. */
|
|
88
92
|
function _findOwner(map: Map<AbsolutePath, CacheEntry>, path: AbsolutePath): AbsolutePath | undefined {
|
|
89
93
|
let ownerKey: AbsolutePath | undefined;
|
|
90
94
|
let ownerUsed = Number.NEGATIVE_INFINITY;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { type ReactNode } from "react";
|
|
2
|
+
import type { AbsolutePath } from "../../util/path.js";
|
|
3
|
+
/**
|
|
4
|
+
* Props for `<RouteConfig>` — the settings of a page for the surrounding `<Router>` and `<RouteCache>`, and the page content.
|
|
5
|
+
*
|
|
6
|
+
* @see https://shelving.cc/ui/RouteConfigProps
|
|
7
|
+
*/
|
|
8
|
+
export interface RouteConfigProps {
|
|
9
|
+
/** Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. */
|
|
10
|
+
readonly path?: AbsolutePath | undefined;
|
|
11
|
+
/** Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. */
|
|
12
|
+
readonly cache?: boolean | undefined;
|
|
13
|
+
/** The page content. */
|
|
14
|
+
readonly children?: ReactNode;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Configure the current page for the surrounding `<Router>` (and `<RouteCache>`).
|
|
18
|
+
* - `path` says the page owns every path that matches a template. A navigation to a path the page owns keeps the same
|
|
19
|
+
* page mounted, so it keeps its scroll and state, and a `<ViewTransition>` around the page does not run an enter or
|
|
20
|
+
* exit. The page updates for the new URL. Use it for a page whose tabs each have their own path: `path="/dave/{tab}"`.
|
|
21
|
+
* - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
22
|
+
* - `cache={false}` makes `<RouteCache>` drop the page when you leave it, so the next visit starts again with no old
|
|
23
|
+
* state. Use it for a form that makes or edits something, for example a "New challenge" page.
|
|
24
|
+
*
|
|
25
|
+
* @kind component
|
|
26
|
+
* @see https://shelving.cc/ui/RouteConfig
|
|
27
|
+
*/
|
|
28
|
+
export declare function RouteConfig({ path, cache, children }: RouteConfigProps): ReactNode;
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { use } from "react";
|
|
2
|
+
import { RouteContext } from "./RouteContext.js";
|
|
3
|
+
/**
|
|
4
|
+
* Configure the current page for the surrounding `<Router>` (and `<RouteCache>`).
|
|
5
|
+
* - `path` says the page owns every path that matches a template. A navigation to a path the page owns keeps the same
|
|
6
|
+
* page mounted, so it keeps its scroll and state, and a `<ViewTransition>` around the page does not run an enter or
|
|
7
|
+
* exit. The page updates for the new URL. Use it for a page whose tabs each have their own path: `path="/dave/{tab}"`.
|
|
8
|
+
* - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
9
|
+
* - `cache={false}` makes `<RouteCache>` drop the page when you leave it, so the next visit starts again with no old
|
|
10
|
+
* state. Use it for a form that makes or edits something, for example a "New challenge" page.
|
|
11
|
+
*
|
|
12
|
+
* @kind component
|
|
13
|
+
* @see https://shelving.cc/ui/RouteConfig
|
|
14
|
+
*/
|
|
15
|
+
export function RouteConfig({ path, cache, children }) {
|
|
16
|
+
const state = use(RouteContext);
|
|
17
|
+
if (state) {
|
|
18
|
+
_configure(state, path, cache);
|
|
19
|
+
if (state.entry)
|
|
20
|
+
_configure(state.entry, path, cache);
|
|
21
|
+
}
|
|
22
|
+
return children;
|
|
23
|
+
}
|
|
24
|
+
/** Set the given settings on a page's route state. */
|
|
25
|
+
function _configure(state, path, cache) {
|
|
26
|
+
if (path !== undefined)
|
|
27
|
+
state.path = path;
|
|
28
|
+
if (cache !== undefined)
|
|
29
|
+
state.cache = cache;
|
|
30
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# RouteConfig
|
|
2
|
+
|
|
3
|
+
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`, if there is one). It has one prop for each setting, so a page wraps itself in one `<RouteConfig>` for all its settings.
|
|
4
|
+
|
|
5
|
+
- `path` says the page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
|
|
6
|
+
- `cache={false}` tells `<RouteCache>` to drop the page when you leave it. The next visit starts again, with no old state. Use it for a form that makes or edits something, so it never shows old input.
|
|
7
|
+
|
|
8
|
+
**Things to know:**
|
|
9
|
+
|
|
10
|
+
- Without `path`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
|
|
11
|
+
- Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
|
|
12
|
+
- The page still renders for the new URL, so it reads the tab from the URL as usual.
|
|
13
|
+
- The cache key is the path only, not the `?query`. A page that reads its `?query` once (for example `/new?from=123`) should use `cache={false}`, so a visit with another `?query` does not show the old page.
|
|
14
|
+
- It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
```tsx
|
|
19
|
+
import { Page, RouteConfig } from "shelving/ui";
|
|
20
|
+
|
|
21
|
+
// Each tab has its own path, and all of them are the same page.
|
|
22
|
+
function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
23
|
+
return (
|
|
24
|
+
<RouteConfig path={`/${name}/{tab}`}>
|
|
25
|
+
<Page title={name}>
|
|
26
|
+
<ProfileTabs tab={tab} />
|
|
27
|
+
</Page>
|
|
28
|
+
</RouteConfig>
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
// A new form on each visit.
|
|
33
|
+
function NewChallengePage({ from }: { from?: string }) {
|
|
34
|
+
return (
|
|
35
|
+
<RouteConfig cache={false}>
|
|
36
|
+
<Page title="New challenge">
|
|
37
|
+
<ChallengeForm from={from} />
|
|
38
|
+
</Page>
|
|
39
|
+
</RouteConfig>
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
```
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { type ReactNode, use } from "react";
|
|
2
|
+
import type { AbsolutePath } from "../../util/path.js";
|
|
3
|
+
import { RouteContext, type RouteState } from "./RouteContext.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Props for `<RouteConfig>` — the settings of a page for the surrounding `<Router>` and `<RouteCache>`, and the page content.
|
|
7
|
+
*
|
|
8
|
+
* @see https://shelving.cc/ui/RouteConfigProps
|
|
9
|
+
*/
|
|
10
|
+
export interface RouteConfigProps {
|
|
11
|
+
/** Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. */
|
|
12
|
+
readonly path?: AbsolutePath | undefined;
|
|
13
|
+
/** Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. */
|
|
14
|
+
readonly cache?: boolean | undefined;
|
|
15
|
+
/** The page content. */
|
|
16
|
+
readonly children?: ReactNode;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Configure the current page for the surrounding `<Router>` (and `<RouteCache>`).
|
|
21
|
+
* - `path` says the page owns every path that matches a template. A navigation to a path the page owns keeps the same
|
|
22
|
+
* page mounted, so it keeps its scroll and state, and a `<ViewTransition>` around the page does not run an enter or
|
|
23
|
+
* exit. The page updates for the new URL. Use it for a page whose tabs each have their own path: `path="/dave/{tab}"`.
|
|
24
|
+
* - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
25
|
+
* - `cache={false}` makes `<RouteCache>` drop the page when you leave it, so the next visit starts again with no old
|
|
26
|
+
* state. Use it for a form that makes or edits something, for example a "New challenge" page.
|
|
27
|
+
*
|
|
28
|
+
* @kind component
|
|
29
|
+
* @see https://shelving.cc/ui/RouteConfig
|
|
30
|
+
*/
|
|
31
|
+
export function RouteConfig({ path, cache, children }: RouteConfigProps): ReactNode {
|
|
32
|
+
const state = use(RouteContext);
|
|
33
|
+
if (state) {
|
|
34
|
+
_configure(state, path, cache);
|
|
35
|
+
if (state.entry) _configure(state.entry, path, cache);
|
|
36
|
+
}
|
|
37
|
+
return children;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Set the given settings on a page's route state. */
|
|
41
|
+
function _configure(state: RouteState, path: AbsolutePath | undefined, cache: boolean | undefined): void {
|
|
42
|
+
if (path !== undefined) state.path = path;
|
|
43
|
+
if (cache !== undefined) state.cache = cache;
|
|
44
|
+
}
|
|
@@ -1,15 +1,17 @@
|
|
|
1
1
|
import type { AbsolutePath } from "../../util/path.js";
|
|
2
2
|
/**
|
|
3
|
-
* The route state of one page, shared by `<Router>`, `<RouteCache>` and `<
|
|
4
|
-
* - `path` is the template of the paths the page owns, set by `<
|
|
5
|
-
* - `cache` is
|
|
3
|
+
* The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RouteConfig>`.
|
|
4
|
+
* - `path` is the template of the paths the page owns, set by `<RouteConfig path>`.
|
|
5
|
+
* - `cache` is `false` when `<RouteCache>` drops the page as you leave it, set by `<RouteConfig cache>`.
|
|
6
|
+
* - `entry` is the page's `<RouteCache>` entry, so `<RouteConfig>` in a top-level page also tells the cache.
|
|
6
7
|
* - `router` marks a state made by `<Router>`, so a nested router does not pass the cache entry on.
|
|
7
8
|
*
|
|
8
9
|
* @see https://shelving.cc/ui/RouteState
|
|
9
10
|
*/
|
|
10
11
|
export interface RouteState {
|
|
11
12
|
path?: AbsolutePath | undefined;
|
|
12
|
-
|
|
13
|
+
cache?: boolean | undefined;
|
|
14
|
+
readonly entry?: RouteState | undefined;
|
|
13
15
|
readonly router?: true | undefined;
|
|
14
16
|
}
|
|
15
17
|
/**
|
|
@@ -2,16 +2,18 @@ import { createContext } from "react";
|
|
|
2
2
|
import type { AbsolutePath } from "../../util/path.js";
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
|
-
* The route state of one page, shared by `<Router>`, `<RouteCache>` and `<
|
|
6
|
-
* - `path` is the template of the paths the page owns, set by `<
|
|
7
|
-
* - `cache` is
|
|
5
|
+
* The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RouteConfig>`.
|
|
6
|
+
* - `path` is the template of the paths the page owns, set by `<RouteConfig path>`.
|
|
7
|
+
* - `cache` is `false` when `<RouteCache>` drops the page as you leave it, set by `<RouteConfig cache>`.
|
|
8
|
+
* - `entry` is the page's `<RouteCache>` entry, so `<RouteConfig>` in a top-level page also tells the cache.
|
|
8
9
|
* - `router` marks a state made by `<Router>`, so a nested router does not pass the cache entry on.
|
|
9
10
|
*
|
|
10
11
|
* @see https://shelving.cc/ui/RouteState
|
|
11
12
|
*/
|
|
12
13
|
export interface RouteState {
|
|
13
14
|
path?: AbsolutePath | undefined;
|
|
14
|
-
|
|
15
|
+
cache?: boolean | undefined;
|
|
16
|
+
readonly entry?: RouteState | undefined;
|
|
15
17
|
readonly router?: true | undefined;
|
|
16
18
|
}
|
|
17
19
|
|
package/ui/router/Router.d.ts
CHANGED
|
@@ -21,7 +21,7 @@ export interface RouterProps extends PossibleMeta {
|
|
|
21
21
|
* - When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
22
22
|
* - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
23
23
|
* - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
24
|
-
* - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<
|
|
24
|
+
* - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RouteConfig path>` stays mounted when the path changes to one of them.
|
|
25
25
|
* - Returns `null` when there's no URL in context or the URL is outside the base.
|
|
26
26
|
*
|
|
27
27
|
* @kind component
|
package/ui/router/Router.js
CHANGED
|
@@ -12,7 +12,7 @@ import { RouteContext } from "./RouteContext.js";
|
|
|
12
12
|
* - When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
13
13
|
* - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
14
14
|
* - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
15
|
-
* - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<
|
|
15
|
+
* - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RouteConfig path>` stays mounted when the path changes to one of them.
|
|
16
16
|
* - Returns `null` when there's no URL in context or the URL is outside the base.
|
|
17
17
|
*
|
|
18
18
|
* @kind component
|
|
@@ -22,14 +22,14 @@ import { RouteContext } from "./RouteContext.js";
|
|
|
22
22
|
export function Router({ routes, fallback, ...meta }) {
|
|
23
23
|
const combined = requireMetaURL(meta);
|
|
24
24
|
const path = combined;
|
|
25
|
-
// Keep the current page when it owns the new path with `<
|
|
26
|
-
// The top-level router passes the `<RouteCache>` entry on, so `<
|
|
25
|
+
// Keep the current page when it owns the new path with `<RouteConfig path>`, else start a new page for this path.
|
|
26
|
+
// The top-level router passes the `<RouteCache>` entry on, so `<RouteConfig>` in its page also tells the cache.
|
|
27
27
|
const parent = use(RouteContext);
|
|
28
28
|
const pageRef = useRef(undefined);
|
|
29
29
|
const prev = pageRef.current;
|
|
30
30
|
const page = prev && (prev.key === combined.path || (prev.state.path && matchPathTemplate(prev.state.path, combined.path)))
|
|
31
31
|
? prev
|
|
32
|
-
: { key: combined.path, state: { router: true,
|
|
32
|
+
: { key: combined.path, state: { router: true, entry: parent?.router ? undefined : parent } };
|
|
33
33
|
pageRef.current = page;
|
|
34
34
|
const route = _matchRoute(routes, fallback, combined, page.key);
|
|
35
35
|
if (route)
|
package/ui/router/Router.tsx
CHANGED
|
@@ -30,7 +30,7 @@ export interface RouterProps extends PossibleMeta {
|
|
|
30
30
|
* - When `base` is set, the effective path is the URL after stripping the base prefix.
|
|
31
31
|
* - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
|
|
32
32
|
* - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
|
|
33
|
-
* - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<
|
|
33
|
+
* - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RouteConfig path>` stays mounted when the path changes to one of them.
|
|
34
34
|
* - Returns `null` when there's no URL in context or the URL is outside the base.
|
|
35
35
|
*
|
|
36
36
|
* @kind component
|
|
@@ -41,15 +41,15 @@ export function Router({ routes, fallback, ...meta }: RouterProps): ReactElement
|
|
|
41
41
|
const combined = requireMetaURL(meta);
|
|
42
42
|
const path = combined;
|
|
43
43
|
|
|
44
|
-
// Keep the current page when it owns the new path with `<
|
|
45
|
-
// The top-level router passes the `<RouteCache>` entry on, so `<
|
|
44
|
+
// Keep the current page when it owns the new path with `<RouteConfig path>`, else start a new page for this path.
|
|
45
|
+
// The top-level router passes the `<RouteCache>` entry on, so `<RouteConfig>` in its page also tells the cache.
|
|
46
46
|
const parent = use(RouteContext);
|
|
47
47
|
const pageRef = useRef<{ key: string; state: RouteState }>(undefined);
|
|
48
48
|
const prev = pageRef.current;
|
|
49
49
|
const page =
|
|
50
50
|
prev && (prev.key === combined.path || (prev.state.path && matchPathTemplate(prev.state.path, combined.path)))
|
|
51
51
|
? prev
|
|
52
|
-
: { key: combined.path, state: { router: true,
|
|
52
|
+
: { key: combined.path, state: { router: true, entry: parent?.router ? undefined : parent } as RouteState };
|
|
53
53
|
pageRef.current = page;
|
|
54
54
|
|
|
55
55
|
const route = _matchRoute(routes, fallback, combined, page.key);
|
package/ui/router/index.d.ts
CHANGED
|
@@ -2,7 +2,7 @@ export * from "./Navigation.js";
|
|
|
2
2
|
export * from "./NavigationContext.js";
|
|
3
3
|
export * from "./NavigationStore.js";
|
|
4
4
|
export * from "./RouteCache.js";
|
|
5
|
+
export * from "./RouteConfig.js";
|
|
5
6
|
export * from "./RouteContext.js";
|
|
6
|
-
export * from "./RoutePath.js";
|
|
7
7
|
export * from "./Router.js";
|
|
8
8
|
export * from "./Routes.js";
|
package/ui/router/index.js
CHANGED
|
@@ -2,7 +2,7 @@ export * from "./Navigation.js";
|
|
|
2
2
|
export * from "./NavigationContext.js";
|
|
3
3
|
export * from "./NavigationStore.js";
|
|
4
4
|
export * from "./RouteCache.js";
|
|
5
|
+
export * from "./RouteConfig.js";
|
|
5
6
|
export * from "./RouteContext.js";
|
|
6
|
-
export * from "./RoutePath.js";
|
|
7
7
|
export * from "./Router.js";
|
|
8
8
|
export * from "./Routes.js";
|
package/ui/router/index.ts
CHANGED
|
@@ -2,7 +2,7 @@ export * from "./Navigation.js";
|
|
|
2
2
|
export * from "./NavigationContext.js";
|
|
3
3
|
export * from "./NavigationStore.js";
|
|
4
4
|
export * from "./RouteCache.js";
|
|
5
|
+
export * from "./RouteConfig.js";
|
|
5
6
|
export * from "./RouteContext.js";
|
|
6
|
-
export * from "./RoutePath.js";
|
|
7
7
|
export * from "./Router.js";
|
|
8
8
|
export * from "./Routes.js";
|
package/docs/ui/RoutePath.md
DELETED
|
@@ -1,56 +0,0 @@
|
|
|
1
|
-
# RoutePath
|
|
2
|
-
|
|
3
|
-
- Kind: component
|
|
4
|
-
- Import: `import { RoutePath } from "shelving/ui";`
|
|
5
|
-
|
|
6
|
-
Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
|
|
7
|
-
- A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
|
|
8
|
-
and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
|
|
9
|
-
- Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
|
|
10
|
-
- Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
11
|
-
|
|
12
|
-
Tell the surrounding `<Router>` (and `<RouteCache>`, if there is one) that a page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
|
|
13
|
-
|
|
14
|
-
**Things to know:**
|
|
15
|
-
|
|
16
|
-
- Without `<RoutePath>`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
|
|
17
|
-
- Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
|
|
18
|
-
- The page still renders for the new URL, so it reads the tab from the URL as usual.
|
|
19
|
-
- It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
|
|
20
|
-
|
|
21
|
-
## Usage
|
|
22
|
-
|
|
23
|
-
```tsx
|
|
24
|
-
import { Page, RoutePath } from "shelving/ui";
|
|
25
|
-
|
|
26
|
-
function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
27
|
-
return (
|
|
28
|
-
<RoutePath path={`/${name}/{tab}`}>
|
|
29
|
-
<Page title={name}>
|
|
30
|
-
<ProfileTabs tab={tab} />
|
|
31
|
-
</Page>
|
|
32
|
-
</RoutePath>
|
|
33
|
-
);
|
|
34
|
-
}
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
## Signatures
|
|
39
|
-
|
|
40
|
-
```ts
|
|
41
|
-
RoutePath({ path, children }: RoutePathProps): ReactNode
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## Parameters
|
|
45
|
-
|
|
46
|
-
| Param | Type | Description |
|
|
47
|
-
| --- | --- | --- |
|
|
48
|
-
| `props` | `RoutePathProps` | |
|
|
49
|
-
| `.path` | `AbsolutePath` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. |
|
|
50
|
-
| `.children` | `ReactNode` | The page content. Read only. Optional. |
|
|
51
|
-
|
|
52
|
-
## Returns
|
|
53
|
-
|
|
54
|
-
| Type | Description |
|
|
55
|
-
| --- | --- |
|
|
56
|
-
| `ReactNode` | |
|
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
# RoutePathProps
|
|
2
|
-
|
|
3
|
-
- Kind: interface
|
|
4
|
-
- Import: `import { RoutePathProps } from "shelving/ui";`
|
|
5
|
-
|
|
6
|
-
Props for `<RoutePath>` — the path template the page owns, and the page content.
|
|
7
|
-
|
|
8
|
-
## Signatures
|
|
9
|
-
|
|
10
|
-
```ts
|
|
11
|
-
{
|
|
12
|
-
readonly path: AbsolutePath;
|
|
13
|
-
readonly children?: ReactNode;
|
|
14
|
-
}
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Properties
|
|
18
|
-
|
|
19
|
-
| Property | Type | Description |
|
|
20
|
-
| --- | --- | --- |
|
|
21
|
-
| `path` | `AbsolutePath` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. |
|
|
22
|
-
| `children` | `ReactNode` | The page content. Read only. Optional. |
|
package/ui/router/RoutePath.d.ts
DELETED
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
import { type ReactNode } from "react";
|
|
2
|
-
import type { AbsolutePath } from "../../util/path.js";
|
|
3
|
-
/**
|
|
4
|
-
* Props for `<RoutePath>` — the path template the page owns, and the page content.
|
|
5
|
-
*
|
|
6
|
-
* @see https://shelving.cc/ui/RoutePathProps
|
|
7
|
-
*/
|
|
8
|
-
export interface RoutePathProps {
|
|
9
|
-
/** Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. */
|
|
10
|
-
readonly path: AbsolutePath;
|
|
11
|
-
/** The page content. */
|
|
12
|
-
readonly children?: ReactNode;
|
|
13
|
-
}
|
|
14
|
-
/**
|
|
15
|
-
* Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
|
|
16
|
-
* - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
|
|
17
|
-
* and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
|
|
18
|
-
* - Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
|
|
19
|
-
* - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
20
|
-
*
|
|
21
|
-
* @kind component
|
|
22
|
-
* @see https://shelving.cc/ui/RoutePath
|
|
23
|
-
*/
|
|
24
|
-
export declare function RoutePath({ path, children }: RoutePathProps): ReactNode;
|
package/ui/router/RoutePath.js
DELETED
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
import { use } from "react";
|
|
2
|
-
import { RouteContext } from "./RouteContext.js";
|
|
3
|
-
/**
|
|
4
|
-
* Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
|
|
5
|
-
* - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
|
|
6
|
-
* and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
|
|
7
|
-
* - Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
|
|
8
|
-
* - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
9
|
-
*
|
|
10
|
-
* @kind component
|
|
11
|
-
* @see https://shelving.cc/ui/RoutePath
|
|
12
|
-
*/
|
|
13
|
-
export function RoutePath({ path, children }) {
|
|
14
|
-
const state = use(RouteContext);
|
|
15
|
-
if (state) {
|
|
16
|
-
state.path = path;
|
|
17
|
-
if (state.cache)
|
|
18
|
-
state.cache.path = path;
|
|
19
|
-
}
|
|
20
|
-
return children;
|
|
21
|
-
}
|
package/ui/router/RoutePath.md
DELETED
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
# RoutePath
|
|
2
|
-
|
|
3
|
-
Tell the surrounding `<Router>` (and `<RouteCache>`, if there is one) that a page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
|
|
4
|
-
|
|
5
|
-
**Things to know:**
|
|
6
|
-
|
|
7
|
-
- Without `<RoutePath>`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
|
|
8
|
-
- Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
|
|
9
|
-
- The page still renders for the new URL, so it reads the tab from the URL as usual.
|
|
10
|
-
- It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
|
|
11
|
-
|
|
12
|
-
## Usage
|
|
13
|
-
|
|
14
|
-
```tsx
|
|
15
|
-
import { Page, RoutePath } from "shelving/ui";
|
|
16
|
-
|
|
17
|
-
function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
18
|
-
return (
|
|
19
|
-
<RoutePath path={`/${name}/{tab}`}>
|
|
20
|
-
<Page title={name}>
|
|
21
|
-
<ProfileTabs tab={tab} />
|
|
22
|
-
</Page>
|
|
23
|
-
</RoutePath>
|
|
24
|
-
);
|
|
25
|
-
}
|
|
26
|
-
```
|
package/ui/router/RoutePath.tsx
DELETED
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
import { type ReactNode, use } from "react";
|
|
2
|
-
import type { AbsolutePath } from "../../util/path.js";
|
|
3
|
-
import { RouteContext } from "./RouteContext.js";
|
|
4
|
-
|
|
5
|
-
/**
|
|
6
|
-
* Props for `<RoutePath>` — the path template the page owns, and the page content.
|
|
7
|
-
*
|
|
8
|
-
* @see https://shelving.cc/ui/RoutePathProps
|
|
9
|
-
*/
|
|
10
|
-
export interface RoutePathProps {
|
|
11
|
-
/** Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. */
|
|
12
|
-
readonly path: AbsolutePath;
|
|
13
|
-
/** The page content. */
|
|
14
|
-
readonly children?: ReactNode;
|
|
15
|
-
}
|
|
16
|
-
|
|
17
|
-
/**
|
|
18
|
-
* Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
|
|
19
|
-
* - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
|
|
20
|
-
* and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
|
|
21
|
-
* - Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
|
|
22
|
-
* - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
23
|
-
*
|
|
24
|
-
* @kind component
|
|
25
|
-
* @see https://shelving.cc/ui/RoutePath
|
|
26
|
-
*/
|
|
27
|
-
export function RoutePath({ path, children }: RoutePathProps): ReactNode {
|
|
28
|
-
const state = use(RouteContext);
|
|
29
|
-
if (state) {
|
|
30
|
-
state.path = path;
|
|
31
|
-
if (state.cache) state.cache.path = path;
|
|
32
|
-
}
|
|
33
|
-
return children;
|
|
34
|
-
}
|