From 8395390a222ee7faf3388aa485b643cbf729fe74 Mon Sep 17 00:00:00 2001
From: Nikita Klimenko <nikita.klimenko@jetbrains.com>
Date: Wed, 3 Dec 2025 17:03:14 +0200
Subject: [PATCH] Expand HTML rendering documentation

---
 .../kotlinx/dataframe/samples/api/Render.kt   |  48 ---
 docs/StardustDocs/topics/toHTML.md            | 231 ++++++++++++++-
 samples/build.gradle.kts                      |   1 +
 .../kotlinx/dataframe/samples/api/Render.kt   | 273 ++++++++++++++++++
 4 files changed, 502 insertions(+), 51 deletions(-)
 delete mode 100644 core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt
 create mode 100644 samples/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt

diff --git a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt
deleted file mode 100644
index 61e10476f1..0000000000
--- a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt
+++ /dev/null
@@ -1,48 +0,0 @@
-@file:Suppress("ktlint")
-
-package org.jetbrains.kotlinx.dataframe.samples.api
-
-import org.jetbrains.kotlinx.dataframe.api.reorderColumnsByName
-import org.jetbrains.kotlinx.dataframe.api.sortBy
-import org.jetbrains.kotlinx.dataframe.api.sortByDesc
-import org.jetbrains.kotlinx.dataframe.explainer.TransformDataFrameExpressions
-import org.jetbrains.kotlinx.dataframe.io.DataFrameHtmlData
-import org.jetbrains.kotlinx.dataframe.io.DisplayConfiguration
-import org.jetbrains.kotlinx.dataframe.io.toHtml
-import org.jetbrains.kotlinx.dataframe.io.toStandaloneHtml
-import org.junit.Ignore
-import org.junit.Test
-import java.io.File
-import kotlin.io.path.Path
-
-class Render : TestBase() {
-    @Test
-    @TransformDataFrameExpressions
-    @Ignore
-    fun useRenderingResult() {
-        // SampleStart
-        df.toStandaloneHtml(DisplayConfiguration(rowsLimit = null)).openInBrowser()
-        df.toStandaloneHtml(DisplayConfiguration(rowsLimit = null)).writeHtml(File("/path/to/file"))
-        df.toStandaloneHtml(DisplayConfiguration(rowsLimit = null)).writeHtml(Path("/path/to/file"))
-        // SampleEnd
-    }
-
-    @Test
-    fun composeTables() {
-        // SampleStart
-        val df1 = df.reorderColumnsByName()
-        val df2 = df.sortBy { age }
-        val df3 = df.sortByDesc { age }
-
-        listOf(df1, df2, df3).fold(DataFrameHtmlData.tableDefinitions()) { acc, df -> acc + df.toHtml() }
-        // SampleEnd
-    }
-
-    @Test
-    @TransformDataFrameExpressions
-    fun configureCellOutput() {
-        // SampleStart
-        df.toHtml(DisplayConfiguration(cellContentLimit = -1))
-        // SampleEnd
-    }
-}
diff --git a/docs/StardustDocs/topics/toHTML.md b/docs/StardustDocs/topics/toHTML.md
index 89baa91269..e83fbb4813 100644
--- a/docs/StardustDocs/topics/toHTML.md
+++ b/docs/StardustDocs/topics/toHTML.md
@@ -2,6 +2,8 @@
 
 <!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Render-->
 
+## HTML rendering
+
 `DataFrame` instances can be rendered to HTML.
 Rendering of hierarchical tables in HTML is supported by JS and CSS definitions
 that can be found in project resources.
@@ -9,6 +11,212 @@ that can be found in project resources.
 Dataframes can also be formatted before being converted to HTML.
 See [](format.md) for how to do this.
 
+Besides that, DataFrame provides multiple APIs to customize HTML output.
+
+### Display images
+Values of the `org.jetbrains.kotlinx.dataframe.datatypes.IMG` class are rendered as an `<img>` tag
+
+<!---FUN displayImg-->
+
+```kotlin
+val htmlData = dataFrameOf(
+    "kotlinLogo" to columnOf(
+        IMG("https://kotlin.github.io/dataframe/images/kotlin-logo.svg"),
+    ),
+).toStandaloneHtml()
+```
+
+<!---END-->
+
+### Embed pages
+
+Values of the `org.jetbrains.kotlinx.dataframe.datatypes.IFRAME` class are rendered as an `<iframe>` tag
+
+<!---FUN displayIFrame-->
+
+```kotlin
+val htmlData = dataFrameOf(
+    "documentationPages" to columnOf(
+        IFRAME(
+            src = "https://kotlin.github.io/dataframe/tohtml.html",
+            width = 850,
+            height = 500,
+        ),
+    ),
+).toStandaloneHtml()
+```
+
+<!---END-->
+
+### Render clickable links
+
+Values of `java.net.URL` are rendered as `<a>` tag
+
+<!---FUN displayURL-->
+
+```kotlin
+val htmlData = dataFrameOf(
+    "documentationPages" to columnOf(
+        URI("https://kotlin.github.io/dataframe/format.html").toURL(),
+        URI("https://kotlin.github.io/dataframe/tohtml.html").toURL(),
+        URI("https://kotlin.github.io/dataframe/jupyterrendering.html").toURL(),
+    ),
+).toStandaloneHtml()
+```
+
+<!---END-->
+
+### Render any HTML inside a cell
+
+Wrap cell values in custom HTML using `RenderedContent.media`
+
+<!---FUN displayMediaContent-->
+<tabs>
+<tab title="Properties">
+
+```kotlin
+val htmlData = dataFrameOf(
+    "documentationPages" to columnOf(
+        "https://kotlin.github.io/dataframe/format.html",
+        "https://kotlin.github.io/dataframe/tohtml.html",
+        "https://kotlin.github.io/dataframe/jupyterrendering.html",
+    ),
+)
+    .convert { documentationPages }.with {
+        val uri = URI(it)
+        RenderedContent.media("""<a href='$uri'>${uri.path}</a>""")
+    }
+    .toStandaloneHtml()
+```
+
+</tab>
+<tab title="Strings">
+
+```kotlin
+val htmlData = dataFrameOf(
+    "documentationPages" to columnOf(
+        "https://kotlin.github.io/dataframe/format.html",
+        "https://kotlin.github.io/dataframe/tohtml.html",
+        "https://kotlin.github.io/dataframe/jupyterrendering.html",
+    ),
+)
+    .convert { "documentationPages"<String>() }.with {
+        val uri = URI(it)
+        RenderedContent.media("""<a href='$uri'>${uri.path}</a>""")
+    }
+    .toStandaloneHtml()
+```
+
+</tab></tabs>
+<!---END-->
+
+### Sample data 
+This dataframe is used in the following examples
+
+<!---FUN df-->
+
+```kotlin
+val df = dataFrameOf(
+    "name" to columnOf(
+        "firstName" to columnOf("Alice", "Bob", "Charlie", "Charlie", "Bob", "Alice", "Charlie"),
+        "lastName" to columnOf("Cooper", "Dylan", "Daniels", "Chaplin", "Marley", "Wolf", "Byrd"),
+    ),
+    "age" to columnOf(15, 45, 20, 40, 30, 20, 30),
+    "city" to columnOf("London", "Dubai", "Moscow", "Milan", "Tokyo", null, "Moscow"),
+    "weight" to columnOf(54, 87, null, null, 68, 55, 90),
+    "isHappy" to columnOf(true, true, false, true, true, false, true),
+)
+```
+
+<!---END-->
+
+### Reusable rendering logic
+
+Generic approach to custom cell rendering. Useful if you want to apply the same rendering to different dataframes.
+
+<!---FUN cellRenderer-->
+
+```kotlin
+class CustomArrayCellRenderer : ChainedCellRenderer(DefaultCellRenderer) {
+    override fun maybeContent(value: Any?, configuration: DisplayConfiguration): RenderedContent? {
+        if (value is Boolean) {
+            return RenderedContent.text(if (value) "✓" else "✗")
+        }
+        // return null to delegate work to parent renderer: DefaultCellRenderer
+        return null
+    }
+
+    override fun maybeTooltip(value: Any?, configuration: DisplayConfiguration): String? {
+        // return null to delegate work to parent renderer: DefaultCellRenderer
+        return null
+    }
+}
+
+val htmlData = df.toStandaloneHtml(cellRenderer = CustomArrayCellRenderer())
+```
+
+<!---END-->
+
+### Custom HTML outside the table
+
+The result of `toHtml` can be composed with other HTML, CSS, or JS definitions.
+Let's build an alternative to displaying all rows in one table: custom pagination across multiple files
+
+<!---FUN appendCustomHtml-->
+
+```kotlin
+val pages = df.duplicateRows(10).chunked(20)
+val files = pages.indices.map { i -> File("page$i.html") }
+val navLinks = files.mapIndexed { i, file ->
+    """<a href="${file.name}">Page ${i + 1}</a>"""
+}.joinToString(" | ")
+
+pages.forEachIndexed { i, page ->
+    val output = files[i]
+    page.toStandaloneHtml().plus(DataFrameHtmlData(body = navLinks))
+    // uncomment
+    // .writeHtml(output)
+}
+```
+
+<!---END-->
+
+### Custom style and scripts
+
+Let's add a hover effect and click listener for table cells.
+See [init.js](https://github.com/Kotlin/dataframe/blob/704200cb86e7bdc07b800a7cfef48de408bd5fe8/core/src/main/resources/init.js) and [table.css](https://github.com/Kotlin/dataframe/blob/ead4f8666df5cf24e5bf45d245cda3200e150e93/core/src/main/resources/table.css) for reference.
+
+<!---FUN interactiveJs-->
+
+```kotlin
+val selectCellInteraction = DataFrameHtmlData(
+    style =
+        """
+        td:hover {
+            background-color: rgba(0, 123, 255, 0.15);
+            cursor: pointer;
+        }
+        """.trimIndent(),
+    script =
+        """
+        (function() {
+            let cells = document.querySelectorAll('td');
+            cells.forEach(function(cell) {
+                cell.addEventListener('click', function(e) {
+                    let content = cell.textContent;
+                    alert(content);
+                });
+            });
+        })();
+        """.trimIndent(),
+)
+
+// keep in mind JS script initialization order.
+val htmlData = df.toStandaloneHtml().plus(selectCellInteraction)
+```
+
+<!---END-->
+
 Depending on your environment, there can be different ways to use the result of `toHtml` functions.
 
 ## IntelliJ IDEA
@@ -21,9 +229,10 @@ It can be displayed in the browser and has parameters for customization.
 <!---FUN useRenderingResult-->
 
 ```kotlin
-df.toStandaloneHtml(DisplayConfiguration(rowsLimit = null)).openInBrowser()
-df.toStandaloneHtml(DisplayConfiguration(rowsLimit = null)).writeHtml(File("/path/to/file"))
-df.toStandaloneHtml(DisplayConfiguration(rowsLimit = null)).writeHtml(Path("/path/to/file"))
+val configuration = DisplayConfiguration(rowsLimit = null)
+df.toStandaloneHtml(configuration).openInBrowser()
+df.toStandaloneHtml(configuration).writeHtml(File("/path/to/file"))
+df.toStandaloneHtml(configuration).writeHtml(Path("/path/to/file"))
 ```
 
 <!---END-->
@@ -35,6 +244,8 @@ which you can use to include additional scripts, elements,
 or styles at the end of the page or just to merge multiple tables into one HTML snippet.
 
 <!---FUN composeTables-->
+<tabs>
+<tab title="Properties">
 
 ```kotlin
 val df1 = df.reorderColumnsByName()
@@ -44,6 +255,20 @@ val df3 = df.sortByDesc { age }
 listOf(df1, df2, df3).fold(DataFrameHtmlData.tableDefinitions()) { acc, df -> acc + df.toHtml() }
 ```
 
+</tab>
+<tab title="Strings">
+
+```kotlin
+val df1 = df.reorderColumnsByName()
+val df2 = df.sortBy("age")
+val df3 = df.sortByDesc("age")
+
+listOf(df1, df2, df3).fold(DataFrameHtmlData.tableDefinitions()) { acc, df ->
+    acc + df.toHtml()
+}
+```
+
+</tab></tabs>
 <!---END-->
 
 ## Jupyter Notebooks
diff --git a/samples/build.gradle.kts b/samples/build.gradle.kts
index fb101a8441..9b766ee288 100644
--- a/samples/build.gradle.kts
+++ b/samples/build.gradle.kts
@@ -110,6 +110,7 @@ korro {
         include("docs/StardustDocs/topics/write.md")
         include("docs/StardustDocs/topics/rename.md")
         include("docs/StardustDocs/topics/format.md")
+        include("docs/StardustDocs/topics/toHTML.md")
         include("docs/StardustDocs/topics/guides/*.md")
         include("docs/StardustDocs/topics/operations/utils/*.md")
         include("docs/StardustDocs/topics/operations/multiple/*.md")
diff --git a/samples/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt b/samples/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt
new file mode 100644
index 0000000000..c5273d0110
--- /dev/null
+++ b/samples/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Render.kt
@@ -0,0 +1,273 @@
+package org.jetbrains.kotlinx.dataframe.samples.api
+
+import org.jetbrains.kotlinx.dataframe.AnyFrame
+import org.jetbrains.kotlinx.dataframe.api.chunked
+import org.jetbrains.kotlinx.dataframe.api.columnOf
+import org.jetbrains.kotlinx.dataframe.api.convert
+import org.jetbrains.kotlinx.dataframe.api.dataFrameOf
+import org.jetbrains.kotlinx.dataframe.api.duplicateRows
+import org.jetbrains.kotlinx.dataframe.api.forEachIndexed
+import org.jetbrains.kotlinx.dataframe.api.reorderColumnsByName
+import org.jetbrains.kotlinx.dataframe.api.sortBy
+import org.jetbrains.kotlinx.dataframe.api.sortByDesc
+import org.jetbrains.kotlinx.dataframe.api.with
+import org.jetbrains.kotlinx.dataframe.dataTypes.IFRAME
+import org.jetbrains.kotlinx.dataframe.dataTypes.IMG
+import org.jetbrains.kotlinx.dataframe.indices
+import org.jetbrains.kotlinx.dataframe.io.DataFrameHtmlData
+import org.jetbrains.kotlinx.dataframe.io.DisplayConfiguration
+import org.jetbrains.kotlinx.dataframe.io.toHtml
+import org.jetbrains.kotlinx.dataframe.io.toStandaloneHtml
+import org.jetbrains.kotlinx.dataframe.jupyter.ChainedCellRenderer
+import org.jetbrains.kotlinx.dataframe.jupyter.DefaultCellRenderer
+import org.jetbrains.kotlinx.dataframe.jupyter.RenderedContent
+import org.jetbrains.kotlinx.dataframe.samples.DataFrameSampleHelper
+import org.junit.Ignore
+import org.junit.Test
+import java.io.File
+import java.net.URI
+import kotlin.io.path.Path
+
+class Render : DataFrameSampleHelper("toHTML", "api") {
+
+    private val df: AnyFrame = dataFrameOf(
+        "name" to columnOf(
+            "firstName" to columnOf("Alice", "Bob", "Charlie", "Charlie", "Bob", "Alice", "Charlie"),
+            "lastName" to columnOf("Cooper", "Dylan", "Daniels", "Chaplin", "Marley", "Wolf", "Byrd"),
+        ),
+        "age" to columnOf(15, 45, 20, 40, 30, 20, 30),
+        "city" to columnOf("London", "Dubai", "Moscow", "Milan", "Tokyo", null, "Moscow"),
+        "weight" to columnOf(54, 87, null, null, 68, 55, 90),
+        "isHappy" to columnOf(true, true, false, true, true, false, true),
+    )
+
+    @Test
+    @Ignore
+    fun useRenderingResult() {
+        // SampleStart
+        val configuration = DisplayConfiguration(rowsLimit = null)
+        df.toStandaloneHtml(configuration).openInBrowser()
+        df.toStandaloneHtml(configuration).writeHtml(File("/path/to/file"))
+        df.toStandaloneHtml(configuration).writeHtml(Path("/path/to/file"))
+        // SampleEnd
+    }
+
+    @Test
+    fun composeTables_strings() {
+        val df = dataFrameOf(
+            "name" to columnOf(
+                "firstName" to columnOf("Alice", "Bob", "Charlie", "Charlie", "Bob", "Alice", "Charlie"),
+                "lastName" to columnOf("Cooper", "Dylan", "Daniels", "Chaplin", "Marley", "Wolf", "Byrd"),
+            ),
+            "age" to columnOf(15, 45, 20, 40, 30, 20, 30),
+            "city" to columnOf("London", "Dubai", "Moscow", "Milan", "Tokyo", null, "Moscow"),
+            "weight" to columnOf(54, 87, null, null, 68, 55, 90),
+            "isHappy" to columnOf(true, true, false, true, true, false, true),
+        )
+        // SampleStart
+        val df1 = df.reorderColumnsByName()
+        val df2 = df.sortBy("age")
+        val df3 = df.sortByDesc("age")
+
+        listOf(df1, df2, df3).fold(DataFrameHtmlData.tableDefinitions()) { acc, df ->
+            acc + df.toHtml()
+        }
+        // SampleEnd
+    }
+
+    @Test
+    fun composeTables_properties() {
+        val df = dataFrameOf(
+            "name" to columnOf(
+                "firstName" to columnOf("Alice", "Bob", "Charlie", "Charlie", "Bob", "Alice", "Charlie"),
+                "lastName" to columnOf("Cooper", "Dylan", "Daniels", "Chaplin", "Marley", "Wolf", "Byrd"),
+            ),
+            "age" to columnOf(15, 45, 20, 40, 30, 20, 30),
+            "city" to columnOf("London", "Dubai", "Moscow", "Milan", "Tokyo", null, "Moscow"),
+            "weight" to columnOf(54, 87, null, null, 68, 55, 90),
+            "isHappy" to columnOf(true, true, false, true, true, false, true),
+        )
+        // SampleStart
+        val df1 = df.reorderColumnsByName()
+        val df2 = df.sortBy { age }
+        val df3 = df.sortByDesc { age }
+
+        listOf(df1, df2, df3).fold(DataFrameHtmlData.tableDefinitions()) { acc, df -> acc + df.toHtml() }
+        // SampleEnd
+    }
+
+    @Test
+    fun configureCellOutput() {
+        // SampleStart
+        df.toHtml(DisplayConfiguration(cellContentLimit = -1))
+        // SampleEnd
+    }
+
+    @Test
+    fun displayImg() {
+        // SampleStart
+        val htmlData = dataFrameOf(
+            "kotlinLogo" to columnOf(
+                IMG("https://kotlin.github.io/dataframe/images/kotlin-logo.svg"),
+            ),
+        ).toStandaloneHtml()
+        // SampleEnd
+        // .openInBrowser()
+    }
+
+    @Test
+    fun displayIFrame() {
+        // SampleStart
+        val htmlData = dataFrameOf(
+            "documentationPages" to columnOf(
+                IFRAME(
+                    src = "https://kotlin.github.io/dataframe/tohtml.html",
+                    width = 850,
+                    height = 500,
+                ),
+            ),
+        ).toStandaloneHtml()
+        // SampleEnd
+        // .openInBrowser()
+    }
+
+    @Test
+    fun displayURL() {
+        // SampleStart
+        val htmlData = dataFrameOf(
+            "documentationPages" to columnOf(
+                URI("https://kotlin.github.io/dataframe/format.html").toURL(),
+                URI("https://kotlin.github.io/dataframe/tohtml.html").toURL(),
+                URI("https://kotlin.github.io/dataframe/jupyterrendering.html").toURL(),
+            ),
+        ).toStandaloneHtml()
+        // SampleEnd
+        // .openInBrowser()
+    }
+
+    @Test
+    fun displayMediaContent_strings() {
+        // SampleStart
+        val htmlData = dataFrameOf(
+            "documentationPages" to columnOf(
+                "https://kotlin.github.io/dataframe/format.html",
+                "https://kotlin.github.io/dataframe/tohtml.html",
+                "https://kotlin.github.io/dataframe/jupyterrendering.html",
+            ),
+        )
+            .convert { "documentationPages"<String>() }.with {
+                val uri = URI(it)
+                RenderedContent.media("""<a href='$uri'>${uri.path}</a>""")
+            }
+            .toStandaloneHtml()
+        // SampleEnd
+        // .openInBrowser()
+    }
+
+    @Test
+    fun displayMediaContent_properties() {
+        // SampleStart
+        val htmlData = dataFrameOf(
+            "documentationPages" to columnOf(
+                "https://kotlin.github.io/dataframe/format.html",
+                "https://kotlin.github.io/dataframe/tohtml.html",
+                "https://kotlin.github.io/dataframe/jupyterrendering.html",
+            ),
+        )
+            .convert { documentationPages }.with {
+                val uri = URI(it)
+                RenderedContent.media("""<a href='$uri'>${uri.path}</a>""")
+            }
+            .toStandaloneHtml()
+        // SampleEnd
+        // .openInBrowser()
+    }
+
+    @Test
+    fun cellRenderer() {
+        // SampleStart
+        class CustomArrayCellRenderer : ChainedCellRenderer(DefaultCellRenderer) {
+            override fun maybeContent(value: Any?, configuration: DisplayConfiguration): RenderedContent? {
+                if (value is Boolean) {
+                    return RenderedContent.text(if (value) "✓" else "✗")
+                }
+                // return null to delegate work to parent renderer: DefaultCellRenderer
+                return null
+            }
+
+            override fun maybeTooltip(value: Any?, configuration: DisplayConfiguration): String? {
+                // return null to delegate work to parent renderer: DefaultCellRenderer
+                return null
+            }
+        }
+
+        val htmlData = df.toStandaloneHtml(cellRenderer = CustomArrayCellRenderer())
+        // SampleEnd
+        // .openInBrowser()
+    }
+
+    @Test
+    fun df() {
+        // SampleStart
+        val df = dataFrameOf(
+            "name" to columnOf(
+                "firstName" to columnOf("Alice", "Bob", "Charlie", "Charlie", "Bob", "Alice", "Charlie"),
+                "lastName" to columnOf("Cooper", "Dylan", "Daniels", "Chaplin", "Marley", "Wolf", "Byrd"),
+            ),
+            "age" to columnOf(15, 45, 20, 40, 30, 20, 30),
+            "city" to columnOf("London", "Dubai", "Moscow", "Milan", "Tokyo", null, "Moscow"),
+            "weight" to columnOf(54, 87, null, null, 68, 55, 90),
+            "isHappy" to columnOf(true, true, false, true, true, false, true),
+        )
+        // SampleEnd
+    }
+
+    @Test
+    fun appendCustomHtml() {
+        // SampleStart
+        val pages = df.duplicateRows(10).chunked(20)
+        val files = pages.indices.map { i -> File("page$i.html") }
+        val navLinks = files.mapIndexed { i, file ->
+            """<a href="${file.name}">Page ${i + 1}</a>"""
+        }.joinToString(" | ")
+
+        pages.forEachIndexed { i, page ->
+            val output = files[i]
+            page.toStandaloneHtml().plus(DataFrameHtmlData(body = navLinks))
+            // uncomment
+            // .writeHtml(output)
+        }
+        // SampleEnd
+    }
+
+    @Test
+    fun interactiveJs() {
+        // SampleStart
+        val selectCellInteraction = DataFrameHtmlData(
+            style =
+                """
+                td:hover {
+                    background-color: rgba(0, 123, 255, 0.15);
+                    cursor: pointer;
+                }
+                """.trimIndent(),
+            script =
+                """
+                (function() {
+                    let cells = document.querySelectorAll('td');
+                    cells.forEach(function(cell) {
+                        cell.addEventListener('click', function(e) {
+                            let content = cell.textContent;
+                            alert(content);
+                        });
+                    });
+                })();
+                """.trimIndent(),
+        )
+
+        // keep in mind JS script initialization order.
+        val htmlData = df.toStandaloneHtml().plus(selectCellInteraction)
+        // SampleEnd
+        // .openInBrowser()
+    }
+}