newspack-components 4.7.0 → 4.8.0

package/src/stat-card/index.tsx

@@ -0,0 +1,48 @@
+/**
+ * StatCard
+ */
+
+/**
+ * Internal dependencies.
+ */
+import Body from './body';
+import Delta from './delta';
+import Footer from './footer';
+import Label from './label';
+import Root from './root';
+import Secondary from './secondary';
+import Value from './value';
+
+export { STAT_CARD_NULL_GLYPH } from './constants';
+export type {
+	StatCardBodyProps,
+	StatCardDeltaDirection,
+	StatCardDeltaProps,
+	StatCardDeltaTone,
+	StatCardFooterProps,
+	StatCardHeadingLevel,
+	StatCardLabelProps,
+	StatCardLabels,
+	StatCardRootProps,
+	StatCardSecondaryProps,
+	StatCardValue,
+	StatCardValueProps,
+	StatCardValueVariant,
+} from './types';
+
+// Compound components here export one namespace object, as Drawer does.
+export const StatCard = {
+	Root,
+	Label,
+	Body,
+	Value,
+	Delta,
+	Secondary,
+	Footer,
+};
+
+Object.entries( StatCard ).forEach( ( [ name, part ] ) => {
+	( part as { displayName?: string } ).displayName = `StatCard.${ name }`;
+} );
+
+export default StatCard;

package/src/stat-card/label.tsx

@@ -0,0 +1,61 @@
+/**
+ * WordPress dependencies.
+ */
+import { forwardRef, useEffect } from '@wordpress/element';
+import { Stack } from '@wordpress/ui';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import { useStatCardContext } from './context';
+import type { StatCardHeadingLevel, StatCardLabelProps } from './types';
+
+const headings = {
+	2: 'h2',
+	3: 'h3',
+	4: 'h4',
+	5: 'h5',
+	6: 'h6',
+} as const;
+
+const Label = forwardRef< HTMLDivElement, StatCardLabelProps >( function Label( { suffix, heading, className, children, ...props }, ref ) {
+	const context = useStatCardContext();
+	const level = ( heading ?? context.heading ) as StatCardHeadingLevel;
+	// Consumers are largely untyped JS, where an out-of-range level would
+	// otherwise render an <h7>, which carries no heading role at all.
+	const Heading = headings[ level ] || headings[ 3 ];
+
+	useEffect( () => {
+		if ( 'production' === process.env.NODE_ENV || headings[ level ] ) {
+			return;
+		}
+		// eslint-disable-next-line no-console
+		console.warn(
+			`StatCard: unknown heading level "${ level }", falling back to 3. Set \`heading\` on StatCard.Root or StatCard.Label to one of ${ Object.keys(
+				headings
+			).join( ', ' ) }.`
+		);
+	}, [ level ] );
+
+	return (
+		<Stack
+			ref={ ref }
+			direction="row"
+			align="flex-start"
+			justify="space-between"
+			gap="sm"
+			className={ classnames( 'newspack-stat-card__label', className ) }
+			{ ...props }
+		>
+			<Heading className="newspack-stat-card__label-text">{ children }</Heading>
+			{ suffix }
+		</Stack>
+	);
+} );
+
+export default Label;

package/src/stat-card/root.tsx

@@ -0,0 +1,40 @@
+/**
+ * WordPress dependencies.
+ */
+import { forwardRef, useMemo } from '@wordpress/element';
+// Aliased: this package exports a different `Card` of its own.
+import { Card as UICard, Stack } from '@wordpress/ui';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import { resolveStatCardLabels, StatCardContext } from './context';
+import type { StatCardRootProps } from './types';
+import './style.scss';
+
+const Root = forwardRef< HTMLDivElement, StatCardRootProps >( function Root( { heading = 3, labels, className, children, ...props }, ref ) {
+	// Keyed on the strings rather than the object: a caller writing `labels` inline
+	// hands over a fresh object each render, which would defeat the memo entirely.
+	const { notApplicable, up, down } = labels ?? {};
+	const context = useMemo(
+		() => ( { heading, labels: resolveStatCardLabels( { notApplicable, up, down } ) } ),
+		[ heading, notApplicable, up, down ]
+	);
+
+	return (
+		<StatCardContext.Provider value={ context }>
+			<UICard.Root ref={ ref } className={ classnames( 'newspack-stat-card', className ) } { ...props }>
+				<UICard.Content render={ <Stack direction="column" gap="sm" /> } className="newspack-stat-card__content">
+					{ children }
+				</UICard.Content>
+			</UICard.Root>
+		</StatCardContext.Provider>
+	);
+} );
+
+export default Root;

package/src/stat-card/secondary.tsx

@@ -0,0 +1,27 @@
+/**
+ * WordPress dependencies.
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import { useStatCardContext } from './context';
+import type { StatCardSecondaryProps } from './types';
+
+const Secondary = forwardRef< HTMLDivElement, StatCardSecondaryProps >( function Secondary( { className, children, ...props }, ref ) {
+	useStatCardContext();
+
+	return (
+		<div ref={ ref } className={ classnames( 'newspack-stat-card__secondary', className ) } { ...props }>
+			{ children }
+		</div>
+	);
+} );
+
+export default Secondary;

package/src/stat-card/style.scss

@@ -0,0 +1,89 @@
+@use "~@wordpress/base-styles/colors" as wp-colors;
+@use "~@wordpress/base-styles/variables" as wp-vars;
+@use "~@wordpress/base-styles/mixins" as wp-mixins;
+@use "../../../colors/colors.module" as colors;
+@use "../variables" as np-vars;
+
+$stat-card-min-height: wp-vars.$grid-unit * 21;
+
+.newspack-stat-card {
+	--wp-admin-theme-color: #{colors.$primary-600};
+	--wp-admin-theme-color--rgb: #{colors.$primary-600--rgb};
+	--wp-admin-theme-color-darker-10: #{colors.$primary-700};
+	--wp-admin-theme-color-darker-10--rgb: #{colors.$primary-700--rgb};
+	--wp-admin-theme-color-darker-20: #{colors.$primary-800};
+	--wp-admin-theme-color-darker-20--rgb: #{colors.$primary-800--rgb};
+	--wp-admin-theme-color-lighter-10: #{colors.$primary-000};
+	--wp-admin-theme-color-lighter-10--rgb: #{colors.$primary-000--rgb};
+
+	container-type: inline-size;
+	display: flex;
+	flex-direction: column;
+	min-height: $stat-card-min-height;
+
+	&__content {
+		flex: 1;
+	}
+
+	&__label .newspack-info-button {
+		margin-block: calc((#{wp-vars.$font-line-height-small} - #{wp-vars.$button-size-small}) / 2);
+	}
+
+	&__label-text {
+		@include wp-mixins.heading-large();
+		color: wp-colors.$gray-900;
+		margin: 0;
+	}
+
+	&__body {
+		flex: 1;
+	}
+
+	&__value {
+		color: var(--wp-admin-theme-color);
+		font-size: np-vars.$font-size-3x-large;
+		font-size: clamp(#{wp-vars.$font-size-x-large}, 14cqi, #{np-vars.$font-size-3x-large});
+		font-variant-numeric: tabular-nums;
+		font-weight: wp-vars.$font-weight-medium;
+		line-height: np-vars.$font-line-height-3x-large;
+
+		&--text {
+			font-size: wp-vars.$font-size-x-large;
+			line-height: wp-vars.$font-line-height-x-large;
+		}
+	}
+
+	&__delta {
+		@include wp-mixins.heading-medium();
+		color: wp-colors.$gray-700;
+
+		&--positive {
+			color: colors.$success-600;
+		}
+
+		&--negative {
+			color: colors.$error-600;
+		}
+	}
+
+	&__action,
+	&__action.components-button {
+		font-size: wp-vars.$helptext-font-size;
+		line-height: wp-vars.$font-line-height-x-small;
+	}
+
+	&__secondary {
+		@include wp-mixins.heading-medium();
+		color: var(--wp-admin-theme-color);
+		margin: 0;
+		text-wrap: balance;
+	}
+
+	&__description {
+		color: wp-colors.$gray-700;
+		font-size: wp-vars.$helptext-font-size;
+		line-height: wp-vars.$font-line-height-x-small;
+		margin: 0;
+		text-wrap: balance;
+	}
+}

package/src/stat-card/types.ts

@@ -0,0 +1,84 @@
+export type StatCardHeadingLevel = 2 | 3 | 4 | 5 | 6;
+
+export type StatCardValueVariant = 'figure' | 'text';
+
+/** Pre-formatted by the caller. Null, undefined and a blank string all render the null glyph. */
+export type StatCardValue = string | number | null | undefined;
+
+type DivProps = Omit< React.ComponentPropsWithoutRef< 'div' >, 'children' >;
+
+type SpanProps = Omit< React.ComponentPropsWithoutRef< 'span' >, 'children' >;
+
+/** The strings the card speaks for itself, when the caller has supplied none of its own. */
+export type StatCardLabels = {
+	/** Names the null glyph. */
+	notApplicable: string;
+	/** Spoken for an up arrow. */
+	up: string;
+	/** Spoken for a down arrow. */
+	down: string;
+};
+
+export type StatCardRootProps = DivProps & {
+	/** Heading level for `StatCard.Label`, read through context. */
+	heading?: StatCardHeadingLevel;
+	/** Replaces the spoken defaults for every card underneath, e.g. from a consumer's own text domain. */
+	labels?: Partial< StatCardLabels >;
+	/** Merged onto the card, which is the element the hero scale queries. */
+	className?: string;
+	children?: React.ReactNode;
+};
+
+export type StatCardLabelProps = DivProps & {
+	/** Rendered beside the heading rather than inside it, so a control here stays out of the document outline. */
+	suffix?: React.ReactNode;
+	/** Overrides the level set on `StatCard.Root`. */
+	heading?: StatCardHeadingLevel;
+	/** Merged onto the label row, not the heading. */
+	className?: string;
+	children?: React.ReactNode;
+};
+
+export type StatCardBodyProps = DivProps & {
+	className?: string;
+	children?: React.ReactNode;
+};
+
+export type StatCardValueProps = SpanProps & {
+	value: StatCardValue;
+	/** Spoken instead of the visible value, whose meaning may rest on punctuation. */
+	valueLabel?: string;
+	/** `text` drops the hero scale, for a phrase standing in for a number. */
+	variant?: StatCardValueVariant;
+	/** Rendered in a row beside the figure, e.g. a `StatCard.Delta`. */
+	suffix?: React.ReactNode;
+	className?: string;
+};
+
+export type StatCardDeltaDirection = 'up' | 'down';
+
+export type StatCardDeltaTone = 'positive' | 'negative' | 'neutral';
+
+export type StatCardDeltaProps = SpanProps & {
+	/** Which arrow to show. Says nothing about whether the change is good. */
+	direction: StatCardDeltaDirection;
+	/** Which colour to use. The caller decides, because a rise is not always good news. */
+	tone?: StatCardDeltaTone;
+	/** Spoken in place of "Up" or "Down". */
+	directionLabel?: string;
+	/** Spoken in place of the whole delta, arrow and change together. Wins over `directionLabel`. */
+	label?: string;
+	className?: string;
+	/** The change, pre-formatted. Must be non-interactive: `label` hides it from assistive technology. */
+	children?: React.ReactNode;
+};
+
+export type StatCardSecondaryProps = DivProps & {
+	className?: string;
+	children?: React.ReactNode;
+};
+
+export type StatCardFooterProps = DivProps & {
+	className?: string;
+	children?: React.ReactNode;
+};

package/src/stat-card/value.tsx

@@ -0,0 +1,72 @@
+/**
+ * WordPress dependencies.
+ */
+import { forwardRef, useEffect } from '@wordpress/element';
+import { Stack, VisuallyHidden } from '@wordpress/ui';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import { STAT_CARD_NULL_GLYPH } from './constants';
+import { useStatCardContext } from './context';
+import type { StatCardValueProps, StatCardValueVariant } from './types';
+
+const variants: StatCardValueVariant[] = [ 'figure', 'text' ];
+
+const Value = forwardRef< HTMLSpanElement, StatCardValueProps >( function Value(
+	{ value, valueLabel, variant = 'figure', suffix, className, ...props },
+	ref
+) {
+	const { labels } = useStatCardContext();
+
+	useEffect( () => {
+		if ( 'production' === process.env.NODE_ENV || variants.includes( variant ) ) {
+			return;
+		}
+		// eslint-disable-next-line no-console
+		console.warn( `StatCard.Value: unknown variant "${ variant }", falling back to figure. Use one of ${ variants.join( ', ' ) }.` );
+	}, [ variant ] );
+
+	// A blank string is a missing figure too, and an empty hero would read as one
+	// that never loaded. A zero is a figure, so it stays out of this.
+	const isNull = null === value || undefined === value || ( 'string' === typeof value && '' === value.trim() );
+	const shown = isNull ? STAT_CARD_NULL_GLYPH : value;
+	// Trimmed, and `||` not `??`: a blank label is a missing one, and the glyph must never be left unnamed.
+	const spoken = valueLabel?.trim() || ( isNull ? labels.notApplicable : undefined );
+
+	const figure = (
+		<span
+			ref={ ref }
+			className={ classnames( 'newspack-stat-card__value', 'text' === variant && 'newspack-stat-card__value--text', className ) }
+			{ ...props }
+		>
+			{ spoken ? (
+				<>
+					{ /* Hidden, not labelled: ARIA forbids naming a generic element, and `role="img"` announces a graphic. */ }
+					<span aria-hidden="true">{ shown }</span>
+					<VisuallyHidden render={ <span /> }>{ spoken }</VisuallyHidden>
+				</>
+			) : (
+				shown
+			) }
+		</span>
+	);
+
+	if ( ! suffix ) {
+		return figure;
+	}
+
+	return (
+		<Stack direction="row" align="baseline" gap="sm" className="newspack-stat-card__figure">
+			{ figure }
+			{ suffix }
+		</Stack>
+	);
+} );
+
+export default Value;

package/src/status-indicator/README.md

@@ -0,0 +1,123 @@
+# StatusIndicator
+
+A status glyph followed by its label, for the Status column of a DataView.
+
+A badge is an attention marker. In a column where every row carries one it marks
+nothing and adds a block of colour to each row, so the quiet treatment is the
+default there and a badge is kept for the rare row that genuinely stands out,
+such as a group with a seat request waiting on payment.
+
+## Importing
+
+```jsx
+// The barrel.
+import { StatusIndicator } from 'newspack-components';
+
+// The component on its own.
+import StatusIndicator from '../../packages/components/src/status-indicator';
+
+// The vocabulary, for a column's own test. Deliberately not on the barrel: that
+// entry also pulls `Page`'s `:root` token block and the wizards store into
+// whichever bundle asks for it.
+import { statusGlyph, STATUS_NAMES } from '../../packages/components/src/status-indicator';
+```
+
+## Usage
+
+Name the status and the component draws it:
+
+```jsx
+<StatusIndicator status="active">{ __( 'Active', 'newspack-plugin' ) }</StatusIndicator>;
+```
+
+In a field definition, where the screen maps its own status keys onto the
+vocabulary:
+
+```jsx
+{
+	id: 'status',
+	label: __( 'Status', 'newspack-plugin' ),
+	getValue: ( { item } ) => item.status,
+	render: ( { item } ) => <StatusIndicator status={ STATUS_INDICATORS[ item.status ] }>{ item.status_label }</StatusIndicator>,
+	elements: statusElements,
+	filterBy: { operators: [ 'is' ] },
+}
+```
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `status` | `StatusName` | one of the two | The status to draw, from the vocabulary below. |
+| `icon` | `Icon`'s `icon` prop | one of the two | A glyph, for a field the vocabulary does not cover. |
+| `children` | `ReactNode` | yes | The status label. `@wordpress/primitives` forces `aria-hidden` on the glyph, so this is the whole accessible name. |
+
+`status` and `icon` are mutually exclusive, and one of them is required.
+Anything else is spread onto the wrapper, a `Stack` from `@wordpress/ui`, which
+takes the props of a `div`.
+
+## The vocabulary
+
+| Name | Glyph | What it means |
+| --- | --- | --- |
+| `active` | check circle | Live now: a published plan, a running subscription. |
+| `done` | check circle | Finished successfully: a sent newsletter, a completed sync. |
+| `scheduled` | clock | Waiting for a date to arrive. |
+| `draft` | half circle | Not live yet, or switched off. |
+| `pending` | part-filled circle | Waiting on something outside the publisher's hands. |
+| `attention` | exclamation circle | Live but needing a look, usually a payment. |
+| `error` | error | Failed, and the one state that asks the reader to act. |
+| `progress` | update | Running right now. |
+| `cancelled` | slash circle | Stopped on purpose. |
+| `ended` | slash circle | Stopped because its window closed. |
+| `private` | lock | Live, but not publicly reachable. |
+| `trash` | trash | Binned. |
+
+The component owns this so one meaning draws one mark everywhere. Before it
+existed the vocabulary lived in ten screen-level maps, and had already drifted:
+Pending was the half circle in Subscribers and the part-filled one in the
+Audience lists.
+
+**No two statuses in one column may draw the same mark.** A DataViews Status
+column offers its statuses as separate filters, so two that look identical make
+two different states indistinguishable in the one place the difference matters.
+
+Two names may share a glyph where they read differently at the call site but
+mean the same to a reader: a sent newsletter is finished rather than live, and
+an ad whose window closed was not cancelled. Splitting them leaves room to draw
+them apart later without touching a consumer. The pairs are `active`/`done` and
+`cancelled`/`ended`, and `index.test.js` pins that list, so a column keeps the
+rule by using distinct names and at most one half of a pair. `statusGlyph` is
+exported for the columns that want to assert it directly.
+
+The glyph does the separating on its own: the component inherits its colour from
+the surrounding text and tints nothing, so no status leans on colour to carry
+its meaning. That also means a state that needs to shout cannot, which is the
+trade the quiet treatment makes.
+
+## When to pass a glyph instead
+
+`icon` is for fields that classify rather than track a lifecycle, where a status
+name would be the wrong shape. Two exist: Plans' Availability (a gift, a lock
+and a globe for Free, Private and Public) and newsletters' Visibility (a globe
+or an envelope). Both are still Status-column-shaped in every other way, and
+both keep the same distinctness rule.
+
+## The icon's footprint
+
+`@wordpress/icons` draws a 16px glyph inside a 24px viewBox, so a 24px icon
+carries 4px of transparent padding on every side. The component trims that back
+to the visible footprint with a negative margin, which is what makes the 8px gap
+measure 8px between the glyph and the label rather than 12px. An icon that fills
+its viewBox would be cropped by 4px a side; the statuses all come from
+`@wordpress/icons`, which does not.
+
+The margin is derived rather than written as `-4px`, so it follows the two
+values it depends on: `calc((#{wp-vars.$grid-unit-20} - #{wp-vars.$icon-size}) / 2)`,
+the glyph's footprint minus the box it sits in, halved for one side. Sass folds
+it to a literal at build time, so nothing is paid for at runtime.
+
+The box it sits in is the `size={ 24 }` the component passes to `Icon`, which is
+`$icon-size`. The two are written in different files, so anything that changes
+the rendered size has to change the token the margin reads, or the trim stops
+matching the padding it is there to remove.

package/src/status-indicator/index.test.js

@@ -0,0 +1,70 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { drafts, gift, published } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import StatusIndicator, { statusGlyph, STATUS_NAMES } from '.';
+
+describe( 'StatusIndicator', () => {
+	it( 'renders the glyph alongside the label', () => {
+		const { container } = render( <StatusIndicator status="active">Active</StatusIndicator> );
+		expect( screen.getByText( 'Active' ) ).toBeInTheDocument();
+		expect( container.querySelector( 'svg.newspack-status-indicator__icon' ) ).toBeInTheDocument();
+	} );
+
+	// The trim is what makes the 8px gap measure 8px, so it is styled through a
+	// class rather than left to the consumer.
+	it( 'carries the class the icon trim is scoped to', () => {
+		const { container } = render( <StatusIndicator status="active">Active</StatusIndicator> );
+		expect( container.querySelector( '.newspack-status-indicator' ) ).toBeInTheDocument();
+		expect( container.querySelector( '.newspack-status-indicator__icon' ) ).toBeInTheDocument();
+	} );
+
+	it( 'draws a named status the way the vocabulary says', () => {
+		const { container: named } = render( <StatusIndicator status="draft">Draft</StatusIndicator> );
+		const { container: given } = render( <StatusIndicator icon={ drafts }>Draft</StatusIndicator> );
+		expect( named.querySelector( 'svg' ).innerHTML ).toBe( given.querySelector( 'svg' ).innerHTML );
+	} );
+
+	it( 'draws the glyph it is given when there is no name for it', () => {
+		const { container: free } = render( <StatusIndicator icon={ gift }>Free</StatusIndicator> );
+		const { container: active } = render( <StatusIndicator icon={ published }>Active</StatusIndicator> );
+		expect( free.querySelector( 'svg' ).innerHTML ).not.toBe( active.querySelector( 'svg' ).innerHTML );
+	} );
+
+	it( 'keeps the consumer class and passes the rest through', () => {
+		const { container } = render(
+			<StatusIndicator className="custom" data-testid="status" status="active">
+				Active
+			</StatusIndicator>
+		);
+		const root = container.querySelector( '.newspack-status-indicator' );
+		expect( root ).toHaveClass( 'custom' );
+		expect( root ).toHaveAttribute( 'data-testid', 'status' );
+	} );
+} );
+
+describe( 'statusGlyph', () => {
+	it( 'draws every name in the vocabulary', () => {
+		STATUS_NAMES.forEach( name => expect( statusGlyph( name ) ).toBeTruthy() );
+	} );
+
+	// Pinning the complete list is what lets a column assert its own distinctness:
+	// any pair not named here reads apart.
+	it( 'shares a mark only where two names mean the same to a reader', () => {
+		const byGlyph = new Map();
+		STATUS_NAMES.forEach( name => byGlyph.set( statusGlyph( name ), [ ...( byGlyph.get( statusGlyph( name ) ) || [] ), name ] ) );
+		expect( [ ...byGlyph.values() ].filter( names => names.length > 1 ) ).toEqual( [
+			[ 'active', 'done' ],
+			[ 'cancelled', 'ended' ],
+		] );
+	} );
+} );

package/src/status-indicator/index.tsx

@@ -0,0 +1,39 @@
+/**
+ * StatusIndicator
+ */
+
+/**
+ * WordPress dependencies.
+ */
+import { Icon } from '@wordpress/components';
+import { forwardRef } from '@wordpress/element';
+import { Stack } from '@wordpress/ui';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies.
+ */
+import type { StatusIndicatorProps } from './types';
+import { statusGlyph } from './statuses';
+import './style.scss';
+
+const StatusIndicator = forwardRef< HTMLDivElement, StatusIndicatorProps >( function StatusIndicator(
+	{ status, icon, className, children, ...props },
+	ref
+) {
+	return (
+		<Stack ref={ ref } direction="row" align="center" gap="sm" className={ classnames( 'newspack-status-indicator', className ) } { ...props }>
+			<Icon className="newspack-status-indicator__icon" icon={ status ? statusGlyph( status ) : icon } size={ 24 } />
+			<span>{ children }</span>
+		</Stack>
+	);
+} );
+
+export { statusGlyph, STATUS_NAMES } from './statuses';
+export type { StatusName } from './statuses';
+
+export default StatusIndicator;