@wordpress/theme-build-tools 0.0.0-stage → 1.1.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 +137 -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 +46 -0
- package/build-types/postcss-plugins/ds-token-fallbacks.d.mts +48 -0
- package/build-types/postcss-plugins/parse-css-variables.d.mts +18 -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 +127 -5
- package/postcss-plugins/add-fallback-to-var.mjs +97 -0
- package/postcss-plugins/ds-token-fallbacks.mjs +67 -0
- package/postcss-plugins/parse-css-variables.mjs +106 -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 +86 -0
- package/stylelint-plugins/no-unknown-ds-tokens.mjs +72 -0
- package/vite-plugins/vite-ds-token-fallbacks.mjs +33 -0
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
import { parse } from '@babel/parser';
|
|
2
|
+
import { isTSType, traverse } from '@babel/types';
|
|
3
|
+
import MagicString from 'magic-string';
|
|
4
|
+
import {
|
|
5
|
+
addFallbackToVar,
|
|
6
|
+
hasTokenFallbacks,
|
|
7
|
+
} from '../postcss-plugins/ds-token-fallbacks.mjs';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Whether an ancestor makes a literal part of a name, module path, or type.
|
|
11
|
+
*
|
|
12
|
+
* @param {import('@babel/types').TraversalAncestors} ancestors Ancestors.
|
|
13
|
+
* @return {boolean} Whether to leave the literal alone.
|
|
14
|
+
*/
|
|
15
|
+
function isNonValue( ancestors ) {
|
|
16
|
+
return ancestors.some( ( { node, key } ) => {
|
|
17
|
+
if ( isTSType( node ) ) {
|
|
18
|
+
return true;
|
|
19
|
+
}
|
|
20
|
+
if (
|
|
21
|
+
[
|
|
22
|
+
'source',
|
|
23
|
+
'key',
|
|
24
|
+
'property',
|
|
25
|
+
'imported',
|
|
26
|
+
'exported',
|
|
27
|
+
'local',
|
|
28
|
+
].includes( key )
|
|
29
|
+
) {
|
|
30
|
+
return true;
|
|
31
|
+
}
|
|
32
|
+
return (
|
|
33
|
+
node.type === 'ImportAttribute' ||
|
|
34
|
+
( ( node.type === 'TSModuleDeclaration' ||
|
|
35
|
+
node.type === 'TSEnumMember' ) &&
|
|
36
|
+
key === 'id' ) ||
|
|
37
|
+
node.type === 'TSExternalModuleReference' ||
|
|
38
|
+
node.type === 'ImportExpression' ||
|
|
39
|
+
( node.type === 'CallExpression' &&
|
|
40
|
+
( node.callee.type === 'Import' ||
|
|
41
|
+
( node.callee.type === 'Identifier' &&
|
|
42
|
+
node.callee.name === 'require' ) ) )
|
|
43
|
+
);
|
|
44
|
+
} );
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Inject fallbacks into JavaScript values without rewriting other source text.
|
|
49
|
+
* The caller is responsible for composing the returned source map.
|
|
50
|
+
*
|
|
51
|
+
* @param {string} source JavaScript or TypeScript source.
|
|
52
|
+
* @param {string} filename Source filename, without a query string.
|
|
53
|
+
* @return {{ code: string, map: import('magic-string').SourceMap, sourceMappingURL: string | undefined } | null} Transformation, or null when unchanged, unparseable, or `@wordpress/theme` is not installed.
|
|
54
|
+
*/
|
|
55
|
+
export function transformDsTokenFallbacks( source, filename ) {
|
|
56
|
+
if ( ! hasTokenFallbacks || ! source.includes( '--wpds-' ) ) {
|
|
57
|
+
return null;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
const isTypeScript = /\.[mc]?tsx?$/.test( filename );
|
|
61
|
+
/** @type {import('@babel/parser').ParserOptions} */
|
|
62
|
+
const options = {
|
|
63
|
+
sourceType: 'unambiguous',
|
|
64
|
+
allowReturnOutsideFunction: true,
|
|
65
|
+
allowAwaitOutsideFunction: true,
|
|
66
|
+
allowUndeclaredExports: true,
|
|
67
|
+
attachComment: false,
|
|
68
|
+
errorRecovery: true,
|
|
69
|
+
plugins: [
|
|
70
|
+
...( isTypeScript
|
|
71
|
+
? [ /** @type {const} */ ( 'typescript' ) ]
|
|
72
|
+
: [] ),
|
|
73
|
+
...( /\.[mc]?ts$/.test( filename )
|
|
74
|
+
? []
|
|
75
|
+
: [ /** @type {const} */ ( 'jsx' ) ] ),
|
|
76
|
+
'decorators',
|
|
77
|
+
'decoratorAutoAccessors',
|
|
78
|
+
'deprecatedImportAssert',
|
|
79
|
+
'sourcePhaseImports',
|
|
80
|
+
'deferredImportEvaluation',
|
|
81
|
+
],
|
|
82
|
+
};
|
|
83
|
+
let parserSource = source;
|
|
84
|
+
/** @type {ReturnType<typeof parse>} */
|
|
85
|
+
let ast;
|
|
86
|
+
for (;;) {
|
|
87
|
+
try {
|
|
88
|
+
ast = parse( parserSource, options );
|
|
89
|
+
// Unambiguous parsing can retain module errors in a valid script.
|
|
90
|
+
if ( ast.program.sourceType === 'script' && ast.errors?.length ) {
|
|
91
|
+
ast = parse( parserSource, {
|
|
92
|
+
...options,
|
|
93
|
+
sourceType: 'script',
|
|
94
|
+
} );
|
|
95
|
+
}
|
|
96
|
+
break;
|
|
97
|
+
} catch ( error ) {
|
|
98
|
+
const parseError =
|
|
99
|
+
/** @type {import('@babel/parser').ParseError} */ ( error );
|
|
100
|
+
if ( parseError.code !== 'BABEL_PARSER_SYNTAX_ERROR' ) {
|
|
101
|
+
throw error;
|
|
102
|
+
}
|
|
103
|
+
if (
|
|
104
|
+
! isTypeScript ||
|
|
105
|
+
! [ 'UnexpectedLeadingDecorator', 'UnexpectedToken' ].includes(
|
|
106
|
+
parseError.reasonCode
|
|
107
|
+
) ||
|
|
108
|
+
! Number.isInteger( parseError.pos ) ||
|
|
109
|
+
parserSource[ parseError.pos ] !== '!'
|
|
110
|
+
) {
|
|
111
|
+
// A later compiler plugin may understand syntax Babel does not.
|
|
112
|
+
return null;
|
|
113
|
+
}
|
|
114
|
+
// Babel's decorator grammar rejects TypeScript non-null assertions.
|
|
115
|
+
// Mask only the rejected token for parsing, preserving source offsets.
|
|
116
|
+
// The downstream compiler still receives the original assertion.
|
|
117
|
+
parserSource =
|
|
118
|
+
parserSource.slice( 0, parseError.pos ) +
|
|
119
|
+
' ' +
|
|
120
|
+
parserSource.slice( parseError.pos + 1 );
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
// Babel's standard decorators grammar reports parameter decorators even
|
|
124
|
+
// in TypeScript. Leave that one check to the compiler's tsconfig settings.
|
|
125
|
+
for ( const error of ast.errors ?? [] ) {
|
|
126
|
+
if (
|
|
127
|
+
! isTypeScript ||
|
|
128
|
+
error.reasonCode !== 'UnsupportedParameterDecorator'
|
|
129
|
+
) {
|
|
130
|
+
return null;
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
const output = new MagicString( source );
|
|
134
|
+
|
|
135
|
+
traverse( ast, ( node, ancestors ) => {
|
|
136
|
+
if (
|
|
137
|
+
( node.type !== 'StringLiteral' &&
|
|
138
|
+
node.type !== 'TemplateElement' ) ||
|
|
139
|
+
typeof node.start !== 'number' ||
|
|
140
|
+
typeof node.end !== 'number' ||
|
|
141
|
+
isNonValue( ancestors )
|
|
142
|
+
) {
|
|
143
|
+
return;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
if ( node.type === 'StringLiteral' ) {
|
|
147
|
+
const value = addFallbackToVar( node.value );
|
|
148
|
+
if ( value === node.value ) {
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
// Keep JSX literals as literals: JSX compilers can normalize their
|
|
152
|
+
// whitespace differently from JavaScript expression values.
|
|
153
|
+
const isAttribute =
|
|
154
|
+
ancestors.at( -1 )?.node.type === 'JSXAttribute';
|
|
155
|
+
output.overwrite(
|
|
156
|
+
node.start,
|
|
157
|
+
node.end,
|
|
158
|
+
isAttribute
|
|
159
|
+
? `"${ value.replaceAll( '&', '&' ).replaceAll( '"', '"' ) }"`
|
|
160
|
+
: JSON.stringify( value )
|
|
161
|
+
);
|
|
162
|
+
return;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
// Tags can observe raw text, including String.raw and CSS-in-JS tags.
|
|
166
|
+
// Preserve their existing escapes and insert the CSS fallback verbatim.
|
|
167
|
+
const tagged =
|
|
168
|
+
ancestors.at( -2 )?.node.type === 'TaggedTemplateExpression';
|
|
169
|
+
const original = tagged ? node.value.raw : node.value.cooked;
|
|
170
|
+
if ( typeof original !== 'string' ) {
|
|
171
|
+
return;
|
|
172
|
+
}
|
|
173
|
+
const value = addFallbackToVar( original );
|
|
174
|
+
if ( value !== original ) {
|
|
175
|
+
output.overwrite(
|
|
176
|
+
node.start,
|
|
177
|
+
node.end,
|
|
178
|
+
tagged
|
|
179
|
+
? value
|
|
180
|
+
: JSON.stringify( value )
|
|
181
|
+
.slice( 1, -1 )
|
|
182
|
+
.replaceAll( '\\"', '"' )
|
|
183
|
+
.replaceAll( '`', '\\`' )
|
|
184
|
+
.replaceAll( '${', '\\${' )
|
|
185
|
+
);
|
|
186
|
+
}
|
|
187
|
+
} );
|
|
188
|
+
|
|
189
|
+
if ( ! output.hasChanged() ) {
|
|
190
|
+
return null;
|
|
191
|
+
}
|
|
192
|
+
// Read actual comments, not directive-shaped text inside strings/templates.
|
|
193
|
+
let sourceMappingURL;
|
|
194
|
+
for ( const comment of ast.comments ?? [] ) {
|
|
195
|
+
const match = /^[#@]\s*sourceMappingURL=(\S+)\s*$/.exec(
|
|
196
|
+
comment.value
|
|
197
|
+
);
|
|
198
|
+
if ( match ) {
|
|
199
|
+
sourceMappingURL = match[ 1 ];
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
return {
|
|
203
|
+
code: output.toString(),
|
|
204
|
+
sourceMappingURL,
|
|
205
|
+
map: output.generateMap( {
|
|
206
|
+
source: filename,
|
|
207
|
+
includeContent: true,
|
|
208
|
+
hires: true,
|
|
209
|
+
} ),
|
|
210
|
+
};
|
|
211
|
+
}
|
|
@@ -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,128 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@wordpress/theme-build-tools",
|
|
3
|
+
"version": "1.1.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
|
+
"postcss-value-parser": "^4.2.0"
|
|
79
|
+
},
|
|
80
|
+
"devDependencies": {
|
|
81
|
+
"@types/node": "^24.13.3",
|
|
82
|
+
"@wordpress/theme": "^5.0.0",
|
|
83
|
+
"@wordpress/validation-tools": "file:../../tools/validation",
|
|
84
|
+
"esbuild": "^0.27.2",
|
|
85
|
+
"lightningcss": "^1.33.0",
|
|
86
|
+
"postcss": "^8.5.33",
|
|
87
|
+
"postcss-scss": "^4.0.9",
|
|
88
|
+
"source-map": "^0.6.1",
|
|
89
|
+
"stylelint": "^17.14.1",
|
|
90
|
+
"vite": "^8.3.8",
|
|
91
|
+
"vitest": "^5.1.0"
|
|
92
|
+
},
|
|
93
|
+
"peerDependencies": {
|
|
94
|
+
"@wordpress/theme": "^3.0.0 || ^4.0.0 || ^5.0.0",
|
|
95
|
+
"esbuild": ">=0.27.2 <1.0.0",
|
|
96
|
+
"lightningcss": ">=1.33.0 <2.0.0",
|
|
97
|
+
"postcss": "^8.0.0",
|
|
98
|
+
"stylelint": "^16 || ^17",
|
|
99
|
+
"vite": "^7 || ^8"
|
|
100
|
+
},
|
|
101
|
+
"peerDependenciesMeta": {
|
|
102
|
+
"@wordpress/theme": {
|
|
103
|
+
"optional": true
|
|
104
|
+
},
|
|
105
|
+
"esbuild": {
|
|
106
|
+
"optional": true
|
|
107
|
+
},
|
|
108
|
+
"lightningcss": {
|
|
109
|
+
"optional": true
|
|
110
|
+
},
|
|
111
|
+
"postcss": {
|
|
112
|
+
"optional": true
|
|
113
|
+
},
|
|
114
|
+
"stylelint": {
|
|
115
|
+
"optional": true
|
|
116
|
+
},
|
|
117
|
+
"vite": {
|
|
118
|
+
"optional": true
|
|
119
|
+
}
|
|
120
|
+
},
|
|
121
|
+
"publishConfig": {
|
|
122
|
+
"access": "public"
|
|
123
|
+
},
|
|
124
|
+
"scripts": {
|
|
125
|
+
"lint:package-contents": "wp-validate-package-contents . --disallow-path test"
|
|
126
|
+
},
|
|
127
|
+
"gitHead": "1000cdf1dffd5b5e69f75cc4360aa76db8252264"
|
|
128
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import valueParser from 'postcss-value-parser';
|
|
2
|
+
import { parseCSSVariableReferences } from './parse-css-variables.mjs';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Replace bare `var(--wpds-*)` references in a CSS value string with
|
|
6
|
+
* `var(--wpds-*, <fallback>)` using the provided token fallback map.
|
|
7
|
+
*
|
|
8
|
+
* Existing fallbacks (i.e. `var()` calls that already contain a comma)
|
|
9
|
+
* are left untouched, making the function safe to run multiple times
|
|
10
|
+
* (idempotent).
|
|
11
|
+
*
|
|
12
|
+
* This is the generic, reusable implementation that takes the fallback
|
|
13
|
+
* map as an argument. For the variant prebound with the package's
|
|
14
|
+
* generated token fallback map, see `./ds-token-fallbacks.mjs`.
|
|
15
|
+
*
|
|
16
|
+
* @param {string} cssValue A CSS declaration value.
|
|
17
|
+
* @param {Record<string, string>} tokenFallbacks Map of CSS variable names to their fallback expressions.
|
|
18
|
+
* @param {Object} [options] Options.
|
|
19
|
+
* @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in fallback values.
|
|
20
|
+
* Use this when the input is JS/TS source so that
|
|
21
|
+
* injected quotes don't break string literals. JS
|
|
22
|
+
* will unescape them at parse time, so the browser's
|
|
23
|
+
* CSS engine still sees the correct value.
|
|
24
|
+
* @return {string} The value with fallbacks injected.
|
|
25
|
+
*/
|
|
26
|
+
export function addFallbackToVar(
|
|
27
|
+
cssValue,
|
|
28
|
+
tokenFallbacks,
|
|
29
|
+
{ escapeQuotes = false } = {}
|
|
30
|
+
) {
|
|
31
|
+
return cssValue.replace(
|
|
32
|
+
/var\(\s*(--wpds-[\w-]+)\s*\)/g,
|
|
33
|
+
( match, tokenName ) => {
|
|
34
|
+
const fallback = getTokenFallback( tokenName, tokenFallbacks, {
|
|
35
|
+
escapeQuotes,
|
|
36
|
+
} );
|
|
37
|
+
return `var(${ tokenName }, ${ fallback })`;
|
|
38
|
+
}
|
|
39
|
+
);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Replace bare `var(--wpds-*)` references in a parsed CSS value.
|
|
44
|
+
*
|
|
45
|
+
* @param {string} cssValue A CSS declaration value.
|
|
46
|
+
* @param {Record<string, string>} tokenFallbacks Map of CSS variable names to fallback expressions.
|
|
47
|
+
* @return {string} The value with fallbacks injected.
|
|
48
|
+
*/
|
|
49
|
+
export function addFallbackToVarInCSS( cssValue, tokenFallbacks ) {
|
|
50
|
+
if ( ! cssValue.includes( '--wpds-' ) && ! cssValue.includes( '\\' ) ) {
|
|
51
|
+
return cssValue;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const { parsed, references } = parseCSSVariableReferences( cssValue );
|
|
55
|
+
|
|
56
|
+
for ( const reference of references ) {
|
|
57
|
+
if (
|
|
58
|
+
! reference.name.startsWith( '--wpds-' ) ||
|
|
59
|
+
reference.fallbackSeparator
|
|
60
|
+
) {
|
|
61
|
+
continue;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const fallback = getTokenFallback( reference.name, tokenFallbacks );
|
|
65
|
+
reference.node.nodes.push( ...valueParser( `, ${ fallback }` ).nodes );
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
return parsed.toString();
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Get the fallback for a design token.
|
|
73
|
+
*
|
|
74
|
+
* @param {string} tokenName CSS variable name.
|
|
75
|
+
* @param {Record<string, string>} tokenFallbacks Map of CSS variable names to fallback expressions.
|
|
76
|
+
* @param {Object} [options] Options.
|
|
77
|
+
* @param {boolean} [options.escapeQuotes] Whether to escape quotes in the fallback.
|
|
78
|
+
* @return {string} The token fallback.
|
|
79
|
+
*/
|
|
80
|
+
export function getTokenFallback(
|
|
81
|
+
tokenName,
|
|
82
|
+
tokenFallbacks,
|
|
83
|
+
{ escapeQuotes = false } = {}
|
|
84
|
+
) {
|
|
85
|
+
let fallback = tokenFallbacks[ tokenName ];
|
|
86
|
+
if ( fallback === undefined ) {
|
|
87
|
+
throw new Error(
|
|
88
|
+
`Unknown design token: ${ tokenName }. ` +
|
|
89
|
+
'This token is not in the design system. ' +
|
|
90
|
+
'If this token was recently renamed, update all references to use the new name.'
|
|
91
|
+
);
|
|
92
|
+
}
|
|
93
|
+
if ( escapeQuotes ) {
|
|
94
|
+
fallback = fallback.replaceAll( '"', '\\"' ).replaceAll( "'", "\\'" );
|
|
95
|
+
}
|
|
96
|
+
return fallback;
|
|
97
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { tokenFallbacks } from '../lib/theme-tokens.mjs';
|
|
2
|
+
import {
|
|
3
|
+
addFallbackToVar as _addFallbackToVar,
|
|
4
|
+
addFallbackToVarInCSS as _addFallbackToVarInCSS,
|
|
5
|
+
getTokenFallback as _getTokenFallback,
|
|
6
|
+
} from './add-fallback-to-var.mjs';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Replace bare `var(--wpds-*)` references in a CSS value string with
|
|
10
|
+
* `var(--wpds-*, <fallback>)` using the package's generated token
|
|
11
|
+
* fallback map.
|
|
12
|
+
*
|
|
13
|
+
* Existing fallbacks (i.e. var() calls that already contain a comma) are
|
|
14
|
+
* left untouched, making the function safe to run multiple times.
|
|
15
|
+
*
|
|
16
|
+
* This is a thin wrapper around the generic `addFallbackToVar` helper in
|
|
17
|
+
* `./add-fallback-to-var.mjs`, prebound to the package's token fallback
|
|
18
|
+
* map. Update the regex/replacement logic in that file, not here.
|
|
19
|
+
*
|
|
20
|
+
* Returns the value unchanged when `@wordpress/theme` is not installed.
|
|
21
|
+
*
|
|
22
|
+
* @param {string} cssValue A CSS declaration value.
|
|
23
|
+
* @param {Object} [options] Options.
|
|
24
|
+
* @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in
|
|
25
|
+
* fallback values. Use this when the
|
|
26
|
+
* input is JS/TS source so that
|
|
27
|
+
* injected quotes don't break string
|
|
28
|
+
* literals. JS will unescape them at
|
|
29
|
+
* parse time, so the browser's CSS
|
|
30
|
+
* engine still sees the correct value.
|
|
31
|
+
* @return {string} The value with fallbacks injected.
|
|
32
|
+
*/
|
|
33
|
+
export function addFallbackToVar( cssValue, options ) {
|
|
34
|
+
if ( ! tokenFallbacks ) {
|
|
35
|
+
return cssValue;
|
|
36
|
+
}
|
|
37
|
+
return _addFallbackToVar( cssValue, tokenFallbacks, options );
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Whether design token fallbacks are available, i.e. whether
|
|
42
|
+
* `@wordpress/theme` is installed. The plugins do nothing without them.
|
|
43
|
+
*/
|
|
44
|
+
export const hasTokenFallbacks = tokenFallbacks !== undefined;
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Replace bare design token references in a parsed CSS declaration value.
|
|
48
|
+
*
|
|
49
|
+
* @param {string} cssValue A CSS declaration value.
|
|
50
|
+
* @return {string} The value with fallbacks injected.
|
|
51
|
+
*/
|
|
52
|
+
export function addFallbackToVarInCSS( cssValue ) {
|
|
53
|
+
if ( ! tokenFallbacks ) {
|
|
54
|
+
return cssValue;
|
|
55
|
+
}
|
|
56
|
+
return _addFallbackToVarInCSS( cssValue, tokenFallbacks );
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Get the generated fallback for a design token.
|
|
61
|
+
*
|
|
62
|
+
* @param {string} tokenName CSS variable name.
|
|
63
|
+
* @return {string} The token fallback.
|
|
64
|
+
*/
|
|
65
|
+
export function getTokenFallback( tokenName ) {
|
|
66
|
+
return _getTokenFallback( tokenName, tokenFallbacks ?? {} );
|
|
67
|
+
}
|