retrofox · Jul 3, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
@@ -207,6 +207,10 @@ public function prepare_item_for_response( $item, $request ) {
 				$data['description'] = $widget_type->description;
 			}
 
+			if ( rest_is_field_included( 'help', $fields ) ) {
+				$data['help'] = $widget_type->help;
+			}
+
 			if ( rest_is_field_included( 'keywords', $fields ) ) {
 				$data['keywords'] = $widget_type->keywords;
 			}
@@ -283,6 +287,30 @@ public function get_item_schema() {
 						'readonly'    => true,
 					),
 
+					'help'          => array(
+						'description' => __( 'Contextual help note for the widget type: content plus optional links. Translatable.', 'gutenberg' ),
+						'type'        => array( 'object', 'null' ),
+						'properties'  => array(
+							'content' => array(
+								'description' => __( 'Help content; may carry minimal inline emphasis.', 'gutenberg' ),
+								'type'        => 'string',
+							),
+							'links'   => array(
+								'description' => __( 'Optional links contextual to the help content.', 'gutenberg' ),
+								'type'        => 'array',
+								'items'       => array(
+									'type'       => 'object',
+									'properties' => array(
+										'label' => array( 'type' => 'string' ),
+										'href'  => array( 'type' => 'string' ),
+									),
+								),
+							),
+						),
+						'context'     => array( 'view', 'edit', 'embed' ),
+						'readonly'    => true,
+					),
+
 					'keywords'      => array(
 						'description' => __( 'Alternative terms used to match the widget type when searching, e.g. "calendar" for an events widget. Translatable.', 'gutenberg' ),
 						'type'        => array( 'array', 'null' ),

@@ -97,6 +97,16 @@ class WP_Widget_Type {
 		 */
 		public $description = null;
 
+		/**
+		 * Contextual help note: `content` plus optional `links`.
+		 * Translated at registration time using the widget's text domain.
+		 *
+		 * Null when the widget did not declare the field.
+		 *
+		 * @var array|null
+		 */
+		public $help = null;
+
 		/**
 		 * Alternative terms used to match the widget type when searching,
 		 * e.g. "calendar" for an events widget. Translated at registration

@@ -1,5 +1,9 @@
 {
 	"title": "widget title",
 	"description": "widget description",
+	"help": {
+		"content": "widget help content",
+		"links": [ { "label": "widget help link label" } ]
+	},
 	"keywords": [ "widget keyword" ]
 }
@@ -20,15 +20,18 @@
  * translatable and the gettext context to use for each.
  *
  * Read once from widget-i18n.json and memoized for the rest of the request.
+ * Decoded as objects, not associative arrays: that is how
+ * `translate_settings_using_i18n_schema()` tells keyed maps apart from
+ * lists.
  *
- * @return array Map of translatable field name to gettext context.
+ * @return object Map of translatable field name to gettext context.
  */
 function gutenberg_get_widget_metadata_i18n_schema() {
 	static $i18n_schema = null;
 
 	if ( null === $i18n_schema ) {
-		$schema      = wp_json_file_decode( __DIR__ . '/widget-i18n.json', array( 'associative' => true ) );
-		$i18n_schema = is_array( $schema ) ? $schema : array();
+		$schema      = wp_json_file_decode( __DIR__ . '/widget-i18n.json' );
+		$i18n_schema = is_object( $schema ) ? $schema : new stdClass();
 	}
 
 	return $i18n_schema;
@@ -37,9 +40,9 @@ function gutenberg_get_widget_metadata_i18n_schema() {
 /**
  * Translates a widget's user-facing metadata strings.
  *
- * Runs `title`, `description`, and `keywords` through the widget i18n schema
- * using the widget's `textdomain`, leaving every other key untouched. A no-op
- * when the widget declares no `textdomain`.
+ * Runs `title`, `description`, `help`, and `keywords` through the widget
+ * i18n schema using the widget's `textdomain`, leaving every other key
+ * untouched. A no-op when the widget declares no `textdomain`.
  *
  * @param array $widget Widget data from the build manifest.
  * @return array Widget data with its translatable strings localized.
@@ -52,15 +55,57 @@ function gutenberg_translate_widget_metadata( $widget ) {
 
 	$i18n_schema = gutenberg_get_widget_metadata_i18n_schema();
 
-	foreach ( array( 'title', 'description', 'keywords' ) as $field ) {
-		if ( isset( $widget[ $field ], $i18n_schema[ $field ] ) ) {
-			$widget[ $field ] = translate_settings_using_i18n_schema( $i18n_schema[ $field ], $widget[ $field ], $textdomain );
+	foreach ( array( 'title', 'description', 'help', 'keywords' ) as $field ) {
+		if ( isset( $widget[ $field ], $i18n_schema->$field ) ) {
+			$widget[ $field ] = translate_settings_using_i18n_schema( $i18n_schema->$field, $widget[ $field ], $textdomain );
 		}
 	}
 
 	return $widget;
 }
 
+/**
+ * Constrains a widget help note to its allowed shape: `content` keeps
+ * only `em`/`strong` markup, and links missing a `label` or `href` are
+ * dropped.
+ *
+ * @param array|null $help Help note from the build manifest.
+ * @return array|null Sanitized help note, or null when there is no content.
+ */
+function gutenberg_sanitize_widget_help( $help ) {
+	if ( ! is_array( $help ) || empty( $help['content'] ) || ! is_string( $help['content'] ) ) {
+		return null;
+	}
+
+	$sanitized = array(
+		'content' => wp_kses(
+			$help['content'],
+			array(
+				'em'     => array(),
+				'strong' => array(),
+			)
+		),
+	);
+
+	if ( ! empty( $help['links'] ) && is_array( $help['links'] ) ) {
+		$links = array();
+		foreach ( $help['links'] as $link ) {
+			if ( is_array( $link ) && ! empty( $link['label'] ) && ! empty( $link['href'] ) ) {
+				$links[] = array(
+					'label' => $link['label'],
+					'href'  => $link['href'],
+				);
+			}
+		}
+
+		if ( $links ) {
+			$sanitized['links'] = $links;
+		}
+	}
+
+	return $sanitized;
+}
+
 /**
  * Hydrates the widget type registry from the build manifest.
  *
@@ -93,6 +138,7 @@ function gutenberg_register_widget_types() {
 				'category'      => $widget['category'] ?? null,
 				'title'         => $widget['title'] ?? null,
 				'description'   => $widget['description'] ?? null,
+				'help'          => gutenberg_sanitize_widget_help( $widget['help'] ?? null ),
 				'keywords'      => $widget['keywords'] ?? null,
 			)
 		);

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Enhancements
+
+-   `WidgetHeader`: surface the widget type's `help` note as an infotip
+    beside the title: a click-open popover with the note and its links.
+
 ## 0.2.0 (2026-07-01)
 
 ## 0.1.0 (2026-06-24)

@@ -0,0 +1,82 @@
+/**
+ * WordPress dependencies
+ */
+import { createInterpolateElement } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { info } from '@wordpress/icons';
+// eslint-disable-next-line @wordpress/use-recommended-components
+import { Icon, Link, Popover, Stack, VisuallyHidden } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import styles from './widget-header.module.css';
+
+export interface WidgetInfotipProps {
+	/**
+	 * Help content to display; may carry `<em>`/`<strong>`.
+	 */
+	content: string;
+
+	/**
+	 * Links rendered after the content.
+	 */
+	links?: {
+		label: string;
+		href: string;
+	}[];
+}
+
+/**
+ * Header infotip: a click-open popover holding the widget type's help note.
+ *
+ * @param {WidgetInfotipProps} props Component props.
+ */
+export function WidgetInfotip( {
+	content,
+	links,
+}: WidgetInfotipProps ): React.ReactNode {
+	return (
+		<Popover.Root modal="trap-focus">
+			<Popover.Trigger
+				aria-label={ __( 'More information' ) }
+				className={ styles.help }
+			>
+				<Icon icon={ info } size={ 20 } />
+			</Popover.Trigger>
+
+			<Popover.Popup
+				className={ styles.popoverPopup }
+				positioner={ <Popover.Positioner side="top" align="start" /> }
+			>
+				<Popover.Arrow />
+				<VisuallyHidden render={ <Popover.Title /> }>
+					{ __( 'More information' ) }
+				</VisuallyHidden>
+
+				<Stack direction="column" align="start" gap="sm">
+					<Popover.Description>
+						{ createInterpolateElement( content, {
+							em: <em />,
+							strong: <strong />,
+						} ) }
+					</Popover.Description>
+
+					{ links && links.length > 0 && (
+						<Stack direction="row" align="start" gap="sm">
+							{ links.map( ( link ) => (
+								<Link
+									key={ link.href }
+									href={ link.href }
+									className={ styles.link }
+								>
+									{ link.label }
+								</Link>
+							) ) }
+						</Stack>
+					) }
+				</Stack>
+			</Popover.Popup>
+		</Popover.Root>
+	);
+}
@@ -29,6 +29,31 @@
 	color: var(--wpds-color-foreground-content-neutral);
 }
 
+.popoverPopup {
+	max-width: 300px;
+}
+
+/**
+ * Infotip trigger: a bare icon button beside the title.
+ */
+.help {
+	display: inline-flex;
+	align-items: center;
+	padding: 0;
+	border: 0;
+	background: none;
+	color: var(--wpds-color-foreground-content-neutral-weak);
+	cursor: var(--wpds-cursor-control);
+}
+
+/**
+ * Divide adjacent links in the infotip.
+ */
+.link + .link {
+	border-inline-start: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
+	padding-inline-start: var(--wpds-dimension-gap-sm);
+}
+
 .toolbar {
 	margin-inline-start: auto;
 }

@@ -13,11 +13,13 @@ import type { WidgetType } from '@wordpress/widget-primitives';
 /**
  * Internal dependencies
  */
+import { WidgetInfotip } from './widget-header-infotip';
 import styles from './widget-header.module.css';
 
 export interface WidgetHeaderProps {
 	/**
-	 * Widget type, source of the icon and title shown as identity.
+	 * Widget type, source of the icon, title, and help note shown as
+	 * identity.
 	 */
 	widgetType?: WidgetType;
 
@@ -83,8 +85,16 @@ export function WidgetHeader( {
 					<Card.Title id={ titleId } render={ <h2 /> }>
 						{ widgetType.title }
 					</Card.Title>
+
+					{ widgetType.help && (
+						<WidgetInfotip
+							content={ widgetType.help.content }
+							links={ widgetType.help.links }
+						/>
+					) }
 				</Stack>
 			) }
+
 			{ children && <div className={ styles.toolbar }>{ children }</div> }
 		</Card.Header>
 	);

@@ -45,6 +45,10 @@ const widgetTypes: WidgetType[] = [
 		apiVersion: 1,
 		name: 'test/greet',
 		title: 'Greet',
+		help: {
+			content: 'Greetings at a glance.',
+			links: [ { label: 'Learn more', href: 'options-general.php' } ],
+		},
 		renderModule: 'test-greet-module',
 	},
 ];
@@ -101,6 +105,26 @@ describe( 'WidgetDashboard', () => {
 		);
 	} );
 
+	it( 'surfaces the widget type help note in the header', async () => {
+		render( <Harness /> );
+
+		// The infotip trigger opens a popover holding the note.
+		await userEvent.click(
+			await screen.findByRole( 'button', {
+				name: 'More information',
+			} )
+		);
+
+		expect(
+			await screen.findByText( 'Greetings at a glance.' )
+		).toBeInTheDocument();
+
+		// The note's declared links render in the popover.
+		expect(
+			screen.getByRole( 'link', { name: 'Learn more' } )
+		).toBeInTheDocument();
+	} );
+
 	it( 'threads setAttributes into onLayoutChange on commit with merged attributes', async () => {
 		const onChange = jest.fn();
 		render( <Harness onLayoutChange={ onChange } /> );

@@ -16,6 +16,10 @@
 -   `WidgetModuleRecord`: add optional `title`, `description`, and
     `keywords`, overlaid onto the metadata module's values. Lets a host
     supply metadata translated server-side.
+-   `WidgetTypeMetadata`: add optional `help`, a declarative contextual
+    note (`content` plus optional `links`) for compact surfaces such as
+    tooltips. Also carried by `WidgetModuleRecord`, overlaid onto the
+    metadata module's value.
 
 ## 0.2.0 (2026-07-01)
 

@@ -80,6 +80,7 @@ export function useWidgetTypes(
 						...( record.description
 							? { description: record.description }
 							: {} ),
+						...( record.help ? { help: record.help } : {} ),
 						...( record.keywords
 							? { keywords: record.keywords }
 							: {} ),

@@ -12,7 +12,7 @@ The three layers are what a widget _is_, how it _asks_ to be framed, and what it
 
 ## Identity
 
-What the widget is: `name`, `title`, `description`, `icon`, `category`, `keywords`.
+What the widget is: `name`, `title`, `description`, `help`, `icon`, `category`, `keywords`.
 
 The host shows this almost verbatim, in pickers, headers, and help. It decides _where_ identity appears and _whether_ to show it, never _what it says_. Identity is copied, not interpreted: two hosts displaying the same widget show the same title.