Skip to content

joaquim-verges/Helium

Repository files navigation

Helium

Lightweight & intuitive framework for Android & iOS powered by Kotlin Multiplatform.

What if building an App was as simple as assembling Lego blocks?

Download

Maven Central Build Status

implementation 'com.joaquimverges.helium:helium-core:x.y.z' // core classes (Kotlin Multiplatform project)
// or
implementation 'com.joaquimverges.helium:helium-core-android:x.y.z' // core classes (Android project)

implementation 'com.joaquimverges.helium:helium-compose:x.y.z'   // Jetpack Compose integration (Android)
implementation 'com.joaquimverges.helium:helium-ui:x.y.z'   // ui components (Android)
implementation 'com.joaquimverges.helium:helium-navigation:x.y.z'   // navigation components (Android)

testImplementation 'com.joaquimverges.helium:helium-test:x.y.z'   // unit test helper classes (Android)

Documentation

Overview

An intuitive architecture pattern

Building an app should feel like assembling Lego blocks, that's the core principle of Helium. The framework proposes the following mental model to structure your code:

  • UiBlock - a class that handles rendering UI.
  • LogicBlock - a class that handles logic.
  • AppBlock = (LogicBlock + UiBlock) - assembling logic with UI creates a fully functional piece of your App.

Just like Lego blocks, or puzzle pieces, a UiBlock can only be assembled with a LogicBlock if they're compatible.

In code, this is handled by two classes representing the connectors between blocks: BlockState and BlockEvent

  • a LogicBlock exposes (emits) a BlockState and expects (handles) a BlockEvent
  • a UiBlock exposes (emits) a BlockEvent and expects (renders) a BlockState

If both Logic and UI expose and expect the same type of state and event, then they're compatible.

With an intuitive, kotlin first API, assembling blocks in Activity or Fragment is as simple as this:

val logic = MyLogic() // create a logic block
val ui = MyUi(layoutInflater) // create a UI block
assemble(logic + ui) // assemble them

Helium core is a Kotlin Multiplatform library, which means it can be used on both Android and iOS.

Helium works great with declarative UI frameworks like Jetpack Compose and SwiftUI.

For detailed information and examples, head over to the helium-core documentation.

For usage with Jetpack Compose, check out the helium-compose documentation.

Ready to use App Blocks

Helium provides the framework to build your own AppBlocks, but also provides a growing catalog of existing blocks ready to be used:

Here's a typical usage of ListUi, one of the most useful blocks provided.

val listUi = ListUi(layoutInflater, { inflater, container ->
    MyListItem(inflater, container)
})
assemble(MyListLogic() + listUi)

Follow the links above for documentation and examples on how to use those handy App Blocks in your own apps.

Samples

  • multiplaform_app - Simple Multiplatform News App (Android & iOS), using Jetpack Compose and SwiftUI
  • newsapp - Fully functional Android News app downloadable on Google Play
  • demoapp - A catalog of different AppBlocks usages

Testing

Unit testing blocks is easy, and you should always write tests for your LogicBlock when possible. Helium provides helper classes to make testing your logic super simple. Head over to the helium-test documentation to learn more.

License

Copyright (C) 2020 Joaquim Verges

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.