docs: add quick references for composition, DataTable, and versioned themes

Author: watsonryan

README.md

@@ -25,8 +25,12 @@ Pure C++20 plotting API with a gnuplot renderer for figures.
 - Data transforms (`moving_average`, `downsample_uniform`, `autocorrelation`)
 - CSV ingestion and unit-aware labels (`read_csv_numeric`, `label_with_unit`)
 - Faceting helpers (`facet_grid`, `apply_facet_axes`)
+- Composition helpers (`apply_panel_titles`, `apply_shared_legend`, `apply_shared_colorbar_label`)
+- Auto legend placement heuristic (`auto_place_legend`)
 - YAML declarative spec loading (`load_yaml_figure_spec`)
 - Template gallery and quick templates (`apply_plot_template`, `write_template_gallery_yaml`)
+- DataTable column plotting adapters (`add_line`, `add_scatter`)
+- Versioned theme presets (`ThemePreset::*_v1`)
 - Font fallback chain for cross-format typography consistency
 - Reproducibility manifest export (`manifest.json`)
 

docs/EXAMPLES.md

@@ -13,6 +13,7 @@ This file maps repository examples to practical use-cases.
 
 - `feature_rich_showcase.cpp`: confidence bands, histogram+KDE, heatmap, y2 axis.
 - `interactive_facet_example.cpp`: facet grid + interactive preview script.
+- `interactive_facet_example.cpp`: facet grid + shared legend + auto legend placement + DataTable column plotting.
 - `yaml_spec_example.cpp`: declarative plotting from YAML.
 - `stats_plot_examples.cpp`: Q-Q, violin, box summary, confidence ellipses, autocorrelation.
 - `monte_carlo_alpha_example.cpp`: dense ensemble rendering + 3-sigma envelope.
@@ -44,3 +45,24 @@ When creating a new example, copy one close to your use-case:
 1. Keep `FigureSpec` + profile setup.
 2. Replace data generation with your source.
 3. Keep `fig.save(out_dir / "figures")` convention.
+
+## New Composition + DataTable Pattern
+
+```cpp
+auto tbl = gnuplotpp::read_csv_numeric("demo.csv");
+gnuplotpp::apply_facet_axes(fig, base, {"A", "B", "C", "D"});
+gnuplotpp::apply_panel_titles(fig, {"A", "B", "C", "D"});
+
+for (int k = 0; k < 4; ++k) {
+  const auto& y = tbl.column(cols_name[k]);
+  auto ax_spec = fig.axes(k).spec();
+  gnuplotpp::auto_place_legend(ax_spec, tbl.column("t"), y);
+  fig.axes(k).set(ax_spec);
+  tbl.add_line(fig.axes(k), {.label = "mean"}, "t", cols_name[k]);
+}
+
+gnuplotpp::LegendSpec shared_legend;
+shared_legend.enabled = true;
+shared_legend.position = gnuplotpp::LegendPosition::TopLeft;
+gnuplotpp::apply_shared_legend(fig, shared_legend, 0);
+```

docs/PLOT_CONTROLS.md

@@ -15,6 +15,8 @@ This document is the full control reference for `gnuplotpp` plotting.
 - `gnuplotpp::save_theme_json` / `gnuplotpp::load_theme_json`
 - `gnuplotpp::read_csv_numeric`
 - `gnuplotpp::facet_grid` / `gnuplotpp::apply_facet_axes`
+- `gnuplotpp::apply_panel_titles` / `gnuplotpp::apply_shared_legend` / `gnuplotpp::apply_shared_colorbar_label`
+- `gnuplotpp::auto_legend_position` / `gnuplotpp::auto_place_legend`
 - `gnuplotpp::load_yaml_figure_spec`
 - `gnuplotpp::apply_plot_template`
 
@@ -206,6 +208,9 @@ gnuplotpp::confidence_ellipse(x, y, 2.0, ell_x, ell_y, 200);
 
 ```cpp
 auto tbl = gnuplotpp::read_csv_numeric("signals.csv");
+if (tbl.has_column("time") && tbl.has_column("error")) {
+  tbl.add_line(fig.axes(0), {.label = "error"}, "time", "error");
+}
 auto [rows, cols] = gnuplotpp::facet_grid(6);
 fs.rows = rows;
 fs.cols = cols;
@@ -214,6 +219,14 @@ gnuplotpp::AxesSpec base;
 base.xlabel = gnuplotpp::label_with_unit("time", "s");
 base.ylabel = gnuplotpp::label_with_unit("error", "m");
 gnuplotpp::apply_facet_axes(fig, base, {"A","B","C","D","E","F"});
+
+// Composition helpers
+gnuplotpp::apply_panel_titles(fig, {"(a)", "(b)", "(c)", "(d)", "(e)", "(f)"});
+gnuplotpp::LegendSpec shared_legend;
+shared_legend.enabled = true;
+shared_legend.position = gnuplotpp::LegendPosition::TopLeft;
+gnuplotpp::apply_shared_legend(fig, shared_legend, 0);
+gnuplotpp::apply_shared_colorbar_label(fig, "density", rows * cols - 1);
 ```
 
 ### YAML Figure Spec

docs/STYLING_AND_PRESETS.md

@@ -25,6 +25,15 @@ gnuplotpp::apply_style_profile(fs, gnuplotpp::StyleProfile::Tufte_Minimal);
 - `DarkPrintSafe`
 - `Tufte_Minimal`
 
+## Versioned Theme Presets
+
+For reproducibility across releases, use versioned theme ids:
+
+```cpp
+gnuplotpp::apply_theme_preset(fs, gnuplotpp::ThemePreset::IEEE_Strict_v1);
+auto id = gnuplotpp::theme_preset_id(gnuplotpp::ThemePreset::IEEE_Strict_v1);
+```
+
 ## Typography Model
 
 Typography is preset/profile-driven by default: