Add stencils for styling

[NicholasBoll]

There has been a lot of interest in the new styling options introduced in v10. See #2265

The createStyles and createModifiers utility functions aren't obvious from the beginning. The concept of a Stencil is proposed. The concept is similar to the Vanilla Extract Recipes. A stencil would help developers think in terms of base styles and modifiers and the stencil would ensure each are created in the proper order to make sure style merging works as expected.

The API would look similar to this:

import { createStencil } from "./createStencil";

const myVars = createVars("color");
const buttonStencil = createStencil({
  base: {
    padding: 10,
    color: myVars.color
  },
  modifiers: {
    size: {
      large: {
        padding: 30
      },
      small: {
        padding: 5
      }
    },
    position: {
      start: {
        paddingInlineStart: 5
      },
      end: {
        paddingInlineEnd: 5
      }
    }
  },
  compound: [
    {
      modifiers: { size: "large", position: "start" },
      styles: {
        paddingInlineStart: 15
      }
    },
    {
      modifiers: { size: "small", position: "end" },
      styles: {
        paddingInlineEnd: 0
      }
    }
  ]
});

export default function App() {
  const [value, setValue] = React.useState("ff0000");
  const onChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.currentTarget.value);
  };
  return (
    <button
      style={myVars({ color: `#${value}` })}
      className={buttonStencil({ size: "large", position: "start" })}
    >
      Button
    </button>
  );
}

Stencils also introduce the concept of a "compound modifier". A compound modifier is an intersection of two or more modifiers. A overriding style can be defined at the intersection of two or more modifiers. An example we have in Canvas Kit of a compound modifier is size and iconPosition. Since icons have their own padding, less padding is needed before or after the icon and since padding is different depending on the size, the intersection of size and iconPosition determines padding overrides.

A stencil return as valid className. More technically it return a space delimited list of CSS class names. The result of the example would have 4 class names:

• base class
• size modifier
• position modifier
• size/position compound modifier

It will look something like "css-a1 css-a2 css-a3 css-a4"

A PoC can be found as a Stencil codesandbox

[vibdev]

Vanilla Extract Stencil.

Link Iis 404.

---

How doesn't compound resolution work, given

compound: [
    {
      modifiers: { size: "large", position: "start" },
      styles: {
        background: "green"
      }
    },
    {
      modifiers: { size: "small", position: "end" },
      styles: {
        background: "yellow"
      }
    },
    {
      modifiers: { size: "small", position: "end", foo: "bar" },
      styles: {
        background: "orange"
      }
    }
  ]

buttonStencil({
    size: "large",
    position: "start",
    foo: "bar"
})

I would expect the background to be orange here (that doesn't work in your sandbox, but I think that is the intention). Is it always exact? e.g. would

buttonStencil({
  size: "large",
  position: "start",
  foo: "baz"
})

produce a green background since it matches 2/3 and there is no full match? I assume not but wanted to double check.

[NicholasBoll]

Oops, that was an overzealous find/replace. I fixed the link. The link is to Vanilla Extract Recipes.

[NicholasBoll]

The intent is to support partial matches. When I load your codesandbox, the background is orange. Remember, since the utility functions are static, they add styles immediately to the document's head, but that sometimes messes up hot reloading. I plan to introduce a babel plugin to help with hot reloading by tracking style insertion order and maintaining that order via the plugin. For now, I refresh the page when the styles don't match the way I expect to while developing.

[vibdev]

oh right i forgot about that hmr bug.

---

The intent is to support partial matches.

How would this work, if it didn't find a full match would you just pick the fist one (by array order) that matches the most modifiers? I think I would rather it be only explicit matches, but interested in hearing the use case for partial matches.