Merge branch 'feat/4.0.0'

Author: ghivert

sketch/CHANGELOG.md

@@ -1,7 +1,7 @@
-## v4.0.0 - Unreleased
+## v4.0.0 - 2024-01-12
 
 v4.0.0 marks a major release for Sketch! It bundles new improvements, new
-features, and improve namespacing! Six months after the initial release of v3,
+features, and improved namespacing! Six months after the initial release of v3,
 v4 marks a new milestone as Sketch gains in maturity, usability and usage. More
 and more people are using it, and as such, Sketch has to evolve in the right
 path!

sketch/README.md

@@ -65,6 +65,12 @@ abstraction allows a greater flexibility, without adding too much burden, as
 they're still all generated at runtime. Sketch favour explicitness and CSS
 generation for every node instead of relying on cascading and inheritance.
 
+## Examples
+
+Want to see examples to jump directly on subject? Take a look at
+[e2e folder on GitHub](https://github.com/ghivert/sketch/tree/main/e2e) to see
+how it works!
+
 ## Sketch Lustre
 
 ### Setup
@@ -119,7 +125,7 @@ simple node, without any class linked on it.
 
 ```gleam
 import sketch/css
-import sketch/csssize.{px}
+import sketch/css/length.{px}
 import sketch/lustre/element
 import sketch/lustre/element/html
 
@@ -209,7 +215,7 @@ time.
 ```gleam
 import redraw/html as h
 import sketch/css
-import sketch/css/size.{px}
+import sketch/css/length.{px}
 import sketch/redraw/html
 
 fn main_style() {
@@ -384,8 +390,8 @@ to call the proper functions, and Sketch will take care of the rest.
 
 ```gleam
 import sketch/css
+import sketch/css/length.{px}
 import sketch/css/media
-import sketch/css/size.{px}
 
 fn my_class() {
   css.class([

sketch/gleam.toml

@@ -18,7 +18,7 @@ path = "sketch"
 [dependencies]
 gleam_erlang = ">= 0.25.0 and < 1.0.0"
 gleam_otp = ">= 0.10.0 and < 1.0.0"
-gleam_stdlib = ">= 0.34.0 and < 1.0.0"
+gleam_stdlib = ">= 0.42.0 and < 1.0.0"
 
 [dev-dependencies]
 birdie = ">= 1.2.5 and < 2.0.0"

sketch/manifest.toml

@@ -35,5 +35,5 @@ packages = [
 birdie = { version = ">= 1.2.5 and < 2.0.0" }
 gleam_erlang = { version = ">= 0.25.0 and < 1.0.0" }
 gleam_otp = { version = ">= 0.10.0 and < 1.0.0" }
-gleam_stdlib = { version = ">= 0.34.0 and < 1.0.0" }
+gleam_stdlib = { version = ">= 0.42.0 and < 1.0.0" }
 startest = { version = ">= 0.6.0 and < 1.0.0" }

sketch/src/sketch.gleam

@@ -30,7 +30,7 @@ pub fn render(cache: StyleSheet) -> String {
 }
 
 @target(javascript)
-/// Convert a `Class` to its class name, to use it anywhere in your application.
+/// Converts a `Class` to its class name, to use it anywhere in your application.
 /// It always returns the StyleSheet, because the class can have been pushed
 /// in the StyleSheet itself.
 pub fn class_name(class: Class, stylesheet: StyleSheet) -> #(StyleSheet, String) {
@@ -45,6 +45,8 @@ pub fn class_name(class: Class, stylesheet: StyleSheet) -> #(StyleSheet, String)
 }
 
 @target(javascript)
+/// Pushes an `@rule` in the StyleSheet, to get it bundled in the outputted CSS.
+/// It returns the StyleSheet with the rule added.
 pub fn at_rule(rule: AtRule, stylesheet: StyleSheet) -> StyleSheet {
   let cache = cache.at_rule(rule, stylesheet.cache)
   StyleSheet(..stylesheet, cache:)

sketch/src/sketch/css.gleam

@@ -23,7 +23,7 @@ pub type Style =
 pub type Class =
   style.Class
 
-/// Represents an at-rule.
+/// Represents an [at-rule](https://developer.mozilla.org/docs/Web/CSS/At-rule).
 pub type AtRule =
   style.AtRule
 
@@ -137,15 +137,15 @@ pub fn all(value: String) -> Style {
 /// ---
 ///
 /// This property is a shorthand for the following CSS properties:
-/// [`animation-delay`](https://developer.mozilla.org/docs/Web/CSS/animation-delay)
-/// [`animation-direction`](https://developer.mozilla.org/docs/Web/CSS/animation-direction)
-/// [`animation-duration`](https://developer.mozilla.org/docs/Web/CSS/animation-duration)
-/// [`animation-fill-mode`](https://developer.mozilla.org/docs/Web/CSS/animation-fill-mode)
-/// [`animation-iteration-count`](https://developer.mozilla.org/docs/Web/CSS/animation-iteration-count)
-/// [`animation-name`](https://developer.mozilla.org/docs/Web/CSS/animation-name)
-/// [`animation-play-state`](https://developer.mozilla.org/docs/Web/CSS/animation-play-state)
-/// [`animation-timeline`](https://developer.mozilla.org/docs/Web/CSS/animation-timeline)
-/// [`animation-timing-function`](https://developer.mozilla.org/docs/Web/CSS/animation-timing-function)
+/// - [`animation-delay`](https://developer.mozilla.org/docs/Web/CSS/animation-delay)
+/// - [`animation-direction`](https://developer.mozilla.org/docs/Web/CSS/animation-direction)
+/// - [`animation-duration`](https://developer.mozilla.org/docs/Web/CSS/animation-duration)
+/// - [`animation-fill-mode`](https://developer.mozilla.org/docs/Web/CSS/animation-fill-mode)
+/// - [`animation-iteration-count`](https://developer.mozilla.org/docs/Web/CSS/animation-iteration-count)
+/// - [`animation-name`](https://developer.mozilla.org/docs/Web/CSS/animation-name)
+/// - [`animation-play-state`](https://developer.mozilla.org/docs/Web/CSS/animation-play-state)
+/// - [`animation-timeline`](https://developer.mozilla.org/docs/Web/CSS/animation-timeline)
+/// - [`animation-timing-function`](https://developer.mozilla.org/docs/Web/CSS/animation-timing-function)
 ///
 /// ---
 ///

sketch/src/sketch/css/font_face.gleam

@@ -1,3 +1,11 @@
+//// The `@font-face` CSS at-rule specifies a custom font with which to display
+//// text; the font can be loaded from either a remote server or a
+//// locally-installed font on the user's own computer.
+////
+//// ---
+////
+//// [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/@font-face)
+
 import gleam/float
 
 /// A `FontFace` is a part of a `@font-face` rule.

sketch/src/sketch/css/keyframe.gleam

@@ -1,3 +1,13 @@
+//// The `@keyframes` CSS [at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule)
+//// controls the intermediate steps in a CSS  animation sequence by defining
+//// styles for keyframes (or waypoints) along the animation sequence. This
+//// gives more control over the intermediate steps of the animation sequence
+//// than [transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_transitions).
+////
+//// ---
+////
+//// [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/@keyframes)
+
 import gleam/int
 import sketch/internals/cache/cache as style
 

sketch_css/README.md

@@ -8,10 +8,10 @@
 Sketch CSS is a tool to generate CSS from Sketch Class definitions. Because pure
 CSS generation is straightforward, `sketch_css` does not need a cache to
 generate correct CSS files. Instead, `sketch_css` ships with a CLI tool, able to
-read your Gleam styles files, and output corresponding your CSS automagically,
-while providing an abstraction layer written in Gleam, to make sure you're using
-the right classes! It's an other way to leverage Sketch core and enjoy the
-styling in Gleam, while taking advantage of all the static CSS power!
+read your Gleam styles files, and output corresponding CSS automagically, while
+providing an abstraction layer written in Gleam, to make sure you're using the
+right classes! It's an other way to leverage Sketch core and enjoy the styling
+in Gleam, while taking advantage of all the static CSS power!
 
 To run the generator, you have to use the command
 `gleam run -m sketch/css generate` at the root of your project. By default,
@@ -25,16 +25,59 @@ in `src/sketch/styles`, matching your styles files, to use in your project!
 
 ### Options
 
-Sketch CSS generation has strong defaults, but everything can be customised. Use
-the CLI flags to configure what you need. CLI exposes 3 flags:
+Sketch CSS generation has strong defaults, but everything can be customised. To
+pass options to Sketch CSS, you have three ways:
+
+- Pass them directly on the CLI. Every option has its equivalent exposed in the
+  CLI.
+- Write them in a `sketch_css.toml` file, at root of your project, next
+  `gleam.toml`.
+- Write them directly in `gleam.toml`, under `[sketch_css]` section.
+
+Sketch CSS has 3 distinct options:
 
 - `--dest`, accepting a folder, relative to current directory. It defaults to
-  `styles`
+  `styles`.
 - `--src`, accepting a folder, relative to current directory. It defaults to
   `src`.
 - `--interface`, accepting a folder, relative to current directory. It defaults
   to `src/sketch/styles`.
 
+Write directly the folder, path resolution is done with current working
+directory as root.
+
+#### Examples
+
+```sh
+gleam run -m sketch_css generate --src="src" --dest="styles" --interface="src/sketch/styles"
+```
+
+```toml
+# sketch_css.toml
+src = "src"
+dest = "styles"
+interface = "src/sketch/styles"
+```
+
+```toml
+# gleam.toml
+name = "name"
+version = "1.0.0"
+
+[sketch_css]
+src = "src"
+dst = "styles"
+interface = "src/sketch/styles"
+
+[dependencies]
+gleam_stdlib = ">= 0.34.0 and < 2.0.0"
+sketch = ">= 4.0.0 and < 5.0.0"
+sketch_css = ">= 2.0.0 and < 3.0.0"
+
+[dev-dependencies]
+gleeunit = ">= 1.0.0 and < 2.0.0"
+```
+
 ### A note on generation algorithm
 
 Because a Sketch `Class` can be generated in multiple ways, and with variable,
@@ -44,43 +87,49 @@ generated with the variable taken into account! Sketch CSS being opinionated, it
 generates the class, with a CSS variable, letting you update it, override it,
 etc.
 
-All `_` are also automatically transformed into `-`, because CSS classes are
-most of the time used with dashes, so Sketch CSS follows that convention!
+Sketch CSS also acts as a basic interpreter. It means you can write basic
+constants or variables, and they will be taking into account. Be sure to write
+classes like you would do in CSS yet: Sketch CSS does not execute your
+functions!
 
 ### Example
 
 ```gleam
 // src/main_styles.gleam
-import sketch
+import sketch/css
 
-fn flexer() {
-  sketch.class([
-    sketch.display("flex"),
-  ])
+pub fn flexer() {
+  let display = "flex"
+  css.class([css.display(display)])
+}
+
+fn direction(flex_direction: String) {
+  css.flex_direction(flex_direction)
 }
 
-fn flexer_direction(flex_direction: String) {
-  sketch.class([
-    sketch.compose(flexer()),
-    sketch.flex_direction(flex_direction),
+pub fn flexer_direction(flex_direction: String) {
+  css.class([
+    css.compose(flexer()),
+    direction(flex_direction),
   ])
 }
 ```
 
 ```css
 /* styles/main_styles.css */
-.flexer {
+.main_styles-flexer {
   display: flex;
 }
 
-.flexer-direction {
+.main_styles-flexer_direction {
+  display: flex;
   flex-direction: var(--flex-direction);
 }
 ```
 
 ```gleam
 // src/sketch/styles/main_styles.gleam
-pub const flexer = "flexer"
+pub const flexer = "main_styles-flexer"
 
-pub const flexer_direction = "flexer flexer-direction"
+pub const flexer_direction = "main_styles-flexer_direction"
 ```

sketch_css/gleam.toml

@@ -21,7 +21,7 @@ path = "sketch_css"
 argv = ">= 1.0.2 and < 2.0.0"
 glance = ">= 2.0.0 and < 3.0.0"
 gleam_erlang = ">= 0.25.0 and < 1.0.0"
-gleam_stdlib = ">= 0.34.0 and < 2.0.0"
+gleam_stdlib = ">= 0.42.0 and < 2.0.0"
 glint = ">= 1.2.0 and < 2.0.0"
 simplifile = ">= 2.0.1 and < 3.0.0"
 sketch = {path = "../sketch"}