Components: Move Newsletter's placement card to @automattic/jetpack-components as CheckboxCard

projects/js-packages/components/changelog/update-placement-card-shared-component

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Add a CheckboxCard component.

projects/js-packages/components/components/checkbox-card/index.tsx

@@ -0,0 +1,79 @@
+import { useCallback } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { Card, Checkbox, Field, Link, Stack, Text } from '@wordpress/ui';
+import clsx from 'clsx';
+import './style.scss';
+import type { CheckboxCardGridProps, CheckboxCardProps } from './types.ts';
+import type { JSX } from 'react';
+
+/**
+ * Lays out checkbox cards in two columns, or one on narrow screens.
+ *
+ * @param {CheckboxCardGridProps} props - Component props.
+ * @return {JSX.Element} The grid.
+ */
+export function CheckboxCardGrid( { children, className }: CheckboxCardGridProps ): JSX.Element {
+	return <div className={ clsx( 'jp-checkbox-card-grid', className ) }>{ children }</div>;
+}
+
+/**
+ * A card with a checkbox, toggled by a click on its illustration.
+ *
+ * @param {CheckboxCardProps} props - Component props.
+ * @return {JSX.Element} The card.
+ */
+export default function CheckboxCard( {
+	id,
+	name,
+	title,
+	illustration,
+	checked,
+	onChange,
+	previewUrl,
+	onPreviewClick,
+	disabled,
+}: CheckboxCardProps ): JSX.Element {
+	const titleId = `${ id }__title`;
+
+	const handleChange = useCallback(
+		( next: boolean ) => onChange( name, next ),
+		[ name, onChange ]
+	);
+
+	const handlePreviewClick = useCallback( () => {
+		onPreviewClick?.( name );
+	}, [ name, onPreviewClick ] );
+
+	return (
+		<Field.Root disabled={ disabled }>
+			<Card.Root className="jp-checkbox-card" data-checked={ checked }>
+				<Card.Content>
+					<Card.FullBleed className="jp-checkbox-card__surface">
+						{ /* Only the illustration toggles: the title and link sit outside the label. */ }
+						<Field.Label className="jp-checkbox-card__illustration">{ illustration }</Field.Label>
+						<Checkbox
+							id={ id }
+							className="jp-checkbox-card__checkbox"
+							checked={ checked }
+							onCheckedChange={ handleChange }
+							aria-labelledby={ titleId }
+						/>
+					</Card.FullBleed>
+				</Card.Content>
+			</Card.Root>
+			<Stack gap="xs" direction="column">
+				<Text id={ titleId } variant="body-sm">
+					{ title }
+				</Text>
+				{ previewUrl && (
+					<Link href={ previewUrl } onClick={ handlePreviewClick }>
+						{ __( 'Preview and edit', 'jetpack-components' ) }
+					</Link>
+				) }
+			</Stack>
+		</Field.Root>
+	);
+}
+
+export { CheckboxCard };
+export type { CheckboxCardProps, CheckboxCardGridProps };

projects/js-packages/components/components/checkbox-card/stories/index.stories.tsx

@@ -0,0 +1,90 @@
+import { useCallback, useState } from 'react';
+import CheckboxCard, { CheckboxCardGrid } from '../index.tsx';
+import type { Meta, StoryFn } from '@storybook/react';
+
+const meta: Meta< typeof CheckboxCard > = {
+	title: 'JS Packages/Components/Checkbox Card',
+	component: CheckboxCard,
+	argTypes: {
+		illustration: { table: { disable: true } },
+		onChange: { table: { disable: true } },
+		onPreviewClick: { table: { disable: true } },
+	},
+};
+
+export default meta;
+
+const Wireframe = ( { before }: { before?: boolean } ) => {
+	const top = before ? 56 : 24;
+	return (
+		<svg viewBox="0 0 294 192" aria-hidden="true">
+			<rect x="40" y={ top } width="214" height="12" rx="2" fill="#dcdcde" />
+			<rect x="40" y={ top + 24 } width="214" height="80" rx="2" fill="#f0f0f1" />
+			<rect x="40" y={ before ? 24 : 140 } width="120" height="20" rx="4" fill="#3858e9" />
+		</svg>
+	);
+};
+
+const Template: StoryFn< typeof CheckboxCard > = args => {
+	const [ checked, setChecked ] = useState( args.checked );
+	const handleChange = useCallback( ( _name: string, next: boolean ) => setChecked( next ), [] );
+
+	return (
+		<div style={ { maxWidth: 360 } }>
+			<CheckboxCard { ...args } checked={ checked } onChange={ handleChange } />
+		</div>
+	);
+};
+
+export const _default = Template.bind( {} );
+_default.args = {
+	id: 'placement-after-content',
+	name: 'after_content',
+	title: 'After the post content',
+	illustration: <Wireframe />,
+	checked: false,
+};
+
+export const WithPreviewLink = Template.bind( {} );
+WithPreviewLink.args = {
+	..._default.args,
+	checked: true,
+	previewUrl: '#',
+};
+
+export const Disabled = Template.bind( {} );
+Disabled.args = {
+	..._default.args,
+	disabled: true,
+};
+
+export const Grid: StoryFn< typeof CheckboxCard > = () => {
+	const [ selected, setSelected ] = useState< Record< string, boolean > >( {
+		before_content: true,
+	} );
+	const handleChange = useCallback(
+		( name: string, next: boolean ) => setSelected( prev => ( { ...prev, [ name ]: next } ) ),
+		[]
+	);
+
+	return (
+		<CheckboxCardGrid>
+			<CheckboxCard
+				id="placement-before-content"
+				name="before_content"
+				title="Before the post content"
+				illustration={ <Wireframe before /> }
+				checked={ Boolean( selected.before_content ) }
+				onChange={ handleChange }
+			/>
+			<CheckboxCard
+				id="placement-after-content"
+				name="after_content"
+				title="After the post content"
+				illustration={ <Wireframe /> }
+				checked={ Boolean( selected.after_content ) }
+				onChange={ handleChange }
+			/>
+		</CheckboxCardGrid>
+	);
+};

projects/js-packages/components/components/checkbox-card/style.scss

@@ -0,0 +1,54 @@
+@use "@automattic/jetpack-base-styles/gutenberg-base-styles" as gb;
+
+.jp-checkbox-card-grid {
+	display: grid;
+	grid-template-columns: repeat(2, minmax(0, 1fr));
+	column-gap: var(--wpds-dimension-gap-md);
+	row-gap: var(--wpds-dimension-gap-2xl);
+
+	@media (max-width: 720px) {
+		grid-template-columns: minmax(0, 1fr);
+	}
+}
+
+.jp-checkbox-card {
+
+	&[data-checked="true"] {
+		border-color: var(--wpds-color-stroke-interactive-brand-active);
+	}
+
+	&:hover:not([data-checked="true"]) {
+		border-color: var(--wpds-color-stroke-surface-neutral-strong);
+	}
+
+	&:has(:focus-visible) {
+
+		@include gb.outset-ring__focus();
+	}
+
+	@media (prefers-reduced-motion: no-preference) {
+		transition: border-color 0.15s ease-out;
+	}
+}
+
+.jp-checkbox-card__surface {
+	position: relative;
+}
+
+.jp-checkbox-card__illustration {
+	display: flex;
+	aspect-ratio: 294 / 192;
+	background: var(--wpds-color-background-surface-neutral-weak);
+	cursor: var(--wpds-cursor-control);
+
+	> svg {
+		inline-size: 100%;
+		block-size: 100%;
+	}
+}
+
+.jp-checkbox-card__checkbox {
+	position: absolute;
+	inset-block-start: var(--wpds-dimension-padding-md);
+	inset-inline-start: var(--wpds-dimension-padding-md);
+}

projects/js-packages/components/components/checkbox-card/test/component.tsx

@@ -0,0 +1,73 @@
+import { jest } from '@jest/globals';
+import { render, screen } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+import CheckboxCard from '../index.tsx';
+import type { CheckboxCardProps } from '../types.ts';
+
+const renderCard = ( props: Partial< CheckboxCardProps > = {} ) => {
+	const onChange = jest.fn();
+	const onPreviewClick = jest.fn();
+	render(
+		<CheckboxCard
+			id="placement-after-content"
+			name="after_content"
+			title="After the post content"
+			illustration={ <span>Wireframe</span> }
+			checked={ false }
+			onChange={ onChange }
+			onPreviewClick={ onPreviewClick }
+			{ ...props }
+		/>
+	);
+	return { onChange, onPreviewClick };
+};
+
+describe( 'CheckboxCard', () => {
+	// Catches the title id and `aria-labelledby` drifting apart, which leaves the checkbox unnamed.
+	it( 'names the checkbox with the title', () => {
+		renderCard( { checked: true } );
+
+		expect( screen.getByRole( 'checkbox', { name: 'After the post content' } ) ).toBeChecked();
+	} );
+
+	// Catches the label's `htmlFor` no longer matching the checkbox, or `onChange` losing the name.
+	it.each( [
+		[ 'ticks', false, true ],
+		[ 'unticks', true, false ],
+	] )( '%s the card when the illustration is clicked', async ( _, checked, next ) => {
+		const { onChange } = renderCard( { checked } );
+
+		await userEvent.click( screen.getByText( 'Wireframe' ) );
+
+		expect( onChange ).toHaveBeenCalledWith( 'after_content', next );
+	} );
+
+	// Catches the title moving inside the label, where a click meant for the link toggles the card.
+	it( 'does not toggle when the title is clicked', async () => {
+		const { onChange } = renderCard();
+
+		await userEvent.click( screen.getByText( 'After the post content' ) );
+
+		expect( onChange ).not.toHaveBeenCalled();
+	} );
+
+	// Catches the link rendering without a `previewUrl`, or going missing when one is passed.
+	it.each( [
+		[ 'shows', 'https://example.com/wp-admin/site-editor.php', 1 ],
+		[ 'hides', undefined, 0 ],
+	] )( '%s the preview link', ( _, previewUrl, count ) => {
+		renderCard( { previewUrl } );
+
+		// By text: without an `href` the anchor has no link role, so a role query would miss it.
+		expect( screen.queryAllByText( 'Preview and edit' ) ).toHaveLength( count );
+	} );
+
+	// Catches the preview handler losing the name the parent uses to tell cards apart.
+	it( 'passes its name to the preview handler', async () => {
+		const { onPreviewClick } = renderCard( { previewUrl: '#preview' } );
+
+		await userEvent.click( screen.getByRole( 'link', { name: 'Preview and edit' } ) );
+
+		expect( onPreviewClick ).toHaveBeenCalledWith( 'after_content' );
+	} );
+} );

projects/js-packages/components/components/checkbox-card/types.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+
+export type CheckboxCardProps = {
+	/**
+	 * Id of the checkbox; the title's id is built from it.
+	 */
+	id: string;
+	/**
+	 * Passed back to `onChange` and `onPreviewClick`, so one handler can serve every card.
+	 */
+	name: string;
+	/**
+	 * Caption under the card, and the checkbox's accessible name.
+	 */
+	title: string;
+	/**
+	 * Picture filling the card, drawn at a 294×192 aspect ratio.
+	 */
+	illustration?: ReactNode;
+	/**
+	 * Whether the card is checked.
+	 */
+	checked: boolean;
+	/**
+	 * Called with the card's `name` and the next checked value.
+	 */
+	onChange: ( name: string, next: boolean ) => void;
+	/**
+	 * Shows a "Preview and edit" link to this URL under the title.
+	 */
+	previewUrl?: string;
+	/**
+	 * Called with the card's `name` when the "Preview and edit" link is clicked.
+	 */
+	onPreviewClick?: ( name: string ) => void;
+	/**
+	 * Disables the checkbox.
+	 */
+	disabled?: boolean;
+};
+
+export type CheckboxCardGridProps = {
+	/**
+	 * The `CheckboxCard`s to lay out.
+	 */
+	children: ReactNode;
+	/**
+	 * Extra class for the grid.
+	 */
+	className?: string;
+};

projects/js-packages/components/index.ts

@@ -24,6 +24,8 @@ export { default as AutomatticForAgenciesLogo } from './components/automattic-fo
 export { default as JetpackFooter } from './components/jetpack-footer/index.tsx';
 export { default as Gravatar } from './components/gravatar/index.tsx';
 export type { GravatarProps } from './components/gravatar/index.tsx';
+export { default as CheckboxCard, CheckboxCardGrid } from './components/checkbox-card/index.tsx';
+export type { CheckboxCardProps, CheckboxCardGridProps } from './components/checkbox-card/types.ts';
 export { default as IconTooltip } from './components/icon-tooltip/index.tsx';
 export { default as ActionButton } from './components/action-button/index.tsx';
 export { default as PricingCard } from './components/pricing-card/index.tsx';

projects/js-packages/components/package.json

@@ -33,6 +33,11 @@
 			"types": "./build/components/button/index.d.ts",
 			"default": "./build/components/button/index.js"
 		},
+		"./checkbox-card": {
+			"jetpack:src": "./components/checkbox-card/index.tsx",
+			"types": "./build/components/checkbox-card/index.d.ts",
+			"default": "./build/components/checkbox-card/index.js"
+		},
 		"./global-notices": {
 			"jetpack:src": "./components/global-notices/index.ts",
 			"types": "./build/components/global-notices/index.d.ts",

projects/packages/newsletter/changelog/update-placement-card-shared-component

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Settings: Use the shared CheckboxCard component for subscription placements.