@portabletext/block-tools 3.2.1 → 3.3.0

package/src/HtmlDeserializer/flatten-nested-blocks.test.ts

@@ -0,0 +1,140 @@
+import {compileSchema, defineSchema} from '@portabletext/schema'
+import {describe, expect, test} from 'vitest'
+import {createTestKeyGenerator} from '../../test/test-key-generator'
+import {flattenNestedBlocks} from './helpers'
+
+describe(flattenNestedBlocks.name, () => {
+  test('splitting text block', () => {
+    const keyGenerator = createTestKeyGenerator('k')
+    const schema = compileSchema(
+      defineSchema({
+        styles: [{name: 'h1'}],
+        annotations: [{name: 'link'}],
+        blockObjects: [{name: 'image'}],
+      }),
+    )
+    const blockKey = keyGenerator()
+    const fooKey = keyGenerator()
+    const imageKey = keyGenerator()
+    const barKey = keyGenerator()
+    const linkKey = keyGenerator()
+
+    expect(
+      flattenNestedBlocks({schema, keyGenerator}, [
+        {
+          _key: blockKey,
+          _type: 'block',
+          children: [
+            {
+              _key: fooKey,
+              _type: 'span',
+              text: 'foo',
+            },
+            {
+              _key: imageKey,
+              _type: 'image',
+            },
+            {
+              _key: barKey,
+              _type: 'span',
+              text: 'bar',
+              marks: [linkKey],
+            },
+          ],
+          style: 'h1',
+          markDefs: [
+            {
+              _key: linkKey,
+              _type: 'link',
+            },
+          ],
+        },
+      ]),
+    ).toEqual([
+      {
+        _key: blockKey,
+        _type: 'block',
+        children: [{_key: fooKey, _type: 'span', text: 'foo'}],
+        style: 'h1',
+        markDefs: [{_key: linkKey, _type: 'link'}],
+      },
+      {
+        _key: imageKey,
+        _type: 'image',
+      },
+      {
+        _key: blockKey,
+        _type: 'block',
+        children: [
+          {_key: barKey, _type: 'span', text: 'bar', marks: [linkKey]},
+        ],
+        style: 'h1',
+        markDefs: [{_key: linkKey, _type: 'link'}],
+      },
+    ])
+  })
+
+  test('splitting text block with __block', () => {
+    const keyGenerator = createTestKeyGenerator('k')
+    const schema = compileSchema(
+      defineSchema({
+        blockObjects: [{name: 'image'}],
+      }),
+    )
+    const blockKey = keyGenerator()
+    const fooKey = keyGenerator()
+    const imageKey = keyGenerator()
+    const barKey = keyGenerator()
+
+    expect(
+      flattenNestedBlocks({schema, keyGenerator}, [
+        {
+          _key: blockKey,
+          _type: 'block',
+          children: [
+            {
+              _key: fooKey,
+              _type: 'span',
+              text: 'foo',
+              marks: [],
+            },
+            {
+              _type: '__block',
+              block: {
+                _key: imageKey,
+                _type: 'image',
+              },
+            },
+            {
+              _key: barKey,
+              _type: 'span',
+              text: 'bar',
+              marks: [],
+            },
+          ],
+          style: 'normal',
+          markDefs: [],
+        },
+      ]),
+    ).toEqual([
+      {
+        _key: blockKey,
+        _type: 'block',
+        children: [{_key: fooKey, _type: 'span', text: 'foo', marks: []}],
+        style: 'normal',
+        markDefs: [],
+      },
+      {
+        _key: imageKey,
+        _type: 'image',
+      },
+      {
+        _key: blockKey,
+        _type: 'block',
+        children: [{_key: barKey, _type: 'span', text: 'bar', marks: []}],
+        style: 'normal',
+        markDefs: [],
+      },
+    ])
+  })
+})

package/src/HtmlDeserializer/helpers.ts

@@ -3,6 +3,7 @@ import {vercelStegaClean} from '@vercel/stega'
 import {isEqual} from 'lodash'
 import {DEFAULT_BLOCK} from '../constants'
 import type {
+  ArbitraryTypedObject,
   HtmlParser,
   HtmlPreprocessorOptions,
   MinimalBlock,
@@ -12,8 +13,10 @@ import type {
   TypedObject,
 } from '../types'
 import {
+  isSpan,
   isTextBlock,
   type PortableTextObject,
+  type PortableTextSpan,
   type PortableTextTextBlock,
 } from '../types.portable-text'
 import {resolveJsType} from '../util/resolveJsType'
@@ -70,18 +73,121 @@ export function defaultParseHtml(): HtmlParser {
 }
 
 export function flattenNestedBlocks(
-  schema: Schema,
-  blocks: TypedObject[],
+  context: {
+    schema: Schema
+    keyGenerator: () => string
+  },
+  blocks: Array<ArbitraryTypedObject>,
 ): TypedObject[] {
   let depth = 0
   const flattened: TypedObject[] = []
+
   const traverse = (nodes: TypedObject[]) => {
     const toRemove: TypedObject[] = []
     nodes.forEach((node) => {
       if (depth === 0) {
-        flattened.push(node)
+        //Only apply splitting logic if we have block objects defined in the schema
+        if (
+          context.schema.blockObjects.length > 0 &&
+          isTextBlock(context.schema, node)
+        ) {
+          const hasBlockObjects = node.children.some((child) => {
+            const knownBlockObject = context.schema.blockObjects.some(
+              (blockObject) => blockObject.name === child._type,
+            )
+            return knownBlockObject
+          })
+          const hasBlocks = node.children.some(
+            (child) => child._type === '__block',
+          )
+
+          if (hasBlockObjects || hasBlocks) {
+            // Split the block when it contains block objects
+            const splitChildren = node.children.reduce(
+              (slices, child) => {
+                const knownInlineObject = context.schema.inlineObjects.some(
+                  (inlineObject) => inlineObject.name === child._type,
+                )
+                const knownBlockObject = context.schema.blockObjects.some(
+                  (blockObject) => blockObject.name === child._type,
+                )
+
+                const lastSlice = slices.pop()
+
+                if (!isSpan(context.schema, child) && !knownInlineObject) {
+                  if (knownBlockObject) {
+                    return [
+                      ...slices,
+                      ...(lastSlice ? [lastSlice] : []),
+                      {type: 'block object' as const, block: child},
+                    ]
+                  }
+                }
+
+                if (child._type === '__block') {
+                  return [
+                    ...slices,
+                    ...(lastSlice ? [lastSlice] : []),
+                    {
+                      type: 'block object' as const,
+                      block: (child as any).block,
+                    },
+                  ]
+                }
+
+                if (lastSlice) {
+                  if (lastSlice.type === 'children') {
+                    return [
+                      ...slices,
+                      {
+                        type: 'children' as const,
+                        children: [...lastSlice.children, child],
+                      },
+                    ]
+                  }
+                }
+
+                return [
+                  ...slices,
+                  ...(lastSlice ? [lastSlice] : []),
+                  {type: 'children' as const, children: [child]},
+                ]
+              },
+              [] as Array<
+                | {
+                    type: 'children'
+                    children: Array<PortableTextSpan | PortableTextObject>
+                  }
+                | {type: 'block object'; block: PortableTextObject}
+              >,
+            )
+
+            // Process each slice
+            splitChildren.forEach((slice) => {
+              if (slice.type === 'block object') {
+                // Add the block object directly
+                flattened.push(slice.block)
+              } else if (slice.children.length > 0) {
+                // Create a new text block with the remaining children
+                const newBlock = {
+                  ...node,
+                  children: slice.children,
+                }
+                flattened.push(newBlock)
+              }
+            })
+            return
+          } else {
+            // No block objects, add the block as is
+            flattened.push(node)
+          }
+        } else {
+          //Not a text block or no block objects in schema, add directly
+          flattened.push(node)
+        }
       }
-      if (isTextBlock(schema, node)) {
+
+      if (isTextBlock(context.schema, node)) {
         if (depth > 0) {
           toRemove.push(node)
           flattened.push(node)
@@ -187,8 +293,8 @@ export function trimWhitespace(
 
 export function ensureRootIsBlocks(
   schema: Schema,
-  blocks: TypedObject[],
-): TypedObject[] {
+  blocks: Array<ArbitraryTypedObject>,
+): ArbitraryTypedObject[] {
   return blocks.reduce((memo, node, i, original) => {
     if (node._type === 'block') {
       memo.push(node)
@@ -217,7 +323,7 @@ export function ensureRootIsBlocks(
 
     memo.push(block)
     return memo
-  }, [] as TypedObject[])
+  }, [] as ArbitraryTypedObject[])
 }
 
 export function isNodeList(node: unknown): node is NodeList {

package/src/HtmlDeserializer/index.ts

@@ -13,6 +13,7 @@ import {
   type PortableTextBlock,
   type PortableTextObject,
 } from '../types.portable-text'
+import {keyGenerator} from '../util/randomKey'
 import {resolveJsType} from '../util/resolveJsType'
 import {
   defaultParseHtml,
@@ -34,6 +35,7 @@ import {createRules} from './rules'
  *
  */
 export default class HtmlDeserializer {
+  keyGenerator: () => string
   schema: Schema
   rules: DeserializerRule[]
   parseHtml: (html: string) => HTMLElement
@@ -49,8 +51,10 @@ export default class HtmlDeserializer {
     const {rules = [], unstable_whitespaceOnPasteMode = 'preserve'} = options
     const standardRules = createRules(schema, {
       keyGenerator: options.keyGenerator,
+      matchers: options.matchers,
     })
     this.schema = schema
+    this.keyGenerator = options.keyGenerator ?? keyGenerator
     this.rules = [...rules, ...standardRules]
     const parseHtml = options.parseHtml || defaultParseHtml()
     this.parseHtml = (html) => {
@@ -74,8 +78,11 @@ export default class HtmlDeserializer {
     const blocks = trimWhitespace(
       this.schema,
       flattenNestedBlocks(
-        this.schema,
-        ensureRootIsBlocks(this.schema, this.deserializeElements(children)),
+        {schema: this.schema, keyGenerator: this.keyGenerator},
+        ensureRootIsBlocks(
+          this.schema,
+          this.deserializeElements(children) as Array<ArbitraryTypedObject>,
+        ),
       ),
     )
 

package/src/HtmlDeserializer/rules/gdocs.ts

@@ -96,8 +96,16 @@ function getBlockStyle(schema: Schema, el: Node): string {
 export default function createGDocsRules(schema: Schema): DeserializerRule[] {
   return [
     {
-      deserialize(el) {
+      deserialize(el, next) {
         if (isElement(el) && tagName(el) === 'span' && isGoogleDocs(el)) {
+          if (!el.textContent) {
+            if (!el.previousSibling && !el.nextSibling) {
+              el.setAttribute('data-lonely-child', 'true')
+            }
+
+            return next(el.childNodes)
+          }
+
           const span = {
             ...DEFAULT_SPAN,
             marks: [] as string[],

package/src/HtmlDeserializer/rules/html.ts

@@ -10,6 +10,7 @@ import {
   HTML_SPAN_TAGS,
   type PartialBlock,
 } from '../../constants'
+import type {SchemaMatchers} from '../../schema-matchers'
 import type {DeserializerRule} from '../../types'
 import {keyGenerator} from '../../util/randomKey'
 import {isElement, tagName} from '../helpers'
@@ -36,7 +37,7 @@ export function resolveListItem(
 
 export default function createHTMLRules(
   schema: Schema,
-  options: {keyGenerator?: () => string},
+  options: {keyGenerator?: () => string; matchers?: SchemaMatchers},
 ): DeserializerRule[] {
   return [
     whitespaceTextNodeRule,
@@ -265,5 +266,79 @@ export default function createHTMLRules(
         )
       },
     },
+    {
+      deserialize(el) {
+        if (isElement(el) && tagName(el) === 'img') {
+          const src = el.getAttribute('src') ?? undefined
+          const alt = el.getAttribute('alt') ?? undefined
+
+          const props = Object.fromEntries(
+            Array.from(el.attributes).map((attr) => [attr.name, attr.value]),
+          )
+
+          const ancestorOfLonelyChild =
+            el?.parentElement?.parentElement?.getAttribute('data-lonely-child')
+          const ancestorOfListItem = el.closest('li') !== null
+
+          if (ancestorOfLonelyChild && !ancestorOfListItem) {
+            const image = options.matchers?.image?.({
+              context: {
+                schema,
+                keyGenerator: options.keyGenerator ?? keyGenerator,
+              },
+              props: {
+                ...props,
+                ...(src ? {src} : {}),
+                ...(alt ? {alt} : {}),
+              },
+            })
+
+            if (image) {
+              return {
+                _type: '__block',
+                block: image,
+              }
+            }
+          }
+
+          const inlineImage = options.matchers?.inlineImage?.({
+            context: {
+              schema,
+              keyGenerator: options.keyGenerator ?? keyGenerator,
+            },
+            props: {
+              ...props,
+              ...(src ? {src} : {}),
+              ...(alt ? {alt} : {}),
+            },
+          })
+
+          if (inlineImage) {
+            return inlineImage
+          }
+
+          const image = options.matchers?.image?.({
+            context: {
+              schema,
+              keyGenerator: options.keyGenerator ?? keyGenerator,
+            },
+            props: {
+              ...props,
+              ...(src ? {src} : {}),
+              ...(alt ? {alt} : {}),
+            },
+          })
+
+          if (image) {
+            return {
+              _type: '__block',
+              block: image,
+            }
+          }
+        }
+
+        return undefined
+      },
+    },
   ]
 }

package/src/HtmlDeserializer/rules/index.ts

@@ -1,4 +1,5 @@
 import type {Schema} from '@portabletext/schema'
+import type {SchemaMatchers} from '../../schema-matchers'
 import type {DeserializerRule} from '../../types'
 import createGDocsRules from './gdocs'
 import createHTMLRules from './html'
@@ -7,7 +8,7 @@ import createWordRules from './word'
 
 export function createRules(
   schema: Schema,
-  options: {keyGenerator?: () => string},
+  options: {keyGenerator?: () => string; matchers?: SchemaMatchers},
 ): DeserializerRule[] {
   return [
     ...createWordRules(),

package/src/index.ts

@@ -3,7 +3,6 @@ import type {Schema} from '@portabletext/schema'
 import type {ArraySchemaType} from '@sanity/types'
 import HtmlDeserializer from './HtmlDeserializer'
 import type {HtmlDeserializerOptions, TypedObject} from './types'
-import type {PortableTextTextBlock} from './types.portable-text'
 import {normalizeBlock} from './util/normalizeBlock'
 
 /**
@@ -19,7 +18,7 @@ export function htmlToBlocks(
   html: string,
   schemaType: ArraySchemaType | Schema,
   options: HtmlDeserializerOptions = {},
-): (TypedObject | PortableTextTextBlock)[] {
+) {
   const schema = isSanitySchema(schemaType)
     ? sanitySchemaToPortableTextSchema(schemaType)
     : schemaType
@@ -30,6 +29,7 @@ export function htmlToBlocks(
     .map((block) => normalizeBlock(block, {keyGenerator: options.keyGenerator}))
 }
 
+export type {ImageSchemaMatcher, SchemaMatchers} from './schema-matchers'
 export type {ArbitraryTypedObject, DeserializerRule, HtmlParser} from './types'
 export type {
   PortableTextBlock,

package/src/schema-matchers.ts

@@ -0,0 +1,41 @@
+import type {Schema} from '@portabletext/schema'
+import type {ArbitraryTypedObject} from './types'
+
+/**
+ * Use the current `Schema` as well as the potential element props to determine
+ * what Portable Text Object to use to represent the element.
+ */
+type ObjectSchemaMatcher<TProps extends Record<string, unknown>> = ({
+  context,
+  props,
+}: {
+  context: {schema: Schema; keyGenerator: () => string}
+  props: TProps
+}) => ArbitraryTypedObject | undefined
+
+/**
+ * Use the current `Schema` as well as the potential img element props to
+ * determine what Portable Text Object to use to represent the image.
+ * @beta
+ */
+export type ImageSchemaMatcher = ObjectSchemaMatcher<{
+  src?: string
+  alt?: string
+  [key: string]: string | undefined
+}>
+
+/**
+ * @beta
+ */
+export type SchemaMatchers = {
+  /**
+   * Called whenever the HTML parsing encounters an `<img>` element that is
+   * inferred to be a block element.
+   */
+  image?: ImageSchemaMatcher
+  /**
+   * Called whenever the HTML parsing encounters an `<img>` element that is
+   * inferred to be an inline element.
+   */
+  inlineImage?: ImageSchemaMatcher
+}

package/src/types.ts

@@ -1,3 +1,4 @@
+import type {SchemaMatchers} from './schema-matchers'
 import type {PortableTextObject} from './types.portable-text'
 
 /**
@@ -71,6 +72,11 @@ export interface HtmlDeserializerOptions {
   rules?: DeserializerRule[]
   parseHtml?: HtmlParser
   unstable_whitespaceOnPasteMode?: WhiteSpacePasteMode
+  /**
+   * Custom schema matchers to use when deserializing HTML to Portable Text.
+   * @beta
+   */
+  matchers?: SchemaMatchers
 }
 
 export interface HtmlPreprocessorOptions {