newspack-components 4.10.0 → 4.12.0-alpha.1

package/dist/esm/reorder-modal/style.scss

@@ -0,0 +1,114 @@
+@use "~@wordpress/base-styles/colors" as wp-colors;
+@use "~@wordpress/base-styles/mixins" as wp-mixins;
+@use "~@wordpress/base-styles/variables" as wp-vars;
+
+.newspack-reorder-modal {
+	&__body {
+		display: flex;
+		flex-direction: column;
+		min-height: calc(#{wp-vars.$grid-unit} * 23);
+	}
+
+	&__loading {
+		align-items: center;
+		display: flex;
+		flex: 1;
+		justify-content: center;
+	}
+
+	&__notice {
+		margin: 0 0 wp-vars.$grid-unit-10;
+	}
+
+	&__list {
+		display: flex;
+		flex-direction: column;
+		gap: wp-vars.$grid-unit-10;
+		list-style: none;
+		margin: 0;
+		padding: 0;
+	}
+
+	&__item {
+		--newspack-reorder-modal-divider: #{wp-colors.$gray-100};
+		--wp-ui-card-padding: #{wp-vars.$grid-unit-15};
+
+		align-items: stretch;
+		cursor: grab;
+		flex-direction: row;
+		margin: 0;
+
+		&:focus-within,
+		&:hover {
+			--newspack-reorder-modal-divider: #{wp-colors.$gray-300};
+
+			border-color: wp-colors.$gray-300;
+		}
+
+		&.is-dragging {
+			cursor: grabbing;
+			opacity: 0.5;
+		}
+	}
+
+	&__grip {
+		align-items: center;
+		color: wp-colors.$gray-700;
+		display: flex;
+		padding-left: wp-vars.$grid-unit-05;
+	}
+
+	&__move {
+		align-items: center;
+		border-right: 1px solid var(--newspack-reorder-modal-divider);
+		display: flex;
+		flex-direction: column;
+		padding: wp-vars.$grid-unit-05;
+	}
+
+	&__content {
+		align-items: center;
+		align-self: center;
+		display: flex;
+		flex: 1;
+		gap: wp-vars.$grid-unit-10;
+		min-width: 0;
+		padding-block-end: var(--wp-ui-card-padding);
+	}
+
+	&__title {
+		@include wp-mixins.heading-large();
+
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	&__badge {
+		display: flex;
+		flex-shrink: 0;
+	}
+
+	&__toggle {
+		align-items: center;
+		display: flex;
+		padding-inline-end: wp-vars.$grid-unit-15;
+	}
+
+	&__description {
+		margin: 0 0 wp-vars.$grid-unit-20;
+	}
+
+	&__item.is-off &__title {
+		color: wp-colors.$gray-700;
+	}
+
+	&__footer {
+		display: flex;
+		gap: wp-vars.$grid-unit-10;
+		justify-content: flex-end;
+		margin-top: auto;
+		padding-top: wp-vars.$grid-unit-30;
+	}
+}

package/dist/esm/tabbed-navigation/style.scss

@@ -21,6 +21,11 @@
 	/* stylelint-disable-next-line plugin-wpds/no-setting-wpds-custom-properties -- deliberate Newspack brand override of the indicator token. */
 	--wpds-color-stroke-interactive-neutral-strong: #{np-colors.$primary-600};
 
+	[role="tablist"] {
+		max-width: 100%;
+		overflow-x: auto;
+	}
+
 	a[role="tab"] {
 		text-decoration: none;
 

package/dist/esm/tooltip-badge/index.js

@@ -0,0 +1,43 @@
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { Badge, Tooltip } from '@wordpress/ui';
+
+/**
+ * Internal dependencies
+ */
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * A badge whose tooltip explains it. The tooltip serves mouse and keyboard users;
+ * screen readers get the same text as the trigger's description, which keeps it
+ * out of the accessible name of a heading the badge sits in.
+ */
+var _TooltipBadge = function TooltipBadge(_ref) {
+  var label = _ref.label,
+    tooltip = _ref.tooltip,
+    _ref$intent = _ref.intent,
+    intent = _ref$intent === void 0 ? 'none' : _ref$intent;
+  var descriptionId = useInstanceId(_TooltipBadge, 'newspack-tooltip-badge');
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsxs(Tooltip.Root, {
+      children: [/*#__PURE__*/_jsx(Tooltip.Trigger, {
+        render: /*#__PURE__*/_jsx("span", {
+          tabIndex: 0,
+          "aria-describedby": descriptionId
+        }),
+        children: /*#__PURE__*/_jsx(Badge, {
+          intent: intent,
+          children: label
+        })
+      }), /*#__PURE__*/_jsx(Tooltip.Popup, {
+        children: tooltip
+      })]
+    }), /*#__PURE__*/_jsx("span", {
+      id: descriptionId,
+      hidden: true,
+      children: tooltip
+    })]
+  });
+};
+export default _TooltipBadge;

package/dist/esm/tooltip-badge/index.test.js

@@ -0,0 +1,26 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import TooltipBadge from './';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+describe('TooltipBadge', function () {
+  it('describes its focusable trigger with the tooltip text, keeping it out of a surrounding heading name', function () {
+    render(/*#__PURE__*/_jsxs("h3", {
+      children: ["Registration wall", /*#__PURE__*/_jsx(TooltipBadge, {
+        label: "Overrides paid access",
+        tooltip: "This grants registered readers access.",
+        intent: "low"
+      })]
+    }));
+    expect(screen.getByRole('heading', {
+      name: 'Registration wall Overrides paid access'
+    })).toBeInTheDocument();
+    var trigger = screen.getByText('Overrides paid access').closest('[tabindex="0"]');
+    expect(trigger).toHaveAccessibleDescription('This grants registered readers access.');
+  });
+});

package/dist/esm/wizard/index.js

@@ -13,9 +13,8 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies.
  */
-import { DropdownMenu, MenuGroup, MenuItem, Notice, SlotFillProvider, createSlotFill,
-// eslint-disable-next-line @wordpress/no-unsafe-wp-apis
-__experimentalVStack as VStack } from '@wordpress/components';
+import { DropdownMenu, MenuGroup, MenuItem, Notice, SlotFillProvider, createSlotFill } from '@wordpress/components';
+import { Stack } from '@wordpress/ui';
 import { useDispatch, useSelect } from '@wordpress/data';
 import { cloneElement, createInterpolateElement, isValidElement, useLayoutEffect, useRef, useState, forwardRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
@@ -30,7 +29,7 @@ import Router from '../proxied-imports/router';
 import registerStore, { WIZARD_STORE_NAMESPACE } from './store';
 import WizardSnackbar from './components/WizardSnackbar';
 import WizardError from './components/WizardError';
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 registerStore();
 
 /**
@@ -115,12 +114,13 @@ var ResetHeaderData = function ResetHeaderData() {
  * can read the current route and derive the active-tab breadcrumb.
  */
 var WizardHeaderRegion = function WizardHeaderRegion(_ref) {
-  var _activeSection;
+  var _activeSection, _activeSection2;
   var hideHeader = _ref.hideHeader,
     headerText = _ref.headerText,
     sections = _ref.sections,
     sectionName = _ref.sectionName,
     subTitle = _ref.subTitle,
+    headerSubTitle = _ref.headerSubTitle,
     actions = _ref.actions,
     wizardTabbedNavigation = _ref.tabbedNavigation,
     children = _ref.children;
@@ -150,11 +150,19 @@ var WizardHeaderRegion = function WizardHeaderRegion(_ref) {
         break;
       }
     }
+
+    // WizardError normally mounts inside the tab bar, so a route without one renders it itself.
   } catch (err) {
     _iterator.e(err);
   } finally {
     _iterator.f();
   }
+  if ((_activeSection = activeSection(sections, pathname)) !== null && _activeSection !== void 0 && _activeSection.hideTabbedNavigation && tabbedNavigation) {
+    tabbedNavigation = null;
+    children = /*#__PURE__*/_jsxs(_Fragment, {
+      children: [/*#__PURE__*/_jsx(WizardError, {}), children]
+    });
+  }
   if (hideHeader) {
     // Without the Page shell the tabs still own the content: it renders
     // inside the active tab's panel.
@@ -174,10 +182,10 @@ var WizardHeaderRegion = function WizardHeaderRegion(_ref) {
   // Append any render-time leaf crumb(s) the section supplied via
   // headerData.sectionName (deduped against the current trailing label).
   breadcrumbItems = appendSectionName(breadcrumbItems, sectionName);
-  var sectionSubTitle = (_activeSection = activeSection(sections, pathname)) === null || _activeSection === void 0 ? void 0 : _activeSection.subHeaderText;
+  var sectionSubTitle = (_activeSection2 = activeSection(sections, pathname)) === null || _activeSection2 === void 0 ? void 0 : _activeSection2.subHeaderText;
   return /*#__PURE__*/_jsx(Page, {
     breadcrumbItems: breadcrumbItems,
-    subTitle: sectionSubTitle !== null && sectionSubTitle !== void 0 ? sectionSubTitle : subTitle,
+    subTitle: headerSubTitle || (sectionSubTitle !== null && sectionSubTitle !== void 0 ? sectionSubTitle : subTitle),
     actions: actions,
     tabbedNavigation: tabbedNavigation,
     children: children
@@ -190,7 +198,7 @@ var WizardHeaderRegion = function WizardHeaderRegion(_ref) {
  * @property {string}     [subHeaderText]           The sub-header text, optional.
  * @property {string}     [apiSlug]                 The API slug, optional.
  * @property {string}     [className]               CSS classes, optional.
- * @property {any[]}      sections                  Array of sections. A section's own `subHeaderText` replaces the wizard's while it is active.
+ * @property {any[]}      sections                  Array of sections. A section's own `subHeaderText` replaces the wizard's while it is active, and `hideTabbedNavigation` hides the tab bar on its route.
  *                                                  Its optional `tabbedNavigation( params )` returns the tab items shown while its route matches.
  * @property {boolean}    [hasSimpleFooter]         Indicates if a simple footer is used, optional.
  * @property {() => void} [renderAboveSections]     Function to render content above sections, optional.
@@ -248,7 +256,8 @@ var Wizard = function Wizard(_ref2, ref) {
     sectionSize = headerData.sectionSize,
     sectionTitle = headerData.sectionTitle,
     sectionPrimaryAction = headerData.sectionPrimaryAction,
-    sectionSecondaryAction = headerData.sectionSecondaryAction;
+    sectionSecondaryAction = headerData.sectionSecondaryAction,
+    headerSubTitle = headerData.subTitle;
   var mainActions = actions === null || actions === void 0 ? void 0 : actions.filter(function (action) {
     return action.type === 'primary' || action.type === 'secondary';
   });
@@ -311,9 +320,10 @@ var Wizard = function Wizard(_ref2, ref) {
         return /*#__PURE__*/_jsxs(_Fragment, {
           children: [!pluginRequirementsKnown && /*#__PURE__*/_jsx("div", {
             className: "newspack-wizard__loader",
-            children: /*#__PURE__*/_jsxs(VStack, {
-              alignment: "center",
-              spacing: 2,
+            children: /*#__PURE__*/_jsxs(Stack, {
+              direction: "column",
+              align: "center",
+              gap: "sm",
               children: [/*#__PURE__*/_jsx(Waiting, {
                 noMargin: true
               }), /*#__PURE__*/_jsx("strong", {
@@ -467,6 +477,7 @@ var Wizard = function Wizard(_ref2, ref) {
             sections: routedSections,
             sectionName: sectionName,
             subTitle: subHeaderText,
+            headerSubTitle: headerSubTitle,
             actions: headerActions,
             tabbedNavigation: tabbedNavigation,
             children: content

package/dist/esm/wizard/index.test.js

@@ -550,4 +550,82 @@ describe('Wizard section subtitle', function () {
       }
     }, _callee1);
   })));
+});
+describe('Wizard tab bar on hidden routes', function () {
+  beforeEach(function () {
+    apiFetch.mockReset();
+    apiFetch.mockResolvedValue({});
+  });
+  it('hides the tab bar on a hideTabbedNavigation route and restores it on a tab route', /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee10() {
+    var _t10, _t11, _t12;
+    return _regenerator().w(function (_context10) {
+      while (1) switch (_context10.n) {
+        case 0:
+          window.location.hash = '#/list';
+          render(/*#__PURE__*/_jsx(Wizard, {
+            headerText: "Test wizard",
+            sections: [{
+              label: 'List',
+              path: '/list',
+              exact: true,
+              render: function render() {
+                return /*#__PURE__*/_jsx("div", {
+                  children: "List view"
+                });
+              }
+            }, {
+              label: 'Other',
+              path: '/other',
+              exact: true,
+              render: function render() {
+                return /*#__PURE__*/_jsx("div", {
+                  children: "Other view"
+                });
+              }
+            }, {
+              path: '/list/:id',
+              isHidden: true,
+              hideTabbedNavigation: true,
+              render: function render() {
+                return /*#__PURE__*/_jsx("div", {
+                  children: "Item view"
+                });
+              }
+            }]
+          }));
+          _t10 = expect;
+          _context10.n = 1;
+          return screen.findByText('List view');
+        case 1:
+          _t10(_context10.v).toBeInTheDocument();
+          expect(screen.getByRole('tab', {
+            name: 'Other'
+          })).toBeInTheDocument();
+          act(function () {
+            window.location.hash = '#/list/esp';
+            window.dispatchEvent(new HashChangeEvent('hashchange'));
+          });
+          _t11 = expect;
+          _context10.n = 2;
+          return screen.findByText('Item view');
+        case 2:
+          _t11(_context10.v).toBeInTheDocument();
+          expect(screen.queryByRole('tab')).not.toBeInTheDocument();
+          act(function () {
+            window.location.hash = '#/list';
+            window.dispatchEvent(new HashChangeEvent('hashchange'));
+          });
+          _t12 = expect;
+          _context10.n = 3;
+          return screen.findByText('List view');
+        case 3:
+          _t12(_context10.v).toBeInTheDocument();
+          expect(screen.getByRole('tab', {
+            name: 'Other'
+          })).toBeInTheDocument();
+        case 4:
+          return _context10.a(2);
+      }
+    }, _callee10);
+  })));
 });

package/dist/esm/wizard/store/index.js

@@ -27,7 +27,8 @@ var DEFAULT_STATE = {
     badges: [],
     sectionDescription: '',
     sectionName: '',
-    sectionTitle: ''
+    sectionTitle: '',
+    subTitle: ''
   },
   isLoading: false,
   isQuietLoading: false,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "newspack-components",
-	"version": "4.10.0",
+	"version": "4.12.0-alpha.1",
 	"description": "Newspack design system components",
 	"author": "Automattic",
 	"license": "GPL-2.0-or-later",
@@ -30,7 +30,7 @@
 		"classnames": "^2.3.1",
 		"lodash": "^4.17.21",
 		"moment-range": "^3.1.1",
-		"newspack-icons": "1.2.0",
+		"newspack-icons": "1.3.0-alpha.1",
 		"qs": "^6.15.2",
 		"react-router-dom": "^5.3.4",
 		"@babel/runtime": "^7.29.7",

package/src/breadcrumbs/index.js

@@ -80,7 +80,7 @@ const Breadcrumbs = ( { items = [] } ) => {
 
 	return (
 		<nav aria-label={ __( 'Breadcrumbs', 'newspack-plugin' ) }>
-			<Stack render={ <ul /> } direction="row" align="center" className="newspack-breadcrumbs__list">
+			<Stack render={ <ul /> } direction="row" align="center" wrap="wrap" className="newspack-breadcrumbs__list">
 				{ preceding.map( ( item, index ) => (
 					<li key={ item.url || index }>
 						{ item.url ? (

package/src/breadcrumbs/style.scss

@@ -7,8 +7,8 @@
 	padding: 0;
 
 	> li {
-		flex-shrink: 0;
 		margin: 0;
+		min-width: 0;
 
 		a {
 			color: wp-colors.$gray-900;
@@ -20,11 +20,6 @@
 			}
 		}
 	}
-
-	> li:last-child {
-		flex-shrink: 1;
-		min-width: 0;
-	}
 }
 
 .newspack-breadcrumbs__count {
@@ -39,9 +34,7 @@
 }
 
 .newspack-breadcrumbs__list h1.newspack-breadcrumbs__current {
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
+	overflow-wrap: break-word;
 	padding: 0;
-	line-height: normal;
+	line-height: var(--wpds-typography-line-height-md, #{wp-vars.$grid-unit-30});
 }

package/src/card/style-core.scss

@@ -221,7 +221,7 @@
 				color: inherit;
 				text-decoration: none;
 				&:hover {
-					text-decoration: underline;
+					color: var(--wp-admin-theme-color);
 				}
 			}
 		}

package/src/card-form/README.md

@@ -4,8 +4,8 @@ A card component for presenting a named setting or feature with an expandable in
 
 ## 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 }`.
+- Stack multiple `CardForm` cards inside a `<Stack direction="column" gap="lg">` from `@wordpress/ui`; 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, wrap them in a `<Stack gap="sm" align="center">` from `@wordpress/ui`.
 - The form body (`children`) is only mounted when `isOpen` is `true`.
 
 ## States

package/src/card-sortable-list/index.test.js

@@ -26,4 +26,17 @@ describe( 'CardSortableList', () => {
 		// An unguarded Badge would still emit an empty span, so assert on element children.
 		expect( container.querySelector( 'h3' ).children ).toHaveLength( 0 );
 	} );
+
+	it( 'names each toggle after its item', () => {
+		render(
+			<CardSortableList
+				items={ [
+					{ id: 1, title: 'Homepage', toggleChecked: true, onToggleChange: () => {} },
+					{ id: 2, title: 'About', toggleChecked: false, onToggleChange: () => {} },
+				] }
+			/>
+		);
+		expect( screen.getByRole( 'checkbox', { name: 'Homepage' } ) ).toBeChecked();
+		expect( screen.getByRole( 'checkbox', { name: 'About' } ) ).not.toBeChecked();
+	} );
 } );

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

@@ -2,25 +2,26 @@
  * Card - Sortable list component.
  */
 
+/**
+ * External dependencies
+ */
+import classNames from 'classnames';
+
 /**
  * WordPress dependencies.
  */
-import { Disabled, Draggable, __experimentalVStack as VStack } from '@wordpress/components'; // eslint-disable-line @wordpress/no-unsafe-wp-apis
+import { Disabled, Draggable } from '@wordpress/components';
 import { useEffect, useLayoutEffect, useRef, useState } from '@wordpress/element';
-import { Badge } from '@wordpress/ui';
+import { Badge, Stack } from '@wordpress/ui';
 
 /**
  * Internal dependencies
  */
-import { Card } from '../';
+import Card from '../card';
+import TooltipBadge from '../tooltip-badge';
 import type { CardBadge } from '../types';
 import './style.scss';
 
-/**
- * External dependencies
- */
-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
 
@@ -37,6 +38,8 @@ type DraggableItem = {
 	title: string;
 	description?: React.ReactNode;
 	badge?: CardBadge;
+	/** A second badge, e.g. a warning, whose tooltip explains it. */
+	secondaryBadge?: CardBadge & { tooltip?: string };
 	toggleChecked?: boolean;
 	onToggleChange?: () => void;
 	actions?: DraggableItemAction[];
@@ -45,7 +48,7 @@ type DraggableItem = {
 type DragMeasurements = {
 	lockedHeight: number;
 	sourceHeight: number;
-	// Height of each item (including the VStack gap after it, except the last).
+	// Height of each item (including the Stack gap after it, except the last).
 	itemStrides: number[];
 	// Top edge of each item, used for drop position hit-testing in onDragEnd.
 	itemTops: number[];
@@ -357,7 +360,9 @@ const CardSortableList = ( {
 	const isDragging = draggingIndex !== null;
 
 	return (
-		<VStack
+		<Stack
+			direction="column"
+			gap="lg"
 			ref={ listRef }
 			className={ classNames(
 				'newspack-card--core--sortable-list',
@@ -365,7 +370,6 @@ const CardSortableList = ( {
 				isDragging && 'newspack-card--core--sortable-list__is-dragging'
 			) }
 			style={ measurements ? { height: measurements.lockedHeight } : undefined }
-			spacing={ 4 }
 		>
 			{ sortedItems.map( ( item, index ) => {
 				const translateY = getTranslateY( index );
@@ -406,6 +410,18 @@ const CardSortableList = ( {
 														{ item.badge?.label && (
 															<Badge intent={ item.badge.intent ?? 'none' }>{ item.badge.label }</Badge>
 														) }
+														{ item.secondaryBadge?.label &&
+															( item.secondaryBadge.tooltip ? (
+																<TooltipBadge
+																	label={ item.secondaryBadge.label }
+																	tooltip={ item.secondaryBadge.tooltip }
+																	intent={ item.secondaryBadge.intent }
+																/>
+															) : (
+																<Badge intent={ item.secondaryBadge.intent ?? 'none' }>
+																	{ item.secondaryBadge.label }
+																</Badge>
+															) ) }
 													</h3>
 													{ item.description && <p>{ item.description }</p> }
 												</>
@@ -419,6 +435,9 @@ const CardSortableList = ( {
 												actionType: 'toggle',
 												isActive: item.toggleChecked,
 												onToggle: item.onToggleChange,
+												// Names the toggle for assistive tech. The card hides this
+												// label, since the header already shows the title.
+												title: item.title,
 											} ),
 											...( item.actions !== undefined && {
 												actions: item.actions,
@@ -431,7 +450,7 @@ const CardSortableList = ( {
 					</Disabled>
 				);
 			} ) }
-		</VStack>
+		</Stack>
 	);
 };
 

package/src/card-sortable-list/style.scss

@@ -6,6 +6,14 @@ $drop-duration: 400ms; /* must match DROP_ANIMATION_DURATION in index.tsx */
 	&__item {
 		cursor: grab;
 
+		/*
+		 * Keep a card's title in the case it was written in. The block editor
+		 * sidebar uppercases every h3 (`.interface-complementary-area h3`).
+		 */
+		.newspack-card--core__header-content h3 {
+			text-transform: none;
+		}
+
 		/*
 		 * Animate items sliding to fill/make space around the dragged item.
 		 */

package/src/drawer/README.md

@@ -148,9 +148,9 @@ unsaved-changes confirmation always applies.
 
 ## `Drawer.Content`
 
-The body. Repeatable: each `Drawer.Content` is a section, rendered as a VStack
-with a 16px gap by default; `gap` changes it. Children space through the gap
-alone; their own top and bottom margins are reset.
+The body. Repeatable: each `Drawer.Content` is a section that stacks its
+children in a column, 16px apart by default; `gap` changes it. Children space
+through the gap alone; their own top and bottom margins are reset.
 
 Anything can go in a section: an element, a control, a nested stack, or plain
 text. Each child becomes a row separated by the gap, and a run of plain text and
@@ -165,8 +165,8 @@ with markup in your own element and hand the section that instead.
 |------|------|---------|-------------|
 | `children` | `React.ReactNode` | — | Section content. |
 | `className` | `string` | — | Additional CSS class. |
-| `gap` | `number` | `4` | Space between the section's children, on the 4px scale, as VStack's `spacing`. `4` is 16px. |
-| `padding` | `number` | `6` | On the 4px scale, as VStack's `spacing`. `6` is 24px; `0` is a flush section that brings its own padding. |
+| `gap` | `string` | `'lg'` | Space between the section's children, as a `Stack` gap token from `@wordpress/ui`. `'lg'` is 16px. |
+| `padding` | `number` | `6` | On the 4px scale. `6` is 24px; `0` is a flush section that brings its own padding. |
 
 Consecutive sections share one scroll container, so they scroll together between
 the pinned header and footer. Sections are not self-separating: put a
@@ -234,18 +234,12 @@ separator.
 
 ## `Drawer.Footer`
 
-A pinned container for `Drawer.Action` elements. The layout is pure CSS on the
-child count.
+A pinned container for `Drawer.Action` elements. Whatever the number of
+actions, they sit in one row aligned to the end, each at its natural width. The
+row wraps when the actions don't fit side by side.
 
-| Children | Layout |
-|---|---|
-| 1 | Row, the button fills it |
-| 2 | Row, split 50/50 |
-| 3 or more | Column, full-width buttons |
-
-Convention, not enforced: with two actions pass the secondary first, so the
-primary sits on the right; with three pass primary, secondary, tertiary
-top-down.
+Convention, not enforced: pass the primary action last, so it sits at the end
+of the row.
 
 Takes `className` and `children`.