quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/ui_page_renderer.py

@@ -0,0 +1,392 @@
+"""`ui:*` inside a served page (UI-1, PLANO_V1.md U1).
+
+The UI Engine used to be a separate world: `<q:application type="ui">`
+compiled to a file, where each target translated the page's logic on its own.
+Here the page's runtime does the logic — queries, actions, the SPEC's rules —
+and this class only draws: it reuses the HTML adapter's drawing of each
+`ui:*` element and hands everything else (q:loop, q:if, HTML, components)
+back to the page renderer.
+
+What changes from the standalone adapter:
+
+- `{expressions}` are resolved by the page's runtime, and every resolved value
+  is HTML-escaped (the adapter's builder escapes nothing).
+- Events are actions: `<ui:button on-click="save">` posts to the page's
+  `q:action name="save"`; `with="id={row.id}"` adds fields to that post.
+  `<ui:form on-submit="create">` is a form that posts its fields to `create`.
+  An event that names no q:action of the page is an error.
+- The adapter's CSS for the elements comes once per page, without its global
+  reset (the page keeps its own styles).
+"""
+
+import copy
+import html
+from typing import Any, Iterator, List, Optional
+
+from quantum.core.features.ui_engine.src import ast_nodes as ui_nodes
+from quantum.runtime.ui_html_adapter import UIHtmlAdapter
+from quantum.runtime.ui_form_rules import FORM_CSS, form_context, generated_fields, prepare_field
+from quantum.runtime.ui_html_templates import CSS_THEME, RESPONSIVE_CSS, HtmlBuilder
+from quantum.runtime.ui_pager import PAGER_CSS, pager_items
+from quantum.runtime.ui_table_edit import CELL_CSS, cell_field, edit_plan, sort_link
+from quantum.core.xml_lines import tag_error
+
+# Attributes that name an action or a field, never text to resolve. `source`
+# is data (a list), resolved by source_rows().
+_NOT_TEXT = {'on_click', 'on_submit', 'on_change', 'on_select', 'bind', 'children', 'send', 'source',
+             'values'}
+
+
+is_ui_node = ui_nodes.is_ui_node
+
+
+def source_rows(page, node, where: str, default_var: str) -> Iterator[Any]:
+    """UI-5: once per row of a `source="{...}"`, with the row variable set as
+    q:loop sets it (`row`, and `row.field` for dict rows). A source that is not
+    a list is an error — never an empty table."""
+    fonte = (node.source or '').strip()
+    linhas = page._apply_databinding(fonte) if fonte.startswith('{') and fonte.endswith('}') else None
+    if not isinstance(linhas, list):
+        tipo = 'no {expression}' if linhas is None and not fonte.startswith('{') else type(linhas).__name__
+        raise ValueError(
+            f'<{where} source="{fonte}"> needs a list — a q:query or an array, as '
+            f'source="{{rows}}" — and got {tipo} (UI-5).')
+    var = node.as_var or default_var
+    ctx = page.context
+    originais = ctx.local_vars.copy()
+    try:
+        for linha in linhas:
+            ctx.set_variable(var, linha, scope='local')
+            if isinstance(linha, dict):
+                for campo, valor in linha.items():
+                    ctx.set_variable(f'{var}.{campo}', valor, scope='local')
+            yield linha
+    finally:
+        ctx.local_vars = originais
+
+
+def _single_name(expr) -> Optional[str]:
+    import re as _re
+    m = _re.fullmatch(r'\s*\{\s*(\w+)\s*\}\s*', expr or '')
+    return m.group(1) if m else None
+
+
+def cell_value(linha: Any, coluna) -> str:
+    """UI-5: the text of a `<ui:column key>` cell; a key the row lacks is an error."""
+    if not isinstance(linha, dict):
+        return '' if linha is None else str(linha)
+    if coluna.key not in linha:
+        raise ValueError(
+            f'<ui:column key="{coluna.key}"> (UI-5): the row has no field "{coluna.key}" '
+            f'(fields: {", ".join(map(str, linha)) or "none"}).')
+    valor = linha[coluna.key]
+    return '' if valor is None else str(valor)
+
+
+class UIPageRenderer(UIHtmlAdapter):
+
+    def __init__(self, page, action_names: List[str]):
+        super().__init__()
+        self._page = page
+        self._actions = set(action_names)
+
+    # -- entry -------------------------------------------------------------
+
+    def render(self, node) -> str:
+        b = HtmlBuilder()
+        self._render_node(node, b)
+        return b.build()
+
+    @staticmethod
+    def css() -> str:
+        return CSS_THEME + '\n' + RESPONSIVE_CSS + '\n' + FORM_CSS + '\n' + PAGER_CSS + '\n' + CELL_CSS
+
+    # -- dispatch ----------------------------------------------------------
+
+    def _render_node_ui(self, node, b: HtmlBuilder):
+        try:
+            if is_ui_node(node):
+                super()._render_node(self._resolved(node), b)
+            else:
+                b.raw(self._page.render(node))
+        except Exception as exc:
+            # DEV-2: the innermost ui:* element that failed names its line.
+            tag_error(exc, node)
+            raise
+
+    def _render_children(self, children: list, b: HtmlBuilder):
+        for child in children:
+            self._render_node(child, b)
+
+    def _resolved(self, node):
+        """A copy of the node with every `{expression}` resolved and escaped."""
+        copia = copy.copy(node)
+        for nome, valor in vars(node).items():
+            if nome in _NOT_TEXT or not isinstance(valor, str) or '{' not in valor:
+                continue
+            resolvido = self._page._apply_databinding(valor)
+            setattr(copia, nome, html.escape('' if resolvido is None else str(resolvido), quote=True))
+        return copia
+
+    # -- events are actions ------------------------------------------------
+
+    def _action(self, nome: str, onde: str) -> str:
+        nome = (nome or '').strip()
+        if nome.endswith('()'):
+            nome = nome[:-2]
+        if nome not in self._actions:
+            disponiveis = ', '.join(sorted(self._actions)) or 'none'
+            raise ValueError(
+                f'{onde}="{nome}" names no q:action of this page (UI-1; actions: {disponiveis}). '
+                f'Inside a page, a ui:* event is a q:action.')
+        return nome
+
+    def _hidden_fields(self, b: HtmlBuilder, acao: str, envio: str = None):
+        b.open_tag('input', {'type': 'hidden', 'name': 'action', 'value': acao}, self_closing=True)
+        if envio:
+            resolvido = str(self._page._apply_databinding(envio))
+            for par in resolvido.split(','):
+                if '=' not in par:
+                    continue
+                campo, valor = (p.strip() for p in par.split('=', 1))
+                b.open_tag('input', {'type': 'hidden', 'name': html.escape(campo, quote=True),
+                                     'value': html.escape(valor, quote=True)}, self_closing=True)
+
+    def _render_button(self, node, b: HtmlBuilder):
+        if not node.on_click:
+            return super()._render_button(node, b)
+        acao = self._action(node.on_click, '<ui:button on-click')
+        b.open_tag('form', {'method': 'post', 'class': 'q-action', 'style': 'display: inline'})
+        b.indent()
+        self._hidden_fields(b, acao, getattr(node, 'send', None))
+        semeventos = copy.copy(node)
+        semeventos.on_click = None
+        super()._render_button(semeventos, b)
+        b.dedent()
+        b.close_tag('form')
+
+    def _render_form(self, node, b: HtmlBuilder):
+        attrs = {'class': 'q-form', 'method': 'post'}
+        b.open_tag('form', self._merge_attrs(attrs, self._layout_attrs(node)))
+        b.indent()
+        acao = None
+        if node.on_submit:
+            acao = self._action(node.on_submit, '<ui:form on-submit')
+            self._hidden_fields(b, acao, getattr(node, 'send', None))
+        anterior = getattr(self, '_form_ctx', None)
+        self._form_ctx = form_context(self._page, node, acao)       # UI-9
+        try:
+            self._render_children(generated_fields(node, self._form_ctx), b)   # UI-10
+        finally:
+            self._form_ctx = anterior
+        b.dedent()
+        b.close_tag('form')
+
+    # -- fields take the action's rules, the values sent back, their error (UI-9)
+
+    def _field(self, desenhar, node, b: HtmlBuilder):
+        copia, erro = prepare_field(node, getattr(self, '_form_ctx', None), escape=True)
+        desenhar(copia, b)
+        if erro:
+            b.open_tag('span', {'class': 'q-field-error', 'role': 'alert'})
+            b.text(html.escape(erro))
+            b.close_tag('span')
+
+    def _render_input(self, node, b: HtmlBuilder):
+        if getattr(node, 'search', None):
+            return self._render_search(node, b)
+        self._field(super()._render_input, node, b)
+
+    # -- search as you type (UI-12) -------------------------------------------
+
+    def _render_search(self, node, b: HtmlBuilder):
+        """A GET form around the field: Enter searches without JavaScript; with
+        htmx, each pause in typing asks for the same page and swaps only the
+        target region. The other URL parameters are kept; `page` is not (a new
+        search starts on page 1)."""
+        if getattr(self, '_form_ctx', None) is not None:
+            raise ValueError(f'<ui:input bind="{node.bind}" search=...> cannot be inside a ui:form: '
+                             f'it is a form of its own (a GET search) (UI-12)')
+        alvo = node.search
+        self._page._search_targets = getattr(self._page, '_search_targets', set()) | {alvo}
+        contexto = self._page.context
+        caminho = (getattr(contexto, 'request_vars', None) or {}).get('path') or ''
+        try:
+            atuais = contexto.get_variable('query')
+        except Exception:
+            atuais = None
+        atuais = atuais if isinstance(atuais, dict) else {}
+        campo = copy.copy(node)
+        if campo.value in (None, ''):
+            valor = atuais.get(node.bind)
+            campo.value = html.escape(str(valor), quote=True) if valor not in (None, '') else None
+        campo.input_type = 'search' if (campo.input_type or 'text') == 'text' else campo.input_type
+        b.open_tag('form', {'method': 'get', 'role': 'search', 'class': 'q-search',
+                            'action': html.escape(caminho, quote=True)})
+        b.indent()
+        for nome, valor in atuais.items():
+            if nome in (node.bind, 'page'):
+                continue
+            b.open_tag('input', {'type': 'hidden', 'name': html.escape(str(nome), quote=True),
+                                 'value': html.escape(str(valor), quote=True)}, self_closing=True)
+        interno = HtmlBuilder()
+        super()._render_input(campo, interno)
+        hx = (f'hx-get="{html.escape(caminho, quote=True)}" '
+              f'hx-trigger="input changed delay:{int(node.delay)}ms, search" '
+              f'hx-target="#{html.escape(alvo, quote=True)}" hx-select="#{html.escape(alvo, quote=True)}" '
+              f'hx-swap="outerHTML" hx-push-url="true" hx-include="closest form" ')
+        b.raw(interno.build().replace('<input ', f'<input {hx}', 1))
+        b.dedent()
+        b.close_tag('form')
+
+    def _render_select(self, node, b: HtmlBuilder):
+        self._field(super()._render_select, node, b)
+
+    def _render_radio(self, node, b: HtmlBuilder):
+        self._field(super()._render_radio, node, b)
+
+    def _render_checkbox(self, node, b: HtmlBuilder):
+        self._field(super()._render_checkbox, node, b)
+
+    def _render_switch(self, node, b: HtmlBuilder):
+        self._field(super()._render_switch, node, b)
+
+    # -- <ui:pager> (UI-11) ----------------------------------------------------
+
+    def _render_node(self, node, b: HtmlBuilder):
+        if isinstance(node, ui_nodes.UIPagerNode):
+            try:
+                return self._render_pager(node, b)
+            except Exception as exc:
+                tag_error(exc, node)
+                raise
+        return self._render_node_ui(node, b)
+
+    def _render_pager(self, node, b: HtmlBuilder):
+        itens = pager_items(self._page, node)
+        if not itens:
+            return
+        b.open_tag('nav', self._merge_attrs({'class': 'q-pager', 'aria-label': 'Pages'}, self._layout_attrs(node)))
+        for item in itens:
+            if item['href']:
+                b.open_tag('a', {'href': html.escape(item['href'], quote=True),
+                                 'aria-label': item['aria'], 'class': f"q-page-{item['kind']}"})
+                b.text(html.escape(item['label']))
+                b.close_tag('a')
+            else:
+                classe = ('q-page-current' if item['current'] else
+                          'q-page-gap' if item['kind'] == 'gap' else 'q-page-disabled')
+                atributos = {'class': classe}
+                if item['current']:
+                    atributos['aria-current'] = 'page'
+                b.open_tag('span', atributos)
+                b.text(html.escape(item['label']))
+                b.close_tag('span')
+        b.close_tag('nav')
+
+    # -- a section is a titled group, open (UI-7) ------------------------------
+
+    def _render_section(self, node, b: HtmlBuilder):
+        # The standalone build draws a collapsed <details>: in a page its
+        # content was hidden in the browser and shown in the console.
+        b.open_tag('section', self._merge_attrs({'class': 'q-section-group'}, self._layout_attrs(node)))
+        b.indent()
+        if node.title:
+            b.open_tag('div', {'class': 'q-section-title'})
+            b.text(node.title)
+            b.close_tag('div')
+        self._render_children(node.children, b)
+        b.dedent()
+        b.close_tag('section')
+
+    # -- data: source="{rows}" -----------------------------------------------
+
+    def _render_table(self, node, b: HtmlBuilder):
+        if not node.source:
+            return super()._render_table(node, b)
+        colunas = [c for c in node.children if isinstance(c, ui_nodes.UIColumnNode)]
+        if getattr(node, 'sort', False):
+            self._check_sortable(node)
+        plano = edit_plan(self._page, node)                                    # UI-13
+        estado = getattr(self._page, 'form_state', None)
+        b.open_tag('table', self._merge_attrs({'class': 'q-table'}, self._layout_attrs(node)))
+        b.indent()
+        b.open_tag('thead')
+        b.open_tag('tr')
+        for coluna in colunas:
+            estilo = f'text-align: {coluna.align}' if coluna.align else None
+            b.open_tag('th', {'style': estilo} if estilo else None)
+            rotulo = html.escape(coluna.label or coluna.key or '')
+            if getattr(node, 'sort', False) and coluna.key and not coluna.children:
+                href, marca = sort_link(self._page, coluna.key)
+                b.open_tag('a', {'href': html.escape(href, quote=True), 'class': 'q-sort'})
+                b.text(rotulo + (f' {marca}' if marca else ''))
+                b.close_tag('a')
+            else:
+                b.text(rotulo)
+            b.close_tag('th')
+        b.close_tag('tr')
+        b.close_tag('thead')
+        b.open_tag('tbody')
+        b.indent()
+        for linha in source_rows(self._page, node, 'ui:table', 'row'):
+            b.open_tag('tr')
+            for coluna in colunas:
+                estilo = f'text-align: {coluna.align}' if coluna.align else None
+                b.open_tag('td', {'style': estilo} if estilo else None)
+                if coluna.children:
+                    self._render_children(coluna.children, b)
+                elif plano and coluna.key in plano['columns']:
+                    self._render_cell_edit(plano, plano['columns'][coluna.key], linha, estado, b)
+                else:
+                    b.text(html.escape(cell_value(linha, coluna)))
+                b.close_tag('td')
+            b.close_tag('tr')
+        b.dedent()
+        b.close_tag('tbody')
+        b.dedent()
+        b.close_tag('table')
+
+    def _check_sortable(self, node):
+        nome = _single_name(node.source)
+        consulta = (getattr(self._page, '_query_nodes', None) or {}).get(nome)
+        if consulta is not None and not getattr(consulta, 'sortable', False):
+            raise ValueError(f'<ui:table sort="true" source="{node.source}">: the query "{nome}" needs '
+                             f'sortable="true" to order by a column in SQL (UI-13)')
+
+    def _render_cell_edit(self, plano, coluna_schema, linha, estado, b: HtmlBuilder):
+        """UI-13: a cell is a small form that posts to the generated __edit action."""
+        campo, ocultos, erro = cell_field(plano, coluna_schema, linha, estado, escape=True)
+        b.open_tag('form', {'method': 'post', 'class': 'q-cell'})
+        for nome, valor in ocultos.items():
+            b.open_tag('input', {'type': 'hidden', 'name': nome, 'value': html.escape(valor, quote=True)},
+                       self_closing=True)
+        anterior = getattr(self, '_form_ctx', None)
+        self._form_ctx = None                  # the field is prepared already
+        try:
+            super()._render_node(campo, b)
+        finally:
+            self._form_ctx = anterior
+        b.open_tag('button', {'class': 'q-cell-save', 'aria-label': f'Save {coluna_schema.name}'})
+        b.text('✓')
+        b.close_tag('button')
+        b.close_tag('form')
+        if erro:
+            b.open_tag('span', {'class': 'q-field-error', 'role': 'alert'})
+            b.text(html.escape(erro))
+            b.close_tag('span')
+
+    def _render_list(self, node, b: HtmlBuilder):
+        if not node.source:
+            return super()._render_list(node, b)
+        b.open_tag('ul', self._merge_attrs({'class': 'q-list'}, self._layout_attrs(node)))
+        b.indent()
+        for linha in source_rows(self._page, node, 'ui:list', 'item'):
+            if node.children:
+                self._render_children(node.children, b)
+            else:
+                b.open_tag('li')
+                b.text(html.escape('' if linha is None else str(linha)))
+                b.close_tag('li')
+        b.dedent()
+        b.close_tag('ul')

quantum/runtime/ui_pager.py

@@ -0,0 +1,73 @@
+"""<ui:pager for="query"> — pages over a paginated query (M14, UI-11).
+
+The query is `paginate="true"` (DB-2); its page is the URL's `page` parameter
+(DB-9). The pager draws previous, the page numbers around the current one —
+first and last always, a gap where pages are skipped — and next, as links to
+the same page with the other URL parameters kept. The browser and the console
+draw the same items.
+"""
+
+from typing import Dict, List, Optional
+from urllib.parse import urlencode
+
+
+def _pagination(renderer, node) -> dict:
+    nome = node.for_query
+    try:
+        resultado = renderer.context.get_variable(f'{nome}_result')
+    except Exception:
+        resultado = None
+    if isinstance(resultado, dict) and isinstance(resultado.get('pagination'), dict):
+        return resultado['pagination']
+    raise ValueError(
+        f'<ui:pager for="{nome}">: there is no paginated q:query named "{nome}" on this page '
+        f'(it needs paginate="true" and page_size) (UI-11)')
+
+
+def _href(renderer, param: str, pagina: int) -> str:
+    contexto = renderer.context
+    caminho = (getattr(contexto, 'request_vars', None) or {}).get('path') or ''
+    try:
+        atuais = contexto.get_variable('query')
+    except Exception:
+        atuais = None
+    parametros = {k: v for k, v in (atuais or {}).items() if k != param} if isinstance(atuais, dict) else {}
+    parametros[param] = str(pagina)
+    return f'{caminho}?{urlencode(parametros)}'
+
+
+def pager_items(renderer, node) -> List[Dict]:
+    """The pager's items: {'kind': prev|page|gap|next, 'label', 'href' (None if not a link), 'current'}."""
+    pag = _pagination(renderer, node)
+    total = int(pag.get('totalPages') or 0)
+    atual = int(pag.get('currentPage') or 1)
+    if total <= 1:
+        return []
+    janela = max(0, int(node.window))
+    paginas = sorted({1, total} | set(range(max(1, atual - janela), min(total, atual + janela) + 1)))
+    itens: List[Dict] = [{'kind': 'prev', 'label': '‹', 'aria': 'Previous page',
+                          'href': _href(renderer, node.param, atual - 1) if atual > 1 else None,
+                          'current': False}]
+    anterior: Optional[int] = None
+    for n in paginas:
+        if anterior is not None and n > anterior + 1:
+            itens.append({'kind': 'gap', 'label': '…', 'href': None, 'current': False, 'aria': ''})
+        itens.append({'kind': 'page', 'label': str(n), 'aria': f'Page {n}', 'current': n == atual,
+                      'href': None if n == atual else _href(renderer, node.param, n)})
+        anterior = n
+    itens.append({'kind': 'next', 'label': '›', 'aria': 'Next page',
+                  'href': _href(renderer, node.param, atual + 1) if atual < total else None,
+                  'current': False})
+    return itens
+
+
+PAGER_CSS = """
+/* UI-11: <ui:pager> */
+.q-pager { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; margin: 8px 0; }
+.q-pager a, .q-pager span { min-width: 32px; padding: 4px 8px; text-align: center; border-radius: 6px;
+  border: 1px solid var(--q-border, #d0d7de); text-decoration: none; color: inherit; }
+.q-pager a:hover { background: var(--q-surface-hover, #f3f4f6); }
+.q-pager .q-page-current { background: var(--q-primary, #2563eb); border-color: var(--q-primary, #2563eb); color: #fff; }
+.q-pager .q-page-disabled { opacity: .45; }
+.q-pager .q-page-gap { border: none; }
+"""

quantum/runtime/ui_table_edit.py

@@ -0,0 +1,139 @@
+"""A table that sorts and edits itself (M16, UI-13).
+
+`<ui:table source="{tarefas}" sort="true">` — each header is a link that
+orders the query in SQL (`q:query sortable="true"`, by the URL's ?sort= and
+?dir=), so it works with pagination.
+
+`<ui:table source="{tarefas}" edit="tarefas" datasource="db">` — each shown
+column of that table (not the key, not a column with `edit="false"`) is a
+small form in its cell. It posts to an action the page does not write:
+`__edit`, handled by the server (web_server._edit_cell), which accepts only a
+table and column this page declares editable, validates the value with the
+column's rules from the schema (UI-10) and updates one row by its key. What it
+does shows in /_dev like any action.
+"""
+
+import copy
+import html
+from typing import Dict, List, Optional
+from urllib.parse import urlencode
+
+EDIT_ACTION = '__edit'
+
+
+def _query_params(renderer) -> dict:
+    try:
+        atuais = renderer.context.get_variable('query')
+    except Exception:
+        atuais = None
+    return atuais if isinstance(atuais, dict) else {}
+
+
+def _path(renderer) -> str:
+    return (getattr(renderer.context, 'request_vars', None) or {}).get('path') or ''
+
+
+def sort_link(renderer, chave: str):
+    """(href, marker) of a header: the next order for this column, and ▲/▼ if it is the current one."""
+    atuais = _query_params(renderer)
+    atual, direcao = atuais.get('sort'), str(atuais.get('dir') or 'asc').lower()
+    proxima = 'desc' if atual == chave and direcao == 'asc' else 'asc'
+    parametros = {k: v for k, v in atuais.items() if k not in ('sort', 'dir', 'page')}
+    parametros.update({'sort': chave, 'dir': proxima})
+    marca = ('▲' if direcao == 'asc' else '▼') if atual == chave else ''
+    return f'{_path(renderer)}?{urlencode(parametros)}', marca
+
+
+def edit_plan(renderer, table_node) -> Optional[dict]:
+    """For an editable table: the key column and, per editable column key, its schema column."""
+    if not getattr(table_node, 'edit', None):
+        return None
+    from quantum.core.features.ui_engine.src.ast_nodes import UIColumnNode
+    from quantum.runtime.table_params import TableParamsError, columns_of
+    config = getattr(renderer, 'config', None) or {}
+    try:
+        colunas = {c.name: c for c in columns_of(config, table_node.edit_datasource, table_node.edit)}
+    except TableParamsError as exc:
+        raise ValueError(f'<ui:table edit="{table_node.edit}">: {exc} (UI-13)') from exc
+    chaves = [c for c in colunas.values() if c.primary_key]
+    if len(chaves) != 1:
+        raise ValueError(f'<ui:table edit="{table_node.edit}">: the table needs one primary key column '
+                         f'to know which row a cell is (UI-13)')
+    editaveis = {}
+    for coluna in table_node.children:
+        if isinstance(coluna, UIColumnNode) and coluna.key and coluna.edit and not coluna.children:
+            if coluna.key in colunas and not colunas[coluna.key].primary_key:
+                editaveis[coluna.key] = colunas[coluna.key]
+    return {'table': table_node.edit, 'key': chaves[0].name, 'columns': editaveis}
+
+
+def cell_field(plano: dict, coluna_schema, linha: dict, estado: Optional[dict], escape: bool):
+    """The field of one cell (with the column's rules), its hidden fields, and its error."""
+    from quantum.core.features.ui_engine.src.ast_nodes import UICheckboxNode, UIInputNode, UISelectNode
+    from quantum.runtime.table_params import param_from_column
+    from quantum.runtime.ui_form_rules import FormContext, prepare_field
+    chave = plano['key']
+    if chave not in linha:
+        raise ValueError(f'<ui:table edit=...>: the rows need the key column "{chave}" '
+                         f'(add it to the query\'s SELECT) (UI-13)')
+    param = param_from_column(coluna_schema)
+    param.name = 'value'
+    if str(param.type) == 'boolean':
+        campo = UICheckboxNode()
+    elif param.enum:
+        campo = UISelectNode()
+    else:
+        campo = UIInputNode()
+    campo.bind = 'value'
+    campo.ui_id = f'cell-{coluna_schema.name}-{linha.get(plano["key"])}'   # one id per cell
+    atual = linha.get(coluna_schema.name)
+    identidade = f'{coluna_schema.name}@{linha[chave]}'
+    erros, enviados = {}, None
+    if estado and estado.get('action') == EDIT_ACTION and estado.get('cell') == identidade:
+        erros, enviados = estado.get('errors') or {}, estado.get('values') or {}
+    ctx = FormContext([param], {'errors': erros, 'values': enviados} if enviados is not None else None,
+                      True, {'value': atual})
+    campo, erro = prepare_field(campo, ctx, escape)
+    ocultos = {'action': EDIT_ACTION, '__table': plano['table'], '__key': str(linha[chave]),
+               '__column': coluna_schema.name}
+    return campo, ocultos, erro
+
+
+CELL_CSS = """
+/* UI-13: a cell edited in place */
+.q-cell { display: flex; gap: 4px; align-items: center; margin: 0; }
+.q-cell .q-input, .q-cell .q-select { min-width: 0; padding: 2px 6px; }
+.q-cell-save { padding: 2px 8px; border: 1px solid var(--q-border, #d0d7de); border-radius: 6px;
+  background: transparent; cursor: pointer; }
+.q-sort { color: inherit; text-decoration: none; }
+.q-sort:hover { text-decoration: underline; }
+"""
+
+
+def _walk(nodes):
+    for node in nodes or []:
+        yield node
+        for campo in ('statements', 'children', 'body', 'if_body', 'else_body'):
+            yield from _walk(getattr(node, campo, None))
+        for bloco in getattr(node, 'elseif_blocks', None) or []:
+            yield from _walk(bloco.get('body') if isinstance(bloco, dict) else getattr(bloco, 'body', None))
+
+
+def find_editable_table(ast, tabela: str, coluna: str):
+    """The <ui:table edit="tabela"> of this page that shows `coluna` as editable, or None.
+
+    The server edits only what the page declares: a post naming another table
+    or column — a forged form — finds nothing and is refused."""
+    from quantum.core.features.ui_engine.src.ast_nodes import UIColumnNode, UITableNode
+    for node in _walk(getattr(ast, 'statements', None)):
+        if isinstance(node, UITableNode) and node.edit == tabela:
+            for filho in node.children:
+                if isinstance(filho, UIColumnNode) and filho.key == coluna and filho.edit and not filho.children:
+                    return node
+    return None
+
+
+def query_nodes(ast) -> Dict[str, object]:
+    """The page's q:query nodes by name (a sortable table checks its query)."""
+    from quantum.core.ast_nodes import QueryNode
+    return {n.name: n for n in _walk(getattr(ast, 'statements', None)) if isinstance(n, QueryNode)}