django-cfg 1.4.120__py3-none-any.whl → 1.5.2__py3-none-any.whl

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
+        )

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

@@ -0,0 +1,219 @@
+"""
+Key-value display elements for Django Admin.
+
+Provides utilities for displaying key-value pairs, breakdowns, and lists.
+"""
+
+from typing import Any, List, Optional
+
+from django.utils.html import escape, format_html
+from django.utils.safestring import SafeString, mark_safe
+
+
+class KeyValueElements:
+    """Key-value display utilities."""
+
+    @staticmethod
+    def icon(icon_name: str, size: str = "xs") -> SafeString:
+        """Helper to get icon (internal use)."""
+        from .base import BaseElements
+        return BaseElements.icon(icon_name, size)
+
+    @staticmethod
+    def text(content: Any, variant: Optional[str] = None, size: Optional[str] = None) -> SafeString:
+        """Helper to get styled text (internal use)."""
+        from .base import BaseElements
+        return BaseElements.text(content, variant=variant, size=size)
+
+    @staticmethod
+    def key_value(
+        key: str,
+        value: Any,
+        icon: Optional[str] = None,
+        indent: bool = False,
+        divider: bool = False,
+        value_variant: Optional[str] = None,
+        value_size: Optional[str] = None
+    ) -> SafeString:
+        """
+        Render single key-value pair.
+
+        Args:
+            key: Key text
+            value: Value (can be SafeString from other html methods)
+            icon: Material icon name
+            indent: Indent the item
+            divider: Show divider above
+            value_variant: Color variant for value ('success', 'warning', etc)
+            value_size: Size for value ('sm', 'base', 'lg')
+
+        Usage:
+            html.key_value('Total', '100 BTC')
+            html.key_value('Available', '60 BTC', icon=Icons.CHECK_CIRCLE, indent=True)
+            html.key_value('Price', '$1,234', divider=True, value_variant='success', value_size='lg')
+
+        Returns:
+            SafeString with key-value HTML
+        """
+        # Classes
+        classes = ['mb-2']
+        if indent:
+            classes.append('ml-5')
+        if divider:
+            classes.append('mt-4 pt-2 border-t border-base-200 dark:border-base-700')
+
+        # Wrap value if variant or size specified
+        if value_variant or value_size:
+            value = KeyValueElements.text(value, variant=value_variant, size=value_size)
+
+        # Build parts
+        parts = []
+        parts.append(f'<div class="{" ".join(classes)}">')
+
+        # Icon
+        if icon:
+            parts.append(str(KeyValueElements.icon(icon, size="xs")))
+            parts.append(' ')
+
+        # Key
+        parts.append(f'<span class="font-semibold text-font-default-light dark:text-font-default-dark">{escape(key)}:</span> ')
+
+        # Value
+        parts.append(str(value))
+
+        parts.append('</div>')
+
+        return mark_safe(''.join(parts))
+
+    @staticmethod
+    def divider(css_class: str = "my-2") -> SafeString:
+        """
+        Render horizontal divider line.
+
+        Args:
+            css_class: CSS classes for the hr element
+
+        Usage:
+            html.breakdown(
+                section1,
+                html.divider(),
+                section2,
+            )
+
+        Returns:
+            SafeString with hr element
+        """
+        return format_html('<hr class="{}">', css_class)
+
+    @staticmethod
+    def breakdown(*items: SafeString) -> SafeString:
+        """
+        Combine multiple key-value pairs into a breakdown section.
+
+        Args:
+            *items: Variable number of SafeStrings (from html.key_value())
+
+        Usage:
+            html.breakdown(
+                html.key_value('Total', total_val),
+                html.key_value('Available', avail_val, icon=Icons.CHECK_CIRCLE, indent=True),
+                html.key_value('Locked', locked_val, icon=Icons.LOCK, indent=True),
+                html.key_value('Price', price, divider=True) if has_price else None,
+                html.key_value('Total Value', usd_val, value_variant='success', value_size='lg') if has_price else None,
+            )
+
+        Returns:
+            SafeString with combined breakdown HTML
+        """
+        # Filter out None values
+        filtered = [str(item) for item in items if item is not None]
+
+        return mark_safe(''.join(filtered))
+
+    @staticmethod
+    def key_value_list(
+        items: List[dict],
+        layout: str = "vertical",
+        key_width: Optional[str] = None,
+        spacing: str = "normal"
+    ) -> SafeString:
+        """
+        Render key-value pairs as a formatted list.
+
+        Args:
+            items: List of dicts with 'key', 'value', and optional keys:
+                - icon: Material icon name
+                - indent: Boolean for indentation
+                - value_class: Tailwind classes for value
+                - divider: Boolean to show divider above
+                - size: 'sm', 'base', 'lg'
+            layout: "vertical" or "horizontal"
+            key_width: Fixed width for keys (e.g., "100px") for alignment
+            spacing: "tight", "normal", "relaxed"
+
+        Usage:
+            # Simple key-value list
+            html.key_value_list([
+                {'key': 'Total', 'value': '100 BTC', 'size': 'lg'},
+                {'key': 'Available', 'value': '60 BTC', 'indent': True},
+                {'key': 'Locked', 'value': '40 BTC', 'indent': True},
+            ])
+
+            # With icons and styling
+            html.key_value_list([
+                {'key': 'Available', 'value': '60 BTC', 'icon': Icons.CHECK_CIRCLE},
+                {'key': 'Total Value', 'value': '$1,234.56', 'value_class': 'text-success-600 text-lg', 'divider': True},
+            ])
+
+        Returns:
+            SafeString with formatted key-value list HTML
+        """
+        spacing_map = {
+            'tight': 'mb-1',
+            'normal': 'mb-2',
+            'relaxed': 'mb-3'
+        }
+        spacing_class = spacing_map.get(spacing, 'mb-2')
+
+        parts = []
+        for item in items:
+            key = item.get('key', '')
+            value = item.get('value', '')
+            icon = item.get('icon', '')
+            indent = item.get('indent', False)
+            value_class = item.get('value_class', '')
+            divider = item.get('divider', False)
+            size = item.get('size', 'base')
+
+            # Icon HTML
+            icon_html = ""
+            if icon:
+                icon_html = f'{KeyValueElements.icon(icon, size="xs")} '
+
+            # Size classes
+            size_map = {
+                'sm': 'text-sm',
+                'base': 'text-base',
+                'lg': 'text-lg'
+            }
+            size_class = size_map.get(size, 'text-base')
+
+            # Classes
+            indent_class = 'ml-5' if indent else ''
+            divider_class = 'mt-4 pt-2 border-t border-base-200 dark:border-base-700' if divider else ''
+
+            # Build item HTML
+            item_html = format_html(
+                '<div class="{} {} {} {}">{}<span class="font-semibold">{}:</span> <span class="{}">{}</span></div>',
+                spacing_class,
+                indent_class,
+                divider_class,
+                size_class,
+                icon_html,
+                escape(key),
+                value_class,
+                value  # Already SafeString from html.number()
+            )
+            parts.append(item_html)
+
+        return mark_safe(''.join(str(p) for p in parts))

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

@@ -0,0 +1,108 @@
+"""
+Markdown integration for HTML builder.
+
+Provides thin wrapper methods that delegate to MarkdownRenderer.
+"""
+
+from pathlib import Path
+from typing import Optional, Union
+
+from django.utils.safestring import SafeString
+
+
+class MarkdownIntegration:
+    """Markdown rendering integration for HtmlBuilder."""
+
+    @staticmethod
+    def markdown(
+        text: str,
+        css_class: str = "",
+        max_height: Optional[str] = None,
+        enable_plugins: bool = True
+    ) -> SafeString:
+        """
+        Render markdown text to beautifully styled HTML.
+
+        Delegates to MarkdownRenderer.render_markdown() for actual rendering.
+
+        Args:
+            text: Markdown content
+            css_class: Additional CSS classes
+            max_height: Max height with scrolling (e.g., "400px", "20rem")
+            enable_plugins: Enable mistune plugins (tables, strikethrough, etc.)
+
+        Usage:
+            # Simple markdown rendering
+            html.markdown("# Hello\\n\\nThis is **bold** text")
+
+            # With custom styling
+            html.markdown(obj.description, css_class="my-custom-class")
+
+            # With max height for long content
+            html.markdown(obj.documentation, max_height="500px")
+
+        Returns:
+            SafeString with rendered HTML
+        """
+        # Import here to avoid circular dependency
+        from ..markdown.renderer import MarkdownRenderer
+
+        return MarkdownRenderer.render_markdown(
+            text=text,
+            css_class=css_class,
+            max_height=max_height,
+            enable_plugins=enable_plugins
+        )
+
+    @staticmethod
+    def markdown_docs(
+        content: Union[str, Path],
+        collapsible: bool = True,
+        title: str = "Documentation",
+        icon: str = "description",
+        max_height: Optional[str] = "500px",
+        enable_plugins: bool = True,
+        default_open: bool = False
+    ) -> SafeString:
+        """
+        Render markdown documentation from string or file with collapsible UI.
+
+        Auto-detects whether content is a file path or markdown string.
+
+        Args:
+            content: Markdown string or path to .md file
+            collapsible: Wrap in collapsible details/summary
+            title: Title for collapsible section
+            icon: Material icon name for title
+            max_height: Max height for scrolling
+            enable_plugins: Enable markdown plugins
+            default_open: Open by default if collapsible
+
+        Usage:
+            # From string with collapse
+            html.markdown_docs(obj.description, title="Description")
+
+            # From file
+            html.markdown_docs("docs/api.md", title="API Documentation")
+
+            # Simple, no collapse
+            html.markdown_docs(obj.notes, collapsible=False)
+
+            # Open by default
+            html.markdown_docs(obj.readme, default_open=True)
+
+        Returns:
+            Rendered markdown with beautiful Tailwind styling
+        """
+        # Import here to avoid circular dependency
+        from ..markdown.renderer import MarkdownRenderer
+
+        return MarkdownRenderer.render(
+            content=content,
+            collapsible=collapsible,
+            title=title,
+            icon=icon,
+            max_height=max_height,
+            enable_plugins=enable_plugins,
+            default_open=default_open
+        )

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

@@ -0,0 +1,127 @@
+"""
+Progress bar elements for Django Admin.
+
+Provides progress bar rendering with multiple colored segments.
+"""
+
+from django.utils.html import escape
+from django.utils.safestring import SafeString, mark_safe
+
+
+class ProgressElements:
+    """Progress bar display elements."""
+
+    @staticmethod
+    def segment(percentage: float, variant: str = 'primary', label: str = ''):
+        """
+        Create progress bar segment with named parameters.
+
+        Args:
+            percentage: Percentage value (0-100)
+            variant: Color variant ('success', 'warning', 'danger', 'info', 'primary')
+            label: Label text
+
+        Usage:
+            html.segment(percentage=60, variant='success', label='Available')
+
+        Returns:
+            dict with segment data
+        """
+        return {'percentage': percentage, 'variant': variant, 'label': label}
+
+    @staticmethod
+    def progress_bar(
+        *segments,
+        width: str = "w-full max-w-xs",
+        height: str = "h-6",
+        show_labels: bool = True,
+        rounded: bool = True
+    ) -> SafeString:
+        """
+        Render progress bar with multiple colored segments using Tailwind.
+
+        Args:
+            *segments: Variable number of segment dicts (from html.segment())
+            width: Tailwind width classes (default: "w-full max-w-xs")
+            height: Tailwind height class (default: "h-6" = 24px for visibility)
+            show_labels: Show percentage labels below the bar
+            rounded: Use rounded corners
+
+        Usage:
+            html.progress_bar(
+                html.segment(percentage=60, variant='success', label='Available'),
+                html.segment(percentage=40, variant='warning', label='Locked')
+            )
+
+        Returns:
+            SafeString with progress bar HTML
+        """
+        # Standard Tailwind colors with dark mode (работают всегда!)
+        # Progress bars need visible contrast
+        variant_bg_map = {
+            'success': 'bg-green-600 dark:bg-green-500',
+            'warning': 'bg-yellow-600 dark:bg-yellow-500',
+            'danger': 'bg-red-600 dark:bg-red-500',
+            'info': 'bg-blue-600 dark:bg-blue-500',
+            'primary': 'bg-primary-600 dark:bg-primary-500',
+            'secondary': 'bg-gray-400 dark:bg-gray-500',
+        }
+
+        # Standard Tailwind text colors with dark mode
+        variant_text_map = {
+            'success': 'text-green-700 dark:text-green-300',
+            'warning': 'text-yellow-700 dark:text-yellow-300',
+            'danger': 'text-red-700 dark:text-red-300',
+            'info': 'text-blue-700 dark:text-blue-300',
+            'primary': 'text-primary-700 dark:text-primary-300',
+            'secondary': 'text-gray-600 dark:text-gray-400',
+        }
+
+        # Build segments HTML
+        segments_html = []
+        for seg in segments:
+            pct = seg['percentage']
+            variant = seg['variant']
+            bg_class = variant_bg_map.get(variant, 'bg-base-200 dark:bg-base-700')
+
+            if pct > 0:
+                segments_html.append(
+                    f'<div class="{bg_class}" style="width: {pct}%; height: 100%;"></div>'
+                )
+
+        # Build labels HTML
+        labels_html = ""
+        if show_labels:
+            label_parts = []
+            for seg in segments:
+                pct = seg['percentage']
+                variant = seg['variant']
+                label = seg['label']
+                text_class = variant_text_map.get(variant, 'text-base-600')
+
+                if pct > 0 or label:
+                    label_parts.append(
+                        f'<span class="{text_class}">{escape(label)}: {pct:.1f}%</span>'
+                    )
+
+            if label_parts:
+                labels_html = (
+                    f'<div class="flex justify-between mt-1 text-xs">'
+                    f'{"".join(label_parts)}'
+                    f'</div>'
+                )
+
+        # Rounded class
+        rounded_class = 'rounded-lg' if rounded else ''
+
+        # Combine
+        html = (
+            f'<div class="{width}">'
+            f'<div class="bg-base-100 dark:bg-base-800 {height} {rounded_class} overflow-hidden flex">'
+            f'{"".join(segments_html)}'
+            f'</div>'
+            f'{labels_html}'
+            f'</div>'
+        )
+
+        return mark_safe(html)