@portabletext/block-tools/lib/index.d.cts

Can format HTML, Slate JSON or Sanity block array into any other format.

import type {
  ArraySchemaType,
  I18nTitledListValue,
  ObjectSchemaType,
  SpanSchemaType,
  TitledListValue,
} from '@sanity/types'
import {PortableTextSpan, PortableTextTextBlock} from '@sanity/types'
import type {ComponentType} from 'react'

/**
 * @public
 */
export declare interface ArbitraryTypedObject extends TypedObject {
  [key: string]: unknown
}

/**
 * @public
 */
export declare interface BlockContentFeatures {
  styles: TitledListValue<string>[]
  decorators: TitledListValue<string>[]
  annotations: ResolvedAnnotationType[]
  lists: I18nTitledListValue<string>[]
  types: {
    block: ArraySchemaType
    span: SpanSchemaType
    inlineObjects: ObjectSchemaType[]
    blockObjects: ObjectSchemaType[]
  }
}

/**
 * @beta
 */
export declare interface BlockEditorSchemaProps {
  icon?: string | ComponentType
  render?: ComponentType
}

/**
 * Block normalization options
 *
 * @public
 */
export declare 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
  /**
   * Custom key generator function
   */
  keyGenerator?: () => string
}

/**
 * @public
 */
export declare interface DeserializerRule {
  deserialize: (
    el: Node,
    next: (
      elements: Node | Node[] | NodeList,
    ) => TypedObject | TypedObject[] | undefined,
    createBlock: (props: ArbitraryTypedObject) => {
      _type: string
      block: ArbitraryTypedObject
    },
  ) => TypedObject | TypedObject[] | undefined
}

/**
 * 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 declare function getBlockContentFeatures(
  blockContentType: ArraySchemaType,
): BlockContentFeatures

/**
 * @public
 */
export declare interface HtmlDeserializerOptions {
  keyGenerator?: () => string
  rules?: DeserializerRule[]
  parseHtml?: HtmlParser
  unstable_whitespaceOnPasteMode?: WhiteSpacePasteMode
}

/**
 * @public
 */
export declare type HtmlParser = (html: string) => Document

/**
 * 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 declare function htmlToBlocks(
  html: string,
  blockContentType: ArraySchemaType,
  options?: HtmlDeserializerOptions,
): (TypedObject | PortableTextTextBlock)[]

/**
 * 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 declare function normalizeBlock(
  node: TypedObject,
  options?: BlockNormalizationOptions,
): Omit<
  TypedObject | PortableTextTextBlock<TypedObject | PortableTextSpan>,
  '_key'
> & {
  _key: string
}

/**
 * Generate a random key of the given length
 *
 * @param length - Length of string to generate
 * @returns A string of the given length
 * @public
 */
export declare function randomKey(length: number): string

/**
 * @public
 */
export declare interface ResolvedAnnotationType {
  blockEditor?: BlockEditorSchemaProps
  title: string | undefined
  value: string
  type: ObjectSchemaType
  icon: ComponentType | undefined
}

/**
 * @public
 */
export declare interface TypedObject {
  _type: string
  _key?: string
}

/**
 * @public
 */
declare type WhiteSpacePasteMode = 'preserve' | 'remove' | 'normalize'

export {}