docs

documentation/_data/project.yml

@@ -23,10 +23,10 @@ library:
 # optional
 dependencies:
   compose:
-    cmp: 1.7.1
-    compose: 1.7.1
+    cmp: 1.7.3
+    compose: 1.7.5
     material3: 1.3.1
-    experimental: true
+    experimental: false
 
 # -------------
 # Module
@@ -40,9 +40,6 @@ groups:
   - name: modules
     label: Modules
     gradle-comment: statesaver modules
-  - name: plugins
-    label: Plugins
-    gradle-comment: gradle plugins
 
 modules:
   - name: core
@@ -55,26 +52,26 @@ modules:
       jvm: false
       info:
     dependencies: []
-  - name: statesaver-kotpreferences
+  - name: statesaver-preferences
     group: modules
-    description: a statesaver implementation for kotpreferences
+    description: saves the state of the last shown changelog inside a preference file
     optional: true
     platforms:
       android: true
       ios: true
       jvm: false
       info:
-    dependencies:
-      - name: KotPreferences
-        link: https://github.com/MFlisar/KotPreferences
-        version: 0.7.2
-  - name: statesaver-preferences
+    dependencies: [ ]
+  - name: statesaver-kotpreferences
     group: modules
-    description: a statesaver implementation for jetpack preferences
+    description: saves the state of the last shown changelog inside a preference file using my KotPreferences library
     optional: true
     platforms:
       android: true
       ios: true
       jvm: false
       info:
-    dependencies: []
+    dependencies:
+      - name: KotPreferences
+        link: https://github.com/MFlisar/KotPreferences
+        version: 0.7.2

documentation/docs/advanced/gradle-plugin.md

@@ -0,0 +1,57 @@
+---
+icon: material/button-pointer
+---
+
+This plugin allows you to transform a version string into a version code. This is useful if you want to use a version string in your gradle files and want to calculate the version code based on it.
+
+#### Example
+
+Top level `build.gradle.kts` file:
+
+```kotlin
+plugins {
+    id("io.github.mflisar.composechangelog.gradle-plugin") apply false
+}
+```
+
+After adding above you can simple apply the plugin inside your apps `build.gradle.kts` file like following and use it like following:
+
+```kotlin
+import com.michaelflisar.composechangelog.Changelog
+import com.michaelflisar.composechangelog.DefaultVersionFormatter
+
+plugins {
+    // other plugins
+    id("com.android.application")
+    id("kotlin-android")
+    id("kotlin-kapt")
+
+    // plugin of compose changelog
+    id("io.github.mflisar.composechangelog.gradle-plugin")
+}
+
+// define your app version code based on your format, here we use the Major.Minor.Patch format
+val version = "0.3.0"
+val code = Changelog.buildVersionCode(version, DefaultVersionFormatter(DefaultVersionFormatter.Format.MajorMinorPatch))
+
+// make sure to use the SAME formatter inside your code whenever you want to show a changelog - Major.Minor.Patch format is the default one though
+
+android {
+
+    // ...
+
+    defaultConfig {
+        // use the version and code variables from above
+        versionCode = code
+        versionName = version
+    }
+
+     // ...
+}
+```
+
+You now only must change `val version = "0.3.0"` to whatever new version you want and the code will be calculated by itself.
+
+Additionally you can easily use the `versionName` tag inside your `changelog.xml` file, the formatter will correctly parse it to it's number for you.
+
+**Always make sure to use the same formatter in your `build.gradle.kts` as well as inside your code.**

documentation/docs/index.md

@@ -8,11 +8,21 @@ icon: material/information-variant
 
 {% include 'region-features.md' %}
 
-!!! info
+* filtering
+    * useful to filter out uninteresting old changelog entries on app start
+    * useful for filtering changelog based on build flavour
+* also supports automatic handling of showing changelogs on app start (uses preference to save last seen changelog version and handles everything for you automatically to only show **new changelogs** and only show those once)
+* customise look
+    * you can provide custom composables for every item type if desired
+    * you can provide custom version name formatter
+    * you can provide a custom sorter
+* supports raw and xml resources, default resource name is `changelog.xml` in raw folder
+* supports summaries with a "show more" button
+* optional provides a `gradle plugin` that allows you to convert version names automatically to version numbers
 
-    This docs are not written yet - the docs are still placed in the github readme [here](https://github.com/MFlisar/ComposeChangelog) for now.
+!!! info
 
-Under Development
+    All features are splitted into separate modules, just include the modules you want to use!
 
 {% include 'screenshots.md' %}
 

documentation/docs/modules/core.md

@@ -0,0 +1,7 @@
+---
+icon: material/puzzle
+---
+
+This is the core module. It contains the changelog composable and all the necessary logic.
+
+All other modules are just optional extensions.

documentation/docs/modules/statesaver-kotpreferences.md

@@ -0,0 +1,11 @@
+---
+icon: material/puzzle
+---
+
+This module provides the functionality to save and use the last show changelog version. It uses my `KotPreferences` library for this purpose.
+
+```kotlin
+val changelogStateSaverKotPrefs = ChangelogStateSaverKotPreferences(DemoPrefs.lastShownVersionForChangelog) // pass in any StorageSetting<Boolean> from KotPreferences
+
+// use this state saver with ComposeChangelog
+```

documentation/docs/modules/statesaver-preferences.md

@@ -0,0 +1,11 @@
+---
+icon: material/puzzle
+---
+
+This module provides the functionality to save and use the last show changelog version. It uses the plain jetpack preferences to store the version code of the last shown changelog.
+
+```kotlin
+val changelogStateSaverKotPrefs = ChangelogStateSaverPreferences.create(context)
+
+// use this state saver with ComposeChangelog
+```

documentation/docs/usage.md

@@ -2,4 +2,106 @@
 icon: material/keyboard
 ---
 
-#### TODO
+#### Define your changelog as xml file (on android, a raw xml is preferred!)
+
+```xml
+  <changelog>
+
+    <!-- with version names -->
+    <release versionName="1.2.1" date="2024-04-20">
+        <new type="summary">-new gradle plugin added - you don't need to convert version names to version codes anymore!</new>
+    </release>
+    <release versionName="1.2.0" date="2023-03-04">
+        <info>Some info 1 - apostrophe test: it's weird, but apostrophes do not work in precompiled xml files placed in xml resources!</info>
+        <new type="summary">Some improvement 1</new>
+        <bugfix>Some bugfix 1</bugfix>
+        <info>Some info 2</info>
+        <new type="summary">Some improvement 2</new>
+        <bugfix>Some bugfix 2</bugfix>
+        <info>Some info 3</info>
+        <new>Some improvement 3</new>
+        <bugfix>Some bugfix 3</bugfix>
+        <customTag>My custom tag text...</customTag>
+    </release>
+
+    <!-- with version codes -->
+    <release versionCode="118" date="2023-03-04">
+        <new type="summary">This version has a summary item only - no show more button will be shown even if show more buttons are enabled</new>
+    </release>
+    <release versionCode="115" date="2023-03-04">
+        <info>Some info</info>
+        <new type="summary">Some improvement</new>
+        <bugfix>Some bugfix</bugfix>
+    </release>
+    <release versionCode="110" versionName="Version 1.10" date="2023-03-03" filter="dogs">
+        <info>Some dogs info - filter only set in release tag</info>
+        <new type="summary">Some dogs improvement - filter only set in release tag</new>
+        <bugfix>Some dogs bugfix - filter only set in release tag</bugfix>
+    </release>
+    <release versionCode="105" versionName="Version 1.05" date="2023-03-02" filter="cats">
+        <info type="summary">single summary of version 1.05</info>
+        <info>Some cats info - filter only set in release tag</info>
+        <new>Some cats improvement - filter only set in release tag</new>
+        <bugfix>Some cats bugfix - filter only set in release tag</bugfix>
+    </release>
+    <release versionCode="100" versionName="First release" date="2023-03-01">
+        <info filter="cats" type="summary">single cats summary of version 1.00</info>
+        <info filter="dogs" type="summary">single dogs summary of version 1.00</info>
+        <info filter="cats">New cats added - this info has filter text 'cats'</info>
+        <info filter="dogs">New dogs added - this info has filter text 'dogs'</info>
+        <new filter="cats">Some cats improvement - this info has filter text 'cats'</new>
+        <new filter="dogs">Some dogs improvement - this info has filter text 'dogs'</new>
+        <bugfix filter="cats">Some cats bugfix - this info has filter text 'cats'</bugfix>
+        <bugfix filter="dogs">Some dogs bugfix - this info has filter text 'dogs'</bugfix>
+    </release>
+    <release versionCode="90" versionName="First beta" date="2023-02-01">
+        <info>this release does not have any summary item and will be shown expanded even if summary is enabled - this behaviour can be adjusted by the second parameter in the builder with which you enable summaries</info>
+    </release>
+</changelog>
+```
+
+#### Show the interesting parts of the changelog on app start
+
+```kotlin
+ // 1) we need a state saver to persist the version for which the changelog was last shown
+// use either of the following 2 or implement the corresponding interface yourself
+
+// saves the last shown version inside a preference file
+val changelogStateSaver = remember {
+    ChangelogStateSaverPreferences.create(context)
+}
+
+// ALTERNATIVE: if you use my kotpreference library like this demo you can do following:
+val changelogStateSaverKotPrefs = remember {
+    ChangelogStateSaverKotPreferences(DemoPrefs.lastShownVersionForChangelog)
+}
+
+// 2) optional - here you can apply some customisations like changelog resource id, localized texts, styles, filter, sorter, renderer...
+val setup = ChangelogDefaults.setup()
+
+// 3) show the changelog for the app start - this will only show the changelogs that the user did not see yet
+val versionName = ChangelogUtil.getAppVersionName(context)
+ShowChangelogDialogIfNecessary(changelogStateSaver, versionName, setup)
+```
+
+#### Show the full changelog
+
+```kotlin
+// 1) we need a state to decide if we need to show the changelog or not
+var showChangelog by remember { mutableStateOf(false) }
+
+// 2) we need some event source
+Button(onClick = { showChangelog = true }) {
+    Text("Show Changelog")
+}
+
+// 3) we show the changelog if necessary
+if (showChangelog) {
+    // optional setup...
+    val setup = ChangelogDefaults.setup()
+    ShowChangelogDialog(setup) {
+        // this is the dismiss callback, here we must reset the showChangelog flag
+        showChangelog = false
+    }
+}
+```

documentation/mkdocs.yml

@@ -124,26 +124,12 @@ nav:
     - Dependencies: dependencies.md
     - Setup: setup.md
     - Usage: usage.md
-  #- Modules:
-  #  - Core: modules/core.md
-  #  - Dialog Info: modules/dialog-info.md
-  #  - Dialog Input: modules/dialog-input.md
-  #  - Dialog Number: modules/dialog-number.md
-  #  - Dialog Date: modules/dialog-date.md
-  #  - Dialog Time: modules/dialog-time.md
-  #  - Dialog Color: modules/dialog-color.md
-  #  - Dialog List: modules/dialog-list.md
-  #  - Dialog Menu: modules/dialog-menu.md
-  #  - Dialog Progress: modules/dialog-progress.md
-  #  - Dialog Billing: modules/dialog-billing.md
-  #- Advanced:
-  #  - Dialog Styles: advanced/styles.md
-  #  - Events: advanced/events.md
-  #  - Buttons: advanced/buttons.md
-  #  - Options: advanced/options.md
-  #  - Custom Dialog: advanced/custom-dialog.md
-  #- Migration:
-  #  - Version 2: migration/v2.md
+  - Modules:
+    - Core: modules/core.md
+    - State Saver Preferences: modules/statesaver-preferences.md
+    - State Saver KotPreferences: modules/statesaver-kotpreferences.md
+  - Advanced:
+    - Gradle Plugin: advanced/gradle-plugin.md
   - More:
     - Other Libraries: other-libraries.md
     - About Me: me.md

gradle/libs.versions.toml

@@ -4,7 +4,7 @@ gradle = 				        "8.7.3"
 kotlin = 				        "2.1.0"
 dokka =                         "1.9.20"
 gradle-maven-publish-plugin =   "0.30.0"
-compose =                       "1.7.1"
+compose =                       "1.7.3"
 
 [plugins]
 

library/core/build.gradle.kts

@@ -1,7 +1,6 @@
 import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.KotlinMultiplatform
 import com.vanniktech.maven.publish.SonatypeHost
-import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
@@ -43,7 +42,6 @@ kotlin {
     // Android
     androidTarget {
         publishLibraryVariants("release")
-        @OptIn(ExperimentalKotlinGradlePluginApi::class)
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_17)
         }

library/modules/statesaver/kotpreferences/build.gradle.kts

@@ -1,7 +1,6 @@
 import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.KotlinMultiplatform
 import com.vanniktech.maven.publish.SonatypeHost
-import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
@@ -41,7 +40,6 @@ kotlin {
     // Android
     androidTarget {
         publishLibraryVariants("release")
-        @OptIn(ExperimentalKotlinGradlePluginApi::class)
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_17)
         }

library/modules/statesaver/preferences/build.gradle.kts

@@ -1,7 +1,6 @@
 import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.KotlinMultiplatform
 import com.vanniktech.maven.publish.SonatypeHost
-import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
@@ -41,7 +40,6 @@ kotlin {
     // Android
     androidTarget {
         publishLibraryVariants("release")
-        @OptIn(ExperimentalKotlinGradlePluginApi::class)
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_17)
         }