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/ui/Notice.md CHANGED
@@ -30,27 +30,27 @@ import { Notice } from "shelving/ui";
30
30
  import { LOADING_NOTICE } from "shelving/ui";
31
31
 
32
32
  <Suspense fallback={LOADING_NOTICE}>
33
- <SlowPanel />
34
- </Suspense>
33
+ <SlowPanel />
34
+ </Suspense>;
35
35
  ```
36
36
 
37
37
  ## Styling
38
38
 
39
39
  `Notice` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Its `status` (or a `color=` / `status=` on an ancestor scope) sets the tint that the surface, border, and text all derive from; reach for a per-property hook for a single change.
40
40
 
41
- | Variable | Styles | Default |
42
- |---|---|---|
43
- | `--notice-background` | Surface fill | `var(--tint-90)` |
44
- | `--notice-color` | Text colour | `var(--tint-50)` |
45
- | `--notice-border` | Border shorthand | `var(--notice-stroke) solid var(--tint-80)` |
46
- | `--notice-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
47
- | `--notice-shadow` | Drop shadow, for example `var(--shadow-small)` | `none` |
48
- | `--notice-radius` | Corner radius | `var(--radius-xsmall)` |
49
- | `--notice-padding` | Inner top and bottom padding (one length) | `var(--space-small)` (12px) |
50
- | `--notice-indent` | Inner left and right padding (one length) | `var(--space-small)` (12px) |
51
- | `--notice-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` |
52
- | `--notice-size` | Font size | `var(--size-normal)` |
53
- | `--notice-weight` | Font weight | `var(--weight-strong)` |
41
+ | Variable | Styles | Default |
42
+ | --------------------- | ---------------------------------------------- | ------------------------------------------- |
43
+ | `--notice-background` | Surface fill | `var(--tint-90)` |
44
+ | `--notice-color` | Text colour | `var(--tint-50)` |
45
+ | `--notice-border` | Border shorthand | `var(--notice-stroke) solid var(--tint-80)` |
46
+ | `--notice-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
47
+ | `--notice-shadow` | Drop shadow, for example `var(--shadow-small)` | `none` |
48
+ | `--notice-radius` | Corner radius | `var(--radius-xsmall)` |
49
+ | `--notice-padding` | Inner top and bottom padding (one length) | `var(--space-small)` (12px) |
50
+ | `--notice-indent` | Inner left and right padding (one length) | `var(--space-small)` (12px) |
51
+ | `--notice-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` |
52
+ | `--notice-size` | Font size | `var(--size-normal)` |
53
+ | `--notice-weight` | Font weight | `var(--weight-strong)` |
54
54
 
55
55
  **Global tokens it reads** — the tint ladder `--tint-50` / `--tint-80` / `--tint-90`, plus `--space-paragraph`, `--space-small`, `--radius-xsmall`, `--stroke-normal`, `--size-normal`, and `--weight-strong`.
56
56
 
@@ -28,25 +28,25 @@ Mount once near the root of your app:
28
28
  import { Notices } from "shelving/ui";
29
29
 
30
30
  export function AppLayout({ children }) {
31
- return (
32
- <>
33
- {children}
34
- <Notices />
35
- </>
36
- );
31
+ return (
32
+ <>
33
+ {children}
34
+ <Notices />
35
+ </>
36
+ );
37
37
  }
38
38
  ```
39
39
 
40
40
  Show the list in the top-left corner:
41
41
 
42
42
  ```tsx
43
- <Notices position="top-left" />
43
+ <Notices position="top-left" />;
44
44
  ```
45
45
 
46
46
  Show the list at the top of the screen, in the centre:
47
47
 
48
48
  ```tsx
49
- <Notices position="top-center" />
49
+ <Notices position="top-center" />;
50
50
  ```
51
51
 
52
52
  Dispatch notices from anywhere — no context required:
@@ -59,8 +59,8 @@ notifyError("Could not connect.");
59
59
 
60
60
  // Wrap an async callback — dispatches success or error automatically.
61
61
  callNotified(async () => {
62
- await saveProfile(data);
63
- return "Profile updated.";
62
+ await saveProfile(data);
63
+ return "Profile updated.";
64
64
  });
65
65
  ```
66
66
 
@@ -80,13 +80,13 @@ notice.close(); // Or close it immediately.
80
80
 
81
81
  `Notices` positions the list in the place that `position` sets. Each notice is only as wide as its content and is aligned to the side of that corner, or to the centre. The list is never wider than `--notices-width`, and keeps `--notices-offset` clear at both sides on a narrow screen. The offset also adds the safe area of the device (`env(safe-area-inset-*)`). Clicks pass through the gaps between notices to the page. Each item is a `<Notice>`, which has its own hooks. Override these hooks at `:root` (or any ancestor scope) to retheme.
82
82
 
83
- | Variable | Styles | Default |
84
- |---|---|---|
85
- | `--notices-offset` | Distance of the list from the top or bottom edge, and from the left and right edges | `var(--space-normal)` (16px) |
86
- | `--notices-width` | Maximum width of the list and of each notice | `var(--width-narrow)` |
87
- | `--notices-shadow` | Drop shadow under each notice in the list (sets `--notice-shadow`) | `var(--shadow-normal)` |
88
- | `--notices-gap` | Gap between notices | `var(--space-small)` (12px) |
89
- | `--notices-transition-duration` | Length of the slide in, slide out, and move | `var(--duration-fast)` (150ms) |
83
+ | Variable | Styles | Default |
84
+ | ------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------ |
85
+ | `--notices-offset` | Distance of the list from the top or bottom edge, and from the left and right edges | `var(--space-normal)` (16px) |
86
+ | `--notices-width` | Maximum width of the list and of each notice | `var(--width-narrow)` |
87
+ | `--notices-shadow` | Drop shadow under each notice in the list (sets `--notice-shadow`) | `var(--shadow-normal)` |
88
+ | `--notices-gap` | Gap between notices | `var(--space-small)` (12px) |
89
+ | `--notices-transition-duration` | Length of the slide in, slide out, and move | `var(--duration-fast)` (150ms) |
90
90
 
91
91
  **Global tokens it reads** — move these to retheme broadly: `--space-normal`, `--space-small`, `--shadow-normal`, `--width-narrow`, and `--duration-fast`.
92
92
 
package/docs/ui/Page.md CHANGED
@@ -21,11 +21,11 @@ Wraps one page (or screen) inside an app, applying its per-page metadata. It mer
21
21
  import { Page, Section } from "shelving/ui";
22
22
 
23
23
  function UserPage({ id }: { id: string }) {
24
- return (
25
- <Page title="User profile" url={`/users/${id}`} description="View user details.">
26
- <Section>…</Section>
27
- </Page>
28
- );
24
+ return (
25
+ <Page title="User profile" url={`/users/${id}`} description="View user details.">
26
+ <Section>…</Section>
27
+ </Page>
28
+ );
29
29
  }
30
30
  ```
31
31
 
@@ -35,14 +35,14 @@ A page renders no layout. The layout goes outside the page, above the router, so
35
35
  import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
36
36
 
37
37
  <FixedLayout>
38
- <Scroll vertical cover>
39
- <Page title="Sign in">
40
- <Block height="full" middle width="narrow">
41
- <LoginForm/>
42
- </Block>
43
- </Page>
44
- </Scroll>
45
- </FixedLayout>
38
+ <Scroll vertical cover>
39
+ <Page title="Sign in">
40
+ <Block height="full" middle width="narrow">
41
+ <LoginForm />
42
+ </Block>
43
+ </Page>
44
+ </Scroll>
45
+ </FixedLayout>;
46
46
  ```
47
47
 
48
48
 
package/docs/ui/Panel.md CHANGED
@@ -42,14 +42,14 @@ import { Panel, Block, Title, Paragraph } from "shelving/ui";
42
42
 
43
43
  `Panel` paints from the [tint ladder](/ui/TINT_CLASS); apply `color=` / `status=` (on the panel or an ancestor scope) to recolour the whole scope at once — surface and text re-derive together — or reach for a per-property hook for a single change.
44
44
 
45
- | Variable | Styles | Default |
46
- |---|---|---|
47
- | `--panel-background` | Surface fill | `var(--tint-90)` |
48
- | `--panel-color` | Text colour | `var(--tint-00)` |
49
- | `--panel-border` | Top/bottom border shorthand | `var(--panel-stroke) solid var(--tint-80)` |
50
- | `--panel-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
51
- | `--panel-padding` | Block padding (top + bottom) | `var(--space-section)` (2rem) |
52
- | `--panel-indent` | Inline padding (left + right) keeping content off the edges | `var(--space-normal)` (16px) |
45
+ | Variable | Styles | Default |
46
+ | -------------------- | -------------------------------------------------------------------------- | ------------------------------------------ |
47
+ | `--panel-background` | Surface fill | `var(--tint-90)` |
48
+ | `--panel-color` | Text colour | `var(--tint-00)` |
49
+ | `--panel-border` | Top/bottom border shorthand | `var(--panel-stroke) solid var(--tint-80)` |
50
+ | `--panel-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
51
+ | `--panel-padding` | Block padding (top + bottom) | `var(--space-section)` (2rem) |
52
+ | `--panel-indent` | Inline padding (left + right) keeping content off the edges | `var(--space-normal)` (16px) |
53
53
 
54
54
  **Global tokens it reads:** the tint-ladder steps `--tint-00` / `--tint-80` / `--tint-90`, plus `--space-section`, and `--space-normal`. The shared `padding` variant overrides `--panel-padding`; the shared `indent` variant overrides `--panel-indent`.
55
55
 
@@ -21,7 +21,7 @@ A block of body text — renders a `<p>`. The default container for running pros
21
21
  ```tsx live
22
22
  import { Paragraph } from "shelving/ui";
23
23
 
24
- <Paragraph>The best widget on the market.</Paragraph>
24
+ <Paragraph>The best widget on the market.</Paragraph>;
25
25
  ```
26
26
 
27
27
  ### With inline annotations
@@ -30,16 +30,16 @@ import { Paragraph } from "shelving/ui";
30
30
  import { Paragraph, Strong, Link } from "shelving/ui";
31
31
 
32
32
  <Paragraph>
33
- <Strong>Note:</Strong> read our <Link href="/privacy">privacy policy</Link> first.
34
- </Paragraph>
33
+ <Strong>Note:</Strong> read our <Link href="/privacy">privacy policy</Link> first.
34
+ </Paragraph>;
35
35
  ```
36
36
 
37
37
  ## Styling
38
38
 
39
39
  `Paragraph` exposes a single hook for its own block margin; it paints no colour of its own, so it inherits the surrounding text colour. Apply `color=` / `status=` to set the tint scope for any ladder-reading inline content inside it.
40
40
 
41
- | Variable | Styles | Default |
42
- |---|---|---|
41
+ | Variable | Styles | Default |
42
+ | ------------------- | --------------------------------- | ------------------------------- |
43
43
  | `--paragraph-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
44
44
 
45
45
  **Global tokens it reads:** `--space-paragraph`.
@@ -29,7 +29,7 @@ A continuous horizontal progress bar for the completion of a task. Rendered as a
29
29
  import { Progress } from "shelving/ui";
30
30
 
31
31
  // 75% full.
32
- <Progress value={3} max={4} />
32
+ <Progress value={3} max={4} />;
33
33
  ```
34
34
 
35
35
  ### Custom range
@@ -38,7 +38,7 @@ import { Progress } from "shelving/ui";
38
38
  import { Progress } from "shelving/ui";
39
39
 
40
40
  // 50% full — value 15 within the 10–20 range.
41
- <Progress value={15} min={10} max={20} />
41
+ <Progress value={15} min={10} max={20} />;
42
42
  ```
43
43
 
44
44
  ### Status and colour
@@ -67,21 +67,21 @@ import { Progress } from "shelving/ui";
67
67
 
68
68
  `Progress` paints a track (the element / `::-webkit-progress-bar`) and a fill (`::-webkit-progress-value` / `::-moz-progress-bar`) from the [tint ladder](/ui/TINT_CLASS). Apply `color=` / `status=` (on the bar or a tinted ancestor scope) to recolour the fill and track together — reach for a per-property hook only for a single surgical change. Override these hooks at `:root` (or any ancestor scope) to retheme.
69
69
 
70
- | Variable | Styles | Default |
71
- |---|---|---|
72
- | `--progress-height` | Bar thickness | `0.375rem` (6px) |
73
- | `--progress-radius` | Corner radius | `999px` (pill) |
74
- | `--progress-background` | Track fill | `var(--tint-90)` |
75
- | `--progress-color` | Fill colour | `var(--tint-50)` |
76
- | `--progress-duration` | Indeterminate flow-loop duration | `1.5s` |
70
+ | Variable | Styles | Default |
71
+ | ----------------------- | -------------------------------- | ---------------- |
72
+ | `--progress-height` | Bar thickness | `0.375rem` (6px) |
73
+ | `--progress-radius` | Corner radius | `999px` (pill) |
74
+ | `--progress-background` | Track fill | `var(--tint-90)` |
75
+ | `--progress-color` | Fill colour | `var(--tint-50)` |
76
+ | `--progress-duration` | Indeterminate flow-loop duration | `1.5s` |
77
77
 
78
78
  **Global tokens it reads** — move these to retheme broadly rather than overriding the hooks directly: the tint-ladder steps `--tint-50` (fill) and `--tint-90` (track), plus `--duration-fast` (the fill's grow transition). To recolour a bar, prefer `color=` / `status=` (or a tinted ancestor scope) over the per-component hooks.
79
79
 
80
80
  ```css
81
81
  /* Theme: a chunkier, square-cornered bar. */
82
82
  :root {
83
- --progress-height: 0.75rem;
84
- --progress-radius: var(--radius-small);
83
+ --progress-height: 0.75rem;
84
+ --progress-radius: var(--radius-small);
85
85
  }
86
86
  ```
87
87
 
package/docs/ui/Prose.md CHANGED
@@ -10,7 +10,7 @@ A wrapper that applies cohesive longform typography to a subtree of mixed HTML c
10
10
 
11
11
  **Things to know:**
12
12
 
13
- - `Prose` applies the "prose" variant of *every* block and inline component as a single compound class, so raw `<p>`, `<ul>`, `<h2>`, `<code>`, `<a>`, `<progress>`, etc. are styled to match their component counterparts (`<Paragraph>`, `<List>`, `<Heading>`, `<Code>`, `<Link>`, `<Progress>`, …).
13
+ - `Prose` applies the "prose" variant of _every_ block and inline component as a single compound class, so raw `<p>`, `<ul>`, `<h2>`, `<code>`, `<a>`, `<progress>`, etc. are styled to match their component counterparts (`<Paragraph>`, `<List>`, `<Heading>`, `<Code>`, `<Link>`, `<Progress>`, …).
14
14
  - This is the bridge for markup: wrap `shelving/markup` output (or anything that emits raw HTML) in `<Prose>` and it just works — no per-element component wrapping needed.
15
15
  - It only sets up typography and its own outer margin; it paints no colour and adds no box of its own.
16
16
 
@@ -22,8 +22,8 @@ A wrapper that applies cohesive longform typography to a subtree of mixed HTML c
22
22
  import { Prose, Markup } from "shelving/ui";
23
23
 
24
24
  <Prose>
25
- <Markup>{article.body}</Markup>
26
- </Prose>
25
+ <Markup>{article.body}</Markup>
26
+ </Prose>;
27
27
  ```
28
28
 
29
29
  ### Hand-written longform
@@ -32,9 +32,9 @@ import { Prose, Markup } from "shelving/ui";
32
32
  import { Prose, Paragraph } from "shelving/ui";
33
33
 
34
34
  <Prose>
35
- <Paragraph>First.</Paragraph>
36
- <Paragraph>Second.</Paragraph>
37
- </Prose>
35
+ <Paragraph>First.</Paragraph>
36
+ <Paragraph>Second.</Paragraph>
37
+ </Prose>;
38
38
  ```
39
39
 
40
40
  ## Styling
@@ -30,7 +30,7 @@ import { StringSchema } from "shelving/schema";
30
30
 
31
31
  const SEARCH = new StringSchema({ title: "Search", one: "user" });
32
32
 
33
- <QueryRadiosInput name="user" schema={SEARCH} onQuery={search} value={user} onValue={setUser} />
33
+ <QueryRadiosInput name="user" schema={SEARCH} onQuery={search} value={user} onValue={setUser} />;
34
34
  ```
35
35
 
36
36
  ### Inline list with avatars
@@ -43,7 +43,7 @@ const SEARCH = new StringSchema({ title: "Search", one: "user" });
43
43
  onQuery={search}
44
44
  formatter={user => <Avatar user={user} />}
45
45
  onValue={setUser}
46
- />
46
+ />;
47
47
  ```
48
48
 
49
49
  ## Styling
@@ -41,26 +41,26 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
41
41
  import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
42
42
 
43
43
  <AppLayout nav={<StackBar />}>
44
- <HorizontalTransition>
45
- <RouteCache>
46
- <Scroll vertical cover>
47
- <PageLoader>
48
- <Router routes={ROUTES}/>
49
- </PageLoader>
50
- </Scroll>
51
- </RouteCache>
52
- </HorizontalTransition>
53
- </AppLayout>
44
+ <HorizontalTransition>
45
+ <RouteCache>
46
+ <Scroll vertical cover>
47
+ <PageLoader>
48
+ <Router routes={ROUTES} />
49
+ </PageLoader>
50
+ </Scroll>
51
+ </RouteCache>
52
+ </HorizontalTransition>
53
+ </AppLayout>;
54
54
  ```
55
55
 
56
56
  Keep fewer pages:
57
57
 
58
58
  ```tsx
59
59
  <RouteCache maxCached={5}>
60
- <Scroll vertical cover>
61
- <Router routes={ROUTES}/>
62
- </Scroll>
63
- </RouteCache>
60
+ <Scroll vertical cover>
61
+ <Router routes={ROUTES} />
62
+ </Scroll>
63
+ </RouteCache>;
64
64
  ```
65
65
 
66
66
  Clear a create form after it saves. Change the `key` of the `<Form>`, so it mounts again with no input:
@@ -70,19 +70,19 @@ import { useState } from "react";
70
70
  import { Form, requireNavigation } from "shelving/ui";
71
71
 
72
72
  function NewPostPage() {
73
- const nav = requireNavigation();
74
- const [formKey, setFormKey] = useState(0);
75
- return (
76
- <Form
77
- key={formKey}
78
- schema={POST_SCHEMA}
79
- onSubmit={async data => {
80
- const id = await createPost(data);
81
- setFormKey(k => k + 1);
82
- nav.forward(`/post/${id}`);
83
- }}
84
- />
85
- );
73
+ const nav = requireNavigation();
74
+ const [formKey, setFormKey] = useState(0);
75
+ return (
76
+ <Form
77
+ key={formKey}
78
+ schema={POST_SCHEMA}
79
+ onSubmit={async data => {
80
+ const id = await createPost(data);
81
+ setFormKey(k => k + 1);
82
+ nav.forward(`/post/${id}`);
83
+ }}
84
+ />
85
+ );
86
86
  }
87
87
  ```
88
88
 
package/docs/ui/Router.md CHANGED
@@ -31,37 +31,39 @@ A pure URL matcher: it reads the current URL from the surrounding `<Meta>` conte
31
31
  import { HTML, Navigation, Router } from "shelving/ui";
32
32
 
33
33
  <HTML url={initialUrl} root="https://example.com/">
34
- <Navigation>
35
- <Router routes={{
36
- "/": HomePage,
37
- "/users/{id}": UserPage,
38
- "/about": AboutPage,
39
- }}/>
40
- </Navigation>
41
- </HTML>
34
+ <Navigation>
35
+ <Router
36
+ routes={{
37
+ "/": HomePage,
38
+ "/users/{id}": UserPage,
39
+ "/about": AboutPage,
40
+ }}
41
+ />
42
+ </Navigation>
43
+ </HTML>;
42
44
  ```
43
45
 
44
46
  ### Route value types
45
47
 
46
- | Value | Behaviour |
47
- |---|---|
48
- | Component | Rendered as `<Component {...params}/>` with merged placeholder + query props. |
49
- | `AbsolutePath` string | Redirects to that path (placeholders resolved against the source). |
50
- | `ReactElement` | Rendered as-is — use for layout wrapping or composing inner routers. |
51
- | `null` / `false` | Skipped, as if the route were absent — lets a route be conditionally disabled. |
48
+ | Value | Behaviour |
49
+ | --------------------- | ------------------------------------------------------------------------------ |
50
+ | Component | Rendered as `<Component {...params}/>` with merged placeholder + query props. |
51
+ | `AbsolutePath` string | Redirects to that path (placeholders resolved against the source). |
52
+ | `ReactElement` | Rendered as-is — use for layout wrapping or composing inner routers. |
53
+ | `null` / `false` | Skipped, as if the route were absent — lets a route be conditionally disabled. |
52
54
 
53
55
  ### Placeholder syntax
54
56
 
55
57
  All forms produce the same matched value — pick whichever reads best:
56
58
 
57
- | Form | Single segment | Catchall (one+ segments, also matches empty) |
58
- |---|---|---|
59
- | Anonymous | `*` (named `"0"`) | `**` / `***` (named `"0"`) |
60
- | Colon | `:name` | `:name*` / `:name**` |
61
- | Single brace | `{name}` | `{...name}` / `{name*}` |
62
- | Square bracket | `[name]` | `[...name]` / `[name*]` |
63
- | Dollar brace | `${name}` | `${...name}` / `${name*}` |
64
- | Double brace | `{{name}}` | `{{...name}}` / `{{name*}}` |
59
+ | Form | Single segment | Catchall (one+ segments, also matches empty) |
60
+ | -------------- | ----------------- | -------------------------------------------- |
61
+ | Anonymous | `*` (named `"0"`) | `**` / `***` (named `"0"`) |
62
+ | Colon | `:name` | `:name*` / `:name**` |
63
+ | Single brace | `{name}` | `{...name}` / `{name*}` |
64
+ | Square bracket | `[name]` | `[...name]` / `[name*]` |
65
+ | Dollar brace | `${name}` | `${...name}` / `${name*}` |
66
+ | Double brace | `{{name}}` | `{{...name}}` / `{{name*}}` |
65
67
 
66
68
  Modifier chars are tolerant: one-or-more stars and three-or-more dots are all equivalent, so `{path*}`, `{path**}`, `{...path}`, and `{....path}` behave the same. Catchall placeholders allow empty values, so a trailing catchall matches the trailing-slash-absent variant — `/files/{...path}` matches `/files`, `/files/`, and `/files/a/b/c`.
67
69
 
@@ -71,21 +73,23 @@ Put layout JSX as the route value with another `<Router>` inside. Since `<Router
71
73
 
72
74
  ```tsx
73
75
  const SIDEBARRED_ROUTES = {
74
- "/users": <UsersPage/>,
75
- "/users/{id}": <UserPage/>,
76
- "/settings": <SettingsPage/>,
76
+ "/users": <UsersPage />,
77
+ "/users/{id}": <UserPage />,
78
+ "/settings": <SettingsPage />,
77
79
  };
78
80
 
79
- <Router routes={{
80
- "/": <HomePage/>,
81
- "/{...path}": (
82
- <SidebarLayout sidebar={<Nav/>}>
83
- <Scroll vertical cover>
84
- <Router routes={SIDEBARRED_ROUTES}/>
85
- </Scroll>
86
- </SidebarLayout>
87
- ),
88
- }}/>
81
+ <Router
82
+ routes={{
83
+ "/": <HomePage />,
84
+ "/{...path}": (
85
+ <SidebarLayout sidebar={<Nav />}>
86
+ <Scroll vertical cover>
87
+ <Router routes={SIDEBARRED_ROUTES} />
88
+ </Scroll>
89
+ </SidebarLayout>
90
+ ),
91
+ }}
92
+ />;
89
93
  ```
90
94
 
91
95
  ### Section / microsite pattern
@@ -94,21 +98,23 @@ A self-contained "section" — its own URL prefix and routes — composes via a
94
98
 
95
99
  ```tsx
96
100
  const USER_ROUTES = {
97
- "/": UsersPage,
98
- "/{id}": UserPage,
99
- "/{id}/edit": UserEditPage,
101
+ "/": UsersPage,
102
+ "/{id}": UserPage,
103
+ "/{id}/edit": UserEditPage,
100
104
  };
101
105
 
102
106
  export function UserRouter({ path = "/" }: { path?: AbsolutePath }) {
103
- return <Router routes={USER_ROUTES} url={path}/>;
107
+ return <Router routes={USER_ROUTES} url={path} />;
104
108
  }
105
109
 
106
110
  // At the call site — the top-level router stays a flat list of section prefixes:
107
- <Router routes={{
108
- "/": <HomePage/>,
109
- "/users/{...path}": ({ path }) => <UserRouter path={path}/>,
110
- "/blog/{...path}": ({ path }) => <BlogRouter path={path}/>,
111
- }}/>
111
+ <Router
112
+ routes={{
113
+ "/": <HomePage />,
114
+ "/users/{...path}": ({ path }) => <UserRouter path={path} />,
115
+ "/blog/{...path}": ({ path }) => <BlogRouter path={path} />,
116
+ }}
117
+ />;
112
118
  ```
113
119
 
114
120
  The outer router captures everything under `/users` into `path`; the inner router treats it as its starting URL, so its `"/"` matches the bare `/users` and `/{id}` matches `/users/123`.
@@ -119,22 +125,25 @@ The two patterns compose — wrap a group of routes in a layout, then route furt
119
125
 
120
126
  ```tsx
121
127
  const SIDEBARRED_ROUTES = {
122
- "/": <Dashboard/>,
123
- "/users/{...path}": ({ path }) => <UserRouter path={path}/>,
124
- "/blog/{...path}": ({ path }) => <BlogRouter path={path}/>,
125
- "/settings": <SettingsPage/>,
128
+ "/": <Dashboard />,
129
+ "/users/{...path}": ({ path }) => <UserRouter path={path} />,
130
+ "/blog/{...path}": ({ path }) => <BlogRouter path={path} />,
131
+ "/settings": <SettingsPage />,
126
132
  };
127
133
 
128
- <Router routes={{
129
- "/login": <LoginPage/>, // no sidebar
130
- "/{...path}": ( // everything else wrapped
131
- <SidebarLayout sidebar={<Nav/>}>
132
- <Scroll vertical cover>
133
- <Router routes={SIDEBARRED_ROUTES}/>
134
- </Scroll>
135
- </SidebarLayout>
136
- ),
137
- }}/>
134
+ <Router
135
+ routes={{
136
+ "/login": <LoginPage />, // no sidebar
137
+ "/{...path}": // everything else wrapped
138
+ (
139
+ <SidebarLayout sidebar={<Nav />}>
140
+ <Scroll vertical cover>
141
+ <Router routes={SIDEBARRED_ROUTES} />
142
+ </Scroll>
143
+ </SidebarLayout>
144
+ ),
145
+ }}
146
+ />;
138
147
  ```
139
148
 
140
149
  ### Keeping page state
@@ -147,9 +156,9 @@ By default a page is unmounted when you navigate away and mounted fresh when you
147
156
 
148
157
  ```tsx
149
158
  renderToString(
150
- <HTML url={path} root="https://example.com/">
151
- <Router routes={ROUTES}/>
152
- </HTML>
159
+ <HTML url={path} root="https://example.com/">
160
+ <Router routes={ROUTES} />
161
+ </HTML>,
153
162
  );
154
163
  ```
155
164
 
@@ -18,28 +18,28 @@ Schema-driven input dispatch. `SchemaInput` inspects a `Schema` instance and ren
18
18
 
19
19
  The schema-to-input mapping:
20
20
 
21
- | Schema type | Rendered as |
22
- |---|---|
23
- | `StringSchema` | `<TextInput>` |
24
- | `NumberSchema` | `<NumberInput>` (formatted on blur) |
25
- | `DateSchema` | `<DateInput>` |
26
- | `BooleanSchema` | `<CheckboxInput>` |
27
- | `ChoiceSchema` (`input: "radio"`, the default for ≤ 8 options) | `<ChoiceRadioInputs>` |
28
- | `ChoiceSchema` (`input: "select"`, the default for > 8 options) | `<SelectInput>` |
29
- | `ArraySchema` | `<ArrayInput>` |
30
- | `DictionarySchema` | `<DictionaryInput>` |
31
- | `DataSchema` | `<DataInput>` |
21
+ | Schema type | Rendered as |
22
+ | --------------------------------------------------------------- | ----------------------------------- |
23
+ | `StringSchema` | `<TextInput>` |
24
+ | `NumberSchema` | `<NumberInput>` (formatted on blur) |
25
+ | `DateSchema` | `<DateInput>` |
26
+ | `BooleanSchema` | `<CheckboxInput>` |
27
+ | `ChoiceSchema` (`input: "radio"`, the default for ≤ 8 options) | `<ChoiceRadioInputs>` |
28
+ | `ChoiceSchema` (`input: "select"`, the default for > 8 options) | `<SelectInput>` |
29
+ | `ArraySchema` | `<ArrayInput>` |
30
+ | `DictionarySchema` | `<DictionaryInput>` |
31
+ | `DataSchema` | `<DataInput>` |
32
32
 
33
33
  The shared value-input prop contract (`ValueInputProps<O>`):
34
34
 
35
- | Prop | Contract |
36
- |---|---|
37
- | `name` | HTML field name |
38
- | `value` | Current value |
39
- | `onValue(v)` | Called on every change |
40
- | `required` | Marks the field as required |
41
- | `disabled` | Disables the control |
42
- | `message` | Inline error string |
35
+ | Prop | Contract |
36
+ | ------------ | --------------------------- |
37
+ | `name` | HTML field name |
38
+ | `value` | Current value |
39
+ | `onValue(v)` | Called on every change |
40
+ | `required` | Marks the field as required |
41
+ | `disabled` | Disables the control |
42
+ | `message` | Inline error string |
43
43
 
44
44
  `<DataInput>` renders a row of `SchemaInput` elements for each property of a nested data object, and propagates sub-field errors from a `"key: message\n…"` formatted `message` string. `ArrayInput` and `DictionaryInput` both accept an `items` schema to render a repeatable list of sub-inputs with add/remove buttons.
45
45
 
@@ -60,7 +60,7 @@ import { StringSchema, NumberSchema } from "shelving/schema";
60
60
  ```tsx
61
61
  import { SchemaField } from "shelving/ui";
62
62
 
63
- <SchemaField name="email" schema={EMAIL_SCHEMA} /> // <Field> wrapping a <TextInput>
63
+ <SchemaField name="email" schema={EMAIL_SCHEMA} />; // <Field> wrapping a <TextInput>
64
64
  ```
65
65
 
66
66