@byline/richtext-lexical 6.4.0 → 6.5.0

package/src/field/extensions/link/populate.ts

@@ -45,7 +45,99 @@
 
 import { getCollectionDefinition, getLogger } from '@byline/core'
 
-import type { LexicalNodeLike, LexicalNodeVisitor } from '../../lexical-populate-shared'
+import type {
+  LexicalNodeLike,
+  LexicalNodeVisitor,
+  PendingHydration,
+} from '../../lexical-populate-shared'
+
+/**
+ * Build the `apply` / `applyMissing` pair that refreshes an internal-link
+ * relation envelope in place.
+ *
+ * Shared by `linkVisitor` (where the envelope is `node.attributes`) and by
+ * the inline-image plugin's `inlineImageLinkVisitor` (where it is
+ * `node.link`). Both carry the same `DocumentRelation` shape and want the
+ * same three branches, so the resolution rules documented above live here
+ * once rather than being copied per node type.
+ *
+ * `envelope` is mutated in place — the caller owns where it hangs off the
+ * node.
+ */
+export function createInternalLinkHydration(
+  envelope: Record<string, any>,
+  collectionPath: string,
+  documentId: string
+): Pick<PendingHydration, 'apply' | 'applyMissing'> {
+  return {
+    apply(target: Record<string, any>) {
+      const definition = getCollectionDefinition(collectionPath)
+      const useAsTitle = definition?.useAsTitle ?? 'title'
+      const targetFields = (target.fields ?? {}) as Record<string, any>
+      const next: Record<string, any> = { ...(envelope.document ?? {}) }
+
+      // Title — `useAsTitle` lookup with `title` fallback.
+      const title = targetFields[useAsTitle]
+      if (typeof title === 'string' && title.length > 0) {
+        next.title = title
+      }
+
+      // Path — buildDocumentPath, then generic compose fallback.
+      // Branch A: hook threw — leave any existing `document.path`
+      // untouched and surface a log line so operators can find the
+      // bug without it taking the save / read down with it.
+      let pathThrew = false
+      let built: string | null | undefined
+      if (definition?.buildDocumentPath != null) {
+        try {
+          built = definition.buildDocumentPath(
+            {
+              id: target.id as string,
+              path: target.path as string,
+              status: target.status as string,
+              fields: targetFields,
+            },
+            { collectionPath }
+          )
+        } catch (err) {
+          pathThrew = true
+          getLogger().info({ collectionPath, documentId, err }, 'buildDocumentPath threw')
+        }
+      }
+
+      if (!pathThrew) {
+        if (typeof built === 'string') {
+          next.path = built
+        } else {
+          // Generic compose fallback. Only fires when the target has a
+          // non-empty `path` — otherwise we'd produce `/${collectionPath}/`
+          // or `/${collectionPath}/undefined`, both of which are worse
+          // than leaving the previous value alone.
+          const targetPath = target.path as string | undefined
+          if (typeof targetPath === 'string' && targetPath.length > 0) {
+            next.path = `/${collectionPath}/${targetPath}`
+          }
+        }
+      }
+
+      // Found-and-resolved: clear any stale miss flag from a prior pass.
+      if ('_resolved' in next) {
+        delete next._resolved
+      }
+
+      envelope.document = next
+    },
+    applyMissing() {
+      // Branch B — target deleted between picker and walker.
+      getLogger().warn({ collectionPath, documentId }, 'internal link target not found')
+      const next: Record<string, any> = { ...(envelope.document ?? {}) }
+      delete next.title
+      delete next.path
+      next._resolved = false
+      envelope.document = next
+    },
+  }
+}
 
 export const linkVisitor: LexicalNodeVisitor = {
   match(node: LexicalNodeLike) {
@@ -61,72 +153,7 @@ export const linkVisitor: LexicalNodeVisitor = {
       node,
       collectionPath,
       documentId,
-      apply(target: Record<string, any>) {
-        const definition = getCollectionDefinition(collectionPath)
-        const useAsTitle = definition?.useAsTitle ?? 'title'
-        const targetFields = (target.fields ?? {}) as Record<string, any>
-        const next: Record<string, any> = { ...(attributes.document ?? {}) }
-
-        // Title — `useAsTitle` lookup with `title` fallback.
-        const title = targetFields[useAsTitle]
-        if (typeof title === 'string' && title.length > 0) {
-          next.title = title
-        }
-
-        // Path — buildDocumentPath, then generic compose fallback.
-        // Branch A: hook threw — leave any existing `document.path`
-        // untouched and surface a log line so operators can find the
-        // bug without it taking the save / read down with it.
-        let pathThrew = false
-        let built: string | null | undefined
-        if (definition?.buildDocumentPath != null) {
-          try {
-            built = definition.buildDocumentPath(
-              {
-                id: target.id as string,
-                path: target.path as string,
-                status: target.status as string,
-                fields: targetFields,
-              },
-              { collectionPath }
-            )
-          } catch (err) {
-            pathThrew = true
-            getLogger().info({ collectionPath, documentId, err }, 'buildDocumentPath threw')
-          }
-        }
-
-        if (!pathThrew) {
-          if (typeof built === 'string') {
-            next.path = built
-          } else {
-            // Generic compose fallback. Only fires when the target has a
-            // non-empty `path` — otherwise we'd produce `/${collectionPath}/`
-            // or `/${collectionPath}/undefined`, both of which are worse
-            // than leaving the previous value alone.
-            const targetPath = target.path as string | undefined
-            if (typeof targetPath === 'string' && targetPath.length > 0) {
-              next.path = `/${collectionPath}/${targetPath}`
-            }
-          }
-        }
-
-        // Found-and-resolved: clear any stale miss flag from a prior pass.
-        if ('_resolved' in next) {
-          delete next._resolved
-        }
-
-        attributes.document = next
-      },
-      applyMissing() {
-        // Branch B — target deleted between picker and walker.
-        getLogger().warn({ collectionPath, documentId }, 'internal link target not found')
-        const next: Record<string, any> = { ...(attributes.document ?? {}) }
-        delete next.title
-        delete next.path
-        next._resolved = false
-        attributes.document = next
-      },
+      ...createInternalLinkHydration(attributes, collectionPath, documentId),
     }
   },
 }

package/src/field/markdown/lexical-to-markdown.test.node.ts

@@ -309,6 +309,74 @@ describe('lexicalToMarkdown — inline', () => {
     )
   })
 
+  it('wraps a linked inline image in a markdown link', () => {
+    const image = {
+      type: 'inline-image',
+      src: '/uploads/media/photo.avif',
+      altText: 'A photo',
+      showCaption: false,
+      link: { linkType: 'custom', url: 'https://example.com/report', newTab: true },
+      version: 1,
+    }
+    expect(md(root(paragraph(image)))).toBe(
+      '[![A photo](/uploads/media/photo.avif)](https://example.com/report)'
+    )
+  })
+
+  it('resolves an internal link target on a linked inline image', () => {
+    const image = {
+      type: 'inline-image',
+      src: '/uploads/media/photo.avif',
+      altText: 'A photo',
+      showCaption: false,
+      link: {
+        linkType: 'internal',
+        targetDocumentId: 'doc-1',
+        targetCollectionPath: 'pages',
+        document: { title: 'About Us', path: '/pages/about' },
+      },
+      version: 1,
+    }
+    expect(md(root(paragraph(image)))).toBe('[![A photo](/uploads/media/photo.avif)](/pages/about)')
+  })
+
+  // The link wraps the image only. The caption is separate content and
+  // may carry its own links, so nesting it inside the image's link would
+  // produce a nested-anchor shape in every downstream renderer.
+  it('links the image but not its caption', () => {
+    const image = {
+      type: 'inline-image',
+      src: '/uploads/media/photo.avif',
+      altText: 'A photo',
+      showCaption: true,
+      caption: { editorState: root(paragraph(text('Taken in 2026.'))) },
+      link: { linkType: 'custom', url: 'https://example.com/report' },
+      version: 1,
+    }
+    expect(md(root(paragraph(image)))).toBe(
+      '[![A photo](/uploads/media/photo.avif)](https://example.com/report)\n*Taken in 2026.*'
+    )
+  })
+
+  it('drops the link but keeps the image when the target is unresolved', () => {
+    const image = {
+      type: 'inline-image',
+      src: '/uploads/media/photo.avif',
+      altText: 'A photo',
+      showCaption: false,
+      link: {
+        linkType: 'internal',
+        targetDocumentId: 'doc-1',
+        targetCollectionPath: 'pages',
+        document: { _resolved: false },
+      },
+      version: 1,
+    }
+    const result = lexicalToMarkdown(root(paragraph(image)))
+    expect(result.markdown).toBe('![A photo](/uploads/media/photo.avif)')
+    expect(result.warnings).toContainEqual(expect.objectContaining({ kind: 'unresolved-link' }))
+  })
+
   it('serializes hard line breaks', () => {
     expect(
       md(root(paragraph(text('line one'), { type: 'linebreak', version: 1 }, text('line two'))))

package/src/field/markdown/lexical-to-markdown.ts

@@ -424,7 +424,16 @@ function serializeImage(node: AnyNode, ctx: Ctx): string {
   const src = typeof node.src === 'string' ? node.src : ''
   if (src.length === 0) return ''
   const alt = typeof node.altText === 'string' ? node.altText : ''
-  const image = `![${alt.replace(/[[\]]/g, '')}](${src})`
+  let image = `![${alt.replace(/[[\]]/g, '')}](${src})`
+
+  // Optional click-through target. Resolved through the same rules as a
+  // text link, so an unresolved internal target drops the link and keeps
+  // the image rather than emitting a broken href.
+  const link = node.link as Record<string, unknown> | undefined
+  if (link != null) {
+    const href = resolveLinkUrl(link, ctx)
+    if (href != null) image = `[${image}](${href})`
+  }
   // The caption is a nested SerializedEditor — flatten to emphasized text.
   const caption = node.caption as { editorState?: unknown } | undefined
   if (node.showCaption === true && caption?.editorState != null) {

package/src/field/plugins/toolbar-plugin/index.tsx

@@ -18,14 +18,17 @@
 import type * as React from 'react'
 import { Fragment, useCallback, useEffect, useMemo, useState } from 'react'
 
+import { $createCodeNode, $isCodeNode, CodeNode } from '@lexical/code'
+// Lexical 0.51 moved the Prism language tables out of `@lexical/code` and
+// into `@lexical/code-prism`, alongside the tokenizer that populates them.
+// `@lexical/code-shiki` is the other highlighter and exposes
+// `getCodeLanguageOptions()` instead of these maps, so a switch to it would
+// change this dropdown's source of truth, not just its import path.
 import {
-  $createCodeNode,
-  $isCodeNode,
   CODE_LANGUAGE_FRIENDLY_NAME_MAP,
   CODE_LANGUAGE_MAP,
-  CodeNode,
   getLanguageFriendlyName,
-} from '@lexical/code'
+} from '@lexical/code-prism'
 import {
   $isListNode,
   CheckListExtension,

package/src/server.ts

@@ -47,7 +47,10 @@ import type {
   RichTextToTextFn,
 } from '@byline/core'
 
-import { inlineImageVisitor } from './field/extensions/inline-image/populate'
+import {
+  inlineImageLinkVisitor,
+  inlineImageVisitor,
+} from './field/extensions/inline-image/populate'
 import { linkVisitor } from './field/extensions/link/populate'
 import { type LexicalNodeVisitor, runLexicalPopulate } from './field/lexical-populate-shared'
 
@@ -72,7 +75,10 @@ import {
   lexicalToMarkdown,
 } from './field/markdown/lexical-to-markdown'
 
-export { inlineImageVisitor } from './field/extensions/inline-image/populate'
+export {
+  inlineImageLinkVisitor,
+  inlineImageVisitor,
+} from './field/extensions/inline-image/populate'
 export { linkVisitor } from './field/extensions/link/populate'
 export type { EditorConfig, EditorSettings, EditorSettingsOverride } from './field/config/types'
 export type {
@@ -91,7 +97,7 @@ export interface LexicalServerOptions {
   getClient: () => BylineClient<any>
   /**
    * Override the visitor list. Defaults to every visitor the package
-   * ships — currently `[inlineImageVisitor, linkVisitor]`. Useful when a
+   * ships — currently `[inlineImageVisitor, inlineImageLinkVisitor, linkVisitor]`. Useful when a
    * host wants to register additional custom visitors alongside the
    * built-ins, or temporarily disable a built-in:
    *
@@ -112,7 +118,7 @@ export interface LexicalServerOptions {
  * document tree, gated by each leaf field's `populateRelationsOnRead`.
  */
 export function lexicalEditorPopulateServer(options: LexicalServerOptions): RichTextPopulateFn {
-  const visitors = options.visitors ?? [inlineImageVisitor, linkVisitor]
+  const visitors = options.visitors ?? [inlineImageVisitor, inlineImageLinkVisitor, linkVisitor]
   return async (ctx: RichTextPopulateContext): Promise<void> => {
     await runLexicalPopulate({
       readContext: ctx.readContext,
@@ -162,7 +168,7 @@ export function lexicalEditorToTextServer(): RichTextToTextFn {
 }
 
 export function lexicalEditorEmbedServer(options: LexicalServerOptions): RichTextEmbedFn {
-  const visitors = options.visitors ?? [inlineImageVisitor, linkVisitor]
+  const visitors = options.visitors ?? [inlineImageVisitor, inlineImageLinkVisitor, linkVisitor]
   return async (ctx: RichTextEmbedContext): Promise<void> => {
     await runLexicalPopulate({
       readContext: ctx.readContext,

package/src/validate/createEmptyEditorState.ts

@@ -1,9 +1,4 @@
-import type {
-  SerializedEditorState,
-  SerializedLexicalNode,
-  SerializedParagraphNode,
-  SerializedRootNode,
-} from 'lexical'
+import type { SerializedEditorState, SerializedParagraphNode, SerializedRootNode } from 'lexical'
 
 /**
  * createEmptyEditorState
@@ -27,7 +22,7 @@ import type {
         "version": 1
     }
  */
-export function createEmptyEditorState(): SerializedEditorState<SerializedLexicalNode> {
+export function createEmptyEditorState(): SerializedEditorState {
   const emptyParagraphNode: SerializedParagraphNode = {
     children: [],
     direction: null,

package/src/validate/hasText.test.ts

@@ -1,6 +1,5 @@
 import type {
   SerializedEditorState,
-  SerializedLexicalNode,
   SerializedParagraphNode,
   SerializedRootNode,
   SerializedTextNode,
@@ -9,7 +8,7 @@ import { describe, expect, it } from 'vitest'
 
 import { hasText } from './hasText'
 
-type State = SerializedEditorState<SerializedLexicalNode>
+type State = SerializedEditorState
 
 import { createEmptyEditorState } from './createEmptyEditorState'
 

package/src/validate/hasText.ts

@@ -1,13 +1,6 @@
-import type {
-  SerializedEditorState,
-  SerializedLexicalNode,
-  SerializedParagraphNode,
-  SerializedTextNode,
-} from 'lexical'
+import type { SerializedEditorState, SerializedParagraphNode, SerializedTextNode } from 'lexical'
 
-export function hasText(
-  value: SerializedEditorState<SerializedLexicalNode> | null | undefined
-): boolean {
+export function hasText(value: SerializedEditorState | null | undefined): boolean {
   if (value === null || value === undefined) return false
 
   const rootChildren = value.root?.children