quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/ui_console.py

@@ -0,0 +1,405 @@
+"""The console renderer: a Quantum page as a terminal app (UI-3).
+
+`quantum console` starts the application's server in this process and opens a
+Textual app on it. The app asks each page for its view tree
+(quantum/runtime/ui_view.py) instead of HTML, draws it with Textual widgets,
+and sends the same q:action posts a browser sends — with a cookie jar, so
+login, validation, flash and redirects are exactly the web's. Nothing of the
+page's logic is translated: the runtime that serves the browser serves this.
+"""
+
+import asyncio
+from typing import Any, Dict, List, Optional
+from urllib.parse import urljoin
+
+import requests
+from rich.text import Text
+from textual.app import App, ComposeResult
+from textual.containers import Grid, Horizontal, Vertical, VerticalScroll
+from textual.widgets import (Button, Checkbox, Input, ProgressBar, RadioButton, RadioSet,
+                             Select, Static, Switch, TabbedContent, TabPane)
+
+VIEW = 'application/vnd.quantum.view+json'
+
+# UI-2 in a terminal: the breakpoints in columns (a column is ~8 px).
+BREAKPOINT_COLUMNS = {'sm': 80, 'md': 96, 'lg': 128}
+
+
+def _marcado(valor) -> bool:
+    """UI-6: checked="true", or an expression that resolved to a true value."""
+    return valor is not None and str(valor).strip().lower() in ('true', '1', 'on', 'yes', 'checked')
+
+
+def _numero(valor, padrao: float) -> float:
+    try:
+        return float(valor)
+    except (TypeError, ValueError):
+        return padrao
+
+
+class ConsoleUI(App):
+    """Draws a page's view tree; buttons and forms post the page's actions."""
+
+    CSS = """
+    Screen { background: $surface; }
+    #tela { padding: 1 2; }
+    .window { height: auto; }
+    .hbox { height: auto; }
+    .vbox { height: auto; }
+    .hbox > Static { width: auto; margin-right: 1; }
+    .hbox > Button, .hbox > Input, .hbox > Select { margin-right: 1; }
+    .grow { width: 1fr; }
+    .panel { border: round $primary; padding: 0 1; height: auto; margin-bottom: 1; }
+    .flash { background: $success 30%; padding: 0 1; margin-bottom: 1; }
+    .flash-error { background: $error 30%; }
+    .badge { background: $secondary; color: $text; padding: 0 1; }
+    .link { min-width: 0; height: 1; border: none; background: $surface; text-style: underline; }
+    Button { min-width: 8; }
+    .grid { height: auto; grid-rows: auto; grid-gutter: 0 1; }
+    .table { height: auto; margin-bottom: 1; }
+    .row { height: auto; }
+    .row-head { border-bottom: solid $primary; }
+    .cell { height: auto; padding: 0 1; }
+    .label { color: $text-muted; }
+    .unsupported { color: $warning; }
+    .field-error { color: $error; }
+    .invalid { border: tall $error; }
+    TabbedContent { height: auto; }
+    TabPane { height: auto; }
+    """
+
+    def __init__(self, base_url: str, path: str = '/'):
+        super().__init__()
+        self.base_url = base_url
+        self.path = path
+        self.http = requests.Session()
+        self._eventos: Dict[int, Dict[str, Any]] = {}
+        self.titulo_da_pagina = ''
+        self._trava = asyncio.Lock()
+        self.carregando = False
+
+    def compose(self) -> ComposeResult:
+        yield VerticalScroll(id='tela')
+
+    async def on_mount(self) -> None:
+        await self.carregar(self.path)
+
+    # -- talking to the page --------------------------------------------------
+
+    def _pedir(self, metodo: str, caminho: str, dados: Optional[dict] = None) -> dict:
+        url = urljoin(self.base_url, caminho)
+        resposta = self.http.request(metodo, url, data=dados, allow_redirects=True,
+                                     headers={'Accept': VIEW, 'Referer': urljoin(self.base_url, self.path)},
+                                     timeout=30)
+        if resposta.headers.get('Content-Type', '').startswith(VIEW):
+            self.path = resposta.url[len(self.base_url.rstrip('/')):] or '/'
+            return resposta.json()
+        # An error page, a 400 from an unknown action: show it as it is.
+        return {'title': str(resposta.status_code), 'flash': f'{resposta.status_code} {resposta.reason}',
+                'flashType': 'error', 'view': []}
+
+    async def carregar(self, caminho: str, metodo: str = 'GET', dados: Optional[dict] = None) -> None:
+        # One page at a time: a second click while a page is still being
+        # mounted removed half-mounted widgets (Textual's Select then fails).
+        async with self._trava:
+            self.carregando = True
+            try:
+                await self._carregar(caminho, metodo, dados)
+                # Let the new widgets finish their own mounting (a Select
+                # composes its label after mount) before anything replaces them.
+                await asyncio.sleep(0)
+            finally:
+                self.carregando = False
+
+    async def _carregar(self, caminho: str, metodo: str, dados: Optional[dict]) -> None:
+        pagina = self._pedir(metodo, caminho, dados)
+        self.titulo_da_pagina = pagina.get('title', '')
+        self.title = self.titulo_da_pagina
+        tela = self.query_one('#tela', VerticalScroll)
+        await tela.remove_children()
+        self._eventos.clear()
+        widgets: List = []
+        if pagina.get('flash'):
+            classes = 'flash flash-error' if pagina.get('flashType') == 'error' else 'flash'
+            widgets.append(Static(Text(str(pagina['flash'])), classes=classes, id='flash'))
+        widgets.extend(self._montar(pagina.get('view', [])))
+        await tela.mount_all(widgets)
+
+    # -- drawing --------------------------------------------------------------
+
+    def _montar(self, nos: List[dict], formulario: Optional[dict] = None) -> List:
+        widgets = [w for no in nos for w in [self._widget(no, formulario)] if w is not None]
+        for w in widgets:
+            if formulario is not None and not hasattr(w, '_quantum_formulario'):
+                w._quantum_formulario = formulario
+        return widgets
+
+    def _classes_css(self, props: dict, base: str) -> str:
+        classes = [base]
+        if str(props.get('grow', '')).lower() == 'true':
+            classes.append('grow')
+        return ' '.join(classes)
+
+    def _widget(self, no: dict, formulario: Optional[dict]):
+        widget = self._widget_sem_largura(no, formulario)
+        props = no.get('props') or {}
+        largura = str(props.get('width') or '')
+        if widget is not None and largura.isdigit():
+            # A width in px becomes columns (~8 px each), as the breakpoints do.
+            widget.styles.width = max(8, int(largura) // 8)
+        if widget is not None and props.get('error'):
+            # UI-9: the server refused this field; its message under it.
+            widget.add_class('invalid')
+            return Vertical(widget, Static(Text(str(props['error'])), classes='field-error'), classes='vbox')
+        return widget
+
+    def _widget_sem_largura(self, no: dict, formulario: Optional[dict]):
+        tipo, props = no.get('type'), no.get('props', {})
+        filhos = no.get('children', [])
+        ident = props.get('ui_id')
+        texto = str(props.get('text') or '')
+
+        if tipo in ('window', 'vbox', 'scrollbox', 'cardbody', 'cardfooter', 'tab'):
+            return Vertical(*self._montar(filhos, formulario), classes=self._classes_css(props, 'vbox'), id=ident)
+        if tipo == 'section':
+            titulo = [Static(Text(str(props['title']), style='bold'), classes='text')] if props.get('title') else []
+            return Vertical(*titulo, *self._montar(filhos, formulario), classes=self._classes_css(props, 'vbox'),
+                            id=ident)
+        if tipo == 'card':
+            cartao = Vertical(*self._montar(filhos, formulario), classes='panel', id=ident)
+            cartao.border_title = props.get('title', '')
+            return cartao
+        if tipo == 'hbox':
+            empilha = props.get('stack_below')
+            estreito = empilha and self.size.width < BREAKPOINT_COLUMNS.get(empilha, 0)
+            tipo_caixa = Vertical if estreito else Horizontal
+            filhos_w = self._montar(filhos, formulario)
+            if estreito:
+                # Stacked: fixed widths stop applying, as in the web's CSS (UI-2).
+                for w in filhos_w:
+                    w.styles.width = '100%'
+            return tipo_caixa(*filhos_w,
+                              classes=self._classes_css(props, 'vbox' if estreito else 'hbox'), id=ident)
+        if tipo == 'grid':
+            grade = Grid(*self._montar(filhos, formulario), classes='grid', id=ident)
+            grade.styles.grid_size_columns = self._colunas_da_grade(str(props.get('columns') or '1'))
+            return grade
+        if tipo == 'panel':
+            painel = Vertical(*self._montar(filhos, formulario), classes='panel', id=ident)
+            painel.border_title = props.get('title', '')
+            return painel
+        if tipo == 'tabpanel':
+            abas = TabbedContent(id=ident)
+            for n, f in enumerate(f for f in filhos if f.get('type') == 'tab'):
+                abas.compose_add_child(TabPane(str(f.get('props', {}).get('title') or n + 1),
+                                               *self._montar(f.get('children', []), formulario)))
+            return abas
+        if tipo == 'form':
+            # The form's marker exists before its children, so each widget
+            # inside can point to it; the marker keeps the box and the action.
+            marcador = {'event': no.get('event')}
+            caixa = Vertical(*self._montar(filhos, marcador), classes='vbox', id=ident)
+            marcador['caixa'] = caixa
+            return caixa
+        if tipo == 'formitem':
+            rotulo = [Static(Text(str(props['label'])), classes='label')] if props.get('label') else []
+            return Vertical(*rotulo, *self._montar(filhos, formulario), classes='vbox', id=ident)
+        if tipo == 'button':
+            botao = Button(texto or props.get('label') or '', id=ident,
+                           variant='error' if props.get('variant') == 'danger' else
+                           ('primary' if props.get('variant') == 'primary' else 'default'))
+            if no.get('event'):
+                self._eventos[id(botao)] = no['event']
+            return botao
+        if tipo == 'link':
+            link = Button(texto or props.get('to', ''), classes='link', id=ident)
+            self._eventos[id(link)] = {'navigate': props.get('to', '/')}
+            return link
+        if tipo == 'input':
+            campo = Input(value=str(props.get('value') or ''), placeholder=props.get('placeholder', ''),
+                          id=ident, classes=self._classes_css(props, 'input'),
+                          password=props.get('input_type') == 'password')
+            campo._quantum_nome = props.get('bind')
+            if props.get('search'):
+                # UI-12: typing asks for the page again with ?bind=value.
+                campo._quantum_busca = int(props.get('delay') or 300)
+                campo._quantum_inicial = campo.value
+            return campo
+        if tipo == 'select':
+            opcoes = [(o.strip(), o.strip()) for o in str(props.get('options') or '').split(',') if o.strip()]
+            opcoes += [(str(f['props'].get('label') or f['props'].get('value') or ''),
+                        str(f['props'].get('value') or ''))
+                       for f in filhos if f.get('type') == 'option']
+            valores = [v for _, v in opcoes]
+            escolhido = str(props.get('value') or '')
+            valor = escolhido if escolhido in valores else (valores[0] if valores else Select.BLANK)
+            escolha = Select(opcoes, value=valor, allow_blank=not opcoes, id=ident)
+            escolha._quantum_nome = props.get('bind')
+            return escolha
+        if tipo == 'checkbox':
+            caixa = Checkbox(str(props.get('label') or ''), value=_marcado(props.get('checked')), id=ident)
+            caixa._quantum_nome = props.get('bind')
+            return caixa
+        if tipo == 'switch':
+            chave = Switch(value=_marcado(props.get('checked')))
+            chave._quantum_nome = props.get('bind')
+            return Horizontal(chave, Static(Text(str(props.get('label') or '')), classes='text'),
+                              classes='hbox', id=ident)
+        if tipo == 'radio':
+            escolhido = str(props.get('value') or '')
+            opcoes = [o.strip() for o in str(props.get('options') or '').split(',') if o.strip()]
+            grupo = RadioSet(*[RadioButton(o, value=o == escolhido) for o in opcoes], id=ident)
+            grupo._quantum_nome = props.get('bind')
+            return grupo
+        if tipo == 'table':
+            return self._tabela(no, formulario, ident)
+        if tipo == 'list':
+            return Vertical(*self._montar(filhos, formulario), classes='vbox', id=ident)
+        if tipo == 'item':
+            return Horizontal(Static('•', classes='text'), *self._montar(filhos, formulario),
+                              classes='hbox', id=ident)
+        if tipo == 'progress':
+            barra = ProgressBar(total=_numero(props.get('max'), 100), show_eta=False, id=ident)
+            barra.progress = _numero(props.get('value'), 0)
+            return barra
+        if tipo == 'image':
+            return Static(Text(f"[{props.get('alt') or props.get('src') or 'image'}]"), classes='text', id=ident)
+        if tipo in ('header', 'cardheader'):
+            titulo = str(props.get('title') or texto)
+            return Vertical(Static(Text(titulo, style='bold'), classes='text'),
+                            *self._montar(filhos, formulario), classes='vbox', id=ident)
+        if tipo == 'alert':
+            classes = 'flash flash-error' if props.get('variant') in ('danger', 'error') else 'flash'
+            titulo = f"{props['title']}: " if props.get('title') else ''
+            return Static(Text(titulo + texto), classes=classes, id=ident)
+        if tipo == 'badge':
+            return Static(Text(texto), classes='badge', id=ident)
+        if tipo == 'text':
+            return Static(Text(texto, style='bold' if props.get('weight') == 'bold' else ''),
+                          classes='text', id=ident)
+        if tipo == 'footer':
+            return Static(Text(texto, style='dim'), classes='text', id=ident)
+        if tipo == 'rule':
+            return Static('─' * 40, classes='text')
+        if tipo == 'spacer':
+            return Static('', classes='text')
+        # UI-7: outside the core set, say so — never draw something else in its place.
+        return Static(Text(f'[ui:{tipo} is not drawn in the console]', style='italic'),
+                      classes='unsupported', id=ident)
+
+    def _colunas_da_grade(self, spec: str) -> int:
+        """UI-2 `columns="1 sm:2 lg:3"` counted in terminal columns; "1fr 2fr" is 2."""
+        partes = spec.split()
+        if len(partes) > 1 and all(p.endswith('fr') for p in partes):
+            return len(partes)
+        colunas = 1
+        for parte in partes:
+            faixa, _, valor = parte.rpartition(':')
+            if valor.isdigit() and (not faixa or self.size.width >= BREAKPOINT_COLUMNS.get(faixa, 10 ** 6)):
+                colunas = int(valor)
+        return max(1, colunas)
+
+    def _tabela(self, no: dict, formulario: Optional[dict], ident):
+        """UI-5: a header row and one row per record; a cell holds text or widgets."""
+        colunas = no.get('columns', [])
+
+        def celula(widgets, coluna):
+            caixa = Vertical(*widgets, classes='cell')
+            largura = str(coluna.get('width') or '')
+            caixa.styles.width = max(4, int(largura) // 8) if largura.isdigit() else '1fr'
+            return caixa
+
+        def titulo(c):
+            if c.get('to'):
+                # UI-13: a sortable header is a link, as in the browser.
+                link = Button(c['label'], classes='link')
+                self._eventos[id(link)] = {'navigate': c['to']}
+                return link
+            return Static(Text(c['label'], style='bold'))
+
+        cabecalho = Horizontal(*[celula([titulo(c)], c) for c in colunas], classes='row row-head')
+        linhas = [Horizontal(*[celula(self._montar(cel, formulario), c) for cel, c in zip(linha, colunas)],
+                             classes='row')
+                  for linha in no.get('rows', [])]
+        return Vertical(cabecalho, *linhas, classes='table', id=ident)
+
+    # -- events are the page's actions ---------------------------------------
+
+    def _campos_do_formulario(self, formulario: dict) -> Dict[str, str]:
+        """The fields a browser would post: a checked box posts 'on', an unchecked one nothing."""
+        campos = {}
+        for w in formulario['caixa'].query('Input, Select, Checkbox, Switch, RadioSet'):
+            nome = getattr(w, '_quantum_nome', None)
+            if not nome:
+                continue
+            if isinstance(w, (Checkbox, Switch)):
+                if w.value:
+                    campos[nome] = 'on'
+                continue
+            if isinstance(w, RadioSet):
+                if w.pressed_button is not None:
+                    campos[nome] = str(w.pressed_button.label)
+                continue
+            valor = w.value
+            campos[nome] = '' if valor is None or valor is Select.BLANK else str(valor)
+        return campos
+
+    async def on_button_pressed(self, evento: Button.Pressed) -> None:
+        botao = evento.button
+        acao = self._eventos.get(id(botao))
+        if acao and 'navigate' in acao:
+            await self.carregar(acao['navigate'])
+            return
+        formulario = getattr(botao, '_quantum_formulario', None)
+        if acao is None and formulario is not None:
+            acao = formulario.get('event')
+            if acao:
+                dados = {'action': acao['action'], **acao.get('fields', {}),
+                         **self._campos_do_formulario(formulario)}
+                await self.carregar(self.path, 'POST', dados)
+            return
+        if acao:
+            await self.carregar(self.path, 'POST', {'action': acao['action'], **acao.get('fields', {})})
+
+    def on_input_changed(self, evento: Input.Changed) -> None:
+        """UI-12: search as you type — after a pause, the page with ?bind=value."""
+        campo = evento.input
+        espera = getattr(campo, '_quantum_busca', None)
+        if espera is None or campo.value == getattr(campo, '_quantum_inicial', None):
+            return
+        anterior = getattr(self, '_busca_timer', None)
+        if anterior is not None:
+            anterior.stop()
+        nome, valor = campo._quantum_nome, campo.value
+        self._busca_timer = self.set_timer(
+            espera / 1000, lambda: self.run_worker(self._buscar(nome, valor), exclusive=True, group='busca'))
+
+    async def _buscar(self, nome: str, valor: str) -> None:
+        from urllib.parse import parse_qsl, urlencode, urlsplit
+        partes = urlsplit(self.path)
+        parametros = {k: v for k, v in parse_qsl(partes.query) if k not in (nome, 'page')}
+        if valor:
+            parametros[nome] = valor
+        await self.carregar(partes.path + ('?' + urlencode(parametros) if parametros else ''))
+        # The page was drawn again: the field keeps the focus and the cursor at the end.
+        for campo in self.query(Input):
+            if getattr(campo, '_quantum_nome', None) == nome and getattr(campo, '_quantum_busca', None):
+                campo.focus()
+                campo.cursor_position = len(campo.value)
+                break
+
+    async def on_input_submitted(self, evento: Input.Submitted) -> None:
+        formulario = getattr(evento.input, '_quantum_formulario', None)
+        acao = formulario.get('event') if formulario is not None else None
+        if acao:
+            dados = {'action': acao['action'], **acao.get('fields', {}), **self._campos_do_formulario(formulario)}
+            await self.carregar(self.path, 'POST', dados)
+
+
+def run_console(config_path: str = 'quantum.config.yaml', path: str = '/') -> int:
+    """`quantum console`: the application's server in a thread, the page in the terminal."""
+    from quantum.runtime.local_server import local_server
+
+    with local_server(config_path) as base_url:
+        ConsoleUI(base_url, path).run()
+    return 0

quantum/runtime/ui_desktop.py

@@ -0,0 +1,56 @@
+"""The desktop renderer: a Quantum application in its own window (UI-4).
+
+`quantum desktop` starts the application's server on a free local port and
+opens a native window (pywebview) on it. The window is a browser without the
+browser's chrome: pages, q:action, sessions and UI-2 layout are exactly the
+web's, because it is the web's server that answers. Nothing of a page's logic
+is translated.
+"""
+
+import sys
+from urllib.parse import urljoin
+
+INSTALL_HINT = 'pip install "quantum-framework[desktop]"'
+
+DEFAULT_WIDTH = 1024
+DEFAULT_HEIGHT = 720
+
+
+def _webview():
+    try:
+        import webview
+    except ImportError:
+        return None
+    return webview
+
+
+def open_window(webview, url: str, title: str = 'Quantum',
+                width: int = DEFAULT_WIDTH, height: int = DEFAULT_HEIGHT):
+    """Create the window on `url`; its title follows each page's <title>."""
+    janela = webview.create_window(title, url, width=width, height=height, min_size=(360, 480))
+
+    def ao_carregar():
+        titulo = janela.evaluate_js('document.title')
+        if titulo:
+            janela.set_title(str(titulo))
+
+    janela.events.loaded += ao_carregar
+    return janela
+
+
+def run_desktop(config_path: str = 'quantum.config.yaml', path: str = '/',
+                width: int = DEFAULT_WIDTH, height: int = DEFAULT_HEIGHT,
+                webview=None) -> int:
+    """`quantum desktop`: the application's server in a thread, the pages in a window."""
+    webview = webview or _webview()
+    if webview is None:
+        print(f'[ERROR] quantum desktop needs pywebview: {INSTALL_HINT}', file=sys.stderr)
+        return 1
+    from quantum.runtime.local_server import local_server
+
+    with local_server(config_path) as base_url:
+        open_window(webview, urljoin(base_url, path.lstrip('/')), width=width, height=height)
+        # Blocks until the window closes; the server stops with it.
+        webview.start(private_mode=True)
+    return 0
+

quantum/runtime/ui_form_rules.py

@@ -0,0 +1,193 @@
+"""Forms that know their action's rules (M1, UI-9).
+
+A `<ui:form on-submit="criar">` posts to `<q:action name="criar">`, whose
+`q:param`s already say what each field must be. The form takes those rules
+as HTML attributes — `required`, `minlength`, `min`, `type="number"`… — so the
+browser checks them before posting; the server still validates (ACT-2). When
+the server's validation fails, the next render of that form shows the values
+that were sent (never a password) and each error next to its field.
+
+What a field gets is visible in the HTML it draws; `<ui:form rules="off">`
+turns it off; an attribute written on the field always wins.
+"""
+
+import copy
+import html
+from typing import Dict, Optional, Tuple
+
+from quantum.core.features.ui_engine.src.ast_nodes import (
+    UICheckboxNode, UIInputNode, UIRadioNode, UISelectNode, UISwitchNode)
+
+FIELDS = (UIInputNode, UISelectNode, UIRadioNode, UICheckboxNode, UISwitchNode)
+
+# q:param type -> the input type the browser checks
+_HTML_TYPE = {'integer': 'number', 'number': 'number', 'decimal': 'number', 'float': 'number',
+              'email': 'email', 'url': 'url', 'date': 'date'}
+
+
+class FormContext:
+    """What a form knows while its fields are drawn."""
+
+    def __init__(self, params=None, state: Optional[dict] = None, rules: bool = True,
+                 initial: Optional[dict] = None, action=None, config=None):
+        self.all_params = list(params or [])
+        self.params = {p.name: p for p in self.all_params} if rules else {}
+        self.errors: Dict[str, str] = (state or {}).get('errors') or {}
+        self.values: Optional[Dict[str, str]] = (state or {}).get('values') if state else None
+        self.initial: Dict[str, object] = initial or {}          # UI-10: values="{row}"
+        self.action = action
+        self.config = config or {}
+
+
+def form_context(renderer, form_node, action_name: Optional[str]) -> Optional[FormContext]:
+    if not action_name:
+        return None
+    acao = (getattr(renderer, '_ui_action_nodes', None) or {}).get(action_name)
+    estado = getattr(renderer, 'form_state', None)
+    if not estado or estado.get('action') != action_name:
+        estado = None
+    config = getattr(renderer, 'config', None) or {}
+    params = []
+    if acao is not None:
+        from quantum.runtime.table_params import TableParamsError, params_of
+        try:
+            params = params_of(acao, config)
+        except TableParamsError as exc:
+            raise ValueError(f'<ui:form on-submit="{action_name}">: {exc}') from exc
+    inicial = {}
+    expressao = getattr(form_node, 'values', None)
+    if expressao:
+        linha = renderer._apply_databinding(expressao)
+        if isinstance(linha, list) and len(linha) == 1:
+            linha = linha[0]                                  # a q:query of one row
+        if linha not in (None, ''):
+            if not isinstance(linha, dict):
+                raise ValueError(f'<ui:form values="{expressao}"> needs a row (a record), '
+                                 f'got {type(linha).__name__} (UI-10)')
+            inicial = linha
+    return FormContext(params, estado, getattr(form_node, 'rules', None) != 'off', inicial, acao, config)
+
+
+def prepare_field(node, ctx: Optional[FormContext], escape: bool) -> Tuple[object, Optional[str]]:
+    """A copy of the field with the action's rules and the values sent, and its error.
+
+    `escape`: the HTML renderer writes attribute values as they are, so a
+    value sent back to the page is escaped here; the view tree is not (UI-3).
+    """
+    nome = getattr(node, 'bind', None)
+    if ctx is None or not nome:
+        return node, None
+    copia = copy.copy(node)
+    param = ctx.params.get(nome)
+    if param is not None:
+        if isinstance(copia, UIInputNode):
+            if param.required and not copia.required:
+                copia.required = True
+            for campo in ('minlength', 'maxlength'):
+                valor = getattr(param, campo, None)
+                if getattr(copia, campo) is None and valor is not None:
+                    setattr(copia, campo, int(valor))
+            for campo in ('min', 'max'):
+                valor = getattr(param, campo, None)
+                if getattr(copia, campo) is None and valor is not None:
+                    setattr(copia, campo, str(valor))
+            padrao = getattr(param, 'pattern', None) or ''
+            # The server searches (re.search); HTML's pattern must match the
+            # whole value. Only an anchored ^…$ pattern means the same in both.
+            if not copia.pattern and padrao.startswith('^') and padrao.endswith('$'):
+                copia.pattern = padrao[1:-1]
+            tipo = _HTML_TYPE.get(str(getattr(param, 'type', '') or '').lower())
+            if tipo and (copia.input_type or 'text') == 'text':
+                copia.input_type = tipo
+        elif isinstance(copia, (UISelectNode, UIRadioNode)):
+            if not copia.options and not getattr(copia, 'children', None) and getattr(param, 'enum', None):
+                copia.options = param.enum
+    if ctx.values is None and nome in ctx.initial:
+        # UI-10: an edit form opens with the row's value (unless the field sets its own).
+        inicial = ctx.initial[nome]
+        if isinstance(copia, (UICheckboxNode, UISwitchNode)):
+            if getattr(copia, 'checked', None) is None:
+                copia.checked = 'true' if inicial not in (None, '', 0, '0', False, 'false') else 'false'
+        elif getattr(copia, 'value', None) in (None, '') and inicial is not None                 and not (isinstance(copia, UIInputNode) and copia.input_type == 'password'):
+            copia.value = html.escape(str(inicial), quote=True) if escape else str(inicial)
+    if ctx.values is not None:
+        if isinstance(copia, (UICheckboxNode, UISwitchNode)):
+            # A browser sends a checked box and omits an unchecked one.
+            copia.checked = 'true' if nome in ctx.values else 'false'
+        elif nome in ctx.values and not (isinstance(copia, UIInputNode) and copia.input_type == 'password'):
+            valor = str(ctx.values[nome])
+            copia.value = html.escape(valor, quote=True) if escape else valor
+    erro = ctx.errors.get(nome)
+    if erro:
+        copia.ui_class = ((getattr(copia, 'ui_class', None) or '') + ' q-invalid').strip()
+    return copia, erro
+
+
+FORM_CSS = """
+/* UI-9: a field the server's validation refused, and its message */
+.q-invalid, .q-invalid input { border-color: var(--q-danger, #dc2626) !important; }
+.q-field-error { display: block; color: var(--q-danger, #dc2626); font-size: 13px; margin-top: 4px; }
+"""
+
+
+def has_fields(nodes) -> bool:
+    """Whether a form's markup already has fields of its own."""
+    for no in nodes or []:
+        if isinstance(no, FIELDS) or has_fields(getattr(no, 'children', None)):
+            return True
+    return False
+
+
+def has_button(nodes) -> bool:
+    from quantum.core.features.ui_engine.src.ast_nodes import UIButtonNode
+    for no in nodes or []:
+        if isinstance(no, UIButtonNode) or has_button(getattr(no, 'children', None)):
+            return True
+    return False
+
+
+def generated_fields(form_node, ctx: Optional[FormContext]) -> list:
+    """UI-10: a form with no fields draws one per param of its action, and a button."""
+    from quantum.core.features.ui_engine.src.ast_nodes import (
+        UIButtonNode, UIFormItemNode, UIOptionNode)
+    from quantum.runtime.table_params import humanize, reference_options
+    filhos = list(getattr(form_node, 'children', None) or [])
+    if ctx is None or not ctx.params or has_fields(filhos):
+        return filhos
+    gerados = []
+    for param in ctx.all_params:
+        rotulo = humanize(param.name)
+        if str(param.type).lower() == 'boolean':
+            campo = UICheckboxNode()
+            campo.bind, campo.label = param.name, rotulo
+            gerados.append(campo)
+            continue
+        referencia = getattr(param, 'references', None)
+        if referencia and ctx.action is not None:
+            campo = UISelectNode()
+            campo.bind = param.name
+            if not param.required:
+                vazio = UIOptionNode()
+                vazio.value, vazio.label = '', '—'
+                campo.children.append(vazio)
+            for valor, texto in reference_options(ctx.config, ctx.action.table_datasource, referencia):
+                opcao = UIOptionNode()
+                opcao.value, opcao.label = valor, texto
+                campo.children.append(opcao)
+        elif param.enum:
+            campo = UISelectNode()
+            campo.bind = param.name
+        else:
+            campo = UIInputNode()
+            campo.bind = param.name
+        item = UIFormItemNode()
+        item.label = rotulo
+        item.children.append(campo)
+        gerados.append(item)
+    if not has_button(filhos):
+        botao = UIButtonNode()
+        botao.content = getattr(form_node, 'submit', None) or 'Save'
+        botao.variant = 'primary'
+        gerados.append(botao)
+    return filhos + gerados
+