tts-html-utils 0.5.4__py3-none-any.whl

tts_html_utils/core/components/list.py

@@ -0,0 +1,168 @@
+#Standard Library Imports
+import pdb
+
+#Installed dependency imports
+#None yet
+
+#Teamtools Studio Imports
+from tts_utilities.logger import create_logger
+
+#This Library Imports
+from tts_html_utils.core.components.base import HtmlComponent, HtmlComponentSimple
+
+logger = create_logger(name='html_utils.core.components.base')
+
+class UnorderedList(HtmlComponentSimple):
+    """
+    A standard bulleted list (<ul>).
+    
+    **Concept:**
+    Used for items where the order does not matter. Browsers typically 
+    render these with bullet points. This is also a common structural
+    element that is used without looking like a literal list.
+
+    **Alias:** `UL`
+    """
+    TAG = 'ul'
+
+UL = UnorderedList
+
+class OrderedList(HtmlComponentSimple):
+    """
+    A numbered list (<ol>).
+
+    **Concept:**
+    Used for items where the sequence is important. Browsers typically render 
+    these with numbers (1, 2, 3...) or letters (a, b, c...). Much less common
+    than an unordered list.
+
+
+    **Alias:** `OL`
+    """
+    TAG = 'ol'
+OL = OrderedList
+
+class ListItem(HtmlComponentSimple):
+    """
+    A single row within a list (<li>).
+
+    **Concept:**
+    Neither `<ul>` nor `<ol>` can directly contain text. They can only contain `<li>` tags.
+    This component wraps the actual content of the list entry.
+
+    **Alias:** `LI`
+    """
+    TAG = 'li'
+LI = ListItem
+
+class PowerList(HtmlComponent):
+    """
+    A smart builder for creating complex, nested lists without the headache.
+
+    **The Problem:**
+    Creating nested HTML lists is very repetative. You have to remember to open a `<ul>`, 
+    add an `<li>`, open a new `<ul>` *inside* that `<li>` for the sub-items, and then 
+    close everything in the exact reverse order.
+
+    **The Solution:**
+    `PowerList` works like a text editor's outline mode. You simply add a line, and 
+    command it to "indent" (`up_level`) or "outdent" (`down_level`). It tracks 
+    where you are in the hierarchy and handles all the tag nesting for you automatically.
+
+    :param children: Initial list items to populate. (Usually better to use `.line()` after init).
+    :type children: List, optional
+    :param class_name: CSS classes for the root list element.
+    :type class_name: str or list of str, optional
+    :param extra_class_name: Additional CSS classes to append.
+    :type extra_class_name: str or list of str, optional
+    :param style: Inline CSS styles for the root list element.
+    :type style: dict, optional
+    :param ordered: If True, renders as a numbered list (`<ol>`). If False, renders as bullets (`<ul>`). Defaults to False.
+    :type ordered: bool
+    """
+    def __init__(self, children=None, class_name=None, extra_class_name=None, style=None, ordered=False):
+        super().__init__(children=children, class_name=class_name, extra_class_name=extra_class_name, style=style)
+        self.ordered = ordered
+
+        # 'target' acts as a cursor. It points to the specific list (root or nested)
+        # where the next item should be added.
+        self.target = [self]
+
+    def line(self, line, class_name=None, extra_class_name=None, style=None):
+        """
+        Appends a new item to the current level of the list.
+
+        :param line: The content of the item (text or another HtmlComponent).
+        :type line: str or HtmlComponent
+        :param class_name: CSS classes for this specific list item (`<li>`).
+        :type class_name: str or list of str, optional
+        :param extra_class_name: Additional CSS classes to append.
+        :type extra_class_name: str or list of str, optional
+        :param style: Inline CSS styles for this specific list item.
+        :type style: dict, optional
+        """
+        if not isinstance(line, ListItem):
+            line = ListItem(children=line, class_name=class_name, extra_class_name=extra_class_name, style=style)
+
+        self.target[-1].add_child(line)
+
+
+    def up_level(self, label=None, new_list=None, class_name=None, extra_class_name=None, style=None, ordered=None):
+        """
+        Indents the list (creates a sub-list).
+
+        **How it works:**
+        This creates a new list (container) and nests it inside the *last item* you added.
+        The internal "cursor" moves to this new list, so subsequent `.line()` calls 
+        will appear as sub-items.
+
+        :param label: Optional text to place on the parent item *before* the sub-list starts.
+        :type label: str or HtmlComponent, optional
+        :param new_list: If you have already built a `UL` or `OL` object, you can pass it here to insert it.
+        :type new_list: UL or OL, optional
+        :param class_name: CSS classes for the new sub-list container.
+        :type class_name: str or list of str, optional
+        :param extra_class_name: Additional CSS classes to append.
+        :type extra_class_name: str or list of str, optional
+        :param style: Inline CSS styles for the new sub-list container.
+        :type style: dict, optional
+        :param ordered: If True, the sub-list will be numbered. If False, bulleted. Defaults to the parent list's type.
+        :type ordered: bool, optional
+        """
+
+        if not new_list:
+            if ordered is None:
+                ordered = self.ordered
+            
+            # FIX: Pass the styling arguments to the new PowerList
+            new_list = PowerList(
+                ordered=ordered, 
+                class_name=class_name, 
+                extra_class_name=extra_class_name, 
+                style=style
+            )
+
+        if label is not None: 
+            self.target[-1].add_child(ListItem(children=[label, new_list]))
+        else:
+            self.target[-1].add_child(ListItem(children=new_list))
+        self.target.append(new_list)
+
+    def down_level(self):
+        """
+        Outdents the list (returns to the parent level).
+
+        **How it works:**
+        Moves the internal "cursor" back up to the parent list.
+        """
+        if len(self.target) <= 1:
+            return # Do nothing if we're at the root level already
+        self.target.pop()
+
+    def render(self):
+        """
+        Converts the internal PowerList structure into standard HTML components
+        (`UL`/`OL` and `LI`) and renders them to a string.
+        """
+        top_list = OrderedList if self.ordered else UnorderedList
+        return top_list(children=self.children, class_name=self.class_name, style=self.style).rendered

tts_html_utils/core/components/misc.py

@@ -0,0 +1,237 @@
+#Standard Library Imports
+import pdb
+
+#Installed dependency imports
+#None yet
+
+#Teamtools Studio Imports
+from tts_utilities.logger import create_logger
+
+#This Library Imports
+from tts_html_utils.core.components.base import HtmlComponentSimple, HtmlComponentSingleSimple
+from tts_html_utils.core.components.favicon import favicon_data
+
+logger = create_logger(name='html_utils.core.components.base')
+
+class HTML(HtmlComponentSimple):
+    """
+    The root container for the entire document.
+
+    **Concept:**
+    This is the outermost shell of a webpage. Every other element (Head, Body, etc.) 
+    lives inside this tag.
+
+    **Usage Note:**
+    You rarely need to instantiate this yourself. The `HtmlCompiler` typically 
+    creates this automatically when you build a page.
+    """
+    TAG = 'html'
+
+class Head(HtmlComponentSimple):
+    """
+    The "Settings" section of the document.
+
+    **Concept:**
+    The `<head>` contains metadata—information *about* the page rather than content 
+    *on* the page. It holds the title, CSS links, scripts, and browser instructions.
+    Nothing put here is displayed in the main browser window.
+
+    **Usage Note:**
+    Like `HTML`, this is usually managed automatically by the `HtmlCompiler`.
+    """
+    TAG = 'head'
+
+class Body(HtmlComponentSimple):
+    """
+    The "Canvas" of the document.
+
+    **Concept:**
+    The `<body>` contains everything the user actually sees: text, images, buttons, 
+    and tables. If you are building a component to display data, it eventually 
+    lives inside here.
+
+    **Usage Note:**
+    Managed automatically by the `HtmlCompiler`. You typically just add children 
+    to the compiler, and it places them in the Body for you.
+    """
+    TAG = 'body'
+
+class Header(HtmlComponentSimple):
+    """
+    A semantic container for introductory content.
+
+    **Concept:**
+    Not to be confused with `<head>`. The `<header>` is a visible section of the page, 
+    usually containing the logo, navigation bar, and page title. It helps screen readers 
+    and search engines understand the structure of your content.
+    """
+    TAG = 'header'
+
+class Footer(HtmlComponentSimple):
+    """
+    A semantic container for the bottom of a page or section.
+
+    **Concept:**
+    Usually contains copyright notices, contact info, or links to privacy policies. 
+    Like `<header>`, this is a "semantic" tag—it behaves exactly like a `Div` 
+    visually, but it tells search engines "this is the end of the content."
+    """
+    TAG = 'footer'
+
+class Style(HtmlComponentSimple):
+    """
+    A container for raw CSS code.
+
+    **Concept:**
+    Allows you to write CSS rules directly within the HTML file rather than linking 
+    to an external `.css` file.
+    
+    **Usage Note:**
+    The `HtmlCompiler` uses this to inject CSS dependencies. You generally shouldn't 
+    need to use this manually; prefer creating `.css` files and linking them.
+    """
+    TAG = 'style'
+
+class Script(HtmlComponentSimple):
+    """
+    A container for raw JavaScript code.
+
+    **Concept:**
+    Allows you to write JavaScript logic directly within the HTML file. 
+
+    **Usage Note:**
+    The `HtmlCompiler` uses this to inject JS dependencies. For complex logic, 
+    prefer creating `.js` files and letting the compiler link them.
+    """
+    TAG = 'script'
+
+class Title(HtmlComponentSimple):
+    """
+    The browser tab name.
+
+    **Concept:**
+    Defines the text that appears in the browser tab, bookmarks, and search engine results. 
+    It does not appear in the page content itself.
+    """
+    TAG = 'title'
+
+class Div(HtmlComponentSimple):
+    """
+    The generic "Lego Brick" of the web.
+
+    **Concept:**
+    The `<div>` (Division) is a generic container used to group other elements together 
+    for styling or layout purposes. It has no semantic meaning (unlike `<header>` or `<footer>`).
+    
+    Most modern web layouts are essentially nested structures of Divs.
+    """
+    TAG = 'div'
+
+class TtsFavicon(Script):
+    """
+    Injects the Teamtools Studio logo into the browser tab.
+
+    **How it works:**
+    Instead of requiring you to manage a physical `.ico` or `.png` file on the server, 
+    this class contains the base64-encoded image data of the logo. It uses a small 
+    JavaScript snippet to create the link tag dynamically and attach it to the document head.
+    """
+    def __init__(self):
+        super().__init__()
+        self.js_includes = [('\n'.join([
+                      "const favicon = document.createElement('link');",
+                      "favicon.rel = 'icon';",
+                      "favicon.type = 'image/png';",
+                      f"favicon.href = '{favicon_data}';",
+                      "document.head.appendChild(favicon);",
+                    ]), {})]
+
+
+class HorizontalBreak(HtmlComponentSingleSimple):
+    """
+    A thematic break (Horizontal Rule).
+
+    **Concept:**
+    Renders a horizontal line across the container. Used to visually separate 
+    different topics or sections of content.
+
+    **Alias:** `HR`
+    """
+
+    TAG = 'hr'
+    DEFAULT_CLASS=['faded']
+
+HR = HorizontalBreak
+
+class LineBreak(HtmlComponentSingleSimple):
+    """
+    A forced line break.
+
+    **Concept:**
+    Forces the text following it to start on a new line. 
+    
+    **Usage Note:**
+    Use sparingly. For spacing between paragraphs, it is usually better to use 
+    CSS margins or separate `<p>` (Paragraph) tags rather than multiple `<br>` tags.
+
+    **Alias:** `BR`
+    """
+    TAG = 'br'
+
+BR = LineBreak
+
+class Link(HtmlComponentSimple):
+    """
+    A hyperlink (Anchor tag).
+
+    **Concept:**
+    The fundamental connector of the web. Links one page (or section) to another.
+
+    **Alias:** `A`
+
+    :param text: The clickable text the user sees.
+    :type text: str
+    :param href: The destination URL. If None, defaults to the `text` (useful if pasting raw URLs).
+    :type href: str, optional
+    :param new_tab: If True, clicking the link opens a new browser tab (`target="_blank"`). 
+                    If False, it navigates the current tab. Defaults to True.
+    :type new_tab: bool, optional
+    :param kwargs: Additional keyword arguments passed to the `HtmlComponent` constructor.
+    """
+
+    TAG='a'
+    def __init__(self, text, href=None, new_tab=True, **kwargs):
+        if href is None: href = text
+        attr = {'href': href, 'target': '_blank' if new_tab else '_self'}
+        if 'attr' in kwargs.keys():
+            attr = {**attr, **kwargs['attr']}
+            del kwargs['attr']
+        super().__init__(children=text, attr=attr, **kwargs)
+
+A = Link
+
+class Button(HtmlComponentSimple):
+    """
+    A clickable button element.
+
+    **Concept:**
+    Used for actions (like "Submit", "Calculate", "Toggle"), as opposed to Links 
+    which are used for navigation.
+
+    :param text: The label displayed on the button.
+    :type text: str
+    :param button_type: The HTML behavior type. 
+                        - 'button': A generic clickable button (requires JS to do anything).
+                        - 'submit': Submits a parent form.
+                        - 'reset': Resets a parent form.
+    :type button_type: str, optional
+    :param kwargs: Additional keyword arguments passed to the `HtmlComponent` constructor.
+    """
+
+    TAG='button'
+    def __init__(self, text, button_type='button', **kwargs):
+        attr = {'type': button_type}
+        if 'attr' in kwargs.keys():
+            attr = {**attr, **kwargs['attr']}
+            del kwargs['attr']
+        super().__init__(children=text, attr=attr, **kwargs)

tts_html_utils/core/components/navigation.py

@@ -0,0 +1,55 @@
+#Standard Library Imports
+from pathlib import Path
+import pdb
+
+#Installed dependency imports
+#None yet
+
+#Teamtools Studio Imports
+from tts_utilities.logger import create_logger
+
+#This Library Imports
+from tts_html_utils.core.components.list import PowerList, ListItem
+from tts_html_utils.core.components.misc import Link
+
+logger = create_logger(name='html_utils.core.components.base')
+
+
+class Navbar(PowerList):
+    """
+    Simple class to streamline creation of a navbar, which is essentially an unordered list
+    of links.
+
+    Nothing special now, but eventually this will be part of stock templates and will include out of the box CSS
+
+    :param mapping: Dictionary where keys are labels and values are URLs
+    :type style: dict
+
+    :param new_tab: Should links open to a new tab or in the current one?
+    :type new_tab: bool
+
+    :param kwargs: Additional keyword arguments passed to the `HtmlComponent` constructor.
+    """
+    def __init__(self, mapping, new_tab=False, **kwargs):
+        super().__init__(class_name='navbar', **kwargs)
+        self.add_items(mapping, new_tab=new_tab)
+        self.css_includes = [(Path(__file__).parent.parent.parent.joinpath('resources/css/navbar.css'),{})]
+
+    def add_items(self, mapping, new_tab=False):
+        """
+        Add an item to an existing Navbar. This is equivalent to including the item in the mapping parameter of __init__()
+
+        :param mapping: Dictionary where keys are labels and values are URLs
+        :type style: dict
+
+        :param new_tab: Should links open to a new tab or in the current one?
+        :type new_tab: bool
+        """
+        for label, href in mapping.items():
+            if isinstance(href, dict):
+                self.up_level(label=label)
+                self.add_items(href)
+                self.down_level()
+            else:
+                self.line(Link(label, href=href, new_tab=new_tab), class_name='navbartab')
+

tts_html_utils/core/components/plot.py

@@ -0,0 +1,166 @@
+#Standard Library Imports
+import pdb
+import uuid
+
+#Installed dependency imports
+import plotly.graph_objects as go
+import plotly.express as px
+import plotly.io as pio
+
+#Teamtools Studio Imports
+from tts_utilities.logger import create_logger
+
+#This Library Imports
+from tts_html_utils.core.components.base import HtmlComponent
+from tts_html_utils.core.components.misc import Div
+
+logger = create_logger(name='html_utils.core.components.base')
+
+class PlotBase(HtmlComponent):
+    """
+    The base wrapper for embedding Plotly figures into the HTML document.
+
+    **Concept:**
+    Plotly produces interactive, JavaScript-based charts. To put them in an HTML file, 
+    we need to convert the Python `Figure` object into a specific block of HTML/JS code.
+    
+    **Important Note on Performance:**
+    This component renders with `include_plotlyjs=False`. The global `plotly.js` library 
+    is automatically requested via the component's `js_includes` and managed by the 
+    `HtmlCompiler` to ensure it is loaded once in the `<head>`.
+
+    :param fig: The existing Plotly figure to render. If None, creates a blank figure.
+    :type fig: plotly.graph_objects.Figure, optional
+    :param title: Sets the title of the plot layout.
+    :type title: str, optional
+    :param template: The visual theme to use (e.g., 'plotly_dark', 'seaborn', 'ggplot2'). 
+                     Defaults to 'seaborn'.
+    :type template: str, optional
+    :param class_name: Primary CSS class for the container Div.
+    :type class_name: str, optional
+    :param extra_class_name: Additional CSS classes.
+    :type extra_class_name: str, optional
+    :param id: Optional. A custom ID for this container. If not provided, a unique ID will be generated.
+    :type id: str, optional
+    :param style: Dictionary of inline CSS styles for the container Div.
+    :type style: dict, optional
+    """
+    DEFAULT_PLOTLY_TEMPLATE = 'seaborn'
+    def __init__(self, fig=None, title=None, template=None, class_name=None, extra_class_name=None, id=None, style=None, include_plotlyjs=False, full_html=False):
+        self.fig = fig or go.Figure()
+        self.fig.update_layout(template=(template or self.DEFAULT_PLOTLY_TEMPLATE))
+        self.include_plotlyjs = include_plotlyjs
+        self.full_html = full_html
+        
+        if title:
+            self.fig.update_layout(title=title)
+        
+        # Ensure every plot has a unique ID for JS scoping if one isn't provided
+        if id is None:
+            id = f"plotly-{uuid.uuid4().hex[:8]}"
+
+        super().__init__(children=None, class_name=class_name, extra_class_name=extra_class_name, id=id, style=style)
+        
+        # Automatically include the Plotly global library via CDN
+        # The HtmlCompiler will deduplicate this if multiple plots are present.
+        self.js_includes.append(("https://cdn.plot.ly/plotly-3.3.1.min.js", {}))
+
+    def render(self):
+        """
+        Converts the Python Plotly figure into an HTML Div string.
+        """
+        # Generate the Plotly HTML snippet. 
+        # This already includes a <div id="self.id"> and a <script>.
+        plotly_html = pio.to_html(
+            self.fig,
+            include_plotlyjs=self.include_plotlyjs,
+            full_html=self.full_html,
+            div_id=self.id
+        )
+
+        return plotly_html
+
+
+class ScatterPlot(PlotBase):
+    """
+    A helper for creating basic line/scatter plots.
+
+    **Legacy Note:** This is a legacy wrapper. For complex visualization needs, it is generally 
+    recommended to use `dtat-lib` or build `go.Figure` objects directly and pass 
+    them to `PlotBase`.
+    """
+    def add_trace(self, y, x=None, name=None, lines=False, markers=True, trace_kwargs=None, scatter_kwargs=None):
+        """
+        Adds a new data series (trace) to the plot.
+
+        :param y: The Y-axis data points.
+        :type y: list or array-like
+        :param x: The X-axis data points.
+        :type x: list or array-like, optional
+        :param name: The name of this series (appears in the legend).
+        :type name: str, optional
+        :param lines: If True, connects points with lines.
+        :type lines: bool, default False
+        :param markers: If True, draws a dot at each data point.
+        :type markers: bool, default True
+        :param trace_kwargs: A passthrough dictionary of arguments sent to `self.fig.add_trace`. 
+                             Useful for advanced layout options like `secondary_y=True`.
+        :type trace_kwargs: dict, optional
+        :param scatter_kwargs: A passthrough dictionary of arguments sent to `go.Scatter`.
+                               Useful for styling options like `line_color`, `marker_size`, etc.
+        :type scatter_kwargs: dict, optional
+        """
+        modes = []
+        if lines:
+            modes.append('lines')
+        if markers:
+            modes.append('markers')
+
+        trace_kwargs = trace_kwargs or {}
+        scatter_kwargs = scatter_kwargs or {}
+
+        self.fig.add_trace(
+            go.Scatter(
+                x=x,
+                y=y,
+                mode='+'.join(modes),
+                name=name,
+                **scatter_kwargs
+            ),
+            **trace_kwargs
+        )
+
+class TimelinePlot(PlotBase):
+    """
+    A helper for creating Gantt-style timeline charts.
+
+    **Legacy Note:**
+    This is a legacy wrapper. Consider using `dtat-lib` for modern timeline visualization.
+    """
+    def __init__(self, data, x_start_name, x_end_name, y_name, color=None, title=None, date_format_str=None):
+        """
+        Initialize the timeline using `plotly.express.timeline`.
+
+        :param data: The dataset (usually a Pandas DataFrame).
+        :type data: pandas.DataFrame or list of dicts
+        :param x_start_name: The column name containing start timestamps.
+        :type x_start_name: str
+        :param x_end_name: The column name containing end timestamps.
+        :type x_end_name: str
+        :param y_name: The column name to use for the Y-axis labels (tasks/rows).
+        :type y_name: str
+        :param color: The column name to use for coloring the bars.
+        :type color: str, optional
+        :param title: The chart title.
+        :type title: str, optional
+        :param date_format_str: A d3-formatting string to control how dates appear on the X-axis 
+                                (e.g., '%Y-%m-%d').
+        :type date_format_str: str, optional
+        """
+        timeline = px.timeline(data, x_start=x_start_name, x_end=x_end_name, y=y_name, color=color)
+
+        super().__init__(fig=timeline, title=title)
+
+        # optionally update the formatting of the x-axis ticks (which are datetime compliant for all timeline plots)
+        if date_format_str:
+            self.fig.update_layout(xaxis_tickformat = date_format_str)