newspack-components 4.6.3 → 4.7.0-alpha.2

package/src/table-card/README.md

@@ -0,0 +1,100 @@
+# TableCard
+
+A card frame for a table: an optional heading, the table shown edge-to-edge,
+and padded slots above and below it. It pins the composition the Gutenberg
+DataViews docs demonstrate as "With Card" — `@wordpress/ui`'s compound `Card`
+with the table in `Card.FullBleed` — so screens don't each reassemble the
+spacing and slot order by hand.
+
+Nothing in it is DataViews-specific. Any content that should run to the card's
+edges works: a DataViews table, a plain `<table>`, an embed.
+
+```jsx
+import { TableCard } from 'newspack-components';
+```
+
+## Usage
+
+```jsx
+import { __ } from '@wordpress/i18n';
+import { useId } from '@wordpress/element';
+import { TableCard } from 'newspack-components';
+
+const titleId = useId();
+
+<TableCard
+	title={ __( 'Price Schedule', 'newspack-plugin' ) }
+	titleId={ titleId }
+	actions={ <Button variant="secondary">{ __( 'Add Price', 'newspack-plugin' ) }</Button> }
+>
+	<div role="region" aria-labelledby={ titleId }>
+		<DataViews … />
+	</div>
+</TableCard>
+```
+
+## Props
+
+- `title` — optional heading, rendered in a `Card.Header` as a real heading
+  element (`h3` by default; see `heading`). `0` renders; `''`/`null`/
+  `undefined`/booleans (the leftovers of `cond && '…'`) render no heading.
+- `titleId` — id placed on the heading element, so a region inside the card can
+  name itself with `aria-labelledby` instead of duplicating the visible title
+  in an `aria-label`. Only meaningful together with `title`: with no heading
+  rendered, an `aria-labelledby` pointing at it names nothing.
+- `heading` — heading level for the title, `1`–`6`. Defaults to `3`, one level
+  under the `SectionHeader` (`h2`) most wizard screens use.
+- `actions` — controls rendered in the card header: opposite the title when
+  there is one, end-aligned on their own otherwise. A header renders when
+  either `title` or `actions` is renderable (same falsy rules as `title`).
+- `before` / `after` — content rendered inside the card padding, above and
+  below the table: stats rows, notes, footer actions. Slot children stretch to
+  the card's full content width; wrap a lone control in an `HStack` to keep its
+  natural width.
+- `className` — forwarded to `Card.Root`, the card's outermost element.
+- `children` — the table itself, rendered edge-to-edge via `Card.FullBleed`.
+  The card supplies no cell padding: pad the table's first and last columns to
+  the card's own padding (24px — `$grid-unit-30`, matching upstream's
+  `--wpds-dimension-padding-2xl`) or the outer columns land against the card
+  border.
+
+## How the edges behave
+
+Whether the table touches the card's top and bottom edges is decided by
+upstream `:first-child`/`:last-child` rules, and absent slots render no DOM
+node, so the shape follows from which props are passed:
+
+- No `title`, no `actions`, no `before`, no `after` — the table is flush to
+  all four card edges.
+- `title` or `actions` present — a header sits above; the table is inset from
+  the top by the card's header→content gap token (upstream's
+  `.header + .content` rule zeroes the content's own top padding and reconciles
+  the header's bottom padding to that gap with a compensating margin).
+- `before` / `after` present — the slot sits in the padding and the table no
+  longer touches that edge.
+
+A slot that appears conditionally (a See More button only when the table is
+long) therefore changes the card's shape with the condition. That can be the
+right call — a card with a footer control legitimately looks different from one
+without — but make it deliberately, knowing a data-size threshold can flip it.
+
+## On a `@wordpress/ui` upgrade
+
+The component is a thin composition over `@wordpress/ui` internals that are not
+a stable contract. The package pins `^0.16.0` (0.x, so 0.16.x only); when
+bumping past it, re-check:
+
+- `Card.FullBleed`'s placement rules — the edge behaviour above comes from its
+  stylesheet, not from this component.
+- `Card.Content` composed with `Stack` via the `render` prop — the documented
+  way to add inter-slot spacing while keeping `FullBleed` a direct child.
+- `Card.Title`'s default rendering (a `div`; this component swaps in a heading
+  via `render`) and the global-CSS-defense rules that keep wp-admin's heading
+  styles from restyling it.
+- That the card padding is still 24px — callers pad their outer table columns
+  with `$grid-unit-30` to match it, and the two values drift independently.
+- Every consumer, visually: the Price Schedule card (the one product surface
+  with a header — title, heading render, and the actions row), the impact table
+  (headerless; rendered by both the rule editor and the list page's catalog
+  panel), and the components-demo section, which is the cheapest place to
+  eyeball a bump.

package/src/table-card/index.test.js

@@ -0,0 +1,112 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import TableCard from '.';
+
+// @wordpress/ui injects no CSS under Jest, so the layout this component exists
+// for (full bleed, edge bumps, the content gap) is invisible here; slot order
+// and heading semantics are the assertable contract.
+describe( 'TableCard', () => {
+	it( 'renders the table children inside the card', () => {
+		render(
+			<TableCard>
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		expect( screen.getByRole( 'table', { name: 'Prices' } ) ).toBeInTheDocument();
+	} );
+
+	it( 'renders the title as a real heading carrying the given id', () => {
+		const { rerender } = render(
+			<TableCard title="Price schedule" titleId="tc-title">
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		expect( screen.getByRole( 'heading', { level: 3, name: 'Price schedule' } ) ).toHaveAttribute( 'id', 'tc-title' );
+
+		rerender(
+			<TableCard title="Price schedule" heading={ 2 }>
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		expect( screen.getByRole( 'heading', { level: 2, name: 'Price schedule' } ) ).toBeInTheDocument();
+
+		rerender(
+			<TableCard>
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		expect( screen.queryByRole( 'heading' ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'treats 0 as a renderable title and the empty string as none', () => {
+		const { rerender } = render(
+			<TableCard title={ 0 }>
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		expect( screen.getByRole( 'heading', { level: 3, name: '0' } ) ).toBeInTheDocument();
+
+		rerender(
+			<TableCard title="">
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		expect( screen.queryByRole( 'heading' ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'renders header actions alongside the title', () => {
+		render(
+			<TableCard title="Price Schedule" actions={ <button>Add Price</button> }>
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		const heading = screen.getByRole( 'heading', { level: 3, name: 'Price Schedule' } );
+		const action = screen.getByRole( 'button', { name: 'Add Price' } );
+		expect( heading.parentElement ).toContainElement( action );
+	} );
+
+	it( 'renders a header for actions alone, and none for boolean slot leftovers', () => {
+		const { rerender } = render(
+			<TableCard actions={ <button>Add Price</button> }>
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		expect( screen.getByRole( 'button', { name: 'Add Price' } ) ).toBeInTheDocument();
+		expect( screen.queryByRole( 'heading' ) ).not.toBeInTheDocument();
+
+		rerender(
+			<TableCard title={ false } actions={ false }>
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		expect( screen.queryByRole( 'heading' ) ).not.toBeInTheDocument();
+		expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'orders before, table, after within the card body', () => {
+		render(
+			<TableCard before={ <p>Stats row</p> } after={ <button>See More</button> }>
+				<table aria-label="Prices" />
+			</TableCard>
+		);
+		const before = screen.getByText( 'Stats row' );
+		const after = screen.getByRole( 'button', { name: 'See More' } );
+		const table = screen.getByRole( 'table', { name: 'Prices' } );
+		// Walk the table up to the card body's direct child, so extra upstream
+		// wrappers cannot silently repoint the comparison.
+		const body = before.parentElement;
+		let tableWrap = table;
+		while ( tableWrap.parentElement !== body ) {
+			tableWrap = tableWrap.parentElement;
+		}
+		const order = Array.from( body.children );
+		expect( order.indexOf( before ) ).toBeLessThan( order.indexOf( tableWrap ) );
+		expect( order.indexOf( tableWrap ) ).toBeLessThan( order.indexOf( after ) );
+	} );
+} );

package/src/table-card/index.tsx

@@ -0,0 +1,56 @@
+/**
+ * TableCard
+ *
+ * The DataViews-in-a-card composition from @wordpress/ui. Which card edges the
+ * table touches follows upstream first/last-child rules, so it changes with the
+ * slots present — the README spells the combinations out.
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { Card, Stack } from '@wordpress/ui';
+
+interface TableCardProps {
+	title?: React.ReactNode;
+	/** Id for the heading, so a caller's region can name itself via `aria-labelledby`. */
+	titleId?: string;
+	heading?: 1 | 2 | 3 | 4 | 5 | 6;
+	actions?: React.ReactNode;
+	before?: React.ReactNode;
+	after?: React.ReactNode;
+	className?: string;
+	/** Rendered edge-to-edge via `Card.FullBleed`. */
+	children: React.ReactNode;
+}
+
+/** `0` is a renderable slot value; the falsy leftovers of `cond && <X />` are not. */
+const isRenderable = ( node: React.ReactNode ) => node !== undefined && node !== null && node !== '' && typeof node !== 'boolean';
+
+export default function TableCard( { title, titleId, heading = 3, actions, before, after, className, children }: TableCardProps ) {
+	const TitleTag = `h${ heading }` as const;
+	const hasTitle = isRenderable( title );
+	const hasActions = isRenderable( actions );
+	return (
+		<Card.Root className={ className }>
+			{ ( hasTitle || hasActions ) && (
+				<Card.Header
+					render={ hasActions ? <Stack direction="row" justify={ hasTitle ? 'space-between' : 'end' } align="center" /> : undefined }
+				>
+					{ hasTitle && <Card.Title render={ <TitleTag id={ titleId } /> }>{ title }</Card.Title> }
+					{ /* Its own row, so several actions don't scatter across the header's space-between. */ }
+					{ hasActions && (
+						<Stack direction="row" gap="sm" align="center">
+							{ actions }
+						</Stack>
+					) }
+				</Card.Header>
+			) }
+			<Card.Content render={ <Stack direction="column" gap="lg" /> }>
+				{ before }
+				<Card.FullBleed>{ children }</Card.FullBleed>
+				{ after }
+			</Card.Content>
+		</Card.Root>
+	);
+}

package/src/with-wizard-screen/style.scss

@@ -18,6 +18,14 @@
 
 	color: wp-colors.$gray-900;
 
+	// Full-width dividers span 100vw, which overspills the admin content area
+	// (admin menu offset + scrollbar) and triggers horizontal scrolling; clip
+	// (not hidden) so no scroll container is created. Scoped off __content,
+	// which can be a constrained centered column.
+	&:not(.newspack-wizard__content) {
+		overflow-x: clip;
+	}
+
 	// Headings
 	h1,
 	h2,

package/src/wizard/index.js

@@ -6,9 +6,10 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies.
  */
-import { DropdownMenu, MenuGroup, MenuItem } from '@wordpress/components';
+// Notice is aliased: `Notice` below is Newspack's own, which this file also uses.
+import { DropdownMenu, MenuGroup, MenuItem, Notice as CoreNotice, SlotFillProvider, createSlotFill } from '@wordpress/components';
 import { useDispatch, useSelect } from '@wordpress/data';
-import { cloneElement, isValidElement, useEffect, useRef, useState, forwardRef } from '@wordpress/element';
+import { cloneElement, createInterpolateElement, isValidElement, useRef, useEffect, useState, forwardRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { category, chevronLeft, moreVertical } from '@wordpress/icons';
 
@@ -24,6 +25,14 @@ import WizardError from './components/WizardError';
 
 registerStore();
 
+/**
+ * Renders a view's page-level banner outside the padded content column, so it sits
+ * flush beneath the header rather than indented within the section it describes.
+ */
+const { Slot: WizardBannerSlot, Fill: WizardBanner } = createSlotFill( 'NewspackWizardBanner' );
+
+export { WizardBanner };
+
 /**
  * Icon registry for resolving icon name strings passed through the data store.
  * React elements from @wordpress/icons can't cross webpack entry point boundaries
@@ -39,6 +48,34 @@ const resolveIcon = icon => {
 
 const { HashRouter, Redirect, Route, Switch, useLocation } = Router;
 
+/**
+ * Interpolate a translated message's named tags, falling back to plain text.
+ *
+ * The message is translated, so its tags are site-controlled: any .mo file under
+ * wp-content/languages/plugins, any GlotPress export, or any `gettext`-filter
+ * plugin can supply one. `createInterpolateElement` throws on an unbalanced
+ * closing tag whose name is in the conversion map - verified against core's own
+ * element.js, which is what runs here since the bundle externalizes wp-element.
+ * Nothing above this renders an error boundary, so an uncaught throw would blank
+ * the whole wizard, including the screen the inert-gating notice links to as the
+ * fix. Degraded copy is recoverable; a blank screen is not.
+ *
+ * The other malformed cases already degrade on their own and are left alone: an
+ * unclosed opener drops that tag and renders the rest as text, and a tag not in
+ * the map renders literally.
+ *
+ * @param {string} message    Translated message carrying named tags.
+ * @param {Object} conversion Conversion map for createInterpolateElement.
+ * @return {JSX.Element|string} The interpolated message, or the message with its tags stripped.
+ */
+const interpolateOrPlainText = ( message, conversion ) => {
+	try {
+		return createInterpolateElement( message, conversion );
+	} catch {
+		return message.replace( /<\/?[a-zA-Z][a-zA-Z0-9]*\s*\/?>/g, '' );
+	}
+};
+
 /**
  * Reset the header data when a new section is rendered.
  */
@@ -87,7 +124,7 @@ const WizardHeaderRegion = ( { hideHeader, headerText, sections, sectionName, su
 
 /**
  * @typedef  {Object}     WizardProps
- * @property {string}     headerText                The header text.
+ * @property {string}     [headerText]              Fallback heading, used only when no section declares breadcrumbs.
  * @property {string}     [subHeaderText]           The sub-header text, optional.
  * @property {string}     [apiSlug]                 The API slug, optional.
  * @property {string}     [className]               CSS classes, optional.
@@ -184,6 +221,26 @@ const Wizard = (
 		</TabbedNavigation>
 	);
 
+	// Rendered here rather than as a core admin notice, which wizards strip at
+	// priority -9999. Sits as the first child of .newspack-wizard__main so it lands
+	// flush beneath the header region and spans the full width in every view: this
+	// describes the state of the whole site, not of the section below it, so it reads
+	// as page chrome rather than as content.
+	const inertGating = window.newspack_aux_data?.inert_gating;
+	const inertGatingNotice = inertGating?.show && (
+		<CoreNotice status="warning" isDismissible={ false } className="newspack-wizard__inert-gating-notice">
+			{ /* The conversion map takes childless elements and fills them from the
+			     translated string, so jsx-a11y can't see the content they end up with. */ }
+			{ interpolateOrPlainText( inertGating.message, {
+				/* eslint-disable jsx-a11y/anchor-has-content */
+				accessControl: <a href={ inertGating.urls.accessControl } />,
+				audience: <a href={ inertGating.urls.audience } />,
+				/* eslint-enable jsx-a11y/anchor-has-content */
+				strong: <strong />,
+			} ) }
+		</CoreNotice>
+	);
+
 	const content = (
 		<>
 			<HandoffMessage />
@@ -191,6 +248,8 @@ const Wizard = (
 			{ sections.length > 1 && <ResetHeaderData /> }
 
 			<div className="newspack-wizard__main">
+				{ inertGatingNotice }
+				<WizardBannerSlot bubblesVirtually />
 				<Switch>
 					{ routedSections.map( ( section, index ) => {
 						const SectionComponent = section.render;
@@ -294,38 +353,40 @@ const Wizard = (
 		) : undefined;
 
 	return (
-		<div ref={ ref }>
-			<div
-				className={ classnames( isLoading ? 'newspack-wizard__is-loading' : 'newspack-wizard__is-loaded', {
-					'newspack-wizard__is-loading-quiet': isQuietLoading,
-				} ) }
-			>
-				<HashRouter hashType="slash">
-					{ newspack_aux_data.is_debug_mode && <Notice debugMode /> }
-					<WizardHeaderRegion
-						hideHeader={ hideHeader }
-						headerText={ headerText }
-						sections={ routedSections }
-						sectionName={ sectionName }
-						subTitle={ subHeaderText }
-						actions={ headerActions }
-						tabbedNavigation={ tabbedNavigation }
-					>
-						{ content }
-					</WizardHeaderRegion>
-				</HashRouter>
-				{ notices?.length > 0 && (
-					<div className="newspack-wizard__snackbar-list">
-						{ notices.map( ( notice, index ) => (
-							<WizardSnackbar key={ notice.id || index } id={ notice.id } type={ notice.type } actions={ notice.actions }>
-								{ notice.message }
-							</WizardSnackbar>
-						) ) }
-					</div>
-				) }
+		<SlotFillProvider>
+			<div ref={ ref }>
+				<div
+					className={ classnames( isLoading ? 'newspack-wizard__is-loading' : 'newspack-wizard__is-loaded', {
+						'newspack-wizard__is-loading-quiet': isQuietLoading,
+					} ) }
+				>
+					<HashRouter hashType="slash">
+						{ newspack_aux_data.is_debug_mode && <Notice debugMode /> }
+						<WizardHeaderRegion
+							hideHeader={ hideHeader }
+							headerText={ headerText }
+							sections={ routedSections }
+							sectionName={ sectionName }
+							subTitle={ subHeaderText }
+							actions={ headerActions }
+							tabbedNavigation={ tabbedNavigation }
+						>
+							{ content }
+						</WizardHeaderRegion>
+					</HashRouter>
+					{ notices?.length > 0 && (
+						<div className="newspack-wizard__snackbar-list">
+							{ notices.map( ( notice, index ) => (
+								<WizardSnackbar key={ notice.id || index } id={ notice.id } type={ notice.type } actions={ notice.actions }>
+									{ notice.message }
+								</WizardSnackbar>
+							) ) }
+						</div>
+					) }
+				</div>
+				{ ! isLoading && <Footer simple={ hasSimpleFooter } /> }
 			</div>
-			{ ! isLoading && <Footer simple={ hasSimpleFooter } /> }
-		</div>
+		</SlotFillProvider>
 	);
 };