@wordpress/block-library 7.4.0 → 7.7.0

package/src/table-of-contents/block.json

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
+	"__experimental": true,
 	"name": "core/table-of-contents",
 	"title": "Table of Contents",
 	"category": "layout",
@@ -8,13 +9,19 @@
 	"keywords": [ "document outline", "summary" ],
 	"textdomain": "default",
 	"attributes": {
+		"headings": {
+			"type": "array",
+			"items": {
+				"type": "object"
+			}
+		},
 		"onlyIncludeCurrentPage": {
 			"type": "boolean",
 			"default": false
 		}
 	},
-	"usesContext": [ "postId" ],
 	"supports": {
 		"html": false
-	}
+	},
+	"example": {}
 }

package/src/table-of-contents/edit.js

@@ -13,7 +13,7 @@ import {
 	store as blockEditorStore,
 	useBlockProps,
 } from '@wordpress/block-editor';
-import { createBlock, store as blocksStore } from '@wordpress/blocks';
+import { createBlock } from '@wordpress/blocks';
 import {
 	PanelBody,
 	Placeholder,
@@ -21,123 +21,215 @@ import {
 	ToolbarButton,
 	ToolbarGroup,
 } from '@wordpress/components';
+import { useDisabled } from '@wordpress/compose';
 import { useDispatch, useSelect } from '@wordpress/data';
-import { renderToString, useEffect, useState } from '@wordpress/element';
+import { __unstableStripHTML as stripHTML } from '@wordpress/dom';
+import { renderToString, useEffect } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
+import { addQueryArgs, removeQueryArgs } from '@wordpress/url';
 
 /**
  * Internal dependencies
  */
+import icon from './icon';
 import TableOfContentsList from './list';
-import { getHeadingsFromContent, linearToNestedHeadingList } from './utils';
+import { linearToNestedHeadingList } from './utils';
+
+/** @typedef {import('./utils').HeadingData} HeadingData */
 
 /**
  * Table of Contents block edit component.
  *
  * @param {Object}                       props                                   The props.
  * @param {Object}                       props.attributes                        The block attributes.
- * @param {boolean}                      props.attributes.onlyIncludeCurrentPage
- *                                                                               Whether to only include headings from the current page (if the post is
- *                                                                               paginated).
+ * @param {HeadingData[]}                props.attributes.headings               A list of data for each heading in the post.
+ * @param {boolean}                      props.attributes.onlyIncludeCurrentPage Whether to only include headings from the current page (if the post is paginated).
  * @param {string}                       props.clientId
  * @param {(attributes: Object) => void} props.setAttributes
  *
  * @return {WPComponent} The component.
  */
 export default function TableOfContentsEdit( {
-	attributes: { onlyIncludeCurrentPage },
+	attributes: { headings = [], onlyIncludeCurrentPage },
 	clientId,
 	setAttributes,
 } ) {
 	const blockProps = useBlockProps();
+	const disabledRef = useDisabled();
 
-	// Local state; not saved to block attributes. The saved block is dynamic and uses PHP to generate its content.
-	const [ headings, setHeadings ] = useState( [] );
-	const [ headingTree, setHeadingTree ] = useState( [] );
+	const canInsertList = useSelect(
+		( select ) => {
+			const { getBlockRootClientId, canInsertBlockType } = select(
+				blockEditorStore
+			);
+			const rootClientId = getBlockRootClientId( clientId );
 
-	const { listBlockExists, postContent } = useSelect(
-		( select ) => ( {
-			listBlockExists: !! select( blocksStore ).getBlockType(
-				'core/list'
-			),
-			// FIXME: @wordpress/block-library should not depend on @wordpress/editor.
-			// Blocks can be loaded into a *non-post* block editor.
-			// eslint-disable-next-line @wordpress/data-no-store-string-literals
-			postContent: select( 'core/editor' ).getEditedPostContent(),
-		} ),
-		[]
+			return canInsertBlockType( 'core/list', rootClientId );
+		},
+		[ clientId ]
 	);
 
-	// The page this block would be part of on the front-end. For performance
-	// reasons, this is only calculated when onlyIncludeCurrentPage is true.
-	const pageIndex = useSelect(
-		( select ) => {
-			if ( ! onlyIncludeCurrentPage ) {
-				return null;
-			}
+	const {
+		__unstableMarkNextChangeAsNotPersistent,
+		replaceBlocks,
+	} = useDispatch( blockEditorStore );
 
+	/**
+	 * The latest heading data, or null if the new data deeply equals the saved
+	 * headings attribute.
+	 *
+	 * Since useSelect forces a re-render when its return value is shallowly
+	 * inequal to its prior call, we would be re-rendering this block every time
+	 * the stores change, even if the latest headings were deeply equal to the
+	 * ones saved in the block attributes.
+	 *
+	 * By returning null when they're equal, we reduce that to 2 renders: one
+	 * when there are new latest headings (and so it returns them), and one when
+	 * they haven't changed (so it returns null). As long as the latest heading
+	 * data remains the same, further calls of the useSelect callback will
+	 * continue to return null, thus preventing any forced re-renders.
+	 */
+	const latestHeadings = useSelect(
+		( select ) => {
 			const {
 				getBlockAttributes,
-				getBlockIndex,
 				getBlockName,
-				getBlockOrder,
+				getClientIdsWithDescendants,
+				__experimentalGetGlobalBlocksByName: getGlobalBlocksByName,
 			} = select( blockEditorStore );
 
-			const blockIndex = getBlockIndex( clientId );
-			const blockOrder = getBlockOrder();
-
-			// Calculate which page the block will appear in on the front-end by
-			// counting how many <!--nextpage--> tags precede it.
-			// Unfortunately, this implementation only accounts for Page Break and
-			// Classic blocks, so if there are any <!--nextpage--> tags in any
-			// other block, they won't be counted. This will result in the table
-			// of contents showing headings from the wrong page if
-			// onlyIncludeCurrentPage === true. Thankfully, this issue only
-			// affects the editor implementation.
-			let page = 1;
-			for ( let i = 0; i < blockIndex; i++ ) {
-				const blockName = getBlockName( blockOrder[ i ] );
+			// FIXME: @wordpress/block-library should not depend on @wordpress/editor.
+			// Blocks can be loaded into a *non-post* block editor, so to avoid
+			// declaring @wordpress/editor as a dependency, we must access its
+			// store by string. When the store is not available, editorSelectors
+			// will be null, and the block's saved markup will lack permalinks.
+			// eslint-disable-next-line @wordpress/data-no-store-string-literals
+			const editorSelectors = select( 'core/editor' );
+
+			const pageBreakClientIds = getGlobalBlocksByName( 'core/nextpage' );
+
+			const isPaginated = pageBreakClientIds.length !== 0;
+
+			// Get the client ids of all blocks in the editor.
+			const allBlockClientIds = getClientIdsWithDescendants();
+
+			// If onlyIncludeCurrentPage is true, calculate the page (of a paginated post) this block is part of, so we know which headings to include; otherwise, skip the calculation.
+			let tocPage = 1;
+
+			if ( isPaginated && onlyIncludeCurrentPage ) {
+				// We can't use getBlockIndex because it only returns the index
+				// relative to sibling blocks.
+				const tocIndex = allBlockClientIds.indexOf( clientId );
+
+				for ( const [
+					blockIndex,
+					blockClientId,
+				] of allBlockClientIds.entries() ) {
+					// If we've reached blocks after the Table of Contents, we've
+					// finished calculating which page the block is on.
+					if ( blockIndex >= tocIndex ) {
+						break;
+					}
+					if ( getBlockName( blockClientId ) === 'core/nextpage' ) {
+						tocPage++;
+					}
+				}
+			}
+
+			const _latestHeadings = [];
+
+			/** The page (of a paginated post) a heading will be part of. */
+			let headingPage = 1;
+
+			/**
+			 * A permalink to the current post. If the core/editor store is
+			 * unavailable, this variable will be null.
+			 */
+			const permalink = editorSelectors?.getPermalink() ?? null;
+
+			let headingPageLink = null;
+
+			// If the core/editor store is available, we can add permalinks to the
+			// generated table of contents.
+			if ( typeof permalink === 'string' ) {
+				headingPageLink = isPaginated
+					? addQueryArgs( permalink, { page: headingPage } )
+					: permalink;
+			}
+
+			for ( const blockClientId of allBlockClientIds ) {
+				const blockName = getBlockName( blockClientId );
 				if ( blockName === 'core/nextpage' ) {
-					page++;
-				} else if ( blockName === 'core/freeform' ) {
-					// Count the page breaks inside the Classic block.
-					const pageBreaks = getBlockAttributes(
-						blockOrder[ i ]
-					).content?.match( /<!--nextpage-->/g );
-
-					if ( pageBreaks !== null && pageBreaks !== undefined ) {
-						page += pageBreaks.length;
+					headingPage++;
+
+					// If we're only including headings from the current page (of
+					// a paginated post), then exit the loop if we've reached the
+					// pages after the one with the Table of Contents block.
+					if ( onlyIncludeCurrentPage && headingPage > tocPage ) {
+						break;
+					}
+
+					if ( typeof permalink === 'string' ) {
+						headingPageLink = addQueryArgs(
+							removeQueryArgs( permalink, [ 'page' ] ),
+							{ page: headingPage }
+						);
+					}
+				}
+				// If we're including all headings or we've reached headings on
+				// the same page as the Table of Contents block, add them to the
+				// list.
+				else if (
+					! onlyIncludeCurrentPage ||
+					headingPage === tocPage
+				) {
+					if ( blockName === 'core/heading' ) {
+						const headingAttributes = getBlockAttributes(
+							blockClientId
+						);
+
+						const canBeLinked =
+							typeof headingPageLink === 'string' &&
+							typeof headingAttributes.anchor === 'string' &&
+							headingAttributes.anchor !== '';
+
+						_latestHeadings.push( {
+							// Convert line breaks to spaces, and get rid of HTML tags in the headings.
+							content: stripHTML(
+								headingAttributes.content.replace(
+									/(<br *\/?>)+/g,
+									' '
+								)
+							),
+							level: headingAttributes.level,
+							link: canBeLinked
+								? `${ headingPageLink }#${ headingAttributes.anchor }`
+								: null,
+						} );
 					}
 				}
 			}
 
-			return page;
+			if ( isEqual( headings, _latestHeadings ) ) {
+				return null;
+			}
+			return _latestHeadings;
 		},
-		[ clientId, onlyIncludeCurrentPage ]
+		[ clientId, onlyIncludeCurrentPage, headings ]
 	);
 
 	useEffect( () => {
-		let latestHeadings;
-
-		if ( onlyIncludeCurrentPage ) {
-			const pagesOfContent = postContent.split( '<!--nextpage-->' );
-
-			latestHeadings = getHeadingsFromContent(
-				pagesOfContent[ pageIndex - 1 ]
-			);
-		} else {
-			latestHeadings = getHeadingsFromContent( postContent );
-		}
-
-		if ( ! isEqual( headings, latestHeadings ) ) {
-			setHeadings( latestHeadings );
-			setHeadingTree( linearToNestedHeadingList( latestHeadings ) );
+		if ( latestHeadings !== null ) {
+			// This is required to keep undo working and not create 2 undo steps
+			// for each heading change.
+			__unstableMarkNextChangeAsNotPersistent();
+			setAttributes( { headings: latestHeadings } );
 		}
-	}, [ pageIndex, postContent, onlyIncludeCurrentPage ] );
+	}, [ latestHeadings ] );
 
-	const { replaceBlocks } = useDispatch( blockEditorStore );
+	const headingTree = linearToNestedHeadingList( headings );
 
-	const toolbarControls = listBlockExists && (
+	const toolbarControls = canInsertList && (
 		<BlockControls>
 			<ToolbarGroup>
 				<ToolbarButton
@@ -145,6 +237,7 @@ export default function TableOfContentsEdit( {
 						replaceBlocks(
 							clientId,
 							createBlock( 'core/list', {
+								ordered: true,
 								values: renderToString(
 									<TableOfContentsList
 										nestedHeadingList={ headingTree }
@@ -162,7 +255,7 @@ export default function TableOfContentsEdit( {
 
 	const inspectorControls = (
 		<InspectorControls>
-			<PanelBody title={ __( 'Table of Contents settings' ) }>
+			<PanelBody title={ __( 'Settings' ) }>
 				<ToggleControl
 					label={ __( 'Only include current page' ) }
 					checked={ onlyIncludeCurrentPage }
@@ -191,7 +284,7 @@ export default function TableOfContentsEdit( {
 			<>
 				<div { ...blockProps }>
 					<Placeholder
-						icon={ <BlockIcon icon="list-view" /> }
+						icon={ <BlockIcon icon={ icon } /> }
 						label="Table of Contents"
 						instructions={ __(
 							'Start adding Heading blocks to create a table of contents. Headings with HTML anchors will be linked here.'
@@ -206,9 +299,9 @@ export default function TableOfContentsEdit( {
 	return (
 		<>
 			<nav { ...blockProps }>
-				<ul>
+				<ol ref={ disabledRef }>
 					<TableOfContentsList nestedHeadingList={ headingTree } />
-				</ul>
+				</ol>
 			</nav>
 			{ toolbarControls }
 			{ inspectorControls }

package/src/table-of-contents/index.js

@@ -4,6 +4,7 @@
 import metadata from './block.json';
 import edit from './edit';
 import icon from './icon';
+import save from './save';
 
 const { name } = metadata;
 
@@ -12,4 +13,5 @@ export { metadata, name };
 export const settings = {
 	icon,
 	edit,
+	save,
 };

package/src/table-of-contents/list.tsx

@@ -0,0 +1,46 @@
+/**
+ * WordPress dependencies
+ */
+import type { WPElement } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { NestedHeadingData } from './utils';
+
+const ENTRY_CLASS_NAME = 'wp-block-table-of-contents__entry';
+
+export default function TableOfContentsList( {
+	nestedHeadingList,
+}: {
+	nestedHeadingList: NestedHeadingData[];
+} ): WPElement {
+	return (
+		<>
+			{ nestedHeadingList.map( ( node, index ) => {
+				const { content, link } = node.heading;
+
+				const entry = link ? (
+					<a className={ ENTRY_CLASS_NAME } href={ link }>
+						{ content }
+					</a>
+				) : (
+					<span className={ ENTRY_CLASS_NAME }>{ content }</span>
+				);
+
+				return (
+					<li key={ index }>
+						{ entry }
+						{ node.children ? (
+							<ol>
+								<TableOfContentsList
+									nestedHeadingList={ node.children }
+								/>
+							</ol>
+						) : null }
+					</li>
+				);
+			} ) }
+		</>
+	);
+}

package/src/table-of-contents/save.js

@@ -0,0 +1,25 @@
+/**
+ * WordPress dependencies
+ */
+import { useBlockProps } from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import TableOfContentsList from './list';
+import { linearToNestedHeadingList } from './utils';
+
+export default function save( { attributes: { headings = [] } } ) {
+	if ( headings.length === 0 ) {
+		return null;
+	}
+	return (
+		<nav { ...useBlockProps.save() }>
+			<ol>
+				<TableOfContentsList
+					nestedHeadingList={ linearToNestedHeadingList( headings ) }
+				/>
+			</ol>
+		</nav>
+	);
+}

package/src/table-of-contents/utils.ts

@@ -0,0 +1,71 @@
+export interface HeadingData {
+	/** The plain text content of the heading. */
+	content: string;
+	/** The heading level. */
+	level: number;
+	/** Link to the heading. */
+	link: string;
+}
+
+export interface NestedHeadingData {
+	/** The heading content, level, and link. */
+	heading: HeadingData;
+	/** The sub-headings of this heading, if any. */
+	children: NestedHeadingData[] | null;
+}
+
+/**
+ * Takes a flat list of heading parameters and nests them based on each header's
+ * immediate parent's level.
+ *
+ * @param  headingList The flat list of headings to nest.
+ *
+ * @return The nested list of headings.
+ */
+export function linearToNestedHeadingList(
+	headingList: HeadingData[]
+): NestedHeadingData[] {
+	const nestedHeadingList: NestedHeadingData[] = [];
+
+	headingList.forEach( ( heading, key ) => {
+		if ( heading.content === '' ) {
+			return;
+		}
+
+		// Make sure we are only working with the same level as the first iteration in our set.
+		if ( heading.level === headingList[ 0 ].level ) {
+			// Check that the next iteration will return a value.
+			// If it does and the next level is greater than the current level,
+			// the next iteration becomes a child of the current iteration.
+			if ( headingList[ key + 1 ]?.level > heading.level ) {
+				// We must calculate the last index before the next iteration that
+				// has the same level (siblings). We then use this index to slice
+				// the array for use in recursion. This prevents duplicate nodes.
+				let endOfSlice = headingList.length;
+				for ( let i = key + 1; i < headingList.length; i++ ) {
+					if ( headingList[ i ].level === heading.level ) {
+						endOfSlice = i;
+						break;
+					}
+				}
+
+				// We found a child node: Push a new node onto the return array
+				// with children.
+				nestedHeadingList.push( {
+					heading,
+					children: linearToNestedHeadingList(
+						headingList.slice( key + 1, endOfSlice )
+					),
+				} );
+			} else {
+				// No child node: Push a new node onto the return array.
+				nestedHeadingList.push( {
+					heading,
+					children: null,
+				} );
+			}
+		}
+	} );
+
+	return nestedHeadingList;
+}

package/src/tag-cloud/block.json

@@ -23,7 +23,7 @@
 		},
 		"smallestFontSize": {
 			"type": "string",
-			"default": "8pt" 
+			"default": "8pt"
 		},
 		"largestFontSize": {
 			"type": "string",

package/src/template-part/edit/index.js

@@ -13,6 +13,7 @@ import {
 	__experimentalUseNoRecursiveRenders as useNoRecursiveRenders,
 	Warning,
 	store as blockEditorStore,
+	__experimentalUseBlockOverlayActive as useBlockOverlayActive,
 } from '@wordpress/block-editor';
 import {
 	ToolbarGroup,
@@ -95,7 +96,15 @@ export default function TemplatePartEdit( {
 	const blockPatterns = useAlternativeBlockPatterns( area, clientId );
 	const hasReplacements = !! templateParts.length || !! blockPatterns.length;
 	const areaObject = useTemplatePartArea( area );
-	const blockProps = useBlockProps();
+	const hasBlockOverlay = useBlockOverlayActive( clientId );
+	const blockProps = useBlockProps(
+		{
+			className: hasBlockOverlay
+				? 'block-editor-block-content-overlay'
+				: undefined,
+		},
+		{ __unstableIsDisabled: hasBlockOverlay }
+	);
 	const isPlaceholder = ! slug;
 	const isEntityAvailable = ! isPlaceholder && ! isMissing && isResolved;
 	const TagName = tagName || areaObject.tagName;
@@ -153,22 +162,23 @@ export default function TemplatePartEdit( {
 					/>
 				</TagName>
 			) }
-			{ isEntityAvailable && hasReplacements && (
-				<BlockControls>
-					<ToolbarGroup className="wp-block-template-part__block-control-group">
-						<ToolbarButton
-							onClick={ () =>
-								setIsTemplatePartSelectionOpen( true )
-							}
-						>
-							{ __( 'Replace' ) }
-						</ToolbarButton>
-					</ToolbarGroup>
-				</BlockControls>
-			) }
+			{ isEntityAvailable &&
+				hasReplacements &&
+				( area === 'header' || area === 'footer' ) && (
+					<BlockControls>
+						<ToolbarGroup className="wp-block-template-part__block-control-group">
+							<ToolbarButton
+								onClick={ () =>
+									setIsTemplatePartSelectionOpen( true )
+								}
+							>
+								{ __( 'Replace' ) }
+							</ToolbarButton>
+						</ToolbarGroup>
+					</BlockControls>
+				) }
 			{ isEntityAvailable && (
 				<TemplatePartInnerBlocks
-					clientId={ clientId }
 					tagName={ TagName }
 					blockProps={ blockProps }
 					postId={ templatePartId }

package/src/template-part/edit/inner-blocks.js

@@ -5,7 +5,6 @@ import { useEntityBlockEditor } from '@wordpress/core-data';
 import {
 	InnerBlocks,
 	useInnerBlocksProps,
-	__experimentalBlockContentOverlay as BlockContentOverlay,
 	useSetting,
 	store as blockEditorStore,
 } from '@wordpress/block-editor';
@@ -15,9 +14,8 @@ export default function TemplatePartInnerBlocks( {
 	postId: id,
 	hasInnerBlocks,
 	layout,
-	tagName,
+	tagName: TagName,
 	blockProps,
-	clientId,
 } ) {
 	const themeSupportsLayout = useSelect( ( select ) => {
 		const { getSettings } = select( blockEditorStore );
@@ -42,11 +40,5 @@ export default function TemplatePartInnerBlocks( {
 		__experimentalLayout: themeSupportsLayout ? usedLayout : undefined,
 	} );
 
-	return (
-		<BlockContentOverlay
-			clientId={ clientId }
-			tagName={ tagName }
-			wrapperProps={ innerBlocksProps }
-		/>
-	);
+	return <TagName { ...innerBlocksProps } />;
 }

package/src/video/edit.js

@@ -32,7 +32,7 @@ import { __, sprintf } from '@wordpress/i18n';
 import { useInstanceId } from '@wordpress/compose';
 import { useSelect } from '@wordpress/data';
 import { video as icon } from '@wordpress/icons';
-import { createBlock } from '@wordpress/blocks';
+import { createBlock, getDefaultBlockName } from '@wordpress/blocks';
 
 /**
  * Internal dependencies
@@ -61,7 +61,8 @@ function VideoEdit( {
 	const { id, caption, controls, poster, src, tracks } = attributes;
 	const isTemporaryVideo = ! id && isBlobURL( src );
 	const mediaUpload = useSelect(
-		( select ) => select( blockEditorStore ).getSettings().mediaUpload
+		( select ) => select( blockEditorStore ).getSettings().mediaUpload,
+		[]
 	);
 
 	useEffect( () => {
@@ -70,9 +71,7 @@ function VideoEdit( {
 			if ( file ) {
 				mediaUpload( {
 					filesList: [ file ],
-					onFileChange: ( [ { url } ] ) => {
-						setAttributes( { src: url } );
-					},
+					onFileChange: ( [ media ] ) => onSelectVideo( media ),
 					onError: ( message ) => {
 						noticeOperations.createErrorNotice( message );
 					},
@@ -275,7 +274,9 @@ function VideoEdit( {
 						}
 						inlineToolbar
 						__unstableOnSplitAtEnd={ () =>
-							insertBlocksAfter( createBlock( 'core/paragraph' ) )
+							insertBlocksAfter(
+								createBlock( getDefaultBlockName() )
+							)
 						}
 					/>
 				) }