Kobweb Files

This release introduces layouts, which let you annotate your layout methods explicilty and let Kobweb call them for you.

[!WARNING] Layouts required me to make a change to a default that may visually impact your site. Unfortunately, there was no easy way to detect the case. You should double check your site before deploying with this new version. If you see your layout collapse vertically on short pages, please read the notes section for an easy way to fix it.

This release also updates kotlin to v2.1.21 and compose to v1.8.0

:::toml
[versions]
kobweb = "0.22.0"
compose = "1.8.0"
kotlin = "2.1.21"

[!IMPORTANT] Planning to upgrade? Review instructions in the README.

As an extremely quick intro to layouts, if you have code in your project that looks like this:

:::kotlin
@Composable
fun PageLayout(content: @Composable () -> Unit) {
   // Layout stuff
   content()
}

@Page
@Composable
fun ExamplePage() {
   PageLayout {
      /*...*/
   }
}

you can apply the @Layout annotation to the layout method (to declare it as a layout) and to the page method (to declare it as using a layout):

:::kotlin
@Composable
@Layout
fun PageLayout(content: @Composable () -> Unit) {
   // Layout stuff
   content()
}

@Page
@Layout(".components.layouts.PageLayout")
@Composable
fun ExamplePage() {
   /*...*/
}

There is much more purpose to this feature than just removing a bit of indentation (although removing indentation is always nice). In short, you can now set up your site in a way that stateful UI in your layout composables now survive across page navigations without needing to use local storage tricks. Visit https://kobweb.varabyte.com/docs/concepts/foundation/layouts for the full rundown.

You can always continue to use the legacy way of handling layouts, that won't go away, but all relevant templates have been ported over to serve as example code.

Changes

Frontend

• Layouts!
• New modifiers for several CSS properties (thanks sandeepjak2007!)
• all
• backface-visibility
• break-before, break-after, break-inside
• column-count, column-fill, column-span
• contain, contain-intrinsic-block-size, contain-intrisic-inline-size
• ruby-position, word-spacing
• will-change
• widows
• Fixed svg attrs blocks no longer autocompleting attributes
• (This broke with K2 mode! We have reported the issue but migrated code over to a way that is no longer affected by the bug)
• Fixed a bug with RawHtml not working with raw SVG tags.

Backend

• Fixed an issue where the Kobweb server wouldn't return html content in some cases when it should have.
• This wouldn't hit anyone when visiting a website served by a Kobweb server, but it could happen if you used tools like curl or wget to query it manually.

Notes

Fixing collapsing heights

[!IMPORTANT] If after upgrading to 0.22.0, you notice your vertical layouts are suddenly collapsing, which will often look like your footer not sticking to the bottom of the screen, read on!

Let's start with the fix, as it is easy. Check your AppEntry.kt file, and look for code setting minHeight like this:

:::kotlin
Surface(SmoothColorStyle.toModifier().minHeight(100.vh)) {
   content()
}

We recommend two possible approaches -- a one-liner for people who just want to move on with their lives, and a slightly longer but possibly more intuitive fix.

One-liner: Create a Box child and move the minHeight modifier onto it.

:::diff
+Surface(SmoothColorStyle.toModifier()) {
+  Box(Modifier.minHeight(100.vh)) {
      content()
   }
}

Set html / body heights explicitly

:::diff
+@InitSilk
+fun initStyles(ctx: InitSilkContext) {
+    ctx.stylesheet.registerStyleBase("html, body") { Modifier.fillMaxHeight() }
+}

@App
@Composable
fun AppEntry(content: @Composable () -> Unit) {
    SilkApp {
+      Surface(SmoothColorStyle.toModifier().fillMaxHeight()) {
            content()
        }
    }
}

Next, we'll discuss the background for anyone interested.

Silk provides the Surface widget. This is fundamentally a <div> plus a little bit of logic that makes it aware of the current Silk color mode (light or dark), which influences the text and background color of the surface itself and all of its children.

Previously, I implemented it internally using a Box, which is a <div> that uses a grid layout to enforce a stack-like layout behavior.

However, for reasons that are hard to describe here, layouts helped me see this was a bad default. The short version is that opting a <div> into a grid layout has some implications for both how it interprets width and height calculations, but also how it flows its children content. The purpose of using a Surface is simply to opt into color mode functionality, NOT choose a non-standard layout flow.

Moving Surface away from using Box suddenly changes how HTML handles height calculations. Standard divs take their height cues from explicitly set heights, so that's why in our second code example above we set the html and body heights.

Unfortunately, many Kobweb templates were built around surfaces being boxes, so there's a good chance that your own site, if built from them, may experience collapsing heights for short pages starting in 0.22.0.

Thanks!

In this release, @sandeepjak2007 joined us and started helping us out by adding more CSS APIs. Their effort caused us to reevaluate our current approach, which we have since migrated to a way that is easier to contribute to. We have also added full test coverage over the CSS APIs, which helped us clean up a few inconsistencies.

---

Full Changelog: https://github.com/varabyte/kobweb/compare/v0.21.1...v0.22.0