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.
- package/docs/llms-full.txt +152 -67
- package/docs/schema/ChoiceGroups.md +21 -0
- package/docs/schema/ChoiceSchema.md +26 -1
- package/docs/schema/ChoiceSchemaOptions.md +3 -0
- package/docs/schema.md +1 -0
- package/docs/ui/RouteCache.md +5 -2
- package/docs/ui/RouteConfig.md +75 -0
- package/docs/ui/RouteConfigProps.md +24 -0
- package/docs/ui/RouteState.md +8 -5
- package/docs/ui/Router.md +1 -1
- package/docs/ui/SelectInput.md +2 -0
- package/docs/ui/SelectProps.md +2 -0
- package/docs/ui.md +3 -3
- package/package.json +1 -1
- package/schema/ChoiceSchema.d.ts +16 -1
- package/schema/ChoiceSchema.js +3 -1
- package/ui/input/Input.test.tsx +33 -1
- package/ui/input/SelectInput.d.ts +4 -1
- package/ui/input/SelectInput.js +13 -2
- package/ui/input/SelectInput.tsx +29 -6
- package/ui/router/RouteCache.d.ts +2 -1
- package/ui/router/RouteCache.js +8 -3
- package/ui/router/RouteCache.md +3 -1
- package/ui/router/RouteCache.tsx +7 -3
- package/ui/router/RouteConfig.d.ts +28 -0
- package/ui/router/RouteConfig.js +30 -0
- package/ui/router/RouteConfig.md +42 -0
- package/ui/router/RouteConfig.tsx +44 -0
- package/ui/router/RouteContext.d.ts +6 -4
- package/ui/router/RouteContext.tsx +6 -4
- package/ui/router/Router.d.ts +1 -1
- package/ui/router/Router.js +4 -4
- package/ui/router/Router.tsx +4 -4
- package/ui/router/index.d.ts +1 -1
- package/ui/router/index.js +1 -1
- package/ui/router/index.ts +1 -1
- package/docs/ui/RoutePath.md +0 -56
- package/docs/ui/RoutePathProps.md +0 -22
- package/ui/router/RoutePath.d.ts +0 -24
- package/ui/router/RoutePath.js +0 -21
- package/ui/router/RoutePath.md +0 -26
- package/ui/router/RoutePath.tsx +0 -34
package/docs/llms-full.txt
CHANGED
|
@@ -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>({
|
|
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
|
-
- [
|
|
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
|
-
- [
|
|
19853
|
-
- [
|
|
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 `<
|
|
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 `<
|
|
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
|
-
#
|
|
31748
|
+
# RouteConfigProps
|
|
31688
31749
|
|
|
31689
31750
|
- Kind: interface
|
|
31690
|
-
- Import: `import {
|
|
31751
|
+
- Import: `import { RouteConfigProps } from "shelving/ui";`
|
|
31691
31752
|
|
|
31692
|
-
|
|
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?:
|
|
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
|
-
#
|
|
31776
|
+
# RouteConfig
|
|
31755
31777
|
|
|
31756
31778
|
- Kind: component
|
|
31757
|
-
- Import: `import {
|
|
31779
|
+
- Import: `import { RouteConfig } from "shelving/ui";`
|
|
31758
31780
|
|
|
31759
|
-
|
|
31760
|
-
- A navigation to a path the page owns keeps the same
|
|
31761
|
-
and a `<ViewTransition>` around the page does not run an enter or
|
|
31762
|
-
|
|
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
|
-
|
|
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
|
|
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,
|
|
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
|
-
<
|
|
31810
|
+
<RouteConfig path={`/${name}/{tab}`}>
|
|
31782
31811
|
<Page title={name}>
|
|
31783
31812
|
<ProfileTabs tab={tab} />
|
|
31784
31813
|
</Page>
|
|
31785
|
-
</
|
|
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
|
-
|
|
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` | `
|
|
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 `<
|
|
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>({
|
|
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.
|
package/docs/ui/RouteCache.md
CHANGED
|
@@ -9,7 +9,8 @@ Keep-alive page cache keyed by the current URL — drop it into a layout around
|
|
|
9
9
|
pages mounted but hidden (via React's `<Activity>`), so navigating back/forward to a page restores its
|
|
10
10
|
entire DOM and component state — scroll position, toggles, searches, inputs, focus — untouched.
|
|
11
11
|
- Pages are kept in a least-recently-used map keyed by `path`; the oldest is unmounted past the limit.
|
|
12
|
-
- A page that owns other paths with `<
|
|
12
|
+
- A page that owns other paths with `<RouteConfig path>` stays mounted when the URL changes to one of them.
|
|
13
|
+
- A page with `<RouteConfig cache={false}>` is dropped as soon as you leave it, so the next visit shows a new page.
|
|
13
14
|
- Each snapshot is frozen under its own `<MetaContext>`, so the same single `children` element resolves a
|
|
14
15
|
different page per path and a hidden page never re-renders for someone else's URL.
|
|
15
16
|
- `<Activity mode="hidden">` preserves a hidden page's state while unmounting its effects, so its
|
|
@@ -26,7 +27,9 @@ Shelving's `<SidebarLayout>` and `<CenteredLayout>` already wrap their scrollabl
|
|
|
26
27
|
**Things to know:**
|
|
27
28
|
|
|
28
29
|
- Pages are kept in a least-recently-used map keyed by `path`. Once `maxCached` pages are retained the least-recently-visited one is unmounted (and loses its state). A never-seen or evicted page mounts fresh at the top.
|
|
29
|
-
- A page can own other paths with `<
|
|
30
|
+
- A page can own other paths with `<RouteConfig path>`, for example its tabs (`/dave/{tab}`). A navigation to one of those paths keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide.
|
|
31
|
+
- A page with `<RouteConfig cache={false}>` is not kept: it unmounts as you leave it, so the next visit starts again. Use it for a form that makes or edits something, so it never shows old input.
|
|
32
|
+
- The cache key is the path only, not the `?query`. So `/new?from=a` and `/new?from=b` are one page.
|
|
30
33
|
- Pass `maxCached={0}` (or less) to disable caching entirely — the page renders directly and unmounts as soon as you leave it.
|
|
31
34
|
- `<Activity mode="hidden">` preserves a hidden page's *state* while unmounting its *effects*, so subscriptions, observers (e.g. infinite-scroll), and timers pause and resume cleanly as the page is hidden and shown.
|
|
32
35
|
- Each snapshot is frozen under its own `<Meta>` context, so the same single `children` element resolves a different page per path and a hidden page never re-renders for someone else's URL.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# RouteConfig
|
|
2
|
+
|
|
3
|
+
- Kind: component
|
|
4
|
+
- Import: `import { RouteConfig } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`).
|
|
7
|
+
- `path` says the page owns every path that matches a template. A navigation to a path the page owns keeps the same
|
|
8
|
+
page mounted, so it keeps its scroll and state, and a `<ViewTransition>` around the page does not run an enter or
|
|
9
|
+
exit. The page updates for the new URL. Use it for a page whose tabs each have their own path: `path="/dave/{tab}"`.
|
|
10
|
+
- Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
|
|
11
|
+
- `cache={false}` makes `<RouteCache>` drop the page when you leave it, so the next visit starts again with no old
|
|
12
|
+
state. Use it for a form that makes or edits something, for example a "New challenge" page.
|
|
13
|
+
|
|
14
|
+
Configure the current page for the surrounding `<Router>` (and `<RouteCache>`, if there is one). It has one prop for each setting, so a page wraps itself in one `<RouteConfig>` for all its settings.
|
|
15
|
+
|
|
16
|
+
- `path` says the page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
|
|
17
|
+
- `cache={false}` tells `<RouteCache>` to drop the page when you leave it. The next visit starts again, with no old state. Use it for a form that makes or edits something, so it never shows old input.
|
|
18
|
+
|
|
19
|
+
**Things to know:**
|
|
20
|
+
|
|
21
|
+
- Without `path`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
|
|
22
|
+
- Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
|
|
23
|
+
- The page still renders for the new URL, so it reads the tab from the URL as usual.
|
|
24
|
+
- The cache key is the path only, not the `?query`. A page that reads its `?query` once (for example `/new?from=123`) should use `cache={false}`, so a visit with another `?query` does not show the old page.
|
|
25
|
+
- It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
import { Page, RouteConfig } from "shelving/ui";
|
|
31
|
+
|
|
32
|
+
// Each tab has its own path, and all of them are the same page.
|
|
33
|
+
function ProfilePage({ name, tab }: { name: string; tab?: string }) {
|
|
34
|
+
return (
|
|
35
|
+
<RouteConfig path={`/${name}/{tab}`}>
|
|
36
|
+
<Page title={name}>
|
|
37
|
+
<ProfileTabs tab={tab} />
|
|
38
|
+
</Page>
|
|
39
|
+
</RouteConfig>
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// A new form on each visit.
|
|
44
|
+
function NewChallengePage({ from }: { from?: string }) {
|
|
45
|
+
return (
|
|
46
|
+
<RouteConfig cache={false}>
|
|
47
|
+
<Page title="New challenge">
|
|
48
|
+
<ChallengeForm from={from} />
|
|
49
|
+
</Page>
|
|
50
|
+
</RouteConfig>
|
|
51
|
+
);
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
## Signatures
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
RouteConfig({ path, cache, children }: RouteConfigProps): ReactNode
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Parameters
|
|
63
|
+
|
|
64
|
+
| Param | Type | Description |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| `props` | `RouteConfigProps` | |
|
|
67
|
+
| `.path` | `AbsolutePath \| undefined` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. Optional. |
|
|
68
|
+
| `.cache` | `boolean \| undefined` | Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. Read only. Optional. |
|
|
69
|
+
| `.children` | `ReactNode` | The page content. Read only. Optional. |
|
|
70
|
+
|
|
71
|
+
## Returns
|
|
72
|
+
|
|
73
|
+
| Type | Description |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `ReactNode` | |
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# RouteConfigProps
|
|
2
|
+
|
|
3
|
+
- Kind: interface
|
|
4
|
+
- Import: `import { RouteConfigProps } from "shelving/ui";`
|
|
5
|
+
|
|
6
|
+
Props for `<RouteConfig>` — the settings of a page for the surrounding `<Router>` and `<RouteCache>`, and the page content.
|
|
7
|
+
|
|
8
|
+
## Signatures
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
{
|
|
12
|
+
readonly path?: AbsolutePath | undefined;
|
|
13
|
+
readonly cache?: boolean | undefined;
|
|
14
|
+
readonly children?: ReactNode;
|
|
15
|
+
}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Properties
|
|
19
|
+
|
|
20
|
+
| Property | Type | Description |
|
|
21
|
+
| --- | --- | --- |
|
|
22
|
+
| `path` | `AbsolutePath \| undefined` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. Optional. |
|
|
23
|
+
| `cache` | `boolean \| undefined` | Set to `false` so `<RouteCache>` drops the page when you leave it, and the next visit shows a new page. Defaults to `true`. Read only. Optional. |
|
|
24
|
+
| `children` | `ReactNode` | The page content. Read only. Optional. |
|