xonecode 0.1.0

package/skills/xone-development/references/xml-ui/contents-y-macros.md

@@ -0,0 +1,392 @@
+# XOne XML — Nodo contents y macros
+
+> Fuente: `xone/v2/xone-help-docs/topics/02c-xml-contents-patrones.md` §6–§7. Referencia de la skill; el índice está en [../../SKILL.md](../../SKILL.md).
+
+Contenido: §6 contents: vinculación con type=Z, filtros dinámicos ##FLD_CAMPO##, asfilter · §7 macros: macros del sistema, setMacro/getMacro y declaración del nodo macro
+
+---
+
+## 6. Nodo contents - Contenido Embebido
+
+### 6.1 Sintaxis y atributos
+
+El nodo `<contents>` define una relación padre-hijo entre colecciones. Permite embeber una lista de registros dentro de otra pantalla.
+
+```xml
+<contents name="@NombreContent"
+          src="NombreColeccionHija"
+          filter="CAMPO=VALOR"
+          sort="CAMPO ASC" />
+```
+
+| Atributo | Tipo | Requerido | Descripción |
+|----------|------|-----------|-------------|
+| `name` | string | **Si** | Nombre del content, con prefijo `@` |
+| `src` | string | **Si** | Nombre de la coleccion fuente (la coleccion hija) |
+| `filter` | string | No | Filtro SQL para los registros |
+| `sort` | string | No | Ordenamiento de los registros |
+
+### 6.2 Vinculacion con prop type=Z
+
+Un `<contents>` por si solo no muestra nada. Necesita estar vinculado a un `<prop type="Z">`:
+
+```xml
+<!-- Prop que muestra la lista -->
+<prop name="MAP_LISTA" type="Z" visible="1"
+      contents="@MiContent"
+      viewmode="recyclerview"
+      width="100%" height="60%"
+      edit-inrow="true" />
+
+<!-- Contents que define la fuente de datos -->
+<contents name="@MiContent" src="ColeccionHija" />
+```
+
+### 6.3 Patron maestro-detalle
+
+El patron más común es mostrar una lista (maestro) donde cada item abre un detalle:
+
+```xml
+<coll name="ListaPedidos" notab="true"
+      sql="SELECT * FROM ##PREF##Pedidos"
+      objname="Pedidos" loadall="true">
+    <group name="Lista" id="1">
+        <!-- Campos visibles en la lista (visible="4" para content) -->
+        <prop name="NUMERO" type="T" visible="4" />
+        <prop name="FECHA" type="D" visible="4" />
+        <prop name="TOTAL" type="N2" visible="4" />
+
+        <!-- Campos visibles solo en edicion -->
+        <prop name="CLIENTE" type="T" visible="1" title="Cliente" />
+        <prop name="ESTADO" type="T" visible="1" title="Estado" />
+
+        <!-- Lista de lineas del pedido -->
+        <prop name="MAP_LINEAS" type="Z" visible="1"
+              contents="@LineasPedido"
+              viewmode="recyclerview"
+              width="100%" height="300p"
+              edit-inrow="true" />
+    </group>
+
+    <contents name="@LineasPedido" src="LineasPedido"
+              filter="ID_PEDIDO=##FLD_ID##" />
+
+    <selecteditem>
+        <action name="runscript">
+            <script>
+                ui.openEditView(self);
+            </script>
+        </action>
+    </selecteditem>
+</coll>
+```
+
+### 6.4 Filtros dinámicos con ##FLD_CAMPO##
+
+La macro `##FLD_CAMPO##` permite filtrar el content basandose en el valor de un campo del registro padre:
+
+```xml
+<!-- Filtra por el ID del registro actual -->
+<contents name="@Detalles" src="Detalles"
+          filter="ID_PADRE=##FLD_ID##" />
+
+<!-- Filtro complejo con fecha -->
+<contents name="Calendariodatos" src="ContentCalendarioLista"
+          filter="strftime('%m',##FLD_MAP_FECHA##)=strftime('%m',FECHA)
+                  and strftime('%Y',##FLD_MAP_FECHA##)=strftime('%Y',FECHA)" />
+
+<!-- Filtro con campo de chat -->
+<contents name="Chatear" src="Chatear"
+          filter="IDCHAT=##FLD_MAP_CHATSEL##" />
+
+<!-- Filtro con usuario actual -->
+<contents name="nUsuarios" src="UsuariosChat"
+          filter="ID<>##USERID##" />
+
+<!-- Filtro complejo con multiples condiciones -->
+<contents name="ContentDatosFiltroMultiseleccion"
+          src="ContentDatosFiltroMultiseleccion"
+          filter="((t1.MARCADO=1 AND 1=##FLD_MAP_BUSCAR_MARCADOS##)
+                   OR (t1.MARCADO=0 AND 1=##FLD_MAP_BUSCAR_NOMARCADOS##))
+                  AND (ifnull(t1.NOMBRE,'') LIKE ##FLD_MAP_BUSCAR_TEXT##)" />
+```
+
+### 6.5 Ejemplos reales
+
+**Ejemplo de contents con edición directa** (del wiki, EspecialContents.xne):
+
+```xml
+<frame name="c1" width="98%" height="78%"
+       framebox="true" border-corner-radius="10" lmargin="1%" tmargin="2%">
+    <prop name="MAP_content1" height="96%" type="Z"
+          contents="content1"
+          forceonchange="true"
+          bgcolor="#FFFFFF"
+          onchange="refresh(@content1)" />
+    <contents name="content1" src="ContentDatos" />
+</frame>
+```
+
+**Ejemplo de contents con edición en fila**:
+
+```xml
+<frame name="c2" width="98%" height="75%"
+       framebox="true" border-corner-radius="10" lmargin="1%" tmargin="2%">
+    <prop name="@content2" height="96%" type="Z"
+          contents="content2"
+          mask="0"
+          edit-inrow="true"
+          bgcolor="#FFFFFF" />
+    <contents name="content2" src="ContentDatosEditRow" />
+</frame>
+```
+
+**Manipulación de contents desde JavaScript** (ver Tópico 03):
+
+```javascript
+// Obtener un content
+var coll = self.getContents("content1");
+
+// Crear un nuevo objeto
+var obj = coll.createObject();
+obj.NOMBRE = "Nuevo registro";
+obj.DIRECCION = "Dirección nueva";
+
+// Agregar a la lista (al final)
+let view = ui.getView(self);
+view.MAP_content1.addItem(obj);
+
+// Agregar en una posicion concreta: 2o parametro opcional con el indice.
+// Sincroniza lista y datos; el indice se acota al rango valido (negativo -> primer
+// elemento; mayor que el total -> al final). Devuelve la vista de la fila insertada.
+view.MAP_content1.addItem(obj, 0);   // insertar como primer elemento
+
+// Filtrar un content
+self.getContents("content4").setFilter("NOMBRE like '%texto%'");
+self.getContents("content4").loadAll();
+ui.getView(self).refresh("@content4");
+
+// Ordenar un content
+self.getContents("content4").sort = "NOMBRE ASC";
+self.getContents("content4").loadAll();
+```
+
+### 6.6 Nodo asfilter - Filtros de Busqueda en Listas
+
+El nodo `<asfilter>` define campos de busqueda que permiten al usuario filtrar los registros de una coleccion directamente desde la interfaz. Se declara como hijo directo de `<coll>` y genera automáticamente una barra de busqueda con los campos especificados.
+
+```xml
+<asfilter fontsize="8" left="12" sort="false">
+    <field name="NUMCOMPLETO" fldname="NUMCOMPLETO"
+           oper="##FLD## LIKE '##VAL##%'" width="15"
+           tooltip="Albaran" newline="false">ALBARAN</field>
+    <field name="FECHA" fldname="FECHA"
+           oper="##FLD## >= '##VAL##'" width="10"
+           tooltip="Fecha desde">FECHA DESDE</field>
+</asfilter>
+```
+
+**Atributos de `<asfilter>`:**
+
+| Atributo | Descripción |
+|----------|-------------|
+| `fontsize` | Tamaño de fuente de los campos del filtro |
+| `left` | Margen izquierdo del panel de filtro |
+| `sort` | Habilita ordenamiento en el filtro (`true`/`false`) |
+
+**Atributos de `<field>` dentro de `<asfilter>`:**
+
+| Atributo | Descripción |
+|----------|-------------|
+| `name` | Nombre del campo de filtro |
+| `fldname` | Nombre del campo real en la tabla de base de datos |
+| `oper` | Operador SQL. Usa `##FLD##` para el nombre del campo y `##VAL##` para el valor ingresado por el usuario |
+| `width` | Ancho del campo de filtro |
+| `tooltip` | Texto de ayuda / placeholder del campo |
+| `newline` | Si es `false`, se coloca en la misma linea que el campo anterior |
+
+**Ejemplo básico de busqueda por nombre:**
+
+```xml
+<asfilter>
+    <field name="BUSCAR" fldname="NOMBRE"
+           oper="##FLD## LIKE '%##VAL##%'" width="20"
+           tooltip="Buscar por nombre">BUSCAR</field>
+</asfilter>
+```
+
+> **Nota:** El contenido de texto del nodo `<field>` (ej. `BUSCAR`, `ALBARAN`) se usa como etiqueta visible del campo de filtro. La macro `##FLD##` se reemplaza por el valor de `fldname` y `##VAL##` por lo que el usuario escribe.
+
+---
+
+## 7. Nodo macro - Variables
+
+### 7.1 Definición y uso
+
+Las macros en XOne son variables que se resuelven en tiempo de ejecución. Se usan con la sintaxis `##NOMBRE##` tanto en atributos XML como en consultas SQL.
+
+### 7.2 Macros del sistema
+
+| Macro | Descripción | Uso típico |
+|-------|-------------|------------|
+| `##PREF##` | Prefijo de tablas en BD (ej: `gen_`) | Consultas SQL |
+| `##ENTID##` | ID de la empresa/entidad actual | Filtros por empresa |
+| `##USERID##` | ID del usuario logueado | Filtros por usuario |
+| `##VERSION##` | Versión de la aplicación | Pantallas "Acerca de" |
+| `##FRAME_VERSION##` | Versión del framework XOne | Información de sistema |
+| `##APP##` | Ruta de la carpeta de la aplicación | Rutas de imágenes |
+| `##EXIT##` | Comando para salir de la pantalla actual (con `appData.failWithMessage(-11888, ...)`). Para cerrar la app entera usar `appData.exit()` | Evento onback |
+| `##NOW_TIME##` | Hora actual del sistema | Timestamps |
+
+**Ejemplo de uso en SQL**:
+```xml
+<coll name="MisRegistros"
+      sql="SELECT * FROM ##PREF##Registros WHERE USUARIO_ID = ##USERID##">
+```
+
+**Ejemplo de uso en ruta de imagen**:
+```xml
+<prop name="ICONO" type="IMG" path="##APP##\icons\xone.png" />
+```
+
+**Ejemplo de uso en create**:
+```xml
+<create>
+    <action name="setval" field="MAP_VERSION"
+            value="Versión ##VERSION## - Framework ##FRAME_VERSION##" />
+</create>
+```
+
+### 7.3 Macros de campo (##FLD_CAMPO##)
+
+Las macros `##FLD_CAMPO##` se resuelven al valor actual del campo especificado. Son útiles en:
+
+- Filtros de contents
+- Colores dinámicos
+- Textos dinámicos en atributos
+
+```xml
+<!-- Color de fondo dinámico basado en un campo -->
+<prop name="MAP_LABEL" type="L"
+      bgcolor="##FLD_MAP_COLOR1##"
+      forecolor="##FLD_MAP_COLOR2##" />
+
+<!-- Imagen dinámica basada en un campo -->
+<prop name="BTORDENAR" type="B"
+      img="##FLD_MAP_BTORDEN##"
+      imgsel="##FLD_MAP_BTORDENCLICK##" />
+
+<!-- Título dinámico -->
+<prop name="lblOrigen" type="L"
+      title="##FLD_MAP_ORIGEN##" />
+
+<!-- Filtro de contents con campo del padre -->
+<contents name="@Detalles" src="Detalles"
+          filter="ID_PADRE=##FLD_ID##" />
+```
+
+### 7.4 Macros de animación
+
+| Macro | Descripción |
+|-------|-------------|
+| `##ALPHA_IN##` | Fade in (aparece) |
+| `##ALPHA_OUT##` | Fade out (desaparece) |
+| `##ZOOM_IN##` | Zoom in (agranda) |
+| `##ZOOM_OUT##` | Zoom out (reduce) |
+| `##LEFT_IN##` | Entrada desde la izquierda |
+| `##LEFT_OUT##` | Salida hacia la izquierda |
+| `##RIGHT_IN##` | Entrada desde la derecha |
+| `##RIGHT_OUT##` | Salida hacia la derecha |
+| `##TOP_IN##` | Entrada desde arriba |
+| `##BOTTOM_IN##` | Entrada desde abajo |
+
+**Uso en frames animados**:
+
+```xml
+<frame name="frmnuevochat"
+       animation-in-delay="250"
+       animation-out-delay="250"
+       animation-in="##RIGHT_IN##"
+       animation-out="##LEFT_OUT##"
+       disablevisible="MAP_VERFLOTANTE=0"
+       floating="true" top="0" left="0"
+       width="100%" height="100%">
+```
+
+**Uso en navegación entre grupos**:
+
+```javascript
+ui.showGroup(2, "##ALPHA_IN##", 500, "##ALPHA_OUT##", 500);
+```
+
+### 7.5 Macros de coleccion — Nodo XML `<macro>` + API `setMacro`/`getMacro`
+
+Las macros de coleccion permiten **parametrizar el SQL de una `<coll>`** (en `sql`, `filter`, subconsultas, etc.) y cambiar su valor en tiempo de ejecución desde JavaScript. Son la herramienta principal para filtros dinámicos por interaccion del usuario (ej: cambiar el filtro de una lista cuando se selecciona un combo).
+
+> **No confundir con `appData.setGlobalMacro` / `getGlobalMacro`**: las macros globales son variables de aplicación (equivalentes a `localStorage` en navegador) y se leen desde cualquier punto. Las macros de coll viven dentro de **una sola coleccion** y solo afectan al SQL de esa coll. Ver también la API JavaScript en el tópico 03.
+
+#### Declaración en el XML — nodo `<macro>`
+
+Para que una macro de coll funcione, **debe declararse explicitamente** dentro de la `<coll>`. El nodo `<macro>` se coloca **al mismo nivel que los nodos `<group>`** (es decir, hijo directo de `<coll>`, no anidado dentro de un `<group>` ni de un `<frame>`).
+
+Sintaxis:
+
+```xml
+<macro name="##NOMBRE##" value="valor por defecto" default="true" />
+```
+
+| Atributo | Descripción |
+|----------|-------------|
+| `name`   | Nombre de la macro con dobles `##...##`. Libre (ej. `##TIPO##`, `##FILTRO##`, `##MACRO1##`). Es el token que se sustituira en el SQL. |
+| `value`  | Valor por defecto. Puede ser un literal (`"1"`, `"abc"`) o un fragmento SQL completo (ej. `"1=1"`, `"FILTRO='A'"`, una subconsulta entera). XOne lo inyecta tal cual en la consulta. |
+| `default`| `true` o `false`. Indica si la macro se aplica desde el inicio (con su `value` por defecto). **Convencion: poner siempre `default="true"`** salvo que tengas una razón explicita para lo contrario. |
+
+#### Ejemplo completo (declaración + uso en SQL + cambio desde JS)
+
+```xml
+<?xml version="1.0" encoding="iso-8859-15"?>
+<coll name="ListaControles"
+      progid="ASData.CASBasicDataObj"
+      sql="SELECT ID, TITULO, FILTRO FROM ##PREF##CONTROLES WHERE ##TIPO##"
+      objname="Controles"
+      loadall="true">
+
+    <!-- Declaracion de macros: al mismo nivel que los <group>, NO dentro de ninguno -->
+    <macro name="##TIPO##" value="1=1" default="true" />
+
+    <group name="General" id="1">
+        <prop name="TITULO"  type="T"  visible="7" />
+        <prop name="FILTRO"  type="T"  visible="7" />
+    </group>
+</coll>
+```
+
+Y desde JavaScript, en un `onchange` de un combo de la pantalla padre:
+
+```javascript
+// CORRECTO: setMacro / getMacro
+var coll = self.getContents("content1");
+if (self.TIPO == "TODOS") {
+    coll.setMacro("##TIPO##", "1=1");
+} else {
+    coll.setMacro("##TIPO##", "FILTRO='" + self.TIPO.toString() + "'");
+}
+ui.refresh();
+```
+
+> **API correcta:** `setMacro("##NOMBRE##", valor)` y `getMacro("##NOMBRE##")`. **NUNCA** `coll.macro(...)` — esa forma no existe en XOne.
+
+#### Casos de uso típicos
+
+- Filtrar una lista por un valor de combo/segmented control.
+- Cambiar la query SELECT entera de un content en función del estado de la pantalla padre (`coll.setMacro("##TIPO##", "SELECT ID, TITULO, FILTRO FROM GEN_CONTROLES WHERE FILTRO='" + valor + "'")`).
+- Habilitar/deshabilitar un fragmento del WHERE poniendo la macro a `"1=1"` (todo) o a una clausula concreta.
+
+#### Diferencias con `##FLD_CAMPO##`
+
+| | `<macro>` + `setMacro` | `##FLD_CAMPO##` |
+|---|---|---|
+| Donde se define | Nodo `<macro>` en la coll + JS imperativo | En el `filter`/SQL del content directamente |
+| Quien la cambia | Código JS llamando a `setMacro` | XOne automáticamente al cambiar el campo padre |
+| Caso típico | Filtro dinámico por interaccion del usuario | Maestro-detalle (sub-content filtrado por el padre) |
+

package/skills/xone-development/references/xml-ui/errores-comunes-xml.md

@@ -0,0 +1,245 @@
+# XOne XML — Errores comunes a evitar
+
+> Fuente: `xone/v2/xone-project-generator/references/xone-xml-ui-e-mapas-errores.md` §14. Referencia de la skill; el índice está en [../../SKILL.md](../../SKILL.md).
+
+Contenido: §14 errores comunes de XML y su corrección
+
+---
+
+## 14. Errores Comunes a Evitar
+
+### Error 1: Usar CSS Web Estándar
+
+```css
+/* INCORRECTO */
+prop { font-size: 14px; margin-top: 10px; }
+
+/* CORRECTO */
+prop { fontsize: 14; tmargin: 10p; }
+```
+
+### Error 2: Olvidar ##PREF## en SQL
+
+```xml
+<!-- INCORRECTO -->
+<coll sql="SELECT * FROM Productos">
+
+<!-- CORRECTO -->
+<coll sql="SELECT * FROM ##PREF##Productos">
+```
+
+### Error 3: Tipos No Validos
+
+```xml
+<!-- INCORRECTO -->
+<prop name="NOMBRE" type="STRING" />
+
+<!-- CORRECTO -->
+<prop name="NOMBRE" type="T" />
+```
+
+### Error 4: Sin objname para Persistencia
+
+```xml
+<!-- NO SE PERSISTE -->
+<coll name="Productos">
+
+<!-- SE PERSISTE -->
+<coll name="Productos" objname="Productos">
+```
+
+### Error 5: APIs Web en JavaScript
+
+```javascript
+// INCORRECTO
+document.getElementById("campo").value = "test";
+localStorage.setItem("key", "value");
+
+// CORRECTO
+self.MAP_CAMPO = "test";
+appData.setGlobalMacro("KEY", "value");
+```
+
+### Error 6: Todas las Colecciones en mappings.xne
+
+mappings.xne solo debe contener Empresas y Usuarios. Las demas colecciones van en archivos `.xne` separados.
+
+### Error 7: Campos Obligatorios Faltantes
+
+Empresas necesita: `CODIGO`, `NOMBRE`, `ROWID`
+Usuarios necesita: `CODIGO`, `NOMBRE`, `IDEMPRESA`, `LOGIN`, `PWD`, `ROWID`
+
+### Error 8: Prefijo Diferente a "gen" Sin Autorización
+
+Siempre usar `prefix="gen"` a menos que el usuario lo solicite explicitamente.
+
+### Error 9: Falta @ en name del Contents
+
+```xml
+<!-- INCORRECTO -->
+<contents name="MiContenido" src="MiColeccion" />
+
+<!-- CORRECTO -->
+<contents name="@MiContenido" src="MiColeccion" />
+```
+
+El `@` va siempre en el `name` del nodo `<contents>` y en el atributo `contents` del `<prop type="Z">` que lo referencia.
+
+### Error 10: Sintaxis de Otros Frameworks
+
+No usar HTML (`<div>`, `<input>`), ni sintaxis React/Angular/Vue. Usar siempre nodos XOne (`<frame>`, `<prop>`, `<coll>`).
+
+### Error 11: progid incorrecto en Empresas / Usuarios
+
+`progid` es **opcional**: si se omite, la coll se comporta como un objeto de datos genérico (equivalente a `ASData.CASBasicDataObj`). El error real es **olvidar el progid propio en las colecciones especiales** Empresas y Usuarios, que lo necesitan para activar su lógica de negocio:
+
+```xml
+<!-- INCORRECTO: Empresas/Usuarios sin su progid propio -->
+<coll name="Empresas" objname="empresa" ...>
+<coll name="Usuarios" objname="usuarios" ...>
+
+<!-- CORRECTO -->
+<coll name="Empresas" objname="empresa" progid="ASGestion.CASEmpresa" ...>
+<coll name="Usuarios" objname="usuarios" progid="ASGestion.CASUser" ...>
+```
+
+Valores:
+- (omitido) o `ASData.CASBasicDataObj` — cualquier coleccion de negocio genérica
+- `ASGestion.CASEmpresa` — coleccion Empresas, en mappings.xne
+- `ASGestion.CASUser` — coleccion Usuarios, en mappings.xne
+
+### Error 12: Encoding incoherente en ficheros XNE
+
+El motor respeta el `encoding` declarado en el prólogo del `.xne` (y asume UTF-8 si no se declara). UTF-8 e `iso-8859-15` son **ambos válidos**. El error real es la **discrepancia**: declarar un encoding distinto de cómo está realmente guardado el fichero, lo que corrompe tildes y ñ.
+
+```xml
+<!-- INCORRECTO: declara iso-8859-15 pero el fichero está guardado como UTF-8 (o al revés) -->
+<?xml version="1.0" encoding="iso-8859-15"?>   <!-- ...y los bytes son UTF-8: tildes/ñ corruptas -->
+
+<!-- CORRECTO: el encoding declarado coincide con cómo se guarda el fichero -->
+<?xml version="1.0" encoding="utf-8"?>          <!-- fichero realmente guardado en UTF-8 -->
+```
+
+### Error 13: Estructura Incorrecta de mappings.xne
+
+```xml
+<!-- INCORRECTO: collprops no existe en XOne -->
+<xml>
+    <collprops type="general">
+        <coll name="Empresas" ...>
+
+<!-- CORRECTO: las colecciones van directamente dentro de <xml> -->
+<xml>
+    <app .../>
+    <coll name="Empresas" progid="ASGestion.CASEmpresa" ...>
+    <coll name="Usuarios" progid="ASGestion.CASUser" ...>
+</xml>
+```
+
+### Error 14: filter y sort dentro del SQL
+
+```xml
+<!-- INCORRECTO: el filtro dentro del SQL no es gestionado por el framework -->
+<coll sql="SELECT * FROM ##PREF##Productos WHERE ACTIVO=1 ORDER BY NOMBRE">
+
+<!-- CORRECTO: filter y sort como atributos separados del nodo coll -->
+<coll sql="SELECT t1.* FROM ##PREF##Productos t1"
+      filter="ACTIVO=1"
+      sort="NOMBRE ASC">
+```
+
+### Error 15: Evento del Calendario con Guion
+
+```xml
+<!-- INCORRECTO -->
+<ondate-selected>
+    <script>self.FECHA = e.selectedDate;</script>
+</ondate-selected>
+
+<!-- CORRECTO: sin guion, y el parametro es DATEVALUE (no e.selectedDate) -->
+<ondateselected>
+    <action name="runscript">
+        <param name="DATEVALUE" />
+        <script language="javascript">
+            self.MAP_FECHA_SEL = DATEVALUE;
+        </script>
+    </action>
+</ondateselected>
+```
+
+### Error 16: Usar APIs del DOM en JavaScript
+
+XOne no es HTML y no ejecuta código en un navegador. Estas APIs del DOM **no existen** en el entorno XOne y causarán errores:
+
+```javascript
+// INCORRECTO — APIs del DOM, no existen en XOne
+document.getElementById("campo").value = "hola";
+document.querySelector(".clase").style.display = "none";
+window.location.href = "otraPantalla";
+localStorage.setItem("clave", "valor");
+sessionStorage.getItem("clave");
+navigator.geolocation.getCurrentPosition(cb);
+history.back();
+
+// CORRECTO — usar las APIs propias de XOne (idiomáticas)
+self.MAP_CAMPO = "hola";                          // escribir en campo
+ui.openEditView("OtraPantalla");                  // navegar (forma corta: XOne crea el dataObject internamente)
+appData.setGlobalMacro("CLAVE", "valor");         // almacenar globalmente
+appData.getGlobalMacro("CLAVE");                  // recuperar valor global
+$http.get("https://api.ejemplo.com/datos", ...);  // petición HTTP idiomática
+ui.startGps(...);                                 // GPS
+
+// TAMBIÉN funcionan — implementación custom XOne, semántica spec-compatible
+fetch("https://api.ejemplo.com/datos").then(r => r.json());  // alternativa a $http
+new Promise((resolve, reject) => { resolve(42); });           // Promise ES2024
+setTimeout(() => doIt(), 1000);                               // ms (no segundos)
+```
+
+### Error 17: Nombres de nodos duplicados dentro de una coleccion
+
+**Esta es una restricción crítica de la plataforma XOne.** Dentro de una `<coll>`, cada nodo con atributo `name` debe tener un nombre único en su ambito. Tampoco puede haber dos `<coll>` con el mismo nombre en el proyecto.
+
+```xml
+<!-- INCORRECTO: dos <group> con el mismo name -->
+<coll name="MiPantalla" special="true">
+    <group name="grpPrincipal" id="1">...</group>
+    <group name="grpPrincipal" id="2">...</group>  <!-- ERROR -->
+</coll>
+
+<!-- INCORRECTO: dos <prop> con el mismo name -->
+<group name="grpDatos" id="1">
+    <prop name="NOMBRE" type="T" visible="7"/>
+    <prop name="NOMBRE" type="L" visible="2"/>    <!-- ERROR -->
+</group>
+
+<!-- INCORRECTO: dos <frame> con el mismo name -->
+<group name="grpPrincipal" id="1">
+    <frame name="frmBody" width="100%" height="200p"/>
+    <frame name="frmBody" width="100%" height="-2"/> <!-- ERROR -->
+</group>
+
+<!-- INCORRECTO: dos eventos del mismo tipo -->
+<coll name="MiPantalla" special="true">
+    <before-edit>...</before-edit>
+    <before-edit>...</before-edit>                 <!-- ERROR -->
+</coll>
+
+<!-- CORRECTO: todos los nombres son unicos en su ambito -->
+<coll name="MiPantalla" special="true">
+    <before-edit>...</before-edit>
+    <group name="grpPrincipal" id="1">
+        <frame name="frmHeader" width="100%" height="100p"/>
+        <frame name="frmBody"   width="100%" height="-2"/>
+        <prop name="MAP_TITULO"    type="L" visible="7"/>
+        <prop name="MAP_SUBTITULO" type="L" visible="7"/>
+    </group>
+    <group name="grpSecundario" id="2">...</group>
+</coll>
+```
+
+**Lo que SI es valido:** dos `<coll>` con distinto `name` pero contenido identico. La restricción es sobre el nombre, no sobre el contenido.
+
+---
+
+*Documento de referencia generado a partir de las knowledgebases del proyecto XOneAI, la base de conocimiento estructurada (docs/kb/) y el análisis de 572 archivos .xne de 224 proyectos reales.*
+