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

Sanity-flavored HTML to Portable Text conversion (wraps @portabletext/html)

import { PortableTextBlock, PortableTextBlock as PortableTextBlock$1, PortableTextObject, PortableTextObject as PortableTextObject$1, PortableTextSpan, PortableTextSpan as PortableTextSpan$1, PortableTextTextBlock, PortableTextTextBlock as PortableTextTextBlock$1, Schema } from "@portabletext/schema";
import { ArraySchemaType } from "@sanity/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
 */
type ImageSchemaMatcher = ObjectSchemaMatcher<{
  src?: string;
  alt?: string;
  [key: string]: string | undefined;
}>;
/**
 * @beta
 */
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;
};
/**
 * @public
 */
interface TypedObject {
  _type: string;
  _key?: string;
}
/**
 * @public
 */
interface ArbitraryTypedObject extends TypedObject {
  [key: string]: unknown;
}
/**
 * @public
 */
type HtmlParser = (html: string) => Document;
/**
 * @public
 */
type WhiteSpacePasteMode = 'preserve' | 'remove' | 'normalize';
/**
 * @public
 */
interface HtmlDeserializerOptions {
  keyGenerator?: () => string;
  rules?: DeserializerRule[];
  parseHtml?: HtmlParser;
  unstable_whitespaceOnPasteMode?: WhiteSpacePasteMode;
  /**
   * Custom schema matchers to use when deserializing HTML to Portable Text.
   * @beta
   */
  matchers?: SchemaMatchers;
}
/**
 * @public
 */
interface DeserializerRule {
  deserialize: (el: Node, next: (elements: Node | Node[] | NodeList) => TypedObject | TypedObject[] | undefined, createBlock: (props: ArbitraryTypedObject) => {
    _type: string;
    block: ArbitraryTypedObject;
  }) => TypedObject | TypedObject[] | undefined;
}
/**
 * Block normalization options
 *
 * @public
 */
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;
}
/**
 * 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
 */
declare function normalizeBlock(node: TypedObject, options?: BlockNormalizationOptions): Omit<TypedObject | PortableTextTextBlock$1<TypedObject | PortableTextSpan$1>, '_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
 */
declare function randomKey(length: number): string;
/**
 * Convert HTML to blocks respecting the block content type's schema
 *
 * @param html - The HTML to convert to blocks
 * @param schemaType - A compiled version of the schema type for the block content
 * @param options - Options for deserializing HTML to blocks
 * @returns Array of blocks
 * @public
 */
declare function htmlToBlocks(html: string, schemaType: ArraySchemaType | Schema, options?: HtmlDeserializerOptions): PortableTextBlock$1[];
export { type ArbitraryTypedObject, type BlockNormalizationOptions, type DeserializerRule, type HtmlDeserializerOptions, type HtmlParser, type ImageSchemaMatcher, type PortableTextBlock, type PortableTextObject, type PortableTextSpan, type PortableTextTextBlock, type SchemaMatchers, type TypedObject, htmlToBlocks, normalizeBlock, randomKey };