@automattic/vip-design-system 2.20.3 → 2.20.5

package/.github/workflows/react-doctor.yml

@@ -0,0 +1,38 @@
+---
+name: React Doctor
+on:
+  pull_request:
+    branches: [trunk]
+    types: [opened, reopened, synchronize, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: react-doctor-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  react-doctor:
+    name: React Doctor
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Full history so the PR can be diffed against the trunk base.
+          fetch-depth: 0
+
+      - uses: millionco/react-doctor@547e1e4ecdb70315d81a91ec3605701d58616ee2 # v2.1.0
+        with:
+          # Advisory only: report findings but never fail the run / block merge.
+          blocking: none
+          # Only report issues this PR introduces versus the trunk base.
+          scope: changed
+          # Keep a single sticky summary comment that updates in place.
+          comment: true
+          # Avoid flooding the PR with inline comments / hitting comment limits.
+          review-comments: false
+          # No commit status (also keeps permissions to contents:read + PR write).
+          commit-status: false

package/build/system/Accordion/Accordion.js

@@ -57,9 +57,6 @@ export var Item = function Item(_ref) {
       '&:last-child': {
         borderBottomLeftRadius: 1,
         borderBottomRightRadius: 1
-      },
-      '&:focus-within': function focusWithin(theme) {
-        return theme.outline;
       }
     },
     children: children
@@ -108,6 +105,19 @@ export var Trigger = /*#__PURE__*/React.forwardRef(function (_ref2, forwardedRef
         },
         '&:hover': {
           backgroundColor: 'accordion.background.hover'
+        },
+        // Keyboard-only focus ring on the header (the trigger button
+        // fills the header). Rendered inset, reusing the shared
+        // focus-ring colors, because the parent Item has overflow:hidden
+        // for its rounded corners which would clip an outset ring.
+        '&:focus-visible': function focusVisible(theme) {
+          var _theme$outline;
+          var ring = (_theme$outline = theme.outline) == null ? void 0 : _theme$outline.boxShadow;
+          return ring ? {
+            boxShadow: ring.split(/,(?![^(]*\))/).map(function (layer) {
+              return "inset " + layer.trim();
+            }).join(', ')
+          } : {};
         }
       }, sx)
     }, props, {

package/build/system/Form/Input.styles.d.ts

@@ -11,7 +11,6 @@ export declare const inputBaseText = "input.text.default";
 export declare const inputBaseBackground = "input.background.default";
 export declare const baseControlFocusStyle: {
     '&:focus-visible': (theme: InputTheme) => Record<string, string> | undefined;
-    '&:focus-within': (theme: InputTheme) => Record<string, string> | undefined;
 };
 export declare const baseControlStyle: {
     '&:disabled': {
@@ -26,7 +25,6 @@ export declare const baseControlStyle: {
         opacity: number;
     };
     '&:focus-visible': (theme: InputTheme) => Record<string, string> | undefined;
-    '&:focus-within': (theme: InputTheme) => Record<string, string> | undefined;
     backgroundColor: string;
     color: string;
     borderRadius: number;

package/build/system/Form/Input.styles.js

@@ -11,9 +11,6 @@ export var inputBaseBackground = 'input.background.default';
 export var baseControlFocusStyle = {
   '&:focus-visible': function focusVisible(theme) {
     return theme.outline;
-  },
-  '&:focus-within': function focusWithin(theme) {
-    return theme.outline;
   }
 };
 export var baseControlStyle = _extends({}, baseControlBorderStyle, {

package/build/system/Form/Radio/styles.js

@@ -11,7 +11,7 @@ export var inputStyle = function inputStyle(variant) {
     clipPath: 'inset(50%)',
     width: RADIO_SIZE,
     height: RADIO_SIZE,
-    '&:focus ~ label:before': {
+    '&:focus-visible ~ label:before': {
       variant: 'outline',
       content: '""',
       border: '1px solid',

package/build/system/NewDialog/DialogTitle.js

@@ -28,8 +28,7 @@ export var DialogTitle = function DialogTitle(_ref) {
   return _jsx(DialogPrimitive.Title, {
     sx: {
       margin: 0,
-      fontSize: 3,
-      fontWeight: 'medium',
+      variant: 'text.h3',
       color: 'heading'
     },
     children: titleNode

package/build/system/Wizard/Wizard.d.ts

@@ -4,6 +4,7 @@ import React from 'react';
  * Internal dependencies
  */
 import { WizardStepProps } from './WizardStep';
+import { HeadingProps } from '../Heading/Heading';
 export interface WizardProps {
     /** The array of step configurations to render. */
     steps: WizardStepProps[];
@@ -42,6 +43,18 @@ export interface WizardProps {
      * @default 'table'
      */
     summaryAs?: 'table' | 'dl';
+    /**
+     * The heading variant (typographic style) applied to every step title. A step
+     * can override this with its own `titleVariant`.
+     * @default 'h3'
+     */
+    titleVariant?: HeadingProps['variant'];
+    /**
+     * The HTML heading element used for every step title, independent of its
+     * visual style — useful for keeping a correct document outline. A step can
+     * override this with its own `titleAs`. Defaults to the value of `titleVariant`.
+     */
+    titleAs?: HeadingProps['variant'];
 }
 /**
  * A multi-step wizard component that displays a sequence of steps with progress tracking.

package/build/system/Wizard/Wizard.js

@@ -32,7 +32,9 @@ export var Wizard = /*#__PURE__*/React.forwardRef(function (_ref, forwardRef) {
     _ref$showStepText = _ref.showStepText,
     showStepText = _ref$showStepText === void 0 ? true : _ref$showStepText,
     _ref$summaryAs = _ref.summaryAs,
-    summaryAs = _ref$summaryAs === void 0 ? 'table' : _ref$summaryAs;
+    summaryAs = _ref$summaryAs === void 0 ? 'table' : _ref$summaryAs,
+    titleVariant = _ref.titleVariant,
+    titleAs = _ref.titleAs;
   var _useState = useState(false),
     didMount = _useState[0],
     setDidMount = _useState[1];
@@ -52,7 +54,8 @@ export var Wizard = /*#__PURE__*/React.forwardRef(function (_ref, forwardRef) {
       var title = _ref2.title,
         subTitle = _ref2.subTitle,
         children = _ref2.children,
-        titleVariant = _ref2.titleVariant,
+        stepTitleVariant = _ref2.titleVariant,
+        stepTitleAs = _ref2.titleAs,
         summary = _ref2.summary,
         onChange = _ref2.onChange,
         actionLabel = _ref2.actionLabel,
@@ -68,7 +71,8 @@ export var Wizard = /*#__PURE__*/React.forwardRef(function (_ref, forwardRef) {
         totalSteps: steps.length,
         subTitle: subTitle,
         title: title,
-        titleVariant: titleVariant,
+        titleVariant: stepTitleVariant != null ? stepTitleVariant : titleVariant,
+        titleAs: stepTitleAs != null ? stepTitleAs : titleAs,
         summary: summary,
         onChange: onChange,
         shouldFocusTitle: titleAutofocus && didMount,

package/build/system/Wizard/Wizard.stories.d.ts

@@ -12,6 +12,13 @@ declare const _default: {
 export default _default;
 type Story = StoryObj<typeof Wizard>;
 export declare const Primary: Story;
+/**
+ * `titleVariant` (visual style) and `titleAs` (semantic HTML element) can be set
+ * once at the Wizard level so they apply to every step, avoiding repetition. Here
+ * all titles render as `h2` elements while keeping `h3` styling, and the last step
+ * overrides `titleAs` to `h4` to demonstrate per-step precedence.
+ */
+export declare const WizardTitleLevels: Story;
 export declare const Error: Story;
 export declare const Default: Story;
 export declare const WithTitleAutoFocus: Story;

package/build/system/Wizard/Wizard.stories.js

@@ -37,6 +37,32 @@ export var Primary = {
     }]
   }
 };
+
+/**
+ * `titleVariant` (visual style) and `titleAs` (semantic HTML element) can be set
+ * once at the Wizard level so they apply to every step, avoiding repetition. Here
+ * all titles render as `h2` elements while keeping `h3` styling, and the last step
+ * overrides `titleAs` to `h4` to demonstrate per-step precedence.
+ */
+export var WizardTitleLevels = {
+  args: {
+    activeStep: 0,
+    completed: [],
+    titleVariant: 'h3',
+    titleAs: 'h2',
+    steps: [{
+      title: 'Step One',
+      subTitle: 'Rendered as an h2 element with h3 styling.',
+      children: 'Step one content'
+    }, {
+      title: 'Step Two',
+      subTitle: 'Also an h2 element, inheriting the Wizard-level titleAs.'
+    }, {
+      title: 'Step Three (overrides titleAs)',
+      titleAs: 'h4'
+    }]
+  }
+};
 export var Error = {
   render: function render() {
     var steps = [{

package/build/system/Wizard/Wizard.test.js

@@ -116,4 +116,78 @@ describe('<Wizard /> error state', function () {
     }));
     expect(screen.getByText('Step instructions')).toBeInTheDocument();
   });
+});
+describe('<Wizard /> title element and style', function () {
+  it('renders step titles as h3 elements by default', function () {
+    var _renderWithTheme4 = renderWithTheme(_jsx(Wizard, {
+        activeStep: 0,
+        steps: steps
+      })),
+      container = _renderWithTheme4.container;
+    expect(container.querySelectorAll('h3')).toHaveLength(steps.length);
+  });
+  it('applies a Wizard-level titleAs element to every step', function () {
+    var _renderWithTheme5 = renderWithTheme(_jsx(Wizard, {
+        activeStep: 0,
+        steps: steps,
+        titleAs: "h2"
+      })),
+      container = _renderWithTheme5.container;
+    expect(container.querySelectorAll('h2')).toHaveLength(steps.length);
+    expect(container.querySelectorAll('h3')).toHaveLength(0);
+  });
+  it('lets a step override the Wizard-level titleAs', function () {
+    var overrideSteps = [{
+      title: 'Step One'
+    }, {
+      title: 'Step Two',
+      titleAs: 'h4'
+    }];
+    var _renderWithTheme6 = renderWithTheme(_jsx(Wizard, {
+        activeStep: 0,
+        steps: overrideSteps,
+        titleAs: "h2"
+      })),
+      container = _renderWithTheme6.container;
+
+    // One inherits the Wizard default (h2), the other overrides to h4.
+    expect(container.querySelectorAll('h2')).toHaveLength(1);
+    expect(container.querySelectorAll('h4')).toHaveLength(1);
+  });
+  it('keeps titleVariant styling while titleAs changes the element', function () {
+    var _renderWithTheme7 = renderWithTheme(_jsx(Wizard, {
+        activeStep: 0,
+        steps: [{
+          title: 'Only Step'
+        }],
+        titleVariant: "h3",
+        titleAs: "h2"
+      })),
+      container = _renderWithTheme7.container;
+
+    // The rendered element is an h2 that still carries the shared heading class
+    // (typographic variant is driven by titleVariant, not the element).
+    var heading = container.querySelector('h2.vip-heading-component');
+    expect(heading).toBeInTheDocument();
+  });
+  it('has no accessibility violations when using a custom title element', /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
+    var _renderWithTheme8, container, _t2;
+    return _regenerator().w(function (_context2) {
+      while (1) switch (_context2.n) {
+        case 0:
+          _renderWithTheme8 = renderWithTheme(_jsx(Wizard, {
+            activeStep: 0,
+            steps: steps,
+            titleAs: "h2"
+          })), container = _renderWithTheme8.container;
+          _t2 = expect;
+          _context2.n = 1;
+          return axe(container);
+        case 1:
+          _t2(_context2.v).toHaveNoViolations();
+        case 2:
+          return _context2.a(2);
+      }
+    }, _callee2);
+  })));
 });

package/build/system/Wizard/WizardStep.d.ts

@@ -25,10 +25,16 @@ export interface WizardStepProps {
     /** The title content displayed in the step header. */
     title: React.ReactNode;
     /**
-     * The heading variant used for the step title.
+     * The heading variant used for the step title. Controls the typographic style.
      * @default 'h3'
      */
     titleVariant?: HeadingProps['variant'];
+    /**
+     * The HTML heading element used to render the step title, independent of its
+     * visual style. Use this to keep a correct document outline (e.g. render an
+     * `h2` while keeping `h3` styling). Defaults to the value of `titleVariant`.
+     */
+    titleAs?: HeadingProps['variant'];
     /** A subtitle displayed below the title when the step is active. */
     subTitle?: React.ReactNode;
     /** The content rendered inside the step when it is active. */

package/build/system/Wizard/WizardStep.js

@@ -32,6 +32,7 @@ export var WizardStep = /*#__PURE__*/React.forwardRef(function (_ref, forwardRef
     shouldFocusTitle = _ref.shouldFocusTitle,
     _ref$titleVariant = _ref.titleVariant,
     titleVariant = _ref$titleVariant === void 0 ? 'h3' : _ref$titleVariant,
+    titleAs = _ref.titleAs,
     summary = _ref.summary,
     summaryTitle = _ref.summaryTitle,
     _ref$summaryAs = _ref.summaryAs,
@@ -113,6 +114,7 @@ export var WizardStep = /*#__PURE__*/React.forwardRef(function (_ref, forwardRef
       },
       children: [_jsxs(Heading, {
         variant: titleVariant,
+        as: titleAs != null ? titleAs : titleVariant,
         sx: {
           mb: 0,
           color: headingColor,

package/doctor.config.jsonc

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://react.doctor/schema/config.json",
+  "rules": {
+    // theme-ui `sx` prop is flagged as an unknown DOM attribute everywhere — pure noise
+    "react-doctor/no-unknown-property": "off"
+  },
+  "ignore": {
+    // Glob patterns excluded from ALL rules.
+    "files": [
+      // Design-token source + Figma tooling: generated/build-time code (incl. the intentional
+      // `eval()` in the responsive-type calculator), never shipped in the component bundle.
+      "tokens/**"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/vip-design-system",
-  "version": "2.20.3",
+  "version": "2.20.5",
   "repository": {
     "type": "git",
     "url": "https://github.com/Automattic/vip-design-system"

package/src/system/Accordion/Accordion.tsx

@@ -92,7 +92,6 @@ export const Item = ( { children, ...props }: AccordionItemProps ) => (
 				borderBottomLeftRadius: 1,
 				borderBottomRightRadius: 1,
 			},
-			'&:focus-within': ( theme: AccordionTheme ) => theme.outline,
 		} }
 	>
 		{ children }
@@ -136,6 +135,21 @@ export const Trigger = React.forwardRef< HTMLButtonElement, TriggerProps >(
 						'.vip-accordion-trigger-indicator': { transform: 'rotate(270deg)' },
 					},
 					'&:hover': { backgroundColor: 'accordion.background.hover' },
+					// Keyboard-only focus ring on the header (the trigger button
+					// fills the header). Rendered inset, reusing the shared
+					// focus-ring colors, because the parent Item has overflow:hidden
+					// for its rounded corners which would clip an outset ring.
+					'&:focus-visible': ( theme: AccordionTheme ) => {
+						const ring = theme.outline?.boxShadow;
+						return ring
+							? {
+									boxShadow: ring
+										.split( /,(?![^(]*\))/ )
+										.map( layer => `inset ${ layer.trim() }` )
+										.join( ', ' ),
+							  }
+							: {};
+					},
 					...sx,
 				} }
 				{ ...props }

package/src/system/Form/Input.styles.ts

@@ -14,7 +14,6 @@ export const inputBaseText = 'input.text.default';
 export const inputBaseBackground = 'input.background.default';
 export const baseControlFocusStyle = {
 	'&:focus-visible': ( theme: InputTheme ) => theme.outline,
-	'&:focus-within': ( theme: InputTheme ) => theme.outline,
 };
 
 export const baseControlStyle = {

package/src/system/Form/Radio/styles.ts

@@ -13,7 +13,7 @@ export const inputStyle = ( variant: string ): ThemeUIStyleObject => ( {
 	clipPath: 'inset(50%)',
 	width: RADIO_SIZE,
 	height: RADIO_SIZE,
-	'&:focus ~ label:before': {
+	'&:focus-visible ~ label:before': {
 		variant: 'outline',
 		content: '""',
 		border: '1px solid',

package/src/system/NewDialog/DialogTitle.tsx

@@ -34,9 +34,7 @@ export const DialogTitle: React.FC< DialogTitleProps > = ( { title, hidden = fal
 	}
 
 	return (
-		<DialogPrimitive.Title
-			sx={ { margin: 0, fontSize: 3, fontWeight: 'medium', color: 'heading' } }
-		>
+		<DialogPrimitive.Title sx={ { margin: 0, variant: 'text.h3', color: 'heading' } }>
 			{ titleNode }
 		</DialogPrimitive.Title>
 	);

package/src/system/Wizard/Wizard.stories.tsx

@@ -47,6 +47,36 @@ export const Primary: Story = {
 	},
 };
 
+/**
+ * `titleVariant` (visual style) and `titleAs` (semantic HTML element) can be set
+ * once at the Wizard level so they apply to every step, avoiding repetition. Here
+ * all titles render as `h2` elements while keeping `h3` styling, and the last step
+ * overrides `titleAs` to `h4` to demonstrate per-step precedence.
+ */
+export const WizardTitleLevels: Story = {
+	args: {
+		activeStep: 0,
+		completed: [],
+		titleVariant: 'h3',
+		titleAs: 'h2',
+		steps: [
+			{
+				title: 'Step One',
+				subTitle: 'Rendered as an h2 element with h3 styling.',
+				children: 'Step one content',
+			},
+			{
+				title: 'Step Two',
+				subTitle: 'Also an h2 element, inheriting the Wizard-level titleAs.',
+			},
+			{
+				title: 'Step Three (overrides titleAs)',
+				titleAs: 'h4',
+			},
+		],
+	},
+};
+
 export const Error: Story = {
 	render: () => {
 		const steps: WizardStepProps[] = [

package/src/system/Wizard/Wizard.test.tsx

@@ -77,3 +77,55 @@ describe( '<Wizard /> error state', () => {
 		expect( screen.getByText( 'Step instructions' ) ).toBeInTheDocument();
 	} );
 } );
+
+describe( '<Wizard /> title element and style', () => {
+	it( 'renders step titles as h3 elements by default', () => {
+		const { container } = renderWithTheme( <Wizard activeStep={ 0 } steps={ steps } /> );
+
+		expect( container.querySelectorAll( 'h3' ) ).toHaveLength( steps.length );
+	} );
+
+	it( 'applies a Wizard-level titleAs element to every step', () => {
+		const { container } = renderWithTheme(
+			<Wizard activeStep={ 0 } steps={ steps } titleAs="h2" />
+		);
+
+		expect( container.querySelectorAll( 'h2' ) ).toHaveLength( steps.length );
+		expect( container.querySelectorAll( 'h3' ) ).toHaveLength( 0 );
+	} );
+
+	it( 'lets a step override the Wizard-level titleAs', () => {
+		const overrideSteps = [ { title: 'Step One' }, { title: 'Step Two', titleAs: 'h4' as const } ];
+		const { container } = renderWithTheme(
+			<Wizard activeStep={ 0 } steps={ overrideSteps } titleAs="h2" />
+		);
+
+		// One inherits the Wizard default (h2), the other overrides to h4.
+		expect( container.querySelectorAll( 'h2' ) ).toHaveLength( 1 );
+		expect( container.querySelectorAll( 'h4' ) ).toHaveLength( 1 );
+	} );
+
+	it( 'keeps titleVariant styling while titleAs changes the element', () => {
+		const { container } = renderWithTheme(
+			<Wizard
+				activeStep={ 0 }
+				steps={ [ { title: 'Only Step' } ] }
+				titleVariant="h3"
+				titleAs="h2"
+			/>
+		);
+
+		// The rendered element is an h2 that still carries the shared heading class
+		// (typographic variant is driven by titleVariant, not the element).
+		const heading = container.querySelector( 'h2.vip-heading-component' );
+		expect( heading ).toBeInTheDocument();
+	} );
+
+	it( 'has no accessibility violations when using a custom title element', async () => {
+		const { container } = renderWithTheme(
+			<Wizard activeStep={ 0 } steps={ steps } titleAs="h2" />
+		);
+
+		expect( await axe( container ) ).toHaveNoViolations();
+	} );
+} );

package/src/system/Wizard/Wizard.tsx

@@ -11,6 +11,7 @@ import React, { useLayoutEffect, useState } from 'react';
  */
 import { WizardStepProps } from './WizardStep';
 import { Box, WizardStep } from '..';
+import { HeadingProps } from '../Heading/Heading';
 
 export interface WizardProps {
 	/** The array of step configurations to render. */
@@ -50,6 +51,18 @@ export interface WizardProps {
 	 * @default 'table'
 	 */
 	summaryAs?: 'table' | 'dl';
+	/**
+	 * The heading variant (typographic style) applied to every step title. A step
+	 * can override this with its own `titleVariant`.
+	 * @default 'h3'
+	 */
+	titleVariant?: HeadingProps[ 'variant' ];
+	/**
+	 * The HTML heading element used for every step title, independent of its
+	 * visual style — useful for keeping a correct document outline. A step can
+	 * override this with its own `titleAs`. Defaults to the value of `titleVariant`.
+	 */
+	titleAs?: HeadingProps[ 'variant' ];
 }
 
 /**
@@ -68,6 +81,8 @@ export const Wizard = React.forwardRef< HTMLDivElement, WizardProps >(
 			titleAutofocus = false,
 			showStepText = true,
 			summaryAs = 'table',
+			titleVariant,
+			titleAs,
 		},
 		forwardRef
 	) => {
@@ -88,7 +103,8 @@ export const Wizard = React.forwardRef< HTMLDivElement, WizardProps >(
 							title,
 							subTitle,
 							children,
-							titleVariant,
+							titleVariant: stepTitleVariant,
+							titleAs: stepTitleAs,
 							summary,
 							onChange,
 							actionLabel,
@@ -108,7 +124,8 @@ export const Wizard = React.forwardRef< HTMLDivElement, WizardProps >(
 							totalSteps={ steps.length }
 							subTitle={ subTitle }
 							title={ title }
-							titleVariant={ titleVariant }
+							titleVariant={ stepTitleVariant ?? titleVariant }
+							titleAs={ stepTitleAs ?? titleAs }
 							summary={ summary }
 							onChange={ onChange }
 							shouldFocusTitle={ titleAutofocus && didMount }

package/src/system/Wizard/WizardStep.tsx

@@ -35,10 +35,16 @@ export interface WizardStepProps {
 	/** The title content displayed in the step header. */
 	title: React.ReactNode;
 	/**
-	 * The heading variant used for the step title.
+	 * The heading variant used for the step title. Controls the typographic style.
 	 * @default 'h3'
 	 */
 	titleVariant?: HeadingProps[ 'variant' ];
+	/**
+	 * The HTML heading element used to render the step title, independent of its
+	 * visual style. Use this to keep a correct document outline (e.g. render an
+	 * `h2` while keeping `h3` styling). Defaults to the value of `titleVariant`.
+	 */
+	titleAs?: HeadingProps[ 'variant' ];
 	/** A subtitle displayed below the title when the step is active. */
 	subTitle?: React.ReactNode;
 	/** The content rendered inside the step when it is active. */
@@ -106,6 +112,7 @@ export const WizardStep = React.forwardRef< HTMLDivElement, WizardStepProps >(
 			totalSteps,
 			shouldFocusTitle,
 			titleVariant = 'h3',
+			titleAs,
 			summary,
 			summaryTitle,
 			summaryAs = 'table',
@@ -188,6 +195,7 @@ export const WizardStep = React.forwardRef< HTMLDivElement, WizardStepProps >(
 				<Flex sx={ { alignItems: 'center' } }>
 					<Heading
 						variant={ titleVariant }
+						as={ titleAs ?? titleVariant }
 						sx={ {
 							mb: 0,
 							color: headingColor,