django-cfg 1.4.48__py3-none-any.whl → 1.5.7__py3-none-any.whl

django_cfg/modules/django_admin/utils/html_builder.py

@@ -1,205 +1,66 @@
 """
-Universal HTML builder for Django Admin display methods.
-"""
+HtmlBuilder - Facade class for backward compatibility.
 
-from typing import Any, List, Optional, Union
+This class provides the old `self.html.*` API by delegating to new modular components.
+All existing admin code using `self.html.badge()`, `self.html.inline()`, etc. will continue to work.
 
-from django.utils.html import escape, format_html
-from django.utils.safestring import SafeString
+New code should import and use the specific modules directly:
+    from django_cfg.modules.django_admin.utils import BaseElements, FormattingElements, etc.
+"""
 
-from ..icons import Icons
+from .html import (
+    BadgeElements,
+    BaseElements,
+    CodeElements,
+    CompositionElements,
+    FormattingElements,
+    KeyValueElements,
+    MarkdownIntegration,
+    ProgressElements,
+)
 
 
 class HtmlBuilder:
     """
-    Universal HTML builder with Material Icons support.
+    Facade class that delegates to modular HTML utilities.
 
-    Usage in admin methods:
-        def stats(self, obj):
-            return self.html.inline([
-                self.html.icon_text(Icons.EDIT, obj.posts_count),
-                self.html.icon_text(Icons.CHAT, obj.comments_count),
-            ])
+    Provides backward compatibility for `self.html.*` API in admin classes.
     """
 
-    @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 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 = HtmlBuilder.icon(icon_str, size=icon_size)
-
-        return format_html('{}{}<span>{}</span>', icon_html, separator, escape(str(text)))
-
-    @staticmethod
-    def inline(items: List[Any], separator: str = " | ",
-               size: str = "small", css_class: str = "") -> SafeString:
-        """
-        Render items inline with separator.
-
-        Args:
-            items: List of SafeString/str items to join
-            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),
-            ])
-        """
-        if not 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}"
-
-        # Join items with separator
-        joined = format_html(separator.join(['{}'] * len(items)), *items)
-
-        return format_html('<span class="{}">{}</span>', classes, joined)
-
-    @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 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 badge(text: Any, variant: str = "primary", icon: Optional[str] = None) -> SafeString:
-        """
-        Render badge with optional icon.
-
-        Args:
-            text: Badge text
-            variant: primary, success, warning, danger, info, secondary
-            icon: Optional Material Icon
-
-        Usage:
-            html.badge("Active", variant="success", icon=Icons.CHECK_CIRCLE)
-        """
-        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',
-        }
-
-        css_classes = variant_classes.get(variant, variant_classes['primary'])
-
-        icon_html = ""
-        if icon:
-            icon_html = format_html('<span class="material-symbols-outlined text-xs mr-1">{}</span>', icon)
-
-        return format_html(
-            '<span class="inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium {}">{}{}</span>',
-            css_classes, icon_html, escape(str(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)
-        )
+    # === BaseElements ===
+    icon = staticmethod(BaseElements.icon)
+    span = staticmethod(BaseElements.span)
+    text = staticmethod(BaseElements.text)
+    div = staticmethod(BaseElements.div)
+    link = staticmethod(BaseElements.link)
+    empty = staticmethod(BaseElements.empty)
+
+    # === CodeElements ===
+    code = staticmethod(CodeElements.code)
+    code_block = staticmethod(CodeElements.code_block)
+
+    # === BadgeElements ===
+    badge = staticmethod(BadgeElements.badge)
+
+    # === CompositionElements ===
+    inline = staticmethod(CompositionElements.inline)
+    icon_text = staticmethod(CompositionElements.icon_text)
+    header = staticmethod(CompositionElements.header)
+
+    # === FormattingElements ===
+    number = staticmethod(FormattingElements.number)
+    uuid_short = staticmethod(FormattingElements.uuid_short)
+
+    # === KeyValueElements ===
+    key_value = staticmethod(KeyValueElements.key_value)
+    breakdown = staticmethod(KeyValueElements.breakdown)
+    divider = staticmethod(KeyValueElements.divider)
+    key_value_list = staticmethod(KeyValueElements.key_value_list)
+
+    # === ProgressElements ===
+    segment = staticmethod(ProgressElements.segment)
+    progress_bar = staticmethod(ProgressElements.progress_bar)
+
+    # === MarkdownIntegration ===
+    markdown = staticmethod(MarkdownIntegration.markdown)
+    markdown_docs = staticmethod(MarkdownIntegration.markdown_docs)

django_cfg/modules/django_admin/utils/markdown/__init__.py

@@ -0,0 +1,21 @@
+"""
+Markdown rendering utilities for Django Admin.
+
+Provides MarkdownRenderer and mermaid plugin support.
+"""
+
+from .mermaid_plugin import (
+    get_mermaid_resources,
+    get_mermaid_script,
+    get_mermaid_styles,
+    mermaid_plugin,
+)
+from .renderer import MarkdownRenderer
+
+__all__ = [
+    "MarkdownRenderer",
+    "mermaid_plugin",
+    "get_mermaid_styles",
+    "get_mermaid_script",
+    "get_mermaid_resources",
+]

django_cfg/modules/django_admin/utils/markdown/mermaid_plugin.py

@@ -0,0 +1,288 @@
+"""
+Mermaid diagram plugin for Mistune markdown parser.
+
+Renders ```mermaid code blocks as interactive diagrams using Mermaid.js.
+"""
+
+import re
+from typing import Any, Dict
+
+
+def mermaid_plugin(md):
+    """
+    Mistune plugin to render Mermaid diagrams.
+
+    Detects code fences with 'mermaid' language and renders them as
+    Mermaid diagram containers that will be processed by Mermaid.js.
+
+    Usage:
+        ```mermaid
+        graph TD
+            A[Start] --> B{Decision}
+            B -->|Yes| C[OK]
+            B -->|No| D[Cancel]
+        ```
+
+    Args:
+        md: Mistune markdown instance
+    """
+
+    def render_mermaid(text: str, **attrs: Any) -> str:
+        """
+        Render Mermaid diagram HTML.
+
+        Args:
+            text: Mermaid diagram code
+            **attrs: Additional attributes
+
+        Returns:
+            HTML with Mermaid container
+        """
+        # Generate unique ID for this diagram
+        import hashlib
+        diagram_id = f"mermaid-{hashlib.md5(text.encode()).hexdigest()[:8]}"
+
+        # Escape HTML special characters but preserve Mermaid syntax
+        escaped_text = text.strip()
+
+        # Return HTML container with Mermaid code
+        return f'''<div class="mermaid-container">
+    <div class="mermaid-wrapper">
+        <pre class="mermaid" id="{diagram_id}">
+{escaped_text}
+        </pre>
+    </div>
+</div>'''
+
+    # Override code block renderer for mermaid language
+    original_code = md.renderer.block_code
+
+    def patched_code(code: str, info: str = None, **attrs: Any) -> str:
+        """
+        Patched code block renderer that checks for mermaid language.
+
+        Args:
+            code: Code content
+            info: Language info
+            **attrs: Additional attributes
+
+        Returns:
+            Rendered code block (either Mermaid or normal code)
+        """
+        if info and info.strip().lower() == 'mermaid':
+            return render_mermaid(code, **attrs)
+        return original_code(code, info, **attrs)
+
+    md.renderer.block_code = patched_code
+
+    return md
+
+
+def get_mermaid_styles() -> str:
+    """
+    Get CSS styles for Mermaid diagrams with Unfold semantic colors.
+
+    Returns:
+        CSS string for Mermaid container styling
+    """
+    return """
+<style>
+    /* Mermaid container styles with Unfold semantic colors */
+    .mermaid-container {
+        margin: 1.5rem 0;
+        padding: 0;
+    }
+
+    .mermaid-wrapper {
+        border: 1px solid rgb(var(--color-base-200));
+        border-radius: 0.5rem;
+        padding: 1.5rem;
+        background: rgb(var(--color-base-50));
+        overflow-x: auto;
+    }
+
+    /* Dark mode styles with semantic colors */
+    .dark .mermaid-wrapper {
+        border-color: rgb(var(--color-base-700));
+        background: rgb(var(--color-base-900));
+    }
+
+    /* Mermaid diagram */
+    .mermaid {
+        display: flex;
+        justify-content: center;
+        background: transparent !important;
+        border: none !important;
+        padding: 0 !important;
+        margin: 0 !important;
+        font-family: inherit !important;
+    }
+
+    /* Ensure diagrams are centered */
+    .mermaid svg {
+        max-width: 100%;
+        height: auto;
+    }
+
+    /* Loading state with semantic colors */
+    .mermaid[data-processed="false"] {
+        color: rgb(var(--color-base-400));
+        text-align: center;
+        padding: 2rem;
+    }
+
+    .dark .mermaid[data-processed="false"] {
+        color: rgb(var(--color-base-500));
+    }
+
+    /* Error state with semantic colors */
+    .mermaid.error {
+        color: rgb(239, 68, 68);
+        border: 1px solid rgb(252, 165, 165);
+        background: rgb(254, 242, 242);
+        padding: 1rem;
+        border-radius: 0.375rem;
+    }
+
+    .dark .mermaid.error {
+        color: rgb(248, 113, 113);
+        border-color: rgb(153, 27, 27);
+        background: rgb(127, 29, 29);
+    }
+</style>
+"""
+
+
+def get_mermaid_script(theme: str = "default") -> str:
+    """
+    Get Mermaid.js initialization script with Unfold semantic colors.
+
+    Args:
+        theme: Mermaid theme ('default', 'dark', 'forest', 'neutral')
+
+    Returns:
+        HTML script tag with Mermaid.js and initialization
+    """
+    return f"""
+<script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+
+    // Helper to get CSS variable value
+    function getCSSVar(name) {{
+        const value = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+        // Convert "R, G, B" format to "#RRGGBB"
+        if (value.includes(',')) {{
+            const [r, g, b] = value.split(',').map(x => parseInt(x.trim()));
+            return '#' + [r, g, b].map(x => x.toString(16).padStart(2, '0')).join('');
+        }}
+        return value;
+    }}
+
+    // Auto-detect dark mode
+    const isDarkMode = document.documentElement.classList.contains('dark') ||
+                       window.matchMedia('(prefers-color-scheme: dark)').matches;
+
+    // Get Unfold semantic colors
+    function getThemeColors() {{
+        if (isDarkMode) {{
+            return {{
+                primaryColor: '#3b82f6',
+                primaryTextColor: getCSSVar('--color-base-100'),
+                primaryBorderColor: getCSSVar('--color-base-700'),
+                lineColor: getCSSVar('--color-base-600'),
+                secondaryColor: getCSSVar('--color-base-800'),
+                tertiaryColor: getCSSVar('--color-base-700'),
+                background: getCSSVar('--color-base-900'),
+                mainBkg: getCSSVar('--color-base-800'),
+                secondBkg: getCSSVar('--color-base-700'),
+                border1: getCSSVar('--color-base-700'),
+                border2: getCSSVar('--color-base-600'),
+                note: getCSSVar('--color-base-800'),
+                noteText: getCSSVar('--color-base-200'),
+                noteBorder: getCSSVar('--color-base-600'),
+                text: getCSSVar('--color-base-200'),
+                critical: '#ef4444',
+                done: '#10b981',
+                active: '#3b82f6',
+            }};
+        }} else {{
+            return {{
+                primaryColor: '#2563eb',
+                primaryTextColor: getCSSVar('--color-base-900'),
+                primaryBorderColor: getCSSVar('--color-base-300'),
+                lineColor: getCSSVar('--color-base-400'),
+                secondaryColor: getCSSVar('--color-base-100'),
+                tertiaryColor: '#ffffff',
+                background: '#ffffff',
+                mainBkg: getCSSVar('--color-base-50'),
+                secondBkg: '#ffffff',
+                border1: getCSSVar('--color-base-300'),
+                border2: getCSSVar('--color-base-200'),
+                note: '#fef3c7',
+                noteText: getCSSVar('--color-base-900'),
+                noteBorder: '#fbbf24',
+                text: getCSSVar('--color-base-900'),
+                critical: '#dc2626',
+                done: '#059669',
+                active: '#2563eb',
+            }};
+        }}
+    }}
+
+    // Initialize Mermaid with Unfold semantic colors
+    mermaid.initialize({{
+        startOnLoad: true,
+        theme: 'base',
+        securityLevel: 'loose',
+        fontFamily: 'ui-sans-serif, system-ui, sans-serif',
+        themeVariables: getThemeColors()
+    }});
+
+    // Listen for dark mode changes and re-render
+    const observer = new MutationObserver((mutations) => {{
+        mutations.forEach((mutation) => {{
+            if (mutation.attributeName === 'class') {{
+                // Re-initialize with new theme colors
+                mermaid.initialize({{
+                    startOnLoad: true,
+                    theme: 'base',
+                    securityLevel: 'loose',
+                    fontFamily: 'ui-sans-serif, system-ui, sans-serif',
+                    themeVariables: getThemeColors()
+                }});
+                // Re-render all diagrams
+                mermaid.run({{
+                    querySelector: '.mermaid',
+                }});
+            }}
+        }});
+    }});
+
+    observer.observe(document.documentElement, {{
+        attributes: true,
+        attributeFilter: ['class'],
+    }});
+
+    // Error handling
+    window.addEventListener('error', (event) => {{
+        if (event.message && event.message.includes('mermaid')) {{
+            console.error('Mermaid error:', event);
+            const mermaidElements = document.querySelectorAll('.mermaid[data-processed="false"]');
+            mermaidElements.forEach(el => {{
+                el.classList.add('error');
+                el.textContent = 'Error rendering diagram. Check console for details.';
+            }});
+        }}
+    }});
+</script>
+"""
+
+
+def get_mermaid_resources() -> str:
+    """
+    Get complete Mermaid resources (styles + script).
+
+    Returns:
+        HTML string with styles and script for Mermaid support
+    """
+    return get_mermaid_styles() + get_mermaid_script()