@wordpress/blocks/build-module/api/parser/index.js

Block API for WordPress.

/**
 * WordPress dependencies
 */
import { parse as grammarParse } from '@wordpress/block-serialization-default-parser';
import { autop } from '@wordpress/autop';

/**
 * Internal dependencies
 */
import { getFreeformContentHandlerName, getUnregisteredTypeHandlerName, getBlockType } from '../registration';
import { getSaveContent } from '../serializer';
import { validateBlock } from '../validation';
import { createBlock } from '../factory';
import { convertLegacyBlockNameAndAttributes } from './convert-legacy-block';
import { serializeRawBlock } from './serialize-raw-block';
import { getBlockAttributes } from './get-block-attributes';
import { applyBlockDeprecatedVersions } from './apply-block-deprecated-versions';
import { applyBuiltInValidationFixes } from './apply-built-in-validation-fixes';

/**
 * The raw structure of a block includes its attributes, inner
 * blocks, and inner HTML. It is important to distinguish inner blocks from
 * the HTML content of the block as only the latter is relevant for block
 * validation and edit operations.
 *
 * @typedef WPRawBlock
 *
 * @property {string=}         blockName    Block name
 * @property {Object=}         attrs        Block raw or comment attributes.
 * @property {string}          innerHTML    HTML content of the block.
 * @property {(string|null)[]} innerContent Content without inner blocks.
 * @property {WPRawBlock[]}    innerBlocks  Inner Blocks.
 */

/**
 * Fully parsed block object.
 *
 * @typedef WPBlock
 *
 * @property {string}     name                    Block name
 * @property {Object}     attributes              Block raw or comment attributes.
 * @property {WPBlock[]}  innerBlocks             Inner Blocks.
 * @property {string}     originalContent         Original content of the block before validation fixes.
 * @property {boolean}    isValid                 Whether the block is valid.
 * @property {Object[]}   validationIssues        Validation issues.
 * @property {WPRawBlock} [__unstableBlockSource] Un-processed original copy of block if created through parser.
 */

/**
 * @typedef  {Object}  ParseOptions
 * @property {boolean?} __unstableSkipMigrationLogs If a block is migrated from a deprecated version, skip logging the migration details.
 * @property {boolean?} __unstableSkipAutop         Whether to skip autop when processing freeform content.
 */

/**
 * Convert legacy blocks to their canonical form. This function is used
 * both in the parser level for previous content and to convert such blocks
 * used in Custom Post Types templates.
 *
 * @param {WPRawBlock} rawBlock
 *
 * @return {WPRawBlock} The block's name and attributes, changed accordingly if a match was found
 */
function convertLegacyBlocks(rawBlock) {
  const [correctName, correctedAttributes] = convertLegacyBlockNameAndAttributes(rawBlock.blockName, rawBlock.attrs);
  return {
    ...rawBlock,
    blockName: correctName,
    attrs: correctedAttributes
  };
}

/**
 * Normalize the raw block by applying the fallback block name if none given,
 * sanitize the parsed HTML...
 *
 * @param {WPRawBlock}    rawBlock The raw block object.
 * @param {ParseOptions?} options  Extra options for handling block parsing.
 *
 * @return {WPRawBlock} The normalized block object.
 */
export function normalizeRawBlock(rawBlock, options) {
  const fallbackBlockName = getFreeformContentHandlerName();

  // If the grammar parsing don't produce any block name, use the freeform block.
  const rawBlockName = rawBlock.blockName || getFreeformContentHandlerName();
  const rawAttributes = rawBlock.attrs || {};
  const rawInnerBlocks = rawBlock.innerBlocks || [];
  let rawInnerHTML = rawBlock.innerHTML.trim();

  // Fallback content may be upgraded from classic content expecting implicit
  // automatic paragraphs, so preserve them. Assumes wpautop is idempotent,
  // meaning there are no negative consequences to repeated autop calls.
  if (rawBlockName === fallbackBlockName && rawBlockName === 'core/freeform' && !options?.__unstableSkipAutop) {
    rawInnerHTML = autop(rawInnerHTML).trim();
  }
  return {
    ...rawBlock,
    blockName: rawBlockName,
    attrs: rawAttributes,
    innerHTML: rawInnerHTML,
    innerBlocks: rawInnerBlocks
  };
}

/**
 * Uses the "unregistered blockType" to create a block object.
 *
 * @param {WPRawBlock} rawBlock block.
 *
 * @return {WPRawBlock} The unregistered block object.
 */
function createMissingBlockType(rawBlock) {
  const unregisteredFallbackBlock = getUnregisteredTypeHandlerName() || getFreeformContentHandlerName();

  // Preserve undelimited content for use by the unregistered type
  // handler. A block node's `innerHTML` isn't enough, as that field only
  // carries the block's own HTML and not its nested blocks.
  const originalUndelimitedContent = serializeRawBlock(rawBlock, {
    isCommentDelimited: false
  });

  // Preserve full block content for use by the unregistered type
  // handler, block boundaries included.
  const originalContent = serializeRawBlock(rawBlock, {
    isCommentDelimited: true
  });
  return {
    blockName: unregisteredFallbackBlock,
    attrs: {
      originalName: rawBlock.blockName,
      originalContent,
      originalUndelimitedContent
    },
    innerHTML: rawBlock.blockName ? originalContent : rawBlock.innerHTML,
    innerBlocks: rawBlock.innerBlocks,
    innerContent: rawBlock.innerContent
  };
}

/**
 * Validates a block and wraps with validation meta.
 *
 * The name here is regrettable but `validateBlock` is already taken.
 *
 * @param {WPBlock}                               unvalidatedBlock
 * @param {import('../registration').WPBlockType} blockType
 * @return {WPBlock}                              validated block, with auto-fixes if initially invalid
 */
function applyBlockValidation(unvalidatedBlock, blockType) {
  // Attempt to validate the block.
  const [isValid] = validateBlock(unvalidatedBlock, blockType);
  if (isValid) {
    return {
      ...unvalidatedBlock,
      isValid,
      validationIssues: []
    };
  }

  // If the block is invalid, attempt some built-in fixes
  // like custom classNames handling.
  const fixedBlock = applyBuiltInValidationFixes(unvalidatedBlock, blockType);
  // Attempt to validate the block once again after the built-in fixes.
  const [isFixedValid, validationIssues] = validateBlock(fixedBlock, blockType);
  return {
    ...fixedBlock,
    isValid: isFixedValid,
    validationIssues
  };
}

/**
 * Given a raw block returned by grammar parsing, returns a fully parsed block.
 *
 * @param {WPRawBlock}   rawBlock The raw block object.
 * @param {ParseOptions} options  Extra options for handling block parsing.
 *
 * @return {WPBlock | undefined} Fully parsed block.
 */
export function parseRawBlock(rawBlock, options) {
  let normalizedBlock = normalizeRawBlock(rawBlock, options);

  // During the lifecycle of the project, we renamed some old blocks
  // and transformed others to new blocks. To avoid breaking existing content,
  // we added this function to properly parse the old content.
  normalizedBlock = convertLegacyBlocks(normalizedBlock);

  // Try finding the type for known block name.
  let blockType = getBlockType(normalizedBlock.blockName);

  // If not blockType is found for the specified name, fallback to the "unregisteredBlockType".
  if (!blockType) {
    normalizedBlock = createMissingBlockType(normalizedBlock);
    blockType = getBlockType(normalizedBlock.blockName);
  }

  // If it's an empty freeform block or there's no blockType (no missing block handler)
  // Then, just ignore the block.
  // It might be a good idea to throw a warning here.
  // TODO: I'm unsure about the unregisteredFallbackBlock check,
  // it might ignore some dynamic unregistered third party blocks wrongly.
  const isFallbackBlock = normalizedBlock.blockName === getFreeformContentHandlerName() || normalizedBlock.blockName === getUnregisteredTypeHandlerName();
  if (!blockType || !normalizedBlock.innerHTML && isFallbackBlock) {
    return;
  }

  // Parse inner blocks recursively.
  const parsedInnerBlocks = normalizedBlock.innerBlocks.map(innerBlock => parseRawBlock(innerBlock, options))
  // See https://github.com/WordPress/gutenberg/pull/17164.
  .filter(innerBlock => !!innerBlock);

  // Get the fully parsed block.
  const parsedBlock = createBlock(normalizedBlock.blockName, getBlockAttributes(blockType, normalizedBlock.innerHTML, normalizedBlock.attrs), parsedInnerBlocks);
  parsedBlock.originalContent = normalizedBlock.innerHTML;
  const validatedBlock = applyBlockValidation(parsedBlock, blockType);
  const {
    validationIssues
  } = validatedBlock;

  // Run the block deprecation and migrations.
  // This is performed on both invalid and valid blocks because
  // migration using the `migrate` functions should run even
  // if the output is deemed valid.
  const updatedBlock = applyBlockDeprecatedVersions(validatedBlock, normalizedBlock, blockType);
  if (!updatedBlock.isValid) {
    // Preserve the original unprocessed version of the block
    // that we received (no fixes, no deprecations) so that
    // we can save it as close to exactly the same way as
    // we loaded it. This is important to avoid corruption
    // and data loss caused by block implementations trying
    // to process data that isn't fully recognized.
    updatedBlock.__unstableBlockSource = rawBlock;
  }
  if (!validatedBlock.isValid && updatedBlock.isValid && !options?.__unstableSkipMigrationLogs) {
    /* eslint-disable no-console */
    console.groupCollapsed('Updated Block: %s', blockType.name);
    console.info('Block successfully updated for `%s` (%o).\n\nNew content generated by `save` function:\n\n%s\n\nContent retrieved from post body:\n\n%s', blockType.name, blockType, getSaveContent(blockType, updatedBlock.attributes), updatedBlock.originalContent);
    console.groupEnd();
    /* eslint-enable no-console */
  } else if (!validatedBlock.isValid && !updatedBlock.isValid) {
    validationIssues.forEach(({
      log,
      args
    }) => log(...args));
  }
  return updatedBlock;
}

/**
 * Utilizes an optimized token-driven parser based on the Gutenberg grammar spec
 * defined through a parsing expression grammar to take advantage of the regular
 * cadence provided by block delimiters -- composed syntactically through HTML
 * comments -- which, given a general HTML document as an input, returns a block
 * list array representation.
 *
 * This is a recursive-descent parser that scans linearly once through the input
 * document. Instead of directly recursing it utilizes a trampoline mechanism to
 * prevent stack overflow. This initial pass is mainly interested in separating
 * and isolating the blocks serialized in the document and manifestly not in the
 * content within the blocks.
 *
 * @see
 * https://developer.wordpress.org/block-editor/packages/packages-block-serialization-default-parser/
 *
 * @param {string}       content The post content.
 * @param {ParseOptions} options Extra options for handling block parsing.
 *
 * @return {Array} Block list.
 */
export default function parse(content, options) {
  return grammarParse(content).reduce((accumulator, rawBlock) => {
    const block = parseRawBlock(rawBlock, options);
    if (block) {
      accumulator.push(block);
    }
    return accumulator;
  }, []);
}
//# sourceMappingURL=index.js.map