quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/ui_validator.py

@@ -0,0 +1,365 @@
+"""
+UI Engine - Cross-Target Validator
+
+Analyzes UI AST to detect features that may not translate well between
+different targets (HTML, Textual). Returns compatibility reports and warnings.
+
+Usage:
+    from quantum.runtime.ui_validator import UIValidator
+
+    validator = UIValidator()
+    report = validator.validate(app.ui_windows, app.ui_children)
+
+    print(f"Compatibility Score: {report.compatibility_score}%")
+    for warning in report.warnings:
+        print(f"  - {warning}")
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Set, Dict, Optional
+from enum import Enum
+
+from quantum.core.ast_nodes import QuantumNode
+from quantum.core.features.ui_engine.src.ast_nodes import (
+    UIWindowNode, UIHBoxNode, UIVBoxNode, UIPanelNode,
+    UITabPanelNode, UITabNode, UIGridNode, UIAccordionNode,
+    UISectionNode, UIDividedBoxNode, UIFormNode, UIFormItemNode,
+    UISpacerNode, UIScrollBoxNode,
+    UITextNode, UIButtonNode, UIInputNode, UICheckboxNode,
+    UIRadioNode, UISwitchNode, UISelectNode, UITableNode,
+    UIColumnNode, UIListNode, UIItemNode, UIImageNode,
+    UILinkNode, UIProgressNode, UITreeNode, UIMenuNode,
+    UIOptionNode, UILogNode, UIMarkdownNode, UIHeaderNode,
+    UIFooterNode, UIRuleNode, UILoadingNode, UIBadgeNode,
+)
+
+
+class Severity(Enum):
+    """Warning severity levels."""
+    INFO = "info"        # FYI, no impact
+    WARNING = "warning"  # Works differently
+    ERROR = "error"      # Does not work
+
+
+@dataclass
+class CompatibilityIssue:
+    """Single compatibility issue."""
+    feature: str
+    message: str
+    severity: Severity
+    target: str  # Which target is affected
+    node_type: str
+    suggestion: Optional[str] = None
+
+
+@dataclass
+class ValidationReport:
+    """Complete validation report."""
+    issues: List[CompatibilityIssue] = field(default_factory=list)
+    features_used: Set[str] = field(default_factory=set)
+    widgets_count: int = 0
+    containers_count: int = 0
+
+    @property
+    def compatibility_score(self) -> int:
+        """Calculate compatibility score (0-100) based on issues."""
+        if not self.issues:
+            return 100
+
+        # Weight by severity
+        error_count = sum(1 for i in self.issues if i.severity == Severity.ERROR)
+        warning_count = sum(1 for i in self.issues if i.severity == Severity.WARNING)
+        info_count = sum(1 for i in self.issues if i.severity == Severity.INFO)
+
+        # Calculate penalty
+        total_elements = max(1, self.widgets_count + self.containers_count)
+        penalty = (error_count * 20 + warning_count * 5 + info_count * 1)
+        score = max(0, 100 - penalty)
+
+        return score
+
+    @property
+    def html_compatible(self) -> bool:
+        """Check if fully HTML compatible."""
+        return not any(i.target == 'html' and i.severity == Severity.ERROR
+                      for i in self.issues)
+
+    @property
+    def textual_compatible(self) -> bool:
+        """Check if fully Textual compatible."""
+        return not any(i.target == 'textual' and i.severity == Severity.ERROR
+                      for i in self.issues)
+
+    @property
+    def warnings(self) -> List[str]:
+        """Get formatted warning messages."""
+        return [f"[{i.severity.value}] {i.feature}: {i.message}"
+                for i in self.issues]
+
+
+# Feature compatibility matrix
+FEATURE_COMPAT = {
+    # Feature: (html_support, textual_support, message, suggestion)
+    'image': (True, 'degraded',
+              "Images display as placeholder text in terminal",
+              "Consider using ASCII art or omit images for TUI target"),
+
+    'link_external': (True, 'degraded',
+                      "External links are not clickable in terminal",
+                      "Link URL is shown as text instead"),
+
+    'gap': (True, False,
+            "CSS gap property is not supported in Textual",
+            "Layout may differ; children won't have automatic spacing"),
+
+    'justify_between': (True, False,
+                        "justify-content: space-between not available in Textual",
+                        "Items will be centered instead"),
+
+    'justify_around': (True, False,
+                       "justify-content: space-around not available in Textual",
+                       "Items will be centered instead"),
+
+    'font_size': (True, False,
+                  "Font sizes cannot be changed in terminal",
+                  "Use text weight (bold) for emphasis instead"),
+
+    'pixel_units': (True, 'converted',
+                    "Pixel values are converted to character cells (÷8)",
+                    "Results may vary; prefer tokens like 'sm', 'md', 'lg'"),
+
+    'animation': (True, False,
+                  "CSS animations are not supported in terminal",
+                  None),
+
+    'gradient': (True, False,
+                 "CSS gradients are not supported in terminal",
+                 "Use solid colors instead"),
+
+    'shadow': (True, False,
+               "Box shadows are not supported in terminal",
+               None),
+
+    'border_radius': (True, False,
+                      "Border radius is not supported in terminal",
+                      "Borders will appear rectangular"),
+}
+
+
+class UIValidator:
+    """Validates UI AST for cross-target compatibility."""
+
+    def __init__(self):
+        self._report: ValidationReport = None
+        self._target: str = 'all'  # 'html', 'textual', or 'all'
+
+    def validate(self, windows: List[QuantumNode],
+                 ui_children: List[QuantumNode],
+                 target: str = 'all') -> ValidationReport:
+        """
+        Validate UI AST for target compatibility.
+
+        Args:
+            windows: List of UIWindowNode
+            ui_children: List of top-level UI nodes
+            target: 'html', 'textual', or 'all' (check both)
+
+        Returns:
+            ValidationReport with issues and compatibility score
+        """
+        self._report = ValidationReport()
+        self._target = target
+
+        # Walk all windows
+        for window in windows:
+            self._validate_node(window)
+
+        # Walk top-level children
+        for child in ui_children:
+            self._validate_node(child)
+
+        return self._report
+
+    def _validate_node(self, node: QuantumNode):
+        """Recursively validate a node and its children."""
+        if node is None:
+            return
+
+        # Classify node
+        if self._is_container(node):
+            self._report.containers_count += 1
+            self._validate_container(node)
+        elif self._is_widget(node):
+            self._report.widgets_count += 1
+            self._validate_widget(node)
+
+        # Validate layout attributes common to all nodes
+        self._validate_layout_attrs(node)
+
+        # Recurse into children
+        if hasattr(node, 'children') and node.children:
+            for child in node.children:
+                self._validate_node(child)
+
+    def _is_container(self, node) -> bool:
+        """Check if node is a container type."""
+        return isinstance(node, (
+            UIWindowNode, UIHBoxNode, UIVBoxNode, UIPanelNode,
+            UITabPanelNode, UITabNode, UIGridNode, UIAccordionNode,
+            UISectionNode, UIDividedBoxNode, UIFormNode, UIFormItemNode,
+            UIScrollBoxNode, UIListNode, UIItemNode, UIMenuNode,
+        ))
+
+    def _is_widget(self, node) -> bool:
+        """Check if node is a widget type."""
+        return isinstance(node, (
+            UITextNode, UIButtonNode, UIInputNode, UICheckboxNode,
+            UIRadioNode, UISwitchNode, UISelectNode, UITableNode,
+            UIProgressNode, UITreeNode, UILogNode, UIMarkdownNode,
+            UIHeaderNode, UIFooterNode, UIRuleNode, UILoadingNode,
+            UIImageNode, UILinkNode, UIBadgeNode, UISpacerNode,
+            UIColumnNode, UIOptionNode,
+        ))
+
+    def _validate_container(self, node):
+        """Validate container-specific features."""
+        pass  # Containers generally work well across targets
+
+    def _validate_widget(self, node):
+        """Validate widget-specific features."""
+        # Image - limited in terminal
+        if isinstance(node, UIImageNode):
+            self._add_feature_issue('image', type(node).__name__)
+
+        # External link - not clickable in terminal
+        if isinstance(node, UILinkNode):
+            if node.external:
+                self._add_feature_issue('link_external', type(node).__name__)
+
+        # Markdown - supported in both but rendering differs
+        if isinstance(node, UIMarkdownNode):
+            self._report.features_used.add('markdown')
+
+    def _validate_layout_attrs(self, node):
+        """Validate layout attributes for compatibility."""
+        node_type = type(node).__name__
+
+        # Gap
+        if hasattr(node, 'gap') and node.gap:
+            self._add_feature_issue('gap', node_type)
+
+        # Justify
+        if hasattr(node, 'justify') and node.justify:
+            if node.justify == 'between':
+                self._add_feature_issue('justify_between', node_type)
+            elif node.justify == 'around':
+                self._add_feature_issue('justify_around', node_type)
+
+        # Pixel values
+        if hasattr(node, 'width') and node.width:
+            if self._is_pixel_value(node.width):
+                self._add_feature_issue('pixel_units', node_type)
+
+        if hasattr(node, 'height') and node.height:
+            if self._is_pixel_value(node.height):
+                self._add_feature_issue('pixel_units', node_type)
+
+        if hasattr(node, 'padding') and node.padding:
+            if self._is_pixel_value(node.padding):
+                self._add_feature_issue('pixel_units', node_type)
+
+        if hasattr(node, 'margin') and node.margin:
+            if self._is_pixel_value(node.margin):
+                self._add_feature_issue('pixel_units', node_type)
+
+        # Font size
+        if hasattr(node, 'size') and node.size:
+            # For text nodes
+            self._add_feature_issue('font_size', node_type)
+
+    def _is_pixel_value(self, value: str) -> bool:
+        """Check if value is a raw pixel value (not a token)."""
+        if not value:
+            return False
+        value = str(value).strip().lower()
+        # Check if it's a number or ends with 'px'
+        if value.endswith('px'):
+            return True
+        try:
+            int(value)
+            return True
+        except ValueError:
+            return False
+
+    def _add_feature_issue(self, feature: str, node_type: str):
+        """Add a feature compatibility issue to the report."""
+        if feature in self._report.features_used:
+            return  # Already reported
+
+        self._report.features_used.add(feature)
+
+        if feature not in FEATURE_COMPAT:
+            return
+
+        html_support, textual_support, message, suggestion = FEATURE_COMPAT[feature]
+
+        # Determine severity for Textual target
+        if textual_support is False:
+            severity = Severity.WARNING
+        elif textual_support == 'degraded':
+            severity = Severity.INFO
+        elif textual_support == 'converted':
+            severity = Severity.INFO
+        else:
+            return  # Fully supported
+
+        # Only add if checking this target
+        if self._target in ('all', 'textual'):
+            self._report.issues.append(CompatibilityIssue(
+                feature=feature,
+                message=message,
+                severity=severity,
+                target='textual',
+                node_type=node_type,
+                suggestion=suggestion,
+            ))
+
+
+def validate_cross_target(windows: List[QuantumNode],
+                          ui_children: List[QuantumNode]) -> ValidationReport:
+    """
+    Convenience function to validate UI for cross-target compatibility.
+
+    Args:
+        windows: List of UIWindowNode
+        ui_children: List of top-level UI nodes
+
+    Returns:
+        ValidationReport with compatibility score and issues
+    """
+    validator = UIValidator()
+    return validator.validate(windows, ui_children)
+
+
+def print_validation_report(report: ValidationReport):
+    """Print a formatted validation report."""
+    print(f"\n{'='*60}")
+    print(f"UI Cross-Target Compatibility Report")
+    print(f"{'='*60}")
+    print(f"Containers: {report.containers_count}")
+    print(f"Widgets: {report.widgets_count}")
+    print(f"Compatibility Score: {report.compatibility_score}%")
+    print(f"HTML Compatible: {'Yes' if report.html_compatible else 'No'}")
+    print(f"Textual Compatible: {'Yes' if report.textual_compatible else 'No'}")
+
+    if report.issues:
+        print(f"\nIssues ({len(report.issues)}):")
+        for issue in report.issues:
+            icon = {'info': 'ℹ', 'warning': '⚠', 'error': '✖'}.get(issue.severity.value, '•')
+            print(f"  {icon} [{issue.target}] {issue.feature}: {issue.message}")
+            if issue.suggestion:
+                print(f"    └─ Suggestion: {issue.suggestion}")
+    else:
+        print("\nNo compatibility issues found!")
+
+    print(f"{'='*60}\n")

quantum/runtime/ui_view.py

@@ -0,0 +1,221 @@
+"""The view of a page as data, for renderers that are not a browser (UI-3).
+
+The web server executes a page as always, and — when asked with
+`Accept: application/vnd.quantum.view+json` — answers with this tree instead
+of HTML. The console renderer (quantum/runtime/ui_console.py) draws it and
+sends the same q:action posts a browser would. One runtime, two renderers:
+nothing about the page's logic is translated.
+
+A view node is a dict:
+
+    {"type": "hbox", "props": {...}, "children": [...]}
+    {"type": "button", "props": {"text": "Salvar"},
+     "event": {"action": "salvar", "fields": {"id": "3"}}}
+    {"type": "text", "props": {"text": "..."}}        # also plain text/HTML
+"""
+
+import copy
+from typing import Any, Dict, List
+
+from quantum.core.ast_nodes import CommentNode, HTMLNode, TextNode
+from quantum.core.features.conditionals.src.ast_node import IfNode
+from quantum.core.features.loops.src.ast_node import LoopNode
+from quantum.core.features.ui_engine.src.ast_nodes import (
+    UIColumnNode, UIFormNode, UIListNode, UIPagerNode, UITableNode, UIWindowNode, is_ui_node)
+from quantum.runtime.ui_pager import pager_items
+from quantum.runtime.ui_table_edit import cell_field, edit_plan, sort_link
+from quantum.runtime.ui_form_rules import FIELDS, form_context, generated_fields, prepare_field
+from quantum.runtime.ui_page_renderer import cell_value, source_rows
+
+# Fields that are structure or events, not props.
+_NAO_PROPS = {'children', 'on_click', 'on_submit', 'on_change', 'on_select', 'send', 'source', 'as_var', 'values',
+              'edit', 'edit_datasource', 'sort',
+              # DEV-2: where the element is in the .q — never sent to a client
+              'source_line', 'source_file'}
+
+
+def _tipo(node) -> str:
+    nome = type(node).__name__
+    return nome[2:-4].lower() if nome.startswith('UI') and nome.endswith('Node') else nome.lower()
+
+
+def page_title(ast, renderer) -> str:
+    """UI-4: a page's title, the same for every renderer — the first ui:window's
+    `title` (bindings resolved), else the component's name."""
+    for node in getattr(ast, 'statements', []):
+        if isinstance(node, UIWindowNode) and node.title:
+            titulo = renderer._apply_databinding(node.title)
+            if titulo not in (None, ''):
+                return str(titulo)
+    return getattr(ast, 'name', '') or ''
+
+
+class UIViewBuilder:
+    """Walks a page's nodes with the page renderer's evaluation (loops, ifs, bindings)."""
+
+    def __init__(self, renderer):
+        self.r = renderer
+
+    def build(self, nodes) -> List[Dict[str, Any]]:
+        vista: List[Dict[str, Any]] = []
+        for node in nodes:
+            vista.extend(self._node(node))
+        return vista
+
+    def _texto(self, valor: str) -> str:
+        resolvido = self.r._apply_databinding(valor)
+        return '' if resolvido is None else str(resolvido)
+
+    def _campos(self, envio) -> Dict[str, str]:
+        campos = {}
+        if envio:
+            for par in self._texto(envio).split(','):
+                if '=' in par:
+                    campo, valor = (p.strip() for p in par.split('=', 1))
+                    campos[campo] = valor
+        return campos
+
+    def _node(self, node) -> List[Dict[str, Any]]:
+        if is_ui_node(node):
+            return [self._ui(node)]
+        if isinstance(node, LoopNode):
+            return self._loop(node)
+        if isinstance(node, IfNode):
+            return self.build(self._ramo(node))
+        if isinstance(node, TextNode):
+            texto = self._texto(node.content).strip()
+            return [{'type': 'text', 'props': {'text': texto}}] if texto else []
+        if isinstance(node, HTMLNode):
+            # HTML inside a UI page: its text, in order (a terminal draws no tags).
+            filhos = self.build(node.children or [])
+            return filhos
+        if isinstance(node, CommentNode):
+            return []
+        return []
+
+    def _ui(self, node) -> Dict[str, Any]:
+        if isinstance(node, UIPagerNode):
+            # UI-11: the same items the browser gets, as links the console follows.
+            filhos = []
+            for item in pager_items(self.r, node):
+                if item['href']:
+                    filhos.append({'type': 'link', 'props': {'to': item['href'], 'text': item['label']},
+                                   'children': []})
+                else:
+                    texto = f"[{item['label']}]" if item['current'] else item['label']
+                    filhos.append({'type': 'text', 'props': {'text': texto}, 'children': []})
+            return {'type': 'hbox', 'props': {'ui_id': getattr(node, 'ui_id', None)}, 'children': filhos}
+        erro = None
+        if getattr(node, 'search', None) and getattr(node, 'value', None) in (None, ''):
+            # UI-12: the search field shows the search in the URL, as in the browser.
+            try:
+                atuais = self.r.context.get_variable('query')
+            except Exception:
+                atuais = None
+            if isinstance(atuais, dict) and atuais.get(node.bind) not in (None, ''):
+                node = copy.copy(node)
+                node.value = str(atuais[node.bind])
+        if isinstance(node, FIELDS):
+            # UI-9: the same rules, values and errors the browser's form gets.
+            node, erro = prepare_field(node, getattr(self, '_form_ctx', None), escape=False)
+        if isinstance(node, UIFormNode):
+            anterior = getattr(self, '_form_ctx', None)
+            acao = (node.on_submit or '').strip().rstrip('()') or None
+            self._form_ctx = form_context(self.r, node, acao)
+            try:
+                com_campos = copy.copy(node)
+                com_campos.children = generated_fields(node, self._form_ctx)      # UI-10
+                return self._ui_sem_contexto(com_campos, None)
+            finally:
+                self._form_ctx = anterior
+        return self._ui_sem_contexto(node, erro)
+
+    def _ui_sem_contexto(self, node, erro) -> Dict[str, Any]:
+        props = {}
+        for nome, valor in vars(node).items():
+            if nome in _NAO_PROPS or nome.startswith('_') or valor is None:
+                continue
+            if isinstance(valor, str):
+                props[nome] = self._texto(valor) if '{' in valor else valor
+            elif isinstance(valor, (bool, int, float)):
+                props[nome] = valor
+        if 'content' in props:
+            props['text'] = props.pop('content')
+        if isinstance(node, UITableNode) and node.source:
+            return self._tabela(node, props)
+        if isinstance(node, UIListNode) and node.source:
+            filhos = []
+            for linha in source_rows(self.r, node, 'ui:list', 'item'):
+                filhos.extend(self.build(node.children) if node.children
+                              else [{'type': 'item', 'props': {}, 'children': [
+                                  {'type': 'text', 'props': {'text': '' if linha is None else str(linha)}}]}])
+            return {'type': 'list', 'props': props, 'children': filhos}
+        if erro:
+            props['error'] = erro
+        vista = {'type': _tipo(node), 'props': props,
+                 'children': self.build(getattr(node, 'children', None) or [])}
+        acao = getattr(node, 'on_click', None) or getattr(node, 'on_submit', None)
+        if acao:
+            vista['event'] = {'action': acao.strip().rstrip('()'), 'fields': self._campos(getattr(node, 'send', None))}
+        return vista
+
+    def _tabela(self, node: UITableNode, props: Dict[str, Any]) -> Dict[str, Any]:
+        """UI-5: a table with its rows; each cell is a list of view nodes.
+        UI-13: sortable headers carry the link; an editable cell is a form."""
+        colunas = [c for c in node.children if isinstance(c, UIColumnNode)]
+        plano = edit_plan(self.r, node)
+        estado = getattr(self.r, 'form_state', None)
+        linhas = []
+        for linha in source_rows(self.r, node, 'ui:table', 'row'):
+            celulas = []
+            for c in colunas:
+                if c.children:
+                    celulas.append(self.build(c.children))
+                elif plano and c.key in plano['columns']:
+                    campo, ocultos, erro = cell_field(plano, plano['columns'][c.key], linha, estado, escape=False)
+                    vista_campo = self._ui(campo)
+                    if erro:
+                        vista_campo['props']['error'] = erro
+                    celulas.append([{'type': 'form', 'props': {},
+                                     'event': {'action': ocultos.pop('action'), 'fields': ocultos},
+                                     'children': [vista_campo]}])
+                else:
+                    celulas.append([{'type': 'text', 'props': {'text': cell_value(linha, c)}}])
+            linhas.append(celulas)
+        cabecalho = []
+        for c in colunas:
+            coluna = {'label': c.label or c.key or '', 'align': c.align, 'width': c.column_width}
+            if getattr(node, 'sort', False) and c.key and not c.children:
+                href, marca = sort_link(self.r, c.key)
+                coluna['to'] = href
+                coluna['label'] += f' {marca}' if marca else ''
+            cabecalho.append(coluna)
+        return {'type': 'table', 'props': props, 'columns': cabecalho, 'rows': linhas, 'children': []}
+
+    def _ramo(self, node: IfNode) -> list:
+        if self.r._evaluate_condition(node.condition):
+            return list(node.if_body)
+        for bloco in node.elseif_blocks or []:
+            cond = bloco.get('condition') if isinstance(bloco, dict) else getattr(bloco, 'condition', None)
+            corpo = bloco.get('body') if isinstance(bloco, dict) else getattr(bloco, 'body', None)
+            if cond is not None and self.r._evaluate_condition(cond):
+                return list(corpo or [])
+        return list(node.else_body or [])
+
+    def _loop(self, node: LoopNode) -> List[Dict[str, Any]]:
+        # The same iteration as HTMLRenderer._render_loop.
+        vista: List[Dict[str, Any]] = []
+        ctx = self.r.context
+        originais = ctx.local_vars.copy()
+        try:
+            for indice, item in enumerate(self.r._get_loop_items(node) or []):
+                ctx.set_variable(node.var_name, item, scope='local')
+                if node.loop_type == 'query' and isinstance(item, dict):
+                    for campo, valor in item.items():
+                        ctx.set_variable(f'{node.var_name}.{campo}', valor, scope='local')
+                if node.index_name:
+                    ctx.set_variable(node.index_name, indice, scope='local')
+                vista.extend(self.build(node.body))
+        finally:
+            ctx.local_vars = originais
+        return vista