shelving 1.322.0 → 1.322.2
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/api/APIProvider.md +2 -2
- package/docs/api/CachedAPIProvider.md +6 -8
- package/docs/api/ClientAPIProvider.md +5 -5
- package/docs/api/DebugAPIProvider.md +3 -5
- package/docs/api/HydratingAPIProvider.md +2 -2
- package/docs/api/JSONAPIProvider.md +3 -5
- package/docs/api/LoggingAPIProvider.md +7 -9
- package/docs/api/MockAPIProvider.md +4 -4
- package/docs/api/MockEndpointAPIProvider.md +5 -7
- package/docs/api/ThroughAPIProvider.md +15 -10
- package/docs/api/ValidationAPIProvider.md +3 -5
- package/docs/api/XMLAPIProvider.md +3 -3
- package/docs/api.md +48 -44
- package/docs/bun.md +9 -9
- package/docs/db/DBProvider.md +6 -6
- package/docs/db/MemoryDBProvider.md +3 -3
- package/docs/db/PostgresProvider.md +6 -4
- package/docs/db/SQLProvider.md +6 -3
- package/docs/db/SQLiteProvider.md +9 -4
- package/docs/db/StorageDBProvider.md +2 -2
- package/docs/db/ThroughDBProvider.md +6 -6
- package/docs/db/UndoDBProvider.md +2 -2
- package/docs/db.md +32 -32
- package/docs/error/NetworkError.md +5 -5
- package/docs/error/RequestError.md +4 -4
- package/docs/error/RequiredError.md +2 -2
- package/docs/error/ResponseError.md +1 -1
- package/docs/error/UnexpectedError.md +1 -1
- package/docs/error/UnsupportedError.md +3 -3
- package/docs/error/ValueError.md +2 -2
- package/docs/error.md +20 -19
- package/docs/extract.md +14 -14
- package/docs/firebase.md +6 -6
- package/docs/guides/building-with-shelving.md +113 -85
- package/docs/guides/styleguide.md +29 -29
- package/docs/index.md +3 -2
- package/docs/llms-full.txt +2541 -2295
- package/docs/markup.md +15 -17
- package/docs/react/createAPIContext.md +12 -12
- package/docs/react/createDBContext.md +21 -15
- package/docs/react/useInstance.md +2 -2
- package/docs/react/useLazy.md +1 -1
- package/docs/react/useMap.md +10 -6
- package/docs/react/useReduce.md +2 -2
- package/docs/react/useSequence.md +2 -2
- package/docs/react/useStore.md +10 -10
- package/docs/react.md +22 -16
- package/docs/schema/ArraySchema.md +6 -6
- package/docs/schema/BooleanSchema.md +5 -5
- package/docs/schema/ChoiceSchema.md +1 -1
- package/docs/schema/CurrencyAmountSchema.md +2 -2
- package/docs/schema/DataSchema.md +5 -5
- package/docs/schema/NullableSchema.md +4 -4
- package/docs/schema/NumberSchema.md +4 -4
- package/docs/schema/OptionalSchema.md +1 -1
- package/docs/schema/StringSchema.md +7 -7
- package/docs/schema.md +21 -21
- package/docs/sequence/DeferredSequence.md +1 -1
- package/docs/sequence/InspectSequence.md +8 -6
- package/docs/sequence/LazySequence.md +3 -3
- package/docs/sequence/Sequence.md +6 -6
- package/docs/sequence/ThroughSequence.md +4 -2
- package/docs/sequence.md +3 -3
- package/docs/store/ArrayStore.md +6 -6
- package/docs/store/BooleanStore.md +2 -2
- package/docs/store/BusyStore.md +1 -1
- package/docs/store/DataStore.md +5 -5
- package/docs/store/DictionaryStore.md +4 -4
- package/docs/store/FetchStore.md +6 -6
- package/docs/store/PathStore.md +4 -4
- package/docs/store/PayloadFetchStore.md +1 -5
- package/docs/store/Store.md +8 -6
- package/docs/store/URLStore.md +5 -5
- package/docs/store.md +15 -15
- package/docs/test.md +6 -6
- package/docs/ui/App.md +99 -69
- package/docs/ui/AppLayout.md +35 -26
- package/docs/ui/BackButton.md +13 -11
- package/docs/ui/Button.md +73 -64
- package/docs/ui/Card.md +23 -22
- package/docs/ui/Catcher.md +3 -3
- package/docs/ui/ClassProps.md +1 -1
- package/docs/ui/Code.md +11 -11
- package/docs/ui/CollapseTransition.md +5 -5
- package/docs/ui/Deleted.md +6 -6
- package/docs/ui/Details.md +13 -13
- package/docs/ui/Dialog.md +42 -28
- package/docs/ui/Dialogs.md +4 -0
- package/docs/ui/DocumentationButtons.md +2 -2
- package/docs/ui/DocumentationCard.md +2 -2
- package/docs/ui/DocumentationFrame.md +4 -4
- package/docs/ui/DocumentationLive.md +11 -11
- package/docs/ui/DocumentationPage.md +3 -3
- package/docs/ui/Emphasis.md +4 -4
- package/docs/ui/Empty.md +2 -2
- package/docs/ui/FadeTransition.md +9 -9
- package/docs/ui/Field.md +14 -14
- package/docs/ui/FixedLayout.md +27 -25
- package/docs/ui/Form.md +41 -39
- package/docs/ui/FormStore.md +6 -2
- package/docs/ui/Grid.md +21 -9
- package/docs/ui/HTML.md +10 -8
- package/docs/ui/Head.md +2 -3
- package/docs/ui/Heading.md +12 -12
- package/docs/ui/HorizontalTransition.md +10 -10
- package/docs/ui/Icon.md +4 -4
- package/docs/ui/ImageInput.md +12 -12
- package/docs/ui/Inserted.md +6 -6
- package/docs/ui/Link.md +11 -11
- package/docs/ui/List.md +7 -7
- package/docs/ui/Loading.md +6 -6
- package/docs/ui/Mark.md +11 -9
- package/docs/ui/Markup.md +4 -4
- package/docs/ui/Menu.md +24 -24
- package/docs/ui/MenuItem.md +29 -29
- package/docs/ui/Modal.md +57 -45
- package/docs/ui/Navigation.md +28 -26
- package/docs/ui/NavigationStore.md +18 -18
- package/docs/ui/Notice.md +15 -15
- package/docs/ui/Notices.md +17 -17
- package/docs/ui/Page.md +13 -13
- package/docs/ui/Panel.md +8 -8
- package/docs/ui/Paragraph.md +5 -5
- package/docs/ui/Progress.md +11 -11
- package/docs/ui/Prose.md +6 -6
- package/docs/ui/QueryRadiosInput.md +2 -2
- package/docs/ui/RouteCache.md +27 -27
- package/docs/ui/Router.md +70 -61
- package/docs/ui/SchemaInput.md +20 -20
- package/docs/ui/Scroll.md +16 -16
- package/docs/ui/Section.md +13 -10
- package/docs/ui/SidebarLayout.md +27 -27
- package/docs/ui/Small.md +4 -4
- package/docs/ui/Span.md +3 -1
- package/docs/ui/StackButton.md +13 -7
- package/docs/ui/Strong.md +4 -4
- package/docs/ui/Subheading.md +12 -12
- package/docs/ui/TINT_CLASS.md +11 -11
- package/docs/ui/Table.md +40 -29
- package/docs/ui/Tag.md +15 -15
- package/docs/ui/Title.md +13 -13
- package/docs/ui/Transition.md +22 -22
- package/docs/ui/TreeApp.md +8 -8
- package/docs/ui/TreeMarkup.md +2 -2
- package/docs/ui/TreeMenu.md +3 -3
- package/docs/ui/TreeSidebar.md +1 -1
- package/docs/ui/VerticalTransition.md +8 -8
- package/docs/ui/getClass.md +10 -10
- package/docs/ui/getColorClass.md +23 -23
- package/docs/ui/getDurationClass.md +5 -5
- package/docs/ui/getGridClass.md +2 -2
- package/docs/ui/getHeightClass.md +4 -4
- package/docs/ui/getRadiusClass.md +9 -9
- package/docs/ui/getShadowClass.md +6 -6
- package/docs/ui/getSpaceClass.md +13 -13
- package/docs/ui/getStrokeClass.md +6 -6
- package/docs/ui/getTypographyClass.md +38 -38
- package/docs/ui/getWidthClass.md +4 -4
- package/docs/ui/notify.md +11 -11
- package/docs/ui/requireContext.md +1 -1
- package/docs/ui.md +4 -4
- package/docs/util/array.md +35 -29
- package/docs/util/async.md +2 -2
- package/docs/util/base64.md +7 -7
- package/docs/util/boolean.md +10 -10
- package/docs/util/buffer.md +5 -5
- package/docs/util/bytes.md +9 -9
- package/docs/util/class.md +10 -6
- package/docs/util/color.md +13 -13
- package/docs/util/constants.md +2 -2
- package/docs/util/crypto.md +1 -1
- package/docs/util/currency.md +2 -2
- package/docs/util/data.md +18 -18
- package/docs/util/date.md +22 -22
- package/docs/util/debug/debug.md +12 -12
- package/docs/util/dictionary.md +21 -18
- package/docs/util/diff.md +6 -6
- package/docs/util/dispose/dispose.md +5 -5
- package/docs/util/duration.md +9 -9
- package/docs/util/element.md +1 -1
- package/docs/util/entity.md +6 -6
- package/docs/util/entry.md +21 -8
- package/docs/util/env.md +2 -2
- package/docs/util/equal.md +16 -16
- package/docs/util/error.md +4 -4
- package/docs/util/file.md +8 -8
- package/docs/util/filter.md +9 -5
- package/docs/util/format.md +18 -18
- package/docs/util/function.md +4 -4
- package/docs/util/geo.md +13 -13
- package/docs/util/hash.md +3 -3
- package/docs/util/http.md +1 -1
- package/docs/util/hydrate/hydrate.md +7 -4
- package/docs/util/item.md +4 -4
- package/docs/util/iterate.md +11 -11
- package/docs/util/jwt.md +1 -6
- package/docs/util/link.md +5 -5
- package/docs/util/map.md +17 -11
- package/docs/util/merge.md +2 -5
- package/docs/util/null.md +20 -10
- package/docs/util/number.md +16 -16
- package/docs/util/object.md +25 -22
- package/docs/util/path.md +17 -17
- package/docs/util/query.md +23 -25
- package/docs/util/random.md +7 -7
- package/docs/util/regexp.md +16 -16
- package/docs/util/sequence.md +16 -10
- package/docs/util/serialise/serialise.md +6 -6
- package/docs/util/set.md +10 -10
- package/docs/util/sort.md +10 -11
- package/docs/util/source.md +11 -7
- package/docs/util/start.md +8 -8
- package/docs/util/string.md +14 -14
- package/docs/util/template.md +3 -3
- package/docs/util/timeout.md +5 -5
- package/docs/util/transform.md +6 -6
- package/docs/util/tree.md +13 -13
- package/docs/util/undefined.md +3 -3
- package/docs/util/units.md +15 -15
- package/docs/util/update.md +16 -16
- package/docs/util/uri.md +12 -12
- package/docs/util/url.md +11 -11
- package/docs/util/uuid.md +3 -3
- package/docs/util/validate.md +14 -9
- package/package.json +3 -3
- package/skills/shelving/SKILL.md +1 -0
- package/ui/README.md +4 -4
- package/ui/app/App.md +99 -69
- package/ui/block/Card.md +23 -22
- package/ui/block/Details.md +13 -13
- package/ui/block/Grid.md +21 -9
- package/ui/block/Heading.md +12 -12
- package/ui/block/List.md +7 -7
- package/ui/block/Panel.md +8 -8
- package/ui/block/Paragraph.md +5 -5
- package/ui/block/Prose.md +6 -6
- package/ui/block/Section.md +13 -10
- package/ui/block/Subheading.md +12 -12
- package/ui/block/Title.md +13 -13
- package/ui/button/Button.md +73 -64
- package/ui/dialog/Dialog.md +42 -28
- package/ui/dialog/Dialogs.d.ts +4 -0
- package/ui/dialog/Dialogs.js +4 -0
- package/ui/dialog/Dialogs.tsx +4 -0
- package/ui/dialog/Modal.md +57 -45
- package/ui/docs/DocumentationButtons.md +2 -2
- package/ui/docs/DocumentationCard.md +2 -2
- package/ui/docs/DocumentationFrame.md +4 -4
- package/ui/docs/DocumentationLive.md +11 -11
- package/ui/docs/DocumentationPage.md +3 -3
- package/ui/form/Field.md +14 -14
- package/ui/form/Form.md +41 -39
- package/ui/form/FormStore.md +6 -2
- package/ui/form/Progress.md +11 -11
- package/ui/inline/Code.md +11 -11
- package/ui/inline/Deleted.md +6 -6
- package/ui/inline/Emphasis.md +4 -4
- package/ui/inline/Inserted.md +6 -6
- package/ui/inline/Link.md +11 -11
- package/ui/inline/Mark.md +11 -9
- package/ui/inline/Small.md +4 -4
- package/ui/inline/Span.md +3 -1
- package/ui/inline/Strong.md +4 -4
- package/ui/input/ImageInput.md +12 -12
- package/ui/input/QueryRadiosInput.md +2 -2
- package/ui/input/SchemaInput.md +20 -20
- package/ui/layout/AppLayout.md +35 -26
- package/ui/layout/AppLayout.module.css +3 -16
- package/ui/layout/FixedLayout.md +27 -25
- package/ui/layout/SidebarLayout.md +27 -27
- package/ui/layout/SidebarLayout.module.css +1 -0
- package/ui/menu/Menu.md +24 -24
- package/ui/menu/MenuItem.md +29 -29
- package/ui/misc/Catcher.md +3 -3
- package/ui/misc/Icon.md +4 -4
- package/ui/misc/Loading.md +6 -6
- package/ui/misc/Markup.md +4 -4
- package/ui/misc/Tag.md +15 -15
- package/ui/notice/Empty.md +2 -2
- package/ui/notice/Notice.md +15 -15
- package/ui/notice/Notices.md +17 -17
- package/ui/page/HTML.md +10 -8
- package/ui/page/Head.md +2 -3
- package/ui/page/Page.md +13 -13
- package/ui/router/BackButton.md +13 -11
- package/ui/router/Navigation.md +28 -26
- package/ui/router/NavigationStore.md +18 -18
- package/ui/router/RouteCache.md +27 -27
- package/ui/router/Router.md +70 -61
- package/ui/router/StackButton.md +13 -7
- package/ui/style/Scroll.md +16 -16
- package/ui/style/TINT_CLASS.md +11 -11
- package/ui/style/getColorClass.md +23 -23
- package/ui/style/getDurationClass.md +5 -5
- package/ui/style/getGridClass.md +2 -2
- package/ui/style/getHeightClass.md +4 -4
- package/ui/style/getRadiusClass.md +9 -9
- package/ui/style/getShadowClass.md +6 -6
- package/ui/style/getSpaceClass.md +13 -13
- package/ui/style/getStrokeClass.md +6 -6
- package/ui/style/getTypographyClass.md +38 -38
- package/ui/style/getWidthClass.md +4 -4
- package/ui/table/Table.md +40 -30
- package/ui/transition/CollapseTransition.md +5 -5
- package/ui/transition/FadeTransition.md +9 -9
- package/ui/transition/HorizontalTransition.md +10 -10
- package/ui/transition/Transition.md +22 -22
- package/ui/transition/VerticalTransition.md +8 -8
- package/ui/tree/TreeApp.md +8 -8
- package/ui/tree/TreeMarkup.md +2 -2
- package/ui/tree/TreeMenu.md +3 -3
- package/ui/tree/TreeSidebar.md +1 -1
- package/ui/util/ClassProps.md +1 -1
- package/ui/util/getClass.md +10 -10
- package/ui/util/notify.md +11 -11
- package/ui/util/requireContext.md +1 -1
package/docs/markup.md
CHANGED
|
@@ -61,21 +61,21 @@ const node = MARKUP_PARSER.parse(source);
|
|
|
61
61
|
|
|
62
62
|
`MarkupParser` is constructed with `MarkupOptions`:
|
|
63
63
|
|
|
64
|
-
| Option
|
|
65
|
-
|
|
66
|
-
| `rules`
|
|
67
|
-
| `rel`
|
|
68
|
-
| `url`
|
|
69
|
-
| `root`
|
|
70
|
-
| `schemes` | `URISchemes`
|
|
71
|
-
| `context` | `string`
|
|
64
|
+
| Option | Type | Description |
|
|
65
|
+
| --------- | -------------- | ---------------------------------------------------------------------- |
|
|
66
|
+
| `rules` | `MarkupRules` | Rules to apply. Defaults to `MARKUP_RULES` (all block + inline rules). |
|
|
67
|
+
| `rel` | `string` | `rel` attribute applied to every rendered link, e.g. `"nofollow ugc"`. |
|
|
68
|
+
| `url` | `ImmutableURL` | Current page URL — base for resolving relative refs (`./foo`, `#x`). |
|
|
69
|
+
| `root` | `ImmutableURL` | Site root URL — base for resolving site-absolute paths (`/foo`). |
|
|
70
|
+
| `schemes` | `URISchemes` | Allowed URI schemes for links. Defaults to `["http:", "https:"]`. |
|
|
71
|
+
| `context` | `string` | Default starting context. Defaults to `"block"`. |
|
|
72
72
|
|
|
73
73
|
```ts
|
|
74
74
|
const parser = new MarkupParser({
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
75
|
+
rel: "nofollow ugc",
|
|
76
|
+
url: requireURL("https://example.com/page/"),
|
|
77
|
+
root: requireURL("https://example.com/"),
|
|
78
|
+
schemes: ["http:", "https:", "mailto:"],
|
|
79
79
|
});
|
|
80
80
|
```
|
|
81
81
|
|
|
@@ -99,11 +99,9 @@ Build custom rules with `createMarkupRule()` and combine them with the defaults:
|
|
|
99
99
|
```tsx
|
|
100
100
|
import { createMarkupRule, MARKUP_RULES, MarkupParser } from "shelving/markup";
|
|
101
101
|
|
|
102
|
-
const HIGHLIGHT_RULE = createMarkupRule<{ text: string }>(
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
["inline"],
|
|
106
|
-
);
|
|
102
|
+
const HIGHLIGHT_RULE = createMarkupRule<{ text: string }>(/==(?<text>[^=]+)==/, (key, { text }) => <mark key={key}>{text}</mark>, [
|
|
103
|
+
"inline",
|
|
104
|
+
]);
|
|
107
105
|
|
|
108
106
|
const parser = new MarkupParser({ rules: [...MARKUP_RULES, HIGHLIGHT_RULE] });
|
|
109
107
|
```
|
|
@@ -26,21 +26,21 @@ const provider = new ValidationAPIProvider(new ClientAPIProvider({ url: "https:/
|
|
|
26
26
|
const { APIContext, useAPI } = createAPIContext(provider);
|
|
27
27
|
|
|
28
28
|
function UserCard({ id }: { id: string }) {
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
29
|
+
const store = useAPI(getUser, { id }); // Returns an EndpointStore; component suspends while loading.
|
|
30
|
+
const user = store.value;
|
|
31
|
+
return <div>{user.name}</div>;
|
|
32
32
|
}
|
|
33
33
|
|
|
34
34
|
function App() {
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
35
|
+
return (
|
|
36
|
+
<APIContext>
|
|
37
|
+
<ErrorBoundary fallback={<p>Error</p>}>
|
|
38
|
+
<Suspense fallback={<p>Loading...</p>}>
|
|
39
|
+
<UserCard id="u_123" />
|
|
40
|
+
</Suspense>
|
|
41
|
+
</ErrorBoundary>
|
|
42
|
+
</APIContext>
|
|
43
|
+
);
|
|
44
44
|
}
|
|
45
45
|
```
|
|
46
46
|
|
|
@@ -20,27 +20,33 @@ import { createDBContext } from "shelving/react";
|
|
|
20
20
|
const { DBContext, useItem, useQuery } = createDBContext(dbProvider);
|
|
21
21
|
|
|
22
22
|
function UserCard({ id }: { id: string }) {
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
23
|
+
const store = useItem(Users, id); // ItemStore — suspends while loading.
|
|
24
|
+
const user = store.value;
|
|
25
|
+
return <div>{user.name}</div>;
|
|
26
26
|
}
|
|
27
27
|
|
|
28
28
|
function UserList() {
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
29
|
+
const store = useQuery(Users, { $order: "name" }); // QueryStore.
|
|
30
|
+
const users = store.value;
|
|
31
|
+
return (
|
|
32
|
+
<ul>
|
|
33
|
+
{users.map(u => (
|
|
34
|
+
<li key={u.id}>{u.name}</li>
|
|
35
|
+
))}
|
|
36
|
+
</ul>
|
|
37
|
+
);
|
|
32
38
|
}
|
|
33
39
|
|
|
34
40
|
function App() {
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
41
|
+
return (
|
|
42
|
+
<DBContext>
|
|
43
|
+
<ErrorBoundary fallback={<p>Error</p>}>
|
|
44
|
+
<Suspense fallback={<p>Loading...</p>}>
|
|
45
|
+
<UserList />
|
|
46
|
+
</Suspense>
|
|
47
|
+
</ErrorBoundary>
|
|
48
|
+
</DBContext>
|
|
49
|
+
);
|
|
44
50
|
}
|
|
45
51
|
```
|
|
46
52
|
|
|
@@ -18,8 +18,8 @@ import { useInstance } from "shelving/react";
|
|
|
18
18
|
import { APICache } from "shelving/api";
|
|
19
19
|
|
|
20
20
|
function MyComponent({ provider }: { provider: APIProvider }) {
|
|
21
|
-
|
|
22
|
-
|
|
21
|
+
const cache = useInstance(APICache, provider); // Stable across renders.
|
|
22
|
+
// ...rebuilt only when `provider` changes.
|
|
23
23
|
}
|
|
24
24
|
```
|
|
25
25
|
|
package/docs/react/useLazy.md
CHANGED
|
@@ -16,7 +16,7 @@ Compute a value once and recompute it only when its arguments change (by deep eq
|
|
|
16
16
|
```tsx
|
|
17
17
|
import { useLazy } from "shelving/react";
|
|
18
18
|
|
|
19
|
-
const sorted = useLazy(
|
|
19
|
+
const sorted = useLazy(items => [...items].sort(), items);
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
The result is recomputed only when `items` changes. Because arguments are compared by deep equality, a value that is equal-but-not-identical across renders does not trigger recomputation.
|
package/docs/react/useMap.md
CHANGED
|
@@ -16,12 +16,16 @@ Create a mutable `Map` that persists for the lifetime of the component. The same
|
|
|
16
16
|
import { useMap } from "shelving/react";
|
|
17
17
|
|
|
18
18
|
function Gallery({ ids }: { ids: string[] }) {
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
19
|
+
const seen = useMap<string, boolean>(); // Same Map on every render.
|
|
20
|
+
return (
|
|
21
|
+
<>
|
|
22
|
+
{ids.map(id => {
|
|
23
|
+
const isNew = !seen.has(id);
|
|
24
|
+
seen.set(id, true);
|
|
25
|
+
return <Thumbnail key={id} id={id} highlight={isNew} />;
|
|
26
|
+
})}
|
|
27
|
+
</>
|
|
28
|
+
);
|
|
25
29
|
}
|
|
26
30
|
```
|
|
27
31
|
|
package/docs/react/useReduce.md
CHANGED
|
@@ -22,8 +22,8 @@ import { useReduce } from "shelving/react";
|
|
|
22
22
|
import { isDeepEqual } from "shelving/util";
|
|
23
23
|
|
|
24
24
|
const stable = useReduce((prev, next) => {
|
|
25
|
-
|
|
26
|
-
|
|
25
|
+
if (prev && isDeepEqual(prev, next)) return prev; // Preserve reference if equal.
|
|
26
|
+
return next;
|
|
27
27
|
}, incoming);
|
|
28
28
|
```
|
|
29
29
|
|
|
@@ -16,8 +16,8 @@ The return value is `undefined` until the first emission. If the sequence throws
|
|
|
16
16
|
import { useSequence } from "shelving/react";
|
|
17
17
|
|
|
18
18
|
function LiveCounter({ counter }: { counter: AsyncIterable<number> }) {
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
const count = useSequence(counter); // undefined until first emission.
|
|
20
|
+
return <span>{count ?? "—"}</span>;
|
|
21
21
|
}
|
|
22
22
|
```
|
|
23
23
|
|
package/docs/react/useStore.md
CHANGED
|
@@ -20,19 +20,19 @@ import { Suspense } from "react";
|
|
|
20
20
|
import { useStore } from "shelving/react";
|
|
21
21
|
|
|
22
22
|
function UserCard({ store }: { store: Store<User> }) {
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
23
|
+
useStore(store); // Subscribe — re-renders when the store updates.
|
|
24
|
+
const user = store.value; // Throws Promise (loading) or reason (error).
|
|
25
|
+
return <div>{user.name}</div>;
|
|
26
26
|
}
|
|
27
27
|
|
|
28
28
|
function App() {
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
29
|
+
return (
|
|
30
|
+
<ErrorBoundary fallback={<p>Something went wrong.</p>}>
|
|
31
|
+
<Suspense fallback={<p>Loading...</p>}>
|
|
32
|
+
<UserCard store={userStore} />
|
|
33
|
+
</Suspense>
|
|
34
|
+
</ErrorBoundary>
|
|
35
|
+
);
|
|
36
36
|
}
|
|
37
37
|
```
|
|
38
38
|
|
package/docs/react.md
CHANGED
|
@@ -34,25 +34,31 @@ import { createDBContext } from "shelving/react";
|
|
|
34
34
|
const { DBContext, useItem, useQuery } = createDBContext(dbProvider);
|
|
35
35
|
|
|
36
36
|
function UserCard({ id }: { id: string }) {
|
|
37
|
-
|
|
38
|
-
|
|
37
|
+
const user = useItem(Users, id).value; // Suspends while loading.
|
|
38
|
+
return <li>{user.name}</li>;
|
|
39
39
|
}
|
|
40
40
|
|
|
41
41
|
function UserList() {
|
|
42
|
-
|
|
43
|
-
|
|
42
|
+
const users = useQuery(Users, { $order: "name" }).value;
|
|
43
|
+
return (
|
|
44
|
+
<ul>
|
|
45
|
+
{users.map(u => (
|
|
46
|
+
<UserCard key={u.id} id={u.id} />
|
|
47
|
+
))}
|
|
48
|
+
</ul>
|
|
49
|
+
);
|
|
44
50
|
}
|
|
45
51
|
|
|
46
52
|
function App() {
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
53
|
+
return (
|
|
54
|
+
<DBContext>
|
|
55
|
+
<ErrorBoundary fallback={<p>Something went wrong.</p>}>
|
|
56
|
+
<Suspense fallback={<p>Loading…</p>}>
|
|
57
|
+
<UserList />
|
|
58
|
+
</Suspense>
|
|
59
|
+
</ErrorBoundary>
|
|
60
|
+
</DBContext>
|
|
61
|
+
);
|
|
56
62
|
}
|
|
57
63
|
```
|
|
58
64
|
|
|
@@ -65,9 +71,9 @@ import { useInstance, useStore } from "shelving/react";
|
|
|
65
71
|
import { BooleanStore } from "shelving/store";
|
|
66
72
|
|
|
67
73
|
function Toggle() {
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
74
|
+
const open = useInstance(BooleanStore); // Created once, stable across renders.
|
|
75
|
+
useStore(open); // Re-render whenever the store changes.
|
|
76
|
+
return <button onClick={() => open.toggle()}>{open.value ? "Open" : "Closed"}</button>;
|
|
71
77
|
}
|
|
72
78
|
```
|
|
73
79
|
|
|
@@ -19,14 +19,14 @@ Validates a value into a `readonly` array, validating each element against an `i
|
|
|
19
19
|
import { ARRAY, STRING, NUMBER } from "shelving/schema";
|
|
20
20
|
|
|
21
21
|
const TAGS = ARRAY(STRING);
|
|
22
|
-
TAGS.validate(["a", "b"]);
|
|
23
|
-
TAGS.validate("a,b,c");
|
|
24
|
-
TAGS.validate(undefined);
|
|
22
|
+
TAGS.validate(["a", "b"]); // ["a", "b"]
|
|
23
|
+
TAGS.validate("a,b,c"); // ["a", "b", "c"] (split on comma)
|
|
24
|
+
TAGS.validate(undefined); // []
|
|
25
25
|
|
|
26
26
|
const NUMBERS = ARRAY(NUMBER);
|
|
27
|
-
NUMBERS.validate([1, 2]);
|
|
28
|
-
NUMBERS.validate("1,2,3");
|
|
29
|
-
NUMBERS.validate(undefined);
|
|
27
|
+
NUMBERS.validate([1, 2]); // [1, 2]
|
|
28
|
+
NUMBERS.validate("1,2,3"); // [1, 2, 3] (split on comma, each coerced)
|
|
29
|
+
NUMBERS.validate(undefined); // []
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
|
|
@@ -22,11 +22,11 @@ To save creating a new instance of `BooleanSchema` for trivial uses, you can use
|
|
|
22
22
|
```ts
|
|
23
23
|
import { BOOLEAN } from "shelving/schema";
|
|
24
24
|
|
|
25
|
-
BOOLEAN.validate(true);
|
|
26
|
-
BOOLEAN.validate("false");
|
|
27
|
-
BOOLEAN.validate("no");
|
|
28
|
-
BOOLEAN.validate(1);
|
|
29
|
-
BOOLEAN.validate(undefined);
|
|
25
|
+
BOOLEAN.validate(true); // true
|
|
26
|
+
BOOLEAN.validate("false"); // false (coerced)
|
|
27
|
+
BOOLEAN.validate("no"); // false (coerced)
|
|
28
|
+
BOOLEAN.validate(1); // true (truthiness)
|
|
29
|
+
BOOLEAN.validate(undefined); // false (default)
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
|
|
@@ -21,7 +21,7 @@ import { CHOICE } from "shelving/schema";
|
|
|
21
21
|
// Array form — keys and labels are the same.
|
|
22
22
|
const STATUS = CHOICE(["draft", "published", "archived"] as const);
|
|
23
23
|
STATUS.validate("published"); // "published"
|
|
24
|
-
STATUS.validate("deleted");
|
|
24
|
+
STATUS.validate("deleted"); // throws "Unknown value"
|
|
25
25
|
|
|
26
26
|
// Object form — keys are validated values, object values are display labels.
|
|
27
27
|
const Priority = CHOICE({ low: "Low priority", high: "High priority" });
|
|
@@ -19,8 +19,8 @@ A `NumberSchema` subclass for monetary amounts. It rounds to the currency's mino
|
|
|
19
19
|
import { CurrencyAmountSchema } from "shelving/schema";
|
|
20
20
|
|
|
21
21
|
const PRICE = new CurrencyAmountSchema({ title: "Price", currency: "GBP", min: 0 });
|
|
22
|
-
PRICE.validate("12.345");
|
|
23
|
-
PRICE.format(12.3);
|
|
22
|
+
PRICE.validate("12.345"); // 12.35 (rounded to minor units)
|
|
23
|
+
PRICE.format(12.3); // "£12.30"
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
|
|
@@ -21,9 +21,9 @@ When several properties fail, the errors are joined by `\n` with each field name
|
|
|
21
21
|
import { DATA, BOOLEAN, StringSchema, NumberSchema } from "shelving/schema";
|
|
22
22
|
|
|
23
23
|
const PRODUCT = DATA({
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
24
|
+
name: new StringSchema({ title: "Name", min: 1, max: 100 }),
|
|
25
|
+
price: new NumberSchema({ title: "Price", min: 0 }),
|
|
26
|
+
available: BOOLEAN,
|
|
27
27
|
});
|
|
28
28
|
|
|
29
29
|
PRODUCT.validate({ name: "Widget", price: 9.99, available: true });
|
|
@@ -48,8 +48,8 @@ const NameOnly = PRODUCT.pick("name");
|
|
|
48
48
|
import { ITEM, STRING, INTEGER, NUMBER } from "shelving/schema";
|
|
49
49
|
|
|
50
50
|
const PRODUCT_ITEM = ITEM(INTEGER, {
|
|
51
|
-
|
|
52
|
-
|
|
51
|
+
name: STRING,
|
|
52
|
+
price: NUMBER,
|
|
53
53
|
}); // Validates: { id: number, name: string, price: number }
|
|
54
54
|
```
|
|
55
55
|
|
|
@@ -19,10 +19,10 @@ Wraps another schema to allow `null` as a valid value. Following the robustness
|
|
|
19
19
|
import { NULLABLE, NUMBER } from "shelving/schema";
|
|
20
20
|
|
|
21
21
|
const NULLABLE_NUMBER = NULLABLE(NUMBER);
|
|
22
|
-
NULLABLE_NUMBER.validate(null);
|
|
23
|
-
NULLABLE_NUMBER.validate(undefined);
|
|
24
|
-
NULLABLE_NUMBER.validate("");
|
|
25
|
-
NULLABLE_NUMBER.validate(42);
|
|
22
|
+
NULLABLE_NUMBER.validate(null); // null
|
|
23
|
+
NULLABLE_NUMBER.validate(undefined); // null
|
|
24
|
+
NULLABLE_NUMBER.validate(""); // null
|
|
25
|
+
NULLABLE_NUMBER.validate(42); // 42
|
|
26
26
|
```
|
|
27
27
|
|
|
28
28
|
|
|
@@ -22,8 +22,8 @@ To save creating a new instance of `NumberSchema` for trivial uses, you can use
|
|
|
22
22
|
```ts
|
|
23
23
|
import { NUMBER } from "shelving/schema";
|
|
24
24
|
|
|
25
|
-
NUMBER.validate("3.14");
|
|
26
|
-
NUMBER.validate(undefined);
|
|
25
|
+
NUMBER.validate("3.14"); // 3.14 (strings coerced)
|
|
26
|
+
NUMBER.validate(undefined); // 0 (default)
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
### Custom number schemas
|
|
@@ -34,8 +34,8 @@ Construct a `NumberSchema` to apply range and step constraints:
|
|
|
34
34
|
import { NumberSchema } from "shelving/schema";
|
|
35
35
|
|
|
36
36
|
const RATING = new NumberSchema({ title: "Rating", min: 1, max: 5, step: 1 });
|
|
37
|
-
RATING.validate(3);
|
|
38
|
-
RATING.validate(0);
|
|
37
|
+
RATING.validate(3); // 3
|
|
38
|
+
RATING.validate(0); // throws "Minimum 1"
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
|
|
@@ -22,10 +22,10 @@ To save creating a new instance of `StringSchema` for trivial uses, you can use
|
|
|
22
22
|
```ts
|
|
23
23
|
import { STRING, REQUIRED_STRING } from "shelving/schema";
|
|
24
24
|
|
|
25
|
-
STRING.validate("hello");
|
|
26
|
-
STRING.validate(42);
|
|
27
|
-
STRING.validate(undefined);
|
|
28
|
-
REQUIRED_STRING.validate("");
|
|
25
|
+
STRING.validate("hello"); // "hello"
|
|
26
|
+
STRING.validate(42); // "42" (numbers coerced)
|
|
27
|
+
STRING.validate(undefined); // "" (default)
|
|
28
|
+
REQUIRED_STRING.validate(""); // throws "Required"
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
### Custom string schemas
|
|
@@ -36,9 +36,9 @@ Construct a `StringSchema` to apply length and pattern constraints:
|
|
|
36
36
|
import { StringSchema } from "shelving/schema";
|
|
37
37
|
|
|
38
38
|
const USERNAME = new StringSchema({ title: "Username", min: 3, max: 20, match: /^[a-z0-9_]+$/ });
|
|
39
|
-
USERNAME.validate("alice_99");
|
|
40
|
-
USERNAME.validate("al");
|
|
41
|
-
USERNAME.validate("ALICE");
|
|
39
|
+
USERNAME.validate("alice_99"); // "alice_99"
|
|
40
|
+
USERNAME.validate("al"); // throws "Minimum 3 characters"
|
|
41
|
+
USERNAME.validate("ALICE"); // throws "Invalid string"
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
|
package/docs/schema.md
CHANGED
|
@@ -29,35 +29,35 @@ Schema functionality in Shelving follows the **robustness principle**: "be conse
|
|
|
29
29
|
|
|
30
30
|
Every schema carries optional display metadata set at construction time:
|
|
31
31
|
|
|
32
|
-
| Property
|
|
33
|
-
|
|
|
32
|
+
| Property | Default | Purpose |
|
|
33
|
+
| -------------------- | --------------- | ------------------------------------------------- |
|
|
34
34
|
| `Schema.one` | `"value"` | Singular noun, e.g. `"product"` |
|
|
35
35
|
| `Schema.many` | `one + "s"` | Plural noun, e.g. `"products"` |
|
|
36
36
|
| `Schema.title` | `""` | Human-readable label for a field |
|
|
37
37
|
| `Schema.description` | `""` | Longer description for a field |
|
|
38
38
|
| `Schema.placeholder` | `""` | Placeholder text for an input |
|
|
39
39
|
| `Schema.value` | schema-specific | Default used when `validate(undefined)` is called |
|
|
40
|
-
| `Schema.format()`
|
|
40
|
+
| `Schema.format()` | schema-specific | Display formatter for downstream form and UI use |
|
|
41
41
|
|
|
42
42
|
### Sugar instances and factories
|
|
43
43
|
|
|
44
44
|
For convenience the `shelving/schema` module offers sugar constants and factories to improve the readability of code that creates complex schemas. Sugar instances are pre-instantiated copies of `Schema` classes — by convention an instantiated schema is named in `ALL_CAPS`, a convention you will find it convenient to use in your own codebase too. Sugar factories are functions like `OPTIONAL()` and `DATA()` that build a configured schema for you.
|
|
45
45
|
|
|
46
46
|
| Sugar instance / factory | Validated type |
|
|
47
|
-
|
|
|
48
|
-
| `STRING`
|
|
49
|
-
| `NUMBER`
|
|
50
|
-
| `CURRENCY_AMOUNT(code)`
|
|
51
|
-
| `BOOLEAN`
|
|
52
|
-
| `DATA(props)`
|
|
53
|
-
| `ARRAY(itemSchema)`
|
|
54
|
-
| `CHOICE(options)`
|
|
55
|
-
| `NULLABLE(schema)`
|
|
56
|
-
| `OPTIONAL(schema)`
|
|
57
|
-
| `PARTIAL(schema)`
|
|
58
|
-
| `ITEM(idSchema, props)`
|
|
59
|
-
| `UPDATES(dataSchema)`
|
|
60
|
-
| `QUERY(dataSchema)`
|
|
47
|
+
| ------------------------ | -------------------- |
|
|
48
|
+
| `STRING` | `string` |
|
|
49
|
+
| `NUMBER` | `number` |
|
|
50
|
+
| `CURRENCY_AMOUNT(code)` | `number` |
|
|
51
|
+
| `BOOLEAN` | `boolean` |
|
|
52
|
+
| `DATA(props)` | `T` (plain object) |
|
|
53
|
+
| `ARRAY(itemSchema)` | `readonly T[]` |
|
|
54
|
+
| `CHOICE(options)` | union of string keys |
|
|
55
|
+
| `NULLABLE(schema)` | `T \| null` |
|
|
56
|
+
| `OPTIONAL(schema)` | `T \| undefined` |
|
|
57
|
+
| `PARTIAL(schema)` | `Partial<T>` |
|
|
58
|
+
| `ITEM(idSchema, props)` | `{ id: I } & T` |
|
|
59
|
+
| `UPDATES(dataSchema)` | `Updates<T>` |
|
|
60
|
+
| `QUERY(dataSchema)` | `Query<T>` |
|
|
61
61
|
|
|
62
62
|
## Usage
|
|
63
63
|
|
|
@@ -67,10 +67,10 @@ Schemas compose: primitives, wrappers (`NULLABLE()`, `OPTIONAL()`, `ARRAY()`), a
|
|
|
67
67
|
import { ITEM, STRING, REQUIRED_STRING, NUMBER, ARRAY, OPTIONAL, INTEGER } from "shelving/schema";
|
|
68
68
|
|
|
69
69
|
const PRODUCT = ITEM(INTEGER, {
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
70
|
+
name: REQUIRED_STRING,
|
|
71
|
+
price: NUMBER,
|
|
72
|
+
tags: ARRAY(STRING),
|
|
73
|
+
notes: OPTIONAL(STRING),
|
|
74
74
|
});
|
|
75
75
|
|
|
76
76
|
PRODUCT.validate({ id: 1, name: "Widget", price: 9.99, tags: "a,b" });
|
|
@@ -17,18 +17,20 @@ Useful in tests and diagnostics when you need to assert on what a sequence produ
|
|
|
17
17
|
import { InspectSequence } from "shelving/sequence";
|
|
18
18
|
|
|
19
19
|
async function* numbers() {
|
|
20
|
-
|
|
20
|
+
yield 10;
|
|
21
|
+
yield 20;
|
|
22
|
+
yield 30;
|
|
21
23
|
}
|
|
22
24
|
|
|
23
25
|
const watch = new InspectSequence(numbers());
|
|
24
26
|
for await (const n of watch) {
|
|
25
|
-
|
|
27
|
+
console.log("yielded", n);
|
|
26
28
|
}
|
|
27
29
|
|
|
28
|
-
console.log(watch.count);
|
|
29
|
-
console.log(watch.first);
|
|
30
|
-
console.log(watch.last);
|
|
31
|
-
console.log(watch.done);
|
|
30
|
+
console.log(watch.count); // 3
|
|
31
|
+
console.log(watch.first); // 10
|
|
32
|
+
console.log(watch.last); // 30
|
|
33
|
+
console.log(watch.done); // true
|
|
32
34
|
```
|
|
33
35
|
|
|
34
36
|
`first`, `last`, and `returned` throw an `UnexpectedError` if read before the relevant values exist — e.g. `first` before iteration has yielded anything, or `returned` before iteration is `done`.
|
|
@@ -20,12 +20,12 @@ import { DeferredSequence, LazySequence } from "shelving/sequence";
|
|
|
20
20
|
const deferred = new DeferredSequence<number>();
|
|
21
21
|
|
|
22
22
|
const seq = new LazySequence(deferred, () => {
|
|
23
|
-
|
|
24
|
-
|
|
23
|
+
const id = setInterval(() => deferred.resolve(Date.now()), 500);
|
|
24
|
+
return () => clearInterval(id); // StopCallback — runs when the last iterator finishes.
|
|
25
25
|
});
|
|
26
26
|
|
|
27
27
|
for await (const ts of seq) {
|
|
28
|
-
|
|
28
|
+
console.log(ts); // the interval runs only for the duration of this loop
|
|
29
29
|
}
|
|
30
30
|
```
|
|
31
31
|
|
|
@@ -24,12 +24,12 @@ Unlike a generator, a `Sequence` places no one-shot constraint on iteration —
|
|
|
24
24
|
import { Sequence } from "shelving/sequence";
|
|
25
25
|
|
|
26
26
|
class CountdownSequence extends Sequence<number, void, void> {
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
27
|
+
constructor(private n: number) {
|
|
28
|
+
super();
|
|
29
|
+
}
|
|
30
|
+
async next() {
|
|
31
|
+
return this.n > 0 ? { done: false as const, value: this.n-- } : { done: true as const, value: undefined };
|
|
32
|
+
}
|
|
33
33
|
}
|
|
34
34
|
```
|
|
35
35
|
|
|
@@ -18,12 +18,14 @@ Wraps a source `AsyncIterator` and presents it as a full `Sequence`. Use it to t
|
|
|
18
18
|
import { ThroughSequence } from "shelving/sequence";
|
|
19
19
|
|
|
20
20
|
async function* numbers() {
|
|
21
|
-
|
|
21
|
+
yield 1;
|
|
22
|
+
yield 2;
|
|
23
|
+
yield 3;
|
|
22
24
|
}
|
|
23
25
|
|
|
24
26
|
const seq = new ThroughSequence(numbers());
|
|
25
27
|
for await (const n of seq) {
|
|
26
|
-
|
|
28
|
+
console.log(n); // 1, 2, 3
|
|
27
29
|
}
|
|
28
30
|
```
|
|
29
31
|
|
package/docs/sequence.md
CHANGED
|
@@ -30,12 +30,12 @@ const deferred = new DeferredSequence<number>();
|
|
|
30
30
|
|
|
31
31
|
// The interval starts on the first `for await` and stops when the last one ends.
|
|
32
32
|
const clock = new LazySequence(deferred, () => {
|
|
33
|
-
|
|
34
|
-
|
|
33
|
+
const id = setInterval(() => deferred.resolve(Date.now()), 1000);
|
|
34
|
+
return () => clearInterval(id);
|
|
35
35
|
});
|
|
36
36
|
|
|
37
37
|
for await (const ts of clock) {
|
|
38
|
-
|
|
38
|
+
console.log(ts); // a timestamp every second, only while iterating
|
|
39
39
|
}
|
|
40
40
|
```
|
|
41
41
|
|