Add Term Template block

docs/reference-guides/core-blocks.md

@@ -942,13 +942,25 @@ Display the description of categories, tags and custom taxonomies when viewing a
 -	**Supports:** align (full, wide), color (background, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
 -	**Attributes:** textAlign
 
+## Term Template
+
+Contains the block elements used to render a taxonomy term, like the name, description, and more. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/term-template))
+
+-	**Name:** core/term-template
+-	**Experimental:** true
+-	**Category:** theme
+-	**Ancestor:** core/terms-query
+-	**Allowed Blocks:** core/paragraph
+-	**Supports:** align (full, wide), color (background, gradients, link, text), interactivity (clientNavigation), layout, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
+
 ## Terms Query
 
 An advanced block that allows displaying taxonomy terms based on different query parameters and visual configurations. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/terms-query))
 
 -	**Name:** core/terms-query
 -	**Experimental:** true
 -	**Category:** theme
+-	**Allowed Blocks:** core/term-template
 -	**Supports:** align (full, wide), interactivity, layout, ~~html~~
 -	**Attributes:** namespace, tagName, termQuery, termQueryId
 

lib/blocks.php

@@ -120,6 +120,7 @@ function gutenberg_reregister_core_block_types() {
 				'template-part.php'                => 'core/template-part',
 				'term-description.php'             => 'core/term-description',
 				'terms-query.php'                  => 'core/terms-query',
+				'term-template.php'                => 'core/term-template',
 				'video.php'                        => 'core/video',
 			),
 		),

packages/block-library/src/index.js

@@ -119,6 +119,7 @@ import * as tagCloud from './tag-cloud';
 import * as templatePart from './template-part';
 import * as termDescription from './term-description';
 import * as termsQuery from './terms-query';
+import * as termTemplate from './term-template';
 import * as textColumns from './text-columns';
 import * as verse from './verse';
 import * as video from './video';
@@ -233,6 +234,7 @@ const getAllBlocks = () => {
 		logInOut,
 		termDescription,
 		termsQuery,
+		termTemplate,
 		queryTitle,
 		postAuthorBiography,
 	];

packages/block-library/src/term-template/block.json

@@ -0,0 +1,62 @@
+{
+	"$schema": "https://schemas.wp.org/trunk/block.json",
+	"apiVersion": 3,
+	"__experimental": true,
+	"name": "core/term-template",
+	"title": "Term Template",
+	"category": "theme",
+	"ancestor": [ "core/terms-query" ],
+	"description": "Contains the block elements used to render a taxonomy term, like the name, description, and more.",
+	"textdomain": "default",
+	"usesContext": [ "termQueryId", "termQuery", "templateSlug", "termName" ],
+	"supports": {
+		"reusable": false,
+		"html": false,
+		"align": [ "wide", "full" ],
+		"layout": true,
+		"color": {
+			"gradients": true,
+			"link": true,
+			"__experimentalDefaultControls": {
+				"background": true,
+				"text": true
+			}
+		},
+		"typography": {
+			"fontSize": true,
+			"lineHeight": true,
+			"__experimentalFontFamily": true,
+			"__experimentalFontWeight": true,
+			"__experimentalFontStyle": true,
+			"__experimentalTextTransform": true,
+			"__experimentalTextDecoration": true,
+			"__experimentalLetterSpacing": true,
+			"__experimentalDefaultControls": {
+				"fontSize": true
+			}
+		},
+		"spacing": {
+			"margin": true,
+			"padding": true,
+			"blockGap": {
+				"__experimentalDefault": "1.25em"
+			},
+			"__experimentalDefaultControls": {
+				"blockGap": true,
+				"padding": false,
+				"margin": false
+			}
+		},
+		"interactivity": {
+			"clientNavigation": true
+		},
+		"__experimentalBorder": {
+			"radius": true,
+			"color": true,
+			"width": true,
+			"style": true
+		}
+	},
+	"allowedBlocks": [ "core/paragraph" ],
+	"style": "wp-block-term-template"
+}

packages/block-library/src/term-template/edit.js

@@ -0,0 +1,277 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { memo, useMemo, useState } from '@wordpress/element';
+import { useSelect } from '@wordpress/data';
+import { __ } from '@wordpress/i18n';
+import {
+	BlockControls,
+	BlockContextProvider,
+	__experimentalUseBlockPreview as useBlockPreview,
+	useBlockProps,
+	useInnerBlocksProps,
+	store as blockEditorStore,
+} from '@wordpress/block-editor';
+import { Spinner, ToolbarGroup } from '@wordpress/components';
+import { useEntityRecords } from '@wordpress/core-data';
+
+const TEMPLATE = [ [ 'core/paragraph' ] ];
+
+function TermTemplateInnerBlocks( { classList, term } ) {
+	const innerBlocksProps = useInnerBlocksProps(
+		{ className: clsx( 'wp-block-term', classList ) },
+		{ template: TEMPLATE, __unstableDisableLayoutClassNames: true }
+	);
+	return <li { ...innerBlocksProps }>{ term?.name }</li>;
+}
+
+function TermTemplateBlockPreview( {
+	blocks,
+	blockContextId,
+	classList,
+	isHidden,
+	setActiveBlockContextId,
+	termName,
+} ) {
+	const blockPreviewProps = useBlockPreview( {
+		blocks,
+		props: {
+			className: clsx( 'wp-block-term', classList ),
+		},
+	} );
+
+	const handleOnClick = () => {
+		setActiveBlockContextId( blockContextId );
+	};
+
+	const style = {
+		display: isHidden ? 'none' : undefined,
+	};
+
+	return (
+		<li
+			{ ...blockPreviewProps }
+			tabIndex={ 0 }
+			// eslint-disable-next-line jsx-a11y/no-noninteractive-element-to-interactive-role
+			role="button"
+			onClick={ handleOnClick }
+			onKeyPress={ handleOnClick }
+			style={ style }
+		>
+			{ termName }
+		</li>
+	);
+}
+
+const MemoizedTermTemplateBlockPreview = memo( TermTemplateBlockPreview );
+
+/**
+ * Builds a hierarchical tree structure from flat terms array.
+ *
+ * @param {Array} terms Array of term objects.
+ * @return {Array} Tree structure with parent/child relationships.
+ */
+function buildTermsTree( terms ) {
+	const termsById = {};
+	const rootTerms = [];
+
+	terms.forEach( ( term ) => {
+		termsById[ term.id ] = {
+			term,
+			children: [],
+		};
+	} );
+
+	terms.forEach( ( term ) => {
+		if ( term.parent && termsById[ term.parent ] ) {
+			termsById[ term.parent ].children.push( termsById[ term.id ] );
+		} else {
+			rootTerms.push( termsById[ term.id ] );
+		}
+	} );
+
+	return rootTerms;
+}
+
+/**
+ * Renders a single term node and its children recursively.
+ *
+ * @param {Object}   termNode   Term node with term object and children.
+ * @param {Function} renderTerm Function to render a single term.
+ * @return {JSX.Element} Rendered term node.
+ */
+function renderTermNode( termNode, renderTerm ) {
+	const children =
+		termNode.children.length > 0 ? (
+			<ul>
+				{ termNode.children.map( ( childNode ) =>
+					renderTermNode( childNode, renderTerm )
+				) }
+			</ul>
+		) : null;
+
+	return (
+		<>
+			{ renderTerm( termNode.term ) }
+			{ children }
+		</>
+	);
+}
+
+export default function TermTemplateEdit( {
+	clientId,
+	context: {
+		termQuery: {
+			taxonomy,
+			order,
+			orderBy,
+			hideEmpty,
+			hierarchical,
+			parent,
+		} = {},
+	},
+} ) {
+	const [ activeBlockContextId, setActiveBlockContextId ] = useState();
+
+	const queryArgs = {
+		order,
+		orderby: orderBy,
+		hide_empty: hideEmpty,
+	};
+
+	const { records: terms, isResolving } = useEntityRecords(
+		'taxonomy',
+		taxonomy,
+		queryArgs
+	);
+
+	// Filter to show only top-level terms if "Show only top-level terms" is enabled.
+	const filteredTerms = useMemo( () => {
+		if ( ! terms || parent !== 0 ) {
+			return terms;
+		}
+		return terms.filter( ( term ) => ! term.parent );
+	}, [ terms, parent ] );
+
+	const { blocks } = useSelect(
+		( select ) => ( {
+			blocks: select( blockEditorStore ).getBlocks( clientId ),
+		} ),
+		[ clientId ]
+	);
+
+	const blockContexts = useMemo(
+		() =>
+			filteredTerms?.map( ( term ) => ( {
+				taxonomy,
+				termId: term.id,
+				classList: `term-${ term.id }`,
+			} ) ),
+		[ filteredTerms, taxonomy ]
+	);
+
+	const blockProps = useBlockProps( {
+		className: clsx( 'wp-block-term-template' ),
+	} );
+
+	if ( isResolving ) {
+		return (
+			<p { ...blockProps }>
+				<Spinner />
+			</p>
+		);
+	}
+
+	if ( ! filteredTerms?.length ) {
+		return <p { ...blockProps }> { __( 'No terms found.' ) }</p>;
+	}
+
+	const renderTerm = ( term ) => {
+		const blockContext = {
+			taxonomy,
+			termId: term.id,
+			classList: `term-${ term.id }`,
+		};
+
+		return (
+			<BlockContextProvider key={ term.id } value={ blockContext }>
+				{ term.id ===
+				( activeBlockContextId || blockContexts[ 0 ]?.termId ) ? (
+					<TermTemplateInnerBlocks
+						classList={ blockContext.classList }
+						term={ term }
+					/>
+				) : null }
+				<MemoizedTermTemplateBlockPreview
+					blocks={ blocks }
+					blockContextId={ term.id }
+					classList={ blockContext.classList }
+					setActiveBlockContextId={ setActiveBlockContextId }
+					isHidden={
+						term.id ===
+						( activeBlockContextId || blockContexts[ 0 ]?.termId )
+					}
+					termName={ term.name }
+				/>
+			</BlockContextProvider>
+		);
+	};
+
+	const renderTerms = () => {
+		if ( hierarchical ) {
+			const termsTree = buildTermsTree( filteredTerms );
+			return termsTree.map( ( termNode ) =>
+				renderTermNode( termNode, renderTerm )
+			);
+		}
+
+		return blockContexts.map( ( blockContext ) => (
+			<BlockContextProvider
+				key={ blockContext.termId }
+				value={ blockContext }
+			>
+				{ blockContext.termId ===
+				( activeBlockContextId || blockContexts[ 0 ]?.termId ) ? (
+					<TermTemplateInnerBlocks
+						classList={ blockContext.classList }
+						term={ filteredTerms.find(
+							( t ) => t.id === blockContext.termId
+						) }
+					/>
+				) : null }
+				<MemoizedTermTemplateBlockPreview
+					blocks={ blocks }
+					blockContextId={ blockContext.termId }
+					classList={ blockContext.classList }
+					setActiveBlockContextId={ setActiveBlockContextId }
+					isHidden={
+						blockContext.termId ===
+						( activeBlockContextId || blockContexts[ 0 ]?.termId )
+					}
+					termName={
+						filteredTerms.find(
+							( t ) => t.id === blockContext.termId
+						)?.name
+					}
+				/>
+			</BlockContextProvider>
+		) );
+	};
+
+	return (
+		<>
+			<BlockControls>
+				<ToolbarGroup />
+			</BlockControls>
+
+			<div { ...blockProps }>
+				<ul>{ renderTerms() }</ul>
+			</div>
+		</>
+	);
+}