newspack-components 4.8.0 → 4.9.0-alpha.1

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

@@ -9,8 +9,6 @@ import { HashRouter } from 'react-router-dom';
  */
 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>;

package/src/wizard/breadcrumbs-select.js

@@ -11,12 +11,20 @@ import { matchesRoute } from '../route-match';
  * @param {string} pathname Current router pathname.
  * @return {Array} Breadcrumb items `{ label, url? }`.
  */
-export const activeBreadcrumbs = ( sections = [], pathname ) => {
+export const activeBreadcrumbs = ( sections = [], pathname ) => activeSection( sections, pathname )?.breadcrumbs || [];
+
+/**
+ * Select the section matching the current route, falling back to the first.
+ *
+ * @param {Array}  sections Wizard sections.
+ * @param {string} pathname Current router pathname.
+ * @return {Object|undefined} The active section, if any.
+ */
+export const activeSection = ( sections = [], pathname ) => {
 	if ( ! sections?.length ) {
-		return [];
+		return undefined;
 	}
-	const match = sections.find( section => matchesRoute( section, pathname ) ) || sections[ 0 ];
-	return match.breadcrumbs || [];
+	return sections.find( section => matchesRoute( section, pathname ) ) || sections[ 0 ];
 };
 
 /**

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

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies.
  */
-import { activeBreadcrumbs, appendSectionName } from './breadcrumbs-select';
+import { activeBreadcrumbs, activeSection, appendSectionName } from './breadcrumbs-select';
 
 const SECTIONS = [
 	{ path: '/', breadcrumbs: [ { label: 'Audience Management' }, { label: 'Configuration' } ] },
@@ -122,3 +122,17 @@ describe( 'appendSectionName', () => {
 		expect( trail ).toEqual( [ { label: 'Access Control' } ] );
 	} );
 } );
+
+describe( 'activeSection', () => {
+	const sections = [ { path: '/settings', exact: true, subHeaderText: 'Intro' }, { path: '/settings/:integrationId' } ];
+
+	it( 'returns the section matching the route', () => {
+		expect( activeSection( sections, '/settings/esp' ) ).toBe( sections[ 1 ] );
+		expect( activeSection( sections, '/settings' ).subHeaderText ).toBe( 'Intro' );
+	} );
+
+	it( 'falls back to the first section, or nothing without sections', () => {
+		expect( activeSection( sections, '/unknown' ) ).toBe( sections[ 0 ] );
+		expect( activeSection( [], '/settings' ) ).toBeUndefined();
+	} );
+} );

package/src/wizard/index.js

@@ -6,27 +6,26 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies.
  */
-// Notice is aliased: `Notice` below is Newspack's own, which this file also uses.
 import {
 	DropdownMenu,
 	MenuGroup,
 	MenuItem,
-	Notice as CoreNotice,
+	Notice,
 	SlotFillProvider,
 	createSlotFill,
 	// eslint-disable-next-line @wordpress/no-unsafe-wp-apis
 	__experimentalVStack as VStack,
 } from '@wordpress/components';
 import { useDispatch, useSelect } from '@wordpress/data';
-import { cloneElement, createInterpolateElement, isValidElement, useEffect, useRef, useState, forwardRef } from '@wordpress/element';
+import { cloneElement, createInterpolateElement, isValidElement, useLayoutEffect, useRef, useState, forwardRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { category, chevronLeft, moreVertical } from '@wordpress/icons';
 
 /**
  * Internal dependencies
  */
-import { Footer, Notice, Button, TabbedNavigation, PluginInstaller, SectionHeader, HandoffMessage, Page, Waiting } from '../';
-import { activeBreadcrumbs, appendSectionName } from './breadcrumbs-select';
+import { Footer, DebugBadge, Button, TabbedNavigation, PluginInstaller, SectionHeader, HandoffMessage, Page, Waiting } from '../';
+import { activeBreadcrumbs, activeSection, appendSectionName } from './breadcrumbs-select';
 import Router from '../proxied-imports/router';
 import registerStore, { WIZARD_STORE_NAMESPACE } from './store';
 import WizardSnackbar from './components/WizardSnackbar';
@@ -55,7 +54,7 @@ const resolveIcon = icon => {
 	return icon;
 };
 
-const { HashRouter, Redirect, Route, Switch, useLocation } = Router;
+const { HashRouter, Redirect, Route, Switch, matchPath, useLocation } = Router;
 
 /**
  * Interpolate a translated message's named tags, falling back to plain text.
@@ -92,7 +91,9 @@ const ResetHeaderData = () => {
 	const location = useLocation();
 	const { resetHeaderData } = useDispatch( WIZARD_STORE_NAMESPACE );
 
-	useEffect( () => {
+	// Must stay before paint: a passive effect here would run after a section that
+	// publishes from a layout effect, wiping the header it just set.
+	useLayoutEffect( () => {
 		resetHeaderData();
 		window.scrollTo( 0, 0 );
 	}, [ location.pathname, resetHeaderData ] );
@@ -104,9 +105,35 @@ const ResetHeaderData = () => {
  * Wizard header + content region. Rendered inside the wizard's HashRouter so it
  * can read the current route and derive the active-tab breadcrumb.
  */
-const WizardHeaderRegion = ( { hideHeader, headerText, sections, sectionName, subTitle, actions, tabbedNavigation, children } ) => {
+const WizardHeaderRegion = ( {
+	hideHeader,
+	headerText,
+	sections,
+	sectionName,
+	subTitle,
+	actions,
+	tabbedNavigation: wizardTabbedNavigation,
+	children,
+} ) => {
 	const { pathname } = useLocation();
 
+	// A section can carry its own tabs, built from its route params, in place of
+	// the wizard's. The first match wins, as it does in the wizard's `<Switch>`.
+	let tabbedNavigation = wizardTabbedNavigation;
+	for ( const section of sections ) {
+		const match = matchPath( pathname, { path: section.path, exact: section.exact ?? false } );
+		if ( match ) {
+			if ( typeof section.tabbedNavigation === 'function' ) {
+				tabbedNavigation = (
+					<TabbedNavigation items={ section.tabbedNavigation( match.params ) }>
+						<WizardError />
+					</TabbedNavigation>
+				);
+			}
+			break;
+		}
+	}
+
 	if ( hideHeader ) {
 		// Without the Page shell the tabs still own the content: it renders
 		// inside the active tab's panel.
@@ -124,8 +151,10 @@ const WizardHeaderRegion = ( { hideHeader, headerText, sections, sectionName, su
 	// headerData.sectionName (deduped against the current trailing label).
 	breadcrumbItems = appendSectionName( breadcrumbItems, sectionName );
 
+	const sectionSubTitle = activeSection( sections, pathname )?.subHeaderText;
+
 	return (
-		<Page breadcrumbItems={ breadcrumbItems } subTitle={ subTitle } actions={ actions } tabbedNavigation={ tabbedNavigation }>
+		<Page breadcrumbItems={ breadcrumbItems } subTitle={ sectionSubTitle ?? subTitle } actions={ actions } tabbedNavigation={ tabbedNavigation }>
 			{ children }
 		</Page>
 	);
@@ -137,7 +166,8 @@ const WizardHeaderRegion = ( { hideHeader, headerText, sections, sectionName, su
  * @property {string}     [subHeaderText]           The sub-header text, optional.
  * @property {string}     [apiSlug]                 The API slug, optional.
  * @property {string}     [className]               CSS classes, optional.
- * @property {any[]}      sections                  Array of sections.
+ * @property {any[]}      sections                  Array of sections. A section's own `subHeaderText` replaces the wizard's while it is active.
+ *                                                  Its optional `tabbedNavigation( params )` returns the tab items shown while its route matches.
  * @property {boolean}    [hasSimpleFooter]         Indicates if a simple footer is used, optional.
  * @property {() => void} [renderAboveSections]     Function to render content above sections, optional.
  * @property {string[]}   [requiredPlugins]         Array of required plugin strings, optional.
@@ -177,6 +207,7 @@ const Wizard = (
 		actions,
 		backNav,
 		badges,
+		fullWidth: headerFullWidth,
 		sectionDescription,
 		sectionMenu,
 		sectionName,
@@ -269,7 +300,7 @@ const Wizard = (
 	// as page chrome rather than as content.
 	const inertGating = window.newspack_aux_data?.inert_gating;
 	const inertGatingNotice = inertGating?.show && (
-		<CoreNotice status="warning" isDismissible={ false } className="newspack-wizard__inert-gating-notice">
+		<Notice status="warning" isDismissible={ false } className="newspack-wizard__inert-gating-notice">
 			{ /* The conversion map takes childless elements and fills them from the
 			     translated string, so jsx-a11y can't see the content they end up with. */ }
 			{ interpolateOrPlainText( inertGating.message, {
@@ -279,7 +310,7 @@ const Wizard = (
 				/* eslint-enable jsx-a11y/anchor-has-content */
 				strong: <strong />,
 			} ) }
-		</CoreNotice>
+		</Notice>
 	);
 
 	const content = (
@@ -303,7 +334,7 @@ const Wizard = (
 								render={ routerProps => (
 									<div
 										className={ classnames( 'newspack-wizard__content', className, {
-											'newspack-wizard__content--full-width': section.fullWidth,
+											'newspack-wizard__content--full-width': headerFullWidth ?? section.fullWidth,
 										} ) }
 									>
 										{ 'function' === typeof renderAboveSections ? renderAboveSections() : null }
@@ -403,7 +434,7 @@ const Wizard = (
 					} ) }
 				>
 					<HashRouter hashType="slash">
-						{ newspack_aux_data.is_debug_mode && <Notice debugMode /> }
+						<DebugBadge />
 						<WizardHeaderRegion
 							hideHeader={ hideHeader }
 							headerText={ headerText }

package/src/wizard/index.test.js

@@ -7,19 +7,22 @@ import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
  * WordPress dependencies.
  */
 import apiFetch from '@wordpress/api-fetch';
+import { select, useDispatch } from '@wordpress/data';
+import { useLayoutEffect, useState } from '@wordpress/element';
 
 /**
  * Internal dependencies.
  */
 import Wizard from './';
 import { useWizardData } from './store/utils';
+import { WIZARD_STORE_NAMESPACE } from './store';
 
 jest.mock( '@wordpress/api-fetch', () => jest.fn() );
 
-// Both globals are localized onto every real wizard screen. The footer's
-// ExternalLink needs a string href, and the debug Notice reads aux data.
-window.newspack_aux_data = { is_debug_mode: false };
+// Localized onto every real wizard screen; the footer's ExternalLink needs a
+// string href.
 window.newspack_urls = { support: 'https://help.newspack.com/' };
+window.scrollTo = jest.fn();
 
 const SETTINGS = { minimumDonation: '5' };
 
@@ -154,3 +157,166 @@ describe( 'Wizard', () => {
 		expect( counts.wizard ).toBe( 0 );
 	} );
 } );
+
+const NarrowingSection = () => {
+	const { setHeaderData } = useDispatch( WIZARD_STORE_NAMESPACE );
+	useLayoutEffect( () => {
+		setHeaderData( { fullWidth: false } );
+	}, [ setHeaderData ] );
+	return <div>Narrowing section</div>;
+};
+
+const RecoveringSection = () => {
+	const { setHeaderData } = useDispatch( WIZARD_STORE_NAMESPACE );
+	const [ failed, setFailed ] = useState( true );
+	useLayoutEffect( () => {
+		setHeaderData( { fullWidth: failed ? false : undefined } );
+	}, [ setHeaderData, failed ] );
+	return <button onClick={ () => setFailed( false ) }>Retry</button>;
+};
+
+// Two sections, because that is what mounts ResetHeaderData: a single-section
+// wizard never exercises the reset these overrides have to survive.
+const widthSections = renderSection => [
+	{ label: 'List', path: '/', exact: true, fullWidth: true, render: renderSection },
+	{ label: 'Other', path: '/other', render: () => <div>Other section</div> },
+];
+
+describe( 'Wizard content width', () => {
+	beforeEach( () => {
+		apiFetch.mockReset();
+	} );
+
+	it( 'renders full-width when the section declares it and nothing overrides it', async () => {
+		const { container } = render(
+			<Wizard
+				headerText="Test wizard"
+				sections={ widthSections( () => (
+					<div>List content</div>
+				) ) }
+			/>
+		);
+
+		expect( await screen.findByText( 'List content' ) ).toBeInTheDocument();
+		expect( container.querySelector( '.newspack-wizard__content' ) ).toHaveClass( 'newspack-wizard__content--full-width' );
+	} );
+
+	it( 'falls back to the standard width when a section overrides fullWidth before paint', async () => {
+		const { container } = render(
+			<Wizard
+				headerText="Test wizard"
+				sections={ widthSections( () => (
+					<NarrowingSection />
+				) ) }
+			/>
+		);
+
+		expect( await screen.findByText( 'Narrowing section' ) ).toBeInTheDocument();
+		expect( container.querySelector( '.newspack-wizard__content' ) ).not.toHaveClass( 'newspack-wizard__content--full-width' );
+	} );
+
+	it( 'restores the declared width when the section clears its override', async () => {
+		const { container } = render(
+			<Wizard
+				headerText="Test wizard"
+				sections={ widthSections( () => (
+					<RecoveringSection />
+				) ) }
+			/>
+		);
+
+		const retry = await screen.findByRole( 'button', { name: 'Retry' } );
+		expect( container.querySelector( '.newspack-wizard__content' ) ).not.toHaveClass( 'newspack-wizard__content--full-width' );
+
+		fireEvent.click( retry );
+
+		await waitFor( () => expect( container.querySelector( '.newspack-wizard__content' ) ).toHaveClass( 'newspack-wizard__content--full-width' ) );
+	} );
+
+	it( 'keeps a section header published from a layout effect through the mount reset', async () => {
+		render(
+			<Wizard
+				headerText="Test wizard"
+				sections={ widthSections( () => (
+					<NarrowingSection />
+				) ) }
+			/>
+		);
+
+		expect( await screen.findByText( 'Narrowing section' ) ).toBeInTheDocument();
+		expect( select( WIZARD_STORE_NAMESPACE ).getHeaderData().fullWidth ).toBe( false );
+	} );
+} );
+
+describe( 'Wizard section tabs', () => {
+	const sections = [
+		{ label: 'List', path: '/', exact: true, render: () => <div>List content</div> },
+		{
+			path: '/items/:itemId/logs/:tab?',
+			isHidden: true,
+			render: () => <div>Logs content</div>,
+			tabbedNavigation: ( { itemId } ) => [
+				{ label: 'First Tab', path: `/items/${ itemId }/logs`, exact: true },
+				{ label: 'Second Tab', path: `/items/${ itemId }/logs/second`, exact: true },
+			],
+		},
+	];
+
+	beforeEach( () => {
+		apiFetch.mockReset();
+	} );
+
+	afterEach( () => {
+		window.location.hash = '';
+	} );
+
+	it( 'shows the tabs a section builds from its route params while it matches', async () => {
+		window.location.hash = '#/items/42/logs/second';
+		render( <Wizard headerText="Test wizard" sections={ sections } /> );
+
+		expect( await screen.findByText( 'Logs content' ) ).toBeInTheDocument();
+		expect( screen.getByRole( 'tab', { name: 'First Tab' } ) ).toHaveAttribute( 'href', '#/items/42/logs' );
+		expect( screen.getByRole( 'tab', { name: 'Second Tab' } ) ).toHaveAttribute( 'aria-selected', 'true' );
+	} );
+
+	it( 'leaves the tabs out on a route the section does not match', async () => {
+		window.location.hash = '#/';
+		render( <Wizard headerText="Test wizard" sections={ sections } /> );
+
+		expect( await screen.findByText( 'List content' ) ).toBeInTheDocument();
+		expect( screen.queryByRole( 'tab' ) ).toBeNull();
+	} );
+} );
+
+describe( 'Wizard section subtitle', () => {
+	beforeEach( () => {
+		apiFetch.mockReset();
+		apiFetch.mockResolvedValue( {} );
+	} );
+
+	it( "shows the active section's subHeaderText in the header, falling back to the wizard's", async () => {
+		window.location.hash = '#/list';
+		const { container } = render(
+			<Wizard
+				headerText="Test wizard"
+				subHeaderText="Wizard intro"
+				sections={ [
+					{ label: 'List', path: '/list', exact: true, subHeaderText: 'List intro', render: () => <div>List view</div> },
+					{ label: 'Item', path: '/list/:id', isHidden: true, render: () => <div>Item view</div> },
+				] }
+			/>
+		);
+		const subtitle = () => container.querySelector( '.newspack-page__header-subtitle' )?.textContent;
+
+		expect( await screen.findByText( 'List view' ) ).toBeInTheDocument();
+		expect( subtitle() ).toBe( 'List intro' );
+
+		act( () => {
+			window.location.hash = '#/list/esp';
+			window.dispatchEvent( new HashChangeEvent( 'hashchange' ) );
+		} );
+
+		expect( await screen.findByText( 'Item view' ) ).toBeInTheDocument();
+		expect( subtitle() ).toBe( 'Wizard intro' );
+	} );
+} );

package/src/wizard/store/index.js

@@ -16,6 +16,8 @@ import { createAction } from './utils.js';
 export const WIZARD_STORE_NAMESPACE = 'newspack/wizards';
 
 const DEFAULT_STATE = {
+	// `fullWidth` is deliberately absent: a default here would narrow every
+	// full-width section on reset, since Wizard only falls back when it is unset.
 	headerData: {
 		actions: [],
 		backNav: '',