newspack-components 4.8.0 → 4.9.0-alpha.1

package/src/action-card/index.js

@@ -5,8 +5,9 @@
 /**
  * WordPress dependencies
  */
-import { Draggable, ExternalLink, ToggleControl } from '@wordpress/components';
-import { useEffect, useState } from '@wordpress/element';
+import { Draggable, ExternalLink, Notice, ToggleControl } from '@wordpress/components';
+import { RawHTML, useEffect, useState } from '@wordpress/element';
+import { decodeEntities } from '@wordpress/html-entities';
 import { __ } from '@wordpress/i18n';
 import { Icon, check, chevronDown, chevronUp, dragHandle } from '@wordpress/icons';
 import { Badge } from '@wordpress/ui';
@@ -14,7 +15,7 @@ import { Badge } from '@wordpress/ui';
 /**
  * Internal dependencies
  */
-import { Button, Card, Grid, Handoff, Notice, Waiting } from '../';
+import { Button, Card, Grid, Handoff, Waiting } from '../';
 import { ActionCardProps } from './action-card.d.ts';
 import './style.scss';
 
@@ -23,8 +24,76 @@ import './style.scss';
  */
 import classnames from 'classnames';
 
+const NOTIFICATION_LEVELS = [ 'error', 'info', 'success', 'warning' ];
+
+/**
+ * Collect a notification's text, including text nested inside React elements.
+ *
+ * Segments join with a space so that adjacent elements do not weld together: by the
+ * time speak() sees this string the markup that separated them is already gone.
+ *
+ * @param {*} value Notification content.
+ * @return {string} The collected text.
+ */
+const getNotificationText = value => {
+	if ( typeof value === 'string' ) {
+		return value;
+	}
+	if ( typeof value === 'number' ) {
+		return String( value );
+	}
+	if ( value instanceof Error ) {
+		return value.message;
+	}
+	if ( Array.isArray( value ) ) {
+		return value.map( getNotificationText ).join( ' ' );
+	}
+	return value?.props?.children === undefined ? '' : getNotificationText( value.props.children );
+};
+
+/**
+ * Derive a plain-text announcement from a notification.
+ *
+ * Notice defaults spokenMessage to its children and runs renderToString over them
+ * during render, which corrupts the hook dispatcher when those children are
+ * components. A notification can be any element, so the announcement is always
+ * built from its text instead of letting that default apply. Tags in an HTML
+ * notification stay in, since speak() strips them itself. Entities are decoded so
+ * the announcement matches the text on screen, which getNotificationContent decodes
+ * for the same reason.
+ *
+ * @param {*} notification Notification content.
+ * @return {string} Message to announce.
+ */
+const getSpokenNotification = notification => decodeEntities( getNotificationText( notification ) ).replace( /\s+/g, ' ' ).trim();
+
+/**
+ * Decode a notification's own text for display.
+ *
+ * React does not decode entities in text children, and notification text is often
+ * server-sourced, so a message carrying `’` would otherwise show the entity
+ * and announce the character. The HTML branch is left alone: there the browser's
+ * parser decodes as it renders.
+ *
+ * @param {*} value Notification content.
+ * @return {*} The content, with its own strings decoded.
+ */
+const getNotificationContent = value => {
+	if ( value instanceof Error ) {
+		return decodeEntities( value.message );
+	}
+	if ( typeof value === 'string' ) {
+		return decodeEntities( value );
+	}
+	if ( Array.isArray( value ) ) {
+		return value.map( getNotificationContent );
+	}
+	return value;
+};
+
 /**
  * ActionCard component
+ *
  * @param {ActionCardProps} props Component props.
  * @return {JSX.Element} ActionCard component.
  */
@@ -107,6 +176,7 @@ const ActionCard = ( {
 	}, [ collapse ] );
 
 	const hasChildren = notification || children;
+	const notificationContent = getNotificationContent( notification );
 	const classes = classnames(
 		'newspack-action-card',
 		simple && 'newspack-card--is-clickable',
@@ -243,12 +313,15 @@ const ActionCard = ( {
 					</Button>
 				) }
 			</div>
-			{ notification && (
+			{ notification && NOTIFICATION_LEVELS.includes( notificationLevel ) && (
 				<div className="newspack-action-card__notification newspack-action-card__region-children">
-					{ 'error' === notificationLevel && <Notice noticeText={ notification } isError rawHTML={ notificationHTML } /> }
-					{ 'info' === notificationLevel && <Notice noticeText={ notification } rawHTML={ notificationHTML } /> }
-					{ 'success' === notificationLevel && <Notice noticeText={ notification } isSuccess rawHTML={ notificationHTML } /> }
-					{ 'warning' === notificationLevel && <Notice noticeText={ notification } isWarning rawHTML={ notificationHTML } /> }
+					<Notice status={ notificationLevel } isDismissible={ false } spokenMessage={ getSpokenNotification( notification ) }>
+						{ notificationHTML && typeof notification === 'string' ? (
+							<RawHTML className="newspack-action-card__notification-html">{ notification }</RawHTML>
+						) : (
+							notificationContent
+						) }
+					</Notice>
 				</div>
 			) }
 			{ children && ( ( expandable && expanded ) || ! expandable ) ? (

package/src/action-card/index.test.js

@@ -3,11 +3,22 @@
  */
 import { render, screen } from '@testing-library/react';
 
+/**
+ * WordPress dependencies.
+ */
+import { speak } from '@wordpress/a11y';
+import { useState } from '@wordpress/element';
+
 /**
  * Internal dependencies.
  */
 import ActionCard from './index';
 
+jest.mock( '@wordpress/a11y', () => ( {
+	...jest.requireActual( '@wordpress/a11y' ),
+	speak: jest.fn(),
+} ) );
+
 /**
  * The library Badge styles its wrapper rather than its text, so a badge with no label
  * paints a bare coloured pill. Callers build the `badges` array from data that can be
@@ -54,3 +65,151 @@ describe( 'ActionCard badges', () => {
 		expect( withEmptyArray.textContent ).not.toContain( '0' );
 	} );
 } );
+
+/**
+ * ActionCard derives the notice's spoken message rather than letting core default it to
+ * the children. Core runs `renderToString` over that default during render, which corrupts
+ * the hook dispatcher when the children are components — so the derivation is what keeps a
+ * notification carrying a `<Button>` from crashing the card on a later re-render.
+ */
+describe( 'ActionCard notifications', () => {
+	beforeEach( () => {
+		speak.mockClear();
+	} );
+
+	const spoken = () => speak.mock.calls.map( call => call[ 0 ] );
+
+	it( 'renders a notice for a recognised level', () => {
+		const { container } = render( <ActionCard title="Ad Manager" notification="Plugin cannot be installed" notificationLevel="error" /> );
+
+		expect( container.querySelector( '.components-notice.is-error' ) ).toBeInTheDocument();
+	} );
+
+	it( 'renders no notice for an unrecognised or absent level', () => {
+		const { container: unknown } = render( <ActionCard title="Ad Manager" notification="Something happened" notificationLevel="critical" /> );
+		expect( unknown.querySelector( '.components-notice' ) ).not.toBeInTheDocument();
+
+		const { container: absent } = render( <ActionCard title="Ad Manager" notification="Something happened" /> );
+		expect( absent.querySelector( '.components-notice' ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'announces the text inside an element-only notification', () => {
+		render(
+			<ActionCard
+				title="Ad Manager"
+				notificationLevel="error"
+				notification={ [ <button key="connect">Click here to connect your account.</button> ] }
+			/>
+		);
+
+		expect( spoken() ).toContain( 'Click here to connect your account.' );
+	} );
+
+	it( 'announces strings and element text together', () => {
+		render(
+			<ActionCard
+				title="Ad Manager"
+				notificationLevel="success"
+				notification={ [
+					'Created custom targeting keys: ',
+					// eslint-disable-next-line react/jsx-indent
+					<a key="dashboard" href="https://example.org">
+						Visit your GAM dashboard
+					</a>,
+				] }
+			/>
+		);
+
+		expect( spoken() ).toContain( 'Created custom targeting keys: Visit your GAM dashboard' );
+	} );
+
+	it( 'announces an Error and renders its message rather than throwing', () => {
+		render( <ActionCard title="Ad Manager" notificationLevel="error" notification={ new Error( 'Network unreachable' ) } /> );
+
+		expect( screen.getByText( 'Network unreachable' ) ).toBeInTheDocument();
+		expect( spoken() ).toContain( 'Network unreachable' );
+	} );
+
+	it( 'renders HTML notifications in their own wrapper and hands speak() the tags to strip', () => {
+		const { container } = render(
+			<ActionCard title="Ad Manager" notificationLevel="error" notification={ '<p>Install failed.</p><p>Try again.</p>' } notificationHTML />
+		);
+
+		expect( container.querySelectorAll( '.newspack-action-card__notification-html > p' ) ).toHaveLength( 2 );
+		expect( spoken()[ 0 ] ).toContain( '<p>Install failed.</p>' );
+	} );
+
+	it( 'decodes entities in both the announcement and the visible text', () => {
+		render( <ActionCard title="Ad Manager" notificationLevel="error" notification={ 'Plugin &#8220;Foo&#8221; could not be activated' } /> );
+
+		expect( screen.getByText( 'Plugin “Foo” could not be activated' ) ).toBeInTheDocument();
+		expect( spoken()[ 0 ] ).toContain( '“Foo”' );
+	} );
+
+	it( 'decodes entities inside an array of notification parts', () => {
+		render(
+			<ActionCard title="Ad Manager" notificationLevel="error" notification={ [ 'Could not reach the publisher&#8217;s network.', ' ' ] } />
+		);
+
+		expect( screen.getByText( /Could not reach the publisher’s network\./ ) ).toBeInTheDocument();
+		expect( spoken()[ 0 ] ).toContain( 'publisher’s' );
+	} );
+
+	it( 'leaves entity decoding to the browser on the HTML branch', () => {
+		const { container } = render(
+			<ActionCard
+				title="Ad Manager"
+				notificationLevel="error"
+				notification={ 'Get it from <a href="https://example.org">the plugin&#8217;s site</a>' }
+				notificationHTML
+			/>
+		);
+
+		expect( container.querySelector( '.newspack-action-card__notification-html a' ).textContent ).toBe( 'the plugin’s site' );
+		expect( spoken()[ 0 ] ).toContain( 'plugin’s site' );
+	} );
+
+	it( 'renders a non-string notification as children even when notificationHTML is set', () => {
+		const { container } = render(
+			<ActionCard title="Ad Manager" notificationLevel="error" notification={ <span>Network unreachable</span> } notificationHTML />
+		);
+
+		expect( screen.getByText( 'Network unreachable' ) ).toBeInTheDocument();
+		expect( container.querySelector( '.newspack-action-card__notification-html' ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'keeps adjacent element texts apart in the announcement', () => {
+		render(
+			<ActionCard
+				title="Ad Manager"
+				notificationLevel="error"
+				notification={ [
+					// eslint-disable-next-line react/jsx-indent
+					<a key="dashboard" href="https://example.org">
+						Visit your GAM dashboard
+					</a>,
+					<button key="connect" type="button">
+						Click here to connect your account.
+					</button>,
+				] }
+			/>
+		);
+
+		expect( spoken()[ 0 ] ).toBe( 'Visit your GAM dashboard Click here to connect your account.' );
+	} );
+
+	it( 'survives a re-render that changes how many hooked components the notification holds', () => {
+		const HookedAction = ( { children } ) => {
+			const [ label ] = useState( children );
+			return <button type="button">{ label }</button>;
+		};
+		const card = notification => <ActionCard title="Ad Manager" notificationLevel="error" notification={ notification } />;
+
+		const { rerender, container } = render(
+			card( [ <HookedAction key="retry">Retry</HookedAction>, <HookedAction key="docs">Documentation</HookedAction> ] )
+		);
+
+		expect( () => rerender( card( [ <HookedAction key="retry">Retry</HookedAction> ] ) ) ).not.toThrow();
+		expect( container.querySelector( '.components-notice.is-error' ) ).toBeInTheDocument();
+	} );
+} );

package/src/action-card/style.scss

@@ -339,18 +339,12 @@
 
 	/* Notifications */
 	.newspack-action-card__notification {
-		.newspack-notice {
+		.components-notice {
 			margin: 0;
-
-			&__heading {
-				margin-top: 0;
-			}
 		}
 
-		&.newspack-action-card__region-children {
-			.newspack-notice {
-				margin-top: 32px;
-			}
+		.newspack-action-card__notification-html > * {
+			margin: 0;
 		}
 	}
 

package/src/card-feature/README.md

@@ -11,13 +11,15 @@ A card component for presenting a named feature or setting with a predictable, s
 
 Cards sit side by side, so a bare "Enable" names no feature out of context. The card appends `title` to the primary button's accessible name ("Enable Metered Countdown") and to the "More" menu ("More options for Metered Countdown"). The visible label leads, so voice control still matches on the word the user can see. Nothing to pass — this is automatic.
 
+When enabling leaves nothing to configure, the primary button goes away while it still has focus; the card moves that focus to the "More" menu rather than letting it fall to the page.
+
 ## States
 
 | State | Condition | Button | Dropdown | Badge |
 |---|---|---|---|---|
 | **Unmet requirements** | `requirements` is set | "Enable" — blocked but still focusable, and described by the badge (clickable if `requirementsActionable`) | Shown if `enabled` and `requirementsActionable` (and `moreControls` provided); otherwise hidden | High-intent badge with `requirements` text |
 | **Disabled** | `!enabled`, no requirements | "Enable" | Hidden | None |
-| **Enabled** | `enabled`, no requirements | "Configure" | Shown if `moreControls` provided | Stable-intent badge ("Enabled") |
+| **Enabled** | `enabled`, no requirements | "Configure", or none without `onConfigure` | Shown if `moreControls` provided | Stable-intent badge ("Enabled") |
 
 When `requirements` is set the title drops to the muted text colour. The description already uses that colour in every state, so the unmet-requirements state is signalled by the title colour plus the high-intent badge.
 
@@ -75,9 +77,9 @@ import { __ } from '@wordpress/i18n';
 
 ## With a custom icon
 
-`icon` takes either a descriptor object or a ready React element. A descriptor gets the standard treatment: pass `node` for the icon element, `fill` for the SVG colour, `backgroundColor` for a container background, and `radius` for the corner treatment. A ready element renders exactly as given, with no container, background or radius, which is the escape hatch for an icon that already carries its own chrome.
+`icon` takes either a descriptor object or a ready React element. A descriptor gets the standard treatment: pass `node` for the icon element, `fill` for the SVG colour, and `backgroundColor` for a container background. A ready element renders exactly as given, with no container or background, which is the escape hatch for an icon that already carries its own chrome.
 
-A descriptor's container is always **40 × 40 px** with the SVG at **24 × 24 px**. Setting `backgroundColor` without a `radius` gives 2px corners; pass `radius: 'full'` for a circle.
+A descriptor's container is always **40 × 40 px** with the SVG at **24 × 24 px**. Setting `backgroundColor` makes the container a circle.
 
 `fill` sets the container's `color`, which the SVG picks up through `fill: currentcolor`. That only recolours single-colour icons that inherit their fill, such as those from `@wordpress/icons`. A vendor's own mark carries `fill` on its paths and keeps its colours, so pair it with `backgroundColor` rather than trying to tint it.
 
@@ -101,9 +103,9 @@ import colors from 'newspack-colors';
 
 // A vendor mark on its own brand background, keeping the mark's colours
 <CardFeature
-	title={ __( 'Mailchimp', 'newspack-plugin' ) }
+	title="Mailchimp"
 	description={ __( 'Sync reader activity with your Mailchimp audience.', 'newspack-plugin' ) }
-	icon={ { node: <MailchimpMark />, backgroundColor: '#ffe01b', radius: 'full' } }
+	icon={ { node: <MailchimpMark />, backgroundColor: '#ffe01b' } }
 	enabled={ isEnabled }
 	onEnable={ handleEnable }
 	onConfigure={ handleConfigure }
@@ -112,7 +114,7 @@ import colors from 'newspack-colors';
 
 // A ready element, rendered as-is
 <CardFeature
-	title={ __( 'Mailchimp', 'newspack-plugin' ) }
+	title="Mailchimp"
 	description={ __( 'Sync reader activity with your Mailchimp audience.', 'newspack-plugin' ) }
 	icon={ <IntegrationIcon provider="mailchimp" /> }
 	enabled={ isEnabled }
@@ -203,7 +205,7 @@ The card is built on `Card.Root`, `Card.Header` and `Card.Content` from `@wordpr
 | `enableLabel` | `string` | `"Enable"` | Label for the primary button in its "Enable" states: not enabled, or enabled with an unmet requirement |
 | `configureLabel` | `string` | `"Configure"` | Label for the primary button in its "Configure" state: enabled, with no unmet requirement |
 | `onEnable` | `() => void` | — | Called when the primary button is clicked while it reads "Enable". That covers the not-enabled case and the enabled-with-unmet-requirements case, where the feature is on but the requirement is what the button acts on |
-| `onConfigure` | `() => void` | — | Called when the primary button is clicked while it reads "Configure", which is the enabled state with no unmet requirements |
+| `onConfigure` | `() => void` | — | Called when the primary button is clicked while it reads "Configure", which is the enabled state with no unmet requirements. Omit it for a feature with nothing to configure, and that state shows no primary button |
 | `moreControls` | `MoreControl[]` | — | Items for the "More" dropdown. Shown when `enabled` and either there are no `requirements` or `requirementsActionable` is set |
 | `badge` | `{ label?: string; intent?: BadgeIntent }` | `{ label: "Enabled", intent: "stable" }` | Badge shown when enabled. Ignored while `requirements` is set, which takes the badge |
 | `busy` | `boolean` | `false` | Shows the primary button as busy and blocks it while an action is in flight |
@@ -215,10 +217,7 @@ The card is built on `Card.Root`, `Card.Header` and `Card.Content` from `@wordpr
 type CardFeatureIcon = {
 	node: React.ReactNode;       // The icon element to render
 	fill?: string;               // SVG fill colour (applied via currentColor)
-	backgroundColor?: string;    // Background colour of the 40×40 container
-	radius?: 'small' | 'full';   // 'small' = 2px ($radius-small), 'full' = 50% ($radius-round)
-	                             // Defaults to 'small' whenever backgroundColor is set,
-	                             // and has nothing to round without one.
+	backgroundColor?: string;    // Background colour of the 40×40 container, always a circle
 };
 ```
 

package/src/card-feature/index.test.js

@@ -61,7 +61,7 @@ describe( 'CardFeature', () => {
 		} );
 
 		it( 'names the feature in the configure state too', () => {
-			render( <CardFeature title="Content Gifting" enabled /> );
+			render( <CardFeature title="Content Gifting" enabled onConfigure={ () => {} } /> );
 			expect( screen.getByRole( 'button', { name: 'Configure Content Gifting' } ) ).toBeInTheDocument();
 		} );
 
@@ -108,6 +108,43 @@ describe( 'CardFeature', () => {
 			expect( onEnable ).not.toHaveBeenCalled();
 		} );
 
+		// A button reading Configure with nothing behind it would click to nowhere.
+		it( 'drops the primary button once enabled when there is nothing to configure', () => {
+			render(
+				<CardFeature title="Content gifting" enabled onEnable={ jest.fn() } moreControls={ [ { title: 'Disable', onClick: jest.fn() } ] } />
+			);
+			expect( screen.queryByRole( 'button', { name: /Configure/ } ) ).toBeNull();
+			expect( moreMenu() ).toBeInTheDocument();
+		} );
+
+		// Enabling removes the button that was just used; without a hand-off,
+		// keyboard focus falls to the page.
+		it( 'hands focus to the More menu when enabling removes the focused button', () => {
+			const props = { title: 'Content gifting', onEnable: jest.fn(), moreControls: [ { title: 'Disable', onClick: jest.fn() } ] };
+			const { rerender } = render( <CardFeature { ...props } /> );
+			primaryButton().focus();
+			rerender( <CardFeature { ...props } enabled /> );
+			expect( moreMenu() ).toHaveFocus();
+		} );
+
+		it( 'leaves focus alone when the removed button did not have it', () => {
+			const props = { title: 'Content gifting', onEnable: jest.fn(), moreControls: [ { title: 'Disable', onClick: jest.fn() } ] };
+			const { rerender } = render(
+				<>
+					<CardFeature { ...props } />
+					<button>Elsewhere</button>
+				</>
+			);
+			screen.getByRole( 'button', { name: 'Elsewhere' } ).focus();
+			rerender(
+				<>
+					<CardFeature { ...props } enabled />
+					<button>Elsewhere</button>
+				</>
+			);
+			expect( screen.getByRole( 'button', { name: 'Elsewhere' } ) ).toHaveFocus();
+		} );
+
 		it( 'still routes to onEnable when enabled with an unmet requirement, since the button reads Enable', () => {
 			const onEnable = jest.fn();
 			const onConfigure = jest.fn();
@@ -162,7 +199,7 @@ describe( 'CardFeature', () => {
 		} );
 
 		it( 'leaves the enabled badge unlinked, since it explains nothing about the button', () => {
-			render( <CardFeature title="Content gifting" enabled /> );
+			render( <CardFeature title="Content gifting" enabled onConfigure={ () => {} } /> );
 			expect( primaryButton() ).not.toHaveAttribute( 'aria-describedby' );
 		} );
 
@@ -180,7 +217,7 @@ describe( 'CardFeature', () => {
 		it( 'accepts custom labels for both states', () => {
 			const { rerender } = render( <CardFeature title="Apple News" enableLabel="Connect" configureLabel="Manage connection" /> );
 			expect( screen.getByRole( 'button', { name: 'Connect Apple News' } ) ).toBeInTheDocument();
-			rerender( <CardFeature title="Apple News" enabled enableLabel="Connect" configureLabel="Manage connection" /> );
+			rerender( <CardFeature title="Apple News" enabled enableLabel="Connect" configureLabel="Manage connection" onConfigure={ () => {} } /> );
 			expect( screen.getByRole( 'button', { name: 'Manage connection Apple News' } ) ).toBeInTheDocument();
 		} );
 	} );
@@ -234,16 +271,16 @@ describe( 'CardFeature', () => {
 			expect( container.querySelector( '.newspack-card-feature__icon' ) ).toBeNull();
 		} );
 
-		it( 'applies the descriptor colours inline and rounds fully on request', () => {
+		it( 'applies the descriptor colours inline and rounds a backed icon', () => {
 			const { container } = render(
 				<CardFeature
 					title="Content gifting"
-					icon={ { node: <span data-testid="descriptor-icon" />, fill: '#003da5', backgroundColor: '#dfe7f4', radius: 'full' } }
+					icon={ { node: <span data-testid="descriptor-icon" />, fill: '#003da5', backgroundColor: '#dfe7f4' } }
 				/>
 			);
 			const iconContainer = container.querySelector( '.newspack-card-feature__icon' );
 			expect( screen.getByTestId( 'descriptor-icon' ) ).toBeInTheDocument();
-			expect( iconContainer ).toHaveClass( 'newspack-card-feature__icon--radius-full' );
+			expect( iconContainer ).toHaveClass( 'newspack-card-feature__icon--has-background' );
 			expect( iconContainer ).toHaveStyle( { backgroundColor: '#dfe7f4', color: '#003da5' } );
 		} );
 
@@ -252,17 +289,10 @@ describe( 'CardFeature', () => {
 			expect( container.querySelector( '.newspack-card-feature__icon' ) ).toHaveAttribute( 'aria-hidden', 'true' );
 		} );
 
-		it( 'falls back to small corners when a background is set without a radius', () => {
-			const { container } = render( <CardFeature title="Content gifting" icon={ { node: <span />, backgroundColor: '#dfe7f4' } } /> );
-			const iconContainer = container.querySelector( '.newspack-card-feature__icon' );
-			expect( iconContainer ).toHaveClass( 'newspack-card-feature__icon--radius-small' );
-			expect( iconContainer ).not.toHaveClass( 'newspack-card-feature__icon--radius-full' );
-		} );
-
-		it( 'leaves an unbacked descriptor icon without a radius class', () => {
+		it( 'leaves an unbacked descriptor icon without the background class', () => {
 			const { container } = render( <CardFeature title="Content gifting" icon={ { node: <span />, fill: '#003da5' } } /> );
 			const iconContainer = container.querySelector( '.newspack-card-feature__icon' );
-			expect( iconContainer ).not.toHaveClass( 'newspack-card-feature__icon--radius-small' );
+			expect( iconContainer ).not.toHaveClass( 'newspack-card-feature__icon--has-background' );
 		} );
 	} );
 

package/src/card-feature/index.tsx

@@ -7,7 +7,7 @@ import classnames from 'classnames';
  * WordPress dependencies
  */
 import { __, _x, sprintf } from '@wordpress/i18n';
-import { createElement, isValidElement } from '@wordpress/element';
+import { createElement, isValidElement, useCallback, useEffect, useRef } from '@wordpress/element';
 import { useInstanceId } from '@wordpress/compose';
 import { DropdownMenu } from '@wordpress/components';
 import { moreVertical } from '@wordpress/icons';
@@ -25,14 +25,8 @@ type CardFeatureIcon = {
 	node: React.ReactNode;
 	/** SVG fill colour, applied via currentColor. */
 	fill?: string;
-	/** Background colour for the icon container. */
+	/** Background colour for the icon container, which is always a circle. */
 	backgroundColor?: string;
-	/**
-	 * Border-radius of the icon container.
-	 * 'small' uses $radius-small (2px), 'full' uses $radius-round (50%).
-	 * Only relevant when backgroundColor is set, where it defaults to 'small'.
-	 */
-	radius?: 'small' | 'full';
 };
 
 type MoreControl = {
@@ -77,7 +71,7 @@ type CardFeatureProps = {
 	 * where the requirement rather than the feature is what the button acts on.
 	 */
 	onEnable?: () => void;
-	/** Called when the primary button is clicked while it reads "Configure": enabled, with no unmet requirements. */
+	/** Called when the primary button is clicked while it reads "Configure": enabled, with no unmet requirements. Omit it for a feature with nothing to configure, and that state shows no primary button. */
 	onConfigure?: () => void;
 	/** Controls rendered inside the "More" dropdown, shown when enabled — including the unmet-requirements state when `requirementsActionable`. */
 	moreControls?: MoreControl[];
@@ -134,6 +128,29 @@ const CardFeature = ( {
 		title
 	);
 	const showMoreControls = enabled && !! moreControls?.length && ( ! requirements || requirementsActionable );
+	// A Configure button with nothing behind it would click to nowhere.
+	const showPrimaryButton = ! isConfigureState || !! onConfigure;
+
+	// Enabling a feature with nothing to configure removes the button that was
+	// just used, so its focus goes to the More menu instead of the page. React
+	// detaches a ref before removing the node, which is the last point the
+	// button can still be read as focused.
+	const actionsRef = useRef< HTMLDivElement >( null );
+	const primaryButtonNode = useRef< HTMLElement | null >( null );
+	const primaryButtonLeftWithFocus = useRef( false );
+	const primaryButtonRef = useCallback( ( node: HTMLElement | null ) => {
+		if ( ! node && primaryButtonNode.current ) {
+			primaryButtonLeftWithFocus.current = primaryButtonNode.current === primaryButtonNode.current.ownerDocument.activeElement;
+		}
+		primaryButtonNode.current = node;
+	}, [] );
+	useEffect( () => {
+		if ( showPrimaryButton || ! primaryButtonLeftWithFocus.current ) {
+			return;
+		}
+		primaryButtonLeftWithFocus.current = false;
+		actionsRef.current?.querySelector< HTMLElement >( '.components-dropdown-menu__toggle' )?.focus();
+	}, [ showPrimaryButton ] );
 
 	const handleButtonClick = () => {
 		if ( isConfigureState ) {
@@ -146,8 +163,7 @@ const CardFeature = ( {
 	const iconDescriptor = icon && ! isValidElement( icon ) ? ( icon as CardFeatureIcon ) : null;
 	const iconClasses = iconDescriptor
 		? classnames( 'newspack-card-feature__icon', {
-				'newspack-card-feature__icon--radius-small': !! iconDescriptor.backgroundColor && iconDescriptor.radius !== 'full',
-				'newspack-card-feature__icon--radius-full': iconDescriptor.radius === 'full',
+				'newspack-card-feature__icon--has-background': !! iconDescriptor.backgroundColor,
 		  } )
 		: undefined;
 
@@ -183,19 +199,22 @@ const CardFeature = ( {
 			</Card.Header>
 			<Card.Content className="newspack-card-feature__actions">
 				<Stack direction="row" align="center" justify="space-between" gap="sm" wrap="wrap">
-					<Stack direction="row" align="center" gap="sm">
-						<Button
-							variant={ isConfigureState ? 'tertiary' : 'secondary' }
-							accessibleWhenDisabled
-							aria-describedby={ describedById }
-							aria-label={ buttonAccessibleLabel }
-							disabled={ ( isMuted && ! requirementsActionable ) || busy }
-							isBusy={ busy }
-							onClick={ handleButtonClick }
-							size="compact"
-						>
-							{ buttonLabel }
-						</Button>
+					<Stack ref={ actionsRef } direction="row" align="center" gap="sm">
+						{ showPrimaryButton && (
+							<Button
+								ref={ primaryButtonRef }
+								variant={ isConfigureState ? 'tertiary' : 'secondary' }
+								accessibleWhenDisabled
+								aria-describedby={ describedById }
+								aria-label={ buttonAccessibleLabel }
+								disabled={ ( isMuted && ! requirementsActionable ) || busy }
+								isBusy={ busy }
+								onClick={ handleButtonClick }
+								size="compact"
+							>
+								{ buttonLabel }
+							</Button>
+						) }
 						{ showMoreControls && (
 							<DropdownMenu
 								icon={ moreVertical }

package/src/card-feature/style.scss

@@ -49,11 +49,7 @@
 			width: wp-vars.$grid-unit-30;
 		}
 
-		&--radius-small {
-			border-radius: wp-vars.$radius-small;
-		}
-
-		&--radius-full {
+		&--has-background {
 			border-radius: wp-vars.$radius-round;
 		}
 	}

package/src/debug-badge/index.js

@@ -0,0 +1,36 @@
+/**
+ * Debug Badge
+ */
+
+/**
+ * WordPress dependencies.
+ */
+import { __ } from '@wordpress/i18n';
+import { Icon, bug } from '@wordpress/icons';
+
+/**
+ * Internal dependencies.
+ */
+import './style.scss';
+
+/**
+ * Debug Badge component.
+ *
+ * Gates itself on `window.newspack_aux_data.is_debug_mode`, so consumers render
+ * it unconditionally and it stays absent outside debug mode.
+ *
+ * @return {JSX.Element|null} Debug Badge component, or nothing outside debug mode.
+ */
+const DebugBadge = () => {
+	if ( ! window.newspack_aux_data?.is_debug_mode ) {
+		return null;
+	}
+
+	return (
+		<div className="newspack-debug-badge" role="img" aria-label={ __( 'Debug mode', 'newspack-plugin' ) }>
+			<Icon icon={ bug } />
+		</div>
+	);
+};
+
+export default DebugBadge;