@openreachtech/furo-vue 1.3.1

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

@@ -0,0 +1,2048 @@
+import {
+  reactive,
+  nextTick,
+  onMounted,
+} from 'vue'
+
+import {
+  marked,
+} from 'marked'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import FuroEditorCommandContext from './FuroEditorCommandContext.js'
+
+const DEFAULT_LABELS = {
+  normalText: 'Normal text',
+  heading1: 'Heading 1',
+  heading2: 'Heading 2',
+  heading3: 'Heading 3',
+  heading4: 'Heading 4',
+  colorDefault: 'Default',
+  colorRed: 'Red',
+  colorBlue: 'Blue',
+  colorGreen: 'Green',
+  colorOrange: 'Orange',
+  colorPurple: 'Purple',
+  alignLeft: 'Align left',
+  alignCenter: 'Align center',
+  alignRight: 'Align right',
+  alignJustify: 'Justify',
+  heading: 'Text style',
+  textColor: 'Text color',
+  textAlign: 'Text alignment',
+  bold: 'Bold',
+  italic: 'Italic',
+  underline: 'Underline',
+  strike: 'Strikethrough',
+  bullets: 'Bullet list',
+  numbers: 'Numbered list',
+  blockquote: 'Quote',
+  link: 'Link',
+  mention: 'Mention',
+  image: 'Insert image',
+  overflow: 'More options',
+  linkDialogTitle: 'Add link',
+  linkUrlLabel: 'Link',
+  linkDisplayTextLabel: 'Display text (optional)',
+  linkSave: 'Save',
+  linkCancel: 'Cancel',
+}
+
+const OVERFLOW_TOOLBAR_NAME = 'overflow'
+
+const FEATURE_TOOLBAR_NAMES = [
+  'image',
+  'mention',
+]
+
+const COLOR_OPTION_PREFIX = 'color:'
+
+const COLOR_VALUES = {
+  red: '#ef4444',
+  blue: '#3b82f6',
+  green: '#10b981',
+  orange: '#f97316',
+  purple: '#8b5cf6',
+}
+
+const MARKDOWN_PATTERNS = [
+  /^#{1,6}\s/u,
+  /\*\*.*\*\*/u,
+  /\*.*\*/u,
+  /\[.*\]\(.*\)/u,
+  /^-\s/u,
+  /```.*```/su,
+]
+
+/**
+ * Context for the FuroEditor organism.
+ *
+ * Owns the editor lifecycle, the value/attachment surface, the formatting toolbar
+ * model, and the link dialog. Selection and command execution are delegated to a
+ * {@link FuroEditorCommandContext} sub-context. Paste behavior (markdown detection,
+ * font-style stripping, newline preservation) is wired onto the editor on mount.
+ *
+ * Domain concerns (mention search, attachment uploads) are exposed as adapter
+ * callbacks and slots — this component never touches GraphQL or domain schemas.
+ *
+ * @extends {BaseFuroContext<null, FuroEditorContextParams['props'], string>}
+ */
+export default class FuroEditorContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroEditorContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    reactiveHash,
+    editorRef,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.reactiveHash = reactiveHash
+    this.editorRef = editorRef
+    this.commandContext = FuroEditorCommandContext.create({
+      editorRef,
+    })
+
+    /** @type {{ from: number, to: number } | null} */
+    this.linkRange = null
+  }
+
+  /**
+   * Factory method to create a new instance of this class.
+   *
+   * @template {X extends typeof FuroEditorContext ? X : never} T, X
+   * @override
+   * @param {FuroEditorContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} - New instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    editorRef,
+    reactiveHash = this.buildReactiveHash(),
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        reactiveHash,
+        editorRef,
+      })
+    )
+  }
+
+  /** @override */
+  static get EMIT_EVENT_NAME () {
+    return {
+      UPDATE_VALUE: 'update:value',
+      CHANGE_VALUE: 'change-value',
+      COMMIT_VALUE: 'commit-value',
+      UPDATE_ATTACHED_FILES: 'update:attachedFiles',
+      ADD_MENTION: 'mention:add',
+      ADD_FILES: 'files:add',
+      IMAGE_ERROR: 'image:error',
+    }
+  }
+
+  /**
+   * Build reactive hash.
+   *
+   * @override
+   * @returns {FuroEditorContextParams['reactiveHash']}
+   */
+  static buildReactiveHash () {
+    return {
+      statusReactive: reactive({
+        isLinkDialogOpen: false,
+      }),
+      addLinkReactive: reactive({
+        url: '',
+        displayText: '',
+      }),
+    }
+  }
+
+  /**
+   * get: default toolbar labels.
+   *
+   * @returns {typeof DEFAULT_LABELS} - Default labels.
+   */
+  static get DEFAULT_LABELS () {
+    return DEFAULT_LABELS
+  }
+
+  /**
+   * Build the option object for the `useEditor()` composable.
+   *
+   * Keeps all editor-assembly logic out of the component's `setup()`: the SFC only
+   * passes the result to `useEditor()` and hands the ref to {@link create}.
+   *
+   * The Tiptap builders are injected (not imported) so this context module — and the
+   * unit tests that load it — stay free of the editor runtime.
+   *
+   * @param {{
+   *   props: { parcel?: FuroEditorParcel | null }
+   *   componentContext: import('vue').SetupContext<*>
+   *   buildExtensions: typeof import('./build-editor-extensions.js').buildEditorExtensions
+   *   createMention: typeof import('./mention-suggestion.js').createMentionExtension
+   * }} params - Parameters of this method.
+   * @returns {Partial<import('@tiptap/core').EditorOptions>} - useEditor() options.
+   */
+  static buildEditorOptions ({
+    props,
+    componentContext,
+    buildExtensions,
+    createMention,
+  }) {
+    const parcel = props.parcel
+      ?? {}
+
+    const mentionExtension = this.buildMentionExtension({
+      parcel,
+      componentContext,
+      createMention,
+    })
+
+    const placeholder = parcel.placeholder
+      ?? ''
+    const content = parcel.value
+      ?? ''
+
+    const extensions = buildExtensions({
+      placeholder,
+      enableImage: Boolean(parcel.image?.uploadImage),
+      mentionExtension,
+    })
+
+    const attributes = parcel.contentAttributes
+      ?? {}
+
+    return {
+      editable: !parcel.readOnly && parcel.appearance !== 'plain',
+      content,
+      autofocus: parcel.autofocus ?? false,
+      extensions,
+      editorProps: {
+        attributes,
+      },
+    }
+  }
+
+  /**
+   * Build the mention extension via the injected factory.
+   *
+   * Always registers the mention node so saved chips render in any editor (including
+   * read-only / display). The live `@` popup is wired only when a search adapter is
+   * supplied.
+   *
+   * @param {{
+   *   parcel: FuroEditorParcel
+   *   componentContext: import('vue').SetupContext<*>
+   *   createMention: typeof import('./mention-suggestion.js').createMentionExtension
+   * }} params - Parameters of this method.
+   * @returns {import('@tiptap/core').AnyExtension} - Mention extension.
+   */
+  static buildMentionExtension ({
+    parcel,
+    componentContext,
+    createMention,
+  }) {
+    const searchMentions = parcel.mention?.searchMentions
+
+    if (!searchMentions) {
+      return createMention()
+    }
+
+    return createMention({
+      searchMentions,
+      onMentionAdd: mention => componentContext.emit(
+        this.EMIT_EVENT_NAME.ADD_MENTION,
+        mention
+      ),
+    })
+  }
+
+  /**
+   * get: live editor instance, or null before it mounts.
+   *
+   * @returns {import('@tiptap/vue-3').Editor | null} - Editor instance.
+   */
+  get editor () {
+    return this.editorRef.value
+      ?? null
+  }
+
+  /**
+   * get: the command sub-context.
+   *
+   * @returns {FuroEditorCommandContext} - Command facade.
+   */
+  get command () {
+    return this.commandContext
+  }
+
+  /**
+   * get: status reactive (link dialog open state).
+   *
+   * @returns {{ isLinkDialogOpen: boolean }} - Status reactive.
+   */
+  get statusReactive () {
+    return this.reactiveHash.statusReactive
+  }
+
+  /**
+   * get: add-link reactive (url + display text).
+   *
+   * @returns {{ url: string, displayText: string }} - Link reactive.
+   */
+  get addLinkReactive () {
+    return this.reactiveHash.addLinkReactive
+  }
+
+  /**
+   * get: current HTML value from parcel.
+   *
+   * @returns {string} - HTML content.
+   */
+  get value () {
+    return this.parcel?.value
+      ?? ''
+  }
+
+  /**
+   * get: placeholder text.
+   *
+   * @returns {string} - Placeholder.
+   */
+  get placeholder () {
+    return this.parcel?.placeholder
+      ?? ''
+  }
+
+  /**
+   * get: attached files passed in by the consumer.
+   *
+   * @returns {Array<*>} - Attached files.
+   */
+  get attachedFiles () {
+    return this.parcel?.attachedFiles
+      ?? []
+  }
+
+  /**
+   * Whether the editor is read-only.
+   *
+   * @returns {boolean} - true when read-only.
+   */
+  isReadOnly () {
+    return Boolean(this.parcel?.readOnly)
+  }
+
+  /**
+   * Whether the editor renders as plain text (no chrome: toolbar, border, padding).
+   *
+   * @returns {boolean} - true in plain appearance.
+   */
+  isPlain () {
+    return this.parcel?.appearance === 'plain'
+  }
+
+  /**
+   * Whether the editor is display-only (read-only or plain) — never editable.
+   *
+   * @returns {boolean} - true when display-only.
+   */
+  isDisplayOnly () {
+    return this.isReadOnly()
+      || this.isPlain()
+  }
+
+  /**
+   * Whether the editor instance is currently editable.
+   *
+   * @returns {boolean} - true when editable.
+   */
+  isEditorEditable () {
+    return this.editor?.isEditable
+      ?? false
+  }
+
+  /**
+   * Whether the mention feature is enabled (a search adapter was supplied).
+   *
+   * @returns {boolean} - true when mentions are available.
+   */
+  hasMentionFeature () {
+    return Boolean(this.parcel?.mention?.searchMentions)
+  }
+
+  /**
+   * Whether inline images are enabled (an upload adapter was supplied).
+   *
+   * @returns {boolean} - true when inline images are available.
+   */
+  hasImageFeature () {
+    return Boolean(this.parcel?.image?.uploadImage)
+  }
+
+  /**
+   * Whether the link dialog is open.
+   *
+   * @returns {boolean} - true when open.
+   */
+  isLinkDialogOpen () {
+    return this.statusReactive.isLinkDialogOpen
+  }
+
+  /**
+   * Merge consumer label overrides over the defaults.
+   *
+   * @returns {typeof DEFAULT_LABELS} - Effective labels.
+   */
+  extractLabels () {
+    return {
+      ...DEFAULT_LABELS,
+      ...this.parcel?.labels,
+    }
+  }
+
+  /**
+   * Setup component context: bind editor events, paste handlers, and value/readonly sync.
+   *
+   * @template {X extends FuroEditorContext ? X : never} T, X
+   * @override
+   * @returns {T} - For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    onMounted(() => {
+      this.bindEditorEvents()
+      this.bindPasteHandlers()
+    })
+
+    this.watch(
+      () => this.value,
+      () => this.syncValueIntoEditor(),
+      {
+        immediate: true,
+      }
+    )
+
+    this.watch(
+      () => this.isDisplayOnly(),
+      () => this.syncEditableState(),
+      {
+        immediate: true,
+      }
+    )
+
+    // useEditor() from @tiptap/vue-3 destroys the editor on unmount automatically.
+
+    return this
+  }
+
+  /**
+   * Bind editor update/blur events to emits.
+   *
+   * @returns {void}
+   */
+  bindEditorEvents () {
+    if (!this.editor) {
+      return
+    }
+
+    this.editor.on('update', ({
+      editor,
+    }) => {
+      const html = editor.getHTML()
+
+      this.emit(this.EMIT_EVENT_NAME.UPDATE_VALUE, html)
+      this.emit(this.EMIT_EVENT_NAME.CHANGE_VALUE, {
+        value: html,
+      })
+    })
+
+    this.editor.on('blur', ({
+      editor,
+    }) => {
+      this.emit(this.EMIT_EVENT_NAME.COMMIT_VALUE, {
+        value: editor.getHTML(),
+      })
+    })
+  }
+
+  /**
+   * Install paste transforms (markdown detection, font-style stripping, normalization).
+   *
+   * @returns {void}
+   */
+  bindPasteHandlers () {
+    if (!this.editor) {
+      return
+    }
+
+    this.editor.setOptions({
+      editorProps: {
+        ...this.editor.options.editorProps,
+        transformPastedText: text => this.normalizePastedText({
+          text,
+        }),
+        transformPastedHTML: html => this.stripPastedHtmlFontStyles({
+          html,
+        }),
+        handlePaste: (_, clipboardEvent) => this.handleEditorPaste({
+          clipboardEvent,
+        }),
+        handleDrop: (view, dragEvent) => this.handleEditorDrop({
+          view,
+          dragEvent,
+        }),
+      },
+    })
+  }
+
+  /**
+   * Handle a paste: inline images first, then markdown plain text.
+   *
+   * @param {{
+   *   clipboardEvent: ClipboardEvent
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when a handler consumed the paste.
+   */
+  handleEditorPaste ({
+    clipboardEvent,
+  }) {
+    this.emitPastedFiles({ clipboardEvent })
+
+    if (this.handleImagePaste({ clipboardEvent })) {
+      return true
+    }
+
+    return this.handleMarkdownPaste({ clipboardEvent })
+  }
+
+  /**
+   * Emit the pasted files the editor does not insert itself.
+   *
+   * @param {{
+   *   clipboardEvent: ClipboardEvent
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  emitPastedFiles ({
+    clipboardEvent,
+  }) {
+    const clipboard = clipboardEvent?.['clipboardData']
+    const files = this.extractUnconsumedFiles({
+      fileSource: clipboard?.files ?? null,
+    })
+
+    this.emitAddedFiles({ files })
+  }
+
+  /**
+   * Emit files handed to the consumer, unless there are none.
+   *
+   * @param {{
+   *   files: Array<File>
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  emitAddedFiles ({
+    files,
+  }) {
+    if (files.length === 0) {
+      return
+    }
+
+    this.emit(this.EMIT_EVENT_NAME.ADD_FILES, {
+      files,
+    })
+  }
+
+  /**
+   * Upload and insert any image files present on the clipboard.
+   *
+   * @param {{
+   *   clipboardEvent: ClipboardEvent
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when image files were consumed.
+   */
+  handleImagePaste ({
+    clipboardEvent,
+  }) {
+    if (!this.hasImageFeature()) {
+      return false
+    }
+
+    const clipboard = clipboardEvent?.['clipboardData']
+    const imageFiles = this.extractImageFiles({
+      fileSource: clipboard?.files ?? null,
+    })
+
+    if (imageFiles.length === 0) {
+      return false
+    }
+
+    this.uploadAndInsertImages({
+      files: imageFiles,
+      position: null,
+    })
+
+    return true
+  }
+
+  /**
+   * Insert dropped images at the drop position, and hand the other files to the consumer.
+   *
+   * @param {{
+   *   view: import('@tiptap/pm/view').EditorView
+   *   dragEvent: DragEvent
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when the dropped files were taken.
+   */
+  handleEditorDrop ({
+    view,
+    dragEvent,
+  }) {
+    const fileSource = dragEvent?.dataTransfer?.files
+      ?? null
+    const imageFiles = this.extractInsertableImageFiles({ fileSource })
+    const droppedFiles = this.extractUnconsumedFiles({ fileSource })
+
+    if (imageFiles.length === 0 && droppedFiles.length === 0) {
+      return false
+    }
+
+    dragEvent.preventDefault()
+
+    this.emitAddedFiles({ files: droppedFiles })
+
+    const position = this.extractDropPosition({
+      view,
+      dragEvent,
+    })
+
+    this.uploadAndInsertImages({
+      files: imageFiles,
+      position,
+    })
+
+    return true
+  }
+
+  /**
+   * Extract the document position a drag event points at.
+   *
+   * @param {{
+   *   view: import('@tiptap/pm/view').EditorView
+   *   dragEvent: DragEvent
+   * }} params - Parameters of this method.
+   * @returns {number | null} - Document position.
+   */
+  extractDropPosition ({
+    view,
+    dragEvent,
+  }) {
+    const coordinates = view.posAtCoords({
+      left: dragEvent.clientX,
+      top: dragEvent.clientY,
+    })
+
+    return coordinates?.pos
+      ?? null
+  }
+
+  /**
+   * Push the parcel value into the editor when it diverges from the current HTML.
+   *
+   * @returns {void}
+   */
+  syncValueIntoEditor () {
+    if (!this.editor) {
+      return
+    }
+
+    const currentHtml = this.editor.getHTML()
+
+    if (this.value === currentHtml) {
+      return
+    }
+
+    this.editor
+      .commands
+      .setContent(this.value)
+  }
+
+  /**
+   * Reflect the read-only flag onto the editor.
+   *
+   * @returns {void}
+   */
+  syncEditableState () {
+    if (!this.editor) {
+      return
+    }
+
+    this.editor.setEditable(!this.isDisplayOnly())
+  }
+
+  /**
+   * Convert pasted markdown plain text into HTML and insert it.
+   *
+   * @param {{
+   *   clipboardEvent: ClipboardEvent
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when this handler consumed the paste.
+   */
+  handleMarkdownPaste ({
+    clipboardEvent,
+  }) {
+    // Bracket access avoids the Data-suffix identifier lint on native ClipboardEvent APIs.
+    const clipboard = clipboardEvent?.['clipboardData']
+    const rawText = clipboard?.['getData']?.('text/plain')
+
+    if (!rawText) {
+      return false
+    }
+
+    if (!this.isMarkdown({ text: rawText })) {
+      return false
+    }
+
+    this.insertMarkdownAsHtml({
+      rawText,
+    })
+
+    return true
+  }
+
+  /**
+   * Render markdown to HTML asynchronously and insert it at the cursor.
+   *
+   * @param {{
+   *   rawText: string
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  insertMarkdownAsHtml ({
+    rawText,
+  }) {
+    Promise.resolve(marked(rawText))
+      .then(html => {
+        this.editor
+          ?.commands
+          .insertContent(html)
+      })
+  }
+
+  /**
+   * Normalize pasted plain-text line breaks.
+   *
+   * @param {{
+   *   text: string
+   * }} params - Parameters of this method.
+   * @returns {string} - Normalized text.
+   */
+  normalizePastedText ({
+    text,
+  }) {
+    return text
+      .replace(/\r\n/gu, '\n')
+      .replace(/\r/gu, '\n')
+      .replace(/\n{3,}/gu, '\n\n')
+      .trim()
+  }
+
+  /**
+   * Strip font-family / font-size declarations from pasted HTML so external
+   * typography does not override the editor's.
+   *
+   * @param {{
+   *   html: string
+   * }} params - Parameters of this method.
+   * @returns {string} - Sanitized HTML.
+   */
+  stripPastedHtmlFontStyles ({
+    html,
+  }) {
+    return html
+      .replace(/font-family:\s*[^;"]+;?/giu, '')
+      .replace(/font-size:\s*[^;"]+;?/giu, '')
+      .replace(/\s*style="\s*"/giu, '')
+  }
+
+  /**
+   * Whether pasted text looks like markdown.
+   *
+   * @param {{
+   *   text: string
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when markdown patterns match.
+   */
+  isMarkdown ({
+    text,
+  }) {
+    return MARKDOWN_PATTERNS.some(pattern => pattern.test(text))
+  }
+
+  /**
+   * Build the inline-mark controls (bold / italic / underline / strikethrough).
+   *
+   * @returns {Array<FuroEditorControl>} - Mark controls.
+   */
+  generateMarkControls () {
+    const labels = this.extractLabels()
+
+    return /** @type {Array<FuroEditorControl>} */ ([
+      {
+        name: 'bold',
+        kind: 'toggle',
+        command: 'toggleBold',
+        iconName: 'ph:text-b',
+        activeIconName: 'ph:text-b-bold',
+        tooltip: labels.bold,
+      },
+      {
+        name: 'italic',
+        kind: 'toggle',
+        command: 'toggleItalic',
+        iconName: 'ph:text-italic',
+        activeIconName: 'ph:text-italic-bold',
+        tooltip: labels.italic,
+      },
+      {
+        name: 'underline',
+        kind: 'toggle',
+        command: 'toggleUnderline',
+        iconName: 'ph:text-underline',
+        activeIconName: 'ph:text-underline-bold',
+        tooltip: labels.underline,
+      },
+      {
+        name: 'strike',
+        kind: 'toggle',
+        command: 'toggleStrike',
+        iconName: 'ph:text-strikethrough',
+        activeIconName: 'ph:text-strikethrough-bold',
+        tooltip: labels.strike,
+      },
+    ])
+  }
+
+  /**
+   * Build the block controls (bullets / numbers / blockquote).
+   *
+   * @returns {Array<FuroEditorControl>} - Block controls.
+   */
+  generateBlockControls () {
+    const labels = this.extractLabels()
+
+    return /** @type {Array<FuroEditorControl>} */ ([
+      {
+        name: 'bulletList',
+        kind: 'toggle',
+        command: 'toggleBulletList',
+        iconName: 'ph:list-bullets',
+        activeIconName: 'ph:list-bullets-bold',
+        tooltip: labels.bullets,
+      },
+      {
+        name: 'orderedList',
+        kind: 'toggle',
+        command: 'toggleOrderedList',
+        iconName: 'ph:list-numbers',
+        activeIconName: 'ph:list-numbers-bold',
+        tooltip: labels.numbers,
+      },
+      {
+        name: 'blockquote',
+        kind: 'toggle',
+        command: 'toggleBlockquote',
+        iconName: 'ph:quotes',
+        activeIconName: 'ph:quotes-bold',
+        tooltip: labels.blockquote,
+      },
+    ])
+  }
+
+  /**
+   * Build the action controls (link, plus image / mention when enabled).
+   *
+   * @returns {Array<FuroEditorControl>} - Action controls.
+   */
+  generateActionControls () {
+    const labels = this.extractLabels()
+
+    const linkControls = [
+      {
+        name: 'link',
+        kind: 'link',
+        command: '',
+        iconName: 'ph:link',
+        activeIconName: 'ph:link-bold',
+        tooltip: labels.link,
+      },
+    ]
+
+    const imageControls = this.hasImageFeature()
+      ? [
+        {
+          name: 'image',
+          kind: 'image',
+          command: '',
+          iconName: 'ph:image',
+          activeIconName: 'ph:image-fill',
+          tooltip: labels.image,
+        },
+      ]
+      : []
+
+    const mentionControls = this.hasMentionFeature()
+      ? [
+        {
+          name: 'mention',
+          kind: 'mention',
+          command: '',
+          iconName: 'ph:at',
+          activeIconName: 'ph:at-bold',
+          tooltip: labels.mention,
+        },
+      ]
+      : []
+
+    return /** @type {Array<FuroEditorControl>} */ ([
+      ...linkControls,
+      ...imageControls,
+      ...mentionControls,
+    ])
+  }
+
+  /**
+   * Flatten all toolbar controls into a single list.
+   *
+   * @returns {Array<FuroEditorControl>} - Toolbar controls.
+   */
+  generateFormattingControls () {
+    return [
+      ...this.generateMarkControls(),
+      ...this.generateBlockControls(),
+      ...this.generateActionControls(),
+    ]
+  }
+
+  /**
+   * Build a lookup of control descriptors keyed by control name.
+   *
+   * @returns {Record<string, FuroEditorControl>} - Controls keyed by name.
+   */
+  generateControlHash () {
+    const entries = this.generateFormattingControls()
+      .map(control => /** @type {[string, FuroEditorControl]} */ ([
+        control.name,
+        control,
+      ]))
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Build a lookup of dropdown descriptors keyed by name.
+   *
+   * @returns {Record<string, FuroEditorToolbarEntry>} - Dropdown entries keyed by name.
+   */
+  generateDropdownDescriptorHash () {
+    const labels = this.extractLabels()
+
+    return /** @type {Record<string, FuroEditorToolbarEntry>} */ ({
+      heading: {
+        type: 'dropdown',
+        key: 'heading',
+        label: labels.heading,
+        iconName: 'ph:text-aa',
+        dropdownKind: 'heading',
+        options: this.generateHeadingOptions(),
+      },
+      color: {
+        type: 'dropdown',
+        key: 'color',
+        label: labels.textColor,
+        iconName: 'ph:text-t',
+        dropdownKind: 'textStyle',
+        hasSwatch: true,
+        options: this.generateColorOptions(),
+      },
+      align: {
+        type: 'dropdown',
+        key: 'align',
+        label: labels.textAlign,
+        iconName: 'ph:text-align-left',
+        dropdownKind: 'textAlign',
+        options: this.generateAlignOptions(),
+      },
+    })
+  }
+
+  /**
+   * The default toolbar layout: an array of groups, separators sit between groups.
+   *
+   * @returns {Array<Array<string>>} - Groups of item names.
+   */
+  generateDefaultToolbarGroups () {
+    const imageActions = this.hasImageFeature()
+      ? [
+        'image',
+      ]
+      : []
+
+    const mentionActions = this.hasMentionFeature()
+      ? [
+        'mention',
+      ]
+      : []
+
+    const actionGroup = [
+      'link',
+      ...imageActions,
+      ...mentionActions,
+    ]
+
+    return [
+      [
+        'heading',
+        'color',
+        'align',
+      ],
+      [
+        'bold',
+        'italic',
+        'underline',
+        'strike',
+      ],
+      [
+        'bulletList',
+        'orderedList',
+        'blockquote',
+      ],
+      actionGroup,
+    ]
+  }
+
+  /**
+   * The effective toolbar groups (consumer override or the default).
+   *
+   * @returns {Array<Array<string>>} - Groups of item names.
+   */
+  generateToolbarGroups () {
+    return this.parcel?.toolbar
+      ?? this.generateDefaultToolbarGroups()
+  }
+
+  /**
+   * Resolve a name to a dropdown or control descriptor, leaving `overflow` unhandled.
+   *
+   * @param {{
+   *   name: string
+   *   dropdownHash: Record<string, FuroEditorToolbarEntry>
+   *   controlHash: Record<string, FuroEditorControl>
+   * }} params - Parameters of this method.
+   * @returns {FuroEditorToolbarEntry | null} - Render descriptor.
+   */
+  resolveDropdownOrControlEntry ({
+    name,
+    dropdownHash,
+    controlHash,
+  }) {
+    const dropdownEntry = dropdownHash[name]
+
+    if (dropdownEntry) {
+      return dropdownEntry
+    }
+
+    const control = controlHash[name]
+
+    if (!control) {
+      return null
+    }
+
+    return /** @type {FuroEditorToolbarEntry} */ ({
+      type: 'control',
+      key: name,
+      control,
+    })
+  }
+
+  /**
+   * Resolve a toolbar item name to a render descriptor, or null when unavailable.
+   *
+   * @param {{
+   *   name: string
+   *   dropdownHash: Record<string, FuroEditorToolbarEntry>
+   *   controlHash: Record<string, FuroEditorControl>
+   * }} params - Parameters of this method.
+   * @returns {FuroEditorToolbarEntry | null} - Render descriptor.
+   */
+  resolveToolbarEntry ({
+    name,
+    dropdownHash,
+    controlHash,
+  }) {
+    const entry = this.resolveDropdownOrControlEntry({
+      name,
+      dropdownHash,
+      controlHash,
+    })
+
+    if (entry) {
+      return entry
+    }
+
+    if (name === OVERFLOW_TOOLBAR_NAME) {
+      return this.resolveOverflowEntry()
+    }
+
+    this.throwOnUnknownToolbarName({
+      name,
+    })
+
+    return null
+  }
+
+  /**
+   * Resolve the overflow menu, or null when no action is left to put in it.
+   *
+   * @returns {FuroEditorToolbarEntry | null} - Render descriptor.
+   */
+  resolveOverflowEntry () {
+    if (this.generateOverflowEntryNames().length === 0) {
+      return null
+    }
+
+    return /** @type {FuroEditorToolbarEntry} */ ({
+      type: 'overflow',
+      key: OVERFLOW_TOOLBAR_NAME,
+    })
+  }
+
+  /**
+   * List the toolbar names this editor accepts, feature-gated names included.
+   *
+   * @returns {Array<string>} - Accepted names.
+   */
+  generateKnownToolbarNames () {
+    const controlNames = this.generateFormattingControls()
+      .map(control => control.name)
+
+    const gatedNames = FEATURE_TOOLBAR_NAMES
+      .filter(name => !controlNames.includes(name))
+
+    return [
+      ...Object.keys(this.generateDropdownDescriptorHash()),
+      ...controlNames,
+      ...gatedNames,
+      OVERFLOW_TOOLBAR_NAME,
+    ]
+  }
+
+  /**
+   * Whether a toolbar name lies outside the vocabulary. A gated feature's own name
+   * stays known, so switching the feature off never reads as a typo.
+   *
+   * @param {{
+   *   name: string
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when nothing accepts the name.
+   */
+  isUnknownToolbarName ({
+    name,
+  }) {
+    return !this.generateKnownToolbarNames()
+      .includes(name)
+  }
+
+  /**
+   * Fail on a `parcel.toolbar` name nothing can resolve, which would otherwise ship
+   * as a quietly shorter toolbar. Production keeps dropping the name instead.
+   *
+   * @param {{
+   *   name: string
+   * }} params - Parameters of this method.
+   * @returns {void}
+   * @throws {Error} When the name lies outside the toolbar vocabulary.
+   */
+  throwOnUnknownToolbarName ({
+    name,
+  }) {
+    if (process.env.NODE_ENV === 'production') {
+      return
+    }
+
+    if (!this.isUnknownToolbarName({
+      name,
+    })) {
+      return
+    }
+
+    const acceptedNames = this.generateKnownToolbarNames()
+      .join(', ')
+
+    throw new Error(`[FuroEditor] \`parcel.toolbar\` names "${name}", which is not a toolbar action. Accepted names: ${acceptedNames}.`)
+  }
+
+  /**
+   * List the default action names no toolbar group named.
+   *
+   * @returns {Array<string>} - Hidden action names.
+   */
+  generateOverflowEntryNames () {
+    const namedNames = this.generateToolbarGroups()
+      .flat()
+
+    return this.generateDefaultToolbarGroups()
+      .flat()
+      .filter(name => !namedNames.includes(name))
+  }
+
+  /**
+   * Build the render descriptors the overflow menu holds.
+   *
+   * @returns {Array<FuroEditorToolbarEntry>} - Render descriptors.
+   */
+  generateOverflowEntries () {
+    const dropdownHash = this.generateDropdownDescriptorHash()
+    const controlHash = this.generateControlHash()
+
+    return this.generateOverflowEntryNames()
+      .map(name => this.resolveDropdownOrControlEntry({
+        name,
+        dropdownHash,
+        controlHash,
+      }))
+      .filter(entry => entry !== null)
+  }
+
+  /**
+   * Build the overflow menu options, one per hidden action.
+   *
+   * @returns {Array<import('../../molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption>} - Options.
+   */
+  generateOverflowOptions () {
+    return this.generateOverflowEntries()
+      .map(entry => this.buildOverflowOption({
+        entry,
+      }))
+  }
+
+  /**
+   * Build one overflow menu option, nesting a hidden dropdown as a submenu.
+   *
+   * @param {{
+   *   entry: FuroEditorToolbarEntry
+   * }} params - Parameters of this method.
+   * @returns {import('../../molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption} - Option.
+   */
+  buildOverflowOption ({
+    entry,
+  }) {
+    if (entry.type === 'dropdown') {
+      return {
+        label: entry.label,
+        value: entry.key,
+        type: 'submenu',
+        options: entry.options,
+      }
+    }
+
+    if (entry.control.kind !== 'toggle') {
+      return {
+        label: entry.control.tooltip,
+        value: entry.control.name,
+      }
+    }
+
+    return {
+      label: entry.control.tooltip,
+      value: entry.control.name,
+      type: 'checkbox',
+      checked: this.isControlActive({
+        control: entry.control,
+      }),
+    }
+  }
+
+  /**
+   * Extract the icon an overflow row draws, mirroring the on-bar active swap.
+   *
+   * @param {{
+   *   option: import('../../molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption
+   * }} params - Parameters of this method.
+   * @returns {string | null} - Icon name, or null when the row draws none.
+   */
+  extractOverflowIconName ({
+    option,
+  }) {
+    const name = option.value
+      ?? ''
+    const dropdownEntry = this.generateDropdownDescriptorHash()[name]
+
+    if (dropdownEntry) {
+      return dropdownEntry.iconName
+    }
+
+    const control = this.generateControlHash()[name]
+
+    if (!control) {
+      return null
+    }
+
+    return this.isControlActive({
+      control,
+    })
+      ? control.activeIconName
+      : control.iconName
+  }
+
+  /**
+   * Whether an overflow row draws a colour swatch beside its label.
+   *
+   * @param {{
+   *   option: import('../../molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when the row is a colour option.
+   */
+  hasOverflowSwatch ({
+    option,
+  }) {
+    return (option.value ?? '')
+      .startsWith(COLOR_OPTION_PREFIX)
+  }
+
+  /**
+   * React to an overflow menu selection, routing to the handler the value belongs to.
+   *
+   * @param {{
+   *   value?: string
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  onOverflowSelect ({
+    value = '',
+  }) {
+    const control = this.generateControlHash()[value]
+
+    if (!control) {
+      this.onDropdownSelect({
+        value,
+      })
+
+      return
+    }
+
+    this.onControlClick({
+      control,
+    })
+  }
+
+  /**
+   * Build the flat toolbar layout (dropdowns, controls, separators between groups).
+   *
+   * @returns {Array<FuroEditorToolbarEntry>} - Ordered render descriptors.
+   */
+  generateToolbarLayout () {
+    const dropdownHash = this.generateDropdownDescriptorHash()
+    const controlHash = this.generateControlHash()
+
+    const resolvedGroups = this.generateToolbarGroups()
+      .map(group =>
+        group
+          .map(name => this.resolveToolbarEntry({
+            name,
+            dropdownHash,
+            controlHash,
+          }))
+          .filter(entry => entry !== null)
+      )
+      .filter(group => group.length > 0)
+
+    return resolvedGroups.flatMap((group, index) => {
+      const separator = index === 0
+        ? []
+        : [
+          /** @type {FuroEditorToolbarEntry} */ ({
+            type: 'separator',
+            key: `separator-${index}`,
+          }),
+        ]
+
+      return [
+        ...separator,
+        ...group,
+      ]
+    })
+  }
+
+  /**
+   * Build the heading dropdown options.
+   *
+   * @returns {Array<import('../../molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption>} - Options.
+   */
+  generateHeadingOptions () {
+    const labels = this.extractLabels()
+
+    return [
+      {
+        label: labels.normalText,
+        value: 'paragraph',
+      },
+      {
+        label: labels.heading1,
+        value: 'heading:1',
+      },
+      {
+        label: labels.heading2,
+        value: 'heading:2',
+      },
+      {
+        label: labels.heading3,
+        value: 'heading:3',
+      },
+      {
+        label: labels.heading4,
+        value: 'heading:4',
+      },
+    ]
+  }
+
+  /**
+   * Build the text-color dropdown options.
+   *
+   * @returns {Array<import('../../molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption>} - Options.
+   */
+  generateColorOptions () {
+    const labels = this.extractLabels()
+
+    return [
+      {
+        label: labels.colorDefault,
+        value: 'color:',
+      },
+      {
+        label: labels.colorRed,
+        value: `color:${COLOR_VALUES.red}`,
+      },
+      {
+        label: labels.colorBlue,
+        value: `color:${COLOR_VALUES.blue}`,
+      },
+      {
+        label: labels.colorGreen,
+        value: `color:${COLOR_VALUES.green}`,
+      },
+      {
+        label: labels.colorOrange,
+        value: `color:${COLOR_VALUES.orange}`,
+      },
+      {
+        label: labels.colorPurple,
+        value: `color:${COLOR_VALUES.purple}`,
+      },
+    ]
+  }
+
+  /**
+   * Resolve the swatch color for a color dropdown option value.
+   *
+   * @param {{
+   *   value?: string
+   * }} params - Parameters of this method.
+   * @returns {string} - CSS color for the swatch dot.
+   */
+  extractColorSwatch ({
+    value,
+  }) {
+    const rawValue = value
+      ?? ''
+
+    const swatchColor = rawValue.replace(/^color:/u, '')
+
+    return swatchColor === ''
+      ? 'var(--color-foreground)'
+      : swatchColor
+  }
+
+  /**
+   * Build the text-align dropdown options.
+   *
+   * @returns {Array<import('../../molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption>} - Options.
+   */
+  generateAlignOptions () {
+    const labels = this.extractLabels()
+
+    return [
+      {
+        label: labels.alignLeft,
+        value: 'align:left',
+      },
+      {
+        label: labels.alignCenter,
+        value: 'align:center',
+      },
+      {
+        label: labels.alignRight,
+        value: 'align:right',
+      },
+      {
+        label: labels.alignJustify,
+        value: 'align:justify',
+      },
+    ]
+  }
+
+  /**
+   * React to a formatting control click.
+   *
+   * @param {{
+   *   control: FuroEditorControl
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  onControlClick ({
+    control,
+  }) {
+    const override = this.parcel?.actionOverrides?.[control.name]
+
+    if (override) {
+      override({
+        control,
+        command: this.commandContext,
+        editor: this.editor,
+      })
+
+      return
+    }
+
+    const actionHash = {
+      toggle: () => this.commandContext.toggleNodeOrMark({
+        command: control.command,
+      }),
+      link: () => this.openLinkDialog(),
+      image: () => this.openImagePicker(),
+      mention: () => this.commandContext.insertText({
+        text: '@',
+      }),
+    }
+
+    actionHash[control.kind]?.()
+  }
+
+  /**
+   * Open a native file picker for images and insert the chosen files inline.
+   *
+   * @returns {void}
+   */
+  openImagePicker () {
+    if (!this.hasImageFeature()) {
+      return
+    }
+
+    const input = this.createImageFileInput()
+
+    input.addEventListener('change', () => {
+      this.uploadAndInsertImages({
+        files: input.files,
+        position: null,
+      })
+    })
+
+    input.click()
+  }
+
+  /**
+   * Create a hidden multi-image file input element.
+   *
+   * @returns {HTMLInputElement} - The file input.
+   */
+  createImageFileInput () {
+    const input = document.createElement('input')
+
+    input.type = 'file'
+    input.accept = 'image/*'
+    input.multiple = true
+
+    return input
+  }
+
+  /**
+   * Extract image files from a FileList-like value.
+   *
+   * @param {{
+   *   fileSource: FileList | null
+   * }} params - Parameters of this method.
+   * @returns {Array<File>} - Image files only.
+   */
+  extractImageFiles ({
+    fileSource,
+  }) {
+    if (!fileSource) {
+      return []
+    }
+
+    return Array.from(fileSource)
+      .filter(file => file.type.startsWith('image/'))
+  }
+
+  /**
+   * Extract the image files the editor embeds itself, empty without an upload adapter.
+   *
+   * @param {{
+   *   fileSource: FileList | null
+   * }} params - Parameters of this method.
+   * @returns {Array<File>} - Image files the editor takes.
+   */
+  extractInsertableImageFiles ({
+    fileSource,
+  }) {
+    if (!this.hasImageFeature()) {
+      return []
+    }
+
+    return this.extractImageFiles({ fileSource })
+  }
+
+  /**
+   * Extract the files the editor leaves for the consumer to store.
+   *
+   * @param {{
+   *   fileSource: FileList | null
+   * }} params - Parameters of this method.
+   * @returns {Array<File>} - Files the editor does not insert.
+   */
+  extractUnconsumedFiles ({
+    fileSource,
+  }) {
+    if (!fileSource) {
+      return []
+    }
+
+    const insertableFiles = this.extractInsertableImageFiles({ fileSource })
+
+    return Array.from(fileSource)
+      .filter(file => !insertableFiles.includes(file))
+  }
+
+  /**
+   * Upload image files through the consumer adapter and insert them inline.
+   *
+   * The first file lands at `position` (or the cursor when null); the rest follow
+   * it in order. Uploads run sequentially to preserve document order.
+   *
+   * @param {{
+   *   files: FileList | Array<File> | null
+   *   position?: number | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  uploadAndInsertImages ({
+    files,
+    position = null,
+  }) {
+    const imageFiles = this.extractImageFiles({
+      fileSource: /** @type {FileList | null} */ (files),
+    })
+
+    imageFiles.reduce(
+      async (previousPromise, file, index) => {
+        await previousPromise
+
+        const insertPosition = index === 0
+          ? position
+          : null
+
+        await this.uploadAndInsertImage({
+          file,
+          position: insertPosition,
+        })
+      },
+      Promise.resolve()
+    )
+  }
+
+  /**
+   * Upload one image and insert it, reporting a refusal instead of ending the batch.
+   *
+   * @param {{
+   *   file: File
+   *   position: number | null
+   * }} params - Parameters of this method.
+   * @returns {Promise<void>} - Resolves once the file is inserted or reported.
+   */
+  async uploadAndInsertImage ({
+    file,
+    position,
+  }) {
+    const uploadImage = this.parcel?.image?.uploadImage
+
+    if (!uploadImage) {
+      return
+    }
+
+    try {
+      const uploaded = await uploadImage({ file })
+      const altText = uploaded.alt
+        ?? ''
+
+      this.commandContext.insertImage({
+        src: uploaded.src,
+        alt: altText,
+        position,
+      })
+    } catch (error) {
+      this.emit(this.EMIT_EVENT_NAME.IMAGE_ERROR, {
+        file,
+        error,
+      })
+    }
+  }
+
+  /**
+   * React to a dropdown option selection.
+   *
+   * @param {{
+   *   value?: string
+   * }} params - Parameters of this method (value is the option's encoded action).
+   * @returns {void}
+   */
+  onDropdownSelect ({
+    value = '',
+  }) {
+    const [
+      kind,
+      ...rest
+    ] = value.split(':')
+    const argument = rest.join(':')
+
+    const actionHash = {
+      paragraph: () => this.commandContext.executeDropdownCommand({
+        command: 'setParagraph',
+      }),
+      heading: () => this.commandContext.executeDropdownCommand({
+        command: 'toggleHeading',
+        level: Number(argument),
+      }),
+      color: () => this.commandContext.executeDropdownCommand({
+        command: 'setColor',
+        value: argument,
+      }),
+      align: () => this.commandContext.executeDropdownCommand({
+        command: 'setTextAlign',
+        value: argument,
+      }),
+    }
+
+    actionHash[/** @type {keyof typeof actionHash} */ (kind)]?.()
+  }
+
+  /**
+   * Whether a formatting control is currently active.
+   *
+   * @param {{
+   *   control: FuroEditorControl
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when active.
+   */
+  isControlActive ({
+    control,
+  }) {
+    return this.commandContext.isActive({
+      name: control.name,
+    })
+  }
+
+  /**
+   * Extract the button variant for a control based on its active state.
+   *
+   * @param {{
+   *   control: FuroEditorControl
+   * }} params - Parameters of this method.
+   * @returns {'secondary' | 'ghost'} - Variant.
+   */
+  extractControlVariant ({
+    control,
+  }) {
+    return this.isControlActive({
+      control,
+    })
+      ? 'secondary'
+      : 'ghost'
+  }
+
+  /**
+   * Extract the trigger variant for a dropdown group based on its active state.
+   *
+   * @param {{
+   *   kind: 'heading' | 'textStyle' | 'textAlign'
+   * }} params - Parameters of this method.
+   * @returns {'secondary' | 'ghost'} - Variant.
+   */
+  extractDropdownVariant ({
+    kind,
+  }) {
+    return this.isDropdownActive({
+      kind,
+    })
+      ? 'secondary'
+      : 'ghost'
+  }
+
+  /**
+   * Whether a dropdown group (heading / color / align) is active.
+   *
+   * @param {{
+   *   kind: 'heading' | 'textStyle' | 'textAlign'
+   * }} params - Parameters of this method.
+   * @returns {boolean} - true when active.
+   */
+  isDropdownActive ({
+    kind,
+  }) {
+    const activeHash = {
+      heading: () => this.commandContext.isActive({
+        name: 'heading',
+      }),
+      textStyle: () => this.commandContext.isActive({
+        name: 'textStyle',
+      }),
+      textAlign: () => this.commandContext.hasActiveTextAlign({
+        alignments: [
+          'left',
+          'center',
+          'right',
+          'justify',
+        ],
+      }),
+    }
+
+    return activeHash[kind]?.()
+      ?? false
+  }
+
+  /**
+   * Reflect the dialog open state from a FuroDialog open change.
+   *
+   * @param {{
+   *   isOpen: boolean
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  onLinkDialogOpenChange ({
+    isOpen,
+  }) {
+    this.statusReactive.isLinkDialogOpen = isOpen
+  }
+
+  /**
+   * Open the link dialog, prefilling from the current selection.
+   *
+   * @returns {void}
+   */
+  openLinkDialog () {
+    const selectionLink = this.commandContext.extractSelectionLink()
+
+    this.addLinkReactive.url = selectionLink.url
+    this.addLinkReactive.displayText = selectionLink.displayText
+    this.linkRange = selectionLink.range
+
+    this.statusReactive.isLinkDialogOpen = true
+  }
+
+  /**
+   * Close the link dialog.
+   *
+   * @returns {void}
+   */
+  closeLinkDialog () {
+    this.statusReactive.isLinkDialogOpen = false
+  }
+
+  /**
+   * Apply the link from the dialog and close it.
+   *
+   * @returns {void}
+   */
+  saveLink () {
+    const { url } = this.addLinkReactive
+    const { displayText } = this.addLinkReactive
+    const range = this.linkRange
+
+    this.closeLinkDialog()
+
+    this.addLinkReactive.url = ''
+    this.addLinkReactive.displayText = ''
+
+    // Apply after the modal closes so focus returns to the editor before the edit.
+    nextTick(() => {
+      this.commandContext.applyLink({
+        url,
+        displayText,
+        range,
+      })
+
+      this.linkRange = null
+    })
+  }
+
+  /**
+   * Update the dialog link URL.
+   *
+   * @param {{
+   *   url?: string | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  updateLinkUrl ({
+    url = '',
+  }) {
+    this.addLinkReactive.url = url ?? ''
+  }
+
+  /**
+   * Update the dialog link display text.
+   *
+   * @param {{
+   *   displayText?: string | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  updateLinkDisplayText ({
+    displayText = '',
+  }) {
+    this.addLinkReactive.displayText = displayText ?? ''
+  }
+
+  /**
+   * Remove an attached file by index and emit the updated array.
+   *
+   * @param {{
+   *   index: number
+   * }} params - Parameters of this method.
+   * @returns {void}
+   */
+  removeAttachedFile ({
+    index,
+  }) {
+    const nextFiles = this.attachedFiles
+      .filter((file, fileIndex) => fileIndex !== index)
+
+    this.emit(this.EMIT_EVENT_NAME.UPDATE_ATTACHED_FILES, nextFiles)
+  }
+
+  /**
+   * Whether the consumer provided an `attachments` slot.
+   *
+   * @returns {boolean} - true when the slot is present.
+   */
+  hasAttachmentsSlot () {
+    return Boolean(this.slots?.attachments)
+  }
+}
+
+/**
+ * @typedef {{
+ *   name: string
+ *   kind: 'toggle' | 'link' | 'image' | 'mention'
+ *   command: string
+ *   iconName: string
+ *   activeIconName: string
+ *   tooltip: string
+ * }} FuroEditorControl
+ */
+
+/**
+ * @typedef {{
+ *   type: 'separator'
+ *   key: string
+ * } | {
+ *   type: 'dropdown'
+ *   key: string
+ *   label: string
+ *   iconName: string
+ *   dropdownKind: 'heading' | 'textStyle' | 'textAlign'
+ *   hasSwatch?: boolean
+ *   options: Array<import('../../molecules/FuroDropdownMenu/DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption>
+ * } | {
+ *   type: 'control'
+ *   key: string
+ *   control: FuroEditorControl
+ * } | {
+ *   type: 'overflow'
+ *   key: string
+ * }} FuroEditorToolbarEntry
+ */
+
+/**
+ * @typedef {{
+ *   isLinkDialogOpen: boolean
+ * }} FuroEditorStatusReactive
+ */
+
+/**
+ * @typedef {{
+ *   url: string
+ *   displayText: string
+ * }} FuroEditorAddLinkReactive
+ */
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams<{
+ *   parcel?: FuroEditorParcel | null
+ * }> & {
+ *   editorRef: ReturnType<typeof import('@tiptap/vue-3').useEditor>
+ *   reactiveHash: {
+ *     statusReactive: import('vue').Reactive<FuroEditorStatusReactive>
+ *     addLinkReactive: import('vue').Reactive<FuroEditorAddLinkReactive>
+ *   }
+ * }} FuroEditorContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroEditorContextParams, 'reactiveHash'> & {
+ *   reactiveHash?: FuroEditorContextParams['reactiveHash']
+ * }} FuroEditorContextFactoryParams
+ */
+
+/**
+ * @typedef {{
+ *   value?: string
+ *   placeholder?: string
+ *   readOnly?: boolean
+ *   appearance?: 'editor' | 'plain'
+ *   autofocus?: boolean | 'start' | 'end' | 'all' | number
+ *   contentAttributes?: Record<string, string>
+ *   toolbar?: Array<Array<string>>
+ *   attachedFiles?: Array<*>
+ *   labels?: Partial<typeof DEFAULT_LABELS>
+ *   mention?: {
+ *     searchMentions: (params: { query: string }) => Promise<Array<{ id: string | number, label: string }>>
+ *   }
+ *   image?: {
+ *     uploadImage: (params: { file: File }) => Promise<{ src: string, alt?: string }>
+ *   }
+ *   actionOverrides?: Record<string, (params: {
+ *     control: FuroEditorControl
+ *     command: FuroEditorCommandContext
+ *     editor: import('@tiptap/vue-3').Editor | null
+ *   }) => void>
+ * }} FuroEditorParcel
+ */