Bulk editor: add in-app tour for first-time users

composer.json

@@ -111,7 +111,7 @@
 			"Yoast\\WP\\SEO\\Composer\\Actions::check_coding_standards"
 		],
 		"check-cs-thresholds": [
-			"@putenv YOASTCS_THRESHOLD_ERRORS=2378",
+			"@putenv YOASTCS_THRESHOLD_ERRORS=2377",
 			"@putenv YOASTCS_THRESHOLD_WARNINGS=254",
 			"Yoast\\WP\\SEO\\Composer\\Actions::check_cs_thresholds"
 		],

css/src/bulk-editor-page.css

@@ -6,6 +6,11 @@
 		padding-left: 0 !important;
 	}
 
+	/* Keep the admin menu above the guided-tour spotlight dim so it isn't overlaid. */
+	#adminmenuback {
+		z-index: 11;
+	}
+
 	.yst-mobile-navigation__top {
 		/* Offset the sticky bar below the taller mobile admin bar. */
 		@media (min-width: 601px) and (max-width: 768px) {
@@ -107,3 +112,31 @@
 .yst-root .yst-bulk-editor-title-link:focus:not(:focus-visible) {
 	@apply yst-outline-none;
 }
+
+/* The guided-tour spotlight overlay is decorative only; a separate backdrop blocks interaction, so it ignores pointer events. */
+.yst-root .yst-tour-spotlight {
+	pointer-events: none;
+}
+
+/* Prevent the in-app tour popovers title to stack bellow the close button */
+.yst-bulk-editor-tour-card .yst-flex-grow {
+	min-width: 0;
+	padding-inline-end: 2rem;
+}
+
+/* In RTL. */
+.yst-bulk-editor-tour-card.yst-popover--right {
+	margin-inline-start: 0.25rem;
+}
+
+[dir="rtl"] .yst-bulk-editor-tour-card.yst-popover--right {
+	margin-inline-start: 1rem;
+}
+
+[dir="rtl"] .yst-bulk-editor-tour-card.yst-popover--right::before {
+	inset-inline-start: auto !important;
+	inset-inline-end: 100% !important;
+	transform: translateY(-50%) !important;
+	border-inline-start: 14px solid transparent !important;
+	border-inline-end: 14px solid white !important;
+}

css/src/new-settings.css

@@ -220,10 +220,6 @@ body.seo_page_wpseo_page_settings {
 		}
 	}
 
-	.yst-popover-backdrop-highlight-button button {
-		z-index:99;
-	}
-
 	/* RTL */
 
 	&.rtl {

packages/js/src/bulk-editor/components/bulk-action-bar.js

@@ -80,21 +80,23 @@ export const SelectionToolbar = ( { idSuffix = "", isAllSelected, isIndeterminat
 
 	return (
 		<div className="yst-flex yst-items-center yst-gap-4">
-			<Checkbox
-				ref={ checkboxRef }
-				id={ `bulk-editor-select-all${ idSuffix }` }
-				name={ `bulk-editor-select-all${ idSuffix }` }
-				value="all"
-				aria-label={ __( "Select all", "wordpress-seo" ) }
-				checked={ isAllSelected }
-				onChange={ onToggleAll }
-			/>
-			<SelectMenu
-				onSelectAll={ onSelectAll }
-				onDeselectAll={ onDeselectAll }
-				selectedCount={ selectedCount }
-				totalCount={ totalCount }
-			/>
+			<div className="yst-flex yst-items-center yst-gap-4" data-tour-id="selection-toolbar">
+				<Checkbox
+					ref={ checkboxRef }
+					id={ `bulk-editor-select-all${ idSuffix }` }
+					name={ `bulk-editor-select-all${ idSuffix }` }
+					value="all"
+					aria-label={ __( "Select all", "wordpress-seo" ) }
+					checked={ isAllSelected }
+					onChange={ onToggleAll }
+				/>
+				<SelectMenu
+					onSelectAll={ onSelectAll }
+					onDeselectAll={ onDeselectAll }
+					selectedCount={ selectedCount }
+					totalCount={ totalCount }
+				/>
+			</div>
 			{ selectedCount > 0 && (
 				<span className="yst-font-medium yst-text-slate-800">
 					{ sprintf(
@@ -250,10 +252,12 @@ const BulkActionsBand = ( {
 	isPremium, isAiEnabled, isActive, selectedIds, activeFieldSet, contentType, hasUnsavedEdits, editCount, onApplyAll, onDiscardAll, isApplyingAll,
 } ) => (
 	<div className="yst-flex yst-items-center yst-gap-3 yst-border-y yst-border-slate-200 yst-bg-slate-100 yst-px-4 yst-py-3">
-		{ ! isPremium && isAiEnabled && <FreeBulkActions contentType={ contentType } /> }
-		{ isActive && (
-			<Slot name={ BULK_ACTIONS_SLOT } fillProps={ { selectedIds, activeFieldSet, contentType, hasUnsavedEdits } } />
-		) }
+		<div className="yst-flex yst-items-center yst-gap-3" data-tour-id="generate-actions">
+			{ ! isPremium && isAiEnabled && <FreeBulkActions contentType={ contentType } /> }
+			{ isActive && (
+				<Slot name={ BULK_ACTIONS_SLOT } fillProps={ { selectedIds, activeFieldSet, contentType, hasUnsavedEdits } } />
+			) }
+		</div>
 		{ isActive && hasUnsavedEdits && (
 			<ManualReviewActions editCount={ editCount } onApplyAll={ onApplyAll } onDiscardAll={ onDiscardAll } isApplying={ isApplyingAll } />
 		) }

packages/js/src/bulk-editor/components/bulk-editor-content.js

@@ -8,6 +8,7 @@ import { useInlineEdit } from "../hooks/use-inline-edit";
 import { usePosts } from "../services/use-posts";
 import { BulkActions, SelectionToolbar } from "./bulk-action-bar";
 import { BulkEditorFilters } from "./bulk-editor-filters";
+import { BulkEditorTour } from "./tour/bulk-editor-tour";
 import { BulkEditorFooter } from "./bulk-editor-footer";
 import { BulkEditorTable } from "./table/bulk-editor-table";
 import { BulkEditorTabPanel, BulkEditorTabs } from "./bulk-editor-tabs";
@@ -144,87 +145,90 @@ export const BulkEditorContent = ( { dataProvider, remoteDataProvider, contentTy
 	} ), [ selectedIds, toggleRow ] );
 
 	return (
-		<div className="yst-p-8 yst-space-y-6">
-			<div className="yst-flex yst-flex-col yst-gap-4 sm:yst-flex-row sm:yst-items-start sm:yst-justify-between">
-				<BulkEditorTabs
-					tabs={ tabs }
-					activeTab={ activeFieldSet }
-					disabled={ hasExternalGeneration }
-					onChange={ onChangeTab }
-					label={ __( "Bulk editor views", "wordpress-seo" ) }
+		<>
+			<div className="yst-p-8 yst-space-y-6">
+				<div className="yst-flex yst-flex-col yst-gap-4 sm:yst-flex-row sm:yst-items-start sm:yst-justify-between">
+					<BulkEditorTabs
+						tabs={ tabs }
+						activeTab={ activeFieldSet }
+						disabled={ hasExternalGeneration }
+						onChange={ onChangeTab }
+						label={ __( "Bulk editor views", "wordpress-seo" ) }
+					/>
+					<SearchBox contentTypeLabel={ contentTypeLabel } />
+				</div>
+				{ tabs.map( ( tab ) => (
+					<BulkEditorTabPanel key={ tab.id } tabId={ tab.id } isActive={ tab.id === activeFieldSet }>
+						<BulkEditorTable
+							items={ items }
+							fieldSet={ fieldSets[ tab.id ] }
+							selection={ selection }
+							editing={ editing }
+							selectionToolbar={
+								<SelectionToolbar
+									idSuffix={ `-${ tab.id }` }
+									isAllSelected={ isAllSelected }
+									isIndeterminate={ isIndeterminate }
+									onToggleAll={ onToggleAll }
+									onSelectAll={ onSelectAll }
+									onDeselectAll={ deselectAll }
+									selectedCount={ selectedCount }
+									totalCount={ totalCount }
+									contentTypeLabel={ contentTypeLabel }
+								/>
+							}
+							bulkActions={
+								<BulkActions
+									isPremium={ isPremium }
+									isAiEnabled={ isAiEnabled }
+									isActive={ tab.id === activeFieldSet }
+									selectedIds={ selectedIds }
+									activeFieldSet={ activeFieldSet }
+									contentType={ contentType }
+									contentTypeLabel={ contentTypeLabel }
+									contentTypeSingularLabel={ contentTypeSingularLabel }
+									hasUnsavedEdits={ hasUnsavedEdits }
+									editCount={ editCount }
+									onApplyAll={ editing.onApplyAll }
+									onDiscardAll={ editing.onDiscardAll }
+									isApplyingAll={ editing.isApplyingAll }
+									hasSaveError={ editing.hasSaveError }
+									onDismissSaveError={ editing.dismissSaveError }
+								/>
+							}
+							// A selection only warrants the band while AI is enabled (the AI affordances are its only
+							// selection-driven occupant); with AI off the band collapses. Unsaved manual edits are a
+							// separate, non-AI occupant, so they keep it open regardless of the AI toggle. External
+							// pending changes (Premium's AI suggestions) also keep it open: a filter, search, or page
+							// change clears the selection but must leave the pending suggestions actionable.
+							showBulkActions={ ( hasSelection && isAiEnabled ) || hasUnsavedEdits || hasExternalPendingChanges }
+							filters={ <BulkEditorFilters /> }
+							isLoading={ isPending }
+							hasExternalPendingChanges={ hasExternalPendingChanges }
+							hasExternalGeneration={ hasExternalGeneration }
+							footer={ total > 0
+								? <BulkEditorFooter total={ total } totalPages={ totalPages } isPending={ isPending } />
+								: null }
+						/>
+					</BulkEditorTabPanel>
+				) ) }
+				<UnsavedChangesModal
+					isOpen={ hasUnsavedEdits && pendingSwitch !== null }
+					isSaving={ editing.isApplyingAll }
+					onSave={ onSaveAndSwitch }
+					onDiscard={ onDiscardAndSwitch }
+					onClose={ onCancelSwitch }
+				/>
+				<Slot
+					name={ PENDING_CHANGES_MODAL_SLOT }
+					fillProps={ {
+						isOpen: pendingSwitch !== null && ! hasUnsavedEdits,
+						onCommit: onCommitSwitch,
+						onCancel: onCancelSwitch,
+					} }
 				/>
-				<SearchBox contentTypeLabel={ contentTypeLabel } />
 			</div>
-			{ tabs.map( ( tab ) => (
-				<BulkEditorTabPanel key={ tab.id } tabId={ tab.id } isActive={ tab.id === activeFieldSet }>
-					<BulkEditorTable
-						items={ items }
-						fieldSet={ fieldSets[ tab.id ] }
-						selection={ selection }
-						editing={ editing }
-						selectionToolbar={
-							<SelectionToolbar
-								idSuffix={ `-${ tab.id }` }
-								isAllSelected={ isAllSelected }
-								isIndeterminate={ isIndeterminate }
-								onToggleAll={ onToggleAll }
-								onSelectAll={ onSelectAll }
-								onDeselectAll={ deselectAll }
-								selectedCount={ selectedCount }
-								totalCount={ totalCount }
-								contentTypeLabel={ contentTypeLabel }
-							/>
-						}
-						bulkActions={
-							<BulkActions
-								isPremium={ isPremium }
-								isAiEnabled={ isAiEnabled }
-								isActive={ tab.id === activeFieldSet }
-								selectedIds={ selectedIds }
-								activeFieldSet={ activeFieldSet }
-								contentType={ contentType }
-								contentTypeLabel={ contentTypeLabel }
-								contentTypeSingularLabel={ contentTypeSingularLabel }
-								hasUnsavedEdits={ hasUnsavedEdits }
-								editCount={ editCount }
-								onApplyAll={ editing.onApplyAll }
-								onDiscardAll={ editing.onDiscardAll }
-								isApplyingAll={ editing.isApplyingAll }
-								hasSaveError={ editing.hasSaveError }
-								onDismissSaveError={ editing.dismissSaveError }
-							/>
-						}
-						// A selection only warrants the band while AI is enabled (the AI affordances are its only
-						// selection-driven occupant); with AI off the band collapses. Unsaved manual edits are a
-						// separate, non-AI occupant, so they keep it open regardless of the AI toggle. External
-						// pending changes (Premium's AI suggestions) also keep it open: a filter, search, or page
-						// change clears the selection but must leave the pending suggestions actionable.
-						showBulkActions={ ( hasSelection && isAiEnabled ) || hasUnsavedEdits || hasExternalPendingChanges }
-						filters={ <BulkEditorFilters /> }
-						isLoading={ isPending }
-						hasExternalPendingChanges={ hasExternalPendingChanges }
-						hasExternalGeneration={ hasExternalGeneration }
-						footer={ total > 0
-							? <BulkEditorFooter total={ total } totalPages={ totalPages } isPending={ isPending } />
-							: null }
-					/>
-				</BulkEditorTabPanel>
-			) ) }
-			<UnsavedChangesModal
-				isOpen={ hasUnsavedEdits && pendingSwitch !== null }
-				isSaving={ editing.isApplyingAll }
-				onSave={ onSaveAndSwitch }
-				onDiscard={ onDiscardAndSwitch }
-				onClose={ onCancelSwitch }
-			/>
-			<Slot
-				name={ PENDING_CHANGES_MODAL_SLOT }
-				fillProps={ {
-					isOpen: pendingSwitch !== null && ! hasUnsavedEdits,
-					onCommit: onCommitSwitch,
-					onCancel: onCancelSwitch,
-				} }
-			/>
-		</div>
+			<BulkEditorTour onSelectAll={ onSelectAll } onDeselectAll={ deselectAll } hasSelection={ hasSelection } />
+		</>
 	);
 };

packages/js/src/bulk-editor/components/bulk-editor-nav.js

@@ -7,6 +7,9 @@ import { noop } from "lodash";
 import { YoastLogo } from "../../shared-admin/components";
 import { BackToToolsLink } from "./back-to-tools-link";
 
+// The WordPress built-in content types, used to scope the guided-tour spotlight to Posts and Pages.
+const BUILT_IN_CONTENT_TYPES = [ "post", "page" ];
+
 /**
  * One content type entry.
  *
@@ -19,14 +22,15 @@ import { BackToToolsLink } from "./back-to-tools-link";
  * One content type item. Selecting a content type changes view state, it does not navigate.
  * The active state comes from the SidebarNavigation context.
  *
- * @param {Object}                props             The props.
- * @param {BulkEditorContentType} props.contentType The content type.
- * @param {boolean}               props.disabled    Whether the item is disabled.
- * @param {Function}              props.onChange    Called with the content type id when selected.
+ * @param {Object}                props                 The props.
+ * @param {BulkEditorContentType} props.contentType     The content type.
+ * @param {boolean}               props.disabled        Whether the item is disabled.
+ * @param {Function}              props.onChange        Called with the content type id when selected.
+ * @param {boolean}               [props.isHighlightEnd] Whether this is the last item the guided-tour spotlight covers.
  *
  * @returns {JSX.Element} The item.
  */
-const ContentTypeItem = ( { contentType, disabled, onChange } ) => {
+const ContentTypeItem = ( { contentType, disabled, onChange, isHighlightEnd = false } ) => {
 	const handleClick = useCallback( () => onChange( contentType.id ), [ onChange, contentType.id ] );
 
 	return (
@@ -39,6 +43,7 @@ const ContentTypeItem = ( { contentType, disabled, onChange } ) => {
 			disabled={ disabled }
 			onClick={ handleClick }
 			className={ classNames( "yst-w-full", { "yst-opacity-50": disabled } ) }
+			{ ...( isHighlightEnd ? { "data-tour-highlight-end": "true" } : {} ) }
 		/>
 	);
 };
@@ -111,6 +116,12 @@ export const BulkEditorNavMenu = ( {
 } ) => {
 	const hiddenCount = contentTypes.length - visibleLimit;
 
+	// The in-app guided tour highlights only the built-in content types (Posts, Pages).
+	// Post/page are always on top of the registration order.
+	const highlightEndIndex = contentTypes
+		.slice( 0, 2 )
+		.reduce( ( end, contentType, index ) => ( BUILT_IN_CONTENT_TYPES.includes( contentType.id ) ? index : end ), -1 );
+
 	const showMoreLabel = sprintf(
 		/* translators: %d expands to the number of additional content types. */
 		_n( "Show %d more", "Show %d more", hiddenCount, "wordpress-seo" ),
@@ -121,20 +132,28 @@ export const BulkEditorNavMenu = ( {
 		<div className="yst-space-y-6">
 			<NavLogo logoHref={ logoHref } isPremium={ isPremium } idSuffix={ idSuffix } disabled={ disabled } onNavigate={ onNavigate } />
 			<BackToToolsLink href={ backToToolsUrl } disabled={ disabled } onNavigate={ onNavigate } />
-			<SidebarNavigation.MenuItemWithLimiter
-				id={ `bulk-editor-nav-content-types${ idSuffix }` }
-				label={ __( "Bulk editor", "wordpress-seo" ) }
-				icon={ DuplicateIcon }
-				defaultOpen={ true }
-				limit={ visibleLimit }
-				buttonId={ `bulk-editor-nav-more${ idSuffix }` }
-				showMoreLabel={ showMoreLabel }
-				showLessLabel={ __( "Show less", "wordpress-seo" ) }
-			>
-				{ contentTypes.map( ( contentType ) => (
-					<ContentTypeItem key={ contentType.id } contentType={ contentType } disabled={ disabled } onChange={ onChange } />
-				) ) }
-			</SidebarNavigation.MenuItemWithLimiter>
+			<div data-tour-id="content-type-nav">
+				<SidebarNavigation.MenuItemWithLimiter
+					id={ `bulk-editor-nav-content-types${ idSuffix }` }
+					label={ __( "Bulk editor", "wordpress-seo" ) }
+					icon={ DuplicateIcon }
+					defaultOpen={ true }
+					limit={ visibleLimit }
+					buttonId={ `bulk-editor-nav-more${ idSuffix }` }
+					showMoreLabel={ showMoreLabel }
+					showLessLabel={ __( "Show less", "wordpress-seo" ) }
+				>
+					{ contentTypes.map( ( contentType, index ) => (
+						<ContentTypeItem
+							key={ contentType.id }
+							contentType={ contentType }
+							disabled={ disabled }
+							onChange={ onChange }
+							isHighlightEnd={ index === highlightEndIndex }
+						/>
+					) ) }
+				</SidebarNavigation.MenuItemWithLimiter>
+			</div>
 		</div>
 	);
 };