@govbr-ds/webcomponents 2.1.2 → 2.2.0

package/dist/collection/pages/scripts/playground-core.js

@@ -0,0 +1,173 @@
+(() => {
+  const PRESERVE_WHITESPACE = new Set(['pre', 'script', 'style', 'textarea']);
+  const DIFF_CONTEXT = 3;
+
+  const escapeAttribute = (value) => String(value).replace(/&/g, '&').replace(/"/g, '"');
+
+  const normalizeText = (value) => value.replace(/\s+/g, ' ').trim();
+
+  const appendTextNode = (node, lines, indent, preserveWhitespace) => {
+    if (preserveWhitespace) {
+      const rawLines = node.nodeValue?.replace(/\r\n?/g, '\n').split('\n') || [];
+      rawLines.forEach((line) => {
+        lines.push(`${' '.repeat(indent)}${line}`.trimEnd());
+      });
+      return;
+    }
+    const value = normalizeText(node.nodeValue || '');
+    if (value) lines.push(`${' '.repeat(indent)}${value}`);
+  };
+
+  const appendChildNode = (child, lines, indent, preserveWhitespace) => {
+    if (child.nodeType === Node.TEXT_NODE) {
+      appendTextNode(child, lines, indent, preserveWhitespace);
+      return;
+    }
+    if (child.nodeType === Node.COMMENT_NODE) {
+      const value = child.nodeValue?.trim();
+      if (value) lines.push(`${' '.repeat(indent)}<!--${value}-->`);
+      return;
+    }
+    if (child.nodeType === Node.ELEMENT_NODE) serializeElement(child, lines, indent, preserveWhitespace);
+  };
+
+  const appendRootNode = (child, lines) => {
+    if (child.nodeType === Node.TEXT_NODE) {
+      const value = normalizeText(child.nodeValue || '');
+      if (value) lines.push(value);
+      return;
+    }
+    if (child.nodeType === Node.COMMENT_NODE) {
+      const value = child.nodeValue?.trim();
+      if (value) lines.push(`<!--${value}-->`);
+      return;
+    }
+    if (child.nodeType === Node.ELEMENT_NODE) serializeElement(child, lines);
+  };
+
+  const serializeElement = (element, lines, indent = 0, preserveWhitespace = false) => {
+    const padding = ' '.repeat(indent);
+    const tagName = element.localName;
+    const attributes = Array.from(element.attributes)
+      .sort((left, right) => left.name.localeCompare(right.name))
+      .map((attribute) => `${' '.repeat(indent + 2)}${attribute.name}="${escapeAttribute(attribute.value)}"`);
+
+    if (attributes.length === 0) lines.push(`${padding}<${tagName}>`);
+    else lines.push(`${padding}<${tagName}`, ...attributes, `${padding}>`);
+
+    const childPreservesWhitespace = preserveWhitespace || PRESERVE_WHITESPACE.has(tagName);
+    for (const child of element.childNodes) appendChildNode(child, lines, indent + 2, childPreservesWhitespace);
+
+    lines.push(`${padding}</${tagName}>`);
+  };
+
+  const canonicalizeHtml = (source) => {
+    const doc = new DOMParser().parseFromString(`<body>${String(source || '')}</body>`, 'text/html');
+    const lines = [];
+
+    for (const child of doc.body.childNodes) appendRootNode(child, lines);
+
+    return lines;
+  };
+
+  const buildLcsTable = (original, current) => {
+    const rows = Array.from({ length: original.length + 1 }, () => new Uint32Array(current.length + 1));
+    for (let originalIndex = original.length - 1; originalIndex >= 0; originalIndex -= 1) {
+      for (let currentIndex = current.length - 1; currentIndex >= 0; currentIndex -= 1) {
+        rows[originalIndex][currentIndex] =
+          original[originalIndex] === current[currentIndex]
+            ? rows[originalIndex + 1][currentIndex + 1] + 1
+            : Math.max(rows[originalIndex + 1][currentIndex], rows[originalIndex][currentIndex + 1]);
+      }
+    }
+
+    return rows;
+  };
+
+  const backtrackDiff = (original, current, rows) => {
+    const operations = [];
+    let originalIndex = 0;
+    let currentIndex = 0;
+    while (originalIndex < original.length || currentIndex < current.length) {
+      if (
+        originalIndex < original.length &&
+        currentIndex < current.length &&
+        original[originalIndex] === current[currentIndex]
+      ) {
+        operations.push({ type: 'equal', value: original[originalIndex] });
+        originalIndex += 1;
+        currentIndex += 1;
+      } else if (
+        currentIndex < current.length &&
+        (originalIndex === original.length ||
+          rows[originalIndex][currentIndex + 1] >= rows[originalIndex + 1][currentIndex])
+      ) {
+        operations.push({ type: 'insert', value: current[currentIndex] });
+        currentIndex += 1;
+      } else {
+        operations.push({ type: 'delete', value: original[originalIndex] });
+        originalIndex += 1;
+      }
+    }
+    return operations;
+  };
+
+  const buildDiffOperations = (original, current) => backtrackDiff(original, current, buildLcsTable(original, current));
+
+  const addLineNumbers = (operations) => {
+    let originalLine = 1;
+    let currentLine = 1;
+    return operations.map((operation) => {
+      const result = { ...operation, originalLine, currentLine };
+      if (operation.type !== 'insert') originalLine += 1;
+      if (operation.type !== 'delete') currentLine += 1;
+      return result;
+    });
+  };
+
+  const getHunks = (operations, context) => {
+    const changedIndexes = operations
+      .map((operation, index) => (operation.type === 'equal' ? -1 : index))
+      .filter((index) => index >= 0);
+    if (changedIndexes.length === 0) return [];
+
+    const ranges = [];
+    let rangeStart = Math.max(0, changedIndexes[0] - context);
+    let rangeEnd = Math.min(operations.length - 1, changedIndexes[0] + context);
+    changedIndexes.slice(1).forEach((index) => {
+      if (index - rangeEnd > context * 2 + 1) {
+        ranges.push([rangeStart, rangeEnd]);
+        rangeStart = Math.max(0, index - context);
+      }
+      rangeEnd = Math.min(operations.length - 1, index + context);
+    });
+    ranges.push([rangeStart, rangeEnd]);
+    return ranges;
+  };
+
+  const formatRange = (start, count) => `${start},${count}`;
+
+  const createUnifiedDiff = (originalSource, currentSource, context = DIFF_CONTEXT) => {
+    const original = canonicalizeHtml(originalSource);
+    const current = canonicalizeHtml(currentSource);
+    if (original.join('\n') === current.join('\n')) return { changed: false, lines: [], original, current };
+
+    const operations = addLineNumbers(buildDiffOperations(original, current));
+    const output = ['--- Original', '+++ Atual'];
+    getHunks(operations, context).forEach(([start, end]) => {
+      const hunk = operations.slice(start, end + 1);
+      const first = hunk[0];
+      const oldCount = hunk.filter((operation) => operation.type !== 'insert').length;
+      const newCount = hunk.filter((operation) => operation.type !== 'delete').length;
+      output.push(`@@ -${formatRange(first.originalLine, oldCount)} +${formatRange(first.currentLine, newCount)} @@`);
+      hunk.forEach((operation) => {
+        const prefix = operation.type === 'insert' ? '+' : operation.type === 'delete' ? '-' : ' ';
+        output.push(`${prefix}${operation.value || ' '}`);
+      });
+    });
+
+    return { changed: true, lines: output, original, current };
+  };
+
+  window.WBCPlaygroundCore = Object.freeze({ canonicalizeHtml, createUnifiedDiff });
+})();

package/dist/collection/shared/utils/cssVariables.js

@@ -32,6 +32,8 @@ export const getColorCSSVariable = (colorName) => {
  * @returns Valor computado sem espaços extras.
  */
 export const getCSSVariableValue = (variable, component) => {
+    if (!isClient() || !component)
+        return '';
     const styles = getComputedStyle(component);
     return String(styles.getPropertyValue(`--${variable}`)).trim();
 };

package/dist/collection/shared/utils/date.js

@@ -47,7 +47,11 @@ function isCalendarDateValid(year, month, day) {
  * @param locale Código BCP 47 da localidade (ex.: `'pt-BR'`, `'en-US'`).
  * @returns Mapa de nome de mês (lower) para índice 1–12.
  */
+const monthMapCache = new Map();
 function getMonthNameMap(locale) {
+    const cached = monthMapCache.get(locale);
+    if (cached)
+        return cached;
     const map = new Map();
     const date = new Date(2000, 0, 15);
     for (let i = 0; i < 12; i++) {
@@ -61,17 +65,17 @@ function getMonthNameMap(locale) {
     // Também registra os nomes em inglês quando a localidade não é `en-*`,
     // pois muitas APIs e textos de interface ainda usam inglês.
     if (!locale.startsWith('en')) {
-        const enDate = new Date(2000, 0, 15);
         for (let i = 0; i < 12; i++) {
-            enDate.setMonth(i);
-            const fullEn = new Intl.DateTimeFormat('en', { month: 'long' }).format(enDate).toLowerCase();
-            const shortEn = new Intl.DateTimeFormat('en', { month: 'short' }).format(enDate).toLowerCase();
+            date.setMonth(i);
+            const fullEn = new Intl.DateTimeFormat('en', { month: 'long' }).format(date).toLowerCase();
+            const shortEn = new Intl.DateTimeFormat('en', { month: 'short' }).format(date).toLowerCase();
             if (!map.has(fullEn))
                 map.set(fullEn, i + 1);
             if (!map.has(shortEn))
                 map.set(shortEn, i + 1);
         }
     }
+    monthMapCache.set(locale, map);
     return map;
 }
 /**

package/dist/collection/shared/utils/floating-ui.js

@@ -7,7 +7,7 @@
  *
  * Inclui classe e tipos para facilitar tooltips, popovers e overlays usando a biblioteca Floating UI.
  */
-import { arrow, autoUpdate, computePosition, flip, hide, offset, shift, } from "@floating-ui/dom";
+import { arrow, autoUpdate, computePosition, flip, hide, offset, shift, size, } from "@floating-ui/dom";
 /**
  * FloatingUIManager é uma classe utilitária que gerencia o posicionamento de elementos flutuantes
  * como tooltips ou popovers em relação a um elemento de disparo (trigger).
@@ -22,6 +22,7 @@ export class FloatingUIManager {
         this.strategy = options.strategy ?? 'absolute';
         this.boundary = options.boundary ?? 'clippingAncestors';
         this.offsetDistance = options.offset ?? 8;
+        this.matchReferenceWidth = options.matchReferenceWidth ?? false;
         this.onUpdate = options.onUpdate;
     }
     /**
@@ -29,6 +30,9 @@ export class FloatingUIManager {
      */
     start() {
         this.stop();
+        if (this.matchReferenceWidth) {
+            this.previousInlineWidth = this.contentElement.style.width;
+        }
         this.contentElement.style.position = this.strategy;
         this.cleanupAutoUpdate = autoUpdate(this.triggerElement, this.contentElement, () => this.updatePosition());
     }
@@ -39,6 +43,15 @@ export class FloatingUIManager {
         const cleanup = this.cleanupAutoUpdate;
         this.cleanupAutoUpdate = undefined;
         cleanup?.();
+        if (this.previousInlineWidth !== undefined) {
+            if (this.previousInlineWidth) {
+                this.contentElement.style.width = this.previousInlineWidth;
+            }
+            else {
+                this.contentElement.style.removeProperty('width');
+            }
+            this.previousInlineWidth = undefined;
+        }
     }
     /**
      * Atualiza a posição do elemento flutuante com base no elemento disparador e no elemento de conteúdo.
@@ -75,6 +88,16 @@ export class FloatingUIManager {
         if (this.arrowElement != null) {
             middleware.push(arrow({ element: this.arrowElement }));
         }
+        if (this.matchReferenceWidth) {
+            middleware.push(size({
+                apply: ({ elements, rects }) => {
+                    if (this.previousInlineWidth === undefined) {
+                        this.previousInlineWidth = elements.floating.style.width;
+                    }
+                    elements.floating.style.width = `${rects.reference.width}px`;
+                },
+            }));
+        }
         return middleware;
     }
     /**

package/dist/collection/shared/utils/focus.js

@@ -22,3 +22,34 @@ export const getDeepActiveElement = (root = document) => {
     const shadowRoot = activeElement && 'shadowRoot' in activeElement ? activeElement.shadowRoot : null;
     return shadowRoot?.activeElement ? getDeepActiveElement(shadowRoot) : activeElement;
 };
+/** Seletores CSS canônicos para elementos nativos e Web Components focáveis no GovBR-DS. */
+export const FOCUSABLE_SELECTORS = [
+    'a[href]:not([disabled])',
+    'button:not([disabled])',
+    'br-button:not([disabled]):not([tabindex="-1"])',
+    'input:not([disabled])',
+    'br-input:not([disabled]):not([tabindex="-1"])',
+    'select:not([disabled])',
+    'br-select:not([disabled]):not([tabindex="-1"])',
+    'textarea:not([disabled])',
+    'br-textarea:not([disabled]):not([tabindex="-1"])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+/**
+ * Filtra elementos que são visíveis no DOM (com dimensões maiores que zero e visibilidade CSS).
+ */
+export const filterVisibleElements = (elements) => {
+    return elements.filter((el) => el.offsetWidth > 0 && el.offsetHeight > 0 && getComputedStyle(el).visibility !== 'hidden');
+};
+/**
+ * Verifica se a navegação por Tab deve ser mantida dentro dos limites (trap) de uma superfície modal.
+ */
+export const shouldTrapFocus = (isTabForward, firstElement, lastElement, activeElement) => {
+    return (isTabForward && activeElement === lastElement) || (!isTabForward && activeElement === firstElement);
+};
+/**
+ * Move o foco em ciclo entre o primeiro e último elemento focável.
+ */
+export const wrapFocus = (isTabForward, firstElement, lastElement) => {
+    (isTabForward ? firstElement : lastElement).focus();
+};

package/dist/collection/shared/utils/getRandom.js

@@ -11,6 +11,7 @@
  * @param n Quantidade de itens aleatórios desejada.
  * @returns Novo array com os itens sorteados.
  * @throws {RangeError} Quando `n` é maior que o tamanho do array.
+ * @throws {Error} Quando o runtime não fornece Web Crypto.
  */
 export const getRandomFromArray = (arr, n) => {
     let length = arr.length;
@@ -19,9 +20,23 @@ export const getRandomFromArray = (arr, n) => {
     if (n > length)
         throw new RangeError('getRandom: more elements taken than available');
     while (n--) {
-        const x = Date.now() % length;
+        const x = randomIndex(length);
         result[n] = arr[x in taken ? taken[x] : x];
         taken[x] = --length in taken ? taken[length] : length;
     }
     return result;
 };
+function randomIndex(maxExclusive) {
+    const cryptoApi = globalThis.crypto;
+    if (!cryptoApi?.getRandomValues) {
+        throw new Error('A API Web Crypto é necessária para sortear itens.');
+    }
+    // Rejeita a faixa excedente para que o módulo não introduza viés estatístico.
+    const range = 2 ** 32;
+    const limit = range - (range % maxExclusive);
+    const value = new Uint32Array(1);
+    do {
+        cryptoApi.getRandomValues(value);
+    } while (value[0] >= limit);
+    return value[0] % maxExclusive;
+}

package/dist/collection/shared/utils/helpers.js

@@ -6,11 +6,10 @@
  * Utilitários Helpers com funções auxiliares para geração de IDs e formatação de bytes.
  * Mantemos um `default` export com a API compatível para não quebrar importações existentes.
  */
+import { formatBytes as formatBytesCanonical } from "./format-bytes";
+import { generateUniqueId as createUniqueId } from "./id";
 export function generateUniqueId(prefix) {
-    const time = Date.now().toString(36);
-    const rand = Math.random().toString(36).substring(2, 10);
-    const id = (time + rand).substring(0, 16);
-    return prefix ? `${prefix}-${id}` : id;
+    return createUniqueId(prefix);
 }
 /**
  * Formata um valor em bytes para uma representação humana (KB, MB, GB...).
@@ -19,13 +18,7 @@ export function generateUniqueId(prefix) {
  * @returns Valor formatado com unidade.
  */
 export function formatBytes(bytes, decimals = 2) {
-    if (bytes === 0)
-        return '0 Bytes';
-    const k = 1024;
-    const dm = decimals < 0 ? 0 : decimals;
-    const units = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
-    return `${Number.parseFloat((bytes / k ** i).toFixed(dm))} ${units[i]}`;
+    return formatBytesCanonical(bytes, decimals);
 }
 const Helpers = { generateUniqueId, formatBytes };
 export default Helpers;

package/dist/collection/shared/utils/id.js

@@ -5,12 +5,28 @@
 /**
  * Utilitário para geração de IDs únicos para Web Components.
  *
- * Utiliza um contador sequencial em memória combinado com um sufixo aleatório em base36
- * para oferecer alta performance O(1) e garantia de unicidade sem colisões.
- *
- * @returns String de ID único compatível com seletores CSS (ex.: "b0k9f2z").
+ * O Web Crypto fornece entropia sem depender de relógio ou de estado compartilhado
+ * entre instâncias. O prefixo `b` mantém o valor compatível com seletores CSS e com
+ * os IDs gerados pelas versões anteriores da biblioteca.
  */
-let idCounter = 0;
-export function generateUniqueId() {
-    return `b${(idCounter++).toString(36)}${Math.random().toString(36).slice(2, 7)}`;
+function createRandomToken() {
+    const cryptoApi = globalThis.crypto;
+    if (!cryptoApi) {
+        throw new Error('A API Web Crypto é necessária para gerar IDs de componentes.');
+    }
+    if (cryptoApi?.randomUUID) {
+        return cryptoApi.randomUUID().replace(/-/g, '').slice(0, 16);
+    }
+    if (cryptoApi?.getRandomValues) {
+        const values = cryptoApi.getRandomValues(new Uint32Array(3));
+        return Array.from(values)
+            .map((value) => value.toString(36))
+            .join('')
+            .slice(0, 16);
+    }
+    throw new Error('A API Web Crypto não expõe randomUUID nem getRandomValues.');
+}
+export function generateUniqueId(prefix) {
+    const id = `b${createRandomToken()}`;
+    return prefix ? `${prefix}-${id}` : id;
 }

package/dist/collection/shared/utils/index.js

@@ -24,13 +24,15 @@
  * - `isClient`          — Detecção de ambiente navegador
  * - `isDefined`         — Verificação de valores definidos
  * - `isNil`             — Verificação de valores nulos ou indefinidos
+ * - `motion`            — Preferência de movimento e comportamento de rolagem acessível
  * - `parts`             — Exposição confiável de CSS parts em custom elements filhos
  * - `props`             — Validação de propriedades de elementos customizados
  * - `scrollLock`        — Bloqueio/desbloqueio de scroll do body
  * - `setRafTimeout`     — Agendamento eficiente via RAF + setTimeout
  * - `slot`              — Leitura de conteúdo de slots em web components
  * - `swipe`             — Detecção de gestos de swipe
- * - `transition`        — Transições de entrada e saída com classes CSS
+ * - `transition`        — Transições de entrada e saída com classes CSS e fallback de movimento reduzido
+ * - `virtual-scroll`    — Cálculo da janela de itens de listas virtualizadas
  */
 export * from './breakpoint-observer';
 export * from './clamp';
@@ -48,7 +50,9 @@ export * from './interfaces';
 export * from './isClient';
 export * from './isDefined';
 export * from './isNil';
+export * from './motion';
 export * from './native-dialog';
+export * from './ownership';
 export * from './parts';
 export * from './props';
 export * from './raf-batcher';
@@ -58,3 +62,4 @@ export * from './slot';
 export * from './ssr-date';
 export * from './swipe';
 export * from './transition';
+export * from './virtual-scroll';

package/dist/collection/shared/utils/isEmpty.js

@@ -7,7 +7,6 @@
  *
  * Suporta Map, Set, Array, Record, null e undefined.
  */
-import { isDefined } from "./isDefined";
 import { isNil } from "./isNil";
 /**
  * Verifica se uma coleção está vazia.
@@ -22,9 +21,12 @@ export const isEmpty = (value) => {
         return true;
     }
     else if ('size' in value) {
-        return !isDefined(value.size);
+        return value.size === 0;
+    }
+    else if (Array.isArray(value)) {
+        return value.length === 0;
     }
     else {
-        return !isDefined(Object.values(value).length);
+        return Object.keys(value).length === 0;
     }
 };

package/dist/collection/shared/utils/motion.js

@@ -0,0 +1,25 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+const REDUCED_MOTION_MEDIA_QUERY = '(prefers-reduced-motion: reduce)';
+/**
+ * Verifica se a pessoa solicitou redução de movimento no sistema operacional ou navegador.
+ *
+ * Em SSR ou em navegadores sem `matchMedia`, assume o estado mais seguro.
+ *
+ * @returns `true` quando o movimento deve ser reduzido.
+ */
+export const prefersReducedMotion = () => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+        return true;
+    if (typeof document !== 'undefined' && document.documentElement.dataset.wbcReducedMotion === 'true')
+        return true;
+    return window.matchMedia(REDUCED_MOTION_MEDIA_QUERY).matches;
+};
+/**
+ * Define o comportamento de rolagem de acordo com a preferência de movimento.
+ *
+ * @returns `auto` com movimento reduzido e `smooth` nos demais casos.
+ */
+export const getScrollBehavior = () => (prefersReducedMotion() ? 'auto' : 'smooth');

package/dist/collection/shared/utils/ownership.js

@@ -0,0 +1,113 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Utilitários para componentes que coordenam elementos projetados.
+ *
+ * A árvore composta inclui hosts de Shadow DOM e slots, enquanto
+ * `parentElement` considera somente a árvore DOM local. A coordenação entre
+ * um componente pai e seus filhos precisa usar a primeira para não atravessar
+ * o owner errado quando há wrappers ou aliases legados.
+ */
+function getComposedParent(node) {
+    const assignedSlot = node.assignedSlot;
+    if (assignedSlot !== null && assignedSlot !== undefined)
+        return assignedSlot;
+    if (node.parentNode !== null)
+        return node.parentNode;
+    const root = node.getRootNode();
+    return root instanceof ShadowRoot ? root.host : null;
+}
+/** Retorna o owner composto mais próximo que corresponde ao seletor informado. */
+export function findComposedOwner(node, ownerSelector) {
+    let current = node;
+    while (current !== null) {
+        if (current instanceof Element && current.matches(ownerSelector))
+            return current;
+        current = getComposedParent(current);
+    }
+    return null;
+}
+/**
+ * Verifica se um nó é igual ou descendente de outro elemento,
+ * atravessando fronteiras de Shadow DOM aninhados.
+ */
+export function isComposedDescendant(parent, child) {
+    if (!child)
+        return false;
+    if (child === parent)
+        return true;
+    let node = child;
+    while (node !== null && node !== document) {
+        if (node === parent)
+            return true;
+        const root = node.getRootNode();
+        if (root instanceof ShadowRoot) {
+            node = root.host;
+        }
+        else {
+            node = node.parentNode;
+        }
+    }
+    return false;
+}
+/** Verifica se o elemento pertence diretamente ao owner composto informado. */
+export function isOwnedElement(element, owner, childSelector) {
+    return element.matches(childSelector) && findComposedOwner(element, owner.localName) === owner;
+}
+/**
+ * Coleta elementos atribuídos a um slot e seus descendentes de light DOM.
+ * O filtro de owner evita que um componente composto absorva filhos de uma
+ * instância composta aninhada.
+ */
+export function getOwnedAssignedElements(slot, owner, childSelector) {
+    // Achate slots de wrappers legados para preservar a projeção através de
+    // aliases; a coleta interrompe ao encontrar um owner composto aninhado.
+    const assigned = slot?.assignedElements({ flatten: true }) ?? [];
+    const roots = assigned.length > 0 ? assigned : Array.from(owner.children);
+    const candidates = [];
+    const collectCandidates = (node) => {
+        if (node.matches(childSelector))
+            candidates.push(node);
+        // Um componente composto aninhado é um novo limite de ownership. Não
+        // atravesse seus filhos de light DOM, pois eles pertencem ao grupo interno.
+        if (node !== owner && node.localName === owner.localName)
+            return;
+        for (const child of Array.from(node.children))
+            collectCandidates(child);
+    };
+    for (const root of roots)
+        collectCandidates(root);
+    return [...new Set(candidates)].filter((element) => isOwnedElement(element, owner, childSelector));
+}
+/** Retorna somente os filhos DOM diretos que pertencem ao owner. */
+export function getOwnedDirectChildren(owner, childSelector) {
+    return Array.from(owner.children).filter((element) => isOwnedElement(element, owner, childSelector));
+}
+/**
+ * Agenda uma única reconciliação por microtask. O callback pode ser chamado
+ * várias vezes durante uma transição de estado sem repetir a varredura.
+ */
+export function createMicrotaskReconciler(callback) {
+    let scheduled = false;
+    let generation = 0;
+    return {
+        schedule() {
+            if (scheduled)
+                return;
+            scheduled = true;
+            const currentGeneration = ++generation;
+            queueMicrotask(() => {
+                if (currentGeneration !== generation)
+                    return;
+                scheduled = false;
+                callback();
+            });
+        },
+        cancel() {
+            generation++;
+            scheduled = false;
+        },
+    };
+}

package/dist/collection/shared/utils/prop-warning.js

@@ -2,6 +2,53 @@
  * Construído por SERPRO
  * © https://serpro.gov.br/ - MIT License.
  */
+const warningStates = new WeakMap();
+const MAX_VALUE_LENGTH = 120;
+function formatValue(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string') {
+        const formatted = JSON.stringify(value);
+        return formatted.length > MAX_VALUE_LENGTH ? `${formatted.slice(0, MAX_VALUE_LENGTH - 4)}..."` : formatted;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return `[Array(${value.length})]`;
+    if (value instanceof Date)
+        return '[Date]';
+    if (typeof value === 'function')
+        return '[Function]';
+    return '[Object]';
+}
+function getWarningState(host) {
+    let state = warningStates.get(host);
+    if (!state) {
+        state = new Map();
+        warningStates.set(host, state);
+    }
+    return state;
+}
+/** Remove o estado de warning de uma prop quando ela volta a ser válida. */
+export function clearInvalidPropWarning(host, propName) {
+    warningStates.get(host)?.delete(propName);
+}
+/**
+ * Emite um aviso padronizado para uma prop inválida, uma vez por valor inválido.
+ * O estado é associado à instância do componente para evitar spam de renderização.
+ */
+export function reportInvalidPropValue(host, propName, receivedValue, expected, resolution) {
+    const state = getWarningState(host);
+    const received = formatValue(receivedValue);
+    if (state.get(propName) === received)
+        return;
+    state.set(propName, received);
+    const componentTag = host.localName || host.tagName.toLowerCase();
+    console.warn(`[${componentTag}] Prop "${propName}" recebeu ${received}. ${expected} ${resolution}`);
+}
 export function warnInvalidPropValue(componentTag, propName, receivedValue, defaultValue) {
     console.warn(`[${componentTag}]: valor invalido para "${propName}": "${String(receivedValue)}". Usando valor padrao "${defaultValue}".`);
 }