shelving 1.322.1 → 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 +112 -84
- package/docs/guides/styleguide.md +29 -29
- package/docs/index.md +3 -2
- package/docs/llms-full.txt +2531 -2291
- 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 +33 -24
- 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 +39 -27
- 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 +39 -27
- 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 +33 -24
- package/ui/layout/AppLayout.module.css +1 -0
- 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/store/ArrayStore.md
CHANGED
|
@@ -19,13 +19,13 @@ import { ArrayStore } from "shelving/store";
|
|
|
19
19
|
|
|
20
20
|
const tags = new ArrayStore<string>(["a", "b"]);
|
|
21
21
|
|
|
22
|
-
tags.add("c");
|
|
23
|
-
tags.delete("a");
|
|
24
|
-
tags.toggle("b");
|
|
22
|
+
tags.add("c"); // ["a", "b", "c"]
|
|
23
|
+
tags.delete("a"); // ["b", "c"]
|
|
24
|
+
tags.toggle("b"); // ["c"] — removes if present, adds if not
|
|
25
25
|
|
|
26
|
-
console.log(tags.first);
|
|
27
|
-
console.log(tags.count);
|
|
28
|
-
console.log(tags.exists);
|
|
26
|
+
console.log(tags.first); // "c" (throws if empty)
|
|
27
|
+
console.log(tags.count); // 1
|
|
28
|
+
console.log(tags.exists); // true
|
|
29
29
|
|
|
30
30
|
for (const tag of tags) console.log(tag); // ArrayStore is iterable
|
|
31
31
|
```
|
|
@@ -17,8 +17,8 @@ import { BooleanStore } from "shelving/store";
|
|
|
17
17
|
|
|
18
18
|
const open = new BooleanStore(); // defaults to false
|
|
19
19
|
|
|
20
|
-
open.toggle();
|
|
21
|
-
open.value = 0;
|
|
20
|
+
open.toggle(); // true
|
|
21
|
+
open.value = 0; // false — assigned values are coerced to boolean
|
|
22
22
|
console.log(open.value); // false
|
|
23
23
|
```
|
|
24
24
|
|
package/docs/store/BusyStore.md
CHANGED
|
@@ -24,7 +24,7 @@ const store = new BusyStore<number>(NONE);
|
|
|
24
24
|
store.value = fetchNextValue(); // assigning a promise — store.busy becomes true
|
|
25
25
|
|
|
26
26
|
for await (const busy of store.busy) {
|
|
27
|
-
|
|
27
|
+
console.log(busy ? "loading…" : "idle");
|
|
28
28
|
}
|
|
29
29
|
```
|
|
30
30
|
|
package/docs/store/DataStore.md
CHANGED
|
@@ -20,10 +20,10 @@ import { DataStore } from "shelving/store";
|
|
|
20
20
|
|
|
21
21
|
const state = new DataStore<{ name: string; count: number }>({ name: "Dave", count: 0 });
|
|
22
22
|
|
|
23
|
-
state.update({ count: 1 });
|
|
24
|
-
state.set("count", 2);
|
|
23
|
+
state.update({ count: 1 }); // Partial update — merges into the current value.
|
|
24
|
+
state.set("count", 2); // Set a single named prop.
|
|
25
25
|
console.log(state.get("name")); // "Dave"
|
|
26
|
-
console.log(state.data);
|
|
26
|
+
console.log(state.data); // { name: "Dave", count: 2 }
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
### `OptionalDataStore`
|
|
@@ -34,9 +34,9 @@ import { OptionalDataStore, NONE } from "shelving/store";
|
|
|
34
34
|
const profile = new OptionalDataStore<{ name: string }>(NONE);
|
|
35
35
|
|
|
36
36
|
profile.value = { name: "Dave" };
|
|
37
|
-
console.log(profile.exists);
|
|
37
|
+
console.log(profile.exists); // true
|
|
38
38
|
console.log(profile.require().name); // "Dave" — throws RequiredError if absent
|
|
39
|
-
profile.delete();
|
|
39
|
+
profile.delete(); // value is now undefined
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
|
|
@@ -19,12 +19,12 @@ import { DictionaryStore } from "shelving/store";
|
|
|
19
19
|
|
|
20
20
|
const prices = new DictionaryStore<number>({ apple: 1 });
|
|
21
21
|
|
|
22
|
-
prices.set("banana", 2);
|
|
23
|
-
prices.update({ apple: 3 });
|
|
24
|
-
prices.delete("banana");
|
|
22
|
+
prices.set("banana", 2); // { apple: 1, banana: 2 }
|
|
23
|
+
prices.update({ apple: 3 }); // { apple: 3, banana: 2 }
|
|
24
|
+
prices.delete("banana"); // { apple: 3 }
|
|
25
25
|
|
|
26
26
|
console.log(prices.get("apple")); // 3
|
|
27
|
-
console.log(prices.count);
|
|
27
|
+
console.log(prices.count); // 1
|
|
28
28
|
|
|
29
29
|
for (const [key, value] of prices) console.log(key, value); // iterable over entries
|
|
30
30
|
```
|
package/docs/store/FetchStore.md
CHANGED
|
@@ -20,16 +20,16 @@ Pass an initial value (or `NONE`) and a callback. The callback receives an `Abor
|
|
|
20
20
|
```ts
|
|
21
21
|
import { FetchStore, NONE } from "shelving/store";
|
|
22
22
|
|
|
23
|
-
const store = new FetchStore<User>(NONE, async
|
|
24
|
-
|
|
25
|
-
|
|
23
|
+
const store = new FetchStore<User>(NONE, async signal => {
|
|
24
|
+
const res = await fetch("/api/me", { signal });
|
|
25
|
+
return res.json();
|
|
26
26
|
});
|
|
27
27
|
|
|
28
|
-
console.log(store.loading);
|
|
28
|
+
console.log(store.loading); // true — reading this triggered the fetch
|
|
29
29
|
const user = await store.next; // wait for the first value
|
|
30
30
|
|
|
31
|
-
store.invalidate();
|
|
32
|
-
await store.refresh();
|
|
31
|
+
store.invalidate(); // mark stale; the next read re-fetches
|
|
32
|
+
await store.refresh(); // re-fetch now
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
`refresh(maxAge)` accepts a max age in milliseconds: the exported `ALWAYS_REFRESH` (`0`, the default) always re-fetches, while `AVOID_REFRESH` (`Infinity`) only fetches if the store has no value yet.
|
package/docs/store/PathStore.md
CHANGED
|
@@ -17,11 +17,11 @@ import { PathStore } from "shelving/store";
|
|
|
17
17
|
|
|
18
18
|
const route = new PathStore("/products/42");
|
|
19
19
|
|
|
20
|
-
route.value = "../43";
|
|
20
|
+
route.value = "../43"; // resolved against the current path → "/products/43"
|
|
21
21
|
|
|
22
|
-
route.isActive("/products/43");
|
|
23
|
-
route.isProud("/products");
|
|
24
|
-
route.getPath("./reviews");
|
|
22
|
+
route.isActive("/products/43"); // true — exact match of the current path
|
|
23
|
+
route.isProud("/products"); // true — current path is at or below "/products"
|
|
24
|
+
route.getPath("./reviews"); // "/products/43/reviews" — resolve a relative path
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
The constructor takes an optional second `base` argument (default `/`) used to resolve relative paths assigned to the store.
|
|
@@ -19,11 +19,7 @@ Pass an initial payload, an initial value (or `NONE`), and a callback that recei
|
|
|
19
19
|
```ts
|
|
20
20
|
import { PayloadFetchStore, NONE } from "shelving/store";
|
|
21
21
|
|
|
22
|
-
const store = new PayloadFetchStore<string, User>(
|
|
23
|
-
"u_1",
|
|
24
|
-
NONE,
|
|
25
|
-
async (id, signal) => (await fetch(`/api/users/${id}`, { signal })).json(),
|
|
26
|
-
);
|
|
22
|
+
const store = new PayloadFetchStore<string, User>("u_1", NONE, async (id, signal) => (await fetch(`/api/users/${id}`, { signal })).json());
|
|
27
23
|
|
|
28
24
|
const first = await store.next; // fetches for "u_1"
|
|
29
25
|
|
package/docs/store/Store.md
CHANGED
|
@@ -38,7 +38,7 @@ Iterating emits the current value first (if one exists), then each subsequent va
|
|
|
38
38
|
|
|
39
39
|
```ts
|
|
40
40
|
for await (const v of store) {
|
|
41
|
-
|
|
41
|
+
console.log(v); // 43, then any future values
|
|
42
42
|
}
|
|
43
43
|
```
|
|
44
44
|
|
|
@@ -46,9 +46,9 @@ for await (const v of store) {
|
|
|
46
46
|
|
|
47
47
|
```ts
|
|
48
48
|
if (store.loading) {
|
|
49
|
-
|
|
49
|
+
// No value yet — safe to check without risk of throwing.
|
|
50
50
|
} else {
|
|
51
|
-
|
|
51
|
+
console.log(store.value);
|
|
52
52
|
}
|
|
53
53
|
```
|
|
54
54
|
|
|
@@ -58,8 +58,10 @@ if (store.loading) {
|
|
|
58
58
|
|
|
59
59
|
```ts
|
|
60
60
|
store.starter = () => {
|
|
61
|
-
|
|
62
|
-
|
|
61
|
+
const id = setInterval(() => {
|
|
62
|
+
store.value = Date.now();
|
|
63
|
+
}, 1000);
|
|
64
|
+
return () => clearInterval(id);
|
|
63
65
|
};
|
|
64
66
|
```
|
|
65
67
|
|
|
@@ -69,7 +71,7 @@ store.starter = () => {
|
|
|
69
71
|
|
|
70
72
|
```ts
|
|
71
73
|
for await (const _ of store.through(someStream)) {
|
|
72
|
-
|
|
74
|
+
// store.value is updated on each iteration
|
|
73
75
|
}
|
|
74
76
|
```
|
|
75
77
|
|
package/docs/store/URLStore.md
CHANGED
|
@@ -17,14 +17,14 @@ import { URLStore } from "shelving/store";
|
|
|
17
17
|
|
|
18
18
|
const url = new URLStore("https://example.com/search?q=hats");
|
|
19
19
|
|
|
20
|
-
console.log(url.hostname);
|
|
21
|
-
console.log(url.getParam("q"));
|
|
20
|
+
console.log(url.hostname); // "example.com"
|
|
21
|
+
console.log(url.getParam("q")); // "hats"
|
|
22
22
|
|
|
23
|
-
url.setParam("page", "2");
|
|
24
|
-
url.value = "/search?q=shoes";
|
|
23
|
+
url.setParam("page", "2"); // updates the stored URL's query
|
|
24
|
+
url.value = "/search?q=shoes"; // assign a relative path — resolved against the current URL
|
|
25
25
|
|
|
26
26
|
url.isActive("https://example.com/search?q=shoes"); // true
|
|
27
|
-
url.isProud("https://example.com/search");
|
|
27
|
+
url.isProud("https://example.com/search"); // true — current URL sits below this one
|
|
28
28
|
```
|
|
29
29
|
|
|
30
30
|
Param helpers come in mutating (`setParam`, `updateParams`, `deleteParam`, `clearParams`) and non-mutating (`withParam`, `withParams`, `omitParam`) forms — the latter return a new URL without changing the store.
|
package/docs/store.md
CHANGED
|
@@ -19,18 +19,18 @@ Observable value containers for reactive state. A `Store<T>` holds a single curr
|
|
|
19
19
|
|
|
20
20
|
**Subclasses**
|
|
21
21
|
|
|
22
|
-
| Class
|
|
23
|
-
|
|
24
|
-
| `DataStore<T>`
|
|
25
|
-
| `OptionalDataStore<T>`
|
|
26
|
-
| `ArrayStore<T>`
|
|
27
|
-
| `DictionaryStore<T>`
|
|
28
|
-
| `BooleanStore`
|
|
29
|
-
| `PathStore`
|
|
30
|
-
| `URLStore`
|
|
31
|
-
| `BusyStore<T>`
|
|
32
|
-
| `FetchStore<T>`
|
|
33
|
-
| `PayloadFetchStore<P, R>` | A `FetchStore` driven by a `PayloadFetchStore.payload` store — changing the payload re-fetches.
|
|
22
|
+
| Class | Description |
|
|
23
|
+
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
24
|
+
| `DataStore<T>` | Adds `DataStore.data`, `DataStore.update()`, `DataStore.get()`, `DataStore.set()` helpers for object values. |
|
|
25
|
+
| `OptionalDataStore<T>` | Like `DataStore` but the value may be `undefined`; `OptionalDataStore.exists` and `OptionalDataStore.require()` handle the absent case. |
|
|
26
|
+
| `ArrayStore<T>` | Stores an array; adds `ArrayStore.first`, `ArrayStore.last`, `ArrayStore.count`, `ArrayStore.add()`, `ArrayStore.delete()`, `ArrayStore.toggle()`. |
|
|
27
|
+
| `DictionaryStore<T>` | Stores a string-keyed object; adds `DictionaryStore.get()`, `DictionaryStore.set()`, `DictionaryStore.delete()`, `DictionaryStore.update()`. |
|
|
28
|
+
| `BooleanStore` | Stores a boolean; adds `BooleanStore.toggle()`. |
|
|
29
|
+
| `PathStore` | Stores an absolute path; adds `PathStore.isActive()` / `PathStore.isProud()` route helpers. |
|
|
30
|
+
| `URLStore` | Stores a URL; adds query-param helpers and `URLStore.isActive()` / `URLStore.isProud()`. |
|
|
31
|
+
| `BusyStore<T>` | Adds a `BusyStore.busy` boolean store that is `true` while awaiting a value. |
|
|
32
|
+
| `FetchStore<T>` | Fetches its value from a callback; adds `FetchStore.refresh()` / `FetchStore.invalidate()`. |
|
|
33
|
+
| `PayloadFetchStore<P, R>` | A `FetchStore` driven by a `PayloadFetchStore.payload` store — changing the payload re-fetches. |
|
|
34
34
|
|
|
35
35
|
`ItemStore` and `QueryStore` in the `shelving/db` module extend `FetchStore` directly, adding database-aware fetch and subscription logic.
|
|
36
36
|
|
|
@@ -46,9 +46,9 @@ import { Store, NONE } from "shelving/store";
|
|
|
46
46
|
const store = new Store<number>(NONE);
|
|
47
47
|
|
|
48
48
|
async function connect(stream: AsyncIterable<number>) {
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
49
|
+
for await (const _ of store.through(stream)) {
|
|
50
|
+
// store.value is updated on each iteration; any consumers re-render
|
|
51
|
+
}
|
|
52
52
|
}
|
|
53
53
|
```
|
|
54
54
|
|
package/docs/test.md
CHANGED
|
@@ -19,7 +19,7 @@ Reach for these fixtures whenever a test needs a schema, a collection, or a hand
|
|
|
19
19
|
import { BASIC_SCHEMA, basics, basic1 } from "shelving/test";
|
|
20
20
|
|
|
21
21
|
BASIC_SCHEMA.validate(basic1); // Passes.
|
|
22
|
-
basics.length;
|
|
22
|
+
basics.length; // 9, in unsorted order.
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
### People
|
|
@@ -44,11 +44,11 @@ await provider.addItem(BASICS_COLLECTION, basic1);
|
|
|
44
44
|
|
|
45
45
|
## Assertion helpers
|
|
46
46
|
|
|
47
|
-
| Helper
|
|
48
|
-
|
|
49
|
-
| `expectOrderedItems()`
|
|
50
|
-
| `expectUnorderedItems()` | The same, but order does not matter.
|
|
51
|
-
| `EXPECT_PROMISELIKE`
|
|
47
|
+
| Helper | Use |
|
|
48
|
+
| ------------------------ | ----------------------------------------------------------------- |
|
|
49
|
+
| `expectOrderedItems()` | Assert an iterable of items has exactly these ids, in this order. |
|
|
50
|
+
| `expectUnorderedItems()` | The same, but order does not matter. |
|
|
51
|
+
| `EXPECT_PROMISELIKE` | A matcher for "this value looks like a promise". |
|
|
52
52
|
|
|
53
53
|
`expectOrderedItems()` and `expectUnorderedItems()` compare by `id`, so a failure reports the ids that were wrong — far more readable than a deep object diff. Both trim their own stack frame, so the reported failure points at your test.
|
|
54
54
|
|
package/docs/ui/App.md
CHANGED
|
@@ -19,18 +19,18 @@ The smallest single-screen app — `<App>` wraps a layout and some content:
|
|
|
19
19
|
import { App, FixedLayout, Paragraph, Scroll, Section, Title } from "shelving/ui";
|
|
20
20
|
|
|
21
21
|
function HelloApp() {
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
22
|
+
return (
|
|
23
|
+
<App app="My app">
|
|
24
|
+
<FixedLayout>
|
|
25
|
+
<Scroll vertical cover>
|
|
26
|
+
<Section width="narrow">
|
|
27
|
+
<Title>Hello</Title>
|
|
28
|
+
<Paragraph>Welcome to the app.</Paragraph>
|
|
29
|
+
</Section>
|
|
30
|
+
</Scroll>
|
|
31
|
+
</FixedLayout>
|
|
32
|
+
</App>
|
|
33
|
+
);
|
|
34
34
|
}
|
|
35
35
|
```
|
|
36
36
|
|
|
@@ -42,16 +42,18 @@ For a multi-page app, wrap the routes in `<Navigation>` and `<Router>`:
|
|
|
42
42
|
import { App, Navigation, Router } from "shelving/ui";
|
|
43
43
|
|
|
44
44
|
export function MyApp() {
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
45
|
+
return (
|
|
46
|
+
<App app="My app" root="https://example.com/" url="/">
|
|
47
|
+
<Navigation>
|
|
48
|
+
<Router
|
|
49
|
+
routes={{
|
|
50
|
+
"/": HomePage,
|
|
51
|
+
"/about": AboutPage,
|
|
52
|
+
}}
|
|
53
|
+
/>
|
|
54
|
+
</Navigation>
|
|
55
|
+
</App>
|
|
56
|
+
);
|
|
55
57
|
}
|
|
56
58
|
```
|
|
57
59
|
|
|
@@ -81,75 +83,103 @@ Nesting rules:
|
|
|
81
83
|
```tsx
|
|
82
84
|
import { useStore } from "shelving/react";
|
|
83
85
|
import {
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
86
|
+
App,
|
|
87
|
+
AppLayout,
|
|
88
|
+
Catcher,
|
|
89
|
+
DialogsContext,
|
|
90
|
+
Dialogs,
|
|
91
|
+
ErrorPage,
|
|
92
|
+
FixedLayout,
|
|
93
|
+
HorizontalTransition,
|
|
94
|
+
Navigation,
|
|
95
|
+
Notices,
|
|
96
|
+
PageLoader,
|
|
97
|
+
requireMetaURL,
|
|
98
|
+
RouteCache,
|
|
99
|
+
Router,
|
|
100
|
+
type ErrorProps,
|
|
101
|
+
type Routes,
|
|
102
|
+
Scroll,
|
|
103
|
+
StackButton,
|
|
87
104
|
} from "shelving/ui";
|
|
88
105
|
|
|
89
106
|
const STACKS = ["/home", "/discover", "/profile"] as const;
|
|
90
107
|
|
|
91
108
|
/** 1–2. Contexts and the app-level catcher. No layout here. */
|
|
92
109
|
export function MyApp() {
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
110
|
+
const session = useStore(SESSION).value;
|
|
111
|
+
return (
|
|
112
|
+
<App key={session?.id ?? "out"} app="My app" root="https://example.com/">
|
|
113
|
+
<Navigation stacks={STACKS} stack="/home">
|
|
114
|
+
<DialogsContext>
|
|
115
|
+
<Catcher as={AppError}>
|
|
116
|
+
<Shell signedIn={!!session} />
|
|
117
|
+
</Catcher>
|
|
118
|
+
<Dialogs />
|
|
119
|
+
<Notices />
|
|
120
|
+
</DialogsContext>
|
|
121
|
+
</Navigation>
|
|
122
|
+
</App>
|
|
123
|
+
);
|
|
107
124
|
}
|
|
108
125
|
|
|
109
126
|
/** 3–4. Pick the layout. Plain React, so any rule works. */
|
|
110
127
|
function Shell({ signedIn }: { signedIn: boolean }) {
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
128
|
+
const { path } = requireMetaURL();
|
|
129
|
+
if (!signedIn)
|
|
130
|
+
return (
|
|
131
|
+
<FixedLayout>
|
|
132
|
+
<Content routes={LOGIN_ROUTES} />
|
|
133
|
+
</FixedLayout>
|
|
134
|
+
);
|
|
135
|
+
return (
|
|
136
|
+
<AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
|
|
137
|
+
<Content routes={ROUTES} />
|
|
138
|
+
</AppLayout>
|
|
139
|
+
);
|
|
118
140
|
}
|
|
119
141
|
|
|
120
142
|
/** 5. The content of a layout's slot. */
|
|
121
143
|
function Content({ routes }: { routes: Routes }) {
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
144
|
+
return (
|
|
145
|
+
<HorizontalTransition>
|
|
146
|
+
<RouteCache>
|
|
147
|
+
<Scroll vertical cover>
|
|
148
|
+
<PageLoader>
|
|
149
|
+
<Router routes={routes} />
|
|
150
|
+
</PageLoader>
|
|
151
|
+
</Scroll>
|
|
152
|
+
</RouteCache>
|
|
153
|
+
</HorizontalTransition>
|
|
154
|
+
);
|
|
133
155
|
}
|
|
134
156
|
|
|
135
157
|
/** The tab bar, in the layout, outside the cache. */
|
|
136
158
|
function StackBar() {
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
159
|
+
return (
|
|
160
|
+
<>
|
|
161
|
+
<StackButton stack="/home" title="Home">
|
|
162
|
+
<HomeIcon />
|
|
163
|
+
</StackButton>
|
|
164
|
+
<StackButton stack="/discover" title="Discover">
|
|
165
|
+
<SearchIcon />
|
|
166
|
+
</StackButton>
|
|
167
|
+
<StackButton stack="/profile" title="Profile">
|
|
168
|
+
<ProfileIcon />
|
|
169
|
+
</StackButton>
|
|
170
|
+
</>
|
|
171
|
+
);
|
|
142
172
|
}
|
|
143
173
|
|
|
144
174
|
/** An error outside every layout: the app picks one here. */
|
|
145
175
|
function AppError({ reason }: ErrorProps) {
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
176
|
+
return (
|
|
177
|
+
<FixedLayout>
|
|
178
|
+
<Scroll vertical cover>
|
|
179
|
+
<ErrorPage reason={reason} />
|
|
180
|
+
</Scroll>
|
|
181
|
+
</FixedLayout>
|
|
182
|
+
);
|
|
153
183
|
}
|
|
154
184
|
```
|
|
155
185
|
|
package/docs/ui/AppLayout.md
CHANGED
|
@@ -15,6 +15,7 @@ A full-viewport layout with a content slot above a bar of the app's main section
|
|
|
15
15
|
- The content slot does not scroll. Fill it with `<Scroll vertical cover>` inside `<RouteCache>`, so each page scrolls in its own box and keeps its own scroll position.
|
|
16
16
|
- The bar sits below the content slot, not over it. So pages need no extra space at the bottom for the bar.
|
|
17
17
|
- The bar shows at every screen size.
|
|
18
|
+
- The bar paints above the content slot, so its shadow (`--app-layout-nav-shadow`) shows over the pages, even a page with its own background.
|
|
18
19
|
- The content slot stays clear of the notch and the rounded screen corners, and the bar stays clear of the home bar (safe-area insets).
|
|
19
20
|
- Each item in the bar takes an equal share of its width, up to `--app-layout-nav-item-width` each.
|
|
20
21
|
- The bar is outside the page cache, so it has one copy and keeps its state.
|
|
@@ -28,37 +29,45 @@ A full-viewport layout with a content slot above a bar of the app's main section
|
|
|
28
29
|
import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll, StackButton } from "shelving/ui";
|
|
29
30
|
|
|
30
31
|
function StackBar() {
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
32
|
+
return (
|
|
33
|
+
<>
|
|
34
|
+
<StackButton stack="/home" title="Home">
|
|
35
|
+
<HomeIcon />
|
|
36
|
+
</StackButton>
|
|
37
|
+
<StackButton stack="/discover" title="Discover">
|
|
38
|
+
<SearchIcon />
|
|
39
|
+
</StackButton>
|
|
40
|
+
<StackButton stack="/profile" title="Profile">
|
|
41
|
+
<ProfileIcon />
|
|
42
|
+
</StackButton>
|
|
43
|
+
</>
|
|
44
|
+
);
|
|
36
45
|
}
|
|
37
46
|
|
|
38
47
|
<AppLayout nav={<StackBar />}>
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
</AppLayout
|
|
48
|
+
<HorizontalTransition>
|
|
49
|
+
<RouteCache>
|
|
50
|
+
<Scroll vertical cover>
|
|
51
|
+
<PageLoader>
|
|
52
|
+
<Router routes={ROUTES} />
|
|
53
|
+
</PageLoader>
|
|
54
|
+
</Scroll>
|
|
55
|
+
</RouteCache>
|
|
56
|
+
</HorizontalTransition>
|
|
57
|
+
</AppLayout>;
|
|
49
58
|
```
|
|
50
59
|
|
|
51
60
|
## Styling
|
|
52
61
|
|
|
53
|
-
| Variable
|
|
54
|
-
|
|
55
|
-
| `--app-layout-background`
|
|
56
|
-
| `--app-layout-color`
|
|
57
|
-
| `--app-layout-nav-background` | Bar fill (also fills the home-bar area below it)
|
|
58
|
-
| `--app-layout-nav-color`
|
|
59
|
-
| `--app-layout-nav-border`
|
|
60
|
-
| `--app-layout-nav-shadow`
|
|
61
|
-
| `--app-layout-nav-item-width` | Largest width of one bar item
|
|
62
|
+
| Variable | Styles | Default |
|
|
63
|
+
| ----------------------------- | ----------------------------------------------------- | ------------------------------------------- |
|
|
64
|
+
| `--app-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
|
|
65
|
+
| `--app-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
|
|
66
|
+
| `--app-layout-nav-background` | Bar fill (also fills the home-bar area below it) | `var(--tint-100)` (white) |
|
|
67
|
+
| `--app-layout-nav-color` | Bar text and icon colour | `var(--tint-00)` (black) |
|
|
68
|
+
| `--app-layout-nav-border` | Line above the bar | `var(--stroke-normal) solid var(--tint-90)` |
|
|
69
|
+
| `--app-layout-nav-shadow` | Shadow of the bar, for example a soft shadow above it | `none` |
|
|
70
|
+
| `--app-layout-nav-item-width` | Largest width of one bar item | `6rem` |
|
|
62
71
|
|
|
63
72
|
The bar keeps its items clear of the home bar and the rounded screen corners with safe-area insets.
|
|
64
73
|
|
package/docs/ui/BackButton.md
CHANGED
|
@@ -26,28 +26,30 @@ The back button for a page header. It goes back to the page before this one in t
|
|
|
26
26
|
import { BackButton } from "shelving/ui";
|
|
27
27
|
|
|
28
28
|
function PostPage({ id }: { id: string }) {
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
29
|
+
return (
|
|
30
|
+
<>
|
|
31
|
+
<header>
|
|
32
|
+
<BackButton href="/home" />
|
|
33
|
+
<h1>Post</h1>
|
|
34
|
+
</header>
|
|
35
|
+
{/* … */}
|
|
36
|
+
</>
|
|
37
|
+
);
|
|
38
38
|
}
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
With a label:
|
|
42
42
|
|
|
43
43
|
```tsx
|
|
44
|
-
<BackButton href="/profile">Back to profile</BackButton
|
|
44
|
+
<BackButton href="/profile">Back to profile</BackButton>;
|
|
45
45
|
```
|
|
46
46
|
|
|
47
47
|
To go back to one fixed page (not to the page before), use a link with `className="back"`:
|
|
48
48
|
|
|
49
49
|
```tsx
|
|
50
|
-
<Button href="/profile" className="back">
|
|
50
|
+
<Button href="/profile" className="back">
|
|
51
|
+
Profile
|
|
52
|
+
</Button>;
|
|
51
53
|
```
|
|
52
54
|
|
|
53
55
|
## Styling
|