@byline/richtext-lexical 4.13.0 → 4.14.0

package/dist/field/extensions/inline-image/populate.js

@@ -1,10 +1,11 @@
-import { deriveImageSizes } from "./utils.js";
+import { deriveImageSizes, getPreferredSize } from "./utils.js";
 const inlineImageVisitor = {
     match (node) {
         if ('inline-image' !== node.type) return null;
         const collectionPath = node.targetCollectionPath;
         const documentId = node.targetDocumentId;
         if (!collectionPath || !documentId) return null;
+        const imageNode = node;
         return {
             node,
             collectionPath,
@@ -21,6 +22,13 @@ const inlineImageVisitor = {
                 if (null != image) next.image = image;
                 if (sizes.length > 0) next.sizes = sizes;
                 node.document = next;
+                const preferred = getPreferredSize(imageNode.position, image);
+                const url = preferred?.url?.trim();
+                if (url) {
+                    imageNode.src = url;
+                    if (preferred?.width != null) imageNode.width = preferred.width;
+                    if (preferred?.height != null) imageNode.height = preferred.height;
+                }
             }
         };
     }

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -72,10 +72,10 @@
     "clsx": "^2.1.1",
     "lexical": "0.49.0",
     "react-error-boundary": "^6.1.3",
-    "@byline/ui": "4.13.0",
-    "@byline/core": "4.13.0",
-    "@byline/admin": "4.13.0",
-    "@byline/client": "4.13.0"
+    "@byline/admin": "4.14.0",
+    "@byline/core": "4.14.0",
+    "@byline/client": "4.14.0",
+    "@byline/ui": "4.14.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -88,7 +88,7 @@
     "@types/node": "^26.2.0",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",
-    "@vitejs/plugin-react": "^6.0.5",
+    "@vitejs/plugin-react": "^6.1.0",
     "lightningcss": "^1.33.0",
     "npm-run-all": "^4.1.5",
     "react": "^19.2.8",
@@ -96,7 +96,7 @@
     "rimraf": "^6.1.3",
     "typescript": "^7.0.2",
     "typescript-plugin-css-modules": "^5.2.0",
-    "vite": "^8.2.1",
+    "vite": "^8.2.2",
     "vitest": "^4.1.11"
   },
   "publishConfig": {

package/src/field/extensions/README.md

@@ -13,7 +13,7 @@ This README is a navigation aid only. The full reference and authoring contract
 | `floating-text-format/` | Standalone extension that contributes the selection-format pop-over to `BylineFloatingUIExtension`. |
 | `link/` | `LinkExtension`, `AutoLinkExtension`, link node + paste handling + `FloatingLinkEditorPlugin` (contributed back via peer dep), and the link populate visitor. |
 | `table/` | `TableExtension` (Byline wrapper over `@lexical/table`), the table modal, and the `TableActionMenuPlugin` (contributed to the floating-UI registry). |
-| `inline-image/` | `InlineImageExtension`, node + decorator + modal, picker-time embed, and the populate visitor for `{ title, altText, image, sizes }`. |
+| `inline-image/` | `InlineImageExtension`, node + decorator + modal, picker-time embed, and the populate visitor for `{ title, altText, image, sizes }` plus the position-aware editor preview (`src` / `width` / `height`). |
 | `layout/` | `LayoutExtension`, columns layout node + modal. |
 | `admonition/` | `AdmonitionExtension`, admonition node + modal. |
 | `auto-embed/` | `AutoEmbedExtension` — paste-to-embed UX shared by the YouTube/Vimeo embedders. |

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

@@ -0,0 +1,237 @@
+/**
+ * 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
+ */
+
+import { createReadContext, type StoredFileValue } from '@byline/core'
+import { describe, expect, it, vi } from 'vitest'
+
+import { type LexicalNodeLike, runLexicalPopulate } from '../../lexical-populate-shared'
+import { inlineImageVisitor } from './populate'
+import type { Position } from './node-types'
+
+/**
+ * A re-keyed media document: every URL below differs from the stale ones
+ * the fixture node carries, so any assertion that the node was refreshed
+ * is also an assertion that it was refreshed from *this* document.
+ * Variant names and dimensions mirror the `media` collection's declared
+ * `sizes` (see `apps/webapp/byline/collections/media/schema.ts`).
+ */
+const currentImage = {
+  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: 'thumbnail',
+      storagePath: 'media/current-thumbnail.avif',
+      storageUrl: 'https://cdn.example.com/media/current-thumbnail.avif',
+      width: 400,
+      height: 400,
+      format: 'avif',
+    },
+    {
+      name: 'card',
+      storagePath: 'media/current-card.avif',
+      storageUrl: 'https://cdn.example.com/media/current-card.avif',
+      width: 600,
+      height: 450,
+      format: 'avif',
+    },
+    {
+      name: 'tablet',
+      storagePath: 'media/current-tablet.avif',
+      storageUrl: 'https://cdn.example.com/media/current-tablet.avif',
+      width: 1024,
+      height: 768,
+      format: 'avif',
+    },
+    {
+      name: 'desktop',
+      storagePath: 'media/current-desktop.avif',
+      storageUrl: 'https://cdn.example.com/media/current-desktop.avif',
+      width: 1600,
+      height: 1200,
+      format: 'avif',
+    },
+  ],
+} satisfies StoredFileValue
+
+/** The same upload with no variants generated — the fallback-to-original path. */
+const variantlessImage = {
+  ...currentImage,
+  variants: undefined,
+} satisfies StoredFileValue
+
+const STALE_SRC = 'https://cdn.example.com/media/stale-card.avif'
+const STALE_WIDTH = 600
+const STALE_HEIGHT = 450
+
+interface InlineImageNodeLike extends LexicalNodeLike {
+  src?: string
+  position?: Position
+  width?: number | string
+  height?: number | string
+}
+
+function makeNode(position: Position): InlineImageNodeLike {
+  return {
+    type: 'inline-image',
+    src: STALE_SRC,
+    position,
+    width: STALE_WIDTH,
+    height: STALE_HEIGHT,
+    targetCollectionPath: 'media',
+    targetDocumentId: 'media-1',
+    document: { title: 'Stale title' },
+    children: [{ type: 'caption', children: [{ type: 'text' }] }],
+  }
+}
+
+function applyTo(node: InlineImageNodeLike, image: StoredFileValue | undefined, title?: string) {
+  inlineImageVisitor.match(node)?.apply({ fields: { image, ...(title ? { title } : {}) } })
+}
+
+describe('inlineImageVisitor', () => {
+  describe('refreshes the editor preview from the resolved document', () => {
+    it('refreshes a stale src and the document envelope', () => {
+      const node = makeNode('left')
+
+      applyTo(node, currentImage, 'Current title')
+
+      expect(node.src).toBe('https://cdn.example.com/media/current-card.avif')
+      expect(node.document).toEqual(
+        expect.objectContaining({ title: 'Current title', image: currentImage })
+      )
+    })
+
+    // The preview is position-aware by construction — the picker writes
+    // `getPreferredSize(position, image)` into src/width/height at insert
+    // time (inline-image-modal.tsx). Refreshing from `image.storageUrl`
+    // instead would swap each variant for the full-size original.
+    it.each([
+      ['left' as Position, 'card', 600, 450],
+      ['right' as Position, 'card', 600, 450],
+      ['wide' as Position, 'desktop', 1600, 1200],
+      ['full' as Position, 'tablet', 1024, 768],
+      ['default' as Position, 'tablet', 1024, 768],
+      [undefined, 'tablet', 1024, 768],
+    ])(
+      'position %s refreshes from the %s variant with its dimensions',
+      (position, variant, width, height) => {
+        const node = makeNode(position)
+
+        applyTo(node, currentImage)
+
+        expect(node.src).toBe(`https://cdn.example.com/media/current-${variant}.avif`)
+        expect(node.width).toBe(width)
+        expect(node.height).toBe(height)
+      }
+    )
+
+    it('never refreshes src to the full-size original when a variant exists', () => {
+      const node = makeNode('left')
+
+      applyTo(node, currentImage)
+
+      expect(node.src).not.toBe(currentImage.storageUrl)
+    })
+
+    it('falls back to the original when the preferred variant is missing', () => {
+      const node = makeNode('left')
+
+      applyTo(node, variantlessImage)
+
+      expect(node.src).toBe(currentImage.storageUrl)
+      expect(node.width).toBe(4000)
+      expect(node.height).toBe(3000)
+    })
+
+    it('uses the original for SVGs, which have no variants', () => {
+      const node = makeNode('left')
+      const svg = {
+        ...variantlessImage,
+        mimeType: 'image/svg+xml',
+        storageUrl: 'https://cdn.example.com/media/current.svg',
+      } satisfies StoredFileValue
+
+      applyTo(node, svg)
+
+      expect(node.src).toBe('https://cdn.example.com/media/current.svg')
+    })
+  })
+
+  describe('never leaves the node emptier than it found it', () => {
+    it('preserves src, width and height when the target cannot be resolved', async () => {
+      const node = makeNode('left')
+      const readDocuments = vi.fn().mockResolvedValue([])
+
+      await runLexicalPopulate({
+        readContext: createReadContext(),
+        readDocuments,
+        visitors: [inlineImageVisitor],
+        values: [{ root: { type: 'root', children: [node] } }],
+      })
+
+      expect(readDocuments).toHaveBeenCalledWith({
+        collectionPath: 'media',
+        documentIds: ['media-1'],
+      })
+      expect(node.src).toBe(STALE_SRC)
+      expect(node.width).toBe(STALE_WIDTH)
+      expect(node.height).toBe(STALE_HEIGHT)
+    })
+
+    it('preserves the preview when the target resolves without an image', () => {
+      const node = makeNode('left')
+
+      applyTo(node, undefined, 'Current title')
+
+      expect(node.src).toBe(STALE_SRC)
+      expect(node.width).toBe(STALE_WIDTH)
+      expect(node.height).toBe(STALE_HEIGHT)
+      expect(node.document).toEqual(expect.objectContaining({ title: 'Current title' }))
+    })
+
+    // Variant-less, so there is no usable variant URL to fall back to and
+    // the original is the only candidate — exactly the case the guard is for.
+    it.each([undefined, '', '   '])(
+      'preserves the preview when the resolved storageUrl is %j',
+      (storageUrl) => {
+        const node = makeNode('left')
+
+        applyTo(node, { ...variantlessImage, storageUrl })
+
+        expect(node.src).toBe(STALE_SRC)
+        expect(node.width).toBe(STALE_WIDTH)
+        expect(node.height).toBe(STALE_HEIGHT)
+      }
+    )
+  })
+
+  it('is idempotent and leaves unrelated node state untouched', () => {
+    const node = makeNode('left')
+    const children = node.children
+    const pending = inlineImageVisitor.match(node)
+
+    pending?.apply({ fields: { image: currentImage } })
+    const afterFirst = { src: node.src, width: node.width, height: node.height }
+    pending?.apply({ fields: { image: currentImage } })
+
+    expect({ src: node.src, width: node.width, height: node.height }).toEqual(afterFirst)
+    expect(node.position).toBe('left')
+    expect(node.children).toBe(children)
+    expect(node.children).toEqual([{ type: 'caption', children: [{ type: 'text' }] }])
+  })
+})

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

@@ -11,16 +11,40 @@
  * framework-agnostic — imported only from the package's `server` entry.
  *
  * Refreshes `node.document` with `{ title, altText, image, sizes }` from
- * the source media document. Does not touch the inline-image node's
- * top-level `src` / `width` / `height` / `altText` — those are Lexical
- * render state and survive untouched, providing a usable fallback when
- * populate hasn't run.
+ * the source media document. Also refreshes the node's top-level `src` /
+ * `width` / `height` — Lexical's admin-editor preview state — from the
+ * resolved image, so a re-keyed or regenerated upload stops serving a
+ * stale URL to the editor.
+ *
+ * That preview is position-aware: `getPreferredSize` picks the same
+ * variant the picker chose at insert time (`left`/`right` → `card`,
+ * `wide` → `desktop`, otherwise `tablet`, with the original as the
+ * fallback), so the refresh must go through it rather than assigning
+ * `image.storageUrl` directly — otherwise every save would swap the
+ * variant for the full-size original and leave the variant's dimensions
+ * describing different bytes. Missing targets, missing images, and
+ * blank URLs leave all three fields untouched: the visitor never leaves
+ * a node emptier than it found it.
  */
 
 import type { StoredFileValue } from '@byline/core'
 
-import { deriveImageSizes } from './utils'
+import { deriveImageSizes, getPreferredSize } from './utils'
 import type { LexicalNodeLike, LexicalNodeVisitor } from '../../lexical-populate-shared'
+import type { Position } from './node-types'
+
+/**
+ * The inline-image node's own fields, spread flat onto the Lexical node
+ * alongside the shared relation envelope. Narrowed here rather than on
+ * `LexicalNodeLike` — each visitor knows its own shape, and the shared
+ * type stays free of per-plugin fields.
+ */
+interface InlineImageNodeLike extends LexicalNodeLike {
+  src?: string
+  position?: Position
+  width?: number | string
+  height?: number | string
+}
 
 export const inlineImageVisitor: LexicalNodeVisitor = {
   match(node: LexicalNodeLike) {
@@ -28,6 +52,7 @@ export const inlineImageVisitor: LexicalNodeVisitor = {
     const collectionPath = node.targetCollectionPath
     const documentId = node.targetDocumentId
     if (!collectionPath || !documentId) return null
+    const imageNode = node as InlineImageNodeLike
     return {
       node,
       collectionPath,
@@ -42,6 +67,13 @@ export const inlineImageVisitor: LexicalNodeVisitor = {
         if (image != null) next.image = image
         if (sizes.length > 0) next.sizes = sizes
         node.document = next
+        const preferred = getPreferredSize(imageNode.position, image)
+        const url = preferred?.url?.trim()
+        if (url) {
+          imageNode.src = url
+          if (preferred?.width != null) imageNode.width = preferred.width
+          if (preferred?.height != null) imageNode.height = preferred.height
+        }
       },
     }
   },