@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,106 @@
|
|
|
1
|
+
import valueParser from 'postcss-value-parser';
|
|
2
|
+
|
|
3
|
+
const identifierPattern = String.raw`(?:[\w\u0080-\uFFFF-]|\\(?:[\da-f]{1,6}(?:\r\n|[ \t\n\r\f])?|[^\n\r\f]))+`;
|
|
4
|
+
const identifierStart = new RegExp( `^${ identifierPattern }`, 'i' );
|
|
5
|
+
const identifiers = new RegExp( identifierPattern, 'gi' );
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Decode CSS escapes without changing the source nodes used for serialization.
|
|
9
|
+
*
|
|
10
|
+
* @param {string} identifier A CSS identifier's source spelling.
|
|
11
|
+
* @return {string} The decoded identifier.
|
|
12
|
+
*/
|
|
13
|
+
function decodeIdentifier( identifier ) {
|
|
14
|
+
return identifier.replace(
|
|
15
|
+
/\\(?:([\da-f]{1,6})(?:\r\n|[ \t\n\r\f])?|([^\n\r\f]))/gi,
|
|
16
|
+
( match, hex, character ) => {
|
|
17
|
+
if ( ! hex ) {
|
|
18
|
+
return character;
|
|
19
|
+
}
|
|
20
|
+
const codePoint = parseInt( hex, 16 );
|
|
21
|
+
return codePoint === 0 ||
|
|
22
|
+
codePoint > 0x10ffff ||
|
|
23
|
+
( codePoint >= 0xd800 && codePoint <= 0xdfff )
|
|
24
|
+
? '\uFFFD'
|
|
25
|
+
: String.fromCodePoint( codePoint );
|
|
26
|
+
}
|
|
27
|
+
);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* @param {import('postcss-value-parser').Node} node A parsed value node.
|
|
32
|
+
* @return {node is import('postcss-value-parser').DivNode} Whether the node separates a fallback value.
|
|
33
|
+
*/
|
|
34
|
+
function isFallbackSeparator( node ) {
|
|
35
|
+
return node.type === 'div' && node.value === ',';
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Parse the custom property references in CSS `var()` functions.
|
|
40
|
+
*
|
|
41
|
+
* String, URL, and comment contents are not treated as CSS functions.
|
|
42
|
+
*
|
|
43
|
+
* @param {string} value A CSS declaration value.
|
|
44
|
+
* @return {{ parsed: import('postcss-value-parser').ParsedValue, references: Array<{ name: string, sourceIndex: number, fallbackSeparator: import('postcss-value-parser').DivNode | undefined, node: import('postcss-value-parser').FunctionNode }> }} The parsed value and its custom property references.
|
|
45
|
+
*/
|
|
46
|
+
export function parseCSSVariableReferences( value ) {
|
|
47
|
+
const parsed = valueParser( value );
|
|
48
|
+
/** @type {Map<number, number>} */
|
|
49
|
+
const variableFunctionStarts = new Map();
|
|
50
|
+
// Hexadecimal escapes can split function names across value-parser nodes.
|
|
51
|
+
// Scan once to locate their complete source spelling.
|
|
52
|
+
for ( const identifier of value.matchAll( identifiers ) ) {
|
|
53
|
+
const end = identifier.index + identifier[ 0 ].length;
|
|
54
|
+
const prefix = value[ identifier.index - 1 ];
|
|
55
|
+
if (
|
|
56
|
+
prefix !== '#' &&
|
|
57
|
+
prefix !== '@' &&
|
|
58
|
+
value[ end ] === '(' &&
|
|
59
|
+
decodeIdentifier( identifier[ 0 ] ).toLowerCase() === 'var'
|
|
60
|
+
) {
|
|
61
|
+
variableFunctionStarts.set( end, identifier.index );
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
/** @type {Array<{ name: string, sourceIndex: number, fallbackSeparator: import('postcss-value-parser').DivNode | undefined, node: import('postcss-value-parser').FunctionNode }>} */
|
|
65
|
+
const references = [];
|
|
66
|
+
|
|
67
|
+
parsed.walk( ( node ) => {
|
|
68
|
+
if ( node.type !== 'function' ) {
|
|
69
|
+
return;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const sourceIndex = variableFunctionStarts.get(
|
|
73
|
+
node.sourceIndex + node.value.length
|
|
74
|
+
);
|
|
75
|
+
if ( sourceIndex === undefined ) {
|
|
76
|
+
return;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const nameNode = node.nodes.find(
|
|
80
|
+
( child ) => child.type !== 'space' && child.type !== 'comment'
|
|
81
|
+
);
|
|
82
|
+
|
|
83
|
+
if ( nameNode?.type !== 'word' ) {
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// A hexadecimal escape's terminating whitespace can split an identifier
|
|
88
|
+
// across value-parser nodes. Read the whole identifier from its source.
|
|
89
|
+
const spelling = value
|
|
90
|
+
.slice( nameNode.sourceIndex )
|
|
91
|
+
.match( identifierStart )?.[ 0 ];
|
|
92
|
+
const name = decodeIdentifier( spelling ?? '' );
|
|
93
|
+
if ( ! name.startsWith( '--' ) ) {
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
references.push( {
|
|
98
|
+
name,
|
|
99
|
+
sourceIndex,
|
|
100
|
+
fallbackSeparator: node.nodes.find( isFallbackSeparator ),
|
|
101
|
+
node,
|
|
102
|
+
} );
|
|
103
|
+
} );
|
|
104
|
+
|
|
105
|
+
return { parsed, references };
|
|
106
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { addFallbackToVarInCSS } 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 = addFallbackToVarInCSS( 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,86 @@
|
|
|
1
|
+
import stylelint from 'stylelint';
|
|
2
|
+
import { parseCSSVariableReferences } from '../postcss-plugins/parse-css-variables.mjs';
|
|
3
|
+
|
|
4
|
+
const {
|
|
5
|
+
createPlugin,
|
|
6
|
+
utils: { report, ruleMessages, validateOptions },
|
|
7
|
+
} = stylelint;
|
|
8
|
+
|
|
9
|
+
const ruleName = 'plugin-wpds/no-token-fallback-values';
|
|
10
|
+
|
|
11
|
+
const messages = ruleMessages( ruleName, {
|
|
12
|
+
rejected: ( tokenName ) =>
|
|
13
|
+
`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).`,
|
|
14
|
+
} );
|
|
15
|
+
|
|
16
|
+
/** @type {import('stylelint').Rule} */
|
|
17
|
+
const ruleFunction = ( primary ) => {
|
|
18
|
+
return ( root, result ) => {
|
|
19
|
+
const validOptions = validateOptions( result, ruleName, {
|
|
20
|
+
actual: primary,
|
|
21
|
+
possible: [ true ],
|
|
22
|
+
} );
|
|
23
|
+
|
|
24
|
+
if ( ! validOptions ) {
|
|
25
|
+
return;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
root.walkDecls( ( ruleNode ) => {
|
|
29
|
+
if (
|
|
30
|
+
! ruleNode.value.includes( '--wpds-' ) &&
|
|
31
|
+
! ruleNode.value.includes( '\\' )
|
|
32
|
+
) {
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
const declaration = ruleNode.toString();
|
|
37
|
+
const references =
|
|
38
|
+
parseCSSVariableReferences( declaration ).references;
|
|
39
|
+
let { line, column } = ruleNode.rangeBy( { index: 0 } ).start;
|
|
40
|
+
let offset = 0;
|
|
41
|
+
|
|
42
|
+
// SCSS serialization adds closing delimiters to line comments. Those
|
|
43
|
+
// change offsets, but not line/column positions on subsequent lines.
|
|
44
|
+
// References are visited in source order, so advance one shared cursor.
|
|
45
|
+
/** @param {number} index Offset in the serialized declaration. */
|
|
46
|
+
const getPosition = ( index ) => {
|
|
47
|
+
while ( offset < index ) {
|
|
48
|
+
if ( declaration[ offset++ ] === '\n' ) {
|
|
49
|
+
line++;
|
|
50
|
+
column = 1;
|
|
51
|
+
} else {
|
|
52
|
+
column++;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
return { line, column };
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
for ( const reference of references ) {
|
|
59
|
+
if (
|
|
60
|
+
! reference.name.startsWith( '--wpds-' ) ||
|
|
61
|
+
! reference.fallbackSeparator
|
|
62
|
+
) {
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
report( {
|
|
67
|
+
message: messages.rejected( reference.name ),
|
|
68
|
+
node: ruleNode,
|
|
69
|
+
start: getPosition( reference.sourceIndex ),
|
|
70
|
+
end: getPosition(
|
|
71
|
+
reference.fallbackSeparator.sourceEndIndex -
|
|
72
|
+
reference.fallbackSeparator.after.length
|
|
73
|
+
),
|
|
74
|
+
result,
|
|
75
|
+
ruleName,
|
|
76
|
+
} );
|
|
77
|
+
}
|
|
78
|
+
} );
|
|
79
|
+
};
|
|
80
|
+
};
|
|
81
|
+
|
|
82
|
+
ruleFunction.ruleName = ruleName;
|
|
83
|
+
ruleFunction.messages = messages;
|
|
84
|
+
|
|
85
|
+
/** @type {import('stylelint').Plugin} */
|
|
86
|
+
export default createPlugin( ruleName, ruleFunction );
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import stylelint from 'stylelint';
|
|
2
|
+
import { tokenList } from '../lib/theme-tokens.mjs';
|
|
3
|
+
import { parseCSSVariableReferences } from '../postcss-plugins/parse-css-variables.mjs';
|
|
4
|
+
|
|
5
|
+
const DS_TOKEN_PREFIX = 'wpds-';
|
|
6
|
+
|
|
7
|
+
const knownTokens = new Set( tokenList ?? [] );
|
|
8
|
+
|
|
9
|
+
const {
|
|
10
|
+
createPlugin,
|
|
11
|
+
utils: { report, ruleMessages, validateOptions },
|
|
12
|
+
} = stylelint;
|
|
13
|
+
|
|
14
|
+
const ruleName = 'plugin-wpds/no-unknown-ds-tokens';
|
|
15
|
+
|
|
16
|
+
const messages = ruleMessages( ruleName, {
|
|
17
|
+
rejected: ( tokenNames ) =>
|
|
18
|
+
`The following CSS variables are not valid Design System tokens: ${ tokenNames }`,
|
|
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
|
+
// Without `@wordpress/theme` there is no token list to validate against.
|
|
30
|
+
if ( ! validOptions || ! tokenList ) {
|
|
31
|
+
return;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
root.walkDecls( ( ruleNode ) => {
|
|
35
|
+
const { value } = ruleNode;
|
|
36
|
+
if (
|
|
37
|
+
value.includes( `--${ DS_TOKEN_PREFIX }` ) ||
|
|
38
|
+
value.includes( '\\' )
|
|
39
|
+
) {
|
|
40
|
+
const { references } = parseCSSVariableReferences( value );
|
|
41
|
+
const unknownTokens = new Set(
|
|
42
|
+
references
|
|
43
|
+
.map( ( reference ) => reference.name )
|
|
44
|
+
.filter(
|
|
45
|
+
( name ) =>
|
|
46
|
+
name.startsWith( `--${ DS_TOKEN_PREFIX }` ) &&
|
|
47
|
+
! knownTokens.has( name )
|
|
48
|
+
)
|
|
49
|
+
);
|
|
50
|
+
|
|
51
|
+
if ( unknownTokens.size > 0 ) {
|
|
52
|
+
report( {
|
|
53
|
+
message: messages.rejected(
|
|
54
|
+
Array.from( unknownTokens )
|
|
55
|
+
.map( ( token ) => `'${ token }'` )
|
|
56
|
+
.join( ', ' )
|
|
57
|
+
),
|
|
58
|
+
node: ruleNode,
|
|
59
|
+
result,
|
|
60
|
+
ruleName,
|
|
61
|
+
} );
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
} );
|
|
65
|
+
};
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
ruleFunction.ruleName = ruleName;
|
|
69
|
+
ruleFunction.messages = messages;
|
|
70
|
+
|
|
71
|
+
/** @type {import('stylelint').Plugin} */
|
|
72
|
+
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;
|