newspack-components 4.5.0 → 4.6.0

package/src/with-wizard/index.js

@@ -4,12 +4,12 @@
 import { Component, createRef, Fragment } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import apiFetch from '@wordpress/api-fetch';
-import { category } from '@wordpress/icons';
+import { __experimentalHStack as HStack } from '@wordpress/components'; // eslint-disable-line @wordpress/no-unsafe-wp-apis
 
 /**
  * Internal dependencies.
  */
-import { Button, Card, Modal, NewspackIcon, Notice, PluginInstaller } from '../';
+import { Button, Modal, Notice, Page, PluginInstaller } from '../';
 import Router from '../proxied-imports/router';
 import Footer from '../footer';
 import './style.scss';
@@ -99,11 +99,11 @@ export default function withWizard( WrappedComponent, requiredPlugins ) {
 			return (
 				<Modal title={ __( 'Unrecoverable error' ) } onRequestClose={ () => ( window.location = fallbackURL ) }>
 					<Notice noticeText={ message } isError rawHTML />
-					<Card buttonsCard noBorder className="justify-end">
+					<HStack justify="flex-end" spacing={ 4 } wrap className="newspack-modal__footer">
 						<Button isPrimary href={ fallbackURL }>
 							{ __( 'Return to Dashboard', 'newspack-plugin' ) }
 						</Button>
-					</Card>
+					</HStack>
 				</Modal>
 			);
 		};
@@ -203,41 +203,20 @@ export default function withWizard( WrappedComponent, requiredPlugins ) {
 			if ( complete ) {
 				return <Redirect from="/plugin-requirements" to="/" />;
 			}
+			const headerText = requiredPlugins.length > 1 ? __( 'Required plugins', 'newspack-plugin' ) : __( 'Required plugin', 'newspack-plugin' );
+			const content = (
+				<div className="newspack-wizard newspack-wizard__content">
+					<PluginInstaller plugins={ requiredPlugins } onStatus={ status => this.pluginInstallationStatus( status ) } />
+				</div>
+			);
 			return (
 				<Route
 					path="/"
-					render={ () => (
-						<Fragment>
-							{ complete !== null && (
-								<div className="newspack-wizard__header">
-									<div className="newspack-wizard__header__inner">
-										<div className="newspack-wizard__title">
-											<Button
-												isLink
-												href={ newspack_urls.dashboard }
-												label={ __( 'Return to Dashboard', 'newspack-plugin' ) }
-												showTooltip={ true }
-												icon={ category }
-												iconSize={ 36 }
-											>
-												<NewspackIcon size={ 36 } />
-											</Button>
-											<div>
-												<h2>
-													{ requiredPlugins.length > 1
-														? __( 'Required plugins', 'newspack-plugin' )
-														: __( 'Required plugin', 'newspack-plugin' ) }
-												</h2>
-											</div>
-										</div>
-									</div>
-								</div>
-							) }
-							<div className="newspack-wizard newspack-wizard__content">
-								<PluginInstaller plugins={ requiredPlugins } onStatus={ status => this.pluginInstallationStatus( status ) } />
-							</div>
-						</Fragment>
-					) }
+					render={ () =>
+						// While `complete` is still null the requirements are being
+						// determined; render content without a header (matches prior behavior).
+						complete === null ? content : <Page breadcrumbItems={ [ { label: headerText } ] }>{ content }</Page>
+					}
 				/>
 			);
 		};
@@ -256,7 +235,7 @@ export default function withWizard( WrappedComponent, requiredPlugins ) {
 		confirmAction = options => {
 			const modalOptions = {
 				title: null,
-				message: __( 'Are you sure?', 'newpack-plugin' ),
+				message: __( 'Are you sure?', 'newspack-plugin' ),
 				confirmText: __( 'OK', 'newspack-plugin' ),
 				cancelText: __( 'Cancel', 'newspack-plugin' ),
 				callback: null,
@@ -281,7 +260,7 @@ export default function withWizard( WrappedComponent, requiredPlugins ) {
 				callback && (
 					<Modal size="small" hideTitle={ ! title } title={ title } onRequestClose={ () => this.setState( { confirmation: null } ) }>
 						<p>{ message }</p>
-						<Card buttonsCard noBorder className="justify-end">
+						<HStack justify="flex-end" spacing={ 4 } wrap className="newspack-modal__footer">
 							<Button variant="secondary" onClick={ () => this.setState( { confirmation: null } ) }>
 								{ cancelText }
 							</Button>
@@ -294,7 +273,7 @@ export default function withWizard( WrappedComponent, requiredPlugins ) {
 							>
 								{ confirmText }
 							</Button>
-						</Card>
+						</HStack>
 					</Modal>
 				)
 			);

package/src/with-wizard-screen/index.js

@@ -1,25 +1,43 @@
 /**
- * WordPress dependencies.
+ * WordPress dependencies
  */
-import { __ } from '@wordpress/i18n';
-import { category } from '@wordpress/icons';
+import { cloneElement } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
-import { Button, Handoff, NewspackIcon, Notice, HandoffMessage, TabbedNavigation } from '../';
+import { Button, Handoff, Notice, HandoffMessage, TabbedNavigation, Page } from '../';
+import { activeBreadcrumbs } from '../wizard/breadcrumbs-select';
 import { buttonProps } from '../button-props';
+import Router from '../proxied-imports/router';
 import './style.scss';
 
+const { useLocation } = Router;
+
 /**
  * External dependencies
  */
 import classnames from 'classnames';
 
+/**
+ * Derives the active-tab breadcrumb trail from the current route. Only rendered
+ * for tabbed wizards, which always mount inside a Router, so calling useLocation
+ * here keeps router-free consumers (e.g. standalone multibranded) from crashing.
+ *
+ * @param {Object}   props          Component props.
+ * @param {Array}    props.sections Tabbed navigation sections.
+ * @param {Function} props.render   Renders the page given the breadcrumb trail.
+ * @return {JSX.Element} The rendered page.
+ */
+const RouteBreadcrumbs = ( { sections, render } ) => {
+	const { pathname } = useLocation();
+	return render( activeBreadcrumbs( sections, pathname ) );
+};
+
 /**
  * Higher-Order Component to provide plugin management and error handling to Newspack Wizards.
  */
-export default function withWizardScreen( WrappedComponent, { hidePrimaryButton } = {} ) {
+export default function withWizardScreen( WrappedComponent, { hidePrimaryButton, hideHeader } = {} ) {
 	const WrappedWithWizardScreen = props => {
 		const {
 			className,
@@ -29,6 +47,8 @@ export default function withWizardScreen( WrappedComponent, { hidePrimaryButton
 			headerText,
 			subHeaderText,
 			tabbedNavigation,
+			breadcrumbItems,
+			headerActions,
 			secondaryButtonText,
 			secondaryButtonAction,
 			renderAboveContent,
@@ -57,37 +77,15 @@ export default function withWizardScreen( WrappedComponent, { hidePrimaryButton
 					{ ...overridingProps }
 				/>
 			);
-		return (
-			<>
-				{ newspack_aux_data.is_debug_mode && <Notice debugMode /> }
-				<div className="newspack-wizard__header">
-					<div className="newspack-wizard__header__inner">
-						<div className="newspack-wizard__title">
-							<Button
-								isLink
-								href={ newspack_urls.dashboard }
-								label={ __( 'Return to Dashboard', 'newspack-plugin' ) }
-								showTooltip={ true }
-								icon={ category }
-								iconSize={ 36 }
-							>
-								<NewspackIcon size={ 36 } />
-							</Button>
-							<div>
-								{ headerText && <h2>{ headerText }</h2> }
-								{ subHeaderText && <span>{ subHeaderText }</span> }
-							</div>
-						</div>
-					</div>
-				</div>
-
-				{ tabbedNavigation && (
-					<TabbedNavigation
-						disableUpcoming={ disableUpcomingInTabbedNavigation }
-						items={ tabbedNavigation.filter( item => ! item.isHiddenInNav ) }
-					/>
-				) }
+		const tabbedNavigationRegion = tabbedNavigation && (
+			<TabbedNavigation
+				disableUpcoming={ disableUpcomingInTabbedNavigation }
+				items={ tabbedNavigation.filter( item => ! item.isHiddenInNav ) }
+			/>
+		);
 
+		const content = (
+			<>
 				<HandoffMessage />
 
 				<div className={ classnames( 'newspack-wizard newspack-wizard__content', className ) }>
@@ -106,6 +104,43 @@ export default function withWizardScreen( WrappedComponent, { hidePrimaryButton
 				</div>
 			</>
 		);
+
+		const renderPage = crumbs => {
+			let pageBreadcrumbs = crumbs ?? [];
+			if ( ! pageBreadcrumbs.length && headerText ) {
+				pageBreadcrumbs = [ { label: headerText } ];
+			}
+			return (
+				<>
+					{ newspack_aux_data.is_debug_mode && <Notice debugMode /> }
+					{ hideHeader ? (
+						// Without the Page shell the tabs still own the content: it
+						// renders inside the active tab's panel.
+						<>{ tabbedNavigationRegion ? cloneElement( tabbedNavigationRegion, { content } ) : content }</>
+					) : (
+						<Page
+							breadcrumbItems={ pageBreadcrumbs }
+							subTitle={ subHeaderText }
+							actions={ headerActions }
+							tabbedNavigation={ tabbedNavigationRegion }
+						>
+							{ content }
+						</Page>
+					) }
+				</>
+			);
+		};
+
+		if ( hideHeader ) {
+			return renderPage();
+		}
+		if ( breadcrumbItems ) {
+			return renderPage( breadcrumbItems );
+		}
+		if ( tabbedNavigation ) {
+			return <RouteBreadcrumbs sections={ tabbedNavigation } render={ renderPage } />;
+		}
+		return renderPage();
 	};
 	return WrappedWithWizardScreen;
 }

package/src/with-wizard-screen/index.test.js

@@ -0,0 +1,36 @@
+/**
+ * External dependencies.
+ */
+import { render, screen } from '@testing-library/react';
+import { HashRouter } from 'react-router-dom';
+
+/**
+ * Internal dependencies.
+ */
+import withWizardScreen from './';
+
+global.newspack_aux_data = { is_debug_mode: false };
+
+describe( 'withWizardScreen', () => {
+	it( 'falls back to a single headerText breadcrumb when no breadcrumbItems are provided', () => {
+		const WrappedComponent = () => <div>Body content</div>;
+		const ScreenWithHeader = withWizardScreen( WrappedComponent );
+
+		render(
+			<HashRouter>
+				<ScreenWithHeader headerText="Brands" />
+			</HashRouter>
+		);
+
+		expect( screen.getByRole( 'heading', { level: 1 } ) ).toHaveTextContent( 'Brands' );
+	} );
+
+	it( 'renders without a Router when no tabbed navigation is provided', () => {
+		const WrappedComponent = () => <div>Body content</div>;
+		const ScreenWithHeader = withWizardScreen( WrappedComponent );
+
+		render( <ScreenWithHeader headerText="Brands" /> );
+
+		expect( screen.getByRole( 'heading', { level: 1 } ) ).toHaveTextContent( 'Brands' );
+	} );
+} );

package/src/with-wizard-screen/style.scss

@@ -45,129 +45,12 @@
 		}
 	}
 
-	&__header {
-		align-items: center;
-		background: white;
-		border-bottom: 1px solid wp-colors.$gray-300;
-		display: flex;
-		.newspack-wizard__fixed-header & {
-			position: sticky;
-			top: 0;
-			width: 100%;
-			z-index: 1000;
-			.admin-bar & {
-				@media only screen and ( min-width: 601px ) {
-					top: 46px;
-				}
-				@media only screen and ( min-width: 782px ) {
-					top: 32px;
-				}
-			}
-		}
-		&__inner {
-			flex: 1 1 100%;
-		}
-		&__actions {
-			align-items: center;
-			display: flex;
-			gap: 8px;
-			justify-content: flex-end;
-			padding: 0 24px 0 0;
-			> .newspack-wizard__header__actions__main {
-				display: none;
-			}
-			@media only screen and ( min-width: 782px ) {
-				flex: 1 1 auto;
-				> .newspack-wizard__header__actions__main {
-					display: flex;
-				}
-				&__more {
-					&--primary-only,
-					.newspack-wizard__header__actions__more__main {
-						display: none;
-					}
-				}
-			}
-		}
-	}
-
 	&__main {
-		overflow-x: hidden;
+		overflow: hidden;
 		padding-bottom: 1px; /* Prevents borders from being cut off */
 	}
 
 
-	&__title {
-		align-items: center;
-		display: flex;
-
-		h2 {
-			margin: 0;
-			padding: 0;
-		}
-
-		> div {
-			align-items: baseline;
-			display: flex;
-			padding: 0 24px;
-
-			> span {
-				color: wp-colors.$gray-700;
-				display: none;
-				margin-left: 8px;
-
-				@media screen and ( min-width: 744px ) {
-					display: block;
-				}
-			}
-		}
-
-		svg {
-			fill: white;
-			margin: 0 !important;
-
-			&.newspack-icon {
-				flex: 0 0 36px;
-				margin-bottom: -1px !important;
-			}
-
-			&:not(.newspack-icon) {
-				background: var(--wp-admin-theme-color);
-				left: 50%;
-				margin: -28px 0 0 -28px !important;
-				opacity: 0;
-				padding: 10px;
-				position: absolute;
-				top: 50%;
-				transition: opacity 125ms ease-in-out;
-			}
-		}
-
-		.components-button.has-icon {
-			padding: 0;
-			position: relative;
-
-			&:hover {
-				svg {
-					opacity: 1;
-				}
-			}
-
-			&:focus-visible {
-				outline: none !important;
-
-				&::before {
-					border: 2px solid white;
-					border-radius: 2px;
-					content: "";
-					display: block;
-					inset: 6px 6px 5px;
-					position: absolute;
-				}
-			}
-		}
-	}
-
 	&__section-header {
 		margin: 0 auto 32px;
 		max-width: calc(calc(var(--newspack-wizard-section-space) * 2) + var(--newspack-wizard-section-width));
@@ -182,6 +65,7 @@
 
 	&__content {
 		margin: 0 auto;
+		width: 100%;
 		max-width: calc(calc(var(--newspack-wizard-section-space) * 2) + var(--newspack-wizard-section-width));
 		padding: calc(var(--newspack-wizard-section-space) * 2) var(--newspack-wizard-section-space) 0;
 
@@ -225,3 +109,16 @@
 		margin: 0;
 	}
 }
+
+/**
+ * Wizard header overflow ("More") menu, rendered by the Wizard component into
+ * admin-ui's Page actions slot. Hide the toggle when there are no overflow
+ * actions, and hide the duplicated primary items inside the menu on wide
+ * viewports.
+ */
+@media only screen and ( min-width: 782px ) {
+	.newspack-wizard__actions__more--primary-only,
+	.newspack-wizard__actions__more .newspack-wizard__actions__more__main {
+		display: none;
+	}
+}

package/src/wizard/breadcrumbs-select.js

@@ -0,0 +1,51 @@
+/**
+ * Internal dependencies.
+ */
+import { matchesRoute } from '../route-match';
+
+/**
+ * Select the active section's explicit breadcrumb trail by current route. Falls
+ * back to the first section, then to an empty trail.
+ *
+ * @param {Array}  sections Wizard sections (`{ path, breadcrumbs, exact?, activeTabPaths? }`).
+ * @param {string} pathname Current router pathname.
+ * @return {Array} Breadcrumb items `{ label, url? }`.
+ */
+export const activeBreadcrumbs = ( sections = [], pathname ) => {
+	if ( ! sections?.length ) {
+		return [];
+	}
+	const match = sections.find( section => matchesRoute( section, pathname ) ) || sections[ 0 ];
+	return match.breadcrumbs || [];
+};
+
+/**
+ * Append a section's render-time current-page breadcrumb(s) to a trail.
+ *
+ * A section can supply a leaf via `headerData.sectionName` — either a single
+ * label (e.g. an integration name, or Add/Edit) or an ordered array of
+ * `{ label, url? }` crumbs when the leaf needs its own linked ancestors. Each
+ * crumb is appended in turn.
+ *
+ * Convention: a route authors its current-page leaf in exactly ONE place —
+ * the static `breadcrumbs` array for a constant label, or `sectionName` for a
+ * render-time label (e.g. Add/Edit) whose static trail then holds ancestors
+ * only. Never both. The trailing-label skip below is a defensive guard against
+ * a route accidentally doing both; it is not a supported pattern to rely on.
+ *
+ * @param {Array}                  breadcrumbItems Base trail `{ label, url? }[]`.
+ * @param {string|Array|undefined} sectionName     A label, an array of crumbs, or falsy.
+ * @return {Array} A new trail with the section crumb(s) appended (deduped).
+ */
+export const appendSectionName = ( breadcrumbItems = [], sectionName ) => {
+	if ( ! sectionName ) {
+		return breadcrumbItems;
+	}
+	const extraCrumbs = ( Array.isArray( sectionName ) ? sectionName : [ { label: sectionName } ] ).filter( crumb => crumb?.label );
+	return extraCrumbs.reduce( ( trail, crumb ) => {
+		if ( trail[ trail.length - 1 ]?.label === crumb.label ) {
+			return trail;
+		}
+		return [ ...trail, crumb ];
+	}, breadcrumbItems );
+};

package/src/wizard/breadcrumbs-select.test.js

@@ -0,0 +1,124 @@
+/**
+ * Internal dependencies.
+ */
+import { activeBreadcrumbs, appendSectionName } from './breadcrumbs-select';
+
+const SECTIONS = [
+	{ path: '/', breadcrumbs: [ { label: 'Audience Management' }, { label: 'Configuration' } ] },
+	{ path: '/donations', breadcrumbs: [ { label: 'Audience Management' }, { label: 'Donations' } ] },
+];
+
+describe( 'activeBreadcrumbs', () => {
+	it( 'returns the matching section breadcrumbs by exact path', () => {
+		expect( activeBreadcrumbs( SECTIONS, '/donations' ) ).toEqual( [ { label: 'Audience Management' }, { label: 'Donations' } ] );
+	} );
+
+	it( 'falls back to the first section when no path matches', () => {
+		expect( activeBreadcrumbs( SECTIONS, '/nope' ) ).toEqual( SECTIONS[ 0 ].breadcrumbs );
+	} );
+
+	it( 'returns [] when sections is empty', () => {
+		expect( activeBreadcrumbs( [], '/x' ) ).toEqual( [] );
+	} );
+
+	it( 'returns [] when sections is null or undefined', () => {
+		expect( activeBreadcrumbs( null, '/x' ) ).toEqual( [] );
+		expect( activeBreadcrumbs( undefined, '/x' ) ).toEqual( [] );
+	} );
+
+	it( 'matches a non-exact section by path prefix', () => {
+		const sections = [
+			{ path: '/', breadcrumbs: [ { label: 'Root' } ] },
+			{ path: '/access', exact: false, breadcrumbs: [ { label: 'Root' }, { label: 'Access control' } ] },
+		];
+		expect( activeBreadcrumbs( sections, '/access/institutions' ) ).toEqual( [ { label: 'Root' }, { label: 'Access control' } ] );
+	} );
+
+	it( 'matches a parameterized route to its own breadcrumbs', () => {
+		const sections = [
+			{ path: '/content-gates', breadcrumbs: [ { label: 'Access control' } ] },
+			{
+				path: '/institutions/:id',
+				exact: true,
+				breadcrumbs: [ { label: 'Access control' }, { label: 'Edit institution' } ],
+			},
+		];
+		expect( activeBreadcrumbs( sections, '/institutions/123' ) ).toEqual( [ { label: 'Access control' }, { label: 'Edit institution' } ] );
+	} );
+
+	it( 'matches via activeTabPaths wildcard', () => {
+		const sections = [
+			{ path: '/', breadcrumbs: [ { label: 'Root' } ] },
+			{
+				path: '/segments',
+				activeTabPaths: [ '/segments/*' ],
+				breadcrumbs: [ { label: 'Root' }, { label: 'Segments' } ],
+			},
+		];
+		expect( activeBreadcrumbs( sections, '/segments/123' ) ).toEqual( [ { label: 'Root' }, { label: 'Segments' } ] );
+	} );
+
+	it( 'prefers an exact path match over the first section', () => {
+		expect( activeBreadcrumbs( SECTIONS, '/' ) ).toEqual( SECTIONS[ 0 ].breadcrumbs );
+	} );
+
+	it( 'returns [] when the matched section has no breadcrumbs', () => {
+		expect( activeBreadcrumbs( [ { path: '/' } ], '/' ) ).toEqual( [] );
+	} );
+} );
+
+describe( 'appendSectionName', () => {
+	const base = [ { label: 'Access Control' } ];
+
+	it( 'returns the base trail unchanged when sectionName is falsy', () => {
+		expect( appendSectionName( base, undefined ) ).toBe( base );
+		expect( appendSectionName( base, '' ) ).toBe( base );
+		expect( appendSectionName( base, null ) ).toBe( base );
+	} );
+
+	it( 'appends a string sectionName as a leaf crumb', () => {
+		expect( appendSectionName( base, 'Content Gifting' ) ).toEqual( [ { label: 'Access Control' }, { label: 'Content Gifting' } ] );
+	} );
+
+	it( 'appends an array of crumbs in order', () => {
+		const sectionName = [ { label: 'Mailchimp', url: '/mailchimp' }, { label: 'Logs' } ];
+		expect( appendSectionName( base, sectionName ) ).toEqual( [
+			{ label: 'Access Control' },
+			{ label: 'Mailchimp', url: '/mailchimp' },
+			{ label: 'Logs' },
+		] );
+	} );
+
+	it( 'dedupes a string leaf that repeats the current trailing label', () => {
+		const trail = [ { label: 'Access Control' }, { label: 'Metered Countdown' } ];
+		expect( appendSectionName( trail, 'Metered Countdown' ) ).toEqual( trail );
+	} );
+
+	it( 'dedupes an array leaf that repeats the current trailing label', () => {
+		const trail = [ { label: 'Access Control' }, { label: 'Metered Countdown' } ];
+		expect( appendSectionName( trail, [ { label: 'Metered Countdown' } ] ) ).toEqual( trail );
+	} );
+
+	it( 'skips crumbs without a label', () => {
+		expect( appendSectionName( base, [ { url: '/no-label' }, { label: 'Edit' } ] ) ).toEqual( [
+			{ label: 'Access Control' },
+			{ label: 'Edit' },
+		] );
+	} );
+
+	it( 'only dedupes against the immediate predecessor, not earlier crumbs', () => {
+		const trail = [ { label: 'Access Control' }, { label: 'Institutions' } ];
+		// 'Access Control' repeats an earlier (non-adjacent) crumb, so it is kept.
+		expect( appendSectionName( trail, [ { label: 'Access Control' } ] ) ).toEqual( [
+			{ label: 'Access Control' },
+			{ label: 'Institutions' },
+			{ label: 'Access Control' },
+		] );
+	} );
+
+	it( 'does not mutate the input trail', () => {
+		const trail = [ { label: 'Access Control' } ];
+		appendSectionName( trail, 'Content Gifting' );
+		expect( trail ).toEqual( [ { label: 'Access Control' } ] );
+	} );
+} );

package/src/wizard/components/WizardError.js

@@ -3,11 +3,12 @@
  */
 import { __ } from '@wordpress/i18n';
 import { useSelect } from '@wordpress/data';
+import { __experimentalHStack as HStack } from '@wordpress/components'; // eslint-disable-line @wordpress/no-unsafe-wp-apis
 
 /**
  * Internal dependencies.
  */
-import { Button, Card, Modal, Notice } from '../..';
+import { Button, Modal, Notice } from '../..';
 import { WIZARD_STORE_NAMESPACE } from '../store';
 
 const parseError = ( { data, message, code } ) => {
@@ -36,11 +37,11 @@ const WizardError = () => {
 			<Modal title={ __( 'Unrecoverable error' ) } onRequestClose={ fallbackURL ? () => ( window.location = fallbackURL ) : undefined }>
 				<Notice noticeText={ message } isError rawHTML />
 				{ fallbackURL && (
-					<Card buttonsCard noBorder className="justify-end">
+					<HStack justify="flex-end" spacing={ 4 } wrap className="newspack-modal__footer">
 						<Button isPrimary href={ fallbackURL }>
 							{ __( 'Return to Dashboard', 'newspack-plugin' ) }
 						</Button>
-					</Card>
+					</HStack>
 				) }
 			</Modal>
 		);