newspack-components 4.7.0 → 4.8.0

package/src/empty-state/index.test.js

@@ -0,0 +1,247 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import EmptyState from '.';
+
+describe( 'EmptyState.Root', () => {
+	it( 'renders the four-column grid spine', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<p>body</p>
+			</EmptyState.Root>
+		);
+		const grid = container.querySelector( '.newspack-empty-state' );
+		expect( grid ).toHaveClass( 'newspack-grid' );
+		expect( grid ).toHaveClass( 'newspack-grid__columns-4' );
+		expect( grid ).toHaveClass( 'newspack-grid--no-margin' );
+	} );
+
+	// grid/style.scss matches on these attributes, so they are a contract.
+	it( 'gives the inner stack the data attributes the Grid stylesheet matches on', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<p>body</p>
+			</EmptyState.Root>
+		);
+		const stack = container.querySelector( '.newspack-empty-state' ).firstElementChild;
+		expect( stack ).toHaveAttribute( 'data-start', '2' );
+		expect( stack ).toHaveAttribute( 'data-end', '4' );
+	} );
+
+	// The width cap hangs off this class, so losing it silently widens the block.
+	it( 'carries the stack class hook', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<p>body</p>
+			</EmptyState.Root>
+		);
+		const stack = container.querySelector( '.newspack-empty-state' ).firstElementChild;
+		expect( stack ).toHaveClass( 'newspack-empty-state__stack' );
+		expect( stack ).toHaveStyle( { gap: 'var(--wpds-dimension-gap-2xl, 32px)' } );
+	} );
+
+	// Consumers key `:has()` selectors off this class, so losing it changes their
+	// layout without failing anything.
+	it( 'merges className onto the grid', () => {
+		const { container } = render(
+			<EmptyState.Root className="consumer-empty-state">
+				<p>body</p>
+			</EmptyState.Root>
+		);
+		expect( container.querySelector( '.newspack-empty-state' ) ).toHaveClass( 'consumer-empty-state' );
+	} );
+
+	// Elements, not a bare string: the stack keeps a lone string but drops one sitting
+	// beside an element.
+	it( 'renders its children', () => {
+		render(
+			<EmptyState.Root>
+				<p>body</p>
+			</EmptyState.Root>
+		);
+		expect( screen.getByText( 'body' ) ).toBeInTheDocument();
+	} );
+} );
+
+describe( 'EmptyState.Header', () => {
+	it( 'renders the title and description in the header', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<EmptyState.Header title="Get started with newsletters" description="Compose and send." />
+			</EmptyState.Root>
+		);
+		expect( container.querySelector( '.newspack-empty-state__title' ) ).toHaveTextContent( 'Get started with newsletters' );
+		expect( container.querySelector( '.newspack-empty-state__description' ) ).toHaveTextContent( 'Compose and send.' );
+	} );
+
+	// Spacing comes from the stacks, so a margin creeping back onto the heading or
+	// paragraph would silently widen every gap.
+	it( 'spaces the header from its stacks rather than from margins', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<EmptyState.Header title="Get started with newsletters" description="Compose and send." />
+			</EmptyState.Root>
+		);
+		const header = container.querySelector( '.newspack-empty-state__header' );
+		expect( header ).toHaveStyle( { flexDirection: 'column', alignItems: 'center', gap: 'var(--wpds-dimension-gap-sm, 8px)' } );
+		expect( header.firstElementChild ).toHaveStyle( {
+			flexDirection: 'column',
+			alignItems: 'center',
+			gap: 'var(--wpds-dimension-gap-lg, 16px)',
+		} );
+	} );
+
+	it( 'wraps the icon in the disc', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<EmptyState.Header title="Get started with newsletters" icon={ <svg /> } />
+			</EmptyState.Root>
+		);
+		expect( container.querySelector( '.newspack-empty-state__icon svg' ) ).toBeInTheDocument();
+	} );
+
+	it( 'omits the description and the icon when they are not given', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<EmptyState.Header title="Get started with newsletters" />
+			</EmptyState.Root>
+		);
+		expect( container.querySelector( '.newspack-empty-state__description' ) ).not.toBeInTheDocument();
+		expect( container.querySelector( '.newspack-empty-state__icon' ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'renders an h2 and a 48px icon at the default size', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<EmptyState.Header title="Get started with newsletters" icon={ <svg /> } />
+			</EmptyState.Root>
+		);
+		expect( screen.getByRole( 'heading', { level: 2, name: 'Get started with newsletters' } ) ).toBeInTheDocument();
+		expect( container.querySelector( '.newspack-empty-state__header--small' ) ).not.toBeInTheDocument();
+		expect( container.querySelector( '.newspack-empty-state__icon svg' ) ).toHaveAttribute( 'width', '48' );
+	} );
+
+	it( 'drops to an h3, the small modifier and a 24px icon when the root is small', () => {
+		const { container } = render(
+			<EmptyState.Root size="small">
+				<EmptyState.Header title="No products match this rule" icon={ <svg /> } />
+			</EmptyState.Root>
+		);
+		expect( container.querySelector( '.newspack-empty-state__header--small' ) ).toBeInTheDocument();
+		expect( screen.getByRole( 'heading', { level: 3, name: 'No products match this rule' } ) ).toBeInTheDocument();
+		expect( container.querySelector( '.newspack-empty-state__icon svg' ) ).toHaveAttribute( 'width', '24' );
+		expect( container.querySelector( '.newspack-empty-state__header' ).firstElementChild ).toHaveStyle( {
+			gap: 'var(--wpds-dimension-gap-md, 12px)',
+		} );
+	} );
+
+	it( 'lets heading override the level the size implies', () => {
+		render(
+			<EmptyState.Root size="small">
+				<EmptyState.Header title="No products match this rule" heading={ 1 } />
+			</EmptyState.Root>
+		);
+		expect( screen.getByRole( 'heading', { level: 1, name: 'No products match this rule' } ) ).toBeInTheDocument();
+	} );
+
+	it( 'carries its own class hook alongside any className', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<EmptyState.Header title="Get started with newsletters" className="consumer-header" />
+			</EmptyState.Root>
+		);
+		const header = container.querySelector( '.newspack-empty-state__header' );
+		expect( header ).toBeInTheDocument();
+		expect( header ).toHaveClass( 'consumer-header' );
+	} );
+
+	it( 'throws outside Root in development', () => {
+		const consoleError = jest.spyOn( console, 'error' ).mockImplementation( () => {} );
+		try {
+			expect( () => render( <EmptyState.Header title="Orphan" /> ) ).toThrow(
+				'EmptyState subcomponents must be rendered inside EmptyState.Root.'
+			);
+		} finally {
+			consoleError.mockRestore();
+		}
+	} );
+
+	// Header is the visible half, so a misplaced one blanking an admin screen costs more
+	// than the default size it falls back to.
+	it( 'falls back to the default size outside Root in production', () => {
+		const previous = process.env.NODE_ENV;
+		process.env.NODE_ENV = 'production';
+		try {
+			const { container } = render( <EmptyState.Header title="Orphan" icon={ <svg /> } /> );
+			expect( screen.getByRole( 'heading', { level: 2, name: 'Orphan' } ) ).toBeInTheDocument();
+			expect( container.querySelector( '.newspack-empty-state__header--small' ) ).not.toBeInTheDocument();
+			expect( container.querySelector( '.newspack-empty-state__icon svg' ) ).toHaveAttribute( 'width', '48' );
+		} finally {
+			process.env.NODE_ENV = previous;
+		}
+	} );
+} );
+
+describe( 'EmptyState.Actions', () => {
+	it( 'renders its children in a centred row', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<EmptyState.Actions>
+					<button type="button">Add Newsletter</button>
+				</EmptyState.Actions>
+			</EmptyState.Root>
+		);
+		expect( container.querySelector( '.newspack-empty-state__actions' ) ).toBeInTheDocument();
+		expect( container.querySelector( '.newspack-empty-state__actions' ) ).toHaveStyle( {
+			justifyContent: 'center',
+			gap: 'var(--wpds-dimension-gap-sm, 8px)',
+		} );
+		expect( screen.getByRole( 'button', { name: 'Add Newsletter' } ) ).toBeInTheDocument();
+	} );
+
+	it( 'stacks into a column while keeping the hook class', () => {
+		const { container } = render(
+			<EmptyState.Root>
+				<EmptyState.Actions orientation="column">
+					<button type="button">Set up Audience Management</button>
+					<a href="https://example.com">Learn more</a>
+				</EmptyState.Actions>
+			</EmptyState.Root>
+		);
+		const actions = container.querySelector( '.newspack-empty-state__actions' );
+		expect( actions ).toBeInTheDocument();
+		expect( actions ).toHaveStyle( { flexDirection: 'column' } );
+		// A stack's own default is `stretch`, so without align="center" the buttons
+		// would go full-bleed while flexDirection stayed correct.
+		expect( actions ).toHaveStyle( { alignItems: 'center' } );
+	} );
+
+	it( 'throws outside Root in development', () => {
+		const consoleError = jest.spyOn( console, 'error' ).mockImplementation( () => {} );
+		try {
+			expect( () => render( <EmptyState.Actions>x</EmptyState.Actions> ) ).toThrow(
+				'EmptyState subcomponents must be rendered inside EmptyState.Root.'
+			);
+		} finally {
+			consoleError.mockRestore();
+		}
+	} );
+
+	// Actions reads nothing from context, so the invariant is a development aid. A
+	// stray one must not blank an admin screen in production over a layout hint.
+	it( 'renders outside Root in production', () => {
+		const previous = process.env.NODE_ENV;
+		process.env.NODE_ENV = 'production';
+		try {
+			const { container } = render( <EmptyState.Actions>x</EmptyState.Actions> );
+			expect( container.querySelector( '.newspack-empty-state__actions' ) ).toBeInTheDocument();
+		} finally {
+			process.env.NODE_ENV = previous;
+		}
+	} );
+} );

package/src/empty-state/index.tsx

@@ -0,0 +1,22 @@
+/**
+ * EmptyState
+ */
+
+/**
+ * Internal dependencies.
+ */
+import Actions from './actions';
+import Header from './header';
+import Root from './root';
+
+export const EmptyState = {
+	Root,
+	Header,
+	Actions,
+};
+
+Object.entries( EmptyState ).forEach( ( [ name, part ] ) => {
+	( part as { displayName?: string } ).displayName = `EmptyState.${ name }`;
+} );
+
+export default EmptyState;

package/src/empty-state/root.tsx

@@ -0,0 +1,39 @@
+/**
+ * WordPress dependencies.
+ */
+import { useMemo } from '@wordpress/element';
+import { Stack } from '@wordpress/ui';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import Grid from '../grid';
+import { EmptyStateContext } from './context';
+import type { EmptyStateRootProps } from './types';
+import './style.scss';
+
+// Positions the stack in columns 2 to 4. `data-` attributes because that is the form
+// grid/style.scss standardised on, after prop filtering was found to drop a bare `end`
+// before it reached the DOM. That file carries the full note.
+const gridColumn = { 'data-start': '2', 'data-end': '4' };
+
+const Root = ( { size = 'default', className, children }: EmptyStateRootProps ) => {
+	const context = useMemo( () => ( { size } ), [ size ] );
+
+	return (
+		<EmptyStateContext.Provider value={ context }>
+			<Grid className={ classnames( 'newspack-empty-state', className ) } columns={ 4 } noMargin>
+				<Stack className="newspack-empty-state__stack" direction="column" gap="2xl" { ...gridColumn }>
+					{ children }
+				</Stack>
+			</Grid>
+		</EmptyStateContext.Provider>
+	);
+};
+
+export default Root;

package/src/empty-state/style.scss

@@ -0,0 +1,51 @@
+@use "~@wordpress/base-styles/colors" as wp-colors;
+@use "~@wordpress/base-styles/mixins" as wp-mixins;
+@use "~@wordpress/base-styles/variables" as wp-vars;
+@use "../../../colors/colors.module" as np-colors;
+
+.newspack-empty-state {
+	&__stack {
+		margin-inline: auto;
+		max-width: var(--wpds-dimension-surface-width-lg, 560px);
+	}
+
+	&__header {
+		text-align: center;
+		text-wrap: balance;
+	}
+
+	&__icon {
+		background-color: var(--wp-admin-theme-color-lighter-10, #{np-colors.$primary-000});
+		border-radius: 100%;
+		display: grid;
+		height: wp-vars.$grid-unit-50 * 2;
+		place-items: center;
+		width: wp-vars.$grid-unit-50 * 2;
+
+		svg {
+			fill: var(--wp-admin-theme-color, #{np-colors.$primary-600});
+		}
+	}
+
+	&__title {
+		@include wp-mixins.heading-x-large();
+		color: var(--wpds-color-foreground-content-neutral, #{wp-colors.$gray-900});
+		margin: 0;
+	}
+
+	&__description {
+		color: var(--wpds-color-foreground-content-neutral-weak, #{wp-colors.$gray-700});
+		margin: 0;
+	}
+
+	&__header--small {
+		.newspack-empty-state__icon {
+			height: wp-vars.$grid-unit-50;
+			width: wp-vars.$grid-unit-50;
+		}
+
+		.newspack-empty-state__title {
+			@include wp-mixins.heading-large();
+		}
+	}
+}

package/src/empty-state/types.ts

@@ -0,0 +1,33 @@
+import type { GapSize } from '@wordpress/theme';
+
+export type EmptyStateSize = 'default' | 'small';
+
+export type EmptyStateActionsOrientation = 'row' | 'column';
+
+export type EmptyStateRootProps = {
+	/** Read by `EmptyState.Header` through context. */
+	size?: EmptyStateSize;
+	/** Merged onto the grid, which is the element consumers' `:has()` selectors look for. */
+	className?: string;
+	children?: React.ReactNode;
+};
+
+export type EmptyStateHeaderProps = {
+	icon?: JSX.Element;
+	title: string;
+	description?: React.ReactNode;
+	/** Defaults to 3 when the root is small, 2 otherwise. */
+	heading?: 1 | 2 | 3 | 4 | 5 | 6;
+	/** Merged onto `newspack-empty-state__header`. */
+	className?: string;
+};
+
+export type EmptyStateActionsProps = {
+	/** `column` stacks the actions instead, for a button above a link or a note. */
+	orientation?: EmptyStateActionsOrientation;
+	/** Gap between actions, on the design-system scale. */
+	gap?: GapSize;
+	/** Merged onto the stack. */
+	className?: string;
+	children?: React.ReactNode;
+};

package/src/index.js

@@ -1,9 +1,7 @@
-export { default as Accordion, AccordionPanel } from './accordion';
 export { default as ActionCard } from './action-card';
 export { default as AutocompleteTokenField } from './autocomplete-tokenfield';
 export { default as AutocompleteWithSuggestions } from './autocomplete-with-suggestions';
 export { default as AutocompleteWithLatestPosts } from './autocomplete-with-latest-posts';
-export { default as Badge } from './badge';
 export { default as Breadcrumbs } from './breadcrumbs';
 export { default as Button } from './button';
 export { default as BoxContrast } from './box-contrast';
@@ -14,12 +12,14 @@ export { default as CardSettingsGroup } from './card-settings-group';
 export { default as CardSortableList } from './card-sortable-list';
 export { default as IntegrationIcon } from './integration-icon';
 export { default as CategoryAutocomplete } from './category-autocomplete';
+export { default as CollapsibleGroup } from './collapsible-group';
 export { default as ColorPicker } from './color-picker';
 export { default as ConfirmDialog } from './confirm-dialog';
 export { default as CustomSelectControl } from './custom-select-control';
 export { default as DataViews } from './dataviews';
 export { default as Divider } from './divider';
 export { default as Drawer } from './drawer';
+export { default as EmptyState } from './empty-state';
 export { default as FormTokenField } from './form-token-field';
 export { default as Footer } from './footer';
 export { default as Handoff } from './handoff';
@@ -42,6 +42,8 @@ export { default as RadioControl } from './radio-control';
 export { default as SectionHeader } from './section-header';
 export { default as SelectControl } from './select-control';
 export { default as Settings } from './settings';
+export { default as StatCard, STAT_CARD_NULL_GLYPH } from './stat-card';
+export { default as StatusIndicator } from './status-indicator';
 export { default as StepsList } from './steps-list';
 export { default as StepsListItem } from './steps-list-item';
 export { default as StyleCard } from './style-card';

package/src/info-button/README.md

@@ -0,0 +1,115 @@
+# InfoButton
+
+An icon button that reveals supplementary context on hover, tap or activation.
+It renders nothing but the button and its popup; most often it is placed next to
+a label, explaining the setting beside it.
+
+```jsx
+import { InfoButton } from 'newspack-components';
+
+<InfoButton description={ __( 'Number of articles read in the last 30 day period.', 'newspack-plugin' ) } />
+```
+
+The component imports its own stylesheet, so the barrel ships the CSS with it.
+There is nothing separate to import.
+
+It carries no inline margin, so the row it sits in owns the spacing beside it.
+In a flex or grid row that is the row's own `gap`; anywhere else the caller sets
+it.
+
+Vertically it is a 24px control, `$button-size-small`, and it makes no assumption
+about the line it lands on. Beside text on a shorter line it grows the row unless
+the row pulls it back, which is the host's call rather than the component's: a row
+that is happy at 24px needs nothing. `StatCard.Label` and `SettingsSection` both
+trim it to the 20px line their text sits on, so a label carrying one stays level
+with a label without.
+
+## What belongs in it
+
+**Supplementary context only.** Anything a reader needs in order to use the
+control belongs in visible help text beside it, not behind an affordance they
+have to find first. The design system stops short of this: it only rules out
+hiding an important description behind a *tooltip*, and offers a popover as the
+alternative when space is tight. The stricter line is ours, not the library's.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `description` | `string` | — | The context to reveal. The whole component renders nothing without it. |
+| `className` | `string` | — | Additional CSS class on the trigger. |
+| `triggerLabel` | `string` | `'More information'` | Accessible name for the trigger. |
+
+Unrecognised props pass through to the trigger, so `id`, `data-*` and event
+handlers all land on the button, and a `ref` reaches the button itself. An
+`aria-label` names the popup as well as the trigger, so the two never disagree.
+
+## Name each one for its setting
+
+**Pass `triggerLabel` whenever a screen holds more than one.** The default name
+is the same for every instance, so a screen with a dozen of them gives a screen
+reader user a dozen identical entries in its controls list with nothing to tell
+them apart.
+
+```jsx
+<InfoButton
+	description={ criteria.description }
+	triggerLabel={ sprintf(
+		// translators: %s is the name of the setting being explained.
+		__( 'More information about %s', 'newspack-plugin' ),
+		criteria.name
+	) }
+/>
+```
+
+**Pass it in the calling plugin's own text domain.** The samples here say
+`newspack-plugin` because that catalogue picks the package's strings up through
+the symlink at `plugins/newspack-plugin/packages/components`. Everywhere else
+the package resolves through `node_modules`, which `make-pot` skips, so a
+`newspack-plugin`-domained string passed in from another plugin ships
+untranslated.
+
+## Built on Popover, not Tooltip
+
+It looks like a tooltip and is not one. `@wordpress/ui` documents its `Tooltip`
+as visual-only, not exposed to assistive technology, and unavailable on touch
+devices, so it "should not be used for infotips, descriptions, or dynamic status
+messages". Both components gate hover on a mouse-like pointer, but only a
+popover trigger also opens on press, which is what makes it reachable by tap.
+
+The consequences, all of which a tooltip would lose:
+
+- Hover opens it on a desktop after 200ms, and a 200ms close delay means
+  overshooting the 24px trigger does not dismiss it instantly.
+- A tap opens it on a touch device.
+- Escape closes it and returns focus to the trigger.
+- The popup carries the context on its own `aria-describedby` rather than
+  folding it into the button's accessible name, so the trigger keeps a short
+  name of its own.
+
+The library marks `Popover` "use with caution" next to `@wordpress/components`,
+pending a review of overlay compatibility. The portal answers that by opting into
+the shared overlay slot, a body-level container the library reserves above the
+older z-index map, so the popup clears a core popover instead of tying with it.
+Outside a WordPress screen the slot is absent and the stylesheet's own z-index
+applies.
+
+`Popover.Popup` is rendered with `variant="unstyled"`, which skips the design
+system's own light card surface so the stylesheet can reproduce a tooltip's
+appearance instead. That is also why the popup carries no enter animation: the
+motion layer ships with the default surface.
+
+## Accessibility
+
+The trigger is a native `<button>` with no action of its own. Activating it
+opens the popup and moves focus into it, so the description is the next thing a
+keyboard user reaches.
+
+The popup is a `role="dialog"` named by a visually hidden `Popover.Title`. The
+title repeats the trigger's name, which is what the design system's own infotip
+reference does, and the description carries the prose.
+
+The description keeps the design system's body type rather than a tooltip's
+smaller size, because `Popover.Description` renders a `Text` and does not expose
+its variant. At the 320px width cap, a long description wraps to about four
+lines.