cronixui 1.1.1 → 1.1.3

package/packages/python/cronixui/list.py

@@ -1,51 +1,154 @@
-"""CronixUI List Component"""
+"""CronixUI List Component.
 
-from typing import Optional, Callable
-from .core import create_el
+Generates HTML for lists with optional icons, titles, subtitles, and actions.
+No browser DOM APIs are used - all output is HTML strings or data structures.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ListElement:
+    """Represents a rendered list element."""
+
+    tag: str = "div"
+    classes: List[str] = field(default_factory=list)
+    attributes: Dict[str, str] = field(default_factory=dict)
+    inner_html: str = ""
+
+    def render_html(self) -> str:
+        """Render as HTML string.
+
+        Returns:
+            Complete HTML for the list element
+        """
+        class_str = " ".join(self.classes)
+        class_attr = f' class="{class_str}"' if class_str else ""
+        attrs_str = "".join(f' {k}="{v}"' for k, v in self.attributes.items())
+        return f"<{self.tag}{class_attr}{attrs_str}>{self.inner_html}</{self.tag}>"
+
+    def render(self) -> "ListElement":
+        """Return self for API compatibility."""
+        return self
 
 
 class List:
-    """List component."""
+    """List component for displaying collections of items.
+
+    Items can be simple strings or dictionaries with optional keys:
+        - icon: SVG markup for the item icon
+        - title: Primary text for the item
+        - subtitle: Secondary/description text
+        - actions: HTML string for action buttons/links
+
+    Args:
+        items: List of items (strings or dicts)
+        clickable: Whether items should appear clickable (default: False)
+
+    Example:
+        >>> simple = List(["Item 1", "Item 2", "Item 3"])
+        >>> print(simple.render_html())
+        <div class="cn-list">
+            <div class="cn-list-item"><div class="cn-list-item-content">Item 1</div></div>
+            <div class="cn-list-item"><div class="cn-list-item-content">Item 2</div></div>
+            <div class="cn-list-item"><div class="cn-list-item-content">Item 3</div></div>
+        </div>
+
+        >>> rich = List([
+        ...     {
+        ...         "icon": "<svg>...</svg>",
+        ...         "title": "Dashboard",
+        ...         "subtitle": "Main overview",
+        ...         "actions": "<button>Edit</button>",
+        ...     },
+        ...     {"title": "Settings", "subtitle": "App configuration"},
+        ... ], clickable=True)
+        >>> print(rich.render_html())
+    """
+
+    def __init__(self, items: List[Any], clickable: bool = False):
+        if not items:
+            raise ValueError("items cannot be empty")
 
-    def __init__(self, items: list, clickable: bool = False):
         self.items = items
         self.clickable = clickable
-        self.element = self._render()
 
-    def _render(self):
-        el = create_el("div", "cn-list")
+    def render(self) -> ListElement:
+        """Render the list as a ListElement.
+
+        Returns:
+            ListElement containing all list items
+        """
+        item_parts = []
         for item in self.items:
-            item_el = create_el("div", "cn-list-item")
+            item_classes = ["cn-list-item"]
             if self.clickable:
-                item_el.classList.add("cn-list-item-clickable")
+                item_classes.append("cn-list-item-clickable")
 
             if isinstance(item, dict):
-                if icon := item.get("icon"):
-                    icon_el = create_el("span", "cn-list-item-icon")
-                    icon_el.innerHTML = icon
-                    item_el.appendChild(icon_el)
-
-                content = create_el("div", "cn-list-item-content")
-                if title := item.get("title"):
-                    title_el = create_el("div", "cn-list-item-title")
-                    title_el.textContent = title
-                    content.appendChild(title_el)
-
-                if subtitle := item.get("subtitle"):
-                    subtitle_el = create_el("div", "cn-list-item-subtitle")
-                    subtitle_el.textContent = subtitle
-                    content.appendChild(subtitle_el)
-
-                item_el.appendChild(content)
-
-                if actions := item.get("actions"):
-                    actions_el = create_el("div", "cn-list-item-actions")
-                    actions_el.innerHTML = actions
-                    item_el.appendChild(actions_el)
+                item_parts.append(self._render_dict_item(item, item_classes))
             else:
-                content = create_el("div", "cn-list-item-content")
-                content.textContent = str(item)
-                item_el.appendChild(content)
+                content = self._esc(str(item))
+                item_parts.append(
+                    f'<div class="{" ".join(item_classes)}">'
+                    f'<div class="cn-list-item-content">{content}</div>'
+                    f"</div>"
+                )
+
+        return ListElement(
+            classes=["cn-list"],
+            inner_html="".join(item_parts),
+        )
+
+    def _render_dict_item(self, item: dict, item_classes: List[str]) -> str:
+        """Render a single dict-based list item."""
+        class_str = " ".join(item_classes)
+        parts = [f'<div class="{class_str}">']
+
+        # Icon
+        if icon := item.get("icon"):
+            parts.append(f'<span class="cn-list-item-icon">{icon}</span>')
+
+        # Content
+        content_parts = []
+        if title := item.get("title"):
+            content_parts.append(
+                f'<div class="cn-list-item-title">{self._esc(title)}</div>'
+            )
+        if subtitle := item.get("subtitle"):
+            content_parts.append(
+                f'<div class="cn-list-item-subtitle">{self._esc(subtitle)}</div>'
+            )
+        if content_parts:
+            parts.append(
+                f'<div class="cn-list-item-content">{"".join(content_parts)}</div>'
+            )
+
+        # Actions
+        if actions := item.get("actions"):
+            parts.append(f'<div class="cn-list-item-actions">{actions}</div>')
+
+        parts.append("</div>")
+        return "".join(parts)
+
+    def render_html(self) -> str:
+        """Render the list as an HTML string.
+
+        Returns:
+            HTML string representation of the list
+        """
+        return self.render().render_html()
 
-            el.appendChild(item_el)
-        return el
+    @staticmethod
+    def _esc(text: str) -> str:
+        """Escape HTML special characters."""
+        return (
+            text.replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+            .replace("'", "&#x27;")
+        )

package/packages/python/cronixui/loading.py

@@ -1,36 +1,126 @@
-"""CronixUI Loading Components"""
+"""CronixUI Loading Components.
 
-from .core import create_el
+Generates HTML for spinners and skeleton loading placeholders.
+No browser DOM APIs are used - all output is HTML strings or data structures.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class LoadingElement:
+    """Represents a rendered loading element."""
+
+    tag: str = "div"
+    classes: List[str] = field(default_factory=list)
+    attributes: Dict[str, str] = field(default_factory=dict)
+    inner_html: str = ""
+
+    def render_html(self) -> str:
+        """Render as HTML string.
+
+        Returns:
+            Complete HTML for the loading element
+        """
+        class_str = " ".join(self.classes)
+        class_attr = f' class="{class_str}"' if class_str else ""
+        attrs_str = "".join(f' {k}="{v}"' for k, v in self.attributes.items())
+        return f"<{self.tag}{class_attr}{attrs_str}>{self.inner_html}</{self.tag}>"
+
+    def render(self) -> "LoadingElement":
+        """Return self for API compatibility."""
+        return self
 
 
 class Spinner:
-    """Loading spinner component."""
+    """Loading spinner component.
+
+    Args:
+        size: Spinner size - sm, md, lg (default: md)
+
+    Example:
+        >>> spinner = Spinner(size="lg")
+        >>> print(spinner.render_html())
+        <div class="cn-spinner cn-spinner-lg"></div>
+    """
 
     SIZES = ("sm", "md", "lg")
 
     def __init__(self, size: str = "md"):
-        self.size = size if size in self.SIZES else "md"
-        self.element = self._render()
+        if size not in self.SIZES:
+            raise ValueError(f"Invalid size '{size}'. Must be one of {self.SIZES}")
+
+        self.size = size
+
+    def render(self) -> LoadingElement:
+        """Render the spinner as a LoadingElement.
 
-    def _render(self):
-        el = create_el("div", "cn-spinner")
+        Returns:
+            LoadingElement representing the spinner
+        """
+        classes = ["cn-spinner"]
         if self.size != "md":
-            el.classList.add(f"cn-spinner-{self.size}")
-        return el
+            classes.append(f"cn-spinner-{self.size}")
+
+        return LoadingElement(classes=classes)
+
+    def render_html(self) -> str:
+        """Render the spinner as an HTML string.
+
+        Returns:
+            HTML string representation of the spinner
+        """
+        return self.render().render_html()
 
 
 class Skeleton:
-    """Skeleton loading placeholder."""
+    """Skeleton loading placeholder for content while it loads.
+
+    Args:
+        variant: Skeleton type - text, title, avatar (default: text)
+        width: Optional CSS width for the skeleton (e.g. "200px", "50%")
+
+    Example:
+        >>> skeleton = Skeleton(variant="title", width="300px")
+        >>> print(skeleton.render_html())
+        <div class="cn-skeleton cn-skeleton-title" style="width: 300px;"></div>
+    """
 
     VARIANTS = ("text", "title", "avatar")
 
-    def __init__(self, variant: str = "text", width: str = None):
-        self.variant = variant if variant in self.VARIANTS else "text"
+    def __init__(self, variant: str = "text", width: Optional[str] = None):
+        if variant not in self.VARIANTS:
+            raise ValueError(
+                f"Invalid variant '{variant}'. Must be one of {self.VARIANTS}"
+            )
+
+        self.variant = variant
         self.width = width
-        self.element = self._render()
 
-    def _render(self):
-        el = create_el("div", f"cn-skeleton cn-skeleton-{self.variant}")
+    def render(self) -> LoadingElement:
+        """Render the skeleton as a LoadingElement.
+
+        Returns:
+            LoadingElement representing the skeleton placeholder
+        """
+        classes = ["cn-skeleton", f"cn-skeleton-{self.variant}"]
+
+        attrs: Dict[str, str] = {}
         if self.width:
-            el.style.width = self.width
-        return el
+            attrs["style"] = f"width: {self.width};"
+
+        return LoadingElement(
+            classes=classes,
+            attributes=attrs,
+        )
+
+    def render_html(self) -> str:
+        """Render the skeleton as an HTML string.
+
+        Returns:
+            HTML string representation of the skeleton placeholder
+        """
+        return self.render().render_html()

package/packages/python/cronixui/progress.py

@@ -1,10 +1,63 @@
-"""CronixUI Progress Components"""
+"""CronixUI Progress Components.
 
-from .core import create_el
+Generates HTML for progress bars and stat/metric displays.
+No browser DOM APIs are used - all output is HTML strings or data structures.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ProgressElement:
+    """Represents a rendered progress/stat element."""
+
+    tag: str = "div"
+    classes: List[str] = field(default_factory=list)
+    attributes: Dict[str, str] = field(default_factory=dict)
+    inner_html: str = ""
+
+    def render_html(self) -> str:
+        """Render as HTML string.
+
+        Returns:
+            Complete HTML for the element
+        """
+        class_str = " ".join(self.classes)
+        class_attr = f' class="{class_str}"' if class_str else ""
+        attrs_str = "".join(f' {k}="{v}"' for k, v in self.attributes.items())
+        return f"<{self.tag}{class_attr}{attrs_str}>{self.inner_html}</{self.tag}>"
+
+    def render(self) -> "ProgressElement":
+        """Return self for API compatibility."""
+        return self
 
 
 class Progress:
-    """Progress bar component."""
+    """Progress bar component for showing completion percentage.
+
+    Args:
+        value: Current progress value (default: 0)
+        max: Maximum value (default: 100)
+        variant: Progress variant - default, success, warning, error (default: default)
+        size: Progress bar size - sm, md, lg (default: md)
+        show_label: Whether to show value/max text (default: False)
+
+    Example:
+        >>> progress = Progress(value=75, max=100, show_label=True)
+        >>> print(progress.render_html())
+        <div>
+            <div class="cn-progress-label"><span>75</span><span>100</span></div>
+            <div class="cn-progress">
+                <div class="cn-progress-bar" style="width: 75.0%;"></div>
+            </div>
+        </div>
+
+        >>> success = Progress(value=100, variant="success", size="lg")
+        >>> print(success.render_html())
+    """
 
     VARIANTS = ("default", "success", "warning", "error")
     SIZES = ("sm", "md", "lg")
@@ -17,74 +70,163 @@ class Progress:
         size: str = "md",
         show_label: bool = False,
     ):
+        if max <= 0:
+            raise ValueError("max must be greater than 0")
+        if value < 0:
+            raise ValueError("value cannot be negative")
+        if variant not in self.VARIANTS:
+            raise ValueError(
+                f"Invalid variant '{variant}'. Must be one of {self.VARIANTS}"
+            )
+        if size not in self.SIZES:
+            raise ValueError(f"Invalid size '{size}'. Must be one of {self.SIZES}")
+
         self.value = value
         self.max = max
-        self.variant = variant if variant in self.VARIANTS else "default"
-        self.size = size if size in self.SIZES else "md"
+        self.variant = variant
+        self.size = size
         self.show_label = show_label
-        self.element = self._render()
 
-    def _render(self):
-        container = create_el("div")
+    def render(self) -> ProgressElement:
+        """Render the progress bar as a ProgressElement.
+
+        Returns:
+            ProgressElement representing the progress bar
+        """
+        parts = []
 
+        # Label
         if self.show_label:
-            label = create_el("div", "cn-progress-label")
-            current = create_el("span")
-            current.textContent = str(int(self.value))
-            total = create_el("span")
-            total.textContent = str(int(self.max))
-            label.appendChild(current)
-            label.appendChild(total)
-            container.appendChild(label)
-
-        progress = create_el("div", "cn-progress")
+            parts.append(
+                f'<div class="cn-progress-label">'
+                f"<span>{int(self.value)}</span>"
+                f"<span>{int(self.max)}</span>"
+                f"</div>"
+            )
+
+        # Progress bar container
+        bar_classes = ["cn-progress"]
         if self.size != "md":
-            progress.classList.add(f"cn-progress-{self.size}")
+            bar_classes.append(f"cn-progress-{self.size}")
         if self.variant != "default":
-            progress.classList.add(f"cn-progress-{self.variant}")
+            bar_classes.append(f"cn-progress-{self.variant}")
 
-        bar = create_el("div", "cn-progress-bar")
-        bar.style.width = f"{(self.value / self.max) * 100}%"
-        progress.appendChild(bar)
+        # Bar fill
+        percentage = (self.value / self.max) * 100
+        bar_fill = (
+            f'<div class="cn-progress-bar" style="width: {percentage}%;"></div>'
+        )
 
-        container.appendChild(progress)
-        return container
+        parts.append(
+            f'<div class="{" ".join(bar_classes)}">{bar_fill}</div>'
+        )
 
-    def set_value(self, value: float):
-        self.value = value
-        bar = self.element.querySelector(".cn-progress-bar")
-        if bar:
-            bar.style.width = f"{(self.value / self.max) * 100}%"
+        return ProgressElement(inner_html="".join(parts))
+
+    def render_html(self) -> str:
+        """Render the progress bar as an HTML string.
+
+        Returns:
+            HTML string representation of the progress bar
+        """
+        return self.render().render_html()
+
+    def with_value(self, value: float) -> "Progress":
+        """Return a new Progress with updated value (immutable pattern).
+
+        Since components generate strings, we can't update in place after rendering.
+        Use this to create an updated copy.
+
+        Args:
+            value: New progress value
+
+        Returns:
+            New Progress instance with the updated value
+        """
+        return Progress(
+            value=value,
+            max=self.max,
+            variant=self.variant,
+            size=self.size,
+            show_label=self.show_label,
+        )
 
 
 class Stat:
-    """Stat component for displaying metrics."""
+    """Stat component for displaying metrics with optional delta/ trend.
+
+    Args:
+        value: Primary stat value (e.g. "1,234")
+        label: Stat label (e.g. "Total Users")
+        delta: Optional delta text (e.g. "+12%")
+        delta_type: Optional delta type for styling (e.g. "positive", "negative")
+
+    Example:
+        >>> stat = Stat(value="1,234", label="Total Users", delta="+12%", delta_type="positive")
+        >>> print(stat.render_html())
+        <div class="cn-stat">
+            <div class="cn-stat-value">1,234</div>
+            <div class="cn-stat-label">Total Users</div>
+            <div class="cn-stat-delta cn-stat-delta-positive">+12%</div>
+        </div>
+    """
 
     def __init__(
-        self, value: str, label: str, delta: str = None, delta_type: str = None
+        self,
+        value: str,
+        label: str,
+        delta: Optional[str] = None,
+        delta_type: Optional[str] = None,
     ):
+        if not value:
+            raise ValueError("value cannot be empty")
+        if not label:
+            raise ValueError("label cannot be empty")
+
         self.value = value
         self.label = label
         self.delta = delta
         self.delta_type = delta_type
-        self.element = self._render()
-
-    def _render(self):
-        el = create_el("div", "cn-stat")
 
-        value_el = create_el("div", "cn-stat-value")
-        value_el.textContent = self.value
-        el.appendChild(value_el)
+    def render(self) -> ProgressElement:
+        """Render the stat as a ProgressElement.
 
-        label_el = create_el("div", "cn-stat-label")
-        label_el.textContent = self.label
-        el.appendChild(label_el)
+        Returns:
+            ProgressElement representing the stat display
+        """
+        parts = [
+            f'<div class="cn-stat-value">{self._esc(self.value)}</div>',
+            f'<div class="cn-stat-label">{self._esc(self.label)}</div>',
+        ]
 
         if self.delta:
-            delta_el = create_el(
-                "div", f"cn-stat-delta cn-stat-delta-{self.delta_type}"
+            delta_classes = ["cn-stat-delta"]
+            if self.delta_type:
+                delta_classes.append(f"cn-stat-delta-{self.delta_type}")
+            parts.append(
+                f'<div class="{" ".join(delta_classes)}">{self._esc(self.delta)}</div>'
             )
-            delta_el.textContent = self.delta
-            el.appendChild(delta_el)
 
-        return el
+        return ProgressElement(
+            classes=["cn-stat"],
+            inner_html="".join(parts),
+        )
+
+    def render_html(self) -> str:
+        """Render the stat as an HTML string.
+
+        Returns:
+            HTML string representation of the stat
+        """
+        return self.render().render_html()
+
+    @staticmethod
+    def _esc(text: str) -> str:
+        """Escape HTML special characters."""
+        return (
+            text.replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+            .replace("'", "&#x27;")
+        )