Updates in docs, mainly in the 'Gallery' and 'What's New'

Writerside/lpk.tree

@@ -10,6 +10,7 @@
     <toc-element href="%api_reference%" toc-title="API Reference"/>
     <toc-element topic="gallery.md"/>
     <toc-element topic="charts.md"/>
+    <toc-element topic="whats_new.md"/>
     <toc-element toc-title="Key Features">
         <toc-element topic="aesthetics.md"/>
         <toc-element topic="named_colors.md"/>

Writerside/topics/charts.md

@@ -213,10 +213,36 @@ Examples:
 [`scaleXTime()`](%api_scale%/scale-x-time.html),
 [`scaleYTime()`](%api_scale%/scale-y-time.html)
 
+*Lets-Plot* handles all temporal data types through a unified "datetime" scale (excluding duration, which is handled by the "time" scale).
+This is in contrast to R's ggplot2, which provides separate "date", "time", and "datetime" scales.
+
+**Supported temporal data types**:
+
+- `kotlinx.datetime` library:
+
+  - `Instant`
+  - `LocalDate`
+  - `LocalTime`
+  - `LocalDateTime`
+
+- `java.time` package:
+
+  - `Instant`
+  - `LocalDate`
+  - `LocalTime`
+  - `LocalDateTime`
+  - `ZonedDateTime` (timezone-aware)
+  - `OffsetDateTime` (timezone-aware with offset)
+
+- `java.util` package:
+
+  - `Date`
+
 Examples:
 
 - [Scale time](%nb-scale_time%)
 - [Plotting time series](%nb-time_date_datetime%)
+- [Bitcoin daily trend visualization](%nb-trading_chart%)
 
 
 ## Images

Writerside/topics/gallery.md

@@ -1,6 +1,16 @@
 # Gallery
 
 <list columns="3">
+    <li>
+        <a href="%nb-raincloud%">
+            <img alt="Raincloud plot" src="square-raincloud.png"/>
+        </a>
+    </li>
+    <li>
+        <a href="%nb-europe_capitals%">
+            <img alt="Lets-Plot GeoTools with texts and labels" src="square-europe_capitals.png"/>
+        </a>
+    </li>
     <li>
         <a href="%nb-trading_chart%">
             <img alt="Bitcoin daily trend visualization (2024)" src="square-trading_chart.png"/>
@@ -51,11 +61,21 @@
             <img alt="Wind rose" src="square-wind_rose.png"/>
         </a>
     </li>
+    <li>
+        <a href="%nb-periodic_table%">
+            <img alt="Mendeleev's periodic table of elements" src="square-periodic_table.png"/>
+        </a>
+    </li>
     <li>
         <a href="%nb-palmer_penguins%">
             <img alt="Palmer penguins" src="square-palmer_penguins.png"/>
         </a>
     </li>
+    <li>
+        <a href="%nb-post-punk_remake%">
+            <img alt="A post-punk chart remake" src="square-post-punk_remake.png"/>
+        </a>
+    </li>
     <li>
         <a href="%nb-mpg_daisy%">
             <img alt="MPG daisy" src="square-mpg_daisy.png"/>
@@ -66,4 +86,9 @@
             <img alt="Inset map of Kotlin island" src="square-spatialdataset_kotlin_isl.png"/>
         </a>
     </li>
+    <li>
+        <a href="%nb-klein_bottle%">
+            <img alt="Klein bottle visualization" src="square-klein_bottle.png"/>
+        </a>
+    </li>
 </list>

Writerside/topics/whats_new.md

@@ -0,0 +1,123 @@
+# What Is New in 4.11.0
+
+- **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="time_date_datetime.png" alt="changelog/4.11.0/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="bitcoin_trading.png" alt="changelog/4.11.0/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/>
+
+- **`geomSina()` Geometry**
+
+  <img src="geom_sina.png" alt="changelog/4.11.0/geom_sina.png" width="400" height="276"/>
+
+  See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/geom_sina.ipynb).
+
+- **`geomTextRepel()` and `geomLabelRepel()` Geometries**
+
+  <img src="geom_repel.png" alt="changelog/4.11.0/geom_repel.png" width="400" height="232"/>
+
+  See: [example notebook](https://nbviewer.org/github/JetBrains/lets-plot-kotlin/blob/master/docs/examples/jupyter-notebooks/f-4.11.0/ggrepel.ipynb).
+
+- **`waterfallPlot()` Chart**
+
+  - Annotations support via `relativeLabels` and `absoluteLabels` parameters.
+    <br/><br/>
+
+    <img src="waterfall_plot_annotations.png" alt="changelog/4.11.0/waterfall_plot_annotations.png" width="400" height="253"/>
+
+    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="waterfall_plot_layers.png" alt="changelog/4.11.0/waterfall_plot_layers.png" width="400" height="227"/>
+
+    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**
+
+  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="combo_discrete_continuous.png" alt="changelog/4.11.0/combo_discrete_continuous.png" width="400" height="151"/>
+
+  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).
+
+  > [!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.
+
+- **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="plot_layout_diagram.png" alt="changelog/4.11.0/plot_layout_diagram.png" width="400" height="175"/>
+
+  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.
+
+- **And More**
+
+  See [CHANGELOG.md](https://github.com/JetBrains/lets-plot-kotlin/blob/master/CHANGELOG.md) for a full list of changes.
+
+## Recent Updates in the [Gallery](gallery.md)
+
+<list columns="4">
+    <li>
+        <a href="%nb-raincloud%">
+            <img alt="Raincloud plot" src="square-raincloud.png"/>
+        </a>
+    </li>
+    <li>
+        <a href="%nb-europe_capitals%">
+            <img alt="Lets-Plot GeoTools with texts and labels" src="square-europe_capitals.png"/>
+        </a>
+    </li>
+    <li>
+        <a href="%nb-trading_chart%">
+            <img alt="Bitcoin daily trend visualization (2024)" src="square-trading_chart.png"/>
+        </a>
+    </li>
+    <li>
+        <a href="%nb-magnifier_inset%">
+            <img alt="Creating magnifier inset effect with ggbunch()" src="square-magnifier_inset.png"/>
+        </a>
+    </li>
+    <li>
+        <a href="%nb-theme_legend_scheme%">
+            <img alt="Theme legend scheme" src="square-theme_legend_scheme.png"/>
+        </a>
+    </li>
+    <li>
+        <a href="%nb-interact_pan_zoom%">
+            <img alt="Zoom and Pan interactivity" src="square-interact_pan_zoom.png"/>
+        </a>
+    </li>
+    <li>
+        <a href="%nb-lp_verse%">
+            <img alt="The observable LP-verse" src="square-lp_verse.png"/>
+        </a>
+    </li>
+    <li>
+        <a href="%nb-sunshine_hours%">
+            <img alt="Sunshine hours" src="square-sunshine_hours.png"/>
+        </a>
+    </li>
+</list>
+
+## Change Log
+
+See [CHANGELOG.md](https://github.com/JetBrains/lets-plot-kotlin/blob/master/CHANGELOG.md) for other changes and fixes.

Writerside/v.list

@@ -31,13 +31,18 @@
     <var name="nbp-tooltips" value="https://datalore.jetbrains.com/report/static/HZqq77cegYd.E7get_WnChZ/2u1Afm6IqmUugSWKG6ULsq"/>
     <var name="nbp-annotations" value="https://datalore.jetbrains.com/report/static/HZqq77cegYd.E7get_WnChZ/mynA4kNRFpu3XYl2b7tlBd"/>
     <!-- Gallery -->
+    <var name="nb-europe_capitals" value="%nbviewer_demo%/europe_capitals.ipynb"/>
     <var name="nb-geotools_naturalearth" value="%nbviewer_demo%/geotools_naturalearth.ipynb"/>
     <var name="nb-interact_pan_zoom" value="%nbviewer_demo%/interact_pan_zoom.ipynb"/>
+    <var name="nb-klein_bottle" value="%nbviewer_demo%/klein_bottle.ipynb"/>
     <var name="nb-lp_verse" value="%nbviewer_demo%/lp_verse.ipynb"/>
     <var name="nb-magnifier_inset" value="%nbviewer_demo%/magnifier_inset.ipynb"/>
     <var name="nb-mpg_daisy" value="%nbviewer_demo%/mpg_daisy.ipynb"/>
     <var name="nb-palmer_penguins" value="%nbviewer_demo%/palmer_penguins.ipynb"/>
-    <var name="nb-pushkin" value="%nbviewer_demo%/pushkin.ipynb"/>
+    <var name="nb-periodic_table" value="%nbviewer_demo%/periodic_table.ipynb"/>
+    <var name="nb-post-punk_remake" value="%nbviewer_demo%/post-punk_remake.ipynb"/>
+    <var name="nb-pushkin" value="https://datalore.jetbrains.com/report/static/HZqq77cegYd.E7get_WnChZ/zsJCczXy0RTjcczKj3BGMk"/>
+    <var name="nb-raincloud" value="%nbviewer_demo%/raincloud.ipynb"/>
     <var name="nb-spatialdataset_kotlin_isl" value="%nbviewer_demo%/spatialdataset_kotlin_isl.ipynb"/>
     <var name="nb-sunshine_hours" value="%nbviewer_demo%/sunshine_hours.ipynb"/>
     <var name="nb-theme_legend_scheme" value="%nbviewer_demo%/theme_legend_scheme.ipynb"/>

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_label_repel.kt

@@ -78,6 +78,19 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  *  1 or "top" - top-aligned (top of text at y).
  *  There are two special alignments: "inward" (aligns text towards the plot center) and "outward" (away from the plot center).
  * @param angle Label rotation angle in degrees.
+ * @param shape Shape of the point.
+ *  For more info see: [aesthetics.html#point-shapes](https://lets-plot.org/kotlin/aesthetics.html#point-shapes).
+ * @param pointSize A value representing the visual size of the point associated with the label.
+ *  Set to 0 to prevent label repulsion from data points.
+ * @param pointStroke Width of the point border.
+ * @param segmentColor Color of the line segment connecting the label to the point.
+ * @param segmentSize Width of the line segment connecting the label to the point.
+ * @param segmentAlpha Transparency level of the line segment. Understands numbers between 0 and 1.
+ * @param linetype Type of the line.
+ *  Accept codes or names (0 = "blank", 1 = "solid", 2 = "dashed", 3 = "dotted", 4 = "dotdash", 5 = "longdash", 6 = "twodash"),
+ *  a hex string (up to 8 digits for dash-gap lengths),
+ *  or a pattern `offset to listOf(dash, gap, ...)` / `listOf(dash, gap, ...)`.
+ *  For more info see: [aesthetics.html#line-types](https://lets-plot.org/kotlin/aesthetics.html#line-types).
  * @param lineheight Line height multiplier applied to the font size in the case of multi-line text.
  * @param labelFormat Specifies the format pattern for displaying mapped values.
  * @param naText default = "n/a".

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_text_repel.kt

@@ -75,6 +75,19 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  *  1 or "top" - top-aligned (top of text at y).
  *  There are two special alignments: "inward" (aligns text towards the plot center) and "outward" (away from the plot center).
  * @param angle Text rotation angle in degrees.
+ * @param shape Shape of the point.
+ *  For more info see: [aesthetics.html#point-shapes](https://lets-plot.org/kotlin/aesthetics.html#point-shapes).
+ * @param pointSize A value representing the visual size of the point associated with the label.
+ *  Set to 0 to prevent label repulsion from data points.
+ * @param pointStroke Width of the point border.
+ * @param segmentColor Color of the line segment connecting the label to the point.
+ * @param segmentSize Width of the line segment connecting the label to the point.
+ * @param segmentAlpha Transparency level of the line segment. Understands numbers between 0 and 1.
+ * @param linetype Type of the line.
+ *  Accept codes or names (0 = "blank", 1 = "solid", 2 = "dashed", 3 = "dotted", 4 = "dotdash", 5 = "longdash", 6 = "twodash"),
+ *  a hex string (up to 8 digits for dash-gap lengths),
+ *  or a pattern `offset to listOf(dash, gap, ...)` / `listOf(dash, gap, ...)`.
+ *  For more info see: [aesthetics.html#line-types](https://lets-plot.org/kotlin/aesthetics.html#line-types).
  * @param lineheight Line height multiplier applied to the font size in the case of multi-line text.
  * @param labelFormat Specifies the format pattern for displaying mapped values.
  * @param naText default = "n/a".