docs: pestañas de vars con data-field-group + infoLabels de uploads en builder-fields

docs/01-builder-fields.md

@@ -3,7 +3,7 @@ title: "Campos editables del builder"
 tags: [builder, twig, html, modules]
 load_priority: 80
 load_when: [always]
-summary: "Atributos data-field-* (textfield, headfield, link, upload, list, multiv2, checkbox), c-if/c-for/c-class, c-form, componentes built-in del builder Acai."
+summary: "Atributos data-field-* (textfield, headfield, link, upload, list, multiv2, checkbox), agrupar campos en pestañas con data-field-group, c-if/c-for/c-class, c-form, componentes built-in del builder Acai."
 ---
 # Builder Fields — Campos editables del index-base.tpl
 
@@ -108,7 +108,25 @@ Devuelve un array. Acceso en Twig: `{{ imagen[0].urlPath }}`.
 Atributos disponibles:
 - `data-lazy="true"` — carga perezosa
 - `data-field-width="1400"` — ancho máximo sugerido
-- `data-field-info1="titulo"` — campo de información adicional (típicamente alt)
+- `data-field-info1` … `data-field-info5` — labels de los campos de información por imagen
+
+Los `data-field-infoN` (hasta 5) definen los labels que el builder muestra como campos editables **en cada imagen subida** (van a `infoLabels` en el `builder.json`). Sus valores se leen luego como `info1`…`info4` dentro del array del var.
+
+```html
+<img data-field-type="upload"
+     data-field-label="Imagen Principal"
+     data-field-info1="Texto alternativo"
+     data-field-info2="Pie de foto"
+     data-field-width="1400"
+     alt="">
+```
+
+```twig
+<img src="{{ imagenprincipal[0].urlPath }}" alt="{{ imagenprincipal[0].info1 }}">
+<figcaption>{{ imagenprincipal[0].info2 }}</figcaption>
+```
+
+Los `data-field-infoN` funcionan igual en `uploadMulti`.
 
 ### uploadMulti
 
@@ -200,6 +218,41 @@ Devuelve `1` o `0` (número), nunca `true`/`false`.
 
 Devuelve un string hexadecimal (`#ff0000`). Almacenado en config-vars (no en `builder_custom`).
 
+## Agrupar campos en pestañas (`data-field-group`)
+
+Los campos de un módulo se reparten en pestañas dentro del panel de configuración añadiendo `data-field-group="Nombre del grupo"` al mismo elemento que ya lleva `data-field-type`.
+
+Mecanismo: cualquier atributo `data-field-*` extra —aparte de `data-field-type`, `data-field-label` y `data-field-value`— se recoge en el objeto `customDataField` del var, recortando el prefijo `data-field-`. Es decir, `data-field-group="Estilos"` acaba como `customDataField: { group: "Estilos" }` en el `builder.json`.
+
+Comportamiento del panel:
+- Los vars se agrupan por `customDataField.group` y se muestran en pestañas laterales.
+- Los vars sin `data-field-group` caen en la pestaña **Principal**.
+- El orden de las pestañas es el de primera aparición de cada grupo en el template.
+- Con un solo grupo no se muestran pestañas.
+- Funciona igual en vars de primer nivel y dentro de `multiv2`.
+
+```html
+<div data-field-type="textfield" data-field-label="Título" data-field-group="Contenido">
+  Título de la sección
+</div>
+<div data-field-type="textbox" data-field-label="Descripción" data-field-group="Contenido">
+  Texto de apoyo
+</div>
+
+<div c-hidden="true">
+  <div data-field-type="colorpicker" data-field-label="Color de fondo" data-field-group="Estilos"></div>
+  <div data-field-type="list"
+       data-field-label="Alineación"
+       data-list-options="|Izquierda,1|Centro,2|Derecha"
+       data-field-group="Estilos"></div>
+</div>
+```
+
+Recomendación de uso:
+- Agrupa cuando el módulo pase de ~6-8 vars; por debajo, una sola lista se lee mejor.
+- Reparto habitual: **Contenido** (textos e imágenes), **Estilos** (colores, alineación, bordes), **Ajustes** (opciones de comportamiento, límites, enlaces).
+- Mantén los nombres de grupo consistentes entre módulos y en español. Son literales: `Estilos` y `estilos` generan dos pestañas distintas.
+
 ## Atributos Acai
 
 ### `c-if` — Renderizado condicional