@shelamkoff/rector 1.0.0

package/dist/plugins/checklist/index.js

@@ -0,0 +1,407 @@
+import { sanitizeHtml } from '../../core/sanitize.js'
+import { resolvePath } from '../../shared/resolvePath.js'
+import { BlockPluginAbstract } from '../BlockPluginAbstract.js'
+import { validateChecklistData } from '../../shared/blockDataValidators.js'
+import { mapTextFields } from './mapTextFields.js'
+import { normalizeTextValue } from '../../shared/textFormat.js'
+
+const editorStyles = resolvePath('./checklist.css', import.meta.url)
+
+// Tabler icon: list-check
+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="M3.5 5.5l1.5 1.5l2.5-2.5"/><path d="M3.5 11.5l1.5 1.5l2.5-2.5"/><path d="M3.5 17.5l1.5 1.5l2.5-2.5"/><path d="M11 6h9"/><path d="M11 12h9"/><path d="M11 18h9"/></svg>'
+
+// Check icon inside checkbox
+const CHECK_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>'
+
+
+const mutationContexts = new WeakMap()
+/** Editable checklist block with independently toggleable rich-text items. */
+export class Checklist extends BlockPluginAbstract {
+  static isTextBlock = true
+  static styles = [editorStyles]
+  type = 'checklist'
+  icon = ICON
+  inlineTools = true
+  mapTextFields = mapTextFields
+
+  /**
+   * Return the localized toolbox label for this block.
+   * @returns {string}
+   */
+  get title() {
+    return this._t('title', 'Checklist')
+  }
+
+  /**
+   * Create the editable DOM owned by this block instance.
+   * @param {{ items?: Array<{ text: string, checked: boolean } | string>, text?: string }} data
+   * @param {import('../../core/types').BlockMutationContext} context
+   * @returns {HTMLElement}
+   */
+  render(data, context) {
+    const wrapper = document.createElement('div')
+    wrapper.classList.add('oe-checklist')
+    mutationContexts.set(wrapper, context)
+
+    const serializedItems = Array.isArray(data?.items)
+      ? data.items.flatMap(item => {
+        if (typeof item === 'string') return [{ text: item, checked: false }]
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+          return [{
+            text: typeof item.text === 'string' ? item.text : '',
+            checked: item.checked === true,
+          }]
+        }
+        return []
+      })
+      : []
+    const transferredText = normalizeTextValue(data?.text)
+    const items = serializedItems.length > 0
+      ? serializedItems
+      : [{ text: transferredText, checked: false }]
+
+    for (const item of items) {
+      this.#addItem(wrapper, typeof item.text === 'string' ? item.text : '', item.checked === true)
+    }
+
+    wrapper.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && !e.shiftKey) {
+        if (this.#handleEnter(wrapper)) {
+          e.preventDefault()
+          e.stopPropagation()
+        }
+      }
+      if (e.key === 'Backspace') {
+        this.#handleBackspace(wrapper, e)
+      }
+    })
+
+    return wrapper
+  }
+
+  /**
+   * Serialize the current block DOM into document data.
+   * @param {HTMLElement} element
+   * @returns {{ items: Array<{ text: string, checked: boolean }> }}
+   */
+  save(element) {
+    const items = []
+    for (const item of element.querySelectorAll('.oe-checklist__item')) {
+      const text = item.querySelector('.oe-checklist__text')
+      const checked = item.classList.contains('oe-checklist__item--checked')
+      items.push({
+        text: sanitizeHtml(text?.innerHTML?.trim() || ''),
+        checked,
+      })
+    }
+    return { items }
+  }
+
+  /**
+   * Check whether serialized data satisfies this block's schema.
+   * @param {{ items?: Array<{ text: string, checked: boolean }> }} data
+   * @returns {boolean}
+   */
+  validate(data) {
+    return validateChecklistData(data)
+  }
+
+  /**
+   * Check whether the block has no meaningful user content.
+   * @param {HTMLElement} element
+   * @returns {boolean}
+   */
+  isEmpty(element) {
+    const items = element.querySelectorAll('.oe-checklist__item')
+    if (items.length === 0) return true
+    if (items.length === 1) {
+      const text = items[0]?.querySelector('.oe-checklist__text')
+      return !text?.textContent?.trim()
+    }
+    return false
+  }
+
+  /**
+   * Extract neutral text that can initialize another block type.
+   * @param {HTMLElement} element
+   * @returns {{ text: string }}
+   */
+  exportData(element) {
+    const texts = []
+    for (const item of element.querySelectorAll('.oe-checklist__text')) {
+      const t = sanitizeHtml(item.innerHTML?.trim() || '')
+      if (t) texts.push(t)
+    }
+    return { text: texts.join('<br>') }
+  }
+
+  /**
+   * Merge incoming text into the current block.
+   * @param {HTMLElement} element
+   * @param {Record<string, unknown>} data
+   * @returns {void}
+   */
+  merge(element, data) {
+    if (Array.isArray(data?.items)) {
+      for (const item of data.items) {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) continue
+        this.#addItem(element, typeof item.text === 'string' ? item.text : '', item.checked === true)
+      }
+    } else {
+      const text = normalizeTextValue(data?.text)
+      if (text) this.#addItem(element, text, false)
+    }
+    const lastText = /** @type {HTMLElement | null} */ (element.querySelector('.oe-checklist__item:last-child .oe-checklist__text'))
+    if (lastText) {
+      lastText.focus()
+      const sel = window.getSelection()
+      if (sel) {
+        const range = document.createRange()
+        range.selectNodeContents(lastText)
+        range.collapse(false)
+        sel.removeAllRanges()
+        sel.addRange(range)
+      }
+    }
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────────
+
+  /**
+   * @param {HTMLElement} wrapper
+   * @param {string} text
+   * @param {boolean} checked
+   * @returns {void}
+   */
+  #addItem(wrapper, text, checked) {
+    const item = document.createElement('div')
+    item.className = `oe-checklist__item${checked ? ' oe-checklist__item--checked' : ''}`
+
+    const checkbox = this.#createCheckbox(wrapper, item, checked)
+
+    const content = document.createElement('div')
+    content.className = 'oe-checklist__text'
+    content.contentEditable = 'true'
+    if (text) content.innerHTML = sanitizeHtml(text)
+
+    item.append(checkbox, content)
+    wrapper.appendChild(item)
+  }
+
+  /** @param {HTMLElement} wrapper @returns {boolean} Whether the key press was handled by this checklist. */
+  #handleEnter(wrapper) {
+    const sel = window.getSelection()
+    if (!sel?.rangeCount) return false
+
+    const range = sel.getRangeAt(0)
+    const currentText = range.startContainer.nodeType === Node.TEXT_NODE
+      ? range.startContainer.parentElement?.closest('.oe-checklist__text')
+      : /** @type {HTMLElement} */ (range.startContainer).closest('.oe-checklist__text')
+    const endText = range.endContainer.nodeType === Node.TEXT_NODE
+      ? range.endContainer.parentElement?.closest('.oe-checklist__text')
+      : /** @type {HTMLElement} */ (range.endContainer).closest('.oe-checklist__text')
+    if (!currentText || !endText || !wrapper.contains(currentText) || !wrapper.contains(endText)) return false
+
+    const currentItem = currentText.closest('.oe-checklist__item')
+    const endItem = endText.closest('.oe-checklist__item')
+    if (!currentItem || !endItem || currentItem.parentElement !== wrapper || endItem.parentElement !== wrapper) return false
+
+    const context = mutationContexts.get(wrapper)
+    if (!context) return false
+
+    const itemCount = wrapper.querySelectorAll('.oe-checklist__item').length
+    if (!currentText.textContent?.trim()) {
+      if (itemCount <= 1) {
+        context.exitEmptyBlock()
+        return true
+      }
+
+      context.mutate(() => {
+        const isLast = currentItem === wrapper.lastElementChild
+        const nextItem = currentItem.nextElementSibling
+        currentItem.remove()
+
+        if (isLast) {
+          const lastText = /** @type {HTMLElement | null} */ (
+            wrapper.querySelector('.oe-checklist__item:last-child .oe-checklist__text')
+          )
+          if (lastText) {
+            lastText.focus()
+            const end = document.createRange()
+            end.selectNodeContents(lastText)
+            end.collapse(false)
+            sel.removeAllRanges()
+            sel.addRange(end)
+          }
+          context.splitBlock()
+          return
+        }
+
+        const nextText = /** @type {HTMLElement | null} */ (nextItem?.querySelector('.oe-checklist__text'))
+        if (nextText) {
+          nextText.focus()
+          const start = document.createRange()
+          start.setStart(nextText, 0)
+          start.collapse(true)
+          sel.removeAllRanges()
+          sel.addRange(start)
+        }
+      })
+      return true
+    }
+
+    context.mutate(() => {
+      const selectionEnd = document.createRange()
+      selectionEnd.setStart(range.endContainer, range.endOffset)
+      selectionEnd.setEnd(endText, endText.childNodes.length)
+      const afterFrag = selectionEnd.extractContents()
+
+      if (currentItem === endItem) {
+        range.deleteContents()
+      } else {
+        const selectedStart = document.createRange()
+        selectedStart.setStart(range.startContainer, range.startOffset)
+        selectedStart.setEnd(currentText, currentText.childNodes.length)
+        selectedStart.deleteContents()
+
+        let item = currentItem.nextElementSibling
+        while (item) {
+          const next = item.nextElementSibling
+          const reachedEnd = item === endItem
+          item.remove()
+          if (reachedEnd) break
+          item = next
+        }
+      }
+
+      const afterText = document.createElement('div')
+      afterText.appendChild(afterFrag)
+      const newText = afterText.innerHTML.trim()
+
+      // Create new item after current
+      const newItem = document.createElement('div')
+      newItem.className = 'oe-checklist__item'
+
+      const checkbox = this.#createCheckbox(wrapper, newItem, false)
+
+      const content = document.createElement('div')
+      content.className = 'oe-checklist__text'
+      content.contentEditable = 'true'
+      if (newText) content.innerHTML = newText
+
+      newItem.append(checkbox, content)
+      currentItem.after(newItem)
+
+      // Focus new item
+      content.focus()
+      const newRange = document.createRange()
+      newRange.setStart(content, 0)
+      newRange.collapse(true)
+      sel.removeAllRanges()
+      sel.addRange(newRange)
+    })
+    return true
+  }
+
+  /**
+   * @param {HTMLElement} wrapper
+   * @param {HTMLElement} item
+   * @param {boolean} checked
+   * @returns {HTMLButtonElement}
+   */
+  #createCheckbox(wrapper, item, checked) {
+    const checkbox = document.createElement('button')
+    checkbox.type = 'button'
+    checkbox.className = 'oe-checklist__checkbox'
+    checkbox.innerHTML = CHECK_SVG
+    checkbox.setAttribute('aria-label', this._t('toggle', 'Toggle checklist item'))
+    checkbox.setAttribute('aria-pressed', String(checked))
+    checkbox.addEventListener('mousedown', (event) => event.preventDefault())
+    checkbox.addEventListener('click', (event) => {
+      event.stopPropagation()
+      mutationContexts.get(wrapper)?.mutate(() => {
+        const next = !item.classList.contains('oe-checklist__item--checked')
+        item.classList.toggle('oe-checklist__item--checked', next)
+        checkbox.setAttribute('aria-pressed', String(next))
+      })
+    })
+    return checkbox
+  }
+
+  /**
+   * @param {HTMLElement} wrapper
+   * @param {KeyboardEvent} e
+   * @returns {void}
+   */
+  #handleBackspace(wrapper, e) {
+    const items = wrapper.querySelectorAll('.oe-checklist__item')
+    if (items.length <= 1) return
+
+    const sel = window.getSelection()
+    if (!sel?.rangeCount) return
+    const range = sel.getRangeAt(0)
+    if (!range.collapsed) return
+
+    const currentText = range.startContainer.nodeType === Node.TEXT_NODE
+      ? range.startContainer.parentElement?.closest('.oe-checklist__text')
+      : /** @type {HTMLElement} */ (range.startContainer).closest('.oe-checklist__text')
+    if (!(currentText instanceof HTMLElement) || !wrapper.contains(currentText)) return
+
+    if (!this.#isCaretAtStart(currentText, range)) return
+
+    const currentItem = currentText.closest('.oe-checklist__item')
+    if (!currentItem || currentItem.parentElement !== wrapper) return
+    const prevItem = currentItem?.previousElementSibling
+    if (!prevItem) return
+
+    e.preventDefault()
+    e.stopPropagation()
+
+    const prevText = /** @type {HTMLElement | null} */ (prevItem.querySelector('.oe-checklist__text'))
+    if (!prevText) return
+
+    const context = mutationContexts.get(wrapper)
+    if (!context) return
+
+    context.mutate(() => {
+      // Merge into previous
+      const mergePoint = prevText.childNodes.length
+      while (currentText.firstChild) {
+        prevText.appendChild(currentText.firstChild)
+      }
+      currentItem.remove()
+
+      // Set caret at merge point
+      prevText.focus()
+      const newRange = document.createRange()
+      if (prevText.childNodes[mergePoint]) {
+        newRange.setStartBefore(prevText.childNodes[mergePoint])
+      } else {
+        newRange.setStart(prevText, prevText.childNodes.length)
+      }
+      newRange.collapse(true)
+      sel.removeAllRanges()
+      sel.addRange(newRange)
+    })
+  }
+
+  /**
+   * @param {HTMLElement} text
+   * @param {Range} range
+   * @returns {boolean}
+   */
+  #isCaretAtStart(text, range) {
+    const { startContainer, startOffset } = range
+    if (startContainer === text && startOffset === 0) return true
+    if (startContainer.nodeType !== Node.TEXT_NODE || startOffset !== 0) return false
+
+    /** @type {Node | null} */
+    let node = startContainer
+    while (node && node !== text) {
+      if (node.previousSibling) return false
+      node = node.parentNode
+    }
+    return node === text
+  }
+
+}

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

@@ -0,0 +1,5 @@
+declare const _default: {
+    'plugin.checklist.title': string;
+    'plugin.checklist.toggle': string;
+};
+export default _default;

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

@@ -0,0 +1,4 @@
+export default {
+  'plugin.checklist.title': 'Checklist',
+  'plugin.checklist.toggle': 'Toggle checklist item',
+}

package/dist/plugins/checklist/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/checklist/locale/ru.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    'plugin.checklist.title': string;
+    'plugin.checklist.toggle': string;
+};
+export default _default;

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

@@ -0,0 +1,4 @@
+export default {
+  'plugin.checklist.title': 'Контрольный список',
+  'plugin.checklist.toggle': 'Изменить состояние пункта списка',
+}

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

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

package/dist/plugins/checklist/mapTextFields.js

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

package/dist/plugins/code/README.md

@@ -0,0 +1,59 @@
+# Code block plugin
+
+Code block with a language selector and optional syntax highlighting.
+
+## Install and register
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Code } from '@shelamkoff/rector/plugins/code'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Code()],
+})
+```
+
+The registered block type is `code`. The class is also exported by the complete `@shelamkoff/rector/plugins` preset and can be loaded through `@shelamkoff/rector/plugins/async`.
+
+## Data
+
+```json
+{ "code": "const value = 1", "language": "javascript" }
+```
+
+### Field reference
+
+| Field | Required | Meaning and constraints |
+| --- | --- | --- |
+| `code` | yes | Non-blank source text. It is never executed as HTML. |
+| `language` | no | Language identifier used for highlighting. Saving a new block writes `auto` until the user selects another language. Unknown strings remain valid data and fall back to plain text when the highlighter cannot resolve them. |
+
+An empty code block is allowed as an editing draft but fails 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.
+
+`hljs?: object` supplies a compatible highlight.js instance. Without it the bundled highlighting runtime is loaded lazily; if highlighting is unavailable, code remains readable as plain text.
+
+The language menu contains the built-in identifiers used by the bundled highlighter. Documents may also contain any non-empty language string. Such a value is preserved and displayed even when it is absent from the menu; if the active highlighting runtime does not recognize it, the block falls back to escaped plain text. The copy button uses the browser Clipboard API. When that API is unavailable or rejects the write, the document and button state remain unchanged.
+
+## Capabilities
+
+Code/pre tag paste; fenced-code pattern paste; keyboard-accessible language selection and filtering; optional syntax highlighting; Clipboard API copy; export for conversion.
+
+## 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/code`. The VitePress guide documents configuration, commands and history, extension contracts, document migrations, styling, security, and lifecycle in a sequential form.

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

@@ -0,0 +1,60 @@
+# Блочный плагин Code
+
+Блок кода с выбором языка и необязательной подсветкой синтаксиса.
+
+## Установка и регистрация
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Code } from '@shelamkoff/rector/plugins/code'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Code()],
+})
+```
+
+Тип блока — `code`. Класс также экспортируется общей точкой входа `@shelamkoff/rector/plugins` и может загружаться по типу документа через `@shelamkoff/rector/plugins/async`.
+
+## Данные
+
+```json
+{ "code": "const value = 1", "language": "javascript" }
+```
+
+### Поля данных
+
+| Поле | Обязательно | Назначение и ограничения |
+| --- | --- | --- |
+| `code` | да | Непустой исходный текст. Он никогда не выполняется как HTML. |
+| `language` | нет | Идентификатор языка для подсветки. Новый блок сохраняет `auto`, пока пользователь не выберет другой язык. Неизвестная строка остаётся допустимыми данными; если модуль подсветки не распознает её, код отображается как обычный текст. |
+
+Пустой блок кода допустим как черновик, но не проходит строгую проверку сохранённых данных.
+
+## Конфигурация
+
+Каждый встроенный блочный плагин принимает два параметра владения стилями: `injectStyles?: boolean` по умолчанию равен `true`; укажите `false`, если приложение само включает CSS этого плагина. `css?: string` добавляет URL таблицы стилей приложения после стандартной, а при отключённой стандартной инъекции служит URL замены.
+
+`hljs?: object` передаёт совместимый экземпляр highlight.js. Без него встроенная подсветка загружается по требованию; если она недоступна, код остаётся обычным текстом.
+
+Меню языка содержит встроенные идентификаторы, поддерживаемые поставляемой подсветкой. Документ может хранить и любую другую непустую строку языка. Она сохраняется и отображается, даже если отсутствует в меню; когда текущий модуль подсветки её не распознаёт, блок показывает экранированный исходный текст без подсветки. Кнопка копирования использует браузерный API буфера обмена `navigator.clipboard`. Если этот интерфейс недоступен или запись отклонена, документ и состояние кнопки не меняются.
+
+
+## Возможности
+
+Вставка `code`, `pre` и ограждённого блока кода; доступные с клавиатуры выбор и фильтрация языка; необязательная подсветка; копирование через API буфера обмена; преобразование блока.
+
+## История, жизненный цикл и стили
+
+Действия плагина входят в конвейер команд через предоставленный контекст `mutate()`, поэтому одно завершённое действие создаёт один шаг отмены и повтора. Редактор подсчитывает владельцев объявленных URL стилей. Удаление блока вызывает его метод освобождения ресурсов; `editor.destroy()` освобождает оставшиеся блоки и общие ресурсы.
+
+Не удаляйте контейнер редактора до вызова `editor.destroy()`.
+
+## Вывод документа
+
+Используйте фабричную функцию из `@shelamkoff/rector/renderer/renderers/code`. Последовательное руководство VitePress описывает проверку данных, миграции, разработку расширений, диагностику, безопасность и стили.