@byline/richtext-lexical 6.4.0 → 6.6.0

package/src/field/extensions/inline-image/inline-image-node.test.tsx

@@ -0,0 +1,331 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Serialization coverage for the inline image's optional click-through
+ * link.
+ *
+ * The JSON round-trip is the load-bearing one: copying an inline image in
+ * the editor and pasting it elsewhere goes through
+ * `application/x-lexical-editor` (priority 0, ahead of `text/html` at 10 —
+ * see `@lexical/clipboard`'s `DEFAULT_IMPORT_MIME_TYPE_PRIORITY`), which is
+ * `exportJSON` → `importJSON`, NOT `exportDOM` / `importDOM`. So the link
+ * surviving `exportJSON`/`importJSON` is what makes copy-paste keep it.
+ *
+ * The DOM round-trip is the secondary path — pasting out to a non-Lexical
+ * target and back, or between editors whose namespaces differ. It encodes
+ * the relation on the `<img>` as `data-link-*` attributes rather than
+ * wrapping in an `<a>`, because an `<a>` would make Lexical's own link
+ * conversion produce a link node wrapping an inline-image node on import.
+ */
+
+import { createEditor, type LexicalEditor } from 'lexical'
+import { describe, expect, it } from 'vitest'
+
+import { $createInlineImageNode, $isInlineImageNode, InlineImageNode } from './inline-image-node'
+import type { LinkAttributes } from '../link'
+import type { InlineImageAttributes, SerializedInlineImageNode } from './node-types'
+
+function editorWithImageNode(): LexicalEditor {
+  return createEditor({
+    namespace: 'test',
+    nodes: [InlineImageNode],
+    onError: (e) => {
+      throw e
+    },
+  })
+}
+
+const baseAttributes: InlineImageAttributes = {
+  targetDocumentId: 'media-1',
+  targetCollectionId: 'coll-media',
+  targetCollectionPath: 'media',
+  src: 'https://cdn.example.com/media/shot-card.avif',
+  altText: 'A photograph of a heron',
+  position: 'left',
+  width: 600,
+  height: 450,
+  showCaption: false,
+}
+
+const internalLink: LinkAttributes = {
+  linkType: 'internal',
+  newTab: false,
+  targetDocumentId: 'doc-1',
+  targetCollectionId: 'coll-pages',
+  targetCollectionPath: 'pages',
+  document: { title: 'About Us', path: '/pages/about' },
+}
+
+const customLink: LinkAttributes = {
+  linkType: 'custom',
+  url: 'https://example.com/report',
+  newTab: true,
+}
+
+/** Serialize a node built from `attributes`, then parse it back. */
+function jsonRoundTrip(attributes: InlineImageAttributes): SerializedInlineImageNode {
+  const editor = editorWithImageNode()
+  let serialized: SerializedInlineImageNode | undefined
+  editor.update(
+    () => {
+      const exported = $createInlineImageNode(attributes).exportJSON()
+      const reimported = InlineImageNode.importJSON(exported)
+      serialized = reimported.exportJSON()
+    },
+    { discrete: true }
+  )
+  if (serialized == null) throw new Error('round-trip produced nothing')
+  return serialized
+}
+
+describe('InlineImageNode link serialization', () => {
+  describe('exportJSON', () => {
+    it('omits link entirely when the image has no click target', () => {
+      const editor = editorWithImageNode()
+      let out: SerializedInlineImageNode | undefined
+      editor.update(
+        () => {
+          out = $createInlineImageNode(baseAttributes).exportJSON()
+        },
+        { discrete: true }
+      )
+      expect(out?.link).toBeUndefined()
+    })
+
+    it('carries an internal link', () => {
+      const editor = editorWithImageNode()
+      let out: SerializedInlineImageNode | undefined
+      editor.update(
+        () => {
+          out = $createInlineImageNode({ ...baseAttributes, link: internalLink }).exportJSON()
+        },
+        { discrete: true }
+      )
+      expect(out?.link).toEqual(internalLink)
+    })
+  })
+
+  describe('JSON round-trip (the copy-paste path)', () => {
+    it('preserves an internal link', () => {
+      expect(jsonRoundTrip({ ...baseAttributes, link: internalLink }).link).toEqual(internalLink)
+    })
+
+    it('preserves a custom URL link with its newTab flag', () => {
+      expect(jsonRoundTrip({ ...baseAttributes, link: customLink }).link).toEqual(customLink)
+    })
+
+    it('leaves an unlinked image unlinked', () => {
+      expect(jsonRoundTrip(baseAttributes).link).toBeUndefined()
+    })
+
+    it('keeps the media relation and the link relation distinct', () => {
+      const out = jsonRoundTrip({ ...baseAttributes, link: internalLink })
+      expect(out.targetDocumentId).toBe('media-1')
+      expect(out.targetCollectionPath).toBe('media')
+      expect(out.link?.linkType === 'internal' && out.link.targetDocumentId).toBe('doc-1')
+    })
+
+    // Nodes written before this feature have no `link` key at all; they
+    // must import without complaint and stay unlinked.
+    it('imports a pre-feature node that has no link key', () => {
+      const editor = editorWithImageNode()
+      let node: InlineImageNode | undefined
+      editor.update(
+        () => {
+          const legacy = { ...baseAttributes, type: 'inline-image', version: 1 } as any
+          delete legacy.link
+          legacy.caption = { editorState: { root: { children: [], type: 'root', version: 1 } } }
+          node = InlineImageNode.importJSON(legacy)
+        },
+        { discrete: true }
+      )
+      expect(node && $isInlineImageNode(node)).toBe(true)
+      expect(node?.getLink()).toBeUndefined()
+    })
+  })
+
+  describe('update()', () => {
+    it('sets a link on an image that had none', () => {
+      const editor = editorWithImageNode()
+      let link: LinkAttributes | undefined
+      editor.update(
+        () => {
+          const node = $createInlineImageNode(baseAttributes)
+          node.update({ ...baseAttributes, link: internalLink })
+          link = node.getLink()
+        },
+        { discrete: true }
+      )
+      expect(link).toEqual(internalLink)
+    })
+
+    it('replaces an existing link', () => {
+      const editor = editorWithImageNode()
+      let link: LinkAttributes | undefined
+      editor.update(
+        () => {
+          const node = $createInlineImageNode({ ...baseAttributes, link: internalLink })
+          node.update({ ...baseAttributes, link: customLink })
+          link = node.getLink()
+        },
+        { discrete: true }
+      )
+      expect(link).toEqual(customLink)
+    })
+
+    // The rest of `update()` uses `!= null` guards, so an explicit
+    // undefined would be a silent no-op. Removing a link has to work.
+    it('clears the link when the key is present and undefined', () => {
+      const editor = editorWithImageNode()
+      let link: LinkAttributes | undefined = internalLink
+      editor.update(
+        () => {
+          const node = $createInlineImageNode({ ...baseAttributes, link: internalLink })
+          node.update({ ...baseAttributes, link: undefined })
+          link = node.getLink()
+        },
+        { discrete: true }
+      )
+      expect(link).toBeUndefined()
+    })
+
+    it('leaves the link untouched when the key is absent', () => {
+      const editor = editorWithImageNode()
+      let link: LinkAttributes | undefined
+      editor.update(
+        () => {
+          const node = $createInlineImageNode({ ...baseAttributes, link: internalLink })
+          node.update({ altText: 'Changed alt' } as InlineImageAttributes)
+          link = node.getLink()
+        },
+        { discrete: true }
+      )
+      expect(link).toEqual(internalLink)
+    })
+  })
+
+  describe('DOM round-trip', () => {
+    it('encodes a custom link as data attributes without wrapping in an anchor', () => {
+      const editor = editorWithImageNode()
+      let element: HTMLElement | undefined
+      editor.update(
+        () => {
+          element = $createInlineImageNode({ ...baseAttributes, link: customLink }).exportDOM()
+            .element as HTMLElement
+        },
+        { discrete: true }
+      )
+      expect(element?.tagName).toBe('IMG')
+      expect(element?.getAttribute('data-link-type')).toBe('custom')
+      expect(element?.getAttribute('data-link-url')).toBe('https://example.com/report')
+      expect(element?.getAttribute('data-link-new-tab')).toBe('true')
+    })
+
+    it('encodes an internal link relation as data attributes', () => {
+      const editor = editorWithImageNode()
+      let element: HTMLElement | undefined
+      editor.update(
+        () => {
+          element = $createInlineImageNode({ ...baseAttributes, link: internalLink }).exportDOM()
+            .element as HTMLElement
+        },
+        { discrete: true }
+      )
+      expect(element?.getAttribute('data-link-type')).toBe('internal')
+      expect(element?.getAttribute('data-link-target-document-id')).toBe('doc-1')
+      expect(element?.getAttribute('data-link-target-collection-id')).toBe('coll-pages')
+      expect(element?.getAttribute('data-link-target-collection-path')).toBe('pages')
+    })
+
+    it('emits no link attributes for an unlinked image', () => {
+      const editor = editorWithImageNode()
+      let element: HTMLElement | undefined
+      editor.update(
+        () => {
+          element = $createInlineImageNode(baseAttributes).exportDOM().element as HTMLElement
+        },
+        { discrete: true }
+      )
+      expect(element?.hasAttribute('data-link-type')).toBe(false)
+    })
+
+    it('reads a custom link back off the data attributes', () => {
+      const editor = editorWithImageNode()
+      const img = document.createElement('img')
+      img.setAttribute('src', baseAttributes.src)
+      img.setAttribute('alt', 'A photograph of a heron')
+      img.setAttribute('data-id', 'media-1')
+      img.setAttribute('data-collection', 'media')
+      img.setAttribute('data-link-type', 'custom')
+      img.setAttribute('data-link-url', 'https://example.com/report')
+      img.setAttribute('data-link-new-tab', 'true')
+
+      let link: LinkAttributes | undefined
+      editor.update(
+        () => {
+          const conversion = InlineImageNode.importDOM()?.img?.(img)
+          const output = conversion?.conversion(img)
+          const node = output?.node
+          link = $isInlineImageNode(node) ? node.getLink() : undefined
+        },
+        { discrete: true }
+      )
+      expect(link).toEqual({ linkType: 'custom', url: 'https://example.com/report', newTab: true })
+    })
+
+    // The denormalised `{ title, path }` bag is deliberately NOT encoded —
+    // it is re-derived by `inlineImageLinkVisitor` on the next save or
+    // read, so the relation ids are all the markup needs to carry.
+    it('reads an internal link relation back without the denormalised document bag', () => {
+      const editor = editorWithImageNode()
+      const img = document.createElement('img')
+      img.setAttribute('src', baseAttributes.src)
+      img.setAttribute('alt', 'A photograph of a heron')
+      img.setAttribute('data-link-type', 'internal')
+      img.setAttribute('data-link-target-document-id', 'doc-1')
+      img.setAttribute('data-link-target-collection-id', 'coll-pages')
+      img.setAttribute('data-link-target-collection-path', 'pages')
+
+      let link: LinkAttributes | undefined
+      editor.update(
+        () => {
+          const output = InlineImageNode.importDOM()?.img?.(img)?.conversion(img)
+          const node = output?.node
+          link = $isInlineImageNode(node) ? node.getLink() : undefined
+        },
+        { discrete: true }
+      )
+      expect(link).toEqual({
+        linkType: 'internal',
+        newTab: false,
+        targetDocumentId: 'doc-1',
+        targetCollectionId: 'coll-pages',
+        targetCollectionPath: 'pages',
+      })
+    })
+
+    it('produces no link for an ordinary pasted image', () => {
+      const editor = editorWithImageNode()
+      const img = document.createElement('img')
+      img.setAttribute('src', 'https://example.com/plain.jpg')
+      img.setAttribute('alt', 'Plain')
+
+      let link: LinkAttributes | undefined = customLink
+      editor.update(
+        () => {
+          const output = InlineImageNode.importDOM()?.img?.(img)?.conversion(img)
+          const node = output?.node
+          link = $isInlineImageNode(node) ? node.getLink() : undefined
+        },
+        { discrete: true }
+      )
+      expect(link).toBeUndefined()
+    })
+  })
+})

package/src/field/extensions/inline-image/inline-image-node.tsx

@@ -24,10 +24,60 @@ import type {
 import { $applyNodeReplacement, createEditor, DecoratorNode } from 'lexical'
 
 import type { DocumentRelation } from '../../nodes/document-relation'
+import type { LinkAttributes } from '../link'
 import type { InlineImageAttributes, Position, SerializedInlineImageNode } from './node-types'
 
 const InlineImageComponent = React.lazy(async () => await import('./inline-image-node-component'))
 
+/**
+ * Encode an optional click-through target onto the exported `<img>`.
+ *
+ * Deliberately NOT an `<a>` wrapper: Lexical's own link conversion would
+ * claim that anchor on re-import and produce a link node wrapping an
+ * inline-image node — a shape this plugin does not model. Discrete
+ * `data-link-*` attributes survive the existing `img` conversion instead.
+ *
+ * The denormalised `{ title, path }` bag is not encoded. It is re-derived
+ * by `inlineImageLinkVisitor` on the next save or read, so the relation
+ * ids are all the markup needs to carry.
+ */
+function writeLinkAttributes(element: HTMLElement, link: LinkAttributes | undefined): void {
+  if (link == null) return
+  element.setAttribute('data-link-type', link.linkType ?? 'custom')
+  if (link.newTab === true) element.setAttribute('data-link-new-tab', 'true')
+  if (link.linkType === 'internal') {
+    element.setAttribute('data-link-target-document-id', link.targetDocumentId)
+    element.setAttribute('data-link-target-collection-id', link.targetCollectionId)
+    element.setAttribute('data-link-target-collection-path', link.targetCollectionPath)
+  } else if (link.url != null) {
+    element.setAttribute('data-link-url', link.url)
+  }
+}
+
+/** Inverse of `writeLinkAttributes`. Returns undefined for an unlinked image. */
+function readLinkAttributes(domNode: HTMLElement): LinkAttributes | undefined {
+  const linkType = domNode.dataset.linkType
+  if (linkType !== 'custom' && linkType !== 'internal') return undefined
+  const newTab = domNode.dataset.linkNewTab === 'true'
+  if (linkType === 'internal') {
+    const targetDocumentId = domNode.dataset.linkTargetDocumentId
+    const targetCollectionPath = domNode.dataset.linkTargetCollectionPath
+    // Without both ids there is nothing to resolve; drop the link rather
+    // than carry an envelope the visitor can never hydrate.
+    if (!targetDocumentId || !targetCollectionPath) return undefined
+    return {
+      linkType: 'internal',
+      newTab,
+      targetDocumentId,
+      targetCollectionId: domNode.dataset.linkTargetCollectionId ?? '',
+      targetCollectionPath,
+    }
+  }
+  const url = domNode.dataset.linkUrl
+  if (!url) return undefined
+  return { linkType: 'custom', url, newTab }
+}
+
 function convertInlineImageElement(domNode: Node): null | DOMConversionOutput {
   if (domNode instanceof HTMLImageElement) {
     const { alt: altText, src, width, height } = domNode
@@ -42,6 +92,7 @@ function convertInlineImageElement(domNode: Node): null | DOMConversionOutput {
       altText,
       height,
       width,
+      link: readLinkAttributes(domNode),
     })
     return { node }
   }
@@ -57,6 +108,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
   __height: number | string | undefined
   __showCaption: boolean
   __caption: LexicalEditor
+  __link: LinkAttributes | undefined
 
   static getType(): string {
     return 'inline-image'
@@ -72,6 +124,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
       node.__height,
       node.__showCaption,
       node.__caption,
+      node.__link,
       node.__key
     )
   }
@@ -85,6 +138,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
       width,
       showCaption,
       caption,
+      link,
       targetDocumentId,
       targetCollectionId,
       targetCollectionPath,
@@ -101,6 +155,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
       width,
       height,
       showCaption,
+      link,
     })
     const nestedEditor = node.__caption
     const editorState = nestedEditor.parseEditorState(caption.editorState)
@@ -128,6 +183,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
     height?: number | string,
     showCaption?: boolean,
     caption?: LexicalEditor,
+    link?: LinkAttributes,
     key?: NodeKey
   ) {
     super(key)
@@ -139,6 +195,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
     this.__height = height
     this.__showCaption = showCaption ?? false
     this.__caption = caption ?? createEditor()
+    this.__link = link
   }
 
   exportDOM(): DOMExportOutput {
@@ -155,6 +212,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
     if (this.__height != null) {
       element.setAttribute('height', this.__height.toString())
     }
+    writeLinkAttributes(element, this.__link)
     return { element }
   }
 
@@ -168,6 +226,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
       width: this.__width,
       showCaption: this.__showCaption,
       caption: this.__caption.toJSON(),
+      link: this.__link,
       type: 'inline-image',
       version: 1,
     }
@@ -205,6 +264,15 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
     writable.__showCaption = showCaption
   }
 
+  getLink(): LinkAttributes | undefined {
+    return this.__link
+  }
+
+  setLink(link: LinkAttributes | undefined): void {
+    const writable = this.getWritable()
+    writable.__link = link
+  }
+
   getPosition(): Position {
     return this.__position
   }
@@ -228,6 +296,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
       width,
       showCaption,
     } = payload
+
     if (targetDocumentId != null) {
       writable.__relation = {
         targetDocumentId,
@@ -254,29 +323,44 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
     if (showCaption != null) {
       writable.__showCaption = showCaption
     }
+    // `link` is keyed on PRESENCE, not on null-ness, unlike every field
+    // above. The `!= null` convention cannot express "remove the link" —
+    // an explicit `link: undefined` would be a silent no-op — and
+    // clearing a click target has to work.
+    if ('link' in payload) {
+      writable.__link = payload.link
+    }
   }
 
   // View
 
+  /**
+   * `has-link` drives the editor's cursor affordance — see
+   * `inline-image-node-component.css`. It is a class rather than a
+   * decorator-side style so the hover state is correct before React has
+   * hydrated the decorator.
+   */
+  private buildClassName(config: EditorConfig): string {
+    const linked = this.__link != null ? ' has-link' : ''
+    return `${config.theme.inlineImage} position-${this.__position}${linked}`
+  }
+
   createDOM(config: EditorConfig): HTMLElement {
     const span = document.createElement('span')
-    const className = `${config.theme.inlineImage} position-${this.__position}`
-    if (className !== undefined) {
-      span.className = className
-    }
+    span.className = this.buildClassName(config)
     return span
   }
 
   updateDOM(prevNode: InlineImageNode, dom: HTMLElement, config: EditorConfig): boolean {
-    const position = this.__position
-    if (position !== prevNode.__position) {
-      const className = `${config.theme.inlineImage} position-${position}`
-      if (className !== undefined) {
-        dom.className = className
-      }
+    if (
+      this.__position !== prevNode.__position ||
+      (this.__link != null) !== (prevNode.__link != null)
+    ) {
+      dom.className = this.buildClassName(config)
       return true
     }
     if (this.__showCaption !== prevNode.__showCaption) return true
+    if (this.__link !== prevNode.__link) return true
     return false
   }
 
@@ -292,6 +376,7 @@ export class InlineImageNode extends DecoratorNode<React.JSX.Element> {
           height={this.__height}
           showCaption={this.__showCaption}
           caption={this.__caption}
+          link={this.__link}
           nodeKey={this.getKey()}
         />
       </Suspense>
@@ -311,6 +396,7 @@ export function $createInlineImageNode({
   width,
   showCaption,
   caption,
+  link,
   key,
 }: InlineImageAttributes): InlineImageNode {
   const relation: DocumentRelation = {
@@ -320,7 +406,18 @@ export function $createInlineImageNode({
     document,
   }
   return $applyNodeReplacement(
-    new InlineImageNode(relation, src, position, altText, width, height, showCaption, caption, key)
+    new InlineImageNode(
+      relation,
+      src,
+      position,
+      altText,
+      width,
+      height,
+      showCaption,
+      caption,
+      link,
+      key
+    )
   )
 }
 

package/src/field/extensions/inline-image/node-types.ts

@@ -15,9 +15,25 @@ import type {
 } from 'lexical'
 
 import type { DocumentRelation } from '../../nodes/document-relation'
+import type { LinkAttributes } from '../link'
 
 export type Position = 'left' | 'right' | 'full' | 'wide' | 'default' | undefined
 
+/**
+ * An inline image carries **two** independent document references, and the
+ * distinction matters at every layer:
+ *
+ *   - the flat `DocumentRelation` this interface extends — the *media*
+ *     document the image is sourced from. Always present.
+ *   - `link` — an optional *click-through target*. Nested rather than
+ *     flattened precisely because the flat envelope is already spent on
+ *     the media pick, and the two resolve against different collections.
+ *
+ * `link` reuses the link extension's discriminated union, so an image can
+ * point at a Byline document (`linkType: 'internal'`, relation refreshed
+ * by `inlineImageLinkVisitor`) or at an arbitrary URL
+ * (`linkType: 'custom'`). Absent means the image is not clickable.
+ */
 export interface InlineImageAttributes extends DocumentRelation {
   src: string
   altText?: string
@@ -27,6 +43,7 @@ export interface InlineImageAttributes extends DocumentRelation {
   key?: NodeKey
   showCaption?: boolean
   caption?: LexicalEditor
+  link?: LinkAttributes
 }
 
 export type SerializedInlineImageNode = Spread<
@@ -38,6 +55,8 @@ export type SerializedInlineImageNode = Spread<
     width?: number | string
     showCaption: boolean
     caption: SerializedEditor
+    /** Optional click-through target; absent on unlinked images. */
+    link?: LinkAttributes
   },
   SerializedLexicalNode
 >