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/Scroll.md CHANGED
@@ -24,8 +24,8 @@ A box that scrolls its content on one or both axes. Use it for a wide table on a
24
24
  import { Scroll, Table } from "shelving/ui";
25
25
 
26
26
  <Scroll horizontal>
27
- <Table>…</Table>
28
- </Scroll>
27
+ <Table>…</Table>
28
+ </Scroll>;
29
29
  ```
30
30
 
31
31
  ### A scroll box for each page
@@ -36,30 +36,30 @@ Put `<Scroll vertical cover>` inside `<RouteCache>`, so each kept page has its o
36
36
  import { AppLayout, HorizontalTransition, PageLoader, RouteCache, Router, Scroll } from "shelving/ui";
37
37
 
38
38
  <AppLayout nav={<StackBar />}>
39
- <HorizontalTransition>
40
- <RouteCache>
41
- <Scroll vertical cover>
42
- <PageLoader>
43
- <Router routes={ROUTES} />
44
- </PageLoader>
45
- </Scroll>
46
- </RouteCache>
47
- </HorizontalTransition>
48
- </AppLayout>
39
+ <HorizontalTransition>
40
+ <RouteCache>
41
+ <Scroll vertical cover>
42
+ <PageLoader>
43
+ <Router routes={ROUTES} />
44
+ </PageLoader>
45
+ </Scroll>
46
+ </RouteCache>
47
+ </HorizontalTransition>
48
+ </AppLayout>;
49
49
  ```
50
50
 
51
51
  ### A chat
52
52
 
53
53
  ```tsx
54
54
  <Scroll vertical cover reverse>
55
- <div>{messages}</div>
56
- </Scroll>
55
+ <div>{messages}</div>
56
+ </Scroll>;
57
57
  ```
58
58
 
59
59
  ## Styling
60
60
 
61
- | Variable | Styles | Default |
62
- |---|---|---|
61
+ | Variable | Styles | Default |
62
+ | ----------------------- | --------------------------------------- | ---------------------------------------------- |
63
63
  | `--scroll-focus-border` | Outline when the box has keyboard focus | `var(--stroke-focus) solid var(--color-focus)` |
64
64
 
65
65
  **Global tokens it reads** — `--stroke-focus`, `--stroke-normal`, and `--color-focus`.
@@ -23,13 +23,16 @@ A landmark content region — renders a `<section>` with block-level spacing and
23
23
  import { Section, Heading, Definitions } from "shelving/ui";
24
24
 
25
25
  <Section width="narrow">
26
- <Heading>Account details</Heading>
27
- <Definitions>
28
- <dt>Name</dt><dd>Alice Smith</dd>
29
- <dt>Email</dt><dd>alice@example.com</dd>
30
- <dt>Plan</dt><dd>Pro</dd>
31
- </Definitions>
32
- </Section>
26
+ <Heading>Account details</Heading>
27
+ <Definitions>
28
+ <dt>Name</dt>
29
+ <dd>Alice Smith</dd>
30
+ <dt>Email</dt>
31
+ <dd>alice@example.com</dd>
32
+ <dt>Plan</dt>
33
+ <dd>Pro</dd>
34
+ </Definitions>
35
+ </Section>;
33
36
  ```
34
37
 
35
38
  ### Landmark elements
@@ -46,9 +49,9 @@ import { Header, Nav, Footer } from "shelving/ui";
46
49
 
47
50
  `Section` exposes hooks for its width and rhythm; it paints no colour of its own, so it inherits the surrounding tint.
48
51
 
49
- | Variable | Styles | Default |
50
- |---|---|---|
51
- | `--section-width` | Content width | `var(--width-normal)` (55rem) |
52
+ | Variable | Styles | Default |
53
+ | ----------------- | --------------------------------- | ----------------------------- |
54
+ | `--section-width` | Content width | `var(--width-normal)` (55rem) |
52
55
  | `--section-space` | Outer block margin (top + bottom) | `var(--space-section)` (2rem) |
53
56
 
54
57
  **Global tokens it reads:** `--space-section` and `--width-normal` (the default content width). The `width` variant (`narrow` / `normal` / `wide` / `full` / `fit`) and the `indent` variant (inline padding, via `getIndentClass()`) come from the shared `shelving/ui` styling system.
@@ -30,24 +30,24 @@ A full-viewport layout with a fixed-width side column next to a content slot. Th
30
30
  import { Menu, MenuItem, PageLoader, RouteCache, Router, Scroll, SidebarLayout } from "shelving/ui";
31
31
 
32
32
  function AppShell() {
33
- const nav = (
34
- <Menu>
35
- <MenuItem href="/dashboard">Dashboard</MenuItem>
36
- <MenuItem href="/users">Users</MenuItem>
37
- <MenuItem href="/settings">Settings</MenuItem>
38
- </Menu>
39
- );
40
- return (
41
- <SidebarLayout sidebar={nav}>
42
- <RouteCache>
43
- <Scroll vertical cover>
44
- <PageLoader>
45
- <Router routes={ROUTES}/>
46
- </PageLoader>
47
- </Scroll>
48
- </RouteCache>
49
- </SidebarLayout>
50
- );
33
+ const nav = (
34
+ <Menu>
35
+ <MenuItem href="/dashboard">Dashboard</MenuItem>
36
+ <MenuItem href="/users">Users</MenuItem>
37
+ <MenuItem href="/settings">Settings</MenuItem>
38
+ </Menu>
39
+ );
40
+ return (
41
+ <SidebarLayout sidebar={nav}>
42
+ <RouteCache>
43
+ <Scroll vertical cover>
44
+ <PageLoader>
45
+ <Router routes={ROUTES} />
46
+ </PageLoader>
47
+ </Scroll>
48
+ </RouteCache>
49
+ </SidebarLayout>
50
+ );
51
51
  }
52
52
  ```
53
53
 
@@ -55,15 +55,15 @@ To slide pages, put a transition around the `<RouteCache>`, inside the layout. T
55
55
 
56
56
  ## Styling
57
57
 
58
- | Variable | Styles | Default |
59
- |---|---|---|
60
- | `--sidebar-layout-width` | Width of the side column (and drawer) | `17.5rem` |
61
- | `--sidebar-layout-background` | Page background while the layout is mounted (also fills the content column) | `var(--tint-100)` (white) |
62
- | `--sidebar-layout-color` | Text colour for the layout (set on `body`, inherited by the content column) | `var(--tint-00)` (black) |
63
- | `--sidebar-layout-sidebar-background` | Sidebar column fill | `var(--tint-90)` (one shade darker than the page) |
64
- | `--sidebar-layout-sidebar-color` | Sidebar column text colour | `var(--tint-00)` (black) |
65
- | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
66
- | `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
58
+ | Variable | Styles | Default |
59
+ | ------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------- |
60
+ | `--sidebar-layout-width` | Width of the side column (and drawer) | `17.5rem` |
61
+ | `--sidebar-layout-background` | Page background while the layout is mounted (also fills the content column) | `var(--tint-100)` (white) |
62
+ | `--sidebar-layout-color` | Text colour for the layout (set on `body`, inherited by the content column) | `var(--tint-00)` (black) |
63
+ | `--sidebar-layout-sidebar-background` | Sidebar column fill | `var(--tint-90)` (one shade darker than the page) |
64
+ | `--sidebar-layout-sidebar-color` | Sidebar column text colour | `var(--tint-00)` (black) |
65
+ | `--sidebar-layout-border` | Divider between sidebar and content, e.g. `1px solid var(--tint-90)` | `none` |
66
+ | `--sidebar-layout-shadow` | Drop shadow of the open drawer on a narrow screen | `var(--shadow-large)` |
67
67
 
68
68
  The sidebar scrolls on its own. The content slot does not scroll: its `<Scroll vertical cover>` box does.
69
69
 
package/docs/ui/Small.md CHANGED
@@ -20,16 +20,16 @@ Small print — renders a `<small>` element for side comments and fine print suc
20
20
  import { Paragraph, Small } from "shelving/ui";
21
21
 
22
22
  <Paragraph>
23
- Upgrade any time. <Small>Terms apply.</Small>
24
- </Paragraph>
23
+ Upgrade any time. <Small>Terms apply.</Small>
24
+ </Paragraph>;
25
25
  ```
26
26
 
27
27
  ## Styling
28
28
 
29
29
  `Small` mutes its text colour to a lighter tint step and inherits size and weight from its surroundings.
30
30
 
31
- | Variable | Styles | Default |
32
- |---|---|---|
31
+ | Variable | Styles | Default |
32
+ | --------------- | ----------- | ---------------- |
33
33
  | `--small-color` | Text colour | `var(--tint-70)` |
34
34
 
35
35
  **Global tokens it reads:** the tint-ladder step `--tint-70`.
package/docs/ui/Span.md CHANGED
@@ -31,7 +31,9 @@ import { Span } from "shelving/ui";
31
31
  ```tsx live
32
32
  import { Span } from "shelving/ui";
33
33
 
34
- <Span color="purple" tint="40">on-brand accent</Span>
34
+ <Span color="purple" tint="40">
35
+ on-brand accent
36
+ </Span>;
35
37
  ```
36
38
 
37
39
  ## Styling
@@ -30,13 +30,19 @@ import { Navigation, StackButton } from "shelving/ui";
30
30
  import { HomeIcon, SearchIcon, UserIcon } from "./icons.js";
31
31
 
32
32
  <Navigation stacks={["/home", "/discover", "/profile"]}>
33
- {/* … */}
34
- <nav className="tab-bar">
35
- <StackButton stack="/home" title="Home"><HomeIcon/></StackButton>
36
- <StackButton stack="/discover" title="Discover"><SearchIcon/></StackButton>
37
- <StackButton stack="/profile" title="Profile"><UserIcon/></StackButton>
38
- </nav>
39
- </Navigation>
33
+ {/* … */}
34
+ <nav className="tab-bar">
35
+ <StackButton stack="/home" title="Home">
36
+ <HomeIcon />
37
+ </StackButton>
38
+ <StackButton stack="/discover" title="Discover">
39
+ <SearchIcon />
40
+ </StackButton>
41
+ <StackButton stack="/profile" title="Profile">
42
+ <UserIcon />
43
+ </StackButton>
44
+ </nav>
45
+ </Navigation>;
40
46
  ```
41
47
 
42
48
  ## Styling
package/docs/ui/Strong.md CHANGED
@@ -21,16 +21,16 @@ Strong importance — renders a `<strong>` element for text that carries strong
21
21
  import { Paragraph, Strong } from "shelving/ui";
22
22
 
23
23
  <Paragraph>
24
- Press save before leaving. <Strong>Unsaved changes will be lost.</Strong>
25
- </Paragraph>
24
+ Press save before leaving. <Strong>Unsaved changes will be lost.</Strong>
25
+ </Paragraph>;
26
26
  ```
27
27
 
28
28
  ## Styling
29
29
 
30
30
  `Strong` only sets its font weight and inherits colour and size from its surroundings.
31
31
 
32
- | Variable | Styles | Default |
33
- |---|---|---|
32
+ | Variable | Styles | Default |
33
+ | ----------------- | ----------- | ---------------------- |
34
34
  | `--strong-weight` | Font weight | `var(--weight-strong)` |
35
35
 
36
36
  **Global tokens it reads:** `--weight-strong`.
@@ -24,9 +24,9 @@ A subsection heading — renders an `<h3>`. It is the smallest member of the thr
24
24
  import { Card, Subheading, Paragraph } from "shelving/ui";
25
25
 
26
26
  <Card>
27
- <Subheading>Storage</Subheading>
28
- <Paragraph>1.2 GB of 5 GB used.</Paragraph>
29
- </Card>
27
+ <Subheading>Storage</Subheading>
28
+ <Paragraph>1.2 GB of 5 GB used.</Paragraph>
29
+ </Card>;
30
30
  ```
31
31
 
32
32
  ### The heading family together
@@ -43,15 +43,15 @@ import { Title, Heading, Subheading } from "shelving/ui";
43
43
 
44
44
  `Subheading` exposes hooks for its rhythm and type. It inherits text colour by default; set `--subheading-color` only to override that.
45
45
 
46
- | Variable | Styles | Default |
47
- |---|---|---|
48
- | `--subheading-color` | Text colour | `inherit` |
49
- | `--subheading-space-before` | Top margin | `var(--space-section)` (2rem) |
50
- | `--subheading-space` | Bottom margin | `var(--space-paragraph)` (16px) |
51
- | `--subheading-font` | Font family | `var(--font-title)` |
52
- | `--subheading-weight` | Font weight | `var(--weight-strong)` (700) |
53
- | `--subheading-size` | Font size | `var(--size-large)` |
54
- | `--subheading-leading` | Line height | `var(--leading)` |
46
+ | Variable | Styles | Default |
47
+ | --------------------------- | ------------- | ------------------------------- |
48
+ | `--subheading-color` | Text colour | `inherit` |
49
+ | `--subheading-space-before` | Top margin | `var(--space-section)` (2rem) |
50
+ | `--subheading-space` | Bottom margin | `var(--space-paragraph)` (16px) |
51
+ | `--subheading-font` | Font family | `var(--font-title)` |
52
+ | `--subheading-weight` | Font weight | `var(--weight-strong)` (700) |
53
+ | `--subheading-size` | Font size | `var(--size-large)` |
54
+ | `--subheading-leading` | Line height | `var(--leading)` |
55
55
 
56
56
  **Global tokens it reads:** `--space-section`, `--space-paragraph`, `--font-title`, `--weight-strong`, `--size-large`, and `--leading`.
57
57
 
@@ -16,7 +16,7 @@ The anchor defaults to `--color-gray`, so the default ladder is a neutral grey r
16
16
 
17
17
  ## The recompute trick
18
18
 
19
- The ladder is computed at `:root` and *recomputed* under `TINT_CLASS` (the `.tint` class). That recomputation is the whole trick: move the anchor at any scope, apply `TINT_CLASS`, and all 21 shades (and `--tint-contrast`) rebuild from the new hue at that scope. Colour and status classes are exactly that — they only move the anchor:
19
+ The ladder is computed at `:root` and _recomputed_ under `TINT_CLASS` (the `.tint` class). That recomputation is the whole trick: move the anchor at any scope, apply `TINT_CLASS`, and all 21 shades (and `--tint-contrast`) rebuild from the new hue at that scope. Colour and status classes are exactly that — they only move the anchor:
20
20
 
21
21
  ```css
22
22
  /* Color.module.css — a colour variant just moves the anchor. */
@@ -36,15 +36,15 @@ The ladder is computed at `:root` and *recomputed* under `TINT_CLASS` (the `.tin
36
36
 
37
37
  Components paint from the ladder by convention:
38
38
 
39
- | Step | Used for |
40
- |---|---|
41
- | `--tint-00` | Body text, headings — maximum contrast |
42
- | `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `<Button>` backgrounds |
43
- | `--tint-80` | Borders of boxes and controls — `<Card>`, `<Input>`, `<Notice>` |
44
- | `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds; light rules — `<Divider>`, `<Table>` rows, `<Blockquote>` |
45
- | `--tint-95` | Hover state of those surfaces |
46
- | `--tint-100` | The page background; text on `--tint-50` backgrounds |
47
- | `--tint-contrast` | Text on `--tint-50` backgrounds when the anchor can be light or dark |
39
+ | Step | Used for |
40
+ | ----------------- | ---------------------------------------------------------------------------------------------------------- |
41
+ | `--tint-00` | Body text, headings — maximum contrast |
42
+ | `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `<Button>` backgrounds |
43
+ | `--tint-80` | Borders of boxes and controls — `<Card>`, `<Input>`, `<Notice>` |
44
+ | `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds; light rules — `<Divider>`, `<Table>` rows, `<Blockquote>` |
45
+ | `--tint-95` | Hover state of those surfaces |
46
+ | `--tint-100` | The page background; text on `--tint-50` backgrounds |
47
+ | `--tint-contrast` | Text on `--tint-50` backgrounds when the anchor can be light or dark |
48
48
 
49
49
  Pairings follow contrast: long text reads at `00`-on-`90` or `00`-on-`100`; short labels read at `100`-on-`50`, or at `contrast`-on-`50` when the anchor can be light.
50
50
 
@@ -73,5 +73,5 @@ A theme is a CSS file of custom-property overrides at `:root`, imported after th
73
73
 
74
74
  `TINT_CLASS` adds a plain global `tint` class (as well as its hashed module class) for this purpose, so `tint` is a reserved class name. Do not use `* { … }` for this: it declares the variable on every element, which adds style-recalc cost on large pages.
75
75
 
76
- **Don't override individual ladder steps (`--tint-90`, etc.) at `:root`.** The ladder is *recomputed* from the anchor inside every `TINT_CLASS` scope — which includes every component that accepts `color=` or `status=` — so a step override at `:root` only reaches untinted regions and produces inconsistent surfaces. Move the anchor (option 1 or 2) instead, and the steps follow.
76
+ **Don't override individual ladder steps (`--tint-90`, etc.) at `:root`.** The ladder is _recomputed_ from the anchor inside every `TINT_CLASS` scope — which includes every component that accepts `color=` or `status=` — so a step override at `:root` only reaches untinted regions and produces inconsistent surfaces. Move the anchor (option 1 or 2) instead, and the steps follow.
77
77
 
package/docs/ui/Table.md CHANGED
@@ -30,14 +30,23 @@ A data table — renders a `<table>`. Compose the usual `<thead>` / `<tbody>` /
30
30
  import { Table } from "shelving/ui";
31
31
 
32
32
  <Table>
33
- <thead>
34
- <tr><th>Name</th><th>Plan</th></tr>
35
- </thead>
36
- <tbody>
37
- <tr><td>Alice</td><td>Pro</td></tr>
38
- <tr><td>Bob</td><td>Free</td></tr>
39
- </tbody>
40
- </Table>
33
+ <thead>
34
+ <tr>
35
+ <th>Name</th>
36
+ <th>Plan</th>
37
+ </tr>
38
+ </thead>
39
+ <tbody>
40
+ <tr>
41
+ <td>Alice</td>
42
+ <td>Pro</td>
43
+ </tr>
44
+ <tr>
45
+ <td>Bob</td>
46
+ <td>Free</td>
47
+ </tr>
48
+ </tbody>
49
+ </Table>;
41
50
  ```
42
51
 
43
52
  ### Cell padding
@@ -46,13 +55,15 @@ import { Table } from "shelving/ui";
46
55
  import { Button, Cell, Table } from "shelving/ui";
47
56
 
48
57
  <Table padding="small">
49
- <tbody>
50
- <tr>
51
- <Cell width="full">Alice</Cell>
52
- <Cell width="fit" padding="none"><Button small>Remove</Button></Cell>
53
- </tr>
54
- </tbody>
55
- </Table>
58
+ <tbody>
59
+ <tr>
60
+ <Cell width="full">Alice</Cell>
61
+ <Cell width="fit" padding="none">
62
+ <Button small>Remove</Button>
63
+ </Cell>
64
+ </tr>
65
+ </tbody>
66
+ </Table>;
56
67
  ```
57
68
 
58
69
  ## Styling
@@ -61,19 +72,19 @@ import { Button, Cell, Table } from "shelving/ui";
61
72
 
62
73
  `--table-padding` sets the top and bottom padding of each cell, and `--table-indent` the left and right. Each takes one length. The table's `padding` and `indent` variants set these hooks. The outermost columns still drop their outer inline padding, and `<thead>` / `<tfoot>` their outer block padding, so the table stays flush with its container.
63
74
 
64
- | Variable | Styles | Default |
65
- |---|---|---|
66
- | `--table-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
67
- | `--table-padding` | Cell top and bottom padding (one length) | `var(--space-xsmall)` (8px) |
68
- | `--table-indent` | Cell left and right padding (one length) | `var(--space-xsmall)` (8px) |
69
- | `--table-border` | Cell border shorthand | `var(--table-stroke)` |
70
- | `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-90)` |
71
- | `--table-header-weight` | Weight of `<thead>` / `<tfoot>` / `<tbody> <th>` cells | `var(--weight-strong)` |
72
- | `--table-label-font` | Label font for `<thead>` / `<tfoot>` `<th>` | `var(--font-label)` |
73
- | `--table-label-weight` | Label weight | `var(--weight-label)` |
74
- | `--table-label-size` | Label size | `var(--size-label)` |
75
- | `--table-label-case` | Label letter case | `var(--case-label)` |
76
- | `--table-label-color` | Label colour | `var(--tint-70)` |
75
+ | Variable | Styles | Default |
76
+ | ----------------------- | ------------------------------------------------------ | ------------------------------------------- |
77
+ | `--table-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
78
+ | `--table-padding` | Cell top and bottom padding (one length) | `var(--space-xsmall)` (8px) |
79
+ | `--table-indent` | Cell left and right padding (one length) | `var(--space-xsmall)` (8px) |
80
+ | `--table-border` | Cell border shorthand | `var(--table-stroke)` |
81
+ | `--table-stroke` | Cell border thickness/colour | `var(--stroke-normal) solid var(--tint-90)` |
82
+ | `--table-header-weight` | Weight of `<thead>` / `<tfoot>` / `<tbody> <th>` cells | `var(--weight-strong)` |
83
+ | `--table-label-font` | Label font for `<thead>` / `<tfoot>` `<th>` | `var(--font-label)` |
84
+ | `--table-label-weight` | Label weight | `var(--weight-label)` |
85
+ | `--table-label-size` | Label size | `var(--size-label)` |
86
+ | `--table-label-case` | Label letter case | `var(--case-label)` |
87
+ | `--table-label-color` | Label colour | `var(--tint-70)` |
77
88
 
78
89
  **Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, `--stroke-normal`, the tint-ladder steps `--tint-70` / `--tint-90`, and the label tokens `--font-label` / `--weight-label` / `--size-label` / `--case-label` / `--weight-strong`.
79
90
 
@@ -103,7 +114,6 @@ The following table will be defined with two fixed width cells and a longer cell
103
114
 
104
115
  The following table does the same but with a minimum width on the description column:
105
116
 
106
-
107
117
  ```TableWidths.tsx
108
118
  <Table>
109
119
  <tr>
@@ -114,6 +124,7 @@ The following table does the same but with a minimum width on the description co
114
124
  </Table>
115
125
  ```
116
126
 
127
+
117
128
  ## Signatures
118
129
 
119
130
  ```ts
package/docs/ui/Tag.md CHANGED
@@ -29,21 +29,21 @@ import { Tag } from "shelving/ui";
29
29
 
30
30
  `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.
31
31
 
32
- | Variable | Styles | Default |
33
- |---|---|---|
34
- | `--tag-background` | Surface fill | `var(--tint-50)` |
35
- | `--tag-hover-background` | Surface fill when an interactive tag is hovered | `var(--tint-55)` |
36
- | `--tag-color` | Text colour | `var(--tint-100)` |
37
- | `--tag-padding` | Inner top and bottom padding (one length) | `0` |
38
- | `--tag-indent` | Inner left and right padding (one length) | `var(--space-xxsmall)` (4px) |
39
- | `--tag-border` | Border shorthand | `0` |
40
- | `--tag-radius` | Corner radius | `var(--radius-xxsmall)` |
41
- | `--tag-font` | Font family | `var(--font-body)` |
42
- | `--tag-size` | Font size | `var(--size-small)` |
43
- | `--tag-weight` | Font weight | `var(--weight-strong)` |
44
- | `--tag-leading` | Line height | `var(--leading)` |
45
- | `--tag-case` | Text transform | `var(--case-label)` |
46
- | `--tag-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
32
+ | Variable | Styles | Default |
33
+ | ------------------------ | ----------------------------------------------- | ---------------------------------------------- |
34
+ | `--tag-background` | Surface fill | `var(--tint-50)` |
35
+ | `--tag-hover-background` | Surface fill when an interactive tag is hovered | `var(--tint-55)` |
36
+ | `--tag-color` | Text colour | `var(--tint-100)` |
37
+ | `--tag-padding` | Inner top and bottom padding (one length) | `0` |
38
+ | `--tag-indent` | Inner left and right padding (one length) | `var(--space-xxsmall)` (4px) |
39
+ | `--tag-border` | Border shorthand | `0` |
40
+ | `--tag-radius` | Corner radius | `var(--radius-xxsmall)` |
41
+ | `--tag-font` | Font family | `var(--font-body)` |
42
+ | `--tag-size` | Font size | `var(--size-small)` |
43
+ | `--tag-weight` | Font weight | `var(--weight-strong)` |
44
+ | `--tag-leading` | Line height | `var(--leading)` |
45
+ | `--tag-case` | Text transform | `var(--case-label)` |
46
+ | `--tag-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
47
47
 
48
48
  **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`.
49
49
 
package/docs/ui/Title.md CHANGED
@@ -32,25 +32,25 @@ import { Title, Paragraph } from "shelving/ui";
32
32
  import { Panel, Block, Title } from "shelving/ui";
33
33
 
34
34
  <Panel as="header" color="primary">
35
- <Block width="narrow">
36
- <Title>Welcome</Title>
37
- </Block>
38
- </Panel>
35
+ <Block width="narrow">
36
+ <Title>Welcome</Title>
37
+ </Block>
38
+ </Panel>;
39
39
  ```
40
40
 
41
41
  ## Styling
42
42
 
43
43
  `Title` exposes hooks for its rhythm and type. It inherits text colour by default; set `--title-color` only to override that.
44
44
 
45
- | Variable | Styles | Default |
46
- |---|---|---|
47
- | `--title-color` | Text colour | `inherit` |
48
- | `--title-space-before` | Top margin | `var(--space-section)` (2rem) |
49
- | `--title-space` | Bottom margin | `var(--space-paragraph)` (16px) |
50
- | `--title-font` | Font family | `var(--font-title)` |
51
- | `--title-weight` | Font weight | `var(--weight-strong)` (700) |
52
- | `--title-size` | Font size | `var(--size-xxxlarge)` |
53
- | `--title-leading` | Line height | `var(--leading)` |
45
+ | Variable | Styles | Default |
46
+ | ---------------------- | ------------- | ------------------------------- |
47
+ | `--title-color` | Text colour | `inherit` |
48
+ | `--title-space-before` | Top margin | `var(--space-section)` (2rem) |
49
+ | `--title-space` | Bottom margin | `var(--space-paragraph)` (16px) |
50
+ | `--title-font` | Font family | `var(--font-title)` |
51
+ | `--title-weight` | Font weight | `var(--weight-strong)` (700) |
52
+ | `--title-size` | Font size | `var(--size-xxxlarge)` |
53
+ | `--title-leading` | Line height | `var(--leading)` |
54
54
 
55
55
  **Global tokens it reads:** `--space-section`, `--space-paragraph`, `--font-title`, `--weight-strong`, `--size-xxxlarge`, and `--leading`.
56
56
 
@@ -27,8 +27,8 @@ The base View Transition wrapper. It wraps its children in React 19's `<ViewTran
27
27
  import { Transition } from "shelving/ui";
28
28
 
29
29
  <Transition default="zoom" forward="zoomIn" back="zoomOut">
30
- {children}
31
- </Transition>
30
+ {children}
31
+ </Transition>;
32
32
  ```
33
33
 
34
34
  ### Overlay
@@ -37,8 +37,8 @@ import { Transition } from "shelving/ui";
37
37
  import { FadeTransition } from "shelving/ui";
38
38
 
39
39
  <FadeTransition overlay>
40
- <Notification/>
41
- </FadeTransition>
40
+ <Notification />
41
+ </FadeTransition>;
42
42
  ```
43
43
 
44
44
  ### Page transitions
@@ -50,10 +50,10 @@ import { HorizontalTransition, Navigation, Router } from "shelving/ui";
50
50
 
51
51
  // Slides right on forward, left on back:
52
52
  <Navigation>
53
- <HorizontalTransition>
54
- <Router routes={ROUTES}/>
55
- </HorizontalTransition>
56
- </Navigation>
53
+ <HorizontalTransition>
54
+ <Router routes={ROUTES} />
55
+ </HorizontalTransition>
56
+ </Navigation>;
57
57
  ```
58
58
 
59
59
  ### Setting the direction with `setTransitionType()`
@@ -63,17 +63,17 @@ import { HorizontalTransition, setTransitionType } from "shelving/ui";
63
63
  import { startTransition, useState } from "react";
64
64
 
65
65
  function Steps() {
66
- const [step, setStep] = useState(0);
67
- const go = (direction: "forward" | "back") =>
68
- startTransition(() => {
69
- setTransitionType(direction);
70
- setStep(s => s + (direction === "forward" ? 1 : -1));
71
- });
72
- return (
73
- <HorizontalTransition>
74
- <Step key={step} step={step} onNext={() => go("forward")} onBack={() => go("back")}/>
75
- </HorizontalTransition>
76
- );
66
+ const [step, setStep] = useState(0);
67
+ const go = (direction: "forward" | "back") =>
68
+ startTransition(() => {
69
+ setTransitionType(direction);
70
+ setStep(s => s + (direction === "forward" ? 1 : -1));
71
+ });
72
+ return (
73
+ <HorizontalTransition>
74
+ <Step key={step} step={step} onNext={() => go("forward")} onBack={() => go("back")} />
75
+ </HorizontalTransition>
76
+ );
77
77
  }
78
78
  ```
79
79
 
@@ -81,9 +81,9 @@ function Steps() {
81
81
 
82
82
  Transitions are driven by CSS `::view-transition-*` pseudo-element rules keyed on the transition class names, not by per-component `--variable` hooks. `<Transition>` itself only ships the `overlay` rule:
83
83
 
84
- | Variable | Styles | Default |
85
- |---|---|---|
86
- | _(none)_ | `<Transition>` exposes no own custom properties | — |
84
+ | Variable | Styles | Default |
85
+ | -------- | ----------------------------------------------- | ------- |
86
+ | _(none)_ | `<Transition>` exposes no own custom properties | — |
87
87
 
88
88
  The `overlay` variant sets `z-index: 100` on `::view-transition-group(.overlay)`. The preset variants document their own timing/distance hooks (`--fade-transition-duration`, `--vertical-transition-size` / `-duration`, `--horizontal-transition-size` / `-duration`) on their pages.
89
89