newspack-components 4.7.0 → 4.8.0

package/src/collapsible-group/index.test.js

@@ -0,0 +1,168 @@
+/**
+ * External dependencies
+ */
+import { fireEvent, render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import CollapsibleGroup from './index';
+
+const renderItems = ( count, props = {} ) =>
+	render(
+		<CollapsibleGroup { ...props }>
+			{ Array.from( { length: count }, ( _, i ) => (
+				<CollapsibleGroup.Item key={ i } title={ `Panel ${ i }` }>
+					content
+				</CollapsibleGroup.Item>
+			) ) }
+		</CollapsibleGroup>
+	);
+
+const dividers = container => container.querySelectorAll( '.newspack-divider' );
+const items = container => container.querySelectorAll( '.newspack-collapsible-group__item' );
+
+describe( 'CollapsibleGroup dividers', () => {
+	it( 'renders no divider for a single item', () => {
+		const { container } = renderItems( 1 );
+		expect( items( container ) ).toHaveLength( 1 );
+		expect( dividers( container ) ).toHaveLength( 0 );
+	} );
+
+	it( 'renders a divider between items but not after the last', () => {
+		const { container } = renderItems( 3 );
+		expect( items( container ) ).toHaveLength( 3 );
+		expect( dividers( container ) ).toHaveLength( 2 );
+		expect( container.querySelector( '.newspack-collapsible-group' ).lastElementChild ).not.toHaveClass( 'newspack-divider' );
+	} );
+
+	it( 'counts only rendered items when placing dividers', () => {
+		const { container } = render(
+			<CollapsibleGroup>
+				<CollapsibleGroup.Item title="Panel 0">content</CollapsibleGroup.Item>
+				<CollapsibleGroup.Item title="Panel 1">content</CollapsibleGroup.Item>
+				{ false }
+				{ 'trailing text' }
+			</CollapsibleGroup>
+		);
+
+		expect( items( container ) ).toHaveLength( 2 );
+		expect( dividers( container ) ).toHaveLength( 1 );
+		expect( container.querySelector( '.newspack-collapsible-group' ).lastElementChild ).not.toHaveClass( 'newspack-divider' );
+	} );
+
+	it( 'renders tertiary dividers', () => {
+		const { container } = renderItems( 2 );
+		expect( dividers( container )[ 0 ] ).toHaveClass( 'newspack-divider--variant-tertiary' );
+	} );
+} );
+
+describe( 'CollapsibleGroup titleLevel', () => {
+	it( 'renders item titles as h2 by default', () => {
+		renderItems( 2 );
+		expect( screen.getAllByRole( 'heading', { level: 2 } ) ).toHaveLength( 2 );
+	} );
+
+	it( 'renders every item title at the level given', () => {
+		renderItems( 2, { titleLevel: 3 } );
+		expect( screen.getAllByRole( 'heading', { level: 3 } ) ).toHaveLength( 2 );
+		expect( screen.queryByRole( 'heading', { level: 2 } ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'clamps a level above the heading range', () => {
+		renderItems( 2, { titleLevel: 7 } );
+		expect( screen.getAllByRole( 'heading', { level: 6 } ) ).toHaveLength( 2 );
+	} );
+
+	it( 'clamps a level below the heading range', () => {
+		renderItems( 1, { titleLevel: 0 } );
+		expect( screen.getByRole( 'heading', { level: 1 } ) ).toBeInTheDocument();
+	} );
+
+	it( 'inherits the level in a nested group', () => {
+		render(
+			<CollapsibleGroup titleLevel={ 4 }>
+				<CollapsibleGroup.Item title="Outer" defaultOpen>
+					<CollapsibleGroup>
+						<CollapsibleGroup.Item title="Inner">content</CollapsibleGroup.Item>
+					</CollapsibleGroup>
+				</CollapsibleGroup.Item>
+			</CollapsibleGroup>
+		);
+		expect( screen.getByRole( 'heading', { level: 4, name: 'Inner' } ) ).toBeInTheDocument();
+	} );
+
+	it( 'inherits the level in a nested group when the title is hidden', () => {
+		render(
+			<CollapsibleGroup titleLevel={ 4 } hideSingleTitle>
+				<CollapsibleGroup.Item title="Outer">
+					<CollapsibleGroup>
+						<CollapsibleGroup.Item title="Inner">content</CollapsibleGroup.Item>
+					</CollapsibleGroup>
+				</CollapsibleGroup.Item>
+			</CollapsibleGroup>
+		);
+		expect( screen.getByRole( 'heading', { level: 4, name: 'Inner' } ) ).toBeInTheDocument();
+	} );
+} );
+
+describe( 'CollapsibleGroup hideSingleTitle', () => {
+	it( 'keeps the title on a lone item by default', () => {
+		renderItems( 1 );
+		expect( screen.getByRole( 'button', { name: 'Panel 0' } ) ).toBeInTheDocument();
+	} );
+
+	it( 'drops the title and opens a lone item when set', () => {
+		renderItems( 1, { hideSingleTitle: true } );
+		expect( screen.queryByRole( 'button', { name: 'Panel 0' } ) ).not.toBeInTheDocument();
+		expect( screen.getByText( 'content' ) ).toBeVisible();
+	} );
+
+	it( 'leaves titles alone when there is more than one item', () => {
+		renderItems( 2, { hideSingleTitle: true } );
+		expect( screen.getByRole( 'button', { name: 'Panel 0' } ) ).toBeInTheDocument();
+		expect( screen.getByRole( 'button', { name: 'Panel 1' } ) ).toBeInTheDocument();
+	} );
+} );
+
+describe( 'CollapsibleGroup item state', () => {
+	it( 'expands only the item marked defaultOpen', () => {
+		render(
+			<CollapsibleGroup>
+				<CollapsibleGroup.Item title="Open" defaultOpen>
+					open content
+				</CollapsibleGroup.Item>
+				<CollapsibleGroup.Item title="Closed">closed content</CollapsibleGroup.Item>
+			</CollapsibleGroup>
+		);
+		expect( screen.getByRole( 'button', { name: 'Open' } ) ).toHaveAttribute( 'aria-expanded', 'true' );
+		expect( screen.getByRole( 'button', { name: 'Closed' } ) ).toHaveAttribute( 'aria-expanded', 'false' );
+	} );
+
+	it( 'leaves a collapsed panel reachable by find-in-page', () => {
+		const { container } = renderItems( 1 );
+		expect( container.querySelector( '.newspack-collapsible-group__panel' ) ).toHaveAttribute( 'hidden', 'until-found' );
+		expect( screen.getByText( 'content' ) ).toBeInTheDocument();
+	} );
+
+	it( 'opens an item when its trigger is clicked', () => {
+		const { container } = renderItems( 1 );
+		const trigger = screen.getByRole( 'button', { name: 'Panel 0' } );
+
+		fireEvent.click( trigger );
+
+		expect( trigger ).toHaveAttribute( 'aria-expanded', 'true' );
+		expect( container.querySelector( '.newspack-collapsible-group__panel' ) ).not.toHaveAttribute( 'hidden' );
+	} );
+
+	it( 'closes an open item when its trigger is clicked', () => {
+		const { container } = renderItems( 1 );
+		const trigger = screen.getByRole( 'button', { name: 'Panel 0' } );
+
+		fireEvent.click( trigger );
+		fireEvent.click( trigger );
+
+		expect( trigger ).toHaveAttribute( 'aria-expanded', 'false' );
+		expect( container.querySelector( '.newspack-collapsible-group__panel' ) ).toHaveAttribute( 'hidden', 'until-found' );
+	} );
+} );

package/src/collapsible-group/index.tsx

@@ -0,0 +1,17 @@
+/**
+ * CollapsibleGroup
+ */
+
+/**
+ * Internal dependencies
+ */
+import Item from './item';
+import Root from './root';
+
+// The group is itself renderable, so `Item` hangs off it rather than forming a namespace object like `Drawer`.
+const CollapsibleGroup = Object.assign( Root, { Item } );
+
+( CollapsibleGroup as { displayName?: string } ).displayName = 'CollapsibleGroup';
+( Item as { displayName?: string } ).displayName = 'CollapsibleGroup.Item';
+
+export default CollapsibleGroup;

package/src/collapsible-group/item.tsx

@@ -0,0 +1,42 @@
+/**
+ * WordPress dependencies
+ */
+import { Icon, chevronDown } from '@wordpress/icons';
+import { Collapsible } from '@wordpress/ui';
+
+/**
+ * External dependencies
+ */
+import classNames from 'classnames';
+
+/**
+ * Internal dependencies
+ */
+import { useTitleLevel } from './context';
+import type { CollapsibleGroupItemProps } from './types';
+
+const Item = ( { children, className, defaultOpen = false, title }: CollapsibleGroupItemProps ) => {
+	const titleLevel = useTitleLevel();
+
+	if ( ! title ) {
+		return <div className={ classNames( 'newspack-collapsible-group__item', className ) }>{ children }</div>;
+	}
+
+	const Heading = `h${ titleLevel }` as const;
+
+	return (
+		<Collapsible.Root className={ classNames( 'newspack-collapsible-group__item', className ) } defaultOpen={ defaultOpen }>
+			<Heading className="newspack-collapsible-group__heading">
+				<Collapsible.Trigger className="newspack-collapsible-group__trigger">
+					{ title }
+					<Icon icon={ chevronDown } size={ 24 } />
+				</Collapsible.Trigger>
+			</Heading>
+			<Collapsible.Panel className="newspack-collapsible-group__panel" hiddenUntilFound>
+				<div className="newspack-collapsible-group__panel-inner">{ children }</div>
+			</Collapsible.Panel>
+		</Collapsible.Root>
+	);
+};
+
+export default Item;

package/src/collapsible-group/root.tsx

@@ -0,0 +1,42 @@
+/**
+ * WordPress dependencies
+ */
+import { Children, Fragment, cloneElement, isValidElement } from '@wordpress/element';
+import { Stack } from '@wordpress/ui';
+
+/**
+ * External dependencies
+ */
+import classNames from 'classnames';
+
+/**
+ * Internal dependencies
+ */
+import Divider from '../divider';
+import { TitleLevelContext, useTitleLevel } from './context';
+import type { CollapsibleGroupItemProps, CollapsibleGroupProps, HeadingLevel } from './types';
+import './style.scss';
+
+const clampTitleLevel = ( level: unknown ): HeadingLevel | undefined =>
+	Number.isFinite( level ) ? ( Math.min( 6, Math.max( 1, Math.round( level as number ) ) ) as HeadingLevel ) : undefined;
+
+const Root = ( { children, className, gap = 'xl', hideSingleTitle = false, titleLevel }: CollapsibleGroupProps ) => {
+	const inheritedTitleLevel = useTitleLevel();
+	const items = Children.toArray( children ).filter( isValidElement ) as React.ReactElement< CollapsibleGroupItemProps >[];
+	const hideTitle = hideSingleTitle && items.length === 1;
+
+	return (
+		<TitleLevelContext.Provider value={ clampTitleLevel( titleLevel ) ?? inheritedTitleLevel }>
+			<Stack className={ classNames( 'newspack-collapsible-group', className ) } direction="column" gap={ gap }>
+				{ items.map( ( item, index ) => (
+					<Fragment key={ item.key }>
+						{ hideTitle ? cloneElement( item, { title: undefined } ) : item }
+						{ index < items.length - 1 && <Divider variant="tertiary" marginBottom={ 0 } marginTop={ 0 } /> }
+					</Fragment>
+				) ) }
+			</Stack>
+		</TitleLevelContext.Provider>
+	);
+};
+
+export default Root;

package/src/collapsible-group/style.scss

@@ -0,0 +1,47 @@
+@use "../mixins" as mixins;
+@use "~@wordpress/base-styles/mixins" as wp-mixins;
+@use "~@wordpress/base-styles/variables" as wp-vars;
+
+.newspack-collapsible-group {
+	&__heading {
+		margin: 0;
+	}
+
+	&__trigger {
+		@include wp-mixins.heading-large();
+		align-items: center;
+		background: none;
+		border: 0;
+		color: inherit;
+		cursor: pointer;
+		display: flex;
+		gap: wp-vars.$grid-unit-10;
+		justify-content: space-between;
+		padding: 0;
+		text-align: left;
+		width: 100%;
+
+		&:focus-visible {
+			@include mixins.wpds-focus-ring;
+			outline-offset: wp-vars.$grid-unit-05;
+		}
+
+		svg {
+			flex-shrink: 0;
+		}
+
+		&[aria-expanded="true"] svg {
+			transform: rotate(180deg);
+		}
+
+		@media (prefers-reduced-motion: no-preference) {
+			svg {
+				transition: transform 0.1s ease-out;
+			}
+		}
+	}
+
+	&__panel-inner {
+		padding-top: wp-vars.$grid-unit-30;
+	}
+}

package/src/collapsible-group/types.ts

@@ -0,0 +1,22 @@
+import type { GapSize } from '@wordpress/theme';
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export type CollapsibleGroupProps = {
+	className?: string;
+	/** `Stack` gap either side of each divider, so items sit twice this far apart. */
+	gap?: GapSize;
+	/** Renders a lone item open and untitled, since it has nothing to collapse against. */
+	hideSingleTitle?: boolean;
+	/** Heading level for every item title, so the group shares one place in the outline. Defaults to the level inherited from an enclosing group, or 2. */
+	titleLevel?: HeadingLevel;
+	children?: React.ReactNode;
+};
+
+export type CollapsibleGroupItemProps = {
+	className?: string;
+	defaultOpen?: boolean;
+	/** Without a title there is no trigger, so the content renders permanently open. */
+	title?: string;
+	children?: React.ReactNode;
+};

package/src/drawer/README.md

@@ -10,8 +10,8 @@ the one part with no counterpart there.
 
 The parts hang off one exported object rather than the flat named exports the
 rest of this package uses. That is deliberate, to keep them recognisable against
-`@wordpress/ui`'s own `Drawer`, and not a pattern for the next compound
-component to copy.
+`@wordpress/ui`'s own `Drawer`. It is also the shape compound components in this
+package follow, `EmptyState` included.
 
 ```jsx
 import { Drawer } from 'newspack-components';

package/src/empty-state/README.md

@@ -0,0 +1,165 @@
+# EmptyState
+
+The "nothing here yet" treatment for a list screen or an onboarding view: an
+icon, a title, a short description, and usually one call to action.
+
+The API is compound: an `EmptyState.Root` and one subcomponent per slot. The
+parts hang off one exported object, as `Drawer`'s do.
+
+Root brings the layout its consumers used to hand-write, including the
+`data-start` and `data-end` attributes the `Grid` stylesheet matches on. The
+parts are composed from `Stack`, so every gap belongs to a stack rather than to
+a margin, and the component's own stylesheet covers only the icon disc and the
+type of the title and description.
+
+## Importing
+
+The package barrel and the component's own entry point both work:
+
+```jsx
+// The barrel.
+import { EmptyState } from 'newspack-components';
+
+// The component on its own, from newspack-plugin.
+import EmptyState from '../../packages/components/src/empty-state';
+```
+
+The by-path form above is newspack-plugin's, which compiles the monorepo source
+directly. newspack-newsletters resolves `newspack-components` to the built
+`dist/esm/index.js`, so its only per-component route is
+`newspack-components/dist/esm/empty-state`, which reaches past the package's
+public surface: `main` is the only declared entry and there is no `exports` map
+to make that path supported. Importing per component holds for one of the two
+consumers until the package declares one.
+
+Take the barrel where the bundle already pulls the package in wholesale, as the
+newsletters admin shell does. Import by path where a bundle should stay narrow:
+the barrel reaches `Page`, whose stylesheet carries a `:root` block of
+design-system token overrides, and that block then rides into every bundle that
+touches the barrel.
+
+One by-path import does not settle it, and today none of them do. The package
+declares no `sideEffects`, so a bundler cannot drop anything the barrel
+re-exports, and every newspack-plugin screen using `EmptyState` still imports
+`Button` or `Card` from the barrel on a neighbouring line. Until the package
+declares `sideEffects`, importing by path is the direction of travel rather than
+a saving already banked.
+
+## Usage
+
+```jsx
+import { __ } from '@wordpress/i18n';
+import { Button } from '@wordpress/components';
+import { envelope } from '@wordpress/icons';
+import { EmptyState } from 'newspack-components';
+
+<EmptyState.Root className={ EMPTY_STATE_CLASS }>
+	<EmptyState.Header
+		icon={ envelope }
+		title={ __( 'Get started with newsletters', 'newspack-newsletters' ) }
+		description={ __( 'Compose, schedule, and send newsletters to your subscribers.', 'newspack-newsletters' ) }
+	/>
+	<EmptyState.Actions>
+		<Button variant="primary" href={ addNewHref }>
+			{ __( 'Add Newsletter', 'newspack-newsletters' ) }
+		</Button>
+	</EmptyState.Actions>
+</EmptyState.Root>
+```
+
+Every slot except `Root` is optional, and anything else you pass to `Root`
+becomes a sibling of the header at the same 8-unit gap. A screen that offers
+choices rather than one action can drop a stack of cards in instead of
+`EmptyState.Actions`. Pass elements: `Root`'s stack keeps a lone string but drops
+one sitting beside an element, so wrap loose text in a `<p>`. The `Grid` margin
+reset reaches direct children only, so a `<p>` inside a slot keeps the browser's
+default block margin and you zero it where you use it. The component resets
+margins on the two elements it renders itself and stops there: a blanket reset on
+slot content would silently flatten a consumer's own stack of cards or prose, and
+the gaps this component owns all come from its stacks anyway.
+
+## Consumers own their wrappers
+
+The component does not position itself on the page, so each screen decides
+whether it needs a wrapper at all.
+
+Pass a class to `Root` when the styling targets the empty state itself. The
+newsletters screens do that, exporting the class from the shell rather than
+repeating the literal: the shell keys `:has()` off it to hide its header and
+hold the main region to 1006px, and both are rules about an empty state being
+on screen.
+
+Wrap `Root` in your own element when the wrapper is page layout that would
+still be there without an empty state. `institutions/onboarding.tsx` does that:
+`newspack-wizard__column` is the wizard's own column width, and the view
+would want it whatever it rendered.
+
+## Strict-empty only
+
+**Render this when the *unfiltered* collection is empty.** A search or filter
+that matches nothing keeps the DataViews "no results" treatment, which tells
+the reader their query was too narrow rather than that they have nothing.
+
+The component cannot enforce that: it never sees the collection. In the
+newsletters admin shell the rule lives in `isStrictlyEmpty`.
+
+## Actions take any button
+
+`EmptyState.Actions` renders whatever you give it, so each consumer keeps its
+own `Button`. newspack-newsletters passes the `@wordpress/components` one and
+newspack-plugin passes this package's.
+
+That is also why there is no CTA invariant. The component this replaced took a
+`ctaHref` / `ctaOnClick` pair and required exactly one, throwing in development.
+With a children slot there is no pair to check. A button that navigates takes
+`href`; one that opens something in place takes `onClick`.
+
+## `EmptyState.Root`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | — | The slots, plus any custom body. |
+| `className` | `string` | — | Merged onto the grid. |
+| `size` | `'default'` \| `'small'` | `'default'` | Read by `EmptyState.Header`. `small` suits an empty state standing in for a panel inside a card. |
+
+The grid always carries `newspack-empty-state`, and `className` lands there
+rather than on a wrapper, because consumers key off both. Inside it, the stack
+carries `newspack-empty-state__stack`, sits in columns two to four, and is
+capped at `--wpds-dimension-surface-width-lg` so it cannot sprawl in a wider
+container.
+
+## `EmptyState.Header`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Merged onto `newspack-empty-state__header`. |
+| `description` | `React.ReactNode` | — | One or two sentences on what would fill the screen. |
+| `heading` | `1`–`6` | `3` when small, `2` otherwise | HTML heading level. |
+| `icon` | `JSX.Element` | — | From `@wordpress/icons` or `newspack-icons`. |
+| `title` | `string` | — | **Required.** |
+
+`heading` follows `size` by default but stays yours to set. Heading level is a
+document-outline concern rather than a visual one, so a headerless screen that
+needs this to be its `h1` passes `heading={ 1 }`.
+
+## `EmptyState.Actions`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | — | Usually one primary button. |
+| `className` | `string` | — | Merged onto the stack. |
+| `orientation` | `'row'` \| `'column'` | `'row'` | `column` stacks the actions, for a button above a link or an explanatory note. |
+| `gap` | `GapSize` | `'sm'` | Gap between actions, on the design-system scale (`xs` to `3xl`). |
+
+A centred stack, carrying `newspack-empty-state__actions`. A row wraps rather
+than overflowing, since the empty state only gets half the grid on a wide screen.
+With one action, prefer a single primary button: an empty state asking for two
+decisions at once is usually a sign the screen needs an onboarding view instead.
+
+## Outside the Root
+
+`EmptyState.Header` and `EmptyState.Actions` both throw "EmptyState
+subcomponents must be rendered inside EmptyState.Root." when rendered anywhere
+else, in development only. In production `Header` falls back to the default
+size and `Actions` renders as it would inside a Root, so a misplaced part never
+blanks an admin screen.

package/src/empty-state/actions.tsx

@@ -0,0 +1,37 @@
+/**
+ * WordPress dependencies.
+ */
+import { Stack } from '@wordpress/ui';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import { useEmptyStateInvariant } from './context';
+import type { EmptyStateActionsProps } from './types';
+
+const Actions = ( { orientation = 'row', gap = 'sm', className, children }: EmptyStateActionsProps ) => {
+	useEmptyStateInvariant();
+
+	const isColumn = orientation === 'column';
+
+	// Rows wrap: the empty state only gets half the grid above 1054px.
+	return (
+		<Stack
+			direction={ isColumn ? 'column' : 'row' }
+			align="center"
+			justify="center"
+			gap={ gap }
+			wrap={ isColumn ? undefined : 'wrap' }
+			className={ classnames( 'newspack-empty-state__actions', className ) }
+		>
+			{ children }
+		</Stack>
+	);
+};
+
+export default Actions;

package/src/empty-state/context.ts

@@ -0,0 +1,40 @@
+/**
+ * WordPress dependencies.
+ */
+import { createContext, useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies.
+ */
+import type { EmptyStateSize } from './types';
+
+type EmptyStateContextValue = {
+	size: EmptyStateSize;
+};
+
+export const EmptyStateContext = createContext< EmptyStateContextValue | null >( null );
+
+const FALLBACK_CONTEXT: EmptyStateContextValue = { size: 'default' };
+
+export const useEmptyStateContext = (): EmptyStateContextValue => {
+	const context = useContext( EmptyStateContext );
+	if ( ! context && process.env.NODE_ENV !== 'production' ) {
+		throw new Error( 'EmptyState subcomponents must be rendered inside EmptyState.Root.' );
+	}
+	return context ?? FALLBACK_CONTEXT;
+};
+
+/**
+ * Assert placement inside a `Root` without depending on the value.
+ *
+ * For subcomponents that read nothing from context. Both hooks throw in
+ * development so the mistake surfaces while it is cheap, and neither throws in
+ * production, because a stray subcomponent should not blank an admin screen
+ * over a layout hint.
+ */
+export const useEmptyStateInvariant = (): void => {
+	const context = useContext( EmptyStateContext );
+	if ( ! context && process.env.NODE_ENV !== 'production' ) {
+		throw new Error( 'EmptyState subcomponents must be rendered inside EmptyState.Root.' );
+	}
+};

package/src/empty-state/header.tsx

@@ -0,0 +1,48 @@
+/**
+ * WordPress dependencies.
+ */
+import { Icon } from '@wordpress/icons';
+import { Stack } from '@wordpress/ui';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import { useEmptyStateContext } from './context';
+import type { EmptyStateHeaderProps } from './types';
+
+const Header = ( { icon, title, description, heading, className }: EmptyStateHeaderProps ) => {
+	const { size } = useEmptyStateContext();
+	const isSmall = size === 'small';
+
+	// Heading level is a document-outline concern, so the size only sets a default.
+	const level = heading ?? ( isSmall ? 3 : 2 );
+	const HeadingTag = `h${ level }` as keyof JSX.IntrinsicElements;
+
+	// Two stacks so each gap belongs to exactly one of them: the inner one spaces the
+	// icon from the title, the outer one the title from the description.
+	return (
+		<Stack
+			direction="column"
+			align="center"
+			gap="sm"
+			className={ classnames( 'newspack-empty-state__header', isSmall && 'newspack-empty-state__header--small', className ) }
+		>
+			<Stack direction="column" align="center" gap={ isSmall ? 'md' : 'lg' }>
+				{ icon && (
+					<div className="newspack-empty-state__icon">
+						<Icon icon={ icon } size={ isSmall ? 24 : 48 } />
+					</div>
+				) }
+				<HeadingTag className="newspack-empty-state__title">{ title }</HeadingTag>
+			</Stack>
+			{ description && <p className="newspack-empty-state__description">{ description }</p> }
+		</Stack>
+	);
+};
+
+export default Header;