Release v4.12.0

alshan · alshan · commit c562791c621c · 2025-12-02T14:21:34.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,120 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). All scales should have the 'format' parameter.
 
+## [4.12.0] - 2025-12-02
+
+This release is 100% compatible with Lets-Plot [v 4.8.1](https://github.com/JetBrains/lets-plot/releases/tag/v4.8.0),
+GeoTools [v 33.2](https://github.com/geotools/geotools/releases/tag/33.2)
+
+### Added
+
+- Geometries:
+    - `geomPointDensity()` [[#1370](https://github.com/JetBrains/lets-plot/issues/1370)].
+
+      See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/geom_pointdensity.html).
+
+    - Geoms with 1-to-1 statistics (such as `geomQQ()`, `geomSina()`) preserve the mapping to original data after statistical transformation.
+
+      See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/stat_data_bijection.html).
+
+    - `geomHistogram()`: custom bin bounds (parameter `breaks`) [[#1382](https://github.com/JetBrains/lets-plot/issues/1382)].
+
+      See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/geom_histogram_param_breaks.html).
+
+- Plot Layout:
+    - The legend automatically wraps to prevent overlap - up to 15 rows for vertical legends and 5 columns for horizontal ones [[#1235](https://github.com/JetBrains/lets-plot/issues/1235)].
+
+      See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/legend_wrap.html).
+
+    - `gggrid()`: support for shared legends (parameter `guides`).
+
+      See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/gggrid_legend_collect.html).
+
+- Plot Theme:
+    - `flavorStandard()` sets the theme's default color scheme [[#1277](https://github.com/JetBrains/lets-plot/issues/1277)]. <br>
+      Use to override other flavors or to make defaults explicit.
+
+      See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/flavor_standard.html).
+
+    - `themeGray()` as an alias for `themeGrey()`.
+
+    - New `theme` functions for setting legend justification: `legendJustificationTop()`, `legendJustificationRight()`, <br>
+      `legendJustificationBottom()`, and `legendJustificationLeft()`.
+
+      See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/legend_justification.html).
+
+    - Support for inward axis ticks.
+
+      See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/axis_tick_direction.html).
+
+- Markdown:
+    - Support for `target` attribute for links.
+    - Links now open in a new tab by default [[#1397](https://github.com/JetBrains/lets-plot/issues/1397)].
+
+- `ggtb()`: `sizeZoomin` and `sizeBasis` parameters for geometry scaling [[#1369](https://github.com/JetBrains/lets-plot/issues/1369)].
+
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/ggtb_size_zoomin.html).
+
+- New `output` parameter for the library descriptor to control output types stored in notebook cells [[LPK-277](https://github.com/JetBrains/lets-plot-kotlin/issues/277)].\
+  Thanks to [AndreiKingsley](https://github.com/AndreiKingsley) for the contribution!
+  ```
+    %use lets-plot(output="js, png")
+  ```
+
+  Available output types:
+    - `js` - Classic Web output: HTML+JS
+    - `ktnb` - Kotlin Notebook Swing-based rendering
+    - `svg` - Static SVG output
+    - `png` - Static PNG output
+
+  Default: `"js, ktnb, svg"`
+
+  **Note:** Static images (SVG/PNG) are hidden when `js` or `ktnb` outputs are present, and only displayed in environments where JavaScript is not executed (e.g., GitHub).
+
+  This option can be helpful when a Kotlin Notebook file size becomes a problem. \
+  For example, when working with large datasets where plot interactivity is not a priority, storing only static output (SVG or PNG) can significantly reduce file size.
+
+- [`CenteredPlotPanel`](https://github.com/JetBrains/lets-plot/blob/master/platf-awt/src/main/kotlin/org/jetbrains/letsPlot/awt/plot/component/CenteredPlotPanel.kt) helper class for displaying plots centered in Swing applications.
+
+### Changed
+
+- [**BREAKING**] Explicit `group` aesthetic now overrides default grouping behavior instead of combining with it [[#1401](https://github.com/JetBrains/lets-plot/issues/1401)].
+
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/group_override_defaults.html).
+
+> [!IMPORTANT]
+> Previously, setting `group="variable"` would group by both the explicit variable AND any discrete
+> aesthetics (color, shape, etc.). \
+> Now it groups ONLY by the explicit variable, matching `ggplot2` behavior. \
+> Use `group=listOf(var1, var2, ...)` to group by multiple variables explicitly, \
+> and `group=emptyList<Any>()` to disable any grouping.
+
+- Missing values in `geomLine(), geomPath(), geomRibbon()`, and `geomArea()` create gaps in geometries instead of being interpolated over [[LPK-269](https://github.com/JetBrains/lets-plot-kotlin/issues/269)],[[#818](https://github.com/JetBrains/lets-plot/issues/818)], [[#1406](https://github.com/JetBrains/lets-plot/issues/1406)].
+
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/missing_values_line_path_area_ribbon.html).
+
+- `theme`: the `exponentFormat` default value changed to `"pow"` - superscript powers of 10 (was e-notation).
+
+- The multi-layer line plot now shows tooltips for each series simultaneously, in the same way that a single-layer plot with color mapped to series does.
+
+
+### Fixed
+
+- Group by multiple columns [[LPK-136](https://github.com/JetBrains/lets-plot-kotlin/issues/136)].
+- `geomPie` on geospatial plot with `mapJoin` failes to render without explicit `group` aesthetic.
+- `geomDensity2D`: NullPointerException when weight aesthetic contains None values [[#1399](https://github.com/JetBrains/lets-plot/issues/1399)].
+- Tooltip shows duplicate lines when as_discrete is applied twice to the same var [[#1400](https://github.com/JetBrains/lets-plot/issues/1400)].
+- `geomSina`: incorrect shape in legend [[#1403](https://github.com/JetBrains/lets-plot/issues/1403)].
+- `geomDensity2D`: Incorrect processing of weighted statistics when None value occurs in the x or y column.
+- `facetWrap`: indescriptive error when the specified facet variable is not present in the dataset [[#1409](https://github.com/JetBrains/lets-plot/issues/1409)].
+- Integer numbers in facet strip titles are displayed as float [[#1386](https://github.com/JetBrains/lets-plot/issues/1386)].
+- Error when using `scaleIdentity(aesthetic="shape")` [[#1212](https://github.com/JetBrains/lets-plot/issues/1212)].
+- `ggsave`: theme option `face="italic"` doesn't work [[#1391](https://github.com/JetBrains/lets-plot/issues/1391)].
+- Fail early if string format is incorrect [[#1410](https://github.com/JetBrains/lets-plot/issues/1410)].
+- `statECDF()` takes a very long time for even moderately sized datasets [[#1424](https://github.com/JetBrains/lets-plot/issues/1424)].
+- inconsistencies in theme/flavor inheritance in `gggrid()` subplots.
+
+
 ## [4.11.2] - 2025-09-12
 
 This release is 100% compatible with Lets-Plot [v 4.7.3](https://github.com/JetBrains/lets-plot/releases/tag/v4.7.3),
diff --git a/README.md b/README.md
@@ -67,7 +67,7 @@ See the "Quickstart" notebook in [Datalore](https://datalore.jetbrains.com/view/
   - [Compose Multiplatform](#in-compose-multiplatform)
   - [JVM and Kotlin/JS](#in-jvm-js)
 - [Documentation](#documentation)
-- [What is new in 4.11.0](#new)
+- [What is new in 4.12.0](#new)
 - [Recent Updates in the Gallery](#recent_gallery_updates)
 - [Change Log](#change_log)
 - [Code of Conduct](#CoC)
@@ -103,12 +103,21 @@ In this case the latest `library descriptor` will be pulled from the [Kotlin Jup
 #### Library Descriptor Parameters
 
 ```
-%use lets-plot(v=4.11.2, isolatedFrame=false)
+%use lets-plot(v=4.12.0, isolatedFrame=false, output="js, ktnb, svg")
 ```                                                                 
 - `v` - version of the Lets-Plot Kotlin API.
-- `isolatedFrame` - If `false`: load JS just once per notebook (default in Jupyter).
+- `isolatedFrame` - If `false`: load JS just once per notebook (default in Jupyter).  
   If `true`: include Lets-Plot JS in each output (default in [Datalore](https://datalore.jetbrains.com/) notebooks).
+- `output` - comma-separated list of output types to store in notebook cells (default: `"js, ktnb, svg"`). \  
+  Available types:
+    - `js` - Classic Web output: HTML+JS
+    - `ktnb` - Kotlin Notebook Swing-based rendering
+    - `svg` - Static SVG output
+    - `png` - Static PNG output
 
+  **Note:** Static images (SVG/PNG) are hidden when `js` or `ktnb` outputs are present, and only displayed in environments where JavaScript is not executed (e.g., GitHub).
+
+  This option can be helpful when file size becomes a problem. For example, storing only static output (SVG or PNG) can significantly reduce file size when working with large datasets where plot interactivity is not a priority.
 
 <a id="in-compose-multiplatform"></a>
 ### Compose Multiplatform
@@ -132,68 +141,61 @@ Examples of using the Lets-Plot Kotlin API in JVM and Kotlin/JS applications are
 
 
 <a id="new"></a>
-## What is new in 4.11.0
+## What is new in 4.12.0
+
+- #### `geomPointDensity()` Geometry
+
+  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25e/images/geom_pointdensity.png" alt="f-25e/images/geom_pointdensity.png" width="400" height="246">
+
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/geom_pointdensity.html).
+
+- #### Explicit `group` aesthetic now overrides default grouping behavior instead of combining with it
+
+> [!IMPORTANT]
+> **BREAKING CHANGE:**
+>
+> Previously, setting `group='variable'` would group by both the explicit variable AND any discrete
+> aesthetics (color, shape, etc.). \
+> Now it groups ONLY by the explicit variable, matching `ggplot2` behavior. \
+> Use `group=[var1, var2, ...]` to group by multiple variables explicitly, \
+> and `group=[]` to disable any grouping.
 
-- #### Time Series Plotting
-  - Support temporal data types from `kotlinx.datetime`, `java.time`, and `java.util`.
-  - Support for timezone-aware `java.time.ZonedDateTime` and `java.time.OffsetDateTime` objects.
+  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25e/images/group_override_defaults.png" alt="f-25e/images/group_override_defaults.png" width="400" height="263">
 
-  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25b/images/time_date_datetime.png" alt="f-25b/images/time_date_datetime.png" width="400" height="237">
-  
-  See [Date-time](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/time_date_datetime.ipynb) cookbook.
-  <br><br>
-  <img src="https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/images/bitcoin_trading.png" alt="f-4.11.0/images/bitcoin_trading.png" width="400" height="237">
-  
-  See [Bitcoin trading](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/demo/trading_chart.ipynb) demo.
-  <br><br>
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/group_override_defaults.html).
 
-- #### `geomSina()` Geometry
+- #### `gggrid()`: support for shared legends (parameter `guides`)
 
-  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25b/images/geom_sina.png" alt="f-25b/images/geom_sina.png" width="400" height="276">
+  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25e/images/gggrid_legend_collect.png" alt="f-25e/images/group_override_defaults.png" width="500" height="172">
 
-  See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/geom_sina.ipynb).
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/gggrid_legend_collect.html).
 
-- #### `geomTextRepel()` and `geomLabelRepel()` Geometries
+- #### Better handling of missing values in `geomLine(), geomPath(), geomRibbon()`, and `geomArea()`
 
-  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25b/images/geom_repel.png" alt="f-25b/images/geom_repel.png" width="400" height="232">
+  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25e/images/missing_values_ribbon.png" alt="f-25e/images/missing_values_ribbon.png" width="500" height="192">
 
-  See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/ggrepel.ipynb).
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/missing_values_line_path_area_ribbon.html).
 
-- #### `waterfallPlot()` Chart
+- #### `geomHistogram()`: custom bin bounds (parameter `breaks`)
 
-  - Annotations support via `relativeLabels` and `absoluteLabels` parameters.
-    <br><br>
-    <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25b/images/waterfall_plot_annotations.png" alt="f-25b/images/waterfall_plot_annotations.png" width="400" height="253">
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/geom_histogram_param_breaks.html).
 
-    See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/waterfall_plot_annotations.ipynb).
-    <br><br>
-  - Support for combining waterfall bars with other geometry layers.
-    <br><br>
-    <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25b/images/waterfall_plot_layers.png" alt="f-25b/images/waterfall_plot_layers.png" width="400" height="227">
+- #### Legend automatically wraps to prevent overlap — up to 15 rows for vertical legends and 5 columns for horizontal ones
 
-    See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/waterfall_plot_layers.ipynb).
-    
-- #### Continuous Data on Discrete Scales
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/legend_wrap.html).
 
-  Continuous data when used with discrete positional scales is no longer transformed to discrete data. <br>
-  Instead, it remains continuous, allowing for precise positioning of continuous elements relative to discrete ones.
-  <br><br>
-  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25b/images/combo_discrete_continuous.png" alt="f-25b/images/combo_discrete_continuous.png" width="400" height="151">
+- #### `flavorStandard()` resets the theme's default color scheme
+  Use to override other flavors or make defaults explicit.
 
-  See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/numeric_data_on_discrete_scale.ipynb).
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/flavor_standard.html).
 
-> [!TIP]
-> New way of handling continuous data on discrete scales could potentially break existing plots.
-> If you want to restore a broken plot to its original form, you can use the [`asDiscrete()`](https://lets-plot.org/kotlin/as-discrete.html) function to annotate continuous data as discrete.
+- #### `theme` methods controlling legend justification: `legendJustificationTop()`, `legendJustificationRight()`, `legendJustificationBottom()`, and `legendJustificationLeft()`
 
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/legend_justification.html).
 
-- #### Plot Layout
-  The default plot layout has been improved to better accommodate axis labels and titles. <br>
-  Also, new `theme()` options `axisTextSpacing`, `axisTextSpacingX`, and `axisTextSpacingY` control spacing between axis ticks and labels.
-  <br><br>
-  <img src="https://raw.githubusercontent.com/JetBrains/lets-plot/master/docs/f-25b/images/plot_layout_diagram.png" alt="f-25b/images/plot_layout_diagram.png" width="400" height="175">
+- #### `ggtb()`: Added `sizeZoomin` and `sizeBasis` parameters to control point size scaling behavior when zooming (works with `geomPoint` and related layers).
 
-  See new [Plot Layout Diagrams](https://lets-plot.org/kotlin/presentation-options.html#plot-layout-diagrams) showing various layout options and their effects on plot appearance.
+  See: [example notebook](https://raw.githack.com/JetBrains/lets-plot-kotlin/refs/heads/master/docs/examples/jupyter-notebooks/f-4.12.0/ggtb_size_zoomin.html).
 
 
 - #### And More
diff --git a/USAGE_BATIK_JFX_JS.md b/USAGE_BATIK_JFX_JS.md
@@ -52,9 +52,9 @@ plugins {
 
 dependencies {
     // Lets-Plot Kotlin API 
-    implementation("org.jetbrains.lets-plot:lets-plot-kotlin-jvm:4.11.2")
+    implementation("org.jetbrains.lets-plot:lets-plot-kotlin-jvm:4.12.0")
     // Lets-Plot Multiplatform (Batik rendering)
-    implementation("org.jetbrains.lets-plot:lets-plot-batik:4.7.3")
+    implementation("org.jetbrains.lets-plot:lets-plot-batik:4.8.1")
 }
 ```
 
@@ -75,9 +75,9 @@ plugins {
 
 dependencies {
     // Lets-Plot Kotlin API 
-    implementation("org.jetbrains.lets-plot:lets-plot-kotlin-jvm:4.11.2")
+    implementation("org.jetbrains.lets-plot:lets-plot-kotlin-jvm:4.12.0")
     // Lets-Plot Multiplatform (JFX Scene rendering)
-    implementation("org.jetbrains.lets-plot:lets-plot-jfx:4.7.3")
+    implementation("org.jetbrains.lets-plot:lets-plot-jfx:4.8.1")
 }
 ```
 
@@ -95,7 +95,7 @@ kotlin {
         named("jsMain") {
             dependencies {
                 // Lets-Plot Kotlin API 
-                implementation("org.jetbrains.lets-plot:lets-plot-kotlin-js:4.11.2")
+                implementation("org.jetbrains.lets-plot:lets-plot-kotlin-js:4.12.0")
             }
         }
     }
@@ -193,7 +193,7 @@ val rawSpec = figure.toSpec()
     ```kotlin
     val html: String = PlotHtmlExport.buildHtmlFromRawSpecs(
                                         plotSpec = rawSpec,
-                                        scriptUrl = PlotHtmlHelper.scriptUrl(version="4.7.3"),
+                                        scriptUrl = PlotHtmlHelper.scriptUrl(version="4.8.1"),
                                         iFrame = true    
                                     )
     ```
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -36,7 +36,7 @@ if (project.file("local.properties").exists()) {
 
 allprojects {
     group = "org.jetbrains.lets-plot"
-    version = "4.11.3-SNAPSHOT"
+    version = "4.12.1-SNAPSHOT"
 //    version = "0.0.0-SNAPSHOT"  // for local publishing only
 
     tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().all {
diff --git a/future_changes.md b/future_changes.md
diff --git a/plot-api/src/jvmMain/resources/letsPlotKotlinAPI/version.properties b/plot-api/src/jvmMain/resources/letsPlotKotlinAPI/version.properties
