Debian Codegraph @

vendor/ipl/web/src/Less/CssVarVisitor.php

raw
1 <?php
2
3 namespace ipl\Web\Less;
4
5 use Less_Functions;
6 use Less_Tree_Call;
7 use Less_Tree_Color;
8 use Less_Tree_Keyword;
9 use Less_Tree_Mixin_Call;
10 use Less_Tree_Mixin_Definition;
11 use Less_Tree_Variable;
12 use SplDoublyLinkedList;
13
14 /**
15 * Replace Less color variables with CSS `var()` function calls
16 *
17 * Every color variable reference (even nested aliases) is replaced with a `var(--name, fallback)` call.
18 * The visitor is scope-aware: it excludes mixin parameter names from replacement and disables replacement
19 * inside built-in Less functions that require resolved color values.
20 *
21 * See the following example Less and resolved CSS for a rough overview of the visitor features.
22 * Note that at-signs used for Less variables are omitted because PHPStorm interprets them as annotations.
23 *
24 * Less:
25 * ```
26 * bg-color: black;
27 * text-color: white;
28 *
29 * body {
30 * background-color: bg-color;
31 * color: text-color;
32 * }
33 * ```
34 *
35 * CSS:
36 * ```
37 * body {
38 * background-color: var(--bg-color, black);
39 * color: var(--text-color, white);
40 * }
41 * ```
42 */
43 class CssVarVisitor extends PreEvalVisitor
44 {
45 /**
46 * Boolean stack that gates CSS `var()` replacement during compilation
47 *
48 * Push `false` when you compile a context that must see resolved Less values (e.g., built-in Less functions),
49 * and pop it when you leave that context. Keep at least one frame on the stack at all times.
50 *
51 * @var SplDoublyLinkedList<bool>
52 */
53 protected SplDoublyLinkedList $replaceCssVars;
54
55 /**
56 * Stack of mixin parameter names to exclude from CSS `var()` replacement
57 *
58 * Each frame represents one mixin definition currently being visited and contains its parameter names.
59 * Frames are kept in innermost-first order: {@see visitMixinDefinition()} prepends each new frame,
60 * so index 0 always holds the currently active scope. This lets {@see visitVariable()} iterate
61 * forward without reversing to check the nearest enclosing scope first.
62 *
63 * @var list<list<string>>
64 */
65 protected array $mixinParams = [];
66
67 /**
68 * Handle a {@see Less_Tree_Call} node during AST traversal
69 *
70 * Call nodes represent both built-in Less functions (e.g., `fade()`) and CSS functions (e.g., `calc()`).
71 * Less.php calls our {@see visitVariable()} for function call arguments,
72 * potentially replacing them with CSS `var()` calls.
73 * That behavior is desired for CSS functions such as `calc()`, but it breaks built-in Less functions
74 * such as `fade()`, because they require resolved values. To preserve Less semantics,
75 * this method replaces the call node that compiles twice if applicable:
76 *
77 * - First pass: disable CSS `var()` replacement while compiling the call (so built-in Less functions see
78 * resolved values).
79 *
80 * - Second pass: if compilation still returns a call node, treat it as a CSS function and recompile with
81 * CSS `var()` replacement enabled again.
82 *
83 * Given the context `icinga-red: red`, this ensures that:
84 *
85 * - `fade(icinga-red)` compiles to `fade(red)`.
86 * - `calc(icinga-red)` compiles to `calc(var(--icinga-red, red))`.
87 *
88 * @param Less_Tree_Call $c The function call node being visited
89 *
90 * @return Less_Tree_Call A new call node replacing the original with adjusted `compile()` logic
91 *
92 * @see visitVariable() For variable replacement logic
93 * @see Less_Functions For built-in Less functions
94 */
95 public function visitCall(Less_Tree_Call $c): Less_Tree_Call
96 {
97 $call = new class ($c->name, $c->args, $c->index, $c->currentFileInfo) extends Less_Tree_Call {
98 /** @var SplDoublyLinkedList<bool> */
99 public SplDoublyLinkedList $replaceCssVars;
100
101 public function compile($env)
102 {
103 // Temporarily disable CSS `var()` replacement for current call node arguments.
104 $this->replaceCssVars->push(false);
105 $compiled = parent::compile($env);
106 $this->replaceCssVars->pop();
107
108 if ($compiled instanceof Less_Tree_Call) {
109 // Built-in Less functions (e.g. `fade()`) compile to a specific value (e.g. Color),
110 // whereas CSS functions (e.g. `calc()`) remain a call node after compilation.
111 // Recompile such call nodes with CSS `var()` replacement enabled for arguments.
112 // (Note: Replacement might still be disabled due to nested function calls.)
113 $compiled = parent::compile($env);
114 }
115
116 return $compiled;
117 }
118 };
119 $call->replaceCssVars = $this->replaceCssVars;
120
121 return $call;
122 }
123
124 /**
125 * Handle a {@see Less_Tree_Variable} node during AST traversal
126 *
127 * Less variable nodes represent unresolved references that Less.php resolves during compilation.
128 * This visitor replaces variable nodes that compile to a CSS `var()` call, unless:
129 *
130 * 1. The variable is a mixin parameter name.
131 * 2. It is an argument to a built-in Less function.
132 * 3. The resolved value is not a color or not already a CSS `var()` call.
133 *
134 * Mixin parameters are special: they behave like variables, but must not be replaced with CSS `var()` calls.
135 * The parameter stack maintained by {@see visitMixinDefinition()} and {@see visitMixinDefinitionOut()}
136 * provides context to ignore them.
137 *
138 * @param Less_Tree_Variable $v The variable node being visited
139 *
140 * @return Less_Tree_Variable The original variable if it is a mixin parameter; otherwise a
141 * replacement variable node that compiles to a CSS `var()` call if applicable
142 *
143 * @see visitCall() For disabling replacement in built-in Less functions
144 * @see visitMixinDefinition() For mixin parameter stack setup
145 * @see visitMixinDefinitionOut() For mixin parameter stack teardown
146 */
147 public function visitVariable(Less_Tree_Variable $v): Less_Tree_Variable
148 {
149 foreach ($this->mixinParams as $ignoreVars) {
150 if (in_array($v->name, $ignoreVars, true)) {
151 return $v;
152 }
153 }
154
155 $variable = new class ($v->name, $v->index, $v->currentFileInfo) extends Less_Tree_Variable {
156 /** @var SplDoublyLinkedList<bool> */
157 public SplDoublyLinkedList $replaceCssVars;
158
159 public function compile($env)
160 {
161 $compiled = parent::compile($env);
162
163 // Do not replace variable with CSS `var()` function call if...
164 if (
165 // ... replacing CSS vars is disabled because a function call is compiled,
166 ! $this->replaceCssVars->top()
167 // ... or the compiled variable is neither a color nor a CSS `var()` call.
168 || (
169 ! $compiled instanceof Less_Tree_Color
170 && (! $compiled instanceof Less_Tree_Call || $compiled->name !== 'var')
171 )
172 ) {
173 return $compiled;
174 }
175
176 // Remove '@' from name.
177 $name = substr($this->name, 1);
178
179 if ($name[0] === '@') {
180 // Evaluate variable variable as in Less_Tree_Variable.
181 $name = (new Less_Tree_Variable($name, $this->index + 1, $this->currentFileInfo))
182 ->compile($env)
183 ->value;
184 }
185
186 $args = [
187 'var',
188 [
189 new Less_Tree_Keyword("--{$name}"),
190 $compiled,
191 ],
192 $this->index,
193 ];
194
195 // No need to call `compile()` on the new call node (replacing the variable node),
196 // as it's not a built-in Less function, `Less_Tree_Keyword::compile()` is a no-op,
197 // and it wraps the already compiled variable node.
198 return new Less_Tree_Call(...$args);
199 }
200 };
201 $variable->replaceCssVars = $this->replaceCssVars;
202
203 return $variable;
204 }
205
206 /**
207 * Handle a {@see Less_Tree_Mixin_Definition} node during AST traversal
208 *
209 * Less.php does not visit default parameter values, which would leave
210 * `.mixin(@color: @icinga-red)` producing `var(--color, …)` instead of `var(--icinga-red, …)`.
211 *
212 * This method works around the traversal gap by pushing the mixin's parameter names onto a stack and
213 * manually visiting each parameter value. For all frames in the stack, {@see visitVariable()}
214 * returns parameter names unchanged and only rewrites parameter values.
215 *
216 * Simplified AST traversal context:
217 * ```
218 * MixinDefinition(.mixin) ← visitMixinDefinition()
219 * └─ Parameters
220 * ├─ Variable (name: color) ← instrument visitVariable() call to ignore this variable
221 * └─ Variable (value: icinga-red) ← force visitVariable() call
222 * visitMixinDefinitionOut() revert instrumentation
223 * ```
224 *
225 * @param Less_Tree_Mixin_Definition $d The mixin definition node being visited
226 *
227 * @return Less_Tree_Mixin_Definition The original mixin definition node (modified in-place)
228 *
229 * @see visitMixinDefinitionOut() For cleanup after traversal
230 * @see visitVariable() For replacement logic that checks exclusion stack
231 */
232 public function visitMixinDefinition(Less_Tree_Mixin_Definition $d): Less_Tree_Mixin_Definition
233 {
234 // Less_Tree_Mixin_Definition::accept() does not visit parameters, but we have to replace them if necessary.
235 foreach ($d->params as &$p) {
236 if (isset($p['value'])) {
237 $p['value'] = $this->visitObj($p['value']);
238 }
239 }
240 unset($p);
241
242 array_unshift($this->mixinParams, array_column($d->params, 'name'));
243
244 return $d;
245 }
246
247 /**
248 * Leave a {@see Less_Tree_Mixin_Definition} node
249 *
250 * Removes the current mixin's parameter names from {@see $mixinParams},
251 * restoring the parent scope.
252 *
253 * @return void
254 */
255 public function visitMixinDefinitionOut(): void
256 {
257 array_shift($this->mixinParams);
258 }
259
260 /**
261 * Handle a {@see Less_Tree_Mixin_Call} node during AST traversal
262 *
263 * Since Less.php does not visit arguments of mixin calls, this visitor forces each argument to be visited
264 * to trigger our {@see visitVariable()} so that arguments are replaced by CSS `var()` calls if applicable,
265 * e.g., `.mixin(icinga-red)` → `.mixin(var(--icinga-red, ...))`.
266 *
267 * Simplified AST traversal context:
268 * ```
269 * MixinCall (.mixin) ← visitMixinCall()
270 * └─ Arguments
271 * └─ Variable (icinga-red) ← force visitVariable() call
272 * ```
273 *
274 * @param Less_Tree_Mixin_Call $c The mixin call node being visited
275 *
276 * @return Less_Tree_Mixin_Call The original mixin call node (modified in-place)
277 */
278 public function visitMixinCall(Less_Tree_Mixin_Call $c): Less_Tree_Mixin_Call
279 {
280 // Less_Tree_Mixin_Call::accept() does not visit arguments, but we have to replace them if necessary.
281 foreach ($c->arguments as &$a) {
282 $a['value'] = $this->visitObj($a['value']);
283 }
284 unset($a);
285
286 return $c;
287 }
288
289 /**
290 * Set up the CSS `var()` replacement state stack
291 *
292 * Creates {@see $replaceCssVars} with an initial `true` frame so that replacement
293 * is enabled at the start of each traversal.
294 *
295 * @return void
296 *
297 * @see visitCall() Which pushes/pops frames to disable replacement inside built-in Less functions
298 */
299 protected function init(): void
300 {
301 $this->replaceCssVars = new SplDoublyLinkedList();
302 // Enable CSS `var()` replacement.
303 $this->replaceCssVars->push(true);
304 }
305
306 /**
307 * Deep-copy object-type state when this visitor is cloned by {@see PreEvalVisitor::run()}
308 *
309 * {@see $replaceCssVars} is a {@see SplDoublyLinkedList} and would otherwise be shared
310 * between the prototype and the clone. Cloning it ensures each traversal starts with
311 * its own independent stack.
312 *
313 * @return void
314 */
315 public function __clone(): void
316 {
317 $this->replaceCssVars = clone $this->replaceCssVars;
318 }
319 }