@byline/richtext-lexical 6.4.0 → 6.5.0

package/src/field/extensions/inline-image/populate-link.test.node.ts

@@ -0,0 +1,320 @@
+/**
+ * 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
+ */
+
+/**
+ * Tests for `inlineImageLinkVisitor` — the second relation on an
+ * inline-image node. The flat relation envelope on the node addresses the
+ * *media* document; `node.link` optionally addresses a *click-through
+ * target*, which is an entirely different document in an entirely
+ * different collection.
+ *
+ * The two relations hydrate independently through the same
+ * `runLexicalPopulate` pass, because the driver runs every visitor against
+ * every node and enqueues each match separately. The final suite here
+ * pins that co-existence — it is the whole reason a second visitor is the
+ * right shape rather than widening `inlineImageVisitor`.
+ */
+
+import {
+  type BylineLogger,
+  type CollectionDefinition,
+  createReadContext,
+  defineServerConfig,
+  type StoredFileValue,
+} from '@byline/core'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { type LexicalNodeLike, runLexicalPopulate } from '../../lexical-populate-shared'
+import { inlineImageLinkVisitor, inlineImageVisitor } from './populate'
+
+// ---------------------------------------------------------------------------
+// Test harness — mirrors `extensions/link/populate.test.node.ts`
+// ---------------------------------------------------------------------------
+
+function makeLogger(): BylineLogger {
+  return {
+    log: vi.fn(),
+    fatal: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+    trace: vi.fn(),
+    silent: vi.fn(),
+  }
+}
+
+function registerCollection(definition: Partial<CollectionDefinition> & { path: string }): void {
+  defineServerConfig({
+    collections: [
+      {
+        labels: { singular: 'Page', plural: 'Pages' },
+        fields: [{ name: 'title', type: 'text', label: 'Title' }],
+        useAsTitle: 'title',
+        ...definition,
+      } as CollectionDefinition,
+    ],
+  } as unknown as Parameters<typeof defineServerConfig>[0])
+}
+
+function clearConfig(): void {
+  ;(globalThis as any)[Symbol.for('__byline_server_config__')] = null
+  ;(globalThis as any)[Symbol.for('__byline_client_config__')] = null
+}
+
+function installLogger(logger: BylineLogger): void {
+  ;(globalThis as any)[Symbol.for('__byline_logger__')] = logger
+}
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+interface InlineImageNodeLike extends LexicalNodeLike {
+  src?: string
+  position?: string
+  link?: Record<string, any>
+}
+
+/**
+ * An inline-image node carrying BOTH relations: the flat envelope points
+ * at `media/media-1`, `link` points at `pages/doc-1`.
+ */
+function makeLinkedImageNode(link?: Record<string, any>): InlineImageNodeLike {
+  return {
+    type: 'inline-image',
+    src: 'https://cdn.example.com/media/stale-card.avif',
+    position: 'left',
+    targetCollectionPath: 'media',
+    targetDocumentId: 'media-1',
+    document: { title: 'Stale media title' },
+    link,
+  }
+}
+
+const internalLink = {
+  linkType: 'internal',
+  newTab: false,
+  targetDocumentId: 'doc-1',
+  targetCollectionId: 'coll-1',
+  targetCollectionPath: 'pages',
+  document: { title: 'Stale link title', path: '/pages/stale' },
+}
+
+const linkTarget = {
+  id: 'doc-1',
+  path: 'about',
+  status: 'published',
+  fields: { title: 'About Us' },
+}
+
+const mediaImage = {
+  fileId: 'file-1',
+  filename: 'current.jpg',
+  originalFilename: 'current.jpg',
+  mimeType: 'image/jpeg',
+  fileSize: 123,
+  storageProvider: 's3',
+  storagePath: 'media/current.jpg',
+  storageUrl: 'https://cdn.example.com/media/current.jpg',
+  imageWidth: 4000,
+  imageHeight: 3000,
+  processingStatus: 'complete',
+  variants: [
+    {
+      name: 'card',
+      storagePath: 'media/current-card.avif',
+      storageUrl: 'https://cdn.example.com/media/current-card.avif',
+      width: 600,
+      height: 450,
+      format: 'avif',
+    },
+  ],
+} satisfies StoredFileValue
+
+// ---------------------------------------------------------------------------
+// Suite
+// ---------------------------------------------------------------------------
+
+describe('inlineImageLinkVisitor', () => {
+  beforeEach(() => {
+    installLogger(makeLogger())
+    clearConfig()
+  })
+
+  afterEach(() => {
+    clearConfig()
+  })
+
+  describe('match', () => {
+    it('returns null for nodes that are not inline images', () => {
+      expect(inlineImageLinkVisitor.match({ type: 'paragraph' })).toBeNull()
+    })
+
+    it('returns null for an inline image with no link', () => {
+      expect(inlineImageLinkVisitor.match(makeLinkedImageNode(undefined))).toBeNull()
+    })
+
+    it('returns null for a custom-URL link, which carries no relation', () => {
+      const node = makeLinkedImageNode({
+        linkType: 'custom',
+        url: 'https://example.com',
+        newTab: true,
+      })
+      expect(inlineImageLinkVisitor.match(node)).toBeNull()
+    })
+
+    it('returns null when the link relation is missing its document id', () => {
+      const node = makeLinkedImageNode({ linkType: 'internal', targetCollectionPath: 'pages' })
+      expect(inlineImageLinkVisitor.match(node)).toBeNull()
+    })
+
+    // The load-bearing assertion: the pending hydration addresses the LINK
+    // target, not the media document the flat envelope points at.
+    it('addresses the link target rather than the media document', () => {
+      registerCollection({ path: 'pages' })
+      const pending = inlineImageLinkVisitor.match(makeLinkedImageNode({ ...internalLink }))
+
+      expect(pending?.collectionPath).toBe('pages')
+      expect(pending?.documentId).toBe('doc-1')
+    })
+  })
+
+  describe('apply', () => {
+    it('refreshes the link title and path from the resolved target', () => {
+      registerCollection({ path: 'pages', useAsTitle: 'title' })
+      const node = makeLinkedImageNode({ ...internalLink })
+
+      inlineImageLinkVisitor.match(node)?.apply(linkTarget)
+
+      expect(node.link?.document).toEqual({ title: 'About Us', path: '/pages/about' })
+    })
+
+    it('uses buildDocumentPath when the collection defines one', () => {
+      registerCollection({
+        path: 'pages',
+        useAsTitle: 'title',
+        buildDocumentPath: (doc) => `/custom/${doc.path}`,
+      })
+      const node = makeLinkedImageNode({ ...internalLink })
+
+      inlineImageLinkVisitor.match(node)?.apply(linkTarget)
+
+      expect(node.link?.document?.path).toBe('/custom/about')
+    })
+
+    it('leaves the media relation completely untouched', () => {
+      registerCollection({ path: 'pages', useAsTitle: 'title' })
+      const node = makeLinkedImageNode({ ...internalLink })
+
+      inlineImageLinkVisitor.match(node)?.apply(linkTarget)
+
+      expect(node.targetCollectionPath).toBe('media')
+      expect(node.targetDocumentId).toBe('media-1')
+      expect(node.document).toEqual({ title: 'Stale media title' })
+    })
+
+    it('clears a stale _resolved flag once the target resolves again', () => {
+      registerCollection({ path: 'pages', useAsTitle: 'title' })
+      const node = makeLinkedImageNode({
+        ...internalLink,
+        document: { _resolved: false },
+      })
+
+      inlineImageLinkVisitor.match(node)?.apply(linkTarget)
+
+      expect(node.link?.document).not.toHaveProperty('_resolved')
+    })
+  })
+
+  describe('applyMissing', () => {
+    it('marks the link unresolved and drops the stale title and path', () => {
+      registerCollection({ path: 'pages', useAsTitle: 'title' })
+      const node = makeLinkedImageNode({ ...internalLink })
+
+      inlineImageLinkVisitor.match(node)?.applyMissing?.()
+
+      expect(node.link?.document).toEqual({ _resolved: false })
+    })
+
+    // The image must keep rendering even when its click target is gone —
+    // only the anchor is dropped, by the renderer, off `_resolved: false`.
+    it('leaves the image itself renderable', () => {
+      registerCollection({ path: 'pages', useAsTitle: 'title' })
+      const node = makeLinkedImageNode({ ...internalLink })
+
+      inlineImageLinkVisitor.match(node)?.applyMissing?.()
+
+      expect(node.src).toBe('https://cdn.example.com/media/stale-card.avif')
+      expect(node.targetDocumentId).toBe('media-1')
+    })
+  })
+
+  describe('alongside inlineImageVisitor in one populate pass', () => {
+    it('hydrates both relations from their own collections', async () => {
+      registerCollection({ path: 'pages', useAsTitle: 'title' })
+      const node = makeLinkedImageNode({ ...internalLink })
+
+      const readDocuments = vi.fn(async ({ collectionPath }: { collectionPath: string }) =>
+        collectionPath === 'media'
+          ? [
+              {
+                document_id: 'media-1',
+                path: 'shot',
+                status: 'published',
+                fields: { image: mediaImage, title: 'Current media title' },
+              },
+            ]
+          : [
+              {
+                document_id: 'doc-1',
+                path: 'about',
+                status: 'published',
+                fields: { title: 'About Us' },
+              },
+            ]
+      )
+
+      await runLexicalPopulate({
+        readContext: createReadContext(),
+        readDocuments,
+        visitors: [inlineImageVisitor, inlineImageLinkVisitor],
+        values: [{ root: { type: 'root', children: [node] } }],
+      })
+
+      // Media relation refreshed from `media`…
+      expect(node.src).toBe('https://cdn.example.com/media/current-card.avif')
+      expect(node.document).toEqual(
+        expect.objectContaining({ title: 'Current media title', image: mediaImage })
+      )
+      // …and the link relation refreshed from `pages`, in the same pass.
+      expect(node.link?.document).toEqual({ title: 'About Us', path: '/pages/about' })
+    })
+
+    it('batches one read per collection', async () => {
+      registerCollection({ path: 'pages', useAsTitle: 'title' })
+      const node = makeLinkedImageNode({ ...internalLink })
+      const readDocuments = vi.fn().mockResolvedValue([])
+
+      await runLexicalPopulate({
+        readContext: createReadContext(),
+        readDocuments,
+        visitors: [inlineImageVisitor, inlineImageLinkVisitor],
+        values: [{ root: { type: 'root', children: [node] } }],
+      })
+
+      expect(readDocuments).toHaveBeenCalledTimes(2)
+      expect(readDocuments.mock.calls.map(([arg]) => arg)).toEqual(
+        expect.arrayContaining([
+          { collectionPath: 'media', documentIds: ['media-1'] },
+          { collectionPath: 'pages', documentIds: ['doc-1'] },
+        ])
+      )
+    })
+  })
+})

package/src/field/extensions/inline-image/populate.ts

@@ -29,8 +29,10 @@
 
 import type { StoredFileValue } from '@byline/core'
 
+import { createInternalLinkHydration } from '../link/populate'
 import { deriveImageSizes, getPreferredSize } from './utils'
 import type { LexicalNodeLike, LexicalNodeVisitor } from '../../lexical-populate-shared'
+import type { LinkAttributes } from '../link'
 import type { Position } from './node-types'
 
 /**
@@ -44,6 +46,8 @@ interface InlineImageNodeLike extends LexicalNodeLike {
   position?: Position
   width?: number | string
   height?: number | string
+  /** Optional click-through target — a SECOND relation, see below. */
+  link?: LinkAttributes
 }
 
 export const inlineImageVisitor: LexicalNodeVisitor = {
@@ -78,3 +82,43 @@ export const inlineImageVisitor: LexicalNodeVisitor = {
     }
   },
 }
+
+/**
+ * Second visitor for the same node type. An inline image carries **two**
+ * independent relations:
+ *
+ *   - the flat `DocumentRelation` envelope on the node — the *media*
+ *     document the image comes from, refreshed by `inlineImageVisitor`
+ *     above;
+ *   - `node.link` — an optional *click-through target*, which is an
+ *     unrelated document in an unrelated collection.
+ *
+ * They cannot share one visitor: `PendingHydration` addresses exactly one
+ * `{ collectionPath, documentId }` pair. `runLexicalPopulate` runs every
+ * visitor against every node and enqueues each match separately, so
+ * registering this alongside `inlineImageVisitor` hydrates both relations
+ * in the same batched pass with no change to the driver contract.
+ *
+ * Only `linkType: 'internal'` links carry a relation; custom-URL links are
+ * a literal href and are skipped. Resolution branches — found, hook threw,
+ * target missing — are the internal-link rules shared with `linkVisitor`
+ * (see `../link/populate.ts`).
+ */
+export const inlineImageLinkVisitor: LexicalNodeVisitor = {
+  match(node: LexicalNodeLike) {
+    if (node.type !== 'inline-image') return null
+    const link = (node as InlineImageNodeLike).link
+    if (link == null) return null
+    if (link.linkType !== 'internal') return null
+    const collectionPath = link.targetCollectionPath
+    const documentId = link.targetDocumentId
+    if (!collectionPath || !documentId) return null
+
+    return {
+      node,
+      collectionPath,
+      documentId,
+      ...createInternalLinkHydration(link, collectionPath, documentId),
+    }
+  },
+}

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

@@ -7,6 +7,7 @@
  */
 
 import type { DocumentRelation } from '../../nodes/document-relation'
+import type { LinkAttributes } from '../link'
 import type { Position } from './node-types'
 
 /**
@@ -25,6 +26,12 @@ export interface InlineImageData {
   width?: number | string
   height?: number | string
   showCaption?: boolean
+  /**
+   * Optional click-through target. `undefined` means "no link" — and the
+   * modal always emits the key, so the node's `update()` can tell
+   * "unchanged" from "cleared".
+   */
+  link?: LinkAttributes
 }
 
 export interface InlineImageModalProps {

package/src/field/extensions/link/link-href.test.node.ts

@@ -0,0 +1,78 @@
+/**
+ * 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
+ */
+
+/**
+ * The internal-link fallback chain, as a pure function.
+ *
+ * Returning `null` is meaningful: it is the signal that no usable target
+ * exists, and every caller reacts by degrading rather than by emitting a
+ * broken href — the editor hides its cmd-click affordance, the markdown
+ * serializer drops the wrapper, the public renderer strips the anchor.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { resolveLinkHref } from './link-href'
+import type { LinkAttributes } from '.'
+
+const internal = (document?: Record<string, unknown>): LinkAttributes => ({
+  linkType: 'internal',
+  targetDocumentId: 'doc-1',
+  targetCollectionId: 'coll-1',
+  targetCollectionPath: 'pages',
+  document: document as any,
+})
+
+describe('resolveLinkHref', () => {
+  it('returns null for an absent link', () => {
+    expect(resolveLinkHref(undefined)).toBeNull()
+  })
+
+  describe('custom targets', () => {
+    it.each([
+      'https://example.com/report',
+      '/docs/getting-started',
+      'mailto:hello@example.com',
+      '#section',
+    ])('passes %s through unchanged', (url) => {
+      expect(resolveLinkHref({ linkType: 'custom', url })).toBe(url)
+    })
+
+    it.each([undefined, ''])('returns null for a %j url', (url) => {
+      expect(resolveLinkHref({ linkType: 'custom', url })).toBeNull()
+    })
+  })
+
+  describe('internal targets', () => {
+    it('uses a canonical path written by the embed walker', () => {
+      expect(resolveLinkHref(internal({ path: '/about-us' }))).toBe('/about-us')
+    })
+
+    it('composes a bare slug against the target collection', () => {
+      expect(resolveLinkHref(internal({ path: 'about' }))).toBe('/pages/about')
+    })
+
+    // The walker sets this when the target was deleted. The image must stay
+    // on the page; only its click target goes away.
+    it('returns null when the walker marked the target unresolved', () => {
+      expect(resolveLinkHref(internal({ path: '/about-us', _resolved: false }))).toBeNull()
+    })
+
+    it.each([undefined, {}, { path: '' }])(
+      'returns null when there is no path to build from (%j)',
+      (document) => {
+        expect(resolveLinkHref(internal(document))).toBeNull()
+      }
+    )
+
+    it('returns null for a bare slug with no collection path to compose against', () => {
+      const link = { ...internal({ path: 'about' }), targetCollectionPath: '' } as LinkAttributes
+      expect(resolveLinkHref(link)).toBeNull()
+    })
+  })
+})

package/src/field/extensions/link/link-href.ts

@@ -0,0 +1,52 @@
+/**
+ * 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
+ */
+
+/**
+ * Resolve a `LinkAttributes` to a renderable href, or `null` when no
+ * usable target exists.
+ *
+ * React-free and DOM-free, so the editor, the markdown serializer and any
+ * host renderer can share one definition of the internal-link fallback
+ * chain (documented in `docs/04-collections/07-rich-text.md`):
+ *
+ *   1. `document._resolved === false` — the server-side walker could not
+ *      find the target on its last pass. Return null; callers degrade.
+ *   2. `document.path` starts with `/` — canonical, written by the walker
+ *      via `buildDocumentPath`. Use as-is.
+ *   3. `document.path` is a bare slug — compose `/${collectionPath}/${path}`.
+ *      Covers legacy nodes and picker-time writes not yet walked.
+ *   4. Anything else — null.
+ *
+ * `null` is never "render an empty href". It means the link is not
+ * renderable, and each caller has its own way of degrading: the editor
+ * withholds its cmd-click affordance, the markdown serializer emits the
+ * image without a wrapper, the public renderer drops the anchor.
+ */
+
+import type { LinkAttributes } from '.'
+
+export function resolveLinkHref(link: LinkAttributes | undefined | null): string | null {
+  if (link == null) return null
+
+  if (link.linkType === 'internal') {
+    // Step 1 — walker explicitly marked the target as missing.
+    if (link.document?._resolved === false) return null
+
+    const path = link.document?.path
+    if (typeof path !== 'string' || path.length === 0) return null
+    // Step 2 — canonical path.
+    if (path.startsWith('/')) return path
+    // Step 3 — bare slug, generic compose fallback.
+    if (link.targetCollectionPath) return `/${link.targetCollectionPath}/${path}`
+    // Step 4 — nothing to compose against.
+    return null
+  }
+
+  const url = link.url
+  return typeof url === 'string' && url.length > 0 ? url : null
+}