@govbr-ds/webcomponents 2.4.0 → 2.6.0

package/dist/types/components/table/table.d.ts

@@ -1,165 +1,295 @@
-import type { ColumnWidth, TableAlignment, TableDensity, TableDividerStyle, TableOverflow, TableTooltipMode, TableTooltipState } from './table-types';
+import { type EventEmitter } from '../../stencil-public-runtime';
+import type { DropdownOpenChangeDetail } from '../dropdown/dropdown.types';
+import type { TableHeaderHeight } from './table.header-height';
+import { type TableCellFocus } from './table.keyboard';
+import type { ColumnWidth, TableActionClickDetail, TableAlignment, TableData, TableDensity, TableDividerStyle, TableOverflow, TablePageChangeDetail, TablePageSizeChangeDetail, TableRowExpansionChangeDetail, TableSearchDetail, TableSelectionChangeDetail, TableSortChangeDetail, TableSortMode, TableSortRequestDetail, TableSortState, TableSortStrategy, TableTooltipMode, TableTooltipState } from './table.types';
 /**
- * O componente `br-table` é o elemento oficial do GovBR-DS para exibição e gerenciamento de dados tabulares estruturados em linhas e colunas, desenvolvido com suporte a CSS Grid, responsividade e alta flexibilidade de composição.
+ * ## Design System
  *
- * ### Para que serve
+ * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).
  *
- * - **Apresentação de conjuntos de dados relacionais:** Organiza registros com múltiplos atributos comparáveis (ex.: relatórios, tabelas de processos, listagens financeiras).
- * - **Recursos interativos avançados:** Suporta ordenação por coluna, seleção simples ou múltipla de linhas, densidades variadas (alta, média, baixa) e paginação integrada com `br-pagination`.
- * - **Acessibilidade WAI-ARIA:** Preserva a semântica de tabela acessível (`role="table"`, `role="columnheader"`, `role="row"`, `role="cell"`) mesmo em leiautes baseados em CSS Grid.
+ * Apresenta e permite interagir com dados tabulares; não deve ser usada para
+ * organizar layout ou conteúdo que não seja tabular. Recebe o cabeçalho e o corpo
+ * pelos slots `header` e `body`, compostos por `br-table-header` e
+ * `br-table-header-cell`, e por `br-table-body`, `br-table-row` e `br-table-cell`.
+ * Orquestra a grade, a acessibilidade, a ordenação, a seleção e a expansão das
+ * linhas. A barra de ações é gerenciada pela tabela; `br-table-footer` é
+ * renderizado quando a paginação está habilitada. As propriedades de célula
+ * seguem, quando aplicável, a precedência: célula, linha, coluna, tabela e valor
+ * padrão. Cabeçalhos multinível usam várias linhas em `br-table-header` com
+ * `colSpan`/`rowSpan`. Linhas contíguas com `rowGroup` formam unidades de ordenação,
+ * paginação e virtualização; a seleção permanece individual. Células com `rowSpan`
+ * não atravessam os limites do grupo. Prefira tabelas simples quando possível.
  *
- * ### Quando utilizar
- *
- * - **Utilize quando:**
- *   - As informações compartilharem campos e atributos fixos que justifiquem a comparação lado a lado em colunas.
- *   - A pessoa usuária precisar ordenar, filtrar ou selecionar múltiplos registros da lista.
- * - **Evite e prefira outro componente quando:**
- *   - Os itens forem heterogêneos com estruturas visuais distintas (prefira `br-card`).
- *   - Houver apenas um texto linear simples por item (prefira `br-list`).
- *
- * ### Composição e Subcomponentes
- *
- * O ecossistema da Tabela segue a hierarquia semântica modular:
- *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-table` | **Orquestrador principal.** Gerencia o grid de colunas, ordenação, seleção de linhas e densidade. | Contêiner raiz da tabela. |
- * | `br-table-header` | **Seção de cabeçalho.** Agrupa as linhas de títulos das colunas. | Declarado no slot `header` da tabela. |
- * | `br-table-body` | **Corpo de dados.** Agrupa as linhas de registros de conteúdo. | Declarado no slot `body` (ou padrão) da tabela. |
- * | `br-table-row` | **Linha.** Representa uma linha de cabeçalho ou de registro de dados. | Declarado dentro de `br-table-header` ou `br-table-body`. |
- * | `br-table-header-cell` | **Célula de título.** Célula de cabeçalho com suporte a botão de ordenação. | Declarado dentro de `br-table-row` no cabeçalho. |
- * | `br-table-cell` | **Célula de dados.** Célula de conteúdo individual de uma coluna. | Declarado dentro de `br-table-row` no corpo de dados. |
- *
- * ### Como os subcomponentes se relacionam
- *
- * A arquitetura de `br-table` reflete a semântica nativa de tabelas HTML de forma modular:
- * `br-table` → `br-table-header` / `br-table-body` → `br-table-row` → `br-table-header-cell` / `br-table-cell`.
- * O componente pai orquestra o alinhamento das colunas via tokens de Grid, distribuindo automaticamente os estados de seleção e foco para as linhas filhas.
- *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).
- *
-
- * @category Dados, Conteúdo
- * @status stable
- * @Slot header: Área para inclusão do subcomponente br-table-header
- * @Slot body: Área para inclusão do subcomponente br-table-body
+ * @slot header - Componente `br-table-header` que define as colunas.
+ * @slot body - Componente `br-table-body` que contém as linhas de dados.
+ * @slot global-actions - Ações aplicadas ao conjunto completo de dados.
+ * @slot contextual-actions - Ações aplicadas às linhas selecionadas.
  * @slot loading - Indicador exibido enquanto as linhas são atualizadas.
- *
- * @part container - Wrapper principal da tabela.
- * @part content - Área de conteúdo que contém header e body.
- * @part loading - Área do indicador de carregamento.
+ * @part container - Contêiner visual principal.
+ * @part scroll-container - Área com rolagem que contém apenas os dados da tabela.
+ * @part content - Grid que contém cabeçalho e corpo.
+ * @part footer - Contêiner do rodapé, exibido abaixo do corpo da tabela.
+ * @part loading - Scrim local e área do painel de carregamento sobre a tabela inteira.
+ * @cssprop --br-table-loading-opacity - Opacidade do conteúdo durante o carregamento. Padrão: 0.5.
+ * @fires brTableActionClick - Quando uma ação pública é acionada.
+ * @fires brTableSelectionChange - Quando o conjunto selecionado muda.
+ * @fires brTableRowExpansionChange - Quando uma linha expande ou recolhe.
+ * @fires brTableSortRequest - Antes de aplicar uma solicitação de ordenação.
+ * @fires brTableSortChange - Quando os critérios de ordenação mudam.
+ * @fires brTablePageChange - Quando o consumidor solicita outra página pela paginação do rodapé.
+ * @fires brTablePageSizeChange - Quando o consumidor solicita outra quantidade de itens por página.
+ * @fires brTableSearch - Quando a busca é enviada ou fechada.
  */
 export declare class Table {
-    /**
-     * Referência ao elemento host do componente.
-     * Utilize esta propriedade para acessar e manipular o elemento do DOM associado ao componente.
-     *
-     */
     el: HTMLBrTableElement;
     /**
-     * Largura global aplicada a todas as colunas.
-     *
-     *  @remarks Valores aceitos:
-     * - fill
-     * - content
-     * - ${number}px
-     * - ${number}fr
-     *
-     * Observação:
-     * - `columnWidth` não define o comportamento de `overflow`, mas pode interferir na sua percepção ao alterar o espaço disponível da coluna.
-     * - `content` (`max-content`) tende a expandir a coluna e reduzir casos visíveis de truncagem.
-     * - `fill` (`1fr`) tende a evidenciar truncagem quando o espaço horizontal é insuficiente.
+     * Largura padrão utilizada pelas colunas sem configuração própria.
      *
      * @default fill
-     * @example
-     * ```html
-     * <br-table column-width="160px"></br-table>
-     * ```
      */
     columnWidth?: ColumnWidth;
     /**
-     * Define a densidade visual do componente.
+     * Densidade visual aplicada aos espaçamentos da tabela.
      *
-     * - `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).
-     * - `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.
-     * - `large`: Baixa densidade (componente maior, mais espaçamento e altura).
-     *
-     * Valores inválidos usam `medium`. Quando omitida, a densidade média é aplicada ao token.
+     * @remarks Quando omitida, a propriedade permanece `undefined` e a densidade
+     * visual média é aplicada aos tokens da tabela.
+     * @default undefined
      */
     density?: TableDensity;
     /**
-     * Define o estilo visual dos divisores.
-     *
-     * @remarks Valores aceitos:
-     * - solid
-     * - dashed
+     * Estilo aplicado aos divisores habilitados.
      *
      * @default solid
      */
     dividerStyle?: TableDividerStyle;
     /**
-     * Ativa divisores verticais entre colunas.
+     * Habilita divisores entre colunas quando `columnDivider` não é informado.
      *
+     * @deprecated Use `columnDivider` instead.
      * @default false
-     * @deprecated Use `columnDivider`.
      */
     hasColumnDivider?: boolean;
-    /** Ativa divisores verticais. Quando informada, tem precedência sobre `hasColumnDivider`. */
+    /**
+     * Habilita divisores entre colunas.
+     *
+     * @remarks Quando informado, tem precedência sobre `hasColumnDivider`,
+     * inclusive quando `false`. Na ausência de ambos, os divisores ficam desabilitados.
+     */
     columnDivider?: boolean;
     /**
-     * Ativa divisores horizontais entre linhas.
+     * Habilita divisores entre linhas quando `rowDivider` não é informado.
      *
+     * @deprecated Use `rowDivider` instead.
      * @default false
-     * @deprecated Use `rowDivider`.
      */
     hasRowDivider?: boolean;
-    /** Ativa divisores horizontais. Quando informada, tem precedência sobre `hasRowDivider`. */
+    /**
+     * Habilita divisores entre linhas.
+     *
+     * @remarks Quando informado, tem precedência sobre `hasRowDivider`,
+     * inclusive quando `false`. Na ausência de ambos, os divisores ficam desabilitados.
+     */
     rowDivider?: boolean;
     /**
-     * Define o alinhamento horizontal do conteúdo das células.
+     * Habilita o realce visual das linhas ao passar o ponteiro.
      *
-     * @remarks Valores aceitos:
-     * - start
-     * - center
-     * - end
+     * @default false
+     */
+    hasRowHover: boolean;
+    /**
+     * Indica que as linhas estão sendo atualizadas pelo consumidor.
+     *
+     * @remarks Mantém os dados anteriores, reduz sua opacidade e exibe o slot
+     * `loading` em um painel central com scrim sobre toda a tabela, incluindo
+     * barra de ações e paginação. O scrim fica limitado ao componente.
+     * Reflete o atributo `loading` e pode ser alterada diretamente ou pelos métodos
+     * `startLoading()` e `stopLoading()`. Não bloqueia o teclado nem gerencia
+     * requisições, erros ou substituição dos dados.
+     * @default false
+     */
+    loading: boolean;
+    /**
+     * Título apresentado na barra principal.
+     *
+     * @default null
+     */
+    heading?: string;
+    /**
+     * Força a apresentação da barra contextual.
+     *
+     * @default false
+     */
+    showContextualBar: boolean;
+    /**
+     * Limite usado para decidir quando agrupar ações globais em um menu.
+     * Quando o número de ações excede esse valor, as ações são agrupadas no
+     * dropdown (atualmente todas são movidas para o menu colapsado).
+     *
+     * @default 4
+     */
+    headingActionsLimit: number;
+    /**
+     * Limite usado para decidir quando agrupar ações contextuais em um menu.
+     * Quando o número de ações excede esse valor, as ações são agrupadas no
+     * dropdown (atualmente todas são movidas para o menu colapsado).
+     *
+     * @default 4
+     */
+    contextualActionsLimit: number;
+    /**
+     * Texto do tooltip do botão de ações agrupadas na barra de título.
+     * Quando vazio ou composto apenas por espaços, usa "Mais ações".
+     * Não altera o nome acessível do botão nem os rótulos do menu.
+     *
+     * @default 'Mais ações'
+     */
+    moreActionsHeadingLabel: string;
+    /**
+     * Texto do tooltip do botão de ações agrupadas da barra contextual.
+     * Quando vazio ou composto apenas por espaços, usa "Mais ações".
+     * Não altera o nome acessível do botão nem os rótulos do menu.
+     *
+     * @default 'Mais ações'
+     */
+    moreActionsContextualLabel: string;
+    /**
+     * Texto completo do tooltip dos botões de ações agrupadas nas células.
+     * Quando informado, prevalece sobre `moreActionsLabel` de cada célula.
+     * Quando omitido, a célula usa seu valor local ou "Mais ações".
+     * Valores vazios ou compostos apenas por espaços usam "Mais ações".
+     * Aceita texto simples por atributo ou propriedade.
+     * Reflete o valor no atributo `more-actions-label` para sincronizar as células.
+     *
+     * @default undefined
+     */
+    moreActionsLabel?: string;
+    /**
+     * Limite padrão de ações exibidas em cada célula.
+     *
+     * @default 4
+     */
+    cellActionsLimit: number;
+    /**
+     * Habilita a coluna de seleção de linhas.
+     *
+     * @default false
+     */
+    hasRowSelection: boolean;
+    /**
+     * Habilita a coluna de expansão de linhas.
+     *
+     * @default false
+     */
+    hasRowExpansion: boolean;
+    /**
+     * Disponibiliza a interface de busca, sem filtrar ou destacar o conteúdo.
+     * A aplicação recebe `brTableSearch` e atualiza os dados local ou remotamente.
+     *
+     * @default false
+     */
+    hasSearch: boolean;
+    /**
+     * Habilita a paginação da tabela, renderizando `br-table-footer` internamente.
+     *
+     * @remarks A paginação define o subconjunto lógico disponível para a lista
+     * virtual. `pageSize` conta linhas independentes ou grupos completos, e
+     * `visibleRows` controla quantas delas cabem simultaneamente na viewport.
+     * Quando os dados completos ainda não estão disponíveis localmente
+     * (paginação por API), informe `totalItems` e forneça o subconjunto
+     * correspondente após `brTablePageChange`.
+     * @default false
+     */
+    hasPagination: boolean;
+    /**
+     * Página atual exibida pela paginação (1-indexada).
+     *
+     * @remarks Atualizada internamente quando `TableDataStore` já cobre a
+     * página solicitada. Utilize como valor inicial ou para navegar
+     * programaticamente para outra página.
+     * @default 1
+     */
+    currentPage: number;
+    /**
+     * Quantidade de itens pertencentes a cada página (linhas independentes ou grupos completos).
+     *
+     * @remarks Quando omitida, utiliza `visibleRows` como fallback para manter
+     * compatibilidade com a API anterior. Defina um valor maior que
+     * `visibleRows` para que paginação e virtualização operem simultaneamente.
+     */
+    pageSize?: number;
+    /**
+     * Opções disponíveis de itens por página no seletor da paginação.
+     *
+     * @default [10, 20, 30]
+     */
+    pageSizeOptions: number[];
+    /**
+     * Quantidade total de itens do conjunto de dados.
+     *
+     * @remarks Necessário apenas quando `TableDataStore` não contém o conjunto
+     * completo (paginação por API). Quando omitido, é derivado automaticamente
+     * da quantidade de linhas independentes e grupos já presentes na tabela.
+     */
+    totalItems?: number;
+    /**
+     * Define se a tabela aceita uma única coluna ordenada ou múltiplas colunas.
+     * No modo `multi`, a prioridade é sempre a ordem visual da esquerda para a direita.
+     *
+     * @default single
+     */
+    sortMode: TableSortMode;
+    /**
+     * Define se a tabela ordena as linhas localmente ou deixa a aplicação aplicar
+     * a ordenação solicitada. Em `manual`, a tabela mantém os indicadores e emite
+     * `brTableSortChange`, mas não reordena as linhas; use `setData()` para fornecer
+     * os resultados customizados ou remotos. Valores não reconhecidos usam a
+     * estratégia local.
+     *
+     * @default local
+     */
+    sortStrategy: TableSortStrategy;
+    /**
+     * Quantidade de linhas de dados visíveis simultaneamente na viewport.
+     *
+     * @remarks Não limita o conjunto de dados nem realiza paginação. A altura da
+     * região de scroll é derivada desta quantidade e da densidade atual. Mesmo
+     * com `hasPagination` habilitado, esta propriedade continua definindo
+     * apenas a capacidade visual da viewport; `pageSize` define o tamanho lógico
+     * da página.
+     * @default 10
+     */
+    visibleRows: number;
+    /**
+     * Quantidade de itens lógicos usada somente para calcular a altura da viewport.
+     * Cada grupo contíguo conta como um item; a altura inclui todas as linhas
+     * físicas que compõem os grupos reservados. Não altera paginação, rolagem ou
+     * virtualização. Quando omitida, acompanha `visibleRows`.
+     * @default visibleRows
+     */
+    heightRows?: number;
+    /** Altura adicional estimada para conteúdo expandido ainda não medido. */
+    virtualExpandedContentHeight: number;
+    /**
+     * Alinhamento horizontal padrão da tabela.
      *
      * @default start
      */
     horizontalAlignment?: TableAlignment;
     /**
-     * Define o alinhamento vertical do conteúdo das células.
-     *
-     * @remarks Valores aceitos:
-     * - start
-     * - center
-     * - end
+     * Alinhamento vertical padrão da tabela.
      *
      * @default start
      */
     verticalAlignment?: TableAlignment;
     /**
-     * Define o comportamento de overflow para as células.
-     *
-     * @remarks Valores aceitos:
-     * - truncate
-     * - wrap
-     *
-     * Observação:
-     * - O overflow é independente de `columnWidth`.
-     * - Com `columnWidth="content"`, a coluna tende a crescer com o conteúdo (`max-content`), o que pode reduzir casos visíveis de truncagem.
-     * - Com `columnWidth="fill"`, a coluna ocupa o espaço disponível (`1fr`), então a truncagem tende a ficar mais evidente quando não há espaço suficiente.
+     * Estratégia padrão para conteúdos que excedem a célula.
      *
      * @default wrap
      */
     overflow?: TableOverflow;
     /**
-     * Define o estado semântico do tooltip nas células da tabela.
-     *
-     * @remarks Valores aceitos:
-     * - info
-     * - warning
-     * - danger
-     * - success
+     * Estado visual padrão dos tooltips.
      *
      * @default info
      */
@@ -167,226 +297,468 @@ export declare class Table {
     /**
      * Define o modo de resolução do tooltip nas células da tabela.
      *
-     * @remarks Valores aceitos:
-     * - inherit
-     * - enabled
-     * - disabled
-     *
      * @default disabled (valor efetivo)
      */
     tooltipMode?: TableTooltipMode;
-    private get effectiveDividerStyle();
-    private get effectiveHorizontalAlignment();
-    private get effectiveVerticalAlignment();
-    private get effectiveOverflow();
-    private get effectiveTooltipState();
-    private get effectiveTooltipMode();
+    private selectedRowsCount;
+    private measuredCollapsedRowHeight;
+    private measuredHeaderHeight;
+    private hasGlobalActionsContent;
+    private hasContextualActionsContent;
+    private hasScrollableContent;
+    /**
+     * Reemite ações globais, contextuais e de linha para o consumidor.
+     *
+     * @remarks O `detail` utiliza `TableActionClickDetail`.
+     */
+    brTableActionClick: EventEmitter<TableActionClickDetail>;
     /**
-     * Indica que as linhas estão sendo atualizadas pelo consumidor.
-     * O componente mantém o conteúdo anterior, aplica `aria-busy="true"` e
-     * exibe o slot `loading` sobre os dados; transporte, erro e substituição das
-     * linhas ficam sob responsabilidade da aplicação.
-     * A prop pode ser alterada diretamente ou pelos métodos `startLoading()` e
-     * `stopLoading()`.
-     * @default false
+     * Emitido quando o conjunto de linhas selecionadas muda.
+     *
+     * @remarks O `detail` utiliza `TableSelectionChangeDetail`.
      */
-    loading: boolean;
-    private headers;
-    private rows;
-    private cells;
-    private rowCells;
-    private columnIndexes;
-    private structureReady;
-    private structureRefreshFrame;
-    private readonly handleColumnWidthEvent;
-    private readonly handleAlignmentEvent;
-    private readonly handleOverflowEvent;
-    /**
-     * Reaplica a largura das colunas quando alterada.
+    brTableSelectionChange: EventEmitter<TableSelectionChangeDetail>;
+    /**
+     * Emitido quando uma linha é expandida ou recolhida.
+     *
+     * @remarks O `detail` utiliza `TableRowExpansionChangeDetail`.
+     */
+    brTableRowExpansionChange: EventEmitter<TableRowExpansionChangeDetail>;
+    /** Emitido sempre que o conjunto de critérios de ordenação muda. */
+    brTableSortChange: EventEmitter<TableSortChangeDetail>;
+    /** Emitido antes de aplicar uma solicitação de ordenação; `preventDefault()` cancela a mudança local. */
+    brTableSortRequest: EventEmitter<TableSortRequestDetail>;
+    /** Emitido quando o consumidor solicita outra página pela paginação do rodapé. */
+    brTablePageChange: EventEmitter<TablePageChangeDetail>;
+    /** Emitido quando o consumidor solicita outra quantidade de itens por página; atualize `visibleRows` ao tratar. */
+    brTablePageSizeChange: EventEmitter<TablePageSizeChangeDetail>;
+    /**
+     * Evento customizado originado em `br-table-bar` e propagado pela tabela,
+     * sem reemissão. Envia `{ term }` por Enter ou botão e `{ term: '' }` ao fechar.
+     * Digitação, inicialização e alterações programáticas não emitem o evento.
+     * Propaga, atravessa Shadow DOM e é cancelável.
+     */
+    brTableSearch: EventEmitter<TableSearchDetail>;
+    private readonly generatedHeaderPrefix;
+    private readonly dataStore;
+    private isRenderingData;
+    private selfMutationDepth;
+    private expansion;
+    private selection;
+    private virtualList;
+    private structureObserver?;
+    private viewportMeasureFrame;
+    private sorting;
+    private keyboard;
+    private openDropdowns;
+    private headerHeights;
+    protected handleHeaderHeight(event: CustomEvent<TableHeaderHeight>): void;
+    private updateHeaderHeight;
+    protected handleDropdownOpenChange(event: CustomEvent<DropdownOpenChangeDetail>): void;
+    private handleViewportScroll;
+    protected handleCellFocusRegistration(event: CustomEvent<TableCellFocus>): void;
+    protected handleGridFocusIn(event: FocusEvent): void;
+    protected handleGridFocusOut(event: FocusEvent): void;
+    protected handleGridKeyDown(event: KeyboardEvent): void;
+    private handleFooterPageChange;
+    private handleFooterPerPageChange;
+    private applyFooterPerPageChange;
+    /**
+     * Inicializa os controllers antes da primeira renderização completa.
+     */
+    componentWillLoad(): void;
+    /**
+     * Retoma a coordenação de densidade quando a tabela é reinserida.
+     */
+    connectedCallback(): void;
+    /**
+     * Monta a estrutura derivada e registra os listeners de coordenação.
+     */
+    componentDidLoad(): void;
+    private scrollShadows?;
+    private syncScrollShadows;
+    componentDidRender(): void;
+    /**
+     * Libera o observer quando a tabela é removida do documento.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Recalcula o grid quando a largura padrão muda.
      */
     protected handleTableColumnWidthChange(): void;
     /**
-     * Reaplica o token de densidade quando alterado.
+     * Reaplica os tokens e recalcula a virtualização quando a densidade muda.
      */
     protected handleDensityChange(): void;
     /**
-     * Atualiza os tokens de divisor quando qualquer propriedade relacionada é alterada.
+     * Recalcula a viewport e a janela virtual quando a quantidade visível muda.
+     */
+    protected handleVisibleRowsChange(): void;
+    /** Reinicia a janela virtual quando a paginação é alternada. */
+    protected handleHasPaginationChange(): void;
+    /** Reinicia a janela virtual no subconjunto correspondente à página atual. */
+    protected handleCurrentPageChange(): void;
+    /** Reinicia a página e a janela virtual quando o tamanho lógico da página muda. */
+    protected handlePageSizeChange(): void;
+    /** Normaliza a quantidade pública de linhas visíveis para o intervalo suportado. */
+    private resolveConfiguredVisibleRows;
+    /** Quantidade total de itens usada pela paginação, priorizando o valor explícito. */
+    private resolvePaginationTotalItems;
+    /** Resolve o tamanho lógico da página sem acoplá-lo à altura da viewport. */
+    private resolvePageSize;
+    /** Retorna a página normalizada para o total e o tamanho atuais. */
+    private resolveCurrentPage;
+    /**
+     * Retorna o dataset lógico consumido pela lista virtual. Com paginação local,
+     * corresponde apenas ao slice da página; com paginação remota, corresponde
+     * ao subconjunto atualmente fornecido pelo consumidor.
+     */
+    private getVirtualRows;
+    /**
+     * Converte os índices locais da janela virtual para índices do dataset
+     * completo quando a paginação é realizada localmente.
+     *
+     * Na paginação remota, o data store contém somente a página fornecida pelo
+     * consumidor, portanto não há offset físico a aplicar ao renderRange.
+     */
+    private resolveVirtualRangeOffset;
+    /** Atualiza a janela virtual; a paginação apenas altera seu dataset de entrada. */
+    private syncVisibleRange;
+    /**
+     * Resolve a altura-base estimada da linha a partir da densidade atual.
+     *
+     * @remarks A célula utiliza a densidade como padding vertical. A estimativa
+     * soma duas vezes esse padding a uma altura de conteúdo de uma linha (24px).
+     * Após a materialização, a lista virtual substitui a estimativa pela altura
+     * efetivamente medida.
+     */
+    private resolveVirtualRowHeight;
+    /**
+     * Define a altura da região rolável pelo número de itens lógicos solicitado.
+     * Grupos contam como um item, mas reservam a altura de todas as suas linhas.
+     */
+    private resolveScrollViewportHeight;
+    /**
+     * Reaplica os divisores após qualquer mudança relacionada.
      */
     protected handleDividerChange(): void;
     /**
-     * Atualiza os tokens de alinhamento quando alterados.
+     * Recalcula os alinhamentos herdados de todas as células.
      */
     protected handleAlignmentChange(): void;
     /**
-     * Atualiza os tokens de overflow quando a propriedade é alterada.
+     * Recalcula o overflow herdado de todas as células.
      */
     protected handleOverflowChange(): void;
-    protected handleTooltipPropsChange(): void;
-    private validateTooltipProps;
+    protected handleVirtualExpandedContentHeightChange(): void;
     /**
-     * Ciclo de vida do componente que é chamado após o componente ser carregado no DOM.
-     * Inicializa os tokens visuais após a montagem do componente.
+     * Sincroniza a estrutura quando a seleção é habilitada ou desabilitada.
      */
-    componentDidLoad(): void;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    /** Inicia o estado de carregamento da tabela. */
+    protected handleRowSelectionChange(): void;
+    /** Sincroniza a elegibilidade visual de hover das linhas. */
+    protected handleRowHoverChange(): void;
+    /**
+     * Sincroniza a estrutura quando a expansão é habilitada ou desabilitada.
+     */
+    protected handleRowExpansionChange(): void;
+    /** Normaliza o estado ativo quando o consumidor alterna entre multi e single-sort. */
+    protected handleSortModeChange(): void;
+    /** Reaplica o estado atual quando a estratégia de ordenação muda. */
+    protected handleSortStrategyChange(): void;
+    /** Consome solicitações emitidas pelo trigger de ordenação do cabeçalho. */
+    protected handleSortRequest(event: CustomEvent<void>): void;
+    /**
+     * Encaminha mudanças dos checkboxes ao controller de seleção.
+     */
+    protected handleSelectionCheckboxChange(event: CustomEvent<boolean>): void;
+    /**
+     * Consome ações internas de expansão e normaliza as demais ações.
+     */
+    protected handleActionClick(event: CustomEvent<TableActionClickDetail>): void;
+    /** Resolve o índice da linha associado à ação quando o contexto é `row`. */
+    private resolveActionRowIndex;
+    /** Inicia o estado visual de carregamento sem alterar os dados da tabela. */
     startLoading(): Promise<void>;
-    /** Interrompe o estado de carregamento da tabela. */
+    /** Interrompe o estado visual de carregamento sem alterar os dados da tabela. */
     stopLoading(): Promise<void>;
-    private generatedHeaderPrefix;
     /**
-     * Marca a última linha e a última coluna para permitir estilização condicional.
+     * Substitui os dados lógicos da tabela e reconstrói seus subcomponentes.
+     *
+     * @remarks Esta é a mesma estrutura interna utilizada após a ingestão dos slots.
+     * @param data Colunas, linhas e ações que formarão a tabela.
+     * @example
+     * ```js
+     * const table = document.querySelector('br-table');
+     * await table.setData({
+     *   columns: [],
+     *   headerRows: [
+     *     [{ content: 'Unidade', rowSpan: 2 }, { content: 'Equipe', colSpan: 2 }],
+     *     [{ content: 'Nome', sortable: true }, { content: 'Cargo', sortable: true }],
+     *   ],
+     *   rows: [
+     *     { rowGroup: 'brasilia', cells: [
+     *       { content: 'Brasília', rowSpan: 2, rowHeader: true },
+     *       { content: 'Ana' }, { content: 'Analista' },
+     *     ] },
+     *     { rowGroup: 'brasilia', cells: [{ content: 'Carlos' }, { content: 'Técnico' }] },
+     *   ],
+     * });
+     * ```
+     */
+    setData(data: TableData): Promise<void>;
+    /** Preserva apenas critérios que continuam válidos no novo dataset. */
+    private resolvePreservedSorting;
+    /**
+     * Captura a entrada declarativa inicial e a materializa a partir do modelo virtual.
+     */
+    private captureAndRenderInitialData;
+    /**
+     * Retorna as linhas atualmente selecionadas.
+     *
+     * @returns Elementos `br-table-row` selecionados no corpo.
+     */
+    getSelectedRows(): Promise<HTMLBrTableRowElement[]>;
+    /**
+     * Seleciona todas as linhas elegíveis.
+     */
+    selectAllRows(): Promise<void>;
+    /**
+     * Limpa a seleção de todas as linhas elegíveis.
      */
-    private refreshStructure;
-    private scheduleStructureRefresh;
+    clearSelection(): Promise<void>;
+    /** Retorna o estado atual de ordenação aplicado na tabela. */
+    getSorting(): Promise<TableSortState[]>;
     /**
-     * Atualiza a largura das colunas com base nos cabeçalhos.
-     * @returns void
+     * Expande uma linha elegível do corpo.
+     *
+     * @param rowIndex Índice da linha, começando em zero.
+     */
+    expandRow(rowIndex: number): Promise<void>;
+    /**
+     * Recolhe uma linha do corpo.
+     *
+     * @param rowIndex Índice da linha, começando em zero.
+     */
+    collapseRow(rowIndex: number): Promise<void>;
+    /**
+     * Recolhe todas as linhas que estiverem expandidas.
+     */
+    collapseAllRows(): Promise<void>;
+    /** Resolve o próximo estado de ordenação para a coluna acionada. */
+    private resolveNextSorting;
+    /** Mantém a prioridade do multi-sort estritamente da esquerda para a direita. */
+    private getSortingByColumnOrder;
+    /**
+     * Aplica a ordenação ao dataset completo e só então reinicia a janela virtual.
+     */
+    private applySorting;
+    /** Reflete o estado lógico nos cabeçalhos para atualizar ícones e semântica. */
+    private syncHeaderSortState;
+    /**
+     * Observa linhas adicionadas, removidas ou alteradas em tempo de execução.
+     */
+    private observeStructureChanges;
+    /**
+     * Processa mutações externas: estrutura completa quando linhas mudam e somente
+     * densidade quando a herança CSS dentro da tabela pode ter mudado.
+     */
+    private handleStructureMutations;
+    /**
+     * Executa escritas internas sem realimentar o observer estrutural.
+     *
+     * @remarks Mutações externas já pendentes são preservadas e reprocessadas;
+     * somente os registros gerados durante `write` são descartados, pois quem
+     * escreve já sincroniza o estado derivado.
+     */
+    private runWithoutSelfMutations;
+    /**
+     * Determina se uma mutação exige sincronização estrutural da tabela.
+     */
+    private isRelevantStructureMutation;
+    /**
+     * Processa mutações de atributo aplicadas às linhas.
+     */
+    private handleGroupingMutation;
+    private handleRowAttributeMutation;
+    /**
+     * Verifica se os nós alterados impactam linhas da tabela.
+     */
+    private hasRowChangeInNodes;
+    /**
+     * Detecta a presença de ações atribuídas às barras.
+     */
+    private syncBarActionsContent;
+    /**
+     * Atualiza o estado reativo usado pela barra contextual.
+     */
+    private updateSelectionCount;
+    /**
+     * Sincroniza células, checkboxes e estado da seleção.
+     */
+    private syncSelectionStructure;
+    /**
+     * Sincroniza células, ações e estado da expansão.
+     */
+    private syncExpansionStructure;
+    /** Aplica às linhas a marca consumida pelo estilo de hover das células. */
+    private syncRowHoverState;
+    /**
+     * Retorna somente as linhas pertencentes ao corpo da tabela.
+     */
+    private getBodyRows;
+    /** Atualiza somente os elementos atualmente materializados pela lista virtual. */
+    private syncRenderedRange;
+    private updateActionDensities;
+    private updateScrollableContentState;
+    /**
+     * Mede cabeçalho e uma linha colapsada já renderizada para garantir que
+     * `visibleRows` corresponda à quantidade real de linhas visíveis.
+     * A estimativa baseada em densidade continua sendo usada somente antes da
+     * primeira materialização.
+     */
+    /**
+     * Invalida as métricas que definem a altura externa da viewport.
+     *
+     * @remarks A altura não deve ser recalculada durante o scroll, porque
+     * diferentes janelas podem conter linhas com alturas distintas. Recalcular
+     * nesse momento faria o próprio `br-table` crescer ou encolher e deslocaria
+     * elementos externos à tabela.
+     */
+    private invalidateViewportMetrics;
+    private scheduleViewportHeightMeasurement;
+    private applyMeasuredViewportHeight;
+    /**
+     * Marca limites de linha e coluna usados pelos estilos de divisores.
+     */
+    /** Matriz lógica inclui células mescladas nas posições ocupadas. */
+    private getKeyboardRows;
+    private syncHeaderGrouping;
+    private annotateBoundaries;
+    /**
+     * Registra a coordenação de mudanças de largura emitidas pelas colunas.
+     */
+    private registerColumnWidthListener;
+    /**
+     * Recalcula e aplica a definição de colunas do grid.
      */
     private updateColumnWidths;
     /**
-     * Constrói o template de grid para a tabela com base nos cabeçalhos.
-     * @param headers Os elementos de cabeçalho da tabela.
-     * @returns Uma string representando o template de grid CSS.
+     * Constrói o valor de `grid-template-columns` na ordem dos cabeçalhos.
      */
     private buildGridTemplate;
     /**
-     * Resolve a largura de uma coluna específica com base no cabeçalho e na largura global da tabela.
+     * Resolve a largura padrão declarada na tabela.
      */
     private resolveTableColumnWidth;
     /**
-     * Resolve a largura de uma coluna específica com base no cabeçalho e na largura global da tabela.
-     * @param header O elemento de cabeçalho da coluna.
-     * @param fallback A largura de fallback a ser usada caso o cabeçalho não defina uma largura.
-     * @returns A largura resolvida da coluna.
+     * Resolve a largura de uma coluna com fallback para a tabela.
      */
     private resolveColumnWidth;
     /**
-     * Aplica o template de grid à tabela definindo a propriedade CSS customizada correspondente.
-     * @param raw O template de grid bruto a ser aplicado.
-     * @param fallback O template de grid de fallback a ser usado caso o valor bruto seja inválido.
-     * @return void
+     * Valida e converte larguras semânticas ou valores CSS aceitos.
      */
     private resolveWidthToken;
     /**
-     * Aplica o template de grid à tabela definindo a propriedade CSS customizada correspondente.
-     * @param template O template de grid a ser aplicado.
+     * Publica a definição de colunas por meio do token do grid.
      */
     private applyGridTemplate;
     /**
-     * Atualiza o alinhamento de todas as células da tabela com base nos tokens de alinhamento.
+     * Registra a coordenação de mudanças de alinhamento emitidas pelos filhos.
+     */
+    private registerAlignmentListener;
+    /**
+     * Recalcula os alinhamentos efetivos de todas as células.
      */
     private updateAllCellAlignments;
     /**
-     * Atualiza o alinhamento de uma célula específica com base nos tokens de alinhamento.
-     * @param cell A célula a ser atualizada.
+     * Aplica os alinhamentos efetivos como tokens locais da célula.
      */
     private updateAlignmentForCell;
     /**
-     * Resolve o alinhamento horizontal de uma célula específica com base nos tokens de alinhamento.
-     * @param cell A célula a ser avaliada.
-     * @returns O valor do token de alinhamento horizontal resolvido.
+     * Resolve o alinhamento horizontal conforme a hierarquia da tabela.
      */
     private resolveHorizontalAlignmentForCell;
     /**
-     * Resolve o alinhamento vertical de uma célula específica com base nos tokens de alinhamento.
-     * @param cell A célula a ser avaliada.
-     * @returns O valor do token de alinhamento vertical resolvido.
+     * Resolve o alinhamento vertical conforme a hierarquia da tabela.
      */
     private resolveVerticalAlignmentForCell;
     /**
-     * Resolve um valor de token de alinhamento com base no valor bruto e no mapeamento semântico definido.
-     * @param value O valor bruto do token de alinhamento a ser resolvido.
-     * @returns O valor do token de alinhamento resolvido, ou o valor de fallback se o valor bruto for inválido.
+     * Converte um alinhamento semântico no valor CSS correspondente.
      */
     private resolveAlignmentToken;
     /**
-     * Retorna o valor do atributo de alinhamento de uma coluna específica.
-     * @param cell A célula para a qual o alinhamento da coluna deve ser obtido.
-     * @param attribute O atributo de alinhamento a ser obtido ('horizontal-alignment' ou 'vertical-alignment').
-     * @returns O valor do atributo de alinhamento da coluna, ou null se não estiver definido.
+     * Obtém um atributo herdável no cabeçalho da coluna correspondente.
      */
     private getColumnAlignment;
     /**
-     * Obtém o índice da coluna para uma célula específica, permitindo a associação entre células e seus respectivos cabeçalhos para herança de propriedades como alinhamento e largura.
-     * @param cell A célula para a qual o índice da coluna deve ser obtido.
-     * @returns O índice da coluna correspondente à célula, ou -1 se a célula não estiver dentro de uma linha válida.
+     * Retorna a posição de uma célula dentro de sua linha.
      */
     private getColumnIndex;
     /**
-     * Constrói o template de grid para a tabela com base nos cabeçalhos.
-     * @return Array de larguras de coluna resolvidas.
+     * Retorna os cabeçalhos na ordem visual do grid.
      */
     private getHeaderCells;
     /**
-     * Obtém todas as células (tanto de corpo quanto de cabeçalho) da tabela, permitindo a aplicação de estilos e tokens de forma abrangente.
-     * @returns Um array contendo todas as células da tabela.
+     * Retorna células de cabeçalho e de dados.
      */
     private getAllCells;
     /**
-     * Recalcula estrutura, tokens e metadados de acessibilidade quando há mudança de slots.
+     * Registra a coordenação de mudanças de overflow emitidas pelos filhos.
+     */
+    private registerOverflowListener;
+    /**
+     * Ressincroniza todas as estruturas derivadas após uma mudança no conteúdo.
+     * A ordem preserva expansão antes de seleção e ambas antes das colunas de dados.
      */
     private handleStructureChange;
     /**
-     * Aplica metadados ARIA para melhorar a navegação por leitores de tela.
+     * Aplica contagens e índices ARIA à estrutura atual.
      */
     private applyAriaMetadata;
     /**
-     * Atualiza os tokens de overflow para todas as células da tabela, garantindo que as mudanças na propriedade de overflow sejam refletidas dinamicamente em todas as células, controlando o comportamento de overflow, text-overflow e white-space conforme definido no token.
+     * Recalcula o overflow efetivo de todas as células.
      */
     private updateAllCellOverflow;
-    private updateAlignmentForTarget;
-    private updateOverflowForTarget;
     /**
-     * Atualiza os tokens de overflow para uma célula específica, controlando o comportamento de overflow, text-overflow e white-space com base na resolução do token de overflow para a célula, que considera atributos específicos da célula, da linha, da coluna e da tabela para determinar o comportamento final de overflow a ser aplicado.
-     * @param cell A célula para a qual os tokens de overflow devem ser atualizados.
+     * Aplica a configuração efetiva de overflow como tokens locais.
      */
     private updateOverflowForCell;
     /**
-     * Resolve o token de overflow para uma célula específica, considerando a hierarquia de atributos (célula, linha, coluna, tabela) para determinar o comportamento de overflow final a ser aplicado à célula.
-     * @param cell A célula para a qual o token de overflow deve ser resolvido.
-     * @returns O valor do token de overflow resolvido para a célula, determinando o comportamento de overflow a ser aplicado.
+     * Resolve o overflow conforme célula, linha, coluna e tabela.
      */
     private resolveOverflowForCell;
     /**
-     * Obtém o valor de um atributo específico de uma coluna para uma célula, permitindo a herança de propriedades da coluna para as células associadas com base no cabeçalho correspondente.
-     * @param cell A célula para a qual o atributo da coluna deve ser obtido.
-     * @param attribute O atributo específico a ser obtido da coluna (por exemplo, 'horizontal-alignment' ou 'vertical-alignment').
-     * @returns O valor do atributo da coluna correspondente à célula, ou null se não estiver definido.
+     * Obtém um atributo no cabeçalho correspondente à célula.
      */
     private getColumnAttribute;
     /**
-     * Obtém o elemento de cabeçalho correspondente a uma célula específica, permitindo a associação entre células e seus respectivos cabeçalhos para herança de propriedades como alinhamento e largura.
-     * @param cell A célula para a qual o cabeçalho correspondente deve ser obtido.
-     * @returns O elemento de cabeçalho correspondente à célula, ou null se não for encontrado.
+     * Localiza o cabeçalho que ocupa a mesma coluna da célula.
      */
     private getHeaderForCell;
+    /** Publica a altura padrão da área expandida para herança pelas linhas. */
+    private applyExpandedContentHeight;
     /**
-     * Resolve e aplica o token de densidade.
+     * Converte a densidade semântica em tokens de espaçamento.
      */
     private applyDensity;
     /**
-     * Resolve e aplica os tokens relacionados aos divisores
-     * (estilo e fatores de linha/coluna).
+     * Aplica estilo e fatores de visibilidade dos divisores.
      */
     private applyDividers;
     /**
-     * Retorna o mapa de classes base do componente.
-     *
-     * @returns Um objeto representando as classes CSS a serem aplicadas ao elemento da tabela.
-     */
-    private getTableCssClassMap;
-    /**
-     * Renderiza a estrutura interna da tabela (header e body).
+     * Renderiza barras, slots e o grid principal.
      *
-     * @returns JSX.Element representando o conteúdo da tabela, incluindo os slots para header e body.
+     * @remarks `role="grid"` fica isolado no contêiner que só possui os dois
+     * elementos `role="rowgroup"` como filhos; a barra de ações e o rodapé
+     * ficam fora dessa árvore para não serem contados como filhos inválidos do
+     * papel `grid`. O nome acessível vai como `aria-label` (string), pois um
+     * `aria-labelledby` não resolveria um id do light DOM a partir da shadow tree.
      */
     private renderContent;
+    /** Resolve o nome acessível do papel `grid`, sempre como texto plano. */
+    private resolveAccessibleGridName;
     /**
-     * Renderiza o host do componente.
-     *
-     * @returns JSX.Element representando o elemento host do componente, contendo a estrutura da tabela.
+     * Renderiza o componente com semântica ARIA de grid.
      */
     render(): any;
 }