@wordpress/theme-build-tools 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +788 -0
- package/README.md +133 -2
- package/build-types/esbuild-plugins/esbuild-ds-token-fallbacks.d.mts +12 -0
- package/build-types/js-plugins/transform-ds-token-fallbacks.d.mts +14 -0
- package/build-types/lib/theme-tokens.d.mts +28 -0
- package/build-types/lightningcss-plugins/lightningcss-ds-token-fallbacks.d.mts +13 -0
- package/build-types/postcss-plugins/add-fallback-to-var.d.mts +38 -0
- package/build-types/postcss-plugins/ds-token-fallbacks.d.mts +41 -0
- package/build-types/postcss-plugins/postcss-ds-token-fallbacks.d.mts +4 -0
- package/build-types/stylelint-plugins/no-setting-wpds-custom-properties.d.mts +5 -0
- package/build-types/stylelint-plugins/no-token-fallback-values.d.mts +5 -0
- package/build-types/stylelint-plugins/no-unknown-ds-tokens.d.mts +5 -0
- package/build-types/vite-plugins/vite-ds-token-fallbacks.d.mts +12 -0
- package/esbuild-plugins/esbuild-ds-token-fallbacks.mjs +130 -0
- package/js-plugins/transform-ds-token-fallbacks.mjs +211 -0
- package/lib/theme-tokens.mjs +58 -0
- package/lightningcss-plugins/lightningcss-ds-token-fallbacks.mjs +89 -0
- package/package.json +125 -5
- package/postcss-plugins/add-fallback-to-var.mjs +65 -0
- package/postcss-plugins/ds-token-fallbacks.mjs +53 -0
- package/postcss-plugins/postcss-ds-token-fallbacks.mjs +17 -0
- package/stylelint-plugins/no-setting-wpds-custom-properties.mjs +45 -0
- package/stylelint-plugins/no-token-fallback-values.mjs +55 -0
- package/stylelint-plugins/no-unknown-ds-tokens.mjs +102 -0
- package/vite-plugins/vite-ds-token-fallbacks.mjs +33 -0
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Token data from the installed `@wordpress/theme`.
|
|
3
|
+
*
|
|
4
|
+
* The plugins do nothing when `@wordpress/theme` cannot be loaded.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { createRequire } from 'node:module';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* @typedef {Object} DesignTokensModule
|
|
11
|
+
* @property {Record<string, { fallback: string }>} tokens Token metadata, keyed by CSS custom property name.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Load `@wordpress/theme/design-tokens.js`, or return `undefined` when it
|
|
16
|
+
* cannot be loaded.
|
|
17
|
+
*
|
|
18
|
+
* This loads the module synchronously, without a top-level `await`, so that
|
|
19
|
+
* CommonJS consumers can still `require()` the plugins.
|
|
20
|
+
*
|
|
21
|
+
* @return {DesignTokensModule | undefined} The module, or `undefined`.
|
|
22
|
+
*/
|
|
23
|
+
function loadDesignTokens() {
|
|
24
|
+
try {
|
|
25
|
+
return createRequire( import.meta.url )(
|
|
26
|
+
'@wordpress/theme/design-tokens.js'
|
|
27
|
+
);
|
|
28
|
+
} catch {
|
|
29
|
+
return undefined;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const designTokens = loadDesignTokens();
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Map of design token names to their generated fallback values, or
|
|
37
|
+
* `undefined` when `@wordpress/theme` is unavailable.
|
|
38
|
+
*
|
|
39
|
+
* @type {Record<string, string> | undefined}
|
|
40
|
+
*/
|
|
41
|
+
export const tokenFallbacks = designTokens
|
|
42
|
+
? Object.fromEntries(
|
|
43
|
+
Object.entries( designTokens.tokens ).map( ( [ name, token ] ) => [
|
|
44
|
+
name,
|
|
45
|
+
token.fallback,
|
|
46
|
+
] )
|
|
47
|
+
)
|
|
48
|
+
: undefined;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* List of design token names, or `undefined` when `@wordpress/theme` is
|
|
52
|
+
* unavailable.
|
|
53
|
+
*
|
|
54
|
+
* @type {string[] | undefined}
|
|
55
|
+
*/
|
|
56
|
+
export const tokenList = designTokens
|
|
57
|
+
? Object.keys( designTokens.tokens )
|
|
58
|
+
: undefined;
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { transform } from 'lightningcss';
|
|
2
|
+
import { tokenFallbacks } from '../lib/theme-tokens.mjs';
|
|
3
|
+
import { getTokenFallback } from '../postcss-plugins/ds-token-fallbacks.mjs';
|
|
4
|
+
|
|
5
|
+
/** @type {Map<string, import('lightningcss').TokenOrValue[]>} */
|
|
6
|
+
const parsedFallbacks = new Map();
|
|
7
|
+
|
|
8
|
+
// Raw replacements discard CSS Modules reference metadata. Parse the generated
|
|
9
|
+
// fallbacks once so the visitor can combine them with each original reference.
|
|
10
|
+
if ( tokenFallbacks ) {
|
|
11
|
+
const fallbacks = tokenFallbacks;
|
|
12
|
+
transform( {
|
|
13
|
+
filename: 'design-token-fallbacks.css',
|
|
14
|
+
code: Buffer.from(
|
|
15
|
+
`:root {\n${ Object.entries( fallbacks )
|
|
16
|
+
.map(
|
|
17
|
+
( [ tokenName, fallback ] ) =>
|
|
18
|
+
`\t${ tokenName }: var(${ tokenName }, ${ fallback });`
|
|
19
|
+
)
|
|
20
|
+
.join( '\n' ) }\n}`
|
|
21
|
+
),
|
|
22
|
+
visitor: {
|
|
23
|
+
Variable( variable ) {
|
|
24
|
+
if (
|
|
25
|
+
variable.fallback &&
|
|
26
|
+
Object.hasOwn( fallbacks, variable.name.ident )
|
|
27
|
+
) {
|
|
28
|
+
// Generated fallbacks reference global custom properties.
|
|
29
|
+
// Keep CSS Modules from scoping them to the consumer's file.
|
|
30
|
+
const fallback = JSON.parse(
|
|
31
|
+
JSON.stringify( variable.fallback, ( key, value ) =>
|
|
32
|
+
key === 'from' && value === null
|
|
33
|
+
? { type: 'global' }
|
|
34
|
+
: value
|
|
35
|
+
)
|
|
36
|
+
);
|
|
37
|
+
parsedFallbacks.set( variable.name.ident, fallback );
|
|
38
|
+
}
|
|
39
|
+
},
|
|
40
|
+
},
|
|
41
|
+
} );
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Lightning CSS visitor that injects design-system token fallbacks into CSS.
|
|
46
|
+
*
|
|
47
|
+
* Replaces bare `var(--wpds-*)` references with `var(--wpds-*, <fallback>)`.
|
|
48
|
+
*
|
|
49
|
+
* Existing fallbacks are left untouched. Unknown tokens throw. Does nothing
|
|
50
|
+
* when `@wordpress/theme` is not installed.
|
|
51
|
+
*
|
|
52
|
+
* @type {import('lightningcss').Visitor<never>}
|
|
53
|
+
*/
|
|
54
|
+
const plugin = {
|
|
55
|
+
/** @param {import('lightningcss').Variable} variable */
|
|
56
|
+
Variable( variable ) {
|
|
57
|
+
// Leave existing fallbacks alone, including the valid empty fallback
|
|
58
|
+
// form `var(--token,)` which Lightning CSS parses as `fallback: []`.
|
|
59
|
+
if ( variable.fallback !== null || ! tokenFallbacks ) {
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
const tokenName = variable.name.ident;
|
|
64
|
+
if ( ! tokenName.startsWith( '--wpds-' ) ) {
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
const fallback = parsedFallbacks.get( tokenName );
|
|
69
|
+
if ( ! fallback ) {
|
|
70
|
+
getTokenFallback( tokenName );
|
|
71
|
+
throw new Error(
|
|
72
|
+
`No parsed fallback for design token: ${ tokenName }. ` +
|
|
73
|
+
'Check that its generated fallback can be parsed by Lightning CSS.'
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
return {
|
|
78
|
+
type: 'var',
|
|
79
|
+
value: {
|
|
80
|
+
name: variable.name.from
|
|
81
|
+
? variable.name
|
|
82
|
+
: { ident: variable.name.ident },
|
|
83
|
+
fallback: structuredClone( fallback ),
|
|
84
|
+
},
|
|
85
|
+
};
|
|
86
|
+
},
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
export default plugin;
|
package/package.json
CHANGED
|
@@ -1,6 +1,126 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@wordpress/theme-build-tools",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Build plugins and Stylelint rules for the WordPress Design System design tokens.",
|
|
5
|
+
"author": "The WordPress Contributors",
|
|
6
|
+
"license": "GPL-2.0-or-later",
|
|
7
|
+
"keywords": [
|
|
8
|
+
"wordpress",
|
|
9
|
+
"gutenberg",
|
|
10
|
+
"design-system",
|
|
11
|
+
"design-tokens",
|
|
12
|
+
"stylelint",
|
|
13
|
+
"postcss",
|
|
14
|
+
"lightningcss",
|
|
15
|
+
"esbuild",
|
|
16
|
+
"vite"
|
|
17
|
+
],
|
|
18
|
+
"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/theme-build-tools/README.md",
|
|
19
|
+
"repository": {
|
|
20
|
+
"type": "git",
|
|
21
|
+
"url": "git+https://github.com/WordPress/gutenberg.git",
|
|
22
|
+
"directory": "packages/theme-build-tools"
|
|
23
|
+
},
|
|
24
|
+
"bugs": {
|
|
25
|
+
"url": "https://github.com/WordPress/gutenberg/issues"
|
|
26
|
+
},
|
|
27
|
+
"engines": {
|
|
28
|
+
"node": ">=22.13.0"
|
|
29
|
+
},
|
|
30
|
+
"files": [
|
|
31
|
+
"build-types",
|
|
32
|
+
"*-plugins/**",
|
|
33
|
+
"lib/**",
|
|
34
|
+
"!build-types/**/*.d.mts.map",
|
|
35
|
+
"!build-types/**/*.d.ts.map",
|
|
36
|
+
"!**/test/**"
|
|
37
|
+
],
|
|
38
|
+
"type": "module",
|
|
39
|
+
"exports": {
|
|
40
|
+
"./postcss-plugins/postcss-ds-token-fallbacks": {
|
|
41
|
+
"types": "./build-types/postcss-plugins/postcss-ds-token-fallbacks.d.mts",
|
|
42
|
+
"default": "./postcss-plugins/postcss-ds-token-fallbacks.mjs"
|
|
43
|
+
},
|
|
44
|
+
"./lightningcss-plugins/lightningcss-ds-token-fallbacks": {
|
|
45
|
+
"types": "./build-types/lightningcss-plugins/lightningcss-ds-token-fallbacks.d.mts",
|
|
46
|
+
"default": "./lightningcss-plugins/lightningcss-ds-token-fallbacks.mjs"
|
|
47
|
+
},
|
|
48
|
+
"./esbuild-plugins/esbuild-ds-token-fallbacks": {
|
|
49
|
+
"types": "./build-types/esbuild-plugins/esbuild-ds-token-fallbacks.d.mts",
|
|
50
|
+
"default": "./esbuild-plugins/esbuild-ds-token-fallbacks.mjs"
|
|
51
|
+
},
|
|
52
|
+
"./vite-plugins/vite-ds-token-fallbacks": {
|
|
53
|
+
"types": "./build-types/vite-plugins/vite-ds-token-fallbacks.d.mts",
|
|
54
|
+
"default": "./vite-plugins/vite-ds-token-fallbacks.mjs"
|
|
55
|
+
},
|
|
56
|
+
"./stylelint-plugins/no-unknown-ds-tokens": {
|
|
57
|
+
"types": "./build-types/stylelint-plugins/no-unknown-ds-tokens.d.mts",
|
|
58
|
+
"default": "./stylelint-plugins/no-unknown-ds-tokens.mjs"
|
|
59
|
+
},
|
|
60
|
+
"./stylelint-plugins/no-setting-wpds-custom-properties": {
|
|
61
|
+
"types": "./build-types/stylelint-plugins/no-setting-wpds-custom-properties.d.mts",
|
|
62
|
+
"default": "./stylelint-plugins/no-setting-wpds-custom-properties.mjs"
|
|
63
|
+
},
|
|
64
|
+
"./stylelint-plugins/no-token-fallback-values": {
|
|
65
|
+
"types": "./build-types/stylelint-plugins/no-token-fallback-values.d.mts",
|
|
66
|
+
"default": "./stylelint-plugins/no-token-fallback-values.mjs"
|
|
67
|
+
},
|
|
68
|
+
"./package.json": "./package.json"
|
|
69
|
+
},
|
|
70
|
+
"wpScript": false,
|
|
71
|
+
"sideEffects": false,
|
|
72
|
+
"dependencies": {
|
|
73
|
+
"@babel/parser": "^7.28.6",
|
|
74
|
+
"@babel/types": "^7.29.7",
|
|
75
|
+
"@jridgewell/remapping": "^2.3.5",
|
|
76
|
+
"@jridgewell/trace-mapping": "^0.3.31",
|
|
77
|
+
"magic-string": "^0.30.21"
|
|
78
|
+
},
|
|
79
|
+
"devDependencies": {
|
|
80
|
+
"@types/node": "^24.13.3",
|
|
81
|
+
"@wordpress/theme": "^4.0.0",
|
|
82
|
+
"@wordpress/validation-tools": "file:../../tools/validation",
|
|
83
|
+
"esbuild": "^0.27.2",
|
|
84
|
+
"lightningcss": "^1.33.0",
|
|
85
|
+
"postcss": "^8.4.38",
|
|
86
|
+
"source-map": "^0.6.1",
|
|
87
|
+
"stylelint": "^17.14.1",
|
|
88
|
+
"vite": "^8.3.5",
|
|
89
|
+
"vitest": "^5.0.5"
|
|
90
|
+
},
|
|
91
|
+
"peerDependencies": {
|
|
92
|
+
"@wordpress/theme": "^3.0.0 || ^4.0.0",
|
|
93
|
+
"esbuild": ">=0.27.2 <1.0.0",
|
|
94
|
+
"lightningcss": ">=1.33.0 <2.0.0",
|
|
95
|
+
"postcss": "^8.0.0",
|
|
96
|
+
"stylelint": "^16 || ^17",
|
|
97
|
+
"vite": "^7 || ^8"
|
|
98
|
+
},
|
|
99
|
+
"peerDependenciesMeta": {
|
|
100
|
+
"@wordpress/theme": {
|
|
101
|
+
"optional": true
|
|
102
|
+
},
|
|
103
|
+
"esbuild": {
|
|
104
|
+
"optional": true
|
|
105
|
+
},
|
|
106
|
+
"lightningcss": {
|
|
107
|
+
"optional": true
|
|
108
|
+
},
|
|
109
|
+
"postcss": {
|
|
110
|
+
"optional": true
|
|
111
|
+
},
|
|
112
|
+
"stylelint": {
|
|
113
|
+
"optional": true
|
|
114
|
+
},
|
|
115
|
+
"vite": {
|
|
116
|
+
"optional": true
|
|
117
|
+
}
|
|
118
|
+
},
|
|
119
|
+
"publishConfig": {
|
|
120
|
+
"access": "public"
|
|
121
|
+
},
|
|
122
|
+
"scripts": {
|
|
123
|
+
"lint:package-contents": "wp-validate-package-contents . --disallow-path test"
|
|
124
|
+
},
|
|
125
|
+
"gitHead": "9b70363b9f93cff0583a1f3153738d383cf5a49e"
|
|
126
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Replace bare `var(--wpds-*)` references in a CSS value string with
|
|
3
|
+
* `var(--wpds-*, <fallback>)` using the provided token fallback map.
|
|
4
|
+
*
|
|
5
|
+
* Existing fallbacks (i.e. `var()` calls that already contain a comma)
|
|
6
|
+
* are left untouched, making the function safe to run multiple times
|
|
7
|
+
* (idempotent).
|
|
8
|
+
*
|
|
9
|
+
* This is the generic, reusable implementation that takes the fallback
|
|
10
|
+
* map as an argument. For the variant prebound with the package's
|
|
11
|
+
* generated token fallback map, see `./ds-token-fallbacks.mjs`.
|
|
12
|
+
*
|
|
13
|
+
* @param {string} cssValue A CSS declaration value.
|
|
14
|
+
* @param {Record<string, string>} tokenFallbacks Map of CSS variable names to their fallback expressions.
|
|
15
|
+
* @param {Object} [options] Options.
|
|
16
|
+
* @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in fallback values.
|
|
17
|
+
* Use this when the input is JS/TS source so that
|
|
18
|
+
* injected quotes don't break string literals. JS
|
|
19
|
+
* will unescape them at parse time, so the browser's
|
|
20
|
+
* CSS engine still sees the correct value.
|
|
21
|
+
* @return {string} The value with fallbacks injected.
|
|
22
|
+
*/
|
|
23
|
+
export function addFallbackToVar(
|
|
24
|
+
cssValue,
|
|
25
|
+
tokenFallbacks,
|
|
26
|
+
{ escapeQuotes = false } = {}
|
|
27
|
+
) {
|
|
28
|
+
return cssValue.replace(
|
|
29
|
+
/var\(\s*(--wpds-[\w-]+)\s*\)/g,
|
|
30
|
+
( match, tokenName ) => {
|
|
31
|
+
const fallback = getTokenFallback( tokenName, tokenFallbacks, {
|
|
32
|
+
escapeQuotes,
|
|
33
|
+
} );
|
|
34
|
+
return `var(${ tokenName }, ${ fallback })`;
|
|
35
|
+
}
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Get the fallback for a design token.
|
|
41
|
+
*
|
|
42
|
+
* @param {string} tokenName CSS variable name.
|
|
43
|
+
* @param {Record<string, string>} tokenFallbacks Map of CSS variable names to fallback expressions.
|
|
44
|
+
* @param {Object} [options] Options.
|
|
45
|
+
* @param {boolean} [options.escapeQuotes] Whether to escape quotes in the fallback.
|
|
46
|
+
* @return {string} The token fallback.
|
|
47
|
+
*/
|
|
48
|
+
export function getTokenFallback(
|
|
49
|
+
tokenName,
|
|
50
|
+
tokenFallbacks,
|
|
51
|
+
{ escapeQuotes = false } = {}
|
|
52
|
+
) {
|
|
53
|
+
let fallback = tokenFallbacks[ tokenName ];
|
|
54
|
+
if ( fallback === undefined ) {
|
|
55
|
+
throw new Error(
|
|
56
|
+
`Unknown design token: ${ tokenName }. ` +
|
|
57
|
+
'This token is not in the design system. ' +
|
|
58
|
+
'If this token was recently renamed, update all references to use the new name.'
|
|
59
|
+
);
|
|
60
|
+
}
|
|
61
|
+
if ( escapeQuotes ) {
|
|
62
|
+
fallback = fallback.replaceAll( '"', '\\"' ).replaceAll( "'", "\\'" );
|
|
63
|
+
}
|
|
64
|
+
return fallback;
|
|
65
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { tokenFallbacks } from '../lib/theme-tokens.mjs';
|
|
2
|
+
import {
|
|
3
|
+
addFallbackToVar as _addFallbackToVar,
|
|
4
|
+
getTokenFallback as _getTokenFallback,
|
|
5
|
+
} from './add-fallback-to-var.mjs';
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Replace bare `var(--wpds-*)` references in a CSS value string with
|
|
9
|
+
* `var(--wpds-*, <fallback>)` using the package's generated token
|
|
10
|
+
* fallback map.
|
|
11
|
+
*
|
|
12
|
+
* Existing fallbacks (i.e. var() calls that already contain a comma) are
|
|
13
|
+
* left untouched, making the function safe to run multiple times.
|
|
14
|
+
*
|
|
15
|
+
* This is a thin wrapper around the generic `addFallbackToVar` helper in
|
|
16
|
+
* `./add-fallback-to-var.mjs`, prebound to the package's token fallback
|
|
17
|
+
* map. Update the regex/replacement logic in that file, not here.
|
|
18
|
+
*
|
|
19
|
+
* Returns the value unchanged when `@wordpress/theme` is not installed.
|
|
20
|
+
*
|
|
21
|
+
* @param {string} cssValue A CSS declaration value.
|
|
22
|
+
* @param {Object} [options] Options.
|
|
23
|
+
* @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in
|
|
24
|
+
* fallback values. Use this when the
|
|
25
|
+
* input is JS/TS source so that
|
|
26
|
+
* injected quotes don't break string
|
|
27
|
+
* literals. JS will unescape them at
|
|
28
|
+
* parse time, so the browser's CSS
|
|
29
|
+
* engine still sees the correct value.
|
|
30
|
+
* @return {string} The value with fallbacks injected.
|
|
31
|
+
*/
|
|
32
|
+
export function addFallbackToVar( cssValue, options ) {
|
|
33
|
+
if ( ! tokenFallbacks ) {
|
|
34
|
+
return cssValue;
|
|
35
|
+
}
|
|
36
|
+
return _addFallbackToVar( cssValue, tokenFallbacks, options );
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Whether design token fallbacks are available, i.e. whether
|
|
41
|
+
* `@wordpress/theme` is installed. The plugins do nothing without them.
|
|
42
|
+
*/
|
|
43
|
+
export const hasTokenFallbacks = tokenFallbacks !== undefined;
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Get the generated fallback for a design token.
|
|
47
|
+
*
|
|
48
|
+
* @param {string} tokenName CSS variable name.
|
|
49
|
+
* @return {string} The token fallback.
|
|
50
|
+
*/
|
|
51
|
+
export function getTokenFallback( tokenName ) {
|
|
52
|
+
return _getTokenFallback( tokenName, tokenFallbacks ?? {} );
|
|
53
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { addFallbackToVar } from './ds-token-fallbacks.mjs';
|
|
2
|
+
|
|
3
|
+
/** @type {import('postcss').PluginCreator<never>} */
|
|
4
|
+
const plugin = () => ( {
|
|
5
|
+
postcssPlugin: 'postcss-ds-token-fallbacks',
|
|
6
|
+
/** @param {import('postcss').Declaration} decl */
|
|
7
|
+
Declaration( decl ) {
|
|
8
|
+
const updated = addFallbackToVar( decl.value );
|
|
9
|
+
if ( updated !== decl.value ) {
|
|
10
|
+
decl.value = updated;
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
} );
|
|
14
|
+
|
|
15
|
+
plugin.postcss = true;
|
|
16
|
+
|
|
17
|
+
export default plugin;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import stylelint from 'stylelint';
|
|
2
|
+
|
|
3
|
+
const {
|
|
4
|
+
createPlugin,
|
|
5
|
+
utils: { report, ruleMessages, validateOptions },
|
|
6
|
+
} = stylelint;
|
|
7
|
+
|
|
8
|
+
const ruleName = 'plugin-wpds/no-setting-wpds-custom-properties';
|
|
9
|
+
|
|
10
|
+
const messages = ruleMessages( ruleName, {
|
|
11
|
+
rejected: () =>
|
|
12
|
+
`Do not set CSS custom properties using the Design System tokens namespace (i.e. beginning with --wpds-*).`,
|
|
13
|
+
} );
|
|
14
|
+
|
|
15
|
+
/** @type {import('stylelint').Rule} */
|
|
16
|
+
const ruleFunction = ( primary ) => {
|
|
17
|
+
return ( root, result ) => {
|
|
18
|
+
const validOptions = validateOptions( result, ruleName, {
|
|
19
|
+
actual: primary,
|
|
20
|
+
possible: [ true ],
|
|
21
|
+
} );
|
|
22
|
+
|
|
23
|
+
if ( ! validOptions ) {
|
|
24
|
+
return;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
root.walkDecls( ( ruleNode ) => {
|
|
28
|
+
const { prop } = ruleNode;
|
|
29
|
+
if ( prop.startsWith( '--wpds-' ) ) {
|
|
30
|
+
report( {
|
|
31
|
+
message: messages.rejected(),
|
|
32
|
+
node: ruleNode,
|
|
33
|
+
result,
|
|
34
|
+
ruleName,
|
|
35
|
+
} );
|
|
36
|
+
}
|
|
37
|
+
} );
|
|
38
|
+
};
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
ruleFunction.ruleName = ruleName;
|
|
42
|
+
ruleFunction.messages = messages;
|
|
43
|
+
|
|
44
|
+
/** @type {import('stylelint').Plugin} */
|
|
45
|
+
export default createPlugin( ruleName, ruleFunction );
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import stylelint from 'stylelint';
|
|
2
|
+
|
|
3
|
+
const {
|
|
4
|
+
createPlugin,
|
|
5
|
+
utils: { report, ruleMessages, validateOptions },
|
|
6
|
+
} = stylelint;
|
|
7
|
+
|
|
8
|
+
const ruleName = 'plugin-wpds/no-token-fallback-values';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Matches `var(--wpds-<name>,` — the comma signals a fallback value.
|
|
12
|
+
* Captures the token name (e.g. `--wpds-color-foreground-content-neutral`).
|
|
13
|
+
*/
|
|
14
|
+
const varWithFallbackRegex = /var\(\s*(--wpds-[\w-]+)\s*,/g;
|
|
15
|
+
|
|
16
|
+
const messages = ruleMessages( ruleName, {
|
|
17
|
+
rejected: ( tokenName ) =>
|
|
18
|
+
`Do not add a fallback value for Design System token '${ tokenName }'. Fallbacks should be injected automatically at build time (see @wordpress/theme-build-tools package README).`,
|
|
19
|
+
} );
|
|
20
|
+
|
|
21
|
+
/** @type {import('stylelint').Rule} */
|
|
22
|
+
const ruleFunction = ( primary ) => {
|
|
23
|
+
return ( root, result ) => {
|
|
24
|
+
const validOptions = validateOptions( result, ruleName, {
|
|
25
|
+
actual: primary,
|
|
26
|
+
possible: [ true ],
|
|
27
|
+
} );
|
|
28
|
+
|
|
29
|
+
if ( ! validOptions ) {
|
|
30
|
+
return;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
root.walkDecls( ( ruleNode ) => {
|
|
34
|
+
const { value } = ruleNode;
|
|
35
|
+
|
|
36
|
+
let match;
|
|
37
|
+
varWithFallbackRegex.lastIndex = 0;
|
|
38
|
+
while ( ( match = varWithFallbackRegex.exec( value ) ) !== null ) {
|
|
39
|
+
report( {
|
|
40
|
+
message: messages.rejected( match[ 1 ] ),
|
|
41
|
+
node: ruleNode,
|
|
42
|
+
word: match[ 0 ],
|
|
43
|
+
result,
|
|
44
|
+
ruleName,
|
|
45
|
+
} );
|
|
46
|
+
}
|
|
47
|
+
} );
|
|
48
|
+
};
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
ruleFunction.ruleName = ruleName;
|
|
52
|
+
ruleFunction.messages = messages;
|
|
53
|
+
|
|
54
|
+
/** @type {import('stylelint').Plugin} */
|
|
55
|
+
export default createPlugin( ruleName, ruleFunction );
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import stylelint from 'stylelint';
|
|
2
|
+
import { tokenList } from '../lib/theme-tokens.mjs';
|
|
3
|
+
|
|
4
|
+
const DS_TOKEN_PREFIX = 'wpds-';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Extracts all unique CSS custom properties (variables) from a given CSS value string,
|
|
8
|
+
* including those in fallback positions, optionally filtering by a specific prefix.
|
|
9
|
+
*
|
|
10
|
+
* @param {string} value - The CSS value string to search for variables.
|
|
11
|
+
* @param {string} [prefix=''] - Optional prefix to filter variables (e.g., 'wpds-').
|
|
12
|
+
* @return {Set<string>} A Set of unique matched CSS variable names (e.g., Set { '--wpds-token' }).
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* extractCSSVariables(
|
|
16
|
+
* 'border: 1px solid var(--wpds-border-radius-sm, var(--wpds-border-radius-md)); ' +
|
|
17
|
+
* 'color: var(--wpds-color-foreground-content-neutral, black); ' +
|
|
18
|
+
* 'background: var(--unrelated-bg);',
|
|
19
|
+
* 'wpds'
|
|
20
|
+
* );
|
|
21
|
+
* // → Set { '--wpds-border-radius-sm', '--wpds-border-radius-md', '--wpds-color-foreground-content-neutral' }
|
|
22
|
+
*/
|
|
23
|
+
function extractCSSVariables( value, prefix = '' ) {
|
|
24
|
+
const regex = /--[\w-]+/g;
|
|
25
|
+
/** @type {Set<string>} */
|
|
26
|
+
const variables = new Set();
|
|
27
|
+
|
|
28
|
+
let match;
|
|
29
|
+
while ( ( match = regex.exec( value ) ) !== null ) {
|
|
30
|
+
const variableName = match[ 0 ];
|
|
31
|
+
if ( variableName.startsWith( `--${ prefix }` ) ) {
|
|
32
|
+
variables.add( variableName );
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
return variables;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const knownTokens = new Set( tokenList ?? [] );
|
|
40
|
+
const wpdsTokensRegex = new RegExp( `[^\\w]--${ DS_TOKEN_PREFIX }`, 'i' );
|
|
41
|
+
|
|
42
|
+
const {
|
|
43
|
+
createPlugin,
|
|
44
|
+
utils: { report, ruleMessages, validateOptions },
|
|
45
|
+
} = stylelint;
|
|
46
|
+
|
|
47
|
+
const ruleName = 'plugin-wpds/no-unknown-ds-tokens';
|
|
48
|
+
|
|
49
|
+
const messages = ruleMessages( ruleName, {
|
|
50
|
+
rejected: ( tokenNames ) =>
|
|
51
|
+
`The following CSS variables are not valid Design System tokens: ${ tokenNames }`,
|
|
52
|
+
} );
|
|
53
|
+
|
|
54
|
+
/** @type {import('stylelint').Rule} */
|
|
55
|
+
const ruleFunction = ( primary ) => {
|
|
56
|
+
return ( root, result ) => {
|
|
57
|
+
const validOptions = validateOptions( result, ruleName, {
|
|
58
|
+
actual: primary,
|
|
59
|
+
possible: [ true ],
|
|
60
|
+
} );
|
|
61
|
+
|
|
62
|
+
// Without `@wordpress/theme` there is no token list to validate against.
|
|
63
|
+
if ( ! validOptions || ! tokenList ) {
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
root.walkDecls( ( ruleNode ) => {
|
|
68
|
+
const { value } = ruleNode;
|
|
69
|
+
// Early match for WPDS tokens to avoid unnecessary processing.
|
|
70
|
+
if ( wpdsTokensRegex.test( value ) ) {
|
|
71
|
+
const usedTokens = extractCSSVariables(
|
|
72
|
+
value,
|
|
73
|
+
DS_TOKEN_PREFIX
|
|
74
|
+
);
|
|
75
|
+
const unknownTokens = new Set(
|
|
76
|
+
[ ...usedTokens ].filter(
|
|
77
|
+
( token ) => ! knownTokens.has( token )
|
|
78
|
+
)
|
|
79
|
+
);
|
|
80
|
+
|
|
81
|
+
if ( unknownTokens.size > 0 ) {
|
|
82
|
+
report( {
|
|
83
|
+
message: messages.rejected(
|
|
84
|
+
Array.from( unknownTokens )
|
|
85
|
+
.map( ( token ) => `'${ token }'` )
|
|
86
|
+
.join( ', ' )
|
|
87
|
+
),
|
|
88
|
+
node: ruleNode,
|
|
89
|
+
result,
|
|
90
|
+
ruleName,
|
|
91
|
+
} );
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
} );
|
|
95
|
+
};
|
|
96
|
+
};
|
|
97
|
+
|
|
98
|
+
ruleFunction.ruleName = ruleName;
|
|
99
|
+
ruleFunction.messages = messages;
|
|
100
|
+
|
|
101
|
+
/** @type {import('stylelint').Plugin} */
|
|
102
|
+
export default createPlugin( ruleName, ruleFunction );
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { transformDsTokenFallbacks } from '../js-plugins/transform-ds-token-fallbacks.mjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Vite plugin that injects design-system token fallbacks into JS/TS files.
|
|
5
|
+
*
|
|
6
|
+
* Replaces bare `var(--wpds-*)` references in string literals with
|
|
7
|
+
* `var(--wpds-*, <fallback>)` so components render correctly without
|
|
8
|
+
* a ThemeProvider. Does nothing when `@wordpress/theme` is not installed.
|
|
9
|
+
*
|
|
10
|
+
* @type {() => import('vite').Plugin}
|
|
11
|
+
*/
|
|
12
|
+
const plugin = () => ( {
|
|
13
|
+
name: 'ds-token-fallbacks-js',
|
|
14
|
+
enforce: 'pre',
|
|
15
|
+
transform( code, id ) {
|
|
16
|
+
const [ filename, query = '' ] = id.split( '?' );
|
|
17
|
+
const params = new URLSearchParams( query );
|
|
18
|
+
if (
|
|
19
|
+
! /\.[mc]?[jt]sx?$/.test( filename ) ||
|
|
20
|
+
params.has( 'raw' ) ||
|
|
21
|
+
params.has( 'url' )
|
|
22
|
+
) {
|
|
23
|
+
return null;
|
|
24
|
+
}
|
|
25
|
+
if ( id.includes( 'node_modules' ) ) {
|
|
26
|
+
return null;
|
|
27
|
+
}
|
|
28
|
+
const result = transformDsTokenFallbacks( code, filename );
|
|
29
|
+
return result ? { code: result.code, map: result.map } : null;
|
|
30
|
+
},
|
|
31
|
+
} );
|
|
32
|
+
|
|
33
|
+
export default plugin;
|