Multiplatform progress bar rewrite

.github/workflows/build.yml

@@ -1,4 +1,4 @@
-name: Test and Publish
+name: Build
 
 on:
   pull_request:
@@ -37,6 +37,7 @@ jobs:
         with:
           arguments: |
             :mordant:check
+            :extensions:mordant-coroutines:jvmTest
             :test:proguard:r8jar
             ${{matrix.EXTRA_GRADLE_ARGS}}
             --stacktrace

CHANGELOG.md

@@ -1,13 +1,31 @@
 # Changelog
 
+## Unreleased
+### Added
+- New implementation of progress bars with a number of improvements:
+  - Any widget can be added to a progress layout, not just the built-in cell types
+  - TODO New cell: timeElapsed
+  - Added `compact` style to `timeRemaining` cells.
+  - Added `marquee` cell that can scroll text that is larger than a fixed width. 
+- Added `Viewport` widget that can crop or pad another widget to a fixed size, and scroll it within that size.
+- Added `precision` parameter to `completed` progress cell that controls the number of decimal places shown.
+- Animation now handle terminal resizing, although on some terminals, partially drawn frames may be visible. Due to a bug in JNI, the terminal size isn't automatically updated on JVM on macOS.
+- Added `TableBuilder.addPaddingWidthToFixedWidth` option to control how padding is added to fixed width columns.
+
+### Changed
+- Animations now never add a trailing newline while they're running. They always add one once the animation is stopped. The `trailNewline` parameter is deprecated. This allows full screen animations without a blank line at the bottom. 
+
+### Fixed
+- Vertical layout now correctly pads non-text cells when `align` is set to `TextAlign.LEFT`
+
 ## 2.3.0
 ### Added
 - Vararg constructors for `UnorderedList` and `OrderedList`
-- `UnorderedList` and `OrderedList` now support being empty 
+- `UnorderedList` and `OrderedList` now support being empty
 - Added optional terminal frame to `TerminalRecorder.outputAsHtml`
 
 ### Changed
-- When setting conflicting styles on a `Table` or its cells, the innermost style now takes precedence (i.e. if you set different styles on the whole table and a cell, the style applied to the cell will be used). 
+- When setting conflicting styles on a `Table` or its cells, the innermost style now takes precedence (i.e. if you set different styles on the whole table and a cell, the style applied to the cell will be used).
 
 ### Fixed
 - Updated bundled proguard rules [(#130)](https://github.com/ajalt/mordant/issues/130)

build.gradle.kts

@@ -1,9 +1,24 @@
+import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
+import org.jetbrains.dokka.gradle.DokkaTask
+
 plugins {
     alias(libs.plugins.kotlinBinaryCompatibilityValidator)
+    id("org.jetbrains.dokka")
 }
 
 apiValidation {
     // https://github.com/Kotlin/binary-compatibility-validator/issues/3
     project("samples").subprojects.mapTo(ignoredProjects) { it.name }
     project("test").subprojects.mapTo(ignoredProjects) { it.name }
 }
+
+tasks.withType<DokkaMultiModuleTask>().configureEach {
+    outputDirectory.set(rootProject.rootDir.resolve("docs/api"))
+    pluginsMapConfiguration.set(
+        mapOf(
+            "org.jetbrains.dokka.base.DokkaBase" to """{
+                "footerMessage": "Copyright &copy; 2017 AJ Alt"
+            }"""
+        )
+    )
+}

buildSrc/src/main/kotlin/mordant-jvm-sample-conventions.gradle.kts

@@ -8,10 +8,8 @@ kotlin {
     jvm { withJava() }
 
     sourceSets {
-        val jvmMain by getting {
-            dependencies {
-                implementation(project(":mordant"))
-            }
+        jvmMain.dependencies {
+            implementation(project(":mordant"))
         }
     }
 }

buildSrc/src/main/kotlin/mordant-mpp-sample-conventions.gradle.kts

@@ -2,3 +2,11 @@ plugins {
     id("mordant-jvm-sample-conventions")
     id("mordant-native-sample-conventions")
 }
+
+kotlin {
+    sourceSets {
+        commonMain.dependencies {
+            implementation(project(":mordant"))
+        }
+    }
+}

buildSrc/src/main/kotlin/mordant-publishing-conventions.gradle.kts

@@ -4,6 +4,7 @@ import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.KotlinMultiplatform
 import com.vanniktech.maven.publish.SonatypeHost
 import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.dokka.gradle.DokkaTaskPartial
 import java.io.ByteArrayOutputStream
 
 plugins {
@@ -35,22 +36,13 @@ fun getPublishVersion(): String {
 mavenPublishing {
     project.setProperty("VERSION_NAME", getPublishVersion())
     pomFromGradleProperties()
-    configure(KotlinMultiplatform(JavadocJar.Dokka("dokkaHtml")))
+    configure(KotlinMultiplatform(JavadocJar.Dokka("dokkaHtmlPartial")))
     publishToMavenCentral(SonatypeHost.DEFAULT)
     signAllPublications()
 }
 
-tasks.named<DokkaTask>("dokkaHtml") {
-    outputDirectory.set(rootProject.rootDir.resolve("docs/api"))
-    pluginsMapConfiguration.set(
-        mapOf(
-            "org.jetbrains.dokka.base.DokkaBase" to """{
-                "footerMessage": "Copyright &copy; 2017 AJ Alt"
-            }"""
-        )
-    )
+tasks.withType<DokkaTaskPartial>().configureEach {
     dokkaSourceSets.configureEach {
-        reportUndocumented.set(false)
         skipDeprecated.set(true)
     }
 }

deploy_website.sh

@@ -9,7 +9,7 @@
 set -ex
 
 # Generate API docs
-./gradlew dokkaHtml
+./gradlew dokkaHtmlMultiModule
 
 # Copy the changelog into the site, omitting the unreleased section
 cat CHANGELOG.md \

docs/guide.md

@@ -370,61 +370,34 @@ t.cursor.hide(showOnExit = true)
 ## Animations
 
 You can animate any widget like a table with [Terminal.animation], or any regular
-string with [Terminal.textAnimation].
+string with [Terminal.textAnimation]. For progress bar animations, see [the docs on progress
+bars](progress.md).
 
 === "Code"
     ```kotlin
-    val t = Terminal()
-    val a = t.textAnimation<Int> { frame ->
+    val terminal = Terminal()
+    val a = terminal.textAnimation<Int> { frame ->
         (1..50).joinToString("") {
             val hue = (frame + it) * 3 % 360
             TextColors.hsv(hue, 1, 1)("━")
         }
     }
 
-    t.cursor.hide(showOnExit = true)
+    terminal.cursor.hide(showOnExit = true)
     repeat(120) {
         a.update(it)
         Thread.sleep(25)
     }
     ```
 
 === "Output"
-    ![](img/animation.svg)
-
-
-## Progress bars
-
-You can create customizable progress bars that automatically compute speed and time remaining.
-
-=== "Code"
-    ```kotlin
-    val t = Terminal()
-    val progress = t.progressAnimation {
-        text("my-file.iso")
-        percentage()
-        progressBar()
-        completed()
-        speed("B/s")
-        timeRemaining()
-    }
-    ```
-=== "Output"
-    <div style="border-radius: 8px;width: fit-content;padding: 0.5em 1em;filter: drop-shadow(0.5em 0.5em 0.5em black);background-color: rgb(12 12 12);">
-    <div style="margin: -0.5em 0px;font-size: 2em"><span style="color: #ff5f56;">●&nbsp;</span><span style="color: #ffbd2e">●&nbsp;</span><span style="color: #27c93f">●&nbsp;</span></div>
-    <pre style="font-family: monospace">
-    <span>my-file.iso</span><span> </span><span>83%</span><span> </span><span style="color: #61afef">━━━━━━</span><span style="color: #68b2f0">━</span><span style="color: #88c2f4">━</span><span style="color: #b9dbf9">━</span><span style="color: #e5f2fd">━</span><span style="color: #fcfeff">━━</span><span style="color: #e5f2fd">━</span><span style="color: #b9dbf9">━</span><span style="color: #88c2f4">━</span><span style="color: #68b2f0">━</span><span style="color: #61afef">━━</span><span> </span><span style="color: #5c6370">━━━</span><span> </span><span>25.0/30.0G</span><span> </span><span>71.2MB/s</span><span>  </span><span>eta</span><span> </span><span>0:01:10</span>
-    </pre>
-    </div>
 
-Call [progress.start] to animate the progress, and [progress.update] or [progress.advance] as your
-task completes.
+    ![](img/animation_text.gif)
 
-!!! note
-    The [progressAnimation] builder is currently JVM-only - see [issue #148](https://github.com/ajalt/mordant/issues/148).
-    On other platforms, you can still use `t.animation { progressLayout { ... } }` which will render the same widget, 
-    you'll just need to call [progress.build] manually.
+!!! tip
 
+    If you have an `animation<Unit>` or `textAnimation<Unit>`, you can refresh them automatically with
+    [animateOnThread] or [animateOnCoroutine].
 
 ## Prompting for input
 
@@ -464,6 +437,8 @@ creating a subclass of the [Prompt] class. Mordant includes [StringPrompt], [Yes
 [Text]:                     api/mordant/com.github.ajalt.mordant.widgets/-text/index.html
 [Whitespace]:               api/mordant/com.github.ajalt.mordant.rendering/-whitespace/index.html
 [YesNoPrompt]:              api/mordant/com.github.ajalt.mordant.terminal/-yes-no-prompt/index.html
+[animateOnCoroutine]:       api/extensions/mordant-coroutines/com.github.ajalt.mordant.animation.coroutines/animate-in-coroutine.html
+[animateOnThread]:          api/mordant/com.github.ajalt.mordant.animation.progress/animate-on-thread.html
 [color.bg]:                 api/mordant/com.github.ajalt.mordant.rendering/-text-style/bg.html
 [color.on]:                 api/mordant/com.github.ajalt.mordant.rendering/-text-style/on.html
 [cursor]:                   api/mordant/com.github.ajalt.mordant.terminal/-terminal/cursor.html