@shelamkoff/rector 1.0.0

package/dist/plugins/image/index.js

@@ -0,0 +1,346 @@
+import { resolvePath } from '../../shared/resolvePath.js'
+import { isSupportedImageFile, triggerFileInput } from '../shared/fileInput.js'
+import { BlockPluginAbstract } from '../BlockPluginAbstract.js'
+import { validateImageData } from '../../shared/blockDataValidators.js'
+import { CSS } from './css.js'
+import { ICON } from './icons.js'
+import { ImageState, normalizeImageData, emptyImageData } from './state.js'
+import { ImageUploader } from './uploader.js'
+import { renderEmptyView } from './view-empty.js'
+import { renderFilledView } from './view-filled.js'
+import { sanitizeMediaUrl } from '../../shared/sanitize/index.js'
+
+const editorStyles = resolvePath('./image.css', import.meta.url)
+
+/**
+ * @typedef {{ url: string, alt?: string }} ImageSourceResult
+ * @typedef {(file: File, context: { signal: AbortSignal }) => Promise<ImageSourceResult>} ImageUpload
+ * @typedef {(context: { signal: AbortSignal }) => Promise<ImageSourceResult | null>} ImageSourceHandler
+ * @typedef {{ icon?: string, label: string, handler: ImageSourceHandler }} ImageSourceAction
+ *
+ * @typedef {Object} ImageConfig
+ * @property {ImageUpload} [uploadFile] Uploads a browser file. Without this callback the plugin reads the file into a data URL stored in the document.
+ * @property {ImageSourceAction[]} [actions] Additional application-owned image sources. `icon` is trusted application markup; never pass user-authored HTML.
+ * @property {boolean} [injectStyles=true] Whether the editor should load the built-in image stylesheet.
+ * @property {string} [css] Additional stylesheet URL, or the replacement URL when `injectStyles` is `false`.
+ */
+
+/**
+ * Block plugin for images. Public surface implements `BlockPlugin`.
+ * Internal logic is split across:
+ *  - `state.js` — per-block state container (replaces module WeakMap)
+ *  - `uploader.js` — file upload pipeline (HTTP or data-URL fallback)
+ *  - `view-empty.js`/`view-filled.js` — DOM rendering for the two states
+ *  - `settings.js` — settings dropdown form
+ *  - `styles.js` — inline style application
+ *
+ * @extends {BlockPluginAbstract<ImageConfig>}
+ */
+export class Image extends BlockPluginAbstract {
+  static isTextBlock = false
+  static styles = [editorStyles]
+
+  type = 'image'
+  icon = ICON
+  inlineTools = false
+
+  pasteConfig = {
+    files: ['image/*'],
+    patterns: [/https?:\/\/\S+\.(gif|jpe?g|png|svg|webp)(\?\S*)?$/i],
+  }
+
+  #uploader
+  /** @type {ImageConfig} */
+  #config
+  /** Per-block state, keyed by wrapper element. Encapsulated to this instance. */
+  #states = /** @type {WeakMap<HTMLElement, ImageState>} */ (new WeakMap())
+  /** @type {WeakMap<HTMLElement, import('../../core/types').BlockMutationContext>} */
+  #contexts = new WeakMap()
+  /**
+   * Create an Image instance with the supplied consumer configuration.
+   * @param {ImageConfig} [config]
+   */
+  constructor(config) {
+    super(config)
+    this.#config = /** @type {ImageConfig} */ (this.getPluginConfig())
+    this.#uploader = new ImageUploader(this.#config)
+  }
+
+  /**
+   * Return the localized toolbox label for this block.
+   * @returns {string}
+   */
+  get title() {
+    return this._t('title', 'Image')
+  }
+
+  // ── BlockPlugin contract ───────────────────────────────────────────────────
+
+  /**
+   * Create the editable DOM owned by this block instance.
+   * @param {Record<string, unknown>} data
+   * @param {import('../../core/types').BlockMutationContext} context
+   * @returns {HTMLElement}
+   */
+  render(data, context) {
+    const blockData = normalizeImageData(data)
+    const pendingFile = /** @type {File | null} */ (/** @type {any} */ (data)?._pendingFile || null)
+
+    const wrapper = document.createElement('div')
+    wrapper.classList.add(CSS.wrapper)
+    wrapper.contentEditable = 'false'
+    wrapper.tabIndex = -1
+
+    const state = new ImageState(blockData, pendingFile)
+    this.#states.set(wrapper, state)
+    this.#contexts.set(wrapper, context)
+
+    if (blockData.withBorder) wrapper.classList.add(CSS.withBorder)
+    if (blockData.expanded) wrapper.classList.add(CSS.expanded)
+    if (blockData.withBackground) wrapper.classList.add(CSS.withBackground)
+
+    if (blockData.file.url) {
+      this.#renderFilled(wrapper)
+    } else {
+      this.#renderEmpty(wrapper)
+    }
+
+    // Drain pending file from paste (async; renders after upload completes).
+    if (state.pendingFile && !context.readOnly) {
+      const file = state.pendingFile
+      state.pendingFile = null
+      state.pendingUpload = this.#handleFile(wrapper, file).finally(() => {
+        if (this.#states.get(wrapper) === state) state.pendingUpload = null
+      })
+    }
+
+    return wrapper
+  }
+
+  /**
+   * Serialize the current block DOM into document data.
+   * @param {HTMLElement} element
+   * @returns {Record<string, unknown>}
+   */
+  save(element) {
+    const state = this.#states.get(element)
+    if (!state) return emptyImageData()
+    return { ...state.data, styles: { ...state.data.styles } }
+  }
+
+  /**
+   * Check whether serialized data satisfies this block's schema.
+   * @param {Record<string, unknown>} data
+   * @returns {boolean}
+   */
+  validate(data) {
+    return validateImageData(data)
+  }
+
+  /**
+   * Check whether the block has no meaningful user content.
+   * @param {HTMLElement} element
+   * @returns {boolean}
+   */
+  isEmpty(element) {
+    const state = this.#states.get(element)
+    return !state?.data.file.url
+  }
+
+  /**
+   * Extract neutral text that can initialize another block type.
+   * @param {HTMLElement} element
+   * @returns {Record<string, unknown>}
+   */
+  exportData(element) {
+    const state = this.#states.get(element)
+    return { text: state?.data.caption || '' }
+  }
+
+  /**
+   * Handle supported pasted content for this block.
+   * @param {import('../../types').PasteEvent} event
+   * @returns {Record<string, unknown> | null}
+   */
+  onPaste(event) {
+    if (event.type === 'file') {
+      // Pass the file through the _pendingFile marker; render() will pick it up.
+      const data = /** @type {any} */ (emptyImageData())
+      data._pendingFile = event.file
+      return data
+    }
+    if (event.type === 'pattern') {
+      const url = String(event.data)
+      if (url && /^https?:\/\/.+/i.test(url)) {
+        return { ...emptyImageData(), file: { url } }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Keep a file paste inside one undo transaction until its upload finishes.
+   * @param {HTMLElement} element
+   * @returns {Promise<void>}
+   */
+  waitForPaste(element) {
+    return this.#states.get(element)?.pendingUpload ?? Promise.resolve()
+  }
+
+  /**
+   * Release listeners and resources owned by this block element.
+   * @param {HTMLElement} element
+   * @returns {void}
+   */
+  destroy(element) {
+    const state = this.#states.get(element)
+    if (!state) return
+    state.dispose()
+    this.#states.delete(element)
+    this.#contexts.delete(element)
+  }
+
+  // ── Internal coordination ──────────────────────────────────────────────────
+
+  /**
+   * Resolve a localized image-plugin message.
+   * @param {string} key Translation key scoped to the image plugin.
+   * @param {string} fallback Message returned when the key is unavailable.
+   * @returns {string}
+   */
+  #t = (key, fallback) => this._t(key, fallback)
+
+  /**
+   * Execute one completed block mutation through the editor command context.
+   * @param {HTMLElement} wrapper Image block wrapper that owns the context.
+   * @param {() => void} operation Synchronous DOM and state mutation.
+   * @returns {void}
+   */
+  #mutate = (wrapper, operation) => {
+    this.#contexts.get(wrapper)?.mutate(operation)
+  }
+
+  /** @param {HTMLElement} wrapper @returns {void} */
+  #renderEmpty(wrapper) {
+    const state = this.#states.get(wrapper)
+    if (!state) return
+    renderEmptyView(wrapper, state, {
+      t: this.#t,
+      readOnly: Boolean(this.#contexts.get(wrapper)?.readOnly),
+      onUploadClick: () => this.#triggerFileInput(wrapper),
+      onFileDropped: (file) => { void this.#handleFile(wrapper, file) },
+      customActions: this.#config.actions || [],
+      runCustomAction: async (handler) => this.#runCustomAction(wrapper, handler),
+    })
+  }
+
+  /** @param {HTMLElement} wrapper @returns {void} */
+  #renderFilled(wrapper) {
+    const state = this.#states.get(wrapper)
+    if (!state) return
+    renderFilledView(wrapper, state, {
+      t: this.#t,
+      readOnly: Boolean(this.#contexts.get(wrapper)?.readOnly),
+      mutate: (operation) => this.#mutate(wrapper, operation),
+      customActions: this.#config.actions || [],
+      onTriggerFileInput: () => this.#triggerFileInput(wrapper),
+      onPromptUrl: () => this.#promptUrl(wrapper),
+      onDelete: () => this.#deleteImage(wrapper),
+      runCustomAction: async (handler) => this.#runCustomAction(wrapper, handler),
+    })
+  }
+
+  /** @param {HTMLElement} wrapper @returns {void} */
+  #triggerFileInput(wrapper) {
+    if (this.#contexts.get(wrapper)?.readOnly) return
+    triggerFileInput({
+      accept: 'image/*',
+      signal: this.#states.get(wrapper)?.abortController?.signal,
+      onFiles: (files) => {
+        if (files[0]) void this.#handleFile(wrapper, files[0])
+      },
+    })
+  }
+
+  /**
+   * @param {HTMLElement} wrapper
+   * @param {File} file
+   * @returns {Promise<void>}
+   */
+  async #handleFile(wrapper, file) {
+    const state = this.#states.get(wrapper)
+    const context = this.#contexts.get(wrapper)
+    if (!state || !context || context.readOnly || !isSupportedImageFile(file)) return
+    const controller = state.beginTask()
+    wrapper.classList.add(CSS.loading)
+    try {
+      await this.#uploader.handle(file, (result) => {
+        if (controller.signal.aborted || this.#states.get(wrapper) !== state) return
+        this.#mutate(wrapper, () => {
+          state.data.file = { url: result.url }
+          if (result.alt && !state.data.caption) state.data.caption = result.alt
+          this.#renderFilled(wrapper)
+        })
+      }, controller.signal)
+    } finally {
+      if (state.finishTask(controller)) wrapper.classList.remove(CSS.loading)
+    }
+  }
+
+  /**
+   * @param {HTMLElement} wrapper
+   * @param {(context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null>} handler
+   * @returns {Promise<void>}
+   */
+  async #runCustomAction(wrapper, handler) {
+    const state = this.#states.get(wrapper)
+    if (!state || this.#contexts.get(wrapper)?.readOnly) return
+    const controller = state.beginTask()
+    wrapper.classList.add(CSS.loading)
+    try {
+      const result = await handler({ signal: controller.signal })
+      const url = sanitizeMediaUrl(result?.url || '')
+      if (!controller.signal.aborted && this.#states.get(wrapper) === state && url) {
+        this.#mutate(wrapper, () => {
+          state.data.file = { url }
+          if (typeof result?.alt === 'string' && result.alt && !state.data.caption) {
+            state.data.caption = result.alt
+          }
+          this.#renderFilled(wrapper)
+        })
+      }
+    } catch {
+      // Action was canceled or failed.
+    } finally {
+      if (state.finishTask(controller)) wrapper.classList.remove(CSS.loading)
+    }
+  }
+
+  /** @param {HTMLElement} wrapper @returns {void} */
+  #promptUrl(wrapper) {
+    const state = this.#states.get(wrapper)
+    if (!state || this.#contexts.get(wrapper)?.readOnly) return
+    const url = sanitizeMediaUrl(prompt(this.#t('urlPrompt', 'Image URL:')) || '')
+    if (url) {
+      state.cancelTask()
+      wrapper.classList.remove(CSS.loading)
+      this.#mutate(wrapper, () => {
+        state.data.file = { url }
+        this.#renderFilled(wrapper)
+      })
+    }
+  }
+
+  /** @param {HTMLElement} wrapper @returns {void} */
+  #deleteImage(wrapper) {
+    const state = this.#states.get(wrapper)
+    if (!state) return
+    state.cancelTask()
+    wrapper.classList.remove(CSS.loading)
+    this.#mutate(wrapper, () => {
+      state.data.file = { url: '' }
+      state.data.styles = {}
+      this.#renderEmpty(wrapper)
+    })
+  }
+}

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

@@ -0,0 +1,39 @@
+declare const _default: {
+    'plugin.image.title': string;
+    'plugin.image.upload': string;
+    'plugin.image.url': string;
+    'plugin.image.urlPrompt': string;
+    'plugin.image.dropzone': string;
+    'plugin.image.dropzoneUpload': string;
+    'plugin.image.dropzoneText': string;
+    'plugin.image.replace': string;
+    'plugin.image.delete': string;
+    'plugin.image.caption': string;
+    'plugin.image.settings': string;
+    'plugin.image.expand': string;
+    'plugin.image.background': string;
+    'plugin.image.back': string;
+    'plugin.image.dimensions': string;
+    'plugin.image.display': string;
+    'plugin.image.widthShort': string;
+    'plugin.image.heightShort': string;
+    'plugin.image.minWidth': string;
+    'plugin.image.minHeight': string;
+    'plugin.image.maxWidth': string;
+    'plugin.image.maxHeight': string;
+    'plugin.image.fit': string;
+    'plugin.image.position': string;
+    'plugin.image.color': string;
+    'plugin.image.border': string;
+    'plugin.image.width': string;
+    'plugin.image.radius': string;
+    'plugin.image.value.none': string;
+    'plugin.image.value.cover': string;
+    'plugin.image.value.contain': string;
+    'plugin.image.value.fill': string;
+    'plugin.image.value.scale-down': string;
+    'plugin.image.value.solid': string;
+    'plugin.image.value.dashed': string;
+    'plugin.image.emptyReadonly': string;
+};
+export default _default;

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

@@ -0,0 +1,38 @@
+export default {
+  'plugin.image.title': 'Image',
+  'plugin.image.upload': 'Upload',
+  'plugin.image.url': 'URL',
+  'plugin.image.urlPrompt': 'Image URL:',
+  'plugin.image.dropzone': 'or drag and drop a file here',
+  'plugin.image.dropzoneUpload': 'Upload',
+  'plugin.image.dropzoneText': 'an image from your device or drag and drop it here',
+  'plugin.image.replace': 'Replace',
+  'plugin.image.delete': 'Delete',
+  'plugin.image.caption': 'Caption',
+  'plugin.image.settings': 'Settings',
+  'plugin.image.expand': 'Expand',
+  'plugin.image.background': 'Background',
+  'plugin.image.back': 'Back',
+  'plugin.image.dimensions': 'Dimensions',
+  'plugin.image.display': 'Display',
+  'plugin.image.widthShort': 'W',
+  'plugin.image.heightShort': 'H',
+  'plugin.image.minWidth': 'Min W',
+  'plugin.image.minHeight': 'Min H',
+  'plugin.image.maxWidth': 'Max W',
+  'plugin.image.maxHeight': 'Max H',
+  'plugin.image.fit': 'Fit',
+  'plugin.image.position': 'Position',
+  'plugin.image.color': 'Color',
+  'plugin.image.border': 'Border',
+  'plugin.image.width': 'Width',
+  'plugin.image.radius': 'Radius',
+  'plugin.image.value.none': 'None',
+  'plugin.image.value.cover': 'Cover',
+  'plugin.image.value.contain': 'Contain',
+  'plugin.image.value.fill': 'Fill',
+  'plugin.image.value.scale-down': 'Scale down',
+  'plugin.image.value.solid': 'Solid',
+  'plugin.image.value.dashed': 'Dashed',
+  'plugin.image.emptyReadonly': 'No image',
+}

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

@@ -0,0 +1,39 @@
+declare const _default: {
+    'plugin.image.title': string;
+    'plugin.image.upload': string;
+    'plugin.image.url': string;
+    'plugin.image.urlPrompt': string;
+    'plugin.image.dropzone': string;
+    'plugin.image.dropzoneUpload': string;
+    'plugin.image.dropzoneText': string;
+    'plugin.image.replace': string;
+    'plugin.image.delete': string;
+    'plugin.image.caption': string;
+    'plugin.image.settings': string;
+    'plugin.image.expand': string;
+    'plugin.image.background': string;
+    'plugin.image.back': string;
+    'plugin.image.dimensions': string;
+    'plugin.image.display': string;
+    'plugin.image.widthShort': string;
+    'plugin.image.heightShort': string;
+    'plugin.image.minWidth': string;
+    'plugin.image.minHeight': string;
+    'plugin.image.maxWidth': string;
+    'plugin.image.maxHeight': string;
+    'plugin.image.fit': string;
+    'plugin.image.position': string;
+    'plugin.image.color': string;
+    'plugin.image.border': string;
+    'plugin.image.width': string;
+    'plugin.image.radius': string;
+    'plugin.image.value.none': string;
+    'plugin.image.value.cover': string;
+    'plugin.image.value.contain': string;
+    'plugin.image.value.fill': string;
+    'plugin.image.value.scale-down': string;
+    'plugin.image.value.solid': string;
+    'plugin.image.value.dashed': string;
+    'plugin.image.emptyReadonly': string;
+};
+export default _default;

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

@@ -0,0 +1,38 @@
+export default {
+  'plugin.image.title': 'Изображение',
+  'plugin.image.upload': 'Загрузить',
+  'plugin.image.url': 'URL',
+  'plugin.image.urlPrompt': 'URL изображения:',
+  'plugin.image.dropzone': 'или перетащите файл сюда',
+  'plugin.image.dropzoneUpload': 'Загрузите',
+  'plugin.image.dropzoneText': 'изображение с устройства или перетащите его сюда',
+  'plugin.image.replace': 'Заменить',
+  'plugin.image.delete': 'Удалить',
+  'plugin.image.caption': 'Подпись',
+  'plugin.image.settings': 'Настройки',
+  'plugin.image.expand': 'Расширить',
+  'plugin.image.background': 'Фон',
+  'plugin.image.back': 'Назад',
+  'plugin.image.dimensions': 'Размеры',
+  'plugin.image.display': 'Отображение',
+  'plugin.image.widthShort': 'Ш',
+  'plugin.image.heightShort': 'В',
+  'plugin.image.minWidth': 'Мин. ширина',
+  'plugin.image.minHeight': 'Мин. высота',
+  'plugin.image.maxWidth': 'Макс. ширина',
+  'plugin.image.maxHeight': 'Макс. высота',
+  'plugin.image.fit': 'Вписывание',
+  'plugin.image.position': 'Положение',
+  'plugin.image.color': 'Цвет',
+  'plugin.image.border': 'Рамка',
+  'plugin.image.width': 'Ширина',
+  'plugin.image.radius': 'Радиус',
+  'plugin.image.value.none': 'Нет',
+  'plugin.image.value.cover': 'Заполнить область',
+  'plugin.image.value.contain': 'Вписать целиком',
+  'plugin.image.value.fill': 'Растянуть',
+  'plugin.image.value.scale-down': 'Только уменьшать',
+  'plugin.image.value.solid': 'Сплошная',
+  'plugin.image.value.dashed': 'Штриховая',
+  'plugin.image.emptyReadonly': 'Нет изображения',
+}

package/dist/plugins/image/settings.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @typedef {Object} SettingsDeps
+ * @property {(key: string, fallback: string) => string} t
+ * @property {(operation: () => void) => void} mutate
+ */
+/**
+ * Build the settings dropdown panel: a styled form with width/height,
+ * object fit/position, expand toggle, background toggle/color, and border.
+ *
+ * Mutations write directly into `state.data.styles` (or `state.data.expanded`
+ * etc.) inside the core-owned mutation boundary so undo/save see each
+ * control action immediately.
+ *
+ * @param {HTMLElement} wrapper
+ * @param {import('./state.js').ImageState} state
+ * @param {SettingsDeps} deps
+ * @returns {HTMLElement}
+ */
+export function buildSettingsPanel(wrapper: HTMLElement, state: import("./state.js").ImageState, deps: SettingsDeps): HTMLElement;
+export type SettingsDeps = {
+    t: (key: string, fallback: string) => string;
+    mutate: (operation: () => void) => void;
+};