shelving 1.312.2 → 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.
Files changed (42) hide show
  1. package/docs/llms-full.txt +152 -67
  2. package/docs/schema/ChoiceGroups.md +21 -0
  3. package/docs/schema/ChoiceSchema.md +26 -1
  4. package/docs/schema/ChoiceSchemaOptions.md +3 -0
  5. package/docs/schema.md +1 -0
  6. package/docs/ui/RouteCache.md +5 -2
  7. package/docs/ui/RouteConfig.md +75 -0
  8. package/docs/ui/RouteConfigProps.md +24 -0
  9. package/docs/ui/RouteState.md +8 -5
  10. package/docs/ui/Router.md +1 -1
  11. package/docs/ui/SelectInput.md +2 -0
  12. package/docs/ui/SelectProps.md +2 -0
  13. package/docs/ui.md +3 -3
  14. package/package.json +1 -1
  15. package/schema/ChoiceSchema.d.ts +16 -1
  16. package/schema/ChoiceSchema.js +3 -1
  17. package/ui/input/Input.test.tsx +33 -1
  18. package/ui/input/SelectInput.d.ts +4 -1
  19. package/ui/input/SelectInput.js +13 -2
  20. package/ui/input/SelectInput.tsx +29 -6
  21. package/ui/router/RouteCache.d.ts +2 -1
  22. package/ui/router/RouteCache.js +8 -3
  23. package/ui/router/RouteCache.md +3 -1
  24. package/ui/router/RouteCache.tsx +7 -3
  25. package/ui/router/RouteConfig.d.ts +28 -0
  26. package/ui/router/RouteConfig.js +30 -0
  27. package/ui/router/RouteConfig.md +42 -0
  28. package/ui/router/RouteConfig.tsx +44 -0
  29. package/ui/router/RouteContext.d.ts +6 -4
  30. package/ui/router/RouteContext.tsx +6 -4
  31. package/ui/router/Router.d.ts +1 -1
  32. package/ui/router/Router.js +4 -4
  33. package/ui/router/Router.tsx +4 -4
  34. package/ui/router/index.d.ts +1 -1
  35. package/ui/router/index.js +1 -1
  36. package/ui/router/index.ts +1 -1
  37. package/docs/ui/RoutePath.md +0 -56
  38. package/docs/ui/RoutePathProps.md +0 -22
  39. package/ui/router/RoutePath.d.ts +0 -24
  40. package/ui/router/RoutePath.js +0 -21
  41. package/ui/router/RoutePath.md +0 -26
  42. package/ui/router/RoutePath.tsx +0 -34
@@ -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.
@@ -5,6 +5,7 @@
5
5
 
6
6
  Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
7
7
  - Shows a placeholder empty option unless the field is required and already has a value.
8
+ - With `groups`, shows each group as an `<optgroup>`, after the options that are in no group. A group key that is not in `options` is skipped.
8
9
 
9
10
  ## Signatures
10
11
 
@@ -18,6 +19,7 @@ SelectInput(props: SelectProps<T>): ReactElement
18
19
  | --- | --- | --- |
19
20
  | `props` | `SelectProps<T>` | |
20
21
  | `.options` | `ChoiceOptions<T>` | The options for the select. |
22
+ | `.groups` | `ChoiceGroups<T> \| undefined` | Show the options under named headings, as `<optgroup>` elements. Options in no group show first. Optional. |
21
23
 
22
24
  ## Returns
23
25
 
@@ -11,6 +11,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
11
11
  ```ts
12
12
  {
13
13
  options: ChoiceOptions<T>;
14
+ groups?: ChoiceGroups<T> | undefined;
14
15
  }
15
16
  ```
16
17
 
@@ -19,3 +20,4 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
19
20
  | Property | Type | Description |
20
21
  | --- | --- | --- |
21
22
  | `options` | `ChoiceOptions<T>` | The options for the select. |
23
+ | `groups` | `ChoiceGroups<T> \| undefined` | Show the options under named headings, as `<optgroup>` elements. Options in no group show first. Optional. |
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.312.2",
3
+ "version": "1.314.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -18,6 +18,17 @@ export type ChoiceOptions<K extends string> = {
18
18
  * @see https://shelving.cc/schema/PossibleChoiceOptions
19
19
  */
20
20
  export type PossibleChoiceOptions<K extends string> = ImmutableArray<K> | ChoiceOptions<K>;
21
+ /**
22
+ * Named groups of option keys for a `ChoiceSchema` in `{ group: [key] }` format, e.g. `{ Fruit: ["apple", "pear"] }`.
23
+ *
24
+ * - Groups are a display hint only: validation and `format()` use `options`, and do not change.
25
+ * - The group order and the key order in each group set the display order.
26
+ *
27
+ * @see https://shelving.cc/schema/ChoiceGroups
28
+ */
29
+ export type ChoiceGroups<K extends string> = {
30
+ readonly [group: string]: ImmutableArray<K>;
31
+ };
21
32
  /**
22
33
  * Input control hint for a `ChoiceSchema`: `"radio"` for radio inputs, or `"select"` for a `<select>`.
23
34
  *
@@ -30,6 +41,7 @@ export type ChoiceInputType = "radio" | "select";
30
41
  * - `options` — the allowed choices, as a `{ key: title }` dictionary or an array of keys.
31
42
  * - `value` — default option used when the input is `undefined`.
32
43
  * - `input` — control hint for downstream UIs (radios or a select).
44
+ * - `groups` — display hint that puts options under named headings (a select shows each group as an `<optgroup>`).
33
45
  *
34
46
  * @see https://shelving.cc/schema/ChoiceSchemaOptions
35
47
  */
@@ -43,6 +55,8 @@ export interface ChoiceSchemaOptions<O extends string, I = never> extends Schema
43
55
  * @default "radio" for 8 or fewer options, otherwise "select"
44
56
  */
45
57
  readonly input?: ChoiceInputType | undefined;
58
+ /** Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. */
59
+ readonly groups?: ChoiceGroups<O> | undefined;
46
60
  }
47
61
  /**
48
62
  * Schema that validates a value against a fixed set of allowed string choices.
@@ -56,7 +70,8 @@ export declare class ChoiceSchema<O extends string, I = never> extends Schema<O>
56
70
  readonly value: O | I | undefined;
57
71
  readonly options: ChoiceOptions<O>;
58
72
  readonly input: ChoiceInputType;
59
- constructor({ one, title, placeholder, options, value, input, ...rest }: ChoiceSchemaOptions<O, I>);
73
+ readonly groups: ChoiceGroups<O> | undefined;
74
+ constructor({ one, title, placeholder, options, value, input, groups, ...rest }: ChoiceSchemaOptions<O, I>);
60
75
  /**
61
76
  * Get an unknown value as one of the allowed choices, or `undefined` if it isn't one.
62
77
  *
@@ -21,9 +21,11 @@ const MAX_RADIO_OPTIONS = 8;
21
21
  export class ChoiceSchema extends Schema {
22
22
  options;
23
23
  input;
24
- constructor({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, input, ...rest }) {
24
+ groups;
25
+ constructor({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, input, groups, ...rest }) {
25
26
  super({ one, title, value, placeholder, ...rest });
26
27
  this.options = _getChoiceOptions(options);
28
+ this.groups = groups;
27
29
  this.input = input ?? (getKeys(this.options).length <= MAX_RADIO_OPTIONS ? "radio" : "select");
28
30
  }
29
31
  /**
@@ -1,6 +1,6 @@
1
1
  import { describe, expect, test } from "bun:test";
2
2
  import type { ReactElement } from "react";
3
- import { DateInput, FileInput, ImageInput, NumberInput, TextareaInput, TextInput } from "shelving/ui";
3
+ import { DateInput, FileInput, ImageInput, NumberInput, SelectInput, TextareaInput, TextInput } from "shelving/ui";
4
4
  import { PASSTHROUGH } from "shelving/util/function";
5
5
 
6
6
  /** The props of the rendered element that the tests read. */
@@ -68,3 +68,35 @@ describe("ImageInput", () => {
68
68
  expect(values).toEqual([file, undefined]);
69
69
  });
70
70
  });
71
+
72
+ describe("SelectInput", () => {
73
+ /** The `[type, key or label]` of each child of a rendered select, with an optgroup's options after it. */
74
+ function _getChildren(element: ReactElement): string[] {
75
+ const out: string[] = [];
76
+ const children = (element.props as { children: unknown[] }).children.flat();
77
+ for (const c of children) {
78
+ if (!c || typeof c !== "object") continue;
79
+ const el = c as ReactElement<{ value?: string; label?: string; children?: unknown }>;
80
+ if (el.type === "optgroup") {
81
+ out.push(`group:${el.props.label}`);
82
+ for (const o of [el.props.children].flat()) if (o) out.push(`option:${(o as ReactElement<{ value: string }>).props.value}`);
83
+ } else out.push(`option:${el.props.value}`);
84
+ }
85
+ return out;
86
+ }
87
+ test("shows options in no group first, then each group as an optgroup", () => {
88
+ const element = SelectInput<string>({
89
+ name: "x",
90
+ required: true,
91
+ value: "a",
92
+ options: { a: "A", b: "B", c: "C", d: "D" },
93
+ groups: { Second: ["d", "b"], Missing: ["z"] },
94
+ onValue: PASSTHROUGH,
95
+ });
96
+ expect(_getChildren(element)).toEqual(["option:a", "option:c", "group:Second", "option:d", "option:b", "group:Missing"]);
97
+ });
98
+ test("shows a flat list with no groups", () => {
99
+ const element = SelectInput<string>({ name: "x", required: true, value: "a", options: { a: "A", b: "B" }, onValue: PASSTHROUGH });
100
+ expect(_getChildren(element)).toEqual(["option:a", "option:b"]);
101
+ });
102
+ });
@@ -1,5 +1,5 @@
1
1
  import type { ReactElement } from "react";
2
- import type { ChoiceOptions } from "../../schema/ChoiceSchema.js";
2
+ import type { ChoiceGroups, ChoiceOptions } from "../../schema/ChoiceSchema.js";
3
3
  import { type InputVariants, type ValueInputProps } from "./Input.js";
4
4
  /**
5
5
  * Props for `SelectInput`, a dropdown `<select>` bound to a string value.
@@ -9,10 +9,13 @@ import { type InputVariants, type ValueInputProps } from "./Input.js";
9
9
  export interface SelectProps<T extends string> extends ValueInputProps<T>, InputVariants {
10
10
  /** The options for the select. */
11
11
  options: ChoiceOptions<T>;
12
+ /** Show the options under named headings, as `<optgroup>` elements. Options in no group show first. */
13
+ groups?: ChoiceGroups<T> | undefined;
12
14
  }
13
15
  /**
14
16
  * Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
15
17
  * - Shows a placeholder empty option unless the field is required and already has a value.
18
+ * - With `groups`, shows each group as an `<optgroup>`, after the options that are in no group. A group key that is not in `options` is skipped.
16
19
  *
17
20
  * @returns A `<select>` element.
18
21
  * @kind component
@@ -3,6 +3,17 @@ import { getProps } from "../../util/object.js";
3
3
  import { getClass, getModuleClass } from "../util/css.js";
4
4
  import { getInputClass } from "./Input.js";
5
5
  import INPUT_CSS from "./Input.module.css";
6
- export function SelectInput({ name, placeholder = "Choose...", required = false, disabled = false, message = "", value = "", onValue, options, className, ...variants }) {
7
- return (_jsxs("select", { name: name, defaultValue: value, onChange: e => onValue(e.currentTarget.value || undefined), className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "select"), className), title: message, "aria-invalid": !!message, disabled: disabled, required: required, children: [!required || !value ? (_jsx("option", { value: "", className: getModuleClass(INPUT_CSS, "empty"), children: placeholder })) : null, getProps(options).map(([k, t]) => (_jsx("option", { value: k, className: getModuleClass(INPUT_CSS, "value"), children: t }, k)))] }));
6
+ const OPTION_CLASS = getModuleClass(INPUT_CSS, "value");
7
+ export function SelectInput({ name, placeholder = "Choose...", required = false, disabled = false, message = "", value = "", onValue, options, groups, className, ...variants }) {
8
+ const grouped = groups ? new Set(Object.values(groups).flat()) : undefined;
9
+ return (_jsxs("select", { name: name, defaultValue: value, onChange: e => onValue(e.currentTarget.value || undefined), className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "select"), className), title: message, "aria-invalid": !!message, disabled: disabled, required: required, children: [!required || !value ? (_jsx("option", { value: "", className: getModuleClass(INPUT_CSS, "empty"), children: placeholder })) : null, getProps(options).map(([k, t]) => (grouped?.has(k) ? null : _renderOption(k, t))), groups
10
+ ? Object.entries(groups).map(([g, keys]) => (_jsx("optgroup", { label: g, children: keys.map(k => _renderGroupOption(options, k)) }, g)))
11
+ : null] }));
12
+ }
13
+ function _renderOption(key, title) {
14
+ return (_jsx("option", { value: key, className: OPTION_CLASS, children: title }, key));
15
+ }
16
+ function _renderGroupOption(options, key) {
17
+ const title = options[key];
18
+ return title === undefined ? null : _renderOption(key, title);
8
19
  }
@@ -1,5 +1,5 @@
1
1
  import type { ReactElement } from "react";
2
- import type { ChoiceOptions } from "../../schema/ChoiceSchema.js";
2
+ import type { ChoiceGroups, ChoiceOptions } from "../../schema/ChoiceSchema.js";
3
3
  import { getProps } from "../../util/object.js";
4
4
  import { getClass, getModuleClass } from "../util/css.js";
5
5
  import { getInputClass, type InputVariants, type ValueInputProps } from "./Input.js";
@@ -13,11 +13,16 @@ import INPUT_CSS from "./Input.module.css";
13
13
  export interface SelectProps<T extends string> extends ValueInputProps<T>, InputVariants {
14
14
  /** The options for the select. */
15
15
  options: ChoiceOptions<T>;
16
+ /** Show the options under named headings, as `<optgroup>` elements. Options in no group show first. */
17
+ groups?: ChoiceGroups<T> | undefined;
16
18
  }
17
19
 
20
+ const OPTION_CLASS = getModuleClass(INPUT_CSS, "value");
21
+
18
22
  /**
19
23
  * Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
20
24
  * - Shows a placeholder empty option unless the field is required and already has a value.
25
+ * - With `groups`, shows each group as an `<optgroup>`, after the options that are in no group. A group key that is not in `options` is skipped.
21
26
  *
22
27
  * @returns A `<select>` element.
23
28
  * @kind component
@@ -34,9 +39,11 @@ export function SelectInput({
34
39
  value = "",
35
40
  onValue,
36
41
  options,
42
+ groups,
37
43
  className,
38
44
  ...variants
39
45
  }: SelectProps<string>): ReactElement {
46
+ const grouped = groups ? new Set(Object.values(groups).flat()) : undefined;
40
47
  return (
41
48
  <select
42
49
  name={name}
@@ -53,11 +60,27 @@ export function SelectInput({
53
60
  {placeholder}
54
61
  </option>
55
62
  ) : null}
56
- {getProps(options).map(([k, t]) => (
57
- <option key={k} value={k} className={getModuleClass(INPUT_CSS, "value")}>
58
- {t}
59
- </option>
60
- ))}
63
+ {getProps(options).map(([k, t]) => (grouped?.has(k) ? null : _renderOption(k, t)))}
64
+ {groups
65
+ ? Object.entries(groups).map(([g, keys]) => (
66
+ <optgroup key={g} label={g}>
67
+ {keys.map(k => _renderGroupOption(options, k))}
68
+ </optgroup>
69
+ ))
70
+ : null}
61
71
  </select>
62
72
  );
63
73
  }
74
+
75
+ function _renderOption(key: string, title: string): ReactElement {
76
+ return (
77
+ <option key={key} value={key} className={OPTION_CLASS}>
78
+ {title}
79
+ </option>
80
+ );
81
+ }
82
+
83
+ function _renderGroupOption(options: ChoiceOptions<string>, key: string): ReactElement | null {
84
+ const title = options[key];
85
+ return title === undefined ? null : _renderOption(key, title);
86
+ }
@@ -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