[css-mixins-1] Scoped mixins

[andruud]

As currently defined, mixin parameters are not evaluated in the context of the element they appear to apply to. Example:

<div class=foo>
  <div class=bar style="--theme:red; font-size:8px"></div>
</div>

@mixin --colorize-tree(--color <color>) {
  &, & * {
    border-color: oklch(from env(--color) calc(l/2) c h);
    accent-color: oklch(from env(--color) calc(l/2) c h);
  }
}

.foo {
  --theme: green;
  @apply --colorize-tree(var(--theme));
}

The above @apply statement would at first appear to colorize the tree green. In reality the var(--theme) gets interpreted against each element it applies to; <div class=bar> gets colorized as red.

The same is true for element-dependent values in general, e.g. em units:

@mixin --pad-tree(--w <length>) {
  &, & * {
    padding: env(--w);
  }
}

.foo {
  font-size: 20px;
  @apply --pad-tree(1em);
}

The above looks like it applies a padding of 1em = 20px to the whole subtree, when in reality it's using the font-size of the elements that are ultimately matched; <div class=bar> gets a padding of 8px. See also this relevant example in the specification.

Short of disallowing computationally dependent values, there is not much we can about this in the current model; env() traverses lexical scopes looking for a matching name, without any knowledge of elements at all.

---

In the var()-based model for mixin parameters, parameters and locals are based on the same dynamic scoping model proposed (or at least spearheaded) by @LeaVerou (#10954). This means we could potentially perform a "hygienic rewrite" (so called by @tabatkins) of the parameters; the --pad-tree example becomes effectively:

@function --f(--w <length>) {
  result: var(--w);
}

.foo {
  font-size: 20px;
  /* Secret, unobservable custom prop from the @apply call: */
  --pad-tree-param-1: 1em; /* Registered type: <length> */
  &, & * {
    padding: --f(var(--pad-tree-param-1));
  }
}

Here, 1em is interpreted at the @apply-site, and made available in computed-value form to the subtree.

This works only when the mixed-in rules all select (inclusive) descendants of the @apply element, hence the mentions in #12927 about mixins optionally being scoped. Applying a scoped mixin would produce behavior similar to wrapping an @apply call in a @scope rule:

@mixin --push-sibling() {
  & + * {
    margin-left: 200px;
  }
}
div {
  @apply --push-sibling();
}

would expand approximately to:

div {
  @scope (&) {
    & + * { /* Not in scope */
      margin-left: 200px;
    }
  }
}

This scoping would give us a guarantee that any information "captured" on the @apply element due to hygienic rewriting will be available to anything that gets mixed in. The obvious drawback is that elements outside the "apply root" can no longer be matched.

There are several open questions about scoped mixins:

• Are they scoped by default, and then you opt out? (Or vice versa?)
• How do you opt-in/out? @mixin unscoped --m() {}?
• Or do you opt-in/out on the call site? @apply unscoped --m().

cc @mirisuzanne

[mirisuzanne]

I suppose another question here is: do we literally apply scope, including the cascade specificity/proximity implications? My instinct is that we don't want every mixin to negate the specificity of the outside selector, so at least in that way we're not likely applying scope logic completely. Applying proximity would be a bit less surprising, but not necessarily intended here.

---

Parameters resolving on the subject-elements rather than the apply-element is pretty surprising behavior, so I doubt we want that as the default. And if a mixin author wants to resolve a value on the subject-elements, they can still do that by using non-parameter variables in the output. So I expect the main reason to want a non-scoped mixin would be the ability to target siblings?

Even with scoped functions, that can be achieved by changing which element the mixin is applied to – scoped selectors can reference previous siblings as context, and parent elements could put all siblings within a scope. That's likely to trip people up at first, but it's teachable.

There's also an accepted proposal for @sibling-scope (or something like that), but the issue here isn't actually related to scope-ability - we're only using scope as a stand-in for inherit-ability. So I don't think that helps.

[andruud]

do we literally apply scope

Especially if mixins are scoped by default, I think we should only apply scoping, and not mess with specificity/proximity. If the author wants that, they can literally use @scope inside the mixin, or at the @apply side.

Even with scoped functions, that can be achieved by changing which element the mixin is applied to – scoped selectors can reference previous siblings as context, and parent elements could put all siblings within a scope. That's likely to trip people up at first, but it's teachable.

So are you thinking that we maybe don't need unscoped mixins at all? Instead of having unscoped mixins, just lift the scope? E.g. .foo { @apply --m(); } => :has(> .foo) { @apply --m(); }.

There's also an accepted proposal for @sibling-scope (or something like that), but the issue here isn't actually related to scope-ability - we're only using scope as a stand-in for inherit-ability. So I don't think that helps.

Yeah, this "hygienic rewrite" cannot be done in the general case because it can create cycles, e.g. a parent style depending on a child style:

@mixin --m() {
  .parent:has(&) {
    /* ... */
  }
}

.child {
  @apply --m();
}

[mirisuzanne]

So are you thinking that we maybe don't need unscoped mixins at all?

Yeah. It's not ideal, but it works consistently.

[kizu]

Related: I did a poll in Mastodon about a similar issue, but with regular custom properties: https://front-end.social/@kizu/115546765910089031

If we had mixins in #CSS, what would you expect the value of the border on a button to be with the following code?

@mixin --border {
	--width: 1px;
	@contents;
	--style: solid;
}
button {
	--width: 42px;
	@apply --border {
		border: var(--width) var(--style);
	};
	--style: dashed;
}

The options and their results were as such, after 177 people voted:

% of votes	option
20%	1px solid
22%	42px dashed
49%	1px dashed
10%	42px solid

The “correct” answer is what is in the current Chrome's prototype: the 1px dashed, but it is interesting that only half of all people who voted guessed correctly.

Things this can mean:

• It is not obvious what will happen, and this can be confusing for authors, but the majority kinda guesses right.
• The even split between the first two options stems not just from the misunderstanding, but often is collaborated by the reasons people provided in the comments.

Some quotes from people who participated, though they were only from people who wanted the “42px dashed”, or “scoped” version:

• https://front-end.social/@jaredwhite@indieweb.social

  I picked 42px dashed, because I don't think mixins should be able to overwrite variables that I've already defined at the point where the mixin gets used. But I can understand the logic of 1px.

• https://front-end.social/@dutchcelt@mastodon.social/115565719719587945

  I haven't really looked in the mixins proposals. So, I've no idea what I'm talking about.

  What I'm not sure about is when the properties are applied.

  So, my assumption is that all the custom properties in the 'mixin' are assigned to the 'content', regardless in which order they appear.
  The custom properties values inside the 'content' will be overwritten by any prepended custom properties.

  Of course, CSS rules wait until they've picked up all custom properties within their rule before applying the values.
  So in this case, you would say the mixin assigns all its custom properties to the mixin content, and the rule that applies the mixin overwrites the content values with all and any of its own custom property values.
  That would make the outcome: 42 dashed.

• https://front-end.social/@mayank/115546851849302360

  i want it to be 42px dashed but it will probably be 1px solid, or worse, 1px dashed.
  […]
  i don't want mixins (and functions) to be able to modify "global" stuff, unless explicitly given permission to. i know that's not how CSS has worked historically, but i feel like it's a missed opportunity to make things more modular.

  i guess the difference between outside/inside @apply in this case could be the value of --style? but if these are all on the same element, there probably shouldn't be a difference (so 1px dashed in both cases)

Quick test: yes, doing the scoped version will make it so the 42px dashed will apply: https://codepen.io/kizu/pen/wBGrybL

This is if the mixin was

@mixin --border(@contents) {
  @scope (&) {
    --width: 1px;
    @contents;
    --style: solid;
  }
}

Scoping by default will result in the version that only 22% expect (second most popular option), but I can see how this option is a more consistent one, and one where it is harder to mess up the author-defined styles outside the mixin with the styles inside the mixin.

That said, given the most popular option was an unscoped version with the literal substitution, if we implement something, I think we have to provide a way to control this. And, given the third most popular option is kinda the opposite, where people will expect the custom properties inside the mixin to have a higher priority, I wonder if that's also something that should be possible to control.

[andruud]

@kizu This issue is about DOM-based scoping, not lexical scoping.

Your Mastodon poll example:

@mixin --border {
	--width: 1px;
	@contents;
	--style: solid;
}
button {
	--width: 42px;
	@apply --border {
		border: var(--width) var(--style);
	};
	--style: dashed;
}

expands to (with some nested declaration rules removed):

button {
	--width: 42px;
	--width: 1px;
	border: var(--width) var(--style);
	--style: solid;
	--style: dashed;
}

and with scoped mixins as proposed here, it would be:

button {
	--width: 42px;
	@scope-without-specificity-proximity-effects (&) {
		--width: 1px;
		border: var(--width) var(--style);
		--style: solid;
	}
	--style: dashed;
}

The result here is 1px dashed regardless of how this issue resolves.

Quick test: yes, doing the scoped version will make it so the 42px dashed will apply: https://codepen.io/kizu/pen/wBGrybL

Not because of scoping. The stuff inside @scope (&) {} has higher lower specificity than button.

---

Lexical scoping (to get 42px dashed) is being discussed as an opt-in here: #11798.

EDIT: higher -> lower

[kizu]

It is not the same, but I think it is similar from an author's perspective: same as 1em can be considered as captured, some people can consider the values of custom properties to be “captured”, or being able to benefit from an effect that allows doing it.

The stuff inside @scope (&) {} has higher specificity than button.

I think you meant lower, as the custom properties from outside the mixin win, and the .foo { @scope (&) { … } } results in zero specificity?

It is useful to look at all these issues, and consider how we can cover all the authors' use cases, and where do we do it, basically, I agree with this issue's questions (where do we want to do it: on the definition or call site), but add a bit more context to the question, so we don't look at it in isolation.

[andruud]

The stuff inside @scope (&) {} has higher specificity than button.

I think you meant lower, as the custom properties from outside the mixin win, and the .foo { @scope (&) { … } } results in zero specificity?

Yes. Thanks. Corrected.

[andruud]

@kizu OK, I have a proposal that would hopefully remove some (not all) of the author confusion around what you mentioned: #13138. (It can be treated independently from this issue.)