@wordpress/eslint-plugin 24.4.1-next.v.202603161435.0 → 24.5.0

package/rules/__tests__/no-unknown-ds-tokens.js

@@ -39,6 +39,9 @@ ruleTester.run( 'no-unknown-ds-tokens', rule, {
 		{
 			code: '`var(--wpds-color-fg-content-neutral) ${ suffix }`',
 		},
+		{
+			code: `const style = { '--wpds-color-fg-content-neutral': 'red' };`,
+		},
 	],
 	invalid: [
 		{
@@ -142,5 +145,60 @@ ruleTester.run( 'no-unknown-ds-tokens', rule, {
 				},
 			],
 		},
+		{
+			code: `const token = '--wpds-color-fg-content-neutral';`,
+			errors: [
+				{
+					messageId: 'bareToken',
+					data: {
+						tokenNames: "'--wpds-color-fg-content-neutral'",
+					},
+				},
+			],
+		},
+		{
+			code: 'const token = `--wpds-color-fg-content-neutral`;',
+			errors: [
+				{
+					messageId: 'bareToken',
+					data: {
+						tokenNames: "'--wpds-color-fg-content-neutral'",
+					},
+				},
+			],
+		},
+		{
+			code: '<div style={ { gap: `--wpds-color-fg-content-neutral` } } />',
+			errors: [
+				{
+					messageId: 'bareToken',
+					data: {
+						tokenNames: "'--wpds-color-fg-content-neutral'",
+					},
+				},
+			],
+		},
+		{
+			code: '`${ prefix }: --wpds-color-fg-content-neutral`',
+			errors: [
+				{
+					messageId: 'bareToken',
+					data: {
+						tokenNames: "'--wpds-color-fg-content-neutral'",
+					},
+				},
+			],
+		},
+		{
+			code: '`var(--wpds-color-fg-content-neutral) --wpds-color-fg-content-neutral ${ x }`',
+			errors: [
+				{
+					messageId: 'bareToken',
+					data: {
+						tokenNames: "'--wpds-color-fg-content-neutral'",
+					},
+				},
+			],
+		},
 	],
 } );

package/rules/__tests__/no-unmerged-classname.js

@@ -0,0 +1,174 @@
+import { RuleTester } from 'eslint';
+import rule from '../no-unmerged-classname';
+
+const ruleTester = new RuleTester( {
+	parserOptions: {
+		sourceType: 'module',
+		ecmaVersion: 2018,
+		ecmaFeatures: {
+			jsx: true,
+		},
+	},
+} );
+
+ruleTester.run( 'no-unmerged-classname', rule, {
+	valid: [
+		{
+			// className destructured and merged via clsx
+			code: `
+				function Foo( { className, ...restProps } ) {
+					return <div className={ clsx( styles.foo, className ) } { ...restProps } />;
+				}
+			`,
+		},
+		{
+			// className destructured and used directly
+			code: `
+				function Foo( { className, ...restProps } ) {
+					return <div className={ className } { ...restProps } />;
+				}
+			`,
+		},
+		{
+			// className merged via template literal
+			code: `
+				function Foo( { className, ...restProps } ) {
+					return <div className={ \`\${styles.foo} \${className}\` } { ...restProps } />;
+				}
+			`,
+		},
+		{
+			// className merged via string concatenation
+			code: `
+				function Foo( { className, ...restProps } ) {
+					return <div className={ styles.foo + ' ' + className } { ...restProps } />;
+				}
+			`,
+		},
+		{
+			// No spread — internal elements are fine
+			code: `
+				function Foo( { ...restProps } ) {
+					return <div className={ styles.foo } />;
+				}
+			`,
+		},
+		{
+			// No className attribute at all
+			code: `
+				function Foo( { ...restProps } ) {
+					return <div { ...restProps } />;
+				}
+			`,
+		},
+		{
+			// No rest element in destructuring
+			code: `
+				function Foo( { padding } ) {
+					return <div className={ styles.foo } { ...someOtherSpread } />;
+				}
+			`,
+		},
+		{
+			// Arrow function component
+			code: `
+				const Foo = ( { className, ...restProps } ) => (
+					<div className={ clsx( styles.foo, className ) } { ...restProps } />
+				);
+			`,
+		},
+		{
+			// className in conditional expression
+			code: `
+				function Foo( { className, isActive, ...restProps } ) {
+					return <div className={ isActive ? className : styles.inactive } { ...restProps } />;
+				}
+			`,
+		},
+		{
+			// className in logical expression
+			code: `
+				function Foo( { className, ...restProps } ) {
+					return <div className={ className || styles.default } { ...restProps } />;
+				}
+			`,
+		},
+		{
+			// className forwarded on a different element than the one with spread
+			code: `
+				function Foo( { className, style, ...props } ) {
+					return (
+						<Outer className={ clsx( styles.outer, className ) } style={ style }>
+							<Inner className={ styles.inner } { ...props } />
+						</Outer>
+					);
+				}
+			`,
+		},
+		{
+			// className destructured but not referenced — not this rule's concern
+			// (would be caught by no-unused-vars)
+			code: `
+				function Foo( { className, ...restProps } ) {
+					return <div className={ clsx( styles.foo ) } { ...restProps } />;
+				}
+			`,
+		},
+	],
+	invalid: [
+		{
+			// className not destructured, sits in rest props
+			code: `
+				function Foo( { padding, ...rest } ) {
+					return <div className={ clsx( styles.foo ) } { ...rest } />;
+				}
+			`,
+			errors: [ { messageId: 'noUnmergedClassname' } ],
+		},
+		{
+			// className not destructured, no other named props
+			code: `
+				function Foo( { ...others } ) {
+					return <div className={ styles.foo } { ...others } />;
+				}
+			`,
+			errors: [ { messageId: 'noUnmergedClassname' } ],
+		},
+		{
+			// Arrow function, className not destructured
+			code: `
+				const Foo = ( { padding, ...props } ) => (
+					<div className={ styles.foo } { ...props } />
+				);
+			`,
+			errors: [ { messageId: 'noUnmergedClassname' } ],
+		},
+		{
+			// Named function expression
+			code: `
+				const Foo = function Foo( { padding, ...rest } ) {
+					return <div className={ styles.foo } { ...rest } />;
+				};
+			`,
+			errors: [ { messageId: 'noUnmergedClassname' } ],
+		},
+		{
+			// forwardRef pattern — className not destructured
+			code: `
+				const Foo = forwardRef( function Foo( { padding, ...restProps }, ref ) {
+					return <div ref={ ref } className={ clsx( styles.foo ) } { ...restProps } />;
+				} );
+			`,
+			errors: [ { messageId: 'noUnmergedClassname' } ],
+		},
+		{
+			// Props not destructured — spread of entire props object
+			code: `
+				function Foo( props ) {
+					return <div className={ styles.foo } { ...props } />;
+				}
+			`,
+			errors: [ { messageId: 'noUnmergedClassname' } ],
+		},
+	],
+} );

package/rules/__tests__/no-unsafe-wp-apis.js

@@ -64,7 +64,6 @@ ruleTester.run( 'no-unsafe-wp-apis', rule, {
 				{
 					message: `Usage of \`__experimentalUnsafe\` from \`@wordpress/package\` is not allowed.
 See https://developer.wordpress.org/block-editor/contributors/develop/coding-guidelines/#experimental-and-unstable-apis for details.`,
-					type: 'ImportSpecifier',
 				},
 			],
 		},
@@ -75,7 +74,6 @@ See https://developer.wordpress.org/block-editor/contributors/develop/coding-gui
 				{
 					message: `Usage of \`__experimentalSafe\` from \`@wordpress/unsafe\` is not allowed.
 See https://developer.wordpress.org/block-editor/contributors/develop/coding-guidelines/#experimental-and-unstable-apis for details.`,
-					type: 'ImportSpecifier',
 				},
 			],
 		},
@@ -86,7 +84,6 @@ See https://developer.wordpress.org/block-editor/contributors/develop/coding-gui
 				{
 					message: `Usage of \`__experimentalSafe\` from \`@wordpress/unsafe\` is not allowed.
 See https://developer.wordpress.org/block-editor/contributors/develop/coding-guidelines/#experimental-and-unstable-apis for details.`,
-					type: 'ImportSpecifier',
 				},
 			],
 		},
@@ -97,7 +94,6 @@ See https://developer.wordpress.org/block-editor/contributors/develop/coding-gui
 				{
 					message: `Usage of \`__experimentalUnsafe\` from \`@wordpress/package\` is not allowed.
 See https://developer.wordpress.org/block-editor/contributors/develop/coding-guidelines/#experimental-and-unstable-apis for details.`,
-					type: 'ImportSpecifier',
 				},
 			],
 		},
@@ -108,7 +104,6 @@ See https://developer.wordpress.org/block-editor/contributors/develop/coding-gui
 				{
 					message: `Usage of \`__unstableFeature\` from \`@wordpress/package\` is not allowed.
 See https://developer.wordpress.org/block-editor/contributors/develop/coding-guidelines/#experimental-and-unstable-apis for details.`,
-					type: 'ImportSpecifier',
 				},
 			],
 		},

package/rules/__tests__/use-recommended-components.js

@@ -41,7 +41,6 @@ ruleTester.run( 'use-recommended-components', rule, {
 				{
 					message:
 						'`SomeComponent` from `@wordpress/ui` is not yet recommended for use in a WordPress environment.',
-					type: 'ImportSpecifier',
 				},
 			],
 		},
@@ -51,12 +50,10 @@ ruleTester.run( 'use-recommended-components', rule, {
 				{
 					message:
 						'`Foo` from `@wordpress/ui` is not yet recommended for use in a WordPress environment.',
-					type: 'ImportSpecifier',
 				},
 				{
 					message:
 						'`Bar` from `@wordpress/ui` is not yet recommended for use in a WordPress environment.',
-					type: 'ImportSpecifier',
 				},
 			],
 		},
@@ -67,7 +64,6 @@ ruleTester.run( 'use-recommended-components', rule, {
 				{
 					message:
 						'__experimentalZStack is planned for deprecation. Write your own CSS instead.',
-					type: 'ImportSpecifier',
 				},
 			],
 		},
@@ -77,7 +73,6 @@ ruleTester.run( 'use-recommended-components', rule, {
 				{
 					message:
 						'__experimentalZStack is planned for deprecation. Write your own CSS instead.',
-					type: 'ImportSpecifier',
 				},
 			],
 		},

package/rules/data-no-store-string-literals.js

@@ -31,7 +31,7 @@ function arrayLast( array ) {
 function getReferences( context, specifiers ) {
 	const variables = specifiers.reduce(
 		( acc, specifier ) =>
-			acc.concat( context.getDeclaredVariables( specifier ) ),
+			acc.concat( context.sourceCode.getDeclaredVariables( specifier ) ),
 		[]
 	);
 	const references = variables.reduce(
@@ -58,7 +58,9 @@ function collectAllNodesFromCallbackFunctions( context, node ) {
 		( acc, { identifier: { parent } } ) =>
 			parent && parent.arguments && parent.arguments.length > 0
 				? acc.concat(
-						context.getDeclaredVariables( parent.arguments[ 0 ] )
+						context.sourceCode.getDeclaredVariables(
+							parent.arguments[ 0 ]
+						)
 				  )
 				: acc,
 		[]
@@ -153,9 +155,10 @@ function getFixes( fixer, context, callNode ) {
 		fixer.replaceText( callNode.arguments[ 0 ], variableName ),
 	];
 
-	const imports = context
-		.getAncestors()[ 0 ]
-		.body.filter( ( node ) => node.type === 'ImportDeclaration' );
+	const ancestors = context.sourceCode.getAncestors( callNode );
+	const imports = ancestors[ 0 ].body.filter(
+		( node ) => node.type === 'ImportDeclaration'
+	);
 	const packageImports = imports.filter(
 		( node ) => node.source.value === importName
 	);

package/rules/dependency-group.js

@@ -22,7 +22,8 @@ module.exports = {
 	},
 	create( context ) {
 		const mode = context.options[ 0 ] || 'always';
-		const comments = context.getSourceCode().getAllComments();
+		const sourceCode = context.sourceCode;
+		const comments = sourceCode.getAllComments();
 
 		/**
 		 * Locality classification of an import, one of "External",
@@ -194,9 +195,7 @@ module.exports = {
 										return null;
 									}
 
-									const text = context
-										.getSourceCode()
-										.getText();
+									const text = sourceCode.getText();
 
 									// Trim preceding and trailing newlines.
 									let [ start, end ] = comment.range;

package/rules/i18n-translator-comments.js

@@ -61,6 +61,7 @@ function extractTranslatorKeys( commentText ) {
 module.exports = {
 	meta: {
 		type: 'problem',
+		schema: [],
 		messages: {
 			missing:
 				'Translation function with placeholders is missing preceding translator comment',
@@ -71,6 +72,7 @@ module.exports = {
 		},
 	},
 	create( context ) {
+		const sourceCode = context.sourceCode;
 		return {
 			CallExpression( node ) {
 				const {
@@ -107,7 +109,7 @@ module.exports = {
 					return;
 				}
 
-				const comments = context.getCommentsBefore( node ).slice();
+				const comments = sourceCode.getCommentsBefore( node ).slice();
 
 				let parentNode = parent;
 
@@ -123,7 +125,9 @@ module.exports = {
 					parentNode.type !== 'Program' &&
 					Math.abs( parentNode.loc.start.line - currentLine ) <= 1
 				) {
-					comments.push( ...context.getCommentsBefore( parentNode ) );
+					comments.push(
+						...sourceCode.getCommentsBefore( parentNode )
+					);
 					parentNode = parentNode.parent;
 				}
 

package/rules/no-dom-globals-in-constructor.js

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+const { createDOMGlobalRule } = require( '../utils/dom-globals' );
+
+module.exports = createDOMGlobalRule( {
+	description: 'Disallow use of DOM globals in class constructors',
+	message:
+		"Use of DOM global '{{name}}' is forbidden in class constructors, consider moving this to componentDidMount() or equivalent for non React components",
+	test( scope ) {
+		if ( scope.block?.parent ) {
+			const { type, kind } = scope.block.parent;
+			return type === 'MethodDefinition' && kind === 'constructor';
+		}
+		return false;
+	},
+} );

package/rules/no-dom-globals-in-module-scope.js

@@ -0,0 +1,12 @@
+/**
+ * Internal dependencies
+ */
+const { createDOMGlobalRule } = require( '../utils/dom-globals' );
+
+module.exports = createDOMGlobalRule( {
+	description: 'Disallow use of DOM globals in module scope',
+	message: "Use of DOM global '{{name}}' is forbidden in module scope",
+	test( scope ) {
+		return scope.type === 'module' || scope.type === 'global';
+	},
+} );

package/rules/no-dom-globals-in-react-cc-render.js

@@ -0,0 +1,26 @@
+/**
+ * Internal dependencies
+ */
+const {
+	createDOMGlobalRule,
+	isReturnValueJSX,
+} = require( '../utils/dom-globals' );
+
+module.exports = createDOMGlobalRule( {
+	description:
+		'Disallow use of DOM globals in render() method of a React class component',
+	message:
+		"Use of DOM global '{{name}}' is forbidden in render(), consider moving this to componentDidMount()",
+	test( scope ) {
+		if ( scope.block?.parent ) {
+			const { type, kind, key } = scope.block.parent;
+			return (
+				type === 'MethodDefinition' &&
+				kind === 'method' &&
+				key.name === 'render' &&
+				isReturnValueJSX( scope )
+			);
+		}
+		return false;
+	},
+} );

package/rules/no-dom-globals-in-react-fc.js

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+const {
+	createDOMGlobalRule,
+	isReturnValueJSX,
+} = require( '../utils/dom-globals' );
+
+module.exports = createDOMGlobalRule( {
+	description:
+		'Disallow use of DOM globals in the render cycle of a React function component',
+	message:
+		"Use of DOM global '{{name}}' is forbidden in the render-cycle of a React FC, consider moving this inside useEffect()",
+	test( scope ) {
+		return isReturnValueJSX( scope );
+	},
+} );

package/rules/no-i18n-in-save.js

@@ -22,7 +22,7 @@ module.exports = {
 	},
 	create( context ) {
 		let saveFunctionDepth = 0;
-		const filename = context.getFilename();
+		const filename = context.filename;
 
 		// Skip deprecated files as they preserve old behavior including translation functions
 		const normalizedFilename = filename.replace( /\\/g, '/' );

package/rules/no-setting-ds-tokens.js

@@ -3,7 +3,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 		type: 'problem',
 		docs: {
 			description:
-				'Disallow setting any CSS custom property beginning with --wpds- in inline styles',
+				'Disallow setting any CSS custom property beginning with --wpds-',
 		},
 		schema: [],
 		messages: {
@@ -14,9 +14,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 	create( context ) {
 		return {
 			/** @param {import('estree').Property} node */
-			'JSXAttribute[name.name="style"] ObjectExpression > Property[key.value=/^--wpds-/]'(
-				node
-			) {
+			'ObjectExpression > Property[key.value=/^--wpds-/]'( node ) {
 				context.report( {
 					node: node.key,
 					messageId: 'disallowedSet',

package/rules/no-unknown-ds-tokens.js

@@ -4,35 +4,41 @@ const tokenList = tokenListModule.default || tokenListModule;
 const DS_TOKEN_PREFIX = 'wpds-';
 
 /**
- * Extracts all unique CSS custom properties (variables) from a given CSS value string,
- * including those in fallback positions, optionally filtering by a specific prefix.
+ * Single-pass extraction that finds all `--prefix-*` tokens in a CSS value
+ * string and classifies each occurrence as `var()`-wrapped or bare.
  *
- * @param {string} value       - The CSS value string to search for variables.
+ * @param {string} value       - The CSS value string to search.
  * @param {string} [prefix=''] - Optional prefix to filter variables (e.g., 'wpds-').
- * @return {Set<string>} A Set of unique matched CSS variable names (e.g., Set { '--wpds-token' }).
+ * @return {{ tokens: Set<string>, bare: Set<string> }}
+ *   `tokens` — every unique matched token;
+ *   `bare`   — the subset that appeared at least once without a `var()` wrapper.
  *
  * @example
- * extractCSSVariables(
- *   'border: 1px solid var(--wpds-border-color, var(--wpds-border-fallback)); ' +
- *   'color: var(--wpds-color-fg, black); ' +
- *   'background: var(--unrelated-bg);',
- *   'wpds'
+ * classifyTokens(
+ *   'var(--wpds-color-fg) --wpds-color-bg',
+ *   'wpds-'
  * );
- * // → Set { '--wpds-border-color', '--wpds-border-fallback', '--wpds-color-fg' }
+ * // → { tokens: Set {'--wpds-color-fg','--wpds-color-bg'},
+ * //     bare:   Set {'--wpds-color-bg'} }
  */
-function extractCSSVariables( value, prefix = '' ) {
-	const regex = /--[\w-]+/g;
-	const variables = new Set();
+function classifyTokens( value, prefix = '' ) {
+	const regex = new RegExp(
+		`(?:^|[^\\w])(var\\(\\s*)?(--${ prefix }[\\w-]+)`,
+		'g'
+	);
+	const tokens = new Set();
+	const bare = new Set();
 
 	let match;
 	while ( ( match = regex.exec( value ) ) !== null ) {
-		const variableName = match[ 0 ];
-		if ( variableName.startsWith( `--${ prefix }` ) ) {
-			variables.add( variableName );
+		const token = match[ 2 ];
+		tokens.add( token );
+		if ( ! match[ 1 ] ) {
+			bare.add( token );
 		}
 	}
 
-	return variables;
+	return { tokens, bare };
 }
 
 const knownTokens = new Set( tokenList );
@@ -50,6 +56,8 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 				'The following CSS variables are not valid Design System tokens: {{ tokenNames }}',
 			dynamicToken:
 				'Design System tokens must not be dynamically constructed, as they cannot be statically verified for correctness or processed automatically to inject fallbacks.',
+			bareToken:
+				'Design System tokens must be wrapped in `var()` for build-time fallback injection to work: {{ tokenNames }}',
 		},
 	},
 	create( context ) {
@@ -71,6 +79,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 			[ dynamicTemplateLiteralAST ]( node ) {
 				let hasDynamic = false;
 				const unknownTokens = [];
+				const bareTokens = [];
 
 				for ( const quasi of node.quasis ) {
 					const raw = quasi.value.raw;
@@ -84,7 +93,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						hasDynamic = true;
 					}
 
-					const tokens = extractCSSVariables(
+					const { tokens, bare } = classifyTokens(
 						value,
 						DS_TOKEN_PREFIX
 					);
@@ -95,12 +104,15 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						const endMatch = value.match( /(--([\w-]+))$/ );
 						if ( endMatch ) {
 							tokens.delete( endMatch[ 1 ] );
+							bare.delete( endMatch[ 1 ] );
 						}
 					}
 
 					for ( const token of tokens ) {
 						if ( ! knownTokens.has( token ) ) {
 							unknownTokens.push( token );
+						} else if ( bare.has( token ) ) {
+							bareTokens.push( token );
 						}
 					}
 				}
@@ -123,6 +135,18 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						},
 					} );
 				}
+
+				if ( bareTokens.length > 0 ) {
+					context.report( {
+						node,
+						messageId: 'bareToken',
+						data: {
+							tokenNames: bareTokens
+								.map( ( token ) => `'${ token }'` )
+								.join( ', ' ),
+						},
+					} );
+				}
 			},
 			/** @param {import('estree').Literal | import('estree').TemplateElement} node */
 			[ staticTokensAST ]( node ) {
@@ -145,7 +169,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 					return;
 				}
 
-				const usedTokens = extractCSSVariables(
+				const { tokens: usedTokens, bare } = classifyTokens(
 					computedValue,
 					DS_TOKEN_PREFIX
 				);
@@ -164,6 +188,31 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						},
 					} );
 				}
+
+				// Skip bare-token check for property keys
+				// (e.g. `{ '--wpds-token': value }` declaring a custom property).
+				const isPropertyKey =
+					node.parent?.type === 'Property' &&
+					node.parent.key === node;
+
+				if ( ! isPropertyKey ) {
+					const bareTokens = [ ...usedTokens ].filter(
+						( token ) =>
+							knownTokens.has( token ) && bare.has( token )
+					);
+
+					if ( bareTokens.length > 0 ) {
+						context.report( {
+							node,
+							messageId: 'bareToken',
+							data: {
+								tokenNames: bareTokens
+									.map( ( token ) => `'${ token }'` )
+									.join( ', ' ),
+							},
+						} );
+					}
+				}
 			},
 		};
 	},