format kdocs++

[Jolanrensen]

Fixes #1280
Fixes #251 (I needed it in the example :) )

• Adds full KDocs and grammar for format
• Breaking change! Renamed FormatDSL to FormatDsl, and RGBColor to RgbColor, following API names should follow CamelCase rules #509 before 1.0 is fully released, as it will be considerably more harmful to do later. Cannot go through deprecation cycle unfortunately.
• Adds at(), and notNull() to format, similar to update, because they seem useful.
• Fixed where filters to add to previous ones instead of overwriting the filter, similar to update
• Fixed KDocs for Update.notNull() because I completely misunderstood how it worked when I wrote the original KDocs
• Bumped Kandy version to include Kotlin/kandy@2fbddba; support for FormattedFrame "sample dataframes" on the website
• Wrote documentation for format on the website including the full grammar and examples :)
• Adds JUnit tests for format

#1356 and #1354 were discovered but can be done later.

[Copilot]

Pull Request Overview

This pull request enhances the format operation for DataFrame rendering with comprehensive KDocs, breaking changes, and new functionality. The main purpose is to provide full documentation and API improvements for the format DSL before the 1.0 release.

• Adds comprehensive KDocs and grammar documentation for the format operation
• Introduces a breaking change by renaming FormatDSL to FormatDsl following project conventions
• Adds new convenience methods at() and notNull() to the format operation, similar to the update operation

Reviewed Changes

Copilot reviewed 35 out of 47 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt	New test file with format operation examples demonstrating various formatting scenarios
tests/build.gradle.kts	Updates Kandy dependencies and excludes dataframe dependency, adds format.md to documentation
gradle/libs.versions.toml	Bumps Kandy version to include FormattedFrame support
docs/StardustDocs/topics/format.md	New comprehensive documentation page for the format operation with examples and grammar
docs/StardustDocs/topics/toHTML.md	Updates HTML rendering documentation to reference format operation
docs/StardustDocs/topics/rendering.md	Updates rendering section to include format operation documentation
Multiple HTML snippet files	Updates to HTML output files with additional CSS properties for improved text color handling

Comments suppressed due to low confidence (1)

docs/StardustDocs/topics/format.md:3

• The TODO comment should be removed since the documentation has been completed in this PR.

<!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->

[koperagen]

Maybe add a deprecated type aliases for FormattingDSL and RGBColor?

[Jolanrensen]

That could help with source-compatibility indeed :) Unfortunately binary compatibility will always break because we use FormattingDsl as receiver in a lamda.
I'll add them

[koperagen]

While we do have this function, using it is worrisome. We calculate min and max (which take full scan of the column) for each row, so it's n^2 complexity out of nowhere.

val col = df["age"] as DataColumn<Int>
val min = col.min()
val max = col.max()


.format("age").with { 
    textColor(
        linear(value = it, from = min to blue, to = max to green)
    )
}

[Jolanrensen]

that... is a very good point. Let me see if I can adjust the examples to avoid repetitive calculations

[Jolanrensen]

in practice it will probably not be that bad. I wonder how many people will try to format a table with hundreds of rows, but it's good to hint towards effecient behavior

[AndreiKingsley]

Nice!
However, FormattedDF iframes don't work properly, but I will investigate that and fix in samples-utils.

[Jolanrensen]

@AndreiKingsley sure :) just bump the kandy version when you're done. I think I could already merge this version because the tables look good enough, right?