Enhancement/11433-pue-pointer

assets/js/components/ScrollEffect.js → assets/js/components/CoreDashboardEffects.js

@@ -1,7 +1,7 @@
 /**
- * ScrollEffect component.
+ * CoreDashboardEffects component.
  *
- * Site Kit by Google, Copyright 2022 Google LLC
+ * Site Kit by Google, Copyright 2025 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,9 +19,11 @@
 /**
  * Internal dependencies
  */
+import useOpenEmailReportingSelectionPanelEffect from '@/js/hooks/useOpenEmailReportingSelectionPanelEffect';
 import { useHasScrolledEffect } from '@/js/hooks/useHasScrolledEffect';
 
-export default function ScrollEffect() {
+export default function CoreDashboardEffects() {
+	useOpenEmailReportingSelectionPanelEffect();
 	useHasScrolledEffect();
 
 	return null;

assets/js/components/DashboardEntityApp.js

@@ -57,11 +57,11 @@ import { Cell, Grid, Row } from '@/js/material-components';
 import PageHeader from './PageHeader';
 import Layout from './layout/Layout';
 import { CORE_WIDGETS } from '@/js/googlesitekit/widgets/datastore/constants';
-import ScrollEffect from './ScrollEffect';
 import DashboardSharingSettingsButton from './dashboard-sharing/DashboardSharingSettingsButton';
 import useViewOnly from '@/js/hooks/useViewOnly';
 import OfflineNotification from './notifications/OfflineNotification';
 import { useMonitorInternetConnection } from '@/js/hooks/useMonitorInternetConnection';
+import CoreDashboardEffects from './CoreDashboardEffects';
 import ModuleDashboardEffects from './ModuleDashboardEffects';
 import UserSettingsSelectionPanel from './email-reporting/UserSettingsSelectionPanel';
 import { useFeature } from '@/js/hooks/useFeature';
@@ -144,7 +144,7 @@ function DashboardEntityApp() {
 	if ( currentEntityURL === null ) {
 		return (
 			<div className="googlesitekit-widget-context googlesitekit-module-page googlesitekit-entity-dashboard">
-				<ScrollEffect />
+				<CoreDashboardEffects />
 				<ModuleDashboardEffects />
 				<Grid>
 					<Row>
@@ -217,7 +217,7 @@ function DashboardEntityApp() {
 	}
 	return (
 		<Fragment>
-			<ScrollEffect />
+			<CoreDashboardEffects />
 			<ModuleDashboardEffects />
 			<Header showNavigation>
 				<EntitySearchInput />

assets/js/components/DashboardMainApp.js

@@ -48,7 +48,6 @@ import DateRangeSelector from './DateRangeSelector';
 import HelpMenu from './help/HelpMenu';
 import SurveyViewTrigger from './surveys/SurveyViewTrigger';
 import CurrentSurveyPortal from './surveys/CurrentSurveyPortal';
-import ScrollEffect from './ScrollEffect';
 import MetricsSelectionPanel from './KeyMetrics/MetricsSelectionPanel';
 import UserSettingsSelectionPanel from './email-reporting/UserSettingsSelectionPanel';
 import { useFeature } from '@/js/hooks/useFeature';
@@ -68,6 +67,7 @@ import useViewOnly from '@/js/hooks/useViewOnly';
 import { CORE_FORMS } from '@/js/googlesitekit/datastore/forms/constants';
 import OfflineNotification from './notifications/OfflineNotification';
 import ModuleDashboardEffects from './ModuleDashboardEffects';
+import CoreDashboardEffects from './CoreDashboardEffects';
 import { useBreakpoint } from '@/js/hooks/useBreakpoint';
 import { useMonitorInternetConnection } from '@/js/hooks/useMonitorInternetConnection';
 import useQueryArg from '@/js/hooks/useQueryArg';
@@ -248,7 +248,7 @@ export default function DashboardMainApp() {
 
 	return (
 		<Fragment>
-			<ScrollEffect />
+			<CoreDashboardEffects />
 			<ModuleDashboardEffects />
 
 			<AdminScreenTooltip />

assets/js/hooks/useOpenEmailReportingSelectionPanelEffect.js

@@ -0,0 +1,45 @@
+/**
+ * Open Email Reporting Selection Panel hook.
+ *
+ * Site Kit by Google, Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * External dependencies
+ */
+import { useMount } from 'react-use';
+
+/**
+ * Internal dependencies
+ */
+import { useDispatch } from 'googlesitekit-data';
+import useQueryArg from '@/js/hooks/useQueryArg';
+import { CORE_UI } from '@/js/googlesitekit/datastore/ui/constants';
+import { USER_SETTINGS_SELECTION_PANEL_OPENED_KEY } from '@/js/components/email-reporting/constants';
+
+export default function useOpenEmailReportingSelectionPanelEffect() {
+	const [ emailReportingPanelOpen, setEmailReportingPanelOpen ] = useQueryArg(
+		'email-reporting-panel'
+	);
+	const { setValue: setUIValue } = useDispatch( CORE_UI );
+
+	useMount( () => {
+		// If redirected from a pointer CTA or following link from email footer, open the Email Reporting selection panel.
+		if ( emailReportingPanelOpen !== undefined ) {
+			setUIValue( USER_SETTINGS_SELECTION_PANEL_OPENED_KEY, true );
+			setEmailReportingPanelOpen( undefined );
+		}
+	} );
+}

assets/sass/components/wp-dashboard/googlesitekit-pointers.scss

@@ -0,0 +1,58 @@
+/**
+ * Pointers styles for WP Dashboard
+ *
+ * Site Kit by Google, Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+.googlesitekit-pointer-cta--dismiss {
+	align-items: center;
+	background-color: $c-white;
+	border: none;
+	border-radius: 50%;
+	display: flex;
+	justify-content: center;
+	position: absolute;
+	right: 10px;
+	top: 12px;
+
+	&:hover {
+		cursor: pointer;
+	}
+}
+
+.googlesitekit-pointer-buttons {
+	margin-top: 55px;
+	padding-bottom: 0;
+	padding-left: 20px;
+	padding-right: 20px;
+}
+
+.googlesitekit-email-pointer {
+	.wp-pointer-content h3::before {
+		content: "\f466"; // Email icon
+		font-family: dashicons, sans-serif;
+		margin-right: 8px;
+	}
+
+	.wp-pointer-content h4 {
+		line-height: 24px;
+		margin-bottom: 0;
+		margin-top: 16px;
+	}
+
+	.wp-pointer-content p {
+		margin-top: 0;
+	}
+}

assets/sass/wpdashboard.scss

@@ -65,6 +65,7 @@
 @import "components/wp-dashboard/googlesitekit-unique-visitors-chart-widget";
 @import "components/wp-dashboard/googlesitekit-wp-dashboard";
 @import "components/wp-dashboard/googlesitekit-wp-dashboard-stats";
+@import "components/wp-dashboard/googlesitekit-pointers";
 
 // Charts
 @import "components/dashboard/googlesitekit-dashboard-charts";

includes/Core/Admin/Pointer.php

@@ -64,6 +64,8 @@ public function __construct( $slug, array $args ) {
 				'target_id'       => '',
 				'position'        => 'top',
 				'active_callback' => null,
+				'buttons'         => null,
+				'class'           => '',
 			)
 		);
 	}
@@ -90,6 +92,28 @@ public function get_title() {
 		return $this->args['title'];
 	}
 
+	/**
+	 * Gets the pointer buttons.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return string Pointer buttons.
+	 */
+	public function get_buttons() {
+		return $this->args['buttons'];
+	}
+
+	/**
+	 * Gets the pointer custom class.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return string|array Pointer custom class.
+	 */
+	public function get_class() {
+		return $this->args['class'];
+	}
+
 	/**
 	 * Gets the pointer content.
 	 *

includes/Core/Admin/Pointers.php

@@ -62,6 +62,8 @@ function ( Pointer $pointer ) use ( $hook_suffix ) {
 		}
 
 		wp_enqueue_style( 'wp-pointer' );
+		// Dashboard styles are required where pointers are used to ensure proper styling.
+		wp_enqueue_style( 'googlesitekit-wp-dashboard-css' );
 		wp_enqueue_script( 'wp-pointer' );
 
 		add_action(
@@ -103,6 +105,7 @@ function ( $pointer ) {
 	 * Prints script for a given pointer.
 	 *
 	 * @since 1.83.0
+	 * @since n.e.x.t Updated to support buttons and header dismiss icon.
 	 *
 	 * @param Pointer $pointer Pointer to print.
 	 */
@@ -112,38 +115,82 @@ private function print_pointer_script( $pointer ) {
 			return;
 		}
 
-		$slug = $pointer->get_slug();
+		$buttons = $pointer->get_buttons();
+		if ( $buttons ) {
+			// Content including buttons escaped below in the inline script with wp_kses.
+			$content .= '<div class="googlesitekit-pointer-buttons">' . $buttons . '</div>';
+		}
 
-		BC_Functions::wp_print_inline_script_tag(
-			sprintf(
-				'
-				jQuery( function() {
-					var options = {
-						content: "<h3>%s</h3>%s",
-						position: %s,
-						pointerWidth: 420,
-						close: function() {
-							jQuery.post(
-								window.ajaxurl,
-								{
-									pointer: "%s",
-									action:  "dismiss-wp-pointer",
-								}
-							);
-						}
-					};
-
-					jQuery( "#%s" ).pointer( options ).pointer( "open" );
-				} );
-				',
-				esc_js( $pointer->get_title() ),
-				$content,
-				wp_json_encode( $pointer->get_position() ),
-				esc_js( $slug ),
-				esc_js( $pointer->get_target_id() )
+		$class = array( 'wp-pointer' );
+		if ( $pointer->get_class() ) {
+			$class[] = $pointer->get_class();
+		}
+
+		$kses_title = array(
+			'span'   => array( 'class' => array() ),
+			'button' => array(
+				'class'       => array(),
+				'type'        => array(),
+				'data-action' => array(),
+			),
+		);
+
+		$kses_content = array(
+			'a'      => array(
+				'href'        => array(),
+				'class'       => array(),
+				'target'      => array(),
+				'rel'         => array(),
+				'data-action' => array(),
+			),
+			'h4'     => array(),
+			'p'      => array( 'class' => array() ),
+			'br'     => array(),
+			'strong' => array(),
+			'em'     => array(),
+			'button' => array(
+				'class'       => array(),
+				'type'        => array(),
+				'data-action' => array(),
 			),
+			'div'    => array( 'class' => array() ),
+		);
+
+		BC_Functions::wp_print_inline_script_tag(
+			<<<'JS'
+			(
+				function ( $, wp, config ) {
+					function initPointer() {
+						const options = {
+							content: '<h3>' + config.title + '</h3>' + config.content,
+							position: JSON.parse( config.position ),
+							pointerWidth: 420,
+							pointerClass: config.class,
+							close: function() {
+								wp.ajax.post( 'dismiss-wp-pointer', { pointer: config.slug } );
+							},
+							buttons: function( event, container ) {
+								container.pointer.on( 'click', '[data-action="dismiss"]', function() {
+									container.element.pointer( 'close' );
+								} );
+							}
+						};
+
+						$( '#' + config.targetId ).pointer( options ).pointer( 'open' );
+					}
+
+					$( initPointer );
+				}
+			)( window.jQuery, window.wp, { ...document.currentScript.dataset } );
+			JS
+			,
 			array(
-				'id' => $slug,
+				'data-slug'      => $pointer->get_slug(),
+				'data-class'     => implode( ' ', $class ),
+				'data-target-id' => $pointer->get_target_id(),
+				'data-title'     => wp_kses( $pointer->get_title(), $kses_title ),
+				'data-content'   => wp_kses( $content, $kses_content ),
+				'data-position'  => wp_json_encode( $pointer->get_position() ),
 			)
 		);
 	}

includes/Core/Dashboard_Sharing/Dashboard_Sharing.php

@@ -10,6 +10,8 @@
 
 namespace Google\Site_Kit\Core\Dashboard_Sharing;
 
+use Google\Site_Kit\Context;
+
 /**
  * Class for handling Dashboard Sharing.
  *
@@ -31,9 +33,12 @@ class Dashboard_Sharing {
 	 *
 	 * @since 1.82.0
 	 * @since 1.158.0 Remove $user_options and $context params.
+	 * @since n.e.x.t Restore $context param.
+	 *
+	 * @param Context $context Plugin context.
 	 */
-	public function __construct() {
-		$this->view_only_pointer = new View_Only_Pointer();
+	public function __construct( Context $context ) {
+		$this->view_only_pointer = new View_Only_Pointer( $context );
 	}
 
 	/**