Learnings from JSS

[kof]

Hi Nathan, we have been talking a lot about JSS and you seemed to be prototyping a material-ui integration with JSS, however you ended up with an own similar implementation. Can you share the learnings you have done and especially the reasons which stopped you from using jss as is?

[nathanmarks]

@kof Definitely, this project started out very much as an experiment (and still is somewhat), material-ui has some specific needs that I tried to address here. I'll write a more detailed response in the next few days.

[kof]

I am interested in adding what is needed, to allow material-ui use it. I believe material-ui requirements can't be so different. A big deal breaker was the SSR (undeterministic id's) which is changed now.

[kof]

I think the entire css in js community would profit if we combine our forces. The amount of work is sooo huge that nobody can do that all alone. I have recently added a roadmap to jss https://github.com/cssinjs/jss#roadmap which reflects the biggest challenges in the project.

[nathanmarks]

@kof I agree that it would be great to pool effort towards a project. I'm still intending on writing an overview of the requirements/difficulties/findings I encountered trying to find a solution for material ui with jss in particular. They weren't all unsolvable with jss, it was the closest I got out of the libraries I had tried using. I also tried aphrodite and another one before jss... the name escapes me though right now.

One or two of the requirements might not be considered a "best fit" for css in js, but when the library (material-ui) has a diverse user-base certain features are necessary to provide a good developer experience all around (also related to the current developer tooling available). They could be made possible with the right options and/or plugin API. I think I got around one of them with jss by mis-using a feature (global named selectors).

I'm in my last week at my current job and things are suddenly very busy, but I'll write out more on the weekend. I'm off next week.

[nathanmarks]

@kof

There are a few difficult issues that I encountered trying to rig up a solution for material-ui using jss (and a couple of other libs).

An important thing to keep in mind while reading this is that the requirements of material-ui are different from a lot of other use cases because at the end of the day we need to provide a usable library API for a diverse group of users. In contrast, it's much easier to work around the difficulties of css in JS when it is being used internally in a system where you and your team control the front-end and can make decisions on sacrifices, workarounds, "gotchas", etc....

I think you'll find that some of the design decisions in stylishly help cater towards a specific use case, and are not necessarily "the best" way to do things for CSS in JS if you're looking at a blank slate.

We really want to make CSS in JS work for us and our users.

createStyleSheet and theming

material-ui uses a dynamic, js based theming system which sits on context in the user's React application.

Whatever const styleSheet = createStyleSheet(...) returns needs to be a stateless object (server side concurrency) that can be used to generate stylesheets with any theme variables. This immediately adds a requirement to create an abstraction around jss in order to be able to create stylesheets at render using the theme currently on context with a user friendly API.

Right now, stylishly accomplishes this by instead creating an object with a callback property, which the styleManager then uses when stylesheets are rendered by supplying the theme object as a first argument to the callback function.

Classnames/selectors

We have a lot of users who use regular CSS. They expect to be able to inspect their application, copy a className and override styles.

This means a couple of things:

A) Selectors need to be identifiable and ideally have some indication of the component they are from
B) If we change a property value in a rule internally in the library, the selector text needs to remain the same, meaning our appended hash does not represent the styles for the rule.

B is likely very different to how a lot of CSS in JS libraries are handling selectors, but it's fairly central to being able to provide the type of API that material-ui users are expecting.

In order to differentiate selectors there are several mechanisms:

1. "sheets" are created with a name argument (usually the component name, as those should be unique) and warnings are displayed if you render multiple sheets with the same name.

2. Selectors all have a hash appended to them which is a unique identifier for the current theme. This is either a hash of the theme object or a user defined string, (eg: button__root--abc123).

Specificity, passing classes, etc.

This is a big challenge for all CSS in JS libraries. It's also fairly critical to provide decent override mechanisms for users when using CSS in JS inside a library.

A user should be able to just pass their own class and as long as the selector is of the same specificity, it should override it. Users of the library should also be able to leverage the same CSS in JS solution built into material-ui to create their styles without difficulty overriding at the same level specificity.

There are several design decisions in place to help accomodate this without too much mess with something like individual stylesheet priority if you have a huge number of stylesheets (1 per component, for example).

By default, there is only a single <style> element rendered to the DOM when using stylishly, all rendered sheets have their styles appended to the content of that element. This allows us to render the library styles in their own "group" in a style tag which is above the user styles. I also added the ability to pre-place the style tags for your "groups" so you can arrange them however you want in the other items in your <head>. This is a lot simpler than a granular per-sheet priority system, but still provides the ability to override any of the styles coming from the library itself.

This still doesn't solve specificity problems within a single stylesheet element ("group") though, and adding a priority system for individual "sheets" is not something I wanted to do. Instead I've added support for descendant selectors, this allows you to leverage CSS specificity to pass a classname into a nested component and override the styles without worrying about style order. Sure, it won't help if you're trying to override the root node, but it does help with a lot of use cases.

---

I have more to add, but wanted to reply with something to get the discussion going!

[kof]

createStyleSheet and theming

Yes theming for react is a missing part in react-jss, however jss itself is ready, you can do a lot of things with it, for e.g. I am experimenting right now with aphrodisiac

Selectors need to be identifiable and ideally have some indication of the component they are from

Yes, one way is to have component name in every selector, another way is to have component name in a style tag attribute. As we have style tag per component. The last one is a matter of passing meta property when creating sheets. Also when people use react, they can use it's dev tool to identify the component. This has been no problem so far.

If we change a property value in a rule internally in the library, the selector text needs to remain the same, meaning our appended hash does not represent the styles for the rule.

Need more context to understand use cases, don't get it. Are you talking about at-runtime rule style modifications which should not affect the generated selector? If yes it is already this way.

Specificity, passing classes

It needs to be ensured that users style tag or link tag is later on in the dom. This might require a small change in jss but not a big deal. As long jss generated selectors are flat (no nesting), they are easily overwritable.

Being able to choose between using classes or styles objects to theme a component is exactly what I am trying to accomplish by theme-standard which needs a lot of documentation as of now, @rofrischmann works on adding examples and validator library, the last one is needed to ensure the theme passed by user is what component expects and provide meaningful errors.

huge number of stylesheets

For this, theme-standard has subthemes, which allows to nest themes same way we nest components.

This allows us to render the library styles in their own "group" in a style tag which is above the user styles.

This can be achieved with style-per-component approach as well by inserting generated styles one after another and putting the first one before any link/style appearance in the head.

Also one style for everybody can be achieved, see aphrodisiac

pre-place the style tags for your "groups"

You mean the passing style element when creating sheet to the renderer, so that it takes your existing one which is placed to ensure specificity, right? You and me added this to jss some time ago.

CSS specificity

The general rule I can define for sure to avoid this kind of problems is: "Don't use multiple classes on one element, especially if they are from different sources.".

As the library requirements are to provide class based theming as well as style object based. You run into specificity conflicts if

1. Lib's sheets are not ensured rendered before the users sheets.
2. Lib's selectors have a higher specificity than a simple class selector. Which means don't use nesting, important , child or sibling selectors.

I think both points can be achieved.

All in all I haven't seen so far big jss specific problems. It is all around react integration and theming. I think you need to distinguish the rendering part and the component level part.

[kof]

Created this issue for specificity problem.

[alinhle]

I'd be happy to see you both join forces, instead of introducing yet another styling solution. Both projects are just too similar. I'm currently using JSS to style my components and actually I decided to go the opposite way and defined a priority for each stylesheet. So far it went straight forward and wasn't "messy". Let me tell you how I do it, maybe it can give you some inspiration.

All my stylesheets are registered into a theme object and receive an implicit priority according to the order of when they were registered. I use a custom DOM renderer that obeys to the priorities when rendering the stylesheets. This is pretty simple and has so far solved all styling issues I encountered with other css based styling solutions.

I used react-toolbox before which is based on CSS-Modules. They use descendant selectors in their styles which has caused me headaches when trying to customize the style. This and the css specificity problem has lead me to drop the project. I highly discourage the use of descendant selectors, they are difficult to overwrite and causes confusion.

[kof]

@cvle how to you define priorities for your sheets? Any code samples?

[kof]

@cvle lets move priority discussion to a separate issue in jss project, because this thread should be focused. I think I could add something to jss to allow manual priority definition.

[kof]

Regarding descendant, sibling and other kinds of nested selectors: they are all considered harmful. They break components encapsulation. The only way they can be used correctly is defining margins and positions/layouting on a child component, which should not be of concern of the child. But lets not go deeper into this.

[nathanmarks]

@kof

All in all I haven't seen so far big jss specific problems. It is all around react integration and theming. I think you need to distinguish the rendering part and the component level part.

You're 100% correct, although I was having to use it in an unnatural way before to achieve certain goals. jss was by far the best solution that I tried using, which is why I created the prototype with it.

Quick note re the descendant selectors:

I completely agree they should be used sparingly, but I think there are more use cases where the extra specificity can make something work much more easily.

For example, I'm yet to find a better solution for handling use cases where something such as a color needs to be changed to fit in with the background. Let's say you're a user, you create yourself an icon component which has a grey color and you decide to place it on a dark blue toolbar and want to color the icon white instead (or any colour combination for that matter). What would you suggest as the className based solution here? All the obvious methods involve some sort of broken encapsulation because of how CSS is designed.

---

You mean the passing style element when creating sheet to the renderer, so that it takes your existing one which is placed to ensure specificity, right? You and me added this to jss some time ago.

Yes, but that was to target for server side rendering reconciliation with the sheets, it doesn't help keep component styles grouped together when more sheets start getting rendered. Or are you suggesting to use only 1 jss sheet as an implementation detail behind custom react bindings that have the react based theming features material-ui needs? This is also a possibility.

Yes, one way is to have component name in every selector, another way is to have component name in a style tag attribute. As we have style tag per component. The last one is a matter of passing meta property when creating sheets. Also when people use react, they can use it's dev tool to identify the component. This has been no problem so far.

I know that here we are mixing the concerns of components + rendering. But this is exactly what I'm talking about when I say that there are design decisions that are catering towards material-ui users. I'm talking about people writing their own CSS and targeting classes that are generated by the material-ui components.

There is an option here to get rid of these mixed concerns and stipulations about className generation: make material-ui component classNames an implementation detail instead of a public API. @oliviertassinari What are your thoughts on this? I think this is one of the areas that stylishly has made some sacrifices

Need more context to understand use cases, don't get it. Are you talking about at-runtime rule style modifications which should not affect the generated selector? If yes it is already this way.

Nope, was talking about actual changes to the rule in the component file. This ties in directly with what I was saying above about providing an API that is friendly for users that use CSS in a more basic fashion.

It's probably confusing because it isn't the route that makes the most sense outside of this use case. I'm really starting to think that we should completely drop this idea and keep selectors as an implementation detail. For the future I definitely think the group of users that the design decision helps will shrink.

---

Bottom Line

@kof The attempt to make selectors a public API is holding the styling solution material-ui back in some ways and preventing a better separation of concerns between components and rendering. It is an attempt to create a medium-term "bridge" for users who are still doing CSS in a less advanced manner.

If we drop that requirement, it's going to be a lot easier to use jss.

[nathanmarks]

@kof

Do you see the ideal way for material-ui to use jss is as a rendering engine behind some additional features?

[kof]

Let's say you're a user, you create yourself an icon component which has a grey color and you decide to place it on a dark blue toolbar and want to color the icon white instead (or any colour combination for that matter). What would you suggest as the className based solution here?

Icon needs to accept a class name which can overwrite props from the system styles on the proper element. However this gives to user ability to overwrite anything else on that element, so yes this is not ideal and can't be controlled, but will certainly work for the user with some caution.

Yes, but that was to target for server side rendering reconciliation with the sheets, it doesn't help keep component styles grouped together when more sheets start getting rendered. Or are you suggesting to use only 1 jss sheet as an implementation detail behind custom react bindings that have the react based theming features material-ui needs? This is also a possibility.

I would rather make renderer place jss styles one after another in some specified order, so that they are grouped. 1 sheet is also a possible way, however I like the 1:1 component-sheet relation, it is easy to see in the dom the entire sheet for one component.

I'm talking about people writing their own CSS and targeting classes that are generated by the material-ui components.

Oh I didn't realize that. I missed the point that you actually want to provide components with global classes. I thought the way you want to allow use regular css with components is to let user pass class names to components, which are then applied. This would fit also css-modules.

const theme = {
  classes: {
    someElement: '.my-very-special-selector'
  }
}

I don't know if we can convince the material-ui community that global classes are evil. But in any case user doesn't need to access generated classes at all. If you want to provide global classes additionally, you can put them additionally to generated classes on the element. This is even easier to achieve because user doesn't need to pass classnames maps. But this is again ... evil.

<button className={`${generatedClass} myButton`}>My button</button>

Do you see the ideal way for material-ui to use jss is as a rendering engine behind some additional features?

Totally. I think the component integration you have made will be perfectly able to use jss as a rendering engine.

[oliviertassinari]

There is an option here to get rid of these mixed concerns and stipulations about className generation: make material-ui component classNames an implementation detail instead of a public API. @oliviertassinari What are your thoughts on this? I think this is one of the areas that stylishly has made some sacrifices

I pretty much agree with @kof. I can't see why we would need to expose global class names at all.
As long as users can control that their specific class names have a higher priority over the material-ui rules we are fine.

with components is to let user pass class names to components

That would pretty close to how material-ui users override the inline style, thanks to style and nested style properties.

If you want to provide global classes additionally, you can put them additionally to generated classes on the element.

I'm not sure it's the best approach, but yes, that's also something we could do 🙈 .