Commit 3539af2

`example`: the attributes hosts preview the widget with, and apply to a new instance created without any, as `{ "attributes": { … } }`. JSON values only, and not translated: example values are data.

`widget.ts` is the live half of the metadata: values that only exist in JavaScript, such as an attribute's `Edit` component or custom validator, or `example` values that need code. It is optional: a widget declared entirely by its manifest ships none, and resolves from its record alone.

`WP_Widget_Type_Registry` (`lib/experimental/dashboard-widgets/`) is a singleton, hydrated at `init` from the manifest. Each entry becomes a `WP_Widget_Type` with `name`, `render_module`, `widget_module`, `presentation`, `category`, `icon`, `example`, and the translatable `title`, `description`, `help`, `actions`, `attributes`, and `keywords` (localized at registration time using the widget's `textdomain`).

- The REST controller (`WP_REST_Widget_Modules_Controller`) exposes it at `/wp/v2/widget-modules`, returning `{ name, render_module, widget_module, presentation, category, title, description, help, icon, actions, attributes, example, keywords }` per record.

`useWidgetTypes( records )` takes the host-supplied records, imports each record's `widget_module` for the live metadata, and merges it with the record into `WidgetType[]`. A record without a metadata module resolves from its own fields, as long as it carries a `render_module`. The record's `presentation`, `category`, `title`, `description`, `help`, `actions`, `attributes`, and `keywords`, all sourced from `widget.json` (with `title`, `description`, `help`, `actions`, `attributes`, and `keywords` localized server-side), win over the module's value. `attributes` merges per entry by `id`: the record wins a shared key, a module entry adds what JSON cannot express, `isValid` merges rule by rule, and module-only entries follow. `example` is the exception: the module's wins, and the record's stands in only when the module declares none, so values that need code stay in the module. The record's `icon` is a registered icon name: the hook resolves it through the application-registered resolver (`registerIconResolver`), and the resolved element wins over a module's element. The hook reaches for no store or endpoint; a host such as the dashboard reads its own `widgetModule` core-data entity (backed by `/wp/v2/widget-modules`) and passes the records in.

if ( rest_is_field_included( 'example', $fields ) ) {

$data['example'] = $widget_type->example;

}

'example' => array(

'description' => __( 'Structured example: the attributes hosts preview the widget type with, and apply to a new instance created without any.', 'gutenberg' ),

'type' => array( 'object', 'null' ),

'properties' => array(

'attributes' => array(

'description' => __( 'Attribute values by attribute name.', 'gutenberg' ),

'type' => 'object',

'additionalProperties' => true,

),

),

'context' => array( 'view', 'edit', 'embed' ),

'readonly' => true,

),

/**

public $example = null;

function gutenberg_is_widget_json_value( $value ) {

if ( is_array( $value ) ) {

foreach ( $value as $item ) {

if ( ! gutenberg_is_widget_json_value( $item ) ) {

return false;

}

}

return true;

}

if ( is_float( $value ) ) {

return is_finite( $value );

}

return null === $value || is_bool( $value ) || is_int( $value ) || is_string( $value );

}

function gutenberg_sanitize_widget_example( $example ) {

if ( ! is_array( $example ) || ! isset( $example['attributes'] ) || ! is_array( $example['attributes'] ) ) {

return null;

}

$attributes = array();

foreach ( $example['attributes'] as $name => $value ) {

if ( ! is_string( $name ) || '' === $name || ! gutenberg_is_widget_json_value( $value ) ) {

continue;

}

$attributes[ $name ] = $value;

}

return $attributes ? array( 'attributes' => $attributes ) : null;

}

'example' => gutenberg_sanitize_widget_example( $widget['example'] ?? null ),

- `WidgetModuleRecord.example`: a record carries the `example` `widget.json` declares, in the shape of the runtime field; `useWidgetTypes` reads it for a record without a metadata module, and when the module declares no `example` of its own ([#85240](https://github.com/WordPress/gutenberg/pull/85240)).

metadata module, when it declares one, and returns the resolved `WidgetType[]`.

It takes host-supplied records (`WidgetModuleRecord[]`, or `null` while loading) and imports each one's metadata module when it declares one. A record without one resolves from its own fields. It returns `[ widgetTypes, isResolvingWidgetTypes ]`; the flag stays `true` until they resolve.

example: { attributes: { location: 'Module', label: 'Store' } },

const exampleRecords: WidgetModuleRecord[] = [

{

...moduleLessRecords[ 0 ],

example: { attributes: { message: 'Hello from the record' } },

},

const moduleWithoutExampleRecords: WidgetModuleRecord[] = [

{

...stringIconRecords[ 0 ],

example: { attributes: { message: 'Hello from the record' } },

},

const moduleExampleRecords: WidgetModuleRecord[] = [

{

...records[ 0 ],

example: { attributes: { location: 'Record' } },

},

it( 'reads the record example without a metadata module', async () => {

const { result } = renderHook( () => useWidgetTypes( exampleRecords ) );

await waitFor( () => expect( result.current[ 1 ] ).toBe( false ) );

expect( result.current[ 0 ][ 0 ].example ).toEqual( {

attributes: { message: 'Hello from the record' },

} );

} );

it( 'falls back to the record example when the module declares none', async () => {

const { result } = renderHook( () =>

useWidgetTypes( moduleWithoutExampleRecords )

);

await waitFor( () => expect( result.current[ 1 ] ).toBe( false ) );

expect( result.current[ 0 ][ 0 ].example ).toEqual( {

attributes: { message: 'Hello from the record' },

} );

} );

it( 'keeps the module example over the record', async () => {

const { result } = renderHook( () =>

useWidgetTypes( moduleExampleRecords )

);

await waitFor( () => expect( result.current[ 1 ] ).toBe( false ) );

expect( result.current[ 0 ][ 0 ].example ).toEqual( {

attributes: { location: 'Module', label: 'Store' },

} );

} );

...( record.example

? { example: record.example }

: {} ),

const example = metadata.example ?? record.example;

...( example ? { example } : {} ),