beez-ui 0.4.0

package/dist/components/filter-query-grammar.js

@@ -0,0 +1,830 @@
+/**
+ * Gramática pura (sin React) para una barra de filtro estilo GitHub Issues.
+ *
+ * La barra acepta una query de texto con tokens `clave:valor` más texto libre.
+ * Este módulo tokeniza la query, la parsea contra una configuración de
+ * qualifiers y la traduce a los tres canales de filtrado que ya consume la
+ * tabla: búsqueda fuzzy por descripción, exclusiones de descripción y filtros
+ * avanzados por columna (`DataTableColumnFilterValue`).
+ */
+const DIACRITICS_PATTERN = /[̀-ͯ]/g;
+const YEAR_MONTH_SLUG_PATTERN = /^(\d{4})-(0[1-9]|1[0-2])$/;
+const RANGE_SEPARATOR = "..";
+/** Slug de valor para los modos de presencia/rango mes-año sin cota. */
+export const YEAR_MONTH_NO_VALUE_SLUG = "sin-fechas";
+export const YEAR_MONTH_HAS_VALUE_SLUG = "con-fechas";
+export const PRESENCE_TRUE_SLUG = "si";
+export const PRESENCE_FALSE_SLUG = "no";
+/**
+ * GitHub-style meta-keys to filter by presence/absence of ANY field:
+ * `tiene:<field>` (the field has a value) and `no:<field>` (the field is empty).
+ * The token value is the key of the target qualifier (e.g. `tiene:enviados`,
+ * `no:carpeta`). They unify presence across every kind into a single syntax,
+ * instead of a `<field>:si/no` per qualifier.
+ */
+export const PRESENCE_HAS_META_KEY = "tiene";
+export const PRESENCE_NO_META_KEY = "no";
+/** Identificador de "sin carpeta asignada" en un qualifier de carpeta. */
+export const UNASSIGNED_FOLDER_FILTER_VALUE = "__unassigned__";
+/** Normaliza una clave o slug: sin acentos, minúsculas, recortado. */
+export function normalizeFilterSlug(value) {
+    return value
+        .normalize("NFD")
+        .replace(DIACRITICS_PATTERN, "")
+        .toLocaleLowerCase()
+        .trim();
+}
+function stripSurroundingQuotes(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' || first === "'") && first === last) {
+            return value.slice(1, -1);
+        }
+    }
+    // Comilla de apertura sin cierre (token a medio tipear).
+    if (value.startsWith('"') || value.startsWith("'")) {
+        return value.slice(1);
+    }
+    return value;
+}
+/**
+ * Envuelve en comillas un valor que, sin comillas, se re-tokenizaría distinto:
+ * espacios, un `:` (se interpretaría como `clave:valor`) o un `-` inicial (se
+ * interpretaría como exclusión). Mantiene la query como fuente de verdad sin
+ * pérdida entre la barra unificada y los controles clásicos.
+ */
+function quoteTokenIfNeeded(value) {
+    return /[\s:]/.test(value) || value.startsWith("-")
+        ? `"${value}"`
+        : value;
+}
+/**
+ * Serializa el texto libre de descripción citando, palabra por palabra, los
+ * segmentos que se parsearían como un token (por ejemplo `total:100`), de modo
+ * que un filtro de descripción no se transforme en un filtro avanzado al
+ * re-parsear la query.
+ */
+function serializeDescriptionFilter(descriptionFilter) {
+    return descriptionFilter
+        .split(/\s+/)
+        .filter((word) => word.length > 0)
+        .map(quoteTokenIfNeeded)
+        .join(" ");
+}
+/**
+ * Divide la query en tokens respetando comillas (`"..."` / `'...'` agrupan
+ * espacios). Conserva los índices de cada token para que el autocompletado
+ * pueda ubicar el token bajo el caret.
+ */
+export function tokenizeFilterQuery(query) {
+    const tokens = [];
+    let index = 0;
+    const { length } = query;
+    while (index < length) {
+        if (/\s/.test(query[index])) {
+            index += 1;
+            continue;
+        }
+        const startIndex = index;
+        let quoteChar = null;
+        while (index < length) {
+            const character = query[index];
+            if (quoteChar) {
+                if (character === quoteChar) {
+                    quoteChar = null;
+                }
+                index += 1;
+                continue;
+            }
+            if (character === '"' || character === "'") {
+                quoteChar = character;
+                index += 1;
+                continue;
+            }
+            if (/\s/.test(character)) {
+                break;
+            }
+            index += 1;
+        }
+        const raw = query.slice(startIndex, index);
+        tokens.push(buildToken(raw, startIndex, index));
+    }
+    return tokens;
+}
+function findKeyColonIndex(text) {
+    for (let position = 0; position < text.length; position += 1) {
+        const character = text[position];
+        if (character === '"' || character === "'") {
+            // Una comilla antes del `:` significa que no hay clave (es texto libre).
+            return -1;
+        }
+        if (character === ":") {
+            return position;
+        }
+    }
+    return -1;
+}
+function buildToken(raw, startIndex, endIndex) {
+    // A leading `-` marks exclusion, even when it is the only character: this way,
+    // when starting an exclusion from the bar (`-`), the token is already negated
+    // and autocompletion can offer the fields to exclude. A lone `-` is ignored
+    // when parsing (empty value) and filters nothing.
+    const negated = raw.startsWith("-");
+    const remainder = negated ? raw.slice(1) : raw;
+    const colonIndex = findKeyColonIndex(remainder);
+    if (colonIndex === -1) {
+        return {
+            endIndex,
+            hasColon: false,
+            negated,
+            raw,
+            rawKey: null,
+            startIndex,
+            value: stripSurroundingQuotes(remainder),
+        };
+    }
+    return {
+        endIndex,
+        hasColon: true,
+        negated,
+        raw,
+        rawKey: remainder.slice(0, colonIndex),
+        startIndex,
+        value: stripSurroundingQuotes(remainder.slice(colonIndex + 1)),
+    };
+}
+function buildQualifierLookup(configs) {
+    const lookup = new Map();
+    for (const config of configs) {
+        if (config.kind === "text" || !config.key) {
+            continue;
+        }
+        lookup.set(normalizeFilterSlug(config.key), config);
+        for (const alias of config.aliases ?? []) {
+            lookup.set(normalizeFilterSlug(alias), config);
+        }
+    }
+    return lookup;
+}
+function parseNumber(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return null;
+    }
+    const parsed = Number(normalized);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * Parsea el valor de un qualifier numérico. Acepta comparadores (`>`, `>=`,
+ * `<`, `<=`, `=`), igualdad implícita (`N`) y rangos (`A..B`, `A..`, `..B`).
+ * `>` y `>=` son ambos inclusivos para preservar la semántica del matcher
+ * existente (`value < min → false`); `<` y `<=` mapean a `max`.
+ */
+function parseNumberRangeValue(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return null;
+    }
+    if (normalized.includes(RANGE_SEPARATOR)) {
+        const [rawMin, rawMax] = normalized.split(RANGE_SEPARATOR, 2);
+        const hasMin = rawMin.trim().length > 0;
+        const hasMax = rawMax.trim().length > 0;
+        if (!hasMin && !hasMax) {
+            return null;
+        }
+        const min = hasMin ? parseNumber(rawMin) : null;
+        const max = hasMax ? parseNumber(rawMax) : null;
+        if ((hasMin && min == null) || (hasMax && max == null)) {
+            return null;
+        }
+        // Un rango invertido (`100..50`) no puede matchear ninguna fila: es inválido.
+        if (min != null && max != null && min > max) {
+            return null;
+        }
+        return {
+            kind: "numberRange",
+            ...(max != null ? { max } : {}),
+            ...(min != null ? { min } : {}),
+        };
+    }
+    if (normalized.startsWith(">=") || normalized.startsWith(">")) {
+        const min = parseNumber(normalized.replace(/^>=?/, ""));
+        return min == null ? null : { kind: "numberRange", min };
+    }
+    if (normalized.startsWith("<=") || normalized.startsWith("<")) {
+        const max = parseNumber(normalized.replace(/^<=?/, ""));
+        return max == null ? null : { kind: "numberRange", max };
+    }
+    const exact = parseNumber(normalized.replace(/^=/, ""));
+    return exact == null ? null : { kind: "numberRange", max: exact, min: exact };
+}
+/** Convierte un slug `AAAA-MM` a su valor numérico comparable `AAAAMM`. */
+export function parseYearMonthSlug(value) {
+    const match = YEAR_MONTH_SLUG_PATTERN.exec(value.trim());
+    if (!match) {
+        return null;
+    }
+    const [, year, month] = match;
+    return Number(`${year}${month}`);
+}
+/** Formatea un valor numérico `AAAAMM` de vuelta a su slug `AAAA-MM`. */
+export function formatYearMonthSlug(value) {
+    const year = Math.floor(value / 100);
+    const month = value % 100;
+    return `${year}-${String(month).padStart(2, "0")}`;
+}
+function parseYearMonthRangeValue(value) {
+    const normalized = normalizeFilterSlug(value);
+    if (!normalized) {
+        return null;
+    }
+    if (normalized === YEAR_MONTH_NO_VALUE_SLUG) {
+        return { kind: "yearMonthRange", mode: "noValue" };
+    }
+    if (normalized === YEAR_MONTH_HAS_VALUE_SLUG) {
+        return { kind: "yearMonthRange", mode: "hasValue" };
+    }
+    // Comparators `>=`/`>` (from) and `<=`/`<` (to), analogous to the numeric
+    // ones, to bound dates with a single endpoint without writing an `A..` range.
+    if (normalized.startsWith(">=") || normalized.startsWith(">")) {
+        const min = parseYearMonthSlug(normalized.replace(/^>=?/, ""));
+        return min == null ? null : { kind: "yearMonthRange", min, mode: "from" };
+    }
+    if (normalized.startsWith("<=") || normalized.startsWith("<")) {
+        const max = parseYearMonthSlug(normalized.replace(/^<=?/, ""));
+        return max == null ? null : { kind: "yearMonthRange", max, mode: "to" };
+    }
+    if (normalized.includes(RANGE_SEPARATOR)) {
+        const [rawFrom, rawTo] = normalized.split(RANGE_SEPARATOR, 2);
+        const hasFrom = rawFrom.trim().length > 0;
+        const hasTo = rawTo.trim().length > 0;
+        if (!hasFrom && !hasTo) {
+            return null;
+        }
+        const min = hasFrom ? parseYearMonthSlug(rawFrom) : null;
+        const max = hasTo ? parseYearMonthSlug(rawTo) : null;
+        if ((hasFrom && min == null) || (hasTo && max == null)) {
+            return null;
+        }
+        if (min != null && max != null) {
+            // Rango invertido (`2026-12..2026-06`): imposible de matchear, inválido.
+            if (min > max) {
+                return null;
+            }
+            return { kind: "yearMonthRange", max, min, mode: "range" };
+        }
+        if (min != null) {
+            return { kind: "yearMonthRange", min, mode: "from" };
+        }
+        return { kind: "yearMonthRange", max: max, mode: "to" };
+    }
+    const exact = parseYearMonthSlug(normalized);
+    if (exact == null) {
+        return null;
+    }
+    return { kind: "yearMonthRange", max: exact, min: exact, mode: "range" };
+}
+function buildColumnFilterValue(config, value) {
+    if (config.kind === "numberRange") {
+        return parseNumberRangeValue(value);
+    }
+    if (config.kind === "yearMonthRange") {
+        return parseYearMonthRangeValue(value);
+    }
+    if (config.kind === "enum") {
+        // A leading `@` mention-style prefix is tolerated (e.g. `prestamista:@vero`).
+        const normalized = normalizeFilterSlug(value).replace(/^@/, "");
+        const option = (config.options ?? []).find((candidate) => normalizeFilterSlug(candidate.slug) === normalized);
+        return option ? { kind: "enum", value: option.value } : null;
+    }
+    if (config.kind === "presence") {
+        const normalized = normalizeFilterSlug(value);
+        if (normalized === PRESENCE_TRUE_SLUG) {
+            return { kind: "presence", value: "hasValue" };
+        }
+        if (normalized === PRESENCE_FALSE_SLUG) {
+            return { kind: "presence", value: "noValue" };
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Parses the value of a text qualifier (`textMatch`) with glob syntax. Accepts
+ * presence (`si`/`no`) and `*` wildcards: `text*` starts with, `*text` ends
+ * with, `*text*` contains, and `text` (no wildcard) is exact equality. The text
+ * is normalized (no accents, lowercase) to compare case/accent-insensitively.
+ */
+export function parseTextMatchValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const normalizedSlug = normalizeFilterSlug(trimmed);
+    if (normalizedSlug === PRESENCE_TRUE_SLUG) {
+        return { kind: "textMatch", op: "has" };
+    }
+    if (normalizedSlug === PRESENCE_FALSE_SLUG) {
+        return { kind: "textMatch", op: "notHas" };
+    }
+    const startsWithStar = trimmed.startsWith("*");
+    const endsWithStar = trimmed.endsWith("*");
+    if (startsWithStar && endsWithStar) {
+        const text = normalizeFilterSlug(trimmed.slice(1, -1));
+        return text ? { kind: "textMatch", op: "contains", text } : null;
+    }
+    if (endsWithStar) {
+        const text = normalizeFilterSlug(trimmed.slice(0, -1));
+        return text ? { kind: "textMatch", op: "startsWith", text } : null;
+    }
+    if (startsWithStar) {
+        const text = normalizeFilterSlug(trimmed.slice(1));
+        return text ? { kind: "textMatch", op: "endsWith", text } : null;
+    }
+    const text = normalizeFilterSlug(trimmed);
+    return text ? { kind: "textMatch", op: "equals", text } : null;
+}
+/**
+ * Parsea el valor de un qualifier de carpeta (`folder`) contra sus opciones
+ * dinámicas (slug→folderId). `sin-carpeta` mapea al sentinel de "sin asignar".
+ */
+export function parseFolderValue(config, value) {
+    // Se tolera un `@` inicial al estilo "mención" (p. ej. `carpeta:@hogar`),
+    // igual que el parser de enum, para que completar el token tipeando/Enter
+    // coincida con la sugerencia que filtra strip-eando ese `@`.
+    const normalized = normalizeFilterSlug(value).replace(/^@/, "");
+    if (!normalized) {
+        return null;
+    }
+    const option = (config.options ?? []).find((candidate) => normalizeFilterSlug(candidate.slug) === normalized);
+    return option ? { kind: "folder", folderId: option.value } : null;
+}
+/** Construye el valor estructurado de un qualifier según su kind. */
+function buildAppliedFilterValue(config, value) {
+    if (config.kind === "textMatch") {
+        return parseTextMatchValue(value);
+    }
+    if (config.kind === "folder") {
+        return parseFolderValue(config, value);
+    }
+    return buildColumnFilterValue(config, value);
+}
+/** Discrimina un valor que vive en el path de columnas de TanStack. */
+function isColumnFilterValue(value) {
+    return value.kind !== "textMatch" && value.kind !== "folder";
+}
+function mergeColumnFilterValue(existing, next) {
+    if (existing &&
+        existing.kind === "numberRange" &&
+        next.kind === "numberRange") {
+        // Qualifiers repetidos se ANDean: nos quedamos con la cota más ajustada
+        // (mayor mínimo, menor máximo) para que el resultado no dependa del orden.
+        const mergedMin = existing.min != null && next.min != null
+            ? Math.max(existing.min, next.min)
+            : (next.min ?? existing.min);
+        const mergedMax = existing.max != null && next.max != null
+            ? Math.min(existing.max, next.max)
+            : (next.max ?? existing.max);
+        return {
+            kind: "numberRange",
+            ...(mergedMax != null ? { max: mergedMax } : {}),
+            ...(mergedMin != null ? { min: mergedMin } : {}),
+        };
+    }
+    if (existing &&
+        existing.kind === "yearMonthRange" &&
+        next.kind === "yearMonthRange") {
+        const isBounded = (mode) => mode === "range" || mode === "from" || mode === "to";
+        // Los modos de presencia (con/sin fechas) no combinan con cotas: gana el
+        // último. Para range/from/to se intersectan las cotas (mayor desde, menor
+        // hasta), igual que `numberRange`, en vez de descartar la primera cota.
+        if (!isBounded(existing.mode) || !isBounded(next.mode)) {
+            return next;
+        }
+        const mergedMin = existing.min != null && next.min != null
+            ? Math.max(existing.min, next.min)
+            : (next.min ?? existing.min);
+        const mergedMax = existing.max != null && next.max != null
+            ? Math.min(existing.max, next.max)
+            : (next.max ?? existing.max);
+        const mode = mergedMin != null && mergedMax != null
+            ? "range"
+            : mergedMin != null
+                ? "from"
+                : "to";
+        return {
+            kind: "yearMonthRange",
+            mode,
+            ...(mergedMax != null ? { max: mergedMax } : {}),
+            ...(mergedMin != null ? { min: mergedMin } : {}),
+        };
+    }
+    return next;
+}
+/**
+ * Detecta un rango imposible (`min > max`), por ejemplo tras combinar
+ * `total:>100 total:<50`. El matcher rechazaría toda fila, así que se reporta el
+ * token como inválido en vez de aplicar un filtro vacío.
+ */
+function isImpossibleRange(value) {
+    if (value.kind === "numberRange") {
+        return value.min != null && value.max != null && value.min > value.max;
+    }
+    if (value.kind === "yearMonthRange") {
+        return (value.mode === "range" &&
+            value.min != null &&
+            value.max != null &&
+            value.min > value.max);
+    }
+    return false;
+}
+/** Quita duplicados de exclusiones comparando por su forma normalizada. */
+function dedupeByNormalizedSlug(values) {
+    const seenKeys = new Set();
+    const dedupedValues = [];
+    for (const value of values) {
+        const normalizedKey = normalizeFilterSlug(value);
+        if (!normalizedKey || seenKeys.has(normalizedKey)) {
+            continue;
+        }
+        seenKeys.add(normalizedKey);
+        dedupedValues.push(value);
+    }
+    return dedupedValues;
+}
+/** Parsea la query completa contra la configuración de qualifiers. */
+export function parseFilterQuery(query, configs) {
+    const tokens = tokenizeFilterQuery(query);
+    const lookup = buildQualifierLookup(configs);
+    const descriptionParts = [];
+    const excludedDescriptionFilters = [];
+    const advancedFiltersByColumn = {};
+    const appliedFilters = [];
+    // Índice en `appliedFilters` del último filtro de rango (no negado) por clave,
+    // para mergear y validar rangos repetidos de forma uniforme tengan o no columna.
+    const rangeAppliedIndexByKey = new Map();
+    const invalidTokens = [];
+    for (const token of tokens) {
+        if (token.hasColon && token.rawKey) {
+            const normalizedKey = normalizeFilterSlug(token.rawKey);
+            // Presence meta-keys (`tiene:<field>` / `no:<field>`): the value is the
+            // key of the target field. They produce a presence filter that the domain
+            // predicate evaluates per field; they do not go through the column path.
+            if (normalizedKey === PRESENCE_HAS_META_KEY ||
+                normalizedKey === PRESENCE_NO_META_KEY) {
+                const fieldKey = normalizeFilterSlug(token.value ?? "");
+                if (!fieldKey) {
+                    continue;
+                }
+                const fieldConfig = lookup.get(fieldKey);
+                if (!fieldConfig || fieldConfig.supportsPresence === false) {
+                    invalidTokens.push({ raw: token.raw, reason: "invalidValue" });
+                    continue;
+                }
+                // Token negation (`-tiene:x`) flips the meaning, leaving a single
+                // canonical presence filter (without residual negation).
+                const hasValue = (normalizedKey === PRESENCE_HAS_META_KEY) !== token.negated;
+                appliedFilters.push({
+                    key: fieldConfig.key,
+                    negated: false,
+                    value: { kind: "presence", value: hasValue ? "hasValue" : "noValue" },
+                });
+                continue;
+            }
+            const config = lookup.get(normalizedKey);
+            if (!config) {
+                invalidTokens.push({ raw: token.raw, reason: "unknownKey" });
+                const freeText = token.negated ? token.raw.slice(1) : token.raw;
+                if (token.negated) {
+                    excludedDescriptionFilters.push(freeText.trim());
+                }
+                else if (freeText.trim()) {
+                    descriptionParts.push(freeText.trim());
+                }
+                continue;
+            }
+            const value = token.value ?? "";
+            const filterValue = buildAppliedFilterValue(config, value);
+            if (!filterValue) {
+                if (value.trim()) {
+                    invalidTokens.push({ raw: token.raw, reason: "invalidValue" });
+                }
+                continue;
+            }
+            if (isColumnFilterValue(filterValue)) {
+                const isRange = filterValue.kind === "numberRange" ||
+                    filterValue.kind === "yearMonthRange";
+                // Los rangos repetidos de una misma clave (con o sin columna) se mergean
+                // y validan igual: una combinación imposible (p. ej.
+                // `subtotal:>1000 subtotal:<50`) se reporta inválida y conserva la cota
+                // previa, en vez de filtrar todas las filas en silencio.
+                if (!token.negated && isRange) {
+                    const existingIndex = rangeAppliedIndexByKey.get(config.key);
+                    if (existingIndex != null) {
+                        const existingValue = appliedFilters[existingIndex]
+                            .value;
+                        const mergedValue = mergeColumnFilterValue(existingValue, filterValue);
+                        if (isImpossibleRange(mergedValue)) {
+                            invalidTokens.push({ raw: token.raw, reason: "invalidValue" });
+                            continue;
+                        }
+                        appliedFilters[existingIndex] = {
+                            ...appliedFilters[existingIndex],
+                            value: mergedValue,
+                        };
+                        if (config.columnId) {
+                            advancedFiltersByColumn[config.columnId] = mergedValue;
+                        }
+                        continue;
+                    }
+                    appliedFilters.push({
+                        key: config.key,
+                        negated: false,
+                        value: filterValue,
+                    });
+                    rangeAppliedIndexByKey.set(config.key, appliedFilters.length - 1);
+                    if (config.columnId) {
+                        advancedFiltersByColumn[config.columnId] = filterValue;
+                    }
+                    continue;
+                }
+                // enum/presence (not range) or negated: added without merging. The
+                // non-negated ones with a column are projected to the classic TanStack
+                // path.
+                appliedFilters.push({
+                    key: config.key,
+                    negated: token.negated,
+                    value: filterValue,
+                });
+                // Presence (`<field>:si/no`) is unified with the meta-keys and resolved
+                // by the domain predicate, so it is never projected to a column.
+                if (!token.negated &&
+                    config.columnId &&
+                    filterValue.kind !== "presence") {
+                    advancedFiltersByColumn[config.columnId] = mergeColumnFilterValue(advancedFiltersByColumn[config.columnId], filterValue);
+                }
+                continue;
+            }
+            // textMatch / folder: sin columna y sin merge de rango.
+            appliedFilters.push({
+                key: config.key,
+                negated: token.negated,
+                value: filterValue,
+            });
+            continue;
+        }
+        const text = (token.value ?? "").trim();
+        if (!text) {
+            continue;
+        }
+        if (token.negated) {
+            excludedDescriptionFilters.push(text);
+        }
+        else {
+            descriptionParts.push(text);
+        }
+    }
+    return {
+        advancedFiltersByColumn,
+        appliedFilters,
+        descriptionFilter: descriptionParts.join(" "),
+        excludedDescriptionFilters: dedupeByNormalizedSlug(excludedDescriptionFilters),
+        invalidTokens,
+    };
+}
+function serializeNumberRange(key, value) {
+    const { min, max } = value;
+    if (min != null && max != null) {
+        return min === max ? `${key}:=${min}` : `${key}:${min}..${max}`;
+    }
+    if (min != null) {
+        return `${key}:>=${min}`;
+    }
+    if (max != null) {
+        return `${key}:<=${max}`;
+    }
+    return null;
+}
+function serializeYearMonthRange(key, value) {
+    if (value.mode === "noValue") {
+        return `${key}:${YEAR_MONTH_NO_VALUE_SLUG}`;
+    }
+    if (value.mode === "hasValue") {
+        return `${key}:${YEAR_MONTH_HAS_VALUE_SLUG}`;
+    }
+    if (value.mode === "from" && value.min != null) {
+        return `${key}:${formatYearMonthSlug(value.min)}..`;
+    }
+    if (value.mode === "to" && value.max != null) {
+        return `${key}:..${formatYearMonthSlug(value.max)}`;
+    }
+    if (value.mode === "range" && value.min != null && value.max != null) {
+        if (value.min === value.max) {
+            return `${key}:${formatYearMonthSlug(value.min)}`;
+        }
+        return `${key}:${formatYearMonthSlug(value.min)}..${formatYearMonthSlug(value.max)}`;
+    }
+    return null;
+}
+function serializeTextMatch(key, value) {
+    if (value.op === "has") {
+        return `${key}:${PRESENCE_TRUE_SLUG}`;
+    }
+    if (value.op === "notHas") {
+        return `${key}:${PRESENCE_FALSE_SLUG}`;
+    }
+    const text = value.text ?? "";
+    const decorated = value.op === "startsWith"
+        ? `${text}*`
+        : value.op === "endsWith"
+            ? `*${text}`
+            : value.op === "contains"
+                ? `*${text}*`
+                : text;
+    return `${key}:${quoteTokenIfNeeded(decorated)}`;
+}
+function serializeFolderValue(config, value) {
+    const option = (config.options ?? []).find((candidate) => candidate.value === value.folderId);
+    return option ? `${config.key}:${option.slug}` : null;
+}
+function serializeAppliedFilterValue(config, value) {
+    if (value.kind === "numberRange") {
+        return serializeNumberRange(config.key, value);
+    }
+    if (value.kind === "yearMonthRange") {
+        return serializeYearMonthRange(config.key, value);
+    }
+    if (value.kind === "enum") {
+        const option = (config.options ?? []).find((candidate) => candidate.value === value.value);
+        return option ? `${config.key}:${option.slug}` : null;
+    }
+    if (value.kind === "textMatch") {
+        return serializeTextMatch(config.key, value);
+    }
+    if (value.kind === "folder") {
+        return serializeFolderValue(config, value);
+    }
+    // Presence: canonical form with meta-keys (`tiene:<field>` / `no:<field>`).
+    const metaKey = value.value === "hasValue" ? PRESENCE_HAS_META_KEY : PRESENCE_NO_META_KEY;
+    return `${metaKey}:${config.key}`;
+}
+/**
+ * `true` when the filter is already emitted by the classic serialization from
+ * `advancedFiltersByColumn` (not negated, with a column, and of a column kind),
+ * so it is not serialized twice while also iterating `appliedFilters`.
+ *
+ * `textMatch` and `folder` never live in the column map, so they are never
+ * covered. Presence is special: parsing keeps it only in `appliedFilters`, but a
+ * consumer (the advanced dialog) may also place it in the column map. It counts
+ * as covered only when that same column actually holds a value, so a presence
+ * that lives solely in `appliedFilters` is still serialized once and one that
+ * lives in both is not duplicated.
+ */
+function isCoveredByColumnSerialization(appliedFilter, config, advancedFiltersByColumn) {
+    if (appliedFilter.negated ||
+        config.columnId == null ||
+        appliedFilter.value.kind === "textMatch" ||
+        appliedFilter.value.kind === "folder") {
+        return false;
+    }
+    if (appliedFilter.value.kind === "presence") {
+        return advancedFiltersByColumn[config.columnId] != null;
+    }
+    return true;
+}
+/** Reconstruye una query canónica a partir de un resultado parseado. */
+export function serializeFilterQuery(parsed, configs) {
+    const segments = [];
+    const configsByKey = new Map(configs.map((config) => [normalizeFilterSlug(config.key), config]));
+    const descriptionFilter = parsed.descriptionFilter.trim();
+    if (descriptionFilter) {
+        segments.push(serializeDescriptionFilter(descriptionFilter));
+    }
+    // Classic per-column filters (config order), for compatibility with consumers
+    // that build the parsed result only from `advancedFiltersByColumn`.
+    for (const config of configs) {
+        if (!config.columnId) {
+            continue;
+        }
+        const value = parsed.advancedFiltersByColumn[config.columnId];
+        if (!value) {
+            continue;
+        }
+        const serialized = serializeAppliedFilterValue(config, value);
+        if (serialized) {
+            segments.push(serialized);
+        }
+    }
+    // Extras the column path does not cover: negated, textMatch, folder, and
+    // qualifiers without a column.
+    for (const appliedFilter of parsed.appliedFilters ?? []) {
+        const config = configsByKey.get(normalizeFilterSlug(appliedFilter.key));
+        if (!config ||
+            isCoveredByColumnSerialization(appliedFilter, config, parsed.advancedFiltersByColumn)) {
+            continue;
+        }
+        const serialized = serializeAppliedFilterValue(config, appliedFilter.value);
+        if (serialized) {
+            segments.push(appliedFilter.negated ? `-${serialized}` : serialized);
+        }
+    }
+    for (const excluded of parsed.excludedDescriptionFilters) {
+        const trimmed = excluded.trim();
+        if (trimmed) {
+            segments.push(`-${quoteTokenIfNeeded(trimmed)}`);
+        }
+    }
+    return segments.join(" ");
+}
+/**
+ * Returns the character ranges of the VALUES (whatever comes after the `:`) that
+ * are valid for their qualifier, to highlight them in the bar. An invalid,
+ * unknown, or incomplete value produces no range (no highlight). Covers the
+ * presence meta-keys (`tiene:`/`no:` with an existing field) and the normal
+ * qualifiers (value parseable per its kind: enum, range, text, etc.).
+ */
+export function getValueHighlightRanges(query, configs) {
+    const tokens = tokenizeFilterQuery(query);
+    const lookup = buildQualifierLookup(configs);
+    const ranges = [];
+    for (const token of tokens) {
+        if (!token.hasColon || !token.rawKey) {
+            continue;
+        }
+        const negationOffset = token.negated ? 1 : 0;
+        const colonIndex = findKeyColonIndex(token.raw.slice(negationOffset));
+        if (colonIndex === -1) {
+            continue;
+        }
+        const valueStart = token.startIndex + negationOffset + colonIndex + 1;
+        // No value yet (`key:`): nothing to highlight.
+        if (valueStart >= token.endIndex) {
+            continue;
+        }
+        const normalizedKey = normalizeFilterSlug(token.rawKey);
+        const rawValue = token.value ?? "";
+        let isValid = false;
+        if (normalizedKey === PRESENCE_HAS_META_KEY ||
+            normalizedKey === PRESENCE_NO_META_KEY) {
+            // A meta-key's value is the key of an existing field.
+            isValid = lookup.has(normalizeFilterSlug(rawValue));
+        }
+        else {
+            const config = lookup.get(normalizedKey);
+            isValid =
+                config != null && buildAppliedFilterValue(config, rawValue) != null;
+        }
+        if (isValid) {
+            ranges.push({ end: token.endIndex, start: valueStart });
+        }
+    }
+    return ranges;
+}
+/**
+ * Describe el token bajo el caret para alimentar el autocompletado. Decide si
+ * el usuario está tipeando una clave (sin `:`) o el valor de una clave.
+ */
+export function getActiveFilterToken(query, caretIndex) {
+    const tokens = tokenizeFilterQuery(query);
+    const activeToken = tokens.find((token) => caretIndex >= token.startIndex && caretIndex <= token.endIndex);
+    if (!activeToken) {
+        return {
+            keyPart: "",
+            mode: "key",
+            negated: false,
+            replaceEnd: caretIndex,
+            replaceStart: caretIndex,
+            resolvedKey: null,
+            tokenStart: caretIndex,
+            valuePart: "",
+        };
+    }
+    const negationOffset = activeToken.negated ? 1 : 0;
+    const contentStart = activeToken.startIndex + negationOffset;
+    const remainder = activeToken.raw.slice(negationOffset);
+    const colonIndex = findKeyColonIndex(remainder);
+    if (colonIndex === -1) {
+        return {
+            keyPart: remainder,
+            mode: "key",
+            negated: activeToken.negated,
+            replaceEnd: activeToken.endIndex,
+            replaceStart: activeToken.startIndex,
+            resolvedKey: null,
+            tokenStart: activeToken.startIndex,
+            valuePart: "",
+        };
+    }
+    const valueStart = contentStart + colonIndex + 1;
+    return {
+        keyPart: remainder.slice(0, colonIndex),
+        mode: "value",
+        negated: activeToken.negated,
+        replaceEnd: activeToken.endIndex,
+        replaceStart: valueStart,
+        resolvedKey: remainder.slice(0, colonIndex),
+        tokenStart: activeToken.startIndex,
+        valuePart: remainder.slice(colonIndex + 1),
+    };
+}