https://github.com/joaquim-verges/Helium
Lightweight, Intuitive Framework for Android
https://github.com/joaquim-verges/Helium
Last synced: about 2 months ago
JSON representation
Lightweight, Intuitive Framework for Android
- Host: GitHub
- URL: https://github.com/joaquim-verges/Helium
- Owner: joaquim-verges
- License: apache-2.0
- Created: 2018-03-23T21:04:58.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2022-01-20T06:29:29.000Z (over 3 years ago)
- Last Synced: 2025-04-06T10:14:24.081Z (about 2 months ago)
- Language: Kotlin
- Homepage:
- Size: 27.4 MB
- Stars: 341
- Watchers: 9
- Forks: 18
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - joaquim-verges/Helium - Lightweight, Intuitive Framework for Android (Kotlin)
README
# Helium
Lightweight & intuitive framework for Android & iOS powered by Kotlin Multiplatform.
*What if building an App was as simple as assembling Lego blocks?*
## Download
[](https://search.maven.org/search?q=g:com.joaquimverges.helium) [](https://app.bitrise.io/app/9b5a174b9921d71f)
```groovy
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
- ##### [Core framework](/helium-core)
- ##### [Helium Compose](/helium-compose)
- ##### [Helium UI](/helium-ui)
- ##### [Helium Navigation](/helium-navigation)
- ##### [Helium Testing](/helium-test)
## 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:
```kotlin
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](/helium-core) documentation.
For usage with Jetpack Compose, check out the [helium-compose](/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:
- [helium-ui](/helium-ui): List, Cards, ViewPager, etc.
- [helium-navigation](/helium-navigation): Collapsing Toolbar, Bottom Navigation, Drawer, etc.
Here's a typical usage of `ListUi`, one of the most useful blocks provided.
```kotlin
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](/samples/multiplatform_app) - Simple Multiplatform News App (Android & iOS), using Jetpack Compose and SwiftUI
- [newsapp](/samples/newsapp) - Fully functional Android News app downloadable on [Google Play](https://play.google.com/store/apps/details?id=com.jv.news)
- [demoapp](/samples/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](/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.
```