@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
package/README.md
CHANGED
|
@@ -1,3 +1,138 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Theme Build Tools
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Build plugins and Stylelint plugins for the WordPress Design System design tokens provided by [`@wordpress/theme`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/theme/README.md).
|
|
4
|
+
|
|
5
|
+
- The [Stylelint plugins](#stylelint-plugins) validate `--wpds-*` design token usage in CSS.
|
|
6
|
+
- The [build plugins](#build-plugins) inject the generated fallback values into `var(--wpds-*)` references, for PostCSS, Lightning CSS, esbuild, and Vite.
|
|
7
|
+
|
|
8
|
+
The token names and fallback values come from the `@wordpress/theme` package, which is an optional peer dependency, so they match the design tokens stylesheet of the version you installed. If `@wordpress/theme` is not installed, the plugins do nothing: the build plugins leave `var(--wpds-*)` references unchanged, and `no-unknown-ds-tokens` reports nothing.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm install @wordpress/theme-build-tools @wordpress/theme --save-dev
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Install the tool you use the plugins with (`stylelint`, `postcss`, `lightningcss`, `esbuild`, or `vite`) as well; they are optional peer dependencies.
|
|
17
|
+
|
|
18
|
+
The package's entrypoints are ESM-only and require Node.js `>=22.13.0`. Use `import` syntax from ESM or TypeScript configuration files.
|
|
19
|
+
|
|
20
|
+
## Stylelint Plugins
|
|
21
|
+
|
|
22
|
+
These rules validate design token usage in CSS. Enable them in your Stylelint configuration:
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"plugins": [
|
|
27
|
+
"@wordpress/theme-build-tools/stylelint-plugins/no-unknown-ds-tokens",
|
|
28
|
+
"@wordpress/theme-build-tools/stylelint-plugins/no-setting-wpds-custom-properties",
|
|
29
|
+
"@wordpress/theme-build-tools/stylelint-plugins/no-token-fallback-values"
|
|
30
|
+
],
|
|
31
|
+
"rules": {
|
|
32
|
+
"plugin-wpds/no-unknown-ds-tokens": true,
|
|
33
|
+
"plugin-wpds/no-setting-wpds-custom-properties": true,
|
|
34
|
+
"plugin-wpds/no-token-fallback-values": true
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### `plugin-wpds/no-unknown-ds-tokens`
|
|
40
|
+
|
|
41
|
+
Reports references to unknown `--wpds-*` tokens.
|
|
42
|
+
|
|
43
|
+
The rule checks CSS `var()` references. It ignores token-like text in strings and URLs.
|
|
44
|
+
|
|
45
|
+
### `plugin-wpds/no-setting-wpds-custom-properties`
|
|
46
|
+
|
|
47
|
+
Reports definitions or overrides in the `--wpds-*` namespace.
|
|
48
|
+
|
|
49
|
+
### `plugin-wpds/no-token-fallback-values`
|
|
50
|
+
|
|
51
|
+
Reports manual fallbacks that can drift from the generated values.
|
|
52
|
+
|
|
53
|
+
## Build Plugins
|
|
54
|
+
|
|
55
|
+
The build plugins inject generated fallbacks into bare `var(--wpds-*)` references so components still render when the design tokens stylesheet is unavailable. For example, `var(--wpds-color-foreground-content-neutral)` becomes `var(--wpds-color-foreground-content-neutral, #1e1e1e)`.
|
|
56
|
+
|
|
57
|
+
`@wordpress/build` already applies these plugins automatically. You only need to configure them manually for custom build setups.
|
|
58
|
+
|
|
59
|
+
| Export | Tool | Scope |
|
|
60
|
+
| ----------------------------------------------------------------------- | ------------- | ----- |
|
|
61
|
+
| `@wordpress/theme-build-tools/postcss-plugins/postcss-ds-token-fallbacks` | PostCSS | CSS |
|
|
62
|
+
| `@wordpress/theme-build-tools/lightningcss-plugins/lightningcss-ds-token-fallbacks` | Lightning CSS | CSS |
|
|
63
|
+
| `@wordpress/theme-build-tools/esbuild-plugins/esbuild-ds-token-fallbacks` | esbuild | JS/TS |
|
|
64
|
+
| `@wordpress/theme-build-tools/vite-plugins/vite-ds-token-fallbacks` | Vite | JS/TS |
|
|
65
|
+
|
|
66
|
+
Existing fallbacks are unchanged. An unknown token in a bare reference in transformed values fails the build.
|
|
67
|
+
|
|
68
|
+
The PostCSS plugin leaves token-like text in CSS strings and URLs unchanged.
|
|
69
|
+
|
|
70
|
+
The JavaScript plugins treat token references in string values, JSX attribute values, and static template parts as CSS. This includes tagged templates such as `String.raw`. They leave comments, regular expressions, property names, module paths, JSX text, and TypeScript types unchanged. Token names assembled across template expressions are not resolved. As before, a token reference in a runtime message string is also treated as CSS.
|
|
71
|
+
|
|
72
|
+
Files the JavaScript parser cannot read are left unchanged for the downstream compiler. To add fallbacks in Vite files that use custom syntax, configure the syntax-stripping plugin with `enforce: 'pre'` and list it before the token fallback plugin.
|
|
73
|
+
|
|
74
|
+
Both JavaScript plugins preserve source maps. The Vite plugin runs before JavaScript and TypeScript compilation and supports module IDs with query strings. It skips `?raw` and `?url` imports so their exported file contents and URLs stay unchanged.
|
|
75
|
+
|
|
76
|
+
### PostCSS
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
// postcss.config.mjs
|
|
80
|
+
import dsTokenFallbacks from '@wordpress/theme-build-tools/postcss-plugins/postcss-ds-token-fallbacks';
|
|
81
|
+
|
|
82
|
+
export default {
|
|
83
|
+
plugins: [ dsTokenFallbacks ],
|
|
84
|
+
};
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Lightning CSS
|
|
88
|
+
|
|
89
|
+
```js
|
|
90
|
+
import { transform, composeVisitors } from 'lightningcss';
|
|
91
|
+
import dsTokenFallbacks from '@wordpress/theme-build-tools/lightningcss-plugins/lightningcss-ds-token-fallbacks';
|
|
92
|
+
|
|
93
|
+
const { code } = transform( {
|
|
94
|
+
filename: 'styles.css',
|
|
95
|
+
code: Buffer.from( css ),
|
|
96
|
+
visitor: composeVisitors( [ dsTokenFallbacks ] ),
|
|
97
|
+
} );
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The visitor preserves CSS Modules [`from global`](https://lightningcss.dev/css-modules.html#local-css-variables) references such as `var(--wpds-dimension-gap-sm from global)` when it adds a fallback. Custom properties inside generated fallbacks, including `--wp-admin-*` variables, also remain global so admin overrides still apply.
|
|
101
|
+
|
|
102
|
+
### esbuild
|
|
103
|
+
|
|
104
|
+
```js
|
|
105
|
+
import dsTokenFallbacks from '@wordpress/theme-build-tools/esbuild-plugins/esbuild-ds-token-fallbacks';
|
|
106
|
+
|
|
107
|
+
await esbuild.build( {
|
|
108
|
+
plugins: [ dsTokenFallbacks ],
|
|
109
|
+
// …
|
|
110
|
+
} );
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Vite
|
|
114
|
+
|
|
115
|
+
The Vite setup uses both the Vite plugin (for JS/TS) and the PostCSS plugin (for CSS):
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
// vite.config.ts
|
|
119
|
+
import dsTokenFallbacks from '@wordpress/theme-build-tools/postcss-plugins/postcss-ds-token-fallbacks';
|
|
120
|
+
import dsTokenFallbacksJs from '@wordpress/theme-build-tools/vite-plugins/vite-ds-token-fallbacks';
|
|
121
|
+
|
|
122
|
+
export default defineConfig( {
|
|
123
|
+
plugins: [ dsTokenFallbacksJs() ],
|
|
124
|
+
css: {
|
|
125
|
+
postcss: {
|
|
126
|
+
plugins: [ dsTokenFallbacks ],
|
|
127
|
+
},
|
|
128
|
+
},
|
|
129
|
+
} );
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Contributing to this package
|
|
133
|
+
|
|
134
|
+
This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
|
|
135
|
+
|
|
136
|
+
To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
|
|
137
|
+
|
|
138
|
+
<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* esbuild plugin that injects design-system token fallbacks into JS/TS files.
|
|
3
|
+
*
|
|
4
|
+
* Replaces bare `var(--wpds-*)` references in string literals with
|
|
5
|
+
* `var(--wpds-*, <fallback>)` so components render correctly without
|
|
6
|
+
* a ThemeProvider. Does nothing when `@wordpress/theme` is not installed.
|
|
7
|
+
*
|
|
8
|
+
* @type {import('esbuild').Plugin}
|
|
9
|
+
*/
|
|
10
|
+
declare const plugin: import('esbuild').Plugin;
|
|
11
|
+
export default plugin;
|
|
12
|
+
//# sourceMappingURL=esbuild-ds-token-fallbacks.d.mts.map
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Inject fallbacks into JavaScript values without rewriting other source text.
|
|
3
|
+
* The caller is responsible for composing the returned source map.
|
|
4
|
+
*
|
|
5
|
+
* @param {string} source JavaScript or TypeScript source.
|
|
6
|
+
* @param {string} filename Source filename, without a query string.
|
|
7
|
+
* @return {{ code: string, map: import('magic-string').SourceMap, sourceMappingURL: string | undefined } | null} Transformation, or null when unchanged, unparseable, or `@wordpress/theme` is not installed.
|
|
8
|
+
*/
|
|
9
|
+
export declare function transformDsTokenFallbacks(source: string, filename: string): {
|
|
10
|
+
code: string;
|
|
11
|
+
map: import('magic-string').SourceMap;
|
|
12
|
+
sourceMappingURL: string | undefined;
|
|
13
|
+
} | null;
|
|
14
|
+
//# sourceMappingURL=transform-ds-token-fallbacks.d.mts.map
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Token data from the installed `@wordpress/theme`.
|
|
3
|
+
*
|
|
4
|
+
* The plugins do nothing when `@wordpress/theme` cannot be loaded.
|
|
5
|
+
*/
|
|
6
|
+
export type DesignTokensModule = {
|
|
7
|
+
/**
|
|
8
|
+
* Token metadata, keyed by CSS custom property name.
|
|
9
|
+
*/
|
|
10
|
+
tokens: Record<string, {
|
|
11
|
+
fallback: string;
|
|
12
|
+
}>;
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* Map of design token names to their generated fallback values, or
|
|
16
|
+
* `undefined` when `@wordpress/theme` is unavailable.
|
|
17
|
+
*
|
|
18
|
+
* @type {Record<string, string> | undefined}
|
|
19
|
+
*/
|
|
20
|
+
export declare const tokenFallbacks: Record<string, string> | undefined;
|
|
21
|
+
/**
|
|
22
|
+
* List of design token names, or `undefined` when `@wordpress/theme` is
|
|
23
|
+
* unavailable.
|
|
24
|
+
*
|
|
25
|
+
* @type {string[] | undefined}
|
|
26
|
+
*/
|
|
27
|
+
export declare const tokenList: string[] | undefined;
|
|
28
|
+
//# sourceMappingURL=theme-tokens.d.mts.map
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Lightning CSS visitor that injects design-system token fallbacks into CSS.
|
|
3
|
+
*
|
|
4
|
+
* Replaces bare `var(--wpds-*)` references with `var(--wpds-*, <fallback>)`.
|
|
5
|
+
*
|
|
6
|
+
* Existing fallbacks are left untouched. Unknown tokens throw. Does nothing
|
|
7
|
+
* when `@wordpress/theme` is not installed.
|
|
8
|
+
*
|
|
9
|
+
* @type {import('lightningcss').Visitor<never>}
|
|
10
|
+
*/
|
|
11
|
+
declare const plugin: import('lightningcss').Visitor<never>;
|
|
12
|
+
export default plugin;
|
|
13
|
+
//# sourceMappingURL=lightningcss-ds-token-fallbacks.d.mts.map
|
|
@@ -0,0 +1,46 @@
|
|
|
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 declare function addFallbackToVar(cssValue: string, tokenFallbacks: Record<string, string>, { escapeQuotes }?: {
|
|
24
|
+
escapeQuotes?: boolean;
|
|
25
|
+
}): string;
|
|
26
|
+
/**
|
|
27
|
+
* Replace bare `var(--wpds-*)` references in a parsed CSS value.
|
|
28
|
+
*
|
|
29
|
+
* @param {string} cssValue A CSS declaration value.
|
|
30
|
+
* @param {Record<string, string>} tokenFallbacks Map of CSS variable names to fallback expressions.
|
|
31
|
+
* @return {string} The value with fallbacks injected.
|
|
32
|
+
*/
|
|
33
|
+
export declare function addFallbackToVarInCSS(cssValue: string, tokenFallbacks: Record<string, string>): string;
|
|
34
|
+
/**
|
|
35
|
+
* Get the fallback for a design token.
|
|
36
|
+
*
|
|
37
|
+
* @param {string} tokenName CSS variable name.
|
|
38
|
+
* @param {Record<string, string>} tokenFallbacks Map of CSS variable names to fallback expressions.
|
|
39
|
+
* @param {Object} [options] Options.
|
|
40
|
+
* @param {boolean} [options.escapeQuotes] Whether to escape quotes in the fallback.
|
|
41
|
+
* @return {string} The token fallback.
|
|
42
|
+
*/
|
|
43
|
+
export declare function getTokenFallback(tokenName: string, tokenFallbacks: Record<string, string>, { escapeQuotes }?: {
|
|
44
|
+
escapeQuotes?: boolean;
|
|
45
|
+
}): string;
|
|
46
|
+
//# sourceMappingURL=add-fallback-to-var.d.mts.map
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Replace bare `var(--wpds-*)` references in a CSS value string with
|
|
3
|
+
* `var(--wpds-*, <fallback>)` using the package's generated token
|
|
4
|
+
* fallback map.
|
|
5
|
+
*
|
|
6
|
+
* Existing fallbacks (i.e. var() calls that already contain a comma) are
|
|
7
|
+
* left untouched, making the function safe to run multiple times.
|
|
8
|
+
*
|
|
9
|
+
* This is a thin wrapper around the generic `addFallbackToVar` helper in
|
|
10
|
+
* `./add-fallback-to-var.mjs`, prebound to the package's token fallback
|
|
11
|
+
* map. Update the regex/replacement logic in that file, not here.
|
|
12
|
+
*
|
|
13
|
+
* Returns the value unchanged when `@wordpress/theme` is not installed.
|
|
14
|
+
*
|
|
15
|
+
* @param {string} cssValue A CSS declaration value.
|
|
16
|
+
* @param {Object} [options] Options.
|
|
17
|
+
* @param {boolean} [options.escapeQuotes] When true, escape `"` and `'` in
|
|
18
|
+
* fallback values. Use this when the
|
|
19
|
+
* input is JS/TS source so that
|
|
20
|
+
* injected quotes don't break string
|
|
21
|
+
* literals. JS will unescape them at
|
|
22
|
+
* parse time, so the browser's CSS
|
|
23
|
+
* engine still sees the correct value.
|
|
24
|
+
* @return {string} The value with fallbacks injected.
|
|
25
|
+
*/
|
|
26
|
+
export declare function addFallbackToVar(cssValue: string, options?: {
|
|
27
|
+
escapeQuotes?: boolean;
|
|
28
|
+
}): string;
|
|
29
|
+
/**
|
|
30
|
+
* Whether design token fallbacks are available, i.e. whether
|
|
31
|
+
* `@wordpress/theme` is installed. The plugins do nothing without them.
|
|
32
|
+
*/
|
|
33
|
+
export declare const hasTokenFallbacks: boolean;
|
|
34
|
+
/**
|
|
35
|
+
* Replace bare design token references in a parsed CSS declaration value.
|
|
36
|
+
*
|
|
37
|
+
* @param {string} cssValue A CSS declaration value.
|
|
38
|
+
* @return {string} The value with fallbacks injected.
|
|
39
|
+
*/
|
|
40
|
+
export declare function addFallbackToVarInCSS(cssValue: string): string;
|
|
41
|
+
/**
|
|
42
|
+
* Get the generated fallback for a design token.
|
|
43
|
+
*
|
|
44
|
+
* @param {string} tokenName CSS variable name.
|
|
45
|
+
* @return {string} The token fallback.
|
|
46
|
+
*/
|
|
47
|
+
export declare function getTokenFallback(tokenName: string): string;
|
|
48
|
+
//# sourceMappingURL=ds-token-fallbacks.d.mts.map
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parse the custom property references in CSS `var()` functions.
|
|
3
|
+
*
|
|
4
|
+
* String, URL, and comment contents are not treated as CSS functions.
|
|
5
|
+
*
|
|
6
|
+
* @param {string} value A CSS declaration value.
|
|
7
|
+
* @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.
|
|
8
|
+
*/
|
|
9
|
+
export declare function parseCSSVariableReferences(value: string): {
|
|
10
|
+
parsed: import('postcss-value-parser').ParsedValue;
|
|
11
|
+
references: Array<{
|
|
12
|
+
name: string;
|
|
13
|
+
sourceIndex: number;
|
|
14
|
+
fallbackSeparator: import('postcss-value-parser').DivNode | undefined;
|
|
15
|
+
node: import('postcss-value-parser').FunctionNode;
|
|
16
|
+
}>;
|
|
17
|
+
};
|
|
18
|
+
//# sourceMappingURL=parse-css-variables.d.mts.map
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Vite plugin that injects design-system token fallbacks into JS/TS files.
|
|
3
|
+
*
|
|
4
|
+
* Replaces bare `var(--wpds-*)` references in string literals with
|
|
5
|
+
* `var(--wpds-*, <fallback>)` so components render correctly without
|
|
6
|
+
* a ThemeProvider. Does nothing when `@wordpress/theme` is not installed.
|
|
7
|
+
*
|
|
8
|
+
* @type {() => import('vite').Plugin}
|
|
9
|
+
*/
|
|
10
|
+
declare const plugin: () => import('vite').Plugin;
|
|
11
|
+
export default plugin;
|
|
12
|
+
//# sourceMappingURL=vite-ds-token-fallbacks.d.mts.map
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
import { readFile } from 'fs/promises';
|
|
2
|
+
import { fileURLToPath, pathToFileURL } from 'url';
|
|
3
|
+
import remapping from '@jridgewell/remapping';
|
|
4
|
+
import { AnyMap } from '@jridgewell/trace-mapping';
|
|
5
|
+
import { transformDsTokenFallbacks } from '../js-plugins/transform-ds-token-fallbacks.mjs';
|
|
6
|
+
import { hasTokenFallbacks } from '../postcss-plugins/ds-token-fallbacks.mjs';
|
|
7
|
+
|
|
8
|
+
/** @type {Record<string, import('esbuild').Loader>} */
|
|
9
|
+
const LOADER_MAP = {
|
|
10
|
+
'.js': 'jsx',
|
|
11
|
+
'.jsx': 'jsx',
|
|
12
|
+
'.ts': 'ts',
|
|
13
|
+
'.tsx': 'tsx',
|
|
14
|
+
'.mjs': 'jsx',
|
|
15
|
+
'.mts': 'ts',
|
|
16
|
+
'.cjs': 'jsx',
|
|
17
|
+
'.cts': 'ts',
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* esbuild plugin that injects design-system token fallbacks into JS/TS files.
|
|
22
|
+
*
|
|
23
|
+
* Replaces bare `var(--wpds-*)` references in string literals with
|
|
24
|
+
* `var(--wpds-*, <fallback>)` so components render correctly without
|
|
25
|
+
* a ThemeProvider. Does nothing when `@wordpress/theme` is not installed.
|
|
26
|
+
*
|
|
27
|
+
* @type {import('esbuild').Plugin}
|
|
28
|
+
*/
|
|
29
|
+
const plugin = {
|
|
30
|
+
name: 'ds-token-fallbacks-js',
|
|
31
|
+
setup( build ) {
|
|
32
|
+
if ( ! hasTokenFallbacks ) {
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
build.onLoad(
|
|
37
|
+
{ filter: /\.[mc]?[jt]sx?$/, namespace: 'file' },
|
|
38
|
+
async ( args ) => {
|
|
39
|
+
// Skip node_modules.
|
|
40
|
+
if ( args.path.includes( 'node_modules' ) ) {
|
|
41
|
+
return undefined;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
const source = await readFile( args.path, 'utf8' );
|
|
45
|
+
|
|
46
|
+
if ( ! source.includes( '--wpds-' ) ) {
|
|
47
|
+
return undefined;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const ext = args.path.match( /(\.[^.]+)$/ )?.[ 1 ] || '.js';
|
|
51
|
+
const result = transformDsTokenFallbacks( source, args.path );
|
|
52
|
+
if ( ! result ) {
|
|
53
|
+
return {
|
|
54
|
+
contents: source,
|
|
55
|
+
loader: LOADER_MAP[ ext ] || 'jsx',
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
let sourceMap = result.map.toUrl();
|
|
59
|
+
/** @type {string[]} */
|
|
60
|
+
const watchFiles = [];
|
|
61
|
+
/** @type {import('esbuild').PartialMessage[]} */
|
|
62
|
+
const warnings = [];
|
|
63
|
+
if ( result.sourceMappingURL ) {
|
|
64
|
+
try {
|
|
65
|
+
const url = new URL(
|
|
66
|
+
result.sourceMappingURL,
|
|
67
|
+
pathToFileURL( args.path )
|
|
68
|
+
);
|
|
69
|
+
/** @type {string | undefined} */
|
|
70
|
+
let inputMap;
|
|
71
|
+
let mapPath = args.path;
|
|
72
|
+
if ( url.protocol === 'data:' ) {
|
|
73
|
+
const comma = url.href.indexOf( ',' );
|
|
74
|
+
const data = decodeURIComponent(
|
|
75
|
+
url.href.slice( comma + 1 )
|
|
76
|
+
);
|
|
77
|
+
inputMap = url.href
|
|
78
|
+
.slice( 0, comma )
|
|
79
|
+
.endsWith( ';base64' )
|
|
80
|
+
? Buffer.from( data, 'base64' ).toString(
|
|
81
|
+
'utf8'
|
|
82
|
+
)
|
|
83
|
+
: data;
|
|
84
|
+
} else if ( url.protocol === 'file:' ) {
|
|
85
|
+
mapPath = fileURLToPath( url );
|
|
86
|
+
watchFiles.push( mapPath );
|
|
87
|
+
inputMap = await readFile( url, 'utf8' );
|
|
88
|
+
}
|
|
89
|
+
// Like esbuild, do not fetch remote source-map URLs.
|
|
90
|
+
if ( inputMap !== undefined ) {
|
|
91
|
+
const map = remapping(
|
|
92
|
+
[
|
|
93
|
+
result.map.toString(),
|
|
94
|
+
new AnyMap(
|
|
95
|
+
inputMap,
|
|
96
|
+
pathToFileURL( mapPath ).href
|
|
97
|
+
),
|
|
98
|
+
],
|
|
99
|
+
() => null
|
|
100
|
+
);
|
|
101
|
+
sourceMap = `data:application/json;base64,${ Buffer.from( map.toString() ).toString( 'base64' ) }`;
|
|
102
|
+
}
|
|
103
|
+
} catch ( error ) {
|
|
104
|
+
// esbuild ignores missing maps and warns for malformed maps.
|
|
105
|
+
if ( ! (
|
|
106
|
+
error &&
|
|
107
|
+
typeof error === 'object' &&
|
|
108
|
+
'code' in error &&
|
|
109
|
+
error.code === 'ENOENT'
|
|
110
|
+
) ) {
|
|
111
|
+
warnings.push( {
|
|
112
|
+
text: `Could not load the input source map: ${ error instanceof Error ? error.message : String( error ) }`,
|
|
113
|
+
detail: error,
|
|
114
|
+
} );
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
return {
|
|
120
|
+
contents: `${ result.code }\n//# sourceMappingURL=${ sourceMap }`,
|
|
121
|
+
loader: LOADER_MAP[ ext ] || 'jsx',
|
|
122
|
+
watchFiles,
|
|
123
|
+
warnings,
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
);
|
|
127
|
+
},
|
|
128
|
+
};
|
|
129
|
+
|
|
130
|
+
export default plugin;
|