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/ui/block/Panel.md CHANGED
@@ -33,13 +33,13 @@ import { Panel, Block, Title, Paragraph } from "shelving/ui";
33
33
 
34
34
  `Panel` paints from the [tint ladder](/ui/TINT_CLASS); apply `color=` / `status=` (on the panel or an ancestor scope) to recolour the whole scope at once — surface and text re-derive together — or reach for a per-property hook for a single change.
35
35
 
36
- | Variable | Styles | Default |
37
- |---|---|---|
38
- | `--panel-background` | Surface fill | `var(--tint-90)` |
39
- | `--panel-color` | Text colour | `var(--tint-00)` |
40
- | `--panel-border` | Top/bottom border shorthand | `var(--panel-stroke) solid var(--tint-80)` |
41
- | `--panel-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
42
- | `--panel-padding` | Block padding (top + bottom) | `var(--space-section)` (2rem) |
43
- | `--panel-indent` | Inline padding (left + right) keeping content off the edges | `var(--space-normal)` (16px) |
36
+ | Variable | Styles | Default |
37
+ | -------------------- | -------------------------------------------------------------------------- | ------------------------------------------ |
38
+ | `--panel-background` | Surface fill | `var(--tint-90)` |
39
+ | `--panel-color` | Text colour | `var(--tint-00)` |
40
+ | `--panel-border` | Top/bottom border shorthand | `var(--panel-stroke) solid var(--tint-80)` |
41
+ | `--panel-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
42
+ | `--panel-padding` | Block padding (top + bottom) | `var(--space-section)` (2rem) |
43
+ | `--panel-indent` | Inline padding (left + right) keeping content off the edges | `var(--space-normal)` (16px) |
44
44
 
45
45
  **Global tokens it reads:** the tint-ladder steps `--tint-00` / `--tint-80` / `--tint-90`, plus `--space-section`, and `--space-normal`. The shared `padding` variant overrides `--panel-padding`; the shared `indent` variant overrides `--panel-indent`.
@@ -16,7 +16,7 @@ A block of body text — renders a `<p>`. The default container for running pros
16
16
  ```tsx live
17
17
  import { Paragraph } from "shelving/ui";
18
18
 
19
- <Paragraph>The best widget on the market.</Paragraph>
19
+ <Paragraph>The best widget on the market.</Paragraph>;
20
20
  ```
21
21
 
22
22
  ### With inline annotations
@@ -25,16 +25,16 @@ import { Paragraph } from "shelving/ui";
25
25
  import { Paragraph, Strong, Link } from "shelving/ui";
26
26
 
27
27
  <Paragraph>
28
- <Strong>Note:</Strong> read our <Link href="/privacy">privacy policy</Link> first.
29
- </Paragraph>
28
+ <Strong>Note:</Strong> read our <Link href="/privacy">privacy policy</Link> first.
29
+ </Paragraph>;
30
30
  ```
31
31
 
32
32
  ## Styling
33
33
 
34
34
  `Paragraph` exposes a single hook for its own block margin; it paints no colour of its own, so it inherits the surrounding text colour. Apply `color=` / `status=` to set the tint scope for any ladder-reading inline content inside it.
35
35
 
36
- | Variable | Styles | Default |
37
- |---|---|---|
36
+ | Variable | Styles | Default |
37
+ | ------------------- | --------------------------------- | ------------------------------- |
38
38
  | `--paragraph-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
39
39
 
40
40
  **Global tokens it reads:** `--space-paragraph`.
package/ui/block/Prose.md CHANGED
@@ -4,7 +4,7 @@ A wrapper that applies cohesive longform typography to a subtree of mixed HTML c
4
4
 
5
5
  **Things to know:**
6
6
 
7
- - `Prose` applies the "prose" variant of *every* block and inline component as a single compound class, so raw `<p>`, `<ul>`, `<h2>`, `<code>`, `<a>`, `<progress>`, etc. are styled to match their component counterparts (`<Paragraph>`, `<List>`, `<Heading>`, `<Code>`, `<Link>`, `<Progress>`, …).
7
+ - `Prose` applies the "prose" variant of _every_ block and inline component as a single compound class, so raw `<p>`, `<ul>`, `<h2>`, `<code>`, `<a>`, `<progress>`, etc. are styled to match their component counterparts (`<Paragraph>`, `<List>`, `<Heading>`, `<Code>`, `<Link>`, `<Progress>`, …).
8
8
  - This is the bridge for markup: wrap `shelving/markup` output (or anything that emits raw HTML) in `<Prose>` and it just works — no per-element component wrapping needed.
9
9
  - It only sets up typography and its own outer margin; it paints no colour and adds no box of its own.
10
10
 
@@ -16,8 +16,8 @@ A wrapper that applies cohesive longform typography to a subtree of mixed HTML c
16
16
  import { Prose, Markup } from "shelving/ui";
17
17
 
18
18
  <Prose>
19
- <Markup>{article.body}</Markup>
20
- </Prose>
19
+ <Markup>{article.body}</Markup>
20
+ </Prose>;
21
21
  ```
22
22
 
23
23
  ### Hand-written longform
@@ -26,9 +26,9 @@ import { Prose, Markup } from "shelving/ui";
26
26
  import { Prose, Paragraph } from "shelving/ui";
27
27
 
28
28
  <Prose>
29
- <Paragraph>First.</Paragraph>
30
- <Paragraph>Second.</Paragraph>
31
- </Prose>
29
+ <Paragraph>First.</Paragraph>
30
+ <Paragraph>Second.</Paragraph>
31
+ </Prose>;
32
32
  ```
33
33
 
34
34
  ## Styling
@@ -17,13 +17,16 @@ A landmark content region — renders a `<section>` with block-level spacing and
17
17
  import { Section, Heading, Definitions } from "shelving/ui";
18
18
 
19
19
  <Section width="narrow">
20
- <Heading>Account details</Heading>
21
- <Definitions>
22
- <dt>Name</dt><dd>Alice Smith</dd>
23
- <dt>Email</dt><dd>alice@example.com</dd>
24
- <dt>Plan</dt><dd>Pro</dd>
25
- </Definitions>
26
- </Section>
20
+ <Heading>Account details</Heading>
21
+ <Definitions>
22
+ <dt>Name</dt>
23
+ <dd>Alice Smith</dd>
24
+ <dt>Email</dt>
25
+ <dd>alice@example.com</dd>
26
+ <dt>Plan</dt>
27
+ <dd>Pro</dd>
28
+ </Definitions>
29
+ </Section>;
27
30
  ```
28
31
 
29
32
  ### Landmark elements
@@ -40,9 +43,9 @@ import { Header, Nav, Footer } from "shelving/ui";
40
43
 
41
44
  `Section` exposes hooks for its width and rhythm; it paints no colour of its own, so it inherits the surrounding tint.
42
45
 
43
- | Variable | Styles | Default |
44
- |---|---|---|
45
- | `--section-width` | Content width | `var(--width-normal)` (55rem) |
46
+ | Variable | Styles | Default |
47
+ | ----------------- | --------------------------------- | ----------------------------- |
48
+ | `--section-width` | Content width | `var(--width-normal)` (55rem) |
46
49
  | `--section-space` | Outer block margin (top + bottom) | `var(--space-section)` (2rem) |
47
50
 
48
51
  **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.
@@ -18,9 +18,9 @@ A subsection heading — renders an `<h3>`. It is the smallest member of the thr
18
18
  import { Card, Subheading, Paragraph } from "shelving/ui";
19
19
 
20
20
  <Card>
21
- <Subheading>Storage</Subheading>
22
- <Paragraph>1.2 GB of 5 GB used.</Paragraph>
23
- </Card>
21
+ <Subheading>Storage</Subheading>
22
+ <Paragraph>1.2 GB of 5 GB used.</Paragraph>
23
+ </Card>;
24
24
  ```
25
25
 
26
26
  ### The heading family together
@@ -37,14 +37,14 @@ import { Title, Heading, Subheading } from "shelving/ui";
37
37
 
38
38
  `Subheading` exposes hooks for its rhythm and type. It inherits text colour by default; set `--subheading-color` only to override that.
39
39
 
40
- | Variable | Styles | Default |
41
- |---|---|---|
42
- | `--subheading-color` | Text colour | `inherit` |
43
- | `--subheading-space-before` | Top margin | `var(--space-section)` (2rem) |
44
- | `--subheading-space` | Bottom margin | `var(--space-paragraph)` (16px) |
45
- | `--subheading-font` | Font family | `var(--font-title)` |
46
- | `--subheading-weight` | Font weight | `var(--weight-strong)` (700) |
47
- | `--subheading-size` | Font size | `var(--size-large)` |
48
- | `--subheading-leading` | Line height | `var(--leading)` |
40
+ | Variable | Styles | Default |
41
+ | --------------------------- | ------------- | ------------------------------- |
42
+ | `--subheading-color` | Text colour | `inherit` |
43
+ | `--subheading-space-before` | Top margin | `var(--space-section)` (2rem) |
44
+ | `--subheading-space` | Bottom margin | `var(--space-paragraph)` (16px) |
45
+ | `--subheading-font` | Font family | `var(--font-title)` |
46
+ | `--subheading-weight` | Font weight | `var(--weight-strong)` (700) |
47
+ | `--subheading-size` | Font size | `var(--size-large)` |
48
+ | `--subheading-leading` | Line height | `var(--leading)` |
49
49
 
50
50
  **Global tokens it reads:** `--space-section`, `--space-paragraph`, `--font-title`, `--weight-strong`, `--size-large`, and `--leading`.
package/ui/block/Title.md CHANGED
@@ -26,24 +26,24 @@ import { Title, Paragraph } from "shelving/ui";
26
26
  import { Panel, Block, Title } from "shelving/ui";
27
27
 
28
28
  <Panel as="header" color="primary">
29
- <Block width="narrow">
30
- <Title>Welcome</Title>
31
- </Block>
32
- </Panel>
29
+ <Block width="narrow">
30
+ <Title>Welcome</Title>
31
+ </Block>
32
+ </Panel>;
33
33
  ```
34
34
 
35
35
  ## Styling
36
36
 
37
37
  `Title` exposes hooks for its rhythm and type. It inherits text colour by default; set `--title-color` only to override that.
38
38
 
39
- | Variable | Styles | Default |
40
- |---|---|---|
41
- | `--title-color` | Text colour | `inherit` |
42
- | `--title-space-before` | Top margin | `var(--space-section)` (2rem) |
43
- | `--title-space` | Bottom margin | `var(--space-paragraph)` (16px) |
44
- | `--title-font` | Font family | `var(--font-title)` |
45
- | `--title-weight` | Font weight | `var(--weight-strong)` (700) |
46
- | `--title-size` | Font size | `var(--size-xxxlarge)` |
47
- | `--title-leading` | Line height | `var(--leading)` |
39
+ | Variable | Styles | Default |
40
+ | ---------------------- | ------------- | ------------------------------- |
41
+ | `--title-color` | Text colour | `inherit` |
42
+ | `--title-space-before` | Top margin | `var(--space-section)` (2rem) |
43
+ | `--title-space` | Bottom margin | `var(--space-paragraph)` (16px) |
44
+ | `--title-font` | Font family | `var(--font-title)` |
45
+ | `--title-weight` | Font weight | `var(--weight-strong)` (700) |
46
+ | `--title-size` | Font size | `var(--size-xxxlarge)` |
47
+ | `--title-leading` | Line height | `var(--leading)` |
48
48
 
49
49
  **Global tokens it reads:** `--space-section`, `--space-paragraph`, `--font-title`, `--weight-strong`, `--size-xxxlarge`, and `--leading`.
@@ -37,7 +37,9 @@ import { Button } from "shelving/ui";
37
37
  import { Button } from "shelving/ui";
38
38
 
39
39
  // No outer margin: it sits flush with the content around it.
40
- <Button full space="none" onClick={start}>Start</Button>
40
+ <Button full space="none" onClick={start}>
41
+ Start
42
+ </Button>;
41
43
  ```
42
44
 
43
45
  ### A row of buttons
@@ -47,9 +49,13 @@ import { Button } from "shelving/ui";
47
49
  import { Row } from "shelving/ui";
48
50
 
49
51
  <Row gap="small" right>
50
- <Button plain onClick={cancel}>Cancel</Button>
51
- <Button solid color="primary" onClick={submit}>Continue</Button>
52
- </Row>
52
+ <Button plain onClick={cancel}>
53
+ Cancel
54
+ </Button>
55
+ <Button solid color="primary" onClick={submit}>
56
+ Continue
57
+ </Button>
58
+ </Row>;
53
59
  ```
54
60
 
55
61
  ### Tabs
@@ -58,12 +64,12 @@ import { Row } from "shelving/ui";
58
64
  import { Button, Row } from "shelving/ui";
59
65
 
60
66
  <Row gap="xsmall">
61
- {SECTIONS.map(({ key, label }) => (
62
- <Button key={key} small solid selected={key === section} onClick={() => setSection(key)}>
63
- {label}
64
- </Button>
65
- ))}
66
- </Row>
67
+ {SECTIONS.map(({ key, label }) => (
68
+ <Button key={key} small solid selected={key === section} onClick={() => setSection(key)}>
69
+ {label}
70
+ </Button>
71
+ ))}
72
+ </Row>;
67
73
  ```
68
74
 
69
75
  ### A one-off treatment
@@ -72,7 +78,9 @@ import { Button, Row } from "shelving/ui";
72
78
  import { Button } from "shelving/ui";
73
79
 
74
80
  // `.spongy-press` lives in the app's own stylesheet — use it for what the theme hooks below can't express.
75
- <Button className="spongy-press" onClick={claim}>Claim</Button>
81
+ <Button className="spongy-press" onClick={claim}>
82
+ Claim
83
+ </Button>;
76
84
  ```
77
85
 
78
86
  ### Reusing the button class
@@ -82,8 +90,9 @@ import { getButtonClass } from "shelving/ui";
82
90
 
83
91
  // Style an arbitrary element as a button.
84
92
  <label className={getButtonClass({ color: "primary", solid: true, small: true })}>
85
- Upload<input type="file" hidden />
86
- </label>
93
+ Upload
94
+ <input type="file" hidden />
95
+ </label>;
87
96
  ```
88
97
 
89
98
  ## Styling
@@ -102,74 +111,74 @@ The `--button-*` colour hooks without a look in their name paint the default loo
102
111
 
103
112
  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.
104
113
 
105
- | Variable | Styles | Default |
106
- |---|---|---|
107
- | `--button-background` | Surface fill | `var(--tint-90)` |
108
- | `--button-hover-background` | Surface fill on hover / focus | `var(--tint-85)` |
109
- | `--button-hover-border` | Border on hover / focus | `var(--button-stroke) solid transparent` |
110
- | `--button-hover-transform` | Transform on hover / focus | `none` |
111
- | `--button-text` | Label colour | `var(--tint-50)` |
112
- | `--button-border` | Border shorthand | `var(--button-stroke) solid transparent` |
113
- | `--button-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
114
- | `--button-radius` | Corner radius | `var(--radius-xsmall)` (8px) |
115
- | `--button-padding` | Top and bottom padding (one length) | `var(--space-small)` (12px) |
116
- | `--button-indent` | Left and right padding (one length) | `var(--space-small)` (12px) |
117
- | `--button-small-padding` | Top and bottom padding when `small` (one length) | `var(--space-xxsmall)` (4px) |
118
- | `--button-small-indent` | Left and right padding when `small` (one length) | `var(--space-xxsmall)` (4px) |
119
- | `--button-icon-size` | Icon size, and the base of the minimum height | `var(--size-icon)` (24px) |
120
- | `--button-height` | Minimum height | `--button-icon-size` + 2 × `--button-padding` + 2 × `--button-stroke` (52px) |
121
- | `--button-small-height` | Minimum height when `small` | `--button-icon-size` + 2 × `--button-small-padding` + 2 × `--button-stroke` (36px) |
122
- | `--button-gap` | Gap between icon and label | `var(--space-small)` (12px) |
123
- | `--button-small-gap` | Gap between icon and label when `small` | `var(--space-xxsmall)` (4px) |
124
- | `--button-space` | Outer block margin | `var(--space-small)` (12px) |
125
- | `--button-font` | Font family | `var(--font-body)` |
126
- | `--button-weight` | Font weight | `var(--weight-normal)` (400) |
127
- | `--button-size` | Font size | `var(--size-normal)` |
128
- | `--button-leading` | Line height | `var(--leading)` |
129
- | `--button-shadow` | Box shadow (never on `plain`) | `none` |
130
- | `--button-active-background` | Surface fill while pressed | `var(--button-hover-background)` |
131
- | `--button-active-border` | Border while pressed | `var(--button-hover-border)` |
132
- | `--button-active-shadow` | Box shadow while pressed | `var(--button-shadow)` |
133
- | `--button-active-transform` | Transform while pressed | `var(--button-hover-transform)` |
134
- | `--button-transition` | Transition | `all var(--duration-fast)` (150ms) |
135
- | `--button-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
136
- | `--button-disabled-opacity` | Opacity when disabled | `0.5` |
137
- | `--button-solid-background` | Surface fill when `solid` | `var(--tint-50)` |
138
- | `--button-solid-text` | Label colour when `solid` | `var(--tint-100)` (white) |
139
- | `--button-solid-hover-background` | Surface fill on hover / focus when `solid` | `var(--tint-55)` |
140
- | `--button-solid-active-background` | Surface fill while pressed when `solid` | `var(--button-solid-hover-background)` |
141
- | `--button-plain-text` | Label colour when `plain` or `outline` | `var(--tint-50)` |
142
- | `--button-plain-border` | Resting border when `plain` | `var(--button-stroke) solid transparent` |
143
- | `--button-outline-border` | Resting border when `outline` | `var(--button-stroke) solid var(--tint-80)` |
144
- | `--button-unselected-background` | Resting fill when `selected={false}` | `transparent` |
145
- | `--button-plain-hover-background` | Fill on hover / focus when `plain` or `outline` | `var(--button-hover-background)` |
146
- | `--button-plain-hover-border` | Border on hover / focus when `plain` or `outline` | `var(--button-hover-border)` (transparent) |
147
- | `--button-plain-active-background` | Fill while pressed when `plain` or `outline` | `var(--button-plain-hover-background)` |
148
- | `--button-plain-active-border` | Border while pressed when `plain` or `outline` | `var(--button-plain-hover-border)` |
114
+ | Variable | Styles | Default |
115
+ | ---------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
116
+ | `--button-background` | Surface fill | `var(--tint-90)` |
117
+ | `--button-hover-background` | Surface fill on hover / focus | `var(--tint-85)` |
118
+ | `--button-hover-border` | Border on hover / focus | `var(--button-stroke) solid transparent` |
119
+ | `--button-hover-transform` | Transform on hover / focus | `none` |
120
+ | `--button-text` | Label colour | `var(--tint-50)` |
121
+ | `--button-border` | Border shorthand | `var(--button-stroke) solid transparent` |
122
+ | `--button-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
123
+ | `--button-radius` | Corner radius | `var(--radius-xsmall)` (8px) |
124
+ | `--button-padding` | Top and bottom padding (one length) | `var(--space-small)` (12px) |
125
+ | `--button-indent` | Left and right padding (one length) | `var(--space-small)` (12px) |
126
+ | `--button-small-padding` | Top and bottom padding when `small` (one length) | `var(--space-xxsmall)` (4px) |
127
+ | `--button-small-indent` | Left and right padding when `small` (one length) | `var(--space-xxsmall)` (4px) |
128
+ | `--button-icon-size` | Icon size, and the base of the minimum height | `var(--size-icon)` (24px) |
129
+ | `--button-height` | Minimum height | `--button-icon-size` + 2 × `--button-padding` + 2 × `--button-stroke` (52px) |
130
+ | `--button-small-height` | Minimum height when `small` | `--button-icon-size` + 2 × `--button-small-padding` + 2 × `--button-stroke` (36px) |
131
+ | `--button-gap` | Gap between icon and label | `var(--space-small)` (12px) |
132
+ | `--button-small-gap` | Gap between icon and label when `small` | `var(--space-xxsmall)` (4px) |
133
+ | `--button-space` | Outer block margin | `var(--space-small)` (12px) |
134
+ | `--button-font` | Font family | `var(--font-body)` |
135
+ | `--button-weight` | Font weight | `var(--weight-normal)` (400) |
136
+ | `--button-size` | Font size | `var(--size-normal)` |
137
+ | `--button-leading` | Line height | `var(--leading)` |
138
+ | `--button-shadow` | Box shadow (never on `plain`) | `none` |
139
+ | `--button-active-background` | Surface fill while pressed | `var(--button-hover-background)` |
140
+ | `--button-active-border` | Border while pressed | `var(--button-hover-border)` |
141
+ | `--button-active-shadow` | Box shadow while pressed | `var(--button-shadow)` |
142
+ | `--button-active-transform` | Transform while pressed | `var(--button-hover-transform)` |
143
+ | `--button-transition` | Transition | `all var(--duration-fast)` (150ms) |
144
+ | `--button-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
145
+ | `--button-disabled-opacity` | Opacity when disabled | `0.5` |
146
+ | `--button-solid-background` | Surface fill when `solid` | `var(--tint-50)` |
147
+ | `--button-solid-text` | Label colour when `solid` | `var(--tint-100)` (white) |
148
+ | `--button-solid-hover-background` | Surface fill on hover / focus when `solid` | `var(--tint-55)` |
149
+ | `--button-solid-active-background` | Surface fill while pressed when `solid` | `var(--button-solid-hover-background)` |
150
+ | `--button-plain-text` | Label colour when `plain` or `outline` | `var(--tint-50)` |
151
+ | `--button-plain-border` | Resting border when `plain` | `var(--button-stroke) solid transparent` |
152
+ | `--button-outline-border` | Resting border when `outline` | `var(--button-stroke) solid var(--tint-80)` |
153
+ | `--button-unselected-background` | Resting fill when `selected={false}` | `transparent` |
154
+ | `--button-plain-hover-background` | Fill on hover / focus when `plain` or `outline` | `var(--button-hover-background)` |
155
+ | `--button-plain-hover-border` | Border on hover / focus when `plain` or `outline` | `var(--button-hover-border)` (transparent) |
156
+ | `--button-plain-active-background` | Fill while pressed when `plain` or `outline` | `var(--button-plain-hover-background)` |
157
+ | `--button-plain-active-border` | Border while pressed when `plain` or `outline` | `var(--button-plain-hover-border)` |
149
158
 
150
159
  **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`.
151
160
 
152
161
  ```css
153
162
  /* Theme: pill-shaped buttons, with roomier inline padding. */
154
163
  :root {
155
- --button-radius: 999px;
156
- --button-indent: var(--space-normal);
164
+ --button-radius: 999px;
165
+ --button-indent: var(--space-normal);
157
166
  }
158
167
  ```
159
168
 
160
169
  ```css
161
170
  /* Theme: outline buttons use the label colour for their edge. */
162
171
  :root {
163
- --button-outline-border: var(--stroke-normal) solid var(--tint-50);
172
+ --button-outline-border: var(--stroke-normal) solid var(--tint-50);
164
173
  }
165
174
  ```
166
175
 
167
176
  ```css
168
177
  /* Theme: buttons are raised and press down flat — `plain` and `outline` press down too but never casts a shadow. */
169
178
  :root {
170
- --button-shadow: 0 0.25rem 0 var(--tint-30);
171
- --button-active-transform: translateY(0.2rem);
172
- --button-active-shadow: 0 0.05rem 0 var(--tint-30);
173
- --button-transition: all var(--duration-fast) cubic-bezier(0.34, 1.56, 0.64, 1);
179
+ --button-shadow: 0 0.25rem 0 var(--tint-30);
180
+ --button-active-transform: translateY(0.2rem);
181
+ --button-active-shadow: 0 0.05rem 0 var(--tint-30);
182
+ --button-transition: all var(--duration-fast) cubic-bezier(0.34, 1.56, 0.64, 1);
174
183
  }
175
184
  ```
@@ -16,7 +16,9 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
16
16
  - 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.
17
17
  - `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:
18
18
  - `<Dialogs>` renders a `DialogsStore` inside transitions, so a dialog opened with `DialogsStore.show()` animates in and out for you.
19
- - 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.
19
+ - 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.
20
+ - 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.
21
+ - To open a dialog from app code, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
20
22
  - A browser without view transitions shows and hides the dialog at once.
21
23
  - Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
22
24
 
@@ -30,19 +32,25 @@ Mount `<Dialog>` directly when its lifetime matches a React state variable.
30
32
  import { Dialog, Modal } from "shelving/ui";
31
33
 
32
34
  function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose: () => void }) {
33
- return (
34
- <Dialog onClose={onClose}>
35
- <Modal>
36
- <p>Delete this item?</p>
37
- <button type="button" onClick={onConfirm}>Delete</button>
38
- </Modal>
39
- </Dialog>
40
- );
35
+ return (
36
+ <Dialog onClose={onClose}>
37
+ <Modal>
38
+ <p>Delete this item?</p>
39
+ <button type="button" onClick={onConfirm}>
40
+ Delete
41
+ </button>
42
+ </Modal>
43
+ </Dialog>
44
+ );
41
45
  }
42
46
 
43
47
  // In the parent. Open and close inside `startTransition()` so the dialog animates in and out.
44
- <button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>Delete</button>
45
- {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => startTransition(() => setShowConfirm(false))} />}
48
+ <button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>
49
+ Delete
50
+ </button>;
51
+ {
52
+ showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => startTransition(() => setShowConfirm(false))} />;
53
+ }
46
54
  ```
47
55
 
48
56
  ### Imperative
@@ -53,15 +61,21 @@ Set up the context once near the app root (see `<DialogsContext>` and `<Dialogs>
53
61
  import { Modal, requireDialogs } from "shelving/ui";
54
62
 
55
63
  function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
56
- const dialogs = requireDialogs();
57
- const open = () =>
58
- dialogs.show(
59
- <Modal>
60
- <p>Delete this item?</p>
61
- <button type="button" onClick={onConfirm}>Delete</button>
62
- </Modal>,
63
- );
64
- return <button type="button" onClick={open}>Delete</button>;
64
+ const dialogs = requireDialogs();
65
+ const open = () =>
66
+ dialogs.show(
67
+ <Modal>
68
+ <p>Delete this item?</p>
69
+ <button type="button" onClick={onConfirm}>
70
+ Delete
71
+ </button>
72
+ </Modal>,
73
+ );
74
+ return (
75
+ <button type="button" onClick={open}>
76
+ Delete
77
+ </button>
78
+ );
65
79
  }
66
80
  ```
67
81
 
@@ -71,14 +85,14 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
71
85
 
72
86
  `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.
73
87
 
74
- | Variable | Styles | Default |
75
- |---|---|---|
76
- | `--dialog-padding` | Top and bottom padding around the centred content (one length) | `var(--space-normal)` (16px) |
77
- | `--dialog-indent` | Left and right padding around the centred content (one length) | `var(--space-normal)` (16px) |
78
- | `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
79
- | `--dialog-background` | Overlay fill behind the content | `var(--color-backdrop)` |
80
- | `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
81
- | `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
88
+ | Variable | Styles | Default |
89
+ | ----------------------- | -------------------------------------------------------------- | ----------------------------- |
90
+ | `--dialog-padding` | Top and bottom padding around the centred content (one length) | `var(--space-normal)` (16px) |
91
+ | `--dialog-indent` | Left and right padding around the centred content (one length) | `var(--space-normal)` (16px) |
92
+ | `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
93
+ | `--dialog-background` | Overlay fill behind the content | `var(--color-backdrop)` |
94
+ | `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
95
+ | `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
82
96
 
83
97
  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.
84
98
 
@@ -57,6 +57,10 @@ export declare function DialogsContext({ children }: DialogsContextProps): React
57
57
  /**
58
58
  * Render the open dialogs from the current `DialogsContext`.
59
59
  *
60
+ * - It renders the list inside a transition, so each dialog animates in and out.
61
+ * - To open a dialog, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
62
+ * - A `<Dialog>` you render from `useStore()` never animates, even if you write the store inside `startTransition()`.
63
+ *
60
64
  * @kind component
61
65
  * @see https://shelving.cc/ui/Dialogs
62
66
  */
@@ -61,6 +61,10 @@ export function DialogsContext({ children }) {
61
61
  /**
62
62
  * Render the open dialogs from the current `DialogsContext`.
63
63
  *
64
+ * - It renders the list inside a transition, so each dialog animates in and out.
65
+ * - To open a dialog, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
66
+ * - A `<Dialog>` you render from `useStore()` never animates, even if you write the store inside `startTransition()`.
67
+ *
64
68
  * @kind component
65
69
  * @see https://shelving.cc/ui/Dialogs
66
70
  */
@@ -90,6 +90,10 @@ export function DialogsContext({ children }: DialogsContextProps): ReactElement
90
90
  /**
91
91
  * Render the open dialogs from the current `DialogsContext`.
92
92
  *
93
+ * - It renders the list inside a transition, so each dialog animates in and out.
94
+ * - To open a dialog, use `requireDialogs()` and `DialogsStore.show()`. Pass the `DialogsStore` into any function that opens one.
95
+ * - A `<Dialog>` you render from `useStore()` never animates, even if you write the store inside `startTransition()`.
96
+ *
93
97
  * @kind component
94
98
  * @see https://shelving.cc/ui/Dialogs
95
99
  */