varabyte/kobweb v0.11.11

on GitHub

The biggest change in v0.11.11 is support for CSS variables. See its section in the README for more details.

Frontend

• Fixed an issue where really long titles in the kobweb.conf file would cause a compile error (due to how the main.kt file was getting generated in that case)

Silk

• CSSVariables are now supported using the new StyleVariable class.
• Introduced a new common SmoothColorStyle as a safer way to get smoother color transitions when you change your site's color mode (see below for more info).
• (Potentially backwards incompatible) You now override SilkPalette settings in place (see below for more info).
• Added additional versions for specifying extra modifiers when creating ComponentStyle and ComponentVariant instances, where you can pass in a lambda to produce some modifier lazily.
  • The lambda is marked @Composable, so you can call composable methods in there if you need to, which is useful for example since Silk color aware methods are composable.
• Fixed a bug with the box shadow API where if you only specified the spreadRadius, it actually set the blurRadius.
  • If you notice any of your box shadows acting strangely after updating, make sure you don't have a call that looks like boxShadow(spreadRadius = 10.px, color = ...).
  • If you do, change it to boxShadow(blurRadius = 10.px, color = ...).
  • If you're on an older version of Kobweb and can't upgrade but want to set spread radius intentionally, use boxShadow(blurRadius = 0.px, spreadRadius = 10.px)

Applying SmoothColorStyle

Background (feel free to skip)

I tried to be smart with Surface, really, I did!

First, I made its background color change smoothly when the site's color mode changed (which looks better than snapping colors). That worked except children elements which set their own background colors would ruin the illusion by popping when the rest of the site animated smoothly.

So, next, I tried to make surface force all of its children to also transition their background colors. This seemed to work at first, but it prevented users from defining their own transition on their own elements, as the surface transition would take precedence. Instead of additive behavior, the surface transition would replace the user transition.

As a compromise, instead of applying this style automatically, I let people opt-in with a variant. However, even with that approach, I kept running into cases in my own code where too often I would try to create some cool transition only to shake my fist at the fact that the surface once again took precedence. The variant enabled a cool effect but it was a landmine that would explode in your face eventually.

So, at last, I've given up. No more attempts at inheriting transitions. Instead, opt-in as you need to. It actually doesn't take a lot of work for it to feel pretty good.

How to migrate your code

////// Before

Surface(variant = AnimatedColorSurfaceVariant) { ... }

////// After

// Step 1 [REQUIRED]
// Use `SmoothColorStyle` wherever you declare your root surface
Surface(SmoothColorStyle.toModifier()) {
   ...
   SiteHeader()
}

// Step 2: [OPTIONAL]
// Any children you declare which further modify their background color may want
// to add SmoothColorStyle as well.
// One way to do this is via `extraModifiers` when defining a `ComponentStyle`
val SiteHeaderStyle by ComponentStyle(extraModifiers = { SmoothColorStyle.toModifier() }) {
   base {
       Modifier
           .backgroundColor(SiteAccents[colorMode])
           .otherStuff(...)
   }
}

@Composable
private fun SiteHeader() {
   Box(SiteHeaderStyle.toModifier()) { ... }

   // This would also work, if you prefer it over using `extraModifiers`:
   // Box(listOf(SmoothColorStyle, SiteHeaderStyle).toModifier()) { ... }
}

Overriding the SilkPalette

Before, Silk Palettes were data objects, and you would modify the default Silk theme by doing some crazy copying. Now, the InitSilk function gives you access to a mutable structure which will be frozen after init time.

////// Before

@InitSilk
fun initSilk(ctx: InitSilkContext) {
   ctx.theme.palettes = SilkPalettes(
       light = ctx.theme.palettes.light.copy(
          background = themeBright,
          color = themeDark,
          button = ctx.theme.palettes.button.copy(hover = Colors.DarkPink)
        ),
       dark = ctx.theme.palettes.dark.copy(
           background = themeDark,
           color = themeBright,
           button = ctx.theme.palettes.button.copy(hover = Colors.Pink)
        )
    )
}

////// After

@InitSilk
fun initSilk(ctx: InitSilkContext) {
   ctx.theme.palettes.apply {
       light.background = themeBright
       light.color = themeDark
       light.button.hover = Colors.DarkPink
       dark.background = themeDark
       dark.color = themeBright
       dark.button.hover = Colors.Pink
   }
}

////// After (option 2)

// If you liked the way things were before (as it forced you to specify everything without missing anything),
// you can still do that too. Just add "Mutable":

@InitSilk
fun initSilk(ctx: InitSilkContext) {
   ctx.theme.palettes = MutableSilkPalettes(
       light = ctx.theme.palettes.light.copy(
          background = themeBright,
          color = themeDark,
          button = ctx.theme.palettes.button.copy(hover = Colors.DarkPink)
        ),
       dark = ctx.theme.palettes.dark.copy(
           background = themeDark,
           color = themeBright,
           button = ctx.theme.palettes.button.copy(hover = Colors.Pink)
        )
    )
}