nextpy-framework 1.0.0__py3-none-any.whl

nextpy/components/head.py

@@ -0,0 +1,167 @@
+"""
+NextPy Head Component - SEO and meta tag management
+Similar to Next.js's next/head
+"""
+
+from typing import Any, Dict, List, Optional
+from markupsafe import Markup
+
+
+class Head:
+    """
+    Head component for managing document head elements
+    
+    Usage in templates:
+        {{ Head(title="My Page", description="Page description") }}
+    
+    Or in Python:
+        head = Head(title="My Page")
+        head.add_meta(name="author", content="John Doe")
+        print(head.render())
+    """
+    
+    def __init__(
+        self,
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        keywords: Optional[List[str]] = None,
+        canonical: Optional[str] = None,
+        og_title: Optional[str] = None,
+        og_description: Optional[str] = None,
+        og_image: Optional[str] = None,
+        og_type: str = "website",
+        twitter_card: str = "summary_large_image",
+        favicon: Optional[str] = None,
+        **kwargs: Any,
+    ):
+        self.title = title
+        self.description = description
+        self.keywords = keywords or []
+        self.canonical = canonical
+        self.og_title = og_title or title
+        self.og_description = og_description or description
+        self.og_image = og_image
+        self.og_type = og_type
+        self.twitter_card = twitter_card
+        self.favicon = favicon
+        self.extra_meta: List[Dict[str, str]] = []
+        self.extra_links: List[Dict[str, str]] = []
+        self.extra_scripts: List[Dict[str, str]] = []
+        self.extra_kwargs = kwargs
+        
+    def add_meta(self, **attrs: str) -> "Head":
+        """Add a custom meta tag"""
+        self.extra_meta.append(attrs)
+        return self
+        
+    def add_link(self, **attrs: str) -> "Head":
+        """Add a custom link tag"""
+        self.extra_links.append(attrs)
+        return self
+        
+    def add_script(self, src: Optional[str] = None, **attrs: str) -> "Head":
+        """Add a script tag"""
+        if src:
+            attrs["src"] = src
+        self.extra_scripts.append(attrs)
+        return self
+        
+    def render(self) -> str:
+        """Render the head elements as HTML"""
+        elements = []
+        
+        if self.title:
+            elements.append(f"<title>{self._escape(self.title)}</title>")
+            
+        elements.append('<meta charset="UTF-8">')
+        elements.append('<meta name="viewport" content="width=device-width, initial-scale=1.0">')
+        
+        if self.description:
+            elements.append(
+                f'<meta name="description" content="{self._escape(self.description)}">'
+            )
+            
+        if self.keywords:
+            keywords_str = ", ".join(self.keywords)
+            elements.append(f'<meta name="keywords" content="{self._escape(keywords_str)}">')
+            
+        if self.canonical:
+            elements.append(f'<link rel="canonical" href="{self._escape(self.canonical)}">')
+            
+        if self.og_title:
+            elements.append(f'<meta property="og:title" content="{self._escape(self.og_title)}">')
+        if self.og_description:
+            elements.append(
+                f'<meta property="og:description" content="{self._escape(self.og_description)}">'
+            )
+        if self.og_image:
+            elements.append(f'<meta property="og:image" content="{self._escape(self.og_image)}">')
+        if self.og_type:
+            elements.append(f'<meta property="og:type" content="{self._escape(self.og_type)}">')
+            
+        if self.twitter_card:
+            elements.append(f'<meta name="twitter:card" content="{self._escape(self.twitter_card)}">')
+        if self.og_title:
+            elements.append(
+                f'<meta name="twitter:title" content="{self._escape(self.og_title)}">'
+            )
+        if self.og_description:
+            elements.append(
+                f'<meta name="twitter:description" content="{self._escape(self.og_description)}">'
+            )
+        if self.og_image:
+            elements.append(
+                f'<meta name="twitter:image" content="{self._escape(self.og_image)}">'
+            )
+            
+        if self.favicon:
+            elements.append(f'<link rel="icon" href="{self._escape(self.favicon)}">')
+            
+        for meta in self.extra_meta:
+            attrs_str = " ".join(f'{k}="{self._escape(v)}"' for k, v in meta.items())
+            elements.append(f"<meta {attrs_str}>")
+            
+        for link in self.extra_links:
+            attrs_str = " ".join(f'{k}="{self._escape(v)}"' for k, v in link.items())
+            elements.append(f"<link {attrs_str}>")
+            
+        for script in self.extra_scripts:
+            attrs_str = " ".join(f'{k}="{self._escape(v)}"' for k, v in script.items())
+            if "src" in script:
+                elements.append(f"<script {attrs_str}></script>")
+            else:
+                content = script.pop("content", "")
+                elements.append(f"<script {attrs_str}>{content}</script>")
+                
+        return "\n    ".join(elements)
+        
+    def __html__(self) -> str:
+        """Make the component work with Jinja2's autoescape"""
+        return self.render()
+        
+    def __str__(self) -> str:
+        return self.render()
+        
+    def __call__(self, **kwargs: Any) -> Markup:
+        """Allow calling Head() in templates with additional args"""
+        for key, value in kwargs.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+        return Markup(self.render())
+        
+    @staticmethod
+    def _escape(value: str) -> str:
+        """Escape HTML special characters"""
+        return (
+            str(value)
+            .replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+            .replace("'", "&#x27;")
+        )
+
+
+def create_head(**kwargs: Any) -> Head:
+    """Factory function to create a Head component"""
+    return Head(**kwargs)

nextpy/components/hooks_provider.py

@@ -0,0 +1,64 @@
+"""
+Hooks Provider for SSR Integration
+Enables hooks to work seamlessly in server-side rendered pages
+"""
+
+from typing import Any, Dict, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class HooksContext:
+    """Context for hooks across requests"""
+    component_id: str
+    state_data: Dict[str, Any]
+    request_id: Optional[str] = None
+
+
+class HooksProvider:
+    """Global hooks provider for SSR"""
+    
+    _instance = None
+    _request_contexts: Dict[str, HooksContext] = {}
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    @classmethod
+    def create_context(cls, component_id: str, request_id: Optional[str] = None) -> HooksContext:
+        """Create new hooks context for a request"""
+        context = HooksContext(
+            component_id=component_id,
+            state_data={},
+            request_id=request_id
+        )
+        if request_id:
+            cls._request_contexts[request_id] = context
+        return context
+    
+    @classmethod
+    def get_context(cls, request_id: str) -> Optional[HooksContext]:
+        """Get hooks context for a request"""
+        return cls._request_contexts.get(request_id)
+    
+    @classmethod
+    def cleanup_request(cls, request_id: str):
+        """Clean up context after request"""
+        if request_id in cls._request_contexts:
+            del cls._request_contexts[request_id]
+
+
+def with_hooks(component_id: str):
+    """Decorator to enable hooks in page components"""
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            from nextpy.hooks import StateManager
+            StateManager.set_component(component_id)
+            try:
+                return func(*args, **kwargs)
+            finally:
+                StateManager.reset_hook_index()
+        return wrapper
+    return decorator

nextpy/components/image.py

@@ -0,0 +1,180 @@
+"""
+NextPy Image Component - Optimized image handling
+Similar to Next.js's next/image with automatic optimization
+"""
+
+from typing import Any, List, Optional, Tuple
+from pathlib import Path
+from markupsafe import Markup
+
+
+class Image:
+    """
+    Optimized Image component with automatic sizing and lazy loading
+    
+    Usage in templates:
+        {{ Image("/images/hero.jpg", alt="Hero image", width=800, height=600) }}
+    
+    Features:
+        - Automatic srcset generation for responsive images
+        - Lazy loading by default
+        - Placeholder blur support
+        - Size optimization hints
+    """
+    
+    DEFAULT_SIZES = [640, 750, 828, 1080, 1200, 1920, 2048, 3840]
+    DEFAULT_QUALITY = 75
+    
+    def __init__(
+        self,
+        src: str,
+        alt: str = "",
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        layout: str = "intrinsic",
+        priority: bool = False,
+        placeholder: str = "empty",
+        blur_data_url: Optional[str] = None,
+        quality: int = DEFAULT_QUALITY,
+        sizes: Optional[str] = None,
+        class_: Optional[str] = None,
+        style: Optional[str] = None,
+        **kwargs: Any,
+    ):
+        self.src = src
+        self.alt = alt
+        self.width = width
+        self.height = height
+        self.layout = layout
+        self.priority = priority
+        self.placeholder = placeholder
+        self.blur_data_url = blur_data_url
+        self.quality = quality
+        self.sizes = sizes
+        self.class_ = class_
+        self.style = style
+        self.extra_attrs = kwargs
+        
+    def render(self) -> str:
+        """Render the image as an optimized HTML img tag"""
+        attrs = []
+        
+        if self._is_external_url():
+            attrs.append(f'src="{self._escape(self.src)}"')
+        else:
+            attrs.append(f'src="{self._escape(self._get_optimized_url())}"')
+            srcset = self._generate_srcset()
+            if srcset:
+                attrs.append(f'srcset="{srcset}"')
+                
+        attrs.append(f'alt="{self._escape(self.alt)}"')
+        
+        if self.width:
+            attrs.append(f'width="{self.width}"')
+        if self.height:
+            attrs.append(f'height="{self.height}"')
+            
+        if self.sizes:
+            attrs.append(f'sizes="{self._escape(self.sizes)}"')
+        elif self.width:
+            attrs.append(f'sizes="(max-width: {self.width}px) 100vw, {self.width}px"')
+            
+        if not self.priority:
+            attrs.append('loading="lazy"')
+            attrs.append('decoding="async"')
+        else:
+            attrs.append('fetchpriority="high"')
+            
+        if self.placeholder == "blur" and self.blur_data_url:
+            attrs.append(f'style="background-image: url({self.blur_data_url}); background-size: cover;"')
+        elif self.style:
+            attrs.append(f'style="{self._escape(self.style)}"')
+            
+        if self.class_:
+            attrs.append(f'class="{self._escape(self.class_)}"')
+            
+        for key, value in self.extra_attrs.items():
+            attr_name = key.replace("_", "-")
+            if value is True:
+                attrs.append(attr_name)
+            elif value is not False and value is not None:
+                attrs.append(f'{attr_name}="{self._escape(str(value))}"')
+                
+        wrapper_style = self._get_wrapper_style()
+        img_tag = f"<img {' '.join(attrs)}>"
+        
+        if wrapper_style:
+            return f'<span style="{wrapper_style}">{img_tag}</span>'
+        return img_tag
+        
+    def _is_external_url(self) -> bool:
+        """Check if the src is an external URL"""
+        return self.src.startswith(("http://", "https://", "//"))
+        
+    def _get_optimized_url(self) -> str:
+        """Get the optimized image URL"""
+        return f"/_nextpy/image?url={self.src}&w={self.width or 0}&q={self.quality}"
+        
+    def _generate_srcset(self) -> str:
+        """Generate srcset for responsive images"""
+        if self._is_external_url():
+            return ""
+            
+        srcset_parts = []
+        max_width = self.width or 1920
+        
+        for size in self.DEFAULT_SIZES:
+            if size <= max_width * 2:
+                url = f"/_nextpy/image?url={self.src}&w={size}&q={self.quality}"
+                srcset_parts.append(f"{url} {size}w")
+                
+        return ", ".join(srcset_parts)
+        
+    def _get_wrapper_style(self) -> str:
+        """Get wrapper style based on layout mode"""
+        if self.layout == "fill":
+            return "display: block; overflow: hidden; position: absolute; inset: 0;"
+        elif self.layout == "responsive" and self.width and self.height:
+            aspect = (self.height / self.width) * 100
+            return f"display: block; overflow: hidden; position: relative; padding-bottom: {aspect:.2f}%;"
+        elif self.layout == "intrinsic" and self.width and self.height:
+            return f"display: inline-block; max-width: 100%; width: {self.width}px;"
+        return ""
+        
+    def __html__(self) -> str:
+        """Make the component work with Jinja2's autoescape"""
+        return self.render()
+        
+    def __str__(self) -> str:
+        return self.render()
+        
+    def __call__(self, **kwargs: Any) -> Markup:
+        """Allow calling Image() in templates with arguments"""
+        for key, value in kwargs.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+            else:
+                self.extra_attrs[key] = value
+        return Markup(self.render())
+        
+    @staticmethod
+    def _escape(value: str) -> str:
+        """Escape HTML special characters"""
+        return (
+            str(value)
+            .replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+            .replace("'", "&#x27;")
+        )
+
+
+def image(src: str, alt: str = "", **kwargs: Any) -> Markup:
+    """
+    Functional helper to create an Image
+    
+    Usage in templates:
+        {{ image("/hero.jpg", "Hero", width=800) }}
+    """
+    return Markup(Image(src, alt, **kwargs).render())

nextpy/components/layout.py

@@ -0,0 +1,206 @@
+"""
+Layout components for NextPy
+Provides grid, flex, container, and other layout utilities
+"""
+
+from typing import Optional, List, Dict, Any
+
+
+def Container(
+    children: str = "",
+    max_width: str = "max-w-6xl",
+    padding: str = "px-4 sm:px-6 lg:px-8",
+    **kwargs
+) -> str:
+    """Container component with responsive max-width"""
+    classes = f"mx-auto {max_width} {padding}"
+    return f'<div class="{classes}">{children}</div>'
+
+
+def Grid(
+    children: str = "",
+    columns: int = 3,
+    gap: str = "gap-6",
+    responsive: bool = True,
+    **kwargs
+) -> str:
+    """Grid layout component"""
+    if responsive:
+        cols = f"md:grid-cols-{columns}"
+        classes = f"grid {cols} {gap}"
+    else:
+        cols = f"grid-cols-{columns}"
+        classes = f"grid {cols} {gap}"
+    
+    return f'<div class="{classes}">{children}</div>'
+
+
+def Flex(
+    children: str = "",
+    direction: str = "row",
+    justify: str = "justify-start",
+    align: str = "items-start",
+    gap: str = "gap-4",
+    **kwargs
+) -> str:
+    """Flex layout component"""
+    flex_dir = "flex-col" if direction == "column" else "flex-row"
+    classes = f"flex {flex_dir} {justify} {align} {gap}"
+    return f'<div class="{classes}">{children}</div>'
+
+
+def Stack(
+    children: str = "",
+    direction: str = "vertical",
+    spacing: str = "space-y-4",
+    **kwargs
+) -> str:
+    """Stack component (vertical or horizontal)"""
+    if direction == "horizontal":
+        spacing = spacing.replace("space-y", "space-x")
+        classes = f"flex flex-row {spacing}"
+    else:
+        classes = f"flex flex-col {spacing}"
+    
+    return f'<div class="{classes}">{children}</div>'
+
+
+def Section(
+    children: str = "",
+    title: Optional[str] = None,
+    bg_color: str = "bg-white",
+    padding: str = "py-16",
+    **kwargs
+) -> str:
+    """Section component with optional title"""
+    html = f'<section class="{bg_color} {padding}"><div class="max-w-6xl mx-auto px-4">'
+    
+    if title:
+        html += f'<h2 class="text-3xl font-bold mb-8">{title}</h2>'
+    
+    html += children + '</div></section>'
+    return html
+
+
+def Row(
+    children: str = "",
+    gap: str = "gap-4",
+    **kwargs
+) -> str:
+    """Row component (horizontal flex)"""
+    return f'<div class="flex flex-row {gap}">{children}</div>'
+
+
+def Column(
+    children: str = "",
+    gap: str = "gap-4",
+    **kwargs
+) -> str:
+    """Column component (vertical flex)"""
+    return f'<div class="flex flex-col {gap}">{children}</div>'
+
+
+def AspectRatio(
+    children: str = "",
+    ratio: str = "16/9",
+    **kwargs
+) -> str:
+    """AspectRatio component"""
+    ratio_class = {
+        "1/1": "aspect-square",
+        "4/3": "aspect-video",
+        "16/9": "aspect-video",
+        "3/2": "aspect-video",
+    }.get(ratio, "aspect-video")
+    
+    return f'<div class="{ratio_class} overflow-hidden">{children}</div>'
+
+
+def Spacer(height: str = "h-4", **kwargs) -> str:
+    """Spacer component for vertical spacing"""
+    return f'<div class="{height}"></div>'
+
+
+def Divider(
+    color: str = "border-gray-200",
+    **kwargs
+) -> str:
+    """Divider/separator component"""
+    return f'<hr class="border {color}">'
+
+
+def Center(
+    children: str = "",
+    **kwargs
+) -> str:
+    """Center component"""
+    return f'<div class="flex items-center justify-center">{children}</div>'
+
+
+def Sidebar(
+    children: str = "",
+    sidebar_content: str = "",
+    sidebar_width: str = "w-64",
+    **kwargs
+) -> str:
+    """Sidebar layout component"""
+    return f'''
+    <div class="flex gap-6">
+        <aside class="{sidebar_width} flex-shrink-0">
+            {sidebar_content}
+        </aside>
+        <main class="flex-1">
+            {children}
+        </main>
+    </div>
+    '''
+
+
+def TwoColumn(
+    left: str = "",
+    right: str = "",
+    gap: str = "gap-8",
+    **kwargs
+) -> str:
+    """Two-column layout"""
+    return f'''
+    <div class="grid grid-cols-2 {gap}">
+        <div>{left}</div>
+        <div>{right}</div>
+    </div>
+    '''
+
+
+def ThreeColumn(
+    left: str = "",
+    center: str = "",
+    right: str = "",
+    gap: str = "gap-6",
+    **kwargs
+) -> str:
+    """Three-column layout"""
+    return f'''
+    <div class="grid grid-cols-3 {gap}">
+        <div>{left}</div>
+        <div>{center}</div>
+        <div>{right}</div>
+    </div>
+    '''
+
+
+__all__ = [
+    'Container',
+    'Grid',
+    'Flex',
+    'Stack',
+    'Section',
+    'Row',
+    'Column',
+    'AspectRatio',
+    'Spacer',
+    'Divider',
+    'Center',
+    'Sidebar',
+    'TwoColumn',
+    'ThreeColumn',
+]