Enhance Term Description Block with Context Support #71525

sunyatasattva · 2025-09-05T20:29:03Z

What?

The term-description block, as opposed to the post-title or the query-title, always showed a placeholder, even when the data was technically available (e.g. if the user was modifying a specific category template).

This PR fixes that by allowing the term-description block to either receive context from a parent (like the post-title), or fallback to the parsing of the template slug (like the query-title).

Why?

Not showing the actual content is not only a degraded user experience (as the user can't preview the template correctly without displaying the actual description), but also inconsistent with the behavior of other blocks.

How?

The PR basically implements already available patterns from post-title and query-title. This allows the block to be quite versatile and reusable in different contexts.

Testing Instructions

Preserving original functionality

Open the All Archives template.
Insert the term-description block.
Verify that it displays a placeholder.

New functionality

Create a new template for a specific Category (with a description).
Insert the term-description block.
Verify that the actual description is shown, and not a placeholder.

- Added `usesContext` to `block.json` for `termId` and `taxonomy`. - Implemented `useTermDescription` hook to fetch term descriptions based on context or fallback to template parsing. - Updated `TermDescriptionEdit` component to display term descriptions or a placeholder based on the fetched data. This improves the block's functionality by allowing it to dynamically retrieve and display term descriptions in various contexts.

github-actions · 2025-09-05T20:29:13Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: sunyatasattva <sunyatasattva@git.wordpress.org>
Co-authored-by: mikachan <mikachan@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

mikachan

This is working great in my testing, nice work! I'm able to see the term description content in both the editor and the front end:

Editor	Front end

And I can see your approach very closely matches the query-title and post-title implementations.

I can only see the tiniest of improvements: we usually end all comments with a full stop.

packages/block-library/src/term-description/use-term-description.js

tyxla · 2025-09-14T15:50:39Z

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

-				</div>
+				{ termDescription ? (
+					<div
+						dangerouslySetInnerHTML={ { __html: termDescription } }


Should this termDescription go through some sanitization before being passed to dangerouslySetInnerHTML?

The term description here uses term_description(), which already applies sanitisation. I don't believe the content can be edited at any other point, so I'm not sure we need additional sanitisation here. This also follows the same pattern as post-content, post-title, and post-author.

tyxla · 2025-09-14T15:57:07Z

packages/block-library/src/term-description/use-term-description.js

+ * This maintains the same logic as the original implementation for cases where
+ * no termId/taxonomy context is provided.
+ */
+function useTemplateBasedTermData() {


So much duplication with useArchiveLabel() here. Could make sense to consider avoiding it and maybe adding some documentation, because it can be particularly difficult to follow some bits, like the regex match processing, for example.

Yes, to be honest, as this was a PR to tentatively dip my feet into something quite spontaneous, that hadn't been previously discussed, I opted for the minimal approach which wouldn't modify anything else.

I suggest that we merge this PR in this state, and then deal with refactoring in a follow-up PR, so we keep things contained.

What do you think? My concern to keep things “atomically testable”: so we make sure this PR does whatever it says it does, and then we move on to touch other parts of the system which will require a different set of tests, and for which we have safe fallback.

Sounds good to me - I'm good with opening an issue so we can follow up on the deduplication at a later point.

tyxla · 2025-09-14T15:58:33Z

packages/block-library/src/term-description/use-term-description.js

+			return {
+				termDescription,
+			};


Same as above, I don't see a good reason to return an object.

I wanted to keep the return type consistent with useArchiveLabel, so that, when used, these kinds of hooks require the least amount of thought from the consumers as possible, and they look more readable together. Pushing a commit to change this, however, we can always revert it to this type if you think my reasoning makes sense.

I think I prefer the flat version 😉

IMO, the only time when an object with a single property is fine is when we expect that the return value will grow in time and we don't yet have the design for it, but we want to minimize breaking changes and integration cost.

tyxla · 2025-09-14T15:59:49Z

packages/block-library/src/term-description/use-term-description.js

+	}, [] );
+
+	const taxonomyMatches = templateSlug?.match(
+		/^(category|tag|taxonomy-([^-]+))$|^(((category|tag)|taxonomy-([^-]+))-(.+))$/


Would love to see this documented. At first glance, the category|tag|taxonomy- vs (category|tag)|taxonomy- looks like a mistake.

This is the same RegEx used in useArchiveLabel, copy+pasted. See my comment above about refactoring: I think in a followup PR we can consolidate and document.

(Besides, I see some dirty code in useArchiveLabel anyways that could use a cleanup PR).

Yeah, happy to have that in a follow up 👍 just let's make sure it doesn't fall through the cracks (document it in an issue or in TODO as a comment)

tyxla · 2025-09-14T16:02:20Z

packages/block-library/src/term-description/use-term-description.js

+		// 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' );


I do think this is a bit messed up. We don't really avoid a @wordpress/editor dependency, do we? So why pretend? Looks like something we should address further down the line.

I think we're mainly avoiding @wordpress/block-library from being dependent on @wordpress/editor, as blocks can be loaded into a non-post block editor. We're doing something similar for useArchiveLabel(), so if we're going to address this in a different way, then perhaps we could handle both of these cases at once in a separate PR (and probably a few other similar cases).

Makes sense and sounds good to be addressed together and separately from this PR.

tyxla · 2025-09-14T16:03:32Z

packages/block-library/src/term-description/use-term-description.js

+	const hasContext = Boolean( termId && taxonomy );
+
+	return {
+		hasContext,


Why do we need to expose hasContext?

I'm guessing this might be for extensibility reasons, but I'm sure @sunyatasattva can confirm.

Yes, exactly. This was added to make sure that, downstream, the block can know whether the result of the content is coming from the template data or from the passed down context. This is useful when this block is going to be used as an inner block of some arbitrary parent (in one example case: Featured Category block in WooCommerce).

tyxla · 2025-09-14T16:04:47Z

packages/block-library/src/term-description/use-term-description.js

+		hasContext,
+		setDescription,
+		termDescription: hasContext
+			? fullDescription?.rendered || description || ''


Should the empty string fallback be at the end of all the logic?

Mm, not sure I get what you mean. You mean after the whole ternary? Because the other side of the ternary (templateBasedData) already falls back to an empty string.

I'm looking at the code and can't recall why I suggested this. Maybe it was because of the '' fallbacks in other places in the code. Feel free to disregard 👍

tyxla · 2025-09-14T16:05:38Z

packages/block-library/src/term-description/use-term-description.js

+	return useSelect(
+		( select ) => {
+			if ( ! taxonomy || ! termSlug ) {
+				return { termDescription: '' };


Why do we need to return an object? Seems like we can just return the string there.

sunyatasattva · 2025-09-22T15:35:23Z

@tyxla @mikachan I pushed the requested changes, let me know if I have to do anything else. Someone else will need to merge as I don't have permission.

tyxla · 2025-09-22T15:38:52Z

I'll let @mikachan do another round of review, as I don't have much review cycles this week - thanks! 🐢

mikachan

All the changes look good to me, thanks @sunyatasattva!

Looks like we have a few follow-up tasks:

Reduce the duplication with useArchiveLabel and useTemplateBasedTermData: #71525 (comment)
Consolidate and document the regex used in both hooks: #71525 (comment)
Address the workarounds for avoiding being dependent on @wordpress/editor in @wordpress/block-library: #71525 (comment)

I think this is ready to bring in 🚢 ✨

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

ntsekouras · 2025-10-10T06:12:56Z

Shouldn't this PR also handle the php rendering of the block when the context is provided?

mikachan · 2025-10-10T09:17:11Z

Shouldn't this PR also handle the php rendering of the block when the context is provided?

I have a fix here: #72238

sunyatasattva requested review from ajitbohra and fabiankaegy as code owners September 5, 2025 20:29

t-hamano added [Type] Enhancement A suggestion for improvement. [Block] Term Description Affects the Term Description Block - used for displaying the description of a tag, catergory or othe labels Sep 11, 2025

tyxla assigned sunyatasattva Sep 12, 2025

tyxla requested review from scruffian, mikachan and MaggieCabrera September 12, 2025 11:25

mikachan mentioned this pull request Sep 12, 2025

Term Query Loop Block #49094

Open

16 tasks

mikachan approved these changes Sep 12, 2025

View reviewed changes

tyxla reviewed Sep 14, 2025

View reviewed changes

sunyatasattva added 2 commits September 22, 2025 17:25

Change return type of useTemplateBasedTermData to string

f602dc8

Add periods at the end of comments

1256a2e

mikachan approved these changes Sep 22, 2025

View reviewed changes

mikachan merged commit e02df75 into WordPress:trunk Sep 22, 2025
69 of 70 checks passed

github-actions bot added this to the Gutenberg 21.8 milestone Sep 22, 2025

sunyatasattva mentioned this pull request Oct 3, 2025

FCB: Transition the block to Inner Blocks woocommerce/woocommerce#60779

Merged

12 tasks

ntsekouras reviewed Oct 6, 2025

View reviewed changes

packages/block-library/src/term-description/edit.js Show resolved Hide resolved

mikachan mentioned this pull request Oct 10, 2025

Term Description: Fix front end context #72238

Merged

Enhance Term Description Block with Context Support #71525

Enhance Term Description Block with Context Support #71525

Conversation

sunyatasattva commented Sep 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Preserving original functionality

New functionality

Uh oh!

github-actions bot commented Sep 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mikachan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sunyatasattva commented Sep 22, 2025

Uh oh!

tyxla commented Sep 22, 2025

Uh oh!

mikachan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ntsekouras commented Oct 10, 2025

Uh oh!

mikachan commented Oct 10, 2025

Uh oh!

Uh oh!

sunyatasattva commented Sep 5, 2025 •

edited

Loading

github-actions bot commented Sep 5, 2025 •

edited

Loading