@astra-kit/ui 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,875 @@
+/**
+* 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,
+			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)
+	};
+}