cronixui 1.1.2 → 1.1.3

package/packages/python/README.md

@@ -0,0 +1,142 @@
+# CronixUI Python Package
+
+A dark-themed UI toolkit with crimson accents and Outfit typography, implemented in pure Python.
+
+## Installation
+
+```bash
+pip install cronixui
+```
+
+For development:
+
+```bash
+pip install cronixui[dev]
+```
+
+## Quick Start
+
+```python
+from cronixui import Button, Card, Toast, Badge
+from cronixui.tokens import BG, ACCENT, TEXT
+
+# Create a button
+btn = Button("Click me", variant="primary")
+print(btn.render_html())
+# <button class="cn-btn cn-btn-primary">Click me</button>
+
+# Create a card
+card = Card(title="My Card", body="Card content")
+print(card.render_html())
+# <div class="cn-card">...</div>
+
+# Show a toast
+toast = Toast.success("Operation completed!")
+print(toast.message)  # Operation completed!
+
+# Use a badge
+badge = Badge("New", variant="success")
+print(badge.render_html())
+# <span class="cn-badge cn-badge-success">New</span>
+```
+
+## Components
+
+All components generate HTML strings and don't require a browser to run:
+
+- **Button** - Buttons with variants (primary, ghost, outline, danger, success)
+- **ButtonGroup** - Group multiple buttons together
+- **Card** - Card containers with header, body, footer
+- **Badge** - Status badges with semantic colors
+- **Tag** - Removable tags with close buttons
+- **Avatar** - User avatars with initials
+- **AvatarGroup** - Grouped avatar display
+- **Toast** - Toast notification data
+- **Alert** - Alert messages with variants
+- **Progress** - Progress bars
+- **Stat** - Statistics display
+- **Table** - Data tables
+- **List** - Lists with icons and actions
+- **Form** - Form inputs (Input, Textarea, Select, Checkbox, Radio, etc.)
+- **Layout** - Layout components (Header, Sidebar, Footer, Container)
+- **Tooltip** - Tooltip wrappers
+- **Loading** - Spinners and skeletons
+- **Tabs** - Tab navigation
+- **Accordion** - Collapsible sections
+- **Modal** - Modal dialogs
+- **Dropdown** - Dropdown menus
+- **Nav** - Navigation bars
+- **Pagination** - Pagination controls
+- **CommandPalette** - Command palette data
+- **Search** - Search component data
+
+## Design Tokens
+
+Access design tokens for consistent theming:
+
+```python
+from cronixui.tokens import (
+    Color, BG, SURFACE, ACCENT, TEXT,
+    typography, spacing, radius, shadow
+)
+
+# Colors
+print(BG.hex)  # #0a0a0a
+print(ACCENT.rgb)  # (107, 35, 35)
+
+# Typography
+print(typography.font_family)  # 'Outfit', ...
+print(typography.lg)  # 16
+
+# Spacing
+print(spacing.space_4)  # 16
+
+# Border radius
+print(radius.default)  # 10
+
+# Shadows
+print(shadow.lg)  # 0 8px 24px rgba(0, 0, 0, 0.5)
+```
+
+## Development
+
+### Running tests
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=cronixui --cov-report=html
+```
+
+### Code formatting
+
+```bash
+black .
+ruff check .
+```
+
+### Type checking
+
+```bash
+mypy cronixui
+```
+
+### Building the package
+
+```bash
+python -m build
+```
+
+### Publishing to PyPI
+
+```bash
+python -m twine upload dist/*
+```
+
+## License
+
+GPL 3.0, see LICENSE for details.

package/packages/python/cronixui/__init__.py

@@ -24,7 +24,14 @@ from .tooltip import Tooltip
 from .layout import Header, Sidebar, Footer, Container, Divider, Section
 from .form import Input, Textarea, FormField, Checkbox, Radio, Select, Slider, FileInput
 from .progress import Progress, Stat
-from .core import init, query, query_all, create_el
+from .core import (
+    HtmlElement,
+    ComponentGroup,
+    el,
+    classes,
+    attrs,
+    escape_html,
+)
 from .tokens import (
     BG,
     SURFACE,
@@ -71,7 +78,7 @@ from .tokens import (
     Layout,
 )
 
-__version__ = "1.0.6"
+__version__ = "1.1.2"
 __all__ = [
     "Toast",
     "Toggle",
@@ -115,10 +122,12 @@ __all__ = [
     "FileInput",
     "Progress",
     "Stat",
-    "init",
-    "query",
-    "query_all",
-    "create_el",
+    "HtmlElement",
+    "ComponentGroup",
+    "el",
+    "classes",
+    "attrs",
+    "escape_html",
     "BG",
     "SURFACE",
     "SURFACE_2",

package/packages/python/cronixui/alert.py

@@ -1,14 +1,70 @@
-"""CronixUI Alert Component"""
+"""CronixUI Alert Component.
 
-from typing import Optional
-from .core import create_el
+Generates HTML for alert banners with icon, title, message, and optional dismiss button.
+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
+
+from .core import HtmlElement
+
+
+@dataclass
+class AlertElement:
+    """Represents a rendered alert 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 the alert as HTML string.
+
+        Returns:
+            Complete HTML for the alert including icon, content, and optional close button
+        """
+        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) -> "AlertElement":
+        """Return self for API compatibility."""
+        return self
 
 
 class Alert:
-    """Alert component for messages."""
+    """Alert component for displaying informational, success, warning, or error messages.
+
+    Args:
+        message: The alert message text
+        title: Optional alert title
+        variant: Alert variant - info, success, warning, error (default: info)
+        dismissible: Whether to show a close button (default: False)
+
+    Example:
+        >>> alert = Alert("Your changes were saved.", title="Success", variant="success")
+        >>> print(alert.render_html())
+        <div class="cn-alert cn-alert-success">...</div>
+
+        >>> dismissible = Alert("Dismiss me", dismissible=True)
+        >>> print(dismissible.render_html())
+        <div class="cn-alert cn-alert-info" data-dismissible="true">...</div>
+    """
 
     VARIANTS = ("info", "success", "warning", "error")
 
+    _ICONS = {
+        "info": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4M12 8h.01"/></svg>',
+        "success": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/></svg>',
+        "warning": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>',
+        "error": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/></svg>',
+    }
+
     def __init__(
         self,
         message: str,
@@ -16,46 +72,73 @@ class Alert:
         variant: str = "info",
         dismissible: bool = False,
     ):
+        if variant not in self.VARIANTS:
+            raise ValueError(
+                f"Invalid variant '{variant}'. Must be one of {self.VARIANTS}"
+            )
+        if not message:
+            raise ValueError("message cannot be empty")
+
         self.message = message
         self.title = title
-        self.variant = variant if variant in self.VARIANTS else "info"
+        self.variant = variant
         self.dismissible = dismissible
-        self.element = self._render()
 
-    def _render(self):
-        el = create_el("div", f"cn-alert cn-alert-{self.variant}")
+    def render(self) -> AlertElement:
+        """Render the alert as an AlertElement data structure.
+
+        Returns:
+            AlertElement representing the complete alert banner
+        """
+        icon_svg = self._ICONS.get(self.variant, "")
+
+        parts = []
 
-        icon_svg = self._get_icon_svg()
+        # Icon
         if icon_svg:
-            icon = create_el("span", "cn-alert-icon")
-            icon.innerHTML = icon_svg
-            el.appendChild(icon)
+            parts.append(f'<span class="cn-alert-icon">{icon_svg}</span>')
 
-        content = create_el("div", "cn-alert-content")
+        # Content area
+        content_parts = []
         if self.title:
-            title_el = create_el("div", "cn-alert-title")
-            title_el.textContent = self.title
-            content.appendChild(title_el)
+            content_parts.append(
+                f'<div class="cn-alert-title">{self._esc(self.title)}</div>'
+            )
+        content_parts.append(
+            f'<div class="cn-alert-message">{self._esc(self.message)}</div>'
+        )
+        parts.append(f'<div class="cn-alert-content">{"".join(content_parts)}</div>')
 
-        message_el = create_el("div", "cn-alert-message")
-        message_el.textContent = self.message
-        content.appendChild(message_el)
+        # Dismiss button
+        if self.dismissible:
+            parts.append(
+                '<button class="cn-alert-close" data-dismiss="alert">&times;</button>'
+            )
 
-        el.appendChild(content)
+        inner = "".join(parts)
+        dismiss_attr = ' data-dismissible="true"' if self.dismissible else ""
 
-        if self.dismissible:
-            close_btn = create_el("button", "cn-alert-close")
-            close_btn.innerHTML = "&times;"
-            close_btn.addEventListener("click", lambda: el.remove())
-            el.appendChild(close_btn)
-
-        return el
-
-    def _get_icon_svg(self):
-        icons = {
-            "info": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4M12 8h.01"/></svg>',
-            "success": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/></svg>',
-            "warning": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>',
-            "error": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/></svg>',
-        }
-        return icons.get(self.variant)
+        return AlertElement(
+            classes=["cn-alert", f"cn-alert-{self.variant}"],
+            attributes={"data-dismissible": "true"} if self.dismissible else {},
+            inner_html=inner,
+        )
+
+    def render_html(self) -> str:
+        """Render the alert as an HTML string.
+
+        Returns:
+            Complete HTML string for the alert
+        """
+        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;")
+        )

package/packages/python/cronixui/avatar.py

@@ -1,11 +1,62 @@
-"""CronixUI Avatar Component"""
+"""CronixUI Avatar Component.
 
-from typing import Optional
-from .core import create_el
+Generates HTML for user avatars (images or initials) and avatar groups.
+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
+
+from .core import HtmlElement
+
+
+@dataclass
+class AvatarElement:
+    """Represents a rendered avatar 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 the avatar as HTML string.
+
+        Returns:
+            Complete HTML for the avatar 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) -> "AvatarElement":
+        """Return self for API compatibility."""
+        return self
 
 
 class Avatar:
-    """Avatar component for user images or initials."""
+    """Avatar component for displaying user images or initials.
+
+    Args:
+        initials: User initials to display (e.g. "JD")
+        image_url: URL to user's avatar image
+        size: Avatar size - sm, md, lg, xl (default: md)
+
+    Note:
+        If both image_url and initials are provided, image_url takes precedence.
+
+    Example:
+        >>> avatar = Avatar(initials="JD", size="lg")
+        >>> print(avatar.render_html())
+        <div class="cn-avatar cn-avatar-lg">JD</div>
+
+        >>> img_avatar = Avatar(image_url="/path/to/photo.jpg")
+        >>> print(img_avatar.render_html())
+        <div class="cn-avatar"><img src="/path/to/photo.jpg" alt="" /></div>
+    """
 
     SIZES = ("sm", "md", "lg", "xl")
 
@@ -15,36 +66,92 @@ class Avatar:
         image_url: Optional[str] = None,
         size: str = "md",
     ):
+        if size not in self.SIZES:
+            raise ValueError(f"Invalid size '{size}'. Must be one of {self.SIZES}")
+        if not initials and not image_url:
+            raise ValueError("At least one of 'initials' or 'image_url' must be provided")
+
         self.initials = initials
         self.image_url = image_url
-        self.size = size if size in self.SIZES else "md"
-        self.element = self._render()
+        self.size = size
+
+    def render(self) -> AvatarElement:
+        """Render the avatar as an AvatarElement data structure.
 
-    def _render(self):
-        el = create_el("div", "cn-avatar")
+        Returns:
+            AvatarElement representing the avatar
+        """
+        classes = ["cn-avatar"]
         if self.size != "md":
-            el.classList.add(f"cn-avatar-{self.size}")
+            classes.append(f"cn-avatar-{self.size}")
 
         if self.image_url:
-            img = create_el("img")
-            img.setAttribute("src", self.image_url)
-            img.setAttribute("alt", self.initials or "Avatar")
-            el.appendChild(img)
+            alt_text = self.initials[:2].upper() if self.initials else "Avatar"
+            inner = f'<img src="{self.image_url}" alt="{self._esc(alt_text)}" />'
         elif self.initials:
-            el.textContent = self.initials[:2].upper()
+            inner = self._esc(self.initials[:2].upper())
+        else:
+            inner = ""
+
+        return AvatarElement(classes=classes, inner_html=inner)
+
+    def render_html(self) -> str:
+        """Render the avatar as an HTML string.
+
+        Returns:
+            HTML string representation of the avatar
+        """
+        return self.render().render_html()
 
-        return el
+    @staticmethod
+    def _esc(text: str) -> str:
+        """Escape HTML special characters."""
+        return (
+            text.replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+            .replace("'", "&#x27;")
+        )
 
 
 class AvatarGroup:
-    """Group of overlapping avatars."""
+    """Group of overlapping avatars, typically for showing multiple users.
+
+    Args:
+        *avatars: Avatar instances to include in the group
+
+    Example:
+        >>> avatars = AvatarGroup(
+        ...     Avatar(initials="AB"),
+        ...     Avatar(initials="CD"),
+        ...     Avatar(initials="EF"),
+        ... )
+        >>> print(avatars.render_html())
+        <div class="cn-avatar-group">...</div>
+    """
 
     def __init__(self, *avatars: Avatar):
+        if not avatars:
+            raise ValueError("At least one avatar must be provided")
         self.avatars = avatars
-        self.element = self._render()
 
-    def _render(self):
-        el = create_el("div", "cn-avatar-group")
-        for avatar in self.avatars:
-            el.appendChild(avatar.element)
-        return el
+    def render(self) -> AvatarElement:
+        """Render the avatar group as an AvatarElement.
+
+        Returns:
+            AvatarElement wrapping all avatar children
+        """
+        children_html = "".join(a.render_html() for a in self.avatars)
+        return AvatarElement(
+            classes=["cn-avatar-group"],
+            inner_html=children_html,
+        )
+
+    def render_html(self) -> str:
+        """Render the avatar group as an HTML string.
+
+        Returns:
+            HTML string representation of the group
+        """
+        return self.render().render_html()