[css-mixins-1] Expose environmental variables inside apply's contents block

[kizu]

The mixin's @apply rule (https://drafts.csswg.org/css-mixins-1/#apply-rule) has an optional @contents block.

Mixin can also define scoped environmental variables (https://drafts.csswg.org/css-mixins-1/#scoped-env).

Proposal: expose the scoped environmental variables defined inside a mixin to be visible inside the contents block.

Example:

@mixin --nice-hover(@contents) {
	@env --nice-pink: deepPink;
	
	&:hover, &:focus-visible {
		@contents {
			color: env(--nice-pink);
		}
	}
}

.default-link {
	@apply --nice-hover;
}

.inverted-link {
	@apply --nice-hover {
		background: env(--nice-pink);
		color: contrast-color(env(--nice-pink));
	}
}

Exposing scoped environmental variables like this could allow to define mixins that can provide both some default rules, as well as a way to use parts of them alongside some built-in variables that were used as a part of the mixin.

If the @apply is used inside another mixin's definition that contains an environmental variable of the same name, the scoped environmental variable from the applied mixin will win over the local one.

@mixin --foo(@contents) {
	@env --test: lightgreen;
	@contents;
}

@mixin --bar() {
	@env --test: pink;
	@apply --foo {
	  background: env(--test); /* lightgreen */
	}
}

This is because it is possible to rename the local one to be used inside while we can't access the applied mixin to modify the inner one:

@mixin --bar() {
	@env --test: pink;
	@env --test-inner: env(--test);
	@apply --foo {
	  background: env(--test-inner); /* pink */
	}
}

Basically, the declarations inside the contents block first look at the scoped environmental defined inside the applied mixin, then look for them outside.

Open Questions

• Should this be the default behavior for the scoped environmental variables, or should they not be exposed in this way by default and require us to explicitly provide them in some way?
  • I think it is better to do this by default: I don't see use cases that would require the opposite.

[andruud]

I'm not necessarily objecting to this, but ...

@mixin --foo(@contents) {
	@env --test: lightgreen;
	@contents;
}

@mixin --bar() {
	@env --test: pink;
	@apply --foo {
	  background: env(--test); /* lightgreen */
	}
}

... is that indeed desirable behavior from the perspective of --bar? This means that --bar's locals can't be "safely" used within @apply --foo's block, since they can be overwritten by --foo internals? (Imagine that --foo exists elsewhere, and is updated independently of --bar).

I don't see use cases that would require the opposite.

Having a shared intermediate result between stuff in @apply-blocks and elsewhere in the mixin?

[kizu]

is that indeed desirable behavior from the perspective of --bar?

Hmmm. Good point. I guess, possible solutions, brainstorming some ideas:

1. Make local env variables be “closer” than those exposed from the mixin. Because you're in a context you control, if there will be conflicts, you could just rename things. But it could feel pretty awkward.
2. Have some syntax for @apply where you'd need to explicitly define names of inner env variables that you're using, like @apply --foo using --test or something. Unless you define it this way, a local env will be used.
3. Instead of some kind of param in @apply, this could be a special at-statement to be used inside the @apply block, like @apply { @using --test, --test2, --etc; background: env(--test) }
4. Have a special version of env() like inner-env() or with some other name.

I think the solution is somewhere here, basically have some way to differentiate/define them.

I don't see use cases that would require the opposite.

Having a shared intermediate result between stuff in @apply-blocks and elsewhere in the mixin?

Yeah, options are: we make all @envs available inside the @apply in one way or another, or we make them private by default, and have some syntax for @contents that will define the envs that are available for the @apply block, like @contents using(--test); or something.

[kizu]

Playing with the #12927 prototype, and I have a few thoughts.

First, I think that the problem with overriding the outer custom properties from inside can be even more pronounced:

@mixin --test(@contents) {
  --foo: pink;
  @contents;
}

button {
  --foo: lightgreen;
  @apply --test {
    background: var(--foo);
  }
}

Without knowing the implementation details of the --foo mixin, the author might think that the background will be lightgreen, but it will be pink.

That said, mixins being able to apply custom properties already makes this awkward regardless, even without considering the @contents. The above can also be thought of as:

@mixin --test() {
  --foo: pink;
}

button {
  --foo: lightgreen;
  @apply --test;
  background: var(--foo);
}

With the background being obviously pink.

In both these cases, the author has control over what should take priority by moving their --foo after the @apply:

@mixin --test(@contents) {
  --foo: pink;
  @contents;
}

button {
  @apply --test {
    background: var(--foo);
  }
  --foo: lightgreen;
}

Now, the background will be lightgreen, as the button's --foo will override the --foo from inside the mixin (unless it is still higher in the cascade inside the mixin, due to importance or just added specificity).

This feels pretty awkward, but I am not sure if we can do anything about this, really. And this issue will be there regardless of if we use an env()- or var()-based model, as this is just regular custom properties.

Unless we make all custom properties inside a mixin local by default?

---

That said, I was also able to check that the local variables inside a mixin work already (as @local is not implemented, used the default arguments for this):

@mixin --test(@contents, --foo: pink) {
  @contents
}

button {
  @apply --test {
    background: var(--foo);
  }
  --foo: lime;
}

This works and will be pink! The background outside of the @apply does not see the inner --foo, but when inside the @apply it does, and it takes precedence over whatever is outside of @apply regardless of the order (I guess, due to the hypothetical element model?)

The following will be lightgreen, as expected, as the outer and inner background get different --foo values, and the outer overrides the inner:

button {
  --foo: lightgreen;
  @apply --test {
    background: var(--foo);
  }
  background: var(--foo);
}

Given there is already an issue with the regular custom properties and them being potentially overridden from inside the mixin regardless of the model, I am not sure we should do anything special for the local variables available this way? Unless, again, we solve this via making all the mixin's custom properties local by default, then there will be a reason to define some way to get the local variables inside the @apply block.

[andruud]

(Thanks for testing the prototype!)

I think as long are you're using plain custom properties, that behavior is working as expected, and we should not do anything about it.

Unless, again, we solve this via making all the mixin's custom properties local by default

As in --foo: line implicitly becoming @local --foo: lime? I think that interferes too much with the regular case of just mixin in a custom property.

But, I think we still have a decision to make here about @local:

@mixin --foo(@contents) {
  @local --test: lightgreen;
  @contents;
}

@mixin --bar() {
  @local --test: pink;
  @apply --foo {
    background: var(--test); /* lightgreen? pink? */
  }
}

At least from the perspective of this example alone, it seems wise to set up our function stack frames (i.e. "hyopthetical elements") such that declarations in the contents block do not see the locals inside the mixin.

[css-meeting-bot]

The CSS Working Group just discussed [css-mixins-1] Expose environmental variables inside apply's contents block.

The full IRC log of that discussion

<ydaniv> kizu: this depends on change from env vars to regular vars, moving to env vars simplifies things
<TabAtkins> look at this example:
<TabAtkins> @mixin --test(@contents) {
<TabAtkins> --foo: pink;
<TabAtkins> @contents;
<TabAtkins> }
<TabAtkins>
<TabAtkins> button {
<TabAtkins> --foo: lightgreen;
<TabAtkins> @apply --test {
<TabAtkins> background: var(--foo);
<TabAtkins> }
<TabAtkins> }
<ydaniv> ... you can use custom props inside, and means that if you define them they are args to the mixin, and will be invisible inside it
<ydaniv> TabAtkins: posted an example, mixin that sets foo
<ydaniv> ... the element also sets foo
<ydaniv> ... question is which color does it see? the one from the mixin sub?, can mixins shadow vars?
<miriam> q+
<ydaniv> kizu: in my opinion it's useful, however, if we want to explicitly say differently, when you look at the applied value from the side you don't know which one it will be
<ydaniv> ... so either we could either use the one inside, but by default would be more useful to use the one outside, a bit confusing
<ydaniv> TabAtkins: in this example it ends up light green
<astearns> q+
<ntim> my intuition would be either use inner, then outer (if inner is absent).
<ntim> failing that, ignoring both is an option
<ydaniv> ... agree it's possible the most obvious thing, content styles look more local, and if you have nested rule
<ydaniv> ... you wouldn't want to change behavior
<ydaniv> kizu: I think it's actaully pink there
<ydaniv> ... because if you use it this way, because it's a registered custom property
<kizu> https://www.irccloud.com/pastebin/D5y005wZ
<ydaniv> TabAtkins: you're right, if the mixin took that var...
<kizu> @mixin --test(@contents, --foo: pink) {
<kizu> @contents
<kizu> }
<kizu>
<kizu> button {
<kizu> @apply --test {
<kizu> background: var(--foo);
<kizu> }
<kizu> --foo: lime;
<kizu> }
<ydaniv> miriam: I think you're getting confused between what happens in impl and what we want
<ydaniv> TabAtkins: yes, exactly
<ydaniv> kizu: hard to tell from where something would come, and need to resolve it in some way
<ydaniv> TabAtkins: in this example don't care about impl.
<ydaniv> ... so ideally should not be pink?
<ydaniv> kizu: yes
<astearns> ack miriam
<miriam> `@apply dark-colors { background: var(--from-mixin); }`
<ydaniv> miriam: I agree we should with this, but counter for that I know in SASS it's different, where you have a mixin that defines stuff and then you psas a block and want an access to that
<fantasai> +1 miriam
<ydaniv> ... but agree that the default case would not be that
<kizu> `@apply dark-colors using all { … }` maybe?
<ydaniv> TabAtkins: in that case this behavior would be supported
<ydaniv> miriam: ok
<astearns> ack astearns
<ydaniv> astearns: have an explanation... but now confused
<ydaniv> TabAtkins: proposing for this behavior a contents block will see vars defined in the body of mixin,
<ydaniv> ... but it will not see ones defiend in args
<ydaniv> miriam: in several examples there's an @Local
<astearns> s/have an/had an/
<ydaniv> TabAtkins: a local var acts a like arg but just not listed args list
<ydaniv> miriam: in SASS that would not change the outside vars and access the inside, would that be possible?
<ydaniv> ... not sure how important
<ydaniv> kizu: I opened about this, regarding env vars, how do we access them
<ydaniv> TabAtkins: it's still possible for us to add syntax for that
<astearns> ack fantasai
<Zakim> fantasai, you wanted to ask about the earlier example
<ydaniv> fantasai: you had an example before, the contents passed in would have access to sutff in the body, but not parameters
<ydaniv> TabAtkins: yes
<ydaniv> fantasai: in that case the vars would be part of the output of the mixin
<ydaniv> ... so if you wanted a set of vars that put in the mixin, then you would need to overide those say vars on where the mixin is used?
<ydaniv> TabAtkins: yes
<ydaniv> ... currently yes
<ntim> It would be really useful for these kinds of issues to have all the possible combinations listed somewhere as a comment on the Github issue. Having to think through the combinations in your head highers the bar to contribution.
<ydaniv> miriam: that's what I was saying, we could have extra syntax for that
<ydaniv> TabAtkins: yes
<ydaniv> astearns: more qs or examples?
<ydaniv> TabAtkins: I think we got what we need
<ydaniv> ... folks think it's a good behavior, got approvals
<ydaniv> kizu: we should resolve after another related issue
<fantasai> I guess one of the advantages of env() was that it could be clearer about what resolves against what
<ydaniv> astearns: would like to get detailed examples of what we just talked about in the spec and why it works this way
<ydaniv> TabAtkins: yes
<kbabbitt> +1 astearns
<ydaniv> ... I can do that
<ydaniv> ntim: I think this issue is hard to reason about, right now trying to think about it and combinations and it's hard
<ydaniv> TabAtkins: fair enough
<ydaniv> astearns: moving on
<ntim> (and we should get examples of combinations written on the issue)