@thibezer/ui-components-kit 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.6.0 — 2026-10-17
+
+### `<ui-ribbon>` e `<ui-paleta-ferramentas>`: contrato com o consumidor
+
+- **Valor inicial pendente**: `aba-ativa` / `valor` definidos antes de `abas` / `ferramentas` são aplicados quando os dados chegam; `aba-ativa` reflete a aba realmente ativa.
+- **`valor = ''` / `limpar()`** removem a seleção da paleta (`ui-change` com `item: null`). Novas propriedades `orientacao`, `colunas`, `tamanho` (paleta) e `compacto` (ribbon); `valor` reflete no atributo usado (`valor` ou `value`).
+- **Eventos**: `ui-ferramenta` agora é cancelável (`preventDefault()` reverte toggle/seleção); `definirAbaVisivel` emite `ui-aba-change` quando a aba ativa muda; novo `ui-recolhido-change`; tipos dos eventos no `HTMLElementEventMap` (`FerramentaDetail`, `AbaChangeDetail`, `PaletaChangeDetail`, `RecolhidoChangeDetail`).
+- **Foco e roving tabindex**: re-renderizações preservam o foco; o tabindex acompanha o botão focado; `atualizarItem` não recria o DOM para mudanças de estado (paleta) nem para itens de outra aba (ribbon).
+- **Menu/flyout**: `menuitemcheckbox`/`menuitemradio` com `aria-checked`, `aria-controls`, foco devolvido ao botão, fecha ao rolar, `ArrowDown` com menu aberto foca o primeiro item.
+- **ARIA**: abas/painel ligados (`aria-controls`/`aria-labelledby`), `aria-label` e `rotulo-abas` configuráveis, `FerramentaItem.rotuloAcessivel`, `aria-keyshortcuts`; o nome acessível não cai mais no `id` quando há `rotulo` ou ícone nomeado.
+- **Paleta**: grupo pula filho desabilitado/separador; clique longo cancelado ao arrastar; `suprimirClique` não prende mais o clique seguinte; atalhos ignoram `role=textbox` e `aria-modal`.
+- `console.warn` para ids duplicados, `ativar()`/`atualizarItem()`/`selecionarAba()` com id inválido.
+
 ## 2.5.0
 
 ### `<ui-tabela>`: robustez, modo remoto e ordenação

package/README.md

@@ -725,8 +725,8 @@ window.addEventListener('message', (event) => {
 | `<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` (demais eventos: ver seção 4) |
 | `<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-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). `aba-ativa` pode ser definido antes de `abas` (fica pendente); `aria-label` e `rotulo-abas` rotulam a toolbar e o tablist; `ui-ferramenta` é cancelável (`preventDefault()` reverte o toggle); `atalho` é só texto no ribbon. Use `id` únicos e `rotulo`/`rotuloAcessivel` em botões só de ícone. | `abas`, `aba-ativa`, `recolhido`, `compacto`, `aria-label`, `rotulo-abas` | `ui-ferramenta`, `ui-aba-change`, `ui-recolhido-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. `valor` pode vir antes de `ferramentas` (pendente) e `valor = ''` / `limpar()` remove a seleção; `ui-ferramenta` dispara sempre e é cancelável (`preventDefault()` reverte), `ui-change`/`ui-selecionar` só quando a seleção muda (ouça um deles, não ambos). Atalhos: use `atalhos` em uma paleta por página. | `ferramentas`, `valor`, `orientacao`, `colunas`, `tamanho`, `atalhos`, `aria-label` | `ui-change`, `ui-selecionar`, `ui-ferramenta` |
 | `<ui-controle-cores>` | Par de cores de desenho (estilo Illustrator): preenchimento na frente, traço atrás, botões de inverter, "sem cor" e restaurar padrão, estado misto (`?`) e modo só traço. Clique no alvo ativo abre o `<ui-seletor-cor>`. Não registra atalhos: quem usa chama `alternarAlvo()`, `inverter()`, `semCor()`, `restaurarPadrao()` e pode exibir as teclas via `atalhos`. Entrada: `@thibezer/ui-components-kit/cores`. | `preenchimento`, `traco`, `opacidade`, `alvo`, `padrao-preenchimento`, `padrao-traco`, `titulo-seletor`, `so-traco`, `desabilitado`, `coresProjeto`, `definirCores()`, `definirMisto()` | `ui-cores-change` (`confirmado` false = pré-visualização), `ui-alvo-change` |
 | `<ui-seletor-cor>` | Painel de cor flutuante: abas Preenchimento/Traço (ou cor única), prévia antes × depois, hexadecimal, seletor do sistema, opacidade, cores do projeto, paleta e "sem cor". Abra com `abrirSeletorCor({ ancora, ... })`: um por vez, Esc/clique fora confirmam, Cancelar restaura, `X` alterna o alvo. | `abrirSeletorCor()`, `fecharSeletorCor()`, `configurar()`, `modo` (`duplo`, `simples`), `alvo`, `preenchimento`, `traco`, `cor`, `opacidade`, `mostrarOpacidade`, `misto`, `coresProjeto`, `paleta` | `ui-cor-input`, `ui-cor-confirmar`, `ui-cor-cancelar`, `ui-alvo-change` |
 | `<ui-mapa>` | Mapa geográfico interativo com camadas OpenStreetMap. | `lat`, `lng`, `zoom`, `camadas` | - |

package/dist/components/ui-barra-ferramentas/ferramentas-comum.d.ts

@@ -1,22 +1,34 @@
 import { FerramentaItem } from './tipos';
 export type VarianteBotaoFerramenta = 'grande' | 'pequeno' | 'paleta';
 export declare function criarIcone(icone: string | undefined, tamanho: number): HTMLElement | null;
+export declare function nomeAcessivel(item: FerramentaItem): string;
 export declare function textoTooltip(item: FerramentaItem): string;
+/** Avisa (console.warn) sobre ids repetidos. */
+export declare function avisarIdsDuplicados(ids: string[], contexto: string): void;
+export declare function coletarIds(itens: FerramentaItem[], saida?: string[]): string[];
 export declare function aplicarEstadoBotao(btn: HTMLButtonElement, item: FerramentaItem): void;
 export declare function criarBotaoFerramenta(item: FerramentaItem, variante: VarianteBotaoFerramenta, tamanhoIcone: number): HTMLButtonElement;
 export declare function acharItem(itens: FerramentaItem[], id: string): FerramentaItem | undefined;
 export declare function definirRoving(botoes: HTMLButtonElement[]): void;
+/** Garante um único botão com tabindex 0, preservando o atual se ainda estiver habilitado. */
+export declare function atualizarRoving(botoes: HTMLButtonElement[]): void;
+/** O roving tabindex acompanha o botão que recebeu foco (clique, Tab ou programático). */
+export declare function seguirFoco(botoes: HTMLButtonElement[], alvo: EventTarget | null): void;
 /** Move o foco entre botões com as setas informadas. Retorna true se tratou a tecla. */
 export declare function navegarRoving(e: KeyboardEvent, botoes: HTMLButtonElement[], teclasAnterior: string[], teclasProximo: string[]): boolean;
 export interface OpcoesMenu {
     lado?: 'baixo' | 'direita';
     /** Foca o primeiro item ao abrir (abertura por teclado). */
     focar?: boolean;
+    /** Papel dos itens sem `tipo`: ribbon = botao (menuitem), paleta = ferramenta (menuitemradio). */
+    tipoPadrao?: 'botao' | 'ferramenta';
     onFechar?: () => void;
 }
 export interface MenuHandle {
     elemento: HTMLElement;
     ancora: HTMLElement;
     fechar(): void;
+    /** Move o foco para o primeiro item habilitado. */
+    focarPrimeiro(): void;
 }
 export declare function abrirMenu(raiz: ShadowRoot, ancora: HTMLElement, itens: FerramentaItem[], onEscolher: (item: FerramentaItem) => void, opcoes?: OpcoesMenu): MenuHandle;

package/dist/components/ui-barra-ferramentas/tipos.d.ts

@@ -21,6 +21,11 @@ export interface FerramentaItem {
     tipo?: TipoFerramenta;
     ativo?: boolean;
     disabled?: boolean;
+    /**
+     * Nome acessível (leitor de tela) quando não há `rotulo` visível (ex.: botões só de ícone).
+     * Sem ele e sem `rotulo`, usa-se o nome do ícone e, por último, o `id`.
+     */
+    rotuloAcessivel?: string;
     /** Apenas ribbon: botão grande (ícone sobre o rótulo) ou pequeno (em colunas de 3). Padrão: 'pequeno'. */
     tamanho?: 'grande' | 'pequeno';
     /** Apenas ribbon: oculta o rótulo em botões pequenos. */
@@ -53,3 +58,28 @@ export interface FerramentaDetail {
     /** Apenas ribbon: id da aba ativa no momento do disparo. */
     aba?: string;
 }
+/** `detail` de `ui-aba-change`. */
+export interface AbaChangeDetail {
+    id: string;
+    aba: RibbonAba;
+}
+/** `detail` de `ui-change` / `ui-selecionar` da paleta. `item` é `null` quando a seleção é limpa (`valor = ''`). */
+export interface PaletaChangeDetail {
+    valor: string;
+    item: FerramentaItem | null;
+    anterior: string;
+}
+/** `detail` de `ui-recolhido-change` do ribbon. */
+export interface RecolhidoChangeDetail {
+    recolhido: boolean;
+}
+declare global {
+    interface HTMLElementEventMap {
+        /** Cancelável: `preventDefault()` reverte o toggle / a seleção feita pelo clique. */
+        'ui-ferramenta': CustomEvent<FerramentaDetail>;
+        'ui-aba-change': CustomEvent<AbaChangeDetail>;
+        'ui-recolhido-change': CustomEvent<RecolhidoChangeDetail>;
+        'ui-change': CustomEvent<PaletaChangeDetail>;
+        'ui-selecionar': CustomEvent<PaletaChangeDetail>;
+    }
+}

package/dist/components/ui-barra-ferramentas/ui-paleta-ferramentas.d.ts

@@ -9,19 +9,26 @@ import { SafeHTMLElement } from '../../core/ssr-safe';
  * - Com o atributo `atalhos`, a tecla `atalho` do item ativa a ferramenta; teclas repetidas
  *   entre itens percorrem o grupo.
  *
- * Atributos: valor, orientacao (vertical|horizontal), colunas (1|2), tamanho (sm|md|lg), atalhos
- * Propriedades: ferramentas, valor
- * Métodos: ativar(id), atualizarItem(id, parcial)
- * Eventos: ui-change / ui-selecionar { valor, item, anterior }, ui-ferramenta { id, item, pai?, ativo?, origem }
+ * Atributos: valor (vazio limpa a seleção), orientacao (vertical|horizontal), colunas (1|2),
+ *            tamanho (sm|md|lg), atalhos, aria-label (rótulo da toolbar)
+ * Propriedades: ferramentas, valor, orientacao, colunas, tamanho
+ * Métodos: ativar(id), limpar(), atualizarItem(id, parcial)
+ * Eventos: ui-change / ui-selecionar { valor, item, anterior },
+ *          ui-ferramenta { id, item, pai?, ativo?, origem } (cancelável: preventDefault reverte a ação)
+ *
+ * `valor` pode ser definido antes de `ferramentas`: fica pendente até a ferramenta existir.
  */
 export declare class UIPaletaFerramentas extends SafeHTMLElement {
     static get observedAttributes(): string[];
     private rootElement;
     private _ferramentas;
     private _ativo;
+    private _pendente;
     private visiveis;
     private menu;
     private timerPressao;
+    private timerSupressao;
+    private inicioPressao;
     private suprimirClique;
     private listeners;
     constructor();
@@ -34,17 +41,40 @@ export declare class UIPaletaFerramentas extends SafeHTMLElement {
     set valor(id: string);
     get value(): string;
     set value(id: string);
-    /** Ativa uma ferramenta (exclusiva). Se estiver dentro de um grupo, ela passa a ser a exibida. */
+    get orientacao(): 'vertical' | 'horizontal';
+    set orientacao(val: 'vertical' | 'horizontal');
+    get colunas(): 1 | 2;
+    set colunas(val: 1 | 2);
+    get tamanho(): 'sm' | 'md' | 'lg';
+    set tamanho(val: 'sm' | 'md' | 'lg');
+    /**
+     * Ativa uma ferramenta (exclusiva). Se estiver dentro de um grupo, ela passa a ser a exibida.
+     * `id` vazio limpa a seleção. Se as `ferramentas` ainda não foram definidas, o valor fica pendente.
+     */
     ativar(id: string, emitir?: boolean): void;
+    /** Remove a seleção atual (nenhuma ferramenta ativa). Equivale a `valor = ''`. */
+    limpar(emitir?: boolean): void;
     atualizarItem(id: string, parcial: Partial<FerramentaItem>): void;
+    private refletirValor;
+    private aplicarPendente;
     private definirAtivoInterno;
+    private emitirMudanca;
+    /** Filho exibido de um grupo: o último usado, pulando separadores e itens desabilitados. */
     private itemExibido;
+    private itemParaBotao;
     private todasFerramentas;
     private renderizar;
     private botoes;
+    /** Reflete no botão o estado atual do item (sem recriar o DOM). */
+    private atualizarBotaoDe;
     private acionar;
     private handleClick;
+    private handleFocusIn;
     private handlePointerDown;
+    /** Arrastar/rolar com o dedo cancela o clique longo. */
+    private handlePointerMove;
+    /** Fim do gesto: cancela o timer e, se o flyout abriu, descarta a supressão logo após o `click` residual. */
+    private handlePointerFim;
     private cancelarPressao;
     private handleContextMenu;
     private handleKeyDown;

package/dist/components/ui-barra-ferramentas/ui-ribbon.d.ts

@@ -1,18 +1,15 @@
 import { FerramentaItem, RibbonAba } from './tipos';
 import { SafeHTMLElement } from '../../core/ssr-safe';
-/**
- * <ui-ribbon> — barra de ferramentas em abas com grupos (estilo AutoCAD / Word / Excel).
- *
- * Atributos: aba-ativa, recolhido, compacto
- * Propriedades: abas, abaAtiva, recolhido
- * Métodos: atualizarItem(id, parcial), definirAbaVisivel(id, visivel), selecionarAba(id)
- * Eventos: ui-ferramenta { id, item, pai?, ativo?, origem, aba }, ui-aba-change { id, aba }
- */
 export declare class UIRibbon extends SafeHTMLElement {
     static get observedAttributes(): string[];
     private rootElement;
     private abasElement;
     private gruposElement;
+    private painelElement;
+    private fixarElement;
+    private readonly uid;
+    private _abaPendente;
+    private _pronto;
     private _abas;
     private _abaAtiva;
     private menu;
@@ -21,24 +18,34 @@ export declare class UIRibbon extends SafeHTMLElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    private aplicarRotulos;
     get abas(): RibbonAba[];
     set abas(val: RibbonAba[]);
     get abaAtiva(): string;
     set abaAtiva(id: string);
     get recolhido(): boolean;
     set recolhido(val: boolean);
+    get compacto(): boolean;
+    set compacto(val: boolean);
     selecionarAba(id: string, emitir?: boolean): void;
     definirAbaVisivel(id: string, visivel: boolean): void;
     /** Atualiza um item (estado ou aparência) sem precisar recriar as abas. */
     atualizarItem(id: string, parcial: Partial<FerramentaItem>): void;
+    private efetivo;
+    private capturarFoco;
+    private comFoco;
+    private handleFocusInGrupos;
     private abasVisiveis;
     private renderizar;
     private renderizarAbas;
+    private idAba;
     private renderizarPainel;
     private criarGrupo;
     private criarBotao;
     private botoesPainel;
     private handleClickAbas;
+    private handleClickFixar;
+    private get rtl();
     private handleDblClickAbas;
     private handleKeyDownAbas;
     private handleClickGrupos;
@@ -48,5 +55,6 @@ export declare class UIRibbon extends SafeHTMLElement {
     private acionar;
     private alternarMenu;
     private fecharMenu;
+    /** Retorna false se o consumidor cancelou o evento (preventDefault). */
     private emitir;
 }