[mediaqueries-5] Defining `@custom-media` inside conditional at-rules

[tursunova]

Currently Media Queries Level 5 spec allows custom media queries to be defined within other at-rules, including conditional rules like @media. This creates a logical paradox where a custom media query can be used in a condition before it has been defined, leading to a circular dependency that cannot be resolved. For example:

@media (color) and (--custom) {
  @custom-media --custom (max-width: 300px);
  ...
}

Proposing to explicitly disallow @custom-media rules from being defined inside any conditional group rules (e.g., @media, @supports), attempting to use @custom-media inside conditional at-rules will make custom media queries fail to be defined.

CC: @tabatkins @emilio

[romainmenke]

The (very popular) polyfill also doesn't support this. Although it seems we did receive a request to add support for this: csstools/postcss-custom-media#28

This is also the one scenario that I can imagine it being useful.

Given:

@import 'break-screen.css' screen;
@import 'break-print.css' print;
@import 'print' (--foo) print;
@import 'uses-unified-break.css';

Which with postcss-import results (I think):

@media screen {
  @custom-media --foo;
}
@media print {
  @custom-media --foo;
}

[emilio]

But can't you do that with something like this at the top level?

@custom-media --foo ((screen) and (...)) or ((print) and ...);

I guess not because screen and print are media-types, so you'd need two separate queries (--foo-screen and --foo-print or so?). That seems something that if needed we could easily lift if needed.

But yeah it's a good point that conditional stylesheets make this harder... To be fair, what I don't want is having to overcomplicate how we process stylesheets so that we need multiple passes, since that's already fairly hot code for pageload.

I wonder if an alternative is saying that @custom-medias don't apply "backwards", e.g.:

@custom-media --foo ...;
@media (--foo) {
  /* This uses the `--foo` from above, not the one below */
}
@media (--bar) {
  /* This never applies, `--bar` is not defined */
}
@custom-media --foo ...;
@media (--foo) {
  /* This uses the second `--foo` media */
}
@custom-media --bar ...;
@media (--bar) {
  /* This one works */
}

[romainmenke]

That seems worse :)

I think this kind of behavior would be surprising to authors because they expect the last definition (taking into account source order, cascade layers, ...) to have effect.

---

You can write:

@custom-media --foo-print-medium print and (min-width: 400px);
@custom-media --foo-screen-medium screen and (min-width: 500px);
@custom-media --foo (--foo-print-medium) or (--foo-screen-medium)

Or:

@custom-media --foo print and (min-width: 400px), screen and (min-width: 500px)

So I don't think there is any case that can't be expressed at the top level.
There is no capability that is lost by disallowing definitions of @custom-media inside @media.

Unsure if the same is true for @supports, @layer.

---

This issue seems somewhat related to #12417

Where we also want to avoid multiple passes.

[emilio]

I don't think it makes sense to incorporate layer order here if the names are global, since by definition media queries can alter the layer order. Doing so would add yet another layer of circularities (no pun intended)

[tabatkins]

Yes, almost by definition anything has to be allowed inside of "basic" conditional rules, the ones we can use in an import, because the stylesheet can be loaded by a conditional import. I think we'd need a super strong reason to violate that, but I think that doesn't apply here. The same applies to cascade layers.

The similarity to #12417 is actually very deep; it's basically the exact same problem, where a definition can theoretically affect what other definitions exist, at the stylesheet-parsing level. It's also, however, closely related to the custom env() issue, where we want env() to be usable in @media but also want @env to be usable inside of conditional stylesheets, and even directly inside of @media rules.

I feel like custom-media actually falls closer to env here, as we similarly have a JS API that can take up the slack of defining "truly global" values if we need. So I'd prefer we solved it the same way, and make the @custom-media rule lexically scoped. Standard last-wins behavior if there are multiple instances of a given name in a lexical scope, but each name only applies within the scope of the sheet/rule they're defined in, and nested scopes unless there's another definition there. The JS API, then, would be used to define custom medias that work across stylesheets.

This avoids all issues of circularity, or of values changing across the execution of a page except in well-defined (and I think understandable) nesting ways. The downside is that it does lean on JS for some use-cases, but I think there's enough useful cases that are ok with just using a custom MQ within the same sheet it's defined that we're probably okay.

[emilio]

I think that'd be rather unfortunate. Having a "base" stylesheet you import with the design system's tokens and breakpoints seems like a fairly common thing to want.

FWIW, I think something like what I suggested above (apply the last defined version that we've found by the time we get there) also solves the circularities while allowing for more common use cases, and that would also work for @mixin and co.

In general I think "invalid if not defined by the time you try to evaluate it in source order" is fairly reasonable for these kinda-parser-level things... (And yeah, I'm aware these are not quite parser level, but there's a clear distinction between these and things that are more tightly integrated into the cascade to me and implementation-wise)