feat: surface new widget types on user dashboard - #83517

Closes #83441

Surfaces newly registered dashboard widget types to users who have already saved a customized dashboard layout.

Specifically, this PR:

1. Adds presence ('offer' by default, or 'auto') and provenance (plugin name/slug or 'core') to WP_Widget_Type, the REST /wp/v2/widget-modules schema & response, and client-side WidgetType definitions.
2. Tracks knownWidgetTypes in user preferences under core/dashboard, automatically seeded on first visit.
3. Detects newly registered widget types on subsequent dashboard visits (registered - known) and announces them via <InlineNotices />:
   • Widgets with presence: 'offer' (default) provide [Insert] (appends instance to layout) and [Ignore] (dismisses).
   • Widgets with presence: 'auto' automatically append the widget to the layout and provide a notice with a [Remove] action.
   • Interacting with either marks the widget type as known so the notice appears only once.

Why?

When a user customizes their dashboard layout, the layout is saved to user preferences (dashboardLayout). Previously, if a plugin was activated later and registered new widgets, those widget types were never surfaced to the user because their saved layout was locked to the earlier widget set. Users had no easy way of knowing new widgets were available or adding them to their board.

How?

• PHP:
  • lib/experimental/dashboard-widgets/class-wp-widget-type.php: Added presence and provenance properties with normalization.
  • lib/experimental/dashboard-widgets/class-wp-widget-type-registry.php: Automatically resolves caller plugin provenance via backtrace or namespace prefix fallback (ignoring internal Gutenberg frames).
  • lib/experimental/dashboard-widgets/class-wp-rest-widget-modules-controller.php: Added presence and provenance to schema and response item preparation.
  • lib/experimental/dashboard-widgets/dashboard-layout.php: Added GUTENBERG_DASHBOARD_KNOWN_WIDGET_TYPES_KEY = 'knownWidgetTypes'.
  • lib/experimental/dashboard-widgets/widget-types.php: Registered core widgets with 'core' provenance.
• Frontend Packages:
  • packages/widget-primitives: Added presence and provenance to WidgetTypeMetadata, WidgetType, and WidgetModuleRecordOverrides, and threaded them through useWidgetTypes.
  • packages/widget-dashboard: Exported createDashboardWidget for adding instances to layouts.
• Dashboard Route:
  • Added useDashboardUnseenWidgets hook in routes/dashboard/hooks/use-dashboard-unseen-widgets/.
  • Mounted the hook in routes/dashboard/stage.tsx and placed <InlineNotices /> above <WidgetDashboard.Widgets />.
• Tests:
  • Unit tests covering useDashboardUnseenWidgets (seeding, offering new widgets, auto-inserting, dismissal, and removal).
  • Vitest test in packages/widget-primitives for metadata pass-through.
  • PHPUnit tests covering REST controller schema/response and registry provenance resolution.

Testing Instructions

1. Enable the Dashboard Widgets experiment under Gutenberg > Experiments.
2. Navigate to the extensible dashboard at /wp-admin/admin.php?page=dashboard-wp-admin.
3. Open DevTools Console and inspect the stored known widget types:

   wp.data.select( 'core/preferences' ).get( 'core/dashboard', 'knownWidgetTypes' )

   Verify all current widget types are present.
4. Simulate a new plugin registering a widget type (or clear one from known types):

   const current = wp.data.select( 'core/preferences' ).get( 'core/dashboard', 'knownWidgetTypes' );
   wp.data.dispatch( 'core/preferences' ).set( 'core/dashboard', 'knownWidgetTypes', current.filter( id => id !== 'core/activity' ) );

5. Refresh the page.
6. Observe the notice banner above the dashboard widgets announcing the widget.
7. Click Insert — verify an instance is appended to the dashboard and the notice dismisses.
8. Refresh again — verify the notice does not reappear.

Testing Instructions for Keyboard

1. Navigate to the dashboard via keyboard.
2. When the announcement notice appears, press Tab to reach the Insert or Ignore action buttons.
3. Press Enter or Space on either button and verify it activates as expected with proper focus management.

Screencasts

Uploading Screen Recording 2026-09-25 at 11.24.15 AM.mov…