coco_pipe.report.elements
=========================

.. py:module:: coco_pipe.report.elements

.. autoapi-nested-parse::

   Reporting Elements
   ==================

   Generic, reusable report primitives. Each ``Element`` knows how to render
   itself to HTML and (optionally) contribute to the global data payload used
   for interactive widgets.

   Higher-level constructs (:class:`coco_pipe.report.core.Section`,
   :class:`coco_pipe.report.core.Report`) live in :mod:`coco_pipe.report.core`.



Classes
-------

.. autoapisummary::

   coco_pipe.report.elements.Element
   coco_pipe.report.elements.HtmlElement
   coco_pipe.report.elements.ImageElement
   coco_pipe.report.elements.PlotlyElement
   coco_pipe.report.elements.TableElement
   coco_pipe.report.elements.InteractiveTableElement
   coco_pipe.report.elements.MetricsTableElement
   coco_pipe.report.elements.StatCardElement
   coco_pipe.report.elements.CalloutElement
   coco_pipe.report.elements.CodeBlockElement
   coco_pipe.report.elements.ContainerElement
   coco_pipe.report.elements.ColumnsElement
   coco_pipe.report.elements.AccordionElement
   coco_pipe.report.elements.MarkdownElement
   coco_pipe.report.elements.BadgeElement
   coco_pipe.report.elements.ProgressBarElement
   coco_pipe.report.elements.TimelineElement
   coco_pipe.report.elements.TabsElement
   coco_pipe.report.elements.DownloadAssetElement


Module Contents
---------------

.. py:class:: Element

   Bases: :py:obj:`abc.ABC`


   Abstract base class for all report elements.


   .. py:method:: render()
      :abstractmethod:


      Render the element to HTML.



   .. py:method:: collect_payload(registry)

      Collect data to be stored in the global payload.
      Default implementation does nothing.

      :param registry: Global dictionary accumulating data. Keyed by UUID.
      :type registry: Dict[str, Any]



.. py:class:: HtmlElement(html)

   Bases: :py:obj:`Element`


   Wrapper for raw HTML content.

   :param html: The raw HTML string to include.
   :type html: str

   .. rubric:: Examples

   >>> elem = HtmlElement("<div>My Custom HTML</div>")
   >>> rep.add_element(elem)


   .. py:attribute:: html


   .. py:method:: render()

      Render the element to HTML.



.. py:class:: ImageElement(src, caption = None, width = '100%')

   Bases: :py:obj:`Element`


   Embeds an image or matplotlib figure as Base64.

   :param src: The image source.
   :type src: str, bytes, Path, or matplotlib.figure.Figure
   :param caption: Caption text for the figure.
   :type caption: str, optional
   :param width: CSS width (e.g., '100%', '600px'). Default '100%'.
   :type width: str, optional

   .. rubric:: Examples

   >>> fig, ax = plt.subplots()
   >>> ax.plot([1, 2, 3])
   >>> elem = ImageElement(fig, caption="My Plot")


   .. py:attribute:: src


   .. py:attribute:: caption
      :value: None



   .. py:attribute:: width
      :value: '100%'



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: PlotlyElement(figure, height = '500px')

   Bases: :py:obj:`Element`


   Embeds a Plotly figure using lazy loading and global data usage.

   :param figure: The figure to render.
   :type figure: plotly.graph_objects.Figure
   :param height: Height of the plot plot container. Default "500px".
   :type height: str, optional

   .. rubric:: Examples

   >>> fig = go.Figure(data=go.Scatter(x=[1, 2], y=[3, 4]))
   >>> elem = PlotlyElement(fig)


   .. py:attribute:: figure


   .. py:attribute:: height
      :value: '500px'



   .. py:attribute:: registry_id
      :value: None



   .. py:method:: collect_payload(registry)

      Extract figure data and store in registry.



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: TableElement(data, title = None)

   Bases: :py:obj:`Element`


   Renders a Pandas DataFrame or Dict as a styled HTML table.

   :param data: Data to display.
   :type data: DataFrame, Dict, or List[Dict]
   :param title: Title describing the table.
   :type title: str, optional

   .. rubric:: Examples

   >>> df = pd.DataFrame({"A": [1, 2], "B": [3, 4]})
   >>> elem = TableElement(df, title="Metrics")


   .. py:attribute:: data


   .. py:attribute:: title
      :value: None



   .. py:attribute:: table_id
      :value: 'table-00000000'



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: InteractiveTableElement(data, title = None, selector_columns = None, default_sort = None, page_size = 50)

   Bases: :py:obj:`Element`


   Render a payload-backed interactive data table.


   .. py:attribute:: data


   .. py:attribute:: title
      :value: None



   .. py:attribute:: selector_columns
      :value: []



   .. py:attribute:: default_sort


   .. py:attribute:: page_size
      :value: 50



   .. py:attribute:: registry_id
      :type:  str | None
      :value: None



   .. py:method:: collect_payload(registry)

      Collect data to be stored in the global payload.
      Default implementation does nothing.

      :param registry: Global dictionary accumulating data. Keyed by UUID.
      :type registry: Dict[str, Any]



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: MetricsTableElement(data, title = 'Comparison Metrics', highlight_cols = None, higher_is_better = True)

   Bases: :py:obj:`TableElement`


   Comparison table that highlights best values.

   :param data: Comparison data (rows=methods, cols=metrics).
   :type data: DataFrame
   :param highlight_cols: Columns to highlight best values in.
   :type highlight_cols: List[str], optional
   :param higher_is_better: True if higher is better for all, or list of cols where higher is better.
                            Default True.
   :type higher_is_better: Union[bool, List[str]], optional


   .. py:attribute:: highlight_cols
      :value: None



   .. py:attribute:: higher_is_better
      :value: True



   .. py:attribute:: best_vals


.. py:class:: StatCardElement(label, value, unit = '', delta = None, color = 'blue')

   Bases: :py:obj:`Element`


   A KPI-style card displaying a single headline metric.

   :param label: Short metric label (e.g. ``"Mean Accuracy"``).
   :type label: str
   :param value: The metric value to display prominently.
   :type value: str or float
   :param unit: Optional unit suffix appended to the value (e.g. ``"%"``).
   :type unit: str, optional
   :param delta: Optional change indicator rendered below the value (e.g. ``"+2.3%"``).
   :type delta: str, optional
   :param color: Accent color for the top stripe: ``"blue"`` (default), ``"green"``,
                 ``"yellow"``, ``"red"``, or ``"purple"``.
   :type color: str, optional

   .. rubric:: Examples

   >>> card = StatCardElement("Mean Accuracy", 0.842, unit="%", color="green")
   >>> report.add_summary_card({"Mean Accuracy": 0.842, "Models": 3})


   .. py:attribute:: label


   .. py:attribute:: value


   .. py:attribute:: unit
      :value: ''



   .. py:attribute:: delta
      :value: None



   .. py:attribute:: color
      :value: 'blue'



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: CalloutElement(text, kind = 'info', title = None)

   Bases: :py:obj:`Element`


   A tinted callout box for notes, tips, warnings, or errors.

   :param text: The callout body text (plain text or minimal HTML).
   :type text: str
   :param kind: Visual style: ``"info"`` (default), ``"tip"``, ``"warning"``, or ``"error"``.
   :type kind: str, optional
   :param title: Optional bold heading rendered above the body text.
   :type title: str, optional

   .. rubric:: Examples

   >>> note = CalloutElement(
   ...     "Probability calibration was unavailable.", kind="warning"
   ... )
   >>> sec.add_element(note)


   .. py:attribute:: text


   .. py:attribute:: kind
      :value: 'info'



   .. py:attribute:: title
      :value: None



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: CodeBlockElement(code, language = '', title = None, copyable = True)

   Bases: :py:obj:`Element`


   A syntax-highlighted, optionally copyable code block.

   :param code: The code or text to display verbatim.
   :type code: str
   :param language: Language hint shown as a badge (e.g. ``"python"``, ``"json"``). Cosmetic only.
   :type language: str, optional
   :param title: Optional caption rendered in the block header.
   :type title: str, optional
   :param copyable: If True (default), renders a one-click Copy button.
   :type copyable: bool, optional

   .. rubric:: Examples

   >>> block = CodeBlockElement(
   ...     json.dumps(config, indent=2), language="json", title="Run Configuration"
   ... )
   >>> sec.add_element(block)


   .. py:attribute:: language
      :value: ''



   .. py:attribute:: title
      :value: None



   .. py:attribute:: copyable
      :value: True



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: ContainerElement

   Bases: :py:obj:`Element`


   Base class for elements that contain other elements.


   .. py:attribute:: children
      :type:  list[Element]
      :value: []



   .. py:method:: add_element(element)

      Add a child element.

      :param element: The element to add. specific strings are converted to HtmlElement.
      :type element: Element or str

      :returns: Fluent interface.
      :rtype: self



   .. py:method:: add_markdown(text)

      Add a markdown block.



   .. py:method:: render_children()

      Render all child elements concatenated.



   .. py:method:: collect_payload(registry)

      Recursively collect payload from children.



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: ColumnsElement(elements, cols = None, gap = 'gap-4')

   Bases: :py:obj:`ContainerElement`


   Lay out child elements side by side in a responsive CSS grid row.

   :param elements: Child elements to place in columns. Each element occupies one cell.
   :type elements: list of Element
   :param cols: Number of columns. Inferred from ``len(elements)`` when omitted, capped at 4.
   :type cols: int, optional
   :param gap: Tailwind gap class applied to the grid. Default ``"gap-4"``.
   :type gap: str, optional

   .. rubric:: Examples

   >>> row = ColumnsElement(
   ...     [ImageElement(fig1, caption="ROC"), ImageElement(fig2, caption="PR")]
   ... )
   >>> sec.add_element(row)


   .. py:method:: render()

      Render the element to HTML.



.. py:class:: AccordionElement(summary, open = False)

   Bases: :py:obj:`ContainerElement`


   A collapsible ``<details>`` disclosure block for secondary content.

   :param summary: The always-visible summary label (acts as the toggle trigger).
   :type summary: str
   :param open: If True the block starts expanded. Default False.
   :type open: bool, optional

   .. rubric:: Examples

   >>> acc = AccordionElement("Show raw configuration")
   >>> acc.add_element(CodeBlockElement(json_str, language="json"))
   >>> sec.add_element(acc)


   .. py:method:: render()

      Render the element to HTML.



.. py:class:: MarkdownElement(text)

   Bases: :py:obj:`Element`


   Render markdown text as HTML.


   .. py:attribute:: text


   .. py:method:: render()

      Render the element to HTML.



.. py:class:: BadgeElement(text, color = 'blue')

   Bases: :py:obj:`Element`


   A small inline status badge.


   .. py:attribute:: text


   .. py:attribute:: color
      :value: 'blue'



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: ProgressBarElement(value, max_value = 100.0, label = None, color = 'blue')

   Bases: :py:obj:`Element`


   A visual progress bar or gauge.


   .. py:attribute:: value


   .. py:attribute:: max_value
      :value: 100.0



   .. py:attribute:: label
      :value: None



   .. py:attribute:: color
      :value: 'blue'



   .. py:method:: render()

      Render the element to HTML.



.. py:class:: TimelineElement(events)

   Bases: :py:obj:`Element`


   A vertical timeline of events.


   .. py:attribute:: events


   .. py:method:: render()

      Render the element to HTML.



.. py:class:: TabsElement(tabs)

   Bases: :py:obj:`ContainerElement`


   A tabbed container for multiple elements.


   .. py:attribute:: tabs


   .. py:method:: render()

      Render the element to HTML.



.. py:class:: DownloadAssetElement(data, filename, mime_type = 'application/octet-stream', label = 'Download Asset', style = 'blue')

   Bases: :py:obj:`Element`


   A button that downloads binary/text data stored in the report payload.


   .. py:attribute:: data


   .. py:attribute:: filename


   .. py:attribute:: mime_type
      :value: 'application/octet-stream'



   .. py:attribute:: label
      :value: 'Download Asset'



   .. py:attribute:: style
      :value: 'blue'



   .. py:attribute:: registry_id
      :value: None



   .. py:method:: collect_payload(registry)

      Collect data to be stored in the global payload.
      Default implementation does nothing.

      :param registry: Global dictionary accumulating data. Keyed by UUID.
      :type registry: Dict[str, Any]



   .. py:method:: render()

      Render the element to HTML.