Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/guilhe/kmp-composeuiviewcontroller
KSP library and Gradle Plugin for generating ComposeUIViewController and UIViewControllerRepresentable files when using Compose Multiplatform for iOS
https://github.com/guilhe/kmp-composeuiviewcontroller
compose-multiplatform gradle-plugin kotlin-ksp kotlin-multiplatform swiftui
Last synced: 4 days ago
JSON representation
KSP library and Gradle Plugin for generating ComposeUIViewController and UIViewControllerRepresentable files when using Compose Multiplatform for iOS
- Host: GitHub
- URL: https://github.com/guilhe/kmp-composeuiviewcontroller
- Owner: GuilhE
- License: apache-2.0
- Created: 2023-09-05T11:10:18.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-23T22:53:28.000Z (6 days ago)
- Last Synced: 2024-12-23T23:28:12.008Z (6 days ago)
- Topics: compose-multiplatform, gradle-plugin, kotlin-ksp, kotlin-multiplatform, swiftui
- Language: Kotlin
- Homepage: https://guilhe.github.io/KMP-ComposeUIViewController/htmlMultiModule/
- Size: 4.04 MB
- Stars: 72
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# KMP-ComposeUIViewController
KSP library for generating `ComposeUIViewController` and `UIViewControllerRepresentable` implementations when using [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/) for iOS.
| Version | Kotlin | KSP | Compose Multiplatform | Xcode |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------:|:------:|:---------------------:|:------:|
| [](https://plugins.gradle.org/plugin/io.github.guilhe.kmp.plugin-composeuiviewcontroller) | 2.1.0 | 1.0.29 | 1.7.1 | 16.2.0 |
The suffix `-BETA` will be added to reflect JetBrain's [Compose Multiplatform iOS stability level](https://www.jetbrains.com/help/kotlin-multiplatform-dev/supported-platforms.html#current-platform-stability-levels-for-compose-multiplatform-ui-framework), until it becomes `STABLE`.
[](https://androidweekly.net/issues/issue-583) [](https://mailchi.mp/kotlinweekly/kotlin-weekly-378) [](https://mailchi.mp/kotlinweekly/kotlin-weekly-389) 
## Motivation
As the project expands, the codebase required naturally grows, which can quickly become cumbersome and susceptible to errors. To mitigate this challenge, this library leverages [Kotlin Symbol Processing](https://kotlinlang.org/docs/ksp-overview.html) to automatically generate the necessary Kotlin and Swift code for you.
It can be used for **simple** and **advanced** use cases.
### Simple
`@Composable` UI state is managed inside the common code from the KMP module.
### Advanced
`@Composable` UI state is managed by the iOS app.
Kotlin Multiplatform and Compose Multiplatform are built upon the philosophy of incremental adoption and sharing only what you require. Consequently, the support for this specific use-case - in my opinion - is of paramount importance, especially in its capacity to entice iOS developers to embrace Compose Multiplatform.
> [!TIP]
> This library takes care of the heavy lifting for you, but if you're interested in understanding how it works, the detailed approach is explained here: [Compose Multiplatform — Managing UI State on iOS](https://proandroiddev.com/compose-multiplatform-managing-ui-state-on-ios-45d37effeda9).
## Installation
By using the Gradle plugin all configurations will be applied automatically. If you wish to change the default values, you can configure its parameters using the available [extension](kmp-composeuiviewcontroller-gradle-plugin/src/main/kotlin/com/github/guilhe/kmp/composeuiviewcontroller/gradle/ComposeUiViewControllerParameters.kt).
```kotlin
plugins {
id("org.jetbrains.kotlin.multiplatform")
id("com.google.devtools.ksp")
id("io.github.guilhe.kmp.plugin-composeuiviewcontroller") version "$LASTEST_VERSION"
}
ComposeUiViewController {
iosAppName = "Gradient"
targetName = "Gradient"
}
```
## Code generation
### KMP module
Inside `iosMain` we can take advantage of two annotations:
`@ComposeUIViewController`:
To annotate the `@Composable` as a desired `ComposeUIViewController` to be used by the iOS app.
`@ComposeUIViewControllerState`:
To annotate the parameter as the composable state variable (for **advanced** use cases).
> [!IMPORTANT]
> Only 0 or 1 `@ComposeUIViewControllerState` and an arbitrary number of parameter types (excluding `@Composable`) are allowed in `@ComposeUIViewController` functions.
>
> The `@ComposeUIViewController` includes a `frameworkBaseName` parameter, allowing you to specify a framework name manually. While the plugin typically attempts to retrieve this name automatically, you can use this parameter to enforce a specific name if the automatic retrieval fails.
>
> For more information consult the [ProcessorTest.kt](kmp-composeuiviewcontroller-ksp/src/test/kotlin/composeuiviewcontroller/ProcessorTest.kt) file from `kmp-composeuiviewcontroller-ksp`.
#### Examples
Simple
```kotlin
//iosMain
@ComposeUIViewController
@Composable
internal fun ComposeSimpleView() { }
```
will produce a `ComposeSimpleViewUIViewController`:
```kotlin
object ComposeSimpleViewUIViewController {
fun make(): UIViewController {
return ComposeUIViewController {
ComposeSimpleView()
}
}
}
```
and also a `ComposeSimpleViewRepresentable`:
```swift
import SwiftUI
import SharedUI
public struct ComposeSimpleViewRepresentable: UIViewControllerRepresentable {
func makeUIViewController(context: Context) -> UIViewController {
ComposeSimpleViewUIViewController().make()
}
func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
//unused
}
}
```
Advanced
```kotlin
//iosMain
data class ViewState(val isLoading: Boolean)
@ComposeUIViewController
@Composable
internal fun ComposeAdvancedView(@ComposeUIViewControllerState viewState: ViewState, callback: () -> Unit) { }
```
will produce a `ComposeAdvancedViewUIViewController`:
```kotlin
object ComposeAdvancedViewUIViewController {
private val viewState = mutableStateOf(null)
fun make(callback: () -> Unit): UIViewController {
return ComposeUIViewController {
viewState.value?.let { ComposeAdvancedView(it, callback) }
}
}
fun update(viewState: ViewState) {
this.viewState.value = uiState
}
}
```
and also a `ComposeAdvancedViewRepresentable`:
```swift
import SwiftUI
import SharedUI
public struct ComposeAdvancedViewRepresentable: UIViewControllerRepresentable {
@Binding var viewState: ViewState
let callback: () -> Void
func makeUIViewController(context: Context) -> UIViewController {
ComposeAdvancedViewUIViewController().make(callback: callback)
}
func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
ComposeAdvancedViewUIViewController().update(viewState: viewState)
}
}
```
### iOSApp
After a successful build the `UIViewControllerRepresentable` files are included and referenced in the `xcodeproj` ready to be used:
```swift
import SwiftUI
import SharedUI
struct SomeView: View {
@State private var state: ViewState = ViewState(isLoading: false)
var body: some View {
VStack {
ComposeSimpleViewRepresentable()
ComposeAdvancedViewRepresentable(viewState: $state, callback: {})
}
}
}
```
> [!IMPORTANT]
> Avoid deleting `iosApp/Representables` without first using Xcode to `Remove references`.
## Sample
For a working [sample](sample) open `iosApp/Gradient.xcodeproj` in Xcode and run standard configuration or use KMM plugin for Android Studio and choose `iosApp` in run configurations.
```bash
> Task :shared:kspKotlinIosSimulatorArm64
note: [ksp] loaded provider(s): [com.github.guilhe.kmp.composeuiviewcontroller.ksp.ProcessorProvider]
note: [ksp] GradientScreenUIViewController created!
note: [ksp] GradientScreenRepresentable created!
> Task :CopyFilesToXcode
> Copying files to iosApp/SharedRepresentables/
> Checking for new references to be added to xcodeproj
> GradientScreenUIViewControllerRepresentable.swift added!
> Done
```
You can also find other working samples in:
## LICENSE
Copyright (c) 2023-present GuilhE
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
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.