@wordpress/block-editor/build-module/components/inner-blocks/use-inner-block-template-sync.js

Generic block editor.

/**
 * External dependencies
 */
import fastDeepEqual from 'fast-deep-equal/es6';

/**
 * WordPress dependencies
 */
import { useRef, useLayoutEffect } from '@wordpress/element';
import { useRegistry } from '@wordpress/data';
import { synchronizeBlocksWithTemplate } from '@wordpress/blocks';

/**
 * Internal dependencies
 */
import { store as blockEditorStore } from '../../store';

/**
 * This hook makes sure that a block's inner blocks stay in sync with the given
 * block "template". The template is a block hierarchy to which inner blocks must
 * conform. If the blocks get "out of sync" with the template and the template
 * is meant to be locked (e.g. templateLock = "all" or templateLock = "contentOnly"),
 * then we replace the inner blocks with the correct value after synchronizing it with the template.
 *
 * @param {string}  clientId                       The block client ID.
 * @param {Object}  template                       The template to match.
 * @param {string}  templateLock                   The template lock state for the inner blocks. For
 *                                                 example, if the template lock is set to "all",
 *                                                 then the inner blocks will stay in sync with the
 *                                                 template. If not defined or set to false, then
 *                                                 the inner blocks will not be synchronized with
 *                                                 the given template.
 * @param {boolean} templateInsertUpdatesSelection Whether or not to update the
 *                                                 block-editor selection state when inner blocks
 *                                                 are replaced after template synchronization.
 */
export default function useInnerBlockTemplateSync(clientId, template, templateLock, templateInsertUpdatesSelection) {
  // Instead of adding a useSelect mapping here, please add to the useSelect
  // mapping in InnerBlocks! Every subscription impacts performance.
  const registry = useRegistry();

  // Maintain a reference to the previous value so we can do a deep equality check.
  const existingTemplateRef = useRef(null);
  useLayoutEffect(() => {
    let isCancelled = false;
    const {
      getBlocks,
      getSelectedBlocksInitialCaretPosition,
      isBlockSelected
    } = registry.select(blockEditorStore);
    const {
      replaceInnerBlocks,
      __unstableMarkNextChangeAsNotPersistent
    } = registry.dispatch(blockEditorStore);

    // There's an implicit dependency between useInnerBlockTemplateSync and useNestedSettingsUpdate
    // The former needs to happen after the latter and since the latter is using microtasks to batch updates (performance optimization),
    // we need to schedule this one in a microtask as well.
    // Example: If you remove queueMicrotask here, ctrl + click to insert quote block won't close the inserter.
    window.queueMicrotask(() => {
      if (isCancelled) {
        return;
      }

      // Only synchronize innerBlocks with template if innerBlocks are empty
      // or a locking "all" or "contentOnly" exists directly on the block.
      const currentInnerBlocks = getBlocks(clientId);
      const shouldApplyTemplate = currentInnerBlocks.length === 0 || templateLock === 'all' || templateLock === 'contentOnly';
      const hasTemplateChanged = !fastDeepEqual(template, existingTemplateRef.current);
      if (!shouldApplyTemplate || !hasTemplateChanged) {
        return;
      }
      existingTemplateRef.current = template;
      const nextBlocks = synchronizeBlocksWithTemplate(currentInnerBlocks, template);
      if (!fastDeepEqual(nextBlocks, currentInnerBlocks)) {
        __unstableMarkNextChangeAsNotPersistent();
        replaceInnerBlocks(clientId, nextBlocks, currentInnerBlocks.length === 0 && templateInsertUpdatesSelection && nextBlocks.length !== 0 && isBlockSelected(clientId),
        // This ensures the "initialPosition" doesn't change when applying the template
        // If we're supposed to focus the block, we'll focus the first inner block
        // otherwise, we won't apply any auto-focus.
        // This ensures for instance that the focus stays in the inserter when inserting the "buttons" block.
        getSelectedBlocksInitialCaretPosition());
      }
    });
    return () => {
      isCancelled = true;
    };
  }, [template, templateLock, clientId, registry, templateInsertUpdatesSelection]);
}
//# sourceMappingURL=use-inner-block-template-sync.js.map