maidr 1.8.0__py3-none-any.whl → 1.9.0__py3-none-any.whl

maidr/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.8.0"
+__version__ = "1.9.0"
 
 from .api import close, render, save_html, show, stacked
 from .core import Maidr

maidr/api.py

@@ -14,12 +14,12 @@ from maidr.core.figure_manager import FigureManager
 def _get_plot_or_current(plot: Any | None) -> Any:
     """
     Get the plot object or current matplotlib figure if plot is None.
-    
+
     Parameters
     ----------
     plot : Any or None
         The plot object. If None, returns the current matplotlib figure.
-        
+
     Returns
     -------
     Any
@@ -28,7 +28,7 @@ def _get_plot_or_current(plot: Any | None) -> Any:
     if plot is None:
         # Lazy import matplotlib.pyplot when needed
         import matplotlib.pyplot as plt
-        
+
         return plt.gcf()
     return plot
 
@@ -48,7 +48,7 @@ def render(plot: Any | None = None) -> Tag:
         The rendered HTML representation of the plot.
     """
     plot = _get_plot_or_current(plot)
-    
+
     ax = FigureManager.get_axes(plot)
     if isinstance(ax, list):
         for axes in ax:
@@ -82,7 +82,7 @@ def show(
         The display result.
     """
     plot = _get_plot_or_current(plot)
-    
+
     ax = FigureManager.get_axes(plot)
     if isinstance(ax, list):
         for axes in ax:
@@ -95,10 +95,11 @@ def show(
 
 def save_html(
     plot: Any | None = None,
-    *, 
+    *,
     file: str,
-    lib_dir: str | None = "lib", 
-    include_version: bool = True
+    lib_dir: str | None = "lib",
+    include_version: bool = True,
+    data_in_svg: bool = True,
 ) -> str:
     """
     Save a MAIDR plot as HTML file.
@@ -113,6 +114,8 @@ def save_html(
         Directory name for libraries.
     include_version : bool, default True
         Whether to include version information.
+    data_in_svg : bool, default True
+        Controls where the MAIDR JSON payload is placed in the HTML or SVG.
 
     Returns
     -------
@@ -120,19 +123,21 @@ def save_html(
         The path to the saved HTML file.
     """
     plot = _get_plot_or_current(plot)
-    
+
     ax = FigureManager.get_axes(plot)
     htmls = []
     if isinstance(ax, list):
         for axes in ax:
             maidr = FigureManager.get_maidr(axes.get_figure())
-            htmls.append(maidr._create_html_doc(use_iframe=False))
+            htmls.append(maidr._create_html_doc(use_iframe=False, data_in_svg=data_in_svg))
         return htmls[-1].save_html(
             file, libdir=lib_dir, include_version=include_version
         )
     else:
         maidr = FigureManager.get_maidr(ax.get_figure())
-        return maidr.save_html(file, lib_dir=lib_dir, include_version=include_version)
+        return maidr.save_html(
+            file, lib_dir=lib_dir, include_version=include_version, data_in_svg=data_in_svg
+        )
 
 
 def stacked(plot: Axes | BarContainer) -> Maidr:
@@ -150,6 +155,6 @@ def close(plot: Any | None = None) -> None:
         The plot object to close. If None, uses the current matplotlib figure.
     """
     plot = _get_plot_or_current(plot)
-    
+
     ax = FigureManager.get_axes(plot)
     FigureManager.destroy(ax.get_figure())

maidr/core/maidr.py

@@ -72,7 +72,12 @@ class Maidr:
         return self._create_html_tag(use_iframe=True)
 
     def save_html(
-        self, file: str, *, lib_dir: str | None = "lib", include_version: bool = True
+        self,
+        file: str,
+        *,
+        lib_dir: str | None = "lib",
+        include_version: bool = True,
+        data_in_svg: bool = True,
     ) -> str:
         """
         Save the HTML representation of the figure with MAIDR to a file.
@@ -86,9 +91,11 @@ class Maidr:
             (relative to the file's directory).
         include_version : bool, default=True
             Whether to include the version number in the dependency folder name.
+        data_in_svg : bool, default=True
+            Controls where the MAIDR JSON payload is placed in the output HTML or SVG.
         """
         html = self._create_html_doc(
-            use_iframe=False
+            use_iframe=False, data_in_svg=data_in_svg
         )  # Always use direct HTML for saving
         return html.save_html(file, libdir=lib_dir, include_version=include_version)
 
@@ -180,8 +187,17 @@ class Maidr:
         else:
             webbrowser.open(f"file://{html_file_path}")
 
-    def _create_html_tag(self, use_iframe: bool = True) -> Tag:
-        """Create the MAIDR HTML using HTML tags."""
+    def _create_html_tag(self, use_iframe: bool = True, data_in_svg: bool = True) -> Tag:
+        """Create the MAIDR HTML using HTML tags.
+
+        Parameters
+        ----------
+        use_iframe : bool, default=True
+            Whether to render the plot inside an iframe (for notebooks and similar envs).
+        data_in_svg : bool, default=True
+            If True, the MAIDR JSON is embedded in the root <svg> under attribute 'maidr'.
+            If False, a <script>var maidr = {...}</script> tag is injected instead.
+        """
         tagged_elements: list[Any] = [
             element for plot in self._plots for element in plot.elements
         ]
@@ -191,16 +207,31 @@ class Maidr:
             for _ in plot.elements:
                 selector_ids.append(self.selector_ids[i])
 
+        # Build schema once so id stays consistent across SVG and global var
+        schema = self._flatten_maidr()
+
         with HighlightContextManager.set_maidr_elements(tagged_elements, selector_ids):
-            svg = self._get_svg()
-        maidr = f"\nlet maidr = {json.dumps(self._flatten_maidr(), indent=2)}\n"
+            svg = self._get_svg(embed_data=data_in_svg, schema=schema)
+
+        # Generate external payload if data is not embedded in SVG
+        maidr = None
+        if not data_in_svg:
+            maidr = f"\nvar maidr = {json.dumps(schema, indent=2)}\n"
 
         # Inject plot's svg and MAIDR structure into html tag.
         return Maidr._inject_plot(svg, maidr, self.maidr_id, use_iframe)
 
-    def _create_html_doc(self, use_iframe: bool = True) -> HTMLDocument:
-        """Create an HTML document from Tag objects."""
-        return HTMLDocument(self._create_html_tag(use_iframe), lang="en")
+    def _create_html_doc(self, use_iframe: bool = True, data_in_svg: bool = True) -> HTMLDocument:
+        """Create an HTML document from Tag objects.
+
+        Parameters
+        ----------
+        use_iframe : bool, default=True
+            Whether to render the plot inside an iframe (for notebooks and similar envs).
+        data_in_svg : bool, default=True
+            See _create_html_tag for details on payload placement strategy.
+        """
+        return HTMLDocument(self._create_html_tag(use_iframe, data_in_svg), lang="en")
 
     def _merge_plots_by_subplot_position(self) -> list[MaidrPlot]:
         """
@@ -312,10 +343,23 @@ class Maidr:
                 for cell in subplot_grid[i]
             ]
 
-        return {"id": Maidr._unique_id(), "subplots": subplot_grid}
+        return {
+            "id": Maidr._unique_id(),
+            "subplots": subplot_grid,
+        }
 
-    def _get_svg(self) -> HTML:
-        """Extract the chart SVG from ``matplotlib.figure.Figure``."""
+    def _get_svg(self, embed_data: bool = True, schema: dict | None = None) -> HTML:
+        """Extract the chart SVG from ``matplotlib.figure.Figure``.
+
+        Parameters
+        ----------
+        embed_data : bool, default=True
+            If True, embed the MAIDR JSON schema as an attribute named 'maidr' on
+            the root <svg> element. If False, do not embed JSON in the SVG.
+        schema : dict | None, default=None
+            If provided, this schema will be used (ensuring a consistent id across
+            the page). If None, a new schema will be generated.
+        """
         svg_buffer = io.StringIO()
         self._fig.savefig(svg_buffer, format="svg")
         str_svg = svg_buffer.getvalue()
@@ -323,12 +367,14 @@ class Maidr:
         etree.register_namespace("svg", "http://www.w3.org/2000/svg")
         tree_svg = etree.fromstring(str_svg.encode(), parser=None)
         root_svg = None
-        # Find the `svg` tag and set unique id if not present else use it.
+        # Find the `svg` tag and optionally embed MAIDR data.
         for element in tree_svg.iter(tag="{http://www.w3.org/2000/svg}svg"):
-            if "maidr-data" not in element.attrib:
-                element.attrib["maidr-data"] = json.dumps(
-                    self._flatten_maidr(), indent=2
-                )
+            current_schema = schema if schema is not None else self._flatten_maidr()
+            # Ensure SVG id matches schema id in both modes
+            if isinstance(current_schema, dict) and "id" in current_schema:
+                element.attrib["id"] = str(current_schema["id"])  # ensure match
+            if embed_data:
+                element.attrib["maidr"] = json.dumps(current_schema, indent=2)
             root_svg = element
             break
 
@@ -355,36 +401,41 @@ class Maidr:
         return str(uuid.uuid4())
 
     @staticmethod
-    def _inject_plot(plot: HTML, maidr: str, maidr_id, use_iframe: bool = True) -> Tag:
+    def _inject_plot(plot: HTML, maidr: str | None, maidr_id, use_iframe: bool = True) -> Tag:
         """Embed the plot and associated MAIDR scripts into the HTML structure."""
         # Get the latest version from npm registry
         MAIDR_TS_CDN_URL = "https://cdn.jsdelivr.net/npm/maidr@latest/dist/maidr.js"
 
         script = f"""
-            if (!document.querySelector('script[src="{MAIDR_TS_CDN_URL}"]'))
-            {{
-                var script = document.createElement('script');
-                script.type = 'module';
-                script.src = '{MAIDR_TS_CDN_URL}';
-                script.addEventListener('load', function() {{
-                    window.main();
-                }});
-                document.head.appendChild(script);
-            }} else {{
-                document.addEventListener('DOMContentLoaded', function (e) {{
-                    window.main();
-                }});
-            }}
+            (function() {{
+                var existing = document.querySelector('script[src="{MAIDR_TS_CDN_URL}"]');
+                if (!existing) {{
+                    var s = document.createElement('script');
+                    s.src = '{MAIDR_TS_CDN_URL}';
+                    s.onload = function() {{ if (window.main) window.main(); }};
+                    document.head.appendChild(s);
+                }} else {{
+                    if (document.readyState === 'loading') {{
+                        document.addEventListener('DOMContentLoaded', function() {{ if (window.main) window.main(); }});
+                    }} else {{
+                        if (window.main) window.main();
+                    }}
+                }}
+            }})();
         """
 
-        base_html = tags.div(
+        children = [
             tags.link(
                 rel="stylesheet",
                 href="https://cdn.jsdelivr.net/npm/maidr@latest/dist/maidr_style.css",
-            ),
-            tags.script(script, type="text/javascript"),
-            tags.div(plot),
-        )
+            )
+        ]
+        if maidr is not None:
+            children.append(tags.script(maidr, type="text/javascript"))
+        children.append(tags.script(script, type="text/javascript"))
+        children.append(tags.div(plot))
+
+        base_html = tags.div(*children)
 
         # is_quarto = os.getenv("IS_QUARTO") == "True"
 

maidr/core/plot/grouped_barplot.py

@@ -52,18 +52,73 @@ class GroupedBarPlot(
             [patch for container in plot for patch in container.patches]
         )
 
-        for container in plot:
+        # Get hue categories from legend
+        hue_categories = self._extract_hue_categories_from_legend()
+
+        for i, container in enumerate(plot):
             if len(x_level) != len(container.patches):
                 return None
             container_data = []
+
+            # Use hue category if available, otherwise fall back to container label
+            fill_value = hue_categories[i] if i < len(hue_categories) else container.get_label()
+
             for x, y in zip(x_level, container.patches):
                 container_data.append(
                     {
                         MaidrKey.X.value: x,
-                        MaidrKey.FILL.value: container.get_label(),
+                        MaidrKey.FILL.value: fill_value,
                         MaidrKey.Y.value: float(y.get_height()),
                     }
                 )
             data.append(container_data)
 
         return data
+
+    def _extract_hue_categories_from_legend(self) -> list[str]:
+        """
+        Extract hue categories from the axes legend.
+
+        This method reads the legend text elements from the axes legend,
+        trims whitespace from each text, and returns a list of cleaned
+        category names. This is used to get the actual category names
+        instead of using the generic container labels like '_container0', '_container1'.
+
+        Parameters
+        ----------
+        None
+            This method uses the instance's axes object.
+
+        Returns
+        -------
+        list[str]
+            List of trimmed hue category names from the legend.
+            Returns empty list if no legend is found or if legend has no text elements.
+
+        Examples
+        --------
+        >>> # For a seaborn barplot with hue='category' and legend showing 'Below', 'Above'
+        >>> plot = GroupedBarPlot(ax, PlotType.DODGED)
+        >>> categories = plot._extract_hue_categories_from_legend()
+        >>> print(categories)
+        ['Below', 'Above']
+
+        >>> # If no legend exists
+        >>> categories = plot._extract_hue_categories_from_legend()
+        >>> print(categories)
+        []
+        """
+        legend = self.ax.get_legend()
+        if legend is None:
+            return []
+
+        # Get legend text elements
+        legend_texts = legend.get_texts()
+        if not legend_texts:
+            return []
+
+        # Extract text content from legend elements and trim whitespace
+        hue_categories = [text.get_text().strip() for text in legend_texts]
+
+        # Filter out empty strings and return
+        return [category for category in hue_categories if category]

{maidr-1.8.0.dist-info → maidr-1.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maidr
-Version: 1.8.0
+Version: 1.9.0
 Summary: Multimodal Access and Interactive Data Representations
 Project-URL: Homepage, https://xability.github.io/py-maidr
 Project-URL: Repository, https://github.com/xability/py-maidr

{maidr-1.8.0.dist-info → maidr-1.9.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
-maidr/__init__.py,sha256=WHwg8BcJQIcf4dsUFOdKS_frxDfuHewDEGnBBg9j3WE,415
-maidr/api.py,sha256=od539V0CKcs15FEXQo0hX_hK_A0U3noHE54obdHcTqY,4138
+maidr/__init__.py,sha256=szUjuM4cnGyzipfrIxpyZV841yhHjMmIcP7yXHq7kq8,415
+maidr/api.py,sha256=WK7jfQttuPeF1q45RuF_wTciYyiFY6SyjfZVSOVkiUs,4316
 maidr/core/__init__.py,sha256=WgxLpSEYMc4k3OyEOf1shOxfEq0ASzppEIZYmE91ThQ,25
 maidr/core/context_manager.py,sha256=6cT7ZGOApSpC-SLD2XZWWU_H08i-nfv-JUlzXOtvWYw,3374
 maidr/core/figure_manager.py,sha256=t-lhe4jj2gsF5-8VUBUZOPlDutKjm_AZ8xXWJU2pFRc,5555
-maidr/core/maidr.py,sha256=0MuyPgc1CFomA87jq70GG-MSxYaMI2Z7ct2FAOGCxQM,20067
+maidr/core/maidr.py,sha256=Ye2C8tQPY1o8gfURiTyDPMWFoRT0toZOOCugKAz4uQU,22370
 maidr/core/enum/__init__.py,sha256=9ee78L0dlxEx4ulUGVlD-J23UcUZmrGu0rXms54up3c,93
 maidr/core/enum/library.py,sha256=e8ujT_L-McJWfoVJd1ty9K_2bwITnf1j0GPLsnAcHes,104
 maidr/core/enum/maidr_key.py,sha256=ljG0omqzd8K8Yk213N7i7PXGvG-IOlnE5v7o6RoGJzc,795
@@ -13,7 +13,7 @@ maidr/core/plot/__init__.py,sha256=xDIpRGM-4DfaSSL3nKcXrjdMecCHJ6en4K4nA_fPefQ,8
 maidr/core/plot/barplot.py,sha256=0hBgp__putezvxXc9G3qmaktmAzze3cN8pQMD9iqktE,2116
 maidr/core/plot/boxplot.py,sha256=i11GdNuz_c-hilmhydu3ah-bzyVdFoBkNvRi5lpMrrY,9946
 maidr/core/plot/candlestick.py,sha256=ofvlUwtzaaopvv6VjNDf1IZODbu1UkMHsi1zdvcG-Yo,10120
-maidr/core/plot/grouped_barplot.py,sha256=_zn4XMeEnSiDHtf6t4-z9ErBqg_CijhAS2CCtlHgYIQ,2077
+maidr/core/plot/grouped_barplot.py,sha256=odZ52Pl22nb9cWKD3NGsZsyFDxXdBDAEcbOj66HKp9I,4063
 maidr/core/plot/heatmap.py,sha256=yMS-31tS2GW4peds9LtZesMxmmTV_YfqYO5M_t5KasQ,2521
 maidr/core/plot/histogram.py,sha256=QV5W-6ZJQQcZsrM91JJBX-ONktJzH7yg_et5_bBPfQQ,1525
 maidr/core/plot/lineplot.py,sha256=uoJpGkJB3IJSDJTwH6ECxLyXGdarsVQNULELp5NncWg,4522
@@ -52,7 +52,7 @@ maidr/util/mixin/extractor_mixin.py,sha256=j2Rv2vh_gqqcxLV1ka3xsPaPAfWsX94CtKIW2
 maidr/util/mixin/merger_mixin.py,sha256=V0qLw_6DUB7X6CQ3BCMpsCQX_ZuwAhoSTm_E4xAJFKM,712
 maidr/widget/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 maidr/widget/shiny.py,sha256=wrrw2KAIpE_A6CNQGBtNHauR1DjenA_n47qlFXX9_rk,745
-maidr-1.8.0.dist-info/METADATA,sha256=JSCtmOqsD8Mka8aDihHcqHs4wJ9Yc4eBYV3by-pQSl0,3154
-maidr-1.8.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-maidr-1.8.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-maidr-1.8.0.dist-info/RECORD,,
+maidr-1.9.0.dist-info/METADATA,sha256=EK0mJx_hRNjiVvAnGcph7sBceEbiQrgvioGFPcw8-EY,3154
+maidr-1.9.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+maidr-1.9.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+maidr-1.9.0.dist-info/RECORD,,