@shelamkoff/rector 1.0.0

package/dist/plugins/quote/index.js

@@ -0,0 +1,165 @@
+// =============================================================================
+// Quote — blockquote with optional caption
+// =============================================================================
+
+import { sanitizeHtml } from '../../core/sanitize.js'
+import { resolvePath } from '../../shared/resolvePath.js'
+import { BlockPluginAbstract } from '../BlockPluginAbstract.js'
+import { mapTextFields } from './mapTextFields.js'
+import { validateQuoteData } from '../../shared/blockDataValidators.js'
+import { normalizeTextValue } from '../../shared/textFormat.js'
+
+const editorStyles = resolvePath('./quote.css', import.meta.url)
+
+// Tabler icon: blockquote
+const ICON = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><path d="M9 5a2 2 0 0 1 2 2v6c0 3.13 -1.65 5.193 -4.757 5.97a1 1 0 1 1 -.486 -1.94c2.227 -.557 3.243 -1.827 3.243 -4.03v-1h-3a2 2 0 0 1 -1.995 -1.85l-.005 -.15v-3a2 2 0 0 1 2 -2z"/><path d="M18 5a2 2 0 0 1 2 2v6c0 3.13 -1.65 5.193 -4.757 5.97a1 1 0 1 1 -.486 -1.94c2.227 -.557 3.243 -1.827 3.243 -4.03v-1h-3a2 2 0 0 1 -1.995 -1.85l-.005 -.15v-3a2 2 0 0 1 2 -2z"/></svg>'
+
+/** Editable quotation with optional attribution. */
+export class Quote extends BlockPluginAbstract {
+  static isTextBlock = true
+  static styles = [editorStyles]
+  type = 'quote'
+  icon = ICON
+  inlineTools = true
+  mapTextFields = mapTextFields
+  pasteConfig = {
+    tags: ['blockquote'],
+  }
+
+  /**
+   * Return the localized toolbox label for this block.
+   * @returns {string}
+   */
+  get title() {
+    return this._t('title', 'Quote')
+  }
+
+  /**
+   * Create the editable DOM owned by this block instance.
+   * @param {{ text?: string, caption?: string }} data
+   * @returns {HTMLElement}
+   */
+  render(data) {
+    const wrapper = document.createElement('div')
+    wrapper.classList.add('oe-quote')
+
+    const blockquote = document.createElement('blockquote')
+    blockquote.classList.add('oe-quote__text')
+    blockquote.contentEditable = 'true'
+    blockquote.dataset.placeholder = this._t('textPlaceholder', 'Quote')
+    const text = normalizeTextValue(data?.text)
+    if (text) {
+      blockquote.innerHTML = sanitizeHtml(text)
+    }
+
+    const caption = document.createElement('cite')
+    caption.classList.add('oe-quote__caption')
+    caption.contentEditable = 'true'
+    caption.dataset.placeholder = this._t('captionPlaceholder', 'Caption')
+    const captionText = normalizeTextValue(data?.caption)
+    if (captionText) {
+      caption.innerHTML = sanitizeHtml(captionText)
+    }
+
+    // Move between the two fields without trapping focus at block boundaries.
+    wrapper.addEventListener('keydown', (e) => {
+      if (e.key !== 'Tab') return
+      const active = document.activeElement
+      const inQuote = active === blockquote || blockquote.contains(/** @type {Node} */ (active))
+      const inCaption = active === caption || caption.contains(/** @type {Node} */ (active))
+      if (!e.shiftKey && inQuote) {
+        e.preventDefault()
+        e.stopPropagation()
+        caption.focus()
+      } else if (e.shiftKey && inCaption) {
+        e.preventDefault()
+        e.stopPropagation()
+        blockquote.focus()
+      }
+    })
+
+    wrapper.appendChild(blockquote)
+    wrapper.appendChild(caption)
+
+    return wrapper
+  }
+
+  /**
+   * Serialize the current block DOM into document data.
+   * @param {HTMLElement} element
+   * @returns {{ text: string, caption: string }}
+   */
+  save(element) {
+    const textEl = element.querySelector('.oe-quote__text')
+    const captionEl = element.querySelector('.oe-quote__caption')
+    return {
+      text: textEl?.innerHTML.trim() || '',
+      caption: captionEl?.innerHTML.trim() || '',
+    }
+  }
+
+  /**
+   * Check whether serialized data satisfies this block's schema.
+   * @param {{ text?: string, caption?: string }} data
+   * @returns {boolean}
+   */
+  validate(data) {
+    return validateQuoteData(data)
+  }
+
+  /**
+   * Merge incoming text into the current block.
+   * @param {HTMLElement} element
+   * @param {{ text?: string }} data
+   * @returns {void}
+   */
+  merge(element, data) {
+    const textEl = element.querySelector('.oe-quote__text')
+    const text = normalizeTextValue(data.text)
+    if (textEl && text) {
+      textEl.innerHTML += sanitizeHtml(text)
+    }
+  }
+
+  /**
+   * Extract neutral fields that can initialize another block type.
+   * @param {HTMLElement} element
+   * @returns {{ text: string, caption: string }}
+   */
+  exportData(element) {
+    const textEl = element.querySelector('.oe-quote__text')
+    const captionEl = element.querySelector('.oe-quote__caption')
+    return {
+      text: textEl?.innerHTML.trim() || '',
+      caption: captionEl?.innerHTML.trim() || '',
+    }
+  }
+
+  /**
+   * Check whether the block has no meaningful user content.
+   * @param {HTMLElement} element
+   * @returns {boolean}
+   */
+  isEmpty(element) {
+    const textEl = element.querySelector('.oe-quote__text')
+    const captionEl = element.querySelector('.oe-quote__caption')
+    return !textEl?.textContent?.trim() && !captionEl?.textContent?.trim()
+  }
+
+  /**
+   * Handle pasted blockquote elements.
+   * @param {import('../../types').TagPasteEvent} event
+   * @returns {{ text: string, caption: string } | null}
+   */
+  onPaste(event) {
+    if (event.type !== 'tag') return null
+    // Clone to avoid mutating the original pasted element
+    const clone = /** @type {HTMLElement} */ (event.element.cloneNode(true))
+    // Extract cite if present
+    const cite = clone.querySelector('cite, footer, figcaption')
+    const caption = cite?.innerHTML?.trim() || ''
+    if (cite) cite.remove()
+    return { text: clone.innerHTML, caption }
+  }
+
+}

package/dist/plugins/quote/locale/en.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    'plugin.quote.title': string;
+    'plugin.quote.textPlaceholder': string;
+    'plugin.quote.captionPlaceholder': string;
+};
+export default _default;

package/dist/plugins/quote/locale/en.js

@@ -0,0 +1,5 @@
+export default {
+  'plugin.quote.title': 'Quote',
+  'plugin.quote.textPlaceholder': 'Quote',
+  'plugin.quote.captionPlaceholder': 'Caption',
+}

package/dist/plugins/quote/locale/keys.d.ts

@@ -0,0 +1,5 @@
+import enLocale from './en.js'
+
+declare module '../../../core/types.js' {
+  interface I18nMessages extends Record<keyof typeof enLocale, string> {}
+}

package/dist/plugins/quote/locale/ru.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    'plugin.quote.title': string;
+    'plugin.quote.textPlaceholder': string;
+    'plugin.quote.captionPlaceholder': string;
+};
+export default _default;

package/dist/plugins/quote/locale/ru.js

@@ -0,0 +1,5 @@
+export default {
+  'plugin.quote.title': 'Цитата',
+  'plugin.quote.textPlaceholder': 'Цитата',
+  'plugin.quote.captionPlaceholder': 'Подпись',
+}

package/dist/plugins/quote/mapTextFields.d.ts

@@ -0,0 +1 @@
+export { mapQuoteTextFields as mapTextFields } from "../../shared/mapTextFields.js";

package/dist/plugins/quote/mapTextFields.js

@@ -0,0 +1 @@
+export { mapQuoteTextFields as mapTextFields } from '../../shared/mapTextFields.js'

package/dist/plugins/quote/quote.css

@@ -0,0 +1,72 @@
+/* =============================================================================
+   Quote plugin — edit mode styles
+   ============================================================================= */
+
+.oe-quote {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding-left: 16px;
+  border-left: 3px solid var(--oe-accent, #4357b4);
+}
+
+.oe-quote__text {
+  margin: 0;
+  padding: 0;
+  font-size: var(--oe-font-size, 15px);
+  line-height: var(--oe-line-height, 1.7);
+  color: var(--oe-text-1, #f5f5f5);
+  font-family: var(--oe-font, inherit);
+  font-style: italic;
+  outline: none;
+  word-break: break-word;
+  white-space: pre-wrap;
+}
+
+.oe-quote__caption {
+  margin: 0;
+  padding: 0;
+  font-size: 0.85em;
+  line-height: 1.5;
+  color: var(--oe-text-3, #908c8c);
+  font-family: var(--oe-font, inherit);
+  font-style: normal;
+  outline: none;
+  word-break: break-word;
+  white-space: pre-wrap;
+}
+
+/* Placeholders */
+.oe-quote__text:empty::before,
+.oe-quote__caption:empty::before {
+  content: attr(data-placeholder);
+  color: var(--oe-text-3, #908c8c);
+  pointer-events: none;
+  font-weight: 400;
+  font-style: normal;
+}
+
+/* Inline formatting */
+.oe-quote__text b,
+.oe-quote__text strong {
+  font-weight: 600;
+}
+
+.oe-quote__text a {
+  color: var(--oe-text-2, #c4c4c4);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+.oe-quote__text a:hover {
+  color: var(--oe-text-1, #f5f5f5);
+}
+
+/* font-style: normal for code inside italic quote text */
+.oe-quote__text code { font-style: normal; }
+
+.oe-quote__text mark {
+  padding: 1px 4px;
+  background: var(--oe-mark-bg, rgba(245, 166, 35, 0.2));
+  border-radius: 3px;
+}

package/dist/plugins/raw/README.md

@@ -0,0 +1,54 @@
+# Raw block plugin
+
+Raw HTML authoring block.
+
+## Install and register
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Raw } from '@shelamkoff/rector/plugins/raw'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Raw()],
+})
+```
+
+The registered block type is `raw`. The class is also exported by the complete `@shelamkoff/rector/plugins` preset and can be loaded through `@shelamkoff/rector/plugins/async`.
+
+## Data
+
+```json
+{ "html": "<section>Content</section>" }
+```
+
+### Field reference
+
+| Field | Required | Meaning and constraints |
+| --- | --- | --- |
+| `html` | yes | Non-blank HTML source string. |
+
+HTML stays inert in the source editor. Tab indents the selected lines and Shift+Tab removes one leading tab or up to two leading spaces; each indentation action is one history step. The preview is shown automatically in read-only mode and can be toggled while editing. Both the editor preview and the matching renderer sanitize the source before mounting it. The editor preview additionally uses a sandboxed iframe without script permissions. Active elements, unsafe URLs, event attributes, and unsafe CSS are removed, but allowed remote images and other safe resources can still cause browser requests, so the host remains responsible for its network and content policy. An empty draft does not pass strict persisted-data validation.
+
+## Configuration
+
+Every built-in block plugin accepts two style ownership options: `injectStyles?: boolean` defaults to `true`; set it to `false` when the host bundles that plugin's CSS. `css?: string` adds one host-provided stylesheet URL after the plugin default, or acts as the replacement URL when default injection is disabled.
+
+## Capabilities
+
+Raw text editing; multiline Tab and Shift+Tab indentation; sandboxed editor preview; sanitized document rendering; automatic preview in read-only mode.
+
+## Undo, lifecycle, and styles
+
+User actions exposed by the plugin enter the command pipeline through the supplied `context.mutate()` capability, so each completed action is one undo/redo step. The editor reference-counts the plugin's declared stylesheet URLs. Removing a block calls its cleanup hook; removing the editor calls `destroy()` for every remaining block and then releases shared plugin resources.
+
+Do not remove the editor holder without first calling `editor.destroy()`.
+
+## Document output
+
+Use the matching renderer from `@shelamkoff/rector/renderer/renderers/raw`. The VitePress guide documents configuration, commands and history, extension contracts, document migrations, styling, security, and lifecycle in a sequential form.

package/dist/plugins/raw/README.ru.md

@@ -0,0 +1,55 @@
+# Блочный плагин Raw
+
+Блок для ввода произвольного HTML.
+
+## Установка и регистрация
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Raw } from '@shelamkoff/rector/plugins/raw'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Raw()],
+})
+```
+
+Тип блока — `raw`. Класс также экспортируется общей точкой входа `@shelamkoff/rector/plugins` и может загружаться по типу документа через `@shelamkoff/rector/plugins/async`.
+
+## Данные
+
+```json
+{ "html": "<section>Содержимое</section>" }
+```
+
+### Поля данных
+
+| Поле | Обязательно | Назначение и ограничения |
+| --- | --- | --- |
+| `html` | да | Непустая строка с исходным HTML. |
+
+В поле исходного текста HTML остаётся неактивным. `Tab` добавляет отступ выбранным строкам, а `Shift+Tab` удаляет один начальный знак табуляции или до двух начальных пробелов; одно изменение отступа создаёт один шаг истории. В режиме только для просмотра предварительный результат открывается автоматически, а при редактировании его можно включить кнопкой. И предварительный просмотр, и соответствующий рендерер очищают исходный код до добавления в DOM. Предварительный просмотр дополнительно работает в изолированном `iframe` без разрешения на выполнение сценариев. Активные элементы, небезопасные адреса, атрибуты событий и небезопасные стили удаляются, но разрешённые удалённые изображения и другие безопасные ресурсы всё ещё могут создавать сетевые запросы браузера. Поэтому сетевую политику и политику содержимого задаёт приложение. Пустой черновик не проходит строгую проверку сохранённых данных.
+
+## Конфигурация
+
+Каждый встроенный блочный плагин принимает два параметра владения стилями: `injectStyles?: boolean` по умолчанию равен `true`; укажите `false`, если приложение само включает CSS этого плагина. `css?: string` добавляет URL таблицы стилей приложения после стандартной, а при отключённой стандартной инъекции служит URL замены.
+
+
+## Возможности
+
+Редактирование исходного текста; многострочные отступы через `Tab` и `Shift+Tab`; изолированный предварительный просмотр; очищенный итоговый DOM; автоматический предварительный просмотр в режиме только для чтения.
+
+## История, жизненный цикл и стили
+
+Действия плагина входят в конвейер команд через предоставленный контекст `mutate()`, поэтому одно завершённое действие создаёт один шаг отмены и повтора. Редактор подсчитывает владельцев объявленных URL стилей. Удаление блока вызывает его метод освобождения ресурсов; `editor.destroy()` освобождает оставшиеся блоки и общие ресурсы.
+
+Не удаляйте контейнер редактора до вызова `editor.destroy()`.
+
+## Вывод документа
+
+Используйте фабричную функцию из `@shelamkoff/rector/renderer/renderers/raw`. Последовательное руководство VitePress описывает проверку данных, миграции, разработку расширений, диагностику, безопасность и стили.

package/dist/plugins/raw/index.d.ts

@@ -0,0 +1,62 @@
+import type {} from './locale/keys.js'
+/** Raw HTML source block with an optional sanitized editor preview. */
+export class Raw extends BlockPluginAbstract<Record<string, any>> {
+    static isTextBlock: boolean;
+    static styles: string[];
+    constructor(config?: Record<string, any>);
+    type: string;
+    icon: string;
+    inlineTools: boolean;
+    /**
+     * Return the localized toolbox label for this block.
+     * @returns {string}
+     */
+    get title(): string;
+    /**
+     * Create the editable DOM owned by this block instance.
+     * @param {{ html?: string }} data
+     * @param {import('../../core/types.js').BlockMutationContext} context
+     * @returns {HTMLElement}
+     */
+    render(data: {
+        html?: string;
+    }, context: import("../../core/types.js").BlockMutationContext): HTMLElement;
+    /**
+     * Serialize the current block DOM into document data.
+     * @param {HTMLElement} element
+     * @returns {{ html: string }}
+     */
+    save(element: HTMLElement): {
+        html: string;
+    };
+    /**
+     * Check whether serialized data satisfies this block's schema.
+     * @param {{ html?: string }} data
+     * @returns {boolean}
+     */
+    validate(data: {
+        html?: string;
+    }): boolean;
+    /**
+     * Check whether the block has no meaningful user content.
+     * @param {HTMLElement} element
+     * @returns {boolean}
+     */
+    isEmpty(element: HTMLElement): boolean;
+    /**
+     * Extract neutral text that can initialize another block type.
+     * @param {HTMLElement} element
+     * @returns {{ text: string }}
+     */
+    exportData(element: HTMLElement): {
+        text: string;
+    };
+    /**
+     * Release listeners and resources owned by this block element.
+     * @param {HTMLElement} element
+     * @returns {void}
+     */
+    destroy(element: HTMLElement): void;
+    #private;
+}
+import { BlockPluginAbstract } from '../BlockPluginAbstract.js';

package/dist/plugins/raw/index.js

@@ -0,0 +1,227 @@
+import { resolvePath } from '../../shared/resolvePath.js'
+import { BlockPluginAbstract } from '../BlockPluginAbstract.js'
+import { validateRawData } from '../../shared/blockDataValidators.js'
+import { normalizeTextValue } from '../../shared/textFormat.js'
+import { sanitizeRawHtml } from '../../shared/sanitize/sanitizeRawHtml.js'
+
+const editorStyles = resolvePath('./raw.css', import.meta.url)
+
+const ICON = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 16v-8l2 5l2-5v8"/><path d="M1 16v-8"/><path d="M5 8v8"/><path d="M1 12h4"/><path d="M7 8h4"/><path d="M9 8v8"/><path d="M20 8v8h3"/></svg>'
+
+
+const stateMap = new WeakMap()
+let rawSequence = 0
+/** Raw HTML source block with an optional sanitized editor preview. */
+export class Raw extends BlockPluginAbstract {
+  static isTextBlock = false
+  static styles = [editorStyles]
+  type = 'raw'
+  icon = ICON
+  inlineTools = false
+
+  /**
+   * Return the localized toolbox label for this block.
+   * @returns {string}
+   */
+  get title() {
+    return this._t('title', 'Raw HTML')
+  }
+
+  /**
+   * Create the editable DOM owned by this block instance.
+   * @param {{ html?: string }} data
+   * @param {import('../../core/types').BlockMutationContext} context
+   * @returns {HTMLElement}
+   */
+  render(data, context) {
+    const previewId = `oe-raw-preview-${++rawSequence}`
+    const wrapper = document.createElement('div')
+    wrapper.classList.add('oe-raw')
+    wrapper.contentEditable = 'false'
+    wrapper.tabIndex = -1
+
+    // Header bar
+    const bar = document.createElement('div')
+    bar.className = 'oe-raw__bar'
+
+    const label = document.createElement('span')
+    label.className = 'oe-raw__label'
+    label.textContent = 'HTML'
+
+    const toggleBtn = document.createElement('button')
+    toggleBtn.type = 'button'
+    toggleBtn.className = 'oe-raw__toggle'
+    toggleBtn.textContent = this._t('preview', 'Preview')
+    toggleBtn.setAttribute('aria-pressed', 'false')
+    toggleBtn.setAttribute('aria-controls', previewId)
+    toggleBtn.hidden = context.readOnly
+    toggleBtn.disabled = context.readOnly
+    toggleBtn.addEventListener('mousedown', (e) => e.preventDefault())
+    toggleBtn.addEventListener('click', () => {
+      const s = stateMap.get(wrapper)
+      if (s) {
+        s.showPreview = !s.showPreview
+        toggleBtn.setAttribute('aria-pressed', String(s.showPreview))
+        this.#syncPreview(wrapper)
+      }
+    })
+
+    bar.append(label, toggleBtn)
+
+    // Textarea (code input)
+    const textarea = document.createElement('textarea')
+    textarea.className = 'oe-raw__textarea'
+    textarea.placeholder = this._t('placeholder', 'Paste HTML code...')
+    textarea.value = normalizeTextValue(data?.html)
+    textarea.spellcheck = false
+    textarea.readOnly = context.readOnly
+    textarea.addEventListener('input', () => {
+      this.#autoResize(textarea)
+    })
+    textarea.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') e.stopPropagation()
+      if (e.key === 'Tab') {
+        e.preventDefault()
+        e.stopPropagation()
+        context.mutate(() => {
+          const start = textarea.selectionStart
+          const end = textarea.selectionEnd
+          const value = textarea.value
+          const lineStart = value.lastIndexOf('\n', start - 1) + 1
+          if (e.shiftKey) {
+            const selected = value.substring(lineStart, end)
+            const dedented = selected.replace(/^ {1,2}/gm, '')
+            if (selected === dedented) return
+            const firstIndent = selected.match(/^ {1,2}/)?.[0].length ?? 0
+            textarea.value = value.substring(0, lineStart) + dedented + value.substring(end)
+            textarea.selectionStart = Math.max(lineStart, start - firstIndent)
+            textarea.selectionEnd = end > start
+              ? lineStart + dedented.length
+              : textarea.selectionStart
+          } else if (start !== end && value.substring(start, end).includes('\n')) {
+            const before = value.substring(0, start)
+            const selected = value.substring(start, end)
+            const after = value.substring(end)
+            const prefix = before.substring(lineStart)
+            const indented = '  ' + (prefix + selected).replace(/\n/g, '\n  ')
+            textarea.value = before.substring(0, lineStart) + indented + after
+            textarea.selectionStart = lineStart
+            textarea.selectionEnd = lineStart + indented.length
+          } else {
+            textarea.value = value.substring(0, start) + '  ' + value.substring(end)
+            textarea.selectionStart = textarea.selectionEnd = start + 2
+          }
+          this.#autoResize(textarea)
+        })
+      }
+    })
+
+    // Preview container
+    const preview = document.createElement('div')
+    preview.className = 'oe-raw__preview'
+    preview.id = previewId
+    preview.style.display = 'none'
+
+    stateMap.set(wrapper, { textarea, preview, showPreview: context.readOnly })
+
+    wrapper.append(bar, textarea, preview)
+
+    requestAnimationFrame(() => this.#autoResize(textarea))
+    if (context.readOnly) this.#syncPreview(wrapper)
+
+    return wrapper
+  }
+
+  /**
+   * Serialize the current block DOM into document data.
+   * @param {HTMLElement} element
+   * @returns {{ html: string }}
+   */
+  save(element) {
+    const s = stateMap.get(element)
+    return { html: s?.textarea?.value || '' }
+  }
+
+  /**
+   * Check whether serialized data satisfies this block's schema.
+   * @param {{ html?: string }} data
+   * @returns {boolean}
+   */
+  validate(data) {
+    return validateRawData(data)
+  }
+
+  /**
+   * Check whether the block has no meaningful user content.
+   * @param {HTMLElement} element
+   * @returns {boolean}
+   */
+  isEmpty(element) {
+    const s = stateMap.get(element)
+    return !s?.textarea?.value?.trim()
+  }
+
+  /**
+   * Extract neutral text that can initialize another block type.
+   * @param {HTMLElement} element
+   * @returns {{ text: string }}
+   */
+  exportData(element) {
+    const s = stateMap.get(element)
+    return { text: s?.textarea?.value || '' }
+  }
+
+  /**
+   * Release listeners and resources owned by this block element.
+   * @param {HTMLElement} element
+   * @returns {void}
+   */
+  destroy(element) {
+    stateMap.delete(element)
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────────
+
+  /** @param {HTMLTextAreaElement} textarea @returns {void} */
+  #autoResize(textarea) {
+    textarea.style.height = 'auto'
+    textarea.style.height = textarea.scrollHeight + 'px'
+  }
+
+  /** @param {HTMLElement} wrapper @returns {void} */
+  #syncPreview(wrapper) {
+    const s = stateMap.get(wrapper)
+    if (!s) return
+    const toggle = /** @type {HTMLButtonElement | null} */ (wrapper.querySelector('.oe-raw__toggle'))
+    toggle?.setAttribute('aria-pressed', String(s.showPreview))
+
+    if (s.showPreview) {
+      s.textarea.style.display = 'none'
+      s.preview.style.display = ''
+      s.preview.textContent = ''
+      const iframe = document.createElement('iframe')
+      iframe.sandbox = ''
+      iframe.title = this._t('previewFrame', 'HTML preview')
+      iframe.style.cssText = 'width:100%;border:none;min-height:100px'
+      iframe.srcdoc = sanitizeRawHtml(s.textarea.value)
+      s.preview.appendChild(iframe)
+      const resizeIframe = () => {
+        try {
+          const h = iframe.contentDocument?.documentElement?.scrollHeight
+          if (h) iframe.style.height = h + 'px'
+        } catch {
+          // A sandboxed srcdoc intentionally has an opaque origin in browsers
+          // that enforce it here. The minimum height remains the safe fallback.
+        }
+      }
+      iframe.addEventListener('load', resizeIframe)
+      requestAnimationFrame(resizeIframe)
+      toggle?.classList.add('oe-raw__toggle--active')
+    } else {
+      s.textarea.style.display = ''
+      s.preview.style.display = 'none'
+      toggle?.classList.remove('oe-raw__toggle--active')
+      requestAnimationFrame(() => this.#autoResize(s.textarea))
+    }
+  }
+}