Behavior clarification: Should css.resolve accept top level CSS declarations?

[smoores-dev]

Do you want to request a feature or report a bug?

This is primarily a documentation question: the usage described below works, but is undocumented. It would be helpful to have clarification on whether this behavior is supported intentionally or incidentally, to aid in resolving theoludwig/vscode-styled-jsx#58.

Also, if this behavior is supported intentionally, I would propose updating the documentation to suggest using this approach to css.resolve over the existing documentation, as this approach doesn't require breaking encapsulation!

Discussed in vercel/vercel#6065

^{Originally posted by SMores April 3, 2021}
Hello!! I'm working on a project using styled-jsx with next.js. At some point I added a css.resolve call that looks like this:

const burgerStyles = css.resolve`
  display: block;
  position: absolute;
  top: 2.5rem;
  right: 2rem;

  @media (min-width: 769px) {
    display: none;
  }
`;

And then use it in the following JSX:

       <Burger
          className={burgerStyles.className}
          active={isNavShown}
          onClick={() => setIsNavShown((oldValue) => !oldValue)}
        />

This works exactly as I expected it to; the <Burger> component applies its className prop to its top level DOM element, which then gets the declarations defined above.

But... the docs don't ever actually show an example like this. Instead, they have examples that define an entire ruleset, which requires knowing what the DOM within the child component looks like:

const styles = css.resolve`
  button {
    display: block;
    ...
  }
`;

Again, the code that I'm currently using works! My question is: Is that purely incidental?? Is this explicitly supported behavior, or does it just happen to work now and might break in the future? If it's supported on purpose, could it be documented? Personally I have a strong preference for styling child components this way, as it doesn't require breaking encapsulation the way the documented examples do (that is, I don't need to know anything about the internal structure of the component in order to position it or give it margins).