shelving 1.318.0 → 1.319.1

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 (140) hide show
  1. package/docs/llms-full.txt +964 -115
  2. package/docs/markup/FENCED_RULE.md +1 -0
  3. package/docs/markup/FencedInfo.md +24 -0
  4. package/docs/markup/createFencedRegExp.md +31 -0
  5. package/docs/markup/parseFencedInfo.md +34 -0
  6. package/docs/markup.md +3 -0
  7. package/docs/ui/Button.md +1 -1
  8. package/docs/ui/Card.md +4 -4
  9. package/docs/ui/Code.md +1 -1
  10. package/docs/ui/DOCUMENTATION_LIVE_RULE.md +16 -0
  11. package/docs/ui/DOCUMENTATION_MARKUP_RULES.md +12 -0
  12. package/docs/ui/Deleted.md +1 -1
  13. package/docs/ui/Details.md +3 -3
  14. package/docs/ui/Dialog.md +11 -8
  15. package/docs/ui/DialogProps.md +1 -1
  16. package/docs/ui/DocumentationApp.md +5 -5
  17. package/docs/ui/DocumentationFrame.md +57 -0
  18. package/docs/ui/DocumentationFrameProps.md +21 -0
  19. package/docs/ui/DocumentationLive.md +86 -0
  20. package/docs/ui/DocumentationLiveProps.md +22 -0
  21. package/docs/ui/DocumentationPlaygroundInsert.md +30 -0
  22. package/docs/ui/DocumentationPlaygroundInsertProps.md +24 -0
  23. package/docs/ui/DocumentationPlaygroundPage.md +32 -0
  24. package/docs/ui/Emphasis.md +1 -1
  25. package/docs/ui/Empty.md +1 -1
  26. package/docs/ui/Form.md +1 -1
  27. package/docs/ui/Grid.md +1 -1
  28. package/docs/ui/Heading.md +3 -3
  29. package/docs/ui/Icon.md +1 -1
  30. package/docs/ui/Inserted.md +1 -1
  31. package/docs/ui/Link.md +3 -3
  32. package/docs/ui/List.md +1 -1
  33. package/docs/ui/Mark.md +1 -1
  34. package/docs/ui/Menu.md +1 -1
  35. package/docs/ui/MenuItem.md +2 -2
  36. package/docs/ui/Modal.md +1 -1
  37. package/docs/ui/Notice.md +1 -1
  38. package/docs/ui/Notices.md +1 -1
  39. package/docs/ui/PLAYGROUND_COMPONENTS_PATH.md +7 -0
  40. package/docs/ui/PLAYGROUND_FRAME_PATH.md +6 -0
  41. package/docs/ui/PLAYGROUND_HEIGHT_MESSAGE.md +6 -0
  42. package/docs/ui/PLAYGROUND_PAGE_PATH.md +6 -0
  43. package/docs/ui/PLAYGROUND_VARIABLES_PATH.md +7 -0
  44. package/docs/ui/Panel.md +1 -1
  45. package/docs/ui/Paragraph.md +2 -2
  46. package/docs/ui/PlaygroundCode.md +22 -0
  47. package/docs/ui/PlaygroundComponent.md +26 -0
  48. package/docs/ui/PlaygroundVariable.md +24 -0
  49. package/docs/ui/PlaygroundVariableGroup.md +24 -0
  50. package/docs/ui/Progress.md +4 -4
  51. package/docs/ui/Prose.md +1 -1
  52. package/docs/ui/SchemaInput.md +1 -1
  53. package/docs/ui/Section.md +1 -1
  54. package/docs/ui/Small.md +1 -1
  55. package/docs/ui/Span.md +2 -2
  56. package/docs/ui/Strong.md +1 -1
  57. package/docs/ui/Subheading.md +2 -2
  58. package/docs/ui/Table.md +2 -2
  59. package/docs/ui/Tag.md +1 -1
  60. package/docs/ui/Title.md +2 -2
  61. package/docs/ui/formatPlaygroundCSS.md +31 -0
  62. package/docs/ui/formatPlaygroundHash.md +34 -0
  63. package/docs/ui/insertPlaygroundSnippet.md +34 -0
  64. package/docs/ui/insertPlaygroundText.md +33 -0
  65. package/docs/ui/parsePlaygroundHash.md +31 -0
  66. package/docs/ui/requestDialogClose.md +28 -0
  67. package/docs/ui.md +27 -1
  68. package/markup/rule/fenced.d.ts +42 -0
  69. package/markup/rule/fenced.js +48 -4
  70. package/package.json +1 -1
  71. package/ui/README.md +2 -0
  72. package/ui/block/Card.md +4 -4
  73. package/ui/block/Details.md +3 -3
  74. package/ui/block/Grid.md +1 -1
  75. package/ui/block/Heading.md +3 -3
  76. package/ui/block/List.md +1 -1
  77. package/ui/block/Panel.md +1 -1
  78. package/ui/block/Paragraph.md +2 -2
  79. package/ui/block/Prose.md +1 -1
  80. package/ui/block/Section.md +1 -1
  81. package/ui/block/Subheading.md +2 -2
  82. package/ui/block/Title.md +2 -2
  83. package/ui/button/Button.md +1 -1
  84. package/ui/dialog/Dialog.d.ts +15 -3
  85. package/ui/dialog/Dialog.js +17 -10
  86. package/ui/dialog/Dialog.md +9 -6
  87. package/ui/dialog/Dialog.tsx +18 -11
  88. package/ui/dialog/Modal.md +1 -1
  89. package/ui/docs/DocumentationApp.d.ts +6 -2
  90. package/ui/docs/DocumentationApp.js +18 -5
  91. package/ui/docs/DocumentationApp.tsx +32 -3
  92. package/ui/docs/DocumentationFrame.d.ts +26 -0
  93. package/ui/docs/DocumentationFrame.js +34 -0
  94. package/ui/docs/DocumentationFrame.md +28 -0
  95. package/ui/docs/DocumentationFrame.module.css +17 -0
  96. package/ui/docs/DocumentationFrame.tsx +58 -0
  97. package/ui/docs/DocumentationLive.d.ts +37 -0
  98. package/ui/docs/DocumentationLive.js +39 -0
  99. package/ui/docs/DocumentationLive.md +57 -0
  100. package/ui/docs/DocumentationLive.module.css +85 -0
  101. package/ui/docs/DocumentationLive.test.tsx +34 -0
  102. package/ui/docs/DocumentationLive.tsx +75 -0
  103. package/ui/docs/DocumentationPage.js +2 -1
  104. package/ui/docs/DocumentationPage.tsx +2 -1
  105. package/ui/docs/DocumentationPlaygroundInsert.d.ts +24 -0
  106. package/ui/docs/DocumentationPlaygroundInsert.js +80 -0
  107. package/ui/docs/DocumentationPlaygroundInsert.tsx +151 -0
  108. package/ui/docs/DocumentationPlaygroundPage.d.ts +17 -0
  109. package/ui/docs/DocumentationPlaygroundPage.js +215 -0
  110. package/ui/docs/DocumentationPlaygroundPage.module.css +106 -0
  111. package/ui/docs/DocumentationPlaygroundPage.tsx +294 -0
  112. package/ui/docs/index.d.ts +5 -0
  113. package/ui/docs/index.js +5 -0
  114. package/ui/docs/index.ts +5 -0
  115. package/ui/docs/playground.d.ts +139 -0
  116. package/ui/docs/playground.js +162 -0
  117. package/ui/docs/playground.test.ts +83 -0
  118. package/ui/docs/playground.ts +225 -0
  119. package/ui/form/Form.js +4 -3
  120. package/ui/form/Form.md +1 -1
  121. package/ui/form/Form.tsx +3 -2
  122. package/ui/form/Progress.md +4 -4
  123. package/ui/inline/Code.md +1 -1
  124. package/ui/inline/Deleted.md +1 -1
  125. package/ui/inline/Emphasis.md +1 -1
  126. package/ui/inline/Inserted.md +1 -1
  127. package/ui/inline/Link.md +3 -3
  128. package/ui/inline/Mark.md +1 -1
  129. package/ui/inline/Small.md +1 -1
  130. package/ui/inline/Span.md +2 -2
  131. package/ui/inline/Strong.md +1 -1
  132. package/ui/input/SchemaInput.md +1 -1
  133. package/ui/menu/Menu.md +1 -1
  134. package/ui/menu/MenuItem.md +2 -2
  135. package/ui/misc/Icon.md +1 -1
  136. package/ui/misc/Tag.md +1 -1
  137. package/ui/notice/Empty.md +1 -1
  138. package/ui/notice/Notice.md +1 -1
  139. package/ui/notice/Notices.md +1 -1
  140. package/ui/table/Table.md +2 -2
@@ -9998,6 +9998,8 @@ If the text reaches you straight from a `StringSchema`-validated field it is alr
9998
9998
  ## Functions
9999
9999
 
10000
10000
  - [createMarkupRule()](markup/createMarkupRule.md): Create a typed MarkupRule from a NamedRegExp, a renderer, its contexts, and an optional priority.
10001
+ - [parseFencedInfo()](markup/parseFencedInfo.md): Parse the info string of a fenced code block into its language, flags, and title.
10002
+ - [createFencedRegExp()](markup/createFencedRegExp.md): Create the regular expression that matches a fenced code block.
10001
10003
  - [createBlockRegExp()](markup/createBlockRegExp.md): Create a RegExp that matches a block of content, wrapped between block-start and block-end boundaries.
10002
10004
  - [createLineRegExp()](markup/createLineRegExp.md): Create a RegExp that matches a single line of content, wrapped between line-start and line-end boundaries.
10003
10005
  - [createWordRegExp()](markup/createWordRegExp.md): Create a RegExp that matches a word of content, wrapped between word-start and word-end boundaries.
@@ -10010,6 +10012,7 @@ If the text reaches you straight from a `StringSchema`-validated field it is alr
10010
10012
  ## Interfaces
10011
10013
 
10012
10014
  - [MarkupRule](markup/MarkupRule.md): A single markup rule: a regular expression that matches a span of input plus a renderer that turns the match into an element.
10015
+ - [FencedInfo](markup/FencedInfo.md): Parts of the info string that follows the opening fence of a fenced code block.
10013
10016
 
10014
10017
  ## Types
10015
10018
 
@@ -10468,6 +10471,107 @@ new MarkupParser({ rules: [CODE_RULE] }).parse("Some `inline code` here")
10468
10471
  ```
10469
10472
 
10470
10473
 
10474
+ ---
10475
+
10476
+ # FencedInfo
10477
+
10478
+ - Kind: interface
10479
+ - Import: `import { FencedInfo } from "shelving/markup";`
10480
+
10481
+ Parts of the info string that follows the opening fence of a fenced code block.
10482
+
10483
+ ## Signatures
10484
+
10485
+ ```ts
10486
+ {
10487
+ readonly language: string;
10488
+ readonly flags: ImmutableArray<string>;
10489
+ readonly title: string;
10490
+ }
10491
+ ```
10492
+
10493
+ ## Properties
10494
+
10495
+ | Property | Type | Description |
10496
+ | --- | --- | --- |
10497
+ | `language` | `string` | Language of the code, e.g. `"tsx"`, or `""` if the info string has no language. Read only. |
10498
+ | `flags` | `ImmutableArray<string>` | Flags that follow the language, e.g. `["live"]`. Read only. |
10499
+ | `title` | `string` | Title to show above the code, or `""` if the info string has no title. Read only. |
10500
+
10501
+
10502
+ ---
10503
+
10504
+ # parseFencedInfo()
10505
+
10506
+ - Kind: function
10507
+ - Import: `import { parseFencedInfo } from "shelving/markup";`
10508
+
10509
+ Parse the info string of a fenced code block into its language, flags, and title.
10510
+ - The first word is the language, e.g. `tsx`.
10511
+ - A first word with a dot is a file name, e.g. `worker.ts`: it becomes the title, and its extension becomes the language.
10512
+ - Each other word is a flag, e.g. `live`.
10513
+ - Text in double quotes is the title, e.g. `"Card with a link"`.
10514
+
10515
+ ## Signatures
10516
+
10517
+ ```ts
10518
+ parseFencedInfo(info: string): FencedInfo
10519
+ ```
10520
+
10521
+ ## Parameters
10522
+
10523
+ | Param | Type | Description |
10524
+ | --- | --- | --- |
10525
+ | `info` | `string` | The text after the opening fence, e.g. `tsx live "Card with a link"`. |
10526
+
10527
+ ## Returns
10528
+
10529
+ | Type | Description |
10530
+ | --- | --- |
10531
+ | `FencedInfo` | The parsed language, flags, and title. |
10532
+
10533
+ ## Examples
10534
+
10535
+ ```ts
10536
+ parseFencedInfo('tsx live "My card"') // { language: "tsx", flags: ["live"], title: "My card" }
10537
+ ```
10538
+
10539
+
10540
+ ---
10541
+
10542
+ # createFencedRegExp()
10543
+
10544
+ - Kind: function
10545
+ - Import: `import { createFencedRegExp } from "shelving/markup";`
10546
+
10547
+ Create the regular expression that matches a fenced code block.
10548
+
10549
+ ## Signatures
10550
+
10551
+ ```ts
10552
+ createFencedRegExp(info: string = LINE_CONTENT_REGEXP): NamedRegExp<{ fence: string; info?: string; code: string }>
10553
+ ```
10554
+
10555
+ ## Parameters
10556
+
10557
+ | Param | Type | Description |
10558
+ | --- | --- | --- |
10559
+ | `info` | `string` | Regular expression source that the info string after the opening fence must match. Defaults to `LINE_CONTENT_REGEXP`. |
10560
+
10561
+ ## Returns
10562
+
10563
+ | Type | Description |
10564
+ | --- | --- |
10565
+ | `NamedRegExp<{ fence: string; info?: string; code: string }>` | A block regular expression with `fence`, `info`, and `code` named groups. |
10566
+
10567
+ ## Examples
10568
+
10569
+ ```ts
10570
+ createFencedRegExp("tsx live") // Matches only fences that start with ```tsx live
10571
+ @see https://shelving.cc/markup/createFencedRegExp
10572
+ ```
10573
+
10574
+
10471
10575
  ---
10472
10576
 
10473
10577
  # FENCED_RULE
@@ -10481,6 +10585,7 @@ Fenced code blocks
10481
10585
  - Stop when we reach a matching closing fence on a new line, or the end of the string.
10482
10586
  - Closing fence must be exactly the same as the opening fence, and can be made of three or more backticks, or three or more `~~~` tildes.
10483
10587
  - If there's no closing fence the code block will run to the end of the current string.
10588
+ - The info string after the opening fence is parsed with `parseFencedInfo()`: only its title shows, as a caption.
10484
10589
  - Markdown-style four-space indent syntax is not supported (only fenced code since it's less confusing and more common).
10485
10590
 
10486
10591
  ## Examples
@@ -19937,6 +20042,8 @@ The components below are listed in the index following this page; this is the sh
19937
20042
 
19938
20043
  **Documentation site.** Hand an extracted tree to `<TreeApp>` and you get a complete site — sidebar, routing, and a rendered page per element — using the renderers in `docs/`.
19939
20044
 
20045
+ **Live examples and playground.** `<DocumentationApp>` adds a `<DocumentationPlaygroundPage>` at `/playground`, where you write TSX and CSS and see them run with the raw shelving styles. On any docs page, a fenced code block with a `live` flag (` ```tsx live `) shows its code next to a live preview — see `<DocumentationLive>`.
20046
+
19940
20047
 
19941
20048
  ## Components
19942
20049
 
@@ -19977,12 +20084,17 @@ The components below are listed in the index following this page; this is the sh
19977
20084
  - [DialogsContext](ui/DialogsContext.md): Provider that creates a fresh DialogsStore and shares it with its subtree.
19978
20085
  - [Dialogs](ui/Dialogs.md): Render the open dialogs from the current DialogsContext.
19979
20086
  - [Modal](ui/Modal.md): Styled <aside> panel for content inside a <Dialog>, with dark text on a light surface.
20087
+ - [DocumentationApp](ui/DocumentationApp.md): Documentation app.
19980
20088
  - [DocumentationButtons](ui/DocumentationButtons.md): Render a symbol's relational metadata as a <nav> column of labelled links.
19981
20089
  - [DocumentationCard](ui/DocumentationCard.md): Card renderer for a tree-documentation element — a compact summary card linking to the symbol's detail page.
19982
20090
  - [DocumentationDescription](ui/DocumentationDescription.md): Render a documentation table row's description cell.
20091
+ - [DocumentationFrame](ui/DocumentationFrame.md): Show a live preview of playground code in an <iframe> of the playground frame page.
19983
20092
  - [DocumentationKind](ui/DocumentationKind.md): Colour-coded tag for a documented symbol's kind.
20093
+ - [DocumentationLive](ui/DocumentationLive.md): Show a code example next to a live preview of it on a simple phone, with a link under it that opens it in the playground.
19984
20094
  - [DocumentationPage](ui/DocumentationPage.md): Page renderer for a tree-documentation element — the full detail page for a documented symbol.
19985
20095
  - [DocumentationParams](ui/DocumentationParams.md): Render a documented symbol's parameters as a scrollable table — one row per parameter.
20096
+ - [DocumentationPlaygroundInsert](ui/DocumentationPlaygroundInsert.md): Panel that slides in from the right of the playground, to insert a shelving component into the TSX, or a CSS variable into the CSS.
20097
+ - [DocumentationPlaygroundPage](ui/DocumentationPlaygroundPage.md): Page where you can write TSX and CSS and see the result run live, like the TypeScript Playground.
19986
20098
  - [DocumentationProperties](ui/DocumentationProperties.md): Render a documented type's data members (properties, getters/setters) as a scrollable table — one row per property.
19987
20099
  - [DocumentationReferences](ui/DocumentationReferences.md): Render a type alias's referenced type names as a scrollable table — one row per referenced type.
19988
20100
  - [DocumentationReturns](ui/DocumentationReturns.md): Render a documented symbol's @returns entries as a scrollable table — one row per return type.
@@ -20093,10 +20205,15 @@ The components below are listed in the index following this page; this is the sh
20093
20205
  - [ButtonClickable()](ui/ButtonClickable.md): Render a <button> element that runs its onClick handler through a BusyStore and shows a loading spinner while busy.
20094
20206
  - [SpanClickable()](ui/SpanClickable.md): Render a non-interactive <span> element, used as the fallback when none of href, onClick or disabled is provided, e.g. a plain tag.
20095
20207
  - [SubmitButton()](ui/SubmitButton.md): Submit button for a form that disables itself and shows a spinner while the form is busy.
20208
+ - [requestDialogClose()](ui/requestDialogClose.md): Ask a <dialog> element to close, the same way as the Escape key.
20096
20209
  - [requireDialogs()](ui/requireDialogs.md): Read the current DialogsStore from the nearest <DialogsContext>.
20097
- - [DocumentationApp()](ui/DocumentationApp.md): Documentation app.
20098
20210
  - [getDocumentationKindColor()](ui/getDocumentationKindColor.md): Get the raw colour variant for a documented symbol's kind, or undefined for an unknown kind.
20099
20211
  - [splitType()](ui/splitType.md): Split a type expression on | into its individual union members.
20212
+ - [formatPlaygroundHash()](ui/formatPlaygroundHash.md): Format code and CSS as a URL hash for the playground page or its frame, e.g. #code=…&css=….
20213
+ - [parsePlaygroundHash()](ui/parsePlaygroundHash.md): Parse a URL hash made by formatPlaygroundHash() back into code and CSS.
20214
+ - [formatPlaygroundCSS()](ui/formatPlaygroundCSS.md): Format CSS variables as a :root rule that you can paste into the playground CSS and change.
20215
+ - [insertPlaygroundSnippet()](ui/insertPlaygroundSnippet.md): Insert a TSX snippet into playground code, and merge the snippet's imports into the code's imports.
20216
+ - [insertPlaygroundText()](ui/insertPlaygroundText.md): Insert text on its own lines into playground code or CSS.
20100
20217
  - [callNotifiedForm()](ui/callNotifiedForm.md): Run a form submit callback and publish success/error notices based on its return or thrown value.
20101
20218
  - [awaitNotifiedForm()](ui/awaitNotifiedForm.md): Await a pending submit result and publish a success or error notice to a form once it settles.
20102
20219
  - [notifyThrownForm()](ui/notifyThrownForm.md): Notify the user about a value thrown during submit, storing string errors as form field messages.
@@ -20221,14 +20338,21 @@ The components below are listed in the index following this page; this is the sh
20221
20338
  - [ModalProps](ui/ModalProps.md): Props for <Modal> — edge, padding, indent, radius, and shadow variants, optional children content, and an optional className.
20222
20339
  - [DocumentationButtonsProps](ui/DocumentationButtonsProps.md): Props for DocumentationButtons — the relational metadata of a documented symbol (class, extends, implements), plus block-space and flex overrides.
20223
20340
  - [DocumentationDescriptionProps](ui/DocumentationDescriptionProps.md): Props for DocumentationDescription — a description cell's resolved text, plus an optional default/optionality note.
20341
+ - [DocumentationFrameProps](ui/DocumentationFrameProps.md): Props for <DocumentationFrame> — the code and CSS to run, plus a title for the frame.
20224
20342
  - [DocumentationKindProps](ui/DocumentationKindProps.md): Props for DocumentationKind — a TagProps plus the documented symbol's kind.
20343
+ - [DocumentationLiveProps](ui/DocumentationLiveProps.md): Props for <DocumentationLive> — the code to show and run, plus an optional title.
20225
20344
  - [DocumentationParamsProps](ui/DocumentationParamsProps.md): Props for DocumentationParams — the parameter list to render, one row per parameter.
20345
+ - [DocumentationPlaygroundInsertProps](ui/DocumentationPlaygroundInsertProps.md): Props for <DocumentationPlaygroundInsert>.
20226
20346
  - [DocumentationPropertiesProps](ui/DocumentationPropertiesProps.md): Props for DocumentationProperties — the data members of a class/interface/object-literal type to render, one row each.
20227
20347
  - [DocumentationReferencesProps](ui/DocumentationReferencesProps.md): Props for DocumentationReferences — the referenced type names to render, one row each.
20228
20348
  - [DocumentationReturnsProps](ui/DocumentationReturnsProps.md): Props for DocumentationReturns — the @returns entries to render, one row each.
20229
20349
  - [DocumentationSignaturesProps](ui/DocumentationSignaturesProps.md): Props for DocumentationSignatures — the type signatures to render, one block per overload.
20230
20350
  - [DocumentationThrowsProps](ui/DocumentationThrowsProps.md): Props for DocumentationThrows — the @throws entries to render, one row each.
20231
20351
  - [DocumentationTypeProps](ui/DocumentationTypeProps.md): Props for DocumentationType — the union members to render (see splitType()).
20352
+ - [PlaygroundCode](ui/PlaygroundCode.md): Code and CSS that the playground frame runs.
20353
+ - [PlaygroundVariable](ui/PlaygroundVariable.md): One CSS variable that you can set to change the look of shelving components.
20354
+ - [PlaygroundVariableGroup](ui/PlaygroundVariableGroup.md): A group of CSS variables that one CSS module owns, e.g. the --card-* variables of Card.module.css.
20355
+ - [PlaygroundComponent](ui/PlaygroundComponent.md): One shelving component that you can insert into the playground code.
20232
20356
  - [FieldProps](ui/FieldProps.md): Props for Field, a labelled wrapper around a form control.
20233
20357
  - [FormProps](ui/FormProps.md): Props for Form, the schema-driven form wrapper component.
20234
20358
  - [FormFooterProps](ui/FormFooterProps.md): Props for FormFooter, the submit-button-and-message footer for a form.
@@ -20395,6 +20519,13 @@ The components below are listed in the index following this page; this is the sh
20395
20519
  ## Constants
20396
20520
 
20397
20521
  - [RetryContext](ui/RetryContext.md): Context for providing a "retry" callback to descendant <RetryButton> elements.
20522
+ - [DOCUMENTATION_LIVE_RULE](ui/DOCUMENTATION_LIVE_RULE.md): Markup rule that renders a fenced code block with a live flag as a <DocumentationLive> example, e.g. tsx live "Card with a link" `.
20523
+ - [DOCUMENTATION_MARKUP_RULES](ui/DOCUMENTATION_MARKUP_RULES.md): Markup rules for docs site content: DOCUMENTATION_LIVE_RULE then TREE_MARKUP_RULES, so fenced code blocks with a live flag run.
20524
+ - [PLAYGROUND_FRAME_PATH](ui/PLAYGROUND_FRAME_PATH.md): Path of the frame page that runs playground code, relative to the docs site root.
20525
+ - [PLAYGROUND_PAGE_PATH](ui/PLAYGROUND_PAGE_PATH.md): Path of the playground page, relative to the docs site root.
20526
+ - [PLAYGROUND_HEIGHT_MESSAGE](ui/PLAYGROUND_HEIGHT_MESSAGE.md): Type of the message that the frame page posts to its parent with its content height, e.g. { type: PLAYGROUND_HEIGHT_MESSAGE, height: 320 }.
20527
+ - [PLAYGROUND_VARIABLES_PATH](ui/PLAYGROUND_VARIABLES_PATH.md): Path of the CSS variable index that the docs build writes, relative to the docs site root.
20528
+ - [PLAYGROUND_COMPONENTS_PATH](ui/PLAYGROUND_COMPONENTS_PATH.md): Path of the component index that the docs build writes, relative to the docs site root.
20398
20529
  - [FormContext](ui/FormContext.md): React context holding the current FormStore, provided by the Form component.
20399
20530
  - [LOADING_INPUT](ui/LOADING_INPUT.md): Input that is loading.
20400
20531
  - [LOADING](ui/LOADING.md): Shared loading spinner element with a stable key, ready to drop into Suspense fallbacks and lists.
@@ -20916,7 +21047,7 @@ A boxed surface that groups a self-contained piece of content. Rendered as an `<
20916
21047
 
20917
21048
  ### Static card
20918
21049
 
20919
- ```tsx
21050
+ ```tsx live
20920
21051
  import { Card, Subheading, Paragraph } from "shelving/ui";
20921
21052
 
20922
21053
  <Card>
@@ -20927,7 +21058,7 @@ import { Card, Subheading, Paragraph } from "shelving/ui";
20927
21058
 
20928
21059
  ### Navigable card
20929
21060
 
20930
- ```tsx
21061
+ ```tsx live
20931
21062
  import { Card, Subheading, Paragraph } from "shelving/ui";
20932
21063
 
20933
21064
  // The entire card is a link; `title` labels the overlay for screen readers.
@@ -20939,7 +21070,7 @@ import { Card, Subheading, Paragraph } from "shelving/ui";
20939
21070
 
20940
21071
  ### Status and colour
20941
21072
 
20942
- ```tsx
21073
+ ```tsx live
20943
21074
  import { Card, Subheading } from "shelving/ui";
20944
21075
 
20945
21076
  <Card status="error"><Subheading>Couldn't load</Subheading></Card>
@@ -20948,7 +21079,7 @@ import { Card, Subheading } from "shelving/ui";
20948
21079
 
20949
21080
  ### Shadow
20950
21081
 
20951
- ```tsx
21082
+ ```tsx live
20952
21083
  import { Card, Subheading } from "shelving/ui";
20953
21084
 
20954
21085
  // Raise a card a little or a lot.
@@ -21179,7 +21310,7 @@ A collapsible panel. The title is always visible. The content shows when the use
21179
21310
 
21180
21311
  ### Single panel
21181
21312
 
21182
- ```tsx
21313
+ ```tsx live
21183
21314
  import { Details, Paragraph } from "shelving/ui";
21184
21315
 
21185
21316
  <Details title="What is shelving?">
@@ -21189,7 +21320,7 @@ import { Details, Paragraph } from "shelving/ui";
21189
21320
 
21190
21321
  ### Open by default
21191
21322
 
21192
- ```tsx
21323
+ ```tsx live
21193
21324
  import { Details, Paragraph } from "shelving/ui";
21194
21325
 
21195
21326
  <Details title="Release notes" open>
@@ -21199,7 +21330,7 @@ import { Details, Paragraph } from "shelving/ui";
21199
21330
 
21200
21331
  ### Exclusive group (FAQ)
21201
21332
 
21202
- ```tsx
21333
+ ```tsx live
21203
21334
  import { Details, Paragraph } from "shelving/ui";
21204
21335
 
21205
21336
  // Only one answer is open at a time.
@@ -21343,7 +21474,7 @@ A grid container that arranges its children in equal-width columns. Renders a `<
21343
21474
 
21344
21475
  ### Two columns of cards
21345
21476
 
21346
- ```tsx
21477
+ ```tsx live
21347
21478
  import { Card, Grid, Paragraph } from "shelving/ui";
21348
21479
 
21349
21480
  <Grid gap="small">
@@ -21447,7 +21578,7 @@ A section heading — renders an `<h2>`. It sits in the middle of the three-leve
21447
21578
 
21448
21579
  ### Section heading
21449
21580
 
21450
- ```tsx
21581
+ ```tsx live
21451
21582
  import { Heading, Paragraph } from "shelving/ui";
21452
21583
 
21453
21584
  <Heading>Billing</Heading>
@@ -21456,7 +21587,7 @@ import { Heading, Paragraph } from "shelving/ui";
21456
21587
 
21457
21588
  ### The heading family together
21458
21589
 
21459
- ```tsx
21590
+ ```tsx live
21460
21591
  import { Title, Heading, Subheading } from "shelving/ui";
21461
21592
 
21462
21593
  <Title>Account</Title> {/* <h1> */}
@@ -21466,7 +21597,7 @@ import { Title, Heading, Subheading } from "shelving/ui";
21466
21597
 
21467
21598
  ### Coloured heading
21468
21599
 
21469
- ```tsx
21600
+ ```tsx live
21470
21601
  import { Heading } from "shelving/ui";
21471
21602
 
21472
21603
  <Heading color="red">Danger zone</Heading>
@@ -21684,7 +21815,7 @@ A bulleted or numbered list. Renders a `<ul>` by default (or an `<ol>` when `ord
21684
21815
 
21685
21816
  ### Unordered and ordered lists
21686
21817
 
21687
- ```tsx
21818
+ ```tsx live
21688
21819
  import { List } from "shelving/ui";
21689
21820
 
21690
21821
  <List>{["Apples", "Oranges", "Pears"]}</List>
@@ -21786,7 +21917,7 @@ A full-width vertical region that paints the current surface colour. Use panels
21786
21917
 
21787
21918
  ### Page banded into panels
21788
21919
 
21789
- ```tsx
21920
+ ```tsx live
21790
21921
  import { Panel, Block, Title, Paragraph } from "shelving/ui";
21791
21922
 
21792
21923
  <Panel as="header" color="primary">
@@ -21876,7 +22007,7 @@ A block of body text — renders a `<p>`. The default container for running pros
21876
22007
 
21877
22008
  ### Body text
21878
22009
 
21879
- ```tsx
22010
+ ```tsx live
21880
22011
  import { Paragraph } from "shelving/ui";
21881
22012
 
21882
22013
  <Paragraph>The best widget on the market.</Paragraph>
@@ -21884,7 +22015,7 @@ import { Paragraph } from "shelving/ui";
21884
22015
 
21885
22016
  ### With inline annotations
21886
22017
 
21887
- ```tsx
22018
+ ```tsx live
21888
22019
  import { Paragraph, Strong, Link } from "shelving/ui";
21889
22020
 
21890
22021
  <Paragraph>
@@ -22033,7 +22164,7 @@ import { Prose, Markup } from "shelving/ui";
22033
22164
 
22034
22165
  ### Hand-written longform
22035
22166
 
22036
- ```tsx
22167
+ ```tsx live
22037
22168
  import { Prose, Paragraph } from "shelving/ui";
22038
22169
 
22039
22170
  <Prose>
@@ -22174,7 +22305,7 @@ A landmark content region — renders a `<section>` with block-level spacing and
22174
22305
 
22175
22306
  ### Structured page section
22176
22307
 
22177
- ```tsx
22308
+ ```tsx live
22178
22309
  import { Section, Heading, Definitions } from "shelving/ui";
22179
22310
 
22180
22311
  <Section width="narrow">
@@ -22391,7 +22522,7 @@ A subsection heading — renders an `<h3>`. It is the smallest member of the thr
22391
22522
 
22392
22523
  ### Card title
22393
22524
 
22394
- ```tsx
22525
+ ```tsx live
22395
22526
  import { Card, Subheading, Paragraph } from "shelving/ui";
22396
22527
 
22397
22528
  <Card>
@@ -22402,7 +22533,7 @@ import { Card, Subheading, Paragraph } from "shelving/ui";
22402
22533
 
22403
22534
  ### The heading family together
22404
22535
 
22405
- ```tsx
22536
+ ```tsx live
22406
22537
  import { Title, Heading, Subheading } from "shelving/ui";
22407
22538
 
22408
22539
  <Title>Account</Title> {/* <h1> */}
@@ -22489,7 +22620,7 @@ The top-level page heading — renders an `<h1>`. It is the most prominent membe
22489
22620
 
22490
22621
  ### Page title
22491
22622
 
22492
- ```tsx
22623
+ ```tsx live
22493
22624
  import { Title, Paragraph } from "shelving/ui";
22494
22625
 
22495
22626
  <Title>Account</Title>
@@ -22498,7 +22629,7 @@ import { Title, Paragraph } from "shelving/ui";
22498
22629
 
22499
22630
  ### Inside a panel header
22500
22631
 
22501
- ```tsx
22632
+ ```tsx live
22502
22633
  import { Panel, Block, Title } from "shelving/ui";
22503
22634
 
22504
22635
  <Panel as="header" color="primary">
@@ -22774,7 +22905,7 @@ import { Button } from "shelving/ui";
22774
22905
 
22775
22906
  ### Reusing the button class
22776
22907
 
22777
- ```tsx
22908
+ ```tsx live
22778
22909
  import { getButtonClass } from "shelving/ui";
22779
22910
 
22780
22911
  // Style an arbitrary element as a button.
@@ -23359,7 +23490,7 @@ Props for `<Dialog>` — optional `children` content and an `onClose` callback.
23359
23490
 
23360
23491
  | Property | Type | Description |
23361
23492
  | --- | --- | --- |
23362
- | `onClose` | `Callback` | Called when the user closes the dialog. It must unmount the `<Dialog>`, and it runs inside `startTransition()` so the dialog animates out. Optional. |
23493
+ | `onClose` | `Callback` | Called when the user asks to close the dialog. It must unmount the `<Dialog>`. Unmount it inside `startTransition()` to animate it out (`<Dialogs>` does this for you). Optional. |
23363
23494
 
23364
23495
 
23365
23496
  ---
@@ -23373,9 +23504,9 @@ Modal `<dialog>` element that opens on mount and includes a close button.
23373
23504
 
23374
23505
  - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
23375
23506
  - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
23376
- - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
23507
+ - It knows nothing about transitions. It fades in and out only when the update that mounts or unmounts it is a transition, e.g. from `<Dialogs>` or your own `startTransition()`. A `<Modal>` pinned to an edge then slides in its own layer.
23377
23508
  - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
23378
- - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
23509
+ - With `onClose`, it is declarative: a close request calls `onClose()`, and the dialog stays open until it unmounts, so a view transition can capture it as it leaves.
23379
23510
  - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
23380
23511
  - Wraps content in `<Suspense>` so lazy children can stream in.
23381
23512
 
@@ -23389,10 +23520,13 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
23389
23520
  - Children sit in one wrapper in normal block layout, so several children stack as they would on the page. The wrapper is `--dialog-width` wide (never wider than the screen) and centred on the screen. A centred `<Modal>` fills it. Content taller than the screen starts at the top, and the dialog scrolls.
23390
23521
  - While a dialog is open, the page behind it does not scroll. A scroll inside the dialog never passes on to the page.
23391
23522
  - `Dialog` only dims the page. Its text is white (`--tint-100`) so it reads on the dark overlay. Wrap the content in `<Modal>` to give it a panel with dark text on a light surface.
23392
- - `onClose` fires when the user closes the dialog. It must unmount the `Dialog`: clear the React state that mounts it, or (when pushed via a store) remove it from the list. `Dialog` calls `onClose` inside `startTransition()`, and the dialog stays open until it unmounts.
23393
- - The dialog animates with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
23523
+ - `Dialog` is declarative. While it is mounted, it is open. When the user asks to close it, it calls `onClose` and stays open until it unmounts. `onClose` must unmount it: clear the React state that mounts it, or (when pushed via a store) remove it from the list.
23524
+ - To close a dialog from your own code, call `requestDialogClose()` on the `<dialog>` element, not `dialog.close()`. `requestDialogClose()` goes through `onClose` like the Escape key, so the dialog can animate out. `dialog.close()` closes it at once. A successful `<Form>` submit inside a dialog uses `requestDialogClose()`.
23525
+ - The dialog can animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
23394
23526
  - 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.
23395
- - A view transition only runs for a React transition update. `DialogsStore` and `onClose` do this for you. To animate a declarative `Dialog` as it opens, set the state that mounts it inside `startTransition()`.
23527
+ - `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:
23528
+ - `<Dialogs>` renders a `DialogsStore` inside transitions, so a dialog opened with `DialogsStore.show()` animates in and out for you.
23529
+ - 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.
23396
23530
  - A browser without view transitions shows and hides the dialog at once.
23397
23531
  - Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
23398
23532
 
@@ -23416,9 +23550,9 @@ function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose:
23416
23550
  );
23417
23551
  }
23418
23552
 
23419
- // In the parent. Open inside `startTransition()` so the dialog animates in.
23553
+ // In the parent. Open and close inside `startTransition()` so the dialog animates in and out.
23420
23554
  <button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>Delete</button>
23421
- {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => setShowConfirm(false)} />}
23555
+ {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => startTransition(() => setShowConfirm(false))} />}
23422
23556
  ```
23423
23557
 
23424
23558
  ### Imperative
@@ -23441,7 +23575,7 @@ function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
23441
23575
  }
23442
23576
  ```
23443
23577
 
23444
- `dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel.
23578
+ `dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel. `<Dialogs>` renders the list inside transitions, so the dialog animates in and out with no `startTransition()` of your own.
23445
23579
 
23446
23580
  ## Styling
23447
23581
 
@@ -23462,6 +23596,38 @@ The fade uses the `fade` class from `<FadeTransition>`, so `--fade-transition-du
23462
23596
 
23463
23597
 
23464
23598
 
23599
+ ---
23600
+
23601
+ # requestDialogClose()
23602
+
23603
+ - Kind: function
23604
+ - Import: `import { requestDialogClose } from "shelving/ui";`
23605
+
23606
+ Ask a `<dialog>` element to close, the same way as the Escape key.
23607
+ - Fires a cancelable `cancel` event, so a `<Dialog>` keeps itself open and calls its `onClose`. Its parent then unmounts it, and it can animate out.
23608
+ - Closes the dialog at once only if nothing cancels the event.
23609
+ - Use it instead of `dialog.close()`, which closes at once and fires no `cancel` event, so the dialog vanishes with no transition.
23610
+ - Not `requestClose()`: some browsers lack it, and Safari fires its `cancel` event as not cancelable. Both close the dialog at once.
23611
+
23612
+ ## Signatures
23613
+
23614
+ ```ts
23615
+ requestDialogClose(dialog: HTMLDialogElement): void
23616
+ ```
23617
+
23618
+ ## Parameters
23619
+
23620
+ | Param | Type | Description |
23621
+ | --- | --- | --- |
23622
+ | `dialog` | `HTMLDialogElement` | The `<dialog>` element to close. |
23623
+
23624
+ ## Examples
23625
+
23626
+ ```ts
23627
+ requestDialogClose(dialog) // Like pressing Escape.
23628
+ ```
23629
+
23630
+
23465
23631
  ---
23466
23632
 
23467
23633
  # DialogCloseButtonProps
@@ -23744,7 +23910,7 @@ The panel inside a `<Dialog>`. `<Dialog>` dims the page; `Modal` gives the conte
23744
23910
  - The `radius` variant sets the corner radius. On a pinned panel, corners that touch a screen edge stay square.
23745
23911
  - It has a `--shadow-large` drop shadow by default. Set `shadow="none"`, `shadow="small"` or `shadow="normal"` to change it, the same as on `<Card>`.
23746
23912
  - Set `top`, `right`, `bottom`, or `left` to pin the panel to that edge of the screen. A top or bottom panel is full width up to `--modal-width`, and centred on a wider screen. A left or right panel is full height. Use these for mobile menus, bottom sheets, and side menus.
23747
- - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place.
23913
+ - A centred panel fades in and out with its `<Dialog>`. A pinned panel slides in from its edge and out to it, in its own view-transition layer. With reduced motion, a pinned panel fades in place. `Modal` has no transition of its own: it animates only when its `<Dialog>` does (see `Dialog`).
23748
23914
 
23749
23915
  ## Usage
23750
23916
 
@@ -23867,13 +24033,14 @@ Modal({ children, className, ...props }: ModalProps): ReactElement
23867
24033
 
23868
24034
  ---
23869
24035
 
23870
- # DocumentationApp()
24036
+ # DocumentationApp
23871
24037
 
23872
- - Kind: function
24038
+ - Kind: component
23873
24039
  - Import: `import { DocumentationApp } from "shelving/ui";`
23874
24040
 
23875
24041
  Documentation app.
23876
- - Build upon `<TreeApp>` to include a `<DocumentationSearchPage>` at its `/search` URL.
24042
+ - Works like `<TreeApp>`, and adds a `<DocumentationSearchPage>` at its `/search` URL.
24043
+ - Adds a `<DocumentationPlaygroundPage>` at its `/playground` URL. The playground fills the whole window, so it renders outside the `<SidebarLayout>`.
23877
24044
 
23878
24045
  ## Signatures
23879
24046
 
@@ -23887,8 +24054,7 @@ DocumentationApp({
23887
24054
  <TreeSidebar>
23888
24055
  <Menu small>
23889
24056
  <MenuItem href="/search">Search</MenuItem>
23890
- </Menu>
23891
- </TreeSidebar>): void
24057
+ <MenuItem href={`/${PLAYGROUND_PAGE_PATH}`}): void
23892
24058
  ```
23893
24059
 
23894
24060
  ## Parameters
@@ -24150,6 +24316,92 @@ DocumentationDescription({ description, default: def, optional, readonly }: Docu
24150
24316
  ```
24151
24317
 
24152
24318
 
24319
+ ---
24320
+
24321
+ # DocumentationFrameProps
24322
+
24323
+ - Kind: interface
24324
+ - Import: `import { DocumentationFrameProps } from "shelving/ui";`
24325
+ - Extends: `PlaygroundCode`
24326
+
24327
+ Props for `<DocumentationFrame>` — the code and CSS to run, plus a title for the frame.
24328
+
24329
+ ## Signatures
24330
+
24331
+ ```ts
24332
+ {
24333
+ title?: string | undefined;
24334
+ }
24335
+ ```
24336
+
24337
+ ## Properties
24338
+
24339
+ | Property | Type | Description |
24340
+ | --- | --- | --- |
24341
+ | `title` | `string \| undefined` | Accessible title of the frame. Defaults to `"Preview"`. |
24342
+
24343
+
24344
+ ---
24345
+
24346
+ # DocumentationFrame
24347
+
24348
+ - Kind: component
24349
+ - Import: `import { DocumentationFrame } from "shelving/ui";`
24350
+
24351
+ Show a live preview of playground code in an `<iframe>` of the playground frame page.
24352
+ - The frame page loads only the shelving styles, so the preview looks the same as in a real app, and the docs site styles do not leak in.
24353
+ - The code and CSS go in the frame URL hash, so a change runs again without a reload.
24354
+ - The frame grows to fit its content: the frame page posts its height to this component.
24355
+ - The frame loads lazily, when it scrolls near the screen.
24356
+
24357
+ Show a live preview of TSX and CSS in an `<iframe>` of the playground frame page. `<DocumentationLive>` and `<DocumentationPlaygroundPage>` use it.
24358
+
24359
+ **Things to know:**
24360
+
24361
+ - The docs build writes the frame page to `frame.html` (`PLAYGROUND_FRAME_PATH`) at the site root. It loads the shelving styles only, so the preview looks as it does in a real app.
24362
+ - The code and CSS go in the frame URL hash (see `formatPlaygroundHash()`). A new hash runs the code again without a reload.
24363
+ - The frame page loads the TypeScript compiler from esm.sh to transpile the code, and imports it as a module. Its import map resolves `shelving/*` to the shelving build of the same docs site, and `react` and `react-dom` to esm.sh. Any other import fails.
24364
+ - The frame grows to fit its content. The frame page posts its height as a `PLAYGROUND_HEIGHT_MESSAGE` message.
24365
+ - The frame loads lazily, when it scrolls near the screen.
24366
+
24367
+ ## Usage
24368
+
24369
+ ```tsx
24370
+ import { DocumentationFrame } from "shelving/ui";
24371
+
24372
+ <DocumentationFrame code={`import { Button } from "shelving/ui";\n<Button>Hi</Button>`} css=":root { --radius-normal: 4px; }" />
24373
+ ```
24374
+
24375
+ ## Styling
24376
+
24377
+ 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.
24378
+
24379
+ | Variable | Styles | Default |
24380
+ |---|---|---|
24381
+ | `--documentation-frame-background` | Fill behind the frame before it loads | `white` |
24382
+ | `--documentation-frame-height` | Minimum height (one length) | `4rem` |
24383
+
24384
+
24385
+ ## Signatures
24386
+
24387
+ ```ts
24388
+ DocumentationFrame({ code, css, title = "Preview", className }: DocumentationFrameProps): ReactElement
24389
+ ```
24390
+
24391
+ ## Parameters
24392
+
24393
+ | Param | Type | Description |
24394
+ | --- | --- | --- |
24395
+ | `props` | `DocumentationFrameProps` | |
24396
+ | `.title` | `string \| undefined` | Accessible title of the frame. Defaults to `"Preview"`. |
24397
+
24398
+ ## Returns
24399
+
24400
+ | Type | Description |
24401
+ | --- | --- |
24402
+ | `ReactElement` | |
24403
+
24404
+
24153
24405
  ---
24154
24406
 
24155
24407
  # DocumentationKindProps
@@ -24248,86 +24500,238 @@ DocumentationKind({ kind = "unknown", ...props }: DocumentationKindProps): React
24248
24500
 
24249
24501
  ---
24250
24502
 
24251
- # DocumentationPage
24503
+ # DocumentationLiveProps
24504
+
24505
+ - Kind: interface
24506
+ - Import: `import { DocumentationLiveProps } from "shelving/ui";`
24507
+
24508
+ Props for `<DocumentationLive>` — the code to show and run, plus an optional title.
24509
+
24510
+ ## Signatures
24511
+
24512
+ ```ts
24513
+ {
24514
+ code: string;
24515
+ title?: string | undefined;
24516
+ }
24517
+ ```
24518
+
24519
+ ## Properties
24520
+
24521
+ | Property | Type | Description |
24522
+ | --- | --- | --- |
24523
+ | `code` | `string` | TSX source to show and run. It can import from `shelving/*`, `react`, and `react-dom` only. |
24524
+ | `title` | `string \| undefined` | Title of the example, used as the accessible title of the preview frame. Optional. |
24525
+
24526
+
24527
+ ---
24528
+
24529
+ # DocumentationLive
24252
24530
 
24253
24531
  - Kind: component
24254
- - Import: `import { DocumentationPage } from "shelving/ui";`
24532
+ - Import: `import { DocumentationLive } from "shelving/ui";`
24255
24533
 
24256
- Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
24257
- - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, properties, referenced types, and examples.
24258
- - In the Parameters / Returns / Throws / Properties tables the `Type` column links each type to its documented page via `TreeLink` (exact-match only; compound or builtin types stay plain text), and a row with no hand-written description falls back to the referenced type's own `description`. A default renders as a `Defaults to …` note (linking the value when it's a documented token) rather than in a dedicated column.
24259
- - A class/interface/object-literal type's data members render as the Properties table (see `DocumentationProperties`); an options-bag parameter whose type resolves to one is flattened into indented child rows from the same structured list.
24260
- - A `type` alias's referenced type names render as a linked `Type` table, each row carrying the resolved element's `description` (exact-match only).
24261
- - Child symbols (functions, classes, methods — not data members) are grouped by `kind` into card sections, each under its own heading.
24262
- - All sections are conditional — only render when they have entries.
24534
+ Show a code example next to a live preview of it on a simple phone, with a link under it that opens it in the playground.
24535
+ - The preview is a `<DocumentationFrame>`, so it runs in the browser with the raw shelving styles.
24536
+ - The phone is light grey, so it suggests a device without competing with the preview. Its screen is square and has a fixed height, and it scrolls when the preview is taller.
24537
+ - The code and preview are side by side on a wide screen, and stacked on a narrow one.
24263
24538
 
24264
- The full detail page for a documented symbol — the default renderer for `tree-documentation` elements dispatched by `<TreeApp>`. It is the most detailed page renderer in the tree shell; render it directly only when you need a symbol page outside the tree, or replace it for one element type via `TreePageMapping`.
24539
+ Show a code example next to a live preview of it, on a simple phone. The docs site uses it for each fenced code block with a `live` flag.
24265
24540
 
24266
24541
  **Things to know:**
24267
24542
 
24268
- - Above the title it renders an ancestor trail via `<TreeBreadcrumbs>`, so it needs a `<TreeProvider>` above it to resolve the ancestors.
24269
- - The title carries a `<DocumentationKind>` tag, and below it `<DocumentationButtons>` lists the symbol's relations (`member of`, `extends`, `implements`) as links.
24270
- - It renders the signature(s) via `<DocumentationSignatures>` (one block per overload, each carrying the symbol's name), then prose content, then conditional `Parameters` / `Returns` / `Throws` / `Examples` sections — each only appears when it has entries. Parameters render as a `<Table>` (`Param` / `Type` / `Default` / `Description` columns, a `-` standing in where a parameter has no default); Returns and Throws render as two-column tables (`Return` / `Throws` plus `Description`), with the type in the first column.
24271
- - Child symbols follow, grouped by `kind` into card sections (`Modules`, `Components`, `Functions`, `Classes`, `Interfaces`, `Types`, `Constants`, `Static methods`, `Methods`) rendered as `<DocumentationCard>`s inside a `<TreeCards>` listing. Data members (properties) are not child elements — they render as the Properties table instead. A new documented kind needs an entry in `KINDS` here (and a colour in `<DocumentationKind>`).
24543
+ - Add `live` after the language of a fenced code block to make it run: ` ```tsx live `. Put a title in double quotes after it: ` ```tsx live "Card with a link" `. See `parseFencedInfo()` for the full info string format.
24544
+ - `DOCUMENTATION_LIVE_RULE` finds these blocks. `DOCUMENTATION_MARKUP_RULES` adds it to `TREE_MARKUP_RULES`, and `<DocumentationPage>` renders its content with them.
24545
+ - The preview is a `<DocumentationFrame>`. It runs in the browser, with the raw shelving styles and none of the docs site styles.
24546
+ - The code can import from `shelving/*`, `react`, and `react-dom` only. Any other import fails.
24547
+ - Each top-level expression in the code shows in the preview, so a snippet needs no `return` or export. A default export that is a component or an element shows too.
24548
+ - The phone is light grey, not the tint colour, so it suggests a device without competing with the preview. Its screen is square, with a fixed height, and scrolls when the preview is taller.
24549
+ - "Open in playground" under the phone opens the code in `<DocumentationPlaygroundPage>`, where you can change it.
24272
24550
 
24273
24551
  ## Usage
24274
24552
 
24275
- Used automatically by `<TreeApp>`. To render a single page manually, spread the element's flattened props.
24553
+ ### A live example in a Markdown page
24276
24554
 
24277
- ```tsx
24278
- import { DocumentationPage } from "shelving/ui";
24555
+ ````md
24556
+ ```tsx live "A solid button"
24557
+ import { Button } from "shelving/ui";
24279
24558
 
24280
- // `element` is a `tree-documentation` element from DirectoryExtractor (see /extract).
24281
- <DocumentationPage {...element.props} />
24559
+ <Button solid>Save</Button>
24282
24560
  ```
24561
+ ````
24283
24562
 
24284
- To replace this renderer across the whole site, wrap the app in `TreePageMapping`.
24563
+ ### A live example with state
24285
24564
 
24286
- ```tsx
24287
- import { TreeApp, TreePageMapping } from "shelving/ui";
24565
+ ````md
24566
+ ```tsx live
24567
+ import { useState } from "react";
24568
+ import { Button } from "shelving/ui";
24288
24569
 
24289
- <TreePageMapping mapping={{ "tree-documentation": MyDocumentationPage }}>
24290
- <TreeApp tree={tree} />
24291
- </TreePageMapping>
24570
+ function Counter() {
24571
+ const [count, setCount] = useState(0);
24572
+ return <Button onClick={() => setCount(count + 1)}>Clicked {count} times</Button>;
24573
+ }
24574
+
24575
+ <Counter />
24292
24576
  ```
24577
+ ````
24293
24578
 
24294
24579
  ## Styling
24295
24580
 
24296
- `DocumentationPage` has no own CSS hooks — it composes `<Page>`, `<Panel>`, `<Section>`, and the other block components, which carry their own themeable surfaces. Retheme through those.
24581
+ | Variable | Styles | Default |
24582
+ |---|---|---|
24583
+ | `--documentation-live-bezel` | Space above and below the speaker slot, which sets the thickness of the top and the chin (one length) | `2.25rem` |
24584
+ | `--documentation-live-body` | Fill of the phone | `oklch(92% 0 0deg)` (light grey) |
24585
+ | `--documentation-live-detail` | Colour of the speaker slot and home button | `oklch(80% 0 0deg)` |
24586
+ | `--documentation-live-edge` | Width of the phone edge left and right of the screen (one length) | `0.75rem` |
24587
+ | `--documentation-live-gap` | Space between the code and the phone (one length) | `var(--space-normal)` (16px) |
24588
+ | `--documentation-live-height` | Height of the screen (one length) | `26rem` |
24589
+ | `--documentation-live-radius` | Corner radius of the phone | `2.5rem` |
24590
+ | `--documentation-live-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
24591
+ | `--documentation-live-width` | Width of the phone (one length) | `22rem` |
24592
+
24593
+ Global tokens: `--space-normal`, `--space-xsmall`, `--space-paragraph`, `--font-label`, `--size-small`. The code block is a raw `<pre>` with `--preformatted-space` set to `0`, so it takes the other `.prose pre` styles of `<Preformatted>`. The code and phone are side by side when the screen is 75rem or wider.
24297
24594
 
24298
24595
 
24299
24596
  ## Signatures
24300
24597
 
24301
24598
  ```ts
24302
- DocumentationPage({
24303
- title,
24304
- name,
24305
- kind = "unknown",
24306
- description,
24307
- content,
24308
- signatures,
24309
- params,
24310
- returns,
24311
- throws,
24312
- properties,
24313
- types,
24314
- examples,
24315
- children,
24316
- ...props
24317
- }: DocumentationElementProps): ReactNode
24599
+ DocumentationLive({ code, title }: DocumentationLiveProps): ReactElement
24318
24600
  ```
24319
24601
 
24320
24602
  ## Parameters
24321
24603
 
24322
24604
  | Param | Type | Description |
24323
24605
  | --- | --- | --- |
24324
- | `props` | `DocumentationElementProps` | |
24325
- | `.kind` | `string \| undefined` | Read only. Optional. |
24326
- | `.signatures` | `ImmutableArray<string> \| undefined` | Read only. Optional. |
24327
- | `.params` | `ImmutableArray<DocumentationParam> \| undefined` | Read only. Optional. |
24328
- | `.returns` | `ImmutableArray<DocumentationReturn> \| undefined` | Read only. Optional. |
24329
- | `.throws` | `ImmutableArray<DocumentationThrow> \| undefined` | Read only. Optional. |
24330
- | `.examples` | `ImmutableArray<DocumentationExample> \| undefined` | Read only. Optional. |
24606
+ | `props` | `DocumentationLiveProps` | |
24607
+ | `.code` | `string` | TSX source to show and run. It can import from `shelving/*`, `react`, and `react-dom` only. |
24608
+ | `.title` | `string \| undefined` | Title of the example, used as the accessible title of the preview frame. Optional. |
24609
+
24610
+ ## Returns
24611
+
24612
+ | Type | Description |
24613
+ | --- | --- |
24614
+ | `ReactElement` | |
24615
+
24616
+
24617
+ ---
24618
+
24619
+ # DOCUMENTATION_LIVE_RULE
24620
+
24621
+ - Kind: constant
24622
+ - Import: `import { DOCUMENTATION_LIVE_RULE } from "shelving/ui";`
24623
+
24624
+ Markup rule that renders a fenced code block with a `live` flag as a `<DocumentationLive>` example, e.g. ` ```tsx live "Card with a link" `.
24625
+ - The `live` flag must come before any quoted title (see `parseFencedInfo()` for the info string format).
24626
+ - Has the same priority as `FENCED_RULE`, so a `live` block inside a longer fence stays code. List it before `FENCED_RULE`, so it takes the `live` blocks and leaves every other block to `FENCED_RULE`.
24627
+
24628
+ @see https://shelving.cc/ui/DOCUMENTATION_LIVE_RULE
24629
+
24630
+ ## Signatures
24631
+
24632
+ ```ts
24633
+ DOCUMENTATION_LIVE_RULE: MarkupRule
24634
+ ```
24635
+
24636
+
24637
+ ---
24638
+
24639
+ # DOCUMENTATION_MARKUP_RULES
24640
+
24641
+ - Kind: constant
24642
+ - Import: `import { DOCUMENTATION_MARKUP_RULES } from "shelving/ui";`
24643
+
24644
+ Markup rules for docs site content: `DOCUMENTATION_LIVE_RULE` then `TREE_MARKUP_RULES`, so fenced code blocks with a `live` flag run.
24645
+
24646
+ ## Signatures
24647
+
24648
+ ```ts
24649
+ DOCUMENTATION_MARKUP_RULES: MarkupRules
24650
+ ```
24651
+
24652
+
24653
+ ---
24654
+
24655
+ # DocumentationPage
24656
+
24657
+ - Kind: component
24658
+ - Import: `import { DocumentationPage } from "shelving/ui";`
24659
+
24660
+ Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
24661
+ - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, properties, referenced types, and examples.
24662
+ - In the Parameters / Returns / Throws / Properties tables the `Type` column links each type to its documented page via `TreeLink` (exact-match only; compound or builtin types stay plain text), and a row with no hand-written description falls back to the referenced type's own `description`. A default renders as a `Defaults to …` note (linking the value when it's a documented token) rather than in a dedicated column.
24663
+ - A class/interface/object-literal type's data members render as the Properties table (see `DocumentationProperties`); an options-bag parameter whose type resolves to one is flattened into indented child rows from the same structured list.
24664
+ - A `type` alias's referenced type names render as a linked `Type` table, each row carrying the resolved element's `description` (exact-match only).
24665
+ - Child symbols (functions, classes, methods — not data members) are grouped by `kind` into card sections, each under its own heading.
24666
+ - All sections are conditional — only render when they have entries.
24667
+
24668
+ The full detail page for a documented symbol — the default renderer for `tree-documentation` elements dispatched by `<TreeApp>`. It is the most detailed page renderer in the tree shell; render it directly only when you need a symbol page outside the tree, or replace it for one element type via `TreePageMapping`.
24669
+
24670
+ **Things to know:**
24671
+
24672
+ - Above the title it renders an ancestor trail via `<TreeBreadcrumbs>`, so it needs a `<TreeProvider>` above it to resolve the ancestors.
24673
+ - The title carries a `<DocumentationKind>` tag, and below it `<DocumentationButtons>` lists the symbol's relations (`member of`, `extends`, `implements`) as links.
24674
+ - It renders the signature(s) via `<DocumentationSignatures>` (one block per overload, each carrying the symbol's name), then prose content, then conditional `Parameters` / `Returns` / `Throws` / `Examples` sections — each only appears when it has entries. Parameters render as a `<Table>` (`Param` / `Type` / `Default` / `Description` columns, a `-` standing in where a parameter has no default); Returns and Throws render as two-column tables (`Return` / `Throws` plus `Description`), with the type in the first column.
24675
+ - Child symbols follow, grouped by `kind` into card sections (`Modules`, `Components`, `Functions`, `Classes`, `Interfaces`, `Types`, `Constants`, `Static methods`, `Methods`) rendered as `<DocumentationCard>`s inside a `<TreeCards>` listing. Data members (properties) are not child elements — they render as the Properties table instead. A new documented kind needs an entry in `KINDS` here (and a colour in `<DocumentationKind>`).
24676
+
24677
+ ## Usage
24678
+
24679
+ Used automatically by `<TreeApp>`. To render a single page manually, spread the element's flattened props.
24680
+
24681
+ ```tsx
24682
+ import { DocumentationPage } from "shelving/ui";
24683
+
24684
+ // `element` is a `tree-documentation` element from DirectoryExtractor (see /extract).
24685
+ <DocumentationPage {...element.props} />
24686
+ ```
24687
+
24688
+ To replace this renderer across the whole site, wrap the app in `TreePageMapping`.
24689
+
24690
+ ```tsx
24691
+ import { TreeApp, TreePageMapping } from "shelving/ui";
24692
+
24693
+ <TreePageMapping mapping={{ "tree-documentation": MyDocumentationPage }}>
24694
+ <TreeApp tree={tree} />
24695
+ </TreePageMapping>
24696
+ ```
24697
+
24698
+ ## Styling
24699
+
24700
+ `DocumentationPage` has no own CSS hooks — it composes `<Page>`, `<Panel>`, `<Section>`, and the other block components, which carry their own themeable surfaces. Retheme through those.
24701
+
24702
+
24703
+ ## Signatures
24704
+
24705
+ ```ts
24706
+ DocumentationPage({
24707
+ title,
24708
+ name,
24709
+ kind = "unknown",
24710
+ description,
24711
+ content,
24712
+ signatures,
24713
+ params,
24714
+ returns,
24715
+ throws,
24716
+ properties,
24717
+ types,
24718
+ examples,
24719
+ children,
24720
+ ...props
24721
+ }: DocumentationElementProps): ReactNode
24722
+ ```
24723
+
24724
+ ## Parameters
24725
+
24726
+ | Param | Type | Description |
24727
+ | --- | --- | --- |
24728
+ | `props` | `DocumentationElementProps` | |
24729
+ | `.kind` | `string \| undefined` | Read only. Optional. |
24730
+ | `.signatures` | `ImmutableArray<string> \| undefined` | Read only. Optional. |
24731
+ | `.params` | `ImmutableArray<DocumentationParam> \| undefined` | Read only. Optional. |
24732
+ | `.returns` | `ImmutableArray<DocumentationReturn> \| undefined` | Read only. Optional. |
24733
+ | `.throws` | `ImmutableArray<DocumentationThrow> \| undefined` | Read only. Optional. |
24734
+ | `.examples` | `ImmutableArray<DocumentationExample> \| undefined` | Read only. Optional. |
24331
24735
  | `.class` | `string \| undefined` | Name of the class/interface this member belongs to (e.g. `"Store"` for `Store.get()`). Set only on methods and properties. Read only. Optional. |
24332
24736
  | `.readonly` | `boolean \| undefined` | Whether the property is read-only — a `readonly` field, or a getter with no matching setter. Read only. Optional. |
24333
24737
  | `.extends` | `string \| undefined` | Full type text of the class/interface this extends, including any generic arguments (e.g. `"AbstractStore<string>"`, `"Omit<StringSchemaOptions, 'value'>"`). Resolved to a link at render time, trimming generics to the bare name; builtins/wrappers that don't resolve stay as text. Read only. Optional. |
@@ -24406,6 +24810,104 @@ DocumentationParams({ params }: DocumentationParamsProps): ReactNode
24406
24810
  ```
24407
24811
 
24408
24812
 
24813
+ ---
24814
+
24815
+ # DocumentationPlaygroundInsertProps
24816
+
24817
+ - Kind: interface
24818
+ - Import: `import { DocumentationPlaygroundInsertProps } from "shelving/ui";`
24819
+
24820
+ Props for `<DocumentationPlaygroundInsert>`.
24821
+
24822
+ ## Signatures
24823
+
24824
+ ```ts
24825
+ {
24826
+ readonly type: "code" | "css";
24827
+ readonly onInsert: (text: string) => void;
24828
+ readonly onClose: () => void;
24829
+ }
24830
+ ```
24831
+
24832
+ ## Properties
24833
+
24834
+ | Property | Type | Description |
24835
+ | --- | --- | --- |
24836
+ | `type` | `"code" \| "css"` | What to list: shelving components for the TSX, or CSS variables for the CSS. Read only. |
24837
+ | `onInsert` | `(text: string) => void` | Called with a `PlaygroundComponent.snippet` (for the TSX) or a CSS declaration or rule (for the CSS) when you press an item. Read only. |
24838
+ | `onClose` | `() => void` | Called when the panel closes. It must unmount the panel. Read only. |
24839
+
24840
+
24841
+ ---
24842
+
24843
+ # DocumentationPlaygroundInsert
24844
+
24845
+ - Kind: component
24846
+ - Import: `import { DocumentationPlaygroundInsert } from "shelving/ui";`
24847
+
24848
+ Panel that slides in from the right of the playground, to insert a shelving component into the TSX, or a CSS variable into the CSS.
24849
+ - Components come from `PLAYGROUND_COMPONENTS_PATH`, and variables from `PLAYGROUND_VARIABLES_PATH`. The docs build writes both.
24850
+ - Items are grouped by module, and you can search them by name or description. Hover an item to see its description.
24851
+ - Press an item to insert it and close the panel. A group of variables also has "Insert all", which inserts every variable in it.
24852
+
24853
+ ## Signatures
24854
+
24855
+ ```ts
24856
+ DocumentationPlaygroundInsert({ type, onInsert, onClose }: DocumentationPlaygroundInsertProps): ReactNode
24857
+ ```
24858
+
24859
+ ## Parameters
24860
+
24861
+ | Param | Type | Description |
24862
+ | --- | --- | --- |
24863
+ | `props` | `DocumentationPlaygroundInsertProps` | |
24864
+ | `.type` | `"code" \| "css"` | What to list: shelving components for the TSX, or CSS variables for the CSS. Read only. |
24865
+ | `.onInsert` | `(text: string) => void` | Called with a `PlaygroundComponent.snippet` (for the TSX) or a CSS declaration or rule (for the CSS) when you press an item. Read only. |
24866
+ | `.onClose` | `() => void` | Called when the panel closes. It must unmount the panel. Read only. |
24867
+
24868
+ ## Returns
24869
+
24870
+ | Type | Description |
24871
+ | --- | --- |
24872
+ | `ReactNode` | |
24873
+
24874
+
24875
+ ---
24876
+
24877
+ # DocumentationPlaygroundPage
24878
+
24879
+ - Kind: component
24880
+ - Import: `import { DocumentationPlaygroundPage } from "shelving/ui";`
24881
+
24882
+ Page where you can write TSX and CSS and see the result run live, like the TypeScript Playground.
24883
+ - It fills the whole window: the editor is on the left, in a grey panel, and the preview fills the right.
24884
+ - Drag the edge between them (or focus it and press the arrow keys) to change their widths.
24885
+ - The TSX tab holds code that can import from `shelving/*`, `react`, and `react-dom`. Its top-level expressions are shown in the preview.
24886
+ - The CSS tab holds CSS that is added after the shelving styles, so you can change any shelving variable.
24887
+ - The + button opens a `<DocumentationPlaygroundInsert>` panel. On the TSX tab it lists the shelving components, and on the CSS tab the CSS variables. Press one to insert it at the cursor.
24888
+ - The code and CSS are saved in the URL hash on every change, so the address is always a link to what you made.
24889
+ - The preview is a `<DocumentationFrame>`, so it uses the raw shelving styles and not the docs site styles.
24890
+ - It has no sidebar of its own. `<DocumentationApp>` renders it outside its `<SidebarLayout>`.
24891
+
24892
+ ## Signatures
24893
+
24894
+ ```ts
24895
+ DocumentationPlaygroundPage(): ReactNode
24896
+ ```
24897
+
24898
+ ## Returns
24899
+
24900
+ | Type | Description |
24901
+ | --- | --- |
24902
+ | `ReactNode` | |
24903
+
24904
+ ## Examples
24905
+
24906
+ ```ts
24907
+ <Router routes={{ "/playground": DocumentationPlaygroundPage }} />
24908
+ ```
24909
+
24910
+
24409
24911
  ---
24410
24912
 
24411
24913
  # DocumentationPropertiesProps
@@ -24840,6 +25342,353 @@ DocumentationType({ members }: DocumentationTypeProps): ReactNode
24840
25342
  ```
24841
25343
 
24842
25344
 
25345
+ ---
25346
+
25347
+ # PlaygroundCode
25348
+
25349
+ - Kind: interface
25350
+ - Import: `import { PlaygroundCode } from "shelving/ui";`
25351
+
25352
+ Code and CSS that the playground frame runs.
25353
+
25354
+ ## Signatures
25355
+
25356
+ ```ts
25357
+ {
25358
+ readonly code?: string | undefined;
25359
+ readonly css?: string | undefined;
25360
+ }
25361
+ ```
25362
+
25363
+ ## Properties
25364
+
25365
+ | Property | Type | Description |
25366
+ | --- | --- | --- |
25367
+ | `code` | `string \| undefined` | TSX source to run. It can import from `shelving/*`, `react`, and `react-dom` only. Read only. Optional. |
25368
+ | `css` | `string \| undefined` | CSS to add after the shelving styles. Read only. Optional. |
25369
+
25370
+
25371
+ ---
25372
+
25373
+ # PLAYGROUND_FRAME_PATH
25374
+
25375
+ - Kind: constant
25376
+ - Import: `import { PLAYGROUND_FRAME_PATH } from "shelving/ui";`
25377
+
25378
+ Path of the frame page that runs playground code, relative to the docs site root.
25379
+
25380
+
25381
+ ---
25382
+
25383
+ # PLAYGROUND_PAGE_PATH
25384
+
25385
+ - Kind: constant
25386
+ - Import: `import { PLAYGROUND_PAGE_PATH } from "shelving/ui";`
25387
+
25388
+ Path of the playground page, relative to the docs site root.
25389
+
25390
+
25391
+ ---
25392
+
25393
+ # PLAYGROUND_HEIGHT_MESSAGE
25394
+
25395
+ - Kind: constant
25396
+ - Import: `import { PLAYGROUND_HEIGHT_MESSAGE } from "shelving/ui";`
25397
+
25398
+ Type of the message that the frame page posts to its parent with its content height, e.g. `{ type: PLAYGROUND_HEIGHT_MESSAGE, height: 320 }`.
25399
+
25400
+
25401
+ ---
25402
+
25403
+ # formatPlaygroundHash()
25404
+
25405
+ - Kind: function
25406
+ - Import: `import { formatPlaygroundHash } from "shelving/ui";`
25407
+
25408
+ Format code and CSS as a URL hash for the playground page or its frame, e.g. `#code=…&css=…`.
25409
+ - Each value is UTF-8 then Base64URL encoded, so the same input always gives the same hash (on the server and in the browser).
25410
+ - Empty values are left out, and an empty input gives `""`.
25411
+
25412
+ ## Signatures
25413
+
25414
+ ```ts
25415
+ formatPlaygroundHash({ code, css }: PlaygroundCode): string
25416
+ ```
25417
+
25418
+ ## Parameters
25419
+
25420
+ | Param | Type | Description |
25421
+ | --- | --- | --- |
25422
+ | `options` | `PlaygroundCode` | |
25423
+ | `.code` | `string \| undefined` | TSX source to run. It can import from `shelving/*`, `react`, and `react-dom` only. Read only. Optional. |
25424
+ | `.css` | `string \| undefined` | CSS to add after the shelving styles. Read only. Optional. |
25425
+
25426
+ ## Returns
25427
+
25428
+ | Type | Description |
25429
+ | --- | --- |
25430
+ | `string` | The hash, with its leading `#`, or `""` if there is nothing to put in it. |
25431
+
25432
+ ## Examples
25433
+
25434
+ ```ts
25435
+ formatPlaygroundHash({ code: "<Button>Hi</Button>" }) // "#code=PEJ1dHRvbj5IaTwvQnV0dG9uPg"
25436
+ ```
25437
+
25438
+
25439
+ ---
25440
+
25441
+ # parsePlaygroundHash()
25442
+
25443
+ - Kind: function
25444
+ - Import: `import { parsePlaygroundHash } from "shelving/ui";`
25445
+
25446
+ Parse a URL hash made by `formatPlaygroundHash()` back into code and CSS.
25447
+ - Values that are missing or not valid Base64URL are left out.
25448
+
25449
+ ## Signatures
25450
+
25451
+ ```ts
25452
+ parsePlaygroundHash(hash: string): PlaygroundCode
25453
+ ```
25454
+
25455
+ ## Parameters
25456
+
25457
+ | Param | Type | Description |
25458
+ | --- | --- | --- |
25459
+ | `hash` | `string` | The hash to parse, with or without its leading `#`. |
25460
+
25461
+ ## Returns
25462
+
25463
+ | Type | Description |
25464
+ | --- | --- |
25465
+ | `PlaygroundCode` | The code and CSS in the hash. |
25466
+
25467
+ ## Examples
25468
+
25469
+ ```ts
25470
+ parsePlaygroundHash("#code=PEJ1dHRvbj5IaTwvQnV0dG9uPg") // { code: "<Button>Hi</Button>" }
25471
+ ```
25472
+
25473
+
25474
+ ---
25475
+
25476
+ # PLAYGROUND_VARIABLES_PATH
25477
+
25478
+ - Kind: constant
25479
+ - Import: `import { PLAYGROUND_VARIABLES_PATH } from "shelving/ui";`
25480
+
25481
+ Path of the CSS variable index that the docs build writes, relative to the docs site root.
25482
+ - It holds a list of `PlaygroundVariableGroup` objects.
25483
+
25484
+
25485
+ ---
25486
+
25487
+ # PlaygroundVariable
25488
+
25489
+ - Kind: interface
25490
+ - Import: `import { PlaygroundVariable } from "shelving/ui";`
25491
+
25492
+ One CSS variable that you can set to change the look of shelving components.
25493
+
25494
+ ## Signatures
25495
+
25496
+ ```ts
25497
+ {
25498
+ readonly name: string;
25499
+ readonly value: string;
25500
+ readonly description?: string | undefined;
25501
+ }
25502
+ ```
25503
+
25504
+ ## Properties
25505
+
25506
+ | Property | Type | Description |
25507
+ | --- | --- | --- |
25508
+ | `name` | `string` | Name of the variable, e.g. `"--card-background"`. Read only. |
25509
+ | `value` | `string` | Default value of the variable, e.g. `"var(--tint-90)"`. Read only. |
25510
+ | `description` | `string \| undefined` | What the variable styles, e.g. `"Surface fill"`. Read only. Optional. |
25511
+
25512
+
25513
+ ---
25514
+
25515
+ # PlaygroundVariableGroup
25516
+
25517
+ - Kind: interface
25518
+ - Import: `import { PlaygroundVariableGroup } from "shelving/ui";`
25519
+
25520
+ A group of CSS variables that one CSS module owns, e.g. the `--card-*` variables of `Card.module.css`.
25521
+
25522
+ ## Signatures
25523
+
25524
+ ```ts
25525
+ {
25526
+ readonly name: string;
25527
+ readonly tokens?: boolean | undefined;
25528
+ readonly variables: readonly PlaygroundVariable[];
25529
+ }
25530
+ ```
25531
+
25532
+ ## Properties
25533
+
25534
+ | Property | Type | Description |
25535
+ | --- | --- | --- |
25536
+ | `name` | `string` | Name of the group, e.g. `"Card"`. Read only. |
25537
+ | `tokens` | `boolean \| undefined` | Whether the group holds global design tokens (from the `style/` modules), not hooks for one component. Read only. Optional. |
25538
+ | `variables` | `readonly PlaygroundVariable[]` | The variables in the group. Read only. |
25539
+
25540
+
25541
+ ---
25542
+
25543
+ # formatPlaygroundCSS()
25544
+
25545
+ - Kind: function
25546
+ - Import: `import { formatPlaygroundCSS } from "shelving/ui";`
25547
+
25548
+ Format CSS variables as a `:root` rule that you can paste into the playground CSS and change.
25549
+ - Each variable is set to its default value, with its description as a comment.
25550
+
25551
+ ## Signatures
25552
+
25553
+ ```ts
25554
+ formatPlaygroundCSS(variables: readonly PlaygroundVariable[]): string
25555
+ ```
25556
+
25557
+ ## Parameters
25558
+
25559
+ | Param | Type | Description |
25560
+ | --- | --- | --- |
25561
+ | `variables` | `readonly PlaygroundVariable[]` | The variables to put in the rule. |
25562
+
25563
+ ## Returns
25564
+
25565
+ | Type | Description |
25566
+ | --- | --- |
25567
+ | `string` | The CSS rule, or `""` if there are no variables. |
25568
+
25569
+ ## Examples
25570
+
25571
+ ```ts
25572
+ formatPlaygroundCSS([{ name: "--card-radius", value: "var(--radius-normal)" }]) // ":root {\n --card-radius: var(--radius-normal);\n}\n"
25573
+ ```
25574
+
25575
+
25576
+ ---
25577
+
25578
+ # PLAYGROUND_COMPONENTS_PATH
25579
+
25580
+ - Kind: constant
25581
+ - Import: `import { PLAYGROUND_COMPONENTS_PATH } from "shelving/ui";`
25582
+
25583
+ Path of the component index that the docs build writes, relative to the docs site root.
25584
+ - It holds a list of `PlaygroundComponent` objects.
25585
+
25586
+
25587
+ ---
25588
+
25589
+ # PlaygroundComponent
25590
+
25591
+ - Kind: interface
25592
+ - Import: `import { PlaygroundComponent } from "shelving/ui";`
25593
+
25594
+ One shelving component that you can insert into the playground code.
25595
+
25596
+ ## Signatures
25597
+
25598
+ ```ts
25599
+ {
25600
+ readonly name: string;
25601
+ readonly group: string;
25602
+ readonly description?: string | undefined;
25603
+ readonly snippet: string;
25604
+ }
25605
+ ```
25606
+
25607
+ ## Properties
25608
+
25609
+ | Property | Type | Description |
25610
+ | --- | --- | --- |
25611
+ | `name` | `string` | Name of the component, e.g. `"Button"`. Read only. |
25612
+ | `group` | `string` | Name of the group the component is in, e.g. `"block"` or `"form"`. Read only. |
25613
+ | `description` | `string \| undefined` | First line of the component's docblock. Read only. Optional. |
25614
+ | `snippet` | `string` | TSX to insert, with its imports, e.g. `import { Button } from "shelving/ui";\n\n<Button>Save</Button>`. Read only. |
25615
+
25616
+
25617
+ ---
25618
+
25619
+ # insertPlaygroundSnippet()
25620
+
25621
+ - Kind: function
25622
+ - Import: `import { insertPlaygroundSnippet } from "shelving/ui";`
25623
+
25624
+ Insert a TSX snippet into playground code, and merge the snippet's imports into the code's imports.
25625
+ - The snippet body goes on its own lines at `at` (or at the end of the code).
25626
+ - Each name in a snippet `import { … } from "…"` is added to the code's import from the same module, or a new import is added at the top.
25627
+
25628
+ ## Signatures
25629
+
25630
+ ```ts
25631
+ insertPlaygroundSnippet(code: string, snippet: string, at?: number | undefined): string
25632
+ ```
25633
+
25634
+ ## Parameters
25635
+
25636
+ | Param | Type | Description |
25637
+ | --- | --- | --- |
25638
+ | `code` | `string` | The playground code. |
25639
+ | `snippet` | `string` | The TSX snippet to insert, e.g. `PlaygroundComponent.snippet`. |
25640
+ | `at` | `number \| undefined` | The cursor position in `code`, e.g. the `selectionStart` of the text box. Optional. |
25641
+
25642
+ ## Returns
25643
+
25644
+ | Type | Description |
25645
+ | --- | --- |
25646
+ | `string` | The new code. |
25647
+
25648
+ ## Examples
25649
+
25650
+ ```ts
25651
+ insertPlaygroundSnippet("", 'import { Button } from "shelving/ui";\n\n<Button>Hi</Button>') // 'import { Button } from "shelving/ui";\n\n<Button>Hi</Button>\n'
25652
+ ```
25653
+
25654
+
25655
+ ---
25656
+
25657
+ # insertPlaygroundText()
25658
+
25659
+ - Kind: function
25660
+ - Import: `import { insertPlaygroundText } from "shelving/ui";`
25661
+
25662
+ Insert text on its own lines into playground code or CSS.
25663
+ - With no `at`, CSS (text that ends with a `}`) gets the text before its last `}`, and other text gets it at the end.
25664
+
25665
+ ## Signatures
25666
+
25667
+ ```ts
25668
+ insertPlaygroundText(text: string, insert: string, at?: number | undefined): string
25669
+ ```
25670
+
25671
+ ## Parameters
25672
+
25673
+ | Param | Type | Description |
25674
+ | --- | --- | --- |
25675
+ | `text` | `string` | The code or CSS. |
25676
+ | `insert` | `string` | The text to insert. |
25677
+ | `at` | `number \| undefined` | The cursor position in `text`, e.g. the `selectionStart` of the text box. Optional. |
25678
+
25679
+ ## Returns
25680
+
25681
+ | Type | Description |
25682
+ | --- | --- |
25683
+ | `string` | The new text. |
25684
+
25685
+ ## Examples
25686
+
25687
+ ```ts
25688
+ insertPlaygroundText("a\n", "b") // "a\nb\n"
25689
+ ```
25690
+
25691
+
24843
25692
  ---
24844
25693
 
24845
25694
  # FieldProps
@@ -25035,7 +25884,7 @@ The entry point for shelving forms. `Form` creates a `FormStore` from a `schema`
25035
25884
  - If you provide no `children`, `Form` renders `<FormFields>` (one auto-input per schema property) followed by `<FormFooter>` (submit button + error message), so a usable form is one prop away.
25036
25885
  - Pass `data` to pre-populate an edit form. Pass `messages` (a string or dictionary) to seed initial field errors — useful when a server returns validation failures.
25037
25886
  - The whole `<fieldset>` is disabled while a submit is in flight, so inputs and buttons lock automatically.
25038
- - A successful submit inside a `<dialog>` closes the dialog automatically.
25887
+ - A successful submit inside a `<dialog>` closes the dialog automatically, through `requestDialogClose()`, so a `<Dialog>` can animate out.
25039
25888
  - Notices are surfaced from the `onSubmit` return/throw — see [Notices and error surfacing](#notices-and-error-surfacing) below.
25040
25889
 
25041
25890
  ## Usage
@@ -25858,7 +26707,7 @@ A continuous horizontal progress bar for the completion of a task. Rendered as a
25858
26707
 
25859
26708
  ### Basic
25860
26709
 
25861
- ```tsx
26710
+ ```tsx live
25862
26711
  import { Progress } from "shelving/ui";
25863
26712
 
25864
26713
  // 75% full.
@@ -25867,7 +26716,7 @@ import { Progress } from "shelving/ui";
25867
26716
 
25868
26717
  ### Custom range
25869
26718
 
25870
- ```tsx
26719
+ ```tsx live
25871
26720
  import { Progress } from "shelving/ui";
25872
26721
 
25873
26722
  // 50% full — value 15 within the 10–20 range.
@@ -25876,7 +26725,7 @@ import { Progress } from "shelving/ui";
25876
26725
 
25877
26726
  ### Status and colour
25878
26727
 
25879
- ```tsx
26728
+ ```tsx live
25880
26729
  import { Progress } from "shelving/ui";
25881
26730
 
25882
26731
  <Progress value={90} status="success" />
@@ -25886,7 +26735,7 @@ import { Progress } from "shelving/ui";
25886
26735
 
25887
26736
  ### Indeterminate
25888
26737
 
25889
- ```tsx
26738
+ ```tsx live
25890
26739
  import { Progress } from "shelving/ui";
25891
26740
 
25892
26741
  // No `value` → looping flow animation for a task of unknown duration.
@@ -26017,7 +26866,7 @@ import { Code, Keyboard, Sample } from "shelving/ui";
26017
26866
 
26018
26867
  ### Plain (no background)
26019
26868
 
26020
- ```tsx
26869
+ ```tsx live
26021
26870
  import { Code } from "shelving/ui";
26022
26871
 
26023
26872
  <Code plain>const x = 1;</Code>
@@ -26099,7 +26948,7 @@ Deleted text — renders a `<del>` element to mark content that has been removed
26099
26948
 
26100
26949
  ### Marking a removed value
26101
26950
 
26102
- ```tsx
26951
+ ```tsx live
26103
26952
  import { Paragraph, Deleted, Inserted } from "shelving/ui";
26104
26953
 
26105
26954
  <Paragraph>
@@ -26183,7 +27032,7 @@ Emphasised text — renders an `<em>` element for stress emphasis, the kind that
26183
27032
 
26184
27033
  ### Stress emphasis in body copy
26185
27034
 
26186
- ```tsx
27035
+ ```tsx live
26187
27036
  import { Paragraph, Emphasis } from "shelving/ui";
26188
27037
 
26189
27038
  <Paragraph>
@@ -26263,7 +27112,7 @@ Inserted text — renders an `<ins>` element to mark content that has been added
26263
27112
 
26264
27113
  ### Marking an added value
26265
27114
 
26266
- ```tsx
27115
+ ```tsx live
26267
27116
  import { Paragraph, Deleted, Inserted } from "shelving/ui";
26268
27117
 
26269
27118
  <Paragraph>
@@ -26357,7 +27206,7 @@ An inline link or action. Delegates to `<Clickable>`, rendering an `<a>` when `h
26357
27206
 
26358
27207
  ### Link inside body copy
26359
27208
 
26360
- ```tsx
27209
+ ```tsx live
26361
27210
  import { Paragraph, Link } from "shelving/ui";
26362
27211
 
26363
27212
  <Paragraph>
@@ -26367,7 +27216,7 @@ import { Paragraph, Link } from "shelving/ui";
26367
27216
 
26368
27217
  ### Action button
26369
27218
 
26370
- ```tsx
27219
+ ```tsx live
26371
27220
  import { Link } from "shelving/ui";
26372
27221
 
26373
27222
  <Link onClick={() => save()}>Save now</Link>
@@ -26375,7 +27224,7 @@ import { Link } from "shelving/ui";
26375
27224
 
26376
27225
  ### Plain link around a block
26377
27226
 
26378
- ```tsx
27227
+ ```tsx live
26379
27228
  import { Link, Row, Span } from "shelving/ui";
26380
27229
 
26381
27230
  <Link plain href="/jane">
@@ -26456,7 +27305,7 @@ Highlighted text — renders a `<mark>` element to call attention to a run of te
26456
27305
 
26457
27306
  ### Highlighted search term
26458
27307
 
26459
- ```tsx
27308
+ ```tsx live
26460
27309
  import { Mark } from "shelving/ui";
26461
27310
 
26462
27311
  <p>Files are stored in <Mark>UTF-8</Mark> encoding.</p>
@@ -26534,7 +27383,7 @@ Small print — renders a `<small>` element for side comments and fine print suc
26534
27383
 
26535
27384
  ### Fine print after a statement
26536
27385
 
26537
- ```tsx
27386
+ ```tsx live
26538
27387
  import { Paragraph, Small } from "shelving/ui";
26539
27388
 
26540
27389
  <Paragraph>
@@ -26618,7 +27467,7 @@ Styled inline text — renders a `<span>` element that carries only the colour a
26618
27467
 
26619
27468
  ### Applying typography variants
26620
27469
 
26621
- ```tsx
27470
+ ```tsx live
26622
27471
  import { Span } from "shelving/ui";
26623
27472
 
26624
27473
  <p>Total <Span weight="strong">$35.00</Span> due today.</p>
@@ -26627,7 +27476,7 @@ import { Span } from "shelving/ui";
26627
27476
 
26628
27477
  ### Colouring a run of text
26629
27478
 
26630
- ```tsx
27479
+ ```tsx live
26631
27480
  import { Span } from "shelving/ui";
26632
27481
 
26633
27482
  <Span color="purple" tint="40">on-brand accent</Span>
@@ -26701,7 +27550,7 @@ Strong importance — renders a `<strong>` element for text that carries strong
26701
27550
 
26702
27551
  ### Strong importance in body copy
26703
27552
 
26704
- ```tsx
27553
+ ```tsx live
26705
27554
  import { Paragraph, Strong } from "shelving/ui";
26706
27555
 
26707
27556
  <Paragraph>
@@ -28855,7 +29704,7 @@ The shared value-input prop contract (`ValueInputProps<O>`):
28855
29704
 
28856
29705
  ### Dispatch on a single schema
28857
29706
 
28858
- ```tsx
29707
+ ```tsx live
28859
29708
  import { SchemaInput } from "shelving/ui";
28860
29709
  import { StringSchema, NumberSchema } from "shelving/schema";
28861
29710
 
@@ -29856,7 +30705,7 @@ A `<menu>` list of `<MenuItem>` children — the container for URL-aware navigat
29856
30705
 
29857
30706
  ## Usage
29858
30707
 
29859
- ```tsx
30708
+ ```tsx live
29860
30709
  import { Menu, MenuItem } from "shelving/ui";
29861
30710
 
29862
30711
  <Menu>
@@ -29964,7 +30813,7 @@ A single `<li>` link entry inside a `<Menu>`. It reads the current page URL from
29964
30813
 
29965
30814
  ## Usage
29966
30815
 
29967
- ```tsx
30816
+ ```tsx live
29968
30817
  import { Menu, MenuItem } from "shelving/ui";
29969
30818
 
29970
30819
  <Menu>
@@ -29981,7 +30830,7 @@ import { Menu, MenuItem } from "shelving/ui";
29981
30830
 
29982
30831
  ### Small items
29983
30832
 
29984
- ```tsx
30833
+ ```tsx live
29985
30834
  import { Menu, MenuItem } from "shelving/ui";
29986
30835
 
29987
30836
  // One small item.
@@ -30321,7 +31170,7 @@ Renders an icon for a given status, coloured to match. Picks an icon per status
30321
31170
 
30322
31171
  ## Usage
30323
31172
 
30324
- ```tsx
31173
+ ```tsx live
30325
31174
  import { Icon } from "shelving/ui";
30326
31175
 
30327
31176
  <Icon status="success" size="large" />
@@ -30961,7 +31810,7 @@ A small inline label used to annotate other content. Accepts a status variant or
30961
31810
 
30962
31811
  ## Usage
30963
31812
 
30964
- ```tsx
31813
+ ```tsx live
30965
31814
  import { Tag } from "shelving/ui";
30966
31815
 
30967
31816
  <Tag success>Active</Tag>
@@ -31051,7 +31900,7 @@ Message for a list with nothing in it. `<Empty>` shows its content centred and g
31051
31900
 
31052
31901
  ### Empty list
31053
31902
 
31054
- ```tsx
31903
+ ```tsx live
31055
31904
  import { Empty, Paragraph } from "shelving/ui";
31056
31905
 
31057
31906
  <Empty>
@@ -31197,7 +32046,7 @@ A block-level status callout with an icon and message, used to highlight feedbac
31197
32046
 
31198
32047
  ## Usage
31199
32048
 
31200
- ```tsx
32049
+ ```tsx live
31201
32050
  import { Notice } from "shelving/ui";
31202
32051
 
31203
32052
  <Notice status="success">Your changes have been saved.</Notice>
@@ -31325,7 +32174,7 @@ Renders the global list of active notices and subscribes to incoming `"notice"`
31325
32174
  - Notices auto-dismiss after a short delay unless they carry a `"loading"` status.
31326
32175
  - Backed by the `NOTICES` store singleton; for advanced use you can keep a reference to a notice to update or close it manually.
31327
32176
  - The list shows in the bottom-right corner. Set `position` to `"top-left"`, `"top-center"`, `"top-right"`, `"bottom-left"`, `"bottom-center"`, or `"bottom-right"` to choose a different place.
31328
- - Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
32177
+ - Notices animate with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). `Notices` renders the store inside transitions, so a notice animates with no `startTransition()` of your own. A single `<Notice>` knows nothing about transitions, the same as `<Dialog>`. A new notice slides in from the side of its corner, and a closed notice slides out to that side. In a centred list, notices slide in and out from the top or bottom edge. The other notices move to their new places. A notice that changes in place (for example from loading to success) changes at once, with no animation.
31329
32178
  - With reduced motion, notices fade in and out in place, and the others move at once. A browser without view transitions shows the changes at once.
31330
32179
 
31331
32180
  ## Usage
@@ -34499,7 +35348,7 @@ A data table — renders a `<table>`. Compose the usual `<thead>` / `<tbody>` /
34499
35348
 
34500
35349
  ### Basic table
34501
35350
 
34502
- ```tsx
35351
+ ```tsx live
34503
35352
  import { Table } from "shelving/ui";
34504
35353
 
34505
35354
  <Table>
@@ -34515,7 +35364,7 @@ import { Table } from "shelving/ui";
34515
35364
 
34516
35365
  ### Cell padding
34517
35366
 
34518
- ```tsx
35367
+ ```tsx live
34519
35368
  import { Button, Cell, Table } from "shelving/ui";
34520
35369
 
34521
35370
  <Table padding="small">