Merge pull request #302 from dhis2/docs

docs: [ANDROAPP-6451] Init mobile UI documentation

.github/workflows/continuous-deployment.yml

@@ -1,20 +1,22 @@
-# This is a basic workflow to help you get started with Actions
-
 name: Continuous deployment
 
-# Controls when the workflow will run
+env:
+  main_project_module: android
+
 on:
   push:
     branches:
-      - develop
+      - develop # Automatically generates snapshot versions
 
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
+  workflow_dispatch: ## manually generates release versions
+    inputs:
+      release_version:
+        description: 'Please, enter the release version'
+        required: true
+        type: string
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
-  # This workflow contains a single job called "build"
-  publish:
+  publish-maven:
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
 
@@ -41,3 +43,38 @@ jobs:
           OSSRH_PASSWORD: ${{ secrets.SONATYPE_OSSRH_PASSWORD }}
           SIGNING_PRIVATE_KEY: ${{ secrets.PGP_PRIVATE_KEY }}
           SIGNING_PASSWORD: ${{ secrets.PGP_PASSPHRASE }}
+
+  publish_github:
+    runs-on: ubuntu-latest
+    if: ${{ (inputs.release_version) && (inputs.release_version != '') }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: 17
+          distribution: temurin
+          cache: 'gradle'
+
+      - name: Change wrapper permissions
+        run: chmod +x ./gradlew
+
+      - name: Build Android (APK) - ${{ env.main_project_module }} module
+        run: ./gradlew assembleDebug
+
+      - name: Rename APK
+        run: |
+          mv ${{ env.main_project_module }}/build/outputs/apk/debug/android-debug.apk ${{ env.main_project_module }}/build/outputs/apk/debug/ui-components-android-${{ inputs.release_version }}.apk
+
+
+      - name: Github Release
+        uses: ncipollo/release-action@v1.14.0
+        with:
+          allowUpdates: true
+          draft: true
+          generateReleaseNotes: true
+          name: "Release notes - DHIS2 Design system: ${{ inputs.release_version }}"
+          tag: ${{ inputs.release_version }}
+          artifacts: ${{ env.main_project_module }}/build/outputs/apk/debug/ui-components-android-${{ inputs.release_version }}.apk

.github/workflows/dokka.yml

@@ -0,0 +1,57 @@
+name: Deploy API docs
+
+on:
+  push:
+    branches:
+      - main
+      - docs
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: 17
+          distribution: temurin
+          cache: 'gradle'
+      - name: Change wrapper permission
+        run: chmod +x ./gradlew
+
+      - name: Build Java docs
+        run: ./gradlew :designsystem:dokkaHtml -PremoveSnapshotSuffix
+
+      - name: Organize pages structure
+        run: |
+          mkdir _site && mkdir _site/api
+          cp -r designsystem/build/dokka/html/* _site/api
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,53 +1,6 @@
 # DHIS2 Mobile UI
 
-> **@dhis2/dhis2-mobile-ui** is
-> a [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/) DHIS2 design system
-> library for [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) applications.
-
-**DHIS2 Mobile UI library** is based in
-the [DHIS2 Mobile Design System Figma library](https://www.figma.com/file/eRk6bt0B8BJlTO9PZXirHN/DHIS2-Mobile-Design-System).
-
-This library currently supports **desktop** and **Android** targets, in the next versions it will
-support **iOS** and **web**.
-
-## Installation
-
-In the module **build.gradle.kts**:
-
-```kotlin
-dependencies {
-  implementation("org.hisp.dhis.mobile:designsystem:0.3.0")
-}
-```
-
-# Usage
-
-```kotlin
-setContent {
-  DHIS2Theme {
-    // A surface container using the 'background' color from the theme
-    Surface(
-      modifier = Modifier.fillMaxSize(),
-      color = SurfaceColor.Container
-    ) {
-      Components()
-    }
-  }
-}
-```
-
-```kotlin
-Button(
-  text = provideStringResource("show_more"),
-  icon = {
-    Icon(
-      painter = provideDHIS2Icon(resourceName = "dhis2_blood_a_n_positive"),
-      contentDescription = ""
-    )
-  },
-  style = ButtonStyle.KEYBOARDKEY
-) {}
-```
+Dhis2 Mobile UI library documentation, installation and usage is explained in [DHIS2 Developer portal](https://developers.dhis2.org/mobile/mobile-ui/overview)
 
 ## Compose Compiler Reports
 

common/src/commonMain/kotlin/org/hisp/dhis/common/screens/actionInputs/InputDateTimeScreen.kt

@@ -13,9 +13,9 @@ import org.hisp.dhis.mobile.ui.designsystem.component.DateTimeActionType
 import org.hisp.dhis.mobile.ui.designsystem.component.InputDateTime
 import org.hisp.dhis.mobile.ui.designsystem.component.InputShellState
 import org.hisp.dhis.mobile.ui.designsystem.component.SelectableDates
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.DateTimeTransformation
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.DateTransformation
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.TimeTransformation
+import org.hisp.dhis.mobile.ui.designsystem.component.model.DateTimeTransformation
+import org.hisp.dhis.mobile.ui.designsystem.component.model.DateTransformation
+import org.hisp.dhis.mobile.ui.designsystem.component.model.TimeTransformation
 import org.hisp.dhis.mobile.ui.designsystem.component.state.InputDateTimeData
 import org.hisp.dhis.mobile.ui.designsystem.component.state.rememberInputDateTimeState
 

common/src/commonMain/kotlin/org/hisp/dhis/common/screens/basicTextInputs/InputNumberScreen.kt

@@ -10,7 +10,7 @@ import org.hisp.dhis.mobile.ui.designsystem.component.ColumnComponentContainer
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnScreenContainer
 import org.hisp.dhis.mobile.ui.designsystem.component.InputNumber
 import org.hisp.dhis.mobile.ui.designsystem.component.InputShellState
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.RegExValidations
+import org.hisp.dhis.mobile.ui.designsystem.component.model.RegExValidations
 
 @Composable
 fun InputNumberScreen() {

common/src/commonMain/kotlin/org/hisp/dhis/common/screens/cards/ExpandableListCardScreen.kt

@@ -15,11 +15,11 @@ import org.hisp.dhis.mobile.ui.designsystem.component.AvatarStyleData
 import org.hisp.dhis.mobile.ui.designsystem.component.Button
 import org.hisp.dhis.mobile.ui.designsystem.component.ButtonStyle
 import org.hisp.dhis.mobile.ui.designsystem.component.ExpandableItemColumn
+import org.hisp.dhis.mobile.ui.designsystem.component.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.ListCardDescriptionModel
 import org.hisp.dhis.mobile.ui.designsystem.component.ListCardTitleModel
 import org.hisp.dhis.mobile.ui.designsystem.component.MetadataAvatarSize
 import org.hisp.dhis.mobile.ui.designsystem.component.VerticalInfoListCard
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.state.rememberAdditionalInfoColumnState
 import org.hisp.dhis.mobile.ui.designsystem.component.state.rememberListCardState
 import org.hisp.dhis.mobile.ui.designsystem.theme.SurfaceColor

common/src/commonMain/kotlin/org/hisp/dhis/common/screens/cards/ListCardScreen.kt

@@ -36,11 +36,11 @@ import org.hisp.dhis.mobile.ui.designsystem.component.Button
 import org.hisp.dhis.mobile.ui.designsystem.component.ButtonStyle
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnComponentContainer
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnScreenContainer
+import org.hisp.dhis.mobile.ui.designsystem.component.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.ListCard
 import org.hisp.dhis.mobile.ui.designsystem.component.ListCardDescriptionModel
 import org.hisp.dhis.mobile.ui.designsystem.component.ListCardTitleModel
 import org.hisp.dhis.mobile.ui.designsystem.component.MetadataAvatarSize
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.state.rememberAdditionalInfoColumnState
 import org.hisp.dhis.mobile.ui.designsystem.component.state.rememberListCardState
 import org.hisp.dhis.mobile.ui.designsystem.resource.provideDHIS2Icon

common/src/commonMain/kotlin/org/hisp/dhis/common/screens/parameter/ParameterSelectorScreen.kt

@@ -16,6 +16,7 @@ import org.hisp.dhis.mobile.ui.designsystem.component.CheckBoxData
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnScreenContainer
 import org.hisp.dhis.mobile.ui.designsystem.component.DateTimeActionType
 import org.hisp.dhis.mobile.ui.designsystem.component.DropdownItem
+import org.hisp.dhis.mobile.ui.designsystem.component.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.InputAge
 import org.hisp.dhis.mobile.ui.designsystem.component.InputAgeModel
 import org.hisp.dhis.mobile.ui.designsystem.component.InputBarCode
@@ -36,8 +37,7 @@ import org.hisp.dhis.mobile.ui.designsystem.component.InputShellState
 import org.hisp.dhis.mobile.ui.designsystem.component.InputStyle
 import org.hisp.dhis.mobile.ui.designsystem.component.InputText
 import org.hisp.dhis.mobile.ui.designsystem.component.RadioButtonData
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.DateTimeTransformation
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.ImageCardData
+import org.hisp.dhis.mobile.ui.designsystem.component.model.DateTimeTransformation
 import org.hisp.dhis.mobile.ui.designsystem.component.parameter.ParameterSelectorItem
 import org.hisp.dhis.mobile.ui.designsystem.component.parameter.model.ParameterSelectorItemModel
 import org.hisp.dhis.mobile.ui.designsystem.component.parameter.model.ParameterSelectorItemModel.Status.CLOSED

common/src/commonMain/kotlin/org/hisp/dhis/common/screens/toggleableInputs/InputMatrixScreen.kt

@@ -12,9 +12,9 @@ import androidx.compose.ui.graphics.painter.BitmapPainter
 import androidx.compose.ui.graphics.painter.Painter
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnComponentContainer
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnScreenContainer
+import org.hisp.dhis.mobile.ui.designsystem.component.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.InputMatrix
 import org.hisp.dhis.mobile.ui.designsystem.component.InputShellState
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.theme.SurfaceColor
 
 @Composable

common/src/commonMain/kotlin/org/hisp/dhis/common/screens/toggleableInputs/InputSequentialScreen.kt

@@ -12,9 +12,9 @@ import androidx.compose.ui.graphics.painter.BitmapPainter
 import androidx.compose.ui.graphics.painter.Painter
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnComponentContainer
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnScreenContainer
+import org.hisp.dhis.mobile.ui.designsystem.component.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.InputSequential
 import org.hisp.dhis.mobile.ui.designsystem.component.InputShellState
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.theme.SurfaceColor
 
 @Composable

designsystem/build.gradle.kts

@@ -1,3 +1,5 @@
+import org.jetbrains.dokka.gradle.DokkaTask
+
 version = rootProject.version
 group = rootProject.group
 
@@ -81,3 +83,21 @@ android {
         jvmToolchain(17)
     }
 }
+
+tasks.withType(DokkaTask::class).configureEach {
+    dokkaSourceSets {
+        configureEach {
+            moduleName.set("Mobile UI")
+        }
+    }
+    val dokkaBaseConfiguration = """
+    {
+      "customAssets": ["${file("../assets/logo-icon.svg")}"]
+    }
+    """
+    pluginsMapConfiguration.set(
+        mapOf(
+            "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration,
+        ),
+    )
+}

designsystem/src/androidMain/kotlin/org/hisp/dhis/mobile/ui/designsystem/component/internal/Keyboard.kt

@@ -10,7 +10,7 @@ import androidx.compose.runtime.remember
 import androidx.compose.ui.platform.LocalView
 
 @Composable
-actual fun keyboardAsState(): State<Keyboard> {
+internal actual fun keyboardAsState(): State<Keyboard> {
     val keyboardState = remember { mutableStateOf(Keyboard.Closed) }
     val view = LocalView.current
     DisposableEffect(view) {

designsystem/src/androidUnitTest/kotlin/org/hisp/dhis/mobile/ui/designsystem/ExpandableItemColumnSnapshotTest.kt

@@ -14,11 +14,11 @@ import org.hisp.dhis.mobile.ui.designsystem.component.AvatarStyleData
 import org.hisp.dhis.mobile.ui.designsystem.component.Button
 import org.hisp.dhis.mobile.ui.designsystem.component.ButtonStyle
 import org.hisp.dhis.mobile.ui.designsystem.component.ExpandableItemColumn
+import org.hisp.dhis.mobile.ui.designsystem.component.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.ListCardDescriptionModel
 import org.hisp.dhis.mobile.ui.designsystem.component.ListCardTitleModel
 import org.hisp.dhis.mobile.ui.designsystem.component.MetadataAvatarSize
 import org.hisp.dhis.mobile.ui.designsystem.component.VerticalInfoListCard
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.state.rememberAdditionalInfoColumnState
 import org.hisp.dhis.mobile.ui.designsystem.component.state.rememberListCardState
 import org.hisp.dhis.mobile.ui.designsystem.theme.SurfaceColor

designsystem/src/androidUnitTest/kotlin/org/hisp/dhis/mobile/ui/designsystem/InputMatrixSnapshotTest.kt

@@ -9,9 +9,9 @@ import androidx.compose.ui.graphics.asImageBitmap
 import androidx.compose.ui.graphics.painter.BitmapPainter
 import androidx.compose.ui.platform.LocalContext
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnScreenContainer
+import org.hisp.dhis.mobile.ui.designsystem.component.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.InputMatrix
 import org.hisp.dhis.mobile.ui.designsystem.component.InputShellState
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.theme.SurfaceColor
 import org.junit.Rule
 import org.junit.Test

designsystem/src/androidUnitTest/kotlin/org/hisp/dhis/mobile/ui/designsystem/InputSequentialSnapshotTest.kt

@@ -9,9 +9,9 @@ import androidx.compose.ui.graphics.asImageBitmap
 import androidx.compose.ui.graphics.painter.BitmapPainter
 import androidx.compose.ui.platform.LocalContext
 import org.hisp.dhis.mobile.ui.designsystem.component.ColumnScreenContainer
+import org.hisp.dhis.mobile.ui.designsystem.component.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.component.InputSequential
 import org.hisp.dhis.mobile.ui.designsystem.component.InputShellState
-import org.hisp.dhis.mobile.ui.designsystem.component.internal.ImageCardData
 import org.hisp.dhis.mobile.ui.designsystem.theme.SurfaceColor
 import org.junit.Rule
 import org.junit.Test