> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doglytdc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Piezas de la pantalla

> Todas las piezas @ del Panel Dev, con atributos y ejemplos: texto, número, interruptor, caja de selección, selector de color, tabla, tarjeta de número, aviso y botón.

La `tela.html` de una función se arma con **piezas**. Cada pieza tiene un nombre corto con `@` (usado en la Skill y en `componentes.md`) y una etiqueta `<dt-*>` que tú escribes:

| Pieza | Etiqueta | ¿Guarda un valor? |
| - | - | - |
| `@text` | `<dt-text />` | Sí |
| `@textarea` | `<dt-textarea />` | Sí |
| `@number` | `<dt-number />` | Sí |
| `@switch` | `<dt-switch />` | Sí |
| `@select` | `<dt-select>` + `<dt-option />` | Sí |
| `@color` | `<dt-color />` | Sí |
| `@table` | `<dt-table />` | Solo muestra |
| `@stat` | `<dt-stat />` | Solo muestra |
| `@alert` | `<dt-alert>texto</dt-alert>` | No |
| `@button` | `<dt-button />` | No |

Las piezas usan los mismos componentes del sitio de DoglyTdc: la caja de selección y el selector de color son los del resto del panel, en tema claro y oscuro.

## `bind`: de dónde viene y adónde va el valor

Toda pieza que guarda o muestra un valor necesita `bind="campo"`. El campo es el nombre del valor en la respuesta de la conexión y en lo que se guarda.

* Nombre: empieza con letra; letras, números, `_`, `.` y `-`, hasta 64 caracteres.
* Con `connect.type: "config"`, el `bind` tiene que estar en `connect.keys`.
* Con `connect.type: "collection"`, solo `dt-table` y `dt-stat`.

## @text y @textarea

| Atributo | Qué hace |
| - | - |
| `bind` | Obligatorio |
| `label` | Título del campo |
| `placeholder` | Texto de ejemplo dentro del campo |
| `hint` | Pista pequeña debajo |

```html theme={null}
<dt-text bind="nome" label="Nombre del evento" placeholder="Ej.: Semana del descuento" hint="Aparece arriba del popup." />
<dt-textarea bind="mensagem" label="Mensaje" placeholder="Escribe aquí…" />
```

`@text` acepta hasta 2.000 caracteres; `@textarea`, hasta 8.000.

## @number

| Atributo | Qué hace |
| - | - |
| `bind`, `label`, `hint` | Como arriba |
| `min`, `max`, `step` | Números (acepta negativos y decimales) |

```html theme={null}
<dt-number bind="limite" label="Usos por día" min="0" max="1000" step="10" />
```

Un campo vacío se guarda como `null`.

## @switch

```html theme={null}
<dt-switch bind="ativo" label="Activado" hint="Apágalo para pausar el script para todos." />
```

Guarda `true` o `false`.

## @select — caja de selección

`<dt-select>` es la caja; cada `<dt-option>` es una opción. `<dt-option>` solo funciona **dentro** de `<dt-select>` y necesita `value` y `label`.

| Atributo | En | Qué hace |
| - | - | - |
| `bind` | `dt-select` | Obligatorio |
| `label` | `dt-select` | Título de la caja |
| `placeholder` | `dt-select` | Texto cuando no hay nada elegido (por defecto: "Selecionar") |
| `hint` | `dt-select` | Pista debajo |
| `value` | `dt-option` | Lo que se guarda (texto) |
| `label` | `dt-option` | Lo que ve la persona |

```html theme={null}
<dt-select bind="modo" label="Modo" placeholder="Elige un modo" hint="Cambia el comportamiento del script.">
  <dt-option value="rapido" label="Rápido" />
  <dt-option value="natural" label="Natural" />
  <dt-option value="manual" label="Manual" />
</dt-select>
```

* El valor guardado siempre es **texto**, ej.: `"rapido"`.
* Valor por defecto: devuelve el campo en la carga (`"modo": "natural"`) o déjalo ya guardado en la configuración.
* Con más de 6 opciones, la caja gana búsqueda sola.
* Etiquetas traducidas: `label="@t.modo.rapido"`.

## @color — selector de color

```html theme={null}
<dt-color bind="cor_destaque" label="Color de acento" hint="Usado en los botones del script." />
```

| Atributo | Qué hace |
| - | - |
| `bind` | Obligatorio |
| `label` | Título |
| `hint` | Pista debajo |

* El valor se guarda como **hexadecimal de 6 dígitos**: `"#8b5cf6"`.
* Si el valor guardado no tiene ese formato (o no existe), el selector empieza en `#8b5cf6`.
* Para otro valor por defecto, guarda el color antes en la configuración o devuélvelo en la carga.

En el script, usa el valor directamente:

```js theme={null}
const color = window.DoglyScript.config.cor_destaque || "#8b5cf6";
```

## @table

| Atributo | Qué hace |
| - | - |
| `bind` | Obligatorio. Lista de objetos |
| `label` | Título |
| `columns` | Columnas en orden, separadas por coma (hasta 10). Sin él, las 6 primeras, sin `id` |
| `empty` | Texto cuando la lista está vacía |

```html theme={null}
<dt-table bind="lista" label="Cupones" columns="codigo,desconto,usos" empty="Todavía no hay cupones." />
```

Con `connect.type: "collection"`, la tabla muestra los registros de la colección. En los demás casos, muestra `values.<bind>` o, si no es una lista, `rows`.

## @stat

```html theme={null}
<dt-stat bind="vendas_mes" label="Ventas del mes" icon="trending" />
```

Muestra un número o texto grande con icono.

## @alert

```html theme={null}
<dt-alert tone="warning">Los cambios aquí valen para todos los usuarios al instante.</dt-alert>
```

| `tone` | Uso |
| - | - |
| `info` (por defecto) | Información |
| `success` | Salió bien |
| `warning` | Atención |
| `danger` | Peligro |

`icon` opcional cambia el icono.

## @button

| Atributo | Qué hace |
| - | - |
| `action` | Obligatorio: `@save`, `@reload` o `@call:nombre` |
| `label` | Obligatorio |
| `tone` | `primary` (por defecto), `ghost` o `danger` |
| `icon` | Opcional |

```html theme={null}
<footer>
  <dt-button action="@reload" label="Recargar" tone="ghost" icon="refresh" />
  <dt-button action="@call:limpar" label="Borrar todo" tone="danger" icon="trash" />
  <dt-button action="@save" label="Guardar" icon="check" />
</footer>
```

| Acción | Qué hace | Funciona con |
| - | - | - |
| `@save` | Envía todos los valores de la pantalla | `config`, `function` |
| `@reload` | Vuelve a cargar | todos |
| `@call:nombre` | Llama a la acción `nombre` de la función del servidor | solo `function` |

## Organización

Para ordenar la pantalla usa: `section`, `div`, `header`, `footer`, `h2`, `h3`, `h4`, `p`, `span`, `strong`, `small` y `hr`, con `class` opcional.

| Clase | Efecto |
| - | - |
| `dt-stack` | Elementos uno debajo del otro |
| `dt-row` | Elementos lado a lado, que bajan en el celular |
| `dt-grid` | Cuadrícula de tarjetas pequeñas (ideal para `dt-stat`) |
| `dt-card` | Caja con borde y sombra |
| `dt-muted` | Texto más claro |

Otras clases se ignoran.

## Lo que está prohibido

* JavaScript, `<script>`, `<style>`, `style=""` y `on…=""`.
* Enlaces, imágenes e iframes.
* Elementos fuera de la lista y atributos que la pieza no tiene.
* Más de 250 elementos, 12 niveles o 32 KB por pantalla.

Los errores indican el archivo y el motivo, ej.: `Elemento não permitido: <img>`, `<dt-select> precisa de bind="campo".`, `bind="cor" não está em connect.keys.`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.