--- name: HTML Preview Editor type: MOL section: wysiwyg-editors why: One source, two views - the

you edit is the srcdoc the sandboxed <iframe> runs, so the code shown and the code run cannot differ; the preview runs in an opaque origin, device emulation is CSS zoom over a real viewport, highlighting is Shiki.
when: Live, editable HTML examples - a design-system docs site, a playground, a template editor with a preview. Showing code without running it is a code block or mockup-code; a plain text field is textarea.
where: dist/components/wysiwyg.css + dist/components/wysiwyg.js (the extra bundle - load it after all.css / all.js; per component: dist/components/code-example/code-example.css + code-example.js)
supportedStates: default, code, state, fullscreen
---

# Pattern: HTML Preview Editor

## Native basis

A `<div class="code-example">` around one `<textarea>` holding the HTML
source. The runtime builds the card around it - a stage with a sandboxed
`<iframe srcdoc>` inside a device frame (the shipped `resizer` gives it handles
on every side), a toolbar (Phone / Tablet / Desktop / Full, Rotate, width ×
height, zoom, Code / State tabs, Reset, Fullscreen) and the Code panel, where
the textarea sits over an `aria-hidden` paint layer that Shiki colours. The
preview is rebuilt from the textarea 400 ms after typing stops; nothing else
feeds it.

The **extra bundle**: the component is NOT part of `all.css` / `all.js` - the
page adds `wysiwyg.css` and `wysiwyg.js` after them (or after `core.css` /
`core.js` + its components). The preview runs the same design system: by
default it loads the page's own stylesheets and inlines the page's `all.js`
(or `core.js`), so components work inside it - plus each extra bundle the page
loaded whose components the source names (`wysiwyg.js`, `mermaid.js`,
`math.js`: `df$.shadcn.codeExample.bundlesFor(source)`).

---

## Native Web APIs
- [`<iframe srcdoc sandbox>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox) - the preview: an opaque origin (`allow-scripts allow-forms`), so an edited source cannot touch the page
- [`postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) - the bridge between card and preview, one channel id per card
- [`<textarea>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) - the editable source: undo, selection and assistive tech are native
- [CSS `zoom`](https://developer.mozilla.org/en-US/docs/Web/CSS/zoom) - device boxes shrink to the card while the iframe keeps its declared viewport width (media queries inside stay honest)
- [Fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API) - the whole card fills the screen (a fixed overlay where the page may not go fullscreen)
- [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) - previews boot near the viewport (the rest once the page is idle)
- [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) - the preview reports its true content height; fullscreen refits
- [`checkVisibility()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/checkVisibility) - the source paints when the Code panel opens
- [Dynamic `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) - Shiki (pinned ESM) loads on the first paint
- [`Clipboard API`](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) - Copy
- [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) - `code-example-change`, `code-example-ready`, `code-example-error`
- [WCAG 2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html) - Tab indents, Escape then Tab leaves
- [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) · [`prefers-contrast`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) · [`forced-colors`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors)

---

## Structure

```html
<link rel="stylesheet" href="components/all.css">
<link rel="stylesheet" href="components/wysiwyg.css">
<script type="module" src="components/all.js"></script>
<script type="module" src="components/wysiwyg.js"></script>

``` The runtime builds the rest. A page that renders the card on the server (as this site does) authors the whole shell instead - the runtime finds `.code-example-toolbar` and builds nothing: ```html

``` The source is the textarea's text: escape only `` (as `</textarea>`); everything else is literal. --- ## Variants | Attribute (on `.code-example`) | Behavior | |-----------|----------| | `data-schema='{…}'` | A component schema (`dist/schemas/*.schema.json`): adds the State tab, whose controls drive the previewed component and read its state back | | `data-vp-mode="phone\|tablet\|desktop\|print\|full"` | The device the preview boots in (`full` = the card's width; `print` = an A4 sheet, 794px, 20mm margins, whose preview applies its print styles: `print` and `screen` trade places in every media query of every sheet the preview can read; a sheet has no pages, so every forced page break (`break-before: page`, `left`, `right`) shows as a dashed line with room around it) | | `data-height="N"` | Minimum preview height in rem - for overlays (dialogs, menus) that do not grow the page | | `data-preview-style="…"` | Declarations for the preview's `` (the stage): `display:flex;gap:1rem;justify-content:center` | | `data-language="html\|css\|js\|…"` | The source's language for the colours (default `html`) - any Shiki language | | `data-sandbox="embed"` | Widens the frame for a third-party player (same origin, autoplay, fullscreen) - the one opt-out of the opaque origin | | `data-sandbox="links"` | Lets links in the preview open a new tab | | `data-sandbox="downloads"` | Lets the preview save a file (a download) - the frame stays opaque | | `data-sandbox="fullscreen"` | Lets the preview go full screen (a Video's full screen control) - the frame stays opaque | | `data-links='{"paper.html":"papers/paper.html"}'` | Link targets the preview uses in place of the ones the source names (`href`, `src`, `action`, `poster`); the source keeps what was written, also when the preview writes a change back into it. The docs map their page ids to paths from the docs root, the base of their previews | | `aria-label` | The preview frame's title | --- ## Keyboard | Key | Does | |-----|------| | Tab / Shift + Tab (in the source) | Indent / outdent the selected lines | | Escape, then Tab | Leave the source (no keyboard trap) | | Enter (in the source) | A new line with the current line's indentation | | Escape | Leave fullscreen | --- ## States | State | Meaning | |-------|---------| | `default` | The preview alone - both panels closed | | `code` | The source is open (and painted) | | `state` | The state controls are open (cards with `data-schema`; without one it lands in `default`) | | `fullscreen` | The card fills the screen - `data-fullscreen`; `config.panel` keeps a panel open below the stage | Every state's config carries `source` - the textarea's value. Setting it reruns the preview; `data-edited` marks a source that differs from the authored one. ```js const card = document.querySelector('#playground'); card.api.setState('code'); // open the source card.api.setState('fullscreen', { panel: 'code' }); // fullscreen, source below the stage card.api.getState(); // { name, config: { source, … } } df$.shadcn.codeExample.setSource(card, '

Hello

'); // replace + rerun card.addEventListener('code-example-change', (e) => save(e.detail.source)); card.preview.setState('open'); // a state of the PREVIEWED component (data-schema) ``` --- ## API ### States type CodeExampleState = 'default' | 'code' | 'state' | 'fullscreen' - `setState(name, config)` takes the config of the state it names (`CodeExampleStateConfigs[name]`). | State | Description | |---|---| | `default` | The preview alone - both panels closed. config

Field	Type	Description
`source?`	`string`	replace the source and rerun the preview (getState() reports the source now)

| | `code` | The source editor is open (and painted). config

Field	Type	Description
`source?`	`string`	replace the source and rerun the preview

| | `state` | The state controls are open (a card with data-schema; without one it lands in default). config

Field	Type	Description
`source?`	`string`	replace the source and rerun the preview

| | `fullscreen` | The card fills the screen (data-fullscreen). config

Field	Type	Description
`source?`	`string`	replace the source and rerun the preview
`panel?`	`'code' \\| 'state' \\| null`	the panel kept open below the stage, null for none

| ### Every element | Member | Description | |---|---| | el.api.setState<S extends CodeExampleState>(name: S, config?: CodeExampleStateConfigs[S]): unknown | Enter a state: the DOM work runs (also when it is the current state), the store records it.

Argument	Type	Description
`name`	`S`	a declared state (an unknown name throws)
`config?`	`CodeExampleStateConfigs[S]`	that state's config (merged into the stored one when the component merges)

Returns unknown - what the state's DOM work returned - a Promise for an async state (or await settled()) | | el.api.getState(): { name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState]; model?: ElementModel } | The state the element shows now - read back from the DOM, so it includes what the user changed. Returns { name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState]; model?: ElementModel } - the state's name, its config and the authored markup model render() starts from | |

el.api.render(state?: { name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState]; model?: ElementModel }): string

| The element's markup in a state - the authored markup with that state applied; a pure function of the state.

Argument	Type	Description
`state?`	`{ name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState]; model?: ElementModel }`	a state as getState() returns it (default: the current one)

Returns string - the element's outer HTML in that state | | el.api.settled(): Promise<void> | Wait for the last state's DOM work (async states: a diagram rendering, a chart mounting). Returns Promise<void> - resolves when nothing is pending | | el.store: Store<{ name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState] }> | A defuss-store store of the element's state - subscribe to follow every change (also the user's), set it to drive the component. | ### Registry | Member | Description | |---|---| |

df$.shadcn.codeExampleApi.setState<S extends CodeExampleState>(el: HTMLElement, name: S, config?: CodeExampleStateConfigs[S]): unknown

| Enter a state: the DOM work runs (also when it is the current state), the store records it.

Argument	Type	Description
`el`	`HTMLElement`	the component's element
`name`	`S`	a declared state (an unknown name throws)
`config?`	`CodeExampleStateConfigs[S]`	that state's config (merged into the stored one when the component merges)

Returns unknown - what the state's DOM work returned - a Promise for an async state (await it, or el.api.settled()) | |

df$.shadcn.codeExampleApi.getState(el: HTMLElement): { name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState]; model?: ElementModel }

| The state the element shows now - read back from the DOM, so it includes what the user changed.

Argument	Type	Description
`el`	`HTMLElement`	the component's element

Returns { name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState]; model?: ElementModel } - the state's name, its config and the authored markup model render() starts from | |

df$.shadcn.codeExampleApi.render(state: { name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState]; model?: ElementModel }): string

| The element's markup in a state - the authored markup with that state applied; a pure function of the state.

Argument	Type	Description
`state`	`{ name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState]; model?: ElementModel }`	a state as getState() returns it (with its model)

Returns string - the element's outer HTML in that state | |

df$.shadcn.codeExampleApi.store(el: HTMLElement): Store<{ name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState] }>

| The element's store (bindComponent made it).

Argument	Type	Description
`el`	`HTMLElement`	the component's element

Returns Store<{ name: CodeExampleState; config: CodeExampleStateConfigs[CodeExampleState] }> - a defuss-store store of { name, config } - subscribe to follow every change, set it to drive the component | |

df$.shadcn.codeExampleApi.commit<S extends CodeExampleState>(el: HTMLElement, name: S, config?: CodeExampleStateConfigs[S]): void

| Record a state the element reached on its own (no DOM work) - for a component's own handlers.

Argument	Type	Description
`el`	`HTMLElement`	the component's element
`name`	`S`	the state it is in
`config?`	`CodeExampleStateConfigs[S]`	its config

| | df$.shadcn.codeExampleStates: CodeExampleState[] | The declared states, 'default' first: default, code, state, fullscreen. | ### `df$.shadcn.codeExample` | Member | Description | |---|---| | configure(options: CodeExampleConfig = {}): void | Configure every preview on the page: { styles, scripts } (arrays of URLs or { css } / { js } texts, or a function of the source returning one - default: the page's own stylesheets and all/core bundle, plus each extra bundle the page loaded that the source uses - bundlesFor), tail (markup after the runtime, e.g. an icon library), theme (CSS text or a function returning it - layered last, re-read by refreshTheme), highlight(code, language) returning the HTML of coloured spans (default: Shiki), shiki (its ESM URL), themes ({ light, dark } Shiki themes). Previews built afterwards use it.

Argument	Type	Description
`options`	`CodeExampleConfig` = `{}`	the keys to change; the cards on the page repaint their source

| | bundlesFor(source: string): string[] | The extra bundles (components kept out of all.*) a preview of this source needs - the default scripts add each one the page loaded; a configured `scripts` function can add them itself.

Argument	Type	Description
`source`	`string`	an example's HTML source

Returns string[] - the bundle names (`wysiwyg`, `mermaid`, `math`, `visual-editor`, `geo`) whose components the source names, in that order | | source(target: string \| HTMLElement): string | The card's current source.

Argument	Type	Description
`target`	`string \\| HTMLElement`	the .code-example card or its selector

Returns string - the editor's text ('' when the target is not a card) | | setSource(target: string \| HTMLElement, source: string): void | Replace the source and rerun the preview (the state stays; data-edited follows).

Argument	Type	Description
`target`	`string \\| HTMLElement`	the .code-example card or its selector
`source`	`string`	the new source

| | reset(target: string \| HTMLElement): void | Back to the authored source, rerun.

Argument	Type	Description
`target`	`string \\| HTMLElement`	the .code-example card or its selector

| | run(target: string \| HTMLElement): void | Rebuild the preview from the current source now.

Argument	Type	Description
`target`	`string \\| HTMLElement`	the .code-example card or its selector

Argument	Type	Description
`target`	`string \\| HTMLElement`	the .code-example card or its selector
`mode`	`'phone' \\| 'tablet' \\| 'desktop' \\| 'print' \\| 'full'`	the device width the preview takes ('print': 210mm, its media rules for print applied)

Argument	Type	Description
`target`	`string \\| HTMLElement`	the .code-example card or its selector
`name`	`string`	the state's name in the component's schema
`value`	`string \\| number \\| boolean`	its new value (the schema's type for it)

Argument	Type	Description
`target`	`string \\| HTMLElement`	the .code-example card or its selector

Returns Record<string, string \| number \| boolean> - a copy of the values the preview reported, by state name | | refreshTheme(): void | Re-read the configured theme and hand it to every preview (no rebuild - the previews keep their state). | | highlight(code: string, language: string): Promise<string \| null> | The configured highlighter: from code and a language to a Promise of HTML (coloured spans), or null.

Argument	Type	Description
`code`	`string`	the source text
`language`	`string`	a Shiki language id ('html', 'css', 'ts', ...)

Argument	Type	Description
`target`	`string \\| HTMLElement`	the .code-example card or its selector

Returns Promise<boolean> - true when the clipboard took it | ### Events | Event | Description | |---|---| | `code-example-change` | Fires after the source changed and the preview reran - typing (debounced), setSource(), reset(), setState() with a { source }; the source and where the change came from: 'input' or 'api'. detail: CodeExampleChangeDetail

Field	Type	Description
`source`	`string`	the source now
`origin`	`'input' \\| 'api'`	'input': typed in the editor; 'api': setSource(), reset() or setState()

| | `code-example-error` | The preview reported an error - the source's own script threw, or failed to load - or the preview could not be built. detail: CodeExampleErrorDetail

Field	Type	Description
`message`	`string`	the error message shown under the preview
`stack?`	`string`	the stack, when the preview's script threw

| | `code-example-ready` | The preview finished loading the source - its state can be driven (el.preview) from now on. detail: CodeExampleReadyDetail

Field	Type	Description
`source`	`string`	the source the preview ran

| ### Types | Type | Description | |---|---| | `CodeExampleChangeDetail` | What code-example-change carries.

Field	Type	Description
`source`	`string`	the source now
`origin`	`'input' \\| 'api'`	'input': typed in the editor; 'api': setSource(), reset() or setState()

| | `CodeExampleConfig` | What configure() takes - every key optional, kept for every preview built afterwards.

Field	Type	Description
`styles?`	`CodeExampleStyle[] \\| ((source: string) => CodeExampleStyle[] \\| Promise<CodeExampleStyle[]>) \\| null`	the previews' stylesheets, or a function of the source returning them (default: the page's own stylesheets)
`scripts?`	`CodeExampleScript[] \\| ((source: string) => CodeExampleScript[] \\| Promise<CodeExampleScript[]>) \\| null`	the previews' scripts, or a function of the source returning them (default: the page's all / core bundle and each extra bundle it loaded that the source uses - bundlesFor - inlined)
`tail?`	`string \\| ((source: string) => string)`	markup after the runtime (an icon library), or a function of the source returning it
`theme?`	`string \\| (() => string \\| Promise<string>) \\| null`	theme CSS layered last in every preview, or a function returning it - refreshTheme() re-reads it
`highlight?`	`((code: string, language: string) => string \\| null \\| Promise<string \\| null>) \\| null`	your own highlighter: from code and a language to the HTML of coloured spans (null: show it plain)
`base?`	`string \\| null`	the URL the previews resolve relative references against (`images/x.png` in an example): a `<base href>` first in the preview's head. Default: none - an about:srcdoc document resolves against the host page, which is wrong once that page sits in a folder
`shiki?`	`string`	the ESM URL Shiki is imported from (the default highlighter)
`themes?`	`{ light: string; dark: string }`	the Shiki themes for light and dark

| | `CodeExampleErrorDetail` | What code-example-error carries.

Field	Type	Description
`message`	`string`	the error message shown under the preview
`stack?`	`string`	the stack, when the preview's script threw

| | `CodeExampleReadyDetail` | What code-example-ready carries.

Field	Type	Description
`source`	`string`	the source the preview ran

| | `CodeExampleScript` | A script for the previews: a URL (fetched once), or JS text. = string \| { js: string } | | `CodeExampleStyle` | A stylesheet for the previews: a URL, or CSS text. = string \| { css: string } | --- ## ARIA | Element | Attribute | Notes | |---------|-----------|-------| | `.code-example-frame` | `title` | From the card's `aria-label` (default "Preview") | | `.code-example-src` | `aria-label` or `` | The textarea is what assistive tech reads | | `.code-example-paint` | `aria-hidden="true"` | Presentation only | | `.code-example-tab` / `.code-example-vp` | `aria-pressed` | The open panel / the device | | `.code-example-viewport` | `role="group"` + `aria-label` | The device buttons | | `.code-example-error` | `role="alert"` | A preview error is announced | | `.code-example-full-exit` | `aria-label` | Icon-only | --- ## Notes - **The preview's assets**: `df$.shadcn.codeExample.configure({ styles, scripts, tail, theme })` replaces the discovery - inline texts (`{ css }`, `{ js }`) avoid a request per preview, `tail` adds markup after the runtime (an icon library), `theme` is layered last and `refreshTheme()` pushes a new one into every running preview. Scripts run as classic scripts in their own function scope, so a bundle must be import-free (`all.js`, `core.js` and the extra bundles are). - **Highlighting** is Shiki (`https://esm.sh/shiki@3.0.0`, loaded on the first paint; `github-light` / `github-dark`, following `.dark`). `configure({ highlight })` plugs in any other highlighter: `(code, language) → HTML of coloured spans`. - **Nesting**: a source that contains a `.code-example` gets `wysiwyg.js` and the page's assets handed down - the previews of this page are such nested cards. - **Dark mode and themes** follow the page without rebuilding a preview (the running example keeps its state). - **Forms and links** inside the preview run their handlers; a submit never navigates the preview away (`method="dialog"` still closes a dialog), a link never leaves it (a fragment jumps in place). - The `resizer` component (in `all.js`) supplies the handles; without it the width / height fields still size the preview. - A page may add its own tools to `.code-example-toolbar`: a `