quantum-framework 0.17.0__tar.gz → 0.18.0__tar.gz

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantum-framework
-Version: 0.17.0
+Version: 0.18.0
 Summary: Full-stack declarative framework for building web, desktop, and mobile applications
 Author-email: Daniel Gregorio <danielgregorio2611@gmail.com>
 License: MIT

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantum-framework"
-version = "0.17.0"
+version = "0.18.0"
 description = "Full-stack declarative framework for building web, desktop, and mobile applications"
 readme = "README.md"
 license = {text = "MIT"}

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/cli/check.py

@@ -102,9 +102,30 @@ class ProjectChecker:
         self._fields(ast, rel, colunas, {nome: nome for nome in colunas}, None)
 
     def _queries(self, node, rel: str, colunas: Dict[str, List[str]]) -> None:
-        from quantum.core.ast_nodes import QueryNode
-        from quantum.runtime.db_schema import check_sql
+        from quantum.core.ast_nodes import ActionNode, QueryNode
+        from quantum.runtime.db_schema import check_sql, read_schema
         for filho in _children(node):
+            if isinstance(filho, ActionNode) and getattr(filho, 'table', None):
+                # UI-10: the table the action takes its params from exists, with those columns.
+                ds = filho.table_datasource
+                if ds not in self.datasources:
+                    self.problems.append(Problem(rel, getattr(filho, 'source_line', None),
+                                                 f'<q:action name="{filho.name}">: datasource {ds!r} is not '
+                                                 f'declared in quantum.config.yaml'))
+                elif self._connection(ds) is not None:
+                    esquema = read_schema(self._connection(ds))
+                    tabela = esquema.get(filho.table)
+                    if tabela is None:
+                        self.problems.append(Problem(rel, getattr(filho, 'source_line', None),
+                                                     f'<q:action name="{filho.name}" table="{filho.table}">: '
+                                                     f'no such table (tables: {", ".join(esquema) or "none"})'))
+                    else:
+                        for coluna in filho.table_columns or []:
+                            if coluna not in tabela.columns:
+                                self.problems.append(Problem(
+                                    rel, getattr(filho, 'source_line', None),
+                                    f'<q:action name="{filho.name}" columns=...>: table "{filho.table}" '
+                                    f'has no column "{coluna}"'))
             if isinstance(filho, QueryNode):
                 ds = filho.datasource
                 if not ds or ds.startswith('knowledge:') or getattr(filho, 'source', None):

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/core/ast_nodes.py

@@ -698,6 +698,8 @@ class QueryNode(QuantumNode):
         self.interval = None
         self.paginate = False  # Enable automatic pagination
         self.page = None
+        self.page_expr = None  # DB-9: page as an expression (default {query.page})
+        self.sortable = False  # UI-13: ORDER BY the URL's ?sort=/&dir=
         self.page_size = 20
         self.timeout = None
         self.maxrows = None
@@ -1137,6 +1139,10 @@ class ActionNode(QuantumNode):
         self.method = method.upper()
         self.params: List[QuantumParam] = []
         self.body: List[QuantumNode] = []
+        # UI-10 (M17): params from a table's schema — see quantum/runtime/table_params.py
+        self.table: Optional[str] = None
+        self.table_datasource: Optional[str] = None
+        self.table_columns: Optional[List[str]] = None
 
         # Action configuration
         self.validate_csrf = True  # Auto CSRF protection

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/core/features/ui_engine/src/ast_nodes.py

@@ -319,6 +319,9 @@ class UIFormNode(QuantumNode, UILayoutMixin):
 
     def __init__(self):
         self.on_submit: Optional[str] = None
+        self.rules: Optional[str] = None  # UI-9: 'off' = no rules from the action
+        self.values: Optional[str] = None  # UI-10: {row} whose fields fill the form
+        self.submit: Optional[str] = None  # UI-10: text of the generated button
         self.children: List[QuantumNode] = []
 
         # Validation mode: 'client', 'server', or 'both' (default)
@@ -550,6 +553,8 @@ class UIInputNode(QuantumNode, UILayoutMixin):
     def __init__(self):
         self.bind: Optional[str] = None
         self.value: Optional[str] = None  # initial value (UI-6)
+        self.search: Optional[str] = None  # UI-12: id of the region it refreshes as you type
+        self.delay: Optional[int] = None   # UI-12: ms after the last key (300 with search=)
         self.placeholder: Optional[str] = None
         self.input_type: str = "text"    # text, password, email, number
         self.on_change: Optional[str] = None
@@ -673,6 +678,9 @@ class UITableNode(QuantumNode, UILayoutMixin):
     def __init__(self):
         self.source: Optional[str] = None
         self.as_var: Optional[str] = None  # row variable for column content (UI-5)
+        self.sort: bool = False               # UI-13: headers sort the query
+        self.edit: Optional[str] = None       # UI-13: table whose cells are edited in place
+        self.edit_datasource: Optional[str] = None
         self.children: List[QuantumNode] = []  # UIColumnNode children
         self._init_layout_attrs()
 
@@ -697,6 +705,7 @@ class UIColumnNode(QuantumNode):
         self.label: Optional[str] = None
         self.column_width: Optional[str] = None
         self.align: Optional[str] = None  # left, center, right
+        self.edit: bool = True            # UI-13: edit="false" keeps it read-only
         # UI-5: a column with content draws it once per row (buttons, links).
         self.children: List[QuantumNode] = []
 
@@ -1870,6 +1879,23 @@ class UIDatePickerNode(QuantumNode, UILayoutMixin):
         return self._validate_layout()
 
 
+class UIPagerNode(QuantumNode, UILayoutMixin):
+    """<ui:pager for="query"> — previous, page numbers and next over a paginated query (UI-11)."""
+
+    def __init__(self):
+        self.for_query: Optional[str] = None
+        self.param: str = 'page'
+        self.window: int = 2
+        self.children: List[QuantumNode] = []
+        self._init_layout_attrs()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": "ui_pager", "for": self.for_query, "param": self.param}
+
+    def validate(self) -> List[str]:
+        return [] if self.for_query else ["ui:pager needs for="]
+
+
 def is_ui_node(node) -> bool:
     """A ui:* element (UI-1): markup, drawn by a renderer, never executed."""
     return type(node).__module__ == __name__
@@ -1882,6 +1908,6 @@ CORE_TAGS = frozenset({
     'window', 'hbox', 'vbox', 'grid', 'panel', 'section', 'scrollbox', 'spacer', 'rule',
     'header', 'footer', 'card', 'card-header', 'card-body', 'card-footer', 'tabpanel', 'tab',
     'text', 'badge', 'alert', 'link', 'image', 'progress',
-    'table', 'column', 'list', 'item',
+    'table', 'column', 'list', 'item', 'pager',
     'form', 'formitem', 'input', 'checkbox', 'switch', 'radio', 'select', 'option', 'button',
 })

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/core/features/ui_engine/src/parser.py

@@ -28,7 +28,7 @@ from .ast_nodes import (
     UIToastNode, UIToastContainerNode,
     UICarouselNode, UISlideNode,
     UIStepperNode, UIStepNode,
-    UICalendarNode, UIDatePickerNode,
+    UICalendarNode, UIDatePickerNode, UIPagerNode,
 )
 from quantum.core.features.theming.src import UIThemeNode, UIColorNode
 from quantum.core.ast_nodes import TextNode
@@ -81,6 +81,7 @@ class UIParser:
         'select': '_parse_ui_select',
         'table': '_parse_ui_table',
         'column': '_parse_ui_column',
+        'pager': '_parse_ui_pager',
         'list': '_parse_ui_list',
         'item': '_parse_ui_item',
         'image': '_parse_ui_image',
@@ -359,6 +360,13 @@ class UIParser:
         node = UIFormNode()
         node.on_submit = element.get('on-submit')
         node.send = element.get('with')
+        # UI-9: rules="off" stops the form from taking its fields' rules from the action.
+        node.rules = element.get('rules')
+        # UI-10: an edit form opens with a row's values; the generated button's text.
+        node.values = element.get('values')
+        node.submit = element.get('submit')
+        if node.rules not in (None, 'on', 'off'):
+            raise UIParseError(f'<ui:form rules="{node.rules}">: use on (the default) or off')
 
         # Validation attributes
         node.validation_mode = element.get('validation', 'both')
@@ -430,6 +438,14 @@ class UIParser:
         node = UIInputNode()
         node.bind = element.get('bind')
         node.value = element.get('value')
+        # UI-12: search as you type — refresh the element with this id.
+        node.search = element.get('search')
+        espera = element.get('delay')
+        if espera is not None and not espera.isdigit():
+            raise UIParseError(f'<ui:input delay="{espera}">: milliseconds, e.g. delay="300"')
+        node.delay = int(espera) if espera is not None else (300 if node.search else None)
+        if node.search is not None and not node.bind:
+            raise UIParseError('<ui:input search=...> needs bind= (the URL parameter it sets)')
         node.placeholder = element.get('placeholder')
         node.input_type = element.get('type', 'text')
         node.on_change = element.get('on-change')
@@ -498,6 +514,14 @@ class UIParser:
         node = UITableNode()
         node.source = element.get('source')
         node.as_var = element.get('as')
+        # UI-13: sortable headers and cells edited in place.
+        node.sort = self._parse_bool(element.get('sort'))
+        node.edit = element.get('edit')
+        node.edit_datasource = element.get('datasource')
+        if node.edit and not node.edit_datasource:
+            raise UIParseError(f'<ui:table edit="{node.edit}"> needs datasource= (where the table is)')
+        if (node.sort or node.edit) and not node.source:
+            raise UIParseError('<ui:table sort/edit> needs source="{query}"')
         self._apply_layout_attrs(node, element)
         # Parse child <ui:column> elements
         self._parse_children(element, node)
@@ -509,9 +533,23 @@ class UIParser:
         node.label = element.get('label')
         node.column_width = element.get('width')
         node.align = element.get('align')
+        node.edit = element.get('edit', 'true') != 'false'
         self._parse_children(element, node)
         return node
 
+    def _parse_ui_pager(self, element: ET.Element) -> UIPagerNode:
+        node = UIPagerNode()
+        node.for_query = element.get('for')
+        if not node.for_query:
+            raise UIParseError('<ui:pager> needs for="<the paginated q:query>"')
+        node.param = element.get('param') or 'page'
+        janela = element.get('window')
+        if janela is not None and not janela.isdigit():
+            raise UIParseError(f'<ui:pager window="{janela}">: the number of pages shown each side of the current one')
+        node.window = int(janela) if janela is not None else 2
+        self._apply_layout_attrs(node, element)
+        return node
+
     def _parse_ui_list(self, element: ET.Element) -> UIListNode:
         node = UIListNode()
         node.source = element.get('source')

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/core/parsers/data/query_parser.py

@@ -77,7 +77,27 @@ class QueryParser(BaseTagParser):
         # Parse attributes
         query_node.source = source
         query_node.paginate = self.get_bool_attr(element, 'paginate', False)
-        query_node.page = self.get_int_attr(element, 'page', 0) or None
+        # UI-13: ordered by the URL's ?sort=/&dir= (a <ui:table sort="true"> writes them)
+        query_node.sortable = self.get_bool_attr(element, 'sortable', False)
+        # DB-9: page= is an expression, resolved when the query runs; it was
+        # read as an int at parse time, so page="{query.page}" was always
+        # page 1. With paginate="true" and no page=, the page is the URL's
+        # `page` parameter — the one <ui:pager> writes.
+        pagina = element.get('page')
+        query_node.page = None
+        query_node.page_expr = None
+        if pagina is not None:
+            if '{' in pagina:
+                query_node.page_expr = pagina
+            elif pagina.strip().isdigit():
+                query_node.page = int(pagina)
+            else:
+                from quantum.core.parser import QuantumParseError
+                raise QuantumParseError(
+                    f'<q:query name="{name}" page="{pagina}">: a page number or an expression, '
+                    f'e.g. page="{{query.pagina}}"')
+        elif query_node.paginate:
+            query_node.page_expr = '{query.page}'
         # Accept both spellings: the codebase convention is camelCase, but
         # snake_case reads naturally in XML and the examples used it —
         # the mismatch made page_size None and crashed pagination with

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/core/parsers/forms/action_parser.py

@@ -48,6 +48,21 @@ class ActionParser(BaseTagParser):
                     f'<q:action name="{name}"> {attr}= is not supported: it was accepted '
                     f'and never enforced. {porque}')
 
+        # UI-10 (M17): the action's params come from a table's schema, read
+        # from the database when the action is used; a q:param written wins.
+        action_node.table = element.get('table')
+        action_node.table_datasource = element.get('datasource')
+        colunas = element.get('columns')
+        action_node.table_columns = [c.strip() for c in colunas.split(',') if c.strip()] if colunas else None
+        if (action_node.table_datasource or colunas) and not action_node.table:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:action name="{name}"> datasource= and columns= describe table=, which is missing')
+        if action_node.table and not action_node.table_datasource:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(
+                f'<q:action name="{name}" table="{action_node.table}"> needs datasource= (where the table is)')
+
         # Parse children (params, statements)
         for child in element:
             child_type = self._get_element_name(child)

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/runtime/action_handler.py

@@ -24,8 +24,23 @@ logger = logging.getLogger('quantum.action')
 
 
 class ValidationError(Exception):
-    """Parameter validation error"""
-    pass
+    """Parameter validation error.
+
+    `fields` maps each field that failed to its own message (UI-9): the form
+    shows each one next to its field. The exception's text is the first one,
+    the flash message it always was."""
+
+    def __init__(self, message: str, fields: Optional[Dict[str, str]] = None):
+        super().__init__(message)
+        self.fields = fields or {}
+
+
+def _field_message(nome: str, mensagem: str) -> str:
+    """"Parameter 'titulo' must be at least 3 characters" -> "Must be at least 3 characters"."""
+    texto = re.sub(rf"^Parameter '{re.escape(nome)}' ", '', mensagem)
+    if texto == 'is required':
+        return 'Required'
+    return texto[:1].upper() + texto[1:]
 
 
 class ActionHandler:
@@ -70,7 +85,7 @@ class ActionHandler:
             form_data = self._extract_form_data()
 
             # 2. Validate parameters
-            validated_params = self._validate_parameters(action.params, form_data)
+            validated_params = self._validate_parameters(self._params_of(action), form_data, action)
 
             # 3. Add validated params to context
             for key, value in validated_params.items():
@@ -129,6 +144,15 @@ class ActionHandler:
         except ValidationError as e:
             # Validation failed - set error flash and redirect back
             self._set_flash_message(str(e), 'error')
+            # UI-9: the next render of the form shows each error by its field
+            # and the values that were sent (never a password, never a file).
+            session['form_state'] = {
+                'action': getattr(action, 'name', None),
+                'errors': e.fields,
+                'values': {n: v for n, v in request.form.items()
+                           if n != 'action' and n not in self._secret_fields(action)},
+            }
+            session.modified = True
             # Redirect to referer or home
             referer = request.referrer or '/'
             return referer, 302
@@ -206,10 +230,16 @@ class ActionHandler:
 
         return data
 
+    def _params_of(self, action) -> List[QuantumParam]:
+        """The action's q:params, plus its table's when it declares one (UI-10)."""
+        from quantum.runtime.table_params import params_of
+        return params_of(action, getattr(self.component_runtime, 'config', None) or {})
+
     def _validate_parameters(
         self,
         params: List[QuantumParam],
-        form_data: Dict[str, Any]
+        form_data: Dict[str, Any],
+        action=None,
     ) -> Dict[str, Any]:
         """
         Validate form data against q:param definitions.
@@ -218,30 +248,60 @@ class ActionHandler:
         """
 
         validated = {}
+        primeira = None
+        por_campo: Dict[str, str] = {}
 
         for param in params:
             value = form_data.get(param.name)
+            try:
+                # Check required
+                if param.required and (value is None or value == ''):
+                    raise ValidationError(f"Parameter '{param.name}' is required")
+
+                # Skip validation if optional and not provided
+                if value is None or value == '':
+                    if param.default is not None:
+                        validated[param.name] = param.default
+                    elif getattr(param, 'nullable', False):
+                        validated[param.name] = None      # UI-10: a NULL column left blank
+                    continue
 
-            # Check required
-            if param.required and (value is None or value == ''):
-                raise ValidationError(f"Parameter '{param.name}' is required")
-
-            # Skip validation if optional and not provided
-            if value is None or value == '':
-                if param.default is not None:
-                    validated[param.name] = param.default
-                continue
-
-            # Type validation and conversion
-            validated_value = self._validate_type(param, value)
-
-            # Additional validation rules
-            self._validate_rules(param, validated_value)
-
-            validated[param.name] = validated_value
-
+                # Type validation and conversion
+                validated_value = self._validate_type(param, value)
+
+                # Additional validation rules
+                self._validate_rules(param, validated_value)
+
+                # UI-10: a foreign key names a row that exists.
+                referencia = getattr(param, 'references', None)
+                if referencia and action is not None and getattr(action, 'table_datasource', None):
+                    from quantum.runtime.table_params import reference_exists
+                    if not reference_exists(getattr(self.component_runtime, 'config', None) or {},
+                                            action.table_datasource, referencia, validated_value):
+                        raise ValidationError(
+                            f"Parameter '{param.name}' must name an existing row of {referencia[0]} "
+                            f"(no {referencia[1]} = {validated_value})")
+
+                validated[param.name] = validated_value
+            except ValidationError as erro:
+                # UI-9: every field is checked, so the form can mark each one.
+                primeira = primeira or str(erro)
+                por_campo[param.name] = _field_message(param.name, str(erro))
+
+        if primeira:
+            raise ValidationError(primeira, por_campo)
         return validated
 
+    @staticmethod
+    def _secret_fields(action) -> set:
+        """Fields never sent back to a form: passwords and uploads (UI-9)."""
+        nomes = set()
+        for param in getattr(action, 'params', None) or []:   # table columns are never secrets
+            tipo = str(getattr(param, 'type', '') or '').lower()
+            if tipo in ('password', 'file') or 'senha' in param.name.lower() or 'password' in param.name.lower():
+                nomes.add(param.name)
+        return nomes
+
     def _validate_type(self, param: QuantumParam, value: Any) -> Any:
         """Converte o valor para o tipo declarado, ou levanta ValidationError.
 

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/runtime/component.py

@@ -232,6 +232,11 @@ class ComponentRuntime:
         """Access to service container"""
         return self._services
 
+    @property
+    def config(self) -> Dict[str, Any]:
+        """The project configuration this runtime runs with."""
+        return self._services._config or {}
+
     @property
     def executor_registry(self) -> ExecutorRegistry:
         """Access to executor registry (may be None if not using modular executors)"""

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/runtime/executors/data/query_executor.py

@@ -93,10 +93,11 @@ class QueryExecutor(BaseExecutor):
 
         # Handle pagination
         pagination_metadata = None
-        sql_to_execute = node.sql
+        sql_to_execute = self._sorted_sql(node, params, exec_context)     # UI-13
 
         if node.paginate:
-            pagination_metadata, sql_to_execute = self._handle_pagination(node, params)
+            pagination_metadata, sql_to_execute = self._handle_pagination(
+                node, params, exec_context, base_sql=sql_to_execute)
 
         # Execute query
         result = self.services.database.execute_query(
@@ -110,7 +111,32 @@ class QueryExecutor(BaseExecutor):
 
         return result
 
-    def _handle_pagination(self, node: QueryNode, params: Dict[str, Any]):
+    def _sorted_sql(self, node: QueryNode, params: Dict[str, Any], exec_context) -> str:
+        """UI-13: a sortable query orders by the URL's ?sort= (and ?dir=asc|desc).
+
+        The column must be one the query returns — found with LIMIT 0, never
+        taken from the URL otherwise; an unknown one leaves the order as
+        written (a URL is not an error)."""
+        if not getattr(node, 'sortable', False):
+            return node.sql
+        try:
+            consulta = exec_context.get_variable('query') if exec_context is not None else None
+        except Exception:
+            consulta = None
+        consulta = consulta if isinstance(consulta, dict) else {}
+        coluna = str(consulta.get('sort') or '').strip()
+        direcao = 'DESC' if str(consulta.get('dir') or '').lower() == 'desc' else 'ASC'
+        if not coluna:
+            return node.sql
+        base = node.sql.strip().rstrip(';')
+        sonda = self.services.database.execute_query(
+            node.datasource, f'SELECT * FROM ({base}) AS quantum_ordenada LIMIT 0', params)
+        if coluna not in (sonda.column_list or []):
+            return node.sql
+        return f'SELECT * FROM ({base}) AS quantum_ordenada ORDER BY "{coluna}" {direcao}'
+
+    def _handle_pagination(self, node: QueryNode, params: Dict[str, Any], exec_context=None,
+                           base_sql: str = None):
         """Handle query pagination"""
         count_sql = self._generate_count_query(node.sql)
         count_result = self.services.database.execute_query(
@@ -122,13 +148,21 @@ class QueryExecutor(BaseExecutor):
         total_records = count_result.data[0]['count'] if count_result.data else 0
 
         page = node.page if node.page is not None else 1
+        if getattr(node, 'page_expr', None):
+            # DB-9: from the URL, so never an error — ?page=abc or ?page=-3 is page 1.
+            variaveis = exec_context.get_all_variables() if exec_context is not None else None
+            bruto = self.apply_databinding(node.page_expr, variaveis)
+            try:
+                page = max(1, int(str(bruto).strip()))
+            except (TypeError, ValueError):
+                page = 1
         # paginate="true" without a page size is a config error, not a
         # reason to crash on None arithmetic further down.
         page_size = node.page_size or 10
         total_pages = (total_records + page_size - 1) // page_size
 
         offset = (page - 1) * page_size
-        sql_to_execute = f"{node.sql}\nLIMIT {page_size} OFFSET {offset}"
+        sql_to_execute = f"{base_sql or node.sql}\nLIMIT {page_size} OFFSET {offset}"
 
         pagination_metadata = {
             'totalRecords': total_records,

{quantum_framework-0.17.0 → quantum_framework-0.18.0}/quantum/runtime/renderer.py

@@ -121,6 +121,8 @@ class HTMLRenderer:
             # component rendered is the page; a called component posts to it.
             if not hasattr(self, '_ui_actions'):
                 self._ui_actions = [s.name for s in node.statements if isinstance(s, ActionNode)]
+                # UI-9: a ui:form takes its fields' rules from the action it posts to.
+                self._ui_action_nodes = {s.name: s for s in node.statements if isinstance(s, ActionNode)}
             self.imports = {
                 imp.alias or imp.component: (imp.component, imp.from_path)
                 for imp in node.statements