caspian-utils 0.0.12__py3-none-any.whl

casp/component_decorator.py

@@ -0,0 +1,183 @@
+from .layout import env, load_template_file
+from .html_attrs import get_attributes
+from typing import Callable, TypeVar, Dict, Optional, Any
+from markupsafe import Markup
+import inspect
+import os
+import importlib
+import importlib.util
+
+R = TypeVar('R')
+
+_component_registry: Dict[str, 'Component'] = {}
+
+
+class Component:
+    """Wrapper class for PulsePoint components"""
+    _is_pp_component: bool = True
+    source_path: Optional[str] = None
+
+    def __init__(self, fn: Callable[..., str], source_path: Optional[str] = None):
+        self.fn = fn
+        self.source_path = source_path
+        self.__name__ = fn.__name__
+        self.__doc__ = fn.__doc__
+        self.__signature__ = inspect.signature(fn)
+        _component_registry[fn.__name__] = self
+
+    def __call__(self, *args, **kwargs) -> str:
+        # Standardize React-like props to Pythonic names
+        if "className" in kwargs:
+            kwargs["class_name"] = kwargs.pop("className")
+        if "htmlFor" in kwargs:
+            kwargs["html_for"] = kwargs.pop("htmlFor")
+        return self.fn(*args, **kwargs)
+
+
+def component(fn: Callable[..., str]) -> Component:
+    """Decorator to mark and register a PulsePoint component"""
+    return Component(fn)
+
+
+def load_component_from_path(path: str, component_name: str, base_dir: str = "") -> Component | None:
+    if path == '.' or path == './':
+        full_path = os.path.join(
+            base_dir, f"{component_name}.py") if base_dir else f"{component_name}.py"
+    elif path.startswith('./') or path.startswith('../'):
+        full_path = os.path.normpath(os.path.join(
+            base_dir, path)) if base_dir else os.path.normpath(path)
+    else:
+        full_path = path
+
+    if full_path.endswith('.py'):
+        file_path = full_path
+    elif os.path.isdir(full_path):
+        file_path = os.path.join(full_path, f"{component_name}.py")
+    else:
+        file_path = f"{full_path}.py" if not os.path.isdir(
+            full_path) else os.path.join(full_path, f"{component_name}.py")
+
+    if not os.path.exists(file_path):
+        return None
+
+    try:
+        cwd = os.getcwd()
+        abs_file_path = os.path.abspath(file_path)
+        if abs_file_path.startswith(cwd):
+            rel_path = os.path.relpath(abs_file_path, cwd)
+            if not rel_path.startswith('..'):
+                module_name = os.path.splitext(
+                    rel_path)[0].replace(os.sep, '.')
+                module = importlib.import_module(module_name)
+                comp = getattr(module, component_name, None)
+                if isinstance(comp, Component):
+                    comp.source_path = abs_file_path
+                    return comp
+    except (ImportError, ValueError, AttributeError):
+        pass
+
+    try:
+        unique_module_name = f"pp_component_{os.path.abspath(file_path).replace(os.sep, '_').replace('.', '_')}"
+        spec = importlib.util.spec_from_file_location(
+            unique_module_name, file_path)
+        if spec is None or spec.loader is None:
+            return None
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        comp = getattr(module, component_name, None)
+        if isinstance(comp, Component):
+            comp.source_path = file_path
+            return comp
+    except Exception as e:
+        print(
+            f"Error loading component {component_name} from {file_path}: {e}")
+        return None
+
+    return None
+
+
+# ====
+# TEMPLATE RENDERING (Jinja2 powered)
+# ====
+
+def render_html(file_path: str, **kwargs) -> str:
+    """
+    Load HTML template and render with Jinja2.
+
+    Behaves like React:
+    - [[ props ]] spreads attributes (class="...", id="...")
+    - [[ children ]] inserts the content (safe HTML)
+    - Supports passing __file__ to auto-discover sibling .html
+    """
+    # Resolve file path relative to caller
+    frame = inspect.currentframe()
+    if frame and frame.f_back:
+        caller_file = frame.f_back.f_globals.get('__file__', '')
+        if caller_file:
+            base_dir = os.path.dirname(caller_file)
+            full_path = os.path.join(base_dir, file_path)
+        else:
+            full_path = file_path
+    else:
+        full_path = file_path
+
+    if full_path.endswith('.py'):
+        full_path = full_path[:-3] + '.html'
+
+    content = load_template_file(full_path)
+
+    # 1. EXTRACT CHILDREN
+    # We remove 'children' from props so it doesn't get rendered as an attribute.
+    children_content = kwargs.pop("children", "")
+
+    # 2. MARK CHILDREN AS SAFE
+    # If children is None or empty, use empty string. Otherwise mark as safe HTML.
+    safe_children = Markup(children_content) if children_content else ""
+
+    # 3. GENERATE ATTRIBUTES
+    # Pass the remaining kwargs to get_attributes.
+    # Mark the result as Markup so Jinja doesn't escape the quotes (class="foo").
+    props_string = Markup(get_attributes(kwargs))
+
+    # 4. RENDER
+    # We pass 'children' explicitly as the safe Markup object.
+    # We pass 'props' explicitly as the safe attribute string.
+    template = env.from_string(content)
+    return template.render(props=props_string, children=safe_children, **kwargs)
+
+
+def render_component(py_file: str, template_name: str, context: Optional[Dict[str, Any]] = None) -> str:
+    """
+    Render component template with context.
+    """
+    context = context or {}
+    dir_path = os.path.dirname(os.path.abspath(py_file))
+    html_path = os.path.join(dir_path, template_name)
+
+    content = load_template_file(html_path)
+
+    # 1. Separate props from children
+    attrs = context.copy()
+    children_content = attrs.pop("children", "")
+
+    # 2. Mark safe
+    props_string = Markup(get_attributes(attrs))
+    safe_children = Markup(children_content) if children_content else ""
+
+    # 3. Render
+    template = env.from_string(content)
+    return template.render(props=props_string, children=safe_children, **context)
+
+
+# ====
+# EXPORTS
+# ====
+
+__all__ = [
+    'Component',
+    'component',
+    'load_component_from_path',
+    'render_html',
+    'render_component',
+    '_component_registry',
+]

casp/components_compiler.py

@@ -0,0 +1,293 @@
+from .string_helpers import camel_to_kebab
+from .string_helpers import kebab_to_camel
+from .string_helpers import has_mustache
+import re
+import uuid
+import inspect
+from typing import Dict, List, Optional
+from .component_decorator import Component, load_component_from_path
+import os
+
+
+def convert_mustache_attrs_to_kebab_raw(html):
+    def replace_attr(match):
+        attr_name = match.group(1)
+        equals_quote = match.group(2)
+        value = match.group(3)
+        end_quote = match.group(4)
+
+        if has_mustache(value):
+            new_name = camel_to_kebab(attr_name)
+            return f'{new_name}{equals_quote}{value}{end_quote}'
+        return match.group(0)
+
+    pattern = r'([a-zA-Z_][a-zA-Z0-9_]*)(=["\'])([^"\']*?)(["\'])'
+    return re.sub(pattern, replace_attr, html)
+
+
+def extract_component_original_attrs(html, pattern):
+    component_attrs_map = {}
+
+    for match in re.finditer(pattern, html):
+        component_name = match.group(1)
+        tag_start = match.start()
+
+        remaining = html[tag_start:]
+        tag_end_match = re.search(r'/?>', remaining)
+        if tag_end_match:
+            full_tag = remaining[:tag_end_match.end()]
+
+            attr_pattern = re.compile(
+                r'([a-zA-Z_][\w\-]*)\s*=\s*(?:"[^"]*"|\'[^\']*\'|[^\s>]+)')
+            attrs_original = {}
+            for attr_match in attr_pattern.finditer(full_tag):
+                attr_name = attr_match.group(1)
+                attrs_original[attr_name.lower()] = attr_name
+
+            placeholder = f"ppcomponent{component_name.lower()}"
+            if placeholder not in component_attrs_map:
+                component_attrs_map[placeholder] = []
+            component_attrs_map[placeholder].append(attrs_original)
+
+    return component_attrs_map
+
+# ============================================================================
+# IMPORT PARSING
+# ============================================================================
+
+
+def extract_imports(html: str) -> List[Dict]:
+    """
+    Extract all import statements from HTML.
+
+    Supports:
+        <!-- @import Test from "./path" -->
+        <!-- @import Test from ./path -->  (unquoted)
+        <!-- @import Test as MyTest from "./path" -->
+        <!-- @import { Button, Input } from "./path" -->
+        <!-- @import { Button as Btn, Input as Field } from "./path" -->
+    """
+    imports = []
+
+    # Grouped imports: @import { A, B as C } from "path" or from path
+    grouped_pattern = r'<!--\s*@import\s*\{([^}]+)\}\s*from\s*["\']?([^"\'>\s]+)["\']?\s*-->'
+    for match in re.finditer(grouped_pattern, html):
+        members = match.group(1)
+        path = match.group(2)
+
+        for member in members.split(','):
+            member = member.strip()
+            if not member:
+                continue
+            if ' as ' in member:
+                parts = member.split(' as ')
+                original = parts[0].strip()
+                alias = parts[1].strip()
+            else:
+                original = member
+                alias = member
+            imports.append({
+                'original': original,
+                'alias': alias,
+                'path': path
+            })
+
+    # Single imports: @import Name from "path" OR @import Name as Alias from "path" (quotes optional)
+    single_pattern = r'<!--\s*@import\s+(?!\{)(\w+)(?:\s+as\s+(\w+))?\s+from\s*["\']?([^"\'>\s]+)["\']?\s*-->'
+    for match in re.finditer(single_pattern, html):
+        original = match.group(1)
+        alias = match.group(2) or original
+        path = match.group(3)
+        imports.append({
+            'original': original,
+            'alias': alias,
+            'path': path
+        })
+
+    return imports
+
+
+def strip_imports(html: str) -> str:
+    """Remove import comments from HTML"""
+    # Remove grouped imports (quoted or unquoted)
+    html = re.sub(
+        r'<!--\s*@import\s*\{[^}]+\}\s*from\s*["\']?[^"\'>\s]+["\']?\s*-->\n?', '', html)
+    # Remove single imports (quoted or unquoted)
+    html = re.sub(
+        r'<!--\s*@import\s+\w+(?:\s+as\s+\w+)?\s+from\s*["\']?[^"\'>\s]+["\']?\s*-->\n?', '', html)
+    return html
+
+
+def build_alias_map(imports: List[Dict], base_dir: str = "") -> Dict[str, Component]:
+    """Build mapping from alias names to Component instances."""
+    alias_map = {}
+
+    for imp in imports:
+        original = imp['original']
+        alias = imp['alias']
+        path = imp['path']
+
+        component = load_component_from_path(path, original, base_dir)
+        if component:
+            alias_map[alias] = component
+
+    return alias_map
+
+
+def process_imports(html: str, base_dir: str = "") -> tuple[str, Dict[str, Component]]:
+    """Process imports and return cleaned HTML with alias map."""
+    imports = extract_imports(html)
+    alias_map = build_alias_map(imports, base_dir)
+    cleaned_html = strip_imports(html)
+    return cleaned_html, alias_map
+
+
+# ============================================================================
+# COMPONENT HELPERS
+# ============================================================================
+
+def needs_parent_scope(attrs):
+    for key, value in attrs.items():
+        if key.lower().startswith('on'):
+            return True
+        if has_mustache(value):
+            return True
+    return False
+
+
+def wrap_scope(html, scope):
+    return f'<!-- pp-scope:{scope} -->{html}<!-- /pp-scope -->'
+
+
+def accepts_children(fn):
+    sig = fn.__signature__ if isinstance(
+        fn, Component) else inspect.signature(fn)
+    params = sig.parameters
+    return 'children' in params or any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values())
+
+
+# ============================================================================
+# MAIN TRANSFORM
+# ============================================================================
+
+def transform_components(
+    html: str,
+    parent_scope: str = "app",
+    base_dir: str = "",
+    alias_map: Optional[Dict[str, Component]] = None,
+    _depth: int = 0
+) -> str:
+    """
+    Transform custom component tags. Components MUST be imported to be resolved.
+    Recursively processes the output of components to handle nested imports/components.
+    """
+    if _depth > 50:
+        return html
+
+    # 1. Process imports for the current level
+    html, local_alias_map = process_imports(html, base_dir)
+
+    if alias_map:
+        merged_map = {**alias_map, **local_alias_map}
+    else:
+        merged_map = local_alias_map
+
+    # If no components are imported, we might still have standard HTML to return,
+    # but we can't transform custom tags without a map.
+    if not merged_map:
+        return html
+
+    # 2. Convert mustache attributes (e.g. someProp="{val}") to kebab-case (some-prop="{val}")
+    html = convert_mustache_attrs_to_kebab_raw(html)
+
+    # 3. Process components iteratively
+    max_iterations = 100
+    iteration = 0
+
+    while iteration < max_iterations:
+        iteration += 1
+
+        # Find a component tag (prefer innermost by finding one without nested components)
+        # This regex looks for <CapitalizedTag ... /> or <CapitalizedTag ...>...</CapitalizedTag>
+        component_pattern = r'<([A-Z][a-zA-Z0-9]*)([^>]*?)(?:/>|>([\s\S]*?)</\1>)'
+
+        match = None
+        for m in re.finditer(component_pattern, html):
+            tag_name = m.group(1)
+            # Only process if we have an import for this tag
+            if tag_name in merged_map:
+                inner_content = m.group(3) or ""
+                # Check if this has nested components - if so, skip for now (inner-first strategy)
+                if not re.search(r'<[A-Z][a-zA-Z0-9]*[^>]*(?:/>|>)', inner_content):
+                    match = m
+                    break
+                elif match is None:
+                    match = m  # Fallback to first match if all have nested components
+
+        if not match:
+            break
+
+        tag_name = match.group(1)
+        attrs_str = match.group(2) or ""
+        children = match.group(3) or ""
+
+        component_fn = merged_map.get(tag_name)
+        if not component_fn:
+            # Should not happen due to the check in the loop, but safety first
+            break
+
+        # 4. Parse attributes
+        props = {}
+        attr_pattern = r'([a-zA-Z_][\w\-]*)\s*=\s*(?:"([^"]*)"|\'([^\']*)\'|(\S+))'
+        for attr_match in re.finditer(attr_pattern, attrs_str):
+            attr_name = attr_match.group(1)
+            attr_value = attr_match.group(2) or attr_match.group(
+                3) or attr_match.group(4) or ""
+            camel_name = kebab_to_camel(attr_name)
+            props[camel_name] = attr_value
+
+        # Handle boolean attributes (no value)
+        bool_attr_pattern = r'\s([a-zA-Z_][\w\-]*)(?=\s|/?>|$)(?!=)'
+        for bool_match in re.finditer(bool_attr_pattern, attrs_str):
+            attr_name = bool_match.group(1)
+            if attr_name not in props:
+                props[kebab_to_camel(attr_name)] = ""
+
+        unique_id = f"{tag_name.lower()}_{uuid.uuid4().hex[:8]}"
+
+        # 5. Add children if component accepts them
+        if children.strip() and accepts_children(component_fn):
+            props['children'] = wrap_scope(children, parent_scope)
+
+        # 6. Render the component (get the raw string output)
+        component_html = component_fn(**props)
+
+        # 7. RECURSIVE TRANSFORM [CRITICAL FIX]
+        # We must process the returned HTML to resolve imports and components
+        # inside the child component (e.g., EditTodo -> Button).
+        if hasattr(component_fn, 'source_path') and component_fn.source_path:
+            component_dir = os.path.dirname(component_fn.source_path)
+            component_html = transform_components(
+                component_html,
+                parent_scope=parent_scope,  # Or a new scope if you want isolation
+                base_dir=component_dir,     # Use the component's directory for relative imports
+                _depth=_depth + 1
+            )
+
+        # 8. Add pp-component attribute to root element of the result
+        # (This marks it for PulsePoint reactivity in the DOM)
+        component_html = re.sub(
+            r'^(\s*<[a-zA-Z][a-zA-Z0-9]*)',
+            rf'\1 pp-component="{unique_id}"',
+            component_html.strip(),
+            count=1
+        )
+
+        # 9. Wrap in scope if needed (for events/state binding)
+        if needs_parent_scope(props):
+            component_html = wrap_scope(component_html, parent_scope)
+
+        # 10. Replace the original tag in the HTML with the transformed result
+        html = html[:match.start()] + component_html + html[match.end():]
+
+    return html

casp/html_attrs.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+from .string_helpers import camel_to_kebab
+from typing import Any, Dict, Optional
+import html
+from tailwind_merge import TailwindMerge
+
+_twm = TailwindMerge()
+
+# Map Python-safe names to HTML attributes
+ALIAS_MAP = {
+    "class_name": "class",
+    "className": "class",
+    "html_for": "for",
+    "htmlFor": "for"
+}
+
+
+def merge_classes(*classes: Any) -> str:
+    parts: list[str] = []
+    for c in classes:
+        if not c:
+            continue
+        if isinstance(c, (list, tuple, set)):
+            s = " ".join(str(x) for x in c if x)
+        else:
+            s = str(c).strip()
+        if s:
+            parts.append(s)
+    return _twm.merge(*parts) if parts else ""
+
+
+def _to_attr_value(v: Any) -> Optional[str]:
+    # XML-strict: booleans should have explicit values
+    if v is None:
+        return None
+    if isinstance(v, bool):
+        return "true" if v else None  # omit false
+    if isinstance(v, (list, tuple, set)):
+        s = " ".join(str(x) for x in v if x)
+        return s if s else None
+    s = str(v)
+    return s if s != "" else None
+
+
+def get_attributes(props: Dict[str, Any], overrides: Optional[Dict[str, Any]] = None) -> str:
+    """
+    Build ONE attribute string.
+    - Aliases (class_name -> class) are always resolved.
+    - If the VALUE contains mustache syntax (e.g. "{var}"), the KEY is converted to kebab-case.
+    - Otherwise, the KEY maintains its original casing.
+    - Overrides take priority over props.
+    """
+
+    final_attrs: Dict[str, str] = {}
+
+    def process_dict(d: Dict[str, Any]):
+        if not d:
+            return
+        for k, v in d.items():
+            if not k:
+                continue
+
+            # 1. Check Alias Map first (e.g., class_name -> class)
+            key_name = ALIAS_MAP.get(k, k)
+
+            # 2. Process value to string
+            val = _to_attr_value(v)
+
+            if val is not None:
+                # 3. Check for mustache syntax to decide on casing
+                # If value is a binding (has { and }), force kebab-case on the key
+                if "{" in val and "}" in val:
+                    final_key = camel_to_kebab(key_name)
+                else:
+                    # Otherwise, keep original casing (e.g. standard attributes)
+                    final_key = key_name
+
+                final_attrs[final_key] = val
+
+    # 1. Process base props
+    process_dict(props)
+
+    # 2. Process overrides (these will overwrite keys from step 1)
+    if overrides:
+        process_dict(overrides)
+
+    # 3. Build string
+    parts: list[str] = []
+    # Sorting keys is optional but helpful for consistent testing/output
+    for k, v in final_attrs.items():
+        parts.append(f'{k}="{html.escape(v, quote=True)}"')
+
+    return " ".join(parts)