DEV Community: skalable-dev

Managing Gaps in Rows, Columns (or even both!) with KotlinJS

skalable-dev — Sat, 24 Apr 2021 12:35:02 +0000

At sKalable we are on a mission to make KotlinJS websites mainstream. We strive to make them easy to code, fun to build and, of course, skalable! 😊 😛

We are aware that sometimes when building the design of our website, working with column and row gaps can be initially tricky. Who hasn't struggled with this before? We certainly have...

Let's explore how we can work effectively with gaps in rows and columns to smash our designs!

Mind the Gap

So what actually is the gap property?

The gap property refers to the space between columns and rows by specifying the size of their gutters within flex, multi-columns and grid layouts. We use the gap property to add the required spacing between the items in our website so that they comply with the design and look great! :D

In terms of the syntax it can be confusing to grasp at first. Essentially, Columns have rowGaps and Rows have columnGaps. Each of these takes a Gap value in the form of a size property.

Gaps and Flexbox

When should we use gaps? Usually gaps are used in cells that repeat or to justify items on screen when a particular distance is required between them. In this example project we have used rem to set the sizing of gaps but other sizes such as pct or px work too.

It is worth mentioning that there are three gap variants that we can use with flexbox. Let's explore them in more detail below.

Gap for Rows only

When we want to add spaces to items in a flexDirection column we need to include rowGap as per the example below.

/**
 * Style for rowGap in a flex column
 */
val container by css {
    ...
    display = Display.flex
    flexDirection = FlexDirection.column
    //when flex direction is column we use rowGap as spacing
    rowGap = Gap(YOUR_VALUE.rem.value) // this can be other sizes
    ...
}

As we can see, using a column layout with rowGap applies spacing between the row cells.

Gap for Columns only

Adding spaces to items in a flexDirection row requires rowColumn like in this example.

/**
 * Style for columnGap in a flex row
 */
val container by css {
    ...
    display = Display.flex
    flexDirection = FlexDirection.row
    //when flex direction is row we use columnGap as spacing
    columnGap = Gap(YOUR_VALUE.rem.value) // this can be other sizes
    ...
}

Here we are applying columnGap to a row layout. Modifying the spacing size horizontally between cells.

Gap for both Rows and Columns

What happens when we need both row and column gaps?! Luckily this is built in using just gap as the key...

/**
 * Style for gap in both flexRow and flexColumn
 */
val container by css {
    ...
    display = Display.flex
    flexDirection = FlexDirection.row
    //gap allows for both rows and columns to be sized as one
    gap = Gap(YOUR_VALUE.rem.value) // this can be other sizes
    ...
}

as we can see, both row and column spacing is adjusted in tandem.

What is the Gap Object?!

In KotlinJS and Styled-Components there is a wrapper around how we set the value of the spacing called Gap(value: String) which requires a string value as the parameter.

Because of this we must convert our size by using value which is of type String. This is provided for free thanks to the LinearDimensions class. Ensuring all our conversions are web safe!

Conclusion

Using row and column gaps correctly is incredibly beneficial to keeping CSS clean and will speed up your development process if you can apply them correctly. We hope that this article has helped resolved your confusion around this topic.

Please feel free to post any questions below, and we will be happy to support you :)

You can check out the sample project here.

@sKalable we are Full Stack Kotlin-centric agency that creates code that is always flexible, maintainable and of course, sKalable :D

Twitter

Dev.to

Follow us on for the latest updates and strategies in Kotlin, Multiplatform and much more, catering for your business or personal needs.

Making your KotlinJS Website Mobile-Friendly

skalable-dev — Wed, 07 Apr 2021 11:59:06 +0000

At sKalable we are Kotlin driven, so we are in a mission to make KotlinJS websites mainstream. We are advocates of clean code and strive for the best quality in everything we build!

How many times have you visited a site that is not mobile responsive and thus renders terribly on your device? From my experience, I would say too many times!

Let's explore how we can make our KotlinJS site responsive, so we can delight our users 🙂😛

Making your KotlinJS Website Mobile-Friendly

What is mobile responsiveness?

When a website is responsive, its layout and content automatically adapt to fit and render correctly on the device its being run on. Basically, if the screen gets smaller, then the content and layout rearranges accordingly, ensuring the visuals and functionality are not compromised.

Why is it so important?

Google's recommendation is to adopt a responsive development for our websites. The benefits of doing this are many:

It provides the best quality and user experience as a non-mobile friendly website is very hard to view on devices.
A good website will have better SEO, perform better in rankings and make your brand distill quality!

Users find non-mobile friendly websites frustrating and will certainly abandon your site if it is hard to navigate.

How are we going to achieve this?

We are going to adopt a 'mobile first' approach by using Meta Tags and Media Queries!

Let's get started by building a quick website with a Navigation Bar that changes the layout into a convenient Navigation Drawer depending on the device's dimensions.

Meta Viewport Tag

The ViewPort tag is basically needed to signal browsers that the site adapts to all devices. It provides them with instructions on how to scale and adjust the dimensions to match the screen's size.

The first thing we need to do is to add the Meta Viewport Tag below in your index.html file.

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Media Queries

Media Queries are used to style websites for different sized screens (phones, tablets, desktop). Essentially, by using Media Queries, we can target a specific screen size or pixel range and make changes to the CSS ONLY when the particular screen size that we have set is hit.

So, how do we use them? The syntax of Media Queries for mobile responsiveness looks like this in KotlinJS:

/*Specify the minimum screen width that you want to target in pixels*/
media("only screen and (min-width: 768px)") {
    /*Add the CSS changes you want to display here*/
}

To clarify, the code above will only execute on screens that are 768px or larger.

/*Specify the maximum screen width that you want to target in pixels*/
media("only screen and (max-width: 768px)") {
   /*Add the CSS changes you want to display here*/ 
}

We will adapt our CSS for screen sizes 768px or lower.

Safety in Functions

As we begin to add more and more queries it becomes more and more hardcoded. A misspelling can cause all sorts of havoc in these cases.

Using utility functions to generate these can save us from all types of headaches.

fun mediaOnlyScreenMinWidth(width: LinearDimension) = "only screen and (min-width: ${width})"

fun mediaOnlyScreenMaxWidth(width: LinearDimension) = "only screen and (max-width: ${width})"

Using these functions we can create responsive sizes that will match across our codebase.

Applying the utility functions our code now feels less hardcoded

/*Specify the minimum screen width that you want to target in pixels*/
media(mediaOnlyScreenMinWidth(768.px)) {
    /*Add the CSS changes you want to display here*/
}

As you can see above, we use the (mediaOnlyScreenMaxWidth()) or the
(mediaOnlyScreenMinWidth()) to specify when the changes to the CSS should happen.

Let's explore the code above in more detail with specific examples from our website.

Media in Action

Our top navigation bar includes a logo and three Call to action (CTA) buttons. When the Webpage is rendered on Desktop, we want the navbar to display fully. If the screen size drops below the desired limit, the margin should be removed. To achieve this we use the following code:

  val primaryNav by css {
        marginTop = 5.em

        media(mediaOnlyScreenMinWidth(768.px)) {
            margin(0.px)
        }
    }

Rendering on smaller devices, such as phones and tablets, the navbar should be replaced with a drawer navigation containing the CTAs.

val mobileMenu by css {
        display = Display.block

        media(mediaOnlyScreenMinWidth(768.px)) {
            display = Display.none
            margin(0.px, LinearDimension.auto)
            color = Color.blueViolet
        }
    }

Conclusion

Using media tags in KotlinJS is quite simple. It is definitely worth addressing mobile responsiveness when developing your KotlinJS website. Making it render correctly on a desktop is not enough, especially factoring in that mobile traffic has overtaken desktop and now accounts for the majority of website traffic.

You can check out the sample project here.

Feel free to leave any questions or comments below. We would love hear your thoughts.

@sKalable we are a Full Stack Kotlin-centric agency that create code to ensure it is consistently Maintainable, Flexible and of course, sKalable. 😎

Twitter

Dev.to

for the latest updates and strategies in Kotlin, Multiplatform and much more, catering for your business or personal needs.

KotlinJS and MULTIPLE State Hooks (Part two)

skalable-dev — Mon, 29 Mar 2021 14:38:13 +0000

At sKalable we are just in love with Kotlin! We really strive to make all things Kotlin simple, fun, and a breeze to work with :D <3 KotlinJS is no exception to our mission. 😃 ❤️

Following on from our Part 1 tutorial of KotlinJS and State Hooks , that covers State as a singular, Hooks and the best practices for working with functional components, we want to take things further and delve into using multiple State Hooks or State values in our code. Using multiple State Hooks can be advantageous as you can split them for different uses, better manage properties that change independently of each other... but with certain caveats...

Helping to define the structure and improve the readability of our code so much more!

(Before delving deeper into multiple State Hooks, feel free to take a look at Part 1 of this article as a refresher 😊 )

Let's give it a go!

Multiple States in action

Check out this diagram where we can see multiple states in action!

The problem with Fixed State interfaces

Below is an example looking at some issues of setting an interface object as a useState type value.

/**  
 * EnterWordStateOriginal is used as a State Object * 
 * 
 * @property word is the word that is updated when the input changes.  
 * @property updateClicked is the property that is updated when the button gets clicked.  
 * @property updatedWord the new word that has been updated.  
 */
 external interface EnterWordStateOriginal {  
  var word: String  
  var updateClicked: Int  
  var updatedWord: String  
}

/**  
 * enterWord is a functional component that renders an input, a button and a label. 
 */
private val enterWord = functionalComponent<RProps> {  
/**  
 * When we first declare the useState, the default value is set in the parenthesis. 
 * This will be held in enterWordState. 
 * 
 * To modify this we use the setEnterWord function, delegated with the [by] key. 
 * To clarify enterWord is treated as a var with a getter and a setter. 
 */
var enterWordState by useState<EnterWordStateOriginal> {  
    object : EnterWordStateOriginal {  
        override var word = ""  
        override var updateClicked = 0  
        override var updatedWord = ""  
    }
}

//... functional / render code .

/**
 * Setting a state object requires the full object to be set in functional
 * components. This can become very verbose, incredibly quickly.     
 */  
    //... HTML Input handler 
    onChangeFunction = { event -> 
         enterWordState = object : EnterWordState {  
             override var word = (event.target as HTMLInputElement).value  
             override var updateClicked = enterWordState.updateClicked 
             override var updatedWord = enterWordState.updatedWord
         }  
    }

It might not be the most elegant looking code, but it works. When using state objects in functional components, you'll see there is no requirement to set the RState type on the component itself. This is different to how Class Components work for instance.

Unlike with Class Components, Functional Components do not have a setState {} function to map old state to new state (This is not the case for Props though) . Nor do they require knowledge of the state in their construction either.

We apply the concept of state to a functional component through React Hooks. Using hooks, the component now has the capability to handle state changes. There is a readability issue regarding this though...

Code should be clean, easy to write and read. Unfortunately, using state objects in functional components doesn't help us achieve that with the approach above.

Below, we see that in order to set state we must initialise the full object every time. This requires us to manually set the values of the previous states that don't change.

/** 
 * Setting a state object requires the full object to be set in functional 
 * components. 
 * This can become very verbose, incredibly quickly.     
 */  
 onChangeFunction = { event ->   
     enterWordState = object : EnterWordState {  
         override var word = (event.target as HTMLInputElement).value  
         override var updateClicked = enterWordState.updateClicked 
         override var updatedWord = enterWordState.updatedWord
     }  
 }

Ughhh.... We can't be adding this everywhere each time we update the state. Ok, time to clean this up a little.

Dividing state strategies

There is no real "right" or "wrong" method of tackling division of state, its mostly down to personal preference and use case for each component (although some strategies can look ridiculous such as above).

Larger states have a different challenge than smaller states. Below we outline various strategies and how to decide which is best approach for the components needs and number of states you require.

Dividing by individual values — Multi-State component

For small state interfaces that can be described as having no more than three vars in a State, prefer an individual state for each value.

/**  
 * Primitive State based on a String and an Int. The types are inferred. 
 */
var wordState by useState { props.word } // inferred String 
var updatedClickedState by useState { 0 } // inferred Int

This allows for clean and easy methods to update and read the required state.

updatedClickedState += 1 // update the value by 1

What about larger states? How should we handle those?

Keeping composition / context as a Single State

If you find yourself writing a lot of repetitive code, always think of DRY Principles. We tend do repeat a lot of the state construction just to update a single value when using state as a single object. A separate function within the functional component can help resolve this issue.

Builder functions can be used to create new objects and handle the mapping of values. Kotlin has a feature called default arguments allowing parameter values to have the default value to the corresponding states value. Automatically the parameters will have the value if one has not been provided by the caller.

Applying this approach allows for cleaner code. It does require "boilerplate" in the form of a separate function for each state interface in functional components with interface states.

Though it's a better approach to mapping, it's still not ideal nor efficient when writing components.

/**  
 * When we first declare the useState, the default value is set in the parenthesis. 
 * This will be held in enterWordState. 
 * 
 * To modify this we use the setEnterWord function, delegated with the [by] key.
 * To clarify enterWord is treated as a var with a getter and a setter. 
 */
var enterWordState by useState<EnterWordStateWithBuilder> {  
    object : EnterWordStateWithBuilder {  
        override var word = ""  
        override var updateClicked = 0  
        override var updatedWord = ""  
    }  
}

/**  
 * In this approach we use utility builders within the functional component to set state as a single 
 * line when interfaces are used as state holders.
 * Using default params pointed at [enterWordState] allows for cleaner setters. 
 * 
 * @param word — Has a default of the current state word  
 * @param updateClicked — Has a default of the current state updateClicked  
 * @param updatedWord — Has a default of the current state updatedWord  
 */
fun setWordState(  
    word: String = enterWordState.word,  
    updateClicked: Int = enterWordState.updateClicked,  
    updatedWord: String = enterWordState.updatedWord  
) {  
    enterWordState = object : EnterWordStateWithBuilder {  
        override var word = word  
        override var updateClicked = updateClicked  
        override var updatedWord = updatedWord  
    }  
}

The result of creating a utility builder for the function state is a clean setter.

/**  
 * Setting a state object requires the full object to be set in functional 
 * components. This can become very verbose, incredibly quickly. 
 */  
onChangeFunction = { event -> 
    setWordState(word = (event.target as HTMLInputElement).value)  
}

There must be another option...

As the number of state values grow, they become more and more cumbersome to maintain. If we need to create large builder functions for each State object, our functional components will become more and more polluted.

Utility function to the rescue!

The thought of writing different builders for each state object is daunting. Removing the need for this and providing a clean method of updating state objects without writing builders would be perfect. Even better if it meant changing the component from functional to a class didn't require the interface to change.

To solve this we look at Kotlin itself and the incredible apply function. Using our old state and new state values together provides all the ingredients to create a new object by copying the existing values of the old state and applying the new state values atop.

Let us start by changing the state holder interface slightly.

/**  
 * EnterWordStateOriginal is used as a State Object * 
 *  
 * @property word is the word that is updated when the input changes.  
 * @property updateClicked is the property that is updated when the button gets clicked.  
 * @property updatedWord the new word that has been updated.  
 */
external interface SetStateExampleState: RState {  
    var word: String  
    var updateClicked: Int  
    var updatedWord: String  
}

I know what you're all thinking, "What's RState doing there?!"

There is a genuine reason: earlier we mentioned maintaining cooperation of state if we change the component from functional into a class?

Extending RState achieves this, but also plays a secret second purpose.👇

Functional setState

To prevent any regular interface being used as a state we can extend our state interface from RState. Using this as the type for our setState ensures only state objects can be used. Forcing better readability and cleaner code across our codebase naturally.

no more "What is this badly named interface for?!"

Our new utility function to handle this mapping will now provide us not just the clean setState we want, but the setState we deserve!

/**  
 * By creating a utility function to map the current state with 
 * the updated variables, it removes the need to create multiple 
 * builder functions for larger states across the project. 
 * Using this function we can keep code clean and efficient. 
 * 
 * @see T — The purpose of extending RState is to keep uniformity across the code. 
 *          If we look to change the type of component we can * be guaranteed the state will work for free.
 * 
 * @param oldState — The current state values  
 * @param newState — The new values we would like to apply to the state  
 * 
 * @return T — The values of old state plus the updated values of new state.  
 */
internal inline fun <T : RState> setState(  
    oldState: T,  
    newState: T.() -> Unit  
): T = clone(oldState).apply(newState)

Time to break it down a little:

internal

Prevents the setState function being exposed as part of the overall modules API.

inline

inline optimises functions by inlining the lambda expressions for a reduction in runtime overhead.

<T : RState>

This defines the type of oldState and newState. Extending RState gives us the certainty this will be a state.

oldState: T

The value of the existing state. Kotlin uses "Copy by Value" for function parameters. The oldState param will then be a copy of the state we want to set. (There is some discrepancy in this statement to the values inside, as only the outlining object is copied, but that's for another time.)

newState: T.() -> Unit

For those of you who don't know, this has got to be one of the most amazing features of Kotlin. It's known as a Function literals with receiver. We can set parameters of the receiver T and apply them to our clone.

clone

_Ok, this might not be exactly part of the Kotlin language, but it is part of KotlinJS! It allows us to copy oldState into a new jsObject.

apply(newState)

We want to return the value of the oldState with the updates from newState. Using apply allows for this. apply returns an instance of this so is ideal for returning a new copy after adding newState.

Result

Adding our brand new setState to the functional component we get a clean, readable state management.

enterWordState = setState(enterWordState) {  
    updateClicked += 1  
    updatedWord = word
}

The best part of this approach is autocomplete and no need to define each value to set state. Our generic function infers the type of the state and gives us auto complete within the body of the lambda block while also mapping existing values that haven't changed to the new state.

Awesome right?!

The outcome is a clean state setter within a functional component that can have its interface values extended without requiring refactoring everywhere the state is set.
(As we would with the initial approach)

Closing remarks

Using large sets of values in a state object can be the most efficient way of keeping code clean and maintainable. Especially when dealing with larger state sets within components (such as forms).

As a rule of thumb, with smaller state values individual states can be used. These can lose context of "what they're for" as logic grows.

Object states address this by grouping these values into a single value. Important when improving the clarity of code, also providing a "Context" to what state is.

e.g "formValuesState' would hold the state of fields in a form.

One last tip to help avoid confusion is to make sure you include the actual word State as part of the state variable name, this is especially true with single states. i.e nameState, emailState

To help differentiate we have grouped each approach into separate examples in the project below, so you can get an overall understanding of each approach and its advantages.

Checkout it out here

@sKalable we are a Full Stack Kotlin-centric agency that create code to ensure it is consistently Maintainable, Flexible and of course, sKalable. 😎

We love to hear from the community, so if this helped feel free to get in touch or follow us on

Twitter

Dev.to

to get the latest updates and strategies with Kotlin and Multiplatform for your business or personal needs.

KotlinJS and State Hooks

skalable-dev — Tue, 09 Mar 2021 15:31:00 +0000

At sKalable we are Kotlin Obsessed! Making the environment better is part of our daily mission. We want to make all things KotlinJS amazingly easy to work with too.

As part of our pursuit to clean up code, we will be delving into state management in this two part tutorial. 😎

useState part of React Hooks for state management is something that even Javascript and Typescript engineers struggle with from time to time. We are going to reduce this struggle within the React ecosystem using KotlinJS and the ever incredible Kotlin-React library.

Understanding state

To get an idea of what we are trying to do we need to grasp what state is in react programming.

So lets start!

What is state

The React library provides components with a built-in state management object. In this state object we can store and manipulate the state of the React component on the fly. If the state object changes, then the component will re-render with the updated state and any UI changes will be reflected.

How does it work

Keeping things reactive

We can describe state as being reactive since it stores dynamic data for the component. The state object itself allows the component to keep track of changes and updates to the data and render views accordingly. It works similarly to the Observer Pattern given that it defines a subscription mechanism to notify observers of the data about any events that happen to the payload they are observing.

Moving on we will cover state in both Class and Functional components.

State in Class Components

A Stateful Class component is lifecycle aware and has its state defined in an external interface. They can also initialise state as a class property (which we will cover later in The useState Hook) or in a constructor function — both approaches achieve the same result.

When we first initialise our custom state, it creates a getter and setter for the value of the property we want to have state aware. The getter is named similarly to a property variable in Kotlin (see naming properties in Kotlin) such as count or word, i.e. descriptive of the data it holds.

To update the data in this getter we use the function defined as setState. Inside the Lambda block from this function we have access the variable we want to update.

/**
 * A class component extends from [RComponent]. There is no requirement for
 * an external prop or state. The values of [RProps] and / or [RState]
 * can be provided without the need to declare external interfaces reflecting these.
 */
private class IndentWithDot : RComponent<RProps, IndentState>() {
    /**
     * To initialise the `state` when the class component is created we
     * must override the `RState.init()` function corresponding to the external
     * interface we provided to the component. In our case its `IndentState.init()`
     *
     * @see RComponent<IndentProps, IndentState> — (We're interested in IndentState)
     * @see IndentState
     */
    override fun IndentState.init() {
        indentAmount = 1
        indentationValue = "."
    }

    /**
     * The render function gets called when the component mounts or is updated.
     * Code inside the render function gets rendered when called.
     *
     * In our render function we have a single [button] that updates
     * the [indent] each time its pressed and displays the current update to the user.
     *
     * In order to read the `indentationValue` and `indentAmount` we need to reference the `state` from our class
     * and get the `indent` values from it.
     * @see IndentState
     *
     */
    override fun RBuilder.render() {
        div {
            button {
                // Update the string using the values from state.indentationValue and state.ident
                +"press me to add another dot indent ${state.indentationValue} ${state.indentAmount}"
                attrs {
                    onClickFunction = {
                        setState {
                            /**
                             * Reference the value of the `state.indent` and add 1.
                             * This will become the new value of `indent`.
                             */
                            indentAmount = state.indentAmount + 1
                            indentationValue = ".".repeat(indentAmount)
                        }
                    }
                }
            }
        }
    }
}

/**
 * ReactBuilder function used to construct the React Component IndentWithDot.
 */
fun RBuilder.indentByDots() = child(IndentWithDot::class) {}

Let's see the code in action!

Even though there is nothing wrong with class components, they can be quite verbose and heavyweight so let's compare how this code looks when optimised with the useState hook and Functional Components!

The useState Hook!

Prior to React 16.8, functional components could not hold a state. Luckily, this is no longer the case as we can now use React Hooks that include the power of useState!

Before this, one of the key differences between them was that functional components lacked the capability to hold an abstracted state property. With the introduction of the useState hook there is now an alternative to this. :)

val (word, setWord) = useState("")

The example above shows a simple useState variable of type String. The default value is initialised in the parameters of the useState function — i.e useState("hello"), this would declare the getter value as "hello". To update the value of the word we use the function setWord("World"). Essentially, word is the getter and setWord is the setter.

We can actually tidy up this logic further with delegation using the by keyword to delegate the get and set of useState.

var wordState by useState("")

To benefit from delegation, we need to convert the way we instantiate the state variable. To have state capability, the type of the property needs to become mutable — i.e. val to var. There is also no need to keep two properties for get and set either. Renaming the variable is important as it has a hidden superpower.

Here @sKalable our preference is to give it a suffix named State for more clarity around our code and hidden functionality.

State in Functional Components

lets refactor our Class Component to a Functional Component!

/**
 * [indentWithDot] is a react [functionalComponent]. This type of component is not
 * lifecycle aware and is more lightweight than a class component [RComponent].
 */
private val indentWithDot = functionalComponent<RProps> {
        /**
         *  To initialise the state within the function component we need to
         *  declare the [useState]s as the first variables in the function. Doing
         *  so ensures the variables are available for the rest of the code within
         *  the function.
         *
         *  Using the `by` keyword allows for delegation of the get and set of [useState]
         *  into the indentState var.
         *
         *  @see IndentState for state values
         */
        var indentState by useState<IndentState>(object : IndentState {
            override var indentAmount = 1
            override var indentationValue = "."
        })

        /**
         *  In a [functionalComponent] (FC) the last code block should always be the HTML to
         *  render. Compared to a class component, there is no RBuilder.render() as the HTML
         *  at the end of the function is what gets rendered. A FCs first param is a lambda extending
         *  from [RBuilder] itself so RBuilder.render() is not required.
         *
         *  As we can see, the [button] we render within [div] has an [onClickFunction] attribute that
         *  handles click events.
         *
         *  Here, when handled, we update the [IndentState.indentAmount] by adding one.
         *  [IndentState.indentationValue] is then updated by adding a number of "."s equal
         *  to the amount of [IndentState.indentAmount].
         *
         *  This value is then reflected in the text of the button.
         */
        div {
            button {
                /**
                 * Update the string using the values from [IndentState.indentationValue] and [IndentState.indentAmount]
                 */
                +"press me to add another dot indent from FC ${indentState.indentationValue} ${indentState.indentAmount}"
                attrs {
                    onClickFunction = {
                        indentState = object : IndentState {
                            /**
                             * reference the value of the [IndentState.indentAmount] and increment by one.
                             * The value of [IndentState.indentationValue] is then updated with a number of "."s
                             * equal to the new amount of [IndentState.indentAmount]
                             */
                            override var indentAmount = indentState.indentAmount + 1
                            override var indentationValue = ".".repeat(indentAmount)
                        }
                    }
                }
            }
        }
    }

/**
 * ReactBuilder function used to construct the React Component IndentWithDot.
 */
fun RBuilder.indentByDotsFC() = child(indentWithDot) {}

Running the code again we can see it works exactly the same as before, except with much less boilerplate.

There we have it, two approaches to using state in both a Class and Functional Component!

To Summarise

Effective code is clean and readable code. Also, you might be wondering how to handle multiple states? We cover this in Part 2 of KotlinJS and State Hooks!

As always, you can find the sample project for the above here

Thank you for taking your time to learn with us! Feel free to reach out and say hello.

@sKalable we are a Kotlin-centric agency that builds code to ensure it is Maintainable, Flexible and of course, sKalable.

Follow us on Twitter and Dev.to and LinkedIn to get the latest on Kotlin Multiplatform for your business or personal needs.

Global Applying Kotlin Styled CSS

skalable-dev — Fri, 26 Feb 2021 11:35:56 +0000

Here at sKalable we love all things Kotlin. We use it for working on the FrontEnd, BackEnd and everywhere in between.

We are particularly excited about making code as clean and easy to use as possible within the Kotlin ecosystem. Enabling the formation of an environment that encourages engineers to develop fast, all while applying effective and understandable patterns. We are very passionate about that @sKalable.

Today we will be covering Global Styles in CSS in a KotlinJS project.

To begin we need to see what the outlook of what we would like to achieve feels like.

When looking at the above diagram it shows that we are looking to apply the Img CSS to every image living in the body of the project.

Getting a base Setup

Sometimes the best place to start is with the basics. For this example we will create a base component of just an img within our document.

fun main() {
    window.onload = {
        render(document.getElementById("root")) {
            /**
             * Load our image in the body without any CSS applied directly
             */
            img(
                alt = "Skalable Logo",
                src = "YOUR IMAGE URL"
            ) {}
        }
    }
}

Running the above the following is rendered.

A little on the large side to say the least. We can see it takes up the entirety of the main page. While this might be what you're looking for in some cases it definitely shouldn't be the default.

So how do we address this for all images?

Going Global

Applying global styles can have a huge range of benefits for your project. You can decide default styles and fonts for your basic tags such as p or h1 h2 etc.

To add a global style for your project there are a few approaches. What we tend to prefer @sKalable is SRP - "A class should have only one reason to change"

The message here is to group your logic into separate areas of concern. To achieve this with styles we can create a GlobalStyles object that manages all our global styles in the project.

object GlobalStyles : StyleSheet("GlobalStyles") {}

While currently bare, we need to look to the ever brilliant Kotlin-Styled library for KotlinJS.

Note: at the time of writing the global style approach is non-functional with the listed approach within the README.md

Populating our stylesheet with our global style is easy as 3.14.

We need to begin by declaring our initial style for the body of our page.

object GlobalStyles : StyleSheet("GlobalStyles") {
    private val styles = CSSBuilder().apply {
        body {
            /**
             * Gives the body the following css globally (there is only ever one body)
             *
             *  - Sets the maxWidth with to the size available for the content.
             *  - Adds Auto Margin to the body allowing everything to be centered.
             *  - Creates a padding of 100px all around the body
             */
            maxWidth = LinearDimension.maxContent
            margin(LinearDimension.auto)
            padding(100.px)
            /**
             * We can visualise this much better if we give the background a grey colour.
             */
            backgroundColor = Color.darkGray
        }
    }
}

This won't apply the style just yet, first we need to inject it into the Kotlin-Styled global setter. Without causing confusion and to abide by SRP we can create the handler function for this directly in the stylesheet. Doing so will allow for all the styles that are in the GlobalStyles to remain private.

//Inside GlobalStyles at the bottom 

    /**
     * By creating a wrapper function in our Global Styles, it gives
     * the global style sheet the capability to have the styles set as private.
     */
    fun applyGlobalStyle() {
        styled.injectGlobal(styles.toString())
    }

So when do we use this new applyGlobalStyle function?

Directly in our client class is where!

fun main() {
    /**
     * Using our global styles object we
     * can call our wrapper function to apply
     * the global styles to our project.
     */
    GlobalStyles.applyGlobalStyle()
    window.onload = {
        render(document.getElementById("root")) {
            /**
             * Load our image in the body without any CSS applied directly
             */
            img(
                alt = "Skalable Logo",
                src = "YOUR IMAGE URL"
            ) {}
        }
    }
}

Applying and running the above gives us the following result.

I know, yuck. What the hell is going on here. There is one huge positive in all of this, the style was applied. We haven't done anything with the image in particular in all of this. Time to get specific.

Applying Global CSS to individual components

Back in our GlobalStyles object we are going to add an img tag directly in the body and apply some css to it.

body {
    ... // CSS for Body Tag

    /**
     * When you want to apply a base CSS style to components within the
     * body its as simple as nesting that component within and setting
     * the CSS that you like.
     */
    img {
        maxWidth = 500.px
    }
}

Now where getting somewhere. We have applied the image css to all img tags within our project. Awesome!

Optimise for scalability

Every web engineer knows how important it is to keep your css organised and clean. The best way to apply this philosophy is by starting with it. Since we have everything working correctly lets abstract the individual css for each component to keep readability high and keep things sKalable (see what I did there?)

Back in our GlobalStyles we are going to abstract the image style into its own RuleSet. After we will apply it back into the img tag within the body.

// Inside GlobalStyles below styles val.

    /**
     * Im order to not overwhelm your fellow engineers, we can
     * extract styles into separate CSS components.
     *
     * This is particularly useful when you have quite a few different styles.
     */
    private val baseImg by css {
        maxWidth = 500.px
    }

Now that we've abstracted the img css we can add it to the body with a simple + operator also known as UnaryPlus.

body {
    ... // CSS for Body Tag

    /**
     * When you want to apply a base CSS style to components within the
     * body its as simple as nesting that component within and setting
     * the CSS that you like.
     */
    img {
        +baseImg
    }
}

There we are, a global stylesheet that will grow with your projects needs.

Feel free to comment or get in touch. @sKalable we are a Kotlin agency that builds code the way it should be built to ensure it is Maintainable, Customisable, Flexible and sKalable (I did it again.)

Check out the sample project here

Injectable Kotlin Styles

skalable-dev — Tue, 23 Feb 2021 23:01:25 +0000

Custom Component with Injected Kotlin Styled CSS

At sKalable we love Kotlin! We work with it at both the frontend and backend.

One aspect of Kotlin we are most excited by in terms of potential is Kotlin Multiplatform (KMM). We have recently been doing some work on improving the usability of KMM in a way that creates a friendly environment for engineers working on building web apps using Kotlin. This article helps to explain what we have built.

Reusing components is no easy feat for newcomers, it can take a deep understanding of various frameworks and patterns of development. When building a generic style systems that can change the look and feel of a component in most web frameworks, they are normally created in a separate .ccs or .scss file. These styles are then imported where needed, but what if you wanted to keep it all in the same language? While there are quite a lot of examples around this scenario, the same cannot be said for the incredible Kotlin-Styled framework.

Let's outline what we would like to achieve:

While in theory we can just inject the name of the style in our .css file that we wish to apply to the custom KotlinJS component as a String. We don't really get the same benefit or capability we would by directly accessing the object itself. Following this approach, it also creates more boilerplate from managing constant strings of the style names and reducing re-usability.

Let us look at how our Kotlin Stylesheet is constructed.

object CustomComponentStyles : StyleSheet("CustomComponentStyles") {
   /**
    * A custom style declared directly in Kotlin using styled!
    */
   val cool by css {
      //Custom style
   }
}

To first understand what we need to do we need to look at what css does itself in Kotlin Styled.

fun css(vararg parents: RuleSet, builder: RuleSet) = CssHolder(this, *parents, builder)

While it looks like this just returns a CssHolder, in reality what we get is a RuleSet. The delegation happens when using the by key in our Kotlin Stylesheet. This allows us to use the css getter when applying the values to our cool variable.

A deeper look into the CssHolder reveals the truth of the situation. In overloaded operator on the getValue function we can see it returns a RuleSet. A funny situation to be in when you expected a CssHolder unknowingly.

operator fun getValue(thisRef: Any?, property: KProperty<*>): RuleSet = {}

Extension Functions to the rescue!

With this newfound knowledge we can begin to make our code scale in a way that reads well and causes less confusion for everyone.

To begin we need to analyse what type does a CustomStyledProps expect for css

external interface CustomStyledProps : RProps {
   var css: ArrayList<RuleSet>?
}

We get an ArrayList of type RuleSet which is nullable, our issue is that it's nullable. While some might say, why is that an issue? Readability. That's why.

Let's get building!

Personally I tend to keep all my extension functions in an util directory. So let us create a file in there called CssExt.kt. This is where our custom CSS extension functions will live.

Within this file create a function extending from the RuleSet itself. This function will translate the RuleSet itself into an ArrayList<Ruleset> object that is non nullable as to use it RuleSet must always exist. In this instance we called the function toCss() to make reading the code more intuitive.

fun RuleSet.toCss(): ArrayList<RuleSet> {
   return arrayListOf(this)
}

While we have a way of adding the ArrayList<RuleSet> to the property as a list, we need to be able to also convert it back into a single RuleSet. This brings us back to our Nullability issue. Before we create the second extension to our CssExt.kt file, create a GlobalStyles file with a single empty style within.

object GlobalStyles : StyleSheet("GlobalStyles") {

   /**
    * Rather than setting null we will use an empty style.
    */
   val empty by css {}

}

Now we can use the power of the Elvis operator?: (Turn your head sideways to see elvis) we can add another extension function to give us a guarantee the RuleSet will have a valid value in our extension. This will be based on the CustomStyledProps interface itself.

fun CustomStyledProps.css(): RuleSet {
   return this.css?.first() ?: GlobalStyles.empty
}

Creating a Custom Component

Before we use our new extensions and CustomSyledProps though, we need to create a Custom KotlinJS component. (For this example state is here for extensibility purposes in the future)

import react.*
import styled.CustomStyledProps
import styled.css
import styled.styledDiv
import util.css

/**
 * We use an interface to inject in props. It allows us to create
 * clean DSL builders for our custom components.
 *
 * By extending form CustomStyledProps we can benefit from adding CSS
 * directly through our props.
 */
external interface CustomComponentProps : CustomStyledProps {
   var name: String
}

/**
 * An interface is also used as a state
 * so we can maintain the state of a component.
 */
external interface CustomComponentState : RState {
   var name: String
}

/**
 * We extend from RComponent and tell it the types of Props and State to expect internally.
 *
 * This is our custom component.
 */
@JsExport
class CustomComponent(props: CustomComponentProps) : RComponent<CustomComponentProps, CustomComponentState>(props) {

   /**
    * To begin, we set the initial state to the name in the prop we injected.
    */
   override fun CustomComponentState.init(props: CustomComponentProps) {
      name = props.name
   }

   override fun RBuilder.render() {
      styledDiv {
         css {
            /**
             * We make use of our CustomStyledProps extension function by
             * setting the from the returned value RuleSet.
             */
            +props.css()
         }
         +"Hello there ${state.name} from your very own custom component!"
      }
   }
}

/**
 * Using an extension function on RBuilder we can construct our DSL.
 *
 * Here we apply each variable within the props to the child class of our Custom component,
 * Setting each as an attribute of the component.
 *
 */
fun RBuilder.customComponent(handler: CustomComponentProps.() -> Unit) = child(CustomComponent::class) {
   attrs(handler)
}

Within the styledDiv there is a css section. In here we can embed any custom styles we desire. Using our extension css() we can also call upon the props to fetch the required RuleSet that we have injected.

Result

The extension function at the bottom of the file provides a clean way of building our custom component. Let's see our new utility functions in action.

/**
 * Our custom DSL to create the CustomComponent.
 * Here we use the cool style
 * @see CustomComponentStyles.cool
 */
customComponent {
   /**
    * Using our extension function we can create the desired list
    * that the CustomStyledProps requires.
    * @see CustomComponentProps.css
    */
   css = CustomComponentStyles.cool.toCss()
   name = "Sean"
}
/**
 * The same component but this time
 * we use the cooler style
 * @see CustomComponentStyles.cooler
 */
customComponent {
   css = CustomComponentStyles.cooler.toCss()
   name = "Seb"
}

Calling .toCss() utilises our extension to create the desired output for the CustomStyledProps.

When rendered, we get the following result.

One component, two different styles, no strings, all linked directly with the Power of Kotlin!

Find the sample project for this approach hosted @here

Best of luck from all @ the sKalable team 😎