newspack-components 4.6.3 → 4.7.0-alpha.2

package/src/drawer/style.scss

@@ -0,0 +1,205 @@
+@use "~@wordpress/base-styles/breakpoints" as wp-breakpoints;
+@use "~@wordpress/base-styles/colors" as wp-colors;
+@use "~@wordpress/base-styles/variables" as wp-vars;
+
+$drawer-size-small: 280px;
+$drawer-size-medium: 350px;
+$drawer-size-large: 480px;
+$drawer-size-x-large: 640px;
+
+.newspack-drawer,
+.newspack-drawer *,
+.newspack-drawer *::before,
+.newspack-drawer *::after {
+	box-sizing: border-box;
+}
+
+.newspack-drawer {
+	display: flex;
+	flex-direction: column;
+}
+
+.components-modal__screen-overlay.newspack-drawer__overlay {
+	align-items: stretch;
+	justify-content: flex-end;
+	padding: 0;
+}
+
+.components-modal__frame.newspack-drawer {
+	animation: 0.2s ease-out newspack-drawer-slide-in;
+	border-radius: wp-vars.$radius-large 0 0 wp-vars.$radius-large;
+	height: 100%;
+	margin: 0;
+	max-height: none;
+	min-width: 0;
+	overflow: hidden;
+	width: 100%;
+
+	&.is-exiting {
+		animation: 0.2s ease-in forwards newspack-drawer-slide-out;
+	}
+
+	.components-modal__content {
+		display: flex;
+		flex-direction: column;
+		padding: 0;
+	}
+
+	.components-modal__children-container {
+		display: flex;
+		flex: 1 1 auto;
+		flex-direction: column;
+		min-height: 0;
+	}
+
+	&.newspack-drawer--size-small { max-width: $drawer-size-small; }
+	&.newspack-drawer--size-medium { max-width: $drawer-size-medium; }
+	&.newspack-drawer--size-large { max-width: $drawer-size-large; }
+	&.newspack-drawer--size-x-large { max-width: $drawer-size-x-large; }
+	&.newspack-drawer--size-full {
+		border-radius: 0;
+		max-width: 100vw;
+	}
+
+	@media (max-width: $drawer-size-x-large) {
+		&.newspack-drawer--size-x-large {
+			border-radius: 0;
+		}
+	}
+
+	@media (max-width: wp-breakpoints.$break-small) {
+		&.newspack-drawer--size-small,
+		&.newspack-drawer--size-medium,
+		&.newspack-drawer--size-large,
+		&.newspack-drawer--size-x-large,
+		&.newspack-drawer--size-full {
+			border-radius: 0;
+			max-width: 100vw;
+		}
+	}
+}
+
+.newspack-drawer__header {
+	align-items: center;
+	display: flex;
+	flex: 0 0 auto;
+	gap: wp-vars.$grid-unit-10;
+	padding: wp-vars.$grid-unit-30 wp-vars.$grid-unit-30 wp-vars.$grid-unit-20;
+}
+
+.newspack-drawer__icon {
+	fill: currentcolor;
+	flex: none;
+}
+
+.newspack-drawer__title {
+	flex: 1;
+	font-size: inherit;
+	font-weight: wp-vars.$font-weight-medium;
+	margin: 0;
+	min-width: 0;
+}
+
+.newspack-drawer__dismiss {
+	flex: none;
+	margin-left: auto;
+}
+
+.newspack-drawer__body {
+	flex: 1 1 auto;
+	overflow-y: auto;
+
+	> * {
+		flex: none;
+	}
+}
+
+.newspack-drawer__content {
+	padding: var(--newspack-drawer-content-padding, #{wp-vars.$grid-unit-30});
+
+	> * {
+		margin-bottom: 0;
+		margin-top: 0;
+	}
+}
+
+.newspack-drawer__divider {
+	border: 0;
+	border-top: wp-vars.$border-width solid wp-colors.$gray-300;
+	margin: 0;
+}
+
+.newspack-drawer__header + .newspack-drawer__body .newspack-drawer__content:first-child {
+	padding-top: 0;
+}
+
+.newspack-drawer__body:has(+ .newspack-drawer__footer) .newspack-drawer__content:last-child {
+	padding-bottom: 0;
+}
+
+.newspack-drawer__footer {
+	background: wp-colors.$white;
+	display: flex;
+	flex: 0 0 auto;
+	gap: wp-vars.$grid-unit-10;
+	padding: wp-vars.$grid-unit-20 wp-vars.$grid-unit-30 wp-vars.$grid-unit-30;
+
+	> .components-button {
+		flex: 1;
+		justify-content: center;
+	}
+
+	&:has(> :nth-child(3)) {
+		flex-direction: column;
+
+		> .components-button {
+			flex: 0 0 auto;
+		}
+	}
+}
+
+@keyframes newspack-drawer-slide-in {
+	from {
+		transform: translateX(100%);
+	}
+
+	to {
+		transform: translateX(0);
+	}
+}
+
+@keyframes newspack-drawer-slide-out {
+	from {
+		transform: translateX(0);
+	}
+
+	to {
+		transform: translateX(100%);
+	}
+}
+
+@keyframes newspack-drawer-overlay-fade-out {
+	from {
+		opacity: 1;
+	}
+
+	to {
+		opacity: 0;
+	}
+}
+
+.newspack-drawer__overlay.is-exiting {
+	animation: 0.2s ease-in forwards newspack-drawer-overlay-fade-out;
+}
+
+.components-modal__frame.newspack-drawer .components-popover__content {
+	opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.components-modal__frame.newspack-drawer,
+	.components-modal__frame.newspack-drawer.is-exiting,
+	.newspack-drawer__overlay.is-exiting {
+		animation: none;
+	}
+}

package/src/drawer/title.tsx

@@ -0,0 +1,40 @@
+/**
+ * WordPress dependencies.
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { useLayoutEffect } from '@wordpress/element';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import { useDrawerContext } from './context';
+import type { DrawerTitleProps } from './types';
+
+const Title = ( { className, children }: DrawerTitleProps ) => {
+	const { setTitle } = useDrawerContext();
+	const id = useInstanceId( Title, 'newspack-drawer__title' ) as string;
+
+	// Derived, not keyed on `children`: a JSX title would re-register every render.
+	const text = typeof children === 'string' ? children : null;
+
+	useLayoutEffect( () => {
+		setTitle( { id, text } );
+	}, [ id, text, setTitle ] );
+
+	// Unmount only, scoped to this id: a text change must not re-order the stack,
+	// nor a second title unname the one still rendered.
+	useLayoutEffect( () => () => setTitle( null, id ), [ id, setTitle ] );
+
+	return (
+		<h2 className={ classnames( 'newspack-drawer__title', className ) } id={ id }>
+			{ children }
+		</h2>
+	);
+};
+
+export default Title;

package/src/drawer/types.ts

@@ -0,0 +1,79 @@
+export type DrawerSize = 'small' | 'medium' | 'large' | 'x-large' | 'full';
+
+/** `text` is null unless the title's children are a plain string. */
+export type DrawerTitleInfo = {
+	id: string;
+	text: string | null;
+};
+
+export type DrawerRootProps = {
+	isOpen?: boolean;
+	size?: DrawerSize;
+	onRequestClose: () => void;
+	isDirty?: boolean;
+	confirmCloseMessage?: React.ReactNode;
+	confirmButtonText?: string;
+	requestConfirm?: ( callback: () => void ) => void;
+	contentLabel?: string;
+	describedBy?: string;
+	className?: string;
+	/** Merged into the frame's own style. A `ref` reaches the overlay around it. */
+	style?: React.CSSProperties;
+	children?: React.ReactNode;
+};
+
+export type DrawerHeaderProps = {
+	className?: string;
+	children?: React.ReactNode;
+};
+
+export type DrawerTitleProps = {
+	className?: string;
+	children?: React.ReactNode;
+};
+
+export type DrawerCloseIconProps = {
+	label?: string;
+	icon?: JSX.Element;
+	className?: string;
+};
+
+export type DrawerContentProps = {
+	/** 4px scale, as VStack's `spacing`. `0` for a flush section. */
+	padding?: number;
+	/** 4px scale, as VStack's `spacing`. */
+	gap?: number;
+	className?: string;
+	children?: React.ReactNode;
+};
+
+export type DrawerDividerProps = {
+	className?: string;
+};
+
+export type DrawerBodyProps = {
+	children?: React.ReactNode;
+};
+
+export type DrawerFooterProps = {
+	className?: string;
+	children?: React.ReactNode;
+};
+
+/** `ariaLabel` extends the visible label and must contain it (WCAG 2.5.3, Label in Name). */
+type DrawerActionBaseProps = {
+	ariaLabel?: string;
+	variant?: 'primary' | 'secondary' | 'tertiary' | 'link';
+	disabled?: boolean;
+	isBusy?: boolean;
+	isDestructive?: boolean;
+	className?: string;
+	children?: React.ReactNode;
+};
+
+/** An action either navigates or acts: `href` cannot close the drawer or run a handler. */
+export type DrawerActionProps = DrawerActionBaseProps &
+	(
+		| { href: string; onClick?: never; closes?: never }
+		| { href?: null; onClick?: ( event?: React.MouseEvent< HTMLElement > ) => void; closes?: boolean }
+	);

package/src/drawer/use-exit-animation.ts

@@ -0,0 +1,46 @@
+/**
+ * WordPress dependencies.
+ */
+import { useReducedMotion } from '@wordpress/compose';
+import { useEffect, useState } from '@wordpress/element';
+
+// Covers an animationend that never arrives.
+const EXIT_FALLBACK_MS = 400;
+
+function useExitAnimation( isOpen: boolean, node: HTMLElement | null ) {
+	const [ isExiting, setIsExiting ] = useState( false );
+	const [ wasOpen, setWasOpen ] = useState( isOpen );
+
+	// The stylesheet zeroes the animation here, so animationend never fires and the
+	// fallback would hold a visible panel for 400ms.
+	const prefersReducedMotion = useReducedMotion();
+
+	// During render: a commit later the panel would leave the DOM and remount.
+	if ( wasOpen !== isOpen ) {
+		setWasOpen( isOpen );
+		setIsExiting( ! isOpen && ! prefersReducedMotion );
+	}
+
+	useEffect( () => {
+		if ( ! isExiting ) {
+			return;
+		}
+		// Keyed on the name: animationend bubbles from anything else animating.
+		const finish = ( event?: AnimationEvent ) => {
+			if ( event?.animationName && 'newspack-drawer-slide-out' !== event.animationName ) {
+				return;
+			}
+			setIsExiting( false );
+		};
+		const timer = setTimeout( finish, EXIT_FALLBACK_MS );
+		node?.addEventListener( 'animationend', finish );
+		return () => {
+			clearTimeout( timer );
+			node?.removeEventListener( 'animationend', finish );
+		};
+	}, [ isExiting, node ] );
+
+	return { isRendered: isOpen || isExiting, isExiting };
+}
+
+export default useExitAnimation;

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

@@ -23,6 +23,7 @@ type UseConfirmDialogOptions = {
 type UseConfirmDialogResult = {
 	confirmDialog: React.ReactElement;
 	requestConfirm: ( callback: () => void ) => void;
+	cancelConfirm: () => void;
 };
 
 /**
@@ -40,6 +41,9 @@ type UseConfirmDialogResult = {
  *
  * The `confirmDialog` element must be rendered somewhere in the component's
  * JSX for the dialog to appear.
+ *
+ * `cancelConfirm()` withdraws a pending request without invoking its callback,
+ * for when whatever raised the prompt goes away on its own.
  */
 function useConfirmDialog( options: UseConfirmDialogOptions ): UseConfirmDialogResult {
 	const { message, when, ...dialogProps } = options;
@@ -59,14 +63,21 @@ function useConfirmDialog( options: UseConfirmDialogOptions ): UseConfirmDialogR
 		}
 	}, [] );
 
+	const cancelConfirm = useCallback( () => setPendingAction( null ), [] );
+
 	const confirmDialog = (
 		<ConfirmDialog
 			{ ...dialogProps }
 			when={ when }
 			isOpen={ !! pendingAction }
 			onConfirm={ () => {
-				pendingAction?.();
-				setPendingAction( null );
+				// Cleared either way: a throwing callback would otherwise leave the
+				// dialog permanently unraisable for this instance.
+				try {
+					pendingAction?.();
+				} finally {
+					setPendingAction( null );
+				}
 			} }
 			onCancel={ () => setPendingAction( null ) }
 		>
@@ -74,7 +85,7 @@ function useConfirmDialog( options: UseConfirmDialogOptions ): UseConfirmDialogR
 		</ConfirmDialog>
 	);
 
-	return { confirmDialog, requestConfirm };
+	return { confirmDialog, requestConfirm, cancelConfirm };
 }
 
 export default useConfirmDialog;

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

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies.
  */
-import { useEffect, useRef } from '@wordpress/element';
+import { useCallback, useEffect, useRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 
 /**
@@ -39,17 +39,20 @@ function isSameOriginNavigation( link: HTMLAnchorElement ): boolean {
  * 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.
+ * returned `confirmDialog` element must be rendered in JSX, and `requestConfirm`
+ * and `cancelConfirm` behave as `useConfirmDialog` documents them.
  *
  * 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( {
+	const { confirmDialog, requestConfirm, cancelConfirm } = useConfirmDialog( {
 		when,
 		message: __( 'You have unsaved changes that will be lost. Discard changes?', 'newspack-plugin' ),
-		confirmButtonText: __( 'Discard changes', 'newspack-plugin' ),
+		confirmButtonText: __( 'Discard Changes', 'newspack-plugin' ),
+		// Hidden, but still the dialog's accessible name.
+		title: __( 'Unsaved changes', 'newspack-plugin' ),
 		hideTitle: true,
 	} );
 
@@ -134,7 +137,16 @@ function useUnsavedChangesDialog( { when }: UseUnsavedChangesDialogOptions ) {
 		return () => window.removeEventListener( 'beforeunload', handler );
 	}, [ when ] );
 
-	return { confirmDialog, requestConfirm };
+	// Escape hatch for an action that navigates on its own — a handoff that
+	// POSTs and then assigns `window.location` — once the dialog has already
+	// been confirmed. Left armed, the beforeunload guard would draw a second,
+	// native prompt on top of it. Call it immediately before navigating, so a
+	// failed action leaves the guard in place.
+	const allowNextUnload = useCallback( () => {
+		isNavigatingRef.current = true;
+	}, [] );
+
+	return { confirmDialog, requestConfirm, cancelConfirm, allowNextUnload };
 }
 
 export default useUnsavedChangesDialog;

package/src/index.js

@@ -19,6 +19,7 @@ export { default as ConfirmDialog } from './confirm-dialog';
 export { default as CustomSelectControl } from './custom-select-control';
 export { default as DataViews } from './dataviews';
 export { default as Divider } from './divider';
+export { default as Drawer } from './drawer';
 export { default as FormTokenField } from './form-token-field';
 export { default as Footer } from './footer';
 export { default as Handoff } from './handoff';
@@ -31,6 +32,7 @@ export { default as Modal } from './modal';
 export { default as NewspackIcon } from './newspack-icon';
 export { default as Notice } from './notice';
 export { default as Page } from './page';
+export { default as PageControl } from './page-control';
 export { default as PluginInstaller } from './plugin-installer';
 export { default as PluginSettings } from './plugin-settings';
 export { default as PluginToggle } from './plugin-toggle';
@@ -44,10 +46,12 @@ export { default as StepsList } from './steps-list';
 export { default as StepsListItem } from './steps-list-item';
 export { default as StyleCard } from './style-card';
 export { default as TabbedNavigation } from './tabbed-navigation';
+export { default as TableCard } from './table-card';
 export { default as TextControl } from './text-control';
 export { default as Waiting } from './waiting';
 export { default as WebPreview } from './web-preview';
 export { default as Wizard } from './wizard';
+export { WizardBanner } from './wizard';
 export { default as withWizard } from './with-wizard';
 export { default as withWizardScreen } from './with-wizard-screen';
 

package/src/page/index.js

@@ -39,7 +39,7 @@ import './style.scss';
  *                                          inside its active tab panel — or, when no visible tab
  *                                          owns the route, as a sibling of the panels.
  * @param {string} [props.className]
- * @param {*}      props.children
+ * @param {*}      [props.children]
  * @return {JSX.Element} Page component.
  */
 const Page = ( { breadcrumbItems = [], badges, subTitle, actions, tabbedNavigation, className, children } ) => {

package/src/page-control/index.js

@@ -0,0 +1,63 @@
+/**
+ * Page Control.
+ *
+ * A single-page selector backed by an autocomplete search, for settings that point at a
+ * page without enumerating every page the site has.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useState } from '@wordpress/element';
+import { decodeEntities } from '@wordpress/html-entities';
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { AutocompleteWithSuggestions } from '../';
+
+/**
+ * Render a single-page selector.
+ *
+ * @param {Object}   props          Component props.
+ * @param {string}   props.label    Field label.
+ * @param {string}   props.help     Help text.
+ * @param {boolean}  props.disabled Whether the field is disabled (e.g. while saving).
+ * @param {Object}   props.selected The saved page as `{ label, value }`, if any.
+ * @param {Function} props.onChange Called with the selected page ID, or '' when cleared.
+ */
+const PageControl = ( { label, help, disabled, selected, onChange } ) => {
+	// Titles arrive HTML-encoded from the server, while the autocomplete decodes the
+	// suggestions it fetches. Decode here so the saved page and the search results below
+	// it render the same way.
+	const normalize = item => ( item ? { ...item, label: decodeEntities( item.label ) } : null );
+	const [ selectedItem, setSelectedItem ] = useState( normalize( selected ) );
+	// Settings are fetched after this control first renders, so adopt the saved page
+	// whenever it arrives or changes rather than only on mount.
+	useEffect( () => {
+		setSelectedItem( normalize( selected ) );
+	}, [ selected?.value, selected?.label ] );
+	return (
+		<fieldset disabled={ disabled } className="newspack-page-control">
+			<AutocompleteWithSuggestions
+				label={ label }
+				help={ help }
+				postTypes={ [ { slug: 'page', label: __( 'Page', 'newspack-plugin' ) } ] }
+				postTypeLabel={ __( 'page', 'newspack-plugin' ) }
+				postTypeLabelPlural={ __( 'pages', 'newspack-plugin' ) }
+				selectedItems={ selectedItem ? [ selectedItem ] : [] }
+				onChange={ items => {
+					if ( disabled ) {
+						return;
+					}
+					const item = items && items.length ? items[ items.length - 1 ] : null;
+					setSelectedItem( normalize( item ) );
+					onChange( item ? String( item.value ) : '' );
+				} }
+			/>
+		</fieldset>
+	);
+};
+
+export default PageControl;

package/src/plugin-settings/SettingsSection.js

@@ -13,13 +13,17 @@ import { CheckboxControl } from '@wordpress/components';
 /**
  * Internal dependencies
  */
-import { ActionCard, Button, Grid, Notice, SelectControl, TextControl } from '../';
+import { ActionCard, Button, Grid, Notice, PageControl, SelectControl, TextControl } from '../';
 import './style.scss';
 
 const isSelectControl = setting => {
 	return Array.isArray( setting.options ) && setting.options.length;
 };
 const getControlComponent = setting => {
+	// An explicit `control` overrides the control implied by the setting's data type.
+	if ( 'page' === setting.control ) {
+		return PageControl;
+	}
 	if ( isSelectControl( setting ) ) {
 		return SelectControl;
 	}
@@ -66,6 +70,8 @@ const SettingsSection = props => {
 				label: option.name || option.label,
 			} ) ) || null,
 		value: setting.value,
+		// Only page controls consume `selected`; keep it off every other control's props.
+		selected: 'page' === setting.control ? setting.selected || null : null,
 		multiple: isSelectControl( setting ) && setting.multiple ? true : null,
 		checked: setting.type === 'boolean' ? !! setting.value : null,
 		onChange: value => {
@@ -104,7 +110,7 @@ const SettingsSection = props => {
 							setSaveDisabled( true );
 						} }
 					>
-						{ __( 'Save Settings', 'newspack' ) }
+						{ __( 'Save Settings', 'newspack-plugin' ) }
 					</Button>
 				)
 			}

package/src/section-header/index.js

@@ -36,6 +36,7 @@ import classnames from 'classnames';
  * @property {boolean}            [isWhite=false]    - Indicates if the header should use a white theme.
  * @property {boolean}            [noMargin=false]   - Indicates if the header should have no margin.
  * @property {boolean}            [pageHeader=false] - Indicates if the header is used as a page header.
+ * @property {string}             [size='default']   - Size variant, either 'default' or 'small'. Scales the title, and the icon with it, independently of `pageHeader`.
  * @property {string}             title              - The title of the section.
  * @property {?string}            [id=null]          - Optional ID for the header element.
  * @property {?string|Function|*} [children=null]    - Optional children to display in the header.
@@ -57,6 +58,7 @@ const SectionHeader = ( {
 	isWhite = false,
 	noMargin = false,
 	pageHeader = false,
+	size = 'default',
 	title,
 	id = null,
 	menu,
@@ -82,7 +84,8 @@ const SectionHeader = ( {
 		centered && 'newspack-section-header--is-centered',
 		isWhite && 'newspack-section-header--is-white',
 		noMargin && 'newspack-section-header--no-margin',
-		pageHeader && 'newspack-section-header--page-header'
+		pageHeader && 'newspack-section-header--page-header',
+		size === 'small' && 'newspack-section-header--small'
 	);
 
 	// The breadcrumb `Page` owns the single page `<h1>`, so a `pageHeader` section
@@ -148,7 +151,7 @@ const SectionHeader = ( {
 			<Grid columns={ 1 } gutter={ 8 } className={ classes }>
 				{ icon && (
 					<div className="newspack-section-header__icon">
-						<Icon icon={ icon } size={ 48 } />
+						<Icon icon={ icon } size={ size === 'small' ? 24 : 48 } />
 					</div>
 				) }
 				{ backNav ? (

package/src/section-header/style.scss

@@ -95,6 +95,31 @@
 		@include wp-mixins.heading-x-large();
 	}
 
+	&#{&}--small {
+		.newspack-section-header__title {
+			@include wp-mixins.heading-large();
+		}
+	}
+
+	&__icon {
+		background-color: var(--wp-admin-theme-color-lighter-10);
+		border-radius: 100%;
+		display: grid;
+		height: 80px;
+		margin-bottom: 8px !important;
+		width: 80px;
+		place-items: center;
+		svg {
+			fill: var(--wp-admin-theme-color);
+		}
+	}
+
+	&#{&}--small .newspack-section-header__icon {
+		height: wp-vars.$grid-unit-50;
+		margin-bottom: wp-vars.$grid-unit-05 !important;
+		width: wp-vars.$grid-unit-50;
+	}
+
 	&__title-container {
 		align-items: center;
 		display: flex;
@@ -154,17 +179,5 @@
 		> p {
 			text-align: center;
 		}
-		.newspack-section-header__icon {
-			background-color: var(--wp-admin-theme-color-lighter-10);
-			border-radius: 100%;
-			display: grid;
-			height: 80px;
-			margin-bottom: 8px !important;
-			width: 80px;
-			place-items: center;
-			svg {
-				fill: var(--wp-admin-theme-color);
-			}
-		}
 	}
 }