beez-ui 0.4.0

package/dist/components/filter-query-grammar.d.ts

@@ -0,0 +1,188 @@
+import type { DataTableColumnFilterValue } from "../types/data-table.js";
+/** Slug de valor para los modos de presencia/rango mes-año sin cota. */
+export declare const YEAR_MONTH_NO_VALUE_SLUG = "sin-fechas";
+export declare const YEAR_MONTH_HAS_VALUE_SLUG = "con-fechas";
+export declare const PRESENCE_TRUE_SLUG = "si";
+export declare 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 declare const PRESENCE_HAS_META_KEY = "tiene";
+export declare const PRESENCE_NO_META_KEY = "no";
+export type FilterQualifierKind = "text" | "numberRange" | "enum" | "presence" | "yearMonthRange" | "textMatch" | "folder";
+/** Operadores soportados por un qualifier de texto (`textMatch`). */
+export type TextMatchOperator = "has" | "notHas" | "startsWith" | "endsWith" | "equals" | "contains";
+/** Valor estructurado de un qualifier de texto (link, prestamista, etc.). */
+export interface TextMatchFilterValue {
+    kind: "textMatch";
+    op: TextMatchOperator;
+    /** Texto a comparar (normalizado). Ausente para `has`/`notHas`. */
+    text?: string;
+}
+/** Identificador de "sin carpeta asignada" en un qualifier de carpeta. */
+export declare const UNASSIGNED_FOLDER_FILTER_VALUE = "__unassigned__";
+/** Valor de un qualifier de carpeta (un token; el predicado agrupa varios). */
+export interface FolderFilterValue {
+    kind: "folder";
+    /** Id de carpeta, o `UNASSIGNED_FOLDER_FILTER_VALUE` para sin carpeta. */
+    folderId: string;
+}
+/**
+ * Valor estructurado que viaja al predicado de filtrado, independiente de las
+ * columnas de TanStack. Une los valores clásicos por columna con los nuevos
+ * (texto y carpeta) que no tienen columna.
+ */
+export type AppliedFilterValue = DataTableColumnFilterValue | TextMatchFilterValue | FolderFilterValue;
+/** Un filtro aplicado parseado desde la query: `clave`, negación y valor. */
+export interface AppliedFilter {
+    key: string;
+    negated: boolean;
+    value: AppliedFilterValue;
+}
+export interface FilterQualifierOption {
+    /** Slug que el usuario tipea (sin acentos ni espacios). */
+    slug: string;
+    /** Etiqueta visible en el autocompletado. */
+    label: string;
+    /** Valor interno que consume el matcher de la columna. */
+    value: string;
+}
+export interface FilterQualifierConfig {
+    /**
+     * Slug que el usuario tipea antes del `:`. Cadena vacía para el qualifier de
+     * texto libre por defecto (búsqueda fuzzy por descripción).
+     */
+    key: string;
+    /** Claves alternativas aceptadas al parsear (no se sugieren). */
+    aliases?: string[];
+    /** Columna destino para los filtros avanzados. Ausente para texto libre. */
+    columnId?: string;
+    kind: FilterQualifierKind;
+    /** Etiqueta humana mostrada en la sugerencia de clave. */
+    label: string;
+    /** Valores sugeridos para enum/presence. */
+    options?: FilterQualifierOption[];
+    /**
+     * Logical name of the icon to show in the bar (UI-agnostic; the bar maps it
+     * to a component). E.g. `"user"` for lenders. When omitted, the bar uses the
+     * default icon for the `kind`.
+     */
+    iconName?: string;
+    /**
+     * `false` cuando el campo siempre tiene valor y las meta-claves de presencia
+     * (`tiene:<clave>` / `no:<clave>`) no tienen sentido: la barra no las sugiere
+     * y el parser las rechaza como token inválido. Default: `true`.
+     */
+    supportsPresence?: boolean;
+}
+export interface FilterQueryToken {
+    /** Substring exacto del token (sin espacios alrededor). */
+    raw: string;
+    /** Índice del primer carácter del token en la query original. */
+    startIndex: number;
+    /** Índice siguiente al último carácter del token. */
+    endIndex: number;
+    /** Si el token arranca con `-` (negación / exclusión). */
+    negated: boolean;
+    /** Texto de la clave tal cual se tipeó (sin normalizar), o `null`. */
+    rawKey: string | null;
+    /** Valor del qualifier desenrollado de comillas, o `null` si no hay `:`. */
+    value: string | null;
+    /** Si el token contiene un `:` que separa clave de valor. */
+    hasColon: boolean;
+}
+export type InvalidFilterTokenReason = "unknownKey" | "invalidValue";
+export interface InvalidFilterToken {
+    raw: string;
+    reason: InvalidFilterTokenReason;
+}
+export interface ParsedFilterQuery {
+    /** Texto libre positivo, concatenado para la búsqueda fuzzy por descripción. */
+    descriptionFilter: string;
+    /** Textos a excluir (`-texto`), crudos como espera la tabla. */
+    excludedDescriptionFilters: string[];
+    /**
+     * Filtros avanzados clásicos por `columnId`, derivados para compatibilidad con
+     * el path de columnas de TanStack. Solo incluye qualifiers no negados con
+     * columna. La fuente de verdad completa es {@link ParsedFilterQuery.appliedFilters}.
+     */
+    advancedFiltersByColumn: Record<string, DataTableColumnFilterValue>;
+    /**
+     * Lista completa de filtros aplicados (cualquier kind, con o sin columna,
+     * incluyendo negados). El predicado de dominio consume esta lista.
+     */
+    appliedFilters: AppliedFilter[];
+    /** Tokens que no se pudieron aplicar (clave o valor inválidos). */
+    invalidTokens: InvalidFilterToken[];
+}
+/** Normaliza una clave o slug: sin acentos, minúsculas, recortado. */
+export declare function normalizeFilterSlug(value: string): string;
+/**
+ * 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 declare function tokenizeFilterQuery(query: string): FilterQueryToken[];
+/** Convierte un slug `AAAA-MM` a su valor numérico comparable `AAAAMM`. */
+export declare function parseYearMonthSlug(value: string): number | null;
+/** Formatea un valor numérico `AAAAMM` de vuelta a su slug `AAAA-MM`. */
+export declare function formatYearMonthSlug(value: number): string;
+/**
+ * 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 declare function parseTextMatchValue(value: string): TextMatchFilterValue | 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 declare function parseFolderValue(config: FilterQualifierConfig, value: string): FolderFilterValue | null;
+/** Parsea la query completa contra la configuración de qualifiers. */
+export declare function parseFilterQuery(query: string, configs: FilterQualifierConfig[]): ParsedFilterQuery;
+/** Reconstruye una query canónica a partir de un resultado parseado. */
+export declare function serializeFilterQuery(parsed: ParsedFilterQuery, configs: FilterQualifierConfig[]): string;
+/** Character range (within the query) of a value to highlight. */
+export interface ValueHighlightRange {
+    start: number;
+    end: number;
+}
+/**
+ * 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 declare function getValueHighlightRanges(query: string, configs: FilterQualifierConfig[]): ValueHighlightRange[];
+export type FilterSuggestionMode = "key" | "value";
+export interface ActiveFilterToken {
+    /** Modo de sugerencia según la posición del caret. */
+    mode: FilterSuggestionMode;
+    /** Texto de la clave tipeada hasta el caret (modo `key`). */
+    keyPart: string;
+    /** Texto del valor tipeado hasta el caret (modo `value`). */
+    valuePart: string;
+    /** Clave resuelta cuando el token ya tiene `:` (modo `value`). */
+    resolvedKey: string | null;
+    negated: boolean;
+    /** Rango de la query a reemplazar al insertar una sugerencia. */
+    replaceStart: number;
+    replaceEnd: number;
+    /**
+     * Start of the whole token (including `-` and the key). Allows replacing the
+     * entire token when inserting a meta-key (`tiene:<field>`) or an exclusion
+     * (`-<field>:`), not just the value segment.
+     */
+    tokenStart: number;
+}
+/**
+ * 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 declare function getActiveFilterToken(query: string, caretIndex: number): ActiveFilterToken;