Generating user-friendly class names

[LucasUnplugged]

Hi all! 👋🏻 I'm new to the Stitches community, but feel like I'm hooked! 😁

I've been having a conversation with @peduarte and @afzalsayed96 in this (closed) issue and, as suggested, am moving the convo onto a discussion thread.

---

Overview

The core of what is being discussed is the generation of user-friendly class names, which would make it easier to debug the rendered code, by letting us know where each class is coming from.

Also at the core is if/how this might change the Stitches API, and whether that's desirable.

A semi-related (though slightly different) part of the conversation has been about setting the component displayName, which is handy when inspecting the code via React Dev Tools. @afzalsayed96 has already created a babel plugin for that — which is awesome, though doesn't address the class name issue.

Proposal

Here's what I'm proposing, as seen in this commit to my fork:

1. The styled function would have an optional 3rd param (string), which could be used to generate friendly names.
2. If the 3rd param is passed, it is used both for the class names, AND for the displayName property.
3. This could remain a sort of "hidden feature", if the Stitches team (and community) would like to maintain the current publicly-documented API — but at least a babel plugin could leverage this feature to provide more meaningful display names AND class names.

Usage

Usage (possibly done through a plugin) would be as simple as:

const Box = styled("div", { boxSizing: "border-box" }, "Box")

Output

I've tested this with a local build, and it worked beautifully, with an output such as:

<header class="c-Box-lesPJm c-Flex-dhzjXW c-Row-lfylVv c-Header-fVzExb"><h1>Stitches Demo</h1></header>

<button class="c-Box-lesPJm c-Button-bItMgZ c-Button-bItMgZ-liHaWo-primary-true">Primary</button>

And a React Dev Tools output of:

And a Chrome dev tools output of:

That looks pretty sweet to me, and would make understanding where each style is coming from (via the class names) very easy.

---

NOTE that the Header is composed of styled components, in this sequence:

Box -> Flex -> Row -> Header

[peduarte]

Hi, thanks so much for kicking this off.

I agree that allowing users to provide a friendly class name is a good idea!

I like your proposal, but the styled API isn't limited to 3 arguments. It can accept an infinite number of style objects or Stitches compositions - this is something that cannot change

I have a couple of ideas that I'd like feedback on:

Introduce defaultProps

Jonathan and I have been talking about the possibility of renaming defaultVariants to defaultProps. This would allow users to not just define the default variant but also... wait for it... the default props. This includes any valid props, so className would obviously work.

It would look like this:

const Box = styled('div', {
  boxSizing: 'border-box',
  defaultProps: {
    className: 'custom-class'
  }
})

Technically speaking, this could be used as a way to generate friendly class names, but worth noting:

• they wont be prefixed or hashed
• they won't be used as a CSS rule selector. It'd be added to the DOM element, but there wont be any styles attached to it
• they would be shipped to the production build

Would this be enough?

---

Rely on babel

Would this type of API be better suited for babel rather than the JS lib itself? Both for the DX and less JS to be executed (thinking about perf here).

The benefit of using Babel is that users don't have to do anything - apart from adding the babel plugin.

const Box = styled('div', {})
// <div className="stitchesHash123 s-Box"

const BlogTitle = styled('div', {})
// <div className="stitchesHash123 s-BlogTitle"

The class name is automatically added based on the const. This makes maintenance much easier too.

---

Chances are we'll end up renaming defaultVariants to defaultProps, but for totally separate reasons.

In regards to friendly class names: right now, I feel most comfortable going with the Babel approach, but open to ideas and thoughts.

Thanks!

[afzalsayed96]

+1 for the defaultProps idea @peduarte. It also opens up the possibility for passing a default as prop which I think is a long requested feature from the community.

Also pretty much agree on the Babel approach. Only thing I'm hesitant about is that it would only solve the problem partially i.e.:

they won't be used as a CSS rule selector. It'd be added to the DOM element, but there wont be any styles attached to it

I'm still wondering if there would be a way to prefix the actual classes that are applied to DOM as well as used as selector with Babel. That would make significantly more sense according to me.

Also, I think there's a way to only use a Babel plugin in the dev env and not in prod so we no longer need to worry about:

they would be shipped to the production build

[LucasUnplugged]

+1 for the defaultProps idea @peduarte. It also opens up the possibility for passing a default as prop which I think is a long requested feature from the community.

Yeah, I'm all for this as well, regardless of any considerations specific to this discussion.

Also pretty much agree on the Babel approach. Only thing I'm hesitant about is that it would only solve the problem partially i.e.:

they won't be used as a CSS rule selector. It'd be added to the DOM element, but there wont be any styles attached to it

I'm still wondering if there would be a way to prefix the actual classes that are applied to DOM as well as used as selector with Babel. That would make significantly more sense according to me.

Yup, I love minimal DX too, so am all for the Babel approach as well.

That said, I think the best (maybe only?) way around that hesitation is having Stitches itself provide some support for doing this at its core, even as an undocumented feature. Otherwise, the babel plugin is forced to try to tack it on, and the solution becomes much more limited.

Aside from my suggestion, another similar option would be to have something like a componentName property in the style object, which could be undocumented and added via babel, which would have the same effect as my suggestion.

Either way, I think the best way to give the babel solution enough teeth would be to give this first-class support in Stitches itself, even if it's undocumented. I think that would get the best of both worlds (fully integrated solution + minimal DX).

[LucasUnplugged]

Linking my latest proposal PR for this here as well: #916.