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
@@ -29,7 +29,7 @@ import { Catcher, ErrorPage, RetryButton } from "shelving/ui";
29
29
 
30
30
  // Custom error renderer plus a retry button anywhere in the subtree.
31
31
  <Catcher as={ErrorPage}>
32
- <RiskyComponent />
33
- <RetryButton small />
34
- </Catcher>
32
+ <RiskyComponent />
33
+ <RetryButton small />
34
+ </Catcher>;
35
35
  ```
package/ui/misc/Icon.md CHANGED
@@ -20,9 +20,9 @@ import { Icon } from "shelving/ui";
20
20
 
21
21
  ## Styling
22
22
 
23
- | Variable | Styles | Default |
24
- |---|---|---|
25
- | `--icon-color` | Icon colour | `var(--tint-50)` (the status tint, e.g. `--color-failure` for `status="error"`) |
26
- | `--icon-size` | Icon width / height | `var(--size-icon)` (1.5rem) |
23
+ | Variable | Styles | Default |
24
+ | -------------- | ------------------- | ------------------------------------------------------------------------------- |
25
+ | `--icon-color` | Icon colour | `var(--tint-50)` (the status tint, e.g. `--color-failure` for `status="error"`) |
26
+ | `--icon-size` | Icon width / height | `var(--size-icon)` (1.5rem) |
27
27
 
28
28
  **Global tokens it reads** — the status tint anchor `--tint-50`, `--size-icon` (the unset-`size` default), plus the size tokens `--size-small` / `--size-normal` / `--size-large` / `--size-xlarge` / `--size-xxlarge` used by the `size` prop.
@@ -32,11 +32,11 @@ import { Icon, LOADING, Loading } from "shelving/ui";
32
32
 
33
33
  Size, centring, and overall colour come from wrapping it in `<Icon>` — its `--icon-color` / `--icon-size` hooks and `color` / `status` / `size` / `tint` variants drive the spinner (see the `Icon` Styling section). On top of that, the two arcs expose their own hooks:
34
34
 
35
- | Variable | Styles | Default |
36
- |---|---|---|
37
- | `--loading-track` | Track (background arc) stroke | `var(--tint-70)` |
38
- | `--loading-indicator` | Indicator (moving arc) stroke | `var(--tint-80)` |
39
- | `--loading-stroke-width` | Stroke width of both arcs | `2.5` |
40
- | `--loading-length` | `stroke-dasharray` of the indicator arc | `28 100` |
35
+ | Variable | Styles | Default |
36
+ | ------------------------ | --------------------------------------- | ---------------- |
37
+ | `--loading-track` | Track (background arc) stroke | `var(--tint-70)` |
38
+ | `--loading-indicator` | Indicator (moving arc) stroke | `var(--tint-80)` |
39
+ | `--loading-stroke-width` | Stroke width of both arcs | `2.5` |
40
+ | `--loading-length` | `stroke-dasharray` of the indicator arc | `28 100` |
41
41
 
42
42
  **Global tokens it reads** — the tint-ladder steps `--tint-70` / `--tint-80` for the arc strokes (rebound by the `color` / `status` / `tint` variants on the wrapping `<Icon>`).
package/ui/misc/Markup.md CHANGED
@@ -15,8 +15,8 @@ Parses a markup string and renders the resulting React nodes inline. Defaults to
15
15
  import { Prose, Markup } from "shelving/ui";
16
16
 
17
17
  <Prose>
18
- <Markup>{article.body}</Markup>
19
- </Prose>
18
+ <Markup>{article.body}</Markup>
19
+ </Prose>;
20
20
  ```
21
21
 
22
22
  ```tsx
@@ -24,6 +24,6 @@ import { Markup } from "shelving/ui";
24
24
 
25
25
  // Custom rule set or base URL via MarkupOptions props.
26
26
  <Markup rules={INLINE_ONLY} root="https://example.com">
27
- {comment.body}
28
- </Markup>
27
+ {comment.body}
28
+ </Markup>;
29
29
  ```
package/ui/misc/Tag.md CHANGED
@@ -22,20 +22,20 @@ import { Tag } from "shelving/ui";
22
22
 
23
23
  `Tag` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` (on the tag or an ancestor scope) to recolour the whole tag at once.
24
24
 
25
- | Variable | Styles | Default |
26
- |---|---|---|
27
- | `--tag-background` | Surface fill | `var(--tint-50)` |
28
- | `--tag-hover-background` | Surface fill when an interactive tag is hovered | `var(--tint-55)` |
29
- | `--tag-color` | Text colour | `var(--tint-100)` |
30
- | `--tag-padding` | Inner top and bottom padding (one length) | `0` |
31
- | `--tag-indent` | Inner left and right padding (one length) | `var(--space-xxsmall)` (4px) |
32
- | `--tag-border` | Border shorthand | `0` |
33
- | `--tag-radius` | Corner radius | `var(--radius-xxsmall)` |
34
- | `--tag-font` | Font family | `var(--font-body)` |
35
- | `--tag-size` | Font size | `var(--size-small)` |
36
- | `--tag-weight` | Font weight | `var(--weight-strong)` |
37
- | `--tag-leading` | Line height | `var(--leading)` |
38
- | `--tag-case` | Text transform | `var(--case-label)` |
39
- | `--tag-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
25
+ | Variable | Styles | Default |
26
+ | ------------------------ | ----------------------------------------------- | ---------------------------------------------- |
27
+ | `--tag-background` | Surface fill | `var(--tint-50)` |
28
+ | `--tag-hover-background` | Surface fill when an interactive tag is hovered | `var(--tint-55)` |
29
+ | `--tag-color` | Text colour | `var(--tint-100)` |
30
+ | `--tag-padding` | Inner top and bottom padding (one length) | `0` |
31
+ | `--tag-indent` | Inner left and right padding (one length) | `var(--space-xxsmall)` (4px) |
32
+ | `--tag-border` | Border shorthand | `0` |
33
+ | `--tag-radius` | Corner radius | `var(--radius-xxsmall)` |
34
+ | `--tag-font` | Font family | `var(--font-body)` |
35
+ | `--tag-size` | Font size | `var(--size-small)` |
36
+ | `--tag-weight` | Font weight | `var(--weight-strong)` |
37
+ | `--tag-leading` | Line height | `var(--leading)` |
38
+ | `--tag-case` | Text transform | `var(--case-label)` |
39
+ | `--tag-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
40
40
 
41
41
  **Global tokens it reads** — the tint ladder `--tint-50` / `--tint-55` / `--tint-100`, plus `--space-xxsmall`, `--radius-xxsmall`, `--font-body`, `--size-small`, `--weight-strong`, `--leading`, `--case-label`, `--stroke-normal`, `--stroke-focus`, and `--color-focus`.
@@ -17,7 +17,7 @@ import { Empty, Paragraph } from "shelving/ui";
17
17
 
18
18
  <Empty>
19
19
  <Paragraph>No challenges yet.</Paragraph>
20
- </Empty>
20
+ </Empty>;
21
21
  ```
22
22
 
23
23
  ### Loading list
@@ -27,7 +27,7 @@ import { EMPTY_LOADING, Loader } from "shelving/ui";
27
27
 
28
28
  <Loader fallback={EMPTY_LOADING}>
29
29
  <LoadChallenges />
30
- </Loader>
30
+ </Loader>;
31
31
  ```
32
32
 
33
33
  ## Styling
@@ -22,26 +22,26 @@ import { Notice } from "shelving/ui";
22
22
  import { LOADING_NOTICE } from "shelving/ui";
23
23
 
24
24
  <Suspense fallback={LOADING_NOTICE}>
25
- <SlowPanel />
26
- </Suspense>
25
+ <SlowPanel />
26
+ </Suspense>;
27
27
  ```
28
28
 
29
29
  ## Styling
30
30
 
31
31
  `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.
32
32
 
33
- | Variable | Styles | Default |
34
- |---|---|---|
35
- | `--notice-background` | Surface fill | `var(--tint-90)` |
36
- | `--notice-color` | Text colour | `var(--tint-50)` |
37
- | `--notice-border` | Border shorthand | `var(--notice-stroke) solid var(--tint-80)` |
38
- | `--notice-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
39
- | `--notice-shadow` | Drop shadow, for example `var(--shadow-small)` | `none` |
40
- | `--notice-radius` | Corner radius | `var(--radius-xsmall)` |
41
- | `--notice-padding` | Inner top and bottom padding (one length) | `var(--space-small)` (12px) |
42
- | `--notice-indent` | Inner left and right padding (one length) | `var(--space-small)` (12px) |
43
- | `--notice-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` |
44
- | `--notice-size` | Font size | `var(--size-normal)` |
45
- | `--notice-weight` | Font weight | `var(--weight-strong)` |
33
+ | Variable | Styles | Default |
34
+ | --------------------- | ---------------------------------------------- | ------------------------------------------- |
35
+ | `--notice-background` | Surface fill | `var(--tint-90)` |
36
+ | `--notice-color` | Text colour | `var(--tint-50)` |
37
+ | `--notice-border` | Border shorthand | `var(--notice-stroke) solid var(--tint-80)` |
38
+ | `--notice-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
39
+ | `--notice-shadow` | Drop shadow, for example `var(--shadow-small)` | `none` |
40
+ | `--notice-radius` | Corner radius | `var(--radius-xsmall)` |
41
+ | `--notice-padding` | Inner top and bottom padding (one length) | `var(--space-small)` (12px) |
42
+ | `--notice-indent` | Inner left and right padding (one length) | `var(--space-small)` (12px) |
43
+ | `--notice-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` |
44
+ | `--notice-size` | Font size | `var(--size-normal)` |
45
+ | `--notice-weight` | Font weight | `var(--weight-strong)` |
46
46
 
47
47
  **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`.
@@ -19,25 +19,25 @@ Mount once near the root of your app:
19
19
  import { Notices } from "shelving/ui";
20
20
 
21
21
  export function AppLayout({ children }) {
22
- return (
23
- <>
24
- {children}
25
- <Notices />
26
- </>
27
- );
22
+ return (
23
+ <>
24
+ {children}
25
+ <Notices />
26
+ </>
27
+ );
28
28
  }
29
29
  ```
30
30
 
31
31
  Show the list in the top-left corner:
32
32
 
33
33
  ```tsx
34
- <Notices position="top-left" />
34
+ <Notices position="top-left" />;
35
35
  ```
36
36
 
37
37
  Show the list at the top of the screen, in the centre:
38
38
 
39
39
  ```tsx
40
- <Notices position="top-center" />
40
+ <Notices position="top-center" />;
41
41
  ```
42
42
 
43
43
  Dispatch notices from anywhere — no context required:
@@ -50,8 +50,8 @@ notifyError("Could not connect.");
50
50
 
51
51
  // Wrap an async callback — dispatches success or error automatically.
52
52
  callNotified(async () => {
53
- await saveProfile(data);
54
- return "Profile updated.";
53
+ await saveProfile(data);
54
+ return "Profile updated.";
55
55
  });
56
56
  ```
57
57
 
@@ -71,12 +71,12 @@ notice.close(); // Or close it immediately.
71
71
 
72
72
  `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.
73
73
 
74
- | Variable | Styles | Default |
75
- |---|---|---|
76
- | `--notices-offset` | Distance of the list from the top or bottom edge, and from the left and right edges | `var(--space-normal)` (16px) |
77
- | `--notices-width` | Maximum width of the list and of each notice | `var(--width-narrow)` |
78
- | `--notices-shadow` | Drop shadow under each notice in the list (sets `--notice-shadow`) | `var(--shadow-normal)` |
79
- | `--notices-gap` | Gap between notices | `var(--space-small)` (12px) |
80
- | `--notices-transition-duration` | Length of the slide in, slide out, and move | `var(--duration-fast)` (150ms) |
74
+ | Variable | Styles | Default |
75
+ | ------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------ |
76
+ | `--notices-offset` | Distance of the list from the top or bottom edge, and from the left and right edges | `var(--space-normal)` (16px) |
77
+ | `--notices-width` | Maximum width of the list and of each notice | `var(--width-narrow)` |
78
+ | `--notices-shadow` | Drop shadow under each notice in the list (sets `--notice-shadow`) | `var(--shadow-normal)` |
79
+ | `--notices-gap` | Gap between notices | `var(--space-small)` (12px) |
80
+ | `--notices-transition-duration` | Length of the slide in, slide out, and move | `var(--duration-fast)` (150ms) |
81
81
 
82
82
  **Global tokens it reads** — move these to retheme broadly: `--space-normal`, `--space-small`, `--shadow-normal`, `--width-narrow`, and `--duration-fast`.
package/ui/page/HTML.md CHANGED
@@ -16,14 +16,16 @@ import { Navigation, Router } from "shelving/ui";
16
16
 
17
17
  // Server-side render — pass the request URL to <HTML>.
18
18
  renderToString(
19
- <HTML app="My App" root="https://example.com/" url={requestUrl} language="en">
20
- <Navigation>
21
- <Router routes={{
22
- "/": HomePage,
23
- "/about": AboutPage,
24
- }}/>
25
- </Navigation>
26
- </HTML>
19
+ <HTML app="My App" root="https://example.com/" url={requestUrl} language="en">
20
+ <Navigation>
21
+ <Router
22
+ routes={{
23
+ "/": HomePage,
24
+ "/about": AboutPage,
25
+ }}
26
+ />
27
+ </Navigation>
28
+ </HTML>,
27
29
  );
28
30
  ```
29
31
 
package/ui/page/Head.md CHANGED
@@ -15,7 +15,6 @@ import { Page, Head } from "shelving/ui";
15
15
 
16
16
  // <Page> already renders <Head> for you; render it directly only for custom shells.
17
17
  <Page title="Settings">
18
- <Head/>
19
- …
20
- </Page>
18
+ <Head />…
19
+ </Page>;
21
20
  ```
package/ui/page/Page.md CHANGED
@@ -14,11 +14,11 @@ Wraps one page (or screen) inside an app, applying its per-page metadata. It mer
14
14
  import { Page, Section } from "shelving/ui";
15
15
 
16
16
  function UserPage({ id }: { id: string }) {
17
- return (
18
- <Page title="User profile" url={`/users/${id}`} description="View user details.">
19
- <Section>…</Section>
20
- </Page>
21
- );
17
+ return (
18
+ <Page title="User profile" url={`/users/${id}`} description="View user details.">
19
+ <Section>…</Section>
20
+ </Page>
21
+ );
22
22
  }
23
23
  ```
24
24
 
@@ -28,12 +28,12 @@ A page renders no layout. The layout goes outside the page, above the router, so
28
28
  import { Block, FixedLayout, Page, Scroll } from "shelving/ui";
29
29
 
30
30
  <FixedLayout>
31
- <Scroll vertical cover>
32
- <Page title="Sign in">
33
- <Block height="full" middle width="narrow">
34
- <LoginForm/>
35
- </Block>
36
- </Page>
37
- </Scroll>
38
- </FixedLayout>
31
+ <Scroll vertical cover>
32
+ <Page title="Sign in">
33
+ <Block height="full" middle width="narrow">
34
+ <LoginForm />
35
+ </Block>
36
+ </Page>
37
+ </Scroll>
38
+ </FixedLayout>;
39
39
  ```
@@ -18,28 +18,30 @@ The back button for a page header. It goes back to the page before this one in t
18
18
  import { BackButton } from "shelving/ui";
19
19
 
20
20
  function PostPage({ id }: { id: string }) {
21
- return (
22
- <>
23
- <header>
24
- <BackButton href="/home"/>
25
- <h1>Post</h1>
26
- </header>
27
- {/* … */}
28
- </>
29
- );
21
+ return (
22
+ <>
23
+ <header>
24
+ <BackButton href="/home" />
25
+ <h1>Post</h1>
26
+ </header>
27
+ {/* … */}
28
+ </>
29
+ );
30
30
  }
31
31
  ```
32
32
 
33
33
  With a label:
34
34
 
35
35
  ```tsx
36
- <BackButton href="/profile">Back to profile</BackButton>
36
+ <BackButton href="/profile">Back to profile</BackButton>;
37
37
  ```
38
38
 
39
39
  To go back to one fixed page (not to the page before), use a link with `className="back"`:
40
40
 
41
41
  ```tsx
42
- <Button href="/profile" className="back">Profile</Button>
42
+ <Button href="/profile" className="back">
43
+ Profile
44
+ </Button>;
43
45
  ```
44
46
 
45
47
  ## Styling
@@ -33,10 +33,10 @@ Stacks and slides use the browser [Navigation API](https://developer.mozilla.org
33
33
  import { App, Navigation, Router } from "shelving/ui";
34
34
 
35
35
  <App root="https://example.com/">
36
- <Navigation>
37
- <Router routes={ROUTES}/>
38
- </Navigation>
39
- </App>
36
+ <Navigation>
37
+ <Router routes={ROUTES} />
38
+ </Navigation>
39
+ </App>;
40
40
  ```
41
41
 
42
42
  ### App with a tab bar
@@ -48,27 +48,29 @@ import { App, AppLayout, HorizontalTransition, Navigation, PageLoader, RouteCach
48
48
 
49
49
  const STACKS = ["/home", "/discover", "/profile"] as const;
50
50
 
51
- const TABS = <>
52
- <StackButton stack="/home">Home</StackButton>
53
- <StackButton stack="/discover">Discover</StackButton>
54
- <StackButton stack="/profile">Profile</StackButton>
55
- </>;
51
+ const TABS = (
52
+ <>
53
+ <StackButton stack="/home">Home</StackButton>
54
+ <StackButton stack="/discover">Discover</StackButton>
55
+ <StackButton stack="/profile">Profile</StackButton>
56
+ </>
57
+ );
56
58
 
57
59
  <App root="https://example.com/">
58
- <Navigation stacks={STACKS}>
59
- <AppLayout nav={TABS}>
60
- <HorizontalTransition>
61
- <RouteCache>
62
- <Scroll vertical cover>
63
- <PageLoader>
64
- <Router routes={ROUTES}/>
65
- </PageLoader>
66
- </Scroll>
67
- </RouteCache>
68
- </HorizontalTransition>
69
- </AppLayout>
70
- </Navigation>
71
- </App>
60
+ <Navigation stacks={STACKS}>
61
+ <AppLayout nav={TABS}>
62
+ <HorizontalTransition>
63
+ <RouteCache>
64
+ <Scroll vertical cover>
65
+ <PageLoader>
66
+ <Router routes={ROUTES} />
67
+ </PageLoader>
68
+ </Scroll>
69
+ </RouteCache>
70
+ </HorizontalTransition>
71
+ </AppLayout>
72
+ </Navigation>
73
+ </App>;
72
74
  ```
73
75
 
74
76
  The tab bar is in the layout, outside the cache, so it stays still while pages slide. See "Composing an app" on `<App>` for the full nesting rules.
@@ -114,9 +116,9 @@ Read the store from anywhere in the tree with `requireNavigation()`:
114
116
  import { requireNavigation } from "shelving/ui";
115
117
 
116
118
  const nav = requireNavigation();
117
- nav.forward("/home/post/1"); // Open a page in the current stack.
118
- nav.back("/home"); // Go back to a page.
119
- nav.replace("/login"); // Change the URL of the current page.
119
+ nav.forward("/home/post/1"); // Open a page in the current stack.
120
+ nav.back("/home"); // Go back to a page.
121
+ nav.replace("/login"); // Change the URL of the current page.
120
122
  ```
121
123
 
122
124
  See `NavigationStore` for what each method does.
@@ -14,12 +14,12 @@ The store that holds the current URL, drives browser history, and keeps one stac
14
14
 
15
15
  ## Methods
16
16
 
17
- | Method | What it does | Slide |
18
- |---|---|---|
19
- | `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace. | Forward. Across stacks, by tab order. |
20
- | `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. | Back |
21
- | `replace(href, stack?)` | Changes the URL of the current page. The stack, the depth and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages. | None |
22
- | `history(stack?)` | Returns the pages in `stack`, root first. | — |
17
+ | Method | What it does | Slide |
18
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
19
+ | `forward(href, stack?)` | Opens `href` as a new page on top of the stack. If `href` is the top page of another stack, it switches to that stack (a tab switch). If `href` is the current URL, it is a replace. | Forward. Across stacks, by tab order. |
20
+ | `back(href, stack?)` | Goes back to `href`. If `href` is in the stack, the stack goes back to it, and the pages above it leave the stack. If `href` is the root of the stack, the stack goes to its root. Otherwise `href` takes the place of the top page of the stack. | Back |
21
+ | `replace(href, stack?)` | Changes the URL of the current page. The stack, the depth and the mounted page stay the same. No new history entry. With another `stack`, the page moves into that stack: at its root if `href` is the root, else on top of its pages. | None |
22
+ | `history(stack?)` | Returns the pages in `stack`, root first. | — |
23
23
 
24
24
  `stack` defaults to the current stack.
25
25
 
@@ -48,13 +48,13 @@ Why depth? A browser history entry cannot be changed or removed. So when you go
48
48
 
49
49
  For example, with tabs `/home` and `/profile`:
50
50
 
51
- | Step | New history entry | Home stack | Profile stack |
52
- |---|---|---|---|
53
- | Start at `/home` | `/home` (depth 0) | `/home` | — |
54
- | Open a post | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | — |
55
- | Tap the Profile tab | `/profile` (depth 0) | `/home`, `/home/post/1` | `/profile` |
56
- | Tap the Home tab | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | `/profile` |
57
- | Tap the back button | `/home` (depth 0) | `/home` | `/profile` |
51
+ | Step | New history entry | Home stack | Profile stack |
52
+ | ------------------- | ------------------------ | ----------------------- | ------------- |
53
+ | Start at `/home` | `/home` (depth 0) | `/home` | — |
54
+ | Open a post | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | — |
55
+ | Tap the Profile tab | `/profile` (depth 0) | `/home`, `/home/post/1` | `/profile` |
56
+ | Tap the Home tab | `/home/post/1` (depth 1) | `/home`, `/home/post/1` | `/profile` |
57
+ | Tap the back button | `/home` (depth 0) | `/home` | `/profile` |
58
58
 
59
59
  When the page you go back to is the entry just before the current one, `back()` goes back in the browser history and pushes nothing.
60
60
 
@@ -66,8 +66,8 @@ The browser back and forward buttons walk the history entries one at a time, as
66
66
  import { Button, requireNavigation } from "shelving/ui";
67
67
 
68
68
  function LogoutButton() {
69
- const nav = requireNavigation();
70
- return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
69
+ const nav = requireNavigation();
70
+ return <Button onClick={() => nav.replace("/login")}>Log out</Button>;
71
71
  }
72
72
  ```
73
73
 
@@ -78,9 +78,9 @@ import { useStore } from "shelving/react";
78
78
  import { requireNavigation } from "shelving/ui";
79
79
 
80
80
  function TabTitle() {
81
- const nav = requireNavigation();
82
- const stack = useStore(nav.stack).value;
83
- return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
81
+ const nav = requireNavigation();
82
+ const stack = useStore(nav.stack).value;
83
+ return <h1>{stack === "/profile" ? "Profile" : "Home"}</h1>;
84
84
  }
85
85
  ```
86
86
 
@@ -27,26 +27,26 @@ Layouts do not include a cache. The app composes it, so it can also choose the t
27
27
  import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
28
28
 
29
29
  <AppLayout nav={<StackBar />}>
30
- <HorizontalTransition>
31
- <RouteCache>
32
- <Scroll vertical cover>
33
- <PageLoader>
34
- <Router routes={ROUTES}/>
35
- </PageLoader>
36
- </Scroll>
37
- </RouteCache>
38
- </HorizontalTransition>
39
- </AppLayout>
30
+ <HorizontalTransition>
31
+ <RouteCache>
32
+ <Scroll vertical cover>
33
+ <PageLoader>
34
+ <Router routes={ROUTES} />
35
+ </PageLoader>
36
+ </Scroll>
37
+ </RouteCache>
38
+ </HorizontalTransition>
39
+ </AppLayout>;
40
40
  ```
41
41
 
42
42
  Keep fewer pages:
43
43
 
44
44
  ```tsx
45
45
  <RouteCache maxCached={5}>
46
- <Scroll vertical cover>
47
- <Router routes={ROUTES}/>
48
- </Scroll>
49
- </RouteCache>
46
+ <Scroll vertical cover>
47
+ <Router routes={ROUTES} />
48
+ </Scroll>
49
+ </RouteCache>;
50
50
  ```
51
51
 
52
52
  Clear a create form after it saves. Change the `key` of the `<Form>`, so it mounts again with no input:
@@ -56,19 +56,19 @@ import { useState } from "react";
56
56
  import { Form, requireNavigation } from "shelving/ui";
57
57
 
58
58
  function NewPostPage() {
59
- const nav = requireNavigation();
60
- const [formKey, setFormKey] = useState(0);
61
- return (
62
- <Form
63
- key={formKey}
64
- schema={POST_SCHEMA}
65
- onSubmit={async data => {
66
- const id = await createPost(data);
67
- setFormKey(k => k + 1);
68
- nav.forward(`/post/${id}`);
69
- }}
70
- />
71
- );
59
+ const nav = requireNavigation();
60
+ const [formKey, setFormKey] = useState(0);
61
+ return (
62
+ <Form
63
+ key={formKey}
64
+ schema={POST_SCHEMA}
65
+ onSubmit={async data => {
66
+ const id = await createPost(data);
67
+ setFormKey(k => k + 1);
68
+ nav.forward(`/post/${id}`);
69
+ }}
70
+ />
71
+ );
72
72
  }
73
73
  ```
74
74