# Tucano

> Componentes de formulário e interface para a web, para Django, Laravel, Rails
> ou qualquer back-end que devolve HTML do servidor, com ou sem HTMX. Os
> exemplos deste arquivo usam Django; em PHP e Rails, campo múltiplo precisa de
> name terminado em [] e o upload direto precisa do cabeçalho de CSRF do
> framework (data-csrf="false" e a opção headers do new Upload).
> JavaScript puro, sem dependências em runtime. 43 KB JS + 13 KB CSS (gzip).
> Os estilos são escritos em Tailwind mas distribuídos já compilados: o projeto
> que consome não precisa de build e não recebe o preflight do Tailwind.
>
> Toda a API é em inglês — nomes de classe, métodos, opções, valores, classes
> CSS e atributos. Os comentários do código-fonte e os textos de interface são
> em português, porque é o que o usuário final lê.

> Como este arquivo está organizado: primeiro uma seção por componente, com o
> caminho declarativo (data-attributes) que é o normal num projeto Django;
> depois a REFERÊNCIA COMPLETA, gerada do código a cada build — se uma opção não
> está lá, ela não existe; no fim, as regras do que não fazer.

Documentação: https://juniorcarlini.github.io/tucano/
Código: https://github.com/JuniorCarlini/tucano
Licença: MIT

## Instalação

Dois arquivos, sem build e sem npm:

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/JuniorCarlini/tucano@v0.37.2/dist/tucano.min.css">
    <script src="https://cdn.jsdelivr.net/gh/JuniorCarlini/tucano@v0.37.2/dist/tucano.min.js" defer></script>

Sempre prenda a versão. Global JS: `Tucano`.

Todo elemento com `data-tuc-*` é inicializado sozinho no load e de novo a cada
`htmx:afterSwap`. Não é preciso escrever JavaScript.

## Date picker

    <input type="text" name="date"   data-tuc-datepicker>
    <input type="text" name="when"   data-tuc-datepicker data-time="true">
    <input type="text" name="period" data-tuc-datepicker data-mode="range">

Atributos: data-mode ("single"|"range"), data-time, data-seconds,
data-minute-step, data-locale, data-format, data-months, data-min, data-max,
data-presets, data-week-numbers, data-iso-name, data-placement, data-native.

Opções equivalentes em JS, mais: disabledDates (date => boolean), autoApply,
clearable, firstDayOfWeek, onChange.

O campo tem máscara derivada do formato (dd/mm/aaaa, dd/mm/aaaa hh:mm, e a
variante com travessão no modo range). Digita-se só números.

Por padrão o painel próprio é usado em todo lugar, inclusive no celular, onde
o texto sobe para 16px (abaixo disso o iOS dá zoom ao focar) e os dois meses
empilham no modo período.

O seletor nativo do sistema é opt-in: data-native="true" (ou native: 'auto'
para ligar só em telas de toque). Ele não altera o type do input — um input
nativo transparente fica por cima. Período nunca usa nativo.

## Select

Enriquece um <select> nativo, que continua no DOM guardando o valor. Portanto
name, multiple e required seguem funcionando.

    <select name="state" data-tuc-select>
      <option value="">Selecione...</option>   <!-- vira placeholder, não é opção -->
      <option value="SP">São Paulo</option>
    </select>

    <select name="tags" data-tuc-select multiple data-placeholder="Adicione...">

Atributos: data-placeholder, data-search, data-empty-text, data-max-items,
data-clearable, data-close-on-select, data-wrap-tags.

A busca ignora acentos ("sao" encontra "São Paulo"). <optgroup> vira grupo,
<option disabled> fica desabilitada, também dentro de <optgroup disabled>;
<select disabled> não abre, não aceita texto nem limpa. O campo tem altura fixa e linha única; o
excesso de tags rola na horizontal.

Metodo util: instance.refresh() rele as <option> depois de um swap do HTMX.

Busca no servidor, para listas grandes:

    <select name="customer" data-tuc-select data-url="/api/customers/"></select>

Atributos: data-url, data-query-param (padrao q), data-min-chars (1),
data-debounce (300). A resposta pode ser [{value,label}], ["a","b"],
{results:[...]} do DRF ou {id,text} do Select2. Para controle total existe
loadOptions: async (term) => [...].

## Color picker

    <input type="text" name="color" value="#4f46e5" data-tuc-color>
    <input type="text" name="brand" data-tuc-color data-alpha="false"
           data-swatches="#0a0a0a,#ea580c,#16a34a">

Atributos: data-format ("hex"|"rgb"|"hsl"), data-alpha, data-swatches,
data-placement.

Aceita na entrada: #rgb, #rgba, #rrggbb, #rrggbbaa, rgb(), rgba(), hsl(), hsla().
Texto inválido não zera a cor: volta para o valor atual.
Campo sem value nasce vazio (nenhuma cor escolhida por você), então required
barra o envio; getValue() devolve null e setValue(null) ou setValue('') limpa.
No arrasto, tucano:change sai a cada movimento e o change nativo uma vez, ao
soltar: para prévia ao vivo, ouça tucano:change.

## Upload

    <input type="file" name="attachments" multiple data-tuc-upload data-max-size="5mb">
    <input type="file" name="photos" multiple data-tuc-upload data-url="/upload/">

Sem data-url: os arquivos ficam no <input type="file"> nativo e sobem no submit,
o servidor recebe em request.FILES. Com data-url: cada arquivo sobe na hora com
barra de progresso, cancelar e repetir, e o formulário posta só os ids que o
endpoint devolveu. O modo direto funciona também sem <form>.

Atributos: data-url, data-max-size, data-max-files, data-field-name,
data-response-id, data-response-url, data-delete-url, data-auto-upload, data-csrf.

Tipos aceitos vêm do accept nativo, revalidado ao arrastar: ".pdf,.docx",
"image/*", "image/png,image/jpeg" ou misturado (".pdf,image/*"). Prefira
extensão a MIME: o navegador entrega .csv com type vazio, então
accept="text/csv" recusa e accept=".csv" aceita.

O endpoint deve devolver JSON com um id: {"id": "...", "url": "..."}.
O CSRF vai em X-CSRFToken, lido do cookie, só para url da mesma origem da
página (outra origem: passe headers). Resposta 2xx sem o id vira erro
("O servidor não devolveu o id").

Não existe progresso por arquivo no modo formulário: num submit comum o
navegador envia tudo num bloco e não reporta andamento.

## Máscaras

    <input name="cpf" data-tuc-mask="cpf" data-validate="true">
    <input name="amount" data-tuc-mask="brl">
    <input name="cpf" value="111.444.777-35" data-tuc-mask="cpf" data-tuc-reveal>
    <span data-tuc-format="cpf">12345678901</span>

Formatos: cpf, cnpj, cnpj-numeric, cpf-cnpj, phone, mobile, cep, brl,
currency, date, time, card. Gabarito livre aceita # (digito), A (letra) e *
(ambos), ex.: data-tuc-mask="##/##".

data-validate confere o digito verificador ao sair do campo e usa
setCustomValidity, entao o navegador barra o submit sozinho.
O acerto aparece na hora: com o valor completo e certo o campo ganha
data-tuc-valid e fica verde, ja digitando; o vermelho so vem ao sair do campo.
Num .tuc-input nativo, data-validate tambem pinta de verde por :user-valid.

data-tuc-reveal adiciona o olho de mostrar/ocultar, em qualquer campo. Com
conteudo, nasce oculto; o valor real fica num input hidden com o mesmo name,
entao o servidor recebe completo. Em type=password o olho so alterna o type, e
a senha nasce sempre oculta, mesmo vazia.

Tambem vale em texto solto, fora de campo (span, td), nos mesmos modos e junto
com data-tuc-format. E so visual: o valor inteiro fica no HTML; dado que nao
pode chegar ao navegador se esconde no servidor.

    <td><span data-tuc-format="cpf" data-tuc-reveal>11144477735</span></td>
    <span data-tuc-reveal="all">sk_live_a1b2c3d4e5f6</span>

Modos: data-tuc-reveal (end, padrao, com data-reveal-visible para o numero de
caracteres), data-tuc-reveal="all" (senha, token, chave) e "email"
(automatico em type=email, guarda o dominio: j****@empresa.com.br).

data-tuc-format formata elementos de exibicao, sem input.

CNPJ alfanumerico: 14 posicoes, mesma mascara, 12 primeiras aceitam letras, 2
ultimas numericas, digito verificador pelo codigo ASCII menos 48. O formato
`cnpj` aceita os dois; `cnpj-numeric` recusa letras.

## Botão

Só classe, sem JavaScript:

    <button class="tuc-btn is-primary">Salvar</button>

Variantes: is-primary, is-outline, is-ghost, is-danger, is-link.
Tamanhos: is-sm, is-lg, is-icon, is-block.

## Grupo de botões

Tambem so classe. Sem is-segmented, emenda acoes num bloco so; com ele, veste o
<input> de botao — a caixa e a mesma da aba segmentada, e o valor continua sendo
do input nativo (name, value, required, POST e as setas do teclado):

    <div class="tuc-btn-group is-segmented" role="group" aria-label="Periodo">
      <label class="tuc-btn">
        <input type="radio" class="tuc-btn__input" name="period" value="day" checked> Dia
      </label>
      <label class="tuc-btn">
        <input type="radio" class="tuc-btn__input" name="period" value="week"> Semana
      </label>
    </div>

    <div class="tuc-btn-group" role="group" aria-label="Acoes">
      <button class="tuc-btn is-outline">Editar</button>
      <button class="tuc-btn is-outline">Duplicar</button>
    </div>

O <input> vai DENTRO do <label class="tuc-btn">, como filho direto: e o :has do
rotulo que desenha o escolhido. Ele fica com opacidade zero, e nao escondido,
para continuar focavel. type="checkbox" no lugar do radio permite varios ao
mesmo tempo. is-block ocupa a linha toda. O grupo precisa de nome: role="group"
com aria-label, ou <fieldset> com <legend>.

NAO E ABA. A aba segmentada troca o que se ve na tela; o grupo de botoes e campo
e vai no POST. Ate umas quatro opcoes curtas — passando disso, select ou
.tuc-choices.

## Modal

Sobre <dialog> nativo: showModal() poe na top layer, acima de qualquer z-index
e imune a ancestral com overflow:hidden ou transform. Foco preso, foco devolvido
e Escape vem do proprio elemento.

    Tucano.modal({ title:'Excluir contrato', text:'...', tone:'danger', size:'md', sheet:true,
      actions:[{text:'Cancelar',variant:'outline'},{text:'Excluir',variant:'danger',onClick:fn}] });

    if (await Tucano.confirm({ title:'Excluir contrato?' })) deleteContract();

Tons: padrao, perigo, sucesso, aviso (mudam o brilho do fundo e a aura da caixa).
Tamanhos: sm, md, lg, full. Fechar por fora, pelo X ou por Escape resolve false.

Conteudo do servidor: o <dialog class="tuc-modal"> fica no template, com
data-tuc-modal="#id" no gatilho e data-tuc-modal-close nos botoes de fechar.

## Acordeão

Sobre <details>/<summary> nativos: teclado, semantica e estado vem do elemento,
e funciona antes de o JS carregar. O componente so acrescenta a animacao, que o
nativo nao faz (altura auto nao transiciona, e ao fechar o conteudo some de uma
vez).

    <div data-tuc-accordion data-single="true">
      <details open><summary>Projetos</summary><p>...</p></details>
    </div>

data-single="true" recolhe os outros ao abrir um. .tuc-accordion.is-plain tira as
divisorias, para menu lateral.

## Menu

Lista de navegacao, so classes — nao ha componente nem JS proprio. Item com
submenu e um <details>, entao a animacao vem do acordeao.

    <nav class="tuc-menu" data-tuc-accordion>
      <a class="tuc-menu__item" href="..."><span class="tuc-menu__icon">svg</span>Faturamento</a>

      <details open>
        <summary class="tuc-menu__item"><span class="tuc-menu__icon">svg</span>Desempenho</summary>
        <div class="tuc-menu__sub">
          <a class="tuc-menu__item is-active" href="...">Por periodo</a>
          <a class="tuc-menu__item" href="...">Unidades</a>
        </div>
      </details>

      <div class="tuc-menu__section">Cadastros</div>
      <hr class="tuc-menu__separator">
    </nav>

is-active marca o item atual. No primeiro nivel ele leva cor de destaque, fundo e
peso; no submenu, uma pilula neutra. Filho de submenu nao leva icone: o ponto ja
marca a linha.

tuc-menu__count poe um numero a direita do item.

Barra lateral fixa: uma coluna flex de altura fixa (display:flex;
flex-direction:column; height:100vh), marca em cima e o nav.tuc-menu embaixo.
O menu rola sozinho quando a lista passa da tela; nao ponha overflow no aside.
Dentro de uma gaveta (tuc-drawer__body) quem rola e o corpo da gaveta.

## Editor de texto

    <textarea name="description" data-tuc-editor>{{ form.description.value|default:"" }}</textarea>

O <textarea> continua dono do valor: name, required e o POST funcionam sem nada
especial. Guarda HTML sanitizado. Barra com negrito, italico, sublinhado, dois
titulos, listas, alinhamento nos quatro tipos, citacao, codigo, link e tabela.

Colar e arrastar entram como texto puro. Editor vazio vale '' (e nao <p><br></p>),
entao required barra o envio; link sem esquema ganha https://.
A saida passa por peneira de tags a cada leitura —
sobrevivem p, h2, h3, strong, em, u, s, ul, ol, li, blockquote, code, pre, a e
tabela; atributo nenhum passa, exceto href com destino aceitavel e text-align.
Ainda assim, sanitize no servidor antes de renderizar para o publico.

Variaveis do texto (modelo de mensagem, e-mail, cartao):

    new Tucano.Editor('#message', { variables: [
      { name: 'nome', label: 'Nome do responsavel', example: 'Junior' },
      { name: 'prazo', label: 'Prazo', example: '21/09' },
    ]});

No texto, a variavel ganha fundo leve e a que nao esta na lista sai no tom de
erro — pintura do navegador sobre o trecho (Custom Highlight), nao marcacao: o
valor salvo nao muda. Navegador sem a API mostra o texto sem fundo.

Com elas a barra ganha o botao { } e digitar `{` abre a lista, filtrada pelas
letras seguintes e sem tirar o foco do texto; escolher escreve {{nome}}, texto
puro — o template do servidor troca pelos dados como ja fazia. Seta e Enter
escolhem, Esc fecha. `editor.unknownVariables()` devolve o que esta escrito no
texto e nao esta na lista (o erro de digitacao). Dentro de bloco de codigo a
lista nao abre e nada e acusado: ali se escreve codigo. Sem `variables`, o
editor nao muda em nada.

Exibicao: envolva a saida em .tuc-prose para ela ficar igual ao editor.

    <div class="tuc-prose">{{ project.description|safe }}</div>

O codigo publicado e colorido pelo init(). Tucano.highlight(texto) faz isso a
mao; Tucano.sanitize(html) aplica a peneira.

## Levar só o que se usa

Pelo CDN vem tudo (33 KB gzip) e o navegador guarda em cache por um ano.

Empacotando, importe de 'tucano' e leve so o referenciado: date picker sozinho
9,8 KB, select 6,2 KB, toast 3,1 KB, os dois primeiros juntos 13,7 KB, tudo
30,2 KB. Nao e linear porque o nucleo e compartilhado.

Importando de 'tucano' os campos NAO se inicializam sozinhos: chame
Tucano.init(document), ou importe 'tucano/auto', que inicializa e escuta os
swaps do HTMX como o script do CDN.

## Conferência de tamanhos

    npm run audit

Mede altura e fonte de todo controle em 1280px e em tela estreita, e falha se
algum sair do padrao: 38px no desktop, 44px no toque, e nunca abaixo de 16px de
fonte em campo digitavel, senao o iOS da zoom ao focar. Componente novo com
campo ou botao precisa entrar em tools/audit.mjs e na lista do
@media (max-width: 40rem) em src/styles/core/tokens.css.

## Exibir o que o editor salvou (.tuc-prose)

    <div class="tuc-prose">{{ obj.description|safe }}</div>

O init() pinta os blocos <pre><code> e poe um botao de copiar em cada um — o
botao aparece no hover e no foco, e copia o texto cru, sem as marcacoes de cor.
Sanitize no servidor antes do |safe: a peneira do editor protege o editor, nao
a publicacao.

## Utilitários (Tucano.mask, Tucano.dates, Tucano.color)

Os modulos internos saem prontos como API publica. Nao sao sobra de codigo: sao
o que resolve o que sempre falta num CRUD.

    Tucano.mask.validateCpfCnpj('123.456.789-01')
    Tucano.mask.applyCurrency('12345', { currency:'BRL' })   // 'R$ 123,45'
    Tucano.mask.maskEmail('contato@empresa.com.br')
    Tucano.dates.format(new Date(), 'dd/MM/yyyy')
    Tucano.dates.parseUserInput('7/9/26')
    Tucano.color.isDark('#4f46e5')   // true — escolhe texto claro sobre a cor

mask: CPF, CNPJ, moeda, telefone, aplicar/tirar mascara, ocultar dado sensivel.
dates: ler, formatar, comparar e caminhar por datas respeitando o locale.
color: converter hex/rgb/hsv e medir luminancia.

Quem importa so o Toast pelo npm nao leva nenhum dos tres (3 KB no total).

## Tabela

    <table data-tuc-table data-selectable class="is-striped">
      <thead><tr>
        <th data-sort="text" data-field="customer" style="width:38%">Cliente</th>
        <th data-sort="number" data-field="amount" class="is-number">Valor</th>
        <th data-sort="none" class="tuc-table__actions">Acoes</th>
      </tr></thead>
      <tbody><tr data-id="{{ obj.pk }}"> ... </tr></tbody>
    </table>

Celula livre. Classes de apoio: .tuc-table__user + __avatar + __sub (foto ou
iniciais, nome, segunda linha), .tuc-badge (is-success | is-warning | is-danger |
is-info), .tuc-table__actions (encosta a direita; use os botoes do sistema,
.tuc-btn is-outline is-icon is-sm),
.is-number (direita, digitos de largura fixa), .tuc-table__empty (celula
de estado vazio). Truncar a segunda linha exige
largura na coluna. Variantes: is-striped, is-bordered, is-compact.

data-sort: text | number | date | none. data-sort-value guarda o valor cru.

ORDENAR E DO SERVIDOR, E ESSE E O PADRAO. Numa lista paginada, reordenar as
linhas da tela produz ordem falsa — o maior valor pode estar na pagina 7. O
cabecalho e um <a> para a mesma URL com ?sort= e ?dir=: funciona sem JS, com
hx-boost, abre em outra aba, e o estado da seta sai da query string. Trocar a
ordem volta para a pagina 1. Na view, ?sort e ?dir entram no order_by() antes do
Paginator. data-sort-mode="client" ordena na tela — so para tabela pequena e
completa, sem paginacao.

Selecao gera <input type="checkbox" name="selected" value="{{ data-id }}">:
chega em request.POST.getlist('selected').

## Etiqueta de estado

    <span class="tuc-badge is-success">Aprovado</span>

Tons: is-success, is-warning, is-danger, is-info; sem tom fica neutra.
is-plain tira o ponto. Vale fora da tabela tambem.

## Paginação

    <div data-tuc-pagination
         data-page="{{ page_obj.number }}"
         data-pages="{{ page_obj.paginator.num_pages }}"></div>

data-param (padrao "page"), data-around, data-edges, data-prev-text,
data-next-text. Alinhamento: is-center, is-end.

Os itens sao .tuc-btn — os mesmos botoes do resto da biblioteca — e sao <a> com
href real, preservando o resto da query string: filtro, busca e ordem sobrevivem
a troca de pagina. Quem intercepta passa onChange. Ponta inativa e <span>, nao
<a> sem href, para sair do caminho do Tab. Com uma pagina so, nada e renderizado.

## Formulário

    <label class="tuc-label is-required" for="doc">CNPJ</label>
    <input id="doc" name="doc" data-tuc-mask="cnpj" aria-invalid="true" aria-describedby="doc-e">
    <p class="tuc-error" id="doc-e">CNPJ invalido.</p>

    <select class="tuc-input" name="plan">...</select>
    <p class="tuc-hint">Texto de ajuda.</p>

Campo com erro = aria-invalid="true" no elemento nativo (o Django 5 ja escreve).
Pinta borda e anel vermelhos em todo campo da biblioteca, inclusive select, cor,
editor e upload montados pelo script. Use aria-invalid no campo; .tuc-invalid so e posta pela propria mascara quando
valida (data-validate).
:user-invalid (required, type=email) pinta so depois de a pessoa mexer.
.tuc-input vale em input, textarea e select nativo.

## Caixa, opção e chave

    <label class="tuc-choice">
      <input type="checkbox" class="tuc-check" name="invoice"> Nota fiscal por e-mail
    </label>

    <fieldset class="tuc-choices">
      <legend>Entrega</legend>
      <label class="tuc-choice">
        <input type="radio" class="tuc-radio" name="shipping" value="standard">
        <span>Normal <span class="tuc-choice__hint">Ate 7 dias uteis</span></span>
      </label>
    </fieldset>

    <label class="tuc-choice is-end">
      <input type="checkbox" role="switch" class="tuc-switch"> Avisos por e-mail
    </label>

So classe, sem JavaScript. Desenhados, nao accent-color. Continuam sendo <input>
de verdade: valor, name, required e estado misto sao os nativos.
.tuc-choice e o <label> que alinha o controle a primeira linha; __hint e a
descricao; is-end poe o controle a direita. .tuc-choices empilha um grupo
(feito para <fieldset>); is-inline poe lado a lado.
A chave exige role="switch" no input. Chave para efeito imediato; caixa para o
que so vale ao salvar.

## Menu suspenso (dropdown)

Sobre o mesmo popover do tooltip: vira de lado quando nao cabe, fecha no clique
fora e no Escape. Do servidor:

    <button data-tuc-dropdown="#actions" data-placement="bottom-end">Acoes</button>
    <div class="tuc-dropdown" id="actions" hidden>
      <div class="tuc-dropdown__label">Contrato</div>
      <button class="tuc-dropdown__item">
        <span class="tuc-dropdown__text">Editar</span>
        <span class="tuc-dropdown__shortcut">Cmd E</span>
      </button>
      <hr class="tuc-dropdown__separator">
      <button class="tuc-dropdown__item is-danger">...</button>
    </div>

O hidden e obrigatorio: sem ele o painel aparece no meio da pagina ate o script
rodar. Em JS:

    new Tucano.Dropdown('#actions', { placement:'bottom-start', items:[
      { label:'Contrato' },
      { text:'Editar', icon:PATH_SVG, shortcut:'Cmd E', onClick:fn },
      { text:'Abrir', href:'/contracts/12/' },
      { separator:true },
      { text:'Excluir', variant:'danger', onClick:fn },
    ]});

Item com href vira <a>; sem href vira <button>. Teclado: setas andam, Home e End
vao as pontas, Escape e Tab fecham, e o foco volta ao gatilho. Os itens tem
tabindex="-1" de proposito — dentro de um menu quem navega e a seta, nao o Tab.

Aberto pelo teclado (Enter, Espaco ou seta no gatilho), o primeiro item ja nasce
destacado. Aberto por clique, nenhum: como no menu do sistema, a primeira seta e
que destaca. Vale para o menu do botao direito e para a lista de variaveis do
editor, que sao o mesmo menu.

## Menu do botao direito (contextmenu)

O mesmo menu, aberto pelo `contextmenu` e ancorado no ponto do clique. Do
servidor, com o painel pronto no template:

    <table data-tuc-contextmenu="#row-actions" data-match="tbody tr">...</table>
    <div class="tuc-dropdown" id="row-actions" hidden>...</div>

Em JS, com os itens da linha clicada:

    new Tucano.ContextMenu('#contracts', {
      match: 'tbody tr',
      items: (row) => [
        { label: row.dataset.name },
        { text: 'Editar', onClick: () => edit(row.dataset.id) },
        { separator: true },
        { text: 'Excluir', variant: 'danger', onClick: () => remove(row.dataset.id) },
      ],
    });

Aberto pelo botao direito nenhum item nasce destacado, como no menu do sistema:
a primeira seta destaca o primeiro. Pelo teclado, o primeiro ja vem destacado.

`match` e o seletor do alvo dentro da area; sem ele o alvo e a area inteira.
Fora de um alvo, e com Shift+botao direito, o menu do navegador continua
valendo. Itens, teclado e papeis sao os do dropdown; o alvo clicado fica em
`menu.target`. Rolar a pagina fecha, como no sistema operacional.

Ponha tabindex="0" no alvo: a tecla de menu e o Shift+F10 abrem a partir de
quem tem o foco, e sem isso o menu fica inalcancavel sem mouse. No iPhone o
Safari nao avisa a pagina no toque longo — nenhuma acao pode existir so aqui.

## Teclado nos campos que abrem painel

Chegar de Tab nao abre painel nenhum: quem tabula por um formulario ate o botao
de salvar nao deve levar um calendario na cara a cada campo. Abrir e sempre
explicito — seta para baixo, clique, Espaco, e no select tambem Enter.

No campo de data o Enter fica de fora: e campo de texto dentro de <form>, e
Enter ali envia o formulario. O Espaco abre, e so com o campo vazio, porque em
modo com hora se digita "07/09/2026 14:30". No campo
de cor o gatilho e a amostra ao lado, que e um <button> de verdade.

## Abas

    <div class="tuc-tabs" data-tuc-tabs>
      <div class="tuc-tabs__list">
        <button class="tuc-tabs__tab" aria-selected="true">Dados</button>
        <button class="tuc-tabs__tab">Endereco</button>
      </div>
      <div class="tuc-tabs__panel">...</div>
      <div class="tuc-tabs__panel" hidden>...</div>
    </div>

Escreva as classes, aria-selected="true" na inicial e hidden nos outros paineis:
a pagina nasce certa antes do script. O JS poe os roles e o teclado (setas, Home,
End; Tab para so na aba aberta). data-manual="true" quando o painel carrega por
HTMX: setas so movem o foco. is-segmented = altura de campo, para barra de filtro.
Evento tucano:change com detail { value, tab, panel, instance }.

## Aviso

    <div class="tuc-alert is-warning">
      <svg>...</svg>
      <div class="tuc-alert__body">
        <p class="tuc-alert__title">Assinatura vence em 3 dias</p>
        <p>Renove para nao perder o acesso.</p>
      </div>
      <div class="tuc-alert__actions"><a class="tuc-btn is-outline is-sm" href="...">Renovar</a></div>
    </div>

So classe. Para o que continua valendo na tela (o toast e para o que acabou de
acontecer). Tons: is-info, is-success, is-warning, is-danger. role="alert" so no
que aparece depois do load.

## Carregando

    <button class="tuc-btn is-primary" aria-busy="true" disabled><span class="tuc-spinner"></span> Salvando</button>
    <span class="tuc-spinner htmx-indicator"></span>
    <div class="tuc-skeleton" style="width:60%"></div>

So classe. Spinner mede em em e usa currentColor; is-lg aumenta. Esqueleto
reserva o espaco do conteudo; is-circle para avatar. Nao escreva spinner a mao.

## Linha do tempo

    <ol class="tuc-timeline">
      <li class="tuc-timeline__item is-success is-filled">
        <div class="tuc-timeline__head">
          <p class="tuc-timeline__title">Contrato assinado</p>
          <time class="tuc-timeline__time" datetime="2026-09-12">12/09/2026</time>
        </div>
        <div class="tuc-timeline__body">As duas partes assinaram.</div>
      </li>
    </ol>

So classe, sobre <ol>. Tons no item: is-accent, is-success, is-warning, is-danger,
is-info; is-filled enche o ponto. Icone no lugar do ponto: <span
class="tuc-timeline__icon"><svg>...</svg></span> como primeiro filho do item.

## Gaveta (off-canvas)

Componente proprio, mas divide com o modal a mecanica do <dialog>: top layer,
foco preso, Escape, foco devolvido. Muda a geometria e o movimento.

    Tucano.drawer({ title:'Filtros', side:'right' }).content(form);

side: left | right | top | bottom. Nas laterais o size e largura de
coluna (18, 24, 34rem) e no celular para em 85% da tela. Do servidor:
<dialog class="tuc-drawer is-right"> no template, data-tuc-drawer="#id" no
gatilho e data-tuc-drawer-close nos botoes de fechar.

## Toast e tooltip

    Tucano.toast('Salvo');
    Tucano.toast.error('Nao foi possivel salvar');
    Tucano.toast({ type:'success', title:'...', text:'...', action:{text:'Desfazer', onClick:fn}, position:'bottom-end', duration:null });

Tipos: info, success, warning, error, loading.
Posicoes: top-start, top-center, top-end, bottom-start, bottom-center,
bottom-end. Padrao: bottom-end. No celular o toast ocupa a largura da tela e
entra pelo eixo vertical, qualquer que seja a posicao.

O tipo loading nao fecha sozinho; quem fecha e o fim da operacao. Ele vira o
resultado no mesmo cartao, sem piscar:

    const t = Tucano.toast.loading('Enviando...');
    t.update({ type:'success', text:'Enviado' });

    Tucano.toast.promise(fetch(url), {
      loading: 'Enviando...', success: (r) => `Enviado (${r.status})`, error: 'Falhou',
    });

Mensagens do Django viram toast sem JavaScript:
    {% for m in messages %}<div data-tuc-toast data-type="{{ m.tags }}">{{ m }}</div>{% endfor %}

Servidor dispara pelo HTMX:
    HX-Trigger: {"tucano:toast": {"type": "success", "text": "Salvo"}}

Tooltip:
    <button data-tuc-tip="Gera o PDF">Exportar</button>
    atributos: data-tuc-tip, data-placement, data-delay, data-tip-class

Lados: top, right, bottom, left; alinhamentos: start, center, end — as mesmas
do shadcn, padrao top-center. Quando o lado pedido nao cabe a dica vira para o
oposto e a seta acompanha. Se o gatilho sai da viewport, a dica fecha.

Cor por variavel, e a seta acompanha:

    .tip-accent { --tuc-tip-bg: #4f46e5; --tuc-tip-fg: #fff; }
    <button data-tuc-tip="..." data-tip-class="tip-accent">

Aparece no ponteiro e no foco do teclado; no toque, tocar abre e tocar fora
fecha. Escape sempre fecha.

## Django

O campo visível mostra o formato do locale; um <input type="hidden"> com o mesmo
name carrega o valor em ISO, e é esse que chega no request.POST.

    widgets = {
        "event_date": forms.TextInput(attrs={"data-tuc-datepicker": "", "data-time": "true"}),
        "period":     forms.TextInput(attrs={"data-tuc-datepicker": "", "data-mode": "range"}),
        "state":      forms.Select(attrs={"data-tuc-select": ""}),
        "tags":       forms.SelectMultiple(attrs={"data-tuc-select": ""}),
        "color":      forms.TextInput(attrs={"data-tuc-color": ""}),
    }

O que chega no servidor:

    event_date  = 2026-12-25T09:30      # DateTimeField faz o parse direto
    period      = 2026-03-01,2026-03-15 # separe na vírgula no clean_
    tags        = django                # request.POST.getlist("tags")
    tags        = htmx
    color       = #4f46e5

## API

    document.addEventListener('tucano:change', (e) => {
      e.detail.value; e.detail.iso;   // e.target.name so onde o campo tem name
    });

    new Tucano.DatePicker('#field', { mode: 'range', time: true });
    new Tucano.Select('#state', { maxItems: 3 });
    new Tucano.ColorPicker('#color', { format: 'rgb' });

Métodos: getValue, setValue, clear, open, close, destroy. Select tem refresh.
ColorPicker tem getRgb. Modal e Drawer tem open, close e content; Dropdown tem open, close e toggle;
Modal e Drawer tem content(node). Table tem sort, getSelected, clearSelection.
Pagination tem setPage. Toast tem update e close.

Atalhos: Tucano.modal(), Tucano.confirm(), Tucano.drawer(), Tucano.toast(),
Tucano.pagination(), Tucano.sanitize(), Tucano.highlight(), Tucano.init(node),
Tucano.setTexts(), Tucano.getTexts().

Eventos proprios: tucano:change (campos), tucano:sort e tucano:select (tabela).

## Textos em outros idiomas

Datas e números seguem o lang da página. Os textos que os componentes escrevem
sozinhos (o "Limpar" do calendário, o "Buscar..." do select, o "Fechar" do
modal, os aria-label) vêm em português. Não há dicionário de idiomas no pacote:
num projeto em outro idioma, troque por grupo com Tucano.setTexts.

    <script src=".../tucano.min.js" defer></script>
    <script>
      document.addEventListener('DOMContentLoaded', () => Tucano.setTexts({
        datepicker: { clear: 'Clear', apply: 'Apply', previousMonth: 'Previous month',
                      nextMonth: 'Next month', placeholderLetters: 'ymdhms' },
        select: { searchPlaceholder: 'Search...', emptyText: 'No results',
                  remove: (label) => `Remove ${label}` },
        modal: { close: 'Close' },
      }));
    </script>

    import { setTexts } from 'tucano';   // npm: antes de criar os componentes

Regras: mescla chave a chave dentro do grupo (o que não foi passado fica). O
texto é lido na montagem, então chame antes do init ou do new — o que já está na
tela não muda. A opção da instância vence (data-placeholder, emptyText,
prevText/nextText, texts do upload). Frase que depende de número ou nome é
função: upload.others(n), select.remove(label). Tucano.getTexts() devolve uma
cópia. Todos os grupos e chaves, com o padrão, estão em "Textos
(Tucano.setTexts)" na referência abaixo.

## Tema

Todas as cores e medidas são variáveis CSS com prefixo --tuc-. Nada de cor,
raio, espessura de borda ou altura está fixo no CSS dos componentes.

Cor: --tuc-accent (neutro por padrão: #0a0a0a no claro, #fafafa no escuro — a
cor é do projeto; ao trocar, redefina também em .dark), --tuc-accent-hover,
--tuc-accent-fg (texto sobre o destaque: #ffffff no claro, #0a0a0a no escuro),
--tuc-accent-text (destaque usado como cor de texto: link, menu ativo, tag; com
cor viva, use um tom mais fechado no claro), --tuc-thumb (botão da chave), --tuc-accent-soft,
--tuc-accent-ring, --tuc-bg, --tuc-fg, --tuc-muted, --tuc-subtle,
--tuc-border, --tuc-hover, --tuc-elevated
Forma: --tuc-radius, --tuc-radius-md, --tuc-radius-sm, --tuc-radius-xs,
--tuc-border-width, --tuc-control-height, --tuc-cell, --tuc-swatch, --tuc-text,
--tuc-font
Tons: --tuc-success, --tuc-warning, --tuc-danger, --tuc-info e os -soft, usados
pelo toast, pelo aviso e pela etiqueta de estado. Tom semântico nunca lê o
destaque. --tuc-danger-fill é separado: no escuro o vermelho de
texto é mais claro para ter contraste, e um botão pintado com ele ficaria
pastel — o preenchimento é o mesmo nos dois temas.
Profundidade: --tuc-shadow, --tuc-ring, --tuc-duration, --tuc-duration-lg,
--tuc-duration-out, --tuc-ease, --tuc-ease-in

Os tokens vivem em :root. Sobrescreva sem recompilar:

    :root {
      --tuc-accent: #0d9488;
      --tuc-radius: 1rem;
    }

Como são variáveis, o escopo é seu: em :root valem para a página inteira,
declaradas num container valem só ali dentro.

Escuro segue a classe .dark no <html>. Para seguir o sistema operacional, use
<html data-tuc-theme="auto"> — é opt-in, para o componente não escurecer sozinho
numa página clara.

## Eventos

Todos borbulham, então dá para ouvir no documento e pegar o que vier por HTMX.

    document.addEventListener('tucano:change', (e) => {
      e.detail.value;       // valor pronto para uso
      e.detail.instance;    // a instancia, se precisar de mais
      e.target.name;        // ver a ressalva do date picker abaixo
    });

O evento sai do elemento que guarda o valor. No select, na mascara e no upload
esse elemento e o proprio campo com `name`, entao `e.target.name` funciona. No
date picker, nao: ele move o `name` para um <input type=hidden> com o valor ISO
(e o campo visivel fica sem name, para o servidor receber ISO e nao o texto
formatado). Ali use `e.detail.iso`, ou leia o hidden.

    tucano:change   date picker  → { value, iso, instance }
                    select       → { value, instance }        value e array em multiple
                    color picker → { value, rgb, hsva, instance }
                    mascara      → { value, raw, number, instance }
                    upload       → { value, files, instance }
    tucano:sort     tabela       → { column, field, direction }   direction: 'asc'|'desc'
    tucano:select   tabela       → { selected, row }              selected: array de data-id
    tucano:toast-closed  toast   → sem detail, disparado no proprio no do toast

O `onChange` de cada componente recebe os mesmos dados: (value, detail).

Para disparar um toast do servidor, o Django manda o cabecalho e o listenForEvents
(ligado pelo init) cuida do resto — veja a secao Django.

## Referência completa (gerada pelo build)

Inventario extraido do codigo a cada build. Se algo nao esta aqui, nao existe.

### Accordion
  marcacao   [data-tuc-accordion]
  em JS      new Tucano.Accordion(alvo, opcoes)
  atributos  data-single
  opcoes
    single             = false  — abrir um recolhe os outros
  metodos    open close destroy

### ColorPicker
  marcacao   [data-tuc-color]
  em JS      new Tucano.ColorPicker(alvo, opcoes)
  atributos  data-alpha data-format data-placement data-swatches
  opcoes
    format             = 'hex'  — 'hex' | 'rgb' | 'hsl'
    alpha              = true
    swatches           = PALETTE  — false desliga
    placement          = 'bottom-center'  — mesma regra do date picker: centralizado, preso na borda da tela…
    appendTo           = undefined
    onChange           = null
  metodos    getValue getRgb setValue open close toggle destroy
  eventos    tucano:change

### ContextMenu
  marcacao   [data-tuc-contextmenu]
  em JS      new Tucano.ContextMenu(alvo, opcoes)
  atributos  data-match data-placement data-tuc-contextmenu
  opcoes
    placement          = 'bottom-start'
    items              = null  — array como o do Dropdown, ou (alvo) => array…
    match              = null  — seletor do alvo dentro da area; sem ele, a area inteira…
    closeOnPick        = true
    onOpen             = null  — (alvo, instancia) — para marcar a linha clicada, por exemplo…
    panel              = null  — painel ja escrito no template, no lugar de `items`…
  metodos    openAt close

### DatePicker
  marcacao   [data-tuc-datepicker]
  em JS      new Tucano.DatePicker(alvo, opcoes)
  atributos  data-format data-iso-name data-locale data-max data-min data-minute-step data-mode data-months data-native data-placement data-presets data-seconds data-time data-week-numbers
  opcoes
    mode               = 'single'  — 'single' | 'range'
    time               = false  — true habilita seletor de hora
    seconds            = false
    minuteStep         = 5
    locale             = undefined  — default: locale do documento/navegador
    format             = undefined  — default: padrao numerico do locale
    firstDayOfWeek     = undefined
    months             = undefined  — default: 2 em range, 1 em single…
    min                = null
    max                = null
    disabledDates      = null  — (date) => boolean
    presets            = false  — atalhos de periodo (Hoje, Ultimos 7 dias...): opt-in…
    autoApply          = undefined  — default: true sem hora, false com hora. Sem autoApply, a escolha so vale no Aplicar…
    clearable          = true
    weekNumbers        = false
    placement          = 'bottom-center'  — centralizado no campo; as bordas da tela ainda mandam…
    appendTo           = undefined
    isoName            = undefined  — name do input hidden com o valor ISO…
    native             = false
    onChange           = null
    onOpen             = null
    onClose            = null
  metodos    getValue setValue clear open close toggle destroy
  eventos    tucano:change

### Drawer
  marcacao   dialog.tuc-drawer  ou  [data-tuc-drawer-close]  ou  [data-tuc-drawer]
  em JS      new Tucano.Drawer(opcoes)   atalhos: Tucano.drawer()
  atributos  data-backdrop data-closable data-tuc-drawer
  opcoes
    title              = null
    text               = ''
    side               = 'right'  — left | right | top | bottom…
    size               = 'md'  — sm | md | lg — nas laterais, largura da coluna…
    tone               = 'default'  — default | danger | success | warning…
    closable           = true
    closeOnBackdrop    = true
    actions            = null  — [{ text, variant, onClick, closes }] — closes:false mantem aberto…
    onClose            = null
    className          = ''
  metodos    open close content

### Dropdown
  marcacao   [data-tuc-dropdown]
  em JS      new Tucano.Dropdown(alvo, opcoes)
  atributos  data-placement data-tuc-dropdown
  opcoes
    placement          = 'bottom-start'
    items              = null  — [{ text, icon, shortcut, onClick, href, variant, disabled, separator, label }]
    closeOnPick        = true
  metodos    openAt open close toggle destroy

### Editor
  marcacao   [data-tuc-editor]
  em JS      new Tucano.Editor(alvo, opcoes)
  atributos  data-min-height data-placeholder
  opcoes
    toolbar            = ['bold', 'italic', 'underline', 'title', 'subheading'
    table              = { rows: 3, cols: 3 }
    minHeight          = '9rem'
    placeholder        = ''
    variables          = null
  metodos    inTable apply openVariables insertVariable unknownVariables getValue setValue destroy

### Mask
  marcacao   [data-tuc-mask], [data-tuc-reveal]  ou  [data-tuc-format]:not([data-tuc-formatted])
  em JS      new Tucano.Mask(alvo, opcoes)   atalhos: Tucano.autoFormat()
  atributos  data-currency data-decimals data-error-text data-reveal-mode data-reveal-visible data-tuc-format data-tuc-mask data-tuc-reveal data-validate data-value
  opcoes
    format             = null  — nome de FORMATS ou gabarito livre
    validate           = false  — valida no blur e bloqueia o submit…
    decimals           = 2
    currency           = null  — 'BRL' formata com R$
    reveal             = false  — olhinho para mostrar e ocultar
    revealVisible      = 2  — quantos caracteres ficam a mostra no modo 'end'…
    revealMode         = null  — 'end' | 'email' | 'all'. null decide pelo campo…
    locale             = undefined
    errorText          = null
    onChange           = null
  metodos    getRaw getNumber setValue isValid destroy
  eventos    tucano:change

### Modal
  marcacao   dialog.tuc-modal  ou  [data-tuc-modal-close]  ou  [data-tuc-modal]
  em JS      new Tucano.Modal(opcoes)   atalhos: Tucano.modal(), Tucano.confirm()
  atributos  data-backdrop data-closable data-tuc-modal
  opcoes
    title              = null
    text               = ''
    size               = 'md'  — sm | md | lg | full…
    tone               = 'default'  — default | danger | success | warning…
    sheet              = false  — no celular sobe do rodape em vez de surgir no centro…
    closable           = true  — botao X e Escape
    closeOnBackdrop    = true
    actions            = null  — [{ text, variant, onClick, closes }] — closes:false mantem aberto…
    onClose            = null
    className          = ''
  metodos    open close content

### Pagination
  marcacao   [data-tuc-pagination]
  em JS      new Tucano.Pagination(opcoes)   atalhos: Tucano.pageWindow(), Tucano.pagination()
  atributos  data-around data-edges data-next-text data-page data-pages data-param data-prev-text
  opcoes
    page               = 1
    pages              = 1
    param              = 'page'
    around             = 1  — paginas visiveis de cada lado da atual…
    edges              = 1  — paginas visiveis nas pontas
    prevText           = undefined  — default: setTexts ("Anterior")
    nextText           = undefined  — default: setTexts ("Próxima")
    label              = undefined  — default: setTexts ("Paginação")
    onChange           = null
  metodos    href render setPage destroy

### Select
  marcacao   select[data-tuc-select]
  em JS      new Tucano.Select(alvo, opcoes)
  atributos  data-cache data-clearable data-close-on-select data-debounce data-empty-text data-max-items data-min-chars data-page-param data-query-param data-search data-short-circuit data-url data-wrap-tags
  opcoes
    search             = undefined  — default: liga a partir de 6 opcoes…
    searchMinItems     = 6
    placeholder        = undefined  — default: do atributo, da <option value=""> ou setTexts ("Selecione...")
    searchPlaceholder  = undefined  — default: setTexts ("Buscar...")
    emptyText          = undefined  — default: setTexts ("Nenhum resultado")
    clearable          = true
    maxItems           = null  — limite no modo multiplo
    wrapTags           = false  — true deixa o campo crescer em varias linhas…
    closeOnSelect      = undefined  — default: true em simples, false em multiplo…
    placement          = 'bottom-start'
    appendTo           = undefined
    url                = null  — com url, a lista vem do servidor a cada digitacao…
    loadOptions        = null  — (termo) => Promise<[{value,label,disabled,group}]>
    queryParam         = 'q'
    pageParam          = 'page'  — paginacao ao rolar; null desliga
    minChars           = 1
    debounce           = 300
    cache              = true  — guarda o resultado de cada termo
    cacheSize          = 60
    shortCircuit       = false  — ver _noChance()
    loadingText        = undefined  — default: setTexts ("Buscando...")
    errorText          = undefined  — default: setTexts ("Falha ao buscar")
    onChange           = null
  metodos    getValue setValue clear refresh open close toggle destroy
  eventos    tucano:change

### Table
  marcacao   table[data-tuc-table]
  em JS      new Tucano.Table(alvo, opcoes)
  atributos  data-dir-param data-select-name data-selectable data-sort-mode data-sort-param data-sortable
  opcoes
    sortable           = true
    sortMode           = 'server'  — server | client
    sortParam          = 'sort'
    dirParam           = 'dir'
    selectable         = false  — coluna de selecao em massa
    selectName         = 'selected'
    onSort             = null  — definido, intercepta o clique e cancela a navegacao…
    onSelect           = null
  metodos    sort getSelected clearSelection destroy
  eventos    tucano:sort tucano:select

### Tabs
  marcacao   [data-tuc-tabs]
  em JS      new Tucano.Tabs(alvo, opcoes)
  atributos  data-manual
  opcoes
    selected           = null  — indice da aba inicial; sem ele vale a marcada com aria-selected="true", ou a primeira…
    manual             = false  — setas so movem o foco, e Enter ou Espaco trocam o painel — para painel que carrega por HTMX…
    onChange           = null  — (index, detail) a cada troca feita pela pessoa ou por select()
  metodos    select destroy
  eventos    tucano:change

### Toast
  marcacao   [data-tuc-toast]
  em JS      new Tucano.Toast(opcoes)   atalhos: Tucano.toast(), Tucano.listenForEvents()
  atributos  data-duration data-position data-text data-title data-type
  opcoes
    type               = 'info'  — 'info' | 'success' | 'warning' | 'error' | 'loading'…
    title              = null
    text               = ''
    duration           = undefined  — ms. null nao fecha sozinho. Padrao depende do tipo…
    position           = 'bottom-end'  — top-start|top-center|top-end|bottom-start|bottom-center|bottom-end
    closable           = true
    action             = null  — { text, onClick }
    max                = 4  — toasts simultaneos na mesma posicao
  metodos    update close
  eventos    tucano:toast-closed

### Tooltip
  marcacao   [data-tuc-tip]
  em JS      new Tucano.Tooltip(alvo, opcoes)
  atributos  data-delay data-placement data-tip-class data-tuc-tip
  opcoes
    text               = ''
    placement          = 'top-center'
    delay              = 350  — atraso ao apontar: evita piscar ao passar o mouse de raspao…
    delayOut           = 120
    maxWidth           = '16rem'
    className          = ''  — classe extra no balao, para variar a cor num caso so…
  metodos    setText destroy

### Upload
  marcacao   input[type=file][data-tuc-upload]
  em JS      new Tucano.Upload(alvo, opcoes)
  atributos  data-auto-upload data-csrf data-delete-url data-field-name data-max-files data-max-size data-response-id data-response-url data-url
  opcoes
    url                = null  — com url: upload direto. sem: os arquivos vao no submit…
    method             = 'POST'
    fieldName          = 'file'  — nome do campo no FormData do upload direto…
    extraData          = {}  — campos extras enviados junto
    headers            = {}
    csrf               = true  — manda X-CSRFToken lido do cookie (Django), so para a mesma origem…
    responseId         = 'id'  — chave do id na resposta JSON
    responseUrl        = 'url'  — chave da url na resposta JSON
    deleteUrl          = null  — se definido, remover chama DELETE aqui
    maxSize            = null  — '5mb' ou bytes
    maxFiles           = null
    autoUpload         = true  — no modo direto, comeca ao soltar
    locale             = undefined
    texts              = {}  — por cima de Tucano.setTexts({ upload }), so nesta instancia…
    onChange           = null
    onError            = null
  metodos    getFiles getValue uploadAll clear destroy
  eventos    tucano:change

### Entradas do pacote

  Tucano.init(node)         inicializa todo data-tuc-* dentro de `node`
  autoInitAccordions autoInitColorPickers autoInitContextMenus autoInitDatePickers autoInitDrawers autoInitDropdowns autoInitEditors autoInitMasks autoInitModals autoInitPagination autoInitProse autoInitSelects autoInitTables autoInitTabs autoInitToasts autoInitTooltips autoInitUploads
    → um por componente, quando voce quer inicializar so um tipo
  Accordion ColorPicker ContextMenu DatePicker Drawer Dropdown Editor FORMATS ICON_CHECK ICON_COPY ICON_X Mask Modal Pagination Popover Select Table Tabs Toast Tooltip Upload autoFormat confirm drawer getTexts highlight icon listenForEvents modal pageWindow pagination sanitize setTexts toast
  Tucano.mask / .dates / .color   modulos utilitarios (ver seção Utilitários)

  FORMATS (mascaras prontas): cpf cnpj cnpj-numeric cpf-cnpj phone mobile cep date time card currency brl

### Textos (Tucano.setTexts)

  Tucano.setTexts({ grupo: { chave: texto } }) antes de os componentes montarem;
  mescla chave a chave dentro do grupo. Tucano.getTexts() devolve uma copia.
  A opcao da instancia (emptyText, prevText, texts do upload...) vence o texto global.
  datepicker
    dialog             = 'Selecionar data'
    dialogRange        = 'Selecionar período'
    previousMonth      = 'Mês anterior'
    nextMonth          = 'Próximo mês'
    previous           = 'Anterior'
    next               = 'Próximo'
    time               = 'Horário'
    start              = 'Início'
    end                = 'Fim'
    hour               = 'Hora'
    minute             = 'Minuto'
    second             = 'Segundo'
    clear              = 'Limpar'
    apply              = 'Aplicar'
    today              = 'Hoje'
    yesterday          = 'Ontem'
    last7Days          = 'Últimos 7 dias'
    last30Days         = 'Últimos 30 dias'
    thisMonth          = 'Este mês'
    lastMonth          = 'Mês passado'
    thisYear           = 'Este ano'
    placeholderLetters = 'amdhms'
  select
    placeholder        = 'Selecione...'
    searchPlaceholder  = 'Buscar...'
    emptyText          = 'Nenhum resultado'
    loadingText        = 'Buscando...'
    errorText          = 'Falha ao buscar'
    typeToSearch       = (n) => `Digite ${n} caractere${n > 1 ? 's' : ''} para buscar`
    clear              = 'Limpar seleção'
    remove             = (label) => `Remover ${label}`
  colorpicker
    pick               = 'Escolher cor'
    dialog             = 'Seletor de cor'
    area               = 'Saturação e brilho'
    hue                = 'Matiz'
    alpha              = 'Opacidade'
    value              = 'Valor da cor'
    eyeDropper         = 'Capturar cor da tela'
  upload
    zone               = 'Arraste arquivos aqui ou clique para escolher'
    zoneOne            = 'Arraste um arquivo aqui ou clique para escolher'
    drop               = 'Solte para enviar'
    cancel             = 'Cancelar'
    remove             = 'Remover'
    repeat             = 'Tentar de novo'
    large              = (max) => `Arquivo maior que ${max}`
    type               = 'Tipo de arquivo não aceito'
    others             = (n) => `No máximo ${n} arquivo${n > 1 ? 's' : ''}`
    upTo               = (size) => `até ${size}`
    serverError        = (status) => `O servidor respondeu ${status}`
    networkError       = 'Falha de rede'
    noId               = 'O servidor não devolveu o id'
  mask
    show               = 'Mostrar'
    hide               = 'Ocultar'
    invalid            = 'Valor inválido'
    cpf                = 'CPF inválido'
    cnpj               = 'CNPJ inválido'
    cpfCnpj            = 'Documento inválido'
  toast
    region             = 'Notificações'
    close              = 'Fechar'
    loading            = 'Carregando...'
    success            = 'Pronto'
    error              = 'Algo deu errado'
  modal
    close              = 'Fechar'
    confirm            = 'Confirmar'
    cancel             = 'Cancelar'
  drawer
    close              = 'Fechar'
  table
    selectAll          = 'Selecionar todas as linhas desta página'
    selectRow          = 'Selecionar linha'
  pagination
    prevText           = 'Anterior'
    nextText           = 'Próxima'
    label              = 'Paginação'
  editor
    toolbar            = 'Formatação'
    tableToolbar       = 'Tabela'
    bold               = 'Negrito'
    italic             = 'Itálico'
    underline          = 'Sublinhado'
    title              = 'Título'
    subheading         = 'Subtítulo'
    list               = 'Lista'
    numbered           = 'Lista numerada'
    quote              = 'Citação'
    link               = 'Link'
    clear              = 'Limpar formatação'
    table              = 'Inserir tabela'
    left               = 'Alinhar à esquerda'
    center             = 'Centralizar'
    right              = 'Alinhar à direita'
    justify            = 'Justificar'
    code               = 'Código'
    variable           = 'Variável'
    rowAbove           = 'Inserir linha acima'
    rowBelow           = 'Inserir linha abaixo'
    colBefore          = 'Inserir coluna à esquerda'
    colAfter           = 'Inserir coluna à direita'
    deleteRow          = 'Excluir linha'
    deleteColumn       = 'Excluir coluna'
    deleteTable        = 'Excluir tabela'
    insertLink         = 'Inserir link'
    editLink           = 'Editar link'
    cancel             = 'Cancelar'
    removeLink         = 'Remover'
    save               = 'Salvar'
    insert             = 'Inserir'
  prose
    copy               = 'Copiar código'
    copied             = 'Copiado'

### Classes CSS

Escritas por voce no template (as com __ sao internas, montadas pelo JS):
  tuc-accordion tuc-alert tuc-badge tuc-btn tuc-btn-group tuc-check tuc-choice tuc-choices tuc-color-field tuc-colorpicker tuc-context-pin tuc-copy tuc-dp tuc-drawer tuc-dropdown tuc-editor tuc-error tuc-field tuc-hint tuc-input tuc-input-group tuc-invalid tuc-label tuc-menu tuc-modal tuc-native tuc-native-wrap tuc-pagination tuc-prose tuc-radio tuc-reveal tuc-select tuc-select-native tuc-skeleton tuc-spinner tuc-switch tuc-table tuc-table-wrap tuc-tabs tuc-timeline tuc-tip tuc-toast tuc-toasts tuc-tok-attr tuc-tok-comment tuc-tok-key tuc-tok-num tuc-tok-tag tuc-tok-text tuc-tok-tmpl tuc-upload tuc-upload-native

Montadas pelo JS dentro do componente — nao escreva no template, mas
sao nomes estaveis para o seu proprio CSS:
  tuc-accordion__arrow tuc-accordion__body tuc-accordion__content tuc-accordion__item tuc-accordion__trigger tuc-alert__actions tuc-alert__body tuc-alert__title tuc-btn__input tuc-choice__hint tuc-color-field__swatch tuc-color-field__value tuc-colorpicker__area tuc-colorpicker__field tuc-colorpicker__pick tuc-colorpicker__preview tuc-colorpicker__row tuc-colorpicker__slider tuc-colorpicker__swatchbtn tuc-colorpicker__swatches tuc-colorpicker__thumb tuc-colorpicker__track tuc-colorpicker__tracks tuc-copy__ok tuc-dp__day tuc-dp__daynum tuc-dp__footer tuc-dp__grid tuc-dp__header tuc-dp__label tuc-dp__live tuc-dp__main tuc-dp__month tuc-dp__months tuc-dp__nav tuc-dp__period tuc-dp__periodcell tuc-dp__periodgrid tuc-dp__preset tuc-dp__presets tuc-dp__row tuc-dp__spacer tuc-dp__time tuc-dp__timecols tuc-dp__timegroup tuc-dp__timehead tuc-dp__timeitem tuc-dp__timelabel tuc-dp__timelist tuc-dp__timevalue tuc-dp__weekday tuc-dp__weekdays tuc-dp__weeknum tuc-dp__weeknum-head tuc-drawer__body tuc-drawer__close tuc-drawer__footer tuc-drawer__header tuc-drawer__panel tuc-drawer__text tuc-drawer__title tuc-drawer__top tuc-dropdown__icon tuc-dropdown__item tuc-dropdown__label tuc-dropdown__separator tuc-dropdown__shortcut tuc-dropdown__text tuc-editor__area tuc-editor__scroll tuc-editor__sep tuc-editor__toolbar tuc-editor__value tuc-field__eye tuc-menu__count tuc-menu__icon tuc-menu__item tuc-menu__section tuc-menu__separator tuc-menu__sub tuc-modal__body tuc-modal__close tuc-modal__footer tuc-modal__header tuc-modal__panel tuc-modal__text tuc-modal__title tuc-modal__top tuc-pagination__edge tuc-pagination__gap tuc-pagination__word tuc-prose__block tuc-prose__scroll tuc-reveal__eye tuc-select__arrow tuc-select__check tuc-select__clear tuc-select__empty tuc-select__group tuc-select__label tuc-select__list tuc-select__menu tuc-select__option tuc-select__search tuc-select__single tuc-select__tag tuc-select__tagtext tuc-select__tagx tuc-select__values tuc-table__actions tuc-table__avatar tuc-table__check tuc-table__empty tuc-table__pick tuc-table__sortable tuc-table__sortbtn tuc-table__sorticon tuc-table__sub tuc-table__user tuc-tabs__list tuc-tabs__panel tuc-tabs__tab tuc-timeline__body tuc-timeline__head tuc-timeline__icon tuc-timeline__item tuc-timeline__time tuc-timeline__title tuc-tip__arrow tuc-tip__text tuc-toast__action tuc-toast__body tuc-toast__close tuc-toast__icon tuc-toast__text tuc-toast__title tuc-toasts__live tuc-toasts__stage tuc-upload__actions tuc-upload__bar tuc-upload__barfill tuc-upload__hidden tuc-upload__hint tuc-upload__icon tuc-upload__info tuc-upload__item tuc-upload__label tuc-upload__list tuc-upload__meta tuc-upload__name tuc-upload__ok tuc-upload__rejected tuc-upload__thumb tuc-upload__zone

### Tokens

  --tuc-accent --tuc-accent-fg --tuc-accent-hover --tuc-accent-ring --tuc-accent-soft --tuc-accent-text --tuc-bg --tuc-border --tuc-border-width --tuc-cell --tuc-control-height --tuc-danger --tuc-danger-fill --tuc-danger-soft --tuc-duration --tuc-duration-lg --tuc-duration-out --tuc-ease --tuc-ease-in --tuc-elevated --tuc-fg --tuc-font --tuc-hover --tuc-info --tuc-info-soft --tuc-muted --tuc-radius --tuc-radius-md --tuc-radius-sm --tuc-radius-xs --tuc-ring --tuc-shadow --tuc-subtle --tuc-success --tuc-success-soft --tuc-swatch --tuc-text --tuc-thumb --tuc-warning --tuc-warning-soft

## Ao gerar código que usa Tucano

- Prefira os data-attributes. Só use a API JS quando precisar de opções que não
  existem como atributo (disabledDates, presets customizados, onChange).
- Não escreva date picker, select com busca ou color picker do zero.
- Não remova o <select> nativo nem o name do input: é neles que o valor vive.
- Não estilize as classes internas (.tuc-*) diretamente; use as variáveis CSS
  em :root.
- A API é toda em inglês: open/close/toggle, size, tone, side, items, actions;
  valores como 'left', 'right', 'danger', 'success'. Não existe abrir(), tamanho
  nem 'direita'.
- Numa lista paginada, não ordene no cliente: o cabeçalho da tabela já é um <a>
  para ?sort= e ?dir=, e a ordenação tem de entrar no order_by() antes do
  Paginator. data-sort-mode="client" só para tabela pequena e sem paginação.
- Campo com erro: aria-invalid="true" no input e a mensagem em .tuc-error.
  Não invente classe vermelha; o Django 5 já escreve o atributo.
- Chegar de Tab não abre painel — é a regra do <select> nativo e do ARIA APG.
  Abrir é explícito: seta para baixo, Espaço, clique; Enter também no select.
- No painel escrito no template (dropdown), o hidden é obrigatório: sem ele o
  menu aparece no meio da página até o script rodar.
- Não desenhe um segundo botão. Para qualquer ação — inclusive ícone dentro de
  tabela ou de bloco de código — use `.tuc-btn` com `is-outline`, `is-ghost`,
  `is-icon`, `is-sm`. Classe própria só para posicionar.
- Não escreva o placeholder de um campo com máscara: ele sai do gabarito
  sozinho. `data-tuc-mask="cpf"` já nasce com `000.000.000-00`, e
  `data-tuc-mask="brl"` com `R$ 0,00`.
- Sanitize no servidor antes de publicar o que veio do editor com `|safe`. A
  peneira do editor protege o editor, não a publicação.
- O `<dialog>` do modal e da gaveta precisa do atributo `hidden`? Não — mas o
  painel do dropdown precisa. Copie o exemplo de cada seção em vez de deduzir.
- Componente inicializa sozinho no load e a cada `htmx:afterSwap`. Depois de
  inserir HTML por outro caminho, chame `Tucano.init(node)` no trecho novo.
- Elemento já inicializado ganha `data-tuc-ready`; o autoInit ignora quem tem.
  Não remova esse atributo à mão.