django-cfg 1.4.116__py3-none-any.whl → 1.5.14__py3-none-any.whl

django_cfg/modules/django_admin/utils/html/base.py

@@ -0,0 +1,167 @@
+"""
+Basic HTML elements for Django Admin.
+
+Provides fundamental HTML building blocks: icons, spans, text, divs, links, and empty placeholders.
+"""
+
+from typing import Any, Optional
+
+from django.utils.html import escape, format_html
+from django.utils.safestring import SafeString
+
+
+class BaseElements:
+    """Basic HTML building blocks."""
+
+    @staticmethod
+    def icon(icon_name: str, size: str = "xs", css_class: str = "") -> SafeString:
+        """
+        Render Material Icon.
+
+        Args:
+            icon_name: Icon name from Icons class
+            size: xs, sm, base, lg, xl
+            css_class: Additional CSS classes
+        """
+        size_classes = {
+            'xs': 'text-xs',
+            'sm': 'text-sm',
+            'base': 'text-base',
+            'lg': 'text-lg',
+            'xl': 'text-xl'
+        }
+        size_class = size_classes.get(size, 'text-xs')
+        classes = f"material-symbols-outlined {size_class}"
+        if css_class:
+            classes += f" {css_class}"
+
+        return format_html('<span class="{}">{}</span>', classes, icon_name)
+
+    @staticmethod
+    def span(text: Any, css_class: str = "") -> SafeString:
+        """
+        Render text in span with optional CSS class.
+
+        Args:
+            text: Text to display
+            css_class: CSS classes
+        """
+        if css_class:
+            return format_html('<span class="{}">{}</span>', css_class, escape(str(text)))
+        return format_html('<span>{}</span>', escape(str(text)))
+
+    @staticmethod
+    def text(
+        content: Any,
+        variant: Optional[str] = None,
+        size: Optional[str] = None,
+        weight: Optional[str] = None,
+        muted: bool = False
+    ) -> SafeString:
+        """
+        Render styled text with semantic variants.
+
+        Args:
+            content: Text content (can be SafeString from other html methods)
+            variant: Color variant - 'success', 'warning', 'danger', 'info', 'primary'
+            size: Size - 'xs', 'sm', 'base', 'lg', 'xl', '2xl'
+            weight: Font weight - 'normal', 'medium', 'semibold', 'bold'
+            muted: Use muted/subtle color
+
+        Usage:
+            # Success text
+            html.text("$1,234.56", variant="success", size="lg")
+
+            # Muted small text
+            html.text("(12.5%)", muted=True, size="sm")
+
+            # Combined with other methods
+            total = html.number(1234.56, prefix="$")
+            html.text(total, variant="success", size="lg")
+
+        Returns:
+            SafeString with styled text
+        """
+        classes = []
+
+        # Variant colors
+        if variant:
+            variant_classes = {
+                'success': 'text-success-600 dark:text-success-400',
+                'warning': 'text-warning-600 dark:text-warning-400',
+                'danger': 'text-danger-600 dark:text-danger-400',
+                'info': 'text-info-600 dark:text-info-400',
+                'primary': 'text-primary-600 dark:text-primary-400',
+            }
+            classes.append(variant_classes.get(variant, ''))
+
+        # Muted
+        if muted:
+            classes.append('text-font-subtle-light dark:text-font-subtle-dark')
+
+        # Size
+        if size:
+            size_classes = {
+                'xs': 'text-xs',
+                'sm': 'text-sm',
+                'base': 'text-base',
+                'lg': 'text-lg',
+                'xl': 'text-xl',
+                '2xl': 'text-2xl',
+            }
+            classes.append(size_classes.get(size, ''))
+
+        # Weight
+        if weight:
+            weight_classes = {
+                'normal': 'font-normal',
+                'medium': 'font-medium',
+                'semibold': 'font-semibold',
+                'bold': 'font-bold',
+            }
+            classes.append(weight_classes.get(weight, ''))
+
+        css_class = ' '.join(filter(None, classes))
+
+        if css_class:
+            return format_html('<span class="{}">{}</span>', css_class, content)
+        return format_html('<span>{}</span>', content)
+
+    @staticmethod
+    def div(content: Any, css_class: str = "") -> SafeString:
+        """
+        Render content in div with optional CSS class.
+
+        Args:
+            content: Content to display (can be SafeString)
+            css_class: CSS classes
+        """
+        if css_class:
+            return format_html('<div class="{}">{}</div>', css_class, content)
+        return format_html('<div>{}</div>', content)
+
+    @staticmethod
+    def link(url: str, text: str, css_class: str = "", target: str = "") -> SafeString:
+        """
+        Render link.
+
+        Args:
+            url: URL
+            text: Link text
+            css_class: CSS classes
+            target: Target attribute (_blank, _self, etc)
+        """
+        if target:
+            return format_html(
+                '<a href="{}" class="{}" target="{}">{}</a>',
+                url, css_class, target, escape(text)
+            )
+        return format_html('<a href="{}" class="{}">{}</a>', url, css_class, escape(text))
+
+    @staticmethod
+    def empty(text: str = "—") -> SafeString:
+        """Render empty/placeholder value."""
+        return format_html(
+            '<span class="text-font-subtle-light dark:text-font-subtle-dark">{}</span>',
+            escape(text)
+        )

django_cfg/modules/django_admin/utils/html/code.py

@@ -0,0 +1,87 @@
+"""
+Code display elements for Django Admin.
+
+Provides inline code and code block rendering with syntax highlighting support.
+"""
+
+from typing import Any, Optional
+
+from django.utils.html import escape, format_html
+from django.utils.safestring import SafeString
+
+
+class CodeElements:
+    """Code display elements."""
+
+    @staticmethod
+    def code(text: Any, css_class: str = "") -> SafeString:
+        """
+        Render inline code.
+
+        Args:
+            text: Code text
+            css_class: Additional CSS classes
+
+        Usage:
+            html.code("/path/to/file")
+            html.code("command --arg value")
+        """
+        base_classes = "font-mono text-xs bg-base-100 dark:bg-base-800 px-1.5 py-0.5 rounded"
+        classes = f"{base_classes} {css_class}".strip()
+
+        return format_html(
+            '<code class="{}">{}</code>',
+            classes,
+            escape(str(text))
+        )
+
+    @staticmethod
+    def code_block(
+        text: Any,
+        language: Optional[str] = None,
+        max_height: Optional[str] = None,
+        variant: str = "default"
+    ) -> SafeString:
+        """
+        Render code block with optional syntax highlighting and scrolling.
+
+        Args:
+            text: Code content
+            language: Programming language (json, python, bash, etc.) - for future syntax highlighting
+            max_height: Max height with scrolling (e.g., "400px", "20rem")
+            variant: Color variant - default, warning, danger, success, info
+
+        Usage:
+            html.code_block(json.dumps(data, indent=2), language="json")
+            html.code_block(stdout, max_height="400px")
+            html.code_block(stderr, max_height="400px", variant="warning")
+        """
+        # Variant-specific styles
+        variant_classes = {
+            'default': 'bg-base-50 dark:bg-base-900 border-base-200 dark:border-base-700',
+            'warning': 'bg-warning-50 dark:bg-warning-900/20 border-warning-200 dark:border-warning-700',
+            'danger': 'bg-danger-50 dark:bg-danger-900/20 border-danger-200 dark:border-danger-700',
+            'success': 'bg-success-50 dark:bg-success-900/20 border-success-200 dark:border-success-700',
+            'info': 'bg-info-50 dark:bg-info-900/20 border-info-200 dark:border-info-700',
+        }
+
+        variant_class = variant_classes.get(variant, variant_classes['default'])
+
+        # Base styles
+        base_classes = f"font-mono text-xs whitespace-pre-wrap break-words border rounded-md p-3 {variant_class}"
+
+        # Add max-height and overflow if specified
+        style = ""
+        if max_height:
+            style = f'style="max-height: {max_height}; overflow-y: auto;"'
+
+        # Add language class for potential syntax highlighting
+        lang_class = f"language-{language}" if language else ""
+
+        return format_html(
+            '<pre class="{} {}" {}><code>{}</code></pre>',
+            base_classes,
+            lang_class,
+            style,
+            escape(str(text))
+        )

django_cfg/modules/django_admin/utils/html/composition.py

@@ -0,0 +1,205 @@
+"""
+Composition elements for Django Admin.
+
+Provides methods for composing multiple elements together: inline, icon_text, header.
+"""
+
+from typing import Any, Optional, Union
+
+from django.utils.html import escape, format_html
+from django.utils.safestring import SafeString
+
+
+class CompositionElements:
+    """Element composition utilities."""
+
+    @staticmethod
+    def icon(icon_name: str, size: str = "xs", css_class: str = "") -> SafeString:
+        """
+        Render Material Icon (helper for internal use).
+
+        Args:
+            icon_name: Icon name
+            size: Icon size
+            css_class: Additional CSS classes
+        """
+        from .base import BaseElements
+        return BaseElements.icon(icon_name, size, css_class)
+
+    @staticmethod
+    def icon_text(icon_or_text: Union[str, Any], text: Any = None,
+                  icon_size: str = "xs", separator: str = " ") -> SafeString:
+        """
+        Render icon with text or emoji with text.
+
+        Args:
+            icon_or_text: Icon from Icons class, emoji, or text if text param is None
+            text: Optional text to display after icon
+            icon_size: Icon size (xs, sm, base, lg, xl)
+            separator: Separator between icon and text
+
+        Usage:
+            html.icon_text(Icons.EDIT, 5)  # Icon with number
+            html.icon_text("📝", 5)  # Emoji with number
+            html.icon_text("Active")  # Just text
+        """
+        if text is None:
+            # Just text
+            return format_html('<span>{}</span>', escape(str(icon_or_text)))
+
+        # Check if it's a Material Icon (from Icons class) or emoji
+        icon_str = str(icon_or_text)
+
+        # Detect if it's emoji by checking for non-ASCII characters
+        is_emoji = any(ord(c) > 127 for c in icon_str)
+
+        if is_emoji or icon_str in ['📝', '💬', '🛒', '👤', '📧', '🔔', '⚙️', '🔧', '📊', '🎯']:
+            # Emoji
+            icon_html = escape(icon_str)
+        else:
+            # Material Icon
+            icon_html = CompositionElements.icon(icon_str, size=icon_size)
+
+        # DON'T escape SafeString - it's already safe HTML!
+        from django.utils.safestring import SafeString
+        if isinstance(text, SafeString):
+            text_html = text
+        else:
+            text_html = escape(str(text))
+
+        return format_html('{}{}<span>{}</span>', icon_html, separator, text_html)
+
+    @staticmethod
+    def inline(*items, separator: str = " | ",
+               size: str = "small", css_class: str = "") -> SafeString:
+        """
+        Render items inline with separator.
+
+        Args:
+            *items: Variable number of SafeString/str items to join (filters out None values)
+            separator: Separator between items
+            size: small, medium, large
+            css_class: Additional CSS classes
+
+        Usage:
+            html.inline(
+                html.icon_text(Icons.EDIT, 5),
+                html.icon_text(Icons.CHAT, 10),
+                separator=" | "
+            )
+        """
+        # Filter out None values
+        filtered_items = [item for item in items if item is not None]
+
+        if not filtered_items:
+            return format_html('<span class="text-font-subtle-light dark:text-font-subtle-dark">—</span>')
+
+        size_classes = {
+            'small': 'text-xs',
+            'medium': 'text-sm',
+            'large': 'text-base'
+        }
+        size_class = size_classes.get(size, 'text-xs')
+
+        classes = size_class
+        if css_class:
+            classes += f" {css_class}"
+
+        # Convert items to strings, keeping SafeString as-is
+        from django.utils.safestring import SafeString, mark_safe
+        processed_items = []
+        for item in filtered_items:
+            if isinstance(item, (SafeString, str)):
+                processed_items.append(item)
+            else:
+                processed_items.append(escape(str(item)))
+
+        # Join with separator - str() doesn't lose SafeString when joined then mark_safe'd
+        joined = mark_safe(separator.join(str(item) for item in processed_items))
+
+        return format_html('<span class="{}">{}</span>', classes, joined)
+
+    @staticmethod
+    def header(
+        title: str,
+        subtitle: Optional[str] = None,
+        initials: Optional[str] = None,
+        avatar_variant: str = "primary"
+    ) -> SafeString:
+        """
+        Render header with avatar/initials, title and subtitle.
+
+        Creates a horizontal layout with circular avatar badge and text content.
+        Common pattern for displaying users, accounts, entities with identity.
+
+        Args:
+            title: Main title text
+            subtitle: Optional subtitle text (smaller, muted)
+            initials: Optional initials for avatar (e.g., "AB", "JD")
+            avatar_variant: Color variant for avatar badge (primary, success, info, etc.)
+
+        Usage:
+            # User with avatar
+            html.header(
+                title="John Doe",
+                subtitle="john@example.com • Admin",
+                initials="JD"
+            )
+
+            # Account with info
+            html.header(
+                title="Trading Account",
+                subtitle="Binance • SPOT • user@email.com",
+                initials="TA",
+                avatar_variant="success"
+            )
+
+            # Simple title only
+            html.header(title="Item Name")
+
+        Returns:
+            SafeString with header component HTML
+        """
+        # Avatar/initials badge
+        avatar_html = ""
+        if initials:
+            avatar_html = format_html(
+                '<span class="inline-flex items-center justify-center rounded-full w-8 h-8 text-xs font-semibold {} mr-3">{}</span>',
+                CompositionElements._get_avatar_classes(avatar_variant),
+                escape(initials)
+            )
+
+        # Title
+        title_html = format_html(
+            '<div class="font-medium text-sm text-font-default-light dark:text-font-default-dark">{}</div>',
+            escape(title)
+        )
+
+        # Subtitle
+        subtitle_html = ""
+        if subtitle:
+            subtitle_html = format_html(
+                '<div class="text-xs text-font-subtle-light dark:text-font-subtle-dark mt-0.5">{}</div>',
+                escape(subtitle)
+            )
+
+        # Combine
+        return format_html(
+            '<div class="flex items-center">{}<div>{}{}</div></div>',
+            avatar_html,
+            title_html,
+            subtitle_html
+        )
+
+    @staticmethod
+    def _get_avatar_classes(variant: str) -> str:
+        """Get CSS classes for avatar badge variant."""
+        variant_classes = {
+            'success': 'bg-success-100 text-success-800 dark:bg-success-900 dark:text-success-200',
+            'warning': 'bg-warning-100 text-warning-800 dark:bg-warning-900 dark:text-warning-200',
+            'danger': 'bg-danger-100 text-danger-800 dark:bg-danger-900 dark:text-danger-200',
+            'info': 'bg-info-100 text-info-800 dark:bg-info-900 dark:text-info-200',
+            'primary': 'bg-primary-100 text-primary-800 dark:bg-primary-900 dark:text-primary-200',
+            'secondary': 'bg-base-100 text-font-default-light dark:bg-base-800 dark:text-font-default-dark',
+        }
+        return variant_classes.get(variant, variant_classes['primary'])

django_cfg/modules/django_admin/utils/html/formatting.py

@@ -0,0 +1,231 @@
+"""
+Formatting elements for Django Admin.
+
+Provides number and UUID formatting utilities.
+"""
+
+from typing import Any, Optional
+
+from django.utils.html import escape, format_html
+from django.utils.safestring import SafeString
+
+
+class FormattingElements:
+    """Formatting utilities for numbers and UUIDs."""
+
+    @staticmethod
+    def empty(text: str = "—") -> SafeString:
+        """Helper for empty values."""
+        from .base import BaseElements
+        return BaseElements.empty(text)
+
+    @staticmethod
+    def number(
+        value: Any,
+        precision: int = 8,
+        thousands_separator: bool = True,
+        strip_zeros: bool = True,
+        min_threshold: Optional[float] = None,
+        compact: bool = False,
+        prefix: str = "",
+        suffix: str = "",
+        css_class: str = ""
+    ) -> SafeString:
+        """
+        Format numeric values with smart precision handling.
+
+        Handles:
+        - Trailing zeros removal (20.000000 → 20)
+        - Scientific notation (0E-18 → 0)
+        - Thousands separators (1000000 → 1,000,000)
+        - Very small numbers (0.0000001 → < 0.00000001)
+        - Compact notation with K/M/B/T suffixes (1500000 → 1.5M)
+        - Negative values
+
+        Args:
+            value: Numeric value (int, float, Decimal, str)
+            precision: Number of decimal places (default: 8)
+            thousands_separator: Add thousands separator (default: True)
+            strip_zeros: Remove trailing zeros (default: True)
+            min_threshold: Show "< threshold" for very small numbers
+            compact: Use compact notation with K/M/B/T suffixes (default: False)
+            prefix: Text before number (e.g., "$", "BTC ")
+            suffix: Text after number (e.g., " USD", "%")
+            css_class: Additional CSS classes
+
+        Usage:
+            # Crypto balance
+            html.number(0.00012345, precision=8)  # "0.00012345"
+            html.number(20.000000, precision=8)   # "20"
+            html.number(1000000.5)                # "1,000,000.5"
+
+            # Currency
+            html.number(1234.56, precision=2, prefix="$")  # "$1,234.56"
+
+            # Compact notation
+            html.number(1500, compact=True, prefix="$")           # "$1.5K"
+            html.number(2500000, compact=True, prefix="$")        # "$2.5M"
+            html.number(3500000000, compact=True, prefix="$")     # "$3.5B"
+            html.number(1200000000000, compact=True, prefix="$")  # "$1.2T"
+
+            # Very small numbers
+            html.number(0.0000001, precision=8, min_threshold=1e-8)  # "< 0.00000001"
+
+            # Scientific notation handling
+            html.number("0E-18", precision=8)  # "0"
+
+        Returns:
+            SafeString with formatted number
+        """
+        from decimal import Decimal, InvalidOperation
+
+        # Handle None/empty
+        if value is None or value == "":
+            return FormattingElements.empty("—")
+
+        # Convert to Decimal for precise calculations
+        try:
+            if isinstance(value, str):
+                # Handle scientific notation in strings
+                decimal_value = Decimal(value)
+            elif isinstance(value, (int, float)):
+                decimal_value = Decimal(str(value))
+            elif isinstance(value, Decimal):
+                decimal_value = value
+            else:
+                return FormattingElements.empty(str(value))
+        except (InvalidOperation, ValueError):
+            return FormattingElements.empty(str(value))
+
+        # Check if value is effectively zero (scientific notation like 0E-18)
+        if decimal_value == 0:
+            formatted = "0"
+        else:
+            # Check min_threshold for very small positive numbers
+            if min_threshold and 0 < abs(decimal_value) < min_threshold:
+                threshold_str = f"{min_threshold:.{precision}f}"
+                if strip_zeros:
+                    threshold_str = threshold_str.rstrip('0').rstrip('.')
+                return format_html(
+                    '<span class="{}">{}< {}{}</span>',
+                    css_class,
+                    escape(prefix),
+                    threshold_str,
+                    escape(suffix)
+                )
+
+            # Compact notation with K/M/B/T suffixes
+            if compact:
+                abs_value = abs(float(decimal_value))
+                is_negative = decimal_value < 0
+                compact_suffix = ""
+
+                # Determine divisor and suffix
+                if abs_value >= 1_000_000_000_000:  # Trillion
+                    divided_value = abs_value / 1_000_000_000_000
+                    compact_suffix = "T"
+                elif abs_value >= 1_000_000_000:  # Billion
+                    divided_value = abs_value / 1_000_000_000
+                    compact_suffix = "B"
+                elif abs_value >= 1_000_000:  # Million
+                    divided_value = abs_value / 1_000_000
+                    compact_suffix = "M"
+                elif abs_value >= 1_000:  # Thousand
+                    divided_value = abs_value / 1_000
+                    compact_suffix = "K"
+                else:
+                    # Below 1000, use normal formatting
+                    divided_value = abs_value
+                    compact_suffix = ""
+
+                # Format with precision (use 1 decimal for compact)
+                compact_precision = 1 if compact_suffix else precision
+                formatted = f"{divided_value:.{compact_precision}f}"
+
+                # Strip trailing zeros if requested
+                if strip_zeros:
+                    formatted = formatted.rstrip('0').rstrip('.')
+
+                # Add negative sign back
+                if is_negative:
+                    formatted = f"-{formatted}"
+
+                # Add compact suffix
+                formatted += compact_suffix
+            else:
+                # Format with precision
+                formatted = f"{decimal_value:.{precision}f}"
+
+                # Strip trailing zeros if requested (only for non-compact)
+                if strip_zeros:
+                    formatted = formatted.rstrip('0').rstrip('.')
+
+                # Add thousands separator (only for non-compact)
+                if thousands_separator:
+                    parts = formatted.split('.')
+                    integer_part = parts[0]
+                    decimal_part = parts[1] if len(parts) > 1 else None
+
+                    # Handle negative sign
+                    is_negative = integer_part.startswith('-')
+                    if is_negative:
+                        integer_part = integer_part[1:]
+
+                    # Add commas
+                    integer_part = f"{int(integer_part):,}"
+
+                    # Restore negative sign
+                    if is_negative:
+                        integer_part = f"-{integer_part}"
+
+                    # Rebuild number
+                    formatted = integer_part
+                    if decimal_part:
+                        formatted += f".{decimal_part}"
+
+        # Add prefix/suffix
+        result = f"{prefix}{formatted}{suffix}"
+
+        # Wrap in span with CSS class if provided
+        if css_class:
+            return format_html('<span class="{}">{}</span>', css_class, result)
+
+        return format_html('<span>{}</span>', result)
+
+    @staticmethod
+    def uuid_short(uuid_value: Any, length: int = 6, show_tooltip: bool = True) -> SafeString:
+        """
+        Shorten UUID to first N characters with optional tooltip.
+
+        Args:
+            uuid_value: UUID string or UUID object
+            length: Number of characters to show (default: 6)
+            show_tooltip: Show full UUID on hover (default: True)
+
+        Usage:
+            html.uuid_short(obj.id)  # "a1b2c3..."
+            html.uuid_short(obj.id, length=8)  # "a1b2c3d4..."
+            html.uuid_short(obj.id, show_tooltip=False)  # Just short version
+
+        Returns:
+            SafeString with shortened UUID
+        """
+        uuid_str = str(uuid_value)
+
+        # Remove dashes for cleaner display
+        uuid_clean = uuid_str.replace('-', '')
+
+        # Take first N characters
+        short_uuid = uuid_clean[:length]
+
+        if show_tooltip:
+            return format_html(
+                '<code class="font-mono text-xs bg-base-100 dark:bg-base-800 px-1.5 py-0.5 rounded cursor-help" title="{}">{}</code>',
+                uuid_str,
+                short_uuid
+            )
+
+        return format_html(
+            '<code class="font-mono text-xs bg-base-100 dark:bg-base-800 px-1.5 py-0.5 rounded">{}</code>',
+            short_uuid
+        )