@wordpress/eslint-plugin 24.0.1-next.ba3aee3a2.0 → 24.1.0

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

@@ -0,0 +1,46 @@
+import { RuleTester } from 'eslint';
+import rule from '../no-setting-ds-tokens';
+
+const ruleTester = new RuleTester( {
+	parserOptions: {
+		ecmaVersion: 6,
+		ecmaFeatures: {
+			jsx: true,
+		},
+	},
+} );
+
+ruleTester.run( 'no-setting-ds-tokens', rule, {
+	valid: [
+		{
+			code: `<div style={ { '--my-custom-prop': 'value' } } />`,
+		},
+		{
+			code: `<div style={ { color: 'var(--wpds-color-fg-content-neutral)' } } />`,
+		},
+		{
+			code: `<div style={ { '--other-prefix-token': '10px' } } />`,
+		},
+		{
+			code: `<div style={ { margin: '10px' } } />`,
+		},
+	],
+	invalid: [
+		{
+			code: `<div style={ { '--wpds-color-fg-content-neutral': 'red' } } />`,
+			errors: [
+				{
+					messageId: 'disallowedSet',
+				},
+			],
+		},
+		{
+			code: `<div style={ { '--wpds-font-size-md': '10px', color: 'blue' } } />`,
+			errors: [
+				{
+					messageId: 'disallowedSet',
+				},
+			],
+		},
+	],
+} );

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

@@ -0,0 +1,60 @@
+import { RuleTester } from 'eslint';
+import rule from '../no-unknown-ds-tokens';
+
+const ruleTester = new RuleTester( {
+	parserOptions: {
+		ecmaVersion: 6,
+		ecmaFeatures: {
+			jsx: true,
+		},
+	},
+} );
+
+ruleTester.run( 'no-unknown-ds-tokens', rule, {
+	valid: [
+		{
+			code: `<div style={ { color: 'var(--my-custom-prop)' } } />`,
+		},
+		{
+			code: `<div style={ { color: 'blue' } } />`,
+		},
+		{
+			code: `<div style={ { color: 'var(--other-prefix-token)' } } />`,
+		},
+		{
+			code: `<div style={ { color: 'var(--wpds-color-fg-content-neutral)' } } />`,
+		},
+		{
+			code: '<div style={ { color: `var(--wpds-color-fg-content-neutral)` } } />',
+		},
+	],
+	invalid: [
+		{
+			code: `<div style={ { color: 'var(--wpds-nonexistent-token)' } } />`,
+			errors: [
+				{
+					messageId: 'onlyKnownTokens',
+				},
+			],
+		},
+		{
+			code: `<div style={ { color: 'var(--wpds-fake-color, var(--wpds-also-fake))' } } />`,
+			errors: [
+				{
+					messageId: 'onlyKnownTokens',
+					data: {
+						tokenNames: "'--wpds-fake-color', '--wpds-also-fake'",
+					},
+				},
+			],
+		},
+		{
+			code: '<div style={ { color: `var(--wpds-nonexistent)` } } />',
+			errors: [
+				{
+					messageId: 'onlyKnownTokens',
+				},
+			],
+		},
+	],
+} );

package/rules/components-no-missing-40px-size-prop.js

@@ -0,0 +1,327 @@
+const { hasTruthyJsxAttribute } = require( '../utils' );
+
+/**
+ * Enforces that specific components from @wordpress/components include the
+ * `__next40pxDefaultSize` prop.
+ *
+ * @type {import('eslint').Rule.RuleModule}
+ */
+
+/**
+ * Components that require the __next40pxDefaultSize prop.
+ * These can be exempted if they have a non-default `size` prop.
+ */
+const COMPONENTS_REQUIRING_40PX = new Set( [
+	'BorderBoxControl',
+	'BorderControl',
+	'BoxControl',
+	'Button',
+	'ClipboardButton',
+	'ComboboxControl',
+	'CustomSelectControl',
+	'FontAppearanceControl',
+	'FontFamilyControl',
+	'FontSizePicker',
+	'FormTokenField',
+	'IconButton',
+	'InputControl',
+	'LetterSpacingControl',
+	'LineHeightControl',
+	'NumberControl',
+	'Radio',
+	'RangeControl',
+	'SelectControl',
+	'TextControl',
+	'TreeSelect',
+	'ToggleGroupControl',
+	'UnitControl',
+] );
+
+/**
+ * Components that can use the `render` prop as an alternative to __next40pxDefaultSize.
+ */
+const COMPONENTS_WITH_RENDER_EXEMPTION = new Set( [ 'FormFileUpload' ] );
+
+/**
+ * All tracked component names for path-based detection.
+ */
+const ALL_TRACKED_COMPONENTS = new Set( [
+	...COMPONENTS_REQUIRING_40PX,
+	...COMPONENTS_WITH_RENDER_EXEMPTION,
+] );
+
+module.exports = {
+	meta: {
+		type: 'problem',
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					checkLocalImports: {
+						type: 'boolean',
+						description:
+							'When true, also checks components imported from relative paths (for use inside @wordpress/components package).',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		messages: {
+			missingProp:
+				'{{ component }} should have the `__next40pxDefaultSize` prop when using the default size.',
+			missingPropFormFileUpload:
+				'FormFileUpload should have the `__next40pxDefaultSize` prop to opt-in to the new default size.',
+		},
+	},
+	create( context ) {
+		const checkLocalImports =
+			context.options[ 0 ]?.checkLocalImports ?? false;
+
+		// Track local names of components imported from @wordpress/components
+		// Map: localName -> importedName
+		const trackedImports = new Map();
+
+		/**
+		 * Check if the import source should be tracked.
+		 *
+		 * @param {string} source - The import source path
+		 * @return {boolean} Whether to track imports from this source
+		 */
+		function shouldTrackImportSource( source ) {
+			if ( source === '@wordpress/components' ) {
+				return true;
+			}
+
+			// When checkLocalImports is enabled, also track relative imports
+			if ( checkLocalImports ) {
+				return source.startsWith( '.' ) || source.startsWith( '/' );
+			}
+
+			return false;
+		}
+
+		/**
+		 * Try to infer component name from import path.
+		 * e.g., '../button' -> 'Button', '../input-control' -> 'InputControl'
+		 *
+		 * @param {string} source - The import source path
+		 * @return {string|null} The inferred component name or null
+		 */
+		function inferComponentNameFromPath( source ) {
+			// Get the last segment of the path
+			const lastSegment = source.split( '/' ).pop();
+			if ( ! lastSegment ) {
+				return null;
+			}
+
+			// Convert kebab-case to PascalCase
+			const pascalCase = lastSegment
+				.split( '-' )
+				.map(
+					( part ) => part.charAt( 0 ).toUpperCase() + part.slice( 1 )
+				)
+				.join( '' );
+
+			// Check if it's one of our tracked components
+			if ( ALL_TRACKED_COMPONENTS.has( pascalCase ) ) {
+				return pascalCase;
+			}
+
+			return null;
+		}
+
+		/**
+		 * Check if the `size` prop has a non-default value.
+		 *
+		 * @param {Array} attributes - JSX attributes array
+		 * @return {boolean} Whether size has a non-default value
+		 */
+		function hasNonDefaultSize( attributes ) {
+			const sizeAttr = attributes.find(
+				( a ) =>
+					a.type === 'JSXAttribute' &&
+					a.name &&
+					a.name.name === 'size'
+			);
+
+			if ( ! sizeAttr ) {
+				return false;
+			}
+
+			// String value like `size="small"` or `size="compact"`
+			if (
+				sizeAttr.value &&
+				sizeAttr.value.type === 'Literal' &&
+				typeof sizeAttr.value.value === 'string'
+			) {
+				return sizeAttr.value.value !== 'default';
+			}
+
+			// Expression - could be non-default, so don't report
+			if (
+				sizeAttr.value &&
+				sizeAttr.value.type === 'JSXExpressionContainer'
+			) {
+				return true;
+			}
+
+			return false;
+		}
+
+		/**
+		 * Check if the `render` prop exists.
+		 *
+		 * @param {Array} attributes - JSX attributes array
+		 * @return {boolean} Whether render prop exists
+		 */
+		function hasRenderProp( attributes ) {
+			return attributes.some(
+				( a ) =>
+					a.type === 'JSXAttribute' &&
+					a.name &&
+					a.name.name === 'render'
+			);
+		}
+
+		/**
+		 * Check if the `variant` prop has the value "link".
+		 * Button with variant="link" doesn't need __next40pxDefaultSize.
+		 *
+		 * @param {Array} attributes - JSX attributes array
+		 * @return {boolean} Whether variant is "link"
+		 */
+		function hasLinkVariant( attributes ) {
+			const variantAttr = attributes.find(
+				( a ) =>
+					a.type === 'JSXAttribute' &&
+					a.name &&
+					a.name.name === 'variant'
+			);
+
+			if ( ! variantAttr ) {
+				return false;
+			}
+
+			// String value like `variant="link"`
+			if (
+				variantAttr.value &&
+				variantAttr.value.type === 'Literal' &&
+				variantAttr.value.value === 'link'
+			) {
+				return true;
+			}
+
+			return false;
+		}
+
+		return {
+			ImportDeclaration( node ) {
+				const source = node.source.value;
+
+				if ( ! shouldTrackImportSource( source ) ) {
+					return;
+				}
+
+				// Handle named imports
+				node.specifiers.forEach( ( specifier ) => {
+					if ( specifier.type !== 'ImportSpecifier' ) {
+						return;
+					}
+
+					const importedName = specifier.imported.name;
+					const localName = specifier.local.name;
+
+					// Track components that require the prop
+					if (
+						COMPONENTS_REQUIRING_40PX.has( importedName ) ||
+						COMPONENTS_WITH_RENDER_EXEMPTION.has( importedName )
+					) {
+						trackedImports.set( localName, importedName );
+					}
+				} );
+
+				// Handle default imports when checking local imports
+				// e.g., import InputControl from '../input-control'
+				if ( checkLocalImports ) {
+					node.specifiers.forEach( ( specifier ) => {
+						if ( specifier.type === 'ImportDefaultSpecifier' ) {
+							const localName = specifier.local.name;
+							const inferredName =
+								inferComponentNameFromPath( source );
+							if ( inferredName ) {
+								trackedImports.set( localName, inferredName );
+								return;
+							}
+
+							// Support patterns like `import ClipboardButton from '.';`
+							// (common in component folder examples/tests).
+							// If the local name matches a tracked component, treat it as such.
+							if ( ALL_TRACKED_COMPONENTS.has( localName ) ) {
+								trackedImports.set( localName, localName );
+							}
+						}
+					} );
+				}
+			},
+
+			JSXOpeningElement( node ) {
+				// Only check simple JSX element names (not member expressions)
+				if ( node.name.type !== 'JSXIdentifier' ) {
+					return;
+				}
+
+				const elementName = node.name.name;
+				const importedName = trackedImports.get( elementName );
+
+				// Only check if this is a tracked component from @wordpress/components
+				if ( ! importedName ) {
+					return;
+				}
+
+				const attributes = node.attributes;
+
+				// Check if __next40pxDefaultSize has a truthy value
+				if (
+					hasTruthyJsxAttribute( attributes, '__next40pxDefaultSize' )
+				) {
+					return;
+				}
+
+				// Handle FormFileUpload special case
+				if ( COMPONENTS_WITH_RENDER_EXEMPTION.has( importedName ) ) {
+					// FormFileUpload is valid if it has a `render` prop
+					if ( hasRenderProp( attributes ) ) {
+						return;
+					}
+
+					context.report( {
+						node,
+						messageId: 'missingPropFormFileUpload',
+					} );
+					return;
+				}
+
+				// For other components, check if size prop has a non-default value
+				if ( hasNonDefaultSize( attributes ) ) {
+					return;
+				}
+
+				// Button with variant="link" doesn't need __next40pxDefaultSize
+				if (
+					importedName === 'Button' &&
+					hasLinkVariant( attributes )
+				) {
+					return;
+				}
+
+				context.report( {
+					node,
+					messageId: 'missingProp',
+					data: {
+						component: importedName,
+					},
+				} );
+			},
+		};
+	},
+};

package/rules/components-no-unsafe-button-disabled.js

@@ -0,0 +1,126 @@
+const { hasTruthyJsxAttribute } = require( '../utils' );
+
+/**
+ * Enforces that Button from @wordpress/components includes `accessibleWhenDisabled`
+ * when `disabled` is set.
+ *
+ * @type {import('eslint').Rule.RuleModule}
+ */
+module.exports = {
+	meta: {
+		type: 'problem',
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					checkLocalImports: {
+						type: 'boolean',
+						description:
+							'When true, also checks components imported from relative paths (for use inside @wordpress/components package).',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		messages: {
+			missingAccessibleWhenDisabled:
+				'`disabled` used without the `accessibleWhenDisabled` prop. Disabling a control without maintaining focusability can cause accessibility issues, by hiding their presence from screen reader users, or preventing focus from returning to a trigger element. (Ignore this error if you truly mean to disable.)',
+		},
+	},
+	create( context ) {
+		const checkLocalImports =
+			context.options[ 0 ]?.checkLocalImports ?? false;
+
+		// Track local names of Button imported from @wordpress/components
+		const wpComponentsButtons = new Set();
+
+		/**
+		 * Check if the import source should be tracked.
+		 *
+		 * @param {string} source - The import source path
+		 * @return {boolean} Whether to track imports from this source
+		 */
+		function shouldTrackImportSource( source ) {
+			if ( source === '@wordpress/components' ) {
+				return true;
+			}
+
+			// When checkLocalImports is enabled, also track relative imports
+			if ( checkLocalImports ) {
+				return source.startsWith( '.' ) || source.startsWith( '/' );
+			}
+
+			return false;
+		}
+
+		return {
+			ImportDeclaration( node ) {
+				if ( ! shouldTrackImportSource( node.source.value ) ) {
+					return;
+				}
+
+				node.specifiers.forEach( ( specifier ) => {
+					if ( specifier.type !== 'ImportSpecifier' ) {
+						return;
+					}
+
+					const importedName = specifier.imported.name;
+					if ( importedName === 'Button' ) {
+						// Track the local name (handles aliased imports)
+						wpComponentsButtons.add( specifier.local.name );
+					}
+				} );
+
+				// Also handle default imports when checking local imports
+				// e.g., import Button from './button'
+				if ( checkLocalImports ) {
+					node.specifiers.forEach( ( specifier ) => {
+						if ( specifier.type === 'ImportDefaultSpecifier' ) {
+							const localName = specifier.local.name;
+							// Check if the import path suggests it's a Button component
+							const source = node.source.value;
+							if (
+								source.endsWith( '/button' ) ||
+								source.endsWith( '/Button' )
+							) {
+								wpComponentsButtons.add( localName );
+							}
+						}
+					} );
+				}
+			},
+
+			JSXOpeningElement( node ) {
+				// Only check simple JSX element names (not member expressions)
+				if ( node.name.type !== 'JSXIdentifier' ) {
+					return;
+				}
+
+				const elementName = node.name.name;
+
+				// Only check if this is a Button from @wordpress/components
+				if ( ! wpComponentsButtons.has( elementName ) ) {
+					return;
+				}
+
+				if ( ! hasTruthyJsxAttribute( node.attributes, 'disabled' ) ) {
+					return;
+				}
+
+				const hasAccessibleWhenDisabled = node.attributes.some(
+					( attr ) =>
+						attr.type === 'JSXAttribute' &&
+						attr.name &&
+						attr.name.name === 'accessibleWhenDisabled'
+				);
+
+				if ( ! hasAccessibleWhenDisabled ) {
+					context.report( {
+						node,
+						messageId: 'missingAccessibleWhenDisabled',
+					} );
+				}
+			},
+		};
+	},
+};

package/rules/dependency-group.js

@@ -1,5 +1,9 @@
 /** @typedef {import('estree').Comment} Comment */
 /** @typedef {import('estree').Node} Node */
+/** @typedef {import('estree').SourceLocation} SourceLocation */
+
+const DEPENDENCY_BLOCK_PATTERN =
+	/^\*?\n \* (External|Node|WordPress|Internal) dependencies\n $/;
 
 /** @type {import('eslint').Rule.RuleModule} */
 module.exports = {
@@ -9,10 +13,15 @@ module.exports = {
 			description: 'Enforce dependencies docblocks formatting',
 			url: 'https://github.com/WordPress/gutenberg/blob/HEAD/packages/eslint-plugin/docs/rules/dependency-group.md',
 		},
-		schema: [],
+		schema: [
+			{
+				enum: [ 'always', 'never' ],
+			},
+		],
 		fixable: 'code',
 	},
 	create( context ) {
+		const mode = context.options[ 0 ] || 'always';
 		const comments = context.getSourceCode().getAllComments();
 
 		/**
@@ -94,6 +103,20 @@ module.exports = {
 			return pattern.test( value );
 		}
 
+		/**
+		 * Returns true if the given comment node is any dependency block comment.
+		 *
+		 * @param {Comment} node Comment node to check.
+		 *
+		 * @return {boolean} Whether comment node is a dependency block.
+		 */
+		function isDependencyBlock( node ) {
+			return (
+				node.type === 'Block' &&
+				DEPENDENCY_BLOCK_PATTERN.test( node.value )
+			);
+		}
+
 		/**
 		 * Returns true if the given node occurs prior in code to a reference,
 		 * or false otherwise.
@@ -157,6 +180,46 @@ module.exports = {
 			 * @param {import('estree').Program} node Program node.
 			 */
 			Program( node ) {
+				if ( mode === 'never' ) {
+					for ( const comment of comments ) {
+						if ( isDependencyBlock( comment ) ) {
+							context.report( {
+								loc: /** @type {SourceLocation} */ (
+									comment.loc
+								),
+								message:
+									'Unexpected dependency group comment block',
+								fix( fixer ) {
+									if ( ! comment.range ) {
+										return null;
+									}
+
+									const text = context
+										.getSourceCode()
+										.getText();
+
+									// Trim preceding and trailing newlines.
+									let [ start, end ] = comment.range;
+									while (
+										start > 1 &&
+										text[ start - 1 ] === '\n' &&
+										text[ start - 2 ] === '\n'
+									) {
+										start--;
+									}
+									while ( text[ end ] === '\n' ) {
+										end++;
+									}
+
+									return fixer.removeRange( [ start, end ] );
+								},
+							} );
+						}
+					}
+
+					return;
+				}
+
 				/**
 				 * The set of package localities which have been reported for
 				 * the current program. Each locality is reported at most one

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

@@ -0,0 +1,27 @@
+module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Disallow setting any CSS custom property beginning with --wpds- in inline styles',
+		},
+		schema: [],
+		messages: {
+			disallowedSet:
+				'Do not set CSS custom properties using the Design System tokens namespace (i.e. beginning with --wpds-*).',
+		},
+	},
+	create( context ) {
+		return {
+			/** @param {import('estree').Property} node */
+			'JSXAttribute[name.name="style"] ObjectExpression > Property[key.value=/^--wpds-/]'(
+				node
+			) {
+				context.report( {
+					node: node.key,
+					messageId: 'disallowedSet',
+				} );
+			},
+		};
+	},
+} );