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

# Screen pieces

> Every @ piece of the Dev panel, with attributes and examples: text, number, switch, select box, color picker, table, stat card, alert and button.

A function's `tela.html` is built with **pieces**. Each piece has a short `@` name (used in the Skill and in `componentes.md`) and a `<dt-*>` tag you write:

| Piece | Tag | Holds a value? |
| - | - | - |
| `@text` | `<dt-text />` | Yes |
| `@textarea` | `<dt-textarea />` | Yes |
| `@number` | `<dt-number />` | Yes |
| `@switch` | `<dt-switch />` | Yes |
| `@select` | `<dt-select>` + `<dt-option />` | Yes |
| `@color` | `<dt-color />` | Yes |
| `@table` | `<dt-table />` | Display only |
| `@stat` | `<dt-stat />` | Display only |
| `@alert` | `<dt-alert>text</dt-alert>` | No |
| `@button` | `<dt-button />` | No |

The pieces use the same components as the DoglyTdc site: the select box and color picker are the ones from the rest of the panel, in light and dark themes.

## `bind`: where the value comes from and goes to

Every piece that holds or shows a value needs `bind="field"`. The field is the value's name in the connection's reply and in what gets saved.

* Name: starts with a letter; letters, numbers, `_`, `.` and `-`, up to 64 characters.
* With `connect.type: "config"`, the `bind` must be in `connect.keys`.
* With `connect.type: "collection"`, only `dt-table` and `dt-stat`.

## @text and @textarea

| Attribute | What it does |
| - | - |
| `bind` | Required |
| `label` | Field title |
| `placeholder` | Sample text inside the field |
| `hint` | Small hint below |

```html theme={null}
<dt-text bind="nome" label="Event name" placeholder="E.g. Discount week" hint="Shown at the top of the popup." />
<dt-textarea bind="mensagem" label="Message" placeholder="Write here…" />
```

`@text` accepts up to 2,000 characters; `@textarea`, up to 8,000.

## @number

| Attribute | What it does |
| - | - |
| `bind`, `label`, `hint` | As above |
| `min`, `max`, `step` | Numbers (negative and decimal allowed) |

```html theme={null}
<dt-number bind="limite" label="Uses per day" min="0" max="1000" step="10" />
```

An empty field is saved as `null`.

## @switch

```html theme={null}
<dt-switch bind="ativo" label="On" hint="Turn off to pause the script for everyone." />
```

Saves `true` or `false`.

## @select — select box

`<dt-select>` is the box; each `<dt-option>` is an option. `<dt-option>` only works **inside** `<dt-select>` and needs `value` and `label`.

| Attribute | On | What it does |
| - | - | - |
| `bind` | `dt-select` | Required |
| `label` | `dt-select` | Box title |
| `placeholder` | `dt-select` | Text when nothing is chosen (default: "Select") |
| `hint` | `dt-select` | Hint below |
| `value` | `dt-option` | What is saved (text) |
| `label` | `dt-option` | What the person sees |

```html theme={null}
<dt-select bind="modo" label="Mode" placeholder="Choose a mode" hint="Changes how the script behaves.">
  <dt-option value="rapido" label="Fast" />
  <dt-option value="natural" label="Natural" />
  <dt-option value="manual" label="Manual" />
</dt-select>
```

* The saved value is always **text**, e.g. `"rapido"`.
* Default value: return the field on load (`"modo": "natural"`) or keep it saved in the configuration.
* With more than 6 options, the box gets search automatically.
* Translated labels: `label="@t.modo.rapido"`.

## @color — color picker

```html theme={null}
<dt-color bind="cor_destaque" label="Accent color" hint="Used on the script's buttons." />
```

| Attribute | What it does |
| - | - |
| `bind` | Required |
| `label` | Title |
| `hint` | Hint below |

* The value is saved as a **6-digit hex**: `"#8b5cf6"`.
* If the saved value is not in that format (or missing), the picker starts at `#8b5cf6`.
* For another default, save the color in the configuration first or return it on load.

In the script, use the value directly:

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

## @table

| Attribute | What it does |
| - | - |
| `bind` | Required. List of objects |
| `label` | Title |
| `columns` | Columns in order, comma-separated (up to 10). Without it, the first 6, without `id` |
| `empty` | Text when the list is empty |

```html theme={null}
<dt-table bind="lista" label="Coupons" columns="codigo,desconto,usos" empty="No coupons yet." />
```

With `connect.type: "collection"`, the table shows the collection's records. Otherwise it shows `values.<bind>` or, if that is not a list, `rows`.

## @stat

```html theme={null}
<dt-stat bind="vendas_mes" label="Sales this month" icon="trending" />
```

Shows a big number or text with an icon.

## @alert

```html theme={null}
<dt-alert tone="warning">Changes here apply to every user right away.</dt-alert>
```

| `tone` | Use |
| - | - |
| `info` (default) | Information |
| `success` | It worked |
| `warning` | Attention |
| `danger` | Danger |

Optional `icon` changes the icon.

## @button

| Attribute | What it does |
| - | - |
| `action` | Required: `@save`, `@reload` or `@call:name` |
| `label` | Required |
| `tone` | `primary` (default), `ghost` or `danger` |
| `icon` | Optional |

```html theme={null}
<footer>
  <dt-button action="@reload" label="Reload" tone="ghost" icon="refresh" />
  <dt-button action="@call:limpar" label="Clear all" tone="danger" icon="trash" />
  <dt-button action="@save" label="Save" icon="check" />
</footer>
```

| Action | What it does | Works with |
| - | - | - |
| `@save` | Sends every value on the screen | `config`, `function` |
| `@reload` | Loads again | all |
| `@call:name` | Calls the `name` action of the server function | `function` only |

## Layout

To arrange the screen use: `section`, `div`, `header`, `footer`, `h2`, `h3`, `h4`, `p`, `span`, `strong`, `small` and `hr`, with optional `class`.

| Class | Effect |
| - | - |
| `dt-stack` | Items one below the other |
| `dt-row` | Items side by side, wrapping on phones |
| `dt-grid` | Grid of small cards (great for `dt-stat`) |
| `dt-card` | Box with border and shadow |
| `dt-muted` | Lighter text |

Other classes are ignored.

## What is not allowed

* JavaScript, `<script>`, `<style>`, `style=""` and `on…=""`.
* Links, images and iframes.
* Elements outside the list and attributes the piece does not have.
* More than 250 elements, 12 levels or 32 KB per screen.

Errors give the file and the reason, e.g. `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.