[css-functions-mixins] spreading comma separated var values into multiple arguments by default when calling a custom function

[JaneOri]

Creating this issue as requested on mastodon.

Calling a custom function is only place in CSS where the expected/established DX of vars effectively spreading in-place doesn't happen.

--rgb: 255, 0, 0;
color: rgb(var(--rgb));

As a CSS author, this anti-spreading behavior feels broken/unexpected.
(and is incredibly disappointing to not have access to the enormous potential of argument spreading)

It was originally planned and assumed as the rational expectation:
#11190 (comment)

It appears that it was implemented:
https://issues.chromium.org/issues/390205875#comment3

and then cancelled shortly after (afaik, without public discussion):
https://issues.chromium.org/issues/390205875#comment5

The {var(--csv)} syntax to prevent spreading makes sense from the perspective of a CSS author and is implemented / shipped.

---

The primary counter argument caters to non-CSS developers, stating that other languages don't auto spread arguments so CSS custom functions shouldn't either.

I whole heartedly disagree with the conclusion of this counter argument but so far I have stood alone in intention to question it.

Other counter arguments I've seen are situational and don't uniformly apply (like when arguments are typed, the evaluation happens anyway, etc).

---

For context, I have written dozens of complex custom functions, including working, trivial DX, --repeat() and --loop() functions, an entire bitwise suite, and am actively writing many more.

I know questioning decisions already made is not a pleasant thing to do so I apologize for that while still being incredibly hopeful that the expectation will be restored.

---

It also seems like it would be difficult to maintain erroring when too many arguments are used in the call... though I also want to say that it is confusing DX to try debugging why a function isn't working at all. (Is something cyclic? A semicolon missing? Comma missing? Something else?) Without a CSS error console, it is much much easier to debug an incorrect argument causing weird behavior than to experience when a function isn't returning anything at all.

[mirisuzanne]

While I think the no-spread-by-default behavior would be more accurate to author expectations and use generally, I agree that it's weird to make this change in one place only – when we're compat-constrained in every other context.

In terms of syntax, this feels like an avoidable bonus footgun on top of the existing footgun – where authors now need to learn two different solutions for managing spread in different contexts (that are otherwise designed to feel similar). One syntax is needed to stop spread from happening in provided functions, and another (new) syntax is needed to request spread in custom functions.

I know there are also parsing advantages to the no-spread option, and I'm open to the group deciding the advantages outweigh the issues here – but I do think this is a pretty surprising lack of consistency between CSS functions and… CSS functions.

[JaneOri]

This behavior I filed as a bug might be a side-effect of not evaluating the arguments before calling the function, potentially making it directly relevant to this argument spreading issue:
https://issues.chromium.org/issues/514021797

(functions - especially math heavy functions - that resolve and set a property, followed by a separate property receiving that result as an argument passed into the same function, dies as if it were cyclic when it's clearly not because the first one is fully resolved -- which is crippling for function reuse and mathematical functions)

[tabatkins]

(Jane and I have discussed this on Mastodon previously.)

The primary counter argument caters to non-CSS developers, stating that other languages don't auto spread arguments so CSS custom functions shouldn't either.

This is one argument. It's not the primary one, and I don't think I ever characterized it as such. I do think it's a big one, though!

To elaborate, in normal CSS properties you can drop a var() in anywhere and it'll just spam out whatever it holds, even if that crosses what we would normally consider a "semantic boundary", then CSS parses the whole thing as a unit, with no consideration for where the var()s had appeared. For example:

--foo: center, 20%;
background-position: center var(--foo) 80%;
/* expands to:
  background-position: center center, 20% 80%;
*/

This sort of behavior is extremely confusing. The custom property suggests that it's a comma-separated list of two meaningful values, when it's not - it's two halves of two <position>s. The var() suggests that it's dropping a value into a single background layer, and the surrounding values (center and 80%) are doing their own thing on that layer, but it's not - it's defining two layers, giving the final bit of one layer, and the starting bit of a second layer.

This sort of confusing usage is unavoidable, however, because CSS grammars aren't structured enough to make "semantic units" meaningfully defineable. To allow for a lot of reasonable usages, we had to allow these unreasonable ones. (And this applies to CSS functions in general; while we mimic other language's use of comma-separated arguments, that's just a convention enforced by the function's grammar. We avoid commas in many cases, and in general have access to the full flexibility of CSS property values inside of functions.)

As another example where vars often do contain commas, take gradients. linear-gradient(to top, var(--foo)) makes intuitive sense to us with the var() supplying the stops, as does linear-gradient(var(--foo), red, blue) with the var() supplying the direction/etc. But if you had --foo: to left, white 20%; background: linear-gradient(var(--foo), red, blue);, that could be surprising/confusing to someone else, because the var() is crossing the implicit semantic boundary separating the first argument from the rest. If we had a consistent story for this across CSS, it would be better to disallow that usage by default, and require linear-gradient(...var(--foo), red, blue) to make it clear you're doing something more unusual.

(But this isn't absolute! We do track ()[]{} pairings, and var() can't violate that. You can't, for example, do background-image: url(var(--foo)); --foo: "img1"), url("img2"; and suddenly get two images. So, to the extent that semantic boundaries are easily and unambiguously detectable, we honor them.)

In custom functions, we can't apply arbitrarily-complex grammars inside the (), because we can't parse them unambiguously. The grammars authors can use for their arguments don't include commas, so commas do become an unambiguous semantic-unit separator.

The only arguments that can take commas in their value, then, are those that are left entirely un-syntax'd, almost certainly because they're meant to take a chunk of another property that they'll be subbed into. If you fill in one of these arguments manually, it's much more obvious that you're doing something wrong and might need to reach for {} to wrap the argument, but when you pass it via a var() or similar, that's no longer obvious.

---

Now that was a lot of words for something I said wasn't even the primary motivator. The other big one is consistency, as Miriam alludes to (tho from the other side, lol). Most of the other arbitrary-substitution functions (arbsubs) need to be able to tell their arguments apart immediately, to allow for useful functionality:

• var(), inherit(), and attr() have fallback arguments we want to leave unresolved unless needed.
• first-valid() is all fallback arguments, so the same applies.
• if() wants to have the standard short-circuity behavior that if/else constructs have in almost every language, where the body of a failed test isn't resolved, and early true test will leave the later tests unresolved too.

For all of these, in order to achieve these abilities, we have to see the argument separators before variable substitution, so we can treat each chunk differently. If you need a var() to supply multiple of the arguments, that's what the ...var() spread syntax is for. It signals you're doing something unusual, but you do lose something from it - the contents are entirely evaluated, even if they're part of fallback or unused branches.

Custom functions are also arbsubs, and it's nice to give them the same resolution behavior so there's an easier to understand rule. We shouldn't rule out, too, the possibility that we let custom functions declare some arguments to stay unresolved, so they have access to the same fallback behavior other arbsubs have. Keeping that open as a possibility requires us to have the same arg-splitting behavior from the start.

---

@mirisuzanne

authors now need to learn two different solutions for managing spread in different contexts (that are otherwise designed to feel similar). One syntax is needed to stop spread from happening in provided functions, and another (new) syntax is needed to request spread in custom functions.

I don't see why you seem to be implying these are confusingly opposed. They're a necessary pair; you can't have one without the other (without having a really bizarre functionality hole). It's exactly identical to JS having both [] syntax for arrays holding comma-separated values, and spread syntax supplying multiple comma-separated args with a single variable.

Neither foo(1, [2, 3, 4], 5) (passing three args) nor foo(1, ...args, 3) (passing two or more args) are particularly confusing in JS, and the simple case of foo(1, args, 3) (passing three args regardless of what args is) is also straightforward. In CSS these two are just spelled --foo(1, {2, 3, 4}, 5) and --foo(1, ...var(--args), 3), and the simple case of --foo(1, var(--args), 3) passing exactly three args similarly straightforward.

[tabatkins]

This behavior I filed as a bug might be a side-effect of not evaluating the arguments before calling the function, potentially making it directly relevant to this argument spreading issue:
issues.chromium.org/issues/514021797

No, this is something else. We want to avoid recursion, but the evaluation rules end up ruling out explicitly calling the function in a stack. That's a spec bug, then. (So your Chrome bug is, currently, invalid - the behavior you're seeing is per-spec.) I'll open an issue for it.

[tabatkins]

#13943 for the --foo(--foo(0)) issue

[JaneOri]

In CSS when I see
--foo(1, var(), 5)
I automatically read it as "3 or more parameters" because it's extremely useful (and common) to include commas in var values. Constantly, including the background example you listed as confusing, I appreciate the ability to use arbitrary comma injection into lists.

I read
--foo(1, {var()}, x)
as exactly 3. This syntax was a great idea.

[Spread] signals you're doing something unusual, but you do lose something from it - the contents are entirely evaluated, even if they're part of fallback or unused branches.

Now THAT is confusing. Arguments to a function should be evaluated before the function is called, even if their inclusion in the final evaluation tree is ultimately not used... (It shouldn't matter if it's independently evaluated, only matters if it's used.) If you wanted to introduce a syntax to deliberately avoid evaluation of a parameter ahead of time, that would be awesome imo. Maybe {{unevaluated}}
Not evaluating arguments ahead of calling a function is bizarre even in CSS since var() effectively expands in place everywhere else.

Spreading deliberately wouldn't need to include unused branches of nested if() conditions once the arguments are resolved,, prior to calling the fn, so I'm not sure if you meant to imply that it does

[mirisuzanne]

They're a necessary pair;

That's fair. But my point is less about having both options, and more about the fact that I have to reach for one in round() and the other in --negative() – because those two functions (otherwise designed to use the same syntax) handle this one confusing situation differently.

I agree with you that spread-by-default is not great. I think this is also not great. I don't come down strongly on which is the better outcome – I don't love our options here – but I do think it warrants weigh-in more broadly.

[JaneOri]

If anyone places commas in a var and uses it to call a custom function, they are doing it intentionally.

The situation where comma spreading is confusing implies the author had populated a var for an argument with a comma separated value and expected the custom function to treat it as a single parameter value.

I don't think that is a situation that exists.

Since current implementations of CSS can only modify parameters to a function if they AREN'T multiplied values, the situation where a custom function uses a parameter that can be either multiplied OR singular is one where the custom function isn't doing anything other than spitting out 1:1 what was passed in. Which makes it pointless to use a custom function instead of a var().

In other words, there is no scenario where the expectation is for it to remain as a single argument, but instead only scenarios where the expectation would be that it spreads to multiple arguments.

The only exception is repeating/looping the same argument - which could be a list - X times along with intentionally joining the output with commas, and I'm the only one who has figured out how to do that given current limitations, so I'm likely the only one who has written a custom function that might accept lists as a single argument among other arguments.

I've documented those functions with anti-spread syntax because you must use those curly braces if the argument isn't a var. And it's further confusing caveats that you don't need them when it's a var. Fortunately the curly braces CAN be used with a {var()} so I don't have to document that sometimes-optional confusion and instead can potentially make sure they just always use the braces for that argument when calling my fn. (Which has the added benefit of being compatible with the swap back to what you and I both initially expected, which is that it would spread)

[tabatkins]

In other words, there is no scenario where the expectation is for it to remain as a single argument, but instead only scenarios where the expectation would be that it spreads to multiple arguments.

Not true. I mentioned the exact scenario I'm afraid of - a custom function taking a property value as an argument, where that property can be a comma-separated list, but doesn't have to be. It's easy to author the function with the assumption of a single, simple non-comma value, and then be passed a comma'd value anyway.

Note, importantly, that this isn't a problem that the function author can deal with. If one of their function args can be a comma-separated list, there's nothing they can declare in the definition making that "just work" - instead, every callsite that passes a comma'd value needs to remember that it needs a {} wrapper. That's fairly easy to remember when you're writing the comma manually (it feels like a different kind of comma from the ones separating this arg from the others), but it's much less obvious that you need to do this when the argument is being provided by a var() or similar function.

I understand that your use-cases tend more towards relatively simple arguments, and var()s that can provide multiple of these arguments at once, but I'm trying to consider the full spread of cases I expect to see in the wild. I'm also trying to bias my design towards working "correctly by default" for less-advanced authors; you are emphatically not that. (I never want to shut off the ability for advanced authors to do cool stuff, but if they need to take an extra step to do something "unusual", that's more palatable.)

Which makes it pointless to use a custom function instead of a var().

As I outlined above, this isn't the case. You can output an arg relatively unchanged, but still do so based on non-trivial logic with the other arguments or the surrounding context, like CQs or MQs.

@mirisuzanne

That's fair. But my point is less about having both options, and more about the fact that I have to reach for one in round() and the other in --negative() – because those two functions (otherwise designed to use the same syntax) handle this one confusing situation differently.

Yeah, I consider this a legacy mistake. I do wish we'd had enough foresight to introduce a "no top-level commas in a substitution" rule (at least, when subbing into a function's args, which we can detect at substitution time), with spread syntax bypassing that. There are a pretty limited number of places where you commonly want to sub in a comma'd value, so it wouldn't really hurt to need to ... those, and all the rare cases where you're doing so actually benefit from the ... indicating you're doing something unusual, same as seeing foo(...bar) does in JS.

[JaneOri]

I'd like to better understand what you mean here because I'm having trouble coming up with what you might be imagining:

Not true. I mentioned the exact scenario I'm afraid of - a custom function taking a property value as an argument, where that property can be a comma-separated list, but doesn't have to be. It's easy to author the function with the assumption of a single, simple non-comma value, and then be passed a comma'd value anyway.

If I author a function for a listable property, let's say background, and define a non-multiplied argument for my function, and my user passes a comma separated array as the argument, there is no scenario where that should work or be expected to work.... Why would a dev ever assume they could pass an array to an argument that doesn't document that it accepts one or is specifically typed not to?

Conversely, it will be extremely common that they create a csv var value to "apply()" multiple arguments intentionally in countless scenarios.

The default as it is now is assuming something that doesn't (to me (yet)) make sense for a dev user to even try doing (passing an array to a singular argument) and at the same time the default is blocking the extremely useful and by far most likely use case - reusing multiple arguments (all or a subset) from a single var to the same library function in multiple different places. --rgb

Spread syntax is great to enable that but imo the default should be the most reasonable and useful use case which is reusing multiple arguments/auto-spread (like "apply()")

As soon as I understand what you are imagining, I could flip in an instant but so far I don't know what the concern is

---

importantly, that this isn't a problem that the function author can deal with. If one of their function args can be a comma-separated list, there's nothing they can declare in the definition making that "just work" - instead, every callsite that passes a comma'd value needs to remember that it needs a {} wrapper.

Right, exactly. Just like in js where you wrap it in [] if the argument is an array. Since it works perfectly already and minimizes detailing caveats, custom function authors documenting "{this is how you call it even when it's a one item list}" would be a useful thing to do.

For processing, nth-item(0) (custom and standard) would necessarily return the whole value when there are no top level commas.

That's fairly easy to remember when you're writing the comma manually (it feels like a different kind of comma from the ones separating this arg from the others), but it's much less obvious that you need to do this when the argument is being provided by a var() or similar function

It's more about the custom function's argument than the value of the variable - since all of CSS lists (comma, space, and | separated) are top-level, your {} syntax is the only signal that the parameter itself accepts a list if it's not typed with multiplied syntax. It's not a burden to dev users though because in all other languages, passing arrays as a single argument requires [] somewhere - in CSS it's directly in the call syntax and somewhat amazingly not needed anywhere else

---

Yeah, I consider this a legacy mistake. I do wish we'd had enough foresight to introduce a "no top-level commas in a substitution" rule (at least, when subbing into a function's args, which we can detect at substitution time), with spread syntax bypassing that.

I wholeheartedly agree. But it's confusing to try changing the expectation in one single scenario. (Specifically calling a custom function, specifically be careful when the argument takes a list, specifically when the multiple arguments you provide is a var() list, then you need to use the new spread syntax that isn't implemented yet in order to do what all other scenarios do by default 😬)

[sorvell]

@JaneOri

(and is incredibly disappointing to not have access to the enormous potential of argument spreading)

Is it fair to say that it essentially lets css authors define their own shorthands? If so, that seems obviously incredibly valuable.

@tabatkins

Might we be able to add value spreading explicitly (maybe only for an untyped custom property?):

from(var(--comma-sep), --a: a, --b: b) or
--a: split(var(--comma-sep), 1)

It does seem like if is at least somewhat helpful here:
(note: there are also space separated values but I don't think that's relevant here)

@function --rgb(--config-or-r, --g: , --b: ) {
  result: if(
    style(--g: ): rgb(var(--config-or-r));
    else: rgb(var(--config-or-r), var(--g), var(--b));
  );
}

.foo {
  color: --rgb(0, 100, 0);
   --values: 100, 5, 150;
  background: --rgb(var(--values));
}