Merge pull request #378 from mikepenz/develop

dev -> main

Author: mikepenz

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        os: [ macos-14 ]
+        os: [ macos-latest ]
 
     runs-on: ${{matrix.os}}
 
@@ -62,7 +62,7 @@ jobs:
 
   build:
     name: Build
-    runs-on: macos-14
+    runs-on: macos-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -86,17 +86,17 @@ jobs:
       - name: Build Debug
         run: |
           ./gradlew clean || true
-          ./gradlew app:assembleDebug --stacktrace
+          ./gradlew sample:android:assembleDebug --stacktrace
 
       - name: Run Tests
         run: |
-          ./gradlew app:validateDebugScreenshotTest
+          ./gradlew sample:android:validateDebugScreenshotTest
 
       - name: Publish Test Report
         if: (failure() || success()) && github.event_name == 'pull_request'
         uses: mikepenz/action-junit-report@v5
         with:
-          report_paths: '**/app/build/test-results/validateDebugScreenshotTest/TEST-*.xml'
+          report_paths: '**/sample/android/build/test-results/validateDebugScreenshotTest/TEST-*.xml'
           github_token: ${{ secrets.GITHUB_TOKEN }}
           fail_on_failure: true
           annotate_only: true
@@ -106,9 +106,9 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: "Test-Artifacts"
-          path: "app/build/reports/screenshotTest/preview/debug/"
+          path: "sample/android/build/reports/screenshotTest/preview/debug/"
 
-      - name: Aoi Check
+      - name: Api Check
         if: github.event_name  == 'pull_request'
         run: ./gradlew apiCheck
 
@@ -135,11 +135,11 @@ jobs:
         if: startsWith(github.ref, 'refs/tags/')
         run: |
           echo "${{ secrets.KEYSTORE }}" > opensource.jks.asc
-          gpg -d --passphrase "${{ secrets.KEYSTORE_PASSPHRASE }}" --batch "opensource.jks.asc" > "app/opensource.jks"
+          gpg -d --passphrase "${{ secrets.KEYSTORE_PASSPHRASE }}" --batch "opensource.jks.asc" > "sample/android/opensource.jks"
 
       - name: Build Release App
         if: startsWith(github.ref, 'refs/tags/')
-        run: ./gradlew app:assembleRelease app:bundleRelease -P"com.mikepenz.android.signing.enabled"="true" -P"com.mikepenz.android.signing.storeFile"="opensource.jks" -P"com.mikepenz.android.signing.storePassword"="${{ secrets.STORE_PASSWORD }}" -P"com.mikepenz.android.signing.keyAlias"="${{ secrets.KEY_ALIAS }}" -P"com.mikepenz.android.signing.keyPassword"="${{ secrets.KEY_PASSWORD }}"
+        run: ./gradlew sample:android:assembleRelease sample:android:bundleRelease -P"com.mikepenz.android.signing.enabled"="true" -P"com.mikepenz.android.signing.storeFile"="opensource.jks" -P"com.mikepenz.android.signing.storePassword"="${{ secrets.STORE_PASSWORD }}" -P"com.mikepenz.android.signing.keyAlias"="${{ secrets.KEY_ALIAS }}" -P"com.mikepenz.android.signing.keyPassword"="${{ secrets.KEY_PASSWORD }}"
 
       - name: Collect artifacts
         if: startsWith(github.ref, 'refs/tags/')

.github/workflows/static.yml

@@ -43,12 +43,12 @@ jobs:
         uses: gradle/actions/setup-gradle@v4
       - name: Build Page
         run: |
-          ./gradlew app-wasm:wasmJsBrowserDistribution --no-configuration-cache
+          ./gradlew sample:web:wasmJsBrowserDistribution --no-configuration-cache
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: 'app-wasm/build/dist/wasmJs/productionExecutable'
+          path: 'sample/web/build/dist/wasmJs/productionExecutable'
 
       - name: Deploy to GitHub Pages
         id: deployment

.gitignore

@@ -43,3 +43,6 @@ captures/
 # Generated podspec
 *.podspec
 /.kotlin/
+
+## User settings
+xcuserdata/

CONTRIBUTORS.md

@@ -1,2 +1,2 @@
-Multiplatform Markdown Renderer contributors (sorted alphabeticaly)
+Multiplatform Markdown Renderer contributors (sorted alphabetically)
 ============================================

MIGRATION.md

@@ -1 +1,100 @@
 ### Upgrade Notes
+
+#### Version 0.33.0
+
+- **Dependency Upgrade**: Kotlin 2.1.20
+- **Breaking Change**: The provided `Markdown` (String) is now parsed asynchronously.
+    - This results in a `loading` state being displayed prior to the parsing result.
+        - While the `rememberMarkdownState` offers the ability to require `immediate` parsing as
+          before, this is not advised as it might block the composition of the UI.
+    - A new `loading` and `error` composable can be provided to handle the different states
+    - A new `success` composable was also introduced to modify success states (See more on the lazy
+      handling)
+    - The `linkDefinition` component was deprecated in favor of the new link lookup ahead of time
+    - Accompanying this change, a new `rememberMarkdownState` was introduced to retrieve a hoisted
+      observable state from the markdown.
+        - This offers greater flexibility and allows custom state handling.
+
+```kotlin
+val markdownState = rememberMarkdownState(MARKDOWN)
+Markdown(markdownState = markdownState)
+
+// exposes the general state:
+markdownState.state
+
+// exposes found link definitions and links
+markdownState.links
+```
+
+- **Breaking Change**: The `MarkdownComponent` composable function no longer passes on a
+  `ColumnScope`
+    - This change was made to allow for more flexibility in the layout of the markdown components.
+    - The `ColumnScope` wasn't used by the library before, and prevented use cases like
+      `LazyColumn`.
+    - If you have implemented your own `MarkdownComponent` depending on this, you will need to
+      remove the `ColumnScope` parameter from your implementation, and wrap the component in a
+      `Column {}` directly.
+    - Thanks to this change a new `LazyMarkdownSuccess` composable was introduced to allow
+      rendering very long markdown content as `LazyColumn` instead of a `Column`
+
+```kotlin
+Markdown(
+    markdownState = markdownState,
+    success = { state, components, modifier ->
+        LazyMarkdownSuccess(state, components, modifier, contentPadding = PaddingValues(16.dp))
+    },
+    modifier = Modifier.fillMaxSize()
+)
+```
+
+- **Breaking Change**: The `level` argument for `MarkdownOrderedList` and `MarkdownBulletList` were
+  renamed to `depth`.
+- **Breaking Change**: The `MarkdownListItems` component was refactored rendering nested
+  Ordered/Unordered lists using the `MarkdownComponents` as defined.
+    - As a result the component spec now needs to handle depth.
+      See [Source](https://github.com/keta1/multiplatform-markdown-renderer/blob/develop/multiplatform-markdown-renderer/src/commonMain/kotlin/com/mikepenz/markdown/compose/components/MarkdownComponents.kt#L201-L208)
+      for details.
+- **Breaking Change**: The `MarkdownListItems` component now takes 2 optional lambdas
+    - These lambdas offer the ability to provide custom `Modifier`s for the marker and the list
+      content.
+    - This can be helpful for example to adjust the baseline.
+      See: https://github.com/mikepenz/multiplatform-markdown-renderer/issues/329
+- **Breaking Change**: The `BulletHandler` adds a new argument in the function `listNumber: Int`.
+    - This was introduced to allow for more flexibility in the rendering of the bullet points.
+    - But also specifically to enable list rendering according to spec:
+        - https://spec.commonmark.org/0.31.2/#start-number
+    - The `index` argument was retained to allow custom implementations adjust this behavior.
+
+- **Behavior Change**: To account for the behavior change introduced in v0.32.0 on EOL handling a
+  new API was introduced to bring back prior behavior
+
+```kotlin
+annotator = markdownAnnotator(
+    config = markdownAnnotatorConfig(
+        eolAsNewLine = true
+    )
+)
+```
+
+#### Version 0.32.0
+
+- **Breaking Change**: The `MarkdownTypography` interface introduces the `table` property.
+    - This property is used to define the typography for tables in markdown.
+    - If you have implemented your own `MarkdownTypography`, you will need to add the `table`
+      property to your implementation.
+- **Breaking Change**: The `BulletHandler` function has been updated to include another argument
+  `depth`
+    - This property can be used to use a different `bullet style` for different levels of depth.
+- **Behavior Change**: `EOL`is now considered a `' '` whitespace character instead of a line break.
+    - This change was made to align more properly with the markdown standard
+    - More details: https://github.com/mikepenz/multiplatform-markdown-renderer/issues/337
+- **Behavior Change**: The primary definition for text color of components is now in the
+  `MarkdownTypography` text styles.
+    - This change was made to have a more consistent definition of text colors across all
+      components.
+
+#### Prior release
+
+Unfortunately no upgrade notes were provided for the releases prior to 0.32.0.
+See the release notes available on GitHub for more
+details: https://github.com/mikepenz/multiplatform-markdown-renderer/releases

README.md

@@ -113,6 +113,24 @@ Markdown(markdown)
 <details><summary><b>Advanced Usage</b></summary>
 <p>
 
+### `rememberMarkdownState`
+
+```kotlin
+val markdownState = rememberMarkdownState(markdown)
+Markdown(markdownState)
+```
+
+### Parse Markdown in VM
+
+```kotlin
+// In the VM setup the flow to parse the markdown
+val markdownFlow = parseMarkdownFlow("# Markdown")
+
+// In the Composable use the flow
+val state by markdownFlow.collectAsStateWithLifecycle(State.Loading())
+Markdown(state)
+```
+
 The library offers the ability to modify different behaviour when rendering the markdown.
 
 ### Provided custom style
@@ -138,7 +156,7 @@ Markdown(
             /** No animation */
         }
     ),
-}
+)
 ```
 
 ### Extended spans
@@ -250,7 +268,7 @@ Another example to of a custom component is changing the rendering of an unorder
 // Define a custom component for rendering unordered list items in Markdown
 val customUnorderedListComponent: MarkdownComponent = {
     // Use the MarkdownListItems composable to render the list items
-    MarkdownListItems(it.content, it.node, level = 0) { index, child ->
+    MarkdownListItems(it.content, it.node, level = 0) { startNumber, index, child ->
         // Render an icon for the bullet point with a green tint
         Icon(
             imageVector = icon,
@@ -291,49 +309,44 @@ Markdown(markdown)
 
 ### Image Loading
 
-Starting with 0.21.0 the library does not include image loading by default, however exposes 2
-modules for either coil2 or coil3 dependencies.
-The chosen image transformer implementation has to be passed to the `Markdown` API.
+To configure image loading, the library offers different implementations, to offer great flexibility
+for the respective integration.
+After adding the dependency, the chosen image transformer implementation has to be passed to the
+`Markdown` API.
 
-#### coil2
+> [!NOTE]  
+> Please refer to the official documentation for the specific image loading integration you are
+> using (e.g., coil3) on how to adjust its
+> behavior.
+
+#### coil3
 
 ```groovy
-// Offers coil2 (Coil2ImageTransformerImpl)
-implementation("com.mikepenz:multiplatform-markdown-renderer-coil2:${version}")
+// Offers coil3 (Coil3ImageTransformerImpl)
+implementation("com.mikepenz:multiplatform-markdown-renderer-coil3:${version}")
 ```
 
 ```kotlin
 Markdown(
     MARKDOWN,
-    imageTransformer = Coil2ImageTransformerImpl,
+    imageTransformer = Coil3ImageTransformerImpl,
 )
 ```
 
-> [!NOTE]
-> 0.21.0 adds JVM support for this dependency via `HTTPUrlConnection` -> however this is expected to
-> be removed in the
-> future.
-
-> [!NOTE]  
-> Please refer to the official coil2 documentation on how to adjust the `ImageLoader`
-
-#### coil3
+#### coil2
 
 ```groovy
-// Offers coil3 (Coil3ImageTransformerImpl)
-implementation("com.mikepenz:multiplatform-markdown-renderer-coil3:${version}")
+// Offers coil2 (Coil2ImageTransformerImpl)
+implementation("com.mikepenz:multiplatform-markdown-renderer-coil2:${version}")
 ```
 
 ```kotlin
 Markdown(
     MARKDOWN,
-    imageTransformer = Coil3ImageTransformerImpl,
+    imageTransformer = Coil2ImageTransformerImpl,
 )
 ```
 
-> [!NOTE]  
-> Please refer to the official coil3 documentation on how to adjust the `SingletonImageLoader`
-
 ### Syntax Highlighting
 
 The library (introduced with 0.27.0) offers optional support for syntax highlighting via
@@ -422,7 +435,7 @@ Version 2.0.
 
 ## License
 
-    Copyright 2024 Mike Penz
+    Copyright 2025 Mike Penz
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.