newspack-components 4.2.0 → 4.4.0-epic-editor-refactor.1

package/src/grid/style.scss

@@ -13,7 +13,7 @@
 
 	// No Margin
 	&--no-margin {
-		margin: 0;
+		margin: 0 !important;
 	}
 
 	// Gutter 0
@@ -41,6 +41,11 @@
 		grid-gap: 32px;
 	}
 
+	// Gutter 64
+	&__gutter-64 {
+		grid-gap: 64px;
+	}
+
 	// Row Gap 0
 	&__row-gap-0 {
 		grid-row-gap: 0;
@@ -61,11 +66,6 @@
 		grid-row-gap: 32px;
 	}
 
-	// Gutter 64
-	&__gutter-64 {
-		grid-gap: 64px;
-	}
-
 	// Columns 6
 	&__columns-6 {
 		grid-template-columns: repeat(2, 1fr);
@@ -77,6 +77,14 @@
 		&__columns-3,
 		&__columns-4 {
 			grid-template-columns: repeat(2, 1fr);
+
+			> [start] {
+				grid-column-start: 1;
+			}
+
+			> [end] {
+				grid-column-end: -1;
+			}
 		}
 
 		&__columns-6 {
@@ -84,8 +92,8 @@
 		}
 	}
 
-	// Media Queries - 1128px
-	@media screen and ( min-width: 1128px ) {
+	// Media Queries - 1054px
+	@media screen and ( min-width: 1054px ) {
 		// Columns 3
 		&__columns-3 {
 			grid-template-columns: repeat(3, 1fr);
@@ -94,6 +102,14 @@
 		// Columns 4
 		&__columns-4 {
 			grid-template-columns: repeat(4, 1fr);
+
+			> [start="2"] {
+				grid-column-start: 2;
+			}
+
+			> [end="4"] {
+				grid-column-end: 4;
+			}
 		}
 
 		// Columns 6
@@ -101,6 +117,11 @@
 			grid-template-columns: repeat(6, 1fr);
 		}
 
+		// Columns 12
+		&__columns-12 {
+			grid-template-columns: repeat(12, 1fr);
+		}
+
 		// Gutter 48
 		&__gutter-48 {
 			grid-gap: 48px;
@@ -116,6 +137,44 @@
 	> * {
 		margin-bottom: 0 !important;
 		margin-top: 0 !important;
+		> h1:first-child,
+		> h2:first-child,
+		> h3:first-child,
+		> h4:first-child,
+		> h5:first-child,
+		> h6:first-child {
+			margin-top: 0;
+		}
+	}
+
+	// Borders
+	&__borders {
+		grid-gap: 0 !important;
+		> * {
+			border-bottom: 1px solid wp-colors.$gray-300;
+			&:last-child {
+				border-bottom: none;
+			}
+			@media screen and ( min-width: 744px ) {
+				border-bottom: none;
+				border-right: 1px solid wp-colors.$gray-300;
+				&:last-child {
+					border-right: none;
+				}
+			}
+		}
+		&.newspack-grid__gutter-8 > * {
+			padding: 8px;
+		}
+		&.newspack-grid__gutter-16 > * {
+			padding: 16px;
+		}
+		&.newspack-grid__gutter-32 > * {
+			padding: 32px;
+		}
+		&.newspack-grid__gutter-64 > * {
+			padding: 64px;
+		}
 	}
 
 	.components-base-control {

package/src/handoff/README.md

@@ -0,0 +1,93 @@
+# Handoff
+
+Navigates the user to another admin page and displays a return banner at the top of the destination so they can find their way back.
+
+## How it works
+
+1. The user clicks the Handoff button.
+2. A POST request registers the current URL as the return destination and stores optional banner customisations.
+3. The user is redirected to the destination page.
+4. A banner appears at the top of that page with a "Back to Newspack" button (or custom text) that returns them to the origin.
+
+## Usage
+
+### With a URL
+
+Use the `url` prop to hand off to any WordPress admin URL. No plugin needs to be installed.
+
+```jsx
+<Handoff url="/wp-admin/admin.php?page=newspack-dashboard#/">
+    Go to Dashboard
+</Handoff>
+```
+
+### With a managed plugin slug
+
+Use the `plugin` prop to hand off to a Newspack-managed plugin. The button is automatically disabled if the plugin is not installed or inactive.
+
+```jsx
+<Handoff plugin="jetpack">
+    Configure Jetpack
+</Handoff>
+```
+
+Use `editLink` to override the destination to a specific page within the plugin:
+
+```jsx
+<Handoff plugin="wordpress-seo" editLink="/wp-admin/admin.php?page=wpseo_dashboard">
+    Configure Yoast SEO
+</Handoff>
+```
+
+### Via ActionCard
+
+`ActionCard` accepts `handoffUrl` (URL-based) or `handoff` (plugin slug) as convenience props that render a `Handoff` as the action button. `bannerText` and `bannerButtonText` are supported on both:
+
+```jsx
+<ActionCard
+    title="My Feature"
+    actionText="Configure"
+    handoffUrl="/wp-admin/admin.php?page=my-settings"
+    bannerText="Return here once you're done."
+    bannerButtonText="Back to My Feature"
+/>
+
+<ActionCard
+    title="Jetpack"
+    actionText="Configure"
+    handoff="jetpack"
+    editLink="/wp-admin/admin.php?page=jetpack#/settings"
+    bannerText="Return here once you're done."
+    bannerButtonText="Back to My Feature"
+/>
+```
+
+## Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `url` | `string` | Admin URL to hand off to. Use this or `plugin`, not both. |
+| `plugin` | `string` | Slug of a Newspack-managed plugin to hand off to. |
+| `editLink` | `string` | Overrides the destination URL when using `plugin`. |
+| `bannerText` | `string` | Custom body text for the return banner. Defaults to "Return to Newspack after completing configuration". |
+| `bannerButtonText` | `string` | Custom label for the return button. Defaults to "Back to Newspack". |
+| `showOnBlockEditor` | `bool` | Show the return banner inside the block editor. Default `false`. |
+| `useModal` | `bool` | Show a confirmation modal before navigating. |
+| `modalTitle` | `string` | Title for the confirmation modal. |
+| `modalBody` | `string` | Body text for the confirmation modal. |
+| `onReady` | `func` | Called with plugin info once loaded (plugin mode only). |
+| `children` | `node` | Button label. Falls back to "Manage {Plugin Name}" in plugin mode. |
+
+All other props are passed through to the underlying `Button` component (`isPrimary`, `isLink`, `isTertiary`, `className`, etc.).
+
+## Banner customisation
+
+```jsx
+<Handoff
+    url="/wp-admin/admin.php?page=my-settings"
+    bannerText="Finish your configuration, then come back here."
+    bannerButtonText="Back to My Feature"
+>
+    Open Settings
+</Handoff>
+```

package/src/handoff/index.js

@@ -31,8 +31,10 @@ class Handoff extends Component {
 
 	componentDidMount = () => {
 		this._isMounted = true;
-		const { plugin } = this.props;
-		this.retrievePluginInfo( plugin );
+		const { plugin, url } = this.props;
+		if ( plugin && ! url ) {
+			this.retrievePluginInfo( plugin );
+		}
 	};
 
 	componentWillUnmount = () => {
@@ -60,8 +62,25 @@ class Handoff extends Component {
 		return assign( defaults, this.props );
 	};
 
+	goToUrl = () => {
+		const { url, showOnBlockEditor, bannerText, bannerButtonText } = this.props;
+		apiFetch( {
+			path: '/newspack/v1/handoff',
+			method: 'POST',
+			data: {
+				destinationUrl: url,
+				handoffReturnUrl: window && window.location.href,
+				showOnBlockEditor: showOnBlockEditor ? true : false,
+				bannerText,
+				bannerButtonText,
+			},
+		} ).then( response => {
+			window.location.href = response.HandoffLink;
+		} );
+	};
+
 	goToPlugin = plugin => {
-		const { editLink, showOnBlockEditor } = this.props;
+		const { editLink, showOnBlockEditor, bannerText, bannerButtonText } = this.props;
 		apiFetch( {
 			path: '/newspack/v1/plugins/' + plugin + '/handoff',
 			method: 'POST',
@@ -69,6 +88,8 @@ class Handoff extends Component {
 				editLink,
 				handoffReturnUrl: window && window.location.href,
 				showOnBlockEditor: showOnBlockEditor ? true : false,
+				bannerText,
+				bannerButtonText,
 			},
 		} ).then( response => {
 			window.location.href = response.HandoffLink;
@@ -92,30 +113,47 @@ class Handoff extends Component {
 			onReady,
 			// eslint-disable-next-line no-unused-vars,@typescript-eslint/no-unused-vars
 			editLink,
+			// eslint-disable-next-line no-unused-vars,@typescript-eslint/no-unused-vars
+			bannerText,
+			// eslint-disable-next-line no-unused-vars,@typescript-eslint/no-unused-vars
+			bannerButtonText,
+			// eslint-disable-next-line no-unused-vars,@typescript-eslint/no-unused-vars
+			url,
 			...otherProps
 		} = this.props;
 		const { pluginInfo, showModal } = this.state;
 		const { modalBody, modalTitle, primaryButton, primaryModalButton, dismissModalButton } = this.textForPlugin( pluginInfo );
 		const { Configured, Name, Slug, Status } = pluginInfo;
 		const classes = classnames( Configured && 'is-configured', className );
+		const goTo = () => ( url ? this.goToUrl() : this.goToPlugin( Slug ) );
 		return (
 			<Fragment>
-				{ Name && 'active' === Status && (
+				{ url && (
+					<Button
+						className={ classes }
+						isSecondary={ ! otherProps.isPrimary && ! otherProps.isTertiary && ! otherProps.isLink }
+						{ ...otherProps }
+						onClick={ () => ( useModal && children ? this.setState( { showModal: true } ) : goTo() ) }
+					>
+						{ children ? children : primaryButton }
+					</Button>
+				) }
+				{ ! url && Name && 'active' === Status && (
 					<Button
 						className={ classes }
 						isSecondary={ ! otherProps.isPrimary && ! otherProps.isTertiary && ! otherProps.isLink }
 						{ ...otherProps }
-						onClick={ () => ( useModal ? this.setState( { showModal: true } ) : this.goToPlugin( Slug ) ) }
+						onClick={ () => ( useModal ? this.setState( { showModal: true } ) : goTo() ) }
 					>
 						{ children ? children : primaryButton }
 					</Button>
 				) }
-				{ Name && 'active' !== Status && (
+				{ ! url && Name && 'active' !== Status && (
 					<Button className={ classes } variant="secondary" disabled { ...otherProps }>
 						{ Name + __( ' not installed', 'newspack-plugin' ) }
 					</Button>
 				) }
-				{ ! Name && (
+				{ ! url && ! Name && (
 					<Button
 						className={ classes }
 						isSecondary={ ! otherProps.isPrimary && ! otherProps.isTertiary && ! otherProps.isLink }
@@ -134,7 +172,7 @@ class Handoff extends Component {
 							<Button variant="secondary" onClick={ () => this.setState( { showModal: false } ) }>
 								{ dismissModalButton }
 							</Button>
-							<Button variant="primary" onClick={ () => this.goToPlugin( Slug ) }>
+							<Button variant="primary" onClick={ goTo }>
 								{ primaryModalButton }
 							</Button>
 						</Card>

package/src/hooks/index.ts

@@ -6,10 +6,11 @@ import { useRef } from '@wordpress/element';
 import usePrompt from './usePrompt';
 import useObjectState from './useObjectState';
 import useOnClickOutside from './useOnClickOutside';
+import useConfirmDialog from './use-confirm-dialog';
 
 const useUniqueId = ( prefix: string ) => {
 	const id = useRef( `${ prefix }-${ Math.round( Math.random() * 99999 ) }` );
 	return id.current;
 };
 
-export default { usePrompt, useObjectState, useOnClickOutside, useUniqueId };
+export default { usePrompt, useObjectState, useOnClickOutside, useUniqueId, useConfirmDialog };

package/src/hooks/use-confirm-dialog.tsx

@@ -0,0 +1,80 @@
+/**
+ * WordPress dependencies.
+ */
+import { useCallback, useRef, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies.
+ */
+import ConfirmDialog from '../confirm-dialog';
+
+type UseConfirmDialogOptions = {
+	when?: boolean;
+	message: React.ReactNode;
+	title?: string;
+	confirmButtonText?: string;
+	cancelButtonText?: string;
+	isDestructive?: boolean;
+	hideTitle?: boolean;
+	size?: 'small' | 'medium' | 'large' | 'x-large' | 'full';
+	className?: string;
+};
+
+type UseConfirmDialogResult = {
+	confirmDialog: React.ReactElement;
+	requestConfirm: ( callback: () => void ) => void;
+};
+
+/**
+ * A hook that encapsulates the ConfirmDialog component and provides a
+ * `requestConfirm` function for imperative use.
+ *
+ * Calling `requestConfirm( callback )` will show a confirmation dialog.
+ * If the user confirms, `callback` is invoked. If the user cancels, it is not.
+ *
+ * When `when` is explicitly `false`, `requestConfirm( callback )` calls
+ * `callback` immediately without showing the dialog. This is useful for
+ * guarding actions that are only destructive when there are unsaved changes
+ * (e.g. `when={ isDirty }`). When `when` is omitted or `true`, the dialog
+ * is always shown.
+ *
+ * The `confirmDialog` element must be rendered somewhere in the component's
+ * JSX for the dialog to appear.
+ */
+function useConfirmDialog( options: UseConfirmDialogOptions ): UseConfirmDialogResult {
+	const { message, when, ...dialogProps } = options;
+	const [ pendingAction, setPendingAction ] = useState< ( () => void ) | null >( null );
+
+	// Keep a ref so `requestConfirm` can always read the latest `when` value
+	// without needing to be recreated on every render.
+	const whenRef = useRef( when );
+	whenRef.current = when;
+
+	const requestConfirm = useCallback( ( callback: () => void ) => {
+		if ( whenRef.current !== false ) {
+			// Store as a thunk to opt out of React's functional-update interpretation.
+			setPendingAction( () => callback );
+		} else {
+			callback();
+		}
+	}, [] );
+
+	const confirmDialog = (
+		<ConfirmDialog
+			{ ...dialogProps }
+			when={ when }
+			isOpen={ !! pendingAction }
+			onConfirm={ () => {
+				pendingAction?.();
+				setPendingAction( null );
+			} }
+			onCancel={ () => setPendingAction( null ) }
+		>
+			{ message }
+		</ConfirmDialog>
+	);
+
+	return { confirmDialog, requestConfirm };
+}
+
+export default useConfirmDialog;

package/src/hooks/use-unsaved-changes-dialog.tsx

@@ -0,0 +1,140 @@
+/**
+ * WordPress dependencies.
+ */
+import { useEffect, useRef } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies.
+ */
+import useConfirmDialog from './use-confirm-dialog';
+
+type UseUnsavedChangesDialogOptions = {
+	when: boolean;
+};
+
+// Stack of mounted guards; the last entry owns the document-level handler so
+// only the most-recently-mounted guard prompts when several are active. Using a
+// stack keeps ownership correct under out-of-order unmounts.
+const activeGuards: symbol[] = [];
+
+/**
+ * Returns true when `href` resolves to the same origin as the current page —
+ * i.e. it is an internal navigation that would unload the wizard. External
+ * `https://...` links, `mailto:`, `tel:`, and other schemes navigate to a new
+ * context (new tab, mail client, dialer) without unloading the wizard, and
+ * must not trigger the discard-changes prompt.
+ */
+function isSameOriginNavigation( link: HTMLAnchorElement ): boolean {
+	try {
+		const url = new URL( link.href, window.location.href );
+		return url.origin === window.location.origin && ( url.protocol === 'http:' || url.protocol === 'https:' );
+	} catch ( e ) {
+		return false;
+	}
+}
+
+/**
+ * Shared unsaved-changes guard. Wraps `useConfirmDialog` with standardized
+ * messaging, intercepts same-origin link clicks so the dialog fires instead
+ * of a silent navigation, and adds a `beforeunload` listener as the last-resort
+ * guard for refresh / tab-close (browser-native, cannot be styled). The
+ * returned `confirmDialog` element must be rendered in JSX.
+ *
+ * Single-consumer constraint: the click handler is attached at the document
+ * level in capture phase. Two simultaneously-active instances will both fire
+ * a dialog. A development-only warning surfaces this.
+ */
+function useUnsavedChangesDialog( { when }: UseUnsavedChangesDialogOptions ) {
+	const { confirmDialog, requestConfirm } = useConfirmDialog( {
+		when,
+		message: __( 'You have unsaved changes that will be lost. Discard changes?', 'newspack-plugin' ),
+		confirmButtonText: __( 'Discard changes', 'newspack-plugin' ),
+		hideTitle: true,
+	} );
+
+	// Tracks navigation the user has already approved via our custom dialog so
+	// the beforeunload guard doesn't fire a second native prompt on top of it.
+	const isNavigatingRef = useRef( false );
+
+	useEffect( () => {
+		if ( ! when ) {
+			return;
+		}
+		const ownerId = Symbol( 'unsaved-changes-guard' );
+		activeGuards.push( ownerId );
+		if ( process.env.NODE_ENV !== 'production' && activeGuards.length > 1 ) {
+			// eslint-disable-next-line no-console
+			console.warn(
+				'useUnsavedChangesDialog: more than one active instance detected. ' +
+					'Document-level click capture will fire a dialog per instance — ensure only one guard is active at a time.'
+			);
+		}
+		const handler = ( e: MouseEvent ) => {
+			// Only the top-of-stack guard prompts, so concurrent guards can't stack dialogs.
+			if ( activeGuards[ activeGuards.length - 1 ] !== ownerId ) {
+				return;
+			}
+			if ( e.defaultPrevented || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0 ) {
+				return;
+			}
+			const target = e.target as HTMLElement | null;
+			const link = target?.closest( 'a[href]' ) as HTMLAnchorElement | null;
+			if ( ! link ) {
+				return;
+			}
+			const href = link.getAttribute( 'href' );
+			if ( ! href || href.startsWith( '#' ) || href.startsWith( 'javascript:' ) ) {
+				// All `#`-prefixed links are skipped here: plain anchors
+				// (`#section`) are scroll targets, and HashRouter paths
+				// (`#/route`) are intercepted by `ConfirmDialog`'s built-in
+				// `history.block` listener instead. Routing them through
+				// `window.location.href` here would trigger a hashchange
+				// that the still-active block re-catches, double-prompting.
+				return;
+			}
+			if ( link.target && link.target !== '_self' ) {
+				return;
+			}
+			// Skip mailto:, tel:, external origins, and any non-http(s) scheme —
+			// they don't unload the wizard, so a discard prompt would be wrong.
+			if ( ! isSameOriginNavigation( link ) ) {
+				return;
+			}
+			e.preventDefault();
+			e.stopPropagation();
+			const destination = link.href;
+			requestConfirm( () => {
+				isNavigatingRef.current = true;
+				window.location.href = destination;
+			} );
+		};
+		document.addEventListener( 'click', handler, true );
+		return () => {
+			document.removeEventListener( 'click', handler, true );
+			const idx = activeGuards.indexOf( ownerId );
+			if ( idx !== -1 ) {
+				activeGuards.splice( idx, 1 );
+			}
+		};
+	}, [ when, requestConfirm ] );
+
+	useEffect( () => {
+		if ( ! when ) {
+			return;
+		}
+		const handler = ( e: BeforeUnloadEvent ) => {
+			if ( isNavigatingRef.current ) {
+				return;
+			}
+			e.preventDefault();
+			e.returnValue = '';
+		};
+		window.addEventListener( 'beforeunload', handler );
+		return () => window.removeEventListener( 'beforeunload', handler );
+	}, [ when ] );
+
+	return { confirmDialog, requestConfirm };
+}
+
+export default useUnsavedChangesDialog;

package/src/image-upload/index.js

@@ -7,11 +7,12 @@
  */
 import { Component } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
+import { BaseControl } from '@wordpress/components';
 
 /**
  * Internal dependencies.
  */
-import { Button, InfoButton } from '../';
+import { Button } from '../';
 import './style.scss';
 
 /**
@@ -72,41 +73,35 @@ class ImageUpload extends Component {
 	 * Render.
 	 */
 	render = () => {
-		const { buttonLabel, className, disabled, help, image, info, isCovering, label, onChange, style = {} } = this.props;
+		const { buttonLabel, className, disabled, help, image, isCovering, label, onChange, style = {} } = this.props;
 		const classes = classnames(
 			'newspack-image-upload__image',
 			{ 'newspack-image-upload__image--has-image': image },
 			{ 'newspack-image-upload__image--covering': isCovering }
 		);
 		return (
-			<div className={ classnames( 'newspack-image-upload', className ) }>
-				<div className="newspack-image-upload__header">
-					{ /* eslint-disable-next-line jsx-a11y/label-has-for, jsx-a11y/label-has-associated-control */ }
-					{ label && <label className="newspack-image-upload__label">{ label }</label> }
-					{ info && <InfoButton text={ info } /> }
-				</div>
-				<div className={ classes } style={ { ...style } }>
+			<BaseControl __nextHasNoMarginBottom className={ classnames( 'newspack-image-upload', className ) } help={ help }>
+				{ label && <BaseControl.VisualLabel>{ label }</BaseControl.VisualLabel> }
+				<div className={ classes } style={ style }>
 					{ image?.url ? (
 						<>
 							<img data-testid="image-upload" src={ image.url } alt={ __( 'Image preview', 'newspack-plugin' ) } />
 							<div className="newspack-image-upload__controls">
-								<Button disabled={ disabled } onClick={ this.openModal } isLink>
+								<Button disabled={ disabled } onClick={ this.openModal } variant="tertiary">
 									{ __( 'Replace', 'newspack-plugin' ) }
 								</Button>
-								<span className="sep" />
-								<Button disabled={ disabled } onClick={ () => onChange( null ) } isLink isDestructive>
+								<Button disabled={ disabled } onClick={ () => onChange( null ) } variant="tertiary" isDestructive>
 									{ __( 'Remove', 'newspack-plugin' ) }
 								</Button>
 							</div>
 						</>
 					) : (
-						<Button disabled={ disabled } onClick={ this.openModal } isLink>
+						<Button disabled={ disabled } onClick={ this.openModal } variant="tertiary">
 							{ buttonLabel ? buttonLabel : __( 'Upload', 'newspack-plugin' ) }
 						</Button>
 					) }
 				</div>
-				{ help && <p className="newspack-image-upload__help">{ help }</p> }
-			</div>
+			</BaseControl>
 		);
 	};
 }