newspack-components 4.3.0 → 4.4.0-alpha.1

package/src/card-feature/index.tsx

@@ -0,0 +1,186 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { DropdownMenu, __experimentalHStack as HStack } from '@wordpress/components'; // eslint-disable-line @wordpress/no-unsafe-wp-apis
+import { moreVertical } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import Badge from '../badge';
+import Button from '../button';
+import Card from '../card';
+import './style.scss';
+
+type BadgeLevel = 'default' | 'info' | 'success' | 'warning' | 'error';
+
+type CardFeatureIcon = {
+	/** The icon node to render (e.g. a WordPress <Icon> component). */
+	node: React.ReactNode;
+	/** SVG fill colour, applied via currentColor. */
+	fill?: string;
+	/** Background colour for the icon container. */
+	backgroundColor?: string;
+	/**
+	 * Border-radius of the icon container.
+	 * 'small' uses $radius-small (2px), 'full' uses $radius-round (50%).
+	 * Only relevant when backgroundColor is set.
+	 */
+	radius?: 'small' | 'full';
+};
+
+type MoreControl = {
+	title: string;
+	onClick: () => void;
+	icon?: React.ReactNode;
+};
+
+type CardFeatureProps = {
+	title: string;
+	description?: string;
+	/** Icon displayed on the right-hand side of the title and description. */
+	icon?: CardFeatureIcon;
+	/** Whether the feature is currently enabled. */
+	enabled?: boolean;
+	/**
+	 * When set, the card enters the "unmet requirements" state: an error
+	 * badge displays this string and the title/description are muted. By
+	 * default the primary button is disabled — set `requirementsActionable`
+	 * if the primary button is the remediation for the unmet requirement.
+	 */
+	requirements?: string;
+	/**
+	 * When `requirements` is set, keep the primary button clickable so the
+	 * user can remediate the unmet requirement from this card.
+	 */
+	requirementsActionable?: boolean;
+	/** Primary button label when not enabled. Default: "Enable". */
+	enableLabel?: string;
+	/** Primary button label when enabled. Default: "Configure". */
+	configureLabel?: string;
+	/** Called when the primary button is clicked and the feature is not enabled. */
+	onEnable?: () => void;
+	/** Called when the primary button is clicked and the feature is enabled. */
+	onConfigure?: () => void;
+	/** Controls rendered inside the "More" dropdown, shown only when enabled. */
+	moreControls?: MoreControl[];
+	/** Badge text shown when enabled. Default: "Enabled". */
+	badgeText?: string;
+	/** Badge level shown when enabled. Default: "success". */
+	badgeLevel?: BadgeLevel;
+	className?: string;
+};
+
+/**
+ * CardFeature component.
+ *
+ * A card for presenting a named feature or setting with a predictable
+ * action model: a primary button, an optional "More" dropdown when enabled,
+ * and an automatic badge reflecting the current state.
+ */
+const CardFeature = ( {
+	title,
+	description,
+	icon,
+	enabled = false,
+	requirements,
+	requirementsActionable = false,
+	enableLabel,
+	configureLabel,
+	onEnable,
+	onConfigure,
+	moreControls,
+	badgeText,
+	badgeLevel = 'success',
+	className,
+}: CardFeatureProps ) => {
+	const isMuted = !! requirements;
+	const classes = classnames( 'newspack-card-feature', className, {
+		'newspack-card-feature--muted': isMuted,
+	} );
+
+	let badge: { text: string; level: BadgeLevel } | undefined;
+	if ( requirements ) {
+		badge = { text: requirements, level: 'error' };
+	} else if ( enabled ) {
+		badge = { text: badgeText ?? __( 'Enabled', 'newspack-plugin' ), level: badgeLevel };
+	}
+
+	const isConfigureState = enabled && ! requirements;
+	const buttonLabel = isConfigureState ? configureLabel ?? __( 'Configure', 'newspack-plugin' ) : enableLabel ?? __( 'Enable', 'newspack-plugin' );
+
+	const handleButtonClick = () => {
+		if ( isConfigureState ) {
+			onConfigure?.();
+		} else {
+			onEnable?.();
+		}
+	};
+
+	const iconClasses = icon
+		? classnames( 'newspack-card-feature__icon', {
+				'newspack-card-feature__icon--radius-small': !! icon.backgroundColor && icon.radius !== 'full',
+				'newspack-card-feature__icon--radius-full': icon.radius === 'full',
+		  } )
+		: undefined;
+
+	return (
+		<Card
+			className={ classes }
+			__experimentalCoreCard
+			__experimentalCoreProps={ {
+				headerStyle: { padding: 32 },
+				header: (
+					<>
+						<HStack alignment="top" spacing={ 4 }>
+							<div className="newspack-card-feature__content">
+								<h2 className="newspack-card-feature__title">{ title }</h2>
+								{ description && <p className="newspack-card-feature__description">{ description }</p> }
+							</div>
+							{ icon && (
+								<div
+									className={ iconClasses }
+									style={ {
+										backgroundColor: icon.backgroundColor,
+										color: icon.fill,
+									} }
+								>
+									{ icon.node }
+								</div>
+							) }
+						</HStack>
+						<HStack alignment="edge">
+							<HStack expanded={ false } spacing="8px">
+								<Button
+									variant={ isConfigureState ? 'tertiary' : 'secondary' }
+									disabled={ isMuted && ! requirementsActionable }
+									onClick={ handleButtonClick }
+									size="compact"
+								>
+									{ buttonLabel }
+								</Button>
+								{ isConfigureState && !! moreControls?.length && (
+									<DropdownMenu
+										icon={ moreVertical }
+										label={ __( 'More', 'newspack-plugin' ) }
+										controls={ moreControls }
+										toggleProps={ { size: 'compact' } }
+									/>
+								) }
+							</HStack>
+							{ badge && <Badge text={ badge.text } level={ badge.level } /> }
+						</HStack>
+					</>
+				),
+			} }
+		/>
+	);
+};
+
+export default CardFeature;

package/src/card-feature/style.scss

@@ -0,0 +1,75 @@
+/**
+ * CardFeature
+ */
+
+@use "~@wordpress/base-styles/colors" as wp-colors;
+@use "~@wordpress/base-styles/variables" as wp-vars;
+
+.newspack-card-feature {
+	height: 100%;
+
+	.newspack-card--core__header {
+		height: 100%;
+	}
+
+	.newspack-card--core__header-content {
+		gap: 16px;
+		display: flex;
+		flex-direction: column;
+		height: 100%;
+
+		// Push the action row (buttons + badge) to the bottom.
+		> :last-child {
+			margin-top: auto;
+		}
+	}
+
+	&__content {
+		flex: 1;
+		min-width: 0; // prevent flex blowout on long words
+	}
+
+	&__title {
+		font-size: wp-vars.$font-size-x-large;
+		line-height: wp-vars.$font-line-height-x-large;
+		text-align: left;
+	}
+
+	&__description {
+		text-align: left;
+	}
+
+	&__icon {
+		align-items: center;
+		display: flex;
+		flex: 0 0 40px;
+		height: 40px;
+		justify-content: center;
+
+		svg {
+			display: block;
+			fill: currentcolor;
+			height: 24px;
+			width: 24px;
+		}
+
+		&--radius-small {
+			border-radius: wp-vars.$radius-small;
+		}
+
+		&--radius-full {
+			border-radius: wp-vars.$radius-round;
+		}
+	}
+
+	// Unmet requirements state: lighter border, muted content.
+	&.newspack-card-feature--muted {
+		border-color: wp-colors.$gray-100;
+		box-shadow: wp-colors.$gray-100 0 0 0 1px;
+
+		.newspack-card-feature__title,
+		.newspack-card-feature__description {
+			color: wp-colors.$gray-700;
+		}
+	}
+}

package/src/card-form/README.md

@@ -0,0 +1,113 @@
+# CardForm
+
+A card component for presenting a named setting or feature with an expandable inline form. When open, the card body reveals children (controls, fields, action buttons) and the header border is removed for a seamless look. Intended for lists of items that can each be independently enabled, edited, or configured without leaving the page.
+
+## Layout rules
+
+- Stack multiple `CardForm` cards inside a `<VStack>` — they are designed to appear as a list.
+- The `actions` slot sits to the right of the badge. Keep it to one button; if you need multiple actions, use an `HStack` with `expanded={ false }`.
+- The form body (`children`) is only mounted when `isOpen` is `true`.
+
+## States
+
+| State | `isOpen` | `badge` | `actions` example |
+|---|---|---|---|
+| **Disabled** | `false` | None | "Enable" (secondary) |
+| **Enabling** | `true` | None | "Cancel" (tertiary) |
+| **Enabled** | `false` | Success badge | "Edit" (tertiary) |
+| **Editing** | `true` | Success badge | "Cancel" (tertiary) |
+
+## Basic usage — enable/edit pattern
+
+```tsx
+import { __ } from '@wordpress/i18n';
+import { useState } from '@wordpress/element';
+import { Button } from '@wordpress/components';
+import { CardForm } from '../../../../../packages/components/src';
+
+const [ isOpen, setIsOpen ] = useState( false );
+const [ isEnabled, setIsEnabled ] = useState( false );
+
+const handleClose = () => setIsOpen( false );
+
+<CardForm
+	title={ __( 'Above Header', 'newspack-plugin' ) }
+	description={ __( 'Displays an ad above the site header.', 'newspack-plugin' ) }
+	badge={ isEnabled ? { level: 'success', text: __( 'Enabled', 'newspack-plugin' ) } : undefined }
+	actions={
+		isEnabled ? (
+			<Button variant="tertiary" size="compact" onClick={ () => isOpen ? handleClose() : setIsOpen( true ) }>
+				{ isOpen ? __( 'Cancel', 'newspack-plugin' ) : __( 'Edit', 'newspack-plugin' ) }
+			</Button>
+		) : (
+			<Button variant="secondary" size="compact" onClick={ () => setIsOpen( true ) }>
+				{ __( 'Enable', 'newspack-plugin' ) }
+			</Button>
+		)
+	}
+	isOpen={ isOpen }
+	onRequestClose={ handleClose }
+>
+	{ /* form controls */ }
+	<Button variant="primary" size="compact" onClick={ handleSave }>
+		{ __( 'Update', 'newspack-plugin' ) }
+	</Button>
+</CardForm>
+```
+
+## With a custom badge level
+
+The `badge` prop accepts any `BadgeLevel`. Use `warning` or `error` to communicate a degraded state.
+
+```tsx
+<CardForm
+	title={ __( 'Above Header', 'newspack-plugin' ) }
+	badge={ { level: 'warning', text: __( 'Missing ad unit', 'newspack-plugin' ) } }
+	actions={ <Button variant="tertiary" size="compact">{ __( 'Edit', 'newspack-plugin' ) }</Button> }
+	isOpen={ false }
+/>
+```
+
+## Without a badge
+
+Omit `badge` (or pass `undefined`) to show no badge at all.
+
+```tsx
+<CardForm
+	title={ __( 'Sticky Footer', 'newspack-plugin' ) }
+	description={ __( 'Pins an ad to the bottom of the viewport.', 'newspack-plugin' ) }
+	actions={
+		<Button variant="secondary" size="compact" onClick={ handleEnable }>
+			{ __( 'Enable', 'newspack-plugin' ) }
+		</Button>
+	}
+	isOpen={ false }
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Card heading (**required**) |
+| `description` | `string` | — | Supporting text below the title |
+| `badge` | `{ text: string; level?: BadgeLevel }` | — | Badge shown next to the actions slot. Omit or pass `undefined` to hide. |
+| `actions` | `React.ReactNode` | — | JSX rendered in the header action area (buttons, dropdowns, etc.) |
+| `isOpen` | `boolean` | `false` | When `true`, renders `children` in the card body and removes the header border |
+| `onRequestClose` | `() => void` | — | Called when the user presses Escape while focus is inside the open form |
+| `titleLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Heading level rendered for `title`. Pick the level that fits the surrounding document outline. |
+| `className` | `string` | — | Additional class name applied to the card element |
+| `children` | `React.ReactNode` | — | Form content rendered inside the card body when `isOpen` is `true` |
+
+## Accessibility
+
+- The body is rendered as a `role="region"` labelled by the title, so assistive tech announces it as a named region when focus enters.
+- On open, focus moves to the first focusable element in the body (or to the region itself if none exist). On close, focus is restored to whatever was focused before opening — typically the trigger button.
+- The Escape listener is scoped to the open form's body, so multiple open cards do not all close on a single keypress. If an inner control needs to consume Escape (for example, to close its own menu), call `event.preventDefault()` and CardForm will ignore it.
+
+
+### `BadgeLevel`
+
+```ts
+type BadgeLevel = 'default' | 'info' | 'success' | 'warning' | 'error';
+```

package/src/card-form/index.tsx

@@ -0,0 +1,128 @@
+/**
+ * Card Form component.
+ *
+ * A card with an expandable inline form — title, description, optional badge,
+ * and an actions slot in the header. When `isOpen` is true, children are
+ * rendered in the card body and the header border is removed for a seamless look.
+ */
+
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useRef, createElement } from '@wordpress/element';
+import { useInstanceId } from '@wordpress/compose';
+import { __experimentalHStack as HStack, __experimentalVStack as VStack } from '@wordpress/components'; // eslint-disable-line @wordpress/no-unsafe-wp-apis
+
+/**
+ * Internal dependencies
+ */
+import Badge, { BadgeLevel } from '../badge';
+import Card from '../card';
+import './style.scss';
+
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+type CardFormProps = {
+	title: string;
+	description?: string;
+	badge?: {
+		text: string;
+		level?: BadgeLevel;
+	};
+	/** JSX rendered in the header action area (buttons, etc.). */
+	actions?: React.ReactNode;
+	/** When true, children are shown and the header border is removed. */
+	isOpen?: boolean;
+	/** Called when the user presses Escape while the form is open. */
+	onRequestClose?: () => void;
+	/** Heading level for the title. Defaults to 3. */
+	titleLevel?: HeadingLevel;
+	className?: string;
+	children?: React.ReactNode;
+};
+
+const CardForm = ( { title, description, badge, actions, isOpen = false, onRequestClose, titleLevel = 3, className, children }: CardFormProps ) => {
+	const bodyRef = useRef< HTMLDivElement | null >( null );
+	const previousActiveRef = useRef< HTMLElement | null >( null );
+	const instanceId = useInstanceId( CardForm, 'newspack-card-form' );
+	const titleId = `${ instanceId }__title`;
+	const bodyId = `${ instanceId }__body`;
+
+	// Scope Escape handling to the open form's body, so multiple open CardForms
+	// don't all close on a single keypress, and callers can preventDefault from
+	// inner controls (e.g. select menus) without tripping the close.
+	useEffect( () => {
+		if ( ! isOpen || ! onRequestClose ) {
+			return;
+		}
+		const node = bodyRef.current;
+		if ( ! node ) {
+			return;
+		}
+		const handleKeyDown = ( event: KeyboardEvent ) => {
+			if ( event.key === 'Escape' && ! event.defaultPrevented ) {
+				onRequestClose();
+			}
+		};
+		node.addEventListener( 'keydown', handleKeyDown );
+		return () => node.removeEventListener( 'keydown', handleKeyDown );
+	}, [ isOpen, onRequestClose ] );
+
+	// Move focus into the body on open and restore it to the trigger on close.
+	useEffect( () => {
+		if ( ! isOpen ) {
+			return;
+		}
+		const node = bodyRef.current;
+		if ( node ) {
+			previousActiveRef.current = ( node.ownerDocument?.activeElement ?? null ) as HTMLElement | null;
+			const focusable = node.querySelector< HTMLElement >(
+				'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+			);
+			( focusable ?? node ).focus();
+		}
+		return () => {
+			previousActiveRef.current?.focus?.();
+		};
+	}, [ isOpen ] );
+
+	const titleTag = `h${ titleLevel }`;
+
+	return (
+		<Card
+			className={ classnames( 'newspack-card-form', className, {
+				'newspack-card-form--open': isOpen,
+			} ) }
+			__experimentalCoreCard
+			isSmall
+			__experimentalCoreProps={ {
+				hasHeaderBorder: ! isOpen,
+				header: (
+					<HStack justify="space-between" style={ { width: '100%' } }>
+						<VStack spacing={ 0 } style={ { flex: 1, minWidth: 0 } }>
+							{ createElement( titleTag, { id: titleId, className: 'newspack-card-form__title' }, title ) }
+							{ description && <p className="newspack-card-form__description">{ description }</p> }
+						</VStack>
+						<HStack spacing={ 2 } expanded={ false }>
+							{ badge && <Badge text={ badge.text } level={ badge.level ?? 'success' } /> }
+							{ actions }
+						</HStack>
+					</HStack>
+				),
+			} }
+		>
+			{ isOpen && (
+				<div ref={ bodyRef } id={ bodyId } role="region" aria-labelledby={ titleId } tabIndex={ -1 } className="newspack-card-form__body">
+					{ children }
+				</div>
+			) }
+		</Card>
+	);
+};
+
+export default CardForm;

package/src/card-form/style.scss

@@ -0,0 +1,20 @@
+/**
+ * CardForm
+ */
+
+@use "~@wordpress/base-styles/colors" as wp-colors;
+@use "~@wordpress/base-styles/variables" as wp;
+
+.newspack-card-form {
+	&__title {
+		font-size: wp.$font-size-large;
+		font-weight: 600;
+		line-height: wp.$font-line-height-large;
+	}
+
+	&__description {
+		color: wp-colors.$gray-700;
+		font-size: wp.$font-size-medium;
+		line-height: wp.$font-line-height-medium;
+	}
+}

package/src/card-settings-group/index.tsx

@@ -2,6 +2,11 @@
  * Card - Settings group component.
  */
 
+/**
+ * External dependencies
+ */
+import classNames from 'classnames';
+
 /**
  * Internal dependencies
  */
@@ -9,25 +14,42 @@ import { Card } from '../';
 import './style.scss';
 
 const CardSettingsGroup = ( {
-	actionType = 'chevron',
+	actionType = 'none',
 	children,
+	className,
+	disabled = false,
 	icon = null,
+	headerAction,
 	title = '',
 	description = '',
 	isActive = false,
 	onEnable = () => {},
+	onHeaderClick = () => {},
 }: {
 	actionType?: 'chevron' | 'toggle' | 'button' | 'link' | 'none';
 	children?: React.ReactNode;
+	className?: string;
+	disabled?: boolean;
 	icon?: React.ReactNode;
 	title: string;
+	headerAction?: {
+		label: string;
+		icon?: React.ReactNode;
+		href?: string;
+		onClick?: () => void;
+		disabled?: boolean;
+		destructive?: boolean;
+		tone?: 'primary' | 'secondary' | 'tertiary' | 'link';
+		variant?: 'primary' | 'secondary' | 'tertiary' | 'link';
+	};
 	description?: string;
 	isActive?: boolean;
 	onEnable?: () => void;
+	onHeaderClick?: () => void;
 } ) => {
 	return (
 		<Card
-			className="newspack-card--core--settings-group"
+			className={ classNames( 'newspack-card--core--settings-group', className ) }
 			actionType={ actionType }
 			isSmall
 			__experimentalCoreCard
@@ -38,7 +60,10 @@ const CardSettingsGroup = ( {
 						{ description && <p>{ description }</p> }
 					</>
 				),
-				onHeaderClick: onEnable,
+				headerAction,
+				onHeaderClick,
+				onToggle: onEnable,
+				disabled,
 				icon,
 				iconBackgroundColor: true,
 				isActive,

package/src/card-sortable-list/index.tsx

@@ -22,11 +22,23 @@ import classNames from 'classnames';
 const DROP_ANIMATION_DURATION = 400; // ms — must match $drop-duration in style.scss
 const BUTTON_MOVE_DURATION = 200; // ms — must match $shift-duration in style.scss
 
+type DraggableItemAction = {
+	label: string;
+	icon?: unknown;
+	action: () => void;
+	disabled?: boolean;
+	destructive?: boolean;
+};
+
 type DraggableItem = {
 	id: string | number;
 	title: string;
+	description?: string;
 	badgeLevel: 'default' | 'success' | 'info' | 'warning' | 'error';
 	badgeText: string;
+	toggleChecked?: boolean;
+	onToggleChange?: () => void;
+	actions?: DraggableItemAction[];
 };
 
 type DragMeasurements = {
@@ -387,16 +399,27 @@ const CardSortableList = ( {
 										__experimentalCoreCard
 										__experimentalCoreProps={ {
 											header: (
-												<h3>
-													{ item.title }
-													<Badge level={ item.badgeLevel } text={ item.badgeText } />
-												</h3>
+												<>
+													<h3>
+														{ item.title }
+														<Badge level={ item.badgeLevel } text={ item.badgeText } />
+													</h3>
+													{ item.description && <p>{ item.description }</p> }
+												</>
 											),
 											isDraggable: true,
 											isFirstTarget: index === 0,
 											isLastTarget: index === sortedItems.length - 1,
 											dragIndex: index,
 											onDragCallback: handleButtonMove,
+											...( item.onToggleChange !== undefined && {
+												actionType: 'toggle',
+												isActive: item.toggleChecked,
+												onToggle: item.onToggleChange,
+											} ),
+											...( item.actions !== undefined && {
+												actions: item.actions,
+											} ),
 										} }
 									/>
 								) }