@govbr-ds/webcomponents 2.4.0 → 2.6.0

package/dist/collection/components/table/table.keyboard.js

@@ -0,0 +1,340 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+import { FOCUSABLE_SELECTORS } from "../../shared/utils/focus";
+const CELL_SELECTOR = 'br-table-cell, br-table-header-cell';
+const CONTROL_SELECTOR = `${FOCUSABLE_SELECTORS}, br-checkbox, br-table-action, [contenteditable="true"], summary`;
+/** Coordena apenas o DOM pertencente à célula, sem acessar internals de controles. */
+export class TableCellKeyboard {
+    constructor(host, surface) {
+        this.host = host;
+        this.surface = surface;
+        this.originalTabIndexes = new Map();
+        this.active = false;
+        this.hasGridControls = false;
+    }
+    connect() {
+        this.observer?.disconnect();
+        if (this.host.closest('br-table') === null)
+            return;
+        this.observer = new MutationObserver(() => {
+            this.sync();
+            this.notifyFocusRegistration();
+        });
+        const options = {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ['disabled', 'hidden', 'tabindex', 'sortable'],
+        };
+        this.observer.observe(this.host, options);
+        if (this.host.shadowRoot !== null)
+            this.observer.observe(this.host.shadowRoot, options);
+        this.notifyFocusRegistration();
+        this.sync();
+    }
+    disconnect() {
+        this.observer?.disconnect();
+        this.surface.removeAttribute('tabindex');
+        this.originalTabIndexes.forEach((value, element) => {
+            this.restoreTabIndex(element, value);
+        });
+        this.originalTabIndexes.clear();
+    }
+    candidates() {
+        const roots = [this.host];
+        if (this.host.shadowRoot !== null)
+            roots.push(this.host.shadowRoot);
+        const candidates = roots.flatMap((root) => Array.from(root.querySelectorAll(CONTROL_SELECTOR)).filter((control) => control !== this.surface &&
+            !control.matches(CELL_SELECTOR) &&
+            control.closest(CELL_SELECTOR) === (root === this.host ? this.host : null)));
+        return [...new Set([...candidates, ...this.originalTabIndexes.keys()])].filter((control) => control.closest(CELL_SELECTOR) === this.host ||
+            (control.getRootNode() === this.host.shadowRoot && control.closest(CELL_SELECTOR) === null));
+    }
+    controls() {
+        return this.candidates().filter((control) => !control.matches(':disabled, [disabled], [hidden], [inert]') &&
+            control.closest('[hidden], [inert], [disabled]') === null &&
+            control.getClientRects().length > 0 &&
+            getComputedStyle(control).visibility !== 'hidden' &&
+            this.originalTabIndexes.get(control) !== '-1' &&
+            !this.candidates().some((parent) => parent !== control && parent.contains(control)));
+    }
+    sync() {
+        const candidates = this.candidates();
+        this.originalTabIndexes.forEach((value, control) => {
+            if (candidates.includes(control))
+                return;
+            this.restoreTabIndex(control, value);
+            this.originalTabIndexes.delete(control);
+        });
+        candidates.forEach((control) => {
+            if (!this.originalTabIndexes.has(control)) {
+                this.originalTabIndexes.set(control, control.getAttribute('tabindex'));
+            }
+            const value = this.originalTabIndexes.get(control);
+            if (value === null) {
+                if (control.hasAttribute('tabindex'))
+                    control.removeAttribute('tabindex');
+            }
+            else if (value !== undefined && control.getAttribute('tabindex') !== value) {
+                control.setAttribute('tabindex', value);
+            }
+        });
+        const tabIndex = this.active && !this.hasGridControls ? 0 : -1;
+        if (this.surface.getAttribute('tabindex') !== String(tabIndex))
+            this.surface.tabIndex = tabIndex;
+    }
+    restoreTabIndex(control, value) {
+        if (value === null)
+            control.removeAttribute('tabindex');
+        else
+            control.setAttribute('tabindex', value);
+    }
+    notifyFocusRegistration() {
+        this.host.dispatchEvent(new CustomEvent('brInternalTableCellFocus', {
+            bubbles: true,
+            composed: true,
+            detail: {
+                host: this.host,
+                surface: this.surface,
+                controls: () => this.controls(),
+                update: (active, hasGridControls) => {
+                    this.active = active;
+                    this.hasGridControls = hasGridControls;
+                    this.sync();
+                },
+            },
+        }));
+    }
+}
+/** Gerencia a célula ativa e os dois modos de teclado de uma instância da grade. */
+export class TableKeyboardController {
+    constructor(host, getRows, reveal, pageSize) {
+        this.host = host;
+        this.getRows = getRows;
+        this.reveal = reveal;
+        this.pageSize = pageSize;
+        this.cells = new Map();
+        this.interacting = false;
+        this.hasFocused = false;
+    }
+    register(cell) {
+        if (this.active?.host === cell.host)
+            this.active = cell;
+        this.cells.set(cell.host, cell);
+        this.sync();
+        if (this.pendingFocus === cell.host) {
+            // A linha ancestral também precisa terminar a hidratação antes de receber foco.
+            if (this.focusFrame !== undefined)
+                cancelAnimationFrame(this.focusFrame);
+            this.focusFrame = requestAnimationFrame(() => {
+                this.focusFrame = undefined;
+                this.focusPendingCell();
+            });
+        }
+    }
+    sync() {
+        const logicalCells = this.getRows().flat();
+        this.cells.forEach((cell, host) => {
+            if (!logicalCells.includes(host))
+                this.cells.delete(cell.host);
+        });
+        const available = logicalCells.filter((cell) => this.cells.has(cell) && cell.isConnected);
+        if (!this.hasFocused || this.active === undefined || !available.includes(this.active.host)) {
+            this.active = this.cells.get(available[0]);
+            this.interacting = false;
+        }
+        const hasGridControls = available.some((host) => this.cells.get(host)?.controls().length);
+        this.cells.forEach((cell) => {
+            cell.update(cell === this.active, Boolean(hasGridControls));
+        });
+    }
+    disconnect() {
+        if (this.focusFrame !== undefined)
+            cancelAnimationFrame(this.focusFrame);
+        this.focusFrame = undefined;
+        this.cells.clear();
+        this.active = undefined;
+        this.interacting = false;
+        this.hasFocused = false;
+        this.pendingFocus = undefined;
+        this.releaseTransitionFocus();
+    }
+    focusIn(event) {
+        const cell = this.cellFromEvent(event);
+        if (event.composedPath()[0] !== this.host && this.transitionTabIndex !== undefined) {
+            this.pendingFocus = undefined;
+            this.releaseTransitionFocus();
+        }
+        if (cell === undefined)
+            return;
+        this.active = cell;
+        this.hasFocused = true;
+        this.interacting = event.composedPath()[0] !== cell.surface;
+        this.sync();
+    }
+    focusOut(event) {
+        if (event.relatedTarget instanceof Node && this.host.contains(event.relatedTarget))
+            return;
+        if (event.relatedTarget !== null || event.composedPath()[0] === this.host) {
+            this.pendingFocus = undefined;
+            this.releaseTransitionFocus();
+        }
+        this.interacting = false;
+        this.sync();
+    }
+    keyDown(event) {
+        if (event.defaultPrevented || event.altKey || event.metaKey)
+            return;
+        if (this.pendingFocus !== undefined && event.composedPath()[0] === this.host) {
+            if (event.key === 'Tab') {
+                this.abandonPendingFocus(event.shiftKey);
+                return;
+            }
+            this.navigate(event, this.pendingFocus);
+            return;
+        }
+        const cell = this.cellFromEvent(event);
+        if (cell === undefined)
+            return;
+        if (this.interacting) {
+            this.handleInteraction(event, cell);
+            return;
+        }
+        if (event.key === 'Enter' || event.key === 'F2') {
+            const control = cell.controls()[0];
+            if (control !== undefined) {
+                event.preventDefault();
+                this.interacting = true;
+                this.sync();
+                control.focus();
+            }
+            return;
+        }
+        this.navigate(event, cell.host);
+    }
+    handleInteraction(event, cell) {
+        if (event.key === 'Escape' || event.key === 'F2') {
+            event.preventDefault();
+            this.interacting = false;
+            this.sync();
+            cell.surface.focus();
+        }
+    }
+    navigate(event, host) {
+        const rows = this.getRows();
+        const rowIndex = rows.findIndex((row) => row.includes(host));
+        const columnIndex = rows[rowIndex]?.indexOf(host) ?? -1;
+        if (rowIndex < 0 || columnIndex < 0)
+            return;
+        let nextRow = rowIndex;
+        let nextColumn = columnIndex;
+        switch (event.key) {
+            case 'ArrowRight':
+                nextColumn++;
+                break;
+            case 'ArrowLeft':
+                nextColumn--;
+                break;
+            case 'ArrowDown':
+                nextRow++;
+                break;
+            case 'ArrowUp':
+                nextRow--;
+                break;
+            case 'Home':
+                if (event.ctrlKey)
+                    nextRow = 0;
+                nextColumn = 0;
+                break;
+            case 'End':
+                if (event.ctrlKey)
+                    nextRow = rows.length - 1;
+                nextColumn = (rows[nextRow]?.length ?? 1) - 1;
+                break;
+            case 'PageDown':
+            case 'PageUp': {
+                const pageSize = this.pageSize();
+                nextRow += event.key === 'PageDown' ? pageSize : -pageSize;
+                break;
+            }
+            default:
+                return;
+        }
+        [nextRow, nextColumn] = this.skipMergedCell(event.key, rows, host, rowIndex, columnIndex, nextRow, nextColumn);
+        event.preventDefault();
+        nextRow = Math.max(0, Math.min(nextRow, rows.length - 1));
+        nextColumn = Math.max(0, Math.min(nextColumn, rows[nextRow].length - 1));
+        const target = rows[nextRow][nextColumn];
+        this.pendingFocus = target;
+        this.reveal(target);
+        this.focusPendingCell();
+        if (this.pendingFocus !== undefined) {
+            // Mantém as próximas teclas na grade enquanto a linha de destino hidrata.
+            if (this.transitionTabIndex === undefined)
+                this.transitionTabIndex = this.host.getAttribute('tabindex');
+            this.host.tabIndex = -1;
+            this.host.focus({ preventScroll: true });
+        }
+    }
+    skipMergedCell(key, rows, host, row, column, nextRow, nextColumn) {
+        if (!key.startsWith('Arrow'))
+            return [nextRow, nextColumn];
+        const rowStep = nextRow - row;
+        const columnStep = nextColumn - column;
+        while (rows[nextRow]?.[nextColumn] === host) {
+            nextRow += rowStep;
+            nextColumn += columnStep;
+        }
+        return [nextRow, nextColumn];
+    }
+    abandonPendingFocus(shift) {
+        this.pendingFocus = undefined;
+        if (this.focusFrame !== undefined)
+            cancelAnimationFrame(this.focusFrame);
+        this.focusFrame = undefined;
+        if (!shift) {
+            this.cells.forEach((cell) => {
+                cell.update(false, false);
+            });
+            const scroller = this.host.shadowRoot?.querySelector('.br-table-scroll');
+            if (scroller && !scroller.hasAttribute('tabindex')) {
+                scroller.tabIndex = -1;
+                this.scrollerTabIndexSet = scroller;
+            }
+        }
+    }
+    releaseTransitionFocus() {
+        if (this.scrollerTabIndexSet !== undefined) {
+            this.scrollerTabIndexSet.removeAttribute('tabindex');
+            this.scrollerTabIndexSet = undefined;
+        }
+        if (this.transitionTabIndex === undefined)
+            return;
+        const tabIndex = this.transitionTabIndex;
+        this.transitionTabIndex = undefined;
+        if (tabIndex === null)
+            this.host.removeAttribute('tabindex');
+        else
+            this.host.setAttribute('tabindex', tabIndex);
+    }
+    focusPendingCell() {
+        if (this.pendingFocus === undefined)
+            return;
+        const next = this.cells.get(this.pendingFocus);
+        if (next === undefined || !next.host.isConnected)
+            return;
+        if (getComputedStyle(next.surface).visibility === 'hidden')
+            return;
+        this.pendingFocus = undefined;
+        this.active = next;
+        this.sync();
+        next.surface.focus();
+        this.releaseTransitionFocus();
+    }
+    cellFromEvent(event) {
+        const host = event.composedPath().find((target) => target instanceof HTMLElement && target.matches(CELL_SELECTOR));
+        return host instanceof HTMLElement ? this.cells.get(host) : undefined;
+    }
+}

package/dist/collection/components/table/table.scroll-shadows.js

@@ -0,0 +1,36 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/** Mantém os indicadores de conteúdo oculto sincronizados com a área rolável. */
+export class TableScrollShadows {
+    constructor(viewport, content, shell) {
+        this.viewport = viewport;
+        this.shell = shell;
+        /** Recalcula as bordas, tolerando arredondamento de pixels nas extremidades. */
+        this.update = () => {
+            const { scrollTop, scrollLeft, scrollHeight, scrollWidth, clientHeight, clientWidth } = this.viewport;
+            const directions = {
+                top: scrollTop > 1,
+                bottom: scrollHeight - clientHeight - scrollTop > 1,
+                left: scrollLeft > 1,
+                right: scrollWidth - clientWidth - scrollLeft > 1,
+            };
+            for (const [direction, visible] of Object.entries(directions)) {
+                this.shell.style.setProperty(`--table-scroll-shadow-${direction}`, visible ? '8px' : '0px');
+            }
+        };
+        viewport.addEventListener('scroll', this.update, { passive: true });
+        if (typeof ResizeObserver !== 'undefined') {
+            this.observer = new ResizeObserver(this.update);
+            this.observer.observe(viewport);
+            this.observer.observe(content);
+        }
+        this.update();
+    }
+    /** Remove listeners e observadores ao desmontar a superfície. */
+    disconnect() {
+        this.viewport.removeEventListener('scroll', this.update);
+        this.observer?.disconnect();
+    }
+}

package/dist/collection/components/table/table.selection.elements.js

@@ -0,0 +1,63 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Factories dos elementos utilizados pela seleção de linhas.
+ *
+ * @module table-selection-elements
+ */
+import { TABLE_ALIGNMENT, TABLE_SELECTION_CHECKBOX_ATTR, TABLE_SELECTION_COLUMN_ATTR, TABLE_SELECTION_COLUMN_WIDTH, TABLE_SELECTION_GENERATED_ATTR, } from "./table.constants";
+/**
+ * Cria uma instância configurada do componente `br-checkbox`.
+ *
+ * @param options Categoria, rótulo acessível e nome do controle.
+ * @returns Checkbox pronto para ser anexado a uma célula.
+ */
+export function createSelectionCheckbox({ kind, label, name }) {
+    const checkbox = document.createElement('br-checkbox');
+    checkbox.setAttribute(TABLE_SELECTION_CHECKBOX_ATTR, kind);
+    checkbox.setAttribute('compact', '');
+    checkbox.setAttribute('has-hidden-label', '');
+    checkbox.setAttribute('label', label);
+    checkbox.setAttribute('name', name);
+    return checkbox;
+}
+/**
+ * Cria a célula estrutural de seleção de uma linha.
+ *
+ * @param checkbox Controle associado à linha.
+ * @returns Célula marcada como gerada pelo controller de seleção.
+ */
+export function createSelectionCell(checkbox) {
+    const cell = document.createElement('br-table-cell');
+    cell.setAttribute(TABLE_SELECTION_COLUMN_ATTR, '');
+    cell.setAttribute(TABLE_SELECTION_GENERATED_ATTR, '');
+    cell.setAttribute('horizontal-alignment', TABLE_ALIGNMENT.CENTER);
+    cell.setAttribute('vertical-alignment', TABLE_ALIGNMENT.CENTER);
+    cell.appendChild(checkbox);
+    return cell;
+}
+/**
+ * Cria o cabeçalho que define largura e alinhamentos da coluna de seleção.
+ *
+ * @param options Checkbox global e slot opcional do cabeçalho.
+ * @returns Cabeçalho configurado para participar do grid da tabela.
+ */
+export function createSelectionHeaderCell({ checkbox, slotName, }) {
+    const cell = document.createElement('br-table-header-cell');
+    cell.setAttribute(TABLE_SELECTION_COLUMN_ATTR, '');
+    cell.setAttribute(TABLE_SELECTION_GENERATED_ATTR, '');
+    cell.setAttribute('horizontal-alignment', TABLE_ALIGNMENT.CENTER);
+    cell.setAttribute('vertical-alignment', TABLE_ALIGNMENT.CENTER);
+    /*
+     * A tabela consulta esses atributos antes de o Custom Element necessariamente
+     * concluir seu upgrade; por isso a configuração inicial utiliza atributos.
+     */
+    cell.setAttribute('column-width', TABLE_SELECTION_COLUMN_WIDTH);
+    if (slotName !== undefined) {
+        cell.setAttribute('slot', slotName);
+    }
+    cell.appendChild(checkbox);
+    return cell;
+}

package/dist/collection/components/table/table.selection.js

@@ -0,0 +1,239 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Controller responsável pela seleção de linhas.
+ *
+ * @module table-selection
+ */
+import { TABLE_SELECTION_CHECKBOX_ATTR, TABLE_SELECTION_COLUMN_ATTR, TABLE_SELECTION_GENERATED_ATTR, } from "./table.constants";
+import { createSelectionCell, createSelectionCheckbox, createSelectionHeaderCell } from "./table.selection.elements";
+/**
+ * Coordena a estrutura e o estado da seleção sem acoplar regras ao componente raiz.
+ *
+ * @remarks O controller mantém checkbox, atributos da linha, ARIA e cabeçalho sincronizados.
+ */
+export class TableSelectionController {
+    constructor(options) {
+        this.options = options;
+        this.isSynchronizing = false;
+        this.checkboxDisabledStates = new WeakMap();
+    }
+    /**
+     * Sincroniza a coluna de seleção com a configuração atual da tabela.
+     *
+     * @param enabled Indica se a seleção está habilitada globalmente.
+     */
+    sync(enabled) {
+        if (!enabled) {
+            this.remove();
+            return;
+        }
+        this.ensureHeaderCell();
+        this.ensureRowCells();
+        this.syncRowsFromState();
+        this.syncHeaderCheckbox();
+    }
+    /**
+     * Processa eventos emitidos exclusivamente pelos checkboxes gerados.
+     *
+     * @param event Evento `checkedChange` recebido pela tabela.
+     * @returns `true` quando o evento pertencia ao subsistema de seleção.
+     */
+    handleCheckboxChange(event) {
+        const checkbox = this.getCheckboxFromEvent(event);
+        if (checkbox === null || this.isSynchronizing)
+            return false;
+        const kind = checkbox.getAttribute(TABLE_SELECTION_CHECKBOX_ATTR);
+        if (kind === 'all') {
+            this.selectAll(Boolean(event.detail), 'all');
+            return true;
+        }
+        if (kind !== 'row')
+            return false;
+        const row = checkbox.closest('br-table-row');
+        const rowIndex = row instanceof HTMLElement ? this.getBodyRows().indexOf(row) : -1;
+        if (row instanceof HTMLElement) {
+            this.applyRowState(row, Boolean(event.detail));
+        }
+        this.syncHeaderCheckbox();
+        this.notifyChange('row', rowIndex >= 0 ? rowIndex : undefined);
+        return true;
+    }
+    /**
+     * Retorna o estado de seleção derivado das linhas do corpo.
+     *
+     * @returns Linhas que possuem `selected` ou `data-selected`.
+     */
+    getSelectedRows() {
+        return this.getBodyRows().filter((row) => row.hasAttribute('selected') || row.hasAttribute('data-selected'));
+    }
+    /**
+     * Aplica o mesmo estado a todas as linhas selecionáveis.
+     *
+     * @param selected Novo estado das linhas.
+     * @param source Origem utilizada no evento de mudança.
+     */
+    selectAll(selected, source = 'programmatic') {
+        const entries = this.getSelectableEntries();
+        this.isSynchronizing = true;
+        entries.forEach(({ checkbox, row }) => {
+            checkbox.checked = selected;
+            this.applyRowState(row, selected);
+        });
+        this.isSynchronizing = false;
+        this.syncHeaderCheckbox();
+        this.notifyChange(source);
+    }
+    /**
+     * Limpa todas as linhas selecionáveis.
+     *
+     * @param source Origem utilizada no evento de mudança.
+     */
+    clear(source = 'programmatic') {
+        this.selectAll(false, source);
+    }
+    getCheckboxFromEvent(event) {
+        const target = event
+            .composedPath()
+            .find((node) => node?.tagName?.toLowerCase() === 'br-checkbox');
+        return target?.hasAttribute(TABLE_SELECTION_CHECKBOX_ATTR) ? target : null;
+    }
+    getBodyRows() {
+        if (this.options.getRows !== undefined)
+            return this.options.getRows();
+        return Array.from(this.options.host.querySelectorAll('br-table-row')).filter((row) => row.closest('br-table-header') === null);
+    }
+    getRowCheckbox(row) {
+        return row.querySelector(`br-checkbox[${TABLE_SELECTION_CHECKBOX_ATTR}="row"]`);
+    }
+    getSelectableEntries() {
+        return this.getBodyRows().flatMap((row) => {
+            const checkbox = this.getRowCheckbox(row);
+            const disabled = row.hasAttribute('disabled') || checkbox?.hasAttribute('disabled') === true;
+            return checkbox === null || disabled ? [] : [{ row, checkbox }];
+        });
+    }
+    getHeaderCheckbox() {
+        return this.options.host.querySelector(`br-table-header-cell[${TABLE_SELECTION_COLUMN_ATTR}] br-checkbox[${TABLE_SELECTION_CHECKBOX_ATTR}="all"]`);
+    }
+    /**
+     * Atualiza o estado visual e acessível de uma linha.
+     */
+    applyRowState(row, selected) {
+        row.toggleAttribute('selected', selected);
+        row.toggleAttribute('data-selected', selected);
+        row.setAttribute('aria-selected', String(selected));
+    }
+    syncRowsFromState() {
+        this.isSynchronizing = true;
+        this.getBodyRows().forEach((row) => {
+            const selected = row.hasAttribute('selected') || row.hasAttribute('data-selected');
+            this.applyRowState(row, selected);
+            const checkbox = this.getRowCheckbox(row);
+            if (checkbox !== null) {
+                checkbox.checked = selected;
+                this.syncCheckboxDisabledState(row, checkbox);
+            }
+        });
+        this.isSynchronizing = false;
+    }
+    syncCheckboxDisabledState(row, checkbox) {
+        const hasPreviousDisabledState = this.checkboxDisabledStates.has(checkbox);
+        if (row.hasAttribute('disabled')) {
+            if (!hasPreviousDisabledState) {
+                this.checkboxDisabledStates.set(checkbox, checkbox.disabled);
+            }
+            checkbox.disabled = true;
+        }
+        else if (hasPreviousDisabledState) {
+            checkbox.disabled = this.checkboxDisabledStates.get(checkbox) ?? false;
+            this.checkboxDisabledStates.delete(checkbox);
+        }
+    }
+    /**
+     * Sincroniza o checkbox global, incluindo o estado indeterminado.
+     */
+    syncHeaderCheckbox() {
+        const headerCheckbox = this.getHeaderCheckbox();
+        if (headerCheckbox === null)
+            return;
+        const entries = this.getSelectableEntries();
+        const checkedCount = entries.filter(({ checkbox }) => checkbox.checked).length;
+        this.isSynchronizing = true;
+        headerCheckbox.checked = entries.length > 0 && checkedCount === entries.length;
+        headerCheckbox.indeterminate = checkedCount > 0 && checkedCount < entries.length;
+        this.isSynchronizing = false;
+    }
+    /**
+     * Garante a existência do cabeçalho da coluna de seleção.
+     */
+    ensureHeaderCell() {
+        const existing = this.options.host.querySelector(`br-table-header-cell[${TABLE_SELECTION_GENERATED_ATTR}]`);
+        if (existing !== null)
+            return;
+        const firstHeaderCell = this.options.host.querySelector('br-table-header-cell');
+        if (firstHeaderCell === null)
+            return;
+        const slotName = firstHeaderCell.getAttribute('slot');
+        const checkbox = createSelectionCheckbox({
+            kind: 'all',
+            label: 'Selecionar todas as linhas',
+            name: `${this.options.idPrefix}-selection-all`,
+        });
+        const cell = createSelectionHeaderCell({
+            checkbox,
+            slotName: slotName ?? undefined,
+        });
+        firstHeaderCell.parentElement?.insertBefore(cell, firstHeaderCell);
+    }
+    /**
+     * Garante uma célula de seleção para cada linha do corpo.
+     */
+    ensureRowCells() {
+        this.getBodyRows().forEach((row, index) => {
+            const existingCheckbox = this.getRowCheckbox(row);
+            if (existingCheckbox !== null) {
+                existingCheckbox.setAttribute('label', `Selecionar linha ${index + 1}`);
+                existingCheckbox.setAttribute('name', `${this.options.idPrefix}-selection-row-${index + 1}`);
+                return;
+            }
+            const checkbox = createSelectionCheckbox({
+                kind: 'row',
+                label: `Selecionar linha ${index + 1}`,
+                name: `${this.options.idPrefix}-selection-row-${index + 1}`,
+            });
+            const cell = createSelectionCell(checkbox);
+            row.prepend(cell);
+        });
+    }
+    /**
+     * Remove somente os elementos e atributos gerados pela seleção.
+     */
+    remove() {
+        this.options.host.querySelectorAll(`[${TABLE_SELECTION_GENERATED_ATTR}]`).forEach((node) => {
+            node.remove();
+        });
+        // Desabilitar a UI de seleção remove os controles e a projeção ARIA.
+        // O estado lógico (`selected`/`data-selected`) pertence ao dataset e deve
+        // sobreviver à virtualização e a mudanças de `hasRowSelection`.
+        this.getBodyRows().forEach((row) => {
+            row.removeAttribute('aria-selected');
+        });
+    }
+    /**
+     * Publica um retrato consistente da seleção após uma mudança.
+     */
+    notifyChange(source, rowIndex) {
+        const selectedRows = this.getSelectedRows();
+        const allRows = this.getBodyRows();
+        this.options.onChange({
+            selectedRows,
+            selectedIndexes: selectedRows.map((row) => allRows.indexOf(row)),
+            selectedCount: selectedRows.length,
+            rowIndex,
+            source,
+        });
+    }
+}