@wordpress/block-library 9.31.0 → 9.31.1-next.f56bd8138.0

package/src/term-description/use-term-description.js

@@ -0,0 +1,109 @@
+/**
+ * WordPress dependencies
+ */
+import { store as coreStore, useEntityProp } from '@wordpress/core-data';
+import { useSelect } from '@wordpress/data';
+
+/**
+ * Hook to fetch term description based on context or fallback to template parsing.
+ *
+ * This hook prioritizes context-provided termId and taxonomy, but falls back to
+ * template-based detection when no context is available.
+ *
+ * @param {string|number} termId   The term ID from context
+ * @param {string}        taxonomy The taxonomy name from context
+ */
+export function useTermDescription( termId, taxonomy ) {
+	const [ description, setDescription, fullDescription ] = useEntityProp(
+		'taxonomy',
+		taxonomy,
+		'description',
+		termId
+	);
+
+	// Fallback approach: Parse template slug when no context is available.
+	const templateBasedData = useTemplateBasedTermData();
+
+	const hasContext = Boolean( termId && taxonomy );
+
+	return {
+		hasContext,
+		setDescription,
+		termDescription: hasContext
+			? fullDescription?.rendered || description || ''
+			: templateBasedData,
+	};
+}
+
+/**
+ * Fallback hook to fetch term data from template context (backward compatibility).
+ * This maintains the same logic as the original implementation for cases where
+ * no termId/taxonomy context is provided.
+ */
+function useTemplateBasedTermData() {
+	const templateSlug = useSelect( ( select ) => {
+		// Access core/editor by string to avoid @wordpress/editor dependency.
+		// eslint-disable-next-line @wordpress/data-no-store-string-literals
+		const { getCurrentPostId, getCurrentPostType, getCurrentTemplateId } =
+			select( 'core/editor' );
+		const currentPostType = getCurrentPostType();
+		const templateId =
+			getCurrentTemplateId() ||
+			( currentPostType === 'wp_template' ? getCurrentPostId() : null );
+
+		return templateId
+			? select( coreStore ).getEditedEntityRecord(
+					'postType',
+					'wp_template',
+					templateId
+			  )?.slug
+			: null;
+	}, [] );
+
+	const taxonomyMatches = templateSlug?.match(
+		/^(category|tag|taxonomy-([^-]+))$|^(((category|tag)|taxonomy-([^-]+))-(.+))$/
+	);
+
+	let taxonomy;
+	let termSlug;
+
+	if ( taxonomyMatches ) {
+		// If it's for all taxonomies of a type (e.g., category, tag).
+		if ( taxonomyMatches[ 1 ] ) {
+			taxonomy = taxonomyMatches[ 2 ]
+				? taxonomyMatches[ 2 ]
+				: taxonomyMatches[ 1 ];
+		}
+		// If it's for a specific term (e.g., category-news, tag-featured).
+		else if ( taxonomyMatches[ 3 ] ) {
+			taxonomy = taxonomyMatches[ 6 ]
+				? taxonomyMatches[ 6 ]
+				: taxonomyMatches[ 4 ];
+			termSlug = taxonomyMatches[ 7 ];
+		}
+
+		taxonomy = taxonomy === 'tag' ? 'post_tag' : taxonomy;
+	}
+
+	return useSelect(
+		( select ) => {
+			if ( ! taxonomy || ! termSlug ) {
+				return '';
+			}
+
+			const { getEntityRecords } = select( coreStore );
+
+			const termRecords = getEntityRecords( 'taxonomy', taxonomy, {
+				slug: termSlug,
+				per_page: 1,
+			} );
+
+			if ( termRecords && termRecords[ 0 ] ) {
+				return termRecords[ 0 ].description || '';
+			}
+
+			return '';
+		},
+		[ taxonomy, termSlug ]
+	);
+}

package/src/term-template/block.json

@@ -8,7 +8,7 @@
 	"ancestor": [ "core/terms-query" ],
 	"description": "Contains the block elements used to render a taxonomy term, like the name, description, and more.",
 	"textdomain": "default",
-	"usesContext": [ "termQuery" ],
+	"usesContext": [ "termQuery", "termsToShow" ],
 	"attributes": {
 		"namespace": {
 			"type": "string"

package/src/term-template/edit.js

@@ -191,13 +191,13 @@ export default function TermTemplateEdit( {
 	clientId,
 	setAttributes,
 	context: {
+		termsToShow,
 		termQuery: {
 			taxonomy,
 			order,
 			orderBy,
 			hideEmpty,
 			hierarchical,
-			parent,
 			perPage = 10,
 		} = {},
 	},
@@ -222,13 +222,18 @@ export default function TermTemplateEdit( {
 		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;
+		if ( ! terms ) {
+			return [];
 		}
-		return terms.filter( ( term ) => ! term.parent );
-	}, [ terms, parent ] );
+		if ( termsToShow === 'top-level' ) {
+			return terms.filter( ( term ) => ! term.parent );
+		}
+		if ( termsToShow === 'subterms' ) {
+			return terms.filter( ( term ) => term.parent );
+		}
+		return terms;
+	}, [ terms, termsToShow ] );
 
 	const { blocks, variations, defaultVariation } = useSelect(
 		( select ) => {

package/src/term-template/index.php

@@ -27,7 +27,8 @@ function render_block_core_term_template( $attributes, $content, $block ) {
 		return '';
 	}
 
-	$query = $query_block_context['termQuery'];
+	$query         = $query_block_context['termQuery'];
+	$terms_to_show = $query_block_context['termsToShow'] ?? 'all';
 
 	$query_args = array(
 		'taxonomy'   => $query['taxonomy'] ?? 'category',
@@ -39,13 +40,18 @@ function render_block_core_term_template( $attributes, $content, $block ) {
 		'exclude'    => $query['exclude'] ?? array(),
 	);
 
-	// Handle parent.
-	if ( ! empty( $query['hierarchical'] ) && isset( $query['parent'] ) ) {
-		$query_args['parent'] = $query['parent'];
-	} elseif ( ! empty( $query['hierarchical'] ) ) {
+	// We set parent to 0 only if we show all terms as hierarchical or we show top-level terms.
+	if ( ( 'all' === $terms_to_show && ! empty( $query['hierarchical'] ) ) || 'top-level' === $terms_to_show ) {
 		$query_args['parent'] = 0;
-	} elseif ( isset( $query['parent'] ) ) {
-		$query_args['parent'] = $query['parent'];
+	} elseif ( 'subterms' === $terms_to_show ) {
+		// Check if we're in a taxonomy archive context.
+		if ( is_tax( $query_args['taxonomy'] ) ) {
+			// Get the current term ID from the queried object.
+			$current_term_id = get_queried_object_id();
+			if ( $current_term_id && $current_term_id > 0 ) {
+				$query_args['parent'] = $current_term_id;
+			}
+		}
 	}
 
 	$terms_query = new WP_Term_Query( $query_args );

package/src/terms-query/block.json

@@ -23,10 +23,15 @@
 				"hideEmpty": true,
 				"include": [],
 				"exclude": [],
-				"parent": 0,
+				"parent": false,
 				"hierarchical": false
 			}
 		},
+		"termsToShow": {
+			"type": "string",
+			"default": "all",
+			"enum": [ "all", "top-level", "subterms" ]
+		},
 		"tagName": {
 			"type": "string",
 			"default": "div"
@@ -37,7 +42,8 @@
 	},
 	"providesContext": {
 		"termQueryId": "termQueryId",
-		"termQuery": "termQuery"
+		"termQuery": "termQuery",
+		"termsToShow": "termsToShow"
 	},
 	"supports": {
 		"align": [ "wide", "full" ],

package/src/terms-query/inspector-controls/advanced-controls.js

@@ -0,0 +1,37 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	InspectorControls,
+	privateApis as blockEditorPrivateApis,
+} from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../lock-unlock';
+
+const { HTMLElementControl } = unlock( blockEditorPrivateApis );
+
+export default function AdvancedControls( {
+	TagName,
+	setAttributes,
+	clientId,
+} ) {
+	return (
+		<InspectorControls group="advanced">
+			<HTMLElementControl
+				tagName={ TagName }
+				onChange={ ( value ) => setAttributes( { tagName: value } ) }
+				clientId={ clientId }
+				options={ [
+					{ label: __( 'Default (<div>)' ), value: 'div' },
+					{ label: '<main>', value: 'main' },
+					{ label: '<section>', value: 'section' },
+					{ label: '<aside>', value: 'aside' },
+				] }
+			/>
+		</InspectorControls>
+	);
+}

package/src/terms-query/inspector-controls/display-options.js

@@ -0,0 +1,87 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	RadioControl,
+} from '@wordpress/components';
+
+const getOptions = ( displayTopLevelControl, displaySubtermsControl ) => {
+	const options = [ { label: __( 'Show all' ), value: 'all' } ];
+
+	if ( displayTopLevelControl ) {
+		options.push( {
+			label: __( 'Show only top level terms' ),
+			value: 'top-level',
+		} );
+	}
+
+	if ( displaySubtermsControl ) {
+		options.push( {
+			label: __( 'Show subterms only' ),
+			value: 'subterms',
+			description: __(
+				'Display subterms of the current term. E.g. subcategories of current category.'
+			),
+		} );
+	}
+
+	return options;
+};
+
+const allTermsQuery = {
+	include: [],
+	exclude: [],
+	parent: false,
+};
+
+const topLevelTermsQuery = {
+	include: [],
+	exclude: [],
+	parent: 0,
+	hierarchical: false,
+};
+
+const getQueryAttributes = ( value ) => {
+	if ( value === 'top-level' ) {
+		return topLevelTermsQuery;
+	}
+
+	// For 'all' and 'subterms', we fetch all terms and then filter them as the tree is built in Term Template.
+	return allTermsQuery;
+};
+
+export default function DisplayOptions( {
+	attributes,
+	displayTopLevelControl,
+	displaySubtermsControl,
+	setAttributes,
+} ) {
+	const { termQuery, termsToShow } = attributes;
+
+	return (
+		<ToolsPanelItem
+			hasValue={ () => termsToShow !== 'all' }
+			label={ __( 'Terms to show' ) }
+			onDeselect={ () => setAttributes( { termsToShow: 'all' } ) }
+			isShownByDefault
+		>
+			<RadioControl
+				label={ __( 'Terms to show' ) }
+				options={ getOptions(
+					displayTopLevelControl,
+					displaySubtermsControl
+				) }
+				selected={ termsToShow }
+				onChange={ ( value ) => {
+					const queryAttributes = getQueryAttributes( value );
+					setAttributes( {
+						termsToShow: value,
+						termQuery: { ...termQuery, ...queryAttributes },
+					} );
+				} }
+			/>
+		</ToolsPanelItem>
+	);
+}

package/src/terms-query/inspector-controls/empty-terms-control.js

@@ -0,0 +1,30 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	ToggleControl,
+} from '@wordpress/components';
+
+export default function EmptyTermsControl( { attributes, setQuery } ) {
+	const { termQuery } = attributes;
+
+	return (
+		<ToolsPanelItem
+			hasValue={ () => termQuery.hideEmpty !== true }
+			label={ __( 'Show empty terms' ) }
+			onDeselect={ () => setQuery( { hideEmpty: true } ) }
+			isShownByDefault
+		>
+			<ToggleControl
+				__nextHasNoMarginBottom
+				label={ __( 'Show empty terms' ) }
+				checked={ ! termQuery.hideEmpty }
+				onChange={ ( showEmpty ) =>
+					setQuery( { hideEmpty: ! showEmpty } )
+				}
+			/>
+		</ToolsPanelItem>
+	);
+}

package/src/terms-query/inspector-controls/hierarchy-control.js

@@ -0,0 +1,30 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	ToggleControl,
+} from '@wordpress/components';
+
+export default function HierarchyControl( { attributes, setQuery } ) {
+	const { termQuery } = attributes;
+
+	return (
+		<ToolsPanelItem
+			hasValue={ () => termQuery.hierarchical !== false }
+			label={ __( 'Show hierarchy' ) }
+			onDeselect={ () => setQuery( { hierarchical: false } ) }
+			isShownByDefault
+		>
+			<ToggleControl
+				__nextHasNoMarginBottom
+				label={ __( 'Show hierarchy' ) }
+				checked={ termQuery.hierarchical }
+				onChange={ ( hierarchical ) => {
+					setQuery( { hierarchical } );
+				} }
+			/>
+		</ToolsPanelItem>
+	);
+}

package/src/terms-query/inspector-controls/index.js

@@ -0,0 +1,137 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { __experimentalToolsPanel as ToolsPanel } from '@wordpress/components';
+import { InspectorControls } from '@wordpress/block-editor';
+import { store as coreStore } from '@wordpress/core-data';
+import { useSelect } from '@wordpress/data';
+import { useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { useToolsPanelDropdownMenuProps } from '../../utils/hooks';
+import TaxonomyControl from './taxonomy-control';
+import OrderingControls from './ordering-controls';
+import DisplayOptions from './display-options';
+import HierarchyControl from './hierarchy-control';
+import EmptyTermsControl from './empty-terms-control';
+import MaxTermsControl from './max-terms-control';
+import AdvancedControls from './advanced-controls';
+
+const usePublicTaxonomies = () => {
+	const taxonomies = useSelect(
+		( select ) => select( coreStore ).getTaxonomies( { per_page: -1 } ),
+		[]
+	);
+	return useMemo( () => {
+		return (
+			taxonomies?.filter(
+				( { visibility } ) => visibility?.publicly_queryable
+			) || []
+		);
+	}, [ taxonomies ] );
+};
+
+export default function TermsQueryInspectorControls( {
+	attributes,
+	setQuery,
+	setAttributes,
+	TagName,
+	clientId,
+} ) {
+	const { termQuery, termsToShow } = attributes;
+	const dropdownMenuProps = useToolsPanelDropdownMenuProps();
+	const taxonomies = usePublicTaxonomies();
+
+	const { templateSlug } = useSelect( ( select ) => {
+		// @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.
+		// The solution here is to split WP specific blocks from generic blocks.
+		// eslint-disable-next-line @wordpress/data-no-store-string-literals
+		const { getEditedPostSlug } = select( 'core/editor' );
+		return {
+			templateSlug: getEditedPostSlug(),
+		};
+	}, [] );
+
+	const taxonomyOptions = taxonomies.map( ( taxonomy ) => ( {
+		label: taxonomy.name,
+		value: taxonomy.slug,
+	} ) );
+
+	const isTaxonomyHierarchical = taxonomies.find(
+		( taxonomy ) => taxonomy.slug === termQuery.taxonomy
+	)?.hierarchical;
+
+	const isTaxonomyMatchingTemplate =
+		typeof templateSlug === 'string' &&
+		templateSlug.includes( termQuery.taxonomy );
+
+	const displaySubtermsControl =
+		isTaxonomyHierarchical && isTaxonomyMatchingTemplate;
+
+	return (
+		<>
+			<InspectorControls>
+				<ToolsPanel
+					label={ __( 'Terms Query Settings' ) }
+					resetAll={ () => {
+						setAttributes( {
+							termQuery: {
+								taxonomy: 'category',
+								order: 'asc',
+								orderBy: 'name',
+								hideEmpty: true,
+								hierarchical: false,
+								parent: false,
+								perPage: 10,
+							},
+							termsToShow: 'all',
+						} );
+					} }
+					dropdownMenuProps={ dropdownMenuProps }
+				>
+					<TaxonomyControl
+						attributes={ attributes }
+						setQuery={ setQuery }
+						setAttributes={ setAttributes }
+						taxonomyOptions={ taxonomyOptions }
+					/>
+					<OrderingControls
+						attributes={ attributes }
+						setQuery={ setQuery }
+					/>
+					<EmptyTermsControl
+						attributes={ attributes }
+						setQuery={ setQuery }
+					/>
+					<DisplayOptions
+						attributes={ attributes }
+						setAttributes={ setAttributes }
+						displayTopLevelControl={ isTaxonomyHierarchical }
+						displaySubtermsControl={ displaySubtermsControl }
+					/>
+					<MaxTermsControl
+						attributes={ attributes }
+						setQuery={ setQuery }
+					/>
+					{ isTaxonomyHierarchical && termsToShow === 'all' && (
+						<HierarchyControl
+							attributes={ attributes }
+							setQuery={ setQuery }
+						/>
+					) }
+				</ToolsPanel>
+			</InspectorControls>
+			<AdvancedControls
+				TagName={ TagName }
+				setAttributes={ setAttributes }
+				clientId={ clientId }
+			/>
+		</>
+	);
+}

package/src/terms-query/inspector-controls/max-terms-control.js

@@ -0,0 +1,44 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	RangeControl,
+} from '@wordpress/components';
+
+export default function MaxTermsControl( { attributes, setQuery } ) {
+	const { termQuery } = attributes;
+
+	// Only show pagination control when not hierarchical.
+	if ( termQuery.hierarchical ) {
+		return null;
+	}
+
+	return (
+		<ToolsPanelItem
+			hasValue={ () => termQuery.perPage !== 10 }
+			label={ __( 'Max terms' ) }
+			onDeselect={ () => setQuery( { perPage: 10 } ) }
+			isShownByDefault
+		>
+			<RangeControl
+				__nextHasNoMarginBottom
+				__next40pxDefaultSize
+				label={ __( 'Max terms' ) }
+				value={ termQuery.perPage }
+				min={ 0 }
+				max={ 100 }
+				onChange={ ( perPage ) => {
+					// Show all terms (-1) when 0 is selected.
+					setQuery( {
+						perPage: perPage === 0 ? -1 : perPage,
+					} );
+				} }
+				help={ __(
+					'Limit the number of terms you want to show. To show all terms, use 0 (zero).'
+				) }
+			/>
+		</ToolsPanelItem>
+	);
+}

package/src/terms-query/inspector-controls/ordering-controls.js

@@ -0,0 +1,55 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	SelectControl,
+} from '@wordpress/components';
+
+export default function OrderingControls( { attributes, setQuery } ) {
+	const { termQuery } = attributes;
+
+	return (
+		<ToolsPanelItem
+			hasValue={ () =>
+				termQuery.orderBy !== 'name' || termQuery.order !== 'asc'
+			}
+			label={ __( 'Order by' ) }
+			onDeselect={ () => setQuery( { orderBy: 'name', order: 'asc' } ) }
+			isShownByDefault
+		>
+			<SelectControl
+				__nextHasNoMarginBottom
+				__next40pxDefaultSize
+				label={ __( 'Order by' ) }
+				options={ [
+					{
+						label: __( 'Name: A → Z' ),
+						value: 'name/asc',
+					},
+					{
+						label: __( 'Name: Z → A' ),
+						value: 'name/desc',
+					},
+					{
+						label: __( 'Count, high to low' ),
+						value: 'count/desc',
+					},
+					{
+						label: __( 'Count, low to high' ),
+						value: 'count/asc',
+					},
+				] }
+				value={ termQuery.orderBy + '/' + termQuery.order }
+				onChange={ ( orderBy ) => {
+					const [ newOrderBy, newOrder ] = orderBy.split( '/' );
+					setQuery( {
+						orderBy: newOrderBy,
+						order: newOrder,
+					} );
+				} }
+			/>
+		</ToolsPanelItem>
+	);
+}

package/src/terms-query/inspector-controls/taxonomy-control.js

@@ -0,0 +1,41 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import {
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	SelectControl,
+} from '@wordpress/components';
+
+export default function TaxonomyControl( {
+	attributes,
+	setQuery,
+	setAttributes,
+	taxonomyOptions,
+} ) {
+	const { termQuery } = attributes;
+
+	return (
+		<ToolsPanelItem
+			hasValue={ () => termQuery.taxonomy !== 'category' }
+			label={ __( 'Taxonomy' ) }
+			onDeselect={ () => {
+				setQuery( { taxonomy: 'category' } );
+				setAttributes( { termsToShow: 'all' } );
+			} }
+			isShownByDefault
+		>
+			<SelectControl
+				__nextHasNoMarginBottom
+				__next40pxDefaultSize
+				label={ __( 'Taxonomy' ) }
+				options={ taxonomyOptions }
+				value={ termQuery.taxonomy }
+				onChange={ ( selectedTaxonomy ) => {
+					setQuery( { taxonomy: selectedTaxonomy } );
+					setAttributes( { termsToShow: 'all' } );
+				} }
+			/>
+		</ToolsPanelItem>
+	);
+}