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

tts_html_utils/core/compiler.py

@@ -0,0 +1,215 @@
+#Standard Library Imports
+import pdb
+from collections import defaultdict
+from typing import List, Tuple, Dict, Any
+from pathlib import Path
+import html
+
+#Installed dependency imports
+from jinja2 import Template
+
+#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 HTML, Head, Body, Footer, Style, Script, TtsFavicon, Title
+
+logger = create_logger(name='html_utils.core.components.base')
+
+def make_hashable(obj: Any):
+    """
+    Recursively converts mutable objects (dicts, lists) into immutable equivalents 
+    (frozensets, tuples) to facilitate uniqueness checks.
+
+    This is necessary because we need to detect duplicate configuration dictionaries 
+    when aggregating resources. Since Python `sets` cannot contain mutable dictionaries, 
+    we must freeze them first to check if they are identical.
+
+    :param obj: The object to convert.
+    :return: An immutable, hashable version of the input.
+    """
+    if isinstance(obj, dict):
+        return frozenset((k, make_hashable(v)) for k, v in obj.items())
+    elif isinstance(obj, list):
+        return tuple(make_hashable(v) for v in obj)
+    elif isinstance(obj, set):
+        return frozenset(make_hashable(v) for v in obj)
+    else:
+        return obj
+
+def group_by_path_with_unique_dicts(tuples: List[Tuple[Path, Dict]]) -> List[Tuple[Path, List[Dict]]]:
+    """
+    Groups resource requests by file path and removes duplicate configurations.
+
+    This is used to manage dependencies efficiently. For example, if multiple 
+    components request the same JavaScript library with identical settings, 
+    this ensures the library is only loaded once. If they request the same 
+    library with *different* settings, both configurations are preserved.
+
+    :param tuples: A list of (FilePath, ConfigDict) pairs.
+    :return: A list of tuples where each FilePath is associated with a list of unique ConfigDicts.
+    """
+    grouped = defaultdict(set)
+
+    for path, meta in tuples:
+        hashable_meta = make_hashable(meta)
+        grouped[path].add(hashable_meta)
+
+    result = [
+        (path, [dict(items) for items in dicts])
+        for path, dicts in grouped.items()
+    ]
+
+    return result
+
+
+class HtmlCompiler:
+    """
+    Manages the lifecycle of an HTML document, handling component aggregation 
+    and dependency resolution.
+
+    This class abstracts away the manual construction of the `<html>` structure. 
+    It allows you to add Python component objects from this libary to the 
+    Head or Body, and automatically handles the "plumbing"—ensuring that any 
+    CSS or JavaScript required by those components is injected into the document 
+    correctly and without duplication.
+
+    :param title: The document title (displayed in the browser tab).
+    """
+    def __init__(self, title):
+        self.title = title
+        self.head_components = [TtsFavicon()]
+        self.body_components = list()
+        self.scripts = list()
+        self.styles = list()
+
+    def add_head_component(self, component):
+        """
+        Adds a component to the `<head>` section of the document.
+
+        The Head is used for metadata and configuration that is not directly 
+        displayed on the page canvas (e.g., meta tags, third-party analytics scripts, 
+        favicons, or social media open graph tags).
+
+        :param component: An `HtmlComponent` appropriate for the head section.
+        """
+        if isinstance(component, HtmlComponent):
+            self.head_components.append(component)
+        else:
+            raise Exception(f"{component} is not an HtmlComponent")
+
+    def add_body_component(self, component):
+        """
+        Adds a component to the `<body>` section of the document.
+
+        The Body contains the visible content of the page. Use this for 
+        visual elements like layout containers, text, tables, and widgets.
+
+        :param component: An `HtmlComponent` appropriate for the body section.
+        """
+        if isinstance(component, HtmlComponent):
+            self.body_components.append(component)
+        else:
+            raise Exception(f"{component} is not an HtmlComponent")
+
+    def compile(self):
+        """
+        Assembles the final object tree for the HTML document.
+
+        This method performs dependency injection and deduplication:
+        1. **Aggregation:** Scans all added components to find their required CSS/JS files.
+        2. **Deduplication:** Ensures shared resources (like a common plotting library) are not included twice.
+        3. **Rendering:** processes any Jinja2 templates found in the resource files.
+        4. **Construction:** Builds the root `HTML` object containing the configured `Head` and `Body`.
+
+        :return: The root `HTML` object ready for final string rendering.
+        """
+        css_includes = []
+        js_includes = []
+
+        # 1. Collect dependencies from all components
+        for component in self.head_components + self.body_components:
+            css_includes += component.aggregate_attributes('css_includes')
+            js_includes += component.aggregate_attributes('js_includes')
+
+        # 2. Remove duplicates
+        css_includes = group_by_path_with_unique_dicts(css_includes)
+        js_includes = group_by_path_with_unique_dicts(js_includes)
+
+        document = HTML()
+        head = Head()
+        head.add_child(Title(self.title))
+
+        # 3. Process and attach CSS
+        for path, dicts in css_includes:
+            if isinstance(path, str):
+                # Direct string path inclusion (e.g. for CDNs)
+                head.add_child(Style(path))
+                continue
+            
+            # Render template-based CSS files
+            css_template_text = path.open('r').read()
+            template = Template(css_template_text)
+            for d in dicts:
+                rendered_css = template.render(**d)
+                head.add_child(Style(rendered_css))
+
+        # 4. Process and attach JS
+        for path, dicts in js_includes:
+            if isinstance(path, str):
+                # Direct string path inclusion
+                head.add_child(Script(attr={'src': path}))
+                continue
+            
+            # Render template-based JS files
+            js_template_text = path.open('r').read()
+            template = Template(js_template_text)
+            for d in dicts:
+                rendered_js = template.render(**d)
+                head.add_child(Script(rendered_js))
+
+        # 5. Attach explicit components
+        for head_component in self.head_components:
+            head.add_child(head_component)
+
+        body = Body(style={'padding': '10px'})
+        for body_component in self.body_components:
+            body.add_child(body_component)
+
+        document.add_child(head)
+        document.add_child(body)
+
+        return document
+
+    def render(self):
+        """
+        Compiles the object tree and serializes it into an HTML string.
+
+        :return: The complete HTML source code.
+        """
+        return self.compile().render()
+
+    def render_to_file(self, filepath):
+        """
+        Compiles the HTML and writes it to the specified file path.
+
+        :param filepath: The full destination path for the .html file.
+        """
+        with open(filepath,'w') as f:
+            f.write(self.render())
+
+    def render_to_jnb_iframe(self, width='100%', height='300px'):
+        """
+        Compiles the HTML and writes it to the specified file path.
+
+        :param filepath: The full destination path for the .html file.
+        """
+        escaped_html = html.escape(self.render())
+        return f'''
+                <iframe 
+                    srcdoc="{escaped_html}" 
+                    style="width: {width}; height: {height}; border: 1px solid #ddd;" 
+                    sandbox="allow-scripts allow-same-origin"
+                ></iframe>
+                '''

tts_html_utils/core/components/__init__.py

@@ -0,0 +1,6 @@
+from .base import *
+from .misc import *
+from .text import *
+from .list import *
+from .table import *
+from .plot import *

tts_html_utils/core/components/base.py

@@ -0,0 +1,300 @@
+#Standard Library Imports
+from abc import ABC, abstractmethod
+from uuid import uuid4
+import pdb
+
+#Installed Dependecy Imports
+#none yet
+
+#Teamtools Studio Imports
+from tts_utilities.util import as_list
+from tts_utilities.logger import create_logger
+from bs4 import BeautifulSoup
+
+#This Library Imports
+# None
+
+logger = create_logger(name='html_utils.core.components.base')
+
+#================================================
+# :: Base Component
+#================================================
+class HtmlComponent(ABC):
+    """
+    The fundamental blueprint for all HTML elements in this library.
+
+    **The Concept:**
+    HTML is hierarchical (a tree). A `<div>` contains a `<table>`, which contains 
+    `<tr>` rows, which contain `<td>` cells. This class provides the machinery 
+    to replicate that structure in Python.
+
+    **How it works:**
+    Every specific HTML tag (like `Div`, `Span`, or `Img`) inherits from this class.
+    This base class handles the logic shared by *all* of them, such as:
+    1. **Parent/Child Relationships:** Tracking what is inside what.
+    2. **Attribute Management:** Handling IDs, CSS classes, and inline styles.
+    3. **Dependency bubbling:** If a button deep inside a table requires a specific 
+       JavaScript file, this class allows that requirement to bubble up to the 
+       top of the document so the `HtmlCompiler` can see it.
+
+    **Note:** This is an "Abstract Base Class" (ABC). You cannot create a generic `HtmlComponent` 
+    directly. You must use one of its subclasses that represents a real HTML tag.
+
+    :param children: Any nested components that go *inside* this element.
+    :type children: List of HtmlComponent objects (or plain strings), optional
+    :param class_name: Primary CSS class(es) to control the look/feel.
+    :type class_name: str or list of str, optional
+    :param extra_class_name: Additional CSS classes to append. Useful when extending components 
+                             where you want to keep the base class but add a modifier.
+    :type extra_class_name: str or list of str, optional
+    :param tag: The actual HTML tag name (e.g., 'div', 'a', 'span'). Defaults to the class's `TAG` constant.
+    :type tag: str, optional
+    :param id: The unique HTML `id` attribute for this element.
+    :type id: str, optional
+    :param style: Inline CSS styles (e.g., `{'color': 'red', 'margin': '10px'}`).
+    :type style: dict, optional
+    :param attr: A dictionary of any other HTML attributes not covered above (e.g., `{'href': '...', 'onclick': '...'}`).
+    :type attr: dict, optional
+    """
+    TAG = None
+    DEFAULT_CLASS = []
+    STYLESHEETS = []
+
+    def __init__(self, children=None, class_name=None, extra_class_name=None, tag=None, id=None, style=None, attr=None):
+        self.id = id
+        self.tag = tag or self.TAG
+        self.parent_id = None
+        self.children = []
+        self.js_includes = []
+        self.css_includes = []
+        self.attr = attr if attr is not None else {}
+
+        for child in as_list(children or []):
+            self.add_child(child)
+
+        self._class = [] + as_list(class_name or self.DEFAULT_CLASS)
+        if extra_class_name is not None:
+            self._class += as_list(extra_class_name)
+
+        self.style = style or {}
+
+    def aggregate_attributes(self, attr, lst=None):
+        """
+        The "Harvester" method.
+
+        This function recursively dives down into every child (and grandchild) 
+        of this component to find specific attributes (usually 'js_includes' or 
+        'css_includes').
+
+        **Why?** When you render a full page, the top-level document needs to know about 
+        every JavaScript file required by every tiny widget deep in the page structure.
+        This method bubbles those requirements up to the surface.
+
+        :param attr: The name of the attribute to collect (e.g., `'js_includes'`).
+        :type attr: str
+        :param lst: The accumulator list. If None, a new list is created.
+        :type lst: list, optional
+        :return: A list containing the collected attributes from this component and all descendents.
+        """
+        if lst is None: lst = []
+        v = getattr(self, attr, None)
+        if v is not None: lst += v #support elements without the given attr set
+        for child in self.children:
+            if not isinstance(child, HtmlComponent): continue
+            try:
+                child.aggregate_attributes(attr, lst=lst)
+            except:
+                pdb.set_trace()
+        return lst
+
+    def add_child(self, child):
+        """
+        Nests a new element inside this one.
+
+        :param child: The component to insert.
+        :type child: HtmlComponent or str
+        """
+        self.children.append(child)
+        if isinstance(child, HtmlComponent):
+            child.parent_id = self.id
+
+    @property
+    def class_name(self):
+        """
+        Returns the final, space-separated string of CSS classes.
+
+        This combines the default classes (from `DEFAULT_CLASS`) with any specific 
+        classes added during initialization or via `add_class`. This string is 
+        what actually gets written to the HTML `class="..."` attribute.
+        """
+        return " ".join(self._class)
+
+    def add_class(self, new_class):
+        """
+        Appends a new CSS class to the existing list of classes.
+        Useful for dynamically highlighting an element (e.g., adding 'active' or 'error').
+
+        :param new_class: The CSS class string to add.
+        :type new_class: str
+        """
+        if new_class not in self._class:
+            self._class.append(new_class)
+
+    @property
+    def rendered(self):
+        """
+        A convenience property that triggers the full rendering process.
+        Accessing `.rendered` is equivalent to calling the `.render()` method.
+
+        :return: The fully compiled HTML string for this component.
+        :rtype: str
+        """
+        return self.render()
+
+    @abstractmethod
+    def render(self):
+        """
+        This method transforms the abstract Python object into an actual HTML string.
+        Since this is the base class, it doesn't know *how* to render itself yet. 
+        Specific implementations (like `HtmlComponentSimple`) provide the logic here.
+        """
+        pass
+
+    @property
+    def content(self):
+        """
+        A convenience property that returns the *inner* HTML of the component.
+        
+        Example: If the component is `<div><b>Hello</b></div>`, `.content` returns `<b>Hello</b>`.
+        """
+        return self.render_content()
+
+    def render_content(self):
+        """
+        A hook for how an individual component should render its content as a string.
+        Most compoenents inherit from HtmlComponentSimple, which inherits from this. 
+        HtmlComponentSimple defines render_content itself, but it can always be
+        overridden by a descendent class.
+        """
+        raise NotImplementedError(f'This class does not implement content rendering')
+
+    def recurse_stylesheets(self):
+        """
+        Crawls the component tree to find all stylesheets declared by children.
+
+        Similar to `aggregate_attributes`, this ensures that if a nested component 
+        defines a custom `STYLESHEET`, that sheet is bubbled up and included in the 
+        document head.
+        """
+        child_sheets = self.STYLESHEETS
+        for child in self.children:
+            if isinstance(child, HtmlComponent):
+                child_sheets += child.recurse_stylesheets()
+        return child_sheets
+
+    def pretty_print(self):
+        """
+        A debugging tool that prints the HTML in a readable, indented format.
+        
+        Raw HTML strings are often one massive, unreadable line. This uses 
+        BeautifulSoup to break it into indented lines so you can see the structure 
+        visually.
+        """
+        html = self.render()
+        soup = BeautifulSoup(html, 'html.parser')
+        return soup.prettify()
+
+
+class HtmlComponentSimple(HtmlComponent):
+    """
+    The implementation for standard "Container" HTML tags.
+
+    **Concept:**
+    Most HTML tags work like containers: they open, they hold content, and they close.
+    Examples: `<div>...</div>`, `<p>...</p>`, `<b>...</b>`.
+    
+    This class implements the `render` logic for this open-close pattern.
+    """
+
+    def _render_open(self):
+        """
+        Internal helper: specific logic to build the *opening* tag.
+
+        It takes the Python dictionaries for style/attributes and converts them 
+        into string format.
+        """
+        # 1. Start with the tag itself
+        parts = [self.tag]
+
+        # 2. Add ID if present
+        if self.id:
+            parts.append(f'id="{self.id}"')
+
+        # 3. Add Class if present
+        if self.class_name:
+            parts.append(f'class="{self.class_name}"')
+
+        # 4. Add Style if present
+        if self.style:
+            style_str = ' '.join(f'{k}: {v};' for k, v in self.style.items())
+            parts.append(f'style="{style_str}"')
+
+        # 5. Add other attributes if present
+        if self.attr:
+            attr_str = ' '.join(f'{k}="{v}"' for k, v in self.attr.items())
+            parts.append(attr_str)
+
+        # 6. Join with spaces and wrap in brackets
+        # ' '.join(parts) ensures there is exactly one space between attributes
+        # and no trailing space before the closing bracket.
+        return f'<{" ".join(parts)}>'
+
+    def render(self):
+        """
+        Generates the full HTML string for this element and all its children.
+
+        Structure: `<tag> [All Children Rendered Here] </tag>`
+        """
+        return f'{self._render_open()}{self.content}</{self.tag}>'
+
+    def render_content(self):
+        """
+        Iterates through the children list, asks them to render themselves, 
+        and concatenates the results.
+        """
+        out = ''
+        for child in self.children:
+            if isinstance(child, HtmlComponent):
+                out += child.rendered
+            else:
+                out += str(child)
+        return out
+
+class HtmlComponentSingleSimple(HtmlComponentSimple):
+    """
+    The implementation for "Void" or "Self-Closing" HTML tags.
+
+    **Concept:**
+    Some HTML tags do not contain other elements. They are standalone instructions.
+    Examples: 
+    - `<img>`: Just places an image.
+    - `<br>`: Just creates a line break.
+    - `<input>`: Just creates a text box.
+
+    These tags **must not** have a closing tag (e.g., `</img>` is invalid HTML).
+    This class overrides the render method to ensure we only print the opening tag.
+    """
+    def render(self):
+        """
+        Renders the tag without a closing partner or internal content.
+        
+        Structure: `<tag attribute="value">`
+        """
+        return self._render_open()
+
+    def render_content(self):
+        """
+        Disabled for HtmlComponentSingleSimple, but still here in case it's called
+        so it raises a useful exception.
+        """
+        raise NotImplementedError(f'No content allowed for Singleton HTML elements')

tts_html_utils/core/components/favicon.py

@@ -0,0 +1,17 @@
+import base64
+from pathlib import Path
+
+def png_to_base64_string(image_path):
+    # 1. Open the image file in binary read mode ('rb')
+    with open(image_path, "rb") as image_file:
+        
+        # 2. Read the binary data and encode it to base64
+        base64_bytes = base64.b64encode(image_file.read())
+        
+        # 3. Decode bytes to a UTF-8 string so it can be printed
+        base64_string = base64_bytes.decode('utf-8')
+                
+        return base64_string
+
+favicon_data = f'data:image/png;base64,{png_to_base64_string(Path(__file__).parent.parent.parent / "resources/img/favicon.png")}'
+

tts_html_utils/core/components/flexbox.py

@@ -0,0 +1,133 @@
+#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
+from tts_html_utils.core.components.misc import Div
+
+logger = create_logger(name='tts_html_utils.core.components.flexbox')
+
+class FlexContainer(HtmlComponentSimple):
+    """
+    A flexible container that uses CSS Flexbox for layout.
+    
+    **Concept:**
+    The FlexContainer is a div with display:flex that allows for easy
+    arrangement of child elements in rows or columns with precise control
+    over sizing and spacing.
+    
+    :param children: Child components to be arranged in the flex container.
+    :type children: list or single HtmlComponent
+    :param direction: The flex-direction property. Options: 'row', 'column', 'row-reverse', 'column-reverse'.
+    :type direction: str, optional
+    :param justify: The justify-content property. Options: 'flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly'.
+    :type justify: str, optional
+    :param align: The align-items property. Options: 'flex-start', 'flex-end', 'center', 'stretch', 'baseline'.
+    :type align: str, optional
+    :param wrap: The flex-wrap property. Options: 'nowrap', 'wrap', 'wrap-reverse'.
+    :type wrap: str, optional
+    :param gap: The gap between flex items (e.g., '5px', '1rem').
+    :type gap: str, optional
+    :param kwargs: Additional keyword arguments passed to the parent Div.
+    """
+    TAG = 'div'
+    
+    def __init__(self, children=None, direction='row', justify='flex-start', 
+                 align='stretch', wrap='nowrap', gap=None, **kwargs):
+        # Build the style dictionary for flexbox
+        style = kwargs.get('style', {})
+        style.update({
+            'display': 'flex',
+            'flex-direction': direction,
+            'justify-content': justify,
+            'align-items': align,
+            'flex-wrap': wrap
+        })
+        
+        # Add gap if specified
+        if gap:
+            style['gap'] = gap
+            
+        kwargs['style'] = style
+        super().__init__(children=children, **kwargs)
+
+
+class FlexItem(HtmlComponentSimple):
+    """
+    A flex item that can be placed inside a FlexContainer.
+    
+    **Concept:**
+    FlexItems are divs with flex properties that control how they grow, shrink,
+    and what their base size is within a FlexContainer.
+    
+    :param children: Child components inside this flex item.
+    :type children: list or single HtmlComponent
+    :param width: The width of the item (e.g., '50%', '200px', 'auto').
+    :type width: str, optional
+    :param height: The height of the item (e.g., '100px', 'auto').
+    :type height: str, optional
+    :param grow: The flex-grow property (how much the item can grow). Default is 0 (no growing).
+    :type grow: int, optional
+    :param shrink: The flex-shrink property (how much the item can shrink). Default is 1 (can shrink).
+    :type shrink: int, optional
+    :param basis: The flex-basis property (base size before growing/shrinking). Default is 'auto'.
+    :type basis: str, optional
+    :param align_self: Override the container's align-items for this specific item.
+    :type align_self: str, optional
+    :param kwargs: Additional keyword arguments passed to the parent Div.
+    """
+    TAG = 'div'
+    
+    def __init__(self, children=None, width=None, height=None, grow=None, 
+                 shrink=None, basis=None, align_self=None, **kwargs):
+        # Build the style dictionary for the flex item
+        style = kwargs.get('style', {})
+        
+        # Add width and height if specified
+        if width:
+            style['width'] = width
+        if height:
+            style['height'] = height
+            
+        # Add flex properties if specified
+        if grow is not None or shrink is not None or basis is not None:
+            flex_parts = []
+            flex_parts.append(str(grow) if grow is not None else '0')
+            flex_parts.append(str(shrink) if shrink is not None else '1')
+            flex_parts.append(basis if basis is not None else 'auto')
+            style['flex'] = ' '.join(flex_parts)
+        
+        # Add align-self if specified
+        if align_self:
+            style['align-self'] = align_self
+            
+        kwargs['style'] = style
+        super().__init__(children=children, **kwargs)
+
+
+class FlexRow(FlexContainer):
+    """
+    A convenience class for a horizontal flex container.
+    
+    This is a FlexContainer with direction='row' preset.
+    """
+    def __init__(self, children=None, **kwargs):
+        kwargs['direction'] = 'row'
+        super().__init__(children=children, **kwargs)
+
+
+class FlexColumn(FlexContainer):
+    """
+    A convenience class for a vertical flex container.
+    
+    This is a FlexContainer with direction='column' preset.
+    """
+    def __init__(self, children=None, **kwargs):
+        kwargs['direction'] = 'column'
+        super().__init__(children=children, **kwargs)