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
@@ -12,7 +12,7 @@ import { RouteContext } from "./RouteContext.js";
12
12
  * - When `base` is set, the effective path is the URL after stripping the base prefix.
13
13
  * - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
14
14
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
15
- * - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RoutePath>` stays mounted when the path changes to one of them.
15
+ * - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RouteConfig path>` stays mounted when the path changes to one of them.
16
16
  * - Returns `null` when there's no URL in context or the URL is outside the base.
17
17
  *
18
18
  * @kind component
@@ -22,14 +22,14 @@ import { RouteContext } from "./RouteContext.js";
22
22
  export function Router({ routes, fallback, ...meta }) {
23
23
  const combined = requireMetaURL(meta);
24
24
  const path = combined;
25
- // Keep the current page when it owns the new path with `<RoutePath>`, else start a new page for this path.
26
- // The top-level router passes the `<RouteCache>` entry on, so `<RoutePath>` in its page also tells the cache.
25
+ // Keep the current page when it owns the new path with `<RouteConfig path>`, else start a new page for this path.
26
+ // The top-level router passes the `<RouteCache>` entry on, so `<RouteConfig>` in its page also tells the cache.
27
27
  const parent = use(RouteContext);
28
28
  const pageRef = useRef(undefined);
29
29
  const prev = pageRef.current;
30
30
  const page = prev && (prev.key === combined.path || (prev.state.path && matchPathTemplate(prev.state.path, combined.path)))
31
31
  ? prev
32
- : { key: combined.path, state: { router: true, cache: parent?.router ? undefined : parent } };
32
+ : { key: combined.path, state: { router: true, entry: parent?.router ? undefined : parent } };
33
33
  pageRef.current = page;
34
34
  const route = _matchRoute(routes, fallback, combined, page.key);
35
35
  if (route)
@@ -30,7 +30,7 @@ export interface RouterProps extends PossibleMeta {
30
30
  * - When `base` is set, the effective path is the URL after stripping the base prefix.
31
31
  * - Nest by putting another `<Router>` inside a route's value; pass `base="/section"` (or wrap in `<Meta>`) to scope.
32
32
  * - Route `{placeholders}` are passed as props to function/component route values along with merged URL `?query` params. They are not published into context — descendants of a `ReactElement`-valued route can't see them automatically.
33
- * - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RoutePath>` stays mounted when the path changes to one of them.
33
+ * - Each path is a new page, so a component route remounts when the path changes. A page that owns other paths with `<RouteConfig path>` stays mounted when the path changes to one of them.
34
34
  * - Returns `null` when there's no URL in context or the URL is outside the base.
35
35
  *
36
36
  * @kind component
@@ -41,15 +41,15 @@ export function Router({ routes, fallback, ...meta }: RouterProps): ReactElement
41
41
  const combined = requireMetaURL(meta);
42
42
  const path = combined;
43
43
 
44
- // Keep the current page when it owns the new path with `<RoutePath>`, else start a new page for this path.
45
- // The top-level router passes the `<RouteCache>` entry on, so `<RoutePath>` in its page also tells the cache.
44
+ // Keep the current page when it owns the new path with `<RouteConfig path>`, else start a new page for this path.
45
+ // The top-level router passes the `<RouteCache>` entry on, so `<RouteConfig>` in its page also tells the cache.
46
46
  const parent = use(RouteContext);
47
47
  const pageRef = useRef<{ key: string; state: RouteState }>(undefined);
48
48
  const prev = pageRef.current;
49
49
  const page =
50
50
  prev && (prev.key === combined.path || (prev.state.path && matchPathTemplate(prev.state.path, combined.path)))
51
51
  ? prev
52
- : { key: combined.path, state: { router: true, cache: parent?.router ? undefined : parent } as RouteState };
52
+ : { key: combined.path, state: { router: true, entry: parent?.router ? undefined : parent } as RouteState };
53
53
  pageRef.current = page;
54
54
 
55
55
  const route = _matchRoute(routes, fallback, combined, page.key);
@@ -2,7 +2,7 @@ export * from "./Navigation.js";
2
2
  export * from "./NavigationContext.js";
3
3
  export * from "./NavigationStore.js";
4
4
  export * from "./RouteCache.js";
5
+ export * from "./RouteConfig.js";
5
6
  export * from "./RouteContext.js";
6
- export * from "./RoutePath.js";
7
7
  export * from "./Router.js";
8
8
  export * from "./Routes.js";
@@ -2,7 +2,7 @@ export * from "./Navigation.js";
2
2
  export * from "./NavigationContext.js";
3
3
  export * from "./NavigationStore.js";
4
4
  export * from "./RouteCache.js";
5
+ export * from "./RouteConfig.js";
5
6
  export * from "./RouteContext.js";
6
- export * from "./RoutePath.js";
7
7
  export * from "./Router.js";
8
8
  export * from "./Routes.js";
@@ -2,7 +2,7 @@ export * from "./Navigation.js";
2
2
  export * from "./NavigationContext.js";
3
3
  export * from "./NavigationStore.js";
4
4
  export * from "./RouteCache.js";
5
+ export * from "./RouteConfig.js";
5
6
  export * from "./RouteContext.js";
6
- export * from "./RoutePath.js";
7
7
  export * from "./Router.js";
8
8
  export * from "./Routes.js";
@@ -1,56 +0,0 @@
1
- # RoutePath
2
-
3
- - Kind: component
4
- - Import: `import { RoutePath } from "shelving/ui";`
5
-
6
- Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
7
- - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
8
- and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
9
- - Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
10
- - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
11
-
12
- Tell the surrounding `<Router>` (and `<RouteCache>`, if there is one) that a page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
13
-
14
- **Things to know:**
15
-
16
- - Without `<RoutePath>`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
17
- - Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
18
- - The page still renders for the new URL, so it reads the tab from the URL as usual.
19
- - It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
20
-
21
- ## Usage
22
-
23
- ```tsx
24
- import { Page, RoutePath } from "shelving/ui";
25
-
26
- function ProfilePage({ name, tab }: { name: string; tab?: string }) {
27
- return (
28
- <RoutePath path={`/${name}/{tab}`}>
29
- <Page title={name}>
30
- <ProfileTabs tab={tab} />
31
- </Page>
32
- </RoutePath>
33
- );
34
- }
35
- ```
36
-
37
-
38
- ## Signatures
39
-
40
- ```ts
41
- RoutePath({ path, children }: RoutePathProps): ReactNode
42
- ```
43
-
44
- ## Parameters
45
-
46
- | Param | Type | Description |
47
- | --- | --- | --- |
48
- | `props` | `RoutePathProps` | |
49
- | `.path` | `AbsolutePath` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. |
50
- | `.children` | `ReactNode` | The page content. Read only. Optional. |
51
-
52
- ## Returns
53
-
54
- | Type | Description |
55
- | --- | --- |
56
- | `ReactNode` | |
@@ -1,22 +0,0 @@
1
- # RoutePathProps
2
-
3
- - Kind: interface
4
- - Import: `import { RoutePathProps } from "shelving/ui";`
5
-
6
- Props for `<RoutePath>` — the path template the page owns, and the page content.
7
-
8
- ## Signatures
9
-
10
- ```ts
11
- {
12
- readonly path: AbsolutePath;
13
- readonly children?: ReactNode;
14
- }
15
- ```
16
-
17
- ## Properties
18
-
19
- | Property | Type | Description |
20
- | --- | --- | --- |
21
- | `path` | `AbsolutePath` | Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. Read only. |
22
- | `children` | `ReactNode` | The page content. Read only. Optional. |
@@ -1,24 +0,0 @@
1
- import { type ReactNode } from "react";
2
- import type { AbsolutePath } from "../../util/path.js";
3
- /**
4
- * Props for `<RoutePath>` — the path template the page owns, and the page content.
5
- *
6
- * @see https://shelving.cc/ui/RoutePathProps
7
- */
8
- export interface RoutePathProps {
9
- /** Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. */
10
- readonly path: AbsolutePath;
11
- /** The page content. */
12
- readonly children?: ReactNode;
13
- }
14
- /**
15
- * Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
16
- * - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
17
- * and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
18
- * - Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
19
- * - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
20
- *
21
- * @kind component
22
- * @see https://shelving.cc/ui/RoutePath
23
- */
24
- export declare function RoutePath({ path, children }: RoutePathProps): ReactNode;
@@ -1,21 +0,0 @@
1
- import { use } from "react";
2
- import { RouteContext } from "./RouteContext.js";
3
- /**
4
- * Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
5
- * - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
6
- * and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
7
- * - Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
8
- * - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
9
- *
10
- * @kind component
11
- * @see https://shelving.cc/ui/RoutePath
12
- */
13
- export function RoutePath({ path, children }) {
14
- const state = use(RouteContext);
15
- if (state) {
16
- state.path = path;
17
- if (state.cache)
18
- state.cache.path = path;
19
- }
20
- return children;
21
- }
@@ -1,26 +0,0 @@
1
- # RoutePath
2
-
3
- Tell the surrounding `<Router>` (and `<RouteCache>`, if there is one) that a page owns every path that matches a template. A navigation between paths the page owns keeps the same page mounted: it keeps its scroll and state, and a `<ViewTransition>` around the page does not slide. Use it for a page whose tabs each have their own path.
4
-
5
- **Things to know:**
6
-
7
- - Without `<RoutePath>`, each path is its own page, so `/challenge/123` and `/challenge/456` stay separate pages.
8
- - Put the real values in the template (`/dave/{tab}`). A template such as `/{name}/{tab}` makes every profile the same page.
9
- - The page still renders for the new URL, so it reads the tab from the URL as usual.
10
- - It works with or without a `<RouteCache>`. In a nested router's page, it tells only that nested router.
11
-
12
- ## Usage
13
-
14
- ```tsx
15
- import { Page, RoutePath } from "shelving/ui";
16
-
17
- function ProfilePage({ name, tab }: { name: string; tab?: string }) {
18
- return (
19
- <RoutePath path={`/${name}/{tab}`}>
20
- <Page title={name}>
21
- <ProfileTabs tab={tab} />
22
- </Page>
23
- </RoutePath>
24
- );
25
- }
26
- ```
@@ -1,34 +0,0 @@
1
- import { type ReactNode, use } from "react";
2
- import type { AbsolutePath } from "../../util/path.js";
3
- import { RouteContext } from "./RouteContext.js";
4
-
5
- /**
6
- * Props for `<RoutePath>` — the path template the page owns, and the page content.
7
- *
8
- * @see https://shelving.cc/ui/RoutePathProps
9
- */
10
- export interface RoutePathProps {
11
- /** Path template the page owns, for example `/dave/{tab}`. Every path that matches it shows this same page. */
12
- readonly path: AbsolutePath;
13
- /** The page content. */
14
- readonly children?: ReactNode;
15
- }
16
-
17
- /**
18
- * Tell the surrounding `<Router>` (and `<RouteCache>`) that this page owns every path that matches a template.
19
- * - A navigation to a path the page owns keeps the same page mounted, so it keeps its scroll and state,
20
- * and a `<ViewTransition>` around the page does not run an enter or exit. The page updates for the new URL.
21
- * - Use it for a page whose tabs each have their own path: `<RoutePath path="/dave/{tab}">`.
22
- * - Put the real values in the template. `/{name}/{tab}` would make every person's profile one page.
23
- *
24
- * @kind component
25
- * @see https://shelving.cc/ui/RoutePath
26
- */
27
- export function RoutePath({ path, children }: RoutePathProps): ReactNode {
28
- const state = use(RouteContext);
29
- if (state) {
30
- state.path = path;
31
- if (state.cache) state.cache.path = path;
32
- }
33
- return children;
34
- }