quantized-lab 0.10.0__tar.gz → 0.11.0__tar.gz

{quantized_lab-0.10.0 → quantized_lab-0.11.0}/.gitignore

@@ -16,6 +16,13 @@ node_modules/
 frontend/dist/
 *.tsbuildinfo
 
+# ── Playwright E2E (GUI_INTERACTION_PLAN #15) ──────────────────────────
+frontend/test-results/
+frontend/playwright-report/
+frontend/e2e/test-results/
+frontend/e2e/playwright-report/
+frontend/blob-report/
+
 # ── Tauri / desktop ───────────────────────────────────────────────────
 src-tauri/target/
 

{quantized_lab-0.10.0 → quantized_lab-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantized-lab
-Version: 0.10.0
+Version: 0.11.0
 Summary: Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines.
 Project-URL: Homepage, https://github.com/pquarterman17/quantized
 Project-URL: Documentation, https://github.com/pquarterman17/quantized/wiki

{quantized_lab-0.10.0 → quantized_lab-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantized-lab"
-version = "0.10.0"
+version = "0.11.0"
 description = "Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines."
 readme = "README.md"
 requires-python = ">=3.11"

{quantized_lab-0.10.0 → quantized_lab-0.11.0}/src/quantized/__init__.py

@@ -7,5 +7,5 @@ Layered, enforced architecture (see CLAUDE.md):
 
 from __future__ import annotations
 
-__version__ = "0.10.0"
+__version__ = "0.11.0"
 __all__ = ["__version__"]

{quantized_lab-0.10.0 → quantized_lab-0.11.0}/src/quantized/app.py

@@ -25,12 +25,14 @@ from quantized.routes import (
     calc,
     corrections,
     crystallography,
+    database,
     diffusion,
     electrical,
     electrochemistry,
     export,
     export_facets,
     export_figures,
+    export_figures_aux,
     export_page,
     fitting,
     fitting_bumps,
@@ -146,6 +148,7 @@ def create_app() -> FastAPI:
     application.include_router(import_template.router)
     application.include_router(plot.router)
     application.include_router(corrections.router)
+    application.include_router(database.router)
     application.include_router(fitting.router)
     application.include_router(fitting_bumps.router)
     application.include_router(jobs_api.router)
@@ -156,6 +159,7 @@ def create_app() -> FastAPI:
     application.include_router(reference.router)
     application.include_router(export.router)
     application.include_router(export_figures.router)
+    application.include_router(export_figures_aux.router)
     application.include_router(export_facets.router)
     application.include_router(export_page.router)
     application.include_router(report_export.router)

{quantized_lab-0.10.0 → quantized_lab-0.11.0}/src/quantized/calc/figure.py

@@ -32,7 +32,7 @@ from quantized.calc.figure_ticks import apply_tick_formats, apply_tick_steps  #
 __all__ = ["draw_series_axes", "render_figure", "style_rc"]
 
 _FORMATS = ("pdf", "svg", "png", "tiff")
-_LINESTYLE = {"solid": "-", "dashed": "--", "dotted": ":"}
+_LINESTYLE = {"solid": "-", "dashed": "--", "dotted": ":", "none": "none"}
 # Fixed fill translucency for MAIN #13 (fill under/between curves) — matches
 # the screen side's `uplotFill.ts` FILL_ALPHA_PCT (25%) so an exported figure
 # reads the same as its on-screen counterpart.
@@ -278,6 +278,11 @@ def _render_impl(
     y_fmt: Mapping[str, Any] | None = None,
     x_step: float | None = None,
     y_step: float | None = None,
+    y2_mask: Sequence[bool] | None = None,
+    y2_label: str = "",
+    y2_scale: str | None = None,
+    y2_fmt: Mapping[str, Any] | None = None,
+    y2_step: float | None = None,
 ) -> bytes | dict[str, Any]:
     """Render ``series`` (each ``(label, y)``) against ``x`` to image bytes.
 
@@ -303,7 +308,17 @@ def _render_impl(
     (MAIN #12) select linear/log/reciprocal; ``x_log``/``y_log`` are the
     back-compat boolean fallback (see :func:`draw_series_axes`'s doc).
     ``x_fmt``/``y_fmt`` (MAIN #24) are the tick-label number format -- see
-    :func:`draw_series_axes`'s doc.
+    :func:`draw_series_axes`'s doc. ``y2_mask`` (parallel to ``series``,
+    ``True`` marks a channel drawn on a secondary/right Y axis) dispatches to
+    :func:`quantized.calc.figure_y2.render_with_secondary_axis` -- a real
+    ``Axes.twinx()`` -- instead of ``draw_series_axes``'s single axes;
+    ``None``/all-``False`` (the default) is today's single-axis behaviour,
+    byte-identical. ``y2_label``/``y2_scale``/``y2_fmt``/``y2_step`` mirror
+    their primary-axis counterparts but apply only to the secondary axis;
+    a fixed secondary range rides ``overrides["y2_lim"]`` (see
+    ``figure_y2.render_with_secondary_axis``'s doc). Not compatible with
+    ``x_breaks`` (raises ``ValueError``) -- a broken figure has several
+    axes already and gains no coherent secondary-axis meaning.
     """
     if fmt not in _FORMATS:
         raise ValueError(f"fmt must be one of {_FORMATS}")
@@ -315,11 +330,16 @@ def _render_impl(
     title = safe_mathtext_label(title)
     x_label = safe_mathtext_label(x_label)
     y_label = safe_mathtext_label(y_label)
+    y2_label = safe_mathtext_label(y2_label)
     series = [(safe_mathtext_label(label), y) for label, y in series]
     st = figure_style(style)
     ov = dict(overrides or {})
     _validate_overrides(ov)
     resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+    y2_mask_list = list(y2_mask) if y2_mask is not None else [False] * len(series)
+    if len(y2_mask_list) != len(series):
+        raise ValueError("y2_mask must have the same length as series")
+    has_y2 = any(y2_mask_list)
 
     # rc_context scopes typography to this render (see style_rc). (matplotlib's
     # RcParams Literal-key type is impractical with the dynamic font.<generic>
@@ -329,6 +349,8 @@ def _render_impl(
 
     xv: NDArray[np.float64] = np.asarray(x, dtype=float)
     x_breaks = ov.get("x_breaks")
+    if has_y2 and x_breaks:
+        raise ValueError("y2_keys is not supported together with x_breaks")
     with matplotlib.rc_context(rc):  # type: ignore[arg-type]
         # Manual axis breaks (gap #21): a distinct, twinned-panel rendering
         # path — not compatible with the hit-map collector (collect_map is
@@ -365,26 +387,42 @@ def _render_impl(
             )
         fig, ax = plt.subplots(figsize=figsize)
         try:
-            artists = draw_series_axes(
-                fig,
-                ax,
-                xv,
-                series,
-                st=st,
-                ov=ov,
-                x_log=x_log,
-                y_log=y_log,
-                x_scale=x_scale,
-                y_scale=y_scale,
-                title=title,
-                x_label=x_label,
-                y_label=y_label,
-                series_styles=series_styles,
-                x_fmt=x_fmt,
-                y_fmt=y_fmt,
-                x_step=x_step,
-                y_step=y_step,
-            )
+            if has_y2:
+                # Lazy import: mirrors figure_break's own lazy import above —
+                # keeps this module's own top-level import list light, and
+                # the twinx orchestration out of the 500-line ceiling here.
+                from quantized.calc.figure_y2 import render_with_secondary_axis
+
+                artists = render_with_secondary_axis(
+                    fig, ax, xv, series, series_styles, y2_mask_list,
+                    st=st, ov=ov, x_log=x_log, y_log=y_log,
+                    x_scale=x_scale, y_scale=y_scale,
+                    title=title, x_label=x_label, y_label=y_label,
+                    x_fmt=x_fmt, y_fmt=y_fmt, x_step=x_step, y_step=y_step,
+                    y2_label=y2_label, y2_scale=y2_scale,
+                    y2_fmt=y2_fmt, y2_step=y2_step,
+                )
+            else:
+                artists = draw_series_axes(
+                    fig,
+                    ax,
+                    xv,
+                    series,
+                    st=st,
+                    ov=ov,
+                    x_log=x_log,
+                    y_log=y_log,
+                    x_scale=x_scale,
+                    y_scale=y_scale,
+                    title=title,
+                    x_label=x_label,
+                    y_label=y_label,
+                    series_styles=series_styles,
+                    x_fmt=x_fmt,
+                    y_fmt=y_fmt,
+                    x_step=x_step,
+                    y_step=y_step,
+                )
             if not ov.get("margins"):
                 fig.tight_layout()
             if collect_map:

{quantized_lab-0.10.0 → quantized_lab-0.11.0}/src/quantized/calc/figure_categorical.py

@@ -28,6 +28,44 @@ __all__ = ["render_categorical_figure"]
 _FORMATS = ("pdf", "svg", "png", "tiff")
 
 
+def _draw_categorical_bars(
+    ax: Any,
+    groups: list[str],
+    series: list[str],
+    vals: Any,
+    errs: Any | None,
+    stacked: bool,
+) -> None:
+    """Draw one grouped/stacked bar panel into `ax` — shared by the flat
+    single-panel path below and `figure_facets.render_categorical_facets_figure`
+    (GUI_INTERACTION #12 slice 4b), so a faceted panel matches the flat
+    export exactly. Caller applies title/axis-labels/spines/legend/grid —
+    this function only draws the bars + category ticks + zero baseline."""
+    n_groups, n_series = len(groups), len(series)
+    x = np.arange(n_groups, dtype=float)
+    if stacked:
+        bottom = np.zeros(n_groups)
+        for si in range(n_series):
+            yerr = errs[:, si] if errs is not None and si == n_series - 1 else None
+            ax.bar(
+                x, vals[:, si], 0.68, bottom=bottom, yerr=yerr, capsize=3,
+                label=series[si],
+            )
+            bottom = bottom + np.nan_to_num(vals[:, si])
+    else:
+        width = 0.8 / n_series
+        for si in range(n_series):
+            offset = (si - (n_series - 1) / 2) * width
+            yerr = errs[:, si] if errs is not None else None
+            ax.bar(
+                x + offset, vals[:, si], width * 0.85, yerr=yerr, capsize=3,
+                label=series[si],
+            )
+    ax.set_xticks(x)
+    ax.set_xticklabels(groups)
+    ax.axhline(0, color="0.3", linewidth=0.8)  # baseline, visible for mixed-sign data
+
+
 def _to_matrix(
     values: list[list[float]], n_groups: int, n_series: int, name: str
 ) -> np.ndarray:
@@ -111,28 +149,7 @@ def render_categorical_figure(
     with matplotlib.rc_context(rc):  # type: ignore[arg-type]
         fig, ax = plt.subplots(figsize=figsize)
         try:
-            x = np.arange(n_groups, dtype=float)
-            if stacked:
-                bottom = np.zeros(n_groups)
-                for si in range(n_series):
-                    yerr = errs[:, si] if errs is not None and si == n_series - 1 else None
-                    ax.bar(
-                        x, vals[:, si], 0.68, bottom=bottom, yerr=yerr, capsize=3,
-                        label=series[si],
-                    )
-                    bottom = bottom + np.nan_to_num(vals[:, si])
-            else:
-                width = 0.8 / n_series
-                for si in range(n_series):
-                    offset = (si - (n_series - 1) / 2) * width
-                    yerr = errs[:, si] if errs is not None else None
-                    ax.bar(
-                        x + offset, vals[:, si], width * 0.85, yerr=yerr, capsize=3,
-                        label=series[si],
-                    )
-            ax.set_xticks(x)
-            ax.set_xticklabels(groups)
-            ax.axhline(0, color="0.3", linewidth=0.8)  # baseline, visible for mixed-sign data
+            _draw_categorical_bars(ax, groups, series, vals, errs, stacked)
             if title:
                 ax.set_title(title)
             if x_label:

quantized_lab-0.11.0/src/quantized/calc/figure_facets.py

@@ -0,0 +1,359 @@
+"""Publication rendering for faceted (small-multiples) plots.
+
+ORIGIN_GAP_PLAN #21 (export half, faceting) + GUI_INTERACTION #12 slice 4b
+(stat-stage faceted export). Pure layer: N independently pre-split panels
+sharing scales/labels -> image bytes out. ``render_facets_figure`` mirrors
+the interactive xy facet splitter (frontend ``lib/facet.facetPayloads``):
+each panel is already the (label, x, series) data for one categorical level.
+``render_stat_facets_figure``/``render_categorical_facets_figure`` mirror
+the interactive StatStage's OWN facet grid (``useStatStage``'s
+``drawFacets``) for box/violin and bar mode respectively — reusing
+``figure_statplots``/``figure_categorical``'s per-panel draw functions so a
+single facet renders byte-identically to that module's flat single-panel
+export. All three share this module's grid-layout helpers
+(``_grid_shape``/``_new_grid_figure``): the SAME ``ceil(sqrt(n))``-column,
+auto-wrapping-row layout the screen's CSS grid uses
+(``Math.ceil(Math.sqrt(n)))`` columns — see ``StatStage.tsx``/
+``GraphPreview.tsx``), so an exported faceted figure tiles identically to
+what's on screen.
+"""
+
+from __future__ import annotations
+
+from io import BytesIO
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless
+
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+
+from quantized.calc.figure import _plot_kwargs  # noqa: E402
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_styles import figure_style  # noqa: E402
+
+__all__ = [
+    "render_facets_figure",
+    "render_stat_facets_figure",
+    "render_categorical_facets_figure",
+]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+
+
+def _grid_shape(n: int) -> tuple[int, int]:
+    """(rows, cols) for `n` panels — the SAME `ceil(sqrt(n))`-column layout
+    `render_facets_figure` below already uses, and the screen's own CSS grid
+    formula (`Math.ceil(Math.sqrt(n))` columns, auto-wrapping rows —
+    `StatStage.tsx`/`GraphPreview.tsx`), so every faceted export tiles
+    identically to what's on screen."""
+    cols = int(np.ceil(np.sqrt(n)))
+    rows = int(np.ceil(n / cols))
+    return rows, cols
+
+
+def _new_grid_figure(n: int, figsize: tuple[float, float]) -> tuple[Any, list[Any]]:
+    """A fresh `_grid_shape(n)` subplot grid; returns the figure and its axes
+    flattened + trimmed to exactly `n` (unused trailing cells past `n` are
+    hidden, matching `render_facets_figure`'s own convention below)."""
+    rows, cols = _grid_shape(n)
+    fig, axes_grid = plt.subplots(rows, cols, figsize=figsize, squeeze=False)
+    flat = [ax for row in axes_grid for ax in row]
+    for j in range(n, len(flat)):
+        flat[j].set_visible(False)
+    return fig, flat[:n]
+
+
+def render_facets_figure(
+    panels: list[dict[str, Any]],
+    *,
+    x_log: bool = False,
+    y_log: bool = False,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    fmt: str = "pdf",
+    style: str = "default",
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int = 200,
+) -> bytes:
+    """Render one small-multiples panel per facet level.
+
+    Each ``panels[i]`` is ``{"label": str, "x": [...], "series": [{"label":
+    str, "y": [...]}]}`` — a pre-split slice of data for one categorical
+    level (see the frontend's ``lib/facet.facetPayloads``). Panels tile into
+    as-square-as-possible rows/columns and share x/y scales (``sharex`` /
+    ``sharey``) so magnitudes stay comparable across levels; each panel
+    carries its own facet-level title, and unused trailing grid cells (when
+    the panel count isn't a perfect rows*cols rectangle) are hidden.
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if not panels:
+        raise ValueError("panels must be non-empty")
+    # Rich-text labels (GOTO #5): de-math INVALID $...$ so savefig never raises.
+    title = safe_mathtext_label(title)
+    x_label = safe_mathtext_label(x_label)
+    y_label = safe_mathtext_label(y_label)
+
+    st = figure_style(style)
+    n = len(panels)
+    cols = int(np.ceil(np.sqrt(n)))
+    rows = int(np.ceil(n / cols))
+    figsize = (
+        width_in or st.fig_width_in * cols * 0.8,
+        height_in or st.fig_height_in * rows * 0.8,
+    )
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [st.font_name, fallback],
+        "font.size": st.font_size,
+        "axes.labelsize": st.font_size,
+        "axes.titlesize": st.font_size,
+    }
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, axes_grid = plt.subplots(
+            rows, cols, figsize=figsize, sharex=True, sharey=True, squeeze=False,
+        )
+        try:
+            flat = [ax for row in axes_grid for ax in row]
+            for i, panel in enumerate(panels):
+                ax = flat[i]
+                x = np.asarray(panel.get("x", []), dtype=float)
+                series = panel.get("series", [])
+                for si, s in enumerate(series):
+                    kw = _plot_kwargs(st.line_width, st.marker_size, None)
+                    ax.plot(
+                        x, np.asarray(s.get("y", []), dtype=float),
+                        label=safe_mathtext_label(str(s.get("label", f"s{si}"))), **kw,
+                    )
+                ax.set_title(
+                    safe_mathtext_label(str(panel.get("label", ""))), fontsize=st.font_size
+                )
+                if x_log:
+                    ax.set_xscale("log")
+                if y_log:
+                    ax.set_yscale("log")
+                if not st.box_on:
+                    ax.spines["top"].set_visible(False)
+                    ax.spines["right"].set_visible(False)
+                if st.grid_alpha > 0:
+                    ax.grid(True, alpha=st.grid_alpha)
+                if len(series) > 1:
+                    ax.legend(fontsize=max(6.0, st.legend_font_size - 2), frameon=st.legend_box)
+            for j in range(n, len(flat)):
+                flat[j].set_visible(False)
+
+            if title:
+                fig.suptitle(title)
+            if x_label:
+                fig.supxlabel(x_label)
+            if y_label:
+                fig.supylabel(y_label)
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)
+
+
+def render_stat_facets_figure(
+    panels: list[dict[str, Any]],
+    *,
+    default_kind: str,
+    dist: str = "norm",
+    bins: str | int = "fd",
+    fit: str | None = None,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    fmt: str = "pdf",
+    style: str = "default",
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int | None = None,
+) -> bytes:
+    """Faceted box/violin export (GUI_INTERACTION #12 slice 4b, StatStage's
+    "facet by" grid). Each ``panels[i]`` is ``{"label": str, "kind": "box" |
+    "violin" (optional), "data": [[...], ...], "labels": [...] | None}``.
+
+    ``kind`` is per-facet MODE FIDELITY: the interactive StatStage computes
+    each facet slice independently (``useStatStage.computeFacetGroupDraws``)
+    and a violin slice whose own ``/api/statplots/violin`` call failed
+    degrades to a box plot for JUST that slice (never fabricating a KDE) —
+    omitting ``kind`` falls back to ``default_kind`` (today's degrade-free
+    case, every panel the same requested kind), while an explicit per-panel
+    ``kind`` reproduces a mixed grid exactly as the screen showed it.
+
+    Reuses ``figure_statplots._draw_statplot`` for each panel so a single
+    facet renders byte-identically to that module's flat single-panel path.
+    """
+    from quantized.calc.figure_statplots import _GROUPED, _draw_statplot
+
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if not panels:
+        raise ValueError("panels must be non-empty")
+    title = safe_mathtext_label(title)
+    x_label = safe_mathtext_label(x_label)
+    y_label = safe_mathtext_label(y_label)
+
+    st = figure_style(style)
+    resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+    n = len(panels)
+    rows, cols = _grid_shape(n)
+    figsize = (
+        width_in or st.fig_width_in * cols * 0.8,
+        height_in or st.fig_height_in * rows * 0.8,
+    )
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [st.font_name, fallback],
+        "font.size": st.font_size,
+        "axes.labelsize": st.font_size,
+        "axes.titlesize": st.font_size,
+        "xtick.top": st.box_on,
+        "ytick.right": st.box_on,
+    }
+
+    prepared: list[tuple[str, str, Any, list[str] | None]] = []
+    for p in panels:
+        label = safe_mathtext_label(str(p.get("label", "")))
+        kind = p.get("kind") or default_kind
+        if kind not in _GROUPED:
+            raise ValueError(f"facet kind must be one of {_GROUPED}")
+        data = p.get("data")
+        if not isinstance(data, list) or not data:
+            raise ValueError(f"facet {label!r} needs a non-empty list of groups")
+        flabels = p.get("labels")
+        flabels = [safe_mathtext_label(str(g)) for g in flabels] if flabels else flabels
+        prepared.append((label, kind, data, flabels))
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, axes = _new_grid_figure(n, figsize)
+        try:
+            for ax, (label, kind, data, flabels) in zip(axes, prepared, strict=True):
+                _draw_statplot(ax, kind, data, flabels, dist, bins, fit, st)
+                ax.set_title(label, fontsize=st.font_size)
+                if not st.box_on:
+                    ax.spines["top"].set_visible(False)
+                    ax.spines["right"].set_visible(False)
+            if title:
+                fig.suptitle(title)
+            if x_label:
+                fig.supxlabel(x_label)
+            if y_label:
+                fig.supylabel(y_label)
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=resolved_dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)
+
+
+def render_categorical_facets_figure(
+    panels: list[dict[str, Any]],
+    *,
+    stacked: bool = False,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    fmt: str = "pdf",
+    style: str = "default",
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int = 200,
+) -> bytes:
+    """Faceted grouped/stacked bar export (GUI_INTERACTION #12 slice 4b,
+    StatStage's bar-mode "facet by" grid). Each ``panels[i]`` is
+    ``{"label": str, "groups": [...], "series": [...], "values": [[...]],
+    "errors": [[...]] | None}`` — a SELF-CONTAINED category x series matrix
+    (a facet's category set can differ slice to slice when a grouped-by
+    column level is absent from that slice, so panels never share one
+    ``groups`` list). Reuses ``figure_categorical._draw_categorical_bars``
+    so a single panel matches that module's flat single-panel export.
+
+    ``series`` is assumed consistent across panels (the same plotted
+    channels every slice draws), so ONE legend on the first panel documents
+    the whole figure rather than repeating it in every small cell.
+    """
+    from quantized.calc.figure_categorical import (
+        _draw_categorical_bars,
+        _to_error_matrix,
+        _to_matrix,
+    )
+
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if not panels:
+        raise ValueError("panels must be non-empty")
+    title = safe_mathtext_label(title)
+    x_label = safe_mathtext_label(x_label)
+    y_label = safe_mathtext_label(y_label)
+
+    st = figure_style(style)
+    n = len(panels)
+    rows, cols = _grid_shape(n)
+    figsize = (
+        width_in or st.fig_width_in * cols * 0.8,
+        height_in or st.fig_height_in * rows * 0.8,
+    )
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [st.font_name, fallback],
+        "font.size": st.font_size,
+        "axes.labelsize": st.font_size,
+        "axes.titlesize": st.font_size,
+    }
+
+    prepared = []
+    for p in panels:
+        label = safe_mathtext_label(str(p.get("label", "")))
+        groups = [safe_mathtext_label(str(g)) for g in p.get("groups", [])]
+        series = [safe_mathtext_label(str(s)) for s in p.get("series", [])]
+        if not groups:
+            raise ValueError(f"facet {label!r} needs a non-empty groups list")
+        if not series:
+            raise ValueError(f"facet {label!r} needs a non-empty series list")
+        vals = _to_matrix(p.get("values", []), len(groups), len(series), f"facet {label!r} values")
+        errs = _to_error_matrix(p.get("errors"), len(groups), len(series))
+        prepared.append((label, groups, series, vals, errs))
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, axes = _new_grid_figure(n, figsize)
+        try:
+            for ax, (label, groups, series, vals, errs) in zip(axes, prepared, strict=True):
+                _draw_categorical_bars(ax, groups, series, vals, errs, stacked)
+                ax.set_title(label, fontsize=st.font_size)
+                if not st.box_on:
+                    ax.spines["top"].set_visible(False)
+                    ax.spines["right"].set_visible(False)
+                if st.grid_alpha > 0:
+                    ax.grid(True, alpha=st.grid_alpha, axis="y")
+            first_series = prepared[0][2]
+            if len(first_series) > 1:
+                axes[0].legend(
+                    frameon=st.legend_box, fontsize=max(6.0, st.legend_font_size - 2),
+                    loc=st.legend_location,
+                )
+            if title:
+                fig.suptitle(title)
+            if x_label:
+                fig.supxlabel(x_label)
+            if y_label:
+                fig.supylabel(y_label)
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)