@shelamkoff/rector 1.0.0

package/dist/core/I18n.js

@@ -0,0 +1,296 @@
+import en from './locale/en.js'
+
+/**
+ * @typedef {import('./types').I18nMessages} I18nMessages
+ * @typedef {import('./types').MessageKey} MessageKey
+ * @typedef {import('./types').PluralForms} PluralForms
+ * @typedef {import('./types').LocaleValue} LocaleValue
+ */
+
+/**
+ * Pluralization rules per language. Returns the CLDR plural category for a count.
+ * Add new languages here as needed; default falls through to English rules.
+ *
+ * @type {Record<string, (n: number) => 'zero' | 'one' | 'two' | 'few' | 'many' | 'other'>}
+ */
+const PLURAL_RULES = {
+  en: (n) => (n === 1 ? 'one' : 'other'),
+  ru: (n) => {
+    const mod10 = n % 10
+    const mod100 = n % 100
+    if (mod10 === 1 && mod100 !== 11) return 'one'
+    if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) return 'few'
+    return 'many'
+  },
+}
+
+/**
+ * Interpolate `{name}` placeholders in a message string.
+ * @param {string} msg
+ * @param {Record<string, string | number>} [params]
+ * @returns {string}
+ */
+function interpolate(msg, params) {
+  if (!params) return msg
+  let result = msg
+  for (const [k, v] of Object.entries(params)) {
+    result = result.replaceAll(`{${k}}`, String(v))
+  }
+  return result
+}
+
+/**
+ * Translation dictionary with:
+ *  - fallback chain (primary → fallback language → key)
+ *  - explicit `has()` for missing-key detection
+ *  - plural rules per language (CLDR categories)
+ *  - scoped sub-instances for plugin namespacing
+ *  - immutable freeze after init
+ *  - dev-mode warnings on missing keys
+ *
+ * Architecturally: ONE instance per editor, shared by core and all plugins.
+ * Plugins receive a `ScopedI18n` wrapper that auto-prefixes keys with their
+ * type (e.g. `plugin.heading.*`), so plugin code uses short local keys
+ * without worrying about cross-plugin collisions.
+ */
+export class I18n {
+  /** @type {Record<string, LocaleValue>} */
+  #messages
+
+  /** @type {Record<string, LocaleValue> | null} */
+  #fallback
+
+  /** @type {string} */
+  #lang
+
+  /** @type {boolean} */
+  #frozen = false
+
+  /**
+   * @param {Partial<I18nMessages>} [messages]   primary locale (e.g. ru)
+   * @param {Partial<I18nMessages>} [fallback]   fallback locale (e.g. en) used when a key is missing in primary
+   * @param {string} [lang]                       language code for plural rules ('en', 'ru', ...)
+   */
+  constructor(messages, fallback, lang = 'en') {
+    this.#messages = /** @type {Record<string, LocaleValue>} */ ({ ...(messages || en) })
+    this.#fallback = fallback ? /** @type {Record<string, LocaleValue>} */ ({ ...fallback }) : null
+    this.#lang = lang
+  }
+
+  /**
+   * Merge additional messages into the primary dictionary.
+   * Plugins call this to register their own keys at runtime.
+   * Throws after `freeze()`.
+   *
+   * @param {Partial<I18nMessages>} messages
+   */
+  merge(messages) {
+    if (this.#frozen) throw new Error('[I18n] Dictionary is frozen — cannot merge after init')
+    Object.assign(this.#messages, messages)
+  }
+
+  /**
+   * Merge additional messages into the fallback dictionary.
+   * Used so plugin English locales become the fallback for other languages.
+   * Throws after `freeze()`.
+   *
+   * @param {Partial<I18nMessages>} messages
+   */
+  mergeFallback(messages) {
+    if (this.#frozen) throw new Error('[I18n] Dictionary is frozen — cannot merge after init')
+    if (!this.#fallback) this.#fallback = {}
+    Object.assign(this.#fallback, messages)
+  }
+
+  /**
+   * Lock the dictionary against further mutation. Called by `createEditor`
+   * after all plugins have registered. Subsequent `merge()` calls throw,
+   * and the underlying objects are deep-frozen.
+   */
+  freeze() {
+    if (this.#frozen) return
+    this.#frozen = true
+    Object.freeze(this.#messages)
+    if (this.#fallback) Object.freeze(this.#fallback)
+  }
+
+  /**
+   * @returns {boolean} true if the i18n dictionary has been frozen
+   */
+  get isFrozen() {
+    return this.#frozen
+  }
+
+  /**
+   * Check whether a key resolves to anything (primary or fallback).
+   * Use this to distinguish "missing" from "intentionally returns the key".
+   *
+   * @param {MessageKey | (string & {})} key
+   * @returns {boolean}
+   */
+  has(key) {
+    if (key in this.#messages) return true
+    return !!(this.#fallback && key in this.#fallback);
+  }
+
+  /**
+   * Resolve a translation key with optional `{name}` interpolation.
+   *
+   * Resolution order:
+   *  1. primary dictionary
+   *  2. fallback dictionary (if set)
+   *  3. `defaultValue` from options (if provided)
+   *  4. the key itself, verbatim
+   *
+   * For string values, returns the interpolated message.
+   * For plural-form values (object with `one`/`few`/`many`/`other`), returns the
+   * `other` form interpolated — callers wanting count-aware selection should use `plural()`.
+   *
+   * @param {MessageKey | (string & {})} key
+   * @param {Record<string, string | number>} [params] interpolation params
+   * @returns {string}
+   */
+  t(key, params) {
+    const value = this.#resolve(key)
+    if (value === undefined) {
+      this.#warnMissing(key)
+      return key
+    }
+    if (typeof value === 'string') return interpolate(value, params)
+    // Plural object accessed via t() — fall back to "other" form.
+    return interpolate(value.other ?? Object.values(value)[0] ?? '', params)
+  }
+
+  /**
+   * Resolve a key as a pluralized message.
+   *
+   * The locale value should be a `PluralForms` object (`{ one, few, many, other }`).
+   * If it's a plain string, it's interpolated with `{count}` like a regular message.
+   *
+   * The plural form is chosen by CLDR rules for the current language. `count` is
+   * automatically merged into `params` so messages can use `{count}`.
+   *
+   * @param {MessageKey | (string & {})} key
+   * @param {number} count
+   * @param {Record<string, string | number>} [params]
+   * @returns {string}
+   */
+  plural(key, count, params) {
+    const value = this.#resolve(key)
+    if (value === undefined) {
+      this.#warnMissing(key)
+      return key
+    }
+    const merged = { ...params, count }
+    if (typeof value === 'string') return interpolate(value, merged)
+
+    const rule = PLURAL_RULES[this.#lang] ?? PLURAL_RULES.en
+    const category = /** @type {(n: number) => keyof PluralForms} */ (rule)(count)
+    const form = value[category] ?? value.other ?? Object.values(value)[0] ?? ''
+    return interpolate(form, merged)
+  }
+
+  /**
+   * Create a scoped wrapper that auto-prefixes every key with `prefix.`
+   * (e.g. `i18n.scope('plugin.heading')` makes `t('title')` resolve `plugin.heading.title`).
+   *
+   * Backward-compat: keys that already start with `prefix.` are passed through
+   * untouched, so legacy plugin code using full keys keeps working alongside
+   * new code using short keys.
+   *
+   * @param {string} prefix
+   * @returns {ScopedI18n}
+   */
+  scope(prefix) {
+    return new ScopedI18n(this, prefix)
+  }
+
+  // ── private ────────────────────────────────────────────────────────────────
+
+  /**
+   * @param {string} key
+   * @returns {LocaleValue | undefined}
+   */
+  #resolve(key) {
+    if (key in this.#messages) return this.#messages[key]
+    if (this.#fallback && key in this.#fallback) return this.#fallback[key]
+    return undefined
+  }
+
+  /** @param {string} key */
+  #warnMissing(key) {
+    // Dev warning — surfaces missing keys early during plugin development.
+    // Disabled when frozen has run AND we're not in dev (heuristic: warn if window
+    // exists, since this is a browser-side library).
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn(`[I18n] Missing translation key: "${key}"`)
+    }
+  }
+}
+
+/**
+ * Plugin-facing i18n wrapper. Auto-prefixes every key with the plugin's
+ * namespace, so plugin code can write `_t('title')` instead of
+ * `_t('plugin.heading.title')`.
+ *
+ * Backward-compat: if a caller passes a key that already starts with the
+ * prefix, it's left untouched. This lets old code coexist with new code
+ * during incremental migration.
+ */
+export class ScopedI18n {
+  /** @type {I18n} */
+  #parent
+
+  /** @type {string} */
+  #prefix
+
+  /**
+   * @param {I18n} parent
+   * @param {string} prefix
+   */
+  constructor(parent, prefix) {
+    this.#parent = parent
+    this.#prefix = prefix
+  }
+
+  /** @param {string} key */
+  #fullKey(key) {
+    return key.startsWith(this.#prefix + '.') ? key : `${this.#prefix}.${key}`
+  }
+
+  /**
+   * @param {string} key
+   * @param {Record<string, string | number>} [params]
+   * @returns {string}
+   */
+  t(key, params) {
+    return this.#parent.t(this.#fullKey(key), params)
+  }
+
+  /**
+   * @param {string} key
+   * @returns {boolean}
+   */
+  has(key) {
+    return this.#parent.has(this.#fullKey(key))
+  }
+
+  /**
+   * @param {string} key
+   * @param {number} count
+   * @param {Record<string, string | number>} [params]
+   * @returns {string}
+   */
+  plural(key, count, params) {
+    return this.#parent.plural(this.#fullKey(key), count, params)
+  }
+
+  /**
+   * Create a sub-scope under the current prefix.
+   * @param {string} sub
+   * @returns {ScopedI18n}
+   */
+  scope(sub) {
+    return new ScopedI18n(this.#parent, `${this.#prefix}.${sub}`)
+  }
+}

package/dist/core/InlinePatternMatcher.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @typedef {{ plugin: import('./types.js').InlinePlugin, pattern: RegExp }} PatternEntry
+ */
+/**
+ * Matches text patterns in contenteditable blocks and replaces them with inline plugin widgets.
+ * Handles:
+ * - Paste: scan all text nodes after paste for pattern matches
+ * - Input: when space/Enter is typed, check previous word for pattern match
+ */
+export class InlinePatternMatcher {
+    /**
+     * @param {HTMLElement} rootEl
+     * @param {import('./types.js').IInlinePluginRegistry} registry
+     * @param {import('./types.js').InlinePluginContext} ctx
+     * @param {import('./types.js').IEventBus} events
+     * @param {import('./types.js').IBlockManager} blocks
+     * @param {import('./CommandDispatcher.js').CommandDispatcher} commands
+     */
+    constructor(rootEl: HTMLElement, registry: import("./types.js").IInlinePluginRegistry, ctx: import("./types.js").InlinePluginContext, events: import("./types.js").IEventBus, blocks: import("./types.js").IBlockManager, commands: import("./CommandDispatcher.js").CommandDispatcher);
+    destroy(): void;
+    #private;
+}
+export type PatternEntry = {
+    plugin: import("./types.js").InlinePlugin;
+    pattern: RegExp;
+};

package/dist/core/InlinePatternMatcher.js

@@ -0,0 +1,267 @@
+import { EditorEvent } from './editorEvents.js'
+import { hydrateInlinePlugins } from './hydrateInlinePlugins.js'
+
+/**
+ * @typedef {{ plugin: import('./types').InlinePlugin, pattern: RegExp }} PatternEntry
+ */
+
+/**
+ * Matches text patterns in contenteditable blocks and replaces them with inline plugin widgets.
+ * Handles:
+ * - Paste: scan all text nodes after paste for pattern matches
+ * - Input: when space/Enter is typed, check previous word for pattern match
+ */
+export class InlinePatternMatcher {
+  /** @type {HTMLElement} */
+  #rootEl
+
+  /** @type {import('./types').IInlinePluginRegistry} */
+  #registry
+
+  /** @type {import('./types').InlinePluginContext} */
+  #ctx
+
+  /** @type {import('./types').IEventBus} */
+  #events
+
+  /** @type {import('./types').IBlockManager} */
+  #blocks
+
+  /** @type {import('./CommandDispatcher').CommandDispatcher} */
+  #mutations
+
+  /** @type {() => void} */
+  #unsubscribePasteApplied
+
+  /** @type {PatternEntry[]} */
+  #patterns = []
+
+  /**
+   * @param {HTMLElement} rootEl
+   * @param {import('./types').IInlinePluginRegistry} registry
+   * @param {import('./types').InlinePluginContext} ctx
+   * @param {import('./types').IEventBus} events
+   * @param {import('./types').IBlockManager} blocks
+   * @param {import('./CommandDispatcher').CommandDispatcher} commands
+   */
+  constructor(rootEl, registry, ctx, events, blocks, commands) {
+    this.#rootEl = rootEl
+    this.#registry = registry
+    this.#ctx = ctx
+    this.#events = events
+    this.#blocks = blocks
+    this.#mutations = commands
+
+    // Collect all patterns from plugins
+    for (const plugin of registry.values()) {
+      if (plugin.pasteConfig?.patterns) {
+        for (const pattern of plugin.pasteConfig.patterns) {
+          this.#patterns.push({ plugin, pattern })
+        }
+      }
+    }
+
+    if (this.#patterns.length === 0) return
+
+    this.#unsubscribePasteApplied = events.on(EditorEvent.PASTE_APPLIED, this.#onPasteApplied)
+    rootEl.addEventListener('keydown', this.#onKeyDown)
+  }
+
+  destroy() {
+    this.#unsubscribePasteApplied?.()
+    this.#rootEl.removeEventListener('keydown', this.#onKeyDown)
+  }
+
+  /**
+   * Scan the exact block interval affected by Clipboard while its undo batch
+   * is still open, so paste + automatic widgets remain one history step.
+   * @param {{ startBlockId?: string, endBlockId?: string }} payload
+   */
+  #onPasteApplied = (payload = {}) => {
+    const start = payload.startBlockId
+      ? this.#blocks.getBlockIndex(payload.startBlockId)
+      : this.#blocks.getCurrentIndex()
+    const end = payload.endBlockId
+      ? this.#blocks.getBlockIndex(payload.endBlockId)
+      : this.#blocks.getCurrentIndex()
+    if (start < 0 || end < 0) return
+
+    const candidates = []
+    for (let index = Math.min(start, end); index <= Math.max(start, end); index++) {
+      const block = this.#blocks.getBlockByIndex(index)
+      if (block) candidates.push(block)
+    }
+    this.#replacePatterns(candidates)
+  }
+
+  /**
+   * On space/Enter, check if the word before caret matches a pattern.
+   */
+  #onKeyDown = (/** @type {KeyboardEvent} */ e) => {
+    if (e.key !== ' ' && e.key !== 'Enter') return
+
+    const sel = window.getSelection()
+    if (!sel || !sel.isCollapsed || !sel.rangeCount) return
+
+    const node = sel.anchorNode
+    if (!node || node.nodeType !== Node.TEXT_NODE) return
+    const textNode = /** @type {import('./types').DOMText} */ (node)
+    // Skip inside inline plugin widgets
+    if (/** @type {Element | null} */ (node.parentElement)?.closest('[data-inline-plugin]')) return
+
+    const offset = sel.anchorOffset
+    const text = textNode.data
+    if (!text || offset === 0) return
+
+    // Extract the word before caret (back to previous space or start)
+    let wordStart = offset - 1
+    while (wordStart > 0 && text[wordStart - 1] !== ' ' && text[wordStart - 1] !== '\u00A0') {
+      wordStart--
+    }
+
+    const word = text.slice(wordStart, offset)
+    if (!word) return
+
+    // Check against patterns
+    for (const { plugin, pattern } of this.#patterns) {
+      if (this.#matches(pattern, word)) {
+        e.preventDefault()
+        e.stopPropagation()
+        const block = this.#blocks.getBlockByChildNode(node)
+        if (!block) return
+        this.#mutations.runForBlock(block, () => {
+          this.#replaceMatch(textNode, wordStart, offset, plugin, word)
+
+          // Insert the space that was suppressed by preventDefault
+          if (e.key === ' ') {
+            const r = sel.getRangeAt(0)
+            const spaceNode = document.createTextNode(' ')
+            r.insertNode(spaceNode)
+            r.setStartAfter(spaceNode)
+            r.collapse(true)
+            sel.removeAllRanges()
+            sel.addRange(r)
+          }
+        })
+        return
+      }
+    }
+  }
+
+  /** @param {import('./types').IBlock[]} blocks */
+  #replacePatterns(blocks) {
+    /** @type {Map<import('./types').IBlock, { node: import('./types').DOMText, match: string, start: number, end: number, plugin: import('./types').InlinePlugin }[]>} */
+    const matchesByBlock = new Map()
+    for (const block of blocks) {
+      const matches = []
+      const walker = document.createTreeWalker(block.contentElement, NodeFilter.SHOW_TEXT)
+      while (walker.nextNode()) {
+        const node = /** @type {import('./types').DOMText} */ (walker.currentNode)
+        if (node.parentElement?.closest('[data-inline-plugin]')) continue
+        this.#findMatches(node.textContent || '', node, matches)
+      }
+      if (matches.length > 0) matchesByBlock.set(block, matches)
+    }
+    if (matchesByBlock.size === 0) return
+
+    this.#mutations.runForBlocks(matchesByBlock.keys(), () => {
+      for (const [block, matches] of matchesByBlock) {
+        for (let index = matches.length - 1; index >= 0; index--) {
+          const match = matches[index]
+          if (match) this.#replaceMatch(match.node, match.start, match.end, match.plugin, match.match)
+        }
+        hydrateInlinePlugins(block.contentElement, this.#registry, this.#ctx)
+      }
+    })
+  }
+
+  /**
+   * Find all pattern matches in a text string.
+   * @param {string} text
+   * @param {import('./types').DOMText} node
+   * @param {{ node: import('./types').DOMText, match: string, start: number, end: number, plugin: import('./types').InlinePlugin }[]} results
+   */
+  #findMatches(text, node, results) {
+    // Split text by whitespace and check each word
+    const words = text.split(/(\s+)/)
+    let pos = 0
+
+    for (const segment of words) {
+      if (/^\s+$/.test(segment)) {
+        pos += segment.length
+        continue
+      }
+
+      for (const { plugin, pattern } of this.#patterns) {
+        if (this.#matches(pattern, segment)) {
+          results.push({
+            node,
+            match: segment,
+            start: pos,
+            end: pos + segment.length,
+            plugin,
+          })
+          break // One match per word
+        }
+      }
+
+      pos += segment.length
+    }
+  }
+
+  /**
+   * RegExp instances are plugin-owned and may use `g` or `y`. Calling
+   * `test()` on those expressions mutates `lastIndex`, which otherwise makes
+   * identical adjacent patterns match only intermittently.
+   * @param {RegExp} pattern
+   * @param {string} value
+   */
+  #matches(pattern, value) {
+    pattern.lastIndex = 0
+    const matched = pattern.test(value)
+    pattern.lastIndex = 0
+    return matched
+  }
+
+  /**
+   * Replace a text range with an inline plugin widget.
+   * @param {import('./types').DOMText} textNode
+   * @param {number} start
+   * @param {number} end
+   * @param {import('./types').InlinePlugin} plugin
+   * @param {string} matchText
+   */
+  #replaceMatch(textNode, start, end, plugin, matchText) {
+    const data = plugin.onPatternMatch?.(matchText) ?? { value: matchText }
+    const widget = plugin.createWidget(data)
+    if (!(widget instanceof HTMLElement)) {
+      throw new TypeError(`Inline plugin "${plugin.type}" createWidget() must return an HTMLElement`)
+    }
+
+    // Split text node to isolate the match
+    if (end < textNode.length) {
+      textNode.splitText(end)
+    }
+    const targetNode = start > 0
+      ? /** @type {import('./types').DOMText} */ (textNode.splitText(start))
+      : textNode
+
+    // Replace the matched text with widget
+    targetNode.parentNode?.insertBefore(widget, targetNode)
+    targetNode.remove()
+
+    // Hydrate immediately
+    plugin.hydrate(widget, this.#ctx)
+    widget.dataset.hydrated = '1'
+
+    // Place caret after widget
+    const sel = window.getSelection()
+    if (sel) {
+      const range = document.createRange()
+      range.setStartAfter(widget)
+      range.collapse(true)
+      sel.removeAllRanges()
+      sel.addRange(range)
+    }
+  }
+}

package/dist/core/InlinePluginRegistry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @typedef {import('./types.js').InlinePlugin} InlinePlugin
+ * @typedef {import('./types.js').InlinePluginContext} InlinePluginContext
+ */
+/** @typedef {import('./types.js').IInlinePluginRegistry} IInlinePluginRegistryContract */
+/**
+ * Registry for inline plugins (widgets inside text blocks).
+ * Inline plugins are different from block plugins (full blocks) and inline tools (text formatting).
+ * @implements {IInlinePluginRegistryContract}
+ */
+export class InlinePluginRegistry implements IInlinePluginRegistryContract {
+    /**
+     * @param {InlinePlugin[]} plugins
+     */
+    constructor(plugins?: InlinePlugin[]);
+    /**
+     * @param {InlinePlugin} plugin
+     */
+    register(plugin: InlinePlugin): void;
+    /**
+     * @param {string} type
+     * @returns {InlinePlugin | undefined}
+     */
+    get(type: string): InlinePlugin | undefined;
+    /**
+     * @param {string} char
+     * @returns {InlinePlugin | undefined}
+     */
+    getByTrigger(char: string): InlinePlugin | undefined;
+    /** @returns {IterableIterator<InlinePlugin>} */
+    values(): IterableIterator<InlinePlugin>;
+    /** @returns {number} */
+    get size(): number;
+    /** @returns {boolean} */
+    get hasTriggers(): boolean;
+    /**
+     * Acquire resources that must be scoped to one live editor root.
+     * @param {HTMLElement} rootElement
+     * @param {import('./types.js').InlinePluginContext} ctx
+     */
+    mount(rootElement: HTMLElement, ctx: import("./types.js").InlinePluginContext): void;
+    /**
+     * Get all registered trigger characters.
+     * @returns {string[]}
+     */
+    triggerKeys(): string[];
+    /**
+     * Release plugin-level resources such as global listeners and shared styles.
+     */
+    destroy(): void;
+    #private;
+}
+export type InlinePlugin = import("./types.js").InlinePlugin;
+export type InlinePluginContext = import("./types.js").InlinePluginContext;
+export type IInlinePluginRegistryContract = import("./types.js").IInlinePluginRegistry;