@thibezer/ui-components-kit 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+## 2.1.0 — 2026-10-11
+
+### `<ui-canvas-cad>`: feições genéricas (migração do MapEngine)
+
+Tudo é opt-in: o componente **não cria camadas** de feições sozinho. Pontos, segmentos, vizinhos e SIGEF continuam como antes.
+
+- **Feições**: `definirFeicoes`, `adicionarFeicao`, `atualizarFeicao`, `removerFeicao`, `obterFeicoes`. Point, LineString, Polygon (com furos), Circle (metros) e Text (arrastável), com estilo por feição, ícones SVG, rótulos permanentes (`area`, `extensao`, propriedades) e atualização incremental.
+- **Seleção e popup**: clique, Ctrl/Cmd/Shift, caixa Window (E→D) / Crossing (D→E) com toque geométrico real, popup único (`cad-selecao`, `cad-feicao-selecionada`, `cad-feicao-acao`), hit-test unificado entre camadas empilhadas (tolerância em px, alternância de cliques), `cad-feicao-hover` e `cad-feicao-menu`.
+- **Desempenho**: índice espacial próprio (sem dependências), culling por viewport acima de 300 feições, clusters de pontos (grade de 55 px), simplificação Douglas-Peucker por zoom. Meta: 100 mil feições.
+- **Snap e edição**: snap vértice > ponto médio > aresta (tecla `S`, `Alt` desliga, botão na barra, `definirSnap`); edição de vértices com alças, fantasmas nos pontos médios, exclusão pelo botão direito e HUD ao vivo (`editarVertices`).
+- **Ferramentas**: `ponto`, `linha`, `poligono`, `retangulo`, `elipse`, `poligono-regular` (hexágono), `estrela`, `circulo`, `texto`, `caneta` (Bézier), `medir-distancia`, `medir-area`, `dividir`, `selecao-laco`, `conta-gotas`. Atributo `ferramentas` mostra uma barra opcional; `definirFerramenta(nome, { fechar, iniciarEm })`, `definirCamadaDesenho`, `definirEstiloDesenho`. Clicar no primeiro vértice fecha polígono, laço, medir área e caneta (3+ vértices); o botão direito com ferramenta ativa conclui, desfaz o último vértice ou sai; `selecao-laco` seleciona feições dentro do laço e encerra. Utilitários: `gerarBuffer`, `duplicarFeicao`, `juntarFeicoes`.
+- **Versões e colaboração**: oficial × prévia (`entidadeId`, `definirPreviasGlobais`, `alternarPrevia`, `cad-previas`); cursores remotos (`atualizarCursorRemoto`, nome escapado e cor só `#hex`).
+- **Câmera**: `zoomParaFeicao(s)`, `ajustarTudo`, `ajustarCamada` (ligam camadas e prévias escondidas).
+- Exportados pelo entrypoint `./canvas`: modelo `Feicao`, algoritmos (`dividirPoligonoComLinha`, `gerarBuffer`, `juntarLinhas`, `juntarPoligonos`, `ddParaDms`, `dmsParaDd`, `converterComprimento`, `converterArea`...), índice, snap e editores.
+- Guia de migração: `docs/guia-migracao-mapengine.md`.
+
+### `<ui-canvas-cad>`: pendências da integração com o ConecteMapas
+
+Tudo opt-in: sem os atributos e opções abaixo, o componente se comporta como antes. Detalhes e exemplos em
+`docs/guia-migracao-mapengine.md`; eventos em `docs/canvas-cad-eventos.md`; números em `docs/desempenho-feicoes.md`.
+
+- **Montagem só com API pública**: `inicializarAgora(): L.Map | null` (síncrono, idempotente, cancela o agendamento do `connectedCallback`, nunca cria um 2º mapa); atributos `sem-camadas-padrao` (não cria satélite Google, SIGEF/INCRA, homologados, perímetro, vizinhos, vértices nem grade, e o clique nunca consulta o INCRA), `sem-painel-camadas`, `sem-barra-rapida` e `sem-atalho-snap` (a tecla S não alterna o snap desde o primeiro instante); `definirEstilosExternos(css | CSSStyleSheet[] | null)` injeta CSS do app no shadow root (`adoptedStyleSheets`, com `<style>` de reserva; `destroy()` limpa e a reconexão recoloca). Sem referência a `initCAD`/`initTimeout`.
+- **Posição dos HUDs**: `definirMargensHud({ topo, base, esquerda, direita })` (px) e as propriedades CSS `--cad-hud-topo/-base/-esquerda/-direita`. Os HUDs de desenho e de edição de vértices usam a mesma regra: centralizados na área visível, com largura/altura máximas e quebra de linha. Padrões = posição antiga (`base: 16`).
+- **Linha multiparte (MultiLineString)**: `LineString` aceita `partes: LatLonPar[][]` (ou `coordenadas`). *Decisão:* estender `LineString` em vez de criar um tipo `MultiLineString`, porque quebra menos: `coordenadas` continua existindo (é a 1ª parte) e todo código/consumidor que só lê `coordenadas` segue enxergando uma linha válida; uma parte só normaliza para a linha simples de sempre; nenhum `switch (geometria.tipo)` do consumidor ganha um caso novo. Coberto: normalização, desenho, hit-test (tolerância por parte), caixa Window/Crossing, laço, snap (vértices e arestas de todas as partes, sem aresta entre partes), extensão somada (métricas e rótulo), popup, simplificação por zoom, `obterFeicoes`, `duplicarFeicao`. Recusas com motivo: `editarVertices` → `cad-edicao-recusada` `multiparte`; `juntarFeicoes` → `cad-uniao-falhou` `multiparte`; `dividir` com só multilinhas → `cad-divisao-falhou` `multiparte`; `gerarBuffer` de multilinha devolve `null`. Helpers exportados: `partesDaLinha`, `ehMultilinha`, `criarLinha`.
+- **Lote e ordem**: `aplicarLote(camadaId, { adicionar, atualizar, remover }, opcoes)` faz uma regravação e um `aposDados` e devolve `{ adicionadas, atualizadas, removidas, recusadas }`; `adicionarFeicao`/`atualizarFeicao`/`removerFeicao` passam pelo mesmo caminho. O renderizador recebe só a diferença (índice, loja, oficiais e clusters por célula atualizados item a item) e a busca por id é O(1): com 100 mil feições, uma edição caiu de 60–250 ms para ~0,5 ms (ver `docs/desempenho-feicoes.md`). `atualizarFeicao(camadaId, id, parcial, { substituirPropriedades: true })` (e o mesmo em `aplicarLote`) troca as `propriedades` por inteiro em vez de mesclar.
+- **`Feicao.oculta`**: não desenha, não seleciona (clique, caixa, laço, hit-test, hover, `selecionarFeicoes`), não atrai snap e fica fora de `ajustarTudo`/`ajustarCamada`; segue nos dados, não encerra a edição de vértices em andamento, não conta como excluída e participa da regra oficial × prévia como as demais. `excluida` mantém o significado.
+- **Estilo**: texto com selo (`corFundo`, `corBorda`, `opacidadeFundo`, `raioBorda`; o selo substitui o `halo`) e ponto sem ícone com `corContorno`/`espessuraContorno`, separados do preenchimento. Cores só passam por `corSegura`; números só se finitos.
+- **Ferramentas**: `medir-distancia` com 3+ pontos mostra também área e perímetro no HUD e traz `areaM2`/`perimetroM` em `cad-medicao` (sem criar feição); círculo ignora raio < 2 m; `definirOpcoesPopup({ copiarParaAreaDeTransferencia })` torna opcional a escrita da ação "copiar"; evento cancelável `cad-texto-solicitado` (`preventDefault()` + `detalhe.concluir(texto)`) para usar modal próprio. Teste parametrizado cobre as 15 ferramentas: o ouvinte do evento de conclusão pode desativá-las sem efeito colateral e `cad-selecao` nunca sai com a ferramenta ainda ativa quando a seleção é consequência dela.
+- **Coordenada (0, 0)**: atributo/propriedade `aceitar-origem` / `aceitarOrigem` (padrão `false`) e `{ aceitarOrigem }` nas funções puras de normalização.
+
+### Correções da revisão dos componentes
+
+- **`<ui-tabela src>`**: deixou de refazer o `fetch` a cada mudança de atributo (chegava a dezenas de requisições); busca só ao conectar e quando o `src` muda. Filtro e ordenação passam a valer juntos, e o filtro olha as colunas declaradas (ignora campos fora delas e objetos).
+- **`<ui-camadas>`**: foco do teclado preservado após redesenhar; novo `emLote(fn)` agrupa mutações numa só renderização; `definirCamadas` troca a camada ativa que sumiu; `selecionarFeicao` alcança feições de camadas recolhidas; a ordem enviada pela aplicação vence a ordem salva do usuário quando ela mudou; excluir uma camada apaga o override guardado; aviso no console quando painéis dividem a chave de persistência padrão.
+- **`<ui-lista-flutuante>`**: `formReset` volta ao valor inicial mesmo após mover o elemento; `input` antes de `change`; Esc no gatilho, Tab, Home/End e foco devolvido ao gatilho; abre para cima quando falta espaço embaixo.
+- **`<ui-seletor-mapa-base>`**: `desabilitado` agora funciona; `selecionar` ignora ids fora da lista; setas/Home/End e foco no mapa ativo ao abrir pelo teclado; miniaturas sem `referrer`.
+- **`<ui-canvas-cad>`**: atalhos (`S`, Backspace, Esc) não disparam mais enquanto se digita em campos com shadow DOM; ferramentas funcionam após reconectar o componente; dividir/juntar não perdem a feição original quando o resultado é recusado; `juntarFeicoes` respeita bloqueios; `tamanhoIcone` não numérico não injeta HTML; texto bloqueado e depois liberado persiste o arraste.
+- **`<ui-tabela-propriedades>`**: `-2^2` agora vale -4 (o sinal unário pesa menos que a potência).
+
+### ⚠️ Mudanças de comportamento
+
+- Ctrl/Cmd/Shift + clique no vazio **não limpa mais** a seleção de pontos (modo aditivo).
+- Clique em marcador DOM não é mais repassado às feições do canvas por baixo.
+- `MapaConfiguracoes.magnetSnap` está **obsoleto** e sem efeito (o snap agora é do componente).
+- `adicionarFeicao`/`aplicarLote` com um `id` que já existe **substituem a feição no mesmo lugar**; antes ela ia para o fim da lista (mudava a ordem de empilhamento dentro da camada).
+- **`cad-medicao`** de `medir-distancia` passa a trazer `areaM2` e `perimetroM` quando a régua tem 3 ou mais pontos (antes só `medir-area` trazia). Quem usava `areaM2 !== undefined` para distinguir o tipo deve olhar `tipo`.
+- **Círculo**: o clique que daria raio menor que 2 m é ignorado (antes aceitava qualquer raio > 0). Feições com `Circle` de raio menor continuam válidas na entrada de dados.
+- **`dividir`**: se a feição cortada estava selecionada, a ferramenta encerra antes de a seleção mudar (para `cad-selecao` sair sem ferramenta ativa). Sem seleção envolvida, continua ativa para o próximo corte.
+- **Ordem do aviso nas medições**: `cad-medicao` agora sai depois de a ferramenta estar pronta para a próxima figura; desativar a ferramenta dentro desse evento deixava a sessão "ressuscitar" (corrigido).
+- **HUDs**: ganham `width: max-content`, largura/altura máximas e quebra de linha (o de edição de vértices não quebrava linha). Na posição padrão ficam onde estavam.
+- Valores novos nos `motivo` de `cad-edicao-recusada`, `cad-uniao-falhou` e `cad-divisao-falhou`: `multiparte`. Quem faz `switch` exaustivo precisa tratá-lo.
+- `selecionarFeicoes` e `alternarSelecaoFeicao` ignoram feições `oculta`.
+- `GerenciadorFeicoes.emitir` (uso interno/testes) ganhou um 3º parâmetro opcional `cancelavel` e pode devolver `true` para "cancelado"; o `normalizarFeicaoEntrada`, `normalizarCoordenada` e `parseCoordenada` ganharam um último parâmetro opcional `{ aceitarOrigem }` (compatível).
+
+## 2.0.0
+
+### ⚠️ Mudanças que podem exigir ajuste
+
+- **Tema segue o sistema operacional por padrão.** Antes o kit era sempre escuro. Para manter o escuro fixo, use `<html data-tema="escuro">`. `UIBus.definirTema('auto')` volta a seguir o sistema.
+- **Enter em `<ui-campo-texto>` envia o formulário**, como um campo nativo. Formulários com botão `type="submit"` e sem listener de `submit` com `preventDefault()` passam a enviar (e recarregar a página) ao pressionar Enter.
+- **`ui-abrir` / `ui-fechar` do modal disparam também ao mudar o atributo `aberto`**, não só pelos métodos `abrir()`/`fechar()`.
+- **A seleção de `<ui-tabela>` é mantida ao ordenar, filtrar ou trocar `dados`** (se o item ainda existir). Use `limparSelecao()` para zerar.
+- **Variáveis CSS renomeadas:** `--ui-fonte-mono`, `--ui-fonte-familia` e `--ui-fonte-principal` → `--ui-fonte-codigo` / `--ui-fonte-base`; `--ui-radius-*` → `--ui-raio-*`.
+- **Cores do tema claro mais escuras** para atingir contraste WCAG AA (primária `#006b40`). No escuro, o botão destrutivo passou para `#d32f2f`.
+- Removidos `UIModal._openCount` e o atributo interno `data-scroll-locked`.
+
+### Usuário final
+
+- Textos legíveis nos dois temas (contraste WCAG AA verificado em testes).
+- Tabela por teclado: cabeçalhos ordenáveis com Tab + Enter, linhas com setas, Home/End, PageUp/PageDown, Enter para selecionar.
+- Modal: foco inicial no conteúdo (ou `[autofocus]`), foco devolvido ao fechar, Esc fecha o modal do topo, segundo modal aberto continua interativo, "✕" oculto com `bloquear-fechamento`.
+- Tooltip lido por leitores de tela, fecha com Esc e não some ao levar o ponteiro até o balão.
+- Botões só com ícone recebem nome acessível (`aria-label` ou `title`).
+- Gatilhos Zero-JS ignoram botões desabilitados ou carregando.
+- Correção de segurança: o `label` de campos nunca é interpretado como HTML.
+
+### Desenvolvedor
+
+- **Tipos para React e Vue** gerados a partir do Custom Elements Manifest: `@thibezer/ui-components-kit/tipos-react`, `/tipos-vue` e `/tipos-elementos`.
+- **`custom-elements.json`** publicado (campo `customElements`), para IDEs, Storybook e documentação.
+- **`::part`** nos 14 componentes principais, com estados (`opcao-selecionada`, `linha-selecionada`).
+- **Tokens unificados:** fontes `--ui-fonte-base` / `--ui-fonte-codigo`; escala de raio derivada de `--ui-raio-borda` (`--ui-raio-sm/lg/xl/pill`); novos `--ui-cor-texto-info`, `--ui-cor-texto-sobre-status`, `--ui-cor-fundo-recuado`, `--ui-sombra-sm/md/lg`.
+- `<ui-botao>` form-associated: `form="id"`, `<fieldset disabled>`, `name`/`value` no `e.submitter`, `disabled` como propriedade, `click()` no host.
+- `UIBus.obterTema()`; `tema:alterado` também quando o sistema troca de tema.
+- `<ui-tabela>`: `aria-label` repassado à tabela, `aria-busy` durante o carregamento.
+- README corrigido (exemplo React, atributos do catálogo, import map para mapa/CAD via CDN).
+
+## 1.0.0
+
+- Primeira publicação no npm como `@thibezer/ui-components-kit`.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 thibezer
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 thibezer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 Biblioteca de **Web Components Nativos Universais e Agnósticos**, construída no padrão oficial **W3C Custom Elements + Shadow DOM**, com TypeScript, Design Tokens em CSS modular e Vite.
 
-Projetada para funcionar em **qualquer linguagem, framework ou sistema web** (HTML puro, React, Next.js, Vue, Angular, Svelte, PHP, Django, WordPress, Blazor, etc.) com **zero dependências externas**.
+Projetada para funcionar em **qualquer linguagem, framework ou sistema web** (HTML puro, React, Next.js, Vue, Angular, Svelte, PHP, Django, WordPress, Blazor, etc.) com **zero dependências externas** (exceto `<ui-mapa>` e `<ui-canvas-cad>`, que usam o Leaflet como dependência opcional).
 
 ---
 
@@ -54,6 +54,16 @@ Adicione as tags no `<head>` ou antes do fechamento do `</body>`:
 <ui-botao-primario variante="primary">Clique Aqui</ui-botao-primario>
 ```
 
+> **Mapa e CAD via CDN (`<ui-mapa>`, `<ui-canvas-cad>`)**: esses componentes dependem do [Leaflet](https://leafletjs.com/), importado como `leaflet` (especificador "bare"), que o navegador só resolve com um *import map*. Declare-o **antes** do script da biblioteca:
+>
+> ```html
+> <script type="importmap">
+>   { "imports": { "leaflet": "https://cdn.jsdelivr.net/npm/leaflet@1.9.4/+esm" } }
+> </script>
+> ```
+>
+> Os demais componentes não precisam do Leaflet. Com npm, basta `npm install leaflet`.
+
 ### Opção 2: NPM / Módulos ES (React, Vue, Next.js, Vite)
 
 Instale pelo npm:
@@ -258,6 +268,62 @@ Todos os componentes flutuantes consomem tokens de elevação previsíveis (com
 <ui-switch aria-label="Camada visível"></ui-switch>
 ```
 
+### 8. Temas Claro e Escuro
+Sem configuração, o kit **segue o tema do sistema operacional** (`prefers-color-scheme`). Para fixar um tema, use o atributo na raiz — ou em qualquer elemento, para fixar só aquele trecho:
+```html
+<html data-tema="escuro">   <!-- ou "claro"; também aceitos: class="dark|light" e data-theme="dark|light" -->
+<aside data-tema="claro">…</aside>   <!-- trecho claro dentro de uma página escura -->
+```
+```javascript
+UIBus.definirTema('auto');   // volta a seguir o SO
+UIBus.on('tema:alterado', ({ tema }) => { /* também dispara quando o SO muda, se o tema não estiver fixado */ });
+```
+Os componentes recebem o tema **apenas pelos tokens de cor** (`--ui-cor-*`, `--ui-sombra-*`), que atravessam o Shadow DOM. Todo token de texto atinge contraste **WCAG AA (4,5:1)** nos dois temas, inclusive sobre fundos tingidos de status e no texto sobre a cor primária e o botão destrutivo — verificado em `tests/tema.test.ts`.
+
+| Token | Uso |
+| :--- | :--- |
+| `--ui-cor-texto-sucesso` / `-erro` / `-alerta` / `-info` | Texto e tons de status (alertas, badges, toasts) |
+| `--ui-cor-texto-sobre-status` | Texto sobre fundo sólido de status (badge sólido) |
+| `--ui-cor-fundo-recuado` | Faixas rebaixadas (rodapés de modal e drawer) |
+| `--ui-sombra-sm` / `-md` / `-lg` | Sombras: densas no escuro, suaves no claro |
+
+### 9. Tipografia e Raios
+Todos os componentes usam apenas dois tokens de família de fonte e uma escala de raios derivada de `--ui-raio-borda`. Sobrescreva no `:root` (a escala é calculada lá):
+```css
+:root {
+  --ui-fonte-base: 'Roboto', sans-serif;      /* textos da interface */
+  --ui-fonte-codigo: 'JetBrains Mono', monospace; /* coordenadas, valores técnicos, código */
+
+  --ui-raio-borda: 4px;  /* base: botões, campos, menus */
+  /* derivados automaticamente: --ui-raio-sm (2/3), --ui-raio-lg (5/3), --ui-raio-xl (8/3) */
+  /* --ui-raio-borda: 0  →  interface totalmente reta */
+}
+```
+
+### 10. Estilização Interna com `::part`
+O Shadow DOM isola o CSS, mas os elementos internos principais são expostos com `part`, com nomes consistentes entre componentes (uma regra serve para vários):
+
+| Componente | Parts |
+| :--- | :--- |
+| `<ui-botao>` / `<ui-botao-primario>` | `base`, `spinner` |
+| `<ui-campo-texto>` / `<ui-input>` | `rotulo`, `campo`, `input`, `icone`, `icone-esquerda`, `icone-direita`, `ajuda` |
+| `<ui-lista-flutuante>` / `<ui-select>` | `rotulo`, `campo`, `valor`, `seta`, `lista`, `opcao`, `opcao-selecionada` |
+| `<ui-checkbox>`, `<ui-radio>`, `<ui-switch>` | `base`, `controle`, `indicador`, `rotulo` |
+| `<ui-segmented>` | `base`, `indicador`, `opcao`, `opcao-selecionada` |
+| `<ui-modal>`, `<ui-drawer>` | `fundo`, `painel`, `cabecalho`, `titulo`, `descricao` (drawer), `fechar`, `corpo`, `rodape` |
+| `<ui-card>` | `base`, `midia`, `cabecalho`, `corpo`, `rodape` |
+| `<ui-badge>` / `<ui-chip>` | `base`, `rotulo`, `remover` |
+| `<ui-alerta>` / toasts | `base`, `icone`, `conteudo`, `titulo`, `mensagem`, `acao`, `fechar`, `progresso` |
+| `<ui-tooltip>` | `balao`, `texto`, `seta` |
+| `<ui-tabela>` | `base`, `tabela`, `celula-cabecalho`, `ordenar`, `linha`, `linha-selecionada`, `celula`, `vazio`, `carregando` |
+
+```css
+ui-campo-texto::part(campo) { border-width: 2px; }
+ui-modal::part(painel) { max-width: 720px; }
+ui-tabela::part(linha-selecionada) { background: #0b3d2a; }
+:is(ui-checkbox, ui-radio, ui-switch)::part(rotulo) { font-weight: 600; }
+```
+
 ---
 
 ## ⚡ Recursos Inteligentes de Alta Produtividade
@@ -299,7 +365,7 @@ Você pode acionar modais, fechar janelas, disparar notificações toast ou copi
 | `toast-alerta="msg"` | Dispara uma notificação flutuante de aviso. | `toast-alerta="Preencha os campos obrigatórios."` |
 | `copiar-texto="texto\|#id"` | Copia o texto ou o valor do elemento referenciado. | `copiar-texto="#campo-pix"` |
 | `limpar-form="id"` | Reseta todos os campos do formulário indicado. | `limpar-form="form-cadastro"` |
-| `alternar-tema` | Alterna entre tema claro e escuro globalmente. | `alternar-tema` |
+| `alternar-tema` | Alterna entre tema claro e escuro globalmente (a partir do tema em vigor, inclusive o do SO). | `alternar-tema` |
 
 ---
 
@@ -331,6 +397,8 @@ form.addEventListener('submit', (e) => {
 });
 ```
 
+Assim como nos campos nativos, **Enter** em um `<ui-campo-texto>` submete o formulário pelo botão de envio padrão (`<ui-botao-primario type="submit">` ou `<button>`), que também pode estar fora do `<form>` com `form="id-do-form"`. Para impedir, chame `preventDefault()` no `keydown`. O `name`/`value` do botão que submeteu chega como `e.submitter` (use `new FormData(form, e.submitter)`), e gatilhos Zero-JS em botões `disabled` ou `carregando` são ignorados.
+
 ---
 
 ### 3. Barramento Global de Orquestração (`UIBus`)
@@ -345,7 +413,8 @@ UIBus.fecharModal('modal-confirmacao');
 UIBus.notificar({ tipo: 'sucesso', mensagem: 'Operação concluída!' });
 UIBus.copiar('Texto para a área de transferência', 'Copiado!');
 UIBus.definirDensidade('compacta'); // 'compacta' | 'normal' | 'relaxada'
-UIBus.definirTema('escuro');        // 'claro' | 'escuro'
+UIBus.definirTema('escuro');        // 'claro' | 'escuro' | 'auto' (segue o SO); sem argumento, alterna
+UIBus.obterTema();                  // tema em vigor: 'claro' | 'escuro'
 
 // 2. Comunicação Desacoplada (Pub/Sub):
 UIBus.on('vertice:selecionado', (dadosVertice) => {
@@ -422,6 +491,26 @@ tabela.recarregar();   // Recarrega os dados da API remota
 
 A biblioteca é **100% SSR-safe**: todas as classes herdam de `SafeHTMLElement` e o registro de tags utiliza verificações de segurança para ambientes sem DOM (Node.js). Isso garante que você pode importar tipos, classes e constantes tanto no servidor quanto no cliente sem encontrar `ReferenceError: HTMLElement is not defined` ou `customElements is not defined`.
 
+#### Tipos no TSX (autocompletar e checagem)
+O pacote gera tipos para todas as tags a partir do Custom Elements Manifest. Registre-os uma vez no `tsconfig.json`:
+
+```json
+{ "compilerOptions": { "types": ["@thibezer/ui-components-kit/tipos-react"] } }
+```
+
+A partir daí o editor sugere atributos, propriedades e eventos de cada tag, e o TypeScript recusa valores inválidos:
+
+```tsx
+<ui-tabela
+  colunas={[{ id: 'ponto', rotulo: 'Ponto', ordenavel: true }]}   // tipado como TabelaColuna[]
+  densidade="compacta"                                             // 'compacta' | 'normal' | 'relaxada'
+  onui-sort={(e) => console.log(e.detail)}                         // eventos ui-* no formato do React 19
+/>
+<ui-tabela densidade="enorme" />                                   // ❌ erro de tipo
+```
+
+Outros JSX (Preact, Solid etc.) podem usar o mapa agnóstico `ElementosUI` de `@thibezer/ui-components-kit/tipos-elementos`.
+
 #### No Next.js (App Router):
 
 Crie um componente cliente provedor ou registre no topo do seu layout/página cliente:
@@ -451,9 +540,10 @@ import '@thibezer/ui-components-kit/forms';
 import '@thibezer/ui-components-kit/botao';
 import '@thibezer/ui-components-kit/tabela';
 import { UIBus } from '@thibezer/ui-components-kit/core';
+import type { UITabela } from '@thibezer/ui-components-kit/tabela';
 
 export default function DashboardPropriedades() {
-  const tabelaRef = useRef<any>(null);
+  const tabelaRef = useRef<UITabela>(null);
   const [nome, setNome] = useState('');
 
   useEffect(() => {
@@ -474,8 +564,10 @@ export default function DashboardPropriedades() {
         label="Pesquisar Imóvel"
         value={nome}
         onInput={(e: any) => {
-          setNome(e.detail?.value || '');
-          tabelaRef.current?.filtrar(e.detail?.value || '');
+          // Os eventos nativos `input`/`change` não têm `detail`: leia o valor do próprio elemento
+          const valor = e.target.value;
+          setNome(valor);
+          tabelaRef.current?.filtrar(valor);
         }}
       ></ui-campo-texto>
 
@@ -494,6 +586,18 @@ export default function DashboardPropriedades() {
 ---
 
 ### Vue.js
+
+Para autocompletar e checar props e eventos nos templates (Volar), registre os tipos no `tsconfig.json` e informe ao Vue que tags `ui-*` são custom elements:
+
+```json
+{ "compilerOptions": { "types": ["@thibezer/ui-components-kit/tipos-vue"] } }
+```
+
+```javascript
+// vite.config.js
+vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('ui-') } } })
+```
+
 ```vue
 <template>
   <div class="container">
@@ -563,7 +667,7 @@ window.addEventListener('message', (event) => {
 ### 🟢 Camada 1: Fundamentos
 | Tag | Descrição | Principais Atributos / Props | Eventos Emitidos |
 | :--- | :--- | :--- | :--- |
-| `<ui-botao-primario>` | Botão com estados de loading, ícone e variantes. | `variante`, `carregando`, `disabled`, `target-modal` | `ui-click` |
+| `<ui-botao-primario>` | Botão com estados de loading, ícone e variantes. Form-associated (`type="submit"`/`"reset"`, `name`/`value`, `form`). Só com ícone, informe `aria-label` (ou `title`). | `variante`, `carregando`, `disabled`, `type`, `aria-label`, `target-modal` | `ui-click` |
 | `<ui-campo-texto>` | Input de texto com Floating Label, validação e senha. | `label`, `value`, `tipo`, `obrigatorio`, `name` | `ui-input`, `ui-change` |
 | `<ui-lista-flutuante>` | Select/Dropdown com Bottom Sheet no mobile. | `itens`, `value`, `placeholder`, `name` | `ui-selecionar` |
 | `<ui-texto>` | Tipografia semântica (H1-H6, corpo, caption, código). | `variante`, `cor`, `peso` | - |
@@ -577,26 +681,52 @@ window.addEventListener('message', (event) => {
 | `<ui-switch>` | Chave de alternância liga/desliga física instantânea. | `ativo`, `name`, `value` | `ui-change` |
 | `<ui-segmented>` | Controle segmentado de opções (Pills/Tabs deslizantes). | `opcoes`, `value`, `name`, `tamanho` | `ui-change`, `ui-selecionar` |
 | `<ui-badge>` / `<ui-chip>` | Tags de status e chips com botão de remoção. | `variante`, `removivel`, `value` | `ui-remove` |
-| `<ui-avatar>` | Avatar com fotos, iniciais e status online. | `nome`, `foto`, `status`, `tamanho` | - |
+| `<ui-avatar>` | Avatar com fotos, iniciais e status online. | `nome`, `src`, `status`, `tamanho` | - |
 
 ### 🟣 Camada 3: Contêineres, Overlays, Dados & GIS
 | Tag | Descrição | Principais Atributos / Props | Eventos Emitidos |
 | :--- | :--- | :--- | :--- |
 | `<ui-card>` | Cartão de conteúdo com slots nomeados e elevação. | `elevacao`, `clicavel` | `ui-click` |
-| `<ui-modal>` | Modal centralizado no PC e Bottom Sheet no Mobile. | `aberto`, `titulo`, `bottom-sheet` | `ui-abrir`, `ui-fechar` |
-| `<ui-drawer>` | Painel lateral deslizante (Sheet/Gaveta direita/esquerda). | `aberto`, `lado`, `titulo`, `largura` | `ui-abrir`, `ui-fechar` |
+| `<ui-modal>` | Modal centralizado no PC e Bottom Sheet no Mobile. Abrir/fechar por `abrir()`/`fechar()` ou pelo atributo `aberto` tem o mesmo efeito (eventos, foco, `inert`). Foco inicial no `[autofocus]` ou no primeiro controle do conteúdo; ao fechar, volta ao gatilho. Modais empilhados: só o último aberto é interativo. | `aberto`, `titulo`, `bottom-sheet`, `bloquear-fechamento` (oculta o "✕" e ignora Esc/fundo) | `ui-abrir`, `ui-fechar` |
+| `<ui-drawer>` | Painel lateral deslizante (Sheet/Gaveta direita/esquerda). | `aberto`, `posicao` (`direita`, `esquerda`, `baixo`, `cima`), `titulo`, `largura` | `ui-abrir`, `ui-fechar` |
 | `<ui-alerta>` | Banner de notificação contextual fixo. | `variante`, `titulo`, `fechavel` | `ui-fechar` |
 | `<ui-toast>` | Notificações flutuantes inteligentes com pilha flex. | `UIToast.notificar({ tipo, mensagem })` | - |
-| `<ui-tooltip>` | Dica contextual inteligente (Hover PC / Toque Mobile). | `texto`, `posicao`, `gatilho` | - |
+| `<ui-tooltip>` | Dica contextual inteligente (Hover PC / Toque Mobile). O texto vira `aria-description` do gatilho (lido pelo leitor de tela, também repassado pelo `<ui-botao>`); **Esc** fecha sem mover o foco; o balão não some ao levar o ponteiro até ele. | `texto`, `posicao`, `gatilho` | - |
 | `<ui-skeleton>` | Placeholder de carregamento animado com pulsos. | `tipo`, `largura`, `altura`, `animado` | - |
-| `<ui-stat>` | Cartão KPI de estatísticas, métricas e tendências. | `rotulo`, `valor`, `variacao`, `tipo-variacao` | - |
-| `<ui-tabela>` | Tabela orientada a dados, virtualizada tipo Excel. | `colunas`, `dados`, `src`, `densidade` | `ui-sort`, `ui-column-resize` |
+| `<ui-stat>` | Cartão KPI de estatísticas, métricas e tendências. | `rotulo`, `valor`, `variacao`, `tendencia` (`alta`, `baixa`, `neutro`) | - |
+| `<ui-tabela>` | Tabela orientada a dados, virtualizada tipo Excel. **Teclado**: cabeçalhos ordenáveis são botões (Tab + Enter/Espaço, com `aria-sort`); nas linhas, ↑/↓, Home/End e PageUp/PageDown movem o foco e Enter/Espaço selecionam (`aria-current`). A seleção é mantida ao ordenar e filtrar. Nome acessível via `aria-label`. | `colunas`, `dados`, `src`, `densidade`, `aria-label` | `ui-sort`, `ui-column-resize`, `ui-linha-clique` |
 | `<ui-tabela-propriedades>` | Inspetor de propriedades técnicas padrão AutoCAD & Revit com cálculos matemáticos inline (+, -, *, /, ^, %), arraste de valor contínuo (scrubbing), splitter redimensionável e editores CAD. | `categorias`, `tipo-objeto`, `splitter-pos`, `modo-aplicar`, `filtro` | `ui-propriedade-alterada`, `ui-aplicar`, `ui-desfazer`, `ui-editar-tipo`, `ui-acao-clique`, `ui-quick-select`, `ui-calculadora` |
 | `<ui-ribbon>` | Barra de ferramentas em abas e grupos (estilo AutoCAD / Word / Excel): botões grandes e pequenos em colunas de 3, toggles, menus suspensos, abas contextuais, modo recolhido (duplo clique na aba) e navegação por teclado (roving tabindex). | `abas`, `aba-ativa`, `recolhido`, `compacto` | `ui-ferramenta`, `ui-aba-change` |
 | `<ui-paleta-ferramentas>` | Paleta de ferramentas (estilo Illustrator / Photoshop): seleção exclusiva, grupos com flyout (clique longo, botão direito ou seta), 1 ou 2 colunas, vertical/horizontal e atalhos de teclado que percorrem o grupo. | `ferramentas`, `valor`, `orientacao`, `colunas`, `tamanho`, `atalhos` | `ui-change`, `ui-selecionar`, `ui-ferramenta` |
 | `<ui-mapa>` | Mapa geográfico interativo com camadas OpenStreetMap. | `lat`, `lng`, `zoom`, `camadas` | - |
 | `<ui-camadas>` | Painel de camadas vetoriais CAD/GIS com hierarquia em árvore, barra de arraste vertical (`redimensionavel`), estabilidade de altura sem colapso, drag-and-drop, métricas geodésicas e persistência no LocalStorage. | `redimensionavel`, `altura`, `min-altura`, `max-altura`, `flutuante`, `colapsado`, `camada-ativa`, `persistir` | `ui-redimensionar-altura`, `ui-camada-selecionada`, `ui-camada-visibilidade`, `ui-camadas-reordenadas`, `ui-acao-massa` |
-| `<ui-canvas-cad>` | Mesa CAD/GIS para poligonais e vértices geodésicos. | `pontos`, `segmentos`, `fitBounds()` | `ui-ponto-selecionado` |
+| `<ui-canvas-cad>` | Mesa CAD/GIS para poligonais, vértices geodésicos e **feições genéricas** (ponto, linha, polígono, círculo, texto) que você cria: seleção por clique e caixa, popup, edição de vértices, snap, 15 ferramentas de desenho/medição, oficial × prévia, cursores remotos e culling/clusters para 100 mil feições. Linha multiparte, feição `oculta`, selo de texto e contorno de ponto. Nenhuma camada vem pronta. Guia: [`docs/guia-migracao-mapengine.md`](docs/guia-migracao-mapengine.md). | `pontos`, `segmentos`, `ferramentas`, `sem-camadas-padrao`, `sem-painel-camadas`, `sem-barra-rapida`, `sem-atalho-snap`, `aceitar-origem`, `inicializarAgora()`, `definirFeicoes()`, `aplicarLote()`, `definirFerramenta()`, `editarVertices()`, `definirMargensHud()`, `definirEstilosExternos()`, `fitBounds()` | `ui-ponto-selecionado`, `cad-selecao`, `cad-feicao-selecionada`, `cad-feicao-criada`, `cad-feicao-atualizada`, `cad-feicao-hover`, `cad-feicao-menu`, `cad-snap`, `cad-previas` e outros (ver `docs/canvas-cad-eventos.md`) |
+
+#### `<ui-canvas-cad>`: montar só com API pública (2.1)
+
+```html
+<ui-canvas-cad id="mesa" sem-camadas-padrao sem-painel-camadas sem-barra-rapida sem-atalho-snap aceitar-origem></ui-canvas-cad>
+```
+```js
+const mapa = mesa.inicializarAgora();                    // L.Map síncrono (idempotente; nunca cria um 2º mapa)
+mesa.definirEstilosExternos([...document.styleSheets]);  // CSS do app dentro do shadow root (string ou folhas)
+mesa.definirMargensHud({ base: 56, direita: 320 });      // HUDs de desenho/edição fora de barras e painéis
+mesa.aplicarLote('glebas', { adicionar, atualizar, remover });  // uma regravação, ordem preservada
+mesa.atualizarFeicao('glebas', 'g1', { propriedades }, { substituirPropriedades: true });
+mesa.definirOpcoesPopup({ copiarParaAreaDeTransferencia: false });
+```
+
+- Camadas de fábrica (satélite, SIGEF, homologados, perímetro, vizinhos, vértices, grade) só somem com `sem-camadas-padrao`; sem
+  o atributo continuam como sempre.
+- `Feicao.oculta` (não desenha nem seleciona, mas existe) ≠ `Feicao.excluida`. Linha multiparte: `geometria.partes`.
+- Tudo, com exemplos: [`docs/guia-migracao-mapengine.md`](docs/guia-migracao-mapengine.md) · eventos e ordem das ferramentas:
+  [`docs/canvas-cad-eventos.md`](docs/canvas-cad-eventos.md) · números de desempenho: [`docs/desempenho-feicoes.md`](docs/desempenho-feicoes.md).
+
+
+---
+
+### Custom Elements Manifest
+O pacote publica `custom-elements.json` (campo `customElements` do `package.json`), o formato padrão que IDEs, Storybook e geradores de documentação leem para listar tags, atributos, propriedades, eventos e `::part` de cada componente. Ele é gerado no `npm run build` pelo [`@custom-elements-manifest/analyzer`](https://custom-elements-manifest.open-wc.org/), e os tipos React/Vue são derivados dele — por isso nunca ficam desatualizados em relação ao código.
 
 ---
 
@@ -622,3 +752,9 @@ window.addEventListener('message', (event) => {
    * `dist/index.cjs` e `dist/<modulo>.cjs` (CommonJS para `require`)
    * `dist/*.d.ts` (Tipagens TypeScript)
    * `dist/ui-kit.css` (Design Tokens compilados, 100% autocontido — o build falha se restar qualquer `@import`)
+   * `dist/custom-elements.json` (Custom Elements Manifest) e `dist/tipos-react.d.ts`, `dist/tipos-vue.d.ts`, `dist/tipos-elementos.d.ts`
+
+4. **Verificar os tipos gerados** (depois do build):
+   ```bash
+   npm run test:tipos
+   ```

package/dist/botao.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});;/* empty css                 */const o=require("./ui-botao-DF1yuUUD.cjs");exports.UIBotao=o.UIBotao;exports.UIBotaoPrimario=o.UIBotaoPrimario;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});;/* empty css                 */const o=require("./ui-botao-psS1juof.cjs");exports.UIBotao=o.UIBotao;exports.UIBotaoPrimario=o.UIBotaoPrimario;

package/dist/botao.js

@@ -1,5 +1,5 @@
 /* empty css               */
-import { U as t, a as i } from "./ui-botao-BShEouvi.js";
+import { U as t, a as i } from "./ui-botao-OGJV6Vfk.js";
 export {
   t as UIBotao,
   i as UIBotaoPrimario