Sketch

Sketch is a small module providing CSS-in-Gleam in its simpler form. Sketch does not try to add complicated API on top of CSS. If you have CSS knowledge, you’ll feel right at home, with all the niceties offered by Sketch, i.e. type-checking of sizes and push-to-browser stylesheets of your classes, as well as SSR support.

Sketch has currently only one run mode: directly in your browser to leverage on all abilities of the JS runtime. It also allows you to build two types of CSS classes: dynamic ones, changing over time, and static ones, compiled once and for all, and reused during the entire lifetime of the application, just like classic CSS stylesheets.

Sketch is thought to interact nicely with Lustre, but can also be used directly in your vanilla Gleam application or in your fully-featured application. This should probably only be considered to create custom framework or to integrate Sketch in your favorite framework, because Sketch has its own lifecycle to render styles. More informations can be found in the docs.

Installation

Sketch is published on Hex. Add it to your project by using the gleam CLI.

gleam add sketch

Setup

If you’re using Lustre (which is strongly recommended), you can just use the lustre_setup function.

Otherwise, you have to follow the lifecycle of Sketch, and use the three low-level functions create_cache, prepare and render. Create the cache with create_cache and before every repaint of your frontend, call prepare. After the repaint, synchronously, call render, and let the magic happen in your browser. Heads up in the docs for more details.

Example with Lustre

import sketch
import sketch/options as sketch_options
import gleam/int
import lustre
import lustre/element.{text}
import lustre/element/html.{div, button, p}
import lustre/event.{on_click}

pub fn main() {
 let assert Ok(render) = sketch.setup(sketch_options.browser())
 let app = lustre.simple(init, update, render(view))
 let assert Ok(_) = lustre.start(app, "#app", Nil)
 Nil
}

fn init(_flags) {
 0
}

type Msg {
 Incr
 Decr
}

fn update(model, msg) {
 case msg {
   Incr -> model + 1
   Decr -> model - 1
 }
}

fn main_class() {
 sketch.class([
   sketch.background("red"),
   sketch.display("flex"),
   sketch.flex_direction("row"),
   sketch.gap(px(12)),
   sketch.padding(px(12)),
   sketch.hover([sketch.background("yellow")]),
   sketch.media(media.max_width(px(450)), [
     sketch.background("purple"),
     sketch.hover([sketch.background("white")]),
   ]),
 ])
 |> sketch.to_lustre()
}

fn color_class(model: Model) {
 let back = case model % 3 {
   0 -> "blue"
   _ -> "green"
 }
 let id = "color-" <> back
 sketch.dynamic(id, [sketch.background(back)])
 |> sketch.to_lustre()
}

fn view(model) {
 let count = int.to_string(model)

 div([main_class()], [
   button([on_click(Incr)], [text(" + ")]),
   p([color_class()], [text(count)]),
   button([on_click(Decr)], [text(" - ")])
 ])
}

Compiling static classes

Sketch exposes a single function class allowing you to build your class. The first time your function is called, the corresponding styles will be compiled into CSS rules, and pushed in your browser or your SSR stylesheet. Every time you’ll call the function in the future, no computation will be done, the class name will be returned, thanks to memoization.

import sketch

fn my_class() -> String {
 sketch.class([
   sketch.display("flex"),
   sketch.flex_direction("column"),
 ])
 |> sketch.to_class_name()
}

Compiling dynamic classes

Sketch exposes another function dynamic allowing you to build a dynamic class, changing over time. Each time the function is called, the properties in the declaration will be compiled into CSS, the previous class will be wiped from the browser, and the new one will pushed.

An ID should be provided at the moment, due to a limitation of the runtime, and the limitations of the compilation. Until a workaround is found, be careful to provide a unique id for your dynamic class, to avoid overlap with other classes.

import gleam/bool
import sketch

fn my_dynamic_class(is_column: Bool) -> String {
 // id is unfortunately required at the moment.
 let id = "column-" <> bool.to_string(is_column)
 sketch.dynamic(id, [
   sketch.display("flex"),
   case is_column {
     True -> sketch.flex_direction("column")
     False -> sketch.flex_direction("row")
   }
 ])
 |> sketch.to_class_name()
}

Using media queries and pseudo-selectors

Because we’re in CSS-in-Gleam, we can leverage on the full CSS power, contrarily to inline styling. This mean we can use media queries and pseudo-selectors! You only need to call the proper functions, and sketch will take care of the rest.

import sketch
import sketch/media
import sketch/size.{px}

fn my_class() {
 sketch.class([
   sketch.display("flex"),
   sketch.flex_direction("row"),
   sketch.background("red"),
   sketch.hover([
     sketch.background("blue"),
   ]),
   sketch.media(media.max_width(px(320)), [
     sketch.flex_direction("column"),
     sketch.hover([
       sketch.background("green"),
     ]),
   ]),
 ])
 |> sketch.to_lustre()
}

The example above will be compiled to the following CSS.

.css-001 {
 display: flex;
 flex-direction: row;
 background: red;
}

.css-001:hover {
 background: blue;
}

@media (max-width: 320px) {
 .css-001 {
   flex-direction: column;
 }

 .css-001:hover {
   background: green;
 }
}

Usage with Lustre — Details

Lustre is the recommended framework for frontend development in Gleam. Sketch tries to simplify as much the development with Lustre. That’s why Sketch exposes a lustre_setup function. This function creates a cache, and returns a middleware for the view function. It comes as a “hook” (lustre does not offcially supports hooks right now): it setups the cache before the view, and render the stylesheet after the view has executed. It tries to be side-effect free in the view in order to have a predictable render in Lustre, and stick with the Elm architecture mindset.

Once setuped, you can use classes in your Lustre views: to_lustre(). Just use it in place of to_class_name() to get a Lustre attribute and use it in your views.

import sketch
import lustre/element/html

// With a pipeline.
fn my_view() {
 [sketch.background("red")]
 |> sketch.class()
 |> sketch.to_lustre()
 |> list.repeat(1)
 |> html.div(_, [])
}

// With a dynamic class.
fn my_other_view(model: Bool) {
 let color = case model {
   True -> "red"
   False -> "blue"
 }
 html.div(
   [sketch.to_lustre(sketch.dynamic([sketch.background(color)]))],
   [],
 )
}

Some opinions on properties

A lot of properties are accessible directly through the sketch package. But with time, some could be added, and new features for existing features can appear. That’s why sketch will never try to be on your way: at any time you can access property(), which allows you to push any arbitrary property in a class. Another thing is ç that sketch will always let you access raw, low-level properties. If you’re trying to use something like sketch.width("auto") and the property does not support String, look for a variant with an underscore (_), it should fullfill your needs, like sketch.width_("auto")! In case something is missing or a property does not have its underscore alternative, open an issue — or better, a PR — on the repo!