@thibezer/ui-components-kit 2.6.0 → 2.7.0

package/dist/components/ui-cores/ui-controle-cores.d.ts

@@ -79,11 +79,16 @@ export declare class UIControleCores extends SafeHTMLElement {
     semCor(alvo?: AlvoCor): void;
     /** Volta às cores de `padrao-preenchimento` e `padrao-traco`; emite `ui-cores-change` confirmado. */
     restaurarPadrao(): void;
-    /** Abre o seletor de cor ancorado na amostra do alvo (que passa a ser o ativo). */
-    abrirSeletor(alvo?: AlvoCor): void;
-    /** Fecha o seletor aberto por este controle (confirmando, por padrão). */
+    /** Abre o seletor de cor ancorado na amostra do alvo (que passa a ser o ativo). Com `focar`, leva o foco do teclado para o painel. */
+    abrirSeletor(alvo?: AlvoCor, focar?: boolean): void;
+    /**
+     * Fecha o seletor aberto por este controle. Com `confirmar` (padrão), grava o que foi editado;
+     * sem ele, cancela: as cores iniciais voltam (com um `ui-cores-change` não confirmado) e nada é confirmado.
+     */
     fecharSeletor(confirmar?: boolean): void;
     private mudarAlvo;
+    /** Mantém a aba do seletor aberto igual ao alvo do controle. */
+    private sincronizarSeletor;
     private aplicarDoSeletor;
     private emitirCores;
     private dica;

package/dist/components/ui-cores/ui-seletor-cor.d.ts

@@ -1,7 +1,7 @@
 import { SafeHTMLElement } from '../../core/ssr-safe';
 import { AlvoCor, DetalheSeletorCor, OpcoesSeletorCor, SeletorCorAberto, ValorCor } from './tipos';
 /** Configuração aceita por `UISeletorCor.configurar()` (as opções de `abrirSeletorCor` sem âncora e callbacks). */
-export type ConfiguracaoSeletorCor = Omit<OpcoesSeletorCor, 'ancora' | 'aoAlterar' | 'aoConfirmar' | 'aoCancelar' | 'aoTrocarAlvo'>;
+export type ConfiguracaoSeletorCor = Omit<OpcoesSeletorCor, 'ancora' | 'focar' | 'aoAlterar' | 'aoConfirmar' | 'aoCancelar' | 'aoTrocarAlvo'>;
 /**
  * <ui-seletor-cor> — painel de cor no estilo Illustrator: abas Preenchimento/Traço, prévia
  * antes × depois, hexadecimal, seletor do sistema, opacidade do preenchimento, cores do projeto,
@@ -51,6 +51,8 @@ export declare class UISeletorCor extends SafeHTMLElement {
     private get opacidadeVisivel();
     private renderizar;
     private atualizarVisual;
+    /** `activeElement` lança em alguns DOMs simulados quando o foco está em outra árvore de sombra. */
+    private campoEmFoco;
     private vincularEventos;
     private emitir;
 }

package/dist/components/ui-mapa/mapa-atributos.d.ts

@@ -0,0 +1,14 @@
+import { VistaMapa } from './tipos';
+export declare const VISTA_PADRAO: VistaMapa;
+export declare const COR_MARCADOR_PADRAO = "#00f5a0";
+export declare const COR_LINHA_PADRAO = "#3388ff";
+export declare const ESPESSURA_PADRAO = 3;
+/** Lê lat/lng/zoom; cada campo inválido (ou fora de -90..90, -180..180, 0..22) cai no padrão. */
+export declare function lerVista(lat: string | null, lng: string | null, zoom: string | null): VistaMapa;
+export declare function lerInteiroPositivo(valor: string | null, padrao: number): number;
+/** Aceita só cores CSS conhecidas (hex, rgb/hsl, nome); qualquer outra coisa vira `padrao`. Impede injeção em estilo/atributo. */
+export declare function corSegura(cor: string | null | undefined, padrao: string): string;
+/** Lista de camadas base pedidas, filtrada pelas conhecidas; vazia → `['osm']`. */
+export declare function lerCamadas(texto: string | null, conhecidas: string[]): string[];
+/** Interpreta `pontos` (JSON `[[lat, lng], ...]`); descarta pares inválidos e devolve `[]` se o JSON não for um array. */
+export declare function lerPontos(texto: string | null): Array<[number, number]>;

package/dist/components/ui-mapa/mapa-basemaps.d.ts

@@ -0,0 +1,7 @@
+import { TileLayer } from 'leaflet';
+import { LeafletModulo } from './tipos';
+export interface Basemap {
+    nome: string;
+    layer: () => TileLayer;
+}
+export declare function obterBasemaps(L: LeafletModulo): Record<string, Basemap>;

package/dist/components/ui-mapa/mapa-icones.d.ts

@@ -0,0 +1,4 @@
+import { DivIcon } from 'leaflet';
+import { FormatoMarcador, LeafletModulo } from './tipos';
+/** `cor` já deve ter passado por `corSegura`. */
+export declare function criarIconeMarcador(L: LeafletModulo, cor: string, formato: FormatoMarcador): DivIcon;

package/dist/components/ui-mapa/mapa-leaflet.d.ts

@@ -0,0 +1,5 @@
+import { LeafletModulo } from './tipos';
+/** `L` se o Leaflet já estiver carregado (global ou importado), senão `null`. */
+export declare function obterLeaflet(): LeafletModulo | null;
+/** Carrega o Leaflet sob demanda; `null` se não estiver instalado. */
+export declare function carregarLeafletTipado(): Promise<LeafletModulo | null>;

package/dist/components/ui-mapa/mapa-vinculo-pai.d.ts

@@ -0,0 +1,22 @@
+import { default as L } from 'leaflet';
+export interface OpcoesVinculo {
+    /** Nome da tag, só para as mensagens de aviso. */
+    rotulo: string;
+    /** O mapa do pai está pronto: crie a camada. */
+    aoMapa: (mapa: L.Map) => void;
+    /** O mapa anterior se foi (o pai o recriou): descarte a camada antiga. */
+    aoPerderMapa: () => void;
+}
+export declare class VinculoMapaPai {
+    private host;
+    private opcoes;
+    private pai;
+    private timer;
+    private tentativas;
+    constructor(host: HTMLElement, opcoes: OpcoesVinculo);
+    conectar(): void;
+    desconectar(): void;
+    private aoPronto;
+    private agendar;
+    private tentar;
+}

package/dist/components/ui-mapa/tipos.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tipos compartilhados do <ui-mapa> e de seus filhos.
+ * Responsabilidade única: descrever o módulo do Leaflet e a vista padrão sem recorrer a `any`.
+ */
+import type * as Leaflet from 'leaflet';
+/** O módulo do Leaflet (o `L` global). */
+export type LeafletModulo = typeof Leaflet;
+export interface VistaMapa {
+    lat: number;
+    lng: number;
+    zoom: number;
+}
+export type FormatoMarcador = 'pin' | 'circle';

package/dist/components/ui-mapa/ui-mapa-linha.d.ts

@@ -1,12 +1,19 @@
 import { SafeHTMLElement } from '../../core/ssr-safe';
+/**
+ * Polilinha dentro de um `<ui-mapa>`.
+ *
+ * @attr {string} pontos - JSON `[[lat, lng], ...]`; pares inválidos são ignorados.
+ * @attr {string} cor - Cor do traço (hex, rgb/hsl ou nome; outro valor usa a cor padrão).
+ * @attr {number} espessura - Espessura em pixels (inteiro positivo; padrão 3).
+ */
 export declare class UIMapaLinha extends SafeHTMLElement {
     static get observedAttributes(): string[];
     private polyline;
-    private _initTimer;
-    private _retryCount;
+    private vinculo;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(name: string, oldVal: string, newVal: string): void;
-    private getPontos;
-    private initLinha;
+    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
+    private estilo;
+    private removerLinha;
+    private criarLinha;
 }

package/dist/components/ui-mapa/ui-mapa-marcador.d.ts

@@ -1,15 +1,24 @@
 import { SafeHTMLElement } from '../../core/ssr-safe';
+/**
+ * Marcador dentro de um `<ui-mapa>`.
+ *
+ * @attr {number} lat - Latitude (inválida: o marcador não é criado).
+ * @attr {number} lng - Longitude.
+ * @attr {string} titulo - Texto do popup e nome acessível do marcador (aria-label e title).
+ * @attr {string} cor - Cor do ícone (hex, rgb/hsl ou nome; outro valor usa a cor padrão).
+ * @attr {'pin'|'circle'} formato - Forma do ícone (padrão `pin`).
+ */
 export declare class UIMapaMarcador extends SafeHTMLElement {
     static get observedAttributes(): string[];
     private marker;
-    private _initTimer;
-    private _retryCount;
-    private _parentMap;
+    private vinculo;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    private handleMapReady;
-    attributeChangedCallback(name: string, oldVal: string, newVal: string): void;
+    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
+    private removerMarcador;
     private createPopupContent;
     private createIcon;
-    private initMarker;
+    /** O ícone é um `div`: o nome acessível vai em `aria-label` (o Leaflet já põe `role=button` e `tabindex=0`). */
+    private aplicarNomeAcessivel;
+    private criarMarcador;
 }

package/dist/components/ui-mapa/ui-mapa.d.ts

@@ -1,5 +1,15 @@
 import { default as L } from 'leaflet';
 import { SafeHTMLElement } from '../../core/ssr-safe';
+/**
+ * Mapa Leaflet encapsulado. Aceita `<ui-mapa-marcador>` e `<ui-mapa-linha>` como filhos.
+ *
+ * @attr {number} lat - Latitude do centro (-90..90; inválida cai no padrão).
+ * @attr {number} lng - Longitude do centro (-180..180; inválida cai no padrão).
+ * @attr {number} zoom - Zoom inicial (0..22; inválido cai no padrão).
+ * @attr {string} camadas - Camadas base separadas por vírgula (`osm`, `satelite`, `topografia`, `ruas`).
+ * @attr {string} aria-label - Nome acessível da região do mapa (padrão: "Mapa").
+ * @fires ui-mapa-pronto - O mapa foi criado (`detail.map`); é emitido de novo se o elemento for reconectado.
+ */
 export declare class UIMapa extends SafeHTMLElement {
     static get observedAttributes(): string[];
     private mapContainer;
@@ -7,10 +17,13 @@ export declare class UIMapa extends SafeHTMLElement {
     private _initTimer;
     private _resizeObserver?;
     private _resizeTimer?;
+    private _invalidarTimer?;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldVal: string, newVal: string): void;
+    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
+    /** Nome acessível da região: o `aria-label` do host ou "Mapa". */
+    private sincronizarRotulo;
     private initMap;
     getMap(): L.Map | null;
 }

package/dist/components/ui-modal/modal-acessibilidade.d.ts

@@ -1,12 +1,12 @@
 /**
- * Utilitários de Acessibilidade WAI-ARIA e Gerenciamento de 'inert' para UIModal / UIDialog.
+ * Isolamento do <ui-modal> para tecnologias assistivas: `inert` em tudo o que está "atrás" do modal.
+ * Responsabilidade única: aplicar e desfazer o `inert`, preservando o que a página já tinha inerte.
  */
 /**
- * Aplica o atributo 'inert' em todos os elementos da página que estejam "atrás" do modal,
+ * Aplica `inert` em todos os elementos da página que estejam "atrás" do modal,
  * isolando o modal para tecnologias assistivas e interação de teclado/mouse.
+ * Devolve o conjunto afetado (os que já eram inertes ficam de fora, para não serem liberados depois).
  */
 export declare function aplicarInertForaDoModal(modalElement: HTMLElement): Set<HTMLElement>;
-/**
- * Remove o estado 'inert' dos elementos afetados pelo modal quando este é fechado.
- */
+/** Remove o estado `inert` dos elementos afetados pelo modal quando este é fechado. */
 export declare function removerInertForaDoModal(elementosAfetados: Set<HTMLElement>): void;

package/dist/components/ui-modal/modal-foco.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Foco do <ui-modal>: localizar controles focáveis, foco inicial e armadilha de foco (Tab / Shift+Tab).
+ * Responsabilidade única: decisões sobre foco; não abre nem fecha o modal.
+ */
+export declare const SELETORES_FOCAVEIS = "a[href], button, input, textarea, select, details, [tabindex]:not([tabindex=\"-1\"]), ui-campo-texto, ui-input, ui-botao, ui-botao-primario, ui-checkbox, ui-switch, ui-lista-flutuante, ui-radio, ui-select, ui-segmented";
+/** Elemento realmente focado, atravessando Shadow DOMs (ex.: o <button> interno de um <ui-botao>). */
+export declare function elementoAtivoProfundo(): HTMLElement | null;
+/**
+ * `alvo` é `ativo` ou algum ancestral de `ativo`, subindo também pelos hosts de Shadow DOM.
+ * Necessário porque o foco costuma estar num botão interno de um componente (dentro do shadow do `alvo`).
+ */
+export declare function contemFoco(alvo: Node, ativo: Node | null): boolean;
+export declare function ehFocavel(el: HTMLElement): boolean;
+/** Focáveis do conteúdo projetado (corpo e rodapé), na ordem dos slots. */
+export declare function focaveisDoConteudo(shadow: ShadowRoot): HTMLElement[];
+/** Todos os focáveis do modal: os do próprio Shadow DOM (botão fechar, se visível) e depois os do conteúdo. */
+export declare function focaveisDoModal(shadow: ShadowRoot): HTMLElement[];
+/**
+ * Foco inicial: `[autofocus]`, senão o primeiro controle do conteúdo/rodapé.
+ * O botão "✕" não recebe o foco inicial, evitando fechar o modal com um Enter acidental;
+ * sem controles, o próprio diálogo é focado para que o leitor de tela anuncie o título.
+ */
+export declare function focarConteudoInicial(shadow: ShadowRoot, dialogo: HTMLElement): void;
+/**
+ * Mantém o foco dentro do modal: no último controle, Tab volta ao primeiro; no primeiro, Shift+Tab vai ao último.
+ * Se o foco está fora do modal, é trazido de volta. Chame no `keydown` de Tab.
+ */
+export declare function prenderTab(e: KeyboardEvent, host: HTMLElement, shadow: ShadowRoot): void;

package/dist/components/ui-modal/ui-modal.d.ts

@@ -5,8 +5,8 @@ export declare class UIModal extends SafeHTMLElement {
     private dialogElement;
     private tituloElement;
     private closeElement;
+    private ouvintes;
     private _elementoGatilho;
-    private _focables;
     private _tituloId;
     /** Estado já aplicado (pilha, inert, scroll, eventos); difere de `aberto` durante uma transição. */
     private _estaAberto;
@@ -26,19 +26,9 @@ export declare class UIModal extends SafeHTMLElement {
      */
     private aoAbrir;
     private aoFechar;
-    /**
-     * Foco inicial: `[autofocus]`, senão o primeiro controle do conteúdo/rodapé.
-     * O botão "✕" não recebe o foco inicial, evitando fechar o modal com um Enter acidental;
-     * sem controles, o próprio diálogo é focado para que o leitor de tela anuncie o título.
-     */
-    private focarConteudoInicial;
     private syncState;
     private handleBackdropClick;
     private handleCloseClick;
-    private static ehFocavel;
-    /** Focáveis do conteúdo projetado (corpo e rodapé), na ordem dos slots. */
-    private obterFocaveisDoConteudo;
-    private _atualizarFocables;
     private handleKeyDown;
 }
 export declare class UIDialog extends UIModal {

package/dist/components/ui-radio/radio-grupo-registry.d.ts

@@ -1,10 +1,20 @@
 import { UIRadio } from './ui-radio';
+/**
+ * Grupos de radios por nome, dentro do escopo do formulário (ou da raiz, sem formulário).
+ * O registro de cada radio é guardado ao registrar: assim o cancelamento usa o nome e o escopo de ANTES,
+ * mesmo que o radio já tenha saído do formulário (disconnectedCallback roda depois da remoção) ou mudado de nome.
+ */
 export declare class RadioGrupoRegistry {
     private static registry;
+    private static registros;
     static getScopeNode(radio: HTMLElement): Node;
+    /** Registra (ou re-registra, se o nome ou o escopo mudaram) o radio no grupo do seu nome atual. */
     static registrar(radio: UIRadio): void;
     static desregistrar(radio: UIRadio): void;
+    /** Radios do mesmo grupo que `radio`, usando o registro (não o nome atual, que pode ainda não ter sido registrado). */
     static obterRadiosDoGrupo(radio: UIRadio): UIRadio[];
     static desmarcarOutros(radio: UIRadio): void;
+    /** Reavalia o tabindex (roving) dos radios; use depois de entrar, sair ou mudar de grupo. */
+    static atualizarGrupo(radios: UIRadio[]): void;
     static tratarNavegacaoTeclado(e: KeyboardEvent, radioAtual: UIRadio): void;
 }

package/dist/components/ui-radio/ui-radio.d.ts

@@ -3,11 +3,12 @@ export declare class UIRadio extends FormAssociatedElement {
     static get observedAttributes(): string[];
     containerElement: HTMLDivElement;
     private labelElement;
+    private listeners;
     private _defaultChecked;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, _old: string | null, _value: string | null): void;
+    attributeChangedCallback(nome: string, _old: string | null, _value: string | null): void;
     get marcado(): boolean;
     set marcado(val: boolean);
     get name(): string;
@@ -18,10 +19,16 @@ export declare class UIRadio extends FormAssociatedElement {
     atualizarValidade(): void;
     focus(options?: FocusOptions): void;
     selecionar(): void;
+    /**
+     * Roving tabindex: só um radio do grupo entra na ordem de Tab (o marcado; sem marcado, o primeiro habilitado).
+     * Isolado de `syncState` para reavaliar os vizinhos sem mexer no valor/validade do formulário.
+     */
+    atualizarTabindex(): void;
     syncState(): void;
     formResetCallback(): void;
-    formStateRestoreCallback(state: any, _mode: 'restore' | 'autocomplete'): void;
+    formStateRestoreCallback(state: unknown, _mode: 'restore' | 'autocomplete'): void;
     private handleClick;
+    private handleHostClick;
     private handleKeyDown;
     private handleFocus;
     private handleBlur;

package/dist/components/ui-skeleton/ui-skeleton.d.ts

@@ -4,9 +4,18 @@ export type AnimacaoSkeleton = 'shimmer' | 'pulso' | 'nenhum';
 export declare class UISkeleton extends SafeHTMLElement {
     static get observedAttributes(): string[];
     private rootElement;
+    /** O que este componente escreveu em aria-hidden / role (para não sobrescrever o consumidor). */
+    private _ocultoAuto;
+    private _papelAuto;
+    private _sincronizando;
     constructor();
     connectedCallback(): void;
     attributeChangedCallback(_name: string, _old: string | null, _value: string | null): void;
+    /**
+     * Decorativo por padrão (`aria-hidden`). Com `aria-label` vira uma região de status anunciável
+     * ("Carregando tabela"). O que o consumidor definiu em aria-hidden/role é preservado.
+     */
+    private sincronizarAcessibilidade;
     get variante(): VarianteSkeleton;
     set variante(val: VarianteSkeleton);
     get animado(): AnimacaoSkeleton;

package/dist/components/ui-switch/ui-switch.d.ts

@@ -22,10 +22,12 @@ export declare class UISwitch extends FormAssociatedElement {
     set disabled(val: boolean);
     get type(): string;
     atualizarValidade(): void;
+    /** `focus()` no host leva o foco ao controle interno (necessário para o foco de validação do formulário). */
+    focus(options?: FocusOptions): void;
     alternar(): void;
     protected syncState(): void;
     formResetCallback(): void;
-    formStateRestoreCallback(state: any, _mode: 'restore' | 'autocomplete'): void;
+    formStateRestoreCallback(state: unknown, _mode: 'restore' | 'autocomplete'): void;
     private handleClick;
     private handleHostClick;
     private handleKeyDown;

package/dist/components/ui-tabela/tabela-estados.d.ts

@@ -0,0 +1,16 @@
+import { UIFetchErroDetail } from './tipos';
+export declare const TEXTO_ERRO_PADRAO = "N\u00E3o foi poss\u00EDvel carregar os dados.";
+export declare const TEXTO_SEM_RESULTADOS_PADRAO = "Nenhum resultado para o filtro";
+/** Mostra (ou oculta, com `null`) o aviso de erro com a ação "Tentar novamente". */
+export declare function renderizarErroTabela(el: HTMLElement | null, erro: UIFetchErroDetail | null, textoErro: string | null, temUrlParaRepetir: boolean): void;
+/** Anuncia ao leitor de tela o resultado do filtro (a região é limpa sem filtro ativo). */
+export declare function anunciarResultadoFiltro(regiao: HTMLElement | null, quantidade: number, temFiltro: boolean, textoSemResultados: string): void;
+export interface ElementosAria {
+    tabela: HTMLElement | null;
+    container: HTMLElement | null;
+}
+/**
+ * Nome acessível vem do host (`aria-label`): vai à tabela e, como região rolável nomeada, ao contêiner
+ * (leitores de tela anunciam o contêiner e o teclado alcança a rolagem). `aria-busy` acompanha o carregamento.
+ */
+export declare function sincronizarAriaTabela({ tabela, container }: ElementosAria, rotulo: string | null, carregando: boolean): void;

package/dist/components/ui-tabela/tabela-rolagem.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Rolagem e foco de linhas da <ui-tabela>, inclusive com a janela virtual.
+ * Responsabilidade única: posicionar uma linha na área visível (abaixo do cabeçalho fixo) rolando só o container,
+ * nunca a página, e focar a linha renderizando a janela virtual quando preciso.
+ */
+/** Acesso ao que a rolagem precisa da tabela; tudo é lido na hora (os elementos são recriados). */
+export interface PortasRolagem {
+    container: () => HTMLElement | null;
+    tbody: () => HTMLElement | null;
+    cabecalho: () => HTMLElement | null;
+    alturaLinha: () => number;
+    /** Renderiza a janela virtual (síncrono). */
+    renderizarCorpo: () => void;
+    /** A linha ativa (tabindex 0) mudou para `indice`. */
+    aoLinhaAtiva: (indice: number) => void;
+}
+/** Tempo máximo esperando o `scrollend` da rolagem suave antes de forçar a chegada. */
+export declare const TEMPO_LIMITE_ROLAGEM_SUAVE_MS = 800;
+/**
+ * Quanto o container precisa rolar para a linha ficar inteira na área útil: abaixo do cabeçalho
+ * fixo e acima da barra de rolagem horizontal. 0 = já visível. Linha maior que a área alinha pelo topo.
+ */
+export declare function deslocamentoAteLinha(container: HTMLElement, tr: HTMLElement, alturaCabecalho: number): number;
+/** Rola só o container da tabela (nunca a página, ao contrário de `scrollIntoView`). */
+export declare function rolarContainer(container: HTMLElement, topo: number, comportamento: 'smooth' | 'auto'): void;
+export declare class RolagemLinhas {
+    private p;
+    private cancelarCorrecao;
+    constructor(p: PortasRolagem);
+    private alturaCabecalho;
+    /** Linhas inteiras que cabem na área visível (mínimo 1). */
+    linhasPorPagina(): number;
+    /** Foca a linha, renderizando a janela virtual se necessário, e a mantém visível abaixo do cabeçalho fixo. */
+    focar(indice: number): void;
+    /**
+     * Posiciona a linha exibida `indice` na área visível.
+     * Fora da janela virtual, rola até a posição estimada, renderiza a janela e corrige pela posição
+     * real da linha. No modo suave a correção ocorre ao fim da animação (`scrollend`, com timeout de
+     * segurança para navegadores sem o evento ou quando não há rolagem a fazer).
+     */
+    posicionar(indice: number, comportamento: 'smooth' | 'auto'): boolean;
+    /** Cancela a correção pendente de uma rolagem suave (nova rolagem, desconexão). */
+    cancelar(): void;
+}

package/dist/components/ui-tabela/tabela-teclado.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Teclado nas linhas da <ui-tabela>.
+ * Responsabilidade única: traduzir uma tecla em um destino de foco ou em "ativar a linha". Função pura; quem
+ * chama move o foco, renderiza a janela virtual e dispara o clique.
+ */
+export type AcaoTeclaLinha = {
+    tipo: 'mover';
+    indice: number;
+} | {
+    tipo: 'ativar';
+};
+/**
+ * Setas, Home/End e PageUp/PageDown movem o foco (limitados a `0..ultimo`); Enter e Espaço ativam a linha.
+ * Sem linhas (`ultimo < 0`) ou com índice inválido nenhuma tecla de movimento produz ação.
+ */
+export declare function acaoDaTeclaLinha(key: string, atual: number, ultimo: number, linhasPorPagina: number): AcaoTeclaLinha | null;

package/dist/components/ui-tabela/ui-tabela.d.ts

@@ -31,8 +31,7 @@ export declare class UITabela extends SafeHTMLElement {
     private _indiceAtivo;
     /** Altura real das linhas medida no DOM; null = usa a estimativa da densidade. */
     private _alturaLinhaMedida;
-    /** Cancela a correção pendente de uma rolagem suave anterior. */
-    private _cancelarCorrecaoRolagem;
+    private rolagem;
     private remotaController;
     private selecaoController;
     private dadosController;
@@ -118,23 +117,6 @@ export declare class UITabela extends SafeHTMLElement {
      * Enter/Espaço selecionam a linha (mesmo caminho do clique, emite `ui-linha-clique`).
      */
     private handleTecladoCorpo;
-    private linhasPorPagina;
-    /** Foca a linha, renderizando a janela virtual se necessário, e a mantém visível abaixo do cabeçalho fixo. */
-    private focarLinha;
-    /**
-     * Quanto o container precisa rolar para a linha ficar inteira na área útil: abaixo do cabeçalho
-     * fixo e acima da barra de rolagem horizontal. 0 = já visível. Linha maior que a área alinha pelo topo.
-     */
-    private deslocamentoAteLinha;
-    /** Rola só o container da tabela (nunca a página, ao contrário de `scrollIntoView`). */
-    private rolarContainer;
-    /**
-     * Posiciona a linha exibida `indice` na área visível.
-     * Fora da janela virtual, rola até a posição estimada, renderiza a janela e corrige pela posição
-     * real da linha. No modo suave a correção ocorre ao fim da animação (`scrollend`, com timeout de
-     * segurança para navegadores sem o evento ou quando não há rolagem a fazer).
-     */
-    private posicionarLinha;
     private obterContextoRenderizador;
     private renderHeader;
     renderBody(): void;

package/dist/components/ui-tooltip/tooltip-popover.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Adaptador da Popover API para o balão do <ui-tooltip>.
+ * Responsabilidade única: abrir/fechar o balão na camada superior (top layer) quando o navegador suporta
+ * `popover`, sem casts soltos e sem engolir erros inesperados.
+ */
+export declare function mostrarPopover(el: HTMLElement): void;
+export declare function ocultarPopover(el: HTMLElement): void;

package/dist/components/ui-tooltip/tooltip-posicionamento.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Posicionamento do balão do <ui-tooltip>.
+ * Responsabilidade única: normalizar o lado pedido e calcular `top`/`left` (em px, relativos à janela) do balão,
+ * mantendo-o dentro da tela. Funções puras, sem acesso ao DOM.
+ */
+export type PosicaoTooltip = 'topo' | 'baixo' | 'esquerda' | 'direita';
+export interface Retangulo {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+export interface Viewport {
+    largura: number;
+    altura: number;
+}
+/** Distância entre o gatilho e o balão (seta + folga). */
+export declare const DESLOCAMENTO_PX = 8;
+/** Margem mínima até a borda da janela. */
+export declare const MARGEM_TELA_PX = 8;
+/** Aceita português e inglês, ignora caixa e espaços; qualquer outra coisa vira `topo`. */
+export declare function normalizarPosicao(bruto: string | null | undefined): PosicaoTooltip;
+/** Posição do balão em torno do gatilho, limitada à janela (balão maior que a janela fica na margem). */
+export declare function calcularPosicaoBalao(gatilho: Retangulo, balao: Pick<Retangulo, 'width' | 'height'>, posicao: PosicaoTooltip, viewport: Viewport): {
+    top: number;
+    left: number;
+};

package/dist/components/ui-tooltip/ui-tooltip.d.ts

@@ -1,10 +1,28 @@
 import { SafeHTMLElement } from '../../core/ssr-safe';
+/**
+ * Dica contextual (e popover) ao redor de um gatilho.
+ *
+ * @attr {string} texto - Texto do balão (alias `text`); também vira `aria-description` do gatilho.
+ * @attr {'topo'|'baixo'|'esquerda'|'direita'} posicao - Lado do balão (alias `position`, aceita top/bottom/left/right).
+ * @attr {'hover'|'clique'} gatilho - Como abre (alias `trigger`); em telas de toque o toque sempre alterna.
+ * @attr {boolean} aberto - Balão visível (alias `open`).
+ * @attr {boolean} disabled - Desativa o tooltip; fecha se estiver aberto.
+ * @slot - Elemento gatilho.
+ * @slot conteudo - Conteúdo rico do balão.
+ * @csspart balao - O balão.
+ * @csspart texto - O texto do balão.
+ * @csspart seta - A seta do balão.
+ */
 export declare class UITooltip extends SafeHTMLElement {
     static get observedAttributes(): string[];
     private containerElement;
     private bubbleElement;
-    private _posicionamentoAtivo;
+    /** Ouvintes do host: valem enquanto o elemento está conectado. */
+    private ouvintesHost;
+    /** Ouvintes globais (documento/janela): valem só enquanto o balão está aberto. */
+    private ouvintesAberto;
     private _timerOcultar;
+    private _quadro;
     /** Gatilho que recebeu `aria-description` deste tooltip (para remover depois). */
     private _gatilhoDescrito;
     constructor();
@@ -17,8 +35,12 @@ export declare class UITooltip extends SafeHTMLElement {
     set disabled(val: boolean);
     mostrar(): void;
     ocultar(): void;
+    private lerGatilho;
     private posicionarBubble;
+    private cancelarQuadro;
     private syncState;
+    private abrirBalao;
+    private fecharBalao;
     private handleMouseEnter;
     private handleMouseLeave;
     private cancelarOcultar;
@@ -33,6 +55,7 @@ export declare class UITooltip extends SafeHTMLElement {
      */
     private sincronizarDescricao;
     private removerDescricao;
+    /** O clique do gatilho continua chegando aos ancestrais: o "clicar fora" já ignora cliques dentro do host. */
     private handleClick;
     private handleClickOutside;
 }

package/dist/core/opcoes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Escolha segura de opções vindas de atributos HTML.
+ * Responsabilidade única: transformar texto de atributo (hostil por definição) num valor de um conjunto
+ * conhecido, para que nunca vire nome de classe CSS arbitrário nem estado inesperado.
+ */
+/** Devolve `valor` (sem espaços, em minúsculas) se estiver em `permitidas`; senão `padrao`. */
+export declare function escolherOpcao<T extends string>(valor: string | null | undefined, permitidas: readonly T[], padrao: T): T;
+/** Como `escolherOpcao`, mas devolve `null` quando o valor não é reconhecido (opção opcional). */
+export declare function escolherOpcaoOpcional<T extends string>(valor: string | null | undefined, permitidas: readonly T[]): T | null;

package/dist/core/rotulo-controle.d.ts

@@ -0,0 +1,13 @@
+export interface OpcoesRotuloControle {
+    host: HTMLElement;
+    internals?: {
+        labels?: NodeList;
+    } | null;
+    /** Elemento interno com o papel (switch/checkbox/radio) que recebe o nome acessível. */
+    controle: HTMLElement;
+    /** Elemento interno que exibe o texto do rótulo; precisa ter `id`. */
+    rotulo: HTMLElement;
+    /** Valor do atributo `label` (texto puro, nunca HTML). */
+    texto: string | null;
+}
+export declare function sincronizarRotuloControle({ host, internals, controle, rotulo, texto }: OpcoesRotuloControle): void;

package/dist/core/tipos-toast.d.ts

@@ -0,0 +1,16 @@
+/** Contratos do toast, no core (L1) para que o `UIBus` não dependa do componente (L3). */
+export interface UIToastAcao {
+    rotulo: string;
+    onClick: (e: MouseEvent) => void;
+    tipo?: 'primario' | 'secundario' | 'destrutivo';
+}
+export interface UIToastOpcoes {
+    tipo?: 'sucesso' | 'erro' | 'alerta' | 'info';
+    titulo?: string;
+    mensagem: string;
+    duracao?: number;
+    posicao?: 'bottom-right' | 'top-right' | 'bottom-left' | 'top-left' | 'bottom-center' | 'top-center';
+    acao?: UIToastAcao;
+    fechavel?: boolean;
+    pausarNoHover?: boolean;
+}