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
@@ -11524,6 +11524,7 @@ QUERY(PERSON).validate({ "address.street": "Main" }); // throws "address.street:
11524
11524
 
11525
11525
  - [ChoiceOptions](schema/ChoiceOptions.md): Dictionary of allowed options for a ChoiceSchema in { key: title } format.
11526
11526
  - [PossibleChoiceOptions](schema/PossibleChoiceOptions.md): Things that can be converted to a ChoiceOptions dictionary.
11527
+ - [ChoiceGroups](schema/ChoiceGroups.md): Named groups of option keys for a ChoiceSchema in { group: [key] } format, e.g. { Fruit: ["apple", "pear"] }.
11527
11528
  - [ChoiceInputType](schema/ChoiceInputType.md): Input control hint for a ChoiceSchema: "radio" for radio inputs, or "select" for a <select>.
11528
11529
  - [DateInputType](schema/DateInputType.md): type="" prop for HTML <input /> tags that are relevant for dates.
11529
11530
  - [SchemaOptions](schema/SchemaOptions.md): Options allowed by a Schema instance.
@@ -12008,6 +12009,31 @@ ImmutableArray<K> | ChoiceOptions<K>
12008
12009
  - [ChoiceOptions](schema/ChoiceOptions.md): Dictionary of allowed options for a ChoiceSchema in { key: title } format.
12009
12010
 
12010
12011
 
12012
+ ---
12013
+
12014
+ # ChoiceGroups
12015
+
12016
+ - Kind: type
12017
+ - Import: `import { ChoiceGroups } from "shelving/schema";`
12018
+
12019
+ Named groups of option keys for a `ChoiceSchema` in `{ group: [key] }` format, e.g. `{ Fruit: ["apple", "pear"] }`.
12020
+
12021
+ - Groups are a display hint only: validation and `format()` use `options`, and do not change.
12022
+ - The group order and the key order in each group set the display order.
12023
+
12024
+ ## Signatures
12025
+
12026
+ ```ts
12027
+ {
12028
+ readonly [group: string]: ImmutableArray<K>;
12029
+ }
12030
+ ```
12031
+
12032
+ ## Types
12033
+
12034
+ - [ImmutableArray](util/array/ImmutableArray.md): Immutable array: an array that cannot be changed.
12035
+
12036
+
12011
12037
  ---
12012
12038
 
12013
12039
  # ChoiceInputType
@@ -12037,6 +12063,7 @@ Options for `ChoiceSchema`.
12037
12063
  - `options` — the allowed choices, as a `{ key: title }` dictionary or an array of keys.
12038
12064
  - `value` — default option used when the input is `undefined`.
12039
12065
  - `input` — control hint for downstream UIs (radios or a select).
12066
+ - `groups` — display hint that puts options under named headings (a select shows each group as an `<optgroup>`).
12040
12067
 
12041
12068
  ## Signatures
12042
12069
 
@@ -12045,6 +12072,7 @@ Options for `ChoiceSchema`.
12045
12072
  readonly options: PossibleChoiceOptions<O>;
12046
12073
  readonly value?: O | I;
12047
12074
  readonly input?: ChoiceInputType | undefined;
12075
+ readonly groups?: ChoiceGroups<O> | undefined;
12048
12076
  }
12049
12077
  ```
12050
12078
 
@@ -12055,6 +12083,7 @@ Options for `ChoiceSchema`.
12055
12083
  | `options` | `PossibleChoiceOptions<O>` | Specify correct options using a dictionary of entries. Read only. |
12056
12084
  | `value` | `O \| I` | Default option for the value. Read only. Optional. |
12057
12085
  | `input` | `ChoiceInputType \| undefined` | Input control hint for downstream UIs. Read only. Defaults to `"radio" for 8 or fewer options, otherwise "select"`. |
12086
+ | `groups` | `ChoiceGroups<O> \| undefined` | Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. Read only. Optional. |
12058
12087
 
12059
12088
 
12060
12089
  ---
@@ -12101,11 +12130,34 @@ const UNIT = new ChoiceSchema({ options: ["kg", "g", "lb"], input: "select" });
12101
12130
  const SIZE = new ChoiceSchema({ options: ["s", "m", "l", "xl"], input: "radio" }); // Always radios.
12102
12131
  ```
12103
12132
 
12133
+ ## Groups
12134
+
12135
+ `groups` puts options under named headings. A select shows each group as an `<optgroup>`, after the options that are in no group. The group order and the key order in each group set the display order. Groups are a display hint only: validation and `format()` still use `options`.
12136
+
12137
+ ```ts
12138
+ import { ChoiceSchema } from "shelving/schema";
12139
+
12140
+ const FOOD = new ChoiceSchema({
12141
+ options: { none: "Nothing", apple: "Apple", pear: "Pear", carrot: "Carrot" },
12142
+ groups: { Fruit: ["apple", "pear"], Vegetables: ["carrot"] },
12143
+ input: "select",
12144
+ });
12145
+ ```
12146
+
12104
12147
 
12105
12148
  ## Signatures
12106
12149
 
12107
12150
  ```ts
12108
- new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, input, ...rest }: ChoiceSchemaOptions<O, I>)
12151
+ new ChoiceSchema<O, I>({
12152
+ one = "choice",
12153
+ title = "Choice",
12154
+ placeholder = `No ${one}`,
12155
+ options,
12156
+ value,
12157
+ input,
12158
+ groups,
12159
+ ...rest
12160
+ }: ChoiceSchemaOptions<O, I>)
12109
12161
  ```
12110
12162
 
12111
12163
  ## Parameters
@@ -12116,6 +12168,7 @@ new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${o
12116
12168
  | `.options` | `PossibleChoiceOptions<O>` | Specify correct options using a dictionary of entries. Read only. |
12117
12169
  | `.value` | `O \| I` | Default option for the value. Read only. Optional. |
12118
12170
  | `.input` | `ChoiceInputType \| undefined` | Input control hint for downstream UIs. Read only. Defaults to `"radio" for 8 or fewer options, otherwise "select"`. |
12171
+ | `.groups` | `ChoiceGroups<O> \| undefined` | Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. Read only. Optional. |
12119
12172
 
12120
12173
  ## Returns
12121
12174
 
@@ -12129,6 +12182,7 @@ new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${o
12129
12182
  | --- | --- | --- |
12130
12183
  | `options` | `ChoiceOptions<O>` | Read only. |
12131
12184
  | `input` | `ChoiceInputType` | Read only. |
12185
+ | `groups` | `ChoiceGroups<O> \| undefined` | Read only. |
12132
12186
 
12133
12187
  ## Methods
12134
12188
 
@@ -19602,7 +19656,7 @@ The components below are listed in the index following this page; this is the sh
19602
19656
  - [Page](ui/Page.md): Wrap a single page (or screen) within an app, applying its meta and head tags.
19603
19657
  - [Navigation](ui/Navigation.md): Top-level navigation provider.
19604
19658
  - [RouteCache](ui/RouteCache.md): Keep-alive page cache keyed by the current URL — drop it into a layout around its scrolling content region.
19605
- - [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>).
19606
19660
  - [Router](ui/Router.md): Match the current URL against routes and render the matched element.
19607
19661
  - [Scroll](ui/Scroll.md): Wrap children in a scrollable container with horizontal and/or vertical scrolling enabled.
19608
19662
  - [Cell](ui/Cell.md): Table cell.
@@ -19849,8 +19903,8 @@ The components below are listed in the index following this page; this is the sh
19849
19903
  - [PageProps](ui/PageProps.md): Props for <Page> — per-page Meta (title, description, etc.) plus the page children.
19850
19904
  - [NavigationProps](ui/NavigationProps.md): Props for <Navigation> — initial Meta (url/base) plus optional children.
19851
19905
  - [RouteCacheProps](ui/RouteCacheProps.md): Props for <RouteCache> — the maxCached size and the content children to keep alive per URL.
19852
- - [RouteState](ui/RouteState.md): The route state of one page, shared by <Router>, <RouteCache> and <RoutePath>.
19853
- - [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>.
19854
19908
  - [RouterProps](ui/RouterProps.md): Props for <Router> — the routes to match against plus an optional fallback.
19855
19909
  - [BlockVariants](ui/BlockVariants.md): Variants for block level elements.
19856
19910
  - [ColorVariants](ui/ColorVariants.md): Variant props for colouring an element, e.g. color="purple".
@@ -28914,6 +28968,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28914
28968
  ```ts
28915
28969
  {
28916
28970
  options: ChoiceOptions<T>;
28971
+ groups?: ChoiceGroups<T> | undefined;
28917
28972
  }
28918
28973
  ```
28919
28974
 
@@ -28922,6 +28977,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28922
28977
  | Property | Type | Description |
28923
28978
  | --- | --- | --- |
28924
28979
  | `options` | `ChoiceOptions<T>` | The options for the select. |
28980
+ | `groups` | `ChoiceGroups<T> \| undefined` | Show the options under named headings, as `<optgroup>` elements. Options in no group show first. Optional. |
28925
28981
 
28926
28982
 
28927
28983
  ---
@@ -28933,6 +28989,7 @@ Props for `SelectInput`, a dropdown `<select>` bound to a string value.
28933
28989
 
28934
28990
  Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
28935
28991
  - Shows a placeholder empty option unless the field is required and already has a value.
28992
+ - 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.
28936
28993
 
28937
28994
  ## Signatures
28938
28995
 
@@ -28946,6 +29003,7 @@ SelectInput(props: SelectProps<T>): ReactElement
28946
29003
  | --- | --- | --- |
28947
29004
  | `props` | `SelectProps<T>` | |
28948
29005
  | `.options` | `ChoiceOptions<T>` | The options for the select. |
29006
+ | `.groups` | `ChoiceGroups<T> \| undefined` | Show the options under named headings, as `<optgroup>` elements. Options in no group show first. Optional. |
28949
29007
 
28950
29008
  ## Returns
28951
29009
 
@@ -31625,7 +31683,8 @@ Keep-alive page cache keyed by the current URL — drop it into a layout around
31625
31683
  pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
31626
31684
  entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
31627
31685
  - Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
31628
- - 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.
31629
31688
  - Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
31630
31689
  different page per path and a hidden page never re-renders for someone else's URL.
31631
31690
  - `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
@@ -31642,7 +31701,9 @@ Shelving's `<SidebarLayout>` and `<CenteredLayout>` already wrap their scrollabl
31642
31701
  **Things to know:**
31643
31702
 
31644
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.
31645
- - 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.
31646
31707
  - Pass `maxCached={0}` (or less) to disable caching entirely — the page renders directly and unmounts as soon as you leave it.
31647
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.
31648
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.
@@ -31684,59 +31745,19 @@ RouteCache({ maxCached = 10, children }: RouteCacheProps): ReactNode
31684
31745
 
31685
31746
  ---
31686
31747
 
31687
- # RouteState
31748
+ # RouteConfigProps
31688
31749
 
31689
31750
  - Kind: interface
31690
- - Import: `import { RouteState } from "shelving/ui";`
31751
+ - Import: `import { RouteConfigProps } from "shelving/ui";`
31691
31752
 
31692
- The route state of one page, shared by `<Router>`, `<RouteCache>` and `<RoutePath>`.
31693
- - `path` is the template of the paths the page owns, set by `<RoutePath>`.
31694
- - `cache` is the page's `<RouteCache>` entry, so `<RoutePath>` in a top-level page also tells the cache.
31695
- - `router` marks a state made by `<Router>`, so a nested router does not pass the cache entry on.
31753
+ Props for `<RouteConfig>` — the settings of a page for the surrounding `<Router>` and `<RouteCache>`, and the page content.
31696
31754
 
31697
31755
  ## Signatures
31698
31756
 
31699
31757
  ```ts
31700
31758
  {
31701
- path?: AbsolutePath | undefined;
31702
- readonly cache?: RouteState | undefined;
31703
- readonly router?: true | undefined;
31704
- }
31705
- ```
31706
-
31707
- ## Properties
31708
-
31709
- | Property | Type | Description |
31710
- | --- | --- | --- |
31711
- | `path` | `AbsolutePath \| undefined` | Optional. |
31712
- | `cache` | `RouteState \| undefined` | Read only. Optional. |
31713
- | `router` | `true \| undefined` | Read only. Optional. |
31714
-
31715
-
31716
- ---
31717
-
31718
- # RouteContext
31719
-
31720
- - Kind: constant
31721
- - Import: `import { RouteContext } from "shelving/ui";`
31722
-
31723
- React context holding the `RouteState` of the current page, provided by `<Router>` and `<RouteCache>`.
31724
-
31725
-
31726
- ---
31727
-
31728
- # RoutePathProps
31729
-
31730
- - Kind: interface
31731
- - Import: `import { RoutePathProps } from "shelving/ui";`
31732
-
31733
- Props for `<RoutePath>` — the path template the page owns, and the page content.
31734
-
31735
- ## Signatures
31736
-
31737
- ```ts
31738
- {
31739
- readonly path: AbsolutePath;
31759
+ readonly path?: AbsolutePath | undefined;
31760
+ readonly cache?: boolean | undefined;
31740
31761
  readonly children?: ReactNode;
31741
31762
  }
31742
31763
  ```
@@ -31745,44 +31766,63 @@ Props for `<RoutePath>` — the path template the page owns, and the page conten
31745
31766
 
31746
31767
  | Property | Type | Description |
31747
31768
  | --- | --- | --- |
31748
- | `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. |
31749
31771
  | `children` | `ReactNode` | The page content. Read only. Optional. |
31750
31772
 
31751
31773
 
31752
31774
  ---
31753
31775
 
31754
- # RoutePath
31776
+ # RouteConfig
31755
31777
 
31756
31778
  - Kind: component
31757
- - Import: `import { RoutePath } from "shelving/ui";`
31779
+ - Import: `import { RouteConfig } from "shelving/ui";`
31758
31780
 
31759
- Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
31760
- - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
31761
- and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
31762
- - 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}"`.
31763
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.
31764
31788
 
31765
- 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.
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.
31790
+
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.
31766
31793
 
31767
31794
  **Things to know:**
31768
31795
 
31769
- - 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.
31770
31797
  - Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
31771
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.
31772
31800
  - It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
31773
31801
 
31774
31802
  ## Usage
31775
31803
 
31776
31804
  ```tsx
31777
- import { Page, RoutePath } from "shelving/ui";
31805
+ import { Page, RouteConfig } from "shelving/ui";
31778
31806
 
31807
+ // Each tab has its own path, and all of them are the same page.
31779
31808
  function ProfilePage({ name, tab }: { name: string; tab?: string }) {
31780
31809
  return (
31781
- <RoutePath path={`/${name}/{tab}`}>
31810
+ <RouteConfig path={`/${name}/{tab}`}>
31782
31811
  <Page title={name}>
31783
31812
  <ProfileTabs tab={tab} />
31784
31813
  </Page>
31785
- </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>
31786
31826
  );
31787
31827
  }
31788
31828
  ```
@@ -31791,15 +31831,16 @@ function ProfilePage({ name, tab }: { name: string; tab?: string }) {
31791
31831
  ## Signatures
31792
31832
 
31793
31833
  ```ts
31794
- RoutePath({ path, children }: RoutePathProps): ReactNode
31834
+ RouteConfig({ path, cache, children }: RouteConfigProps): ReactNode
31795
31835
  ```
31796
31836
 
31797
31837
  ## Parameters
31798
31838
 
31799
31839
  | Param | Type | Description |
31800
31840
  | --- | --- | --- |
31801
- | `props` | `RoutePathProps` | |
31802
- | `.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. |
31803
31844
  | `.children` | `ReactNode` | The page content. Read only. Optional. |
31804
31845
 
31805
31846
  ## Returns
@@ -31809,6 +31850,50 @@ RoutePath({ path, children }: RoutePathProps): ReactNode
31809
31850
  | `ReactNode` | |
31810
31851
 
31811
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
+
31812
31897
  ---
31813
31898
 
31814
31899
  # RouterProps
@@ -31848,7 +31933,7 @@ Match the current URL against `routes` and render the matched element.
31848
31933
  - When `base` is set, the effective path is the URL after stripping the base prefix.
31849
31934
  - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
31850
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.
31851
- - 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.
31852
31937
  - Returns `null` when there's no URL in context or the URL is outside the base.
31853
31938
 
31854
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.
@@ -0,0 +1,21 @@
1
+ # ChoiceGroups
2
+
3
+ - Kind: type
4
+ - Import: `import { ChoiceGroups } from "shelving/schema";`
5
+
6
+ Named groups of option keys for a `ChoiceSchema` in `{ group: [key] }` format, e.g. `{ Fruit: ["apple", "pear"] }`.
7
+
8
+ - Groups are a display hint only: validation and `format()` use `options`, and do not change.
9
+ - The group order and the key order in each group set the display order.
10
+
11
+ ## Signatures
12
+
13
+ ```ts
14
+ {
15
+ readonly [group: string]: ImmutableArray<K>;
16
+ }
17
+ ```
18
+
19
+ ## Types
20
+
21
+ - [ImmutableArray](../util/array/ImmutableArray.md): Immutable array: an array that cannot be changed.
@@ -40,11 +40,34 @@ const UNIT = new ChoiceSchema({ options: ["kg", "g", "lb"], input: "select" });
40
40
  const SIZE = new ChoiceSchema({ options: ["s", "m", "l", "xl"], input: "radio" }); // Always radios.
41
41
  ```
42
42
 
43
+ ## Groups
44
+
45
+ `groups` puts options under named headings. A select shows each group as an `<optgroup>`, after the options that are in no group. The group order and the key order in each group set the display order. Groups are a display hint only: validation and `format()` still use `options`.
46
+
47
+ ```ts
48
+ import { ChoiceSchema } from "shelving/schema";
49
+
50
+ const FOOD = new ChoiceSchema({
51
+ options: { none: "Nothing", apple: "Apple", pear: "Pear", carrot: "Carrot" },
52
+ groups: { Fruit: ["apple", "pear"], Vegetables: ["carrot"] },
53
+ input: "select",
54
+ });
55
+ ```
56
+
43
57
 
44
58
  ## Signatures
45
59
 
46
60
  ```ts
47
- new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${one}`, options, value, input, ...rest }: ChoiceSchemaOptions<O, I>)
61
+ new ChoiceSchema<O, I>({
62
+ one = "choice",
63
+ title = "Choice",
64
+ placeholder = `No ${one}`,
65
+ options,
66
+ value,
67
+ input,
68
+ groups,
69
+ ...rest
70
+ }: ChoiceSchemaOptions<O, I>)
48
71
  ```
49
72
 
50
73
  ## Parameters
@@ -55,6 +78,7 @@ new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${o
55
78
  | `.options` | `PossibleChoiceOptions<O>` | Specify correct options using a dictionary of entries. Read only. |
56
79
  | `.value` | `O \| I` | Default option for the value. Read only. Optional. |
57
80
  | `.input` | `ChoiceInputType \| undefined` | Input control hint for downstream UIs. Read only. Defaults to `"radio" for 8 or fewer options, otherwise "select"`. |
81
+ | `.groups` | `ChoiceGroups<O> \| undefined` | Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. Read only. Optional. |
58
82
 
59
83
  ## Returns
60
84
 
@@ -68,6 +92,7 @@ new ChoiceSchema<O, I>({ one = "choice", title = "Choice", placeholder = `No ${o
68
92
  | --- | --- | --- |
69
93
  | `options` | `ChoiceOptions<O>` | Read only. |
70
94
  | `input` | `ChoiceInputType` | Read only. |
95
+ | `groups` | `ChoiceGroups<O> \| undefined` | Read only. |
71
96
 
72
97
  ## Methods
73
98
 
@@ -9,6 +9,7 @@ Options for `ChoiceSchema`.
9
9
  - `options` — the allowed choices, as a `{ key: title }` dictionary or an array of keys.
10
10
  - `value` — default option used when the input is `undefined`.
11
11
  - `input` — control hint for downstream UIs (radios or a select).
12
+ - `groups` — display hint that puts options under named headings (a select shows each group as an `<optgroup>`).
12
13
 
13
14
  ## Signatures
14
15
 
@@ -17,6 +18,7 @@ Options for `ChoiceSchema`.
17
18
  readonly options: PossibleChoiceOptions<O>;
18
19
  readonly value?: O | I;
19
20
  readonly input?: ChoiceInputType | undefined;
21
+ readonly groups?: ChoiceGroups<O> | undefined;
20
22
  }
21
23
  ```
22
24
 
@@ -27,3 +29,4 @@ Options for `ChoiceSchema`.
27
29
  | `options` | `PossibleChoiceOptions<O>` | Specify correct options using a dictionary of entries. Read only. |
28
30
  | `value` | `O \| I` | Default option for the value. Read only. Optional. |
29
31
  | `input` | `ChoiceInputType \| undefined` | Input control hint for downstream UIs. Read only. Defaults to `"radio" for 8 or fewer options, otherwise "select"`. |
32
+ | `groups` | `ChoiceGroups<O> \| undefined` | Show the options under named headings, as a `{ group: [key] }` dictionary. Options in no group show first. Read only. Optional. |
package/docs/schema.md CHANGED
@@ -190,6 +190,7 @@ QUERY(PERSON).validate({ "address.street": "Main" }); // throws "address.street:
190
190
 
191
191
  - [ChoiceOptions](schema/ChoiceOptions.md): Dictionary of allowed options for a ChoiceSchema in { key: title } format.
192
192
  - [PossibleChoiceOptions](schema/PossibleChoiceOptions.md): Things that can be converted to a ChoiceOptions dictionary.
193
+ - [ChoiceGroups](schema/ChoiceGroups.md): Named groups of option keys for a ChoiceSchema in { group: [key] } format, e.g. { Fruit: ["apple", "pear"] }.
193
194
  - [ChoiceInputType](schema/ChoiceInputType.md): Input control hint for a ChoiceSchema: "radio" for radio inputs, or "select" for a <select>.
194
195
  - [DateInputType](schema/DateInputType.md): type="" prop for HTML <input /> tags that are relevant for dates.
195
196
  - [SchemaOptions](schema/SchemaOptions.md): Options allowed by a Schema instance.
@@ -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. |