@govbr-ds/webcomponents 2.5.0 → 2.6.0

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

@@ -0,0 +1,52 @@
+import type { TableDensity } from './table.types';
+/**
+ * Mapa entre um valor semântico e seu valor CSS efetivo.
+ */
+type SemanticMap = Record<string, string>;
+/**
+ * Validador de valores CSS fornecidos pelo consumidor.
+ */
+type Validator = (value: string) => boolean;
+/**
+ * Resolve um valor semântico ou CSS validado, utilizando fallback quando inválido.
+ *
+ * @param raw Valor recebido pela API pública.
+ * @param options Mapa semântico, validadores e fallback da resolução.
+ * @returns Valor CSS seguro que pode ser aplicado ao componente.
+ */
+export declare function resolveTokenValue(raw: string | undefined, options: {
+    fallback: string;
+    semanticMap?: SemanticMap;
+    validators?: Validator[];
+}): string;
+/**
+ * Valida valores positivos expressos em pixels.
+ *
+ * @param value Valor CSS candidato.
+ * @returns `true` quando o valor utiliza `px` e é maior que zero.
+ */
+export declare const positivePxValidator: Validator;
+/**
+ * Valida valores positivos expressos como fração de grid.
+ *
+ * @param value Valor CSS candidato.
+ * @returns `true` quando o valor utiliza `fr` e é maior que zero.
+ */
+export declare const positiveFrValidator: Validator;
+/**
+ * Solicita a execução de uma função no próximo frame de animação.
+ *
+ * @returns Promise que resolve no próximo frame de animação.
+ */
+export declare const requestAnimationFramePromise: () => Promise<void>;
+/**
+ * Resolve a densidade semântica correspondente ao token CSS efetivo de uma célula.
+ */
+export declare function resolveTableDensityFromElement(element: HTMLElement | null): TableDensity;
+/**
+ * Indica se uma mutação de `class` apenas adicionou ou removeu a marca
+ * `hydrated` do Stencil, que não altera a herança de tokens da tabela.
+ * Exige `attributeOldValue` no observer.
+ */
+export declare function isHydrationClassMutation(mutation: MutationRecord): boolean;
+export {};

package/dist/types/components/table/table.virtual-list.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Controlador de janela virtual das linhas da tabela.
+ *
+ * @module table-virtual-list
+ */
+export type TableVirtualRange = {
+    start: number;
+    end: number;
+    beforeHeight: number;
+    afterHeight: number;
+};
+export type TableVirtualListOptions = {
+    /** Visão interna estável; trocar a referência ao substituir, reordenar ou recortar linhas. */
+    getRows: () => readonly HTMLBrTableRowElement[];
+    getViewport: () => HTMLElement | null;
+    getStickyHeaderHeight: () => number;
+    renderRange: (range: TableVirtualRange) => void;
+    visibleRows: () => number;
+    estimatedRowHeight: () => number;
+    estimatedExpandedHeight: () => number;
+    onAfterRender?: () => void;
+};
+/**
+ * Materializa uma quantidade estável de linhas ao redor da viewport.
+ *
+ * @remarks
+ * A quantidade de elementos montados é calculada por `visibleRows` mais um
+ * buffer interno fixo de quatro linhas. A janela é ampliada aos limites dos
+ * grupos contíguos, podendo exceder essa quantidade para manter mesclas íntegras.
+ * Linhas expandidas alteram a altura
+ * total, mas não aumentam a quantidade de `br-table-row` materializados.
+ *
+ * A janela só é reposicionada quando a área visível se aproxima de uma das
+ * bordas do buffer. Isso reduz substituições de DOM durante o scroll.
+ * As somas de alturas são reutilizadas até `reset`, `invalidateRow`, uma nova
+ * sequência lógica ou uma medição diferente. Somente a faixa montada é medida.
+ */
+export declare class TableVirtualListController {
+    private readonly options;
+    private measuredHeights;
+    private indexedRows?;
+    private prefix?;
+    private currentRange;
+    private viewport;
+    private resizeObserver?;
+    private rafId?;
+    private measurementRafId?;
+    private pendingRevealIndex?;
+    private measurementVersion;
+    constructor(options: TableVirtualListOptions);
+    connect(): void;
+    disconnect(): void;
+    reset(scrollToTop?: boolean): void;
+    invalidateRow(index: number): void;
+    /** Recalcula a área útil sem descartar alturas de linhas ou a posição do scroll. */
+    refreshViewport(): void;
+    /** Materializa o destino antes do foco; null representa o cabeçalho. */
+    revealRow(index: number | null): void;
+    sync(force?: boolean): void;
+    /**
+     * Resolve a quantidade total de linhas adicionais mantidas no pool virtual.
+     * O buffer é fixo para tornar o custo de DOM previsível durante o scroll.
+     */
+    private resolveBufferRows;
+    /** Resolve a quantidade efetiva de linhas visíveis para o dataset atual. */
+    private resolveVisibleCapacity;
+    /**
+     * Mantém a janela atual enquanto a viewport estiver dentro de sua zona
+     * segura. A troca ocorre em blocos, e não a cada nova linha visível.
+     */
+    private canKeepCurrentRange;
+    /**
+     * Mantém uma quantidade fixa de linhas materializadas para um mesmo
+     * `visibleRows`: capacidade visível + até quatro linhas de buffer.
+     */
+    private resolveRenderedRowCount;
+    /** Centraliza a faixa ao redor do início visível sem variar seu tamanho. */
+    private createStableRange;
+    /** Reutiliza as somas enquanto a sequência lógica e suas alturas permanecem válidas. */
+    private getPrefix;
+    private estimateHeight;
+    private findRowAtOffset;
+    /**
+     * Mede somente as linhas materializadas e preserva a posição visual da linha
+     * âncora caso a altura de itens anteriores seja corrigida.
+     */
+    private scheduleMeasurement;
+    private isMeasurementCurrent;
+    private applyMeasurements;
+    private updateMeasuredHeights;
+    private measureRows;
+    private scheduleSync;
+    private handleScroll;
+    private disconnectViewport;
+    private isSameRange;
+}