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
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 | 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"`. |
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
- rel: "nofollow ugc",
76
- url: requireURL("https://example.com/page/"),
77
- root: requireURL("https://example.com/"),
78
- schemes: ["http:", "https:", "mailto:"],
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
- /==(?<text>[^=]+)==/,
104
- (key, { text }) => <mark key={key}>{text}</mark>,
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
- const store = useAPI(getUser, { id }); // Returns an EndpointStore; component suspends while loading.
30
- const user = store.value;
31
- return <div>{user.name}</div>;
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
- 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
- );
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
- const store = useItem(Users, id); // ItemStore — suspends while loading.
24
- const user = store.value;
25
- return <div>{user.name}</div>;
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
- const store = useQuery(Users, { $order: "name" }); // QueryStore.
30
- const users = store.value;
31
- return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
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
- return (
36
- <DBContext>
37
- <ErrorBoundary fallback={<p>Error</p>}>
38
- <Suspense fallback={<p>Loading...</p>}>
39
- <UserList />
40
- </Suspense>
41
- </ErrorBoundary>
42
- </DBContext>
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
- const cache = useInstance(APICache, provider); // Stable across renders.
22
- // ...rebuilt only when `provider` changes.
21
+ const cache = useInstance(APICache, provider); // Stable across renders.
22
+ // ...rebuilt only when `provider` changes.
23
23
  }
24
24
  ```
25
25
 
@@ -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((items) => [...items].sort(), items);
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.
@@ -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
- const seen = useMap<string, boolean>(); // Same Map on every render.
20
- return <>{ids.map(id => {
21
- const isNew = !seen.has(id);
22
- seen.set(id, true);
23
- return <Thumbnail key={id} id={id} highlight={isNew} />;
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
 
@@ -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
- if (prev && isDeepEqual(prev, next)) return prev; // Preserve reference if equal.
26
- return next;
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
- const count = useSequence(counter); // undefined until first emission.
20
- return <span>{count ?? "—"}</span>;
19
+ const count = useSequence(counter); // undefined until first emission.
20
+ return <span>{count ?? "—"}</span>;
21
21
  }
22
22
  ```
23
23
 
@@ -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
- 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>;
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
- return (
30
- <ErrorBoundary fallback={<p>Something went wrong.</p>}>
31
- <Suspense fallback={<p>Loading...</p>}>
32
- <UserCard store={userStore} />
33
- </Suspense>
34
- </ErrorBoundary>
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
- const user = useItem(Users, id).value; // Suspends while loading.
38
- return <li>{user.name}</li>;
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
- const users = useQuery(Users, { $order: "name" }).value;
43
- return <ul>{users.map(u => <UserCard key={u.id} id={u.id} />)}</ul>;
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
- return (
48
- <DBContext>
49
- <ErrorBoundary fallback={<p>Something went wrong.</p>}>
50
- <Suspense fallback={<p>Loading…</p>}>
51
- <UserList />
52
- </Suspense>
53
- </ErrorBoundary>
54
- </DBContext>
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
- const open = useInstance(BooleanStore); // Created once, stable across renders.
69
- useStore(open); // Re-render whenever the store changes.
70
- return <button onClick={() => open.toggle()}>{open.value ? "Open" : "Closed"}</button>;
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"]); // ["a", "b"]
23
- TAGS.validate("a,b,c"); // ["a", "b", "c"] (split on comma)
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]); // [1, 2]
28
- NUMBERS.validate("1,2,3"); // [1, 2, 3] (split on comma, each coerced)
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); // 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)
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"); // throws "Unknown value"
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"); // 12.35 (rounded to minor units)
23
- PRICE.format(12.3); // "£12.30"
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
- name: new StringSchema({ title: "Name", min: 1, max: 100 }),
25
- price: new NumberSchema({ title: "Price", min: 0 }),
26
- available: BOOLEAN,
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
- name: STRING,
52
- price: NUMBER,
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); // null
23
- NULLABLE_NUMBER.validate(undefined); // null
24
- NULLABLE_NUMBER.validate(""); // null
25
- NULLABLE_NUMBER.validate(42); // 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"); // 3.14 (strings coerced)
26
- NUMBER.validate(undefined); // 0 (default)
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); // 3
38
- RATING.validate(0); // throws "Minimum 1"
37
+ RATING.validate(3); // 3
38
+ RATING.validate(0); // throws "Minimum 1"
39
39
  ```
40
40
 
41
41
 
@@ -21,7 +21,7 @@ import { OPTIONAL, NUMBER } from "shelving/schema";
21
21
 
22
22
  const OPTIONAL_NUMBER = OPTIONAL(NUMBER);
23
23
  OPTIONAL_NUMBER.validate(undefined); // undefined
24
- OPTIONAL_NUMBER.validate(42); // 42
24
+ OPTIONAL_NUMBER.validate(42); // 42
25
25
  ```
26
26
 
27
27
 
@@ -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"); // "hello"
26
- STRING.validate(42); // "42" (numbers coerced)
27
- STRING.validate(undefined); // "" (default)
28
- REQUIRED_STRING.validate(""); // throws "Required"
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"); // "alice_99"
40
- USERNAME.validate("al"); // throws "Minimum 3 characters"
41
- USERNAME.validate("ALICE"); // throws "Invalid string"
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 | Default | Purpose |
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()` | schema-specific | Display formatter for downstream form and UI use |
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` | `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>` |
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
- name: REQUIRED_STRING,
71
- price: NUMBER,
72
- tags: ARRAY(STRING),
73
- notes: OPTIONAL(STRING),
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" });
@@ -29,7 +29,7 @@ setInterval(() => seq.resolve("ping"), 1000);
29
29
 
30
30
  // Consume in one or more places simultaneously:
31
31
  for await (const msg of seq) {
32
- console.log(msg); // "ping" every second
32
+ console.log(msg); // "ping" every second
33
33
  }
34
34
  ```
35
35
 
@@ -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
- yield 10; yield 20; yield 30;
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
- console.log("yielded", n);
27
+ console.log("yielded", n);
26
28
  }
27
29
 
28
- console.log(watch.count); // 3
29
- console.log(watch.first); // 10
30
- console.log(watch.last); // 30
31
- console.log(watch.done); // true
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
- const id = setInterval(() => deferred.resolve(Date.now()), 500);
24
- return () => clearInterval(id); // StopCallback — runs when the last iterator finishes.
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
- console.log(ts); // the interval runs only for the duration of this loop
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
- constructor(private n: number) { super(); }
28
- async next() {
29
- return this.n > 0
30
- ? { done: false as const, value: this.n-- }
31
- : { done: true as const, value: undefined };
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
- yield 1; yield 2; yield 3;
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
- console.log(n); // 1, 2, 3
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
- const id = setInterval(() => deferred.resolve(Date.now()), 1000);
34
- return () => clearInterval(id);
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
- console.log(ts); // a timestamp every second, only while iterating
38
+ console.log(ts); // a timestamp every second, only while iterating
39
39
  }
40
40
  ```
41
41