@tenphi/cookbook 0.26.0 → 0.28.0

package/docs/authoring.mdx

@@ -154,6 +154,95 @@ shows each inlined file as a `<script src>` tag. Every preview embeds its own
 copy, so keep demo bundles small. A missing file or a path outside the public
 directory fails the build.
 
+A preview that runs scripts, with `javascript` or `scripts`, fits its frame to
+its content. The frame grows and shrinks as the content changes, the page
+width changes, or fonts load. It is at least `10rem` tall and at most as tall
+as the browser window; taller content scrolls inside the frame. A preview
+without scripts keeps a `10rem` frame, and content beyond it scrolls.
+
+```mdx
+<Preview
+  title="Growing list"
+  html={'<button type="button">Add item</button><ol></ol>'}
+  javascript={
+    "document.querySelector('button').addEventListener('click', () => document.querySelector('ol').append(document.createElement('li')));"
+  }
+/>
+```
+
+<Preview
+  title="Growing list"
+  html={'<button type="button">Add item</button><ol></ol>'}
+  javascript={
+    "document.querySelector('button').addEventListener('click', () => document.querySelector('ol').append(document.createElement('li')));"
+  }
+/>
+
+The frame fits the content in the document's flow. An overlay, such as a
+listbox, a popover, a modal dialog, or an absolutely positioned menu, doesn't
+make it taller when it opens, so reserve room for it:
+
+- `buffer` adds room below the content for a picker's list, such as a select's
+  or a combobox's. The room follows the content as the page width changes it.
+  It defaults to `0`. A preview without scripts can't measure its content, so
+  `buffer` has no effect there.
+- `height` sets the frame's minimum height in place of `10rem`, for an overlay
+  that uses the whole frame, such as a modal dialog. It also applies to
+  previews without scripts.
+
+The frame is as tall as the content plus `buffer`, up to the window's height,
+and never shorter than `height`. Both take a CSS length, such as `12rem` or `320px`; any other value, including
+a percentage or `calc()`, fails the build. To change every preview, style
+`theme.styles.Preview.Frame` instead.
+
+```mdx
+<Preview
+  title="Library select"
+  buffer="15rem"
+  html={"<acme-select label='Fruit'></acme-select>"}
+  scripts={["/demo/select.js"]}
+/>
+
+<Preview
+  title="Library dialog"
+  height="24rem"
+  html={"<acme-dialog open>Saved</acme-dialog>"}
+  scripts={["/demo/dialog.js"]}
+/>
+```
+
+Don't size the content by the frame, for example with `100vh` or
+`height: 100%` on the root element: the frame can't fit such content, and it
+can grow to the window's height.
+
+Forms in a preview can be submitted. To show what a form sends, call
+`event.preventDefault()` in a `submit` listener and read its `FormData`;
+otherwise the submission navigates the frame away from the demo. The
+documentation page itself is never navigated, and the frame keeps its separate
+origin.
+
+```mdx
+<Preview
+  title="Form data"
+  html={
+    '<form><label>Name <input name="name" value="Ada"></label> <button>Send</button></form><output></output>'
+  }
+  javascript={
+    "document.querySelector('form').addEventListener('submit', (event) => { event.preventDefault(); document.querySelector('output').value = JSON.stringify(Object.fromEntries(new FormData(event.target))); });"
+  }
+/>
+```
+
+<Preview
+  title="Form data"
+  html={
+    '<form><label>Name <input name="name" value="Ada"></label> <button>Send</button></form><output></output>'
+  }
+  javascript={
+    "document.querySelector('form').addEventListener('submit', (event) => { event.preventDefault(); document.querySelector('output').value = JSON.stringify(Object.fromEntries(new FormData(event.target))); });"
+  }
+/>
+
 ## Cookbook logo
 
 `Logo` renders the Cookbook mark. Use `label` when it carries meaning or
@@ -173,12 +262,12 @@ markers remain visible independently of their theme-aware backgrounds:
 
 ## Component props
 
-| Component | Props and behavior                                                                                                         |
-| --------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `Card`    | Optional `title` and `href`; renders an article or link with slot content                                                  |
-| `Steps`   | Ordered list container; supply `li` elements                                                                               |
-| `Logo`    | Optional `label`, `decorative`, and root `class`; renders the Cookbook mark                                                |
-| `Preview` | Required `title`; optional `html`, `css`, `javascript`, and public-file `scripts`; isolates examples in a sandboxed iframe |
+| Component | Props and behavior                                                                                                                                                                              |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Card`    | Optional `title` and `href`; renders an article or link with slot content                                                                                                                       |
+| `Steps`   | Ordered list container; supply `li` elements                                                                                                                                                    |
+| `Logo`    | Optional `label`, `decorative`, and root `class`; renders the Cookbook mark                                                                                                                     |
+| `Preview` | Required `title`; optional `html`, `css`, `javascript`, public-file `scripts`, minimum frame `height`, and overlay `buffer`; isolates examples in a sandboxed iframe that fits scripted content |
 
 The public package exports each component's props type, such as `TabProps`,
 `CalloutProps`, and `CodeGroupProps`. Styles and all named sub-elements are

package/docs/component-styles.md

@@ -474,10 +474,14 @@ shadow-root templates), and non-Tasty stylesheets throughout documentation HTML.
 It parses actual markup, so escaped examples and strings in scripts are allowed.
 The explicit exception is the separate document in a sandboxed `Preview` iframe;
 it cannot access its parent's origin. Configure its size with
-`theme.styles.Preview.Frame`. The documentation shell supports the CSP directive
-`style-src-attr 'none'`. A host's CSP may also restrict the preview document; when
-using that directive, authored previews must use style blocks rather than style
-attributes.
+`theme.styles.Preview.Frame`, or one preview's minimum height with its `height`
+prop. For a preview that runs scripts, a client script sets the frame's
+`height` to its content plus its `buffer` prop, within the frame's `min-height`
+and `max-height` (by default `10rem` and the window's height). The
+documentation shell supports the CSP directive `style-src-attr 'none'`, which
+allows that script's style changes. A host's CSP may also restrict the preview
+document; when using that directive, authored previews must use style blocks
+rather than style attributes.
 
 Search uses an owned, keyboard-accessible dialog and server-rendered input so
 the first opening can focus the field immediately on mobile. Pagefind's indexing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.26.0",
-    "@tenphi/renderer": "0.26.0"
+    "@tenphi/docs": "0.28.0",
+    "@tenphi/renderer": "0.28.0"
   },
   "peerDependencies": {
     "astro": "^7.3.2"