@openreachtech/furo-vue 1.3.1

package/lib/components/organisms/FuroEditor/build-editor-extensions.js

@@ -0,0 +1,97 @@
+import StarterKit from '@tiptap/starter-kit'
+import {
+  Highlight as TiptapHighlight,
+} from '@tiptap/extension-highlight'
+import {
+  Typography,
+} from '@tiptap/extension-typography'
+import {
+  TextStyleKit,
+} from '@tiptap/extension-text-style'
+import TextAlign from '@tiptap/extension-text-align'
+import {
+  Image as TiptapImage,
+} from '@tiptap/extension-image'
+import {
+  Placeholder,
+} from '@tiptap/extensions'
+
+import {
+  PreserveNewlinesPasteExtension,
+} from './PreserveNewlinesPasteExtension.js'
+
+const LINK_HTML_ATTRIBUTES = {
+  target: '_blank',
+  rel: 'noopener noreferrer nofollow',
+}
+
+const TEXT_ALIGN_TYPES = [
+  'heading',
+  'paragraph',
+]
+
+/**
+ * Build the Tiptap extension list for FuroEditor from parcel flags.
+ *
+ * StarterKit supplies paragraph, headings, bold/italic/underline/strike, lists,
+ * blockquote, code, link, and history. Color comes from TextStyleKit, alignment
+ * from TextAlign, plus Highlight, Typography, Placeholder, and the newline-preserving
+ * paste plugin. An optional pre-configured mention extension is appended last.
+ *
+ * @param {{
+ *   placeholder?: string
+ *   enableImage?: boolean
+ *   mentionExtension?: import('@tiptap/core').AnyExtension | null
+ *   extraExtensions?: Array<import('@tiptap/core').AnyExtension>
+ * }} [params] - Parameters of this function.
+ * @returns {Array<import('@tiptap/core').AnyExtension>} - Ordered extension list.
+ */
+export function buildEditorExtensions ({
+  placeholder = '',
+  enableImage = false,
+  mentionExtension = null,
+  extraExtensions = [],
+} = {}) {
+  const baseExtensions = [
+    StarterKit.configure({
+      link: {
+        autolink: true,
+        linkOnPaste: true,
+        openOnClick: true,
+        HTMLAttributes: LINK_HTML_ATTRIBUTES,
+      },
+    }),
+    TiptapHighlight,
+    Typography,
+    TextStyleKit,
+    TextAlign.configure({
+      types: TEXT_ALIGN_TYPES,
+    }),
+    Placeholder.configure({
+      placeholder,
+    }),
+    PreserveNewlinesPasteExtension,
+  ]
+
+  const imageExtensions = enableImage
+    ? [
+      TiptapImage.configure({
+        inline: false,
+        allowBase64: true,
+      }),
+    ]
+    : []
+
+  const mentionExtensions = mentionExtension
+    ? [
+      mentionExtension,
+    ]
+    : []
+
+  return [
+    ...baseExtensions,
+    ...imageExtensions,
+    ...mentionExtensions,
+    ...extraExtensions,
+  ]
+}

package/lib/components/organisms/FuroEditor/mention-suggestion.js

@@ -0,0 +1,320 @@
+import {
+  nextTick,
+  ref,
+} from 'vue'
+
+import {
+  computePosition,
+  flip,
+  shift,
+} from '@floating-ui/dom'
+
+import {
+  posToDOMRect,
+  VueRenderer,
+  mergeAttributes,
+} from '@tiptap/vue-3'
+import {
+  Mention,
+} from '@tiptap/extension-mention'
+
+import FuroEditorMentionMenu from './FuroEditorMentionMenu.vue'
+
+/**
+ * Position the popup against the current selection using floating-ui.
+ *
+ * @param {{
+ *   editor: import('@tiptap/core').Editor
+ *   element: HTMLElement
+ * }} params - Parameters of this function.
+ * @returns {Promise<import('@floating-ui/dom').ComputePositionReturn>} - Computed position.
+ */
+function updatePosition ({
+  editor,
+  element,
+}) {
+  const virtualElement = {
+    getBoundingClientRect: () => posToDOMRect(
+      editor.view,
+      editor.state.selection.from,
+      editor.state.selection.to
+    ),
+  }
+
+  return computePosition(virtualElement, element, {
+    placement: 'bottom-start',
+    strategy: 'absolute',
+    middleware: [
+      shift(),
+      flip(),
+    ],
+  })
+}
+
+/**
+ * Apply computed coordinates to the popup element.
+ *
+ * @param {{
+ *   element: HTMLElement
+ *   position: import('@floating-ui/dom').ComputePositionReturn
+ * }} params - Parameters of this function.
+ * @returns {void}
+ */
+function applyPosition ({
+  element,
+  position,
+}) {
+  const {
+    style,
+  } = element
+
+  style.width = 'max-content'
+  style.position = position.strategy
+  style.left = `${position.x}px`
+  style.top = `${position.y}px`
+}
+
+/**
+ * Build the Tiptap suggestion `render` factory backed by FuroEditorMentionMenu.
+ *
+ * @returns {import('@tiptap/suggestion').SuggestionOptions['render']} - Render factory.
+ */
+function buildMentionRender () {
+  /** @type {import('vue').Ref<import('@tiptap/vue-3').VueRenderer | null>} */
+  const rendererRef = ref(null)
+
+  // Releasing the ref matters as much as destroying the renderer: while it holds a
+  // destroyed popup, onKeyDown keeps reporting keys as handled by an invisible menu.
+  const closePopup = () => {
+    if (!rendererRef.value) {
+      return
+    }
+
+    rendererRef.value.destroy()
+    rendererRef.value.element?.remove()
+    rendererRef.value = null
+  }
+
+  return () => ({
+    onStart: async suggestionProps => {
+      rendererRef.value = new VueRenderer(FuroEditorMentionMenu, {
+        props: {
+          items: suggestionProps.items,
+          command: suggestionProps.command,
+        },
+        editor: suggestionProps.editor,
+      })
+
+      const { element } = rendererRef.value
+
+      if (
+        !suggestionProps.clientRect
+        || !(element instanceof HTMLElement)
+      ) {
+        return
+      }
+
+      element.style.position = 'absolute'
+      document.body.appendChild(element)
+
+      const position = await updatePosition({
+        editor: suggestionProps.editor,
+        element,
+      })
+
+      nextTick(() => {
+        if (!(rendererRef.value?.element instanceof HTMLElement)) {
+          return
+        }
+
+        applyPosition({
+          element: rendererRef.value.element,
+          position,
+        })
+      })
+    },
+
+    onUpdate: async suggestionProps => {
+      if (!rendererRef.value) {
+        return
+      }
+
+      rendererRef.value.updateProps({
+        items: suggestionProps.items,
+        command: suggestionProps.command,
+      })
+
+      const { element } = rendererRef.value
+
+      if (
+        !suggestionProps.clientRect
+        || !(element instanceof HTMLElement)
+      ) {
+        return
+      }
+
+      const position = await updatePosition({
+        editor: suggestionProps.editor,
+        element,
+      })
+
+      nextTick(() => {
+        if (!(rendererRef.value?.element instanceof HTMLElement)) {
+          return
+        }
+
+        applyPosition({
+          element: rendererRef.value.element,
+          position,
+        })
+      })
+    },
+
+    onKeyDown: suggestionProps => {
+      if (!rendererRef.value) {
+        return false
+      }
+
+      if (suggestionProps.event?.key === 'Escape') {
+        closePopup()
+
+        return true
+      }
+
+      const handled = rendererRef.value.ref?.onKeyDown?.({
+        targetEvent: suggestionProps.event,
+      })
+
+      return handled
+        ?? false
+    },
+
+    onExit: closePopup,
+  })
+}
+
+/**
+ * Mention node that renders `@label` and carries an `id` attribute.
+ */
+const FuroMention = Mention.extend({
+  addAttributes () {
+    return {
+      ...this.parent?.(),
+      id: {
+        default: null,
+        parseHTML: element => element.getAttribute('data-id'),
+        renderHTML: attributes => {
+          if (!attributes.id) {
+            return {}
+          }
+
+          return {
+            'data-id': attributes.id,
+          }
+        },
+      },
+      label: {
+        default: null,
+        parseHTML: element => element.getAttribute('data-label'),
+        renderHTML: attributes => {
+          if (!attributes.label) {
+            return {}
+          }
+
+          return {
+            'data-label': attributes.label,
+          }
+        },
+      },
+    }
+  },
+
+  renderHTML ({
+    HTMLAttributes,
+  }) {
+    const label = HTMLAttributes['data-label']
+      ?? ''
+
+    return [
+      'span',
+      mergeAttributes(
+        {
+          'data-type': 'mention',
+          class: 'furo-mention',
+        },
+        HTMLAttributes
+      ),
+      `@${label}`,
+    ]
+  },
+})
+
+/**
+ * Create the mention extension.
+ *
+ * Without `searchMentions` it registers the mention node only — enough to parse and
+ * render saved `@`-mention chips (e.g. read-only / display editors), with no `@` popup.
+ * With `searchMentions` it additionally wires the live suggestion popup for composing.
+ *
+ * @param {{
+ *   searchMentions?: ((params: { query: string }) => Promise<Array<{ id: string | number, label: string }>>) | null
+ *   onMentionAdd?: ((mention: { id: string | number, label: string }) => void) | null
+ * }} [params] - Parameters of this function.
+ * @returns {import('@tiptap/core').AnyExtension} - Configured mention extension.
+ */
+export function createMentionExtension ({
+  searchMentions = null,
+  onMentionAdd = null,
+} = {}) {
+  if (!searchMentions) {
+    return FuroMention.configure({
+      HTMLAttributes: {
+        class: 'furo-mention',
+      },
+    })
+  }
+
+  return FuroMention.configure({
+    HTMLAttributes: {
+      class: 'furo-mention',
+    },
+    suggestion: {
+      char: '@',
+      allowSpaces: true,
+      items: ({
+        query,
+      }) => searchMentions({
+        query,
+      }),
+      render: buildMentionRender(),
+      command: ({
+        editor,
+        range,
+        props,
+      }) => {
+        editor
+          .chain()
+          .focus()
+          .insertContentAt(range, [
+            {
+              type: 'mention',
+              attrs: {
+                id: /** @type {string | number} */ (props.id),
+                label: /** @type {string} */ (props.label),
+              },
+            },
+            {
+              type: 'text',
+              text: ' ',
+            },
+          ])
+          .run()
+
+        onMentionAdd?.({
+          id: /** @type {string | number} */ (props.id),
+          label: /** @type {string} */ (props.label),
+        })
+      },
+    },
+  })
+}

package/lib/components/organisms/FuroEditor/paste-link-segments.js

@@ -0,0 +1,124 @@
+/**
+ * Pure (Tiptap-free) parsing of pasted plain-text lines into text / link segments.
+ *
+ * Kept separate from PreserveNewlinesPasteExtension so this logic can be unit-tested
+ * without loading the ProseMirror / Tiptap runtime.
+ */
+
+/**
+ * Matches a Markdown link `[text](url)` or a bare `http(s)://` URL within a line.
+ */
+export const MARKDOWN_LINK_OR_BARE_URL_PATTERN = /\[([^\]]+)\]\(([^)]+)\)|https?:\/\/[^\s<]+[^\s<.,:;"')\]]/gu
+
+/**
+ * Create a link segment from a regex match.
+ *
+ * @param {RegExpMatchArray} match - Match from MARKDOWN_LINK_OR_BARE_URL_PATTERN.
+ * @returns {LinkTextSegment} - Link segment.
+ */
+function createLinkSegmentFromMatch (match) {
+  const isMarkdownLink = typeof match[1] === 'string'
+
+  if (isMarkdownLink) {
+    return {
+      type: 'link',
+      text: match[1],
+      href: match[2],
+    }
+  }
+
+  return {
+    type: 'link',
+    text: match[0],
+    href: match[0],
+  }
+}
+
+/**
+ * Extract plain text and link segments from a single line.
+ *
+ * @param {{
+ *   line: string
+ * }} params - Parameters of this function.
+ * @returns {Array<TextSegment>} - Ordered segments for the line.
+ */
+export function extractTextSegmentsFromLine ({
+  line,
+}) {
+  const matches = [
+    ...line.matchAll(MARKDOWN_LINK_OR_BARE_URL_PATTERN),
+  ]
+
+  if (matches.length === 0) {
+    return [
+      {
+        type: 'text',
+        text: line,
+      },
+    ]
+  }
+
+  const segmentsFromMatches = matches.flatMap((match, index) => {
+    const previousMatch = matches[index - 1]
+    const previousEndIndex = previousMatch
+      ? previousMatch.index + previousMatch[0].length
+      : 0
+
+    const leadingText = match.index > previousEndIndex
+      ? line.slice(previousEndIndex, match.index)
+      : ''
+
+    const leadingTextSegment = leadingText === ''
+      ? []
+      : [
+        /** @type {PlainTextSegment} */ ({
+          type: 'text',
+          text: leadingText,
+        }),
+      ]
+
+    return [
+      ...leadingTextSegment,
+      createLinkSegmentFromMatch(match),
+    ]
+  })
+
+  const lastMatch = matches[matches.length - 1]
+  const trailingIndex = lastMatch.index + lastMatch[0].length
+  const trailingText = trailingIndex < line.length
+    ? line.slice(trailingIndex)
+    : ''
+
+  const trailingSegment = trailingText === ''
+    ? []
+    : [
+      /** @type {PlainTextSegment} */ ({
+        type: 'text',
+        text: trailingText,
+      }),
+    ]
+
+  return [
+    ...segmentsFromMatches,
+    ...trailingSegment,
+  ]
+}
+
+/**
+ * @typedef {{
+ *   type: 'text'
+ *   text: string
+ * }} PlainTextSegment
+ */
+
+/**
+ * @typedef {{
+ *   type: 'link'
+ *   text: string
+ *   href: string
+ * }} LinkTextSegment
+ */
+
+/**
+ * @typedef {PlainTextSegment | LinkTextSegment} TextSegment
+ */