# CHANGELOG
## v0.3.0-alpha
- 2026-08-01
- **Added** — the full (TUI) edition as an optional `tui` Cargo feature
- Two binary variants are now shipped: **slim** (default, preprocessor only) and **full** (`-tui`, preprocessor + interactive TUI). Asset names follow `docs/RELEASE.md`; the self-update tool only ever matches assets of its own variant.
- New `mdbook-plotly tui` subcommand hosting three tools:
- **Self-update**: checks GitHub Releases for the latest tag, compares against the running version with semver, downloads the matching `-tui` asset, verifies its `.sha256`, and atomically replaces the running binary after explicit confirmation. Supports `--dry-run` and reads `GITHUB_TOKEN` for the API rate limit.
- **book.toml editor**: walks up from the working directory to find `book.toml`, guides edits of the `[preprocessor.plotly]` keys with per-field descriptions and valid ranges, uses `toml_edit` so comments/formatting are preserved, shows a diff before writing, and writes atomically via temp-file + rename.
- **Plot cheat-sheet**: searches, previews, and copies the minimal examples from `docs/USAGE.md` (cache → release-tag docs → stale cache, so it works offline after the first fetch). Clipboard failures fall back to printing to stdout.
- The cheat-sheet reads the user manual in the language detected from `MDBOOK_PLOTLY_LANG` → `[language] doc` in the settings file → the system locale; both the English and Chinese manuals carry the same machine-readable schema and example ids.
- All GitHub traffic (API, asset downloads, cheat-sheet fetches) is routed through configurable endpoints — `MDBOOK_PLOTLY_GITHUB_PROXY` / `MDBOOK_PLOTLY_GITHUB_API` / `MDBOOK_PLOTLY_GITHUB_RAW` / `MDBOOK_PLOTLY_GITHUB_DOWNLOAD` env vars and/or `~/.config/mdbook-plotly/config.toml` — with no hardcoded GitHub URL.
- The slim edition recognizes the `tui` command and prints install/download instructions instead of an "unknown subcommand" error.
- **Added** — machine-readable schema for `docs/USAGE.md` plot examples
- `<!-- usage-schema: 1 -->` marker plus `<!-- plot:begin/end -->` blocks, specified in `docs/USAGE-SCHEMA.md`. The parser is lenient (unknown fields ignored, malformed blocks skipped with a warning) and degrades gracefully for newer schema versions.
- New `docs_parser` module and an integration test that parses the real `docs/USAGE.md` and asserts every block is complete and every example is valid chart input, so future doc edits are validated in CI.
- **Added** — `docs/RELEASE.md` defining the release-asset naming contract shared by CI and the updater.
- **Changed** — CI now builds and uploads both variants per target (with `cargo build --locked --release`), generates a `.sha256` per asset, and runs `clippy -D warnings` + `cargo test` for both feature combinations (including the docs-schema tests) on every PR/push.
- **Changed** — code organization: the TUI sources were split into focused modules (logic vs. views vs. configuration), all unit tests now live under `tests/`, and the GitHub endpoint logic was extracted into a configurable module with `thiserror`-based error types.
- **Fixed** — none (no behavior changes to the preprocessor itself).
## v0.2.3
- Improved `book.toml` configuration parsing
- Ignored unknown keys at both the top level and inside nested sections such as `map-eval`, while logging a warning for each unknown key path
- Preserved type-sensitive validation for known fields, but limited failures to the field or nested section that failed to parse
- Kept other configuration fields active when one field falls back to its default value
## v0.2.2
- Improved mdBook preprocessing performance
- Skips Markdown parser/cmark rewriting for chapters that cannot contain `plot` / `plotly` blocks
- Injects the Plotly HTML header only when a chart is successfully generated
- Added complete Markdown chapter coverage for mixed prose, regular code fences, and plot fences
- Refined map parser internals
- Split map lookup, expression evaluation, and color parsing into focused modules while preserving existing public imports
- Implemented `reuse-slab` behavior for expression evaluation modes
- Reduced per-item allocation in `g-number-list` generation
## v0.2.2-beta
- Added TOML chart input support
- Added the [`toml`](Cargo.toml:23) dependency and a new [`PlotlyInputType::TOMLInput`](src/preprocessor/config.rs:82) variant
- Added [`handle_toml_input()`](src/code_handler.rs:35) to convert TOML into [`serde_json::Value`](src/code_handler.rs:8) before reusing the existing plot parser
- Added regression coverage in [`tests/test_code_handler.rs`](tests/test_code_handler.rs:55) for direct TOML handling and config-driven input dispatch
## v0.2.2-alpha
- Refined layout parser release-prep cleanup
- Normalized axis `type` error messages in [`parse_axis_obj()`](src/code_handler/plot_obj_parser/layout_parser.rs:256) to match the field-oriented style already used by [`translate_with_config!()`](src/macros.rs:36) and [`translate_enum_with_config!()`](src/macros.rs:66)
- Kept axis parsing on explicit [`ParseContext`](src/code_handler/parse_context.rs:4) / [`MapEvalConfig`](src/preprocessor/config.rs:61) propagation without reintroducing hidden defaults
- Added an axis regression test in [`tests/test_code_handler.rs`](tests/test_code_handler.rs) covering `map.*`-backed `range`, `tick_prefix`, `tick_suffix`, `title`, `anchor`, `overlaying`, `show_tick_labels`, `auto_margin`, `fixed_range`, and axis `type`
- Updated release documentation
- Clarified that parser migration work favors [`translate_with_config!()`](src/macros.rs:36) and [`translate_enum_with_config!()`](src/macros.rs:66) over legacy [`translate!()`](src/macros.rs:29) in active parsing paths
- Documented `map-eval` / `map-parser-extensions` behavior more explicitly in user-facing docs
- Adjusted configs
- Removed `offline_js_sources`
## v0.2.1
- Refined parser migration toward explicit [`MapEvalConfig`](src/preprocessor/config.rs:61) propagation
- Replaced top-level legacy [`translate!()`](src/macros.rs:29) usage in [`parse_config_obj()`](src/code_handler/plot_obj_parser/layout_parser.rs:8) and [`parse_layout_obj()`](src/code_handler/plot_obj_parser/layout_parser.rs:59) with explicit [`translate_with_config!()`](src/macros.rs:36) entrypoints
- Updated tests to validate the migration path remains stable
- Added a layout/config regression case in [`tests/test_code_handler.rs`](tests/test_code_handler.rs) covering `map.*`-backed title, legend, axis range, and config parsing
## v0.2.1-beta
- Refined parser migration toward explicit [`MapEvalConfig`](src/preprocessor/config.rs:61) propagation
- Migrated trace parsers to consume [`ParseContext`](src/code_handler/parse_context.rs:4) instead of raw `map` where applicable
- Removed [`must_translate()`](src/code_handler/until.rs:29) and migrated remaining translation paths to explicit [`ParseContext`](src/code_handler/parse_context.rs:4) / config-driven helpers
- Threaded active map-eval config through generator parsing paths in [`src/code_handler/until.rs`](src/code_handler/until.rs)
- Reused shared helpers like [`parse_marker()`](src/code_handler/plot_obj_parser/common.rs:7) and [`parse_color_bar()`](src/code_handler/plot_obj_parser/common.rs:59) to reduce duplicated translation logic
- Slimmed trace registry dispatch in [`trace_registry.rs`](src/code_handler/plot_obj_parser/trace_registry.rs:1)
- Removed registry-side `.map(into_trace)` adaptation
- Moved trait-object conversion boundaries down into parser modules via `*_trace()` entrypoints
- Updated tests to validate the migration path remains stable
## v0.2.1-alpha
- Refined plot parser structure
- Refined parser config propagation
- Updated deps
## v0.2.0
- Added **Layout field expansion** — Phase 1 & 2
- **Phase 1 (Basic fields)**:
- Spacing: `bar_gap`, `bar_group_gap`, `box_gap`, `box_group_gap`
- Interaction: `hover_mode`, `drag_mode`, `click_mode`
- Sub-objects: `font` (family/size/color), `coloraxis` (cmin/cmax/cmid/auto/reverse/show)
- **Phase 2 (Axis support)**:
- Default axes: `xaxis`, `yaxis` with full field support
- Named axes: `xaxis2`–`xaxis8`, `yaxis2`–`yaxis8`
- Axis fields: `title`, `show_grid`, `show_line`, `zero_line`, `visible`,
`anchor`, `overlaying`, `range`, `color`, `line_color`, `grid_color`,
`tick_prefix`, `tick_suffix`, `tick_format`, `hover_format`, `category_array`,
`fixed_range`, `scale_anchor`, `auto_margin`, `show_tick_labels`
- Axis enums: `category_order` (16 variants), `type` (linear/log/date/category/multicategory)
- Added helper functions: `parse_axis_obj()`, `parse_named_axes()`
- Added 3 axis tests (xaxis, date type, named axes)
- Updated documentation (USAGE-zh_CN.md, USAGE.md) with new Layout fields and Axis reference
## v0.2.0-beta
- Added 6 new Data trace types
- Added `box` (BoxPlot)
- Added `contour` (Contour)
- Added `heatmap` (HeatMap)
- Added `mesh3d` (Mesh3D)
- Added `scatter3d` (Scatter3D)
- Added `surface` (Surface)
- Updated docs for all new trace types (USAGE-zh_CN.md, USAGE.md)
- Added comprehensive tests for all existing and new trace types
- Re-exported all new trace types in `src/code_handler/plot_obj_parser.rs`
## v0.1.9
- Updated interfaces
- Added Marker in `bar`, `histogra`, `pie`, `scatter`, `scatter_geo`, `scatter_mapbox`, `scatter_polar`
- Updated tests and macros
## 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
- Added `chrono`
- Adjusted features
- Add the `map-parser-extensions` feature
- Updated interfaces
- Updated the map parser
- Updated `time`, `g-random`, `g-choose`
- Fixed docs
## v0.1.8
> [!NOTE]
> Hotfix. Please don't use old versions.
- Fixed `BookData`
## v0.1.8-alpha
- Adjusted `code_handler`
- Updated `map`
- Fixed docs
- Updated tests
## v0.1.7
- Adjusted `code_handler`
- Updated `map`
- Fixed docs
- Updated tests
## v0.1.7-beta.2
- Adjusted `code_handler`
- Updated `map`
- Fixed docs
- Adjusted `Cargo.toml`
- Added the `fasteval` crate
## v0.1.7-beta
- Adjusted `code_handler`
- Adjusted `must_translate`
- Added `translate_enum`
- Made it all to support `DataPack`(Map)
- Updated docs
## v0.1.7-alpha
- Adjusted `Cargo.toml`
- The preview version would now provide the symbols.
## v0.1.6
- Adjusted `Cargo.toml`
- Adjusted `[profile.release]`
- Updated docs
## v0.1.6-beta
- Adjusted interfaces
- Adjusted Config
- Adjusted other Datas
- Added Color enum
- Updated docs
- Updated tests
## v0.1.6-alpha
- Adjusted interfaces
- Added Data-candlestick
- Added Data-sankey
- Added Data-scatter_polar
- Added Data-table
- Added Data-ohlc
- Updated docs
## v0.1.5-alpha
- Adjusted interfaces
- Added Data-density_mapbox
- Added Data-histogram
- Added Data-image
- Added Data-scatter_geo
- Added Data-scatter_mapbox
- Adjusted other Datas
- Updated docs
- Updated some tests
## v0.1.4-alpha
> [!WARNING]
> Although `plotly_svg_handler` is updated, it is not available.
- Updated `plotly_svg_handler`
- Adjusted interfaces
- Add Data-scatter
- Adjust Data-bar
## v0.1.3-beta
- Added interfaces
- Added `Data-bar`
- Used `usize` instead of `u64`
- Adjusted deps
- Added `anyhow`
- Added `env_logger` instead of `chlog`
- Used `anyhow` to optimize
## v0.1.3-alpha
- Added interfaces
- Added to `Config`
- `editable`
- `autosizable`
- `responsive`
- `scroll_zoom`
- `fill_frame`
- `frame_margins`
- `show_axis_drag_handlers`
- `show_axis_range_entry_boxes`
- `show_tips`
- `show_link`
- `send_data`
- Updated `docs/USAGE-zh_CN.md`
- Adjusted deps
- Added `rand`
- Adjusted features
- Added `dep:rand` to `plotly-backed`
## v0.1.2-alpha
- Optimized parsers performance in `code_handler`
- Fixed parser bugs
## v0.1.1-alpha
> [!WARNING]
> The changelog of `0.1.0-alpha` has been incorporated into this release.
- Added `plotly-html-handler`
- Added interfaces
- Added `pie` plot
- Updated docs
- Created workflows