@tenphi/cookbook 0.25.4 → 0.27.0

package/docs/authoring.mdx

@@ -130,6 +130,73 @@ import { Preview } from "@tenphi/cookbook/components";
   css={"button { padding: 0.75rem; }"}
 />
 
+To demonstrate your own library, build it into the site's public directory
+(`public/` by default) and list the files in `scripts` by their public path,
+without the Astro `base`. Cookbook inlines each file, in order, before
+`javascript`, so the authored code can use what they define. Each file runs as
+a classic script, so use a self-contained IIFE or UMD build without `import` or
+`export`:
+
+```mdx
+<Preview
+  title="Library button"
+  html={"<acme-button>Save</acme-button>"}
+  scripts={["/demo/button.js"]}
+  javascript={"document.querySelector('acme-button').loading = true;"}
+/>
+```
+
+Inlining keeps the preview isolated and needs no request, so the demo works in
+`astro dev`, `astro preview`, and offline as well as on the deployed site. A
+`<script src>` in `html` is a cross-site request from the sandboxed frame:
+`astro dev` rejects it, and Chrome blocks it from local servers. View source
+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.
+
+The frame is at least `10rem` tall, and content outside it is clipped. Give a
+demo with an overlay, such as a listbox, a popover, or a modal dialog, more
+room with `height`, the frame's minimum height as a CSS length such as `18rem`
+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"
+  height="18rem"
+  html={"<acme-select label='Fruit'></acme-select>"}
+  scripts={["/demo/select.js"]}
+/>
+```
+
+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
@@ -149,12 +216,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`, and `javascript`; 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`, and frame `height`; isolates examples in a sandboxed iframe |
 
 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,7 +474,8 @@ 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
+`theme.styles.Preview.Frame`, or one preview's minimum height with its `height`
+prop. 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.

package/package.json

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