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.
- package/docs/llms-full.txt +964 -115
- package/docs/markup/FENCED_RULE.md +1 -0
- package/docs/markup/FencedInfo.md +24 -0
- package/docs/markup/createFencedRegExp.md +31 -0
- package/docs/markup/parseFencedInfo.md +34 -0
- package/docs/markup.md +3 -0
- package/docs/ui/Button.md +1 -1
- package/docs/ui/Card.md +4 -4
- package/docs/ui/Code.md +1 -1
- package/docs/ui/DOCUMENTATION_LIVE_RULE.md +16 -0
- package/docs/ui/DOCUMENTATION_MARKUP_RULES.md +12 -0
- package/docs/ui/Deleted.md +1 -1
- package/docs/ui/Details.md +3 -3
- package/docs/ui/Dialog.md +11 -8
- package/docs/ui/DialogProps.md +1 -1
- package/docs/ui/DocumentationApp.md +5 -5
- package/docs/ui/DocumentationFrame.md +57 -0
- package/docs/ui/DocumentationFrameProps.md +21 -0
- package/docs/ui/DocumentationLive.md +86 -0
- package/docs/ui/DocumentationLiveProps.md +22 -0
- package/docs/ui/DocumentationPlaygroundInsert.md +30 -0
- package/docs/ui/DocumentationPlaygroundInsertProps.md +24 -0
- package/docs/ui/DocumentationPlaygroundPage.md +32 -0
- package/docs/ui/Emphasis.md +1 -1
- package/docs/ui/Empty.md +1 -1
- package/docs/ui/Form.md +1 -1
- package/docs/ui/Grid.md +1 -1
- package/docs/ui/Heading.md +3 -3
- package/docs/ui/Icon.md +1 -1
- package/docs/ui/Inserted.md +1 -1
- package/docs/ui/Link.md +3 -3
- package/docs/ui/List.md +1 -1
- package/docs/ui/Mark.md +1 -1
- package/docs/ui/Menu.md +1 -1
- package/docs/ui/MenuItem.md +2 -2
- package/docs/ui/Modal.md +1 -1
- package/docs/ui/Notice.md +1 -1
- package/docs/ui/Notices.md +1 -1
- package/docs/ui/PLAYGROUND_COMPONENTS_PATH.md +7 -0
- package/docs/ui/PLAYGROUND_FRAME_PATH.md +6 -0
- package/docs/ui/PLAYGROUND_HEIGHT_MESSAGE.md +6 -0
- package/docs/ui/PLAYGROUND_PAGE_PATH.md +6 -0
- package/docs/ui/PLAYGROUND_VARIABLES_PATH.md +7 -0
- package/docs/ui/Panel.md +1 -1
- package/docs/ui/Paragraph.md +2 -2
- package/docs/ui/PlaygroundCode.md +22 -0
- package/docs/ui/PlaygroundComponent.md +26 -0
- package/docs/ui/PlaygroundVariable.md +24 -0
- package/docs/ui/PlaygroundVariableGroup.md +24 -0
- package/docs/ui/Progress.md +4 -4
- package/docs/ui/Prose.md +1 -1
- package/docs/ui/SchemaInput.md +1 -1
- package/docs/ui/Section.md +1 -1
- package/docs/ui/Small.md +1 -1
- package/docs/ui/Span.md +2 -2
- package/docs/ui/Strong.md +1 -1
- package/docs/ui/Subheading.md +2 -2
- package/docs/ui/Table.md +2 -2
- package/docs/ui/Tag.md +1 -1
- package/docs/ui/Title.md +2 -2
- package/docs/ui/formatPlaygroundCSS.md +31 -0
- package/docs/ui/formatPlaygroundHash.md +34 -0
- package/docs/ui/insertPlaygroundSnippet.md +34 -0
- package/docs/ui/insertPlaygroundText.md +33 -0
- package/docs/ui/parsePlaygroundHash.md +31 -0
- package/docs/ui/requestDialogClose.md +28 -0
- package/docs/ui.md +27 -1
- package/markup/rule/fenced.d.ts +42 -0
- package/markup/rule/fenced.js +48 -4
- package/package.json +1 -1
- package/ui/README.md +2 -0
- package/ui/block/Card.md +4 -4
- package/ui/block/Details.md +3 -3
- package/ui/block/Grid.md +1 -1
- package/ui/block/Heading.md +3 -3
- package/ui/block/List.md +1 -1
- package/ui/block/Panel.md +1 -1
- package/ui/block/Paragraph.md +2 -2
- package/ui/block/Prose.md +1 -1
- package/ui/block/Section.md +1 -1
- package/ui/block/Subheading.md +2 -2
- package/ui/block/Title.md +2 -2
- package/ui/button/Button.md +1 -1
- package/ui/dialog/Dialog.d.ts +15 -3
- package/ui/dialog/Dialog.js +17 -10
- package/ui/dialog/Dialog.md +9 -6
- package/ui/dialog/Dialog.tsx +18 -11
- package/ui/dialog/Modal.md +1 -1
- package/ui/docs/DocumentationApp.d.ts +6 -2
- package/ui/docs/DocumentationApp.js +18 -5
- package/ui/docs/DocumentationApp.tsx +32 -3
- package/ui/docs/DocumentationFrame.d.ts +26 -0
- package/ui/docs/DocumentationFrame.js +34 -0
- package/ui/docs/DocumentationFrame.md +28 -0
- package/ui/docs/DocumentationFrame.module.css +17 -0
- package/ui/docs/DocumentationFrame.tsx +58 -0
- package/ui/docs/DocumentationLive.d.ts +37 -0
- package/ui/docs/DocumentationLive.js +39 -0
- package/ui/docs/DocumentationLive.md +57 -0
- package/ui/docs/DocumentationLive.module.css +85 -0
- package/ui/docs/DocumentationLive.test.tsx +34 -0
- package/ui/docs/DocumentationLive.tsx +75 -0
- package/ui/docs/DocumentationPage.js +2 -1
- package/ui/docs/DocumentationPage.tsx +2 -1
- package/ui/docs/DocumentationPlaygroundInsert.d.ts +24 -0
- package/ui/docs/DocumentationPlaygroundInsert.js +80 -0
- package/ui/docs/DocumentationPlaygroundInsert.tsx +151 -0
- package/ui/docs/DocumentationPlaygroundPage.d.ts +17 -0
- package/ui/docs/DocumentationPlaygroundPage.js +215 -0
- package/ui/docs/DocumentationPlaygroundPage.module.css +106 -0
- package/ui/docs/DocumentationPlaygroundPage.tsx +294 -0
- package/ui/docs/index.d.ts +5 -0
- package/ui/docs/index.js +5 -0
- package/ui/docs/index.ts +5 -0
- package/ui/docs/playground.d.ts +139 -0
- package/ui/docs/playground.js +162 -0
- package/ui/docs/playground.test.ts +83 -0
- package/ui/docs/playground.ts +225 -0
- package/ui/form/Form.js +4 -3
- package/ui/form/Form.md +1 -1
- package/ui/form/Form.tsx +3 -2
- package/ui/form/Progress.md +4 -4
- package/ui/inline/Code.md +1 -1
- package/ui/inline/Deleted.md +1 -1
- package/ui/inline/Emphasis.md +1 -1
- package/ui/inline/Inserted.md +1 -1
- package/ui/inline/Link.md +3 -3
- package/ui/inline/Mark.md +1 -1
- package/ui/inline/Small.md +1 -1
- package/ui/inline/Span.md +2 -2
- package/ui/inline/Strong.md +1 -1
- package/ui/input/SchemaInput.md +1 -1
- package/ui/menu/Menu.md +1 -1
- package/ui/menu/MenuItem.md +2 -2
- package/ui/misc/Icon.md +1 -1
- package/ui/misc/Tag.md +1 -1
- package/ui/notice/Empty.md +1 -1
- package/ui/notice/Notice.md +1 -1
- package/ui/notice/Notices.md +1 -1
- package/ui/table/Table.md +2 -2
package/docs/llms-full.txt
CHANGED
|
@@ -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
|
|
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
|
-
-
|
|
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()
|
|
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
|
-
- `
|
|
23393
|
-
-
|
|
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
|
-
-
|
|
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:
|
|
24038
|
+
- Kind: component
|
|
23873
24039
|
- Import: `import { DocumentationApp } from "shelving/ui";`
|
|
23874
24040
|
|
|
23875
24041
|
Documentation app.
|
|
23876
|
-
-
|
|
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
|
-
|
|
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
|
-
#
|
|
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 {
|
|
24532
|
+
- Import: `import { DocumentationLive } from "shelving/ui";`
|
|
24255
24533
|
|
|
24256
|
-
|
|
24257
|
-
-
|
|
24258
|
-
-
|
|
24259
|
-
-
|
|
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
|
-
|
|
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
|
-
-
|
|
24269
|
-
-
|
|
24270
|
-
-
|
|
24271
|
-
-
|
|
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
|
-
|
|
24553
|
+
### A live example in a Markdown page
|
|
24276
24554
|
|
|
24277
|
-
|
|
24278
|
-
|
|
24555
|
+
````md
|
|
24556
|
+
```tsx live "A solid button"
|
|
24557
|
+
import { Button } from "shelving/ui";
|
|
24279
24558
|
|
|
24280
|
-
|
|
24281
|
-
<DocumentationPage {...element.props} />
|
|
24559
|
+
<Button solid>Save</Button>
|
|
24282
24560
|
```
|
|
24561
|
+
````
|
|
24283
24562
|
|
|
24284
|
-
|
|
24563
|
+
### A live example with state
|
|
24285
24564
|
|
|
24286
|
-
|
|
24287
|
-
|
|
24565
|
+
````md
|
|
24566
|
+
```tsx live
|
|
24567
|
+
import { useState } from "react";
|
|
24568
|
+
import { Button } from "shelving/ui";
|
|
24288
24569
|
|
|
24289
|
-
|
|
24290
|
-
|
|
24291
|
-
</
|
|
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
|
-
|
|
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
|
-
|
|
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` | `
|
|
24325
|
-
| `.
|
|
24326
|
-
| `.
|
|
24327
|
-
|
|
24328
|
-
|
|
24329
|
-
|
|
24330
|
-
|
|
|
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">
|