plotlyjs 2.20.0: Add automargin support to plot titles (plotly/plotly.js#6428)

Author: kMutagene

Diff for: 2.19.fs

@@ -7,33 +7,89 @@ open DynamicObj
 type Title() =
     inherit DynamicObj()
 
+    /// <summary>
+    /// Returns a new Title object with the given styles. Note that this is a multi-purpose object that can be used as plot or different axis titles, with some attributes being only used in some layouts.
+    /// </summary>
+    /// <param name="Text">For all titles: Sets the plot's title. Note that before the existence of `title.text`, the title's contents used to be defined as the `title` attribute itself. This behavior has been deprecated.</param>
+    /// <param name="AutoMargin">For plot titles: Determines whether the title can automatically push the figure margins. If `yref='paper'` then the margin will expand to ensure that the title doesn’t overlap with the edges of the container. If `yref='container'` then the margins will ensure that the title doesn’t overlap with the plot area, tick labels, and axis titles. If `automargin=true` and the margins need to be expanded, then y will be set to a default 1 and yanchor will be set to an appropriate default to ensure that minimal margin space is needed. Note that when `yref='paper'`, only 1 or 0 are allowed y values. Invalid values will be reset to the default 1.</param>
+    /// <param name="Font">For all titles: Sets the title font. Note that the title's font used to be customized by the now deprecated `titlefont` attribute.</param>
+    /// <param name="Standoff">For axis titles: Sets the standoff distance (in px) between the axis labels and the title text The default value is a function of the axis tick labels, the title `font.size` and the axis `linewidth`. Note that the axis title position is always constrained within the margins, so the actual standoff distance is always less than the set or default value. By setting `standoff` and turning on `automargin`, plotly.js will push the margins to fit the axis title at given standoff distance.</param>
+    /// <param name="Side">For colorbar titles: Determines the location of color bar's title with respect to the color bar. Defaults to "top" when `orientation` if "v" and defaults to "right" when `orientation` if "h". Note that the title's location used to be set by the now deprecated `titleside` attribute.</param>
+    /// <param name="X">For plot titles: Sets the x position with respect to `xref` in normalized coordinates from "0" (left) to "1" (right).</param>
+    /// <param name="XAnchor">For plot titles: Sets the title's horizontal alignment with respect to its x position. "left" means that the title starts at x, "right" means that the title ends at x and "center" means that the title's center is at x. "auto" divides `xref` by three and calculates the `xanchor` value automatically based on the value of `x`.</param>
+    /// <param name="XRef">For plot titles: Sets the container `x` refers to. "container" spans the entire `width` of the plot. "paper" refers to the width of the plotting area only.</param>
+    /// <param name="Y">For plot titles: Sets the y position with respect to `yref` in normalized coordinates from "0" (bottom) to "1" (top). "auto" places the baseline of the title onto the vertical center of the top margin.</param>
+    /// <param name="YAnchor">For plot titles: Sets the title's vertical alignment with respect to its y position. "top" means that the title's cap line is at y, "bottom" means that the title's baseline is at y and "middle" means that the title's midline is at y. "auto" divides `yref` by three and calculates the `yanchor` value automatically based on the value of `y`.</param>
+    /// <param name="YRef">For plot titles: Sets the container `y` refers to. "container" spans the entire `height` of the plot. "paper" refers to the height of the plotting area only.</param>
     static member init
         (
             [<Optional; DefaultParameterValue(null)>] ?Text: string,
+            [<Optional; DefaultParameterValue(null)>] ?AutoMargin: bool,
             [<Optional; DefaultParameterValue(null)>] ?Font: Font,
             [<Optional; DefaultParameterValue(null)>] ?Standoff: int,
             [<Optional; DefaultParameterValue(null)>] ?Side: StyleParam.Side,
             [<Optional; DefaultParameterValue(null)>] ?X: float,
-            [<Optional; DefaultParameterValue(null)>] ?Y: float
+            [<Optional; DefaultParameterValue(null)>] ?XAnchor: StyleParam.XAnchorPosition,
+            [<Optional; DefaultParameterValue(null)>] ?XRef: string,
+            [<Optional; DefaultParameterValue(null)>] ?Y: float,
+            [<Optional; DefaultParameterValue(null)>] ?YAnchor: StyleParam.YAnchorPosition,
+            [<Optional; DefaultParameterValue(null)>] ?YRef: string
         ) =
-        Title() |> Title.style (?Text = Text, ?Font = Font, ?Standoff = Standoff, ?Side = Side, ?X = X, ?Y = Y)
+        Title() 
+        |> Title.style (
+            ?Text = Text, 
+            ?AutoMargin = AutoMargin,
+            ?Font = Font, 
+            ?Standoff = Standoff, 
+            ?Side = Side, 
+            ?X = X,
+            ?XAnchor = XAnchor,
+            ?XRef = XRef,
+            ?Y = Y,
+            ?YAnchor = YAnchor,
+            ?YRef = YRef
+        )
 
+    /// <summary>
+    /// Returns a function that applies the given styles to a Title object. Note that this is a multi-purpose object that can be used as plot or different axis titles, with some attributes being only used in some layouts
+    /// </summary>
+    /// <param name="Text">For all titles: Sets the plot's title. Note that before the existence of `title.text`, the title's contents used to be defined as the `title` attribute itself. This behavior has been deprecated.</param>
+    /// <param name="AutoMargin">For plot titles: Determines whether the title can automatically push the figure margins. If `yref='paper'` then the margin will expand to ensure that the title doesn’t overlap with the edges of the container. If `yref='container'` then the margins will ensure that the title doesn’t overlap with the plot area, tick labels, and axis titles. If `automargin=true` and the margins need to be expanded, then y will be set to a default 1 and yanchor will be set to an appropriate default to ensure that minimal margin space is needed. Note that when `yref='paper'`, only 1 or 0 are allowed y values. Invalid values will be reset to the default 1.</param>
+    /// <param name="Font">For all titles: Sets the title font. Note that the title's font used to be customized by the now deprecated `titlefont` attribute.</param>
+    /// <param name="Standoff">For axis titles: Sets the standoff distance (in px) between the axis labels and the title text The default value is a function of the axis tick labels, the title `font.size` and the axis `linewidth`. Note that the axis title position is always constrained within the margins, so the actual standoff distance is always less than the set or default value. By setting `standoff` and turning on `automargin`, plotly.js will push the margins to fit the axis title at given standoff distance.</param>
+    /// <param name="Side">For colorbar titles: Determines the location of color bar's title with respect to the color bar. Defaults to "top" when `orientation` if "v" and defaults to "right" when `orientation` if "h". Note that the title's location used to be set by the now deprecated `titleside` attribute.</param>
+    /// <param name="X">For plot titles: Sets the x position with respect to `xref` in normalized coordinates from "0" (left) to "1" (right).</param>
+    /// <param name="XAnchor">For plot titles: Sets the title's horizontal alignment with respect to its x position. "left" means that the title starts at x, "right" means that the title ends at x and "center" means that the title's center is at x. "auto" divides `xref` by three and calculates the `xanchor` value automatically based on the value of `x`.</param>
+    /// <param name="XRef">For plot titles: Sets the container `x` refers to. "container" spans the entire `width` of the plot. "paper" refers to the width of the plotting area only.</param>
+    /// <param name="Y">For plot titles: Sets the y position with respect to `yref` in normalized coordinates from "0" (bottom) to "1" (top). "auto" places the baseline of the title onto the vertical center of the top margin.</param>
+    /// <param name="YAnchor">For plot titles: Sets the title's vertical alignment with respect to its y position. "top" means that the title's cap line is at y, "bottom" means that the title's baseline is at y and "middle" means that the title's midline is at y. "auto" divides `yref` by three and calculates the `yanchor` value automatically based on the value of `y`.</param>
+    /// <param name="YRef">For plot titles: Sets the container `y` refers to. "container" spans the entire `height` of the plot. "paper" refers to the height of the plotting area only.</param>
     static member style
         (
             [<Optional; DefaultParameterValue(null)>] ?Text: string,
+            [<Optional; DefaultParameterValue(null)>] ?AutoMargin: bool,
             [<Optional; DefaultParameterValue(null)>] ?Font: Font,
             [<Optional; DefaultParameterValue(null)>] ?Standoff: int,
             [<Optional; DefaultParameterValue(null)>] ?Side: StyleParam.Side,
             [<Optional; DefaultParameterValue(null)>] ?X: float,
-            [<Optional; DefaultParameterValue(null)>] ?Y: float
+            [<Optional; DefaultParameterValue(null)>] ?XAnchor: StyleParam.XAnchorPosition,
+            [<Optional; DefaultParameterValue(null)>] ?XRef: string,
+            [<Optional; DefaultParameterValue(null)>] ?Y: float,
+            [<Optional; DefaultParameterValue(null)>] ?YAnchor: StyleParam.YAnchorPosition,
+            [<Optional; DefaultParameterValue(null)>] ?YRef: string
         ) =
         (fun (title: Title) ->
 
             Text |> DynObj.setValueOpt title "text"
+            AutoMargin |> DynObj.setValueOpt title "automargin"
             Font |> DynObj.setValueOpt title "font"
             Standoff |> DynObj.setValueOpt title "standoff"
             Side |> DynObj.setValueOptBy title "side" StyleParam.Side.convert
             X |> DynObj.setValueOpt title "x"
+            XAnchor |> DynObj.setValueOptBy title "xanchor" StyleParam.XAnchorPosition.convert
+            XRef |> DynObj.setValueOpt title "xref"
             Y |> DynObj.setValueOpt title "y"
+            YAnchor |> DynObj.setValueOptBy title "yanchor" StyleParam.YAnchorPosition.convert
+            YRef |> DynObj.setValueOpt title "yref"
 
             title)

Diff for: src/Plotly.NET/CommonAbstractions/Title.fs

@@ -7,7 +7,7 @@ open Giraffe.ViewEngine
 
 /// The plotly js version loaded from cdn in rendered html docs
 [<Literal>]
-let PLOTLYJS_VERSION = "2.19.1"
+let PLOTLYJS_VERSION = "2.20.0"
 
 [<Literal>]
 let SCRIPT_TEMPLATE =

Diff for: src/Plotly.NET/Globals.fs

@@ -40,8 +40,8 @@
   <ItemGroup>
     <None Include="RELEASE_NOTES.md" />
     <None Include="..\..\docs\img\logo.png" Pack="true" PackagePath="\" />
-    <EmbeddedResource Include="plotly-2.19.1.min.js" />
-    <EmbeddedResource Include="plotly-2.19.1.min.js.LICENSE.txt" />
+    <EmbeddedResource Include="plotly-2.20.0.min.js" />
+    <EmbeddedResource Include="plotly-2.20.0.min.js.LICENSE.txt" />
     <Compile Include="Globals.fs" />
     <Compile Include="InternalUtils.fs" />
     <Compile Include="CommonAbstractions\ColorKeyword.fs" />

Diff for: src/Plotly.NET/Plotly.NET.fsproj

@@ -7,8 +7,8 @@
 
   <ItemGroup>
     <EmbeddedResource Include="..\..\..\docs\img\logo.png" />
-    <EmbeddedResource Include="..\..\..\src\Plotly.NET\plotly-2.19.1.min.js" />
-    <EmbeddedResource Include="..\..\..\src\Plotly.NET\plotly-2.19.1.min.js.LICENSE.txt" />
+    <EmbeddedResource Include="..\..\..\src\Plotly.NET\plotly-2.20.0.min.js" />
+    <EmbeddedResource Include="..\..\..\src\Plotly.NET\plotly-2.20.0.min.js.LICENSE.txt" />
   </ItemGroup>
 
   <ItemGroup>
@@ -21,6 +21,7 @@
     <Compile Include="TestCharts\ChartCarpetTestCharts.fs" />
     <Compile Include="TestCharts\ChartDomainTestCharts.fs" />
     <Compile Include="TestCharts\ChartSmithTestCharts.fs" />
+    <Compile Include="TestCharts\UpstreamFeatures\2.20.fs" />
     <Compile Include="TestCharts\UpstreamFeatures\2.19.fs" />
   </ItemGroup>
 

Diff for: src/Plotly.NET/plotly-2.19.1.min.js

@@ -0,0 +1,19 @@
+module PlotlyJS_2_20_TestCharts
+
+open Plotly.NET
+open Plotly.NET.TraceObjects
+open Plotly.NET.LayoutObjects
+
+
+module TitleAutoMargin = 
+    let ``Title with AutoMargin`` =
+        Chart.Point(
+            [1,2],
+            UseDefaults = false
+        )
+        |> Chart.withTitle(
+            Title.init(
+                Text = """Lorem ipsum dolor sit amet, <br>consetetur sadipscing elitr, sed diam nonumy eirmod <br>tempor invidunt ut labore et dolore magna aliquyam erat, <br>sed diam voluptua. At vero eos et accusam et justo <br>duo dolores et ea rebum. Stet clita kasd gubergren,<br>no sea takimata sanctus est Lorem ipsum dolor sit amet. <br>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, <br>sed diam nonumy eirmod tempor invidunt ut labore et <br>dolore magna aliquyam erat, sed diam voluptua. <br>At vero eos et accusam et justo duo dolores et ea rebum. <br>Stet clita kasd gubergren, no sea takimata sanctus est <br>Lorem ipsum dolor sit amet.""",
+                AutoMargin = true
+            )
+        )

Diff for: src/Plotly.NET/plotly-2.20.0.min.js

@@ -11,72 +11,15 @@ open Newtonsoft.Json
 
 [<EntryPoint>]
 let main argv =
-
-    let labelAlias = DynamicObj() 
-    labelAlias?("1") <- "<b>ONE</b>"
-    labelAlias?("0\u00B0") <- "<b>ZERO</b>"
-
-    let linAxis = LinearAxis.init(LabelAlias=labelAlias)
-    let angularAxis = AngularAxis.init(LabelAlias=labelAlias)
-    let radialAxis = RadialAxis.init(LabelAlias=labelAlias)
-    let imaginaryAxis = ImaginaryAxis.init(LabelAlias=labelAlias)
-    let realAxis = RealAxis.init(LabelAlias=labelAlias)
-    let colorBar = ColorBar.init(LabelAlias=labelAlias)
-
-    [
-        Chart.Point([1,1], UseDefaults = false) 
-        |> Chart.withXAxis(linAxis)
-        |> Chart.withYAxis(linAxis)
-
-        Chart.Point3D([1,1,1], UseDefaults = false)
-        |> Chart.withXAxis(linAxis, Id = StyleParam.SubPlotId.Scene 1)
-        |> Chart.withYAxis(linAxis, Id = StyleParam.SubPlotId.Scene 1)
-        |> Chart.withZAxis(linAxis)
-
-        Chart.PointPolar([1,1], UseDefaults = false)
-        |> Chart.withAngularAxis(angularAxis)
-        |> Chart.withRadialAxis(radialAxis)
-
-        Chart.PointTernary([1,1,1], UseDefaults = false)
-        |> Chart.withAAxis(linAxis)
-        |> Chart.withBAxis(linAxis)
-        |> Chart.withCAxis(linAxis)
-
-
-        [
-            Chart.Carpet(
-                carpetId = "carpet1",
-                A = [4.; 4.; 4.; 4.5; 4.5; 4.5; 5.; 5.; 5.; 6.; 6.; 6.], 
-                B = [1.; 2.; 3.; 1.; 2.; 3.; 1.; 2.; 3.; 1.; 2.; 3.], 
-                Y = [2.; 3.5; 4.; 3.; 4.5; 5.; 5.5; 6.5; 7.5; 8.; 8.5; 10.], 
-                AAxis = linAxis,
-                BAxis = linAxis,
-                UseDefaults = false
-            )
-
-        ]
-        |> Chart.combine
-
-        Chart.Heatmap([[1;2];[3;4]], UseDefaults = false)
-        |> Chart.withXAxis(linAxis)
-        |> Chart.withYAxis(linAxis)
-        |> Chart.withColorBar(colorBar)
-
-        Chart.PointSmith([1,2], UseDefaults = false)
-        |> Chart.withImaginaryAxis(imaginaryAxis)
-        |> Chart.withRealAxis(realAxis)
-
-        Chart.Indicator(
-            value = 1, 
-            mode = StyleParam.IndicatorMode.NumberDeltaGauge,
-            DeltaReference = 0,
-            Range = StyleParam.Range.MinMax(-1., 1.),
-            GaugeShape = StyleParam.IndicatorGaugeShape.Bullet,
-            ShowGaugeAxis = true,
-            GaugeAxis = linAxis,
-            UseDefaults = false
+    Chart.Point(
+        [1,2],
+        UseDefaults = false
+    )
+    |> Chart.withTitle(
+        Title.init(
+            Text = """Lorem ipsum dolor sit amet, <br>consetetur sadipscing elitr, sed diam nonumy eirmod <br>tempor invidunt ut labore et dolore magna aliquyam erat, <br>sed diam voluptua. At vero eos et accusam et justo <br>duo dolores et ea rebum. Stet clita kasd gubergren,<br>no sea takimata sanctus est Lorem ipsum dolor sit amet. <br>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, <br>sed diam nonumy eirmod tempor invidunt ut labore et <br>dolore magna aliquyam erat, sed diam voluptua. <br>At vero eos et accusam et justo duo dolores et ea rebum. <br>Stet clita kasd gubergren, no sea takimata sanctus est <br>Lorem ipsum dolor sit amet.""",
+            AutoMargin = true
         )
-
-    ]
-    |> List.iter Chart.show
+    )
+    |> Chart.show
     0

Diff for: src/Plotly.NET/plotly-2.19.1.min.js.LICENSE.txt renamed to src/Plotly.NET/plotly-2.20.0.min.js.LICENSE.txt

@@ -8,8 +8,8 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <EmbeddedResource Include="..\..\..\src\Plotly.NET\plotly-2.19.1.min.js" />
-    <EmbeddedResource Include="..\..\..\src\Plotly.NET\plotly-2.19.1.min.js.LICENSE.txt" />
+    <EmbeddedResource Include="..\..\..\src\Plotly.NET\plotly-2.20.0.min.js" />
+    <EmbeddedResource Include="..\..\..\src\Plotly.NET\plotly-2.20.0.min.js.LICENSE.txt" />
     <!--HTMLCodegen-->
     <Compile Include="HTMLCodegen\Chart2D.fs" />
     <Compile Include="HTMLCodegen\Chart3D.fs" />
@@ -34,6 +34,7 @@
     <Compile Include="Traces\TraceStaticMembers.fs" />
     <Compile Include="Traces\TraceStyle.fs" />
     <Compile Include="Traces\TraceID.fs" />
+    <Compile Include="UpstreamFeatures\2.20.fs" />
     <Compile Include="UpstreamFeatures\2.19.fs" />
     <Compile Include="Main.fs" />
   </ItemGroup>

Diff for: tests/Common/FSharpTestBase/FSharpTestBase.fsproj

@@ -0,0 +1,27 @@
+module CoreTests.UpstreamFeatures.PlotlyJS_2_20
+
+open Expecto
+open Plotly.NET
+open Plotly.NET.LayoutObjects
+open Plotly.NET.TraceObjects
+open Plotly.NET.GenericChart
+
+open TestUtils.HtmlCodegen
+open PlotlyJS_2_20_TestCharts
+
+module TitleAutoMargin = 
+
+    [<Tests>]
+    let ``Title AutoMargin chart HTML codegeneration tests`` =
+        testList "UpstreamFeatures.PlotlyJS_2_20" [
+            testList "TitleAutoMargin" [
+                testCase "Title AutoMargin data" ( fun () ->
+                    """var data = [{"type":"scatter","mode":"markers","x":[1],"y":[2],"marker":{},"line":{}}];"""
+                    |> chartGeneratedContains TitleAutoMargin.``Title with AutoMargin``
+                )
+                testCase "Title AutoMargin layout" ( fun () ->
+                    """var layout = {"title":{"text":"Lorem ipsum dolor sit amet, <br>consetetur sadipscing elitr, sed diam nonumy eirmod <br>tempor invidunt ut labore et dolore magna aliquyam erat, <br>sed diam voluptua. At vero eos et accusam et justo <br>duo dolores et ea rebum. Stet clita kasd gubergren,<br>no sea takimata sanctus est Lorem ipsum dolor sit amet. <br>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, <br>sed diam nonumy eirmod tempor invidunt ut labore et <br>dolore magna aliquyam erat, sed diam voluptua. <br>At vero eos et accusam et justo duo dolores et ea rebum. <br>Stet clita kasd gubergren, no sea takimata sanctus est <br>Lorem ipsum dolor sit amet.","automargin":true}};"""
+                    |> chartGeneratedContains TitleAutoMargin.``Title with AutoMargin``
+                )
+            ]
+        ]