@openreachtech/furo-vue 1.3.1

package/lib/components/organisms/FuroEditor/FuroEditorCommandContext.js

@@ -0,0 +1,420 @@
+/**
+ * Command facade over a Tiptap editor instance.
+ *
+ * Owns the selection/command surface for FuroEditor: querying active marks and
+ * nodes, toggling formatting, applying headings/alignment/color, and editing links.
+ * It is a plain helper (not a Vue context) so it can be unit-tested with a stubbed
+ * editor ref.
+ */
+export default class FuroEditorCommandContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroEditorCommandContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    editorRef,
+  }) {
+    this.editorRef = editorRef
+  }
+
+  /**
+   * Factory method to create a new instance of this class.
+   *
+   * @param {FuroEditorCommandContextParams} params - Parameters of this factory method.
+   * @returns {FuroEditorCommandContext} - New instance of this class.
+   */
+  static create ({
+    editorRef,
+  }) {
+    return new this({
+      editorRef,
+    })
+  }
+
+  /**
+   * get: the live Tiptap editor instance, or null before it mounts.
+   *
+   * @returns {import('@tiptap/vue-3').Editor | null} - Editor instance.
+   */
+  get editor () {
+    return this.editorRef.value
+      ?? null
+  }
+
+  /**
+   * Whether a node or mark is currently active.
+   *
+   * @param {{
+   *   name?: string | null
+   *   attributes?: Record<string, *> | null
+   * }} [params] - Parameters of this method.
+   * @returns {boolean} - true when active.
+   */
+  isActive ({
+    name = null,
+    attributes = null,
+  } = {}) {
+    if (!this.editor) {
+      return false
+    }
+
+    if (!name) {
+      return this.editor.isActive(attributes ?? {})
+    }
+
+    if (!attributes) {
+      return this.editor.isActive(name)
+    }
+
+    return this.editor.isActive(name, attributes)
+  }
+
+  /**
+   * Whether any of the given text-align values is active.
+   *
+   * @param {{
+   *   alignments: Array<string>
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when one alignment is active.
+   */
+  hasActiveTextAlign ({
+    alignments,
+  }) {
+    return alignments.some(alignment => this.isActive({
+      attributes: {
+        textAlign: alignment,
+      },
+    }))
+  }
+
+  /**
+   * Focus the editor and return a fresh command chain.
+   *
+   * @returns {import('@tiptap/core').ChainedCommands | null} - Focused chain, or null.
+   */
+  focusChain () {
+    if (!this.editor) {
+      return null
+    }
+
+    return this.editor
+      .chain()
+      .focus()
+  }
+
+  /**
+   * Toggle a node or mark by its chained-command name (toggleBold, toggleBulletList, ...).
+   *
+   * @param {{
+   *   command: string
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  toggleNodeOrMark ({
+    command,
+  }) {
+    const chain = this.focusChain()
+
+    if (!chain) {
+      return
+    }
+
+    const commandRunnerHash = /** @type {Record<string, () => import('@tiptap/core').ChainedCommands>} */ (
+      /** @type {*} */ (chain)
+    )
+    const runCommand = commandRunnerHash[command]
+
+    if (typeof runCommand !== 'function') {
+      return
+    }
+
+    runCommand.call(chain)
+      .run()
+  }
+
+  /**
+   * Execute a dropdown command (heading level, paragraph, alignment, color).
+   *
+   * @param {{
+   *   command: string
+   *   level?: number | null
+   *   value?: string | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  executeDropdownCommand ({
+    command,
+    level = null,
+    value = null,
+  }) {
+    const chain = this.focusChain()
+
+    if (!chain) {
+      return
+    }
+
+    const commandHash = {
+      setParagraph: () => chain.setParagraph()
+        .run(),
+      toggleHeading: () => this.runToggleHeading({
+        chain,
+        level,
+      }),
+      setTextAlign: () => this.runSetTextAlign({
+        chain,
+        value,
+      }),
+      setColor: () => this.runSetColor({
+        chain,
+        value,
+      }),
+    }
+
+    commandHash[/** @type {keyof typeof commandHash} */ (command)]?.()
+  }
+
+  /**
+   * Run a heading toggle when a level is provided.
+   *
+   * @param {{
+   *   chain: import('@tiptap/core').ChainedCommands
+   *   level: number | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  runToggleHeading ({
+    chain,
+    level,
+  }) {
+    if (!level) {
+      return
+    }
+
+    chain.toggleHeading({
+      level: /** @type {import('@tiptap/extension-heading').Level} */ (level),
+    })
+      .run()
+  }
+
+  /**
+   * Run a text-align command when a value is provided.
+   *
+   * @param {{
+   *   chain: import('@tiptap/core').ChainedCommands
+   *   value: string | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  runSetTextAlign ({
+    chain,
+    value,
+  }) {
+    if (!value) {
+      return
+    }
+
+    chain.setTextAlign(value)
+      .run()
+  }
+
+  /**
+   * Run a color command; an empty value clears the color.
+   *
+   * @param {{
+   *   chain: import('@tiptap/core').ChainedCommands
+   *   value: string | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  runSetColor ({
+    chain,
+    value,
+  }) {
+    if (!value) {
+      chain.unsetColor()
+        .run()
+
+      return
+    }
+
+    chain.setColor(value)
+      .run()
+  }
+
+  /**
+   * Insert literal text at the cursor (used to trigger the mention popup with '@').
+   *
+   * @param {{
+   *   text: string
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  insertText ({
+    text,
+  }) {
+    const chain = this.focusChain()
+
+    if (!chain) {
+      return
+    }
+
+    chain.insertContent(text)
+      .run()
+  }
+
+  /**
+   * Insert an inline image node at the cursor, or at an explicit document position.
+   *
+   * @param {{
+   *   src: string
+   *   alt?: string
+   *   position?: number | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  insertImage ({
+    src,
+    alt = '',
+    position = null,
+  }) {
+    const chain = this.focusChain()
+
+    if (!chain) {
+      return
+    }
+
+    const imageContent = {
+      type: 'image',
+      attrs: {
+        src,
+        alt,
+      },
+    }
+
+    if (position === null) {
+      chain.insertContent(imageContent)
+        .run()
+
+      return
+    }
+
+    chain.insertContentAt(position, imageContent)
+      .run()
+  }
+
+  /**
+   * Read the link href, display text, and document range of the current selection.
+   *
+   * @returns {{
+   *   url: string
+   *   displayText: string
+   *   range: { from: number, to: number } | null
+   * }} - Current link details for the selection.
+   */
+  extractSelectionLink () {
+    if (!this.editor) {
+      return {
+        url: '',
+        displayText: '',
+        range: null,
+      }
+    }
+
+    this.editor
+      .chain()
+      .focus()
+      .extendMarkRange('link')
+      .run()
+
+    const {
+      from,
+      to,
+    } = this.editor.state.selection
+
+    const displayText = this.editor.state
+      .doc
+      .textBetween(from, to)
+    const {
+      href,
+    } = this.editor.getAttributes('link')
+
+    return {
+      url: href ?? '',
+      displayText: displayText ?? '',
+      range: {
+        from,
+        to,
+      },
+    }
+  }
+
+  /**
+   * Apply or clear a link over a document range (or the current selection).
+   *
+   * Using an explicit range keeps the operation reliable after the link dialog
+   * (a focus-trapped modal) closes, since it does not depend on the live cursor.
+   *
+   * @param {{
+   *   url: string
+   *   displayText: string
+   *   range?: { from: number, to: number } | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  applyLink ({
+    url,
+    displayText,
+    range = null,
+  }) {
+    if (!this.editor) {
+      return
+    }
+
+    const trimmedUrl = url.trim()
+    const trimmedDisplayText = displayText.trim()
+
+    const chain = this.editor
+      .chain()
+      .focus()
+
+    const targetedChain = range
+      ? chain.setTextSelection(range)
+      : chain
+
+    if (!trimmedUrl) {
+      targetedChain
+        .unsetLink()
+        .run()
+
+      return
+    }
+
+    const linkText = trimmedDisplayText.length > 0
+      ? trimmedDisplayText
+      : trimmedUrl
+
+    targetedChain
+      .insertContent([
+        {
+          type: 'text',
+          text: linkText,
+          marks: [
+            {
+              type: 'link',
+              attrs: {
+                href: trimmedUrl,
+              },
+            },
+          ],
+        },
+      ])
+      .run()
+  }
+}
+
+/**
+ * @typedef {{
+ *   editorRef: ReturnType<typeof import('@tiptap/vue-3').useEditor>
+ * }} FuroEditorCommandContextParams
+ */