shelving 1.318.0 → 1.319.0
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 +872 -59
- 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/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/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/Notice.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.md +26 -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/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/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/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.
|
|
@@ -20094,9 +20206,13 @@ The components below are listed in the index following this page; this is the sh
|
|
|
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.
|
|
20096
20208
|
- [requireDialogs()](ui/requireDialogs.md): Read the current DialogsStore from the nearest <DialogsContext>.
|
|
20097
|
-
- [DocumentationApp()](ui/DocumentationApp.md): Documentation app.
|
|
20098
20209
|
- [getDocumentationKindColor()](ui/getDocumentationKindColor.md): Get the raw colour variant for a documented symbol's kind, or undefined for an unknown kind.
|
|
20099
20210
|
- [splitType()](ui/splitType.md): Split a type expression on | into its individual union members.
|
|
20211
|
+
- [formatPlaygroundHash()](ui/formatPlaygroundHash.md): Format code and CSS as a URL hash for the playground page or its frame, e.g. #code=…&css=….
|
|
20212
|
+
- [parsePlaygroundHash()](ui/parsePlaygroundHash.md): Parse a URL hash made by formatPlaygroundHash() back into code and CSS.
|
|
20213
|
+
- [formatPlaygroundCSS()](ui/formatPlaygroundCSS.md): Format CSS variables as a :root rule that you can paste into the playground CSS and change.
|
|
20214
|
+
- [insertPlaygroundSnippet()](ui/insertPlaygroundSnippet.md): Insert a TSX snippet into playground code, and merge the snippet's imports into the code's imports.
|
|
20215
|
+
- [insertPlaygroundText()](ui/insertPlaygroundText.md): Insert text on its own lines into playground code or CSS.
|
|
20100
20216
|
- [callNotifiedForm()](ui/callNotifiedForm.md): Run a form submit callback and publish success/error notices based on its return or thrown value.
|
|
20101
20217
|
- [awaitNotifiedForm()](ui/awaitNotifiedForm.md): Await a pending submit result and publish a success or error notice to a form once it settles.
|
|
20102
20218
|
- [notifyThrownForm()](ui/notifyThrownForm.md): Notify the user about a value thrown during submit, storing string errors as form field messages.
|
|
@@ -20221,14 +20337,21 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20221
20337
|
- [ModalProps](ui/ModalProps.md): Props for <Modal> — edge, padding, indent, radius, and shadow variants, optional children content, and an optional className.
|
|
20222
20338
|
- [DocumentationButtonsProps](ui/DocumentationButtonsProps.md): Props for DocumentationButtons — the relational metadata of a documented symbol (class, extends, implements), plus block-space and flex overrides.
|
|
20223
20339
|
- [DocumentationDescriptionProps](ui/DocumentationDescriptionProps.md): Props for DocumentationDescription — a description cell's resolved text, plus an optional default/optionality note.
|
|
20340
|
+
- [DocumentationFrameProps](ui/DocumentationFrameProps.md): Props for <DocumentationFrame> — the code and CSS to run, plus a title for the frame.
|
|
20224
20341
|
- [DocumentationKindProps](ui/DocumentationKindProps.md): Props for DocumentationKind — a TagProps plus the documented symbol's kind.
|
|
20342
|
+
- [DocumentationLiveProps](ui/DocumentationLiveProps.md): Props for <DocumentationLive> — the code to show and run, plus an optional title.
|
|
20225
20343
|
- [DocumentationParamsProps](ui/DocumentationParamsProps.md): Props for DocumentationParams — the parameter list to render, one row per parameter.
|
|
20344
|
+
- [DocumentationPlaygroundInsertProps](ui/DocumentationPlaygroundInsertProps.md): Props for <DocumentationPlaygroundInsert>.
|
|
20226
20345
|
- [DocumentationPropertiesProps](ui/DocumentationPropertiesProps.md): Props for DocumentationProperties — the data members of a class/interface/object-literal type to render, one row each.
|
|
20227
20346
|
- [DocumentationReferencesProps](ui/DocumentationReferencesProps.md): Props for DocumentationReferences — the referenced type names to render, one row each.
|
|
20228
20347
|
- [DocumentationReturnsProps](ui/DocumentationReturnsProps.md): Props for DocumentationReturns — the @returns entries to render, one row each.
|
|
20229
20348
|
- [DocumentationSignaturesProps](ui/DocumentationSignaturesProps.md): Props for DocumentationSignatures — the type signatures to render, one block per overload.
|
|
20230
20349
|
- [DocumentationThrowsProps](ui/DocumentationThrowsProps.md): Props for DocumentationThrows — the @throws entries to render, one row each.
|
|
20231
20350
|
- [DocumentationTypeProps](ui/DocumentationTypeProps.md): Props for DocumentationType — the union members to render (see splitType()).
|
|
20351
|
+
- [PlaygroundCode](ui/PlaygroundCode.md): Code and CSS that the playground frame runs.
|
|
20352
|
+
- [PlaygroundVariable](ui/PlaygroundVariable.md): One CSS variable that you can set to change the look of shelving components.
|
|
20353
|
+
- [PlaygroundVariableGroup](ui/PlaygroundVariableGroup.md): A group of CSS variables that one CSS module owns, e.g. the --card-* variables of Card.module.css.
|
|
20354
|
+
- [PlaygroundComponent](ui/PlaygroundComponent.md): One shelving component that you can insert into the playground code.
|
|
20232
20355
|
- [FieldProps](ui/FieldProps.md): Props for Field, a labelled wrapper around a form control.
|
|
20233
20356
|
- [FormProps](ui/FormProps.md): Props for Form, the schema-driven form wrapper component.
|
|
20234
20357
|
- [FormFooterProps](ui/FormFooterProps.md): Props for FormFooter, the submit-button-and-message footer for a form.
|
|
@@ -20395,6 +20518,13 @@ The components below are listed in the index following this page; this is the sh
|
|
|
20395
20518
|
## Constants
|
|
20396
20519
|
|
|
20397
20520
|
- [RetryContext](ui/RetryContext.md): Context for providing a "retry" callback to descendant <RetryButton> elements.
|
|
20521
|
+
- [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" `.
|
|
20522
|
+
- [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.
|
|
20523
|
+
- [PLAYGROUND_FRAME_PATH](ui/PLAYGROUND_FRAME_PATH.md): Path of the frame page that runs playground code, relative to the docs site root.
|
|
20524
|
+
- [PLAYGROUND_PAGE_PATH](ui/PLAYGROUND_PAGE_PATH.md): Path of the playground page, relative to the docs site root.
|
|
20525
|
+
- [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 }.
|
|
20526
|
+
- [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.
|
|
20527
|
+
- [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
20528
|
- [FormContext](ui/FormContext.md): React context holding the current FormStore, provided by the Form component.
|
|
20399
20529
|
- [LOADING_INPUT](ui/LOADING_INPUT.md): Input that is loading.
|
|
20400
20530
|
- [LOADING](ui/LOADING.md): Shared loading spinner element with a stable key, ready to drop into Suspense fallbacks and lists.
|
|
@@ -20916,7 +21046,7 @@ A boxed surface that groups a self-contained piece of content. Rendered as an `<
|
|
|
20916
21046
|
|
|
20917
21047
|
### Static card
|
|
20918
21048
|
|
|
20919
|
-
```tsx
|
|
21049
|
+
```tsx live
|
|
20920
21050
|
import { Card, Subheading, Paragraph } from "shelving/ui";
|
|
20921
21051
|
|
|
20922
21052
|
<Card>
|
|
@@ -20927,7 +21057,7 @@ import { Card, Subheading, Paragraph } from "shelving/ui";
|
|
|
20927
21057
|
|
|
20928
21058
|
### Navigable card
|
|
20929
21059
|
|
|
20930
|
-
```tsx
|
|
21060
|
+
```tsx live
|
|
20931
21061
|
import { Card, Subheading, Paragraph } from "shelving/ui";
|
|
20932
21062
|
|
|
20933
21063
|
// The entire card is a link; `title` labels the overlay for screen readers.
|
|
@@ -20939,7 +21069,7 @@ import { Card, Subheading, Paragraph } from "shelving/ui";
|
|
|
20939
21069
|
|
|
20940
21070
|
### Status and colour
|
|
20941
21071
|
|
|
20942
|
-
```tsx
|
|
21072
|
+
```tsx live
|
|
20943
21073
|
import { Card, Subheading } from "shelving/ui";
|
|
20944
21074
|
|
|
20945
21075
|
<Card status="error"><Subheading>Couldn't load</Subheading></Card>
|
|
@@ -20948,7 +21078,7 @@ import { Card, Subheading } from "shelving/ui";
|
|
|
20948
21078
|
|
|
20949
21079
|
### Shadow
|
|
20950
21080
|
|
|
20951
|
-
```tsx
|
|
21081
|
+
```tsx live
|
|
20952
21082
|
import { Card, Subheading } from "shelving/ui";
|
|
20953
21083
|
|
|
20954
21084
|
// Raise a card a little or a lot.
|
|
@@ -21179,7 +21309,7 @@ A collapsible panel. The title is always visible. The content shows when the use
|
|
|
21179
21309
|
|
|
21180
21310
|
### Single panel
|
|
21181
21311
|
|
|
21182
|
-
```tsx
|
|
21312
|
+
```tsx live
|
|
21183
21313
|
import { Details, Paragraph } from "shelving/ui";
|
|
21184
21314
|
|
|
21185
21315
|
<Details title="What is shelving?">
|
|
@@ -21189,7 +21319,7 @@ import { Details, Paragraph } from "shelving/ui";
|
|
|
21189
21319
|
|
|
21190
21320
|
### Open by default
|
|
21191
21321
|
|
|
21192
|
-
```tsx
|
|
21322
|
+
```tsx live
|
|
21193
21323
|
import { Details, Paragraph } from "shelving/ui";
|
|
21194
21324
|
|
|
21195
21325
|
<Details title="Release notes" open>
|
|
@@ -21199,7 +21329,7 @@ import { Details, Paragraph } from "shelving/ui";
|
|
|
21199
21329
|
|
|
21200
21330
|
### Exclusive group (FAQ)
|
|
21201
21331
|
|
|
21202
|
-
```tsx
|
|
21332
|
+
```tsx live
|
|
21203
21333
|
import { Details, Paragraph } from "shelving/ui";
|
|
21204
21334
|
|
|
21205
21335
|
// Only one answer is open at a time.
|
|
@@ -21343,7 +21473,7 @@ A grid container that arranges its children in equal-width columns. Renders a `<
|
|
|
21343
21473
|
|
|
21344
21474
|
### Two columns of cards
|
|
21345
21475
|
|
|
21346
|
-
```tsx
|
|
21476
|
+
```tsx live
|
|
21347
21477
|
import { Card, Grid, Paragraph } from "shelving/ui";
|
|
21348
21478
|
|
|
21349
21479
|
<Grid gap="small">
|
|
@@ -21447,7 +21577,7 @@ A section heading — renders an `<h2>`. It sits in the middle of the three-leve
|
|
|
21447
21577
|
|
|
21448
21578
|
### Section heading
|
|
21449
21579
|
|
|
21450
|
-
```tsx
|
|
21580
|
+
```tsx live
|
|
21451
21581
|
import { Heading, Paragraph } from "shelving/ui";
|
|
21452
21582
|
|
|
21453
21583
|
<Heading>Billing</Heading>
|
|
@@ -21456,7 +21586,7 @@ import { Heading, Paragraph } from "shelving/ui";
|
|
|
21456
21586
|
|
|
21457
21587
|
### The heading family together
|
|
21458
21588
|
|
|
21459
|
-
```tsx
|
|
21589
|
+
```tsx live
|
|
21460
21590
|
import { Title, Heading, Subheading } from "shelving/ui";
|
|
21461
21591
|
|
|
21462
21592
|
<Title>Account</Title> {/* <h1> */}
|
|
@@ -21466,7 +21596,7 @@ import { Title, Heading, Subheading } from "shelving/ui";
|
|
|
21466
21596
|
|
|
21467
21597
|
### Coloured heading
|
|
21468
21598
|
|
|
21469
|
-
```tsx
|
|
21599
|
+
```tsx live
|
|
21470
21600
|
import { Heading } from "shelving/ui";
|
|
21471
21601
|
|
|
21472
21602
|
<Heading color="red">Danger zone</Heading>
|
|
@@ -21684,7 +21814,7 @@ A bulleted or numbered list. Renders a `<ul>` by default (or an `<ol>` when `ord
|
|
|
21684
21814
|
|
|
21685
21815
|
### Unordered and ordered lists
|
|
21686
21816
|
|
|
21687
|
-
```tsx
|
|
21817
|
+
```tsx live
|
|
21688
21818
|
import { List } from "shelving/ui";
|
|
21689
21819
|
|
|
21690
21820
|
<List>{["Apples", "Oranges", "Pears"]}</List>
|
|
@@ -21786,7 +21916,7 @@ A full-width vertical region that paints the current surface colour. Use panels
|
|
|
21786
21916
|
|
|
21787
21917
|
### Page banded into panels
|
|
21788
21918
|
|
|
21789
|
-
```tsx
|
|
21919
|
+
```tsx live
|
|
21790
21920
|
import { Panel, Block, Title, Paragraph } from "shelving/ui";
|
|
21791
21921
|
|
|
21792
21922
|
<Panel as="header" color="primary">
|
|
@@ -21876,7 +22006,7 @@ A block of body text — renders a `<p>`. The default container for running pros
|
|
|
21876
22006
|
|
|
21877
22007
|
### Body text
|
|
21878
22008
|
|
|
21879
|
-
```tsx
|
|
22009
|
+
```tsx live
|
|
21880
22010
|
import { Paragraph } from "shelving/ui";
|
|
21881
22011
|
|
|
21882
22012
|
<Paragraph>The best widget on the market.</Paragraph>
|
|
@@ -21884,7 +22014,7 @@ import { Paragraph } from "shelving/ui";
|
|
|
21884
22014
|
|
|
21885
22015
|
### With inline annotations
|
|
21886
22016
|
|
|
21887
|
-
```tsx
|
|
22017
|
+
```tsx live
|
|
21888
22018
|
import { Paragraph, Strong, Link } from "shelving/ui";
|
|
21889
22019
|
|
|
21890
22020
|
<Paragraph>
|
|
@@ -22033,7 +22163,7 @@ import { Prose, Markup } from "shelving/ui";
|
|
|
22033
22163
|
|
|
22034
22164
|
### Hand-written longform
|
|
22035
22165
|
|
|
22036
|
-
```tsx
|
|
22166
|
+
```tsx live
|
|
22037
22167
|
import { Prose, Paragraph } from "shelving/ui";
|
|
22038
22168
|
|
|
22039
22169
|
<Prose>
|
|
@@ -22174,7 +22304,7 @@ A landmark content region — renders a `<section>` with block-level spacing and
|
|
|
22174
22304
|
|
|
22175
22305
|
### Structured page section
|
|
22176
22306
|
|
|
22177
|
-
```tsx
|
|
22307
|
+
```tsx live
|
|
22178
22308
|
import { Section, Heading, Definitions } from "shelving/ui";
|
|
22179
22309
|
|
|
22180
22310
|
<Section width="narrow">
|
|
@@ -22391,7 +22521,7 @@ A subsection heading — renders an `<h3>`. It is the smallest member of the thr
|
|
|
22391
22521
|
|
|
22392
22522
|
### Card title
|
|
22393
22523
|
|
|
22394
|
-
```tsx
|
|
22524
|
+
```tsx live
|
|
22395
22525
|
import { Card, Subheading, Paragraph } from "shelving/ui";
|
|
22396
22526
|
|
|
22397
22527
|
<Card>
|
|
@@ -22402,7 +22532,7 @@ import { Card, Subheading, Paragraph } from "shelving/ui";
|
|
|
22402
22532
|
|
|
22403
22533
|
### The heading family together
|
|
22404
22534
|
|
|
22405
|
-
```tsx
|
|
22535
|
+
```tsx live
|
|
22406
22536
|
import { Title, Heading, Subheading } from "shelving/ui";
|
|
22407
22537
|
|
|
22408
22538
|
<Title>Account</Title> {/* <h1> */}
|
|
@@ -22489,7 +22619,7 @@ The top-level page heading — renders an `<h1>`. It is the most prominent membe
|
|
|
22489
22619
|
|
|
22490
22620
|
### Page title
|
|
22491
22621
|
|
|
22492
|
-
```tsx
|
|
22622
|
+
```tsx live
|
|
22493
22623
|
import { Title, Paragraph } from "shelving/ui";
|
|
22494
22624
|
|
|
22495
22625
|
<Title>Account</Title>
|
|
@@ -22498,7 +22628,7 @@ import { Title, Paragraph } from "shelving/ui";
|
|
|
22498
22628
|
|
|
22499
22629
|
### Inside a panel header
|
|
22500
22630
|
|
|
22501
|
-
```tsx
|
|
22631
|
+
```tsx live
|
|
22502
22632
|
import { Panel, Block, Title } from "shelving/ui";
|
|
22503
22633
|
|
|
22504
22634
|
<Panel as="header" color="primary">
|
|
@@ -22774,7 +22904,7 @@ import { Button } from "shelving/ui";
|
|
|
22774
22904
|
|
|
22775
22905
|
### Reusing the button class
|
|
22776
22906
|
|
|
22777
|
-
```tsx
|
|
22907
|
+
```tsx live
|
|
22778
22908
|
import { getButtonClass } from "shelving/ui";
|
|
22779
22909
|
|
|
22780
22910
|
// Style an arbitrary element as a button.
|
|
@@ -23867,13 +23997,14 @@ Modal({ children, className, ...props }: ModalProps): ReactElement
|
|
|
23867
23997
|
|
|
23868
23998
|
---
|
|
23869
23999
|
|
|
23870
|
-
# DocumentationApp
|
|
24000
|
+
# DocumentationApp
|
|
23871
24001
|
|
|
23872
|
-
- Kind:
|
|
24002
|
+
- Kind: component
|
|
23873
24003
|
- Import: `import { DocumentationApp } from "shelving/ui";`
|
|
23874
24004
|
|
|
23875
24005
|
Documentation app.
|
|
23876
|
-
-
|
|
24006
|
+
- Works like `<TreeApp>`, and adds a `<DocumentationSearchPage>` at its `/search` URL.
|
|
24007
|
+
- Adds a `<DocumentationPlaygroundPage>` at its `/playground` URL. The playground fills the whole window, so it renders outside the `<SidebarLayout>`.
|
|
23877
24008
|
|
|
23878
24009
|
## Signatures
|
|
23879
24010
|
|
|
@@ -23887,8 +24018,7 @@ DocumentationApp({
|
|
|
23887
24018
|
<TreeSidebar>
|
|
23888
24019
|
<Menu small>
|
|
23889
24020
|
<MenuItem href="/search">Search</MenuItem>
|
|
23890
|
-
|
|
23891
|
-
</TreeSidebar>): void
|
|
24021
|
+
<MenuItem href={`/${PLAYGROUND_PAGE_PATH}`}): void
|
|
23892
24022
|
```
|
|
23893
24023
|
|
|
23894
24024
|
## Parameters
|
|
@@ -24150,6 +24280,92 @@ DocumentationDescription({ description, default: def, optional, readonly }: Docu
|
|
|
24150
24280
|
```
|
|
24151
24281
|
|
|
24152
24282
|
|
|
24283
|
+
---
|
|
24284
|
+
|
|
24285
|
+
# DocumentationFrameProps
|
|
24286
|
+
|
|
24287
|
+
- Kind: interface
|
|
24288
|
+
- Import: `import { DocumentationFrameProps } from "shelving/ui";`
|
|
24289
|
+
- Extends: `PlaygroundCode`
|
|
24290
|
+
|
|
24291
|
+
Props for `<DocumentationFrame>` — the code and CSS to run, plus a title for the frame.
|
|
24292
|
+
|
|
24293
|
+
## Signatures
|
|
24294
|
+
|
|
24295
|
+
```ts
|
|
24296
|
+
{
|
|
24297
|
+
title?: string | undefined;
|
|
24298
|
+
}
|
|
24299
|
+
```
|
|
24300
|
+
|
|
24301
|
+
## Properties
|
|
24302
|
+
|
|
24303
|
+
| Property | Type | Description |
|
|
24304
|
+
| --- | --- | --- |
|
|
24305
|
+
| `title` | `string \| undefined` | Accessible title of the frame. Defaults to `"Preview"`. |
|
|
24306
|
+
|
|
24307
|
+
|
|
24308
|
+
---
|
|
24309
|
+
|
|
24310
|
+
# DocumentationFrame
|
|
24311
|
+
|
|
24312
|
+
- Kind: component
|
|
24313
|
+
- Import: `import { DocumentationFrame } from "shelving/ui";`
|
|
24314
|
+
|
|
24315
|
+
Show a live preview of playground code in an `<iframe>` of the playground frame page.
|
|
24316
|
+
- 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.
|
|
24317
|
+
- The code and CSS go in the frame URL hash, so a change runs again without a reload.
|
|
24318
|
+
- The frame grows to fit its content: the frame page posts its height to this component.
|
|
24319
|
+
- The frame loads lazily, when it scrolls near the screen.
|
|
24320
|
+
|
|
24321
|
+
Show a live preview of TSX and CSS in an `<iframe>` of the playground frame page. `<DocumentationLive>` and `<DocumentationPlaygroundPage>` use it.
|
|
24322
|
+
|
|
24323
|
+
**Things to know:**
|
|
24324
|
+
|
|
24325
|
+
- 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.
|
|
24326
|
+
- The code and CSS go in the frame URL hash (see `formatPlaygroundHash()`). A new hash runs the code again without a reload.
|
|
24327
|
+
- 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.
|
|
24328
|
+
- The frame grows to fit its content. The frame page posts its height as a `PLAYGROUND_HEIGHT_MESSAGE` message.
|
|
24329
|
+
- The frame loads lazily, when it scrolls near the screen.
|
|
24330
|
+
|
|
24331
|
+
## Usage
|
|
24332
|
+
|
|
24333
|
+
```tsx
|
|
24334
|
+
import { DocumentationFrame } from "shelving/ui";
|
|
24335
|
+
|
|
24336
|
+
<DocumentationFrame code={`import { Button } from "shelving/ui";\n<Button>Hi</Button>`} css=":root { --radius-normal: 4px; }" />
|
|
24337
|
+
```
|
|
24338
|
+
|
|
24339
|
+
## Styling
|
|
24340
|
+
|
|
24341
|
+
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.
|
|
24342
|
+
|
|
24343
|
+
| Variable | Styles | Default |
|
|
24344
|
+
|---|---|---|
|
|
24345
|
+
| `--documentation-frame-background` | Fill behind the frame before it loads | `white` |
|
|
24346
|
+
| `--documentation-frame-height` | Minimum height (one length) | `4rem` |
|
|
24347
|
+
|
|
24348
|
+
|
|
24349
|
+
## Signatures
|
|
24350
|
+
|
|
24351
|
+
```ts
|
|
24352
|
+
DocumentationFrame({ code, css, title = "Preview", className }: DocumentationFrameProps): ReactElement
|
|
24353
|
+
```
|
|
24354
|
+
|
|
24355
|
+
## Parameters
|
|
24356
|
+
|
|
24357
|
+
| Param | Type | Description |
|
|
24358
|
+
| --- | --- | --- |
|
|
24359
|
+
| `props` | `DocumentationFrameProps` | |
|
|
24360
|
+
| `.title` | `string \| undefined` | Accessible title of the frame. Defaults to `"Preview"`. |
|
|
24361
|
+
|
|
24362
|
+
## Returns
|
|
24363
|
+
|
|
24364
|
+
| Type | Description |
|
|
24365
|
+
| --- | --- |
|
|
24366
|
+
| `ReactElement` | |
|
|
24367
|
+
|
|
24368
|
+
|
|
24153
24369
|
---
|
|
24154
24370
|
|
|
24155
24371
|
# DocumentationKindProps
|
|
@@ -24246,6 +24462,158 @@ DocumentationKind({ kind = "unknown", ...props }: DocumentationKindProps): React
|
|
|
24246
24462
|
```
|
|
24247
24463
|
|
|
24248
24464
|
|
|
24465
|
+
---
|
|
24466
|
+
|
|
24467
|
+
# DocumentationLiveProps
|
|
24468
|
+
|
|
24469
|
+
- Kind: interface
|
|
24470
|
+
- Import: `import { DocumentationLiveProps } from "shelving/ui";`
|
|
24471
|
+
|
|
24472
|
+
Props for `<DocumentationLive>` — the code to show and run, plus an optional title.
|
|
24473
|
+
|
|
24474
|
+
## Signatures
|
|
24475
|
+
|
|
24476
|
+
```ts
|
|
24477
|
+
{
|
|
24478
|
+
code: string;
|
|
24479
|
+
title?: string | undefined;
|
|
24480
|
+
}
|
|
24481
|
+
```
|
|
24482
|
+
|
|
24483
|
+
## Properties
|
|
24484
|
+
|
|
24485
|
+
| Property | Type | Description |
|
|
24486
|
+
| --- | --- | --- |
|
|
24487
|
+
| `code` | `string` | TSX source to show and run. It can import from `shelving/*`, `react`, and `react-dom` only. |
|
|
24488
|
+
| `title` | `string \| undefined` | Title of the example, used as the accessible title of the preview frame. Optional. |
|
|
24489
|
+
|
|
24490
|
+
|
|
24491
|
+
---
|
|
24492
|
+
|
|
24493
|
+
# DocumentationLive
|
|
24494
|
+
|
|
24495
|
+
- Kind: component
|
|
24496
|
+
- Import: `import { DocumentationLive } from "shelving/ui";`
|
|
24497
|
+
|
|
24498
|
+
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.
|
|
24499
|
+
- The preview is a `<DocumentationFrame>`, so it runs in the browser with the raw shelving styles.
|
|
24500
|
+
- 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.
|
|
24501
|
+
- The code and preview are side by side on a wide screen, and stacked on a narrow one.
|
|
24502
|
+
|
|
24503
|
+
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.
|
|
24504
|
+
|
|
24505
|
+
**Things to know:**
|
|
24506
|
+
|
|
24507
|
+
- 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.
|
|
24508
|
+
- `DOCUMENTATION_LIVE_RULE` finds these blocks. `DOCUMENTATION_MARKUP_RULES` adds it to `TREE_MARKUP_RULES`, and `<DocumentationPage>` renders its content with them.
|
|
24509
|
+
- The preview is a `<DocumentationFrame>`. It runs in the browser, with the raw shelving styles and none of the docs site styles.
|
|
24510
|
+
- The code can import from `shelving/*`, `react`, and `react-dom` only. Any other import fails.
|
|
24511
|
+
- 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.
|
|
24512
|
+
- 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.
|
|
24513
|
+
- "Open in playground" under the phone opens the code in `<DocumentationPlaygroundPage>`, where you can change it.
|
|
24514
|
+
|
|
24515
|
+
## Usage
|
|
24516
|
+
|
|
24517
|
+
### A live example in a Markdown page
|
|
24518
|
+
|
|
24519
|
+
````md
|
|
24520
|
+
```tsx live "A solid button"
|
|
24521
|
+
import { Button } from "shelving/ui";
|
|
24522
|
+
|
|
24523
|
+
<Button solid>Save</Button>
|
|
24524
|
+
```
|
|
24525
|
+
````
|
|
24526
|
+
|
|
24527
|
+
### A live example with state
|
|
24528
|
+
|
|
24529
|
+
````md
|
|
24530
|
+
```tsx live
|
|
24531
|
+
import { useState } from "react";
|
|
24532
|
+
import { Button } from "shelving/ui";
|
|
24533
|
+
|
|
24534
|
+
function Counter() {
|
|
24535
|
+
const [count, setCount] = useState(0);
|
|
24536
|
+
return <Button onClick={() => setCount(count + 1)}>Clicked {count} times</Button>;
|
|
24537
|
+
}
|
|
24538
|
+
|
|
24539
|
+
<Counter />
|
|
24540
|
+
```
|
|
24541
|
+
````
|
|
24542
|
+
|
|
24543
|
+
## Styling
|
|
24544
|
+
|
|
24545
|
+
| Variable | Styles | Default |
|
|
24546
|
+
|---|---|---|
|
|
24547
|
+
| `--documentation-live-bezel` | Space above and below the speaker slot, which sets the thickness of the top and the chin (one length) | `2.25rem` |
|
|
24548
|
+
| `--documentation-live-body` | Fill of the phone | `oklch(92% 0 0deg)` (light grey) |
|
|
24549
|
+
| `--documentation-live-detail` | Colour of the speaker slot and home button | `oklch(80% 0 0deg)` |
|
|
24550
|
+
| `--documentation-live-edge` | Width of the phone edge left and right of the screen (one length) | `0.75rem` |
|
|
24551
|
+
| `--documentation-live-gap` | Space between the code and the phone (one length) | `var(--space-normal)` (16px) |
|
|
24552
|
+
| `--documentation-live-height` | Height of the screen (one length) | `26rem` |
|
|
24553
|
+
| `--documentation-live-radius` | Corner radius of the phone | `2.5rem` |
|
|
24554
|
+
| `--documentation-live-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
|
|
24555
|
+
| `--documentation-live-width` | Width of the phone (one length) | `22rem` |
|
|
24556
|
+
|
|
24557
|
+
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.
|
|
24558
|
+
|
|
24559
|
+
|
|
24560
|
+
## Signatures
|
|
24561
|
+
|
|
24562
|
+
```ts
|
|
24563
|
+
DocumentationLive({ code, title }: DocumentationLiveProps): ReactElement
|
|
24564
|
+
```
|
|
24565
|
+
|
|
24566
|
+
## Parameters
|
|
24567
|
+
|
|
24568
|
+
| Param | Type | Description |
|
|
24569
|
+
| --- | --- | --- |
|
|
24570
|
+
| `props` | `DocumentationLiveProps` | |
|
|
24571
|
+
| `.code` | `string` | TSX source to show and run. It can import from `shelving/*`, `react`, and `react-dom` only. |
|
|
24572
|
+
| `.title` | `string \| undefined` | Title of the example, used as the accessible title of the preview frame. Optional. |
|
|
24573
|
+
|
|
24574
|
+
## Returns
|
|
24575
|
+
|
|
24576
|
+
| Type | Description |
|
|
24577
|
+
| --- | --- |
|
|
24578
|
+
| `ReactElement` | |
|
|
24579
|
+
|
|
24580
|
+
|
|
24581
|
+
---
|
|
24582
|
+
|
|
24583
|
+
# DOCUMENTATION_LIVE_RULE
|
|
24584
|
+
|
|
24585
|
+
- Kind: constant
|
|
24586
|
+
- Import: `import { DOCUMENTATION_LIVE_RULE } from "shelving/ui";`
|
|
24587
|
+
|
|
24588
|
+
Markup rule that renders a fenced code block with a `live` flag as a `<DocumentationLive>` example, e.g. ` ```tsx live "Card with a link" `.
|
|
24589
|
+
- The `live` flag must come before any quoted title (see `parseFencedInfo()` for the info string format).
|
|
24590
|
+
- 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`.
|
|
24591
|
+
|
|
24592
|
+
@see https://shelving.cc/ui/DOCUMENTATION_LIVE_RULE
|
|
24593
|
+
|
|
24594
|
+
## Signatures
|
|
24595
|
+
|
|
24596
|
+
```ts
|
|
24597
|
+
DOCUMENTATION_LIVE_RULE: MarkupRule
|
|
24598
|
+
```
|
|
24599
|
+
|
|
24600
|
+
|
|
24601
|
+
---
|
|
24602
|
+
|
|
24603
|
+
# DOCUMENTATION_MARKUP_RULES
|
|
24604
|
+
|
|
24605
|
+
- Kind: constant
|
|
24606
|
+
- Import: `import { DOCUMENTATION_MARKUP_RULES } from "shelving/ui";`
|
|
24607
|
+
|
|
24608
|
+
Markup rules for docs site content: `DOCUMENTATION_LIVE_RULE` then `TREE_MARKUP_RULES`, so fenced code blocks with a `live` flag run.
|
|
24609
|
+
|
|
24610
|
+
## Signatures
|
|
24611
|
+
|
|
24612
|
+
```ts
|
|
24613
|
+
DOCUMENTATION_MARKUP_RULES: MarkupRules
|
|
24614
|
+
```
|
|
24615
|
+
|
|
24616
|
+
|
|
24249
24617
|
---
|
|
24250
24618
|
|
|
24251
24619
|
# DocumentationPage
|
|
@@ -24408,18 +24776,20 @@ DocumentationParams({ params }: DocumentationParamsProps): ReactNode
|
|
|
24408
24776
|
|
|
24409
24777
|
---
|
|
24410
24778
|
|
|
24411
|
-
#
|
|
24779
|
+
# DocumentationPlaygroundInsertProps
|
|
24412
24780
|
|
|
24413
24781
|
- Kind: interface
|
|
24414
|
-
- Import: `import {
|
|
24782
|
+
- Import: `import { DocumentationPlaygroundInsertProps } from "shelving/ui";`
|
|
24415
24783
|
|
|
24416
|
-
Props for
|
|
24784
|
+
Props for `<DocumentationPlaygroundInsert>`.
|
|
24417
24785
|
|
|
24418
24786
|
## Signatures
|
|
24419
24787
|
|
|
24420
24788
|
```ts
|
|
24421
24789
|
{
|
|
24422
|
-
readonly
|
|
24790
|
+
readonly type: "code" | "css";
|
|
24791
|
+
readonly onInsert: (text: string) => void;
|
|
24792
|
+
readonly onClose: () => void;
|
|
24423
24793
|
}
|
|
24424
24794
|
```
|
|
24425
24795
|
|
|
@@ -24427,7 +24797,103 @@ Props for `DocumentationProperties` — the data members of a class/interface/ob
|
|
|
24427
24797
|
|
|
24428
24798
|
| Property | Type | Description |
|
|
24429
24799
|
| --- | --- | --- |
|
|
24430
|
-
| `
|
|
24800
|
+
| `type` | `"code" \| "css"` | What to list: shelving components for the TSX, or CSS variables for the CSS. Read only. |
|
|
24801
|
+
| `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. |
|
|
24802
|
+
| `onClose` | `() => void` | Called when the panel closes. It must unmount the panel. Read only. |
|
|
24803
|
+
|
|
24804
|
+
|
|
24805
|
+
---
|
|
24806
|
+
|
|
24807
|
+
# DocumentationPlaygroundInsert
|
|
24808
|
+
|
|
24809
|
+
- Kind: component
|
|
24810
|
+
- Import: `import { DocumentationPlaygroundInsert } from "shelving/ui";`
|
|
24811
|
+
|
|
24812
|
+
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.
|
|
24813
|
+
- Components come from `PLAYGROUND_COMPONENTS_PATH`, and variables from `PLAYGROUND_VARIABLES_PATH`. The docs build writes both.
|
|
24814
|
+
- Items are grouped by module, and you can search them by name or description. Hover an item to see its description.
|
|
24815
|
+
- Press an item to insert it and close the panel. A group of variables also has "Insert all", which inserts every variable in it.
|
|
24816
|
+
|
|
24817
|
+
## Signatures
|
|
24818
|
+
|
|
24819
|
+
```ts
|
|
24820
|
+
DocumentationPlaygroundInsert({ type, onInsert, onClose }: DocumentationPlaygroundInsertProps): ReactNode
|
|
24821
|
+
```
|
|
24822
|
+
|
|
24823
|
+
## Parameters
|
|
24824
|
+
|
|
24825
|
+
| Param | Type | Description |
|
|
24826
|
+
| --- | --- | --- |
|
|
24827
|
+
| `props` | `DocumentationPlaygroundInsertProps` | |
|
|
24828
|
+
| `.type` | `"code" \| "css"` | What to list: shelving components for the TSX, or CSS variables for the CSS. Read only. |
|
|
24829
|
+
| `.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. |
|
|
24830
|
+
| `.onClose` | `() => void` | Called when the panel closes. It must unmount the panel. Read only. |
|
|
24831
|
+
|
|
24832
|
+
## Returns
|
|
24833
|
+
|
|
24834
|
+
| Type | Description |
|
|
24835
|
+
| --- | --- |
|
|
24836
|
+
| `ReactNode` | |
|
|
24837
|
+
|
|
24838
|
+
|
|
24839
|
+
---
|
|
24840
|
+
|
|
24841
|
+
# DocumentationPlaygroundPage
|
|
24842
|
+
|
|
24843
|
+
- Kind: component
|
|
24844
|
+
- Import: `import { DocumentationPlaygroundPage } from "shelving/ui";`
|
|
24845
|
+
|
|
24846
|
+
Page where you can write TSX and CSS and see the result run live, like the TypeScript Playground.
|
|
24847
|
+
- It fills the whole window: the editor is on the left, in a grey panel, and the preview fills the right.
|
|
24848
|
+
- Drag the edge between them (or focus it and press the arrow keys) to change their widths.
|
|
24849
|
+
- The TSX tab holds code that can import from `shelving/*`, `react`, and `react-dom`. Its top-level expressions are shown in the preview.
|
|
24850
|
+
- The CSS tab holds CSS that is added after the shelving styles, so you can change any shelving variable.
|
|
24851
|
+
- 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.
|
|
24852
|
+
- The code and CSS are saved in the URL hash on every change, so the address is always a link to what you made.
|
|
24853
|
+
- The preview is a `<DocumentationFrame>`, so it uses the raw shelving styles and not the docs site styles.
|
|
24854
|
+
- It has no sidebar of its own. `<DocumentationApp>` renders it outside its `<SidebarLayout>`.
|
|
24855
|
+
|
|
24856
|
+
## Signatures
|
|
24857
|
+
|
|
24858
|
+
```ts
|
|
24859
|
+
DocumentationPlaygroundPage(): ReactNode
|
|
24860
|
+
```
|
|
24861
|
+
|
|
24862
|
+
## Returns
|
|
24863
|
+
|
|
24864
|
+
| Type | Description |
|
|
24865
|
+
| --- | --- |
|
|
24866
|
+
| `ReactNode` | |
|
|
24867
|
+
|
|
24868
|
+
## Examples
|
|
24869
|
+
|
|
24870
|
+
```ts
|
|
24871
|
+
<Router routes={{ "/playground": DocumentationPlaygroundPage }} />
|
|
24872
|
+
```
|
|
24873
|
+
|
|
24874
|
+
|
|
24875
|
+
---
|
|
24876
|
+
|
|
24877
|
+
# DocumentationPropertiesProps
|
|
24878
|
+
|
|
24879
|
+
- Kind: interface
|
|
24880
|
+
- Import: `import { DocumentationPropertiesProps } from "shelving/ui";`
|
|
24881
|
+
|
|
24882
|
+
Props for `DocumentationProperties` — the data members of a class/interface/object-literal type to render, one row each.
|
|
24883
|
+
|
|
24884
|
+
## Signatures
|
|
24885
|
+
|
|
24886
|
+
```ts
|
|
24887
|
+
{
|
|
24888
|
+
readonly properties?: ImmutableArray<DocumentationParam> | undefined;
|
|
24889
|
+
}
|
|
24890
|
+
```
|
|
24891
|
+
|
|
24892
|
+
## Properties
|
|
24893
|
+
|
|
24894
|
+
| Property | Type | Description |
|
|
24895
|
+
| --- | --- | --- |
|
|
24896
|
+
| `properties` | `ImmutableArray<DocumentationParam> \| undefined` | Properties to render — one row each. Read only. Optional. |
|
|
24431
24897
|
|
|
24432
24898
|
|
|
24433
24899
|
---
|
|
@@ -24840,6 +25306,353 @@ DocumentationType({ members }: DocumentationTypeProps): ReactNode
|
|
|
24840
25306
|
```
|
|
24841
25307
|
|
|
24842
25308
|
|
|
25309
|
+
---
|
|
25310
|
+
|
|
25311
|
+
# PlaygroundCode
|
|
25312
|
+
|
|
25313
|
+
- Kind: interface
|
|
25314
|
+
- Import: `import { PlaygroundCode } from "shelving/ui";`
|
|
25315
|
+
|
|
25316
|
+
Code and CSS that the playground frame runs.
|
|
25317
|
+
|
|
25318
|
+
## Signatures
|
|
25319
|
+
|
|
25320
|
+
```ts
|
|
25321
|
+
{
|
|
25322
|
+
readonly code?: string | undefined;
|
|
25323
|
+
readonly css?: string | undefined;
|
|
25324
|
+
}
|
|
25325
|
+
```
|
|
25326
|
+
|
|
25327
|
+
## Properties
|
|
25328
|
+
|
|
25329
|
+
| Property | Type | Description |
|
|
25330
|
+
| --- | --- | --- |
|
|
25331
|
+
| `code` | `string \| undefined` | TSX source to run. It can import from `shelving/*`, `react`, and `react-dom` only. Read only. Optional. |
|
|
25332
|
+
| `css` | `string \| undefined` | CSS to add after the shelving styles. Read only. Optional. |
|
|
25333
|
+
|
|
25334
|
+
|
|
25335
|
+
---
|
|
25336
|
+
|
|
25337
|
+
# PLAYGROUND_FRAME_PATH
|
|
25338
|
+
|
|
25339
|
+
- Kind: constant
|
|
25340
|
+
- Import: `import { PLAYGROUND_FRAME_PATH } from "shelving/ui";`
|
|
25341
|
+
|
|
25342
|
+
Path of the frame page that runs playground code, relative to the docs site root.
|
|
25343
|
+
|
|
25344
|
+
|
|
25345
|
+
---
|
|
25346
|
+
|
|
25347
|
+
# PLAYGROUND_PAGE_PATH
|
|
25348
|
+
|
|
25349
|
+
- Kind: constant
|
|
25350
|
+
- Import: `import { PLAYGROUND_PAGE_PATH } from "shelving/ui";`
|
|
25351
|
+
|
|
25352
|
+
Path of the playground page, relative to the docs site root.
|
|
25353
|
+
|
|
25354
|
+
|
|
25355
|
+
---
|
|
25356
|
+
|
|
25357
|
+
# PLAYGROUND_HEIGHT_MESSAGE
|
|
25358
|
+
|
|
25359
|
+
- Kind: constant
|
|
25360
|
+
- Import: `import { PLAYGROUND_HEIGHT_MESSAGE } from "shelving/ui";`
|
|
25361
|
+
|
|
25362
|
+
Type of the message that the frame page posts to its parent with its content height, e.g. `{ type: PLAYGROUND_HEIGHT_MESSAGE, height: 320 }`.
|
|
25363
|
+
|
|
25364
|
+
|
|
25365
|
+
---
|
|
25366
|
+
|
|
25367
|
+
# formatPlaygroundHash()
|
|
25368
|
+
|
|
25369
|
+
- Kind: function
|
|
25370
|
+
- Import: `import { formatPlaygroundHash } from "shelving/ui";`
|
|
25371
|
+
|
|
25372
|
+
Format code and CSS as a URL hash for the playground page or its frame, e.g. `#code=…&css=…`.
|
|
25373
|
+
- Each value is UTF-8 then Base64URL encoded, so the same input always gives the same hash (on the server and in the browser).
|
|
25374
|
+
- Empty values are left out, and an empty input gives `""`.
|
|
25375
|
+
|
|
25376
|
+
## Signatures
|
|
25377
|
+
|
|
25378
|
+
```ts
|
|
25379
|
+
formatPlaygroundHash({ code, css }: PlaygroundCode): string
|
|
25380
|
+
```
|
|
25381
|
+
|
|
25382
|
+
## Parameters
|
|
25383
|
+
|
|
25384
|
+
| Param | Type | Description |
|
|
25385
|
+
| --- | --- | --- |
|
|
25386
|
+
| `options` | `PlaygroundCode` | |
|
|
25387
|
+
| `.code` | `string \| undefined` | TSX source to run. It can import from `shelving/*`, `react`, and `react-dom` only. Read only. Optional. |
|
|
25388
|
+
| `.css` | `string \| undefined` | CSS to add after the shelving styles. Read only. Optional. |
|
|
25389
|
+
|
|
25390
|
+
## Returns
|
|
25391
|
+
|
|
25392
|
+
| Type | Description |
|
|
25393
|
+
| --- | --- |
|
|
25394
|
+
| `string` | The hash, with its leading `#`, or `""` if there is nothing to put in it. |
|
|
25395
|
+
|
|
25396
|
+
## Examples
|
|
25397
|
+
|
|
25398
|
+
```ts
|
|
25399
|
+
formatPlaygroundHash({ code: "<Button>Hi</Button>" }) // "#code=PEJ1dHRvbj5IaTwvQnV0dG9uPg"
|
|
25400
|
+
```
|
|
25401
|
+
|
|
25402
|
+
|
|
25403
|
+
---
|
|
25404
|
+
|
|
25405
|
+
# parsePlaygroundHash()
|
|
25406
|
+
|
|
25407
|
+
- Kind: function
|
|
25408
|
+
- Import: `import { parsePlaygroundHash } from "shelving/ui";`
|
|
25409
|
+
|
|
25410
|
+
Parse a URL hash made by `formatPlaygroundHash()` back into code and CSS.
|
|
25411
|
+
- Values that are missing or not valid Base64URL are left out.
|
|
25412
|
+
|
|
25413
|
+
## Signatures
|
|
25414
|
+
|
|
25415
|
+
```ts
|
|
25416
|
+
parsePlaygroundHash(hash: string): PlaygroundCode
|
|
25417
|
+
```
|
|
25418
|
+
|
|
25419
|
+
## Parameters
|
|
25420
|
+
|
|
25421
|
+
| Param | Type | Description |
|
|
25422
|
+
| --- | --- | --- |
|
|
25423
|
+
| `hash` | `string` | The hash to parse, with or without its leading `#`. |
|
|
25424
|
+
|
|
25425
|
+
## Returns
|
|
25426
|
+
|
|
25427
|
+
| Type | Description |
|
|
25428
|
+
| --- | --- |
|
|
25429
|
+
| `PlaygroundCode` | The code and CSS in the hash. |
|
|
25430
|
+
|
|
25431
|
+
## Examples
|
|
25432
|
+
|
|
25433
|
+
```ts
|
|
25434
|
+
parsePlaygroundHash("#code=PEJ1dHRvbj5IaTwvQnV0dG9uPg") // { code: "<Button>Hi</Button>" }
|
|
25435
|
+
```
|
|
25436
|
+
|
|
25437
|
+
|
|
25438
|
+
---
|
|
25439
|
+
|
|
25440
|
+
# PLAYGROUND_VARIABLES_PATH
|
|
25441
|
+
|
|
25442
|
+
- Kind: constant
|
|
25443
|
+
- Import: `import { PLAYGROUND_VARIABLES_PATH } from "shelving/ui";`
|
|
25444
|
+
|
|
25445
|
+
Path of the CSS variable index that the docs build writes, relative to the docs site root.
|
|
25446
|
+
- It holds a list of `PlaygroundVariableGroup` objects.
|
|
25447
|
+
|
|
25448
|
+
|
|
25449
|
+
---
|
|
25450
|
+
|
|
25451
|
+
# PlaygroundVariable
|
|
25452
|
+
|
|
25453
|
+
- Kind: interface
|
|
25454
|
+
- Import: `import { PlaygroundVariable } from "shelving/ui";`
|
|
25455
|
+
|
|
25456
|
+
One CSS variable that you can set to change the look of shelving components.
|
|
25457
|
+
|
|
25458
|
+
## Signatures
|
|
25459
|
+
|
|
25460
|
+
```ts
|
|
25461
|
+
{
|
|
25462
|
+
readonly name: string;
|
|
25463
|
+
readonly value: string;
|
|
25464
|
+
readonly description?: string | undefined;
|
|
25465
|
+
}
|
|
25466
|
+
```
|
|
25467
|
+
|
|
25468
|
+
## Properties
|
|
25469
|
+
|
|
25470
|
+
| Property | Type | Description |
|
|
25471
|
+
| --- | --- | --- |
|
|
25472
|
+
| `name` | `string` | Name of the variable, e.g. `"--card-background"`. Read only. |
|
|
25473
|
+
| `value` | `string` | Default value of the variable, e.g. `"var(--tint-90)"`. Read only. |
|
|
25474
|
+
| `description` | `string \| undefined` | What the variable styles, e.g. `"Surface fill"`. Read only. Optional. |
|
|
25475
|
+
|
|
25476
|
+
|
|
25477
|
+
---
|
|
25478
|
+
|
|
25479
|
+
# PlaygroundVariableGroup
|
|
25480
|
+
|
|
25481
|
+
- Kind: interface
|
|
25482
|
+
- Import: `import { PlaygroundVariableGroup } from "shelving/ui";`
|
|
25483
|
+
|
|
25484
|
+
A group of CSS variables that one CSS module owns, e.g. the `--card-*` variables of `Card.module.css`.
|
|
25485
|
+
|
|
25486
|
+
## Signatures
|
|
25487
|
+
|
|
25488
|
+
```ts
|
|
25489
|
+
{
|
|
25490
|
+
readonly name: string;
|
|
25491
|
+
readonly tokens?: boolean | undefined;
|
|
25492
|
+
readonly variables: readonly PlaygroundVariable[];
|
|
25493
|
+
}
|
|
25494
|
+
```
|
|
25495
|
+
|
|
25496
|
+
## Properties
|
|
25497
|
+
|
|
25498
|
+
| Property | Type | Description |
|
|
25499
|
+
| --- | --- | --- |
|
|
25500
|
+
| `name` | `string` | Name of the group, e.g. `"Card"`. Read only. |
|
|
25501
|
+
| `tokens` | `boolean \| undefined` | Whether the group holds global design tokens (from the `style/` modules), not hooks for one component. Read only. Optional. |
|
|
25502
|
+
| `variables` | `readonly PlaygroundVariable[]` | The variables in the group. Read only. |
|
|
25503
|
+
|
|
25504
|
+
|
|
25505
|
+
---
|
|
25506
|
+
|
|
25507
|
+
# formatPlaygroundCSS()
|
|
25508
|
+
|
|
25509
|
+
- Kind: function
|
|
25510
|
+
- Import: `import { formatPlaygroundCSS } from "shelving/ui";`
|
|
25511
|
+
|
|
25512
|
+
Format CSS variables as a `:root` rule that you can paste into the playground CSS and change.
|
|
25513
|
+
- Each variable is set to its default value, with its description as a comment.
|
|
25514
|
+
|
|
25515
|
+
## Signatures
|
|
25516
|
+
|
|
25517
|
+
```ts
|
|
25518
|
+
formatPlaygroundCSS(variables: readonly PlaygroundVariable[]): string
|
|
25519
|
+
```
|
|
25520
|
+
|
|
25521
|
+
## Parameters
|
|
25522
|
+
|
|
25523
|
+
| Param | Type | Description |
|
|
25524
|
+
| --- | --- | --- |
|
|
25525
|
+
| `variables` | `readonly PlaygroundVariable[]` | The variables to put in the rule. |
|
|
25526
|
+
|
|
25527
|
+
## Returns
|
|
25528
|
+
|
|
25529
|
+
| Type | Description |
|
|
25530
|
+
| --- | --- |
|
|
25531
|
+
| `string` | The CSS rule, or `""` if there are no variables. |
|
|
25532
|
+
|
|
25533
|
+
## Examples
|
|
25534
|
+
|
|
25535
|
+
```ts
|
|
25536
|
+
formatPlaygroundCSS([{ name: "--card-radius", value: "var(--radius-normal)" }]) // ":root {\n --card-radius: var(--radius-normal);\n}\n"
|
|
25537
|
+
```
|
|
25538
|
+
|
|
25539
|
+
|
|
25540
|
+
---
|
|
25541
|
+
|
|
25542
|
+
# PLAYGROUND_COMPONENTS_PATH
|
|
25543
|
+
|
|
25544
|
+
- Kind: constant
|
|
25545
|
+
- Import: `import { PLAYGROUND_COMPONENTS_PATH } from "shelving/ui";`
|
|
25546
|
+
|
|
25547
|
+
Path of the component index that the docs build writes, relative to the docs site root.
|
|
25548
|
+
- It holds a list of `PlaygroundComponent` objects.
|
|
25549
|
+
|
|
25550
|
+
|
|
25551
|
+
---
|
|
25552
|
+
|
|
25553
|
+
# PlaygroundComponent
|
|
25554
|
+
|
|
25555
|
+
- Kind: interface
|
|
25556
|
+
- Import: `import { PlaygroundComponent } from "shelving/ui";`
|
|
25557
|
+
|
|
25558
|
+
One shelving component that you can insert into the playground code.
|
|
25559
|
+
|
|
25560
|
+
## Signatures
|
|
25561
|
+
|
|
25562
|
+
```ts
|
|
25563
|
+
{
|
|
25564
|
+
readonly name: string;
|
|
25565
|
+
readonly group: string;
|
|
25566
|
+
readonly description?: string | undefined;
|
|
25567
|
+
readonly snippet: string;
|
|
25568
|
+
}
|
|
25569
|
+
```
|
|
25570
|
+
|
|
25571
|
+
## Properties
|
|
25572
|
+
|
|
25573
|
+
| Property | Type | Description |
|
|
25574
|
+
| --- | --- | --- |
|
|
25575
|
+
| `name` | `string` | Name of the component, e.g. `"Button"`. Read only. |
|
|
25576
|
+
| `group` | `string` | Name of the group the component is in, e.g. `"block"` or `"form"`. Read only. |
|
|
25577
|
+
| `description` | `string \| undefined` | First line of the component's docblock. Read only. Optional. |
|
|
25578
|
+
| `snippet` | `string` | TSX to insert, with its imports, e.g. `import { Button } from "shelving/ui";\n\n<Button>Save</Button>`. Read only. |
|
|
25579
|
+
|
|
25580
|
+
|
|
25581
|
+
---
|
|
25582
|
+
|
|
25583
|
+
# insertPlaygroundSnippet()
|
|
25584
|
+
|
|
25585
|
+
- Kind: function
|
|
25586
|
+
- Import: `import { insertPlaygroundSnippet } from "shelving/ui";`
|
|
25587
|
+
|
|
25588
|
+
Insert a TSX snippet into playground code, and merge the snippet's imports into the code's imports.
|
|
25589
|
+
- The snippet body goes on its own lines at `at` (or at the end of the code).
|
|
25590
|
+
- 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.
|
|
25591
|
+
|
|
25592
|
+
## Signatures
|
|
25593
|
+
|
|
25594
|
+
```ts
|
|
25595
|
+
insertPlaygroundSnippet(code: string, snippet: string, at?: number | undefined): string
|
|
25596
|
+
```
|
|
25597
|
+
|
|
25598
|
+
## Parameters
|
|
25599
|
+
|
|
25600
|
+
| Param | Type | Description |
|
|
25601
|
+
| --- | --- | --- |
|
|
25602
|
+
| `code` | `string` | The playground code. |
|
|
25603
|
+
| `snippet` | `string` | The TSX snippet to insert, e.g. `PlaygroundComponent.snippet`. |
|
|
25604
|
+
| `at` | `number \| undefined` | The cursor position in `code`, e.g. the `selectionStart` of the text box. Optional. |
|
|
25605
|
+
|
|
25606
|
+
## Returns
|
|
25607
|
+
|
|
25608
|
+
| Type | Description |
|
|
25609
|
+
| --- | --- |
|
|
25610
|
+
| `string` | The new code. |
|
|
25611
|
+
|
|
25612
|
+
## Examples
|
|
25613
|
+
|
|
25614
|
+
```ts
|
|
25615
|
+
insertPlaygroundSnippet("", 'import { Button } from "shelving/ui";\n\n<Button>Hi</Button>') // 'import { Button } from "shelving/ui";\n\n<Button>Hi</Button>\n'
|
|
25616
|
+
```
|
|
25617
|
+
|
|
25618
|
+
|
|
25619
|
+
---
|
|
25620
|
+
|
|
25621
|
+
# insertPlaygroundText()
|
|
25622
|
+
|
|
25623
|
+
- Kind: function
|
|
25624
|
+
- Import: `import { insertPlaygroundText } from "shelving/ui";`
|
|
25625
|
+
|
|
25626
|
+
Insert text on its own lines into playground code or CSS.
|
|
25627
|
+
- With no `at`, CSS (text that ends with a `}`) gets the text before its last `}`, and other text gets it at the end.
|
|
25628
|
+
|
|
25629
|
+
## Signatures
|
|
25630
|
+
|
|
25631
|
+
```ts
|
|
25632
|
+
insertPlaygroundText(text: string, insert: string, at?: number | undefined): string
|
|
25633
|
+
```
|
|
25634
|
+
|
|
25635
|
+
## Parameters
|
|
25636
|
+
|
|
25637
|
+
| Param | Type | Description |
|
|
25638
|
+
| --- | --- | --- |
|
|
25639
|
+
| `text` | `string` | The code or CSS. |
|
|
25640
|
+
| `insert` | `string` | The text to insert. |
|
|
25641
|
+
| `at` | `number \| undefined` | The cursor position in `text`, e.g. the `selectionStart` of the text box. Optional. |
|
|
25642
|
+
|
|
25643
|
+
## Returns
|
|
25644
|
+
|
|
25645
|
+
| Type | Description |
|
|
25646
|
+
| --- | --- |
|
|
25647
|
+
| `string` | The new text. |
|
|
25648
|
+
|
|
25649
|
+
## Examples
|
|
25650
|
+
|
|
25651
|
+
```ts
|
|
25652
|
+
insertPlaygroundText("a\n", "b") // "a\nb\n"
|
|
25653
|
+
```
|
|
25654
|
+
|
|
25655
|
+
|
|
24843
25656
|
---
|
|
24844
25657
|
|
|
24845
25658
|
# FieldProps
|
|
@@ -25858,7 +26671,7 @@ A continuous horizontal progress bar for the completion of a task. Rendered as a
|
|
|
25858
26671
|
|
|
25859
26672
|
### Basic
|
|
25860
26673
|
|
|
25861
|
-
```tsx
|
|
26674
|
+
```tsx live
|
|
25862
26675
|
import { Progress } from "shelving/ui";
|
|
25863
26676
|
|
|
25864
26677
|
// 75% full.
|
|
@@ -25867,7 +26680,7 @@ import { Progress } from "shelving/ui";
|
|
|
25867
26680
|
|
|
25868
26681
|
### Custom range
|
|
25869
26682
|
|
|
25870
|
-
```tsx
|
|
26683
|
+
```tsx live
|
|
25871
26684
|
import { Progress } from "shelving/ui";
|
|
25872
26685
|
|
|
25873
26686
|
// 50% full — value 15 within the 10–20 range.
|
|
@@ -25876,7 +26689,7 @@ import { Progress } from "shelving/ui";
|
|
|
25876
26689
|
|
|
25877
26690
|
### Status and colour
|
|
25878
26691
|
|
|
25879
|
-
```tsx
|
|
26692
|
+
```tsx live
|
|
25880
26693
|
import { Progress } from "shelving/ui";
|
|
25881
26694
|
|
|
25882
26695
|
<Progress value={90} status="success" />
|
|
@@ -25886,7 +26699,7 @@ import { Progress } from "shelving/ui";
|
|
|
25886
26699
|
|
|
25887
26700
|
### Indeterminate
|
|
25888
26701
|
|
|
25889
|
-
```tsx
|
|
26702
|
+
```tsx live
|
|
25890
26703
|
import { Progress } from "shelving/ui";
|
|
25891
26704
|
|
|
25892
26705
|
// No `value` → looping flow animation for a task of unknown duration.
|
|
@@ -26017,7 +26830,7 @@ import { Code, Keyboard, Sample } from "shelving/ui";
|
|
|
26017
26830
|
|
|
26018
26831
|
### Plain (no background)
|
|
26019
26832
|
|
|
26020
|
-
```tsx
|
|
26833
|
+
```tsx live
|
|
26021
26834
|
import { Code } from "shelving/ui";
|
|
26022
26835
|
|
|
26023
26836
|
<Code plain>const x = 1;</Code>
|
|
@@ -26099,7 +26912,7 @@ Deleted text — renders a `<del>` element to mark content that has been removed
|
|
|
26099
26912
|
|
|
26100
26913
|
### Marking a removed value
|
|
26101
26914
|
|
|
26102
|
-
```tsx
|
|
26915
|
+
```tsx live
|
|
26103
26916
|
import { Paragraph, Deleted, Inserted } from "shelving/ui";
|
|
26104
26917
|
|
|
26105
26918
|
<Paragraph>
|
|
@@ -26183,7 +26996,7 @@ Emphasised text — renders an `<em>` element for stress emphasis, the kind that
|
|
|
26183
26996
|
|
|
26184
26997
|
### Stress emphasis in body copy
|
|
26185
26998
|
|
|
26186
|
-
```tsx
|
|
26999
|
+
```tsx live
|
|
26187
27000
|
import { Paragraph, Emphasis } from "shelving/ui";
|
|
26188
27001
|
|
|
26189
27002
|
<Paragraph>
|
|
@@ -26263,7 +27076,7 @@ Inserted text — renders an `<ins>` element to mark content that has been added
|
|
|
26263
27076
|
|
|
26264
27077
|
### Marking an added value
|
|
26265
27078
|
|
|
26266
|
-
```tsx
|
|
27079
|
+
```tsx live
|
|
26267
27080
|
import { Paragraph, Deleted, Inserted } from "shelving/ui";
|
|
26268
27081
|
|
|
26269
27082
|
<Paragraph>
|
|
@@ -26357,7 +27170,7 @@ An inline link or action. Delegates to `<Clickable>`, rendering an `<a>` when `h
|
|
|
26357
27170
|
|
|
26358
27171
|
### Link inside body copy
|
|
26359
27172
|
|
|
26360
|
-
```tsx
|
|
27173
|
+
```tsx live
|
|
26361
27174
|
import { Paragraph, Link } from "shelving/ui";
|
|
26362
27175
|
|
|
26363
27176
|
<Paragraph>
|
|
@@ -26367,7 +27180,7 @@ import { Paragraph, Link } from "shelving/ui";
|
|
|
26367
27180
|
|
|
26368
27181
|
### Action button
|
|
26369
27182
|
|
|
26370
|
-
```tsx
|
|
27183
|
+
```tsx live
|
|
26371
27184
|
import { Link } from "shelving/ui";
|
|
26372
27185
|
|
|
26373
27186
|
<Link onClick={() => save()}>Save now</Link>
|
|
@@ -26375,7 +27188,7 @@ import { Link } from "shelving/ui";
|
|
|
26375
27188
|
|
|
26376
27189
|
### Plain link around a block
|
|
26377
27190
|
|
|
26378
|
-
```tsx
|
|
27191
|
+
```tsx live
|
|
26379
27192
|
import { Link, Row, Span } from "shelving/ui";
|
|
26380
27193
|
|
|
26381
27194
|
<Link plain href="/jane">
|
|
@@ -26456,7 +27269,7 @@ Highlighted text — renders a `<mark>` element to call attention to a run of te
|
|
|
26456
27269
|
|
|
26457
27270
|
### Highlighted search term
|
|
26458
27271
|
|
|
26459
|
-
```tsx
|
|
27272
|
+
```tsx live
|
|
26460
27273
|
import { Mark } from "shelving/ui";
|
|
26461
27274
|
|
|
26462
27275
|
<p>Files are stored in <Mark>UTF-8</Mark> encoding.</p>
|
|
@@ -26534,7 +27347,7 @@ Small print — renders a `<small>` element for side comments and fine print suc
|
|
|
26534
27347
|
|
|
26535
27348
|
### Fine print after a statement
|
|
26536
27349
|
|
|
26537
|
-
```tsx
|
|
27350
|
+
```tsx live
|
|
26538
27351
|
import { Paragraph, Small } from "shelving/ui";
|
|
26539
27352
|
|
|
26540
27353
|
<Paragraph>
|
|
@@ -26618,7 +27431,7 @@ Styled inline text — renders a `<span>` element that carries only the colour a
|
|
|
26618
27431
|
|
|
26619
27432
|
### Applying typography variants
|
|
26620
27433
|
|
|
26621
|
-
```tsx
|
|
27434
|
+
```tsx live
|
|
26622
27435
|
import { Span } from "shelving/ui";
|
|
26623
27436
|
|
|
26624
27437
|
<p>Total <Span weight="strong">$35.00</Span> due today.</p>
|
|
@@ -26627,7 +27440,7 @@ import { Span } from "shelving/ui";
|
|
|
26627
27440
|
|
|
26628
27441
|
### Colouring a run of text
|
|
26629
27442
|
|
|
26630
|
-
```tsx
|
|
27443
|
+
```tsx live
|
|
26631
27444
|
import { Span } from "shelving/ui";
|
|
26632
27445
|
|
|
26633
27446
|
<Span color="purple" tint="40">on-brand accent</Span>
|
|
@@ -26701,7 +27514,7 @@ Strong importance — renders a `<strong>` element for text that carries strong
|
|
|
26701
27514
|
|
|
26702
27515
|
### Strong importance in body copy
|
|
26703
27516
|
|
|
26704
|
-
```tsx
|
|
27517
|
+
```tsx live
|
|
26705
27518
|
import { Paragraph, Strong } from "shelving/ui";
|
|
26706
27519
|
|
|
26707
27520
|
<Paragraph>
|
|
@@ -28855,7 +29668,7 @@ The shared value-input prop contract (`ValueInputProps<O>`):
|
|
|
28855
29668
|
|
|
28856
29669
|
### Dispatch on a single schema
|
|
28857
29670
|
|
|
28858
|
-
```tsx
|
|
29671
|
+
```tsx live
|
|
28859
29672
|
import { SchemaInput } from "shelving/ui";
|
|
28860
29673
|
import { StringSchema, NumberSchema } from "shelving/schema";
|
|
28861
29674
|
|
|
@@ -29856,7 +30669,7 @@ A `<menu>` list of `<MenuItem>` children — the container for URL-aware navigat
|
|
|
29856
30669
|
|
|
29857
30670
|
## Usage
|
|
29858
30671
|
|
|
29859
|
-
```tsx
|
|
30672
|
+
```tsx live
|
|
29860
30673
|
import { Menu, MenuItem } from "shelving/ui";
|
|
29861
30674
|
|
|
29862
30675
|
<Menu>
|
|
@@ -29964,7 +30777,7 @@ A single `<li>` link entry inside a `<Menu>`. It reads the current page URL from
|
|
|
29964
30777
|
|
|
29965
30778
|
## Usage
|
|
29966
30779
|
|
|
29967
|
-
```tsx
|
|
30780
|
+
```tsx live
|
|
29968
30781
|
import { Menu, MenuItem } from "shelving/ui";
|
|
29969
30782
|
|
|
29970
30783
|
<Menu>
|
|
@@ -29981,7 +30794,7 @@ import { Menu, MenuItem } from "shelving/ui";
|
|
|
29981
30794
|
|
|
29982
30795
|
### Small items
|
|
29983
30796
|
|
|
29984
|
-
```tsx
|
|
30797
|
+
```tsx live
|
|
29985
30798
|
import { Menu, MenuItem } from "shelving/ui";
|
|
29986
30799
|
|
|
29987
30800
|
// One small item.
|
|
@@ -30321,7 +31134,7 @@ Renders an icon for a given status, coloured to match. Picks an icon per status
|
|
|
30321
31134
|
|
|
30322
31135
|
## Usage
|
|
30323
31136
|
|
|
30324
|
-
```tsx
|
|
31137
|
+
```tsx live
|
|
30325
31138
|
import { Icon } from "shelving/ui";
|
|
30326
31139
|
|
|
30327
31140
|
<Icon status="success" size="large" />
|
|
@@ -30961,7 +31774,7 @@ A small inline label used to annotate other content. Accepts a status variant or
|
|
|
30961
31774
|
|
|
30962
31775
|
## Usage
|
|
30963
31776
|
|
|
30964
|
-
```tsx
|
|
31777
|
+
```tsx live
|
|
30965
31778
|
import { Tag } from "shelving/ui";
|
|
30966
31779
|
|
|
30967
31780
|
<Tag success>Active</Tag>
|
|
@@ -31051,7 +31864,7 @@ Message for a list with nothing in it. `<Empty>` shows its content centred and g
|
|
|
31051
31864
|
|
|
31052
31865
|
### Empty list
|
|
31053
31866
|
|
|
31054
|
-
```tsx
|
|
31867
|
+
```tsx live
|
|
31055
31868
|
import { Empty, Paragraph } from "shelving/ui";
|
|
31056
31869
|
|
|
31057
31870
|
<Empty>
|
|
@@ -31197,7 +32010,7 @@ A block-level status callout with an icon and message, used to highlight feedbac
|
|
|
31197
32010
|
|
|
31198
32011
|
## Usage
|
|
31199
32012
|
|
|
31200
|
-
```tsx
|
|
32013
|
+
```tsx live
|
|
31201
32014
|
import { Notice } from "shelving/ui";
|
|
31202
32015
|
|
|
31203
32016
|
<Notice status="success">Your changes have been saved.</Notice>
|
|
@@ -34499,7 +35312,7 @@ A data table — renders a `<table>`. Compose the usual `<thead>` / `<tbody>` /
|
|
|
34499
35312
|
|
|
34500
35313
|
### Basic table
|
|
34501
35314
|
|
|
34502
|
-
```tsx
|
|
35315
|
+
```tsx live
|
|
34503
35316
|
import { Table } from "shelving/ui";
|
|
34504
35317
|
|
|
34505
35318
|
<Table>
|
|
@@ -34515,7 +35328,7 @@ import { Table } from "shelving/ui";
|
|
|
34515
35328
|
|
|
34516
35329
|
### Cell padding
|
|
34517
35330
|
|
|
34518
|
-
```tsx
|
|
35331
|
+
```tsx live
|
|
34519
35332
|
import { Button, Cell, Table } from "shelving/ui";
|
|
34520
35333
|
|
|
34521
35334
|
<Table padding="small">
|