@govbr-ds/webcomponents 2.1.0 → 2.1.1

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

@@ -0,0 +1,75 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Utilitários para definição e recuperação do caminho base de assets dos componentes.
+ *
+ * Permite customizar o path de SVGs e outros recursos estáticos em runtime.
+ */
+import { isClient } from "./isClient";
+/**
+ * Implementação inspirada nas utilidades de base path do Shoelace.
+ * Referência: https://github.com/shoelace-style/shoelace/blob/next/src/utilities/base-path.ts
+ */
+let wbcBasePath;
+const DATA_WBC_ATTRIBUTE = 'data-wbc';
+const DEFAULT_SVG_PATH = 'svg';
+/**
+ * Define o caminho base dos assets utilizados pelos componentes.
+ *
+ * @param path Caminho base a ser utilizado.
+ */
+export const setBasePath = (path) => {
+    wbcBasePath = path;
+};
+/**
+ * Recupera o caminho base dos assets, com fallback automático quando necessário.
+ *
+ * Ordem de resolução:
+ * 1. valor definido por `setBasePath`
+ * 2. script com atributo `data-wbc`
+ * 3. caminho derivado de um script que contenha `wbc` no `src` + `/svg`
+ *
+ * @param subpath Subcaminho opcional para concatenar ao base path.
+ * @returns Caminho base normalizado (sem `/` final) com subpath opcional.
+ */
+export const getBasePath = (subpath = '') => {
+    if (!wbcBasePath) {
+        const configScript = findConfigScript();
+        const configPath = configScript?.getAttribute(DATA_WBC_ATTRIBUTE);
+        const fallbackScript = findFallbackScript();
+        const fallbackPath = fallbackScript ? `${getScriptPath(fallbackScript)}/${DEFAULT_SVG_PATH}` : '';
+        setBasePath(configPath || fallbackPath);
+    }
+    const formattedSubpath = subpath ? `/${subpath.replace(/^\//, '')}` : '';
+    return wbcBasePath.replace(/\/$/, '') + formattedSubpath;
+};
+/**
+ * Busca o script de configuração por `data-wbc`.
+ */
+const findConfigScript = () => {
+    if (!isClient())
+        return null;
+    return document.querySelector(`script[${DATA_WBC_ATTRIBUTE}]`);
+};
+/**
+ * Busca um script de fallback cujo `src` contenha `wbc`.
+ */
+const findFallbackScript = () => {
+    if (!isClient())
+        return null;
+    return document.querySelector('script[src*="wbc"]');
+};
+/**
+ * Extrai o diretório base do `src` de um script.
+ *
+ * @param script Script alvo.
+ * @returns Diretório do script sem o nome do arquivo.
+ */
+const getScriptPath = (script) => {
+    if (!isClient())
+        return '';
+    const src = script.getAttribute('src');
+    return src ? src.substring(0, src.lastIndexOf('/')) : '';
+};

package/dist/collection/shared/utils/breakpoint-observer.js

@@ -0,0 +1,139 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Utilitários para detecção e manipulação de breakpoints responsivos.
+ *
+ * As media queries são compartilhadas por janela para que várias instâncias de
+ * headers e subcomponentes não instalem o mesmo conjunto de listeners.
+ */
+export const BREAKPOINTS = {
+    X_SMALL: 'x-small',
+    SMALL: 'small',
+    MEDIUM: 'medium',
+    LARGE: 'large',
+    X_LARGE: 'x-large',
+};
+const BREAKPOINT_SETTINGS = {
+    [BREAKPOINTS.X_SMALL]: { name: BREAKPOINTS.X_SMALL, query: '(max-width: 575px)', minWidth: 0, maxWidth: 575 },
+    [BREAKPOINTS.SMALL]: {
+        name: BREAKPOINTS.SMALL,
+        query: '(min-width: 576px) and (max-width: 991px)',
+        minWidth: 576,
+        maxWidth: 991,
+    },
+    [BREAKPOINTS.MEDIUM]: {
+        name: BREAKPOINTS.MEDIUM,
+        query: '(min-width: 992px) and (max-width: 1279px)',
+        minWidth: 992,
+        maxWidth: 1279,
+    },
+    [BREAKPOINTS.LARGE]: {
+        name: BREAKPOINTS.LARGE,
+        query: '(min-width: 1280px) and (max-width: 1599px)',
+        minWidth: 1280,
+        maxWidth: 1599,
+    },
+    [BREAKPOINTS.X_LARGE]: { name: BREAKPOINTS.X_LARGE, query: '(min-width: 1600px)', minWidth: 1600 },
+};
+const sharedStates = new WeakMap();
+function createSharedState(ownerWindow) {
+    const state = {};
+    state.currentBreakpoint = null;
+    state.mediaQueries = [];
+    state.subscriptions = new Set();
+    state.handleChange = () => {
+        for (const { config, mql } of state.mediaQueries) {
+            if (mql.matches && state.currentBreakpoint !== config.name) {
+                state.currentBreakpoint = config.name;
+                for (const subscription of [...state.subscriptions])
+                    subscription.callback(config.name);
+                break;
+            }
+        }
+    };
+    for (const breakpointName of Object.values(BREAKPOINTS)) {
+        const config = BREAKPOINT_SETTINGS[breakpointName];
+        const mql = ownerWindow.matchMedia(config.query);
+        state.mediaQueries.push({ config, mql });
+        if (mql.matches)
+            state.currentBreakpoint = config.name;
+        mql.addEventListener('change', state.handleChange);
+    }
+    sharedStates.set(ownerWindow, state);
+    return state;
+}
+function releaseSharedState(ownerWindow, state) {
+    if (state.subscriptions.size > 0)
+        return;
+    for (const { mql } of state.mediaQueries)
+        mql.removeEventListener('change', state.handleChange);
+    sharedStates.delete(ownerWindow);
+}
+export class BreakpointObserver {
+    constructor() {
+        this.ownerWindow = typeof window === 'undefined' ? null : window;
+        this.shared = this.ownerWindow === null ? null : (sharedStates.get(this.ownerWindow) ?? createSharedState(this.ownerWindow));
+        this.subscriptions = new Set();
+    }
+    getCurrentBreakpoint() {
+        return this.shared?.currentBreakpoint ?? null;
+    }
+    getBreakpointSettings(breakpoint) {
+        return BREAKPOINT_SETTINGS[breakpoint];
+    }
+    getBreakpointQuery(breakpoint) {
+        return BREAKPOINT_SETTINGS[breakpoint]?.query;
+    }
+    getAllBreakpoints() {
+        return Object.values(BREAKPOINTS);
+    }
+    static getBreakpoints(type, breakpoint) {
+        const breakpointOrder = Object.values(BREAKPOINTS);
+        const index = breakpointOrder.indexOf(breakpoint);
+        if (index === -1)
+            return [];
+        switch (type) {
+            case 'above':
+                return breakpointOrder.slice(index + 1);
+            case 'below':
+                return breakpointOrder.slice(0, index);
+            case 'from':
+                return breakpointOrder.slice(index);
+            case 'until':
+                return breakpointOrder.slice(0, index + 1);
+            case 'only':
+                return [breakpoint];
+        }
+    }
+    subscribe(callback) {
+        if (this.shared === null ||
+            (this.subscriptions.size > 0 && [...this.subscriptions].some((item) => item.callback === callback))) {
+            return;
+        }
+        const subscription = { owner: this, callback };
+        this.subscriptions.add(subscription);
+        this.shared.subscriptions.add(subscription);
+        const current = this.shared.currentBreakpoint;
+        if (current !== null)
+            callback(current);
+    }
+    unsubscribe(callback) {
+        for (const subscription of [...this.subscriptions]) {
+            if (subscription.callback !== callback)
+                continue;
+            this.subscriptions.delete(subscription);
+            this.shared?.subscriptions.delete(subscription);
+        }
+        if (this.shared !== null && this.ownerWindow !== null)
+            releaseSharedState(this.ownerWindow, this.shared);
+    }
+    destroy() {
+        for (const subscription of this.subscriptions)
+            this.shared?.subscriptions.delete(subscription);
+        this.subscriptions.clear();
+        if (this.shared !== null && this.ownerWindow !== null)
+            releaseSharedState(this.ownerWindow, this.shared);
+    }
+}

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

@@ -0,0 +1,21 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Utilitário para limitar valores numéricos a um intervalo.
+ *
+ * Restringe um número ao intervalo `[min, max]`.
+ *
+ * @param value Valor de entrada.
+ * @param min Limite inferior.
+ * @param max Limite superior.
+ * @returns Valor limitado ao intervalo informado.
+ */
+export const clamp = (value, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) => {
+    return Math.min(Math.max(min, value), max);
+};
+export const clampNumber = (value, min, max, fallback = min) => {
+    const numeric = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(numeric) ? clamp(numeric, min, max) : fallback;
+};

package/dist/collection/shared/utils/css-variables.js

@@ -0,0 +1,12 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Mapa centralizado de variáveis CSS compartilhadas entre componentes.
+ */
+export const CssVariables = {
+    ALIGN: {
+        HORIZONTAL: '--horizontal-align',
+    },
+};

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

@@ -0,0 +1,37 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Utilitários para manipulação de custom properties CSS (variáveis CSS).
+ *
+ * Permite obter referências e valores computados de tokens de cor e variáveis CSS.
+ */
+import { isClient } from "./isClient";
+const CSS_VALUE_PREFIX = '--bq-';
+/**
+ * Retorna a referência CSS (`var(--token)`) de um token de cor, quando o token existe.
+ *
+ * @param colorName Nome lógico do token (ex.: `ui--primary`).
+ * @returns String no formato `var(--bq-...)` ou `undefined` quando inexistente.
+ */
+export const getColorCSSVariable = (colorName) => {
+    if (!isClient())
+        return undefined;
+    const token = `${CSS_VALUE_PREFIX}${colorName}`;
+    const value = getComputedStyle(document.documentElement).getPropertyValue(token);
+    if (!value)
+        return undefined;
+    return `var(${token})`;
+};
+/**
+ * Retorna o valor computado de uma custom property CSS em um elemento.
+ *
+ * @param variable Nome da variável sem prefixo `--`.
+ * @param component Elemento no qual o valor será resolvido.
+ * @returns Valor computado sem espaços extras.
+ */
+export const getCSSVariableValue = (variable, component) => {
+    const styles = getComputedStyle(component);
+    return String(styles.getPropertyValue(`--${variable}`)).trim();
+};

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

@@ -0,0 +1,405 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+/**
+ * Utilitários de datas para os componentes GovBR-DS.
+ *
+ * Funções puramente nativas (sem dependências externas) para:
+ * - Validação de strings ISO
+ * - Parsing de entradas de data em múltiplos formatos e localidades
+ * - Formatação de datas para exibição usando `Intl.DateTimeFormat`
+ * - Extração e clamp de valores ISO dentro de intervalos
+ *
+ * Todos os formatos ISO utilizados seguem o padrão `YYYY-MM-DD`.
+ */
+// ─── Constantes e cache ───────────────────────────────────────────────────────
+/** Regex que valida o formato ISO `YYYY-MM-DD`. */
+const ISO_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Cache de `Intl.DateTimeFormat` para evitar recriação a cada chamada.
+ * Limitado a 50 entradas; quando excedido, remove a entrada mais antiga (FIFO).
+ */
+const formatterCache = new Map();
+const FORMATTER_CACHE_MAX = 50;
+// ─── Funções privadas ─────────────────────────────────────────────────────────
+/**
+ * Verifica se a data representada pelas partes `year`, `month` e `day` existe
+ * no calendário gregoriano.
+ *
+ * @param year Ano (inteiro positivo).
+ * @param month Mês de 1 a 12.
+ * @param day Dia de 1 a 31.
+ * @returns `true` quando a data é válida no calendário.
+ */
+function isCalendarDateValid(year, month, day) {
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return false;
+    // O construtor de Date normaliza datas inválidas (ex.: 30/02 vira 01/03).
+    // Verificar se o dia/mês não mudou garante que a data existe no calendário.
+    const d = new Date(year, month - 1, day);
+    return d.getFullYear() === year && d.getMonth() === month - 1 && d.getDate() === day;
+}
+/**
+ * Tenta obter os nomes de meses completos e abreviados para uma localidade,
+ * retornando um mapa de nome (normalizado em minúsculo) → índice de mês (1–12).
+ *
+ * @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.
+ */
+function getMonthNameMap(locale) {
+    const map = new Map();
+    const date = new Date(2000, 0, 15);
+    for (let i = 0; i < 12; i++) {
+        date.setMonth(i);
+        const fullName = new Intl.DateTimeFormat(locale, { month: 'long' }).format(date).toLowerCase();
+        const shortName = new Intl.DateTimeFormat(locale, { month: 'short' }).format(date).toLowerCase().replace(/\.$/, '');
+        map.set(fullName, i + 1);
+        if (!map.has(shortName))
+            map.set(shortName, i + 1);
+    }
+    // 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();
+            if (!map.has(fullEn))
+                map.set(fullEn, i + 1);
+            if (!map.has(shortEn))
+                map.set(shortEn, i + 1);
+        }
+    }
+    return map;
+}
+/**
+ * Tenta interpretar uma string com nome de mês (DD MMM YYYY ou MMM DD YYYY).
+ *
+ * @param input String de data a ser analisada.
+ * @param locale Localidade para obter nomes de meses.
+ * @returns Data interpretada ou `null`.
+ */
+function parseTextDate(input, locale) {
+    const monthNames = getMonthNameMap(locale);
+    const normalized = input.toLowerCase().trim();
+    // Formato: DD MMM YYYY ou DD MMMM YYYY (ex.: "30 May 2024", "30 janeiro 2024")
+    const dmyMatch = normalized.match(/^(\d{1,2})\s+([a-záàâãäåæçèéêëìíîïðñòóôõöùúûüý\w]+)(?:,?\s*)(\d{4})$/);
+    if (dmyMatch) {
+        const day = parseInt(dmyMatch[1], 10);
+        const monthName = dmyMatch[2].replace(/\.$/, '');
+        const year = parseInt(dmyMatch[3], 10);
+        const month = monthNames.get(monthName);
+        if (month && isCalendarDateValid(year, month, day)) {
+            return new Date(year, month - 1, day);
+        }
+    }
+    // Formato: MMM DD, YYYY ou MMM DD YYYY (ex.: "May 30, 2024", "January 1 1970")
+    const mdyMatch = normalized.match(/^([a-záàâãäåæçèéêëìíîïðñòóôõöùúûüý\w]+)\s+(\d{1,2}),?\s*(\d{4})$/);
+    if (mdyMatch) {
+        const monthName = mdyMatch[1].replace(/\.$/, '');
+        const day = parseInt(mdyMatch[2], 10);
+        const year = parseInt(mdyMatch[3], 10);
+        const month = monthNames.get(monthName);
+        if (month && isCalendarDateValid(year, month, day)) {
+            return new Date(year, month - 1, day);
+        }
+    }
+    return null;
+}
+/**
+ * Tenta interpretar uma string numérica de data nos formatos
+ * `DD/MM/YYYY`, `MM/DD/YYYY`, `DD-MM-YYYY`, `DD.MM.YYYY`, etc.
+ *
+ * Heurística de localidade:
+ * - Localidades `en-US` / `en` usam `MM/DD/YYYY` por padrão.
+ * - Demais localidades assumem `DD/MM/YYYY`.
+ * - Quando o primeiro número é > 12, não pode ser mês → usa como dia.
+ * - Quando o segundo número é > 12, não pode ser dia no formato MDY → usa como dia.
+ *
+ * @param input String de data a ser analisada.
+ * @param locale Localidade usada como dica de formato.
+ * @returns Data interpretada ou `null`.
+ */
+function parseNumericDate(input, locale) {
+    // Extrai os três componentes numéricos separados por `/`, `-`, `.` ou espaço.
+    const parts = input.trim().split(/[/\-.\s]+/);
+    if (parts.length !== 3)
+        return null;
+    const [a, b, c] = parts.map((p) => parseInt(p, 10));
+    // O último componente deve ser o ano (4 dígitos).
+    if (c < 100)
+        return null;
+    // Detecta formato ISO-like numérico: primeiro número ≥ 1000 → YYYY-MM-DD
+    if (a >= 1000) {
+        // Formato YYYY-MM-DD numérico (já coberto pelo parseISO, mas como fallback)
+        const [year, month, day] = [a, b, c];
+        if (isCalendarDateValid(year, month, day))
+            return new Date(year, month - 1, day);
+        return null;
+    }
+    const isUSLocale = locale === 'en' || locale === 'en-US';
+    let day;
+    let month;
+    if (a > 12) {
+        // `a` não pode ser mês → DD/MM/YYYY
+        day = a;
+        month = b;
+    }
+    else if (b > 12) {
+        // `b` não pode ser dia → MM/DD/YYYY
+        month = a;
+        day = b;
+    }
+    else {
+        // Ambíguo: usa a localidade como dica
+        if (isUSLocale) {
+            month = a;
+            day = b;
+        }
+        else {
+            day = a;
+            month = b;
+        }
+    }
+    const year = c;
+    if (isCalendarDateValid(year, month, day))
+        return new Date(year, month - 1, day);
+    // Tenta a interpretação inversa quando a primeira falhou
+    const [dayAlt, monthAlt] = [b, a];
+    if (isCalendarDateValid(year, monthAlt, dayAlt))
+        return new Date(year, monthAlt - 1, dayAlt);
+    return null;
+}
+/**
+ * Obtém um `Intl.DateTimeFormat` do cache (ou cria e armazena um novo).
+ *
+ * Quando o cache excede `FORMATTER_CACHE_MAX` entradas, a entrada mais antiga
+ * é removida para evitar crescimento ilimitado de memória.
+ *
+ * @param locale Localidade BCP 47.
+ * @param options Opções de formatação.
+ * @returns Instância de `Intl.DateTimeFormat`.
+ */
+function getDateFormatter(locale, options) {
+    const key = `${locale}:${JSON.stringify(options)}`;
+    if (formatterCache.has(key))
+        return formatterCache.get(key);
+    if (formatterCache.size >= FORMATTER_CACHE_MAX) {
+        // Remove a entrada mais antiga (primeira inserida no Map).
+        const oldestKey = formatterCache.keys().next().value;
+        formatterCache.delete(oldestKey);
+    }
+    const formatter = new Intl.DateTimeFormat(locale, options);
+    formatterCache.set(key, formatter);
+    return formatter;
+}
+// ─── API pública ──────────────────────────────────────────────────────────────
+/**
+ * Verifica se uma string está no formato ISO `YYYY-MM-DD` e representa
+ * uma data válida no calendário gregoriano.
+ *
+ * @param dateStr String a ser validada.
+ * @returns `true` quando a string é uma data ISO válida.
+ *
+ * @example
+ * isValidISODate('2024-05-30') // true
+ * isValidISODate('2024-02-30') // false (30/fev não existe)
+ * isValidISODate('30/05/2024') // false (formato incorreto)
+ */
+export function isValidISODate(dateStr) {
+    if (!ISO_REGEX.test(dateStr))
+        return false;
+    const [year, month, day] = dateStr.split('-').map(Number);
+    return isCalendarDateValid(year, month, day);
+}
+/**
+ * Interpreta uma string de data em múltiplos formatos e retorna um objeto `Date`.
+ *
+ * Formatos suportados (em ordem de tentativa):
+ * 1. ISO `YYYY-MM-DD`
+ * 2. Texto com nome de mês: `DD MMM YYYY`, `MMM DD YYYY`, `MMM DD, YYYY`
+ * 3. Numérico: `DD/MM/YYYY`, `MM/DD/YYYY`, `DD-MM-YYYY`, `DD.MM.YYYY`, etc.
+ *
+ * A localidade é utilizada como dica para desambiguar formatos numéricos
+ * (`en-US` presume `MM/DD`; demais presumem `DD/MM`) e para identificar
+ * nomes de meses em outros idiomas.
+ *
+ * @param input String de data de entrada.
+ * @param locale Código BCP 47 de localidade (padrão `'pt-BR'`).
+ * @returns Objeto `Date` sem componente de horário, ou `null` quando a entrada
+ *          é inválida, vazia ou não reconhecida.
+ *
+ * @example
+ * parseDateInput('2024-05-30')          // new Date(2024, 4, 30)
+ * parseDateInput('30 May 2024', 'en-GB') // new Date(2024, 4, 30)
+ * parseDateInput('05/30/2024', 'en-US') // new Date(2024, 4, 30)
+ * parseDateInput('')                     // null
+ */
+export function parseDateInput(input, locale = 'pt-BR') {
+    if (!input?.trim())
+        return null;
+    const trimmed = input.trim();
+    // 1. Formato ISO YYYY-MM-DD
+    if (ISO_REGEX.test(trimmed)) {
+        const [year, month, day] = trimmed.split('-').map(Number);
+        if (!isCalendarDateValid(year, month, day))
+            return null;
+        return new Date(year, month - 1, day);
+    }
+    // 2. Formato com nome de mês (texto)
+    // Verifica se há pelo menos uma letra para identificar como formato textual.
+    if (/[a-záàâãäåæçèéêëìíîïðñòóôõöùúûüý]/i.test(trimmed)) {
+        return parseTextDate(trimmed, locale);
+    }
+    // 3. Formato numérico
+    if (/\d/.test(trimmed)) {
+        return parseNumericDate(trimmed, locale);
+    }
+    return null;
+}
+/**
+ * Converte um objeto `Date` para uma string no formato ISO `YYYY-MM-DD`.
+ *
+ * Utiliza os componentes locais da data (sem conversão para UTC), garantindo
+ * consistência com datas criadas via `new Date(year, month, day)`.
+ *
+ * @param date Data a ser convertida.
+ * @returns String no formato `YYYY-MM-DD`.
+ *
+ * @example
+ * toISODateString(new Date(2024, 4, 30)) // '2024-05-30'
+ * toISODateString(new Date(2024, 0, 5))  // '2024-01-05'
+ */
+export function toISODateString(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Retorna a data de hoje como string ISO `YYYY-MM-DD`.
+ *
+ * @returns Data atual no formato `YYYY-MM-DD`.
+ *
+ * @example
+ * getTodayISO() // ex.: '2024-05-30'
+ */
+export function getTodayISO() {
+    return toISODateString(new Date());
+}
+/**
+ * Formata um valor de data (ou intervalo/lista de datas) para exibição,
+ * usando `Intl.DateTimeFormat` para localização.
+ *
+ * Modos suportados:
+ * - `'single'`: formata uma única data ISO.
+ * - `'multi'`: formata múltiplas datas ISO separadas por espaço.
+ * - `'range'`: formata um intervalo `YYYY-MM-DD/YYYY-MM-DD`.
+ *
+ * Retorna `undefined` quando o valor está vazio ou contém datas inválidas.
+ *
+ * @param value String de valor de data conforme o modo.
+ * @param mode Modo de formatação (`'single'`, `'multi'` ou `'range'`).
+ * @param locale Código BCP 47 de localidade.
+ * @param options Opções de formatação para `Intl.DateTimeFormat`.
+ * @returns String formatada ou `undefined`.
+ *
+ * @example
+ * formatDisplayValue('2024-05-30', 'single', 'en-US', { month: 'long', day: 'numeric', year: 'numeric' })
+ * // 'May 30, 2024'
+ *
+ * formatDisplayValue('2024-05-30 2024-06-15', 'multi', 'en-US', { month: 'long', day: 'numeric', year: 'numeric' })
+ * // 'May 30, 2024, June 15, 2024'
+ *
+ * formatDisplayValue('2024-05-01/2024-05-31', 'range', 'en-US', { month: 'long', day: 'numeric', year: 'numeric' })
+ * // 'May 1 – May 31, 2024' (formato pode variar por localidade)
+ */
+export function formatDisplayValue(value, mode, locale, options) {
+    if (!value?.trim())
+        return undefined;
+    const formatter = getDateFormatter(locale, options);
+    if (mode === 'single') {
+        if (!isValidISODate(value.trim()))
+            return undefined;
+        const [year, month, day] = value.trim().split('-').map(Number);
+        return formatter.format(new Date(year, month - 1, day));
+    }
+    if (mode === 'multi') {
+        const parts = value.trim().split(/\s+/);
+        const formatted = [];
+        for (const part of parts) {
+            if (!isValidISODate(part))
+                return undefined;
+            const [year, month, day] = part.split('-').map(Number);
+            formatted.push(formatter.format(new Date(year, month - 1, day)));
+        }
+        return formatted.join(', ');
+    }
+    if (mode === 'range') {
+        const [startStr, endStr] = value.trim().split('/');
+        if (!isValidISODate(startStr) || !isValidISODate(endStr))
+            return undefined;
+        const [sy, sm, sd] = startStr.split('-').map(Number);
+        const [ey, em, ed] = endStr.split('-').map(Number);
+        const start = new Date(sy, sm - 1, sd);
+        const end = new Date(ey, em - 1, ed);
+        return formatRangeWithFormatter(formatter, start, end);
+    }
+    return undefined;
+}
+/**
+ * Extrai a primeira data ISO `YYYY-MM-DD` encontrada em uma string de valor.
+ *
+ * Funciona com strings de data única, intervalos (`YYYY-MM-DD/YYYY-MM-DD`)
+ * e listas de datas separadas por espaço.
+ *
+ * @param value String de valor de data.
+ * @returns Primeira data ISO encontrada, ou `undefined` quando não há nenhuma.
+ *
+ * @example
+ * extractFocusedDate('2024-05-30')              // '2024-05-30'
+ * extractFocusedDate('2024-05-01/2024-05-31')   // '2024-05-01'
+ * extractFocusedDate('2024-05-30 2024-06-15')   // '2024-05-30'
+ * extractFocusedDate('')                         // undefined
+ */
+export function extractFocusedDate(value) {
+    if (!value?.trim())
+        return undefined;
+    const match = value.match(/\d{4}-\d{2}-\d{2}/);
+    return match ? match[0] : undefined;
+}
+/**
+ * Restringe uma data ISO ao intervalo `[min, max]` (string comparison ISO).
+ *
+ * A comparação utiliza a ordenação lexicográfica das strings ISO, que coincide
+ * com a ordem cronológica para o formato `YYYY-MM-DD`.
+ *
+ * @param date Data ISO a ser limitada.
+ * @param min Data mínima ISO (opcional).
+ * @param max Data máxima ISO (opcional).
+ * @returns Data ISO resultante (dentro do intervalo ou a própria data quando
+ *          nenhum limite foi informado).
+ *
+ * @example
+ * clampDateToRange('2024-01-01', '2024-03-01')               // '2024-03-01'
+ * clampDateToRange('2024-12-31', undefined, '2024-06-30')    // '2024-06-30'
+ * clampDateToRange('2024-05-15', '2024-01-01', '2024-12-31') // '2024-05-15'
+ */
+export function clampDateToRange(date, min, max) {
+    let result = date;
+    if (min && result < min)
+        result = min;
+    if (max && result > max)
+        result = max;
+    return result;
+}
+// Helper para formatar intervalo usando Intl.DateTimeFormat quando disponível
+function formatRangeWithFormatter(formatter, start, end) {
+    const anyFormatter = formatter;
+    if (typeof anyFormatter.formatRange === 'function') {
+        return anyFormatter.formatRange(start, end);
+    }
+    return `${formatter.format(start)} – ${formatter.format(end)}`;
+}