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.
Files changed (316) hide show
  1. package/docs/api/APIProvider.md +2 -2
  2. package/docs/api/CachedAPIProvider.md +6 -8
  3. package/docs/api/ClientAPIProvider.md +5 -5
  4. package/docs/api/DebugAPIProvider.md +3 -5
  5. package/docs/api/HydratingAPIProvider.md +2 -2
  6. package/docs/api/JSONAPIProvider.md +3 -5
  7. package/docs/api/LoggingAPIProvider.md +7 -9
  8. package/docs/api/MockAPIProvider.md +4 -4
  9. package/docs/api/MockEndpointAPIProvider.md +5 -7
  10. package/docs/api/ThroughAPIProvider.md +15 -10
  11. package/docs/api/ValidationAPIProvider.md +3 -5
  12. package/docs/api/XMLAPIProvider.md +3 -3
  13. package/docs/api.md +48 -44
  14. package/docs/bun.md +9 -9
  15. package/docs/db/DBProvider.md +6 -6
  16. package/docs/db/MemoryDBProvider.md +3 -3
  17. package/docs/db/PostgresProvider.md +6 -4
  18. package/docs/db/SQLProvider.md +6 -3
  19. package/docs/db/SQLiteProvider.md +9 -4
  20. package/docs/db/StorageDBProvider.md +2 -2
  21. package/docs/db/ThroughDBProvider.md +6 -6
  22. package/docs/db/UndoDBProvider.md +2 -2
  23. package/docs/db.md +32 -32
  24. package/docs/error/NetworkError.md +5 -5
  25. package/docs/error/RequestError.md +4 -4
  26. package/docs/error/RequiredError.md +2 -2
  27. package/docs/error/ResponseError.md +1 -1
  28. package/docs/error/UnexpectedError.md +1 -1
  29. package/docs/error/UnsupportedError.md +3 -3
  30. package/docs/error/ValueError.md +2 -2
  31. package/docs/error.md +20 -19
  32. package/docs/extract.md +14 -14
  33. package/docs/firebase.md +6 -6
  34. package/docs/guides/building-with-shelving.md +113 -85
  35. package/docs/guides/styleguide.md +29 -29
  36. package/docs/index.md +3 -2
  37. package/docs/llms-full.txt +2541 -2295
  38. package/docs/markup.md +15 -17
  39. package/docs/react/createAPIContext.md +12 -12
  40. package/docs/react/createDBContext.md +21 -15
  41. package/docs/react/useInstance.md +2 -2
  42. package/docs/react/useLazy.md +1 -1
  43. package/docs/react/useMap.md +10 -6
  44. package/docs/react/useReduce.md +2 -2
  45. package/docs/react/useSequence.md +2 -2
  46. package/docs/react/useStore.md +10 -10
  47. package/docs/react.md +22 -16
  48. package/docs/schema/ArraySchema.md +6 -6
  49. package/docs/schema/BooleanSchema.md +5 -5
  50. package/docs/schema/ChoiceSchema.md +1 -1
  51. package/docs/schema/CurrencyAmountSchema.md +2 -2
  52. package/docs/schema/DataSchema.md +5 -5
  53. package/docs/schema/NullableSchema.md +4 -4
  54. package/docs/schema/NumberSchema.md +4 -4
  55. package/docs/schema/OptionalSchema.md +1 -1
  56. package/docs/schema/StringSchema.md +7 -7
  57. package/docs/schema.md +21 -21
  58. package/docs/sequence/DeferredSequence.md +1 -1
  59. package/docs/sequence/InspectSequence.md +8 -6
  60. package/docs/sequence/LazySequence.md +3 -3
  61. package/docs/sequence/Sequence.md +6 -6
  62. package/docs/sequence/ThroughSequence.md +4 -2
  63. package/docs/sequence.md +3 -3
  64. package/docs/store/ArrayStore.md +6 -6
  65. package/docs/store/BooleanStore.md +2 -2
  66. package/docs/store/BusyStore.md +1 -1
  67. package/docs/store/DataStore.md +5 -5
  68. package/docs/store/DictionaryStore.md +4 -4
  69. package/docs/store/FetchStore.md +6 -6
  70. package/docs/store/PathStore.md +4 -4
  71. package/docs/store/PayloadFetchStore.md +1 -5
  72. package/docs/store/Store.md +8 -6
  73. package/docs/store/URLStore.md +5 -5
  74. package/docs/store.md +15 -15
  75. package/docs/test.md +6 -6
  76. package/docs/ui/App.md +99 -69
  77. package/docs/ui/AppLayout.md +35 -26
  78. package/docs/ui/BackButton.md +13 -11
  79. package/docs/ui/Button.md +73 -64
  80. package/docs/ui/Card.md +23 -22
  81. package/docs/ui/Catcher.md +3 -3
  82. package/docs/ui/ClassProps.md +1 -1
  83. package/docs/ui/Code.md +11 -11
  84. package/docs/ui/CollapseTransition.md +5 -5
  85. package/docs/ui/Deleted.md +6 -6
  86. package/docs/ui/Details.md +13 -13
  87. package/docs/ui/Dialog.md +42 -28
  88. package/docs/ui/Dialogs.md +4 -0
  89. package/docs/ui/DocumentationButtons.md +2 -2
  90. package/docs/ui/DocumentationCard.md +2 -2
  91. package/docs/ui/DocumentationFrame.md +4 -4
  92. package/docs/ui/DocumentationLive.md +11 -11
  93. package/docs/ui/DocumentationPage.md +3 -3
  94. package/docs/ui/Emphasis.md +4 -4
  95. package/docs/ui/Empty.md +2 -2
  96. package/docs/ui/FadeTransition.md +9 -9
  97. package/docs/ui/Field.md +14 -14
  98. package/docs/ui/FixedLayout.md +27 -25
  99. package/docs/ui/Form.md +41 -39
  100. package/docs/ui/FormStore.md +6 -2
  101. package/docs/ui/Grid.md +21 -9
  102. package/docs/ui/HTML.md +10 -8
  103. package/docs/ui/Head.md +2 -3
  104. package/docs/ui/Heading.md +12 -12
  105. package/docs/ui/HorizontalTransition.md +10 -10
  106. package/docs/ui/Icon.md +4 -4
  107. package/docs/ui/ImageInput.md +12 -12
  108. package/docs/ui/Inserted.md +6 -6
  109. package/docs/ui/Link.md +11 -11
  110. package/docs/ui/List.md +7 -7
  111. package/docs/ui/Loading.md +6 -6
  112. package/docs/ui/Mark.md +11 -9
  113. package/docs/ui/Markup.md +4 -4
  114. package/docs/ui/Menu.md +24 -24
  115. package/docs/ui/MenuItem.md +29 -29
  116. package/docs/ui/Modal.md +57 -45
  117. package/docs/ui/Navigation.md +28 -26
  118. package/docs/ui/NavigationStore.md +18 -18
  119. package/docs/ui/Notice.md +15 -15
  120. package/docs/ui/Notices.md +17 -17
  121. package/docs/ui/Page.md +13 -13
  122. package/docs/ui/Panel.md +8 -8
  123. package/docs/ui/Paragraph.md +5 -5
  124. package/docs/ui/Progress.md +11 -11
  125. package/docs/ui/Prose.md +6 -6
  126. package/docs/ui/QueryRadiosInput.md +2 -2
  127. package/docs/ui/RouteCache.md +27 -27
  128. package/docs/ui/Router.md +70 -61
  129. package/docs/ui/SchemaInput.md +20 -20
  130. package/docs/ui/Scroll.md +16 -16
  131. package/docs/ui/Section.md +13 -10
  132. package/docs/ui/SidebarLayout.md +27 -27
  133. package/docs/ui/Small.md +4 -4
  134. package/docs/ui/Span.md +3 -1
  135. package/docs/ui/StackButton.md +13 -7
  136. package/docs/ui/Strong.md +4 -4
  137. package/docs/ui/Subheading.md +12 -12
  138. package/docs/ui/TINT_CLASS.md +11 -11
  139. package/docs/ui/Table.md +40 -29
  140. package/docs/ui/Tag.md +15 -15
  141. package/docs/ui/Title.md +13 -13
  142. package/docs/ui/Transition.md +22 -22
  143. package/docs/ui/TreeApp.md +8 -8
  144. package/docs/ui/TreeMarkup.md +2 -2
  145. package/docs/ui/TreeMenu.md +3 -3
  146. package/docs/ui/TreeSidebar.md +1 -1
  147. package/docs/ui/VerticalTransition.md +8 -8
  148. package/docs/ui/getClass.md +10 -10
  149. package/docs/ui/getColorClass.md +23 -23
  150. package/docs/ui/getDurationClass.md +5 -5
  151. package/docs/ui/getGridClass.md +2 -2
  152. package/docs/ui/getHeightClass.md +4 -4
  153. package/docs/ui/getRadiusClass.md +9 -9
  154. package/docs/ui/getShadowClass.md +6 -6
  155. package/docs/ui/getSpaceClass.md +13 -13
  156. package/docs/ui/getStrokeClass.md +6 -6
  157. package/docs/ui/getTypographyClass.md +38 -38
  158. package/docs/ui/getWidthClass.md +4 -4
  159. package/docs/ui/notify.md +11 -11
  160. package/docs/ui/requireContext.md +1 -1
  161. package/docs/ui.md +4 -4
  162. package/docs/util/array.md +35 -29
  163. package/docs/util/async.md +2 -2
  164. package/docs/util/base64.md +7 -7
  165. package/docs/util/boolean.md +10 -10
  166. package/docs/util/buffer.md +5 -5
  167. package/docs/util/bytes.md +9 -9
  168. package/docs/util/class.md +10 -6
  169. package/docs/util/color.md +13 -13
  170. package/docs/util/constants.md +2 -2
  171. package/docs/util/crypto.md +1 -1
  172. package/docs/util/currency.md +2 -2
  173. package/docs/util/data.md +18 -18
  174. package/docs/util/date.md +22 -22
  175. package/docs/util/debug/debug.md +12 -12
  176. package/docs/util/dictionary.md +21 -18
  177. package/docs/util/diff.md +6 -6
  178. package/docs/util/dispose/dispose.md +5 -5
  179. package/docs/util/duration.md +9 -9
  180. package/docs/util/element.md +1 -1
  181. package/docs/util/entity.md +6 -6
  182. package/docs/util/entry.md +21 -8
  183. package/docs/util/env.md +2 -2
  184. package/docs/util/equal.md +16 -16
  185. package/docs/util/error.md +4 -4
  186. package/docs/util/file.md +8 -8
  187. package/docs/util/filter.md +9 -5
  188. package/docs/util/format.md +18 -18
  189. package/docs/util/function.md +4 -4
  190. package/docs/util/geo.md +13 -13
  191. package/docs/util/hash.md +3 -3
  192. package/docs/util/http.md +1 -1
  193. package/docs/util/hydrate/hydrate.md +7 -4
  194. package/docs/util/item.md +4 -4
  195. package/docs/util/iterate.md +11 -11
  196. package/docs/util/jwt.md +1 -6
  197. package/docs/util/link.md +5 -5
  198. package/docs/util/map.md +17 -11
  199. package/docs/util/merge.md +2 -5
  200. package/docs/util/null.md +20 -10
  201. package/docs/util/number.md +16 -16
  202. package/docs/util/object.md +25 -22
  203. package/docs/util/path.md +17 -17
  204. package/docs/util/query.md +23 -25
  205. package/docs/util/random.md +7 -7
  206. package/docs/util/regexp.md +16 -16
  207. package/docs/util/sequence.md +16 -10
  208. package/docs/util/serialise/serialise.md +6 -6
  209. package/docs/util/set.md +10 -10
  210. package/docs/util/sort.md +10 -11
  211. package/docs/util/source.md +11 -7
  212. package/docs/util/start.md +8 -8
  213. package/docs/util/string.md +14 -14
  214. package/docs/util/template.md +3 -3
  215. package/docs/util/timeout.md +5 -5
  216. package/docs/util/transform.md +6 -6
  217. package/docs/util/tree.md +13 -13
  218. package/docs/util/undefined.md +3 -3
  219. package/docs/util/units.md +15 -15
  220. package/docs/util/update.md +16 -16
  221. package/docs/util/uri.md +12 -12
  222. package/docs/util/url.md +11 -11
  223. package/docs/util/uuid.md +3 -3
  224. package/docs/util/validate.md +14 -9
  225. package/package.json +3 -3
  226. package/skills/shelving/SKILL.md +1 -0
  227. package/ui/README.md +4 -4
  228. package/ui/app/App.md +99 -69
  229. package/ui/block/Card.md +23 -22
  230. package/ui/block/Details.md +13 -13
  231. package/ui/block/Grid.md +21 -9
  232. package/ui/block/Heading.md +12 -12
  233. package/ui/block/List.md +7 -7
  234. package/ui/block/Panel.md +8 -8
  235. package/ui/block/Paragraph.md +5 -5
  236. package/ui/block/Prose.md +6 -6
  237. package/ui/block/Section.md +13 -10
  238. package/ui/block/Subheading.md +12 -12
  239. package/ui/block/Title.md +13 -13
  240. package/ui/button/Button.md +73 -64
  241. package/ui/dialog/Dialog.md +42 -28
  242. package/ui/dialog/Dialogs.d.ts +4 -0
  243. package/ui/dialog/Dialogs.js +4 -0
  244. package/ui/dialog/Dialogs.tsx +4 -0
  245. package/ui/dialog/Modal.md +57 -45
  246. package/ui/docs/DocumentationButtons.md +2 -2
  247. package/ui/docs/DocumentationCard.md +2 -2
  248. package/ui/docs/DocumentationFrame.md +4 -4
  249. package/ui/docs/DocumentationLive.md +11 -11
  250. package/ui/docs/DocumentationPage.md +3 -3
  251. package/ui/form/Field.md +14 -14
  252. package/ui/form/Form.md +41 -39
  253. package/ui/form/FormStore.md +6 -2
  254. package/ui/form/Progress.md +11 -11
  255. package/ui/inline/Code.md +11 -11
  256. package/ui/inline/Deleted.md +6 -6
  257. package/ui/inline/Emphasis.md +4 -4
  258. package/ui/inline/Inserted.md +6 -6
  259. package/ui/inline/Link.md +11 -11
  260. package/ui/inline/Mark.md +11 -9
  261. package/ui/inline/Small.md +4 -4
  262. package/ui/inline/Span.md +3 -1
  263. package/ui/inline/Strong.md +4 -4
  264. package/ui/input/ImageInput.md +12 -12
  265. package/ui/input/QueryRadiosInput.md +2 -2
  266. package/ui/input/SchemaInput.md +20 -20
  267. package/ui/layout/AppLayout.md +35 -26
  268. package/ui/layout/AppLayout.module.css +3 -16
  269. package/ui/layout/FixedLayout.md +27 -25
  270. package/ui/layout/SidebarLayout.md +27 -27
  271. package/ui/layout/SidebarLayout.module.css +1 -0
  272. package/ui/menu/Menu.md +24 -24
  273. package/ui/menu/MenuItem.md +29 -29
  274. package/ui/misc/Catcher.md +3 -3
  275. package/ui/misc/Icon.md +4 -4
  276. package/ui/misc/Loading.md +6 -6
  277. package/ui/misc/Markup.md +4 -4
  278. package/ui/misc/Tag.md +15 -15
  279. package/ui/notice/Empty.md +2 -2
  280. package/ui/notice/Notice.md +15 -15
  281. package/ui/notice/Notices.md +17 -17
  282. package/ui/page/HTML.md +10 -8
  283. package/ui/page/Head.md +2 -3
  284. package/ui/page/Page.md +13 -13
  285. package/ui/router/BackButton.md +13 -11
  286. package/ui/router/Navigation.md +28 -26
  287. package/ui/router/NavigationStore.md +18 -18
  288. package/ui/router/RouteCache.md +27 -27
  289. package/ui/router/Router.md +70 -61
  290. package/ui/router/StackButton.md +13 -7
  291. package/ui/style/Scroll.md +16 -16
  292. package/ui/style/TINT_CLASS.md +11 -11
  293. package/ui/style/getColorClass.md +23 -23
  294. package/ui/style/getDurationClass.md +5 -5
  295. package/ui/style/getGridClass.md +2 -2
  296. package/ui/style/getHeightClass.md +4 -4
  297. package/ui/style/getRadiusClass.md +9 -9
  298. package/ui/style/getShadowClass.md +6 -6
  299. package/ui/style/getSpaceClass.md +13 -13
  300. package/ui/style/getStrokeClass.md +6 -6
  301. package/ui/style/getTypographyClass.md +38 -38
  302. package/ui/style/getWidthClass.md +4 -4
  303. package/ui/table/Table.md +40 -30
  304. package/ui/transition/CollapseTransition.md +5 -5
  305. package/ui/transition/FadeTransition.md +9 -9
  306. package/ui/transition/HorizontalTransition.md +10 -10
  307. package/ui/transition/Transition.md +22 -22
  308. package/ui/transition/VerticalTransition.md +8 -8
  309. package/ui/tree/TreeApp.md +8 -8
  310. package/ui/tree/TreeMarkup.md +2 -2
  311. package/ui/tree/TreeMenu.md +3 -3
  312. package/ui/tree/TreeSidebar.md +1 -1
  313. package/ui/util/ClassProps.md +1 -1
  314. package/ui/util/getClass.md +10 -10
  315. package/ui/util/notify.md +11 -11
  316. package/ui/util/requireContext.md +1 -1
@@ -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"); // ["a", "b", "c"]
23
- tags.delete("a"); // ["b", "c"]
24
- tags.toggle("b"); // ["c"] — removes if present, adds if not
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); // "c" (throws if empty)
27
- console.log(tags.count); // 1
28
- console.log(tags.exists); // true
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(); // true
21
- open.value = 0; // false — assigned values are coerced to boolean
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
 
@@ -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
- console.log(busy ? "loading…" : "idle");
27
+ console.log(busy ? "loading…" : "idle");
28
28
  }
29
29
  ```
30
30
 
@@ -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 }); // Partial update — merges into the current value.
24
- state.set("count", 2); // Set a single named prop.
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); // { name: "Dave", count: 2 }
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); // true
37
+ console.log(profile.exists); // true
38
38
  console.log(profile.require().name); // "Dave" — throws RequiredError if absent
39
- profile.delete(); // value is now undefined
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); // { apple: 1, banana: 2 }
23
- prices.update({ apple: 3 }); // { apple: 3, banana: 2 }
24
- prices.delete("banana"); // { apple: 3 }
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); // 1
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
  ```
@@ -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 (signal) => {
24
- const res = await fetch("/api/me", { signal });
25
- return res.json();
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); // true — reading this triggered the fetch
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(); // mark stale; the next read re-fetches
32
- await store.refresh(); // re-fetch now
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.
@@ -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"; // resolved against the current path → "/products/43"
20
+ route.value = "../43"; // resolved against the current path → "/products/43"
21
21
 
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
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
 
@@ -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
- console.log(v); // 43, then any future values
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
- // No value yet — safe to check without risk of throwing.
49
+ // No value yet — safe to check without risk of throwing.
50
50
  } else {
51
- console.log(store.value);
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
- const id = setInterval(() => { store.value = Date.now(); }, 1000);
62
- return () => clearInterval(id);
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
- // store.value is updated on each iteration
74
+ // store.value is updated on each iteration
73
75
  }
74
76
  ```
75
77
 
@@ -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); // "example.com"
21
- console.log(url.getParam("q")); // "hats"
20
+ console.log(url.hostname); // "example.com"
21
+ console.log(url.getParam("q")); // "hats"
22
22
 
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
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"); // true — current URL sits below this one
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 | 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. |
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
- for await (const _ of store.through(stream)) {
50
- // store.value is updated on each iteration; any consumers re-render
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; // 9, in unsorted order.
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 | 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". |
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
- 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
- );
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
- return (
46
- <App app="My app" root="https://example.com/" url="/">
47
- <Navigation>
48
- <Router routes={{
49
- "/": HomePage,
50
- "/about": AboutPage,
51
- }} />
52
- </Navigation>
53
- </App>
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
- App, AppLayout, Catcher, DialogsContext, Dialogs, ErrorPage, FixedLayout, HorizontalTransition,
85
- Navigation, Notices, PageLoader, requireMetaURL, RouteCache, Router, type ErrorProps, type Routes,
86
- Scroll, StackButton,
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
- const session = useStore(SESSION).value;
94
- return (
95
- <App key={session?.id ?? "out"} app="My app" root="https://example.com/">
96
- <Navigation stacks={STACKS} stack="/home">
97
- <DialogsContext>
98
- <Catcher as={AppError}>
99
- <Shell signedIn={!!session} />
100
- </Catcher>
101
- <Dialogs />
102
- <Notices />
103
- </DialogsContext>
104
- </Navigation>
105
- </App>
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
- const { path } = requireMetaURL();
112
- if (!signedIn) return <FixedLayout><Content routes={LOGIN_ROUTES} /></FixedLayout>;
113
- return (
114
- <AppLayout nav={path.startsWith("/squad/") ? false : <StackBar />}>
115
- <Content routes={ROUTES} />
116
- </AppLayout>
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
- return (
123
- <HorizontalTransition>
124
- <RouteCache>
125
- <Scroll vertical cover>
126
- <PageLoader>
127
- <Router routes={routes} />
128
- </PageLoader>
129
- </Scroll>
130
- </RouteCache>
131
- </HorizontalTransition>
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
- return <>
138
- <StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
139
- <StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
140
- <StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
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
- return (
147
- <FixedLayout>
148
- <Scroll vertical cover>
149
- <ErrorPage reason={reason} />
150
- </Scroll>
151
- </FixedLayout>
152
- );
176
+ return (
177
+ <FixedLayout>
178
+ <Scroll vertical cover>
179
+ <ErrorPage reason={reason} />
180
+ </Scroll>
181
+ </FixedLayout>
182
+ );
153
183
  }
154
184
  ```
155
185
 
@@ -15,10 +15,11 @@ 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
- - The bar is outside the page cache, so it has one copy. It keeps its state, and the CSS transitions of its items (an active tab) still play while a page slides.
21
- - The bar has its own view-transition group, so it stays still while the page slides under it.
21
+ - The bar is outside the page cache, so it has one copy and keeps its state.
22
+ - The bar has no view-transition name of its own. Pages slide sideways in the content slot above it, so the bar stays still. A named bar would draw above a dialog or notice that covers it during every view transition.
22
23
  - Leave out `nav`, or set it to `false`, to show no bar. The content slot then fills the screen. To hide the bar for some pages, change the prop from the URL, so the layout and its page cache stay mounted: `nav={path.startsWith("/squad/") ? false : <StackBar />}`.
23
24
  - Pages, error pages and loading states never render it themselves. Pick it above the router. See "Composing an app" on `<App>`.
24
25
 
@@ -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
- return <>
32
- <StackButton stack="/home" title="Home"><HomeIcon /></StackButton>
33
- <StackButton stack="/discover" title="Discover"><SearchIcon /></StackButton>
34
- <StackButton stack="/profile" title="Profile"><ProfileIcon /></StackButton>
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
- <HorizontalTransition>
40
- <RouteCache>
41
- <Scroll vertical cover>
42
- <PageLoader>
43
- <Router routes={ROUTES} />
44
- </PageLoader>
45
- </Scroll>
46
- </RouteCache>
47
- </HorizontalTransition>
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 | Styles | Default |
54
- |---|---|---|
55
- | `--app-layout-background` | Page background while the layout is mounted | `var(--tint-100)` (white) |
56
- | `--app-layout-color` | Text colour for the layout | `var(--tint-00)` (black) |
57
- | `--app-layout-nav-background` | Bar fill (also fills the home-bar area below it) | `var(--tint-100)` (white) |
58
- | `--app-layout-nav-color` | Bar text and icon colour | `var(--tint-00)` (black) |
59
- | `--app-layout-nav-border` | Line above the bar | `var(--stroke-normal) solid var(--tint-90)` |
60
- | `--app-layout-nav-shadow` | Shadow of the bar, for example a soft shadow above it | `none` |
61
- | `--app-layout-nav-item-width` | Largest width of one bar item | `6rem` |
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
 
@@ -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
- return (
30
- <>
31
- <header>
32
- <BackButton href="/home"/>
33
- <h1>Post</h1>
34
- </header>
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">Profile</Button>
50
+ <Button href="/profile" className="back">
51
+ Profile
52
+ </Button>;
51
53
  ```
52
54
 
53
55
  ## Styling