Merge pull request #21 from TickPoints/dev

Update v0.1.9-beta

Author: TickPoints

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook-plotly"
-version = "0.1.9-alpha"
+version = "0.1.9-beta"
 authors = ["TickPoints <tickpoints@outlook.com>"]
 edition = "2024"
 keywords = ["markdown", "mdbook"]

Cargo.toml

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## v0.1.9-beta
+- Updated interfaces
+    - Updated layout
+    - Updated config
+    - Updated legend
+    - Updated the `Color`
+- Fixed docs
+
 ## v0.1.9-alpha
 - Updated Cargo.toml
     - Adjusted deps

docs/CHANGELOG.md

@@ -32,6 +32,7 @@
             - [桑基图](#data-sankey)
             - [地理散点图](#data-scatter_geo)
             - [Mapbox 散点图](#data-scatter_mapbox)
+            - [极坐标散点图](#data-scatter_polar)
             - [Mapbox 密度热力图](#data-density_mapbox)
             - [表格](#data-table)
     - [SandBoxScript（已弃用）](#sand-box-script)
@@ -189,10 +190,9 @@ offline_js_sources = false
 - **Rgb** – `"rgb(u8, u8, u8)"`（例如 `"rgb(0, 0, 0)"`）
 - **Rgba** – `"rgba(u8, u8, u8, f64)"`（例如 `"rgba(0, 0, 0, 0.0)"`）
 - **Color** – 可以是：
-  * 命名的 CSS 颜色：`{ named_color: "aliceblue" }`
+  * 命名的 CSS 颜色：`"aliceblue"`
   * RGB 字符串：`"rgb(255, 0, 0)"`
   * RGBA 字符串：`"rgba(255, 0, 0, 0.5)"`
-  * 或等效的对象形式：`{ rgb_color: "rgb(255,0,0)" }`、`{ rgba_color: "rgba(255,0,0,0.5)" }`
 
 ### 映射与生成器
 
@@ -489,6 +489,10 @@ layout: {
     plot_background_color?: Color,
     // 分离器
     separators?: String,
+    // 是否启用自动尺寸调整（默认 true）
+    auto_size?: bool,
+    // 图纸背景色（区别于 plot_background_color）
+    paper_background_color?: Color,
 
     // 说明器具体设置
     legend?: {
@@ -506,6 +510,38 @@ layout: {
         trace_group_gap?: usize,
         // 标题
         title?: String,
+        // 图例项宽度（像素）
+        item_width?: usize,
+
+        // 图例中 trace 的显示顺序
+        // "normal": 正常顺序
+        // "reversed": 倒序
+        // "grouped": 按组显示
+        // "reversed+grouped": 倒序分组
+        trace_order?: "normal" | "reversed" | "grouped" | "reversed+grouped",
+
+        // 图例项尺寸模式
+        // "trace": 按 trace 宽度
+        // "constant": 恒定宽度
+        item_sizing?: "trace" | "constant",
+
+        // 单击图例项的效果
+        // "toggle": 切换该 trace
+        // "toggleothers": 切换其他 trace
+        // "false": 无操作
+        item_click?: "toggle" | "toggleothers" | "false",
+
+        // 双击图例项的效果（取值同 item_click）
+        item_double_click?: "toggle" | "toggleothers" | "false",
+
+        // 图例文本垂直对齐
+        // "top": 顶对齐 / "middle": 居中 / "bottom": 底对齐
+        valign?: "top" | "middle" | "bottom",
+
+        // 单击图例分组的效果
+        // "toggleitem": 切换组内所有项
+        // "togglegroup": 切换整个组
+        group_click?: "toggleitem" | "togglegroup",
     },
 
     // 图表边缘具体设置
@@ -575,6 +611,22 @@ config: {
     display_logo?: bool,
     // 使用公司标志对图像进行水印处理
     watermark?: bool,
+
+    // 控制模式栏的显示行为
+    // "hover": 仅悬停时显示
+    // "true": 始终显示（默认）
+    // "false": 不显示
+    display_mode_bar?: "hover" | "true" | "false",
+
+    // 双击图表的响应行为
+    // "false": 无操作
+    // "reset": 重置视图
+    // "autosize": 自动调整大小
+    // "reset+autosize": 重置并自动调整
+    double_click?: "false" | "reset" | "autosize" | "reset+autosize",
+
+    // 是否显示“在 Chart Studio 中编辑”链接（show_link 的别名）
+    show_edit_in_chart_studio?: bool,
 }
 ```
 
@@ -1108,6 +1160,76 @@ config: {
 }
 ```
 
+### Data-scatter_polar
+`scatter_polar`可以是一个`Data`。该`Data`将被渲染为极坐标散点图。
+```json5
+{
+    type: "scatter_polar",
+
+    // 角度坐标（单位：度，除非布局中指定了其他单位）
+    theta: [f64; usize],
+    // 径向坐标
+    r: [f64; usize],
+
+    // trace 名称，显示在图例和悬停信息中
+    name?: String,
+    // 是否在图例中显示此 trace
+    show_legend?: bool,
+    // 图例分组标识
+    legend_group?: String,
+    // 不透明度，0（透明）~ 1（不透明）
+    opacity?: f64,
+    // 数据点上显示的统一文本
+    text?: String,
+    // 为每个数据点单独设置显示文本
+    text_array?: [String; usize],
+    // 悬停时显示的统一文本
+    hover_text?: String,
+    // 为每个数据点单独设置悬停文本
+    hover_text_array?: [String; usize],
+    // 悬停标签模板
+    hover_template?: String,
+    // 为每个数据点单独设置悬停模板
+    hover_template_array?: [String; usize],
+    // 指定使用的极坐标子图（如 "polar"、"polar2"）
+    subplot?: String,
+    // 是否连接缺失数据点之间的间隙
+    connect_gaps?: bool,
+    // 径向坐标的参考起始值（与 dr 配合，将数组索引映射为实际径向距离）
+    r0?: f64,
+    // 径向步长
+    dr?: f64,
+    // 角度坐标的参考起始值（度）
+    theta0?: f64,
+    // 角度步长（度）
+    dtheta?: f64,
+    // 填充类型
+    // "tozeroy": 填充到 r=0
+    // "tozerox": 填充到 theta=0
+    // "tonexty": 填充到下一个 trace 的 r 值
+    // "tonextx": 填充到下一个 trace 的 theta 值
+    // "toself": 填充封闭区域自身
+    // "tonext": 填充到下一个 trace
+    // "none": 不填充
+    fill?: "tozeroy" | "tozerox" | "tonexty" | "tonextx" | "toself" | "tonext" | "none",
+    // 绘制模式
+    // "lines": 折线
+    // "markers": 散点标记
+    // "text": 仅文本
+    // "linesmarkers": 折线 + 标记
+    // "linestext": 折线 + 文本
+    // "markerstext": 标记 + 文本
+    // "linemarkerstext": 折线 + 标记 + 文本
+    // "none": 不显示
+    mode?: "lines" | "markers" | "text" | "linesmarkers" | "linestext" | "markerstext" | "linemarkerstext" | "none",
+    // 可见性控制
+    // "true": 可见（默认）
+    // "false": 不可见
+    // "legendonly": 不绘制但在图例中显示
+    visible?: "true" | "false" | "legendonly",
+}
+```
+
 ### Data-scatter
 `scatter`可以是一个`Data`。该`Data`将会被渲染为填充区域图。
 ```json5

docs/USAGE-zh_CN.md

@@ -32,6 +32,7 @@ This is the official user manual (English edition) for **mdbook-plotly**, a prep
             - [Sankey Diagrams](#data-sankey)
             - [Geographic Scatter Plots](#data-scatter_geo)
             - [Mapbox Scatter Plots](#data-scatter_mapbox)
+            - [Polar Scatter Plots](#data-scatter_polar)
             - [Mapbox Density Heatmaps](#data-density_mapbox)
             - [Tables](#data-table)
     - [SandBoxScript (Deprecated)](#sand-box-script)
@@ -189,10 +190,9 @@ The following notation is used throughout this reference to describe expected ty
 - **Rgb** – `"rgb(u8, u8, u8)"` (e.g., `"rgb(0, 0, 0)"`)
 - **Rgba** – `"rgba(u8, u8, u8, f64)"` (e.g., `"rgba(0, 0, 0, 0.0)"`)
 - **Color** – can be one of the following:
-  - A named CSS color: `{ named_color: "aliceblue" }`
-  - An RGB color: `{ rgb_color: "rgb(255, 0, 0)" }`
-  - An RGBA color: `{ rgba_color: "rgba(255, 0, 0, 0.5)" }`
-  - Alternatively, for RGB and RGBA, you can use the plain string forms `"rgb(255,0,0)"` or `"rgba(255,0,0,0.5)"` directly.
+  - A named CSS color: `"aliceblue"`
+  - An RGB color: `"rgb(255, 0, 0)"`
+  - An RGBA color: `"rgba(255, 0, 0, 0.5)"`
 
 ### Map and Generators
 
@@ -497,6 +497,10 @@ layout: {
     plot_background_color?: Color,
     // Separators
     separators?: String,
+    // Whether to enable automatic size adjustment (default true)
+    auto_size?: bool,
+    // Paper background colour (distinct from plot_background_color)
+    paper_background_color?: Color,
 
     // Legend configuration
     legend?: {
@@ -514,6 +518,38 @@ layout: {
         trace_group_gap?: usize,
         // Title
         title?: String,
+        // Width of each legend item (pixels)
+        item_width?: usize,
+
+        // Trace display order within the legend
+        // "normal": natural order
+        // "reversed": reversed order
+        // "grouped": grouped by trace group
+        // "reversed+grouped": reversed and grouped
+        trace_order?: "normal" | "reversed" | "grouped" | "reversed+grouped",
+
+        // Legend item sizing mode
+        // "trace": sized per trace
+        // "constant": constant width
+        item_sizing?: "trace" | "constant",
+
+        // Single-click behaviour on legend items
+        // "toggle": toggle the trace
+        // "toggleothers": toggle all other traces
+        // "false": no action
+        item_click?: "toggle" | "toggleothers" | "false",
+
+        // Double-click behaviour on legend items (same values as item_click)
+        item_double_click?: "toggle" | "toggleothers" | "false",
+
+        // Vertical alignment of legend text
+        // "top", "middle", "bottom"
+        valign?: "top" | "middle" | "bottom",
+
+        // Click behaviour on legend groups
+        // "toggleitem": toggle all items in the group
+        // "togglegroup": toggle the group
+        group_click?: "toggleitem" | "togglegroup",
     },
 
     // Chart margin configuration
@@ -549,9 +585,6 @@ config: {
     editable?: bool,
     // Whether auto-sizing is enabled
     autosizable?: bool,
-    // Whether to resize the layout when the window is resized
-    // WARNING: This option currently has no practical effect.
-    responsive?: bool,
     // Whether to fill the screen
     // NOTE: Only effective when `autosizable` is `true`.
     fill_frame?: bool,
@@ -583,6 +616,22 @@ config: {
     display_logo?: bool,
     // Watermark the image with a company logo
     watermark?: bool,
+
+    // Controls when the modebar appears
+    // "hover": only show on hover
+    // "true": always show (default)
+    // "false": never show
+    display_mode_bar?: "hover" | "true" | "false",
+
+    // Double-click behaviour
+    // "false": no action
+    // "reset": reset the chart view
+    // "autosize": autosize
+    // "reset+autosize": reset and autosize
+    double_click?: "false" | "reset" | "autosize" | "reset+autosize",
+
+    // Whether to show an "Edit in Chart Studio" link (alias for show_link)
+    show_edit_in_chart_studio?: bool,
 }
 ```
 
@@ -1127,6 +1176,78 @@ config: {
 }
 ```
 
+### Data-scatter_polar
+
+`scatter_polar` can be a `Data` entry. This `Data` will be rendered as a scatter plot in polar coordinates.
+
+```json5
+{
+    type: "scatter_polar",
+
+    // Angular coordinates (degrees unless layout.polar.angularaxis.thetaunit is overridden)
+    theta: [f64; usize],
+    // Radial coordinates
+    r: [f64; usize],
+
+    // Trace name, displayed in legend and hover info
+    name?: String,
+    // Whether to show this trace in the legend
+    show_legend?: bool,
+    // Legend group identifier
+    legend_group?: String,
+    // Opacity, from 0 (transparent) to 1 (opaque)
+    opacity?: f64,
+    // Uniform text displayed on data points
+    text?: String,
+    // Per-point text
+    text_array?: [String; usize],
+    // Uniform hover text
+    hover_text?: String,
+    // Per-point hover text
+    hover_text_array?: [String; usize],
+    // Hover label template
+    hover_template?: String,
+    // Per-point hover template
+    hover_template_array?: [String; usize],
+    // Polar subplot to use (e.g. "polar", "polar2")
+    subplot?: String,
+    // Whether to connect gaps between missing data points
+    connect_gaps?: bool,
+    // Reference start value for radial coordinates (used to map array indices to radial distance)
+    r0?: f64,
+    // Radial step (used with r0)
+    dr?: f64,
+    // Reference start value for angular coordinates (degrees)
+    theta0?: f64,
+    // Angular step (degrees)
+    dtheta?: f64,
+    // Fill style
+    // "tozeroy": fill to r=0
+    // "tozerox": fill to theta=0
+    // "tonexty": fill to next trace's r values
+    // "tonextx": fill to next trace's theta values
+    // "toself": fill enclosed area
+    // "tonext": fill to next trace
+    // "none": no fill
+    fill?: "tozeroy" | "tozerox" | "tonexty" | "tonextx" | "toself" | "tonext" | "none",
+    // Drawing mode
+    // "lines": lines only
+    // "markers": markers only
+    // "text": text only
+    // "linesmarkers": lines + markers
+    // "linestext": lines + text
+    // "markerstext": markers + text
+    // "linemarkerstext": lines + markers + text
+    // "none": hidden
+    mode?: "lines" | "markers" | "text" | "linesmarkers" | "linestext" | "markerstext" | "linemarkerstext" | "none",
+    // Visibility control
+    // "true": visible (default)
+    // "false": hidden
+    // "legendonly": not drawn but shown in legend
+    visible?: "true" | "false" | "legendonly",
+}
+```
+
 ### Data-scatter
 
 `scatter` can be a `Data` entry. This `Data` will be rendered as a filled area chart.