Merge pull request #15 from ghivert/feat/turn-js-transform-to-gleam

Feat/turn js transform to gleam

Author: ghivert

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": false,
+  "printWidth": 80,
+  "singleQuote": true,
+  "proseWrap": "always"
+}

README.md

@@ -1,22 +1,35 @@
 # 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 is a 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
+all abilities of the JS runtime. It also allows you to build three types of CSS
+classes: dynamic ones, changing over time, static ones, compiled once at each
+render, and memoized 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](https://hexdocs.pm/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.
+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.
+
+Sketch targets both the JS and the BEAM ecosystem. You can use it transparently
+no matter the target you're using. Sketch works in frontend, backend, SSR, SSG,
+with OTP actors or on Node. While sketch tries to be transparent, it does not
+compromise with performances, and tries to leverage on every abilities of the
+different platforms (and uses a custom renderer both for BEAM and JS, to ensures
+sparkling performances in your browser)!
+
+The rest of this README will focus to get you started quickly with a lustre
+example, and some details on the available functions. If you want to know more
+on how sketch is working, how to use lustre with SSR or SSG, heads up to the
+documentation directly! Bonus: if you're using server components, just follow
+this guide, everything will be working directly!
 
 ## Installation
 
@@ -30,18 +43,23 @@ gleam add sketch
 ## Setup
 
 If you're using Lustre (which is strongly recommended), you can just use the
-[`sketch/lustre.setup`](https://hexdocs.pm/sketch/sketch/lustre.html#setup) function
-and [`sketch/lustre.compose`](https://hexdocs.pm/sketch/sketch/lustre.html#compose) function.
-
-Otherwise, you have to follow the lifecycle of Sketch, and use the three low-level
-functions [`create_cache`](https://hexdocs.pm/sketch/sketch.html#create_cache),
-[`prepare`](https://hexdocs.pm/sketch/sketch.html#prepare) and [`render`](https://hexdocs.pm/sketch/sketch.html#render).
-Create the cache with [`create_cache`](https://hexdocs.pm/sketch/sketch.html#create_cache)
-and before every repaint of your frontend, call [`prepare`](https://hexdocs.pm/sketch/sketch.html#prepare).
-After the repaint, synchronously, call [`render`](https://hexdocs.pm/sketch/sketch.html#render),
-and let the magic happen in your browser. Heads up in the docs for more details.
-
-## Example with Lustre
+[`sketch/lustre.setup`](https://hexdocs.pm/sketch/sketch/lustre.html#setup)
+function and
+[`sketch/lustre.compose`](https://hexdocs.pm/sketch/sketch/lustre.html#compose)
+function.
+
+Otherwise, you have to follow the lifecycle of Sketch, and use the three
+low-level functions
+[`create_cache`](https://hexdocs.pm/sketch/sketch.html#create_cache),
+[`prepare`](https://hexdocs.pm/sketch/sketch.html#prepare) and
+[`render`](https://hexdocs.pm/sketch/sketch.html#render). Create the cache with
+[`create_cache`](https://hexdocs.pm/sketch/sketch.html#create_cache) and before
+every repaint of your application, call
+[`prepare`](https://hexdocs.pm/sketch/sketch.html#prepare). After the repaint,
+synchronously, call [`render`](https://hexdocs.pm/sketch/sketch.html#render),
+and let the magic happen. Heads up in the docs for more details.
+
+## Example with Lustre — Frontend
 
 ```gleam
 import gleam/int
@@ -126,11 +144,13 @@ fn view(model: Model) {
 
 ## Compiling static classes
 
-Sketch exposes a single function [`class`](https://hexdocs.pm/sketch/sketch.html#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.
+Sketch exposes a single function
+[`class`](https://hexdocs.pm/sketch/sketch.html#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 `<style>`
+stylesheet. Every time you'll call the function during the render, no
+computation will be done, the class name will be returned, thanks to virtual
+stylesheet.
 
 ```gleam
 import sketch
@@ -146,14 +166,23 @@ fn my_class() -> String {
 
 ## Compiling dynamic classes
 
-Sketch exposes another function [`dynamic`](https://hexdocs.pm/sketch/sketch.html#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.
+Sketch exposes another function
+[`dynamic`](https://hexdocs.pm/sketch/sketch.html#dynamic) allowing you to build
+a dynamic class, changing over time. The first time the function is called, the
+properties in the declaration will be compiled into CSS, and a class with the
+name of the ID will be pushed in the browser. When a class with the same ID is
+found once again during the render, it will be kept, and reused. `dynamic`
+allows you to build different dynamic classes, with different ID. When you're
+generating the ID, if it does not exists in the stylesheet, it will be pushed in
+it, and kept at least till the next render. While a `class` function generates
+_one_ class at every render, a `dynamic` function generates _multiple_ classes
+at every render.
+
+An ID _should be provided_ at the moment, because the runtime is unable to
+distinguish between the dynamic classes, or at a high cost during computations:
+finding the ID of the new class to generate _is_ a hard task by itself. While a
+solution is awaited to be found, be careful to provide a unique id for your
+dynamic class.
 
 ```gleam
 import gleam/bool
@@ -173,11 +202,21 @@ fn my_dynamic_class(is_column: Bool) -> String {
 }
 ```
 
+## Memoizing a class
+
+Sketch exposes a way to memoize a class:
+[`memo`](https://hexdocs.pm/sketch/sketch.html#memo). `memo` allows to keep a
+generated class _for ever_. When called on a class, sketch will preserves the
+class for ever, and will includes the class in every render, as long as the
+virtual stylesheet exists. This allows to skip all computations work for every
+class computations later, and to increase performances render. _Be careful, a
+class marked as `memo` will be then considered immutable and can never change._
+
 ## 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.
+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.
 
 ```gleam
 import sketch
@@ -230,19 +269,22 @@ The example above will be compiled to the following CSS.
 ## Usage with Lustre — Details
 
 [Lustre](https://hexdocs.pm/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 [`setup`](https://hexdocs.pm/sketch/sketch/lustre.html#setup)
-function. This function creates a cache, and returns it. Another function,
-[`compose`](https://hexdocs.pm/sketch/sketch/lustre.html#compose) allows to easily
-compose the cache with the view function of Lustre.
-It acts as a "hook" (lustre does not officially 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()`](https://hexdocs.pm/sketch/sketch.html#to_lustre).
-Just use it in place of [`to_class_name()`](https://hexdocs.pm/sketch/sketch.html#to_class_name)
-to get a Lustre attribute and use it in your views.
+development in Gleam. Sketch tries to simplify as much the development with
+Lustre. That's why Sketch exposes a
+[`setup`](https://hexdocs.pm/sketch/sketch/lustre.html#setup) function. This
+function creates a cache, and returns it. Another function,
+[`compose`](https://hexdocs.pm/sketch/sketch/lustre.html#compose) allows to
+easily compose the cache with the view function of Lustre. It acts as a "hook"
+(lustre does not officially 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()`](https://hexdocs.pm/sketch/sketch.html#to_lustre). Just use it in
+place of
+[`to_class_name()`](https://hexdocs.pm/sketch/sketch.html#to_class_name) to get
+a Lustre attribute and use it in your views.
 
 ```gleam
 import gleam/list
@@ -275,22 +317,23 @@ fn my_other_view(model: Bool) {
 ## Use with Shadow DOM
 
 Sketch can work with a Shadow DOM, in order to hide the compiled styles from the
-rest of the application. To do it, you can use [`plinth`](https://github.com/CrowdHailer/plinth).
-This allows to create a `ShadowRoot`, to use
+rest of the application. To do it, you can use
+[`plinth`](https://github.com/CrowdHailer/plinth). This allows to create a
+`ShadowRoot`, to use
 [`sketch/options.shadow_root()`](https://hexdocs.pm/sketch/sketch/options.html#shadow_root).
-In the same way you can initialize the cache to render in document or in a `style` node,
-you can now use a Shadow Root to paint styles in your application!
+In the same way you can initialize the cache to render in document or in a
+`style` node, you can now use a Shadow Root to paint styles in your application!
 
 ## 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()`](https://hexdocs.pm/sketch/sketch.html#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!](https://github.com/ghivert/sketch)
+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()`](https://hexdocs.pm/sketch/sketch.html#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!](https://github.com/ghivert/sketch)