shelving 1.313.0 → 1.314.1

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.
@@ -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
- - [RoutePath](ui/RoutePath.md): Tell the surrounding <Router> (and <RouteCache>) that this page owns every path that matches a template.
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
- - [RouteState](ui/RouteState.md): The route state of one page, shared by <Router>, <RouteCache> and <RoutePath>.
19907
- - [RoutePathProps](ui/RoutePathProps.md): Props for <RoutePath> — the path template the page owns, and the page content.
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".
@@ -29376,7 +29376,7 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
29376
29376
  | `--sidebar-layout-color` | Text colour for the layout (set on `body`, inherited by the content column) | `var(--tint-00)` (black) |
29377
29377
  | `--sidebar-layout-sidebar-background` | Sidebar column fill | `var(--tint-90)` (one shade darker than the page) |
29378
29378
  | `--sidebar-layout-sidebar-color` | Sidebar column text colour | `var(--tint-00)` (black) |
29379
- | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-80)` | `none` |
29379
+ | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
29380
29380
  | `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
29381
29381
 
29382
29382
  The sidebar and content columns own their own scroll behaviour directly (this layout no longer composes a shared `.layout` class).
@@ -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 `<RoutePath>` stays mounted when the URL changes to one of them.
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 `<RoutePath>`, 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.
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
- # RouteState
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 { RoutePathProps } from "shelving/ui";`
31751
+ - Import: `import { RouteConfigProps } from "shelving/ui";`
31790
31752
 
31791
- Props for `<RoutePath>` — the path template the page owns, and the page content.
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: AbsolutePath;
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
- # RoutePath
31776
+ # RouteConfig
31813
31777
 
31814
31778
  - Kind: component
31815
- - Import: `import { RoutePath } from "shelving/ui";`
31779
+ - Import: `import { RouteConfig } from "shelving/ui";`
31816
31780
 
31817
- Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
31818
- - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
31819
- and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
31820
- - Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
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
- 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.
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 `<RoutePath>`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
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, RoutePath } from "shelving/ui";
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
- <RoutePath path={`/${name}/{tab}`}>
31810
+ <RouteConfig path={`/${name}/{tab}`}>
31840
31811
  <Page title={name}>
31841
31812
  <ProfileTabs tab={tab} />
31842
31813
  </Page>
31843
- </RoutePath>
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
- RoutePath({ path, children }: RoutePathProps): ReactNode
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` | `RoutePathProps` | |
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 `<RoutePath>` stays mounted when the path changes to one of them.
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.
@@ -33545,8 +33572,8 @@ Components paint from the ladder by convention:
33545
33572
  |---|---|
33546
33573
  | `--tint-00` | Body text, headings — maximum contrast |
33547
33574
  | `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `<Button>` backgrounds |
33548
- | `--tint-80` | Borders |
33549
- | `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds |
33575
+ | `--tint-80` | Borders of boxes and controls — `<Card>`, `<Input>`, `<Notice>` |
33576
+ | `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds; light rules — `<Divider>`, `<Table>` rows, `<Blockquote>` |
33550
33577
  | `--tint-95` | Hover state of those surfaces |
33551
33578
  | `--tint-100` | The page background; text on `--tint-50` backgrounds |
33552
33579
  | `--tint-contrast` | Text on `--tint-50` backgrounds when the anchor can be light or dark |
@@ -34103,7 +34130,7 @@ import { Button, Cell, Table } from "shelving/ui";
34103
34130
  | `--table-padding` | Cell top and bottom padding (one length) | `var(--space-xsmall)` (8px) |
34104
34131
  | `--table-indent` | Cell left and right padding (one length) | `var(--space-xsmall)` (8px) |
34105
34132
  | `--table-border` | Cell border shorthand | `var(--table-stroke)` |
34106
- | `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-80)` |
34133
+ | `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-90)` |
34107
34134
  | `--table-header-weight` | Weight of `<thead>` / `<tfoot>` / `<tbody> <th>` cells | `var(--weight-strong)` |
34108
34135
  | `--table-label-font` | Label font for `<thead>` / `<tfoot>` `<th>` | `var(--font-label)` |
34109
34136
  | `--table-label-weight` | Label weight | `var(--weight-label)` |
@@ -34111,7 +34138,7 @@ import { Button, Cell, Table } from "shelving/ui";
34111
34138
  | `--table-label-case` | Label letter case | `var(--case-label)` |
34112
34139
  | `--table-label-color` | Label colour | `var(--tint-70)` |
34113
34140
 
34114
- **Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, `--stroke-normal`, the tint-ladder steps `--tint-70` / `--tint-80`, and the label tokens `--font-label` / `--weight-label` / `--size-label` / `--case-label` / `--weight-strong`.
34141
+ **Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, `--stroke-normal`, the tint-ladder steps `--tint-70` / `--tint-90`, and the label tokens `--font-label` / `--weight-label` / `--size-label` / `--case-label` / `--weight-strong`.
34115
34142
 
34116
34143
  ## Table contents
34117
34144
 
@@ -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 `<RoutePath>` stays mounted when the URL changes to one of them.
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 `<RoutePath>`, 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.
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. |
@@ -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 `<RoutePath>`.
7
- - `path` is the template of the paths the page owns, set by `<RoutePath>`.
8
- - `cache` is the page's `<RouteCache>` entry, so `<RoutePath>` in a top-level page also tells the cache.
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
- readonly cache?: RouteState | undefined;
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` | `RouteState \| undefined` | Read only. Optional. |
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 `<RoutePath>` stays mounted when the path changes to one of them.
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.
@@ -53,7 +53,7 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
53
53
  | `--sidebar-layout-color` | Text colour for the layout (set on `body`, inherited by the content column) | `var(--tint-00)` (black) |
54
54
  | `--sidebar-layout-sidebar-background` | Sidebar column fill | `var(--tint-90)` (one shade darker than the page) |
55
55
  | `--sidebar-layout-sidebar-color` | Sidebar column text colour | `var(--tint-00)` (black) |
56
- | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-80)` | `none` |
56
+ | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
57
57
  | `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
58
58
 
59
59
  The sidebar and content columns own their own scroll behaviour directly (this layout no longer composes a shared `.layout` class).
@@ -40,8 +40,8 @@ Components paint from the ladder by convention:
40
40
  |---|---|
41
41
  | `--tint-00` | Body text, headings — maximum contrast |
42
42
  | `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `<Button>` backgrounds |
43
- | `--tint-80` | Borders |
44
- | `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds |
43
+ | `--tint-80` | Borders of boxes and controls — `<Card>`, `<Input>`, `<Notice>` |
44
+ | `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds; light rules — `<Divider>`, `<Table>` rows, `<Blockquote>` |
45
45
  | `--tint-95` | Hover state of those surfaces |
46
46
  | `--tint-100` | The page background; text on `--tint-50` backgrounds |
47
47
  | `--tint-contrast` | Text on `--tint-50` backgrounds when the anchor can be light or dark |
package/docs/ui/Table.md CHANGED
@@ -67,7 +67,7 @@ import { Button, Cell, Table } from "shelving/ui";
67
67
  | `--table-padding` | Cell top and bottom padding (one length) | `var(--space-xsmall)` (8px) |
68
68
  | `--table-indent` | Cell left and right padding (one length) | `var(--space-xsmall)` (8px) |
69
69
  | `--table-border` | Cell border shorthand | `var(--table-stroke)` |
70
- | `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-80)` |
70
+ | `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-90)` |
71
71
  | `--table-header-weight` | Weight of `<thead>` / `<tfoot>` / `<tbody> <th>` cells | `var(--weight-strong)` |
72
72
  | `--table-label-font` | Label font for `<thead>` / `<tfoot>` `<th>` | `var(--font-label)` |
73
73
  | `--table-label-weight` | Label weight | `var(--weight-label)` |
@@ -75,7 +75,7 @@ import { Button, Cell, Table } from "shelving/ui";
75
75
  | `--table-label-case` | Label letter case | `var(--case-label)` |
76
76
  | `--table-label-color` | Label colour | `var(--tint-70)` |
77
77
 
78
- **Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, `--stroke-normal`, the tint-ladder steps `--tint-70` / `--tint-80`, and the label tokens `--font-label` / `--weight-label` / `--size-label` / `--case-label` / `--weight-strong`.
78
+ **Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, `--stroke-normal`, the tint-ladder steps `--tint-70` / `--tint-90`, and the label tokens `--font-label` / `--weight-label` / `--size-label` / `--case-label` / `--weight-strong`.
79
79
 
80
80
  ## Table contents
81
81
 
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
- - [RoutePath](ui/RoutePath.md): Tell the surrounding <Router> (and <RouteCache>) that this page owns every path that matches a template.
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
- - [RouteState](ui/RouteState.md): The route state of one page, shared by <Router>, <RouteCache> and <RoutePath>.
442
- - [RoutePathProps](ui/RoutePathProps.md): Props for <RoutePath> — the path template the page owns, and the page content.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.313.0",
3
+ "version": "1.314.1",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -9,7 +9,7 @@
9
9
  .prose blockquote {
10
10
  /* Box */
11
11
  margin-block: var(--blockquote-space, var(--space-paragraph));
12
- border-inline-start: var(--blockquote-border, var(--blockquote-stroke, var(--stroke-normal)) solid var(--tint-80));
12
+ border-inline-start: var(--blockquote-border, var(--blockquote-stroke, var(--stroke-normal)) solid var(--tint-90));
13
13
  padding-block: var(--blockquote-padding, var(--space-small));
14
14
  padding-inline-start: var(--blockquote-indent, var(--space-normal));
15
15
 
@@ -7,7 +7,7 @@
7
7
  .divider,
8
8
  .prose hr {
9
9
  /* Box */
10
- border-block-start: var(--divider-border, var(--divider-stroke, var(--stroke-normal)) solid var(--tint-80));
10
+ border-block-start: var(--divider-border, var(--divider-stroke, var(--stroke-normal)) solid var(--tint-90));
11
11
  margin-block: var(--divider-space, var(--space-paragraph));
12
12
  }
13
13
  }
@@ -43,7 +43,7 @@ Layouts compose naturally as `<Router>` route values — wrap a group of routes
43
43
  | `--sidebar-layout-color` | Text colour for the layout (set on `body`, inherited by the content column) | `var(--tint-00)` (black) |
44
44
  | `--sidebar-layout-sidebar-background` | Sidebar column fill | `var(--tint-90)` (one shade darker than the page) |
45
45
  | `--sidebar-layout-sidebar-color` | Sidebar column text colour | `var(--tint-00)` (black) |
46
- | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-80)` | `none` |
46
+ | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
47
47
  | `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
48
48
 
49
49
  The sidebar and content columns own their own scroll behaviour directly (this layout no longer composes a shared `.layout` class).
@@ -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 `<RoutePath>` stays mounted when the URL changes to one of them.
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
@@ -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 `<RoutePath>` stays mounted when the URL changes to one of them.
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 `<RoutePath>`.
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 `<RoutePath>` owns a path, or `undefined` if none does. */
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;
@@ -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 `<RoutePath>`, 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.
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.
@@ -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 `<RoutePath>` stays mounted when the URL changes to one of them.
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 `<RoutePath>`.
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 `<RoutePath>` owns a path, or `undefined` if none does. */
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 `<RoutePath>`.
4
- * - `path` is the template of the paths the page owns, set by `<RoutePath>`.
5
- * - `cache` is the page's `<RouteCache>` entry, so `<RoutePath>` in a top-level page also tells the cache.
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
- readonly cache?: RouteState | undefined;
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 `<RoutePath>`.
6
- * - `path` is the template of the paths the page owns, set by `<RoutePath>`.
7
- * - `cache` is the page's `<RouteCache>` entry, so `<RoutePath>` in a top-level page also tells the cache.
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
- readonly cache?: RouteState | undefined;
15
+ cache?: boolean | undefined;
16
+ readonly entry?: RouteState | undefined;
15
17
  readonly router?: true | undefined;
16
18
  }
17
19
 
@@ -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 `<RoutePath>` stays mounted when the path changes to one of them.
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
@@ -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 `<RoutePath>` stays mounted when the path changes to one of them.
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 `<RoutePath>`, else start a new page for this path.
26
- // The top-level router passes the `<RouteCache>` entry on, so `<RoutePath>` in its page also tells the cache.
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, cache: parent?.router ? undefined : parent } };
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)
@@ -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 `<RoutePath>` stays mounted when the path changes to one of them.
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 `<RoutePath>`, else start a new page for this path.
45
- // The top-level router passes the `<RouteCache>` entry on, so `<RoutePath>` in its page also tells the cache.
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, cache: parent?.router ? undefined : parent } as RouteState };
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);
@@ -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";
@@ -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";
@@ -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";
@@ -32,8 +32,8 @@ Components paint from the ladder by convention:
32
32
  |---|---|
33
33
  | `--tint-00` | Body text, headings — maximum contrast |
34
34
  | `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `<Button>` backgrounds |
35
- | `--tint-80` | Borders |
36
- | `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds |
35
+ | `--tint-80` | Borders of boxes and controls — `<Card>`, `<Input>`, `<Notice>` |
36
+ | `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds; light rules — `<Divider>`, `<Table>` rows, `<Blockquote>` |
37
37
  | `--tint-95` | Hover state of those surfaces |
38
38
  | `--tint-100` | The page background; text on `--tint-50` backgrounds |
39
39
  | `--tint-contrast` | Text on `--tint-50` backgrounds when the anchor can be light or dark |
package/ui/table/Table.md CHANGED
@@ -59,7 +59,7 @@ import { Button, Cell, Table } from "shelving/ui";
59
59
  | `--table-padding` | Cell top and bottom padding (one length) | `var(--space-xsmall)` (8px) |
60
60
  | `--table-indent` | Cell left and right padding (one length) | `var(--space-xsmall)` (8px) |
61
61
  | `--table-border` | Cell border shorthand | `var(--table-stroke)` |
62
- | `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-80)` |
62
+ | `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-90)` |
63
63
  | `--table-header-weight` | Weight of `<thead>` / `<tfoot>` / `<tbody> <th>` cells | `var(--weight-strong)` |
64
64
  | `--table-label-font` | Label font for `<thead>` / `<tfoot>` `<th>` | `var(--font-label)` |
65
65
  | `--table-label-weight` | Label weight | `var(--weight-label)` |
@@ -67,7 +67,7 @@ import { Button, Cell, Table } from "shelving/ui";
67
67
  | `--table-label-case` | Label letter case | `var(--case-label)` |
68
68
  | `--table-label-color` | Label colour | `var(--tint-70)` |
69
69
 
70
- **Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, `--stroke-normal`, the tint-ladder steps `--tint-70` / `--tint-80`, and the label tokens `--font-label` / `--weight-label` / `--size-label` / `--case-label` / `--weight-strong`.
70
+ **Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, `--stroke-normal`, the tint-ladder steps `--tint-70` / `--tint-90`, and the label tokens `--font-label` / `--weight-label` / `--size-label` / `--case-label` / `--weight-strong`.
71
71
 
72
72
  ## Table contents
73
73
 
@@ -22,7 +22,7 @@
22
22
  td {
23
23
  padding-block: var(--table-padding, var(--space-xsmall));
24
24
  padding-inline: var(--table-indent, var(--space-xsmall));
25
- border-block: var(--table-border, var(--table-stroke, var(--stroke-normal) solid var(--tint-80)));
25
+ border-block: var(--table-border, var(--table-stroke, var(--stroke-normal) solid var(--tint-90)));
26
26
  }
27
27
 
28
28
  th:first-child,
@@ -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. |
@@ -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;
@@ -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
- }
@@ -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
- ```
@@ -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
- }