> ## 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.

# Peças da tela

> Todas as peças @ do Painel Dev, com atributos e exemplos: texto, número, interruptor, caixa de seleção, seletor de cor, tabela, cartão de número, aviso e botão.

A `tela.html` de uma função é montada com **peças**. Cada peça tem um nome curto com `@` (usado na Skill e no `componentes.md`) e uma marca `<dt-*>` que você escreve:

| Peça | Marca | Guarda um valor? |
| - | - | - |
| `@text` | `<dt-text />` | Sim |
| `@textarea` | `<dt-textarea />` | Sim |
| `@number` | `<dt-number />` | Sim |
| `@switch` | `<dt-switch />` | Sim |
| `@select` | `<dt-select>` + `<dt-option />` | Sim |
| `@color` | `<dt-color />` | Sim |
| `@table` | `<dt-table />` | Só mostra |
| `@stat` | `<dt-stat />` | Só mostra |
| `@alert` | `<dt-alert>texto</dt-alert>` | Não |
| `@button` | `<dt-button />` | Não |

As peças usam os mesmos componentes do site do DoglyTdc: a caixa de seleção e o seletor de cor são os do resto do painel, no tema claro e escuro.

## `bind`: de onde vem e para onde vai o valor

Toda peça que guarda ou mostra um valor precisa de `bind="campo"`. O campo é o nome do valor na resposta da ligação e no que é salvo.

* Nome: começa com letra; letras, números, `_`, `.` e `-`, até 64 caracteres.
* Com `connect.type: "config"`, o `bind` precisa estar em `connect.keys`.
* Com `connect.type: "collection"`, só `dt-table` e `dt-stat`.

## @text e @textarea

| Atributo | O que faz |
| - | - |
| `bind` | Obrigatório |
| `label` | Título do campo |
| `placeholder` | Texto de exemplo dentro do campo |
| `hint` | Dica pequena embaixo |

```html theme={null}
<dt-text bind="nome" label="Nome do evento" placeholder="Ex.: Semana do desconto" hint="Aparece no topo do popup." />
<dt-textarea bind="mensagem" label="Mensagem" placeholder="Escreva aqui…" />
```

`@text` aceita até 2.000 caracteres; `@textarea`, até 8.000.

## @number

| Atributo | O que faz |
| - | - |
| `bind`, `label`, `hint` | Como acima |
| `min`, `max`, `step` | Números (aceita negativo e decimal) |

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

Campo vazio é salvo como `null`.

## @switch

```html theme={null}
<dt-switch bind="ativo" label="Ligado" hint="Desligue para pausar o script para todos." />
```

Salva `true` ou `false`.

## @select — caixa de seleção

`<dt-select>` é a caixa; cada `<dt-option>` é uma opção. `<dt-option>` só funciona **dentro** de `<dt-select>` e precisa de `value` e `label`.

| Atributo | Em | O que faz |
| - | - | - |
| `bind` | `dt-select` | Obrigatório |
| `label` | `dt-select` | Título da caixa |
| `placeholder` | `dt-select` | Texto quando nada está escolhido (padrão: "Selecionar") |
| `hint` | `dt-select` | Dica embaixo |
| `value` | `dt-option` | O que é salvo (texto) |
| `label` | `dt-option` | O que a pessoa vê |

```html theme={null}
<dt-select bind="modo" label="Modo" placeholder="Escolha um modo" hint="Muda o comportamento do script.">
  <dt-option value="rapido" label="Rápido" />
  <dt-option value="natural" label="Natural" />
  <dt-option value="manual" label="Manual" />
</dt-select>
```

* O valor salvo é sempre **texto**, ex.: `"rapido"`.
* Valor padrão: devolva o campo na carga (`"modo": "natural"`) ou deixe-o já salvo na configuração.
* Com mais de 6 opções, a caixa ganha busca sozinha.
* Rótulos traduzidos: `label="@t.modo.rapido"`.

## @color — seletor de cor

```html theme={null}
<dt-color bind="cor_destaque" label="Cor de destaque" hint="Usada nos botões do script." />
```

| Atributo | O que faz |
| - | - |
| `bind` | Obrigatório |
| `label` | Título |
| `hint` | Dica embaixo |

* O valor é salvo como **hexadecimal de 6 dígitos**: `"#8b5cf6"`.
* Se o valor salvo não for nesse formato (ou não existir), o seletor começa em `#8b5cf6`.
* Para outro padrão, salve a cor antes na configuração ou devolva-a na carga.

No script, use o valor direto:

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

## @table

| Atributo | O que faz |
| - | - |
| `bind` | Obrigatório. Lista de objetos |
| `label` | Título |
| `columns` | Colunas na ordem, separadas por vírgula (até 10). Sem ele, as 6 primeiras, sem `id` |
| `empty` | Texto quando a lista está vazia |

```html theme={null}
<dt-table bind="lista" label="Cupons" columns="codigo,desconto,usos" empty="Nenhum cupom ainda." />
```

Com `connect.type: "collection"`, a tabela mostra os registros da coleção. Nos outros casos, mostra `values.<bind>` ou, se não for lista, `rows`.

## @stat

```html theme={null}
<dt-stat bind="vendas_mes" label="Vendas no mês" icon="trending" />
```

Mostra um número ou texto grande com ícone.

## @alert

```html theme={null}
<dt-alert tone="warning">Mudanças aqui valem para todos os usuários na hora.</dt-alert>
```

| `tone` | Uso |
| - | - |
| `info` (padrão) | Informação |
| `success` | Deu certo |
| `warning` | Atenção |
| `danger` | Perigo |

`icon` opcional troca o ícone.

## @button

| Atributo | O que faz |
| - | - |
| `action` | Obrigatório: `@save`, `@reload` ou `@call:nome` |
| `label` | Obrigatório |
| `tone` | `primary` (padrão), `ghost` ou `danger` |
| `icon` | Opcional |

```html theme={null}
<footer>
  <dt-button action="@reload" label="Recarregar" tone="ghost" icon="refresh" />
  <dt-button action="@call:limpar" label="Limpar tudo" tone="danger" icon="trash" />
  <dt-button action="@save" label="Salvar" icon="check" />
</footer>
```

| Ação | O que faz | Funciona com |
| - | - | - |
| `@save` | Envia todos os valores da tela | `config`, `function` |
| `@reload` | Carrega de novo | todos |
| `@call:nome` | Chama a ação `nome` da função do servidor | só `function` |

## Organização

Para arrumar a tela use: `section`, `div`, `header`, `footer`, `h2`, `h3`, `h4`, `p`, `span`, `strong`, `small` e `hr`, com `class` opcional.

| Classe | Efeito |
| - | - |
| `dt-stack` | Itens um embaixo do outro |
| `dt-row` | Itens lado a lado, que quebram no celular |
| `dt-grid` | Grade de cartões pequenos (ótima para `dt-stat`) |
| `dt-card` | Caixa com borda e sombra |
| `dt-muted` | Texto mais claro |

Outras classes são ignoradas.

## O que é proibido

* JavaScript, `<script>`, `<style>`, `style=""` e `on…=""`.
* Links, imagens e iframes.
* Elementos fora da lista e atributos que a peça não tem.
* Mais de 250 elementos, 12 níveis ou 32 KB por tela.

Os erros dizem o arquivo e o motivo, ex.: `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.