Release construct

ghivert · ghivert · commit 539f3110f85d · 2025-06-04T18:09:13.000+02:00
diff --git a/sketch_lustre/CHANGELOG.md b/sketch_lustre/CHANGELOG.md
@@ -1,3 +1,49 @@
+## v3.1.0 - 2025-06-04
+
+Sketch Lustre adds a new function, `construct`, to let you inject initial
+styling in the stylesheet. Most of the time, so initial style should be
+injected, whether to style `<body>`, add some keyframe, some font-faces, or
+anything else. Before any use of the stylsheet, `construct` allows you to set
+all those things you need!
+
+You can use it to build something like `normalize.css`, but also to build your
+very own stylesheet, tailored to your needs!
+
+An example :
+
+```gleam
+import lustre
+import lustre/element/html
+import sketch
+import sketch/css
+import sketch/css/length.{percent, px}
+import sketch/lustre as sl
+
+pub fn main() {
+  let assert Ok(stylesheet) = setup_sketch_lustre()
+  let view = view(_, stylesheet)
+  lustre.application(init, view, update)
+  |> lustre.start("#root", Nil)
+}
+
+/// Inject default styling in the initial stylesheet.
+fn setup_sketch_lustre() {
+  use stylesheet <- sl.construct
+  stylesheet
+  |> sketch.global(css.global("body", [css.margin(px(0))]))
+  |> sketch.global(css.global("html", [css.height(percent(100))]))
+  // Add any initial style you want here, `sketch.at_rule`, etc.
+}
+
+fn view(model: Model, stylesheet: sketch.StyleSheet) {
+  use <- sl.render(stylesheet, in: [sl.node()])
+  html.div([], [])
+}
+```
+
+In a nutshell : if you need to instanciate a quick and easy stylesheet, use
+`setup()`, if you need to customize your stylesheet, use `construct()`!
+
 ## v3.0.0 - 2025-05-09
 
 Sketch Lustre Experimental is now official, and become the official way to use
diff --git a/sketch_lustre/gleam.toml b/sketch_lustre/gleam.toml
@@ -1,5 +1,5 @@
 name = "sketch_lustre"
-version = "3.0.0"
+version = "3.1.0"
 
 description = "A Sketch runtime package, made to work with Lustre!"
 internal_modules = ["sketch/lustre/internals", "sketch/lustre/internals/*"]
diff --git a/sketch_lustre/src/sketch/lustre.gleam b/sketch_lustre/src/sketch/lustre.gleam
@@ -26,6 +26,9 @@ pub opaque type Container {
 /// In `sketch_lustre`, there's no notion of persistent or ephemeral stylesheets:
 /// all stylesheets will be persisted in the application.
 ///
+/// In case you need to add initial styling directly in your stylesheet, take a
+/// look at [`construct`](#construct).
+///
 /// ```gleam
 /// pub fn main() {
 ///   let assert Ok(stylesheet) = sketch_lustre.setup()
@@ -39,6 +42,34 @@ pub fn setup() -> Result(sketch.StyleSheet, Nil) {
   }
 }
 
+/// Setup the StyleSheet to use across your application, and let you inject
+/// initial styling directly in your stylesheet. If you don't need to add
+/// default styling, you can take a look at [`setup`](#setup).
+///
+/// In `sketch_lustre`, there's no notion of persistent or ephemeral stylesheets:
+/// all stylesheets will be persisted in the application.
+///
+/// ```gleam
+/// pub fn main() {
+///   let assert Ok(stylesheet) =
+///     sketch_lustre.construct(fn (stylesheet) {
+///       stylesheet
+///       |> sketch.global(css.global("html", [...]))
+///       |> sketch.global(css.global("body", [...]))
+///       |> sketch.global(css.global(":root", [...]))
+///     })
+///   // The following code goes there.
+/// }
+/// ```
+pub fn construct(
+  init: fn(sketch.StyleSheet) -> sketch.StyleSheet,
+) -> Result(sketch.StyleSheet, Nil) {
+  case sketch.stylesheet(strategy: sketch.Persistent) {
+    Error(_) -> Error(Nil)
+    Ok(stylesheet) -> global.set_stylesheet(init(stylesheet))
+  }
+}
+
 /// Unref the StyleSheet to let it be garbaged by the runtime. Because stylesheets
 /// are memoized to guarantee performance and usability of Sketch Lustre, they
 /// should be dereferenced to ensure no memory leaks will happen in the application.
