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/Button.md CHANGED
@@ -47,7 +47,9 @@ import { Button } from "shelving/ui";
47
47
  import { Button } from "shelving/ui";
48
48
 
49
49
  // No outer margin: it sits flush with the content around it.
50
- <Button full space="none" onClick={start}>Start</Button>
50
+ <Button full space="none" onClick={start}>
51
+ Start
52
+ </Button>;
51
53
  ```
52
54
 
53
55
  ### A row of buttons
@@ -57,9 +59,13 @@ import { Button } from "shelving/ui";
57
59
  import { Row } from "shelving/ui";
58
60
 
59
61
  <Row gap="small" right>
60
- <Button plain onClick={cancel}>Cancel</Button>
61
- <Button solid color="primary" onClick={submit}>Continue</Button>
62
- </Row>
62
+ <Button plain onClick={cancel}>
63
+ Cancel
64
+ </Button>
65
+ <Button solid color="primary" onClick={submit}>
66
+ Continue
67
+ </Button>
68
+ </Row>;
63
69
  ```
64
70
 
65
71
  ### Tabs
@@ -68,12 +74,12 @@ import { Row } from "shelving/ui";
68
74
  import { Button, Row } from "shelving/ui";
69
75
 
70
76
  <Row gap="xsmall">
71
- {SECTIONS.map(({ key, label }) => (
72
- <Button key={key} small solid selected={key === section} onClick={() => setSection(key)}>
73
- {label}
74
- </Button>
75
- ))}
76
- </Row>
77
+ {SECTIONS.map(({ key, label }) => (
78
+ <Button key={key} small solid selected={key === section} onClick={() => setSection(key)}>
79
+ {label}
80
+ </Button>
81
+ ))}
82
+ </Row>;
77
83
  ```
78
84
 
79
85
  ### A one-off treatment
@@ -82,7 +88,9 @@ import { Button, Row } from "shelving/ui";
82
88
  import { Button } from "shelving/ui";
83
89
 
84
90
  // `.spongy-press` lives in the app's own stylesheet — use it for what the theme hooks below can't express.
85
- <Button className="spongy-press" onClick={claim}>Claim</Button>
91
+ <Button className="spongy-press" onClick={claim}>
92
+ Claim
93
+ </Button>;
86
94
  ```
87
95
 
88
96
  ### Reusing the button class
@@ -92,8 +100,9 @@ import { getButtonClass } from "shelving/ui";
92
100
 
93
101
  // Style an arbitrary element as a button.
94
102
  <label className={getButtonClass({ color: "primary", solid: true, small: true })}>
95
- Upload<input type="file" hidden />
96
- </label>
103
+ Upload
104
+ <input type="file" hidden />
105
+ </label>;
97
106
  ```
98
107
 
99
108
  ## Styling
@@ -112,75 +121,75 @@ The `--button-*` colour hooks without a look in their name paint the default loo
112
121
 
113
122
  Backgrounds paint to the button's true edge: `background-origin` is set to `border-box`, so a gradient or image background in any state reaches through the transparent border instead of stopping 2px short at the padding box.
114
123
 
115
- | Variable | Styles | Default |
116
- |---|---|---|
117
- | `--button-background` | Surface fill | `var(--tint-90)` |
118
- | `--button-hover-background` | Surface fill on hover / focus | `var(--tint-85)` |
119
- | `--button-hover-border` | Border on hover / focus | `var(--button-stroke) solid transparent` |
120
- | `--button-hover-transform` | Transform on hover / focus | `none` |
121
- | `--button-text` | Label colour | `var(--tint-50)` |
122
- | `--button-border` | Border shorthand | `var(--button-stroke) solid transparent` |
123
- | `--button-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
124
- | `--button-radius` | Corner radius | `var(--radius-xsmall)` (8px) |
125
- | `--button-padding` | Top and bottom padding (one length) | `var(--space-small)` (12px) |
126
- | `--button-indent` | Left and right padding (one length) | `var(--space-small)` (12px) |
127
- | `--button-small-padding` | Top and bottom padding when `small` (one length) | `var(--space-xxsmall)` (4px) |
128
- | `--button-small-indent` | Left and right padding when `small` (one length) | `var(--space-xxsmall)` (4px) |
129
- | `--button-icon-size` | Icon size, and the base of the minimum height | `var(--size-icon)` (24px) |
130
- | `--button-height` | Minimum height | `--button-icon-size` + 2 × `--button-padding` + 2 × `--button-stroke` (52px) |
131
- | `--button-small-height` | Minimum height when `small` | `--button-icon-size` + 2 × `--button-small-padding` + 2 × `--button-stroke` (36px) |
132
- | `--button-gap` | Gap between icon and label | `var(--space-small)` (12px) |
133
- | `--button-small-gap` | Gap between icon and label when `small` | `var(--space-xxsmall)` (4px) |
134
- | `--button-space` | Outer block margin | `var(--space-small)` (12px) |
135
- | `--button-font` | Font family | `var(--font-body)` |
136
- | `--button-weight` | Font weight | `var(--weight-normal)` (400) |
137
- | `--button-size` | Font size | `var(--size-normal)` |
138
- | `--button-leading` | Line height | `var(--leading)` |
139
- | `--button-shadow` | Box shadow (never on `plain`) | `none` |
140
- | `--button-active-background` | Surface fill while pressed | `var(--button-hover-background)` |
141
- | `--button-active-border` | Border while pressed | `var(--button-hover-border)` |
142
- | `--button-active-shadow` | Box shadow while pressed | `var(--button-shadow)` |
143
- | `--button-active-transform` | Transform while pressed | `var(--button-hover-transform)` |
144
- | `--button-transition` | Transition | `all var(--duration-fast)` (150ms) |
145
- | `--button-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
146
- | `--button-disabled-opacity` | Opacity when disabled | `0.5` |
147
- | `--button-solid-background` | Surface fill when `solid` | `var(--tint-50)` |
148
- | `--button-solid-text` | Label colour when `solid` | `var(--tint-100)` (white) |
149
- | `--button-solid-hover-background` | Surface fill on hover / focus when `solid` | `var(--tint-55)` |
150
- | `--button-solid-active-background` | Surface fill while pressed when `solid` | `var(--button-solid-hover-background)` |
151
- | `--button-plain-text` | Label colour when `plain` or `outline` | `var(--tint-50)` |
152
- | `--button-plain-border` | Resting border when `plain` | `var(--button-stroke) solid transparent` |
153
- | `--button-outline-border` | Resting border when `outline` | `var(--button-stroke) solid var(--tint-80)` |
154
- | `--button-unselected-background` | Resting fill when `selected={false}` | `transparent` |
155
- | `--button-plain-hover-background` | Fill on hover / focus when `plain` or `outline` | `var(--button-hover-background)` |
156
- | `--button-plain-hover-border` | Border on hover / focus when `plain` or `outline` | `var(--button-hover-border)` (transparent) |
157
- | `--button-plain-active-background` | Fill while pressed when `plain` or `outline` | `var(--button-plain-hover-background)` |
158
- | `--button-plain-active-border` | Border while pressed when `plain` or `outline` | `var(--button-plain-hover-border)` |
124
+ | Variable | Styles | Default |
125
+ | ---------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
126
+ | `--button-background` | Surface fill | `var(--tint-90)` |
127
+ | `--button-hover-background` | Surface fill on hover / focus | `var(--tint-85)` |
128
+ | `--button-hover-border` | Border on hover / focus | `var(--button-stroke) solid transparent` |
129
+ | `--button-hover-transform` | Transform on hover / focus | `none` |
130
+ | `--button-text` | Label colour | `var(--tint-50)` |
131
+ | `--button-border` | Border shorthand | `var(--button-stroke) solid transparent` |
132
+ | `--button-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
133
+ | `--button-radius` | Corner radius | `var(--radius-xsmall)` (8px) |
134
+ | `--button-padding` | Top and bottom padding (one length) | `var(--space-small)` (12px) |
135
+ | `--button-indent` | Left and right padding (one length) | `var(--space-small)` (12px) |
136
+ | `--button-small-padding` | Top and bottom padding when `small` (one length) | `var(--space-xxsmall)` (4px) |
137
+ | `--button-small-indent` | Left and right padding when `small` (one length) | `var(--space-xxsmall)` (4px) |
138
+ | `--button-icon-size` | Icon size, and the base of the minimum height | `var(--size-icon)` (24px) |
139
+ | `--button-height` | Minimum height | `--button-icon-size` + 2 × `--button-padding` + 2 × `--button-stroke` (52px) |
140
+ | `--button-small-height` | Minimum height when `small` | `--button-icon-size` + 2 × `--button-small-padding` + 2 × `--button-stroke` (36px) |
141
+ | `--button-gap` | Gap between icon and label | `var(--space-small)` (12px) |
142
+ | `--button-small-gap` | Gap between icon and label when `small` | `var(--space-xxsmall)` (4px) |
143
+ | `--button-space` | Outer block margin | `var(--space-small)` (12px) |
144
+ | `--button-font` | Font family | `var(--font-body)` |
145
+ | `--button-weight` | Font weight | `var(--weight-normal)` (400) |
146
+ | `--button-size` | Font size | `var(--size-normal)` |
147
+ | `--button-leading` | Line height | `var(--leading)` |
148
+ | `--button-shadow` | Box shadow (never on `plain`) | `none` |
149
+ | `--button-active-background` | Surface fill while pressed | `var(--button-hover-background)` |
150
+ | `--button-active-border` | Border while pressed | `var(--button-hover-border)` |
151
+ | `--button-active-shadow` | Box shadow while pressed | `var(--button-shadow)` |
152
+ | `--button-active-transform` | Transform while pressed | `var(--button-hover-transform)` |
153
+ | `--button-transition` | Transition | `all var(--duration-fast)` (150ms) |
154
+ | `--button-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
155
+ | `--button-disabled-opacity` | Opacity when disabled | `0.5` |
156
+ | `--button-solid-background` | Surface fill when `solid` | `var(--tint-50)` |
157
+ | `--button-solid-text` | Label colour when `solid` | `var(--tint-100)` (white) |
158
+ | `--button-solid-hover-background` | Surface fill on hover / focus when `solid` | `var(--tint-55)` |
159
+ | `--button-solid-active-background` | Surface fill while pressed when `solid` | `var(--button-solid-hover-background)` |
160
+ | `--button-plain-text` | Label colour when `plain` or `outline` | `var(--tint-50)` |
161
+ | `--button-plain-border` | Resting border when `plain` | `var(--button-stroke) solid transparent` |
162
+ | `--button-outline-border` | Resting border when `outline` | `var(--button-stroke) solid var(--tint-80)` |
163
+ | `--button-unselected-background` | Resting fill when `selected={false}` | `transparent` |
164
+ | `--button-plain-hover-background` | Fill on hover / focus when `plain` or `outline` | `var(--button-hover-background)` |
165
+ | `--button-plain-hover-border` | Border on hover / focus when `plain` or `outline` | `var(--button-hover-border)` (transparent) |
166
+ | `--button-plain-active-background` | Fill while pressed when `plain` or `outline` | `var(--button-plain-hover-background)` |
167
+ | `--button-plain-active-border` | Border while pressed when `plain` or `outline` | `var(--button-plain-hover-border)` |
159
168
 
160
169
  **Global tokens it reads:** the tint ladder `--tint-50` / `--tint-55` / `--tint-80` / `--tint-85` / `--tint-90` / `--tint-100`, plus `--size-icon`, `--space-small`, `--space-xxsmall`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, `--font-body`, `--weight-normal`, `--size-normal`, `--leading`, and `--duration-fast`.
161
170
 
162
171
  ```css
163
172
  /* Theme: pill-shaped buttons, with roomier inline padding. */
164
173
  :root {
165
- --button-radius: 999px;
166
- --button-indent: var(--space-normal);
174
+ --button-radius: 999px;
175
+ --button-indent: var(--space-normal);
167
176
  }
168
177
  ```
169
178
 
170
179
  ```css
171
180
  /* Theme: outline buttons use the label colour for their edge. */
172
181
  :root {
173
- --button-outline-border: var(--stroke-normal) solid var(--tint-50);
182
+ --button-outline-border: var(--stroke-normal) solid var(--tint-50);
174
183
  }
175
184
  ```
176
185
 
177
186
  ```css
178
187
  /* Theme: buttons are raised and press down flat — `plain` and `outline` press down too but never casts a shadow. */
179
188
  :root {
180
- --button-shadow: 0 0.25rem 0 var(--tint-30);
181
- --button-active-transform: translateY(0.2rem);
182
- --button-active-shadow: 0 0.05rem 0 var(--tint-30);
183
- --button-transition: all var(--duration-fast) cubic-bezier(0.34, 1.56, 0.64, 1);
189
+ --button-shadow: 0 0.25rem 0 var(--tint-30);
190
+ --button-active-transform: translateY(0.2rem);
191
+ --button-active-shadow: 0 0.05rem 0 var(--tint-30);
192
+ --button-transition: all var(--duration-fast) cubic-bezier(0.34, 1.56, 0.64, 1);
184
193
  }
185
194
  ```
186
195
 
package/docs/ui/Card.md CHANGED
@@ -15,6 +15,7 @@ A boxed surface that groups a self-contained piece of content. Rendered as an `<
15
15
  **Things to know:**
16
16
 
17
17
  - Set `href` or `onClick` to make the whole card navigable — a stretched, visually-hidden overlay `<a>` / `<button>` covers the card while the children render normally inside. Real interactive elements inside the card (inline links, buttons) stay clickable and keyboard-focusable.
18
+ - The overlay sits at `z-index: 1`, and the links and buttons inside the card at `z-index: 2`. To put your own absolute layer over the card's content, put it after the content, with no `z-index` and no lasting `transform`. The links and buttons inside it are then lifted above the overlay too. A `transform` makes the layer a stacking context below the overlay. A high `z-index` works, but iOS WebKit can drop that layer for one frame when a page view transition starts.
18
19
  - `color=` and `status=` move the tint anchor for the card's scope, so the surface, text, and hover shade all re-derive together — and nested components (`<Tag>`, `<Preformatted>`, `<Button>`) inherit the same tint.
19
20
  - A card styles only the box. Lay out its contents with the usual block components (`<Subheading>`, `<Paragraph>`, `<Row>`, …).
20
21
  - Cards have no drop shadow by default — set `shadow="small"`, `shadow="normal"` or `shadow="large"` to raise a given card.
@@ -28,9 +29,9 @@ A boxed surface that groups a self-contained piece of content. Rendered as an `<
28
29
  import { Card, Subheading, Paragraph } from "shelving/ui";
29
30
 
30
31
  <Card>
31
- <Subheading>Storage</Subheading>
32
- <Paragraph>1.2 GB of 5 GB used.</Paragraph>
33
- </Card>
32
+ <Subheading>Storage</Subheading>
33
+ <Paragraph>1.2 GB of 5 GB used.</Paragraph>
34
+ </Card>;
34
35
  ```
35
36
 
36
37
  ### Navigable card
@@ -40,9 +41,9 @@ import { Card, Subheading, Paragraph } from "shelving/ui";
40
41
 
41
42
  // The entire card is a link; `title` labels the overlay for screen readers.
42
43
  <Card href="/projects/shelving" title="Open Shelving">
43
- <Subheading>Shelving</Subheading>
44
- <Paragraph>TypeScript data toolkit.</Paragraph>
45
- </Card>
44
+ <Subheading>Shelving</Subheading>
45
+ <Paragraph>TypeScript data toolkit.</Paragraph>
46
+ </Card>;
46
47
  ```
47
48
 
48
49
  ### Status and colour
@@ -68,28 +69,28 @@ import { Card, Subheading } from "shelving/ui";
68
69
 
69
70
  `Card` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` (on the card or an ancestor scope) to recolour everything at once — surface, text, and hover shade re-derive together; reach for a per-property hook for a single surgical change.
70
71
 
71
- | Variable | Styles | Default |
72
- |---|---|---|
73
- | `--card-background` | Surface fill | `var(--tint-90)` |
74
- | `--card-hover-background` | Surface fill when a navigable card is hovered | `var(--tint-95)` |
75
- | `--card-color` | Text colour | `var(--tint-00)` |
76
- | `--card-border` | Border shorthand | `var(--card-stroke) solid var(--tint-80)` |
77
- | `--card-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
78
- | `--card-radius` | Corner radius | `var(--radius-normal)` (16px) |
79
- | `--card-padding` | Inner top and bottom padding (one length) | `var(--space-normal)` (16px) |
80
- | `--card-indent` | Inner left and right padding (one length) | `var(--space-normal)` (16px) |
81
- | `--card-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
82
- | `--card-shadow` | Drop shadow | `none` |
83
- | `--card-transition` | Transition | `all var(--duration-fast)` (150ms) |
84
- | `--card-focus-border` | Focus outline, drawn on the navigable overlay so it shows above children like `<Panel>` | `var(--stroke-focus) solid var(--color-focus)` |
72
+ | Variable | Styles | Default |
73
+ | ------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
74
+ | `--card-background` | Surface fill | `var(--tint-90)` |
75
+ | `--card-hover-background` | Surface fill when a navigable card is hovered | `var(--tint-95)` |
76
+ | `--card-color` | Text colour | `var(--tint-00)` |
77
+ | `--card-border` | Border shorthand | `var(--card-stroke) solid var(--tint-80)` |
78
+ | `--card-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
79
+ | `--card-radius` | Corner radius | `var(--radius-normal)` (16px) |
80
+ | `--card-padding` | Inner top and bottom padding (one length) | `var(--space-normal)` (16px) |
81
+ | `--card-indent` | Inner left and right padding (one length) | `var(--space-normal)` (16px) |
82
+ | `--card-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
83
+ | `--card-shadow` | Drop shadow | `none` |
84
+ | `--card-transition` | Transition | `all var(--duration-fast)` (150ms) |
85
+ | `--card-focus-border` | Focus outline, drawn on the navigable overlay so it shows above children like `<Panel>` | `var(--stroke-focus) solid var(--color-focus)` |
85
86
 
86
87
  **Global tokens it reads** — move these to retheme broadly rather than overriding ladder steps directly: the tint ladder `--tint-00` / `--tint-80` / `--tint-90` / `--tint-95`, plus `--space-normal`, `--space-paragraph`, `--radius-normal`, `--stroke-focus`, `--color-focus`, and `--duration-fast`.
87
88
 
88
89
  ```css
89
90
  /* Theme: raised cards with tighter corners. */
90
91
  :root {
91
- --card-shadow: var(--shadow-normal);
92
- --card-radius: var(--radius-small);
92
+ --card-shadow: var(--shadow-normal);
93
+ --card-radius: var(--radius-small);
93
94
  }
94
95
  ```
95
96
 
@@ -38,9 +38,9 @@ import { Catcher, ErrorPage, RetryButton } from "shelving/ui";
38
38
 
39
39
  // Custom error renderer plus a retry button anywhere in the subtree.
40
40
  <Catcher as={ErrorPage}>
41
- <RiskyComponent />
42
- <RetryButton small />
43
- </Catcher>
41
+ <RiskyComponent />
42
+ <RetryButton small />
43
+ </Catcher>;
44
44
  ```
45
45
 
46
46
 
@@ -8,7 +8,7 @@ Props for a component that accepts an additional `className`, merged _after_ the
8
8
  - Merged last so an app's own (unlayered) stylesheet reliably beats the library's `@layer components` rules.
9
9
  - Component hooks (`--card-background` etc.) and the tint ladder remain the primary theming surface; `className` is the escape hatch for one-off treatments they can't express.
10
10
 
11
- The shared `className` prop most components accept — an app class merged *after* the classes the component computes for itself.
11
+ The shared `className` prop most components accept — an app class merged _after_ the classes the component computes for itself.
12
12
 
13
13
  **Things to know:**
14
14
 
package/docs/ui/Code.md CHANGED
@@ -38,23 +38,23 @@ import { Code, Keyboard, Sample } from "shelving/ui";
38
38
  ```tsx live
39
39
  import { Code } from "shelving/ui";
40
40
 
41
- <Code plain>const x = 1;</Code>
41
+ <Code plain>const x = 1;</Code>;
42
42
  ```
43
43
 
44
44
  ## Styling
45
45
 
46
46
  `Code` paints from the [tint ladder](/ui/TINT_CLASS): the box `background` / `color` default to ladder steps so they re-tint with the surrounding scope, and every property has a per-instance override hook.
47
47
 
48
- | Variable | Styles | Default |
49
- |---|---|---|
50
- | `--code-font` | Font family | `var(--font-code)` |
51
- | `--code-weight` | Font weight | `var(--weight-code)` |
52
- | `--code-size` | Font size | `var(--size-smaller)` |
53
- | `--code-leading` | Line height | `var(--leading)` |
54
- | `--code-indent` | Left and right padding (one length; non-`plain`) | `var(--space-xxsmall)` |
55
- | `--code-radius` | Corner radius (non-`plain`) | `var(--radius-xxsmall)` |
56
- | `--code-background` | Background fill (non-`plain`) | `var(--tint-90)` |
57
- | `--code-color` | Text colour (non-`plain`) | `var(--tint-00)` |
48
+ | Variable | Styles | Default |
49
+ | ------------------- | ------------------------------------------------ | ----------------------- |
50
+ | `--code-font` | Font family | `var(--font-code)` |
51
+ | `--code-weight` | Font weight | `var(--weight-code)` |
52
+ | `--code-size` | Font size | `var(--size-smaller)` |
53
+ | `--code-leading` | Line height | `var(--leading)` |
54
+ | `--code-indent` | Left and right padding (one length; non-`plain`) | `var(--space-xxsmall)` |
55
+ | `--code-radius` | Corner radius (non-`plain`) | `var(--radius-xxsmall)` |
56
+ | `--code-background` | Background fill (non-`plain`) | `var(--tint-90)` |
57
+ | `--code-color` | Text colour (non-`plain`) | `var(--tint-00)` |
58
58
 
59
59
  **Global tokens it reads:** `--font-code`, `--weight-code`, `--size-smaller`, `--leading`, `--space-xxsmall`, `--radius-xxsmall`, and the tint-ladder steps `--tint-00` / `--tint-90` for the box fill and text.
60
60
 
@@ -19,11 +19,11 @@ A `<Transition>` preset that collapses its children in and out by animating thei
19
19
  import { CollapseTransition } from "shelving/ui";
20
20
 
21
21
  function Details({ open }: { open: boolean }) {
22
- return open ? (
23
- <CollapseTransition>
24
- <Panel>…</Panel>
25
- </CollapseTransition>
26
- ) : null;
22
+ return open ? (
23
+ <CollapseTransition>
24
+ <Panel>…</Panel>
25
+ </CollapseTransition>
26
+ ) : null;
27
27
  }
28
28
  ```
29
29
 
@@ -21,19 +21,19 @@ Deleted text — renders a `<del>` element to mark content that has been removed
21
21
  import { Paragraph, Deleted, Inserted } from "shelving/ui";
22
22
 
23
23
  <Paragraph>
24
- Was <Deleted>$50</Deleted> <Inserted>$35</Inserted>.
25
- </Paragraph>
24
+ Was <Deleted>$50</Deleted> <Inserted>$35</Inserted>.
25
+ </Paragraph>;
26
26
  ```
27
27
 
28
28
  ## Styling
29
29
 
30
30
  `Deleted` colours its text directly from `--color-red` (not the tint ladder), so deletions stay a consistent red regardless of the surrounding tint. Override `--deleted-color` to recolour.
31
31
 
32
- | Variable | Styles | Default |
33
- |---|---|---|
34
- | `--deleted-color` | Text colour | `var(--color-red)` |
32
+ | Variable | Styles | Default |
33
+ | ---------------------- | --------------- | ----------------------------------- |
34
+ | `--deleted-color` | Text colour | `var(--color-red)` |
35
35
  | `--deleted-decoration` | Text decoration | `line-through var(--stroke-normal)` |
36
- | `--deleted-weight` | Font weight | `var(--weight-strong)` |
36
+ | `--deleted-weight` | Font weight | `var(--weight-strong)` |
37
37
 
38
38
  **Global tokens it reads:** `--color-red`, `--stroke-normal`, and `--weight-strong`.
39
39
 
@@ -25,8 +25,8 @@ A collapsible panel. The title is always visible. The content shows when the use
25
25
  import { Details, Paragraph } from "shelving/ui";
26
26
 
27
27
  <Details title="What is shelving?">
28
- <Paragraph>A TypeScript data toolkit.</Paragraph>
29
- </Details>
28
+ <Paragraph>A TypeScript data toolkit.</Paragraph>
29
+ </Details>;
30
30
  ```
31
31
 
32
32
  ### Open by default
@@ -35,8 +35,8 @@ import { Details, Paragraph } from "shelving/ui";
35
35
  import { Details, Paragraph } from "shelving/ui";
36
36
 
37
37
  <Details title="Release notes" open>
38
- <Paragraph>Bug fixes and small improvements.</Paragraph>
39
- </Details>
38
+ <Paragraph>Bug fixes and small improvements.</Paragraph>
39
+ </Details>;
40
40
  ```
41
41
 
42
42
  ### Exclusive group (FAQ)
@@ -57,15 +57,15 @@ import { Details, Paragraph } from "shelving/ui";
57
57
 
58
58
  `Details` paints from the [tint ladder](/ui/TINT_CLASS). Override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` to an ancestor scope to recolour the chevron and divider together.
59
59
 
60
- | Variable | Styles | Default |
61
- |---|---|---|
62
- | `--details-space` | Outer block margin, and the padding above a divider | `var(--space-paragraph)` (16px) |
63
- | `--details-border` | Divider between panels next to each other | `var(--stroke-normal) solid var(--tint-90)` |
64
- | `--details-marker-color` | Colour of the browser's marker on a raw `<details>` in `.prose` | `var(--tint-80)` |
65
- | `--details-radius` | Corner radius of the title's focus ring | `var(--radius-xsmall)` (8px) |
66
- | `--details-icon-color` | Chevron colour | `var(--tint-50)` |
67
- | `--details-transition` | Open/close animation and chevron turn | `all var(--duration-fast)` (150ms) |
68
- | `--details-gap` | Space between the title and the content | `var(--space-paragraph)` (16px) |
60
+ | Variable | Styles | Default |
61
+ | ------------------------ | --------------------------------------------------------------- | ------------------------------------------- |
62
+ | `--details-space` | Outer block margin, and the padding above a divider | `var(--space-paragraph)` (16px) |
63
+ | `--details-border` | Divider between panels next to each other | `var(--stroke-normal) solid var(--tint-90)` |
64
+ | `--details-marker-color` | Colour of the browser's marker on a raw `<details>` in `.prose` | `var(--tint-80)` |
65
+ | `--details-radius` | Corner radius of the title's focus ring | `var(--radius-xsmall)` (8px) |
66
+ | `--details-icon-color` | Chevron colour | `var(--tint-50)` |
67
+ | `--details-transition` | Open/close animation and chevron turn | `all var(--duration-fast)` (150ms) |
68
+ | `--details-gap` | Space between the title and the content | `var(--space-paragraph)` (16px) |
69
69
 
70
70
  **Global tokens it reads:** the tint ladder `--tint-50` / `--tint-80` / `--tint-90`, plus `--space-paragraph`, `--space-normal`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, `--duration-fast` and `--size-icon` (chevron size, from `getFlexClass`).
71
71
 
package/docs/ui/Dialog.md CHANGED
@@ -29,7 +29,9 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
29
29
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition, so the dialog never ignores a tap while its content changes. The page ignores taps while a view transition runs.
30
30
  - `Dialog` knows nothing about transitions. React runs a view transition only for an update made inside `startTransition()`, so the code that mounts and unmounts the dialog decides if it animates:
31
31
  - `<Dialogs>` renders a `DialogsStore` inside transitions, so a dialog opened with `DialogsStore.show()` animates in and out for you.
32
- - A `Dialog` you mount yourself appears and goes at once, unless you set the state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
32
+ - A `Dialog` you mount yourself appears and goes at once, unless you set the React state that mounts and unmounts it inside `startTransition()`. See the declarative example below.
33
+ - A `Dialog` you mount from a store read with `useStore()` never animates. `useStore()` applies each change at once, so `startTransition()` around the store write does not help.
34
+ - To open a dialog from app code, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
33
35
  - A browser without view transitions shows and hides the dialog at once.
34
36
  - Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
35
37
 
@@ -43,19 +45,25 @@ Mount `<Dialog>` directly when its lifetime matches a React state variable.
43
45
  import { Dialog, Modal } from "shelving/ui";
44
46
 
45
47
  function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose: () => void }) {
46
- return (
47
- <Dialog onClose={onClose}>
48
- <Modal>
49
- <p>Delete this item?</p>
50
- <button type="button" onClick={onConfirm}>Delete</button>
51
- </Modal>
52
- </Dialog>
53
- );
48
+ return (
49
+ <Dialog onClose={onClose}>
50
+ <Modal>
51
+ <p>Delete this item?</p>
52
+ <button type="button" onClick={onConfirm}>
53
+ Delete
54
+ </button>
55
+ </Modal>
56
+ </Dialog>
57
+ );
54
58
  }
55
59
 
56
60
  // In the parent. Open and close inside `startTransition()` so the dialog animates in and out.
57
- <button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>Delete</button>
58
- {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => startTransition(() => setShowConfirm(false))} />}
61
+ <button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>
62
+ Delete
63
+ </button>;
64
+ {
65
+ showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => startTransition(() => setShowConfirm(false))} />;
66
+ }
59
67
  ```
60
68
 
61
69
  ### Imperative
@@ -66,15 +74,21 @@ Set up the context once near the app root (see `<DialogsContext>` and `<Dialogs>
66
74
  import { Modal, requireDialogs } from "shelving/ui";
67
75
 
68
76
  function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
69
- const dialogs = requireDialogs();
70
- const open = () =>
71
- dialogs.show(
72
- <Modal>
73
- <p>Delete this item?</p>
74
- <button type="button" onClick={onConfirm}>Delete</button>
75
- </Modal>,
76
- );
77
- return <button type="button" onClick={open}>Delete</button>;
77
+ const dialogs = requireDialogs();
78
+ const open = () =>
79
+ dialogs.show(
80
+ <Modal>
81
+ <p>Delete this item?</p>
82
+ <button type="button" onClick={onConfirm}>
83
+ Delete
84
+ </button>
85
+ </Modal>,
86
+ );
87
+ return (
88
+ <button type="button" onClick={open}>
89
+ Delete
90
+ </button>
91
+ );
78
92
  }
79
93
  ```
80
94
 
@@ -84,14 +98,14 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
84
98
 
85
99
  `Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. Transparent borders as wide as the screen's safe areas keep the content and the close button clear of the notch, rounded corners and home bar. The inner panel comes from its children, usually `<Modal>`. Override these hooks at `:root` (or any ancestor scope) to retheme.
86
100
 
87
- | Variable | Styles | Default |
88
- |---|---|---|
89
- | `--dialog-padding` | Top and bottom padding around the centred content (one length) | `var(--space-normal)` (16px) |
90
- | `--dialog-indent` | Left and right padding around the centred content (one length) | `var(--space-normal)` (16px) |
91
- | `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
92
- | `--dialog-background` | Overlay fill behind the content | `var(--color-backdrop)` |
93
- | `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
94
- | `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
101
+ | Variable | Styles | Default |
102
+ | ----------------------- | -------------------------------------------------------------- | ----------------------------- |
103
+ | `--dialog-padding` | Top and bottom padding around the centred content (one length) | `var(--space-normal)` (16px) |
104
+ | `--dialog-indent` | Left and right padding around the centred content (one length) | `var(--space-normal)` (16px) |
105
+ | `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
106
+ | `--dialog-background` | Overlay fill behind the content | `var(--color-backdrop)` |
107
+ | `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
108
+ | `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
95
109
 
96
110
  The fade uses the `fade` class from `<FadeTransition>`, so `--fade-transition-duration` sets its length. It runs only as the dialog opens and closes; an open dialog stays still while other dialogs open and close.
97
111
 
@@ -5,6 +5,10 @@
5
5
 
6
6
  Render the open dialogs from the current `DialogsContext`.
7
7
 
8
+ - It renders the list inside a transition, so each dialog animates in and out.
9
+ - To open a dialog, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
10
+ - A `<Dialog>` you render from `useStore()` never animates, even if you write the store inside `startTransition()`.
11
+
8
12
  ## Signatures
9
13
 
10
14
  ```ts
@@ -26,13 +26,13 @@ Used automatically by `<DocumentationPage>` and `<DocumentationCard>`. To render
26
26
  ```tsx
27
27
  import { DocumentationButtons } from "shelving/ui";
28
28
 
29
- <DocumentationButtons class="Store" extends="AbstractStore" implements={["Serializable"]} />
29
+ <DocumentationButtons class="Store" extends="AbstractStore" implements={["Serializable"]} />;
30
30
  ```
31
31
 
32
32
  Drop a relation by omitting it, or tighten spacing with `space`.
33
33
 
34
34
  ```tsx
35
- <DocumentationButtons extends="AbstractStore" space="none" />
35
+ <DocumentationButtons extends="AbstractStore" space="none" />;
36
36
  ```
37
37
 
38
38
  ## Styling
@@ -11,7 +11,7 @@ A compact link tile summarising a documented symbol — the default card rendere
11
11
 
12
12
  **Things to know:**
13
13
 
14
- - It leads with the symbol's signature(s) via `<DocumentationSignatures>` (the same calm code blocks as `<DocumentationPage>`). The signature already carries the name (and `readonly` for properties), so there is no separate title or kind tag — the card's *colour* carries the kind. Symbols with no signature (classes, interfaces, modules) fall back to a plain-name heading.
14
+ - It leads with the symbol's signature(s) via `<DocumentationSignatures>` (the same calm code blocks as `<DocumentationPage>`). The signature already carries the name (and `readonly` for properties), so there is no separate title or kind tag — the card's _colour_ carries the kind. Symbols with no signature (classes, interfaces, modules) fall back to a plain-name heading.
15
15
  - Below the heading it renders the symbol's `<DocumentationButtons>` relations, then a prose lead-in. The `member of` relation is dropped — a member card almost always sits on its own class's page already.
16
16
  - The card links to the element's stamped `path` (the canonical URL set by `flattenTree()` — see `<TreeProvider>`).
17
17
 
@@ -23,7 +23,7 @@ Used automatically via `<TreeCards>` (which `<DocumentationPage>` uses for its c
23
23
  import { DocumentationCard } from "shelving/ui";
24
24
 
25
25
  // `element` is a `tree-documentation` element from DirectoryExtractor (see /extract).
26
- <DocumentationCard {...element.props} />
26
+ <DocumentationCard {...element.props} />;
27
27
  ```
28
28
 
29
29
  To replace this renderer across the whole site, wrap the app in `TreeCardMapping`.
@@ -24,17 +24,17 @@ Show a live preview of TSX and CSS in an `<iframe>` of the playground frame page
24
24
  ```tsx
25
25
  import { DocumentationFrame } from "shelving/ui";
26
26
 
27
- <DocumentationFrame code={`import { Button } from "shelving/ui";\n<Button>Hi</Button>`} css=":root { --radius-normal: 4px; }" />
27
+ <DocumentationFrame code={`import { Button } from "shelving/ui";\n<Button>Hi</Button>`} css=":root { --radius-normal: 4px; }" />;
28
28
  ```
29
29
 
30
30
  ## Styling
31
31
 
32
32
  The frame has no border, radius, or margin. It fills the width of its parent, so the parent sets the look around it (see `<DocumentationLive>`). The space around the preview comes from padding inside the frame page.
33
33
 
34
- | Variable | Styles | Default |
35
- |---|---|---|
34
+ | Variable | Styles | Default |
35
+ | ---------------------------------- | ------------------------------------- | ------- |
36
36
  | `--documentation-frame-background` | Fill behind the frame before it loads | `white` |
37
- | `--documentation-frame-height` | Minimum height (one length) | `4rem` |
37
+ | `--documentation-frame-height` | Minimum height (one length) | `4rem` |
38
38
 
39
39
 
40
40
  ## Signatures