@portabletext/block-tools 0.0.0

package/src/index.ts

@@ -0,0 +1,52 @@
+import type {ArraySchemaType, PortableTextTextBlock} from '@sanity/types'
+import HtmlDeserializer from './HtmlDeserializer'
+import type {
+  BlockContentFeatures,
+  HtmlDeserializerOptions,
+  TypedObject,
+} from './types'
+import blockContentTypeFeatures from './util/blockContentTypeFeatures'
+import {normalizeBlock} from './util/normalizeBlock'
+
+/**
+ * Convert HTML to blocks respecting the block content type's schema
+ *
+ * @param html - The HTML to convert to blocks
+ * @param blockContentType - A compiled version of the schema type for the block content
+ * @param options - Options for deserializing HTML to blocks
+ * @returns Array of blocks
+ * @public
+ */
+export function htmlToBlocks(
+  html: string,
+  blockContentType: ArraySchemaType,
+  options: HtmlDeserializerOptions = {},
+): (TypedObject | PortableTextTextBlock)[] {
+  const deserializer = new HtmlDeserializer(blockContentType, options)
+  return deserializer.deserialize(html).map((block) => normalizeBlock(block))
+}
+
+/**
+ * Normalize and extract features of an schema type containing a block type
+ *
+ * @param blockContentType - Schema type for the block type
+ * @returns Returns the featureset of a compiled block content type.
+ * @public
+ */
+export function getBlockContentFeatures(
+  blockContentType: ArraySchemaType,
+): BlockContentFeatures {
+  return blockContentTypeFeatures(blockContentType)
+}
+
+export {normalizeBlock}
+export {randomKey} from './util/randomKey'
+export type {BlockContentFeatures, HtmlDeserializerOptions, TypedObject}
+export type {
+  ArbitraryTypedObject,
+  BlockEditorSchemaProps,
+  DeserializerRule,
+  HtmlParser,
+  ResolvedAnnotationType,
+} from './types'
+export type {BlockNormalizationOptions} from './util/normalizeBlock'

package/src/types.ts

@@ -0,0 +1,139 @@
+import type {
+  ArraySchemaType,
+  I18nTitledListValue,
+  ObjectSchemaType,
+  PortableTextObject,
+  SpanSchemaType,
+  TitledListValue,
+} from '@sanity/types'
+import type {ComponentType} from 'react'
+
+/**
+ * @public
+ */
+export interface BlockContentFeatures {
+  styles: TitledListValue<string>[]
+  decorators: TitledListValue<string>[]
+  annotations: ResolvedAnnotationType[]
+  lists: I18nTitledListValue<string>[]
+  types: {
+    block: ArraySchemaType
+    span: SpanSchemaType
+    inlineObjects: ObjectSchemaType[]
+    blockObjects: ObjectSchemaType[]
+  }
+}
+
+/**
+ * @beta
+ */
+export interface BlockEditorSchemaProps {
+  icon?: string | ComponentType
+  render?: ComponentType
+}
+
+/**
+ * @public
+ */
+export interface ResolvedAnnotationType {
+  blockEditor?: BlockEditorSchemaProps
+  title: string | undefined
+  value: string
+  type: ObjectSchemaType
+  icon: ComponentType | undefined
+}
+
+/**
+ * @public
+ */
+export interface TypedObject {
+  _type: string
+  _key?: string
+}
+
+/**
+ * @public
+ */
+export interface ArbitraryTypedObject extends TypedObject {
+  [key: string]: unknown
+}
+
+export interface MinimalSpan {
+  _type: 'span'
+  _key?: string
+  text: string
+  marks?: string[]
+}
+
+export interface MinimalBlock extends TypedObject {
+  _type: 'block'
+  children: TypedObject[]
+  markDefs?: TypedObject[]
+  style?: string
+  level?: number
+  listItem?: string
+}
+
+export interface PlaceholderDecorator {
+  _type: '__decorator'
+  name: string
+  children: TypedObject[]
+}
+
+export interface PlaceholderAnnotation {
+  _type: '__annotation'
+  markDef: PortableTextObject
+  children: TypedObject[]
+}
+
+/**
+ * @public
+ */
+export type HtmlParser = (html: string) => Document
+
+/**
+ * @public
+ */
+export type WhiteSpacePasteMode = 'preserve' | 'remove' | 'normalize'
+
+/**
+ * @public
+ */
+export interface HtmlDeserializerOptions {
+  rules?: DeserializerRule[]
+  parseHtml?: HtmlParser
+  unstable_whitespaceOnPasteMode?: WhiteSpacePasteMode
+}
+
+/**
+ * @public
+ */
+export interface HtmlPreprocessorOptions {
+  unstable_whitespaceOnPasteMode?: WhiteSpacePasteMode
+}
+
+/**
+ * @public
+ */
+export interface DeserializerRule {
+  deserialize: (
+    el: Node,
+    next: (
+      elements: Node | Node[] | NodeList,
+    ) => TypedObject | TypedObject[] | undefined,
+    createBlock: (props: ArbitraryTypedObject) => {
+      _type: string
+      block: ArbitraryTypedObject
+    },
+  ) => TypedObject | TypedObject[] | undefined
+}
+
+/**
+ * @public
+ */
+export interface BlockEnabledFeatures {
+  enabledBlockStyles: string[]
+  enabledSpanDecorators: string[]
+  enabledListTypes: string[]
+  enabledBlockAnnotations: string[]
+}

package/src/util/blockContentTypeFeatures.ts

@@ -0,0 +1,141 @@
+import {
+  isBlockChildrenObjectField,
+  isBlockListObjectField,
+  isBlockSchemaType,
+  isBlockStyleObjectField,
+  isObjectSchemaType,
+  isTitledListValue,
+  type ArraySchemaType,
+  type BlockSchemaType,
+  type EnumListProps,
+  type I18nTitledListValue,
+  type ObjectSchemaType,
+  type SpanSchemaType,
+  type TitledListValue,
+} from '@sanity/types'
+import type {BlockContentFeatures, ResolvedAnnotationType} from '../types'
+import {findBlockType} from './findBlockType'
+
+// Helper method for describing a blockContentType's feature set
+export default function blockContentFeatures(
+  blockContentType: ArraySchemaType,
+): BlockContentFeatures {
+  if (!blockContentType) {
+    throw new Error("Parameter 'blockContentType' required")
+  }
+
+  const blockType = blockContentType.of.find(findBlockType)
+  if (!isBlockSchemaType(blockType)) {
+    throw new Error("'block' type is not defined in this schema (required).")
+  }
+
+  const ofType = blockType.fields.find(isBlockChildrenObjectField)?.type?.of
+  if (!ofType) {
+    throw new Error('No `of` declaration found for blocks `children` field')
+  }
+
+  const spanType = ofType.find(
+    (member): member is SpanSchemaType => member.name === 'span',
+  )
+  if (!spanType) {
+    throw new Error(
+      'No `span` type found in `block` schema type `children` definition',
+    )
+  }
+
+  const inlineObjectTypes = ofType.filter(
+    (inlineType): inlineType is ObjectSchemaType =>
+      inlineType.name !== 'span' && isObjectSchemaType(inlineType),
+  )
+
+  const blockObjectTypes = blockContentType.of.filter(
+    (memberType): memberType is ObjectSchemaType =>
+      memberType.name !== blockType.name && isObjectSchemaType(memberType),
+  )
+
+  return {
+    styles: resolveEnabledStyles(blockType),
+    decorators: resolveEnabledDecorators(spanType),
+    annotations: resolveEnabledAnnotationTypes(spanType),
+    lists: resolveEnabledListItems(blockType),
+    types: {
+      block: blockContentType,
+      span: spanType,
+      inlineObjects: inlineObjectTypes,
+      blockObjects: blockObjectTypes,
+    },
+  }
+}
+
+function resolveEnabledStyles(
+  blockType: BlockSchemaType,
+): TitledListValue<string>[] {
+  const styleField = blockType.fields.find(isBlockStyleObjectField)
+  if (!styleField) {
+    throw new Error(
+      "A field with name 'style' is not defined in the block type (required).",
+    )
+  }
+
+  const textStyles = getTitledListValuesFromEnumListOptions(
+    styleField.type.options,
+  )
+  if (textStyles.length === 0) {
+    throw new Error(
+      'The style fields need at least one style ' +
+        "defined. I.e: {title: 'Normal', value: 'normal'}.",
+    )
+  }
+
+  return textStyles
+}
+
+function resolveEnabledAnnotationTypes(
+  spanType: SpanSchemaType,
+): ResolvedAnnotationType[] {
+  return spanType.annotations.map((annotation) => ({
+    title: annotation.title,
+    type: annotation,
+    value: annotation.name,
+    icon: annotation.icon,
+  }))
+}
+
+function resolveEnabledDecorators(
+  spanType: SpanSchemaType,
+): TitledListValue<string>[] {
+  return spanType.decorators
+}
+
+function resolveEnabledListItems(
+  blockType: BlockSchemaType,
+): I18nTitledListValue<string>[] {
+  const listField = blockType.fields.find(isBlockListObjectField)
+  if (!listField) {
+    throw new Error(
+      "A field with name 'list' is not defined in the block type (required).",
+    )
+  }
+
+  const listItems = getTitledListValuesFromEnumListOptions(
+    listField.type.options,
+  )
+  if (!listItems) {
+    throw new Error('The list field need at least to be an empty array')
+  }
+
+  return listItems
+}
+
+function getTitledListValuesFromEnumListOptions(
+  options: EnumListProps<string> | undefined,
+): I18nTitledListValue<string>[] {
+  const list = options ? options.list : undefined
+  if (!Array.isArray(list)) {
+    return []
+  }
+
+  return list.map((item) =>
+    isTitledListValue(item) ? item : {title: item, value: item},
+  )
+}

package/src/util/findBlockType.ts

@@ -0,0 +1,13 @@
+import type {BlockSchemaType, SchemaType} from '@sanity/types'
+
+export function findBlockType(type: SchemaType): type is BlockSchemaType {
+  if (type.type) {
+    return findBlockType(type.type)
+  }
+
+  if (type.name === 'block') {
+    return true
+  }
+
+  return false
+}

package/src/util/normalizeBlock.ts

@@ -0,0 +1,142 @@
+import {
+  isPortableTextSpan,
+  type PortableTextSpan,
+  type PortableTextTextBlock,
+} from '@sanity/types'
+import {isEqual} from 'lodash'
+import type {TypedObject} from '../types'
+import {randomKey} from './randomKey'
+
+/**
+ * Block normalization options
+ *
+ * @public
+ */
+export interface BlockNormalizationOptions {
+  /**
+   * Decorator names that are allowed within portable text blocks, eg `em`, `strong`
+   */
+  allowedDecorators?: string[]
+
+  /**
+   * Name of the portable text block type, if not `block`
+   */
+  blockTypeName?: string
+}
+
+/**
+ * Normalizes a block by ensuring it has a `_key` property. If the block is a
+ * portable text block, additional normalization is applied:
+ *
+ * - Ensures it has `children` and `markDefs` properties
+ * - Ensures it has at least one child (adds an empty span if empty)
+ * - Joins sibling spans that has the same marks
+ * - Removes decorators that are not allowed according to the schema
+ * - Removes marks that have no annotation definition
+ *
+ * @param node - The block to normalize
+ * @param options - Options for normalization process. See {@link BlockNormalizationOptions}
+ * @returns Normalized block
+ * @public
+ */
+export function normalizeBlock(
+  node: TypedObject,
+  options: BlockNormalizationOptions = {},
+): Omit<
+  TypedObject | PortableTextTextBlock<TypedObject | PortableTextSpan>,
+  '_key'
+> & {
+  _key: string
+} {
+  if (node._type !== (options.blockTypeName || 'block')) {
+    return '_key' in node
+      ? (node as TypedObject & {_key: string})
+      : {...node, _key: randomKey(12)}
+  }
+
+  const block: Omit<
+    PortableTextTextBlock<TypedObject | PortableTextSpan>,
+    'style'
+  > = {
+    _key: randomKey(12),
+    children: [],
+    markDefs: [],
+    ...node,
+  }
+
+  const lastChild = block.children[block.children.length - 1]
+  if (!lastChild) {
+    // A block must at least have an empty span type child
+    block.children = [
+      {
+        _type: 'span',
+        _key: `${block._key}${0}`,
+        text: '',
+        marks: [],
+      },
+    ]
+    return block
+  }
+
+  const usedMarkDefs: string[] = []
+  const allowedDecorators =
+    options.allowedDecorators && Array.isArray(options.allowedDecorators)
+      ? options.allowedDecorators
+      : false
+
+  block.children = block.children
+    .reduce(
+      (acc, child) => {
+        const previousChild = acc[acc.length - 1]
+        if (
+          previousChild &&
+          isPortableTextSpan(child) &&
+          isPortableTextSpan(previousChild) &&
+          isEqual(previousChild.marks, child.marks)
+        ) {
+          if (
+            lastChild &&
+            lastChild === child &&
+            child.text === '' &&
+            block.children.length > 1
+          ) {
+            return acc
+          }
+
+          previousChild.text += child.text
+          return acc
+        }
+        acc.push(child)
+        return acc
+      },
+      [] as (TypedObject | PortableTextSpan)[],
+    )
+    .map((child, index) => {
+      if (!child) {
+        throw new Error('missing child')
+      }
+
+      child._key = `${block._key}${index}`
+      if (isPortableTextSpan(child)) {
+        if (!child.marks) {
+          child.marks = []
+        } else if (allowedDecorators) {
+          child.marks = child.marks.filter((mark) => {
+            const isAllowed = allowedDecorators.includes(mark)
+            const isUsed = block.markDefs?.some((def) => def._key === mark)
+            return isAllowed || isUsed
+          })
+        }
+
+        usedMarkDefs.push(...child.marks)
+      }
+
+      return child
+    })
+
+  // Remove leftover (unused) markDefs
+  block.markDefs = (block.markDefs || []).filter((markDef) =>
+    usedMarkDefs.includes(markDef._key),
+  )
+  return block
+}

package/src/util/randomKey.ts

@@ -0,0 +1,26 @@
+import getRandomValues from 'get-random-values-esm'
+
+// WHATWG crypto RNG - https://w3c.github.io/webcrypto/Overview.html
+function whatwgRNG(length = 16) {
+  const rnds8 = new Uint8Array(length)
+  getRandomValues(rnds8)
+  return rnds8
+}
+
+const byteToHex: string[] = []
+for (let i = 0; i < 256; ++i) {
+  byteToHex[i] = (i + 0x100).toString(16).slice(1)
+}
+
+/**
+ * Generate a random key of the given length
+ *
+ * @param length - Length of string to generate
+ * @returns A string of the given length
+ * @public
+ */
+export function randomKey(length: number): string {
+  return whatwgRNG(length)
+    .reduce((str, n) => str + byteToHex[n], '')
+    .slice(0, length)
+}

package/src/util/resolveJsType.ts

@@ -0,0 +1,44 @@
+const objectToString = Object.prototype.toString
+
+// Copied from https://github.com/ForbesLindesay/type-of
+// but inlined to have fine grained control
+export function resolveJsType(val: unknown) {
+  switch (objectToString.call(val)) {
+    case '[object Function]':
+      return 'function'
+    case '[object Date]':
+      return 'date'
+    case '[object RegExp]':
+      return 'regexp'
+    case '[object Arguments]':
+      return 'arguments'
+    case '[object Array]':
+      return 'array'
+    case '[object String]':
+      return 'string'
+    default:
+  }
+
+  if (val === null) {
+    return 'null'
+  }
+
+  if (val === undefined) {
+    return 'undefined'
+  }
+
+  if (
+    val &&
+    typeof val === 'object' &&
+    'nodeType' in val &&
+    (val as {nodeType: unknown}).nodeType === 1
+  ) {
+    return 'element'
+  }
+
+  if (val === Object(val)) {
+    return 'object'
+  }
+
+  return typeof val
+}