Automated commit of generated code

Author: github-actions[bot]

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt

@@ -566,7 +566,7 @@ public fun <T, C> DataFrame<T>.format(vararg columns: KProperty<C>): FormatClaus
  *   If unspecified, all columns will be formatted.
  */
 public fun <T, C> FormattedFrame<T>.format(columns: ColumnsSelector<T, C>): FormatClause<T, C> =
-    FormatClause(df, columns, formatter)
+    FormatClause(df, columns, formatter, oldHeaderFormatter = headerFormatter)
 
 /**
  * Formats the specified [columns] or cells within this dataframe such that
@@ -702,7 +702,13 @@ public fun <T> FormattedFrame<T>.format(): FormatClause<T, Any?> = FormatClause(
  * Check out the full [Grammar][FormatDocs.Grammar].
  */
 public fun <T, C> FormatClause<T, C>.where(filter: RowValueFilter<T, C>): FormatClause<T, C> =
-    FormatClause(filter = this.filter and filter, df = df, columns = columns, oldFormatter = oldFormatter)
+    FormatClause(
+        filter = this.filter and filter,
+        df = df,
+        columns = columns,
+        oldFormatter = oldFormatter,
+        oldHeaderFormatter = oldHeaderFormatter,
+    )
 
 /**
  * Only format the selected columns at given row indices.
@@ -1173,7 +1179,11 @@ public typealias CellFormatter<C> = FormattingDsl.(cell: C) -> CellAttributes?
  *
  * You can apply further formatting to this [FormattedFrame] by calling [format()][FormattedFrame.format] once again.
  */
-public class FormattedFrame<T>(internal val df: DataFrame<T>, internal val formatter: RowColFormatter<T, *>? = null) {
+public class FormattedFrame<T>(
+    internal val df: DataFrame<T>,
+    internal val formatter: RowColFormatter<T, *>? = null,
+    internal val headerFormatter: HeaderColFormatter<*>? = null,
+) {
 
     /**
      * Returns a [DataFrameHtmlData] without additional definitions.
@@ -1219,7 +1229,10 @@ public class FormattedFrame<T>(internal val df: DataFrame<T>, internal val forma
     /** Applies this formatter to the given [configuration] and returns a new instance. */
     @Suppress("UNCHECKED_CAST")
     public fun getDisplayConfiguration(configuration: DisplayConfiguration): DisplayConfiguration =
-        configuration.copy(cellFormatter = formatter as RowColFormatter<*, *>?)
+        configuration.copy(
+            cellFormatter = formatter as RowColFormatter<*, *>?,
+            headerFormatter = headerFormatter,
+        )
 }
 
 /**
@@ -1251,6 +1264,7 @@ public class FormatClause<T, C>(
     internal val columns: ColumnsSelector<T, C> = { all().cast() },
     internal val oldFormatter: RowColFormatter<T, C>? = null,
     internal val filter: RowValueFilter<T, C> = { true },
+    internal val oldHeaderFormatter: HeaderColFormatter<*>? = null,
 ) {
     override fun toString(): String =
         "FormatClause(df=$df, columns=$columns, oldFormatter=$oldFormatter, filter=$filter)"

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/formatHeader.kt

@@ -0,0 +1,143 @@
+package org.jetbrains.kotlinx.dataframe.api
+
+import org.jetbrains.kotlinx.dataframe.ColumnsSelector
+import org.jetbrains.kotlinx.dataframe.DataFrame
+import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath
+import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
+import org.jetbrains.kotlinx.dataframe.impl.api.formatHeaderImpl
+
+// region docs
+
+/**
+ * A lambda used to format a column header (its displayed name) when rendering a dataframe to HTML.
+ *
+ * The lambda runs in the context of [FormattingDsl] and receives the [ColumnWithPath] of the header to format.
+ * Return a [CellAttributes] (or `null`) describing the CSS you want to apply to the header cell.
+ *
+ * Examples:
+ * - Center the header: `attr("text-align", "center")`
+ * - Make it bold: `bold`
+ * - Set a custom color: `textColor(rgb(10, 10, 10))`
+ */
+public typealias HeaderColFormatter<C> = FormattingDsl.(col: ColumnWithPath<C>) -> CellAttributes?
+
+/**
+ * An intermediate class used in the header-format operation [formatHeader].
+ *
+ * This class itself does nothing—it represents a selection of columns whose headers will be formatted.
+ * Finalize this step by calling [with] to produce a new [FormattedFrame].
+ *
+ * Header formatting is additive and supports nested column groups: styles specified for a parent group
+ * are inherited by its child columns unless overridden for the child.
+ */
+public class HeaderFormatClause<T, C>(
+    internal val df: DataFrame<T>,
+    internal val columns: ColumnsSelector<T, C> = { all().cast() },
+    internal val oldHeaderFormatter: HeaderColFormatter<C>? = null,
+    internal val oldCellFormatter: RowColFormatter<T, *>? = null,
+) {
+    override fun toString(): String =
+        "HeaderFormatClause(df=$df, columns=$columns, oldHeaderFormatter=$oldHeaderFormatter, oldCellFormatter=$oldCellFormatter)"
+}
+
+// endregion
+
+// region DataFrame.formatHeader
+
+/**
+ * **Experimental API. It may be changed in the future.**
+ *
+ * Selects [columns] whose headers should be formatted. If unspecified, all columns will be formatted.
+ *
+ * This does not immediately produce a [FormattedFrame]; instead it returns a [HeaderFormatClause]
+ * which must be finalized using [HeaderFormatClause.with].
+ */
+public fun <T, C> DataFrame<T>.formatHeader(columns: ColumnsSelector<T, C>): HeaderFormatClause<T, C> =
+    HeaderFormatClause(this, columns)
+
+/**
+ * **Experimental API. It may be changed in the future.**
+ *
+ * Selects [columns] whose headers should be formatted.
+ *
+ * This does not immediately produce a [FormattedFrame]; instead it returns a [HeaderFormatClause]
+ * which must be finalized using [HeaderFormatClause.with].
+ */
+public fun <T> DataFrame<T>.formatHeader(vararg columns: String): HeaderFormatClause<T, Any?> =
+    formatHeader { columns.toColumnSet() }
+
+/**
+ * **Experimental API. It may be changed in the future.**
+ *
+ * Selects all columns for header formatting.
+ *
+ * This does not immediately produce a [FormattedFrame]; instead it returns a [HeaderFormatClause]
+ * which must be finalized using [HeaderFormatClause.with].
+ */
+public fun <T> DataFrame<T>.formatHeader(): HeaderFormatClause<T, Any?> = HeaderFormatClause(this)
+
+// endregion
+
+// region FormattedFrame.formatHeader
+
+/**
+ * **Experimental API. It may be changed in the future.**
+ *
+ * Selects [columns] whose headers should be formatted.
+ *
+ * This does not immediately produce a [FormattedFrame]; instead it returns a [HeaderFormatClause]
+ * which must be finalized using [HeaderFormatClause.with].
+ */
+public fun <T, C> FormattedFrame<T>.formatHeader(columns: ColumnsSelector<T, C>): HeaderFormatClause<T, C> =
+    HeaderFormatClause(
+        df = df,
+        columns = columns,
+        oldHeaderFormatter = headerFormatter as HeaderColFormatter<C>?,
+        oldCellFormatter = formatter,
+    )
+
+/**
+ * **Experimental API. It may be changed in the future.**
+ *
+ * Selects [columns] whose headers should be formatted.
+ *
+ * This does not immediately produce a [FormattedFrame]; instead it returns a [HeaderFormatClause]
+ * which must be finalized using [HeaderFormatClause.with].
+ */
+public fun <T> FormattedFrame<T>.formatHeader(vararg columns: String): HeaderFormatClause<T, Any?> =
+    formatHeader { columns.toColumnSet() }
+
+/**
+ * **Experimental API. It may be changed in the future.**
+ *
+ * Selects all columns for header formatting.
+ *
+ * This does not immediately produce a [FormattedFrame]; instead it returns a [HeaderFormatClause]
+ * which must be finalized using [HeaderFormatClause.with].
+ */
+public fun <T> FormattedFrame<T>.formatHeader(): HeaderFormatClause<T, Any?> =
+    HeaderFormatClause(
+        df = df,
+        oldHeaderFormatter = headerFormatter,
+        oldCellFormatter = formatter,
+    )
+
+// endregion
+
+// region terminal operations
+
+/**
+ * **Experimental API. It may be changed in the future.**
+ *
+ * Creates a new [FormattedFrame] that uses the specified [HeaderColFormatter] to format the selected headers.
+ *
+ * Header formatting is additive: attributes from already-applied header formatters are combined with the newly
+ *
+ *  returned attributes using [CellAttributes.and]. If a parent column group is selected, its attributes are
+ * applied to its children unless explicitly overridden.
+ */
+@Suppress("UNCHECKED_CAST")
+public fun <T, C> HeaderFormatClause<T, C>.with(formatter: HeaderColFormatter<C>): FormattedFrame<T> =
+    formatHeaderImpl(formatter)
+
+// endregion

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/format.kt

@@ -56,15 +56,18 @@ internal inline fun <T, C> FormatClause<T, C>.formatImpl(
     val clause = this
     val columns = clause.df.getColumnPaths(UnresolvedColumnsPolicy.Skip, clause.columns).toSet()
 
-    return FormattedFrame(clause.df) { row, col ->
-        val oldAttributes = clause.oldFormatter?.invoke(FormattingDsl, row, col.cast())
-        if (col.path in columns) {
-            val value = col[row] as C
-            if (clause.filter(row, value)) {
-                return@FormattedFrame oldAttributes and formatter(FormattingDsl, row.cast(), col.cast())
+    return FormattedFrame(
+        df = clause.df,
+        formatter = { row, col ->
+            val oldAttributes = clause.oldFormatter?.invoke(FormattingDsl, row, col.cast())
+            if (col.path in columns) {
+                val value = col[row] as C
+                if (clause.filter(row, value)) {
+                    return@FormattedFrame oldAttributes and formatter(FormattingDsl, row.cast(), col.cast())
+                }
             }
-        }
-
-        oldAttributes
-    }
+            oldAttributes
+        },
+        headerFormatter = clause.oldHeaderFormatter,
+    )
 }

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/formatHeader.kt

@@ -0,0 +1,24 @@
+package org.jetbrains.kotlinx.dataframe.impl.api
+
+import org.jetbrains.kotlinx.dataframe.api.FormattedFrame
+import org.jetbrains.kotlinx.dataframe.api.FormattingDsl
+import org.jetbrains.kotlinx.dataframe.api.HeaderColFormatter
+import org.jetbrains.kotlinx.dataframe.api.HeaderFormatClause
+import org.jetbrains.kotlinx.dataframe.api.and
+import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath
+import org.jetbrains.kotlinx.dataframe.columns.UnresolvedColumnsPolicy
+import org.jetbrains.kotlinx.dataframe.impl.getColumnPaths
+
+internal fun <T, C> HeaderFormatClause<T, C>.formatHeaderImpl(formatter: HeaderColFormatter<C>): FormattedFrame<T> {
+    val selectedPaths = df.getColumnPaths(UnresolvedColumnsPolicy.Skip, columns).toSet()
+    val oldHeader = oldHeaderFormatter
+
+    val composedHeader: HeaderColFormatter<Any?> = { col ->
+        val typedCol = col as ColumnWithPath<C>
+        val existingAttr = oldHeader?.invoke(FormattingDsl, typedCol)
+        val newAttr = if (col.path in selectedPaths) formatter(FormattingDsl, typedCol) else null
+        existingAttr and newAttr
+    }
+
+    return FormattedFrame(df, oldCellFormatter, composedHeader)
+}