[css-mixins-1] A var()-based model for mixin parameters

[andruud]

Introduction

The mixins specification currently implements parameters and locals by way of custom env. Custom environment variables could be useful in their own right, but I'm not convinced they're a good fit for mixins, since they split "parameters"¹ into two silos that need to be explicitly remembered and dealt with by the author at every site of usage. We also have to invent a new concept of lexically (or dynamically) scoped environment variables, which is annoying when custom properties already are intrinsically scoped---a fact we used to solve "locals" for custom functions already.

Moreover, I don't think the current vision of custom env() works well technically, because it is not clear when (custom) env()functions would resolve (#12676), and there seems to be no single correct answer:

• It cannot resolve at computed-value time (like today), because that would prevent it from working in at-rule preludes, like @media.
• It cannot resolve at soon-after-parsing time², because that doesn't work well for declarations:
  • We would need to invent a new way of handling invalid env(). (E.g. a guaranteed-invalid keyword that we sub in.)
  • It would mean that e.g. attr(my-env-containing-attribute) would no longer work; we cannot substitute stuff in DOM attributes early.
  • Relatedly, "var()-in-var()" functionality (which we introduced along with the work on inline if()/custom functions/argument grammars, [css-values] Short-circuit if() evaluation #11500) would not work: env(var(--myenv)).

Does that mean that env() sometimes resolves at soon-after-parsing time², and sometimes at computed-value time? This seems unfortunate, and annoying to have to design around in the future when adding new interactions with IACVT, for example.

Additionally, div { @apply --my-mixin(var(--x)); } where the mixin parameter is used in e.g. a @media prelude will be forever impossible if we stay on the current path.

Proposal

Instead of mixin parameters existing in a separate namespace, they are placed in a separate "hypothetical element" that exists between any hypothetical elements created by custom functions and the real element. Essentially, every mixed-in declaration acts as if wrapped by a would-be (unobservable) custom function:

@mixin --verdant(--c) {
  color: oklch(0.7 var(--c) 144);
  background-color: oklch(0.5 var(--c) 144);
}

div {
  @apply --verdant(0.2);
}

Desugars into:

@function --f1(--c) {
  result: oklch(0.7 var(--c) 144);
}
@function --g1(--c) {
  result: oklch(0.5 var(--c) 144);
}

div {
  /* CSSNestedDeclarations { */
  color: --f1(0.2);
  background-color: --g1(0.2);
  /* } */
}

This means mixin parameters can be referenced with var() as normal, and (crucially) at the normal time; cases with attr() and "var()-in-var()" should work as expected.

Each (nested) @apply call creates its own "hypothetical element" per declaration, inheriting locals/arguments between them as defined for custom functions.

Here is a more complicated example which adds some color to an element, and places arrows pointing to that element by using ::before and ::after, while varying the colors based on a single input color:

@mixin --squish(--left-color <color>,
                --right-color: var(--left-color)) {
  &::before {
    content: "🡆";
    background-color: var(--left-color);
  }
  &::after {
    content: "🡄";
    background-color: var(--right-color);
  }
}

@mixin --colorized-squish(--color <color>) {
  background-color: var(--color);
  border: 2px solid oklch(from var(--color) calc(l - 0.1) c h);
  @apply --squish(oklch(from var(--color) calc(l - 0.3) c h),
                  oklch(from var(--color) calc(l - 0.2) c h));
}

div {
  @apply --colorized-squish(tomato);
}

This desugars to the following, splitting up the nested rules into three sections so it's easier to read:

div {
  /* CSSNestedDeclarations { */
    background-color: --f1(tomato);
  /* } */
}

/* background-color */
@function --f1(--color <color>) {
  result: var(--color);
}

/* ======== */

div {
  &::before {
    content: --g1(tomato);
    background-color: --h1(tomato);
  }
}

/* content */
@function --g1(--color <color>) {
  result: --g2();
}
@function --g2() {
  result: "🡆";
}

/* background-color */
@function --h1(--color <color>) {
  result: --h2(oklch(from var(--color) calc(l - 0.3) c h),
               oklch(from var(--color) calc(l - 0.2) c h));
}
@function --h2(--left-color <color>,
               --right-color: var(--left-color)) {
  result: var(--left-color);
}

/* ======== */

div {
  &::after {
    content: --i1(tomato);
    background-color: --j1(tomato);
  }
}

/* content*/
@function --i1(--color <color>) {
  result: --i2();
}
@function --i2() {
  result: "🡄";
}

/* background-color */
@function --j1(--color <color>) {
  result: --j2(oklch(from var(--color) calc(l - 0.3) c h),
               oklch(from var(--color) calc(l - 0.2) c h));
}
@function --j2(--left-color <color>,
               --right-color: var(--left-color)) {
  result: var(--right-color);
}

Conceptually, each declaration produced by an @apply call gets a "private" custom function call stack with a size equivalent to the number of @apply calls needed to get there.

I'm assuming it's possible to effectively get the above behavior in a somewhat performant way without literally creating a complete function chain for every declaration. How feasible this is to implement has not yet been seriously investigated; my gut feeling says it should be approachable, but we will have to look into this further.

---

There was a concern raised by @EricSL about how the following should resolve:

  @mixin --set-outer(--outer) {
    @apply --set-inner(env(--outer));
  }
  @mixin --set-inner(--inner) {
    @apply --override-outer(env(--inner), blue);
  }
  @mixin --override-outer(--inner, --outer) {
    color: env(--inner);
  }
  #whatcolorami {
    @apply --set-outer(red); /* red, blue, or infinite loop? */
  }

This concern comes back to when env() should resolve, and what envs actually bind to. Are they resolved eagerly at the @apply site, or are they transported inside other envs and interpreted at the final usage site? It's not clear how well-defined this is by the spec right now (it currently expects lexical and dynamic scoping of envs simultaneously), but in any case, this proposal would desugar that as (replacing env() with var()):

  @function --f1(--outer) {
    result: --f2(var(--outer));
  }
  @function --f2(--inner) {
    result: --f3(var(--inner), blue);
  }
  @function --f3(--inner, --outer) {
    result: var(--inner);
  }
  #whatcolorami {
    /* CSSNestedDeclarations { */
      color: --f1(red); /* Final color: red */
    /* } */
  }

---

The spec currently has an inline issue which explains that we need an analogue to inherit, but for parent lexical scopes of env(). With this proposal, we can obviously just use inherit, and it will resolve to the value of the parent dynamic scope:

@mixin --color-or-default(--c: inherit) {
  color: var(--c);
}

:root {
  --c: tomato;
}
.foo {
  @apply --color-default(); /* tomato */
}
.bar {
  @apply --color-default(olive); /* olive */
}

Locals

Instead of using scoped custom environment variables to represent locals, we could use a special at-rule to add local custom properties to the "hypothetical element":

@mixin --decorate(--c) {
  @local --temp: oklch(from var(--c) 0.3 0.2 h);
  border-color: var(--temp);
  accent-color: var(--temp);
}

div {
  @apply --decorate(olive);
}

Here, @local (name pending) is basically a way to add a custom property to the custom functions "generated" to carry out this mixin:

@function --f1(--c) {
  --temp: oklch(from var(--c) 0.3 0.2 h);
  result: var(--temp);
}

@function --g1(--c) {
  --temp: oklch(from var(--c) 0.3 0.2 h);
  result: var(--temp);
}

div {
  /* CSSNestedDeclarations { */
    border-color: --f1(olive);
    accent-color: --g1(olive);
  /* } */
}

Inner @apply calls would be able to see a reference to this --temp property by the regular inheritance mechanism of custom functions.

Locals "cascade" within the mixin; last seen wins:

@mixin --late-green() {
  @local --temp: red;
  border-color: var(--temp);
  accent-color: var(--temp);
  @local --temp: green;
}

div {
  @apply --late-green(); /* green, not red */
}

Locals are allowed within conditionals, but are not scoped to their parent rules. (Like how locals work in custom functions.)

Block Conditionals

Conditional at-rules (e.g. @media) are supported within @function rules, but we don't yet support arbitrary substitution functions within those preludes:

@function --f(--x) {
  @media (width < var(--x)) { /* Not supported yet */
    result: 1;
  }
  result: 2;
}

I suggest we adopt the same behavior for @mixin for now, and defer support for var()-in-preludes to a future level.

That said, it does appear that we have all the building blocks we need to actually support this soon. With the @if proposal in #12909, the following would be possible, for example:

@mixin --m(--x) {
  @if media(width < var(--x)) {
    font-size: 20px;
    color: green;
  }
}

From there, making @media work with var() is a matter of defining it to behave like @if.

Limitations

@LeaVerou has expressed concern that e.g. @apply var(--my-mixin-name); isn't possible. While this proposal would make @apply --fixed-name(var(--x)) viable (where --x comes from the element) , it still doesn't allow dynamic dispatch of the mixin names themselves. I can see the value of this, but I could not figure out how to make this work while also retaining the capability of having arbitrary nested rules within mixins.

If we imagine a mixin that only accepts declarations (think of it as a parameterized custom shorthand that expands late), then I believe @apply var(--my-mixin-name); should be possible.

If we need to discuss this, it should probably be in a separate issue.

Summary

Proposals:

• Drop custom environment variables from css-mixins-1.
• Desugar mixins into custom functions.
• Defer support for var() in conditional preludes (e.g. @media) until later.

cc editors: @mirisuzanne, @tabatkins

EDIT: Removed some CSSNestedDeclarations comments that were not helpful.

Footnotes

1. In this case, "parameter" includes regular custom properties,
   since they also effectively parameterize styles. ↩

2. I.e. the time when the parsed tree of rules is traversed
   and rules are sorted into a more efficient structure for matching.
   This is also the time (in Blink, at least) when media queries for
   regular @media rules are evaluated. ↩ ↩²

[EricSL]

I think some concept of lexical inheritance is unavoidable for mixins, but maybe I am misunderstanding the details of this proposal. How would the following desugar?

<style>
@mixin --two-divs-in(--col) {
  & > div > div {
    color: var(--col)
  }
}

.two-in-red {
  @apply --two-divs-in(red);
}

.two-in-green {
  @apply --two-divs-in(green);
}
</style>
<div class="two-in-red">black
  <div class="two-in-green">black
    <div>Am I red?
      <div>Am I green?</div>
</div></div></div>

That one is possible with the current implementation.

Also, the spec has a --triple-border example which has a :has(&) selector which would not inherit any vars; do we want to make it possible to propagate vars out as well as in?

[andruud]

How would the following desugar? [...]

@function --f1(--col) {
  result: var(--col);
}

.two-in-red {
  & > div > div {
    color: --f1(red);
  }
}

@function --g1(--col) {
  result: var(--col);
}

.two-in-green {
  & > div > div {
    color: --g1(green);
  }
}

EDIT: Although I suppose there's no point in desugaring to multiple identical functions. But the end result is the same either way.

Also, the spec has a --triple-border example which has a :has(&) selector which would not inherit any vars; do we want to make it possible to propagate vars out as well as in?

Yeah, I was looking at that example earlier today (currently "Example 16"). This proposal does not change how that works. The inline issue associated with the example (currently "Issue 2") asks whether we should try to do something to avoid the "workaround" in the example, and in my opinion the answer is "no"; I don't really see it as a workaround. If you want to "capture" a certain computed value at a point in the inheritance chain and send it down, then the "workaround" is reasonable way to do it, and not something mixins can do automatically. In any case, it would be a separate issue.

[EricSL]

Okay, I missed the pre-substitution you were doing. I like this now. I'm not 100% sold because it is weird that both kinds of variables are evaluated with var() but their inheritance works very differently with one evaluated early and the other late.

So another way of thinking about this is, @local defines a variable that doesn't inherit and also isn't visible outside its nested scope even on its element, but the definition of that variable (not the value itself) is copied into any nested rules. Furthermore, inherit() on such a property will look one lexical level up rather than up the DOM tree like for other properties. Is that right?

So you could also look at my .two-in-green selector as desugaring to:

.two-in-green {
  @nest {
    @local --arg1: green;
    @nest {
      @local --col: inherit(--arg1);
      & > div > div {
        color: var(--col);
      }
    }
  }
}

Which in turn desugars to

.two-in-green > div > div {
  @nest {
    @local --arg1: green;
    @nest {
      @local --col: inherit(--arg1);
      @nest {
        color: var(--col);
      }
    }
  }
}

Is this equivalent to what you are proposing?

[tabatkins]

@andruud Oooh, this is nice. I love the thought you put into this, thanks so much! I agree that this probably looks like it solves the issues I was trying to resolve with avoiding scope pollution, and the reuse of the custom function machinery is very clever. I'll want to poke at it a little in some unusual cases, but it certainly looks like this solves the interaction issues between Mixins and var() very well. Awesome! I definitely appreciate not having to invent an entirely new resolution time and behavior for all of these things.

The other reason I did env() was specifically to allow using them in @media, which you note this approach doesn't solve. But your @if idea for letting us invert rules into declarations would fix that issue, so I think I'm satisfied with this.

So this sounds great, I guess?

[tabatkins]

As noted in the OP, this new model does answer how to handle things like @apply --foo(var(--bar));; it inverts into a custom function that is passed the same arg. This, however, has the exact same issue that the current spec does (as noted in the Mixin Args section, between example 15 and 16 and explained more fully in Example 16 with some workarounds): any values that resolve differently based on the element they're used on (var(), attr(), em values, etc) will resolve based on what element the mixin actually puts them on, rather than on the element the mixin is @apply'd from.

This kinda sucks, but in discussion with Anders, I think we can have a partial solution. Most Mixins will be only styling the @apply element and its children/descendants/pseudos; they'd be completely unaffected by assuming they're scoped (a la @scope). If we assume they're scoped, we can rely on inheritance to do hygienic renaming (explained in #12909 (comment) by Anders) and get the values to correctly resolve based on the @apply element, regardless of where they're eventually used. (Example 16 has an example of doing this by hand, as a workaround.)

So, what if we just declared that Mixins were scoped by default - that is, rather than the mixin body being a CSSNestedDeclarations, it's a CSSScopeRule, and any nested style rules in the body were scoped to the @apply element? Then we can do the "store the argument as an unobservable variable on the @apply element, and rewrite references to use that instead" transform automatically. This would also enable some things that are impossible to do by hand, like allowing @apply --mixin(var(var(--var-name))); to work (because we know it has be rewritten to a hygienic reference, and can carry that information around until the inner var() is actually resolved).

Then we can have a keyword on the @mixin rule that opts out of that, and also turns off the hygienic rewriting, for when you do want to do a Mixin that styles parents or siblings or something.

[mirisuzanne]

I like this overall solution for variables in mixins. I have some concerns about assuming mixins can only impact descendants - though it certainly does help sidestep the question of where variables resolve. I just expect patterns like disclosure widgets might also be candidates for mixins:

button[aria-expanded="false"] + div {
  display: none;
}

On the other hand, this could be written to apply on the div, and reference the button as context outside the scope:

@mixin --disclose {
  button[aria-expanded="false"] + & {
    display: none;
  }
}

.show-hide { @apply --disclose; }

So maybe that works out ok. The concern would be if we need variables to resolve on one sibling and apply to the other.

If we do assume this, then :scope in a mixin refers to the applying element?

[tabatkins]

I have some concerns about assuming mixins can only impact descendants - though it certainly does help sidestep the question of where variables resolve.

Right, we definitely need to allow affecting non-descendants, you just won't get the nice var()/em/attr()/etc behavior if you opt into that. It's a tradeoff the author has to make: hygienic arguments, or unscoped application.

If we do assume this, then :scope in a mixin refers to the applying element?

I suppose so, for consistency. Probably not strictly required, but I don't think it matters much either way.

[andruud]

I have some concerns about assuming mixins can only impact descendants - though it certainly does help sidestep the question of where variables resolve.

Right, we definitely need to allow affecting non-descendants, you just won't get the nice var()/em/attr()/etc behavior if you opt into that. It's a tradeoff the author has to make: hygienic arguments, or unscoped application.

Previously (off-GitHub), we talked about @mixin unscoped --m(), but perhaps it makes more sense to do it on the @apply side? E.g. @apply unscoped --m(1em) could make it more "locally obvious" that your 1em is going to be affected by the unscoped.

If we do assume this, then :scope in a mixin refers to the applying element?

I suppose so, for consistency. Probably not strictly required, but I don't think it matters much either way.

Wait, in my mind this is strictly required and we don't have any other choice. What am I missing here? What do we mean by "applying element"?

In case it helps reveal what I didn't get, this example:

@mixin --disclose {
  button[aria-expanded="false"] + & {
    display: none;
  }
}

.show-hide { @apply --disclose; }

would (in a scoped-by-default world) desugar to something like:

@function --f1() {
  result: none;
}

.show-hide {
  @scope (&) {
    button[aria-expanded="false"] + & {
      display: --f1();
    }
  }
}