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

package/src/card-sortable-list/style.scss

@@ -0,0 +1,48 @@
+$collapse-duration: 200ms;
+$shift-duration: 150ms;
+$drop-duration: 400ms; /* must match DROP_ANIMATION_DURATION in index.tsx */
+
+.newspack-card--core--sortable-list {
+	&__item {
+		cursor: grab;
+
+		/*
+		 * Animate items sliding to fill/make space around the dragged item.
+		 */
+		transition: transform $shift-duration ease;
+
+		/*
+		 * Collapse the source item's content — the wrapper stays in layout as the
+		 * anchor point, and the container height is locked via inline style in JS.
+		 */
+		&.is-source {
+			cursor: grabbing;
+			opacity: 0;
+			transition: opacity $collapse-duration ease;
+		}
+
+		/*
+		 * Drop landing animation: brief fade-in and scale on the newly placed item.
+		 */
+		&.is-dropped {
+			animation: newspack-sortable-drop $drop-duration ease forwards;
+			opacity: 0;
+		}
+
+	}
+}
+
+@keyframes newspack-sortable-drop {
+	0% {
+		opacity: 0;
+		transform: scale(0.98);
+	}
+	60% {
+		opacity: 1;
+		transform: scale(1.01);
+	}
+	100% {
+		opacity: 1;
+		transform: scale(1);
+	}
+}

package/src/color-picker/index.js

@@ -1,7 +1,8 @@
 /**
  * WordPress dependencies.
  */
-import { ColorPicker as ColorPickerComponent } from '@wordpress/components';
+import { BaseControl, ColorPicker as ColorPickerComponent } from '@wordpress/components';
+import { useInstanceId } from '@wordpress/compose';
 import { useState, useRef } from '@wordpress/element';
 
 /**
@@ -26,35 +27,41 @@ const { InteractiveDiv } = utils;
  *
  * @param {Object}             props             - Component props.
  * @param {JSX.Element|string} props.label       - Label for the color picker.
+ * @param {JSX.Element|string} props.help        - Help text for the color picker.
  * @param {string}             [props.color]     - Default color.
  * @param {Function}           props.onChange    - Function to call when the color changes.
  * @param {string}             [props.className] - Additional class name.
  * @return {JSX.Element} ColorPicker component.
  */
-const ColorPicker = ( { label, color = '#fff', onChange, className } ) => {
+const ColorPicker = ( { label, help, color = '#ffffff', onChange, className } ) => {
 	const [ isExpanded, setIsExpanded ] = useState( false );
 	const ref = useRef();
+	const id = useInstanceId( ColorPicker, 'newspack-color-picker' );
+	const labelId = `${ id }-label`;
 	const colordColor = colord( color );
 	hooks.useOnClickOutside( ref, () => setIsExpanded( false ) );
 	return (
-		<div className={ classnames( 'newspack-color-picker', className ) }>
-			<div className="newspack-color-picker__label">{ label }</div>
-
+		<BaseControl id={ id } className={ classnames( 'newspack-color-picker', className ) } help={ help } __nextHasNoMarginBottom>
+			<BaseControl.VisualLabel id={ labelId }>{ label }</BaseControl.VisualLabel>
 			<InteractiveDiv
+				id={ id }
+				aria-labelledby={ labelId }
+				aria-describedby={ help ? `${ id }__help` : undefined }
+				aria-expanded={ isExpanded }
 				className={ 'newspack-color-picker__expander' }
 				onClick={ () => setIsExpanded( ! isExpanded ) }
 				style={ {
 					backgroundColor: color,
-					color: colordColor.contrast() > colordColor.contrast( '#000' ) ? '#fff' : '#000',
+					color: colordColor.contrast() > colordColor.contrast( '#000000' ) ? '#ffffff' : '#000000',
 				} }
 			>
 				{ color }
 			</InteractiveDiv>
 
 			<div className="newspack-color-picker__main" ref={ ref }>
-				{ isExpanded && <ColorPickerComponent color={ color } onChange={ hex => onChange( hex ) } enableAlpha={ false } /> }
+				{ isExpanded && <ColorPickerComponent color={ color } onChange={ onChange } enableAlpha={ false } /> }
 			</div>
-		</div>
+		</BaseControl>
 	);
 };
 

package/src/color-picker/index.test.js

@@ -0,0 +1,52 @@
+/**
+ * External dependencies
+ */
+import { render, fireEvent } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import ColorPicker from './';
+
+describe( 'ColorPicker', () => {
+	it( 'should render the label', () => {
+		const { getByText } = render( <ColorPicker label="Background color" onChange={ () => {} } /> );
+		expect( getByText( 'Background color' ) ).toBeInTheDocument();
+	} );
+
+	it( 'should render help text', () => {
+		const { getByText } = render( <ColorPicker label="Background color" help="Choose a color" onChange={ () => {} } /> );
+		expect( getByText( 'Choose a color' ) ).toBeInTheDocument();
+	} );
+
+	it( 'should start collapsed', () => {
+		const { getByRole } = render( <ColorPicker label="Background color" onChange={ () => {} } /> );
+		expect( getByRole( 'button' ) ).toHaveAttribute( 'aria-expanded', 'false' );
+	} );
+
+	it( 'should expand when the expander is clicked', () => {
+		const { getByRole } = render( <ColorPicker label="Background color" onChange={ () => {} } /> );
+		const expander = getByRole( 'button' );
+		fireEvent.click( expander );
+		expect( expander ).toHaveAttribute( 'aria-expanded', 'true' );
+	} );
+
+	it( 'should associate label via aria-labelledby', () => {
+		const { getByRole, getByText } = render( <ColorPicker label="Background color" onChange={ () => {} } /> );
+		const expander = getByRole( 'button' );
+		const label = getByText( 'Background color' );
+		expect( expander.getAttribute( 'aria-labelledby' ) ).toBe( label.id );
+	} );
+
+	it( 'should associate help text via aria-describedby when help is provided', () => {
+		const { getByRole, getByText } = render( <ColorPicker label="Background color" help="Choose a color" onChange={ () => {} } /> );
+		const expander = getByRole( 'button' );
+		const help = getByText( 'Choose a color' );
+		expect( expander.getAttribute( 'aria-describedby' ) ).toBe( help.id );
+	} );
+
+	it( 'should not set aria-describedby when no help is provided', () => {
+		const { getByRole } = render( <ColorPicker label="Background color" onChange={ () => {} } /> );
+		expect( getByRole( 'button' ) ).not.toHaveAttribute( 'aria-describedby' );
+	} );
+} );

package/src/color-picker/style.scss

@@ -2,31 +2,29 @@
  * Color Picker
  */
 
+@use "~@wordpress/base-styles/colors" as wp-colors;
+@use "~@wordpress/base-styles/variables" as wp-vars;
+
 .newspack-color-picker {
 	position: relative;
-
-	&__label {
-		margin-bottom: 8px;
-	}
-
 	&__expander {
-		box-shadow: inset 0 0 0 1px rgb(0 0 0 / 20%);
-		border-radius: 2px;
-		height: 64px;
-		padding: 12px;
+		box-shadow: inset 0 0 0 1px rgba(wp-colors.$black, 0.54);
+		border-radius: wp-vars.$radius-small;
+		height: wp-vars.$grid-unit-80;
+		padding: wp-vars.$grid-unit-10;
 		text-align: right;
 		text-transform: uppercase;
 
 		&:focus-visible {
 			box-shadow: 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color);
-			border-color: white;
+			border-color: wp-colors.$white;
 		}
 	}
 
 	&__main {
-		background: white;
-		box-shadow: 0 0 8px 4px rgba(black, 0.08);
-		margin: 12px 0;
+		background: wp-colors.$white;
+		box-shadow: wp-vars.$elevation-small;
+		margin: wp-vars.$grid-unit-10 0 0;
 		position: absolute;
 		z-index: 2;
 

package/src/confirm-dialog/README.md

@@ -0,0 +1,128 @@
+# ConfirmDialog
+
+A modal confirmation dialog that intercepts client-side navigation when there are unsaved changes. Built on top of WordPress's `__experimentalConfirmDialog`. The dialog is invisible until a navigation attempt is blocked; when `when` becomes `true` and the user navigates away, the dialog appears automatically and resumes or cancels the navigation based on the user's choice.
+
+For most imperative use cases (confirming a destructive action, guarding an action behind an unsaved-changes check) prefer the [`useConfirmDialog` hook](#useconfirmdialog-hook) over using `ConfirmDialog` directly.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cancelButtonText` | `string` | — | Label for the cancel button. |
+| `children` | `React.ReactNode` | — | Content rendered in the modal body. |
+| `className` | `string` | — | Additional CSS class. |
+| `confirmButtonText` | `string` | — | Label for the confirm button. |
+| `hideTitle` | `boolean` | — | When `true`, hides the modal title and the × close button. |
+| `isDestructive` | `boolean` | — | When `true`, applies destructive (e.g. red) styling to the confirm button. |
+| `isOpen` | `boolean` | `false` | When `true`, shows the dialog immediately without blocking navigation. Use this for imperative confirmation (e.g. confirming a destructive action on a button click). |
+| `size` | `'small'` \| `'medium'` \| `'large'` \| `'x-large'` \| `'full'` | `'small'` | Controls the width of the modal. |
+| `title` | `string` | — | Title displayed in the modal header. |
+| `when` | `boolean` | `false` | When `true`, blocks router navigation and shows the dialog on any attempted navigation. Set this to reflect whether the current form has unsaved changes. |
+
+## Usage
+
+```jsx
+import { ConfirmDialog } from 'newspack-components';
+
+// Guard navigation when a form has unsaved changes.
+// The dialog appears automatically when the user tries to navigate away.
+<ConfirmDialog
+	when={ hasUnsavedChanges }
+	title="Unsaved changes"
+	confirmButtonText="Leave anyway"
+	cancelButtonText="Stay"
+	isDestructive
+>
+	You have unsaved changes. Are you sure you want to leave?
+</ConfirmDialog>
+
+// Larger modal with a custom size
+<ConfirmDialog
+	when={ hasUnsavedChanges }
+	size="medium"
+	title="Discard changes?"
+	confirmButtonText="Discard"
+	cancelButtonText="Keep editing"
+>
+	Your changes will be lost if you leave this page.
+</ConfirmDialog>
+
+// Guard both navigation and an imperative action with a single dialog instance.
+// isOpen triggers the dialog immediately (e.g. on a button click) without
+// blocking navigation. Both when and isOpen can be used together.
+const [ pendingAction, setPendingAction ] = useState( null );
+<ConfirmDialog
+	when={ hasUnsavedChanges }
+	isOpen={ !! pendingAction }
+	confirmButtonText="Discard changes"
+	isDestructive
+	hideTitle
+	onConfirm={ () => {
+		pendingAction?.();
+		setPendingAction( null );
+	} }
+	onCancel={ () => setPendingAction( null ) }
+>
+	You have unsaved changes that will be lost. Discard changes?
+</ConfirmDialog>
+```
+
+---
+
+## `useConfirmDialog` hook
+
+A higher-level hook that wraps `ConfirmDialog` and manages the pending-action state for you. Prefer this over using `ConfirmDialog` directly when you need imperative confirmation.
+
+```jsx
+import { useConfirmDialog } from 'newspack-components';
+```
+
+### Options
+
+Accepts all `ConfirmDialog` props except `isOpen`, `onConfirm`, `onCancel`, and `children`, plus:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `message` | `React.ReactNode` | — | Content rendered in the modal body. |
+| `when` | `boolean` | — | When explicitly `false`, `requestConfirm` skips the dialog and invokes the callback immediately. Omit (or pass `true`) to always show the dialog. Also controls router navigation blocking, same as the `when` prop on `ConfirmDialog`. |
+
+### Returns
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `confirmDialog` | `React.ReactElement` | The dialog element — render this somewhere in your JSX. |
+| `requestConfirm` | `( callback: () => void ) => void` | Call with a callback to request confirmation. Shows the dialog (unless `when` is `false`); invokes the callback only if the user confirms. |
+
+### Usage
+
+```jsx
+// Always-confirm dialog (e.g. destructive delete action).
+const { confirmDialog, requestConfirm } = useConfirmDialog( {
+	title: 'Are you sure?',
+	confirmButtonText: 'Delete',
+	isDestructive: true,
+	message: 'This will permanently delete the item and cannot be undone.',
+} );
+
+// Render the dialog element in JSX:
+{ confirmDialog }
+
+// Call requestConfirm when the user initiates the action:
+<Button onClick={ () => requestConfirm( handleDelete ) }>Delete</Button>
+
+// Conditional dialog — skips confirmation when there are no unsaved changes.
+// Combines navigation blocking with imperative use in a single instance.
+const { confirmDialog, requestConfirm } = useConfirmDialog( {
+	when: isDirty,
+	message: 'You have unsaved changes that will be lost. Discard changes?',
+	confirmButtonText: 'Discard changes',
+	isDestructive: true,
+	hideTitle: true,
+} );
+
+{ confirmDialog }
+
+// In an action handler — shows the dialog only if isDirty, otherwise
+// calls the callback immediately:
+requestConfirm( () => handleToggleEnabled( newConfig ) );
+```

package/src/confirm-dialog/index.tsx

@@ -0,0 +1,132 @@
+/**
+ * Modal
+ */
+
+/**
+ * WordPress dependencies.
+ */
+import { __experimentalConfirmDialog as BaseComponent } from '@wordpress/components'; // eslint-disable-line @wordpress/no-unsafe-wp-apis
+import { forwardRef, useCallback, useEffect, useRef, useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies.
+ */
+import Router from '../proxied-imports/router';
+const { useHistory } = Router;
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/*
+ * See both https://wordpress.github.io/gutenberg/?path=/docs/components-confirmdialog--docs and
+ * https://wordpress.github.io/gutenberg/?path=/docs/components-modal--docs for all supported props.
+ */
+type ConfirmDialogProps = {
+	className?: string;
+	size?: 'small' | 'medium' | 'large' | 'x-large' | 'full';
+	hideTitle?: boolean;
+	title?: string;
+	isDestructive?: boolean;
+	isOpen?: boolean;
+	onConfirm?: () => void;
+	onCancel?: () => void;
+	cancelButtonText?: string;
+	confirmButtonText?: string;
+	children?: React.ReactNode;
+	when?: boolean;
+};
+
+const sizeClassMap = {
+	small: 'newspack-modal--size-small',
+	medium: 'newspack-modal--size-medium',
+	large: 'newspack-modal--size-large',
+	'x-large': 'newspack-modal--size-x-large',
+	full: 'newspack-modal--size-full',
+};
+
+const noOp = () => {};
+
+function ConfirmDialog(
+	{
+		className,
+		size = 'small',
+		hideTitle,
+		isDestructive,
+		onConfirm = noOp,
+		onCancel = noOp,
+		when = false,
+		isOpen = false,
+		...otherProps
+	}: ConfirmDialogProps,
+	ref: React.Ref< HTMLDivElement >
+) {
+	const [ showDialog, setShowDialog ] = useState( isOpen );
+	const history = useHistory();
+	const pendingNavigation = useRef< ( () => void ) | null >( null );
+
+	const handleOnConfirm = useCallback( () => {
+		setShowDialog( false );
+		pendingNavigation.current?.();
+		pendingNavigation.current = null;
+		onConfirm();
+	}, [ onConfirm, pendingNavigation ] );
+
+	const handleOnCancel = useCallback( () => {
+		setShowDialog( false );
+		pendingNavigation.current = null;
+		onCancel();
+	}, [ onCancel, pendingNavigation ] );
+
+	// Block navigation when there are unsaved changes.
+	useEffect( () => {
+		if ( ! when ) {
+			return;
+		}
+		const unblock = history.block( ( location: string, action: string ) => {
+			pendingNavigation.current = () => {
+				unblock();
+				if ( action === 'REPLACE' ) {
+					history.replace( location );
+				} else {
+					history.push( location );
+				}
+			};
+			setShowDialog( true );
+			return false;
+		} );
+		return unblock;
+	}, [ when, history ] );
+
+	// Show the dialog imperatively without blocking navigation.
+	useEffect( () => {
+		if ( isOpen ) {
+			setShowDialog( true );
+		}
+	}, [ isOpen ] );
+
+	if ( ! showDialog ) {
+		return null;
+	}
+
+	const classes = classnames(
+		'newspack-modal',
+		sizeClassMap[ size ],
+		hideTitle && 'newspack-modal--hide-title', // Note: also hides the X close button.
+		isDestructive && 'newspack-modal--destructive',
+		className
+	);
+
+	return (
+		<BaseComponent
+			className={ classes }
+			{ ...otherProps }
+			ref={ ref }
+			onConfirm={ handleOnConfirm }
+			onCancel={ handleOnCancel }
+			__experimentalHideHeader={ false }
+		/>
+	);
+}
+export default forwardRef( ConfirmDialog );

package/src/dataviews/index.tsx

@@ -0,0 +1,34 @@
+/**
+ * DataViews
+ *
+ * Wrapper around @wordpress/dataviews with Newspack styling.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { DataViews as BaseDataViews } from '@wordpress/dataviews';
+
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies
+ */
+import './style.scss';
+
+type DataViewsProps = React.ComponentProps< typeof BaseDataViews > & {
+	className?: string;
+};
+
+export default function DataViews( { className, ...props }: DataViewsProps ) {
+	return (
+		<div className={ classnames( 'newspack-dataviews', className ) }>
+			<BaseDataViews { ...props } />
+		</div>
+	);
+}
+
+export type { Action, Field, View } from '@wordpress/dataviews';

package/src/dataviews/style.scss

@@ -0,0 +1,9 @@
+/* stylelint-disable no-invalid-position-at-import-rule */
+@import "@wordpress/dataviews/build-style/style.css";
+
+.newspack-dataviews {
+	/* Make sure full-width DataViews aligns with the 48px margin. */
+	.newspack-wizard__content--full-width & {
+		margin-top: -16px;
+	}
+}

package/src/divider/README.md

@@ -0,0 +1,25 @@
+# Divider
+
+Horizontal rule component with alignment, variant, and margin options.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `alignment` | `'full-width'` \| `'none'` | `'none'` | `full-width` breaks out of the container to span the viewport; `none` stays within the container. |
+| `className` | `string` | — | Additional CSS class. |
+| `marginBottom` | `number` \| `string` | `64` | Bottom margin (e.g. `64` or `"2rem"`). Capped at 32px on viewports < 783px. |
+| `marginTop` | `number` \| `string` | `64` | Top margin (e.g. `64` or `"2rem"`). Capped at 32px on viewports < 783px. |
+| `variant` | `'default'` \| `'primary'` \| `'secondary'` \| `'tertiary'` | `'default'` | Line color: `default` uses `$gray-300`; `primary` uses the admin theme color (`--wp-admin-theme-color`); `secondary` uses `$gray-900`; `tertiary` uses `$gray-100`. |
+
+## Usage
+
+```jsx
+import { Divider } from 'newspack-components';
+
+<Divider />
+
+<Divider alignment="full-width" variant="primary" />
+
+<Divider marginBottom={ 48 } marginTop={ 32 } variant="secondary" />
+```

package/src/divider/index.js

@@ -0,0 +1,31 @@
+/**
+ * Divider
+ */
+
+/**
+ * Internal dependencies
+ */
+import './style.scss';
+
+/**
+ * External dependencies
+ */
+import classNames from 'classnames';
+
+const Divider = ( { alignment = 'none', className = undefined, marginBottom = 64, marginTop = 64, variant = 'default', ...otherProps } ) => {
+	const classes = classNames(
+		'newspack-divider',
+		className,
+		alignment && `newspack-divider--alignment-${ alignment }`,
+		variant && `newspack-divider--variant-${ variant }`
+	);
+
+	const style = {
+		'--divider-margin-bottom': typeof marginBottom === 'number' ? `${ marginBottom }px` : marginBottom,
+		'--divider-margin-top': typeof marginTop === 'number' ? `${ marginTop }px` : marginTop,
+	};
+
+	return <hr className={ classes } style={ style } { ...otherProps } />;
+};
+
+export default Divider;

package/src/divider/style.scss

@@ -0,0 +1,51 @@
+/**
+ * Divider
+ */
+
+@use "~@wordpress/base-styles/colors" as wp-colors;
+
+.newspack-divider {
+	background: transparent;
+	border: 0;
+	display: block;
+	height: 1px;
+	margin-bottom: min(32px, var(--divider-margin-bottom, 64px));
+	margin-left: 0;
+	margin-right: 0;
+	margin-top: min(32px, var(--divider-margin-top, 64px));
+	padding: 0;
+
+	@media screen and (min-width: 783px) {
+		margin-bottom: var(--divider-margin-bottom, 64px);
+		margin-top: var(--divider-margin-top, 64px);
+	}
+
+	// Alignment
+
+	&--alignment-full-width {
+		margin-left: calc(-50vw + 50%);
+		width: 100vw;
+	}
+
+	&--alignment-none {
+		width: 100%;
+	}
+
+	// Variant
+
+	&--variant-default {
+		background-color: wp-colors.$gray-300;
+	}
+
+	&--variant-primary {
+		background-color: var(--wp-admin-theme-color);
+	}
+
+	&--variant-secondary {
+		background-color: wp-colors.$gray-900;
+	}
+
+	&--variant-tertiary {
+		background-color: wp-colors.$gray-100;
+	}
+}

package/src/form-token-field/style.scss

@@ -7,11 +7,6 @@
 .newspack-form-token-field {
 	width: 100%;
 
-	.components-form-token-field__input-container {
-		padding-bottom: 1px;
-		padding-top: 1px;
-	}
-
 	// Help
 
 	&__help {

package/src/grid/index.tsx

@@ -12,9 +12,10 @@ import './style.scss';
  */
 import classnames from 'classnames';
 
-const Grid = ( { className = '', columns = 2, gutter = 32, noMargin = false, rowGap = 0, ...otherProps } ) => {
+const Grid = ( { className = '', borders = false, columns = 2, gutter = 32, noMargin = false, rowGap = 0, ...otherProps } ) => {
 	const classes = classnames(
 		'newspack-grid',
+		borders && 'newspack-grid__borders',
 		noMargin && 'newspack-grid--no-margin',
 		columns && 'newspack-grid__columns-' + columns,
 		gutter && 'newspack-grid__gutter-' + gutter,