[css-mixins] Custom functions should have some access to custom properties on the calling element. How much?

[mirisuzanne]

And how explicit should that access be?

• The initial proposal suggested explicitly passing in any variables needed, as part of the parameter list
• The more recent proposal involves a using (<vars>) syntax in the at-rule prelude (the same impact, but a bit more concise)
• Others have argued that all external variables should be (somehow) implicitly available.

Much of the previous discussion is in the initial proposal: #9350. There's also a related question about distinguishing between 'arguments' and 'variables' - which may belong as part of this issue, or may also deserve it's own thread?

[tabatkins]

My fairly strongly-held position is that all arguments visible to the function body should be lexically scoped - that is, explicitly declared in the function declaration. So, for example:

@function --foo(--arg1, --arg2) using (--var1, --var2) {
  /* In here, you *only* have access to the two passed arguments,
     from `--foo(1, 2)`,
     and the --var1 and --var2 custom properties from the calling context.
  */
}

I have a few reasons for holding this opinion strongly.

(1) In the future we'll likely want to be able to use JS to define the behavior of custom function, aka a CSS.registerFunction("--foo", ...) API. We probably don't want to pass in the entire set of custom properties to the callback; it's better if it knows exactly what custom props it'll need to look up for passing in.

(2) Lexical scoping makes it very obvious when shadowing is occurring. For example:

@function --outer(--foo) {
  /* declares a --foo argument */
  result: calc(var(--foo) + --inner());
}
@function --inner() {
  /* implicitly grabs the --foo custom property from ~somewhere~ */
  result: calc(var(--foo) / 2);
}
.foo {
  --foo: 1;
  width: calc(--outer(10) * 1px);
}

What's the width? Does --outer()'s argument shadow the custom property that --inner() references, resulting in 15px (10 + 10/2)? Or does --inner() get to "escape" up to the element context and grab that custom property, resulting in 10.5px (10 + 1/2)?

If the answer is 15px, it's not particularly clear that the shadowing is intended. Every function needs to know precisely what variables are referenced by every function it calls (and every function they call, etc), or risk accidentally screwing up the behavior of a function they're not even aware is being called.

If the answer is 10.5px, then it's impossible to override that behavior. It means only the top-level context can pass all the "arguments" to a function; when functions call other functions, they only have access to pass some of the "arguments". It also means that if you just take a chunk of style that currently works, and abstract it into a function, it might break, because it was setting some custom props for a function it was using, and now those are no longer visible. This just sucks.

Having to explicitly list every variable you want to reference does kinda suck as well, I acknowledge. But it means you have all the power you need, refactoring stuff into a function works, and you don't have to worry about accidentally shadowing variables you don't even know about.

[kbabbitt]

Another advantage of lexical scoping is that it becomes simpler for implementations to offload evaluation from the main thread to a worker. Perhaps CSS functions typically end up being small enough that it's not worth doing so, but I think it would be good to have the potential for it.

[Crissov]

If, in Tab’s example, --foo should not be visible inside --inner(), then why would --inner() be accessible inside --outer()?

If the answer is: ”duh, because it’s declared with the @function at-rule and not like a custom property within a ruleset“, we effectively are introducing global constants (with awkward parentheses to distinguish them from custom properties):

@function --phi() {
  result: calc(0.5 + sqrt(1.25));
}
.foo {
--phi: 1.618; /* unused */
  aspect-ratio: var(--phi, 1.6); /* legacy */
  aspect-ratio: --phi();
}

I’m not saying this was bad or unexpected, but I think I vaguely remember some arguments being raised against this when variables had been proposed – using an at-rule – and hence ended up as custom properties.

Nobody wants to define the function body within a property value, I guess:

:root {
--parameter: 1; /* initial */
--function(): calc(1em * arg(1, 1) * pow(2, var(--parameter, 0) / 2));
}
.foo {
--parameter: 2;
  font-size: func(--function, 3); /* = 1em * 3 * pow(2, 2 / 2) */
}

(It’s non-obvious whether the second argument to func() would be passed to the custom function or if it was the fallback value as in var().)

---

I agree that global functions would be hardly manageable if local ”variables“ would intrude their scope. That is one reason why I suggested that, inside functions, named variables needed to be declared explicitly in the usual way as custom properties and would need arg() to use the value of parameters passed to the function.

Although I’m not sure it’s a good idea, you could then still allow external variables to bleed in, but it would be obvious that the closest definition wins. Basically, the function at-rule would behave as if it inherited the custom properties from the ruleset it is used within, and could also overwrite them.

@function --outer() {
--foo: arg(1);
  result: calc(var(--foo) + --inner());
}
@function --inner() {
  result: calc(var(--foo) / 2);
}
.foo {
--foo: 1;
  width: calc(--outer(10) * 1px); /* = 15px */
  height: calc(--inner(10) * 1px); /* = 0.5px */
}

Arguments could also be pre-named, but would live in a different namespace as custom properties and therefore could not be used directly in var():

@function --outer(--foo) {
--foo: arg(--foo); /* for --inner() */
  result: calc(arg(--foo) + --inner());
}

[sorvell]

My fairly strongly-held position is that all arguments visible to the function body should be lexically scoped

What about currentcolor? It seems like this is similar enough to css custom properties that they should behave the same way.

The new thing here seems to be a local variable and if they should have different behavior, would it help if they just used a different syntax so they couldn't easily be confused?

[LeaVerou]

I think this needs to be discussed separately for mixins vs functions, since their use cases are different. While it could be argued both ways for both, I think the need for dynamic scope is higher with mixins.

Also, I do think there is a fundamental difference between incidental variables that happen to be defined somewhere in a subtree, and a website’s design system (typically defined in the :root): fonts, colors, spacings etc. I really hope mixins can have access to those without every mixin having to explicitly define dozens or even hundreds of properties in a using clause, which would render them practically unusable.

We might want to consider a syntax that allows access to many properties en masse, that might make using more palatable, e.g. --color-* for all variables prefixed --color-, --icon-*, --font-* etc.,. And if we allow --* too, authors could opt-in to all custom variables on a case by case basis, rendering these debates moot. 🙂

[kizu]

would it help if they just used a different syntax so they couldn't easily be confused?

I really liked the idea to recall the arguments via arg(--foo) — this way they won't conflict with the variables. Also: what if by separating them and making sure arguments resolve before variables, we could allow doing things like var(arg(--foo))? Was dreaming about something like this for a while.

Kinda related to this,

We might want to consider a syntax that allows access to many properties en masse, that might make using more palatable, e.g. --color-* for all variables prefixed --color-, --icon-, --font- etc.,. And if we allow --* too, authors could opt-in to all custom variables on a case by case basis, rendering these debates moot. 🙂

Other than conditions, a thing to really consider when talking about mixins and functions is an ability to retrieve values from lists and maps. If there was an ability to define all the tokens as a single (or several) map or record, the downsides for the using could be much smaller, as you could just put the whole map there (even though I still not sure if there is any use for it).

---

Update from 2024-02-24: Lea did just open a proposal for CSS Variable Groups which is what I was partially talking about in this point: #9992

[LeaVerou]

would it help if they just used a different syntax so they couldn't easily be confused?

I really liked the idea to recall the arguments via arg(--foo) — this way they won't conflict with the variables. Also: what if by separating them and making sure arguments resolve before variables, we could allow doing things like var(arg(--foo))? Was dreaming about something like this for a while.

I think a common workflow for mixins is to start developing CSS normally, then copy certain code into a mixin. Using a separate syntax makes this higher friction.

Other than conditions, a thing to really consider when talking about mixins and functions is an ability to retrieve values from lists and maps. If there was an ability to define all the tokens as a single (or several) map or record, the downsides for the using could be much smaller, as you could just put the whole map there (even though I still not sure if there is any use for it).

While we do need maps and records, any solution that affects the definition of the data is a no-go for abstractions written by other parties than the page author. Using variables paves the cowpaths here.

[kizu]

I think a common workflow for mixins is to start developing CSS normally, then copy certain code into a mixin. Using a separate syntax makes this higher friction.

I partially agree, but an arg( -> var( replacement is simple; and when I imagine myself in the future where mixins are available, the point where you think “oh, now I need a mixin instead” might come early enough that there won't be a lot of things to replace.

Then, for mixins, if the variables are transparent, then copying the code will work naturally: arguments will be only necessary when you'd want to explicitly separate them from variables.

I'd imagine having to mention every used variables in using might create a much bigger friction than replacing some with arg().

[sorvell]

I really hope mixins can have access to those without every mixin having to explicitly define dozens or even hundreds of properties in a using clause, which would render them practically unusable.

Totally agree that without this, at least for the design system use case, I struggle to see how mixins would be practically useful.

Also, I do think there is a fundamental difference between incidental variables that happen to be defined somewhere in a subtree, and a website’s design system (typically defined in the :root)

I think I disagree with this since it seems relatively common to set design system custom properties for given subtrees. Couple examples: I need this right bar to always be darker or this dialog to always have explicit error button states.

[sorvell]

I really liked the idea to recall the arguments via arg(--foo)

That could be a piece of the puzzle but it seems like maybe there's a problem with the fact that we just have use : for assignment. For example, it's not uncommon currently to define "private" custom properties by convention (--_private). That always feels weird, but do we leverage it here?

What does it mean to define a value inside a mixin?

@apply --bar(--b: 5px;) {
  outline: arg(--b) solid; /* 5px? */
  border-width: var(--b); /* 2px  or requires `using` */
  padding-left: var(--a); /* is this anything? */
}

@mixin --foo(
  --a: 1px;
) {
  --b: 2px; /* is this always a custom property? */
  div {
    @apply --bar();
  }
}

[kizu]

What does it mean to define a value inside a mixin?

I think this is an interesting question indeed.

There will be more research required to gauge how common this use case is.

I will assume that the conflicts like this one is something that we need to handle, but it is a rare enough case to grant a more verbose solution, allowing to make the common cases more simple.

I assume that most developers will want to treat any variables defined inside functions or mixins as being as the “pseudo-ancestors” of any nested function or mixin calls. Again — I assume based on how I think I'll treat it, but this is likely a case where some polling might be required.

Here is how I'd think of the above example (adding some extra stuff to complicate things even more)

@mixin --bar(--b: 5px;) {
  outline: arg(--b) solid; /* 5px as the default value for the --b argument */
  border-width: var(--b); /* 2px as overrided from the `--foo` */
  padding-left: var(--a); /* 0px from the `.foo`, as the `--a` on the `foo` is an argument, not a variable */
  margin: var(--c); /* 1px as we passed the outer --b via `using`, and then passed it to `--bar` via `with` with the `--c` name */
}

@mixin --foo(--a: 1px;) using (--b as --b-outer) {
  --b: 2px; /* custom property override */
  --c: var(--b-outer); /* we can access the outer `--b` by renaming it with `using` */
  div {
    @apply --bar() with(--b-outer as --c);
  }
}

.foo {
  --a: 0px;
  --b: 1px;
  @apply --foo();
}

Basically:

1. We can separate arguments and variables via arg() and var(). We're getting more and more dashed idents everywhere, so I think it is perfectly fine to have these types of separation.

2. If we want to define a local variable with the same name as the outer, while still having access to the outer, we can introduce using(--a as --b) for renaming the variables.

3. If we'd want to override the value of some variable consumed by some mixin, we could introduce something like with(--a as --b).

---

Note that this is more of a brainstorming around the issues while assuming that the most cases won't require either using or with and will be fine with variables being completely transparent, and being overrideable on the nested scopes. Also note that the example is very abstract and is non-practical — to understand what works or not, we'd need to write some pseudocode for some more practical examples of different types of complexity, from more simple DRY mixins and functions, to more complicated constructions and abstractions.

[sorvell]

I'm starting to think we're over-thinking this and should just let all the properties come through and just shadow. There is already a problem of potentially shadowing custom property values in any rule, and typically careful naming is required to avoid this. My sense is that it doesn't seem sufficiently more problematic here to warrant a bespoke solution.

Others have argued that all external variables should be (somehow) implicitly available.

@mirisuzanne This seems to suggest that this behavior might be hard to implement or design. Is that the case?

[xiaochengh]

Edit: the ideas in this comment has been superceded. See my other comment.

---

I think functions and mixins are very different regarding whether/how to access external variables, and should be discussed in separate issues.

Speaking of functions only:

I strongly agree that external variable access must be lexically scoped. Allowing a function to access something from an unknown caller makes the behavior totally unpredictable. I assume dynamic scoping is just a legacy thing that should be completely avoided today.

Tab's using() still looks like dynamic scoping to me, as the function still doesn't know where the variables are from.

---

Alternative idea: allow nested functions (and make the language more functional)

Example:

@function --outer(--foo) {
  /* declares a --foo argument */
  @function --inner() {
    /* captures --foo from the outer scope, same way how capturing works in many other languages */
    result: calc(var(--foo) / 2);
  }
  result: calc(var(--foo) + --inner());
}
@function --outer2() {
  /* captures --foo from the "global" scope, which is the element's custom properties */
  result: calc(var(--foo) / 2);
}
.foo {
  --foo: 1;
  width: calc((--outer(10) + --outer2()) * 1px); /* (15 + 0.5) * 1px */
}

And I don't mind having arg() if that addes more clarity.