Skip to content

Commit 74bd9d5

Browse files
alshanalshan
committed
Improve documentation in the area of 'sizing policy'.
1 parent c62ce26 commit 74bd9d5

File tree

3 files changed

+169
-41
lines changed

3 files changed

+169
-41
lines changed

‎js-package/src/jsMain/kotlin/MonolithicJs.kt

+79-16
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,46 @@ private val LOG = PortableLogging.logger("MonolithicJs")
3333
private const val DATALORE_PREFERRED_WIDTH = "letsPlotPreferredWidth"
3434

3535
/**
36-
* The entry point to call in JS
37-
* `raw specs` are plot specs not processed by datalore plot backend
36+
* Main entry point for creating plots from the JavaScript environment.
37+
*
38+
* Takes "raw" plot specifications (not processed by plot backend)
39+
* and constructs the plot with the specified sizing configuration.
40+
*
41+
* The `sizingJs` parameter is a JavaScript object with the structure:
42+
* {
43+
* width_mode: String // "fixed", "min", "fit", or "scaled" (case-insensitive)
44+
* height_mode: String // "fixed", "min", "fit", or "scaled" (case-insensitive)
45+
* width: Number // optional
46+
* height: Number // optional
47+
* }
48+
*
49+
* Sizing modes:
50+
*
51+
* 1. FIXED mode:
52+
* - Uses the explicitly provided width/height values
53+
* - Falls back to the default figure size if no values provided
54+
* - Not responsive to container size
55+
*
56+
* 2. MIN mode:
57+
* Applies the smallest dimension among:
58+
* - The default figure size
59+
* - The specified width/height (if provided)
60+
* - The container size (if available)
61+
*
62+
* 3. FIT mode:
63+
* Uses either:
64+
* - The specified width/height if provided
65+
* - Otherwise uses container size if available
66+
* - Falls back to default figure size if neither is available
67+
*
68+
* 4. SCALED mode:
69+
* - Always preserves the figure's aspect ratio
70+
* - Typical usage: one dimension (usually width) uses FIXED/MIN/FIT mode
71+
* and SCALED height adjusts to maintain aspect ratio
72+
* - Special case: when both width and height are SCALED:
73+
* * Requires container size to be available
74+
* * Fits figure within container while preserving aspect ratio
75+
*
3876
*/
3977
@OptIn(ExperimentalJsExport::class)
4078
@Suppress("unused")
@@ -72,21 +110,46 @@ fun buildPlotFromRawSpecs(
72110
}
73111

74112
/**
75-
* The entry point to call in JS
76-
* `processed specs` are plot specs processed by datalore plot backend.
113+
* Main entry point for creating plots from the JavaScript environment.
114+
*
115+
* Takes "processed" plot specifications (processed by plot backend)
116+
* and constructs the plot with the specified sizing configuration.
117+
*
118+
* The `sizingJs` parameter is a JavaScript object with the structure:
119+
* {
120+
* width_mode: String // "fixed", "min", "fit", or "scaled" (case-insensitive)
121+
* height_mode: String // "fixed", "min", "fit", or "scaled" (case-insensitive)
122+
* width: Number // optional
123+
* height: Number // optional
124+
* }
125+
*
126+
* Sizing modes:
127+
*
128+
* 1. FIXED mode:
129+
* - Uses the explicitly provided width/height values
130+
* - Falls back to the default figure size if no values provided
131+
* - Not responsive to container size
132+
*
133+
* 2. MIN mode:
134+
* Applies the smallest dimension among:
135+
* - The default figure size
136+
* - The specified width/height (if provided)
137+
* - The container size (if available)
138+
*
139+
* 3. FIT mode:
140+
* Uses either:
141+
* - The specified width/height if provided
142+
* - Otherwise uses container size if available
143+
* - Falls back to default figure size if neither is available
144+
*
145+
* 4. SCALED mode:
146+
* - Always preserves the figure's aspect ratio
147+
* - Typical usage: one dimension (usually width) uses FIXED/MIN/FIT mode
148+
* and SCALED height adjusts to maintain aspect ratio
149+
* - Special case: when both width and height are SCALED:
150+
* * Requires container size to be available
151+
* * Fits figure within container while preserving aspect ratio
77152
*
78-
* @param plotSpecJs plot specifications (a dictionary)
79-
* @param parentElement DOM element to add the plot to.
80-
* The plot size will be determined using `clientWidth` of the parent element.
81-
* @param optionsJs miscellaneous settings.
82-
* For example, set max width to 500px:
83-
* optionsJs = {
84-
* sizing: {
85-
* width_mode: "min",
86-
* height_mode: "scaled",
87-
* width: 500
88-
* }
89-
* };
90153
*/
91154
@OptIn(ExperimentalJsExport::class)
92155
@Suppress("unused")

‎plot-stem/src/commonMain/kotlin/org/jetbrains/letsPlot/core/util/sizing/SizingPolicy.kt

+38
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,44 @@ import kotlin.math.min
1818

1919
private val LOG = PortableLogging.logger("Lets-Plot SizingPolicy")
2020

21+
/**
22+
* Controls the sizing behavior of plots by managing width and height dimensions
23+
* according to different sizing modes.
24+
*
25+
* The policy determines how a plot's dimensions should be calculated based on:
26+
* - The default figure size
27+
* - The container size (if available)
28+
* - The specified width and height values
29+
* - The sizing modes for both width and height
30+
*
31+
* Sizing modes:
32+
*
33+
* 1. FIXED mode:
34+
* - Uses the explicitly provided width/height values
35+
* - Falls back to the default figure size if no values provided
36+
* - Not responsive to container size
37+
*
38+
* 2. MIN mode:
39+
* Applies the smallest dimension among:
40+
* - The default figure size
41+
* - The specified width/height (if provided)
42+
* - The container size (if available)
43+
*
44+
* 3. FIT mode:
45+
* Uses either:
46+
* - The specified width/height if provided
47+
* - Otherwise uses container size if available
48+
* - Falls back to default figure size if neither is available
49+
*
50+
* 4. SCALED mode:
51+
* - Always preserves the figure's aspect ratio
52+
* - Typical usage: one dimension (usually width) uses FIXED/MIN/FIT mode
53+
* and SCALED height adjusts to maintain aspect ratio
54+
* - Special case: when both width and height are SCALED:
55+
* * Requires container size to be available
56+
* * Fits figure within container while preserving aspect ratio
57+
*
58+
*/
2159
class SizingPolicy(
2260
val widthMode: SizingMode,
2361
val heightMode: SizingMode,

‎python-package/lets_plot/_kbridge.py

+52-25
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66

77
import lets_plot_kotlin_bridge
88

9-
from ._type_utils import standardize_dict
109
from ._global_settings import get_js_cdn_url
10+
from ._type_utils import standardize_dict
1111

1212

1313
def _generate_dynamic_display_html(plot_spec: Dict) -> str:
@@ -50,15 +50,16 @@ def _generate_static_configure_html() -> str:
5050

5151

5252
def _generate_display_html_for_raw_spec(
53-
plot_spec: Dict,
54-
sizing_options: Dict,
55-
*,
56-
dynamic_script_loading: bool = False,
57-
force_immediate_render: bool = False,
58-
responsive: bool = False
53+
plot_spec: Dict,
54+
sizing_options: Dict,
55+
*,
56+
dynamic_script_loading: bool = False,
57+
force_immediate_render: bool = False,
58+
responsive: bool = False
5959
) -> str:
6060
"""
61-
Generate HTML for displaying a plot from raw specification with customizable options.
61+
Generate HTML for displaying a plot from 'raw' specification (not processed by plot backend)
62+
with customizable options.
6263
6364
Parameters
6465
----------
@@ -67,9 +68,14 @@ def _generate_display_html_for_raw_spec(
6768
sizing_options : Dict
6869
Dict containing sizing policy options (width_mode, height_mode, width, height).
6970
dynamic_script_loading : bool, default=False
70-
If True, loads JS library dynamically; if False, expects static loading.
71+
Controls how the generated JS code interacts with the lets-plot JS library.
72+
If True, assumes the library will be loaded dynamically.
73+
If False, assumes the library is already present in the page header (static loading).
7174
force_immediate_render : bool, default=False
75+
Controls the timing of plot rendering.
7276
If True, forces immediate plot rendering.
77+
If False, waits for ResizeObserver(JS) event and renders the plot after the plot
78+
container is properly layouted in DOM.
7379
responsive : bool, default=False
7480
If True, makes the plot responsive to container size changes.
7581
@@ -80,21 +86,42 @@ def _generate_display_html_for_raw_spec(
8086
8187
Notes
8288
-----
83-
The sizing_options dict supports the following keys:
84-
- width_mode : str
85-
One of: 'fit', 'min', 'scaled', 'fixed'
86-
- height_mode : str
87-
One of: 'fit', 'min', 'scaled', 'fixed'
88-
- width : number, optional
89-
The width value (used with 'fixed' mode).
90-
- height : number, optional
91-
The height value (used with 'fixed' mode).
92-
93-
The modes determine how the plot dimensions are computed:
94-
- 'fit': uses the container dimension
95-
- 'min': uses the smaller of plot's own dimension or container dimension
96-
- 'scaled': computes dimension to preserve plot's aspect ratio
97-
- 'fixed': uses plot's own dimension (non-responsive)
89+
The sizing_options dict supports the following structure:
90+
{
91+
'width_mode': str, # 'fixed', 'min', 'fit', 'scaled' (case-insensitive)
92+
'height_mode': str, # 'fixed', 'min', 'fit', 'scaled' (case-insensitive)
93+
'width': number, # optional
94+
'height': number # optional
95+
}
96+
97+
Sizing modes determine how the plot dimensions are calculated:
98+
99+
1. FIXED mode:
100+
- Uses the explicitly provided width/height values
101+
- Falls back to the default figure size if no values provided
102+
- Not responsive to container size
103+
104+
2. MIN mode:
105+
Applies the smallest dimension among:
106+
- The default figure size
107+
- The specified width/height (if provided)
108+
- The container size (if available)
109+
110+
3. FIT mode:
111+
Uses either:
112+
- The specified width/height if provided
113+
- Otherwise uses container size if available
114+
- Falls back to default figure size if neither is available
115+
116+
4. SCALED mode:
117+
- Always preserves the figure's aspect ratio
118+
- Typical usage: one dimension (usually width) uses FIXED/MIN/FIT mode
119+
and SCALED height adjusts to maintain aspect ratio
120+
- Special case: when both width and height are SCALED:
121+
* Requires container size to be available
122+
* Fits figure within container while preserving aspect ratio
123+
* Neither dimension is predetermined
124+
98125
"""
99126
plot_spec = _standardize_plot_spec(plot_spec)
100127
sizing_options = standardize_dict(sizing_options)
@@ -104,4 +131,4 @@ def _generate_display_html_for_raw_spec(
104131
dynamic_script_loading,
105132
force_immediate_render,
106133
responsive
107-
)
134+
)

0 commit comments

Comments
 (0)