newspack-components 4.3.0 → 4.4.0-alpha.1

package/src/card/core-card.js

@@ -7,7 +7,7 @@
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
-import { Button, Card as CardWrapper, CardHeader, CardFooter, DropdownMenu, MenuItem, ToggleControl } from '@wordpress/components';
+import { Button, Card as CardWrapper, CardHeader, CardFooter, DropdownMenu, MenuGroup, MenuItem, ToggleControl } from '@wordpress/components';
 import { Icon, chevronDown, chevronRight, chevronUp, dragHandle, moreVertical } from '@wordpress/icons';
 
 /**
@@ -28,6 +28,11 @@ const CoreCard = ( {
 	className,
 	footer,
 	header,
+	headerAction,
+	headerStyle,
+	childrenStyle,
+	footerStyle,
+	disabled,
 	icon,
 	iconBackgroundColor,
 	isActive,
@@ -38,24 +43,30 @@ const CoreCard = ( {
 	isSmall,
 	dragIndex,
 	onDragCallback = () => {},
+	onToggle = () => {},
 	onHeaderClick,
 	noBorder,
 	noMargin,
 	children = null,
+	hasGreyHeader,
+	hasHeaderBorder = true,
 	...otherProps
 } ) => {
 	const classes = classNames(
 		'newspack-card--core',
 		className,
 		( buttonsCard || as === 'a' ) && 'newspack-card--core__buttons-card',
+		actions?.length > 0 && 'newspack-card--core__header--has-actions',
 		isDraggable && 'newspack-card--core__is-draggable',
 		isNarrow && 'newspack-card--core__is-narrow',
 		isSmall && 'newspack-card--core__is-small',
 		icon && 'newspack-card--core__has-icon',
 		iconBackgroundColor && 'newspack-card--core__has-icon-background-color',
 		isActive && 'newspack-card--core__is-active',
+		disabled && 'newspack-card--core__is-disabled',
 		children && 'newspack-card--core__has-children',
-		noMargin && 'newspack-card--core__no-margin'
+		noMargin && 'newspack-card--core__no-margin',
+		hasGreyHeader && 'newspack-card--core__has-grey-header'
 	);
 	let sizeProps = isSmall ? 'small' : otherProps.size;
 	if ( buttonsCard || as === 'a' ) {
@@ -74,9 +85,17 @@ const CoreCard = ( {
 			{ ( header || icon ) && (
 				<CardHeader
 					as={ onHeaderClick ? 'button' : undefined }
-					className={ classNames( 'newspack-card--core__header', isDraggable && 'newspack-card--core__header--is-draggable' ) }
+					className={ classNames(
+						'newspack-card--core__header',
+						isDraggable && 'newspack-card--core__header--is-draggable',
+						! hasHeaderBorder && 'newspack-card--core__header--no-border'
+					) }
+					style={ headerStyle }
 					size={ sizeProps }
-					onClick={ onHeaderClick }
+					gap={ 4 }
+					onClick={ disabled ? undefined : onHeaderClick }
+					disabled={ onHeaderClick && disabled ? true : undefined }
+					aria-disabled={ onHeaderClick && disabled ? true : undefined }
 				>
 					{ isDraggable && (
 						<div className="newspack-card--core__header__draggable-controls">
@@ -106,6 +125,15 @@ const CoreCard = ( {
 							<Icon icon={ icon } height={ isSmall ? 24 : 48 } width={ isSmall ? 24 : 48 } />
 						</div>
 					) }
+					{ actions?.length > 0 && actionType === 'toggle' && (
+						<ToggleControl
+							className="newspack-card--core__action"
+							label={ otherProps.title }
+							hideLabelFromVision
+							checked={ isActive }
+							onChange={ onToggle }
+						/>
+					) }
 					{ header && <div className="newspack-card--core__header-content">{ header }</div> }
 					{ ! actions?.length > 0 && actionType === 'chevron' && (
 						<Icon className="newspack-card--core__action" icon={ chevronRight } height={ 24 } width={ 24 } />
@@ -116,30 +144,79 @@ const CoreCard = ( {
 							label={ otherProps.title }
 							hideLabelFromVision
 							checked={ isActive }
-							onChange={ () => {} }
+							onChange={ onToggle }
 						/>
 					) }
 					{ actions?.length > 0 && (
 						<DropdownMenu icon={ moreVertical } label={ __( 'More', 'newspack-plugin' ) }>
 							{ () =>
-								actions.map( ( action, index ) => (
-									<MenuItem
-										key={ index }
-										icon={ action.icon }
-										onClick={ action.action }
-										disabled={ action.disabled || false }
-										isDestructive={ action.destructive || false }
-									>
-										{ action.label }
-									</MenuItem>
-								) )
+								actions.map( ( action, index ) => {
+									// Actions can be an array of sub-actions, which are rendered within a MenuGroup.
+									if ( Array.isArray( action ) ) {
+										return (
+											<MenuGroup key={ index }>
+												{ action.map( ( subAction, i ) => {
+													return (
+														<MenuItem
+															key={ i }
+															icon={ subAction.icon }
+															onClick={ subAction.action }
+															href={ subAction.href }
+															disabled={ subAction.disabled || false }
+															isDestructive={ subAction.destructive || false }
+														>
+															{ subAction.label }
+														</MenuItem>
+													);
+												} ) }
+											</MenuGroup>
+										);
+									}
+									return (
+										<MenuItem
+											key={ index }
+											icon={ action.icon }
+											onClick={ action.action }
+											href={ action.href }
+											disabled={ action.disabled || false }
+											isDestructive={ action.destructive || false }
+										>
+											{ action.label }
+										</MenuItem>
+									);
+								} )
 							}
 						</DropdownMenu>
 					) }
+					{ headerAction && (
+						<Button
+							className="newspack-card--core__header__action"
+							icon={ headerAction.icon }
+							href={ headerAction.href }
+							disabled={ headerAction.disabled || false }
+							isDestructive={ headerAction.destructive || false }
+							onClick={ headerAction.onClick }
+							tone={ headerAction.tone || 'primary' }
+							variant={ headerAction.variant || 'secondary' }
+						>
+							{ headerAction.label }
+						</Button>
+					) }
 				</CardHeader>
 			) }
-			{ children && <div className="newspack-card--core__body">{ children }</div> }
-			{ footer && <CardFooter size={ sizeProps }>{ footer }</CardFooter> }
+			{ children && (
+				<div
+					className={ classNames( 'newspack-card--core__body', ! hasHeaderBorder && 'newspack-card--core__body--no-header-border' ) }
+					style={ childrenStyle }
+				>
+					{ children }
+				</div>
+			) }
+			{ footer && (
+				<CardFooter size={ sizeProps } style={ footerStyle }>
+					{ footer }
+				</CardFooter>
+			) }
 		</CardWrapper>
 	);
 };

package/src/card/index.js

@@ -43,6 +43,7 @@ class Card extends Component {
 				noMargin: false,
 				isDraggable: false,
 				dragIndex: null,
+				hasGreyHeader: false,
 				onDragCallback: () => {},
 			},
 			...otherProps

package/src/card/style-core.scss

@@ -3,26 +3,27 @@
  */
 
 @use "~@wordpress/base-styles/colors" as wp-colors;
+@use "~@wordpress/base-styles/variables" as wp-vars;
 @use "../../../colors/colors.module" as colors;
 
 .newspack-card--core,
 .newspack-wizard .newspack-card--core {
-	background: white;
+	background: wp-colors.$white;
 	position: relative;
 	transition: background-color 125ms ease-in-out, box-shadow 125ms ease-in-out, color 125ms ease-in-out;
 	svg {
 		transition: fill 125ms ease-in-out;
 	}
 	&__icon {
-		border-radius: 50%;
+		border-radius: wp-vars.$radius-round;
 		display: grid;
-		height: 48px;
+		height: wp-vars.$grid-unit-60;
 		place-items: center;
-		width: 48px;
+		width: wp-vars.$grid-unit-60;
 		svg {
 			fill: var(--wp-admin-theme-color);
-			height: 40px;
-			width: 40px;
+			height: wp-vars.$grid-unit-50;
+			width: wp-vars.$grid-unit-50;
 		}
 		.newspack-card--core__has-icon-background-color & {
 			background: var(--wp-admin-theme-color-lighter-10);
@@ -35,24 +36,37 @@
 		h4,
 		h5,
 		h6 {
-			font-size: 14px;
-			font-weight: 500;
+			font-size: wp-vars.$font-size-large;
 		}
-		.newspack-card--core__icon {
-			height: 40px;
-			width: 40px;
-			svg {
-				height: 24px;
-				width: 24px;
+		.newspack-card--core {
+			&__header-content {
+				* {
+					line-height: wp-vars.$font-line-height-small;
+				}
+			}
+			&__icon {
+				height: wp-vars.$grid-unit-50;
+				width: wp-vars.$grid-unit-50;
+				svg {
+					height: wp-vars.$grid-unit-30;
+					width: wp-vars.$grid-unit-30;
+				}
 			}
 		}
 	}
 	&__no-margin .components-card__body {
 		padding: 0 !important;
 	}
+	&__is-disabled {
+		cursor: not-allowed;
+		opacity: 0.5;
+		.newspack-card--core__header {
+			pointer-events: none;
+		}
+	}
 	&__header {
 		color: wp-colors.$gray-700;
-		column-gap: 16px;
+		flex-wrap: wrap;
 		position: relative;
 		.newspack-card--core__action {
 			margin: 0;
@@ -68,22 +82,26 @@
 				word-wrap: normal !important;
 			}
 		}
-		.components-dropdown-menu {
+		> .components-dropdown-menu {
 			aspect-ratio: 1;
 			border-left: 1px solid wp-colors.$gray-200;
 			display: grid;
 			height: 100%;
+			max-width: 50px;
 			padding: 4px;
 			place-items: center;
 			position: absolute;
 			right: 0;
 			top: 0;
 		}
+		&__action {
+			background-color: wp-colors.$white;
+			flex: 1 100%;
+			justify-content: center !important;
+		}
 	}
 	&__header--is-draggable {
-		.newspack-card--core__header-content {
-			padding-left: 65px;
-		}
+		padding-left: 80px !important;
 		.newspack-card--core__header__draggable-controls {
 			align-items: center;
 			border-right: 1px solid wp-colors.$gray-200;
@@ -110,6 +128,21 @@
 			}
 		}
 	}
+	// Two classes beat the single-class .components-card__header border-bottom
+	// rule from WP Core without needing !important.
+	&__header.newspack-card--core__header--no-border {
+		border-bottom: none;
+	}
+	&__body.newspack-card--core__body--no-header-border {
+		> div:not(.components-card__body):not(.components-card__media):not(.components-card__divider) {
+			padding-top: 0;
+		}
+	}
+	&__header--has-actions {
+		.newspack-card--core__header {
+			padding-right: 70px;
+		}
+	}
 	button.newspack-card--core__header {
 		appearance: none;
 		background-color: white;
@@ -140,18 +173,25 @@
 		h6 {
 			align-items: center;
 			color: wp-colors.$gray-900;
-			font-weight: 500;
+			font-weight: 600;
 			display: flex;
 			gap: 8px;
+			a {
+				color: inherit;
+				text-decoration: none;
+				&:hover {
+					text-decoration: underline;
+				}
+			}
 			.newspack-badge {
 				font-weight: 400;
 			}
 		}
 	}
-	&__is-active {
+	&__is-active:not(.newspack-card--core__is-draggable) {
 		border-color: var(--wp-admin-theme-color);
 		box-shadow: var(--wp-admin-theme-color) 0 0 0 1px;
-		button.newspack-card--core__header {
+		.newspack-card--core__header {
 			background-color: rgba( var(--wp-admin-theme-color--rgb), 0.04 );
 			color: var(--wp-admin-theme-color);
 			h1,
@@ -168,7 +208,7 @@
 		}
 
 		&.newspack-card--core__has-children {
-			button.newspack-card--core__header {
+			.newspack-card--core__header {
 				border-bottom-left-radius: 0;
 				border-bottom-right-radius: 0;
 			}
@@ -203,14 +243,39 @@
 			}
 		}
 	}
+	&.is-destructive {
+		.newspack-card--core__header {
+			h1,
+			h2,
+			h3,
+			h4,
+			h5,
+			h6 {
+				color: wp-colors.$alert-red;
+			}
+			&:hover,
+			&:focus {
+				background-color: wp-colors.$gray-100;
+			}
+		}
+		.newspack-card--core__action,
+		.newspack-card--core__action svg {
+			fill: wp-colors.$alert-red;
+		}
+	}
 	hr.components-card__divider {
 		margin: 0;
 	}
 	&__is-narrow {
 		margin-left: auto;
 		margin-right: auto;
-		@media screen and ( min-width: 608px ) {
-			max-width: 576px;
+		@media screen and ( min-width: 615px ) {
+			max-width: 583px;
+		}
+	}
+	&__has-grey-header {
+		.newspack-card--core__header {
+			background-color: rgba(black, 0.025);
 		}
 	}
 	&__body {
@@ -223,5 +288,8 @@
 				padding: 0;
 			}
 		}
+		> .components-card__media {
+			border-radius: 0 !important;
+		}
 	}
 }

package/src/card/style.scss

@@ -52,8 +52,8 @@
 		margin-left: auto;
 		margin-right: auto;
 
-		@media screen and ( min-width: 608px ) {
-			max-width: 576px;
+		@media screen and ( min-width: 615px ) {
+			max-width: 583px;
 		}
 	}
 

package/src/card-feature/README.md

@@ -0,0 +1,188 @@
+# CardFeature
+
+A card component for presenting a named feature or setting with a predictable, state-driven interaction model. It handles the primary button, an optional "More" dropdown, and a badge automatically based on the `enabled` and `requirements` props.
+
+## Layout rules
+
+- **Maximum 2 cards per row.** Use `<Grid columns={ 2 }>` — never 3 or more. Cards are designed to be read, not scanned, and 3+ columns makes them too narrow for the content.
+- The icon is always displayed on the **right-hand side**, aligned to the top of the content.
+
+## States
+
+| State | Condition | Button | Dropdown | Badge |
+|---|---|---|---|---|
+| **Unmet requirements** | `requirements` is set | "Enable" — disabled (clickable if `requirementsActionable`) | Hidden | Error badge with `requirements` text |
+| **Disabled** | `!enabled`, no requirements | "Enable" | Hidden | None |
+| **Enabled** | `enabled`, no requirements | "Configure" | Shown if `moreControls` provided | Success badge ("Enabled") |
+
+The card content (title + description) is visually muted (gray text, lighter border) when `requirements` is set.
+
+## Basic usage
+
+```tsx
+import { __ } from '@wordpress/i18n';
+
+<CardFeature
+	title={ __( 'Metered countdown', 'newspack-plugin' ) }
+	description={ __( 'Show a countdown banner letting readers know how many free views they have left.', 'newspack-plugin' ) }
+	enabled={ isEnabled }
+	onEnable={ () => setEnabled( true ) }
+	onConfigure={ () => history.push( '/settings/countdown' ) }
+	moreControls={ [
+		{ title: __( 'Disable', 'newspack-plugin' ), onClick: () => setEnabled( false ) },
+	] }
+/>
+```
+
+## With unmet requirements
+
+When `requirements` is set the button is disabled and an error badge displays the string. The title and description are visually muted.
+
+```tsx
+import { __ } from '@wordpress/i18n';
+
+<CardFeature
+	title={ __( 'Metered countdown', 'newspack-plugin' ) }
+	description={ __( 'Show a countdown banner letting readers know how many free views they have left.', 'newspack-plugin' ) }
+	enabled={ isEnabled }
+	requirements={ __( 'Requires metering', 'newspack-plugin' ) }
+	onEnable={ () => setEnabled( true ) }
+	onConfigure={ () => history.push( '/settings/countdown' ) }
+	moreControls={ [
+		{ title: __( 'Disable', 'newspack-plugin' ), onClick: () => setEnabled( false ) },
+	] }
+/>
+```
+
+## With a custom icon
+
+The `icon` prop accepts an object, not a bare node. Pass `node` for the icon element, `fill` to control the SVG colour (applied via `currentColor`), `backgroundColor` for a container background, and `radius` for the corner treatment.
+
+The icon container is always **40 × 40 px** with the SVG at **24 × 24 px**. `radius` only applies when `backgroundColor` is set.
+
+```tsx
+import { __ } from '@wordpress/i18n';
+import { Icon, starFilled } from '@wordpress/icons';
+
+// Icon with fill only
+<CardFeature
+	title={ __( 'Content gifting', 'newspack-plugin' ) }
+	description={ __( 'Let subscribers share gated articles with non-subscribers.', 'newspack-plugin' ) }
+	icon={ { node: <Icon icon={ starFilled } />, fill: '#003da5' } }
+	enabled={ isEnabled }
+	onEnable={ handleEnable }
+	onConfigure={ handleConfigure }
+	moreControls={ [ { title: __( 'Disable', 'newspack-plugin' ), onClick: handleDisable } ] }
+/>
+
+// Icon with circular background
+<CardFeature
+	title={ __( 'Content gifting', 'newspack-plugin' ) }
+	description={ __( 'Let subscribers share gated articles with non-subscribers.', 'newspack-plugin' ) }
+	icon={ { node: <Icon icon={ starFilled } />, fill: '#003da5', backgroundColor: '#dfe7f4', radius: 'full' } }
+	enabled={ isEnabled }
+	onEnable={ handleEnable }
+	onConfigure={ handleConfigure }
+	moreControls={ [ { title: __( 'Disable', 'newspack-plugin' ), onClick: handleDisable } ] }
+/>
+```
+
+## With custom button labels
+
+Override `enableLabel` and `configureLabel` to match the context of the feature.
+
+```tsx
+import { __ } from '@wordpress/i18n';
+
+<CardFeature
+	title={ __( 'Apple News', 'newspack-plugin' ) }
+	description={ __( 'Automatically publish articles to Apple News.', 'newspack-plugin' ) }
+	enabled={ isEnabled }
+	enableLabel={ __( 'Connect', 'newspack-plugin' ) }
+	configureLabel={ __( 'Manage connection', 'newspack-plugin' ) }
+	onEnable={ handleConnect }
+	onConfigure={ () => history.push( '/settings/apple-news' ) }
+	moreControls={ [ { title: __( 'Disconnect', 'newspack-plugin' ), onClick: handleDisconnect } ] }
+/>
+```
+
+## With a custom badge
+
+Override `badgeText` and `badgeLevel` to change the badge shown when the feature is enabled. Available levels: `default`, `info`, `success`, `warning`, `error`.
+
+```tsx
+import { __ } from '@wordpress/i18n';
+
+<CardFeature
+	title={ __( 'Stripe', 'newspack-plugin' ) }
+	description={ __( 'Accept payments via Stripe.', 'newspack-plugin' ) }
+	enabled={ isEnabled }
+	badgeText={ __( 'Live mode', 'newspack-plugin' ) }
+	badgeLevel="info"
+	onEnable={ handleEnable }
+	onConfigure={ () => history.push( '/settings/stripe' ) }
+	moreControls={ [ { title: __( 'Disable', 'newspack-plugin' ), onClick: handleDisable } ] }
+/>
+```
+
+## With multiple "More" controls
+
+`moreControls` accepts any number of items, each with a `title`, `onClick`, and an optional `icon`.
+
+```tsx
+import { __ } from '@wordpress/i18n';
+
+<CardFeature
+	title={ __( 'Newsletters', 'newspack-plugin' ) }
+	description={ __( 'Send newsletters directly from the WordPress editor.', 'newspack-plugin' ) }
+	enabled={ isEnabled }
+	onEnable={ handleEnable }
+	onConfigure={ () => history.push( '/settings/newsletters' ) }
+	moreControls={ [
+		{ title: __( 'Edit', 'newspack-plugin' ), onClick: handleEdit },
+		{ title: __( 'Preview', 'newspack-plugin' ), onClick: handlePreview },
+		{ title: __( 'Disable', 'newspack-plugin' ), onClick: handleDisable },
+	] }
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Card heading (**required**) |
+| `description` | `string` | — | Supporting text below the title |
+| `icon` | `CardFeatureIcon` | — | Icon displayed on the right. See `CardFeatureIcon` below. |
+| `enabled` | `boolean` | `false` | Whether the feature is currently enabled |
+| `requirements` | `string` | — | When set, enters the unmet-requirements state; value is used as the error badge text |
+| `requirementsActionable` | `boolean` | `false` | When `requirements` is set, keep the primary button clickable so it can remediate the unmet requirement |
+| `enableLabel` | `string` | `"Enable"` | Primary button label when not enabled |
+| `configureLabel` | `string` | `"Configure"` | Primary button label when enabled |
+| `onEnable` | `() => void` | — | Called when the primary button is clicked and the feature is not enabled |
+| `onConfigure` | `() => void` | — | Called when the primary button is clicked and the feature is enabled |
+| `moreControls` | `MoreControl[]` | — | Items for the "More" dropdown, shown only when enabled |
+| `badgeText` | `string` | `"Enabled"` | Badge text shown when enabled |
+| `badgeLevel` | `BadgeLevel` | `"success"` | Badge level shown when enabled |
+| `className` | `string` | — | Additional class name applied to the card element |
+
+### `CardFeatureIcon`
+
+```ts
+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)
+	                             // Only applied when backgroundColor is set.
+};
+```
+
+### `MoreControl`
+
+```ts
+type MoreControl = {
+	title: string;
+	onClick: () => void;
+	icon?: React.ReactNode;
+};
+```