dars-framework 1.2.3__py3-none-any.whl

dars/exporters/web/vdom.py

@@ -0,0 +1,251 @@
+"""
+VDOM utilities for Dars HTML exporter.
+
+This module defines a minimal, modular Virtual DOM representation and a builder
+that converts Dars Components (built-in or user-defined) to a serializable
+VNode tree. It is intentionally patch-agnostic; it only focuses on building
+an accurate snapshot that future patch systems can consume.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+# We only use loose imports to avoid heavy coupling
+try:
+    from dars.core.component import Component
+except Exception:  # pragma: no cover - defensive import
+    Component = Any  # type: ignore
+
+
+class VNode:
+    """A minimal serializable Virtual Node for Dars components."""
+
+    def __init__(
+        self,
+        type_name: str,
+        id: Optional[str],
+        key: Optional[str],
+        class_name: Optional[str],
+        style: Dict[str, Any],
+        props: Dict[str, Any],
+        events: Optional[Dict[str, Any]],
+        children: Optional[List["VNode"]] = None,
+        text: Optional[str] = None,
+        is_island: bool = False,
+    ) -> None:
+        self.type = type_name
+        self.id = id
+        self.key = key
+        self.class_name = class_name
+        self.style = style or {}
+        self.props = props or {}
+        self.events = events or None
+        self.children = children or []
+        self.text = text
+        self.isIsland = is_island
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "type": self.type,
+            "id": self.id,
+            "key": self.key,
+            "class": self.class_name,
+            "style": self.style or {},
+            "props": self.props or {},
+            "events": self.events or None,
+            "children": [c.to_dict() for c in (self.children or [])],
+        }
+        if self.text is not None:
+            d["text"] = self.text
+        # Siempre incluimos isIsland para que el runtime pueda tomar decisiones
+        d["isIsland"] = bool(self.isIsland)
+        return d
+
+
+class VDomBuilder:
+    """Builds a VNode tree from a Dars Component tree.
+
+    Notes:
+    - Works with built-in and user-defined components alike.
+    - For user components that render HTML via `render(exporter)`, we still
+      build a structural node capturing props/events. The future patch system
+      may treat these as opaque islands unless more granular hooks are added.
+    """
+
+    def __init__(self, id_provider: Optional[Callable[[Component, str], str]] = None) -> None:
+        # id_provider(component, prefix) -> id string
+        self.id_provider = id_provider
+
+    def build(self, component: Component) -> Dict[str, Any]:
+        vnode = self._build_vnode(component, path=["0"])  # raíz con path estable
+        return vnode.to_dict()
+
+    # --- internals ---
+    def _safe_props(self, component: Component) -> Dict[str, Any]:
+        """Extract props + public attributes into a single serializable mapping.
+
+        Rules:
+        - Start with component.props (if present), but filter out framework-managed fields
+          like id, class_name, style, children, events to avoid duplication.
+        - Augment with other public attributes from the component instance (e.g.,
+          Markdown.dark_theme, Markdown.file_path, CustomComponent.title), skipping
+          callables, private names (prefixed with '_'), Component instances and lists of Components.
+        - Only include values that are JSON-serializable; otherwise, stringify as fallback.
+        """
+        import json
+
+        result: Dict[str, Any] = {}
+        EXCLUDE_KEYS = {
+            'id', 'class_name', 'style', 'children', 'events', 'scripts', 'key',
+            'props',  # avoid nesting component.props inside props
+            'rendered_html',  # avoid transporting heavy derived HTML payloads
+        }
+
+        # 1) Base props from component.props
+        try:
+            base_props = getattr(component, 'props', {}) or {}
+            for k, v in base_props.items():
+                if k in EXCLUDE_KEYS:
+                    continue
+                if callable(v):
+                    continue
+                try:
+                    json.dumps(v)
+                    result[k] = v
+                except Exception:
+                    result[k] = str(v)
+        except Exception:
+            pass
+
+        # 2) Additional public attributes from the instance
+        try:
+            for k, v in vars(component).items():
+                if k in EXCLUDE_KEYS:
+                    continue
+                if k in result:
+                    continue
+                if k.startswith('_'):
+                    continue
+                # Skip methods/callables
+                if callable(v):
+                    continue
+                # Skip Component instances or lists/tuples of Components
+                try:
+                    if isinstance(v, Component):
+                        continue
+                    if isinstance(v, (list, tuple)) and any(isinstance(it, Component) for it in v):
+                        continue
+                except Exception:
+                    pass
+
+                try:
+                    json.dumps(v)
+                    result[k] = v
+                except Exception:
+                    result[k] = str(v)
+        except Exception:
+            pass
+
+        return result
+
+    def _serialize_events(self, component: Component) -> Optional[Dict[str, Any]]:
+        events_payload: Dict[str, Any] = {}
+        try:
+            events = getattr(component, 'events', {}) or {}
+            for ev_name, handler in events.items():
+                code = None
+                try:
+                    if hasattr(handler, 'get_code'):
+                        code = handler.get_code()
+                    elif isinstance(handler, dict):
+                        code = handler.get('code') or handler.get('value')
+                    elif isinstance(handler, str):
+                        code = handler
+                    else:
+                        # fallback best-effort
+                        code = str(handler)
+                except Exception:
+                    code = None
+                if code:
+                    events_payload[ev_name] = {"type": "inline", "code": code}
+        except Exception:
+            pass
+        return events_payload or None
+
+    def _text_value(self, component: Component) -> Optional[str]:
+        # Try extracting a textual value if the component has a primary text prop
+        try:
+            for cand in ('text', 'content', 'value', 'label'):
+                if hasattr(component, cand):
+                    v = getattr(component, cand)
+                    if isinstance(v, (str, int, float)):
+                        return str(v)
+        except Exception:
+            pass
+        return None
+
+    def _build_vnode(self, component: Component, path: list) -> VNode:
+        try:
+            comp_type = component.__class__.__name__
+        except Exception:
+            comp_type = 'Component'
+
+        # Prefer an injected id provider to keep IDs consistent with the HTML output
+        comp_id = getattr(component, 'id', None)
+        if self.id_provider is not None:
+            try:
+                # Choose a sensible prefix based on type name (lowercase)
+                prefix = (component.__class__.__name__ or 'comp').lower()
+                comp_id = self.id_provider(component, prefix=prefix)
+            except Exception:
+                # fallback to existing id attribute (may be None)
+                comp_id = getattr(component, 'id', None)
+
+        # Props
+        safe_props = self._safe_props(component)
+
+        # Events
+        events_payload = self._serialize_events(component)
+
+        # Children
+        children_nodes: List[VNode] = []
+        try:
+            for idx, child in enumerate(getattr(component, 'children', []) or []):
+                if child is None:
+                    continue
+                child_path = path + [str(idx)]
+                children_nodes.append(self._build_vnode(child, child_path))
+        except Exception:
+            children_nodes = []
+
+        # Text (optional)
+        text_value = self._text_value(component)
+
+        # Heurística para saber si es componente "isla" (custom)
+        is_island = False
+        try:
+            mod = getattr(component.__class__, '__module__', '') or ''
+            # Si no pertenece al paquete de componentes built-in, lo tratamos como isla
+            if not mod.startswith('dars.components.'):
+                is_island = True
+        except Exception:
+            is_island = False
+
+        # Clave estable: si no hay id ni key definidos, usamos el path del árbol
+        stable_key = getattr(component, 'key', None)
+        if not stable_key and not comp_id:
+            stable_key = "/".join(path)
+
+        vnode = VNode(
+            type_name=comp_type,
+            id=comp_id,
+            key=stable_key,
+            class_name=getattr(component, 'class_name', None),
+            style=getattr(component, 'style', {}) or {},
+            props=safe_props,
+            events=events_payload,
+            children=children_nodes,
+            text=text_value,
+            is_island=is_island,
+        )
+        return vnode

dars/js_lib.py

@@ -0,0 +1,206 @@
+# Embedded dars.min.js content (ESM + global)
+DARS_MIN_JS = """/* Dars minimal runtime: state + DOM updates (ESM + global) */
+const __registry = new Map();
+
+function $(id){ return document.getElementById(id) || document.querySelector(`[data-id="${id}"]`) || null; }
+
+function registerState(name, cfg){
+  if(!name || !cfg || !cfg.id) return;
+  const entry = {
+    id: cfg.id,
+    states: Array.isArray(cfg.states) ? cfg.states.slice() : [],
+    current: 0,
+    isCustom: !!cfg.isCustom,
+    rules: (cfg.rules && typeof cfg.rules === 'object') ? cfg.rules : {},
+    defaultIndex: (typeof cfg.defaultIndex === 'number') ? cfg.defaultIndex : 0,
+    defaultValue: (cfg.hasOwnProperty('defaultValue') ? cfg.defaultValue : null),
+    __defaultSnapshot: null
+  };
+  __registry.set(name, entry);
+  try{
+    const el = $(entry.id);
+    if(el){
+      const attrs = {};
+      try{
+        for(const a of el.getAttributeNames()) attrs[a] = el.getAttribute(a);
+      }catch(_){ }
+      entry.__defaultSnapshot = { attrs, html: String(el.innerHTML||'') };
+    }
+  }catch(_){ }
+}
+
+function getState(name){ return __registry.get(name); }
+
+function _restoreDefault(id, snap){
+  try{
+    const el = $(id);
+    if(!el || !snap) return;
+    // Remove any dynamic event listeners we attached previously
+    try{
+      if(el.__darsEv){
+        for(const t in el.__darsEv){
+          const fn = el.__darsEv[t];
+          try{ el.removeEventListener(t, fn, true); }catch(_){ }
+          try{ el.removeEventListener(t, fn, false); }catch(_){ }
+        }
+        el.__darsEv = {};
+      }
+    }catch(_){ }
+    try{
+      const current = el.getAttributeNames ? el.getAttributeNames() : [];
+      for(const n of current){ if(n !== 'id') el.removeAttribute(n); }
+      for(const k in snap.attrs){ if(k !== 'id') el.setAttribute(k, snap.attrs[k]); }
+    }catch(_){ }
+    try{ el.innerHTML = snap.html || ''; }catch(_){ }
+  }catch(_){ }
+}
+
+function _applyMods(defaultId, mods){
+  if(!Array.isArray(mods) || !mods.length) return;
+  for(const m of mods){
+    try{
+      const op = m && m.op;
+      if(!op) continue;
+      const tid = (m && m.target) ? m.target : defaultId;
+      const el = $(tid);
+      if(!el) continue;
+      if(op === 'inc' || op === 'dec'){
+        const prop = m.prop || 'text';
+        const by = Number(m.by || (op==='dec'?-1:1));
+        if(prop === 'text'){
+          const cur = parseFloat(el.textContent||'0') || 0;
+          el.textContent = String(cur + by);
+        } else {
+          const cur = parseFloat(el.getAttribute(prop)||'0') || 0;
+          el.setAttribute(prop, String(cur + by));
+        }
+      } else if(op === 'set'){
+        const attrs = m.attrs || {};
+        for(const k in attrs){
+          try{
+            if(k === 'text') { el.textContent = String(attrs[k]); continue; }
+            if(k === 'html') { el.innerHTML = String(attrs[k]); continue; }
+            if(k.startsWith('on_')){
+              const type = k.slice(3);
+              const v = attrs[k];
+              const codes = [];
+              const pushCode = (item)=>{
+                if(typeof item === 'string') codes.push(item);
+                else if(item && typeof item.code === 'string') codes.push(item.code);
+              };
+              if(Array.isArray(v)) v.forEach(pushCode);
+              else pushCode(v);
+              if(codes.length){
+                el.__darsEv = el.__darsEv || {};
+                if(el.__darsEv[type]){
+                  try{ el.removeEventListener(type, el.__darsEv[type], true); }catch(_){ }
+                  try{ el.removeEventListener(type, el.__darsEv[type], false); }catch(_){ }
+                }
+                const handler = function(ev){
+                  try{ ev.stopImmediatePropagation(); }catch(_){ }
+                  try{ ev.stopPropagation(); }catch(_){ }
+                  try{ ev.preventDefault(); }catch(_){ }
+                  try{ ev.cancelBubble = true; }catch(_){ }
+                  let propName = 'on'+type;
+                  let prevOn = null;
+                  try{ prevOn = el[propName]; el[propName] = null; }catch(_){ }
+                  try{ for(const c of codes){ try{ (0,eval)(c); }catch(_){ } } }finally{
+                    try{ setTimeout(()=>{ try{ el[propName] = prevOn; }catch(_){ } }, 0); }catch(_){ }
+                  }
+                };
+                try{ el.addEventListener(type, handler, { capture: true }); }catch(_){ }
+                el.__darsEv[type] = handler;
+                continue;
+              }
+            }
+            el.setAttribute(k, String(attrs[k]));
+          }catch(_){ }
+        }
+      } else if(op === 'toggleClass'){
+        const name = m.name || '';
+        const on = m.hasOwnProperty('on') ? !!m.on : null;
+        if(!name) continue;
+        if(on === null){ el.classList.toggle(name); }
+        else if(on){ el.classList.add(name); }
+        else { el.classList.remove(name); }
+      } else if(op === 'appendText'){
+        el.textContent = String(el.textContent||'') + String(m.value||'');
+      } else if(op === 'prependText'){
+        el.textContent = String(m.value||'') + String(el.textContent||'');
+      } else if(op === 'call'){
+        try{
+          const payload = {};
+          if (m.name) payload.name = String(m.name);
+          if (m.id) payload.id = String(m.id);
+          if (m.hasOwnProperty('state')) payload.state = m.state;
+          if (m.hasOwnProperty('goto')) payload.goto = m.goto;
+          if (!payload.name && !payload.id && defaultId) payload.id = String(defaultId);
+          setTimeout(()=>{ try{ change(payload); }catch(_){ } }, 0);
+        }catch(_){ }
+      }
+    }catch(_){ }
+  }
+}
+
+function _resolveGoto(cur, goto, statesLen){
+  if(goto == null) return cur;
+  if(typeof goto === 'number') return goto;
+  if(typeof goto === 'string'){
+    if(/^[-+]\d+$/.test(goto)){
+      const delta = parseInt(goto, 10);
+      const next = cur + delta;
+      if(statesLen && statesLen > 0){ return Math.max(0, Math.min(statesLen-1, next)); }
+      return next;
+    }
+    const n = parseInt(goto, 10);
+    if(!isNaN(n)) return n;
+  }
+  return cur;
+}
+
+function change(opt){
+  if(!opt||!opt.id) return;
+  if(opt.useCustomRender && typeof opt.html === 'string'){
+    const el = $(opt.id);
+    if(!el) return;
+    el.innerHTML = opt.html;
+    if(typeof window.DarsHydrate === 'function'){ try{ window.DarsHydrate(el); }catch(e){} }
+    return;
+  }
+
+  const name = opt.name || null;
+  const st = name ? __registry.get(name) : null;
+  let targetState = (typeof opt.state === 'number') ? opt.state : null;
+  let goto = (opt.hasOwnProperty('goto') ? opt.goto : null);
+  if(st){
+    const cur = st.current || 0;
+    const len = Array.isArray(st.states) ? st.states.length : 0;
+    if(goto !== null){ targetState = _resolveGoto(cur, goto, len); }
+    if(targetState === null){ targetState = cur; }
+    st.current = targetState;
+    const rules = st.rules && st.rules[String(targetState)];
+    if(targetState === 0){
+      _restoreDefault(st.id, st.__defaultSnapshot);
+      if(rules){ try{ console.error('[Dars] Default state (index 0) is immutable. Rules for state 0 are ignored.'); }catch(_){ } }
+    } else if(rules){
+      if(Array.isArray(rules.mods)){ _applyMods(st.id, rules.mods); }
+      if(rules.hasOwnProperty('goto')){
+        const nxt = _resolveGoto(st.current, rules.goto, len);
+        if(nxt !== st.current){ st.current = nxt; }
+      }
+    }
+  }
+
+  try{
+    const el = $(opt.id);
+    if(!el) return;
+    const ev = new CustomEvent('dars:state', { detail: { id: opt.id, state: targetState } });
+    el.dispatchEvent(ev);
+  }catch(e){ }
+}
+
+const Dars = { registerState, getState, change, $ };
+try { window.Dars = window.Dars || Dars; } catch(_) {}
+export { registerState, getState, change, $ };
+export default Dars;
+"""

dars/scripts/dscript.py

@@ -0,0 +1,26 @@
+from typing import Optional
+from .script import Script
+
+class dScript(Script):
+    """
+    Script that can be defined as inline (JS code in string) or as a reference to an external file.
+    Only one of the two must be present.
+    """
+    def __init__(self, code: Optional[str] = None, file_path: Optional[str] = None, target_language: str = "javascript", module: bool = False):
+        super().__init__(target_language, module=module)
+        if (code is None and file_path is None) or (code is not None and file_path is not None):
+            raise ValueError("You have to specify only one: 'code' (inline) or 'file_path' (external), but not both.")
+        self.code = code
+        self.file_path = file_path
+
+    def get_code(self) -> str:
+        if self.code is not None:
+            return self.code
+        elif self.file_path is not None:
+            try:
+                with open(self.file_path, 'r') as f:
+                    return f.read()
+            except FileNotFoundError:
+                raise FileNotFoundError(f"The script file was not found: {self.file_path}")
+        else:
+            raise ValueError("No code or file path defined for this dScript.")

dars/scripts/script.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+class Script(ABC):
+    """Base class for script definitions"""
+    def __init__(self, target_language: str = "javascript", module: bool = False):
+        if target_language not in ["javascript", "typescript"]:
+            raise ValueError("The target language must be 'javascript' or 'typescript'")
+        self.target_language = target_language
+        self.module = module
+        
+    @abstractmethod
+    def get_code(self) -> str:
+        """Returns the script code in the target language"""
+        pass
+
+class InlineScript(Script):
+    """Script defined directly in Python code"""
+    def __init__(self, code: str, target_language: str = "javascript", module: bool = False):
+        super().__init__(target_language, module=module)
+        self.code = code
+        
+    def get_code(self) -> str:
+        return self.code
+        
+class FileScript(Script):
+    """Script loaded from an external file"""
+    def __init__(self, file_path: str, target_language: str = "javascript", module: bool = False):
+        super().__init__(target_language, module=module)
+        self.file_path = file_path
+        
+    def get_code(self) -> str:
+        try:
+            with open(self.file_path, 'r') as f:
+                return f.read()
+        except FileNotFoundError:
+            raise FileNotFoundError(f"The script file was not found: {self.file_path}")
+
+