@wordpress/theme 0.8.1-next.v.202603102151.0 → 0.9.0

package/src/stylelint-plugins/no-token-fallback-values.mjs

@@ -0,0 +1,55 @@
+import stylelint from 'stylelint';
+
+const {
+	createPlugin,
+	utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = 'plugin-wpds/no-token-fallback-values';
+
+/**
+ * Matches `var(--wpds-<name>,` — the comma signals a fallback value.
+ * Captures the token name (e.g. `--wpds-color-fg-content-neutral`).
+ */
+const varWithFallbackRegex = /var\(\s*(--wpds-[\w-]+)\s*,/g;
+
+const messages = ruleMessages( ruleName, {
+	rejected: ( tokenName ) =>
+		`Do not add a fallback value for Design System token '${ tokenName }'. Fallbacks are injected automatically at build time.`,
+} );
+
+/** @type {import('stylelint').Rule} */
+const ruleFunction = ( primary ) => {
+	return ( root, result ) => {
+		const validOptions = validateOptions( result, ruleName, {
+			actual: primary,
+			possible: [ true ],
+		} );
+
+		if ( ! validOptions ) {
+			return;
+		}
+
+		root.walkDecls( ( ruleNode ) => {
+			const { value } = ruleNode;
+
+			let match;
+			varWithFallbackRegex.lastIndex = 0;
+			while ( ( match = varWithFallbackRegex.exec( value ) ) !== null ) {
+				report( {
+					message: messages.rejected( match[ 1 ] ),
+					node: ruleNode,
+					word: match[ 0 ],
+					result,
+					ruleName,
+				} );
+			}
+		} );
+	};
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+
+/** @type {import('stylelint').Plugin} */
+export default createPlugin( ruleName, ruleFunction );

package/src/stylelint-plugins/test/.stylelintrc.no-setting-wpds-custom-properties.json

@@ -0,0 +1,6 @@
+{
+	"plugins": [ "../no-setting-wpds-custom-properties.mjs" ],
+	"rules": {
+		"plugin-wpds/no-setting-wpds-custom-properties": true
+	}
+}

package/src/stylelint-plugins/test/.stylelintrc.no-token-fallback-values.json

@@ -0,0 +1,6 @@
+{
+	"plugins": [ "../no-token-fallback-values.mjs" ],
+	"rules": {
+		"plugin-wpds/no-token-fallback-values": true
+	}
+}

package/src/stylelint-plugins/test/.stylelintrc.no-unknown-ds-tokens.json

@@ -0,0 +1,6 @@
+{
+	"plugins": [ "../no-unknown-ds-tokens.mjs" ],
+	"rules": {
+		"plugin-wpds/no-unknown-ds-tokens": true
+	}
+}

package/src/stylelint-plugins/test/__snapshots__/no-token-fallback-values.test.ts.snap

@@ -0,0 +1,60 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`flags warnings with invalid css (wpds fallbacks) snapshot matches warnings 1`] = `
+[
+  {
+    "column": 9,
+    "endColumn": 45,
+    "endLine": 3,
+    "line": 3,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-color-fg-content-neutral'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 20,
+    "endColumn": 61,
+    "endLine": 4,
+    "line": 4,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-color-bg-surface-neutral-weak'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 17,
+    "endColumn": 45,
+    "endLine": 5,
+    "line": 5,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-border-radius-sm'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 11,
+    "endColumn": 41,
+    "endLine": 10,
+    "line": 10,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-border-width-focus'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 53,
+    "endColumn": 89,
+    "endLine": 10,
+    "line": 10,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-color-stroke-focus-brand'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+  {
+    "column": 32,
+    "endColumn": 68,
+    "endLine": 15,
+    "line": 15,
+    "rule": "plugin-wpds/no-token-fallback-values",
+    "severity": "error",
+    "text": "Do not add a fallback value for Design System token '--wpds-color-fg-content-neutral'. Fallbacks are injected automatically at build time. (plugin-wpds/no-token-fallback-values)",
+  },
+]
+`;

package/src/stylelint-plugins/test/fixtures/no-token-fallback-values-invalid.css

@@ -0,0 +1,16 @@
+/* Invalid: Using wpds tokens with fallbacks */
+.with-fallback {
+	color: var(--wpds-color-fg-content-neutral, #1e1e1e);
+	background-color: var(--wpds-color-bg-surface-neutral-weak, #f0f0f0);
+	border-radius: var(--wpds-border-radius-sm, 2px);
+}
+
+/* Invalid: Fallbacks in complex values */
+.complex {
+	outline: var(--wpds-border-width-focus, 2px) solid var(--wpds-color-stroke-focus-brand, #0073aa);
+}
+
+/* Invalid: A wpds token with a fallback, even when nested inside another var() */
+.nested-with-fallback {
+	color: var(--my-custom-color, var(--wpds-color-fg-content-neutral, #1e1e1e));
+}

package/src/stylelint-plugins/test/fixtures/no-token-fallback-values-valid.css

@@ -0,0 +1,18 @@
+/* Valid: Using wpds tokens without fallbacks */
+.example {
+	color: var(--wpds-color-fg-content-neutral);
+	background-color: var(--wpds-color-bg-surface-neutral);
+	border-radius: var(--wpds-border-radius-sm);
+	padding: var(--wpds-dimension-padding-md);
+}
+
+/* Valid: Non-wpds custom properties with fallbacks are fine */
+.other-vars {
+	color: var(--my-custom-color, red);
+	background: var(--some-other-var, #fff);
+}
+
+/* Valid: A wpds token used as a fallback of a non-wpds var, with no comma after the wpds token */
+.nested-no-fallback {
+	color: var(--my-custom-color, var(--wpds-color-fg-content-neutral));
+}

package/src/stylelint-plugins/test/no-setting-wpds-custom-properties.test.ts

@@ -1,11 +1,14 @@
 import { getStylelintResult } from './utils';
 
+const CONFIG = './.stylelintrc.no-setting-wpds-custom-properties.json';
+
 describe( 'flags no warnings with valid wpds custom properties css', () => {
 	let result: ReturnType< typeof getStylelintResult >;
 
 	beforeEach( () => {
 		result = getStylelintResult(
-			'./fixtures/no-setting-wpds-custom-properties-valid.css'
+			'./fixtures/no-setting-wpds-custom-properties-valid.css',
+			CONFIG
 		);
 	} );
 
@@ -25,7 +28,8 @@ describe( 'flags warnings with invalid wpds custom properties css', () => {
 
 	beforeEach( () => {
 		result = getStylelintResult(
-			'./fixtures/no-setting-wpds-custom-properties-invalid.css'
+			'./fixtures/no-setting-wpds-custom-properties-invalid.css',
+			CONFIG
 		);
 	} );
 

package/src/stylelint-plugins/test/no-token-fallback-values.test.ts

@@ -0,0 +1,51 @@
+import { getStylelintResult } from './utils';
+
+const CONFIG = './.stylelintrc.no-token-fallback-values.json';
+
+describe( 'flags no warnings with valid css (no wpds fallbacks)', () => {
+	let result: ReturnType< typeof getStylelintResult >;
+
+	beforeEach( () => {
+		result = getStylelintResult(
+			'./fixtures/no-token-fallback-values-valid.css',
+			CONFIG
+		);
+	} );
+
+	it( 'did not error', () => {
+		return result.then( ( data ) => expect( data.errored ).toBeFalsy() );
+	} );
+
+	it( 'flags no warnings', () => {
+		return result.then( ( data ) =>
+			expect( data.results[ 0 ].warnings ).toHaveLength( 0 )
+		);
+	} );
+} );
+
+describe( 'flags warnings with invalid css (wpds fallbacks)', () => {
+	let result: ReturnType< typeof getStylelintResult >;
+
+	beforeEach( () => {
+		result = getStylelintResult(
+			'./fixtures/no-token-fallback-values-invalid.css',
+			CONFIG
+		);
+	} );
+
+	it( 'did error', () => {
+		return result.then( ( data ) => expect( data.errored ).toBeTruthy() );
+	} );
+
+	it( 'flags correct number of warnings', () => {
+		return result.then( ( data ) =>
+			expect( data.results[ 0 ].warnings ).toHaveLength( 6 )
+		);
+	} );
+
+	it( 'snapshot matches warnings', () => {
+		return result.then( ( data ) =>
+			expect( data.results[ 0 ].warnings ).toMatchSnapshot()
+		);
+	} );
+} );

package/src/stylelint-plugins/test/no-unknown-ds-tokens.test.ts

@@ -1,11 +1,14 @@
 import { getStylelintResult } from './utils';
 
+const CONFIG = './.stylelintrc.no-unknown-ds-tokens.json';
+
 describe( 'flags no warnings with valid wpds tokens css', () => {
 	let result: ReturnType< typeof getStylelintResult >;
 
 	beforeEach( () => {
 		result = getStylelintResult(
-			'./fixtures/no-unknown-ds-tokens-valid.css'
+			'./fixtures/no-unknown-ds-tokens-valid.css',
+			CONFIG
 		);
 	} );
 
@@ -25,7 +28,8 @@ describe( 'flags warnings with invalid wpds tokens css', () => {
 
 	beforeEach( () => {
 		result = getStylelintResult(
-			'./fixtures/no-unknown-ds-tokens-invalid.css'
+			'./fixtures/no-unknown-ds-tokens-invalid.css',
+			CONFIG
 		);
 	} );
 

package/src/stylelint-plugins/test/utils/index.ts

@@ -4,17 +4,20 @@ import childProcess from 'node:child_process';
 
 const execute = util.promisify( childProcess.exec );
 
-const generateStylelintCommand = ( filename: string ): string =>
+const generateStylelintCommand = (
+	filename: string,
+	configFile: string
+): string =>
 	'npx stylelint ' +
 	path.resolve( __dirname, '../', filename ) +
 	' -c ' +
-	path.resolve( __dirname, '../', './.stylelintrc.json' ) +
+	path.resolve( __dirname, '../', configFile ) +
 	' --formatter json' +
 	' --ignore-path ' +
 	path.resolve( __dirname, '../', './.stylelintignore' );
 
-export const getStylelintResult = ( filename: string ) =>
-	execute( generateStylelintCommand( filename ) )
+export const getStylelintResult = ( filename: string, configFile: string ) =>
+	execute( generateStylelintCommand( filename, configFile ) )
 		.then( ( { stderr } ) => {
 			return {
 				errored: false,

package/src/vite-plugins/vite-ds-token-fallbacks.mjs

@@ -21,7 +21,10 @@ const plugin = () => ( {
 		}
 		// Sourcemap omitted: replacements are small, inline substitutions
 		// that preserve line structure, so the debugging impact is negligible.
-		return { code: addFallbackToVar( code ), map: null };
+		return {
+			code: addFallbackToVar( code, { escapeQuotes: true } ),
+			map: null,
+		};
 	},
 } );
 

package/src/stylelint-plugins/test/.stylelintrc.json

@@ -1,10 +0,0 @@
-{
-	"plugins": [
-		"../no-unknown-ds-tokens.mjs",
-		"../no-setting-wpds-custom-properties.mjs"
-	],
-	"rules": {
-		"plugin-wpds/no-unknown-ds-tokens": true,
-		"plugin-wpds/no-setting-wpds-custom-properties": true
-	}
-}