CSS Modules

Start by reading the vdom_to_etree and etree_to_vdom utilities mentioned in the issue, then review the linked React CSS Modules examples and previous issue #671. Compare the proposed parser, selector, scoping, caching, and stylesheet-serving options. Done means an agreed interface and implementation plan exists; the issue currently leaves those design choices unresolved.

Current Situation

Currently, there is no way to tie CSS to an individual component, such as React CSS Modules

Here's some samples on how this works in React

• https://css-tricks.com/different-ways-to-write-css-in-react/#aa-use-css-modules
• https://css-tricks.com/css-modules-part-1-need/

See previous issue #671

Proposed Actions

This should be possible by

1. Parse a CSS file into selectors and style pairs such as {'#my-selector': { ... } }. We can do this via...
   • Writing a python-based CSS parser
   • tinycss2
   • cssutils
   • cssjson
2. Parsing the component's VDOM into an LXML node tree using our vdom_to_etree util function
3. Determining where to apply styles via cssslect
4. Convert the etree back into VDOM using etree_to_vdom.

Note: With the interfaces below, we might want to implement a cache_handler = ... parameter to allow for customization on how we store stylesheet in cache.

Inline Style Interface

The user interface may look something like this

@component
@css_module("/path/to/stylesheet.css") # Allow for string paths or a file handle
def my_component( ... ):
   return html.div({"className": "styles.my_selector"}, ... )

However, this kind of interface does not retain the same kind of dot notation that React CSS Modules support. If going with this implementation, we would be forced to apply all styling using in-line styles.

In-line styles are not necessarily an issue, but would severely increase size DOM in situations where one selector can apply to 100+ elements.

CSS Modules Imitation Interface

To more accurately imitate React, we might want to consider this interface instead.

styles = css_module("/path/to/stylesheet.css")  # Allow for string paths or a file handle

@component
@styles  # Makes the CSS module aware of how to uniquely scope class names (see `hash` below)
def my_component( ... ):
   return html.div({"className": styles.my_selector }, ... )

The appended stylesheet will have its selectors converted to be unique {filename}_{classname}_{hash}, and all values referenced by the dot notation (eg styles.my_selector) will use these unique selectors. The hash value should be based on the component's dotted path.

In this example, the uniquely generated selector may look something like styles_my_selector_309571057.

What to do with the stylesheet?

Generally, React CSS modules are precompiled (webpack-esque) and stored in some output directory, then it is left up the the webserver to serve them.

Since we currently have no way of pre-compiling CSS modules, we have a few options

1. Serve the file's contents as a string within a html.style tag
   • This is the simplest solution, but would lead to duplicated style rules for each time the component is rendered on the page
2. Force the user to display a component that renders all CSS modules in one stylesheet
   • Would require creating a load/unload framework for CSS Modules
3. Force the user to display a component that renders one CSS module in a stylesheet
   • Gives the user more control over rending behavior
4. Create a Python view that is effectively a primitive static file server
   • This could prove useful for future JavaScript module capabilities
5. Compile CSS on-the-fly into an output directory and have the user serve this files themselves
   • Is less convenient than the methods above
   • Would not have compatibility with whitenoise