A proc macro for creating compile-time checked CSS class sets, in the style of classNames

Nathan West

Last update: Oct 20, 2022

Related tags

Utilities semester

Overview

semester

Semester is a declarative CSS conditional class name joiner, in the style of React's classnames. It's intended for use in web frameworks (like Yew) and HTML template engines (like horrorshow) as an efficient and compile-time checked way to conditionally activate or deactivate CSS classes on HTML elements.

Semester provides two similar macros, classes and static_classes, for creating sets of classes. Each one has a slightly different mode of operation, but they both use the same simple syntax and perform the same checks and guarantees:

The macro takes a list of CSS classes as input, and returns an impl Classes:

use semester::{classes, Classes as _};

let classes = classes!(
    "class1",
    "class2",
    "class3"
);

assert_eq!(classes.render(), "class1 class2 class3");

Each class may optionally include a condition:

use semester::{classes, Classes as _};

let classes = classes!(
    "always",
    "yup": 10 == 10,
    "nope": 10 == 15,
);

assert_eq!(classes.render(), "always yup");

semester will render all of the enabled classes in declaration order, separated by a single space. It will do its best to pre-compute parts of the output (for instance, by concatenating all the consecutive unconditional classes), and you can go further and use static_classes, which pre-computes every possible combination of classes at compile time.

Besides render, semester provides several other ways to access the class set, so you can use whichever one makes the most sense for your use case. See the Classes and StaticClasses traits for details. semester is no_std and will generally only allocate on specific methods like render and to_string.

Additionally, semester performs several compile time correctness checks on your classes:

Classes must be made up of ascii printable characters:

// This does not compile
use semester::classes;

classes!("null\0class")

Classes must not have any whitespace:

// This does not compile
use semester::classes;

classes!("class pair")

Classes must not be empty:

// This does not compile
use semester::classes;

classes!("")

Classes should exclude the HTML unsafe characters: < > & ' "

// This does not compile
use semester::classes;

classes!("<injected-class>")

Classes may not duplicate. Note that semester can't detect mutually exclusive conditions, so it prevents duplicates unconditionally.

// This does not compile
use semester::classes;

let x = 10;
classes!(
    "class1": x == 10,
    "class1": x != 10,
);

License: MPL-2.0

Comments

Support for dynamic classes
Currently, the classes macro only accepts string literals with conditions. This is already great (thank you very much for this crate, btw).

In my codebase, however, I regularly have components that are “styled” by using enums with Display implementation, e.g.

enum ComponentSize { Normal, Large, ExtraLarge } impl fmt::Display for Structure { … }

where display would output my CSS framework's class names. The nice thing about this is the encapsulation of concerns and not doing the pattern matching on the enum every time I need the (always same) classes out of it.

There are basically two approaches I have found with semester:

performing matching at the call-site (which is definitely far from ideal because I lose encapsulation and swapping out the CSS framework would result in me having to change all call-sites):

classes!( "size-md": matches!(size, ComponentSize::Normal), "size-lg": matches!(size, ComponentSize::Large), "size-xl": matches!(size, ComponentSize::ExtraLarge), )

not implementing Display but instead having something like

impl ComponentSize { fn to_classes() -> impl Classes { … classes as above … } } // call-site size.to_classes().to_string()

Now the 2nd approach looks like it would be nice. However, usually these classes from components are not used in isolation, i.e. I would love to use something like

classes!( "my-component", "another-class", "highlight": required, size.to_classes() )

which will not work at the moment. For my purposes, it would be irrelevant if I would have size.to_classes() (have something return impl Classes) or if I would put some String or &str there, the only important part would be that it is not required to be a string literal (&'static str).

There is, of course, a workaround, but that gets ugly pretty quickly:

size.to_classes().iter().chain(classes!("my-component", …).iter()).collect()

Hence, would it be possible to add some kind of support for dynamic classes to classes or even a new macro dynamic_classes which lets me use variables instead of literals?
opened by stopbystudent 0