@dorsk/tsumikit 0.8.2 → 0.9.1

package/dist/components/organisms/FilterSearchBar.svelte

@@ -0,0 +1,340 @@
+<script lang="ts">
+	// ───────────────────────────────────────────────────────────────────────
+	// FilterSearchBar organism — a YouTrack-style structured search bar.
+	//
+	// The textual query IS the single source of truth: the bar is a small query
+	// language, so a user can type `artist:"Daft Punk" AND year>=2000` by hand
+	// (pure-code mode) OR build it entirely from the context-aware dropdown
+	// (visual helper mode). Both edit the same string.
+	//
+	// The component owns parsing, suggesting and keyboard/dropdown/chips — all of
+	// it generic. Everything project-specific is INJECTED:
+	//   • `schema`  — the field registry (drives autocomplete + the chips).
+	//                 Per-field async `provider`s feed value autocomplete; static
+	//                 `options` cover enums. No `fetch` lives in here.
+	//   • `onchange(query)` — fires the parsed AST whenever it changes; the host
+	//                 runs it against its real backend and renders results.
+	//
+	// The bar owns the QUERY; the host owns the DISPLAY of results.
+	// ───────────────────────────────────────────────────────────────────────
+	import Badge from '../atoms/Badge.svelte';
+	import Icon from '../atoms/Icon.svelte';
+	import { filters, freeText, type Query } from '../../query/ast';
+	import { findField, operatorById, type Schema } from '../../query/schema';
+	import { parse } from '../../query/parser';
+	import { suggest, type SuggestState } from '../../query/suggest';
+
+	let {
+		schema,
+		value = $bindable(''),
+		placeholder = 'artist:"Daft Punk" AND year>=2000',
+		showChips = true,
+		onchange,
+		onsubmit
+	}: {
+		schema: Schema;
+		/** The raw textual query (two-way bindable). */
+		value?: string;
+		placeholder?: string;
+		/** Render the parsed, removable filter chips under the bar. */
+		showChips?: boolean;
+		/** Fires the parsed AST on every change — feed this to your backend. */
+		onchange?: (query: Query, raw: string) => void;
+		/** Fires on Enter / clear / chip-remove with the raw query string. */
+		onsubmit?: (value: string) => void;
+	} = $props();
+
+	let el = $state<HTMLInputElement | null>(null);
+	let menu = $state<SuggestState | null>(null);
+	let active = $state(0);
+	let open = $state(false);
+	let reqId = 0;
+
+	// Parsed view (drives the removable chips + the onchange AST).
+	const ast = $derived(parse(value, schema));
+	const chips = $derived(filters(ast));
+	const text = $derived(freeText(ast));
+
+	// Emit the AST whenever the parse result changes.
+	$effect(() => {
+		onchange?.(ast, value);
+	});
+
+	function labelFor(fieldName: string): string {
+		return findField(schema, fieldName)?.label ?? fieldName;
+	}
+
+	async function refresh() {
+		if (!el) return;
+		const pos = el.selectionStart ?? value.length;
+		const id = ++reqId;
+		const next = await suggest(schema, value, pos);
+		if (id !== reqId) return; // a newer keystroke won
+		menu = next;
+		active = 0;
+		open = !!next && next.items.length > 0;
+	}
+
+	function accept(i: number) {
+		if (!menu || !el) return;
+		const s = menu.items[i];
+		if (!s) return;
+		const [a, b] = menu.span;
+		value = value.slice(0, a) + s.insert + value.slice(b);
+		// Restore caret after the inserted text, then re-run suggestions if the
+		// step advanced (field → operator → value) so the flow keeps going.
+		queueMicrotask(() => {
+			if (!el) return;
+			el.focus();
+			el.setSelectionRange(s.caret, s.caret);
+			if (s.advance) refresh();
+			else open = false;
+		});
+	}
+
+	function onkeydown(e: KeyboardEvent) {
+		if (!open || !menu) {
+			if (e.key === 'Enter') submit();
+			return;
+		}
+		switch (e.key) {
+			case 'ArrowDown':
+				e.preventDefault();
+				active = (active + 1) % menu.items.length;
+				break;
+			case 'ArrowUp':
+				e.preventDefault();
+				active = (active - 1 + menu.items.length) % menu.items.length;
+				break;
+			case 'Enter':
+			case 'Tab':
+				e.preventDefault();
+				accept(active);
+				break;
+			case 'Escape':
+				e.preventDefault();
+				open = false;
+				break;
+		}
+	}
+
+	function submit() {
+		open = false;
+		onsubmit?.(value);
+	}
+
+	function removeChip(span: [number, number]) {
+		// Splice the clause out, plus trailing spaces to avoid doubles.
+		const [a, b] = span;
+		let end = b;
+		while (value[end] === ' ') end++;
+		value = (value.slice(0, a) + value.slice(end)).replace(/\s{2,}/g, ' ').trim();
+		onsubmit?.(value);
+		queueMicrotask(() => el?.focus());
+	}
+
+	const kindLabel: Record<string, string> = {
+		field: 'Fields',
+		operator: 'Operators',
+		value: 'Values'
+	};
+</script>
+
+<div class="fsb" data-tsu="FilterSearchBar">
+	<div class="fsb__bar">
+		<span class="fsb__icon"><Icon name="search" label="Search" /></span>
+		<input
+			bind:this={el}
+			bind:value
+			class="fsb__input"
+			spellcheck="false"
+			autocomplete="off"
+			{placeholder}
+			oninput={refresh}
+			onclick={refresh}
+			onkeyup={(e) => {
+				if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') refresh();
+			}}
+			onfocus={refresh}
+			onblur={() => setTimeout(() => (open = false), 120)}
+			{onkeydown}
+		/>
+		{#if value}
+			<button
+				type="button"
+				class="fsb__clear"
+				title="Clear"
+				onclick={() => {
+					value = '';
+					onsubmit?.('');
+					el?.focus();
+				}}
+			>
+				<Icon name="x" label="Clear" />
+			</button>
+		{/if}
+	</div>
+
+	{#if open && menu}
+		<div class="fsb__menu" role="listbox" aria-label={kindLabel[menu.kind]}>
+			<div class="fsb__menu-head">{kindLabel[menu.kind]}</div>
+			{#each menu.items as item, i (item.insert + i)}
+				<button
+					type="button"
+					class="fsb__opt"
+					class:is-active={i === active}
+					role="option"
+					aria-selected={i === active}
+					onmousedown={(e) => e.preventDefault()}
+					onmouseenter={() => (active = i)}
+					onclick={() => accept(i)}
+				>
+					<span class="fsb__opt-label">{item.label}</span>
+					{#if item.hint}<span class="fsb__opt-hint">{item.hint}</span>{/if}
+					{#if item.code}<span class="fsb__opt-code">{item.code}</span>{/if}
+				</button>
+			{/each}
+		</div>
+	{/if}
+</div>
+
+{#if showChips && (chips.length || text)}
+	<div class="fsb__chips">
+		{#each chips as f (f.span[0])}
+			<Badge tone="info" removable onremove={() => removeChip(f.span)}>
+				<span class="fsb__chip-field">{labelFor(f.field)}</span>
+				<span class="fsb__chip-op">{operatorById(f.op)?.label}</span>
+				<span class="fsb__chip-val">{f.values.join(', ') || '∅'}</span>
+			</Badge>
+		{/each}
+		{#if text}
+			<Badge tone="neutral">
+				<span class="fsb__chip-op">text</span>
+				<span class="fsb__chip-val">{text}</span>
+			</Badge>
+		{/if}
+	</div>
+{/if}
+
+<style>
+	.fsb {
+		position: relative;
+	}
+	.fsb__bar {
+		display: flex;
+		align-items: center;
+		gap: var(--sp-2);
+		padding: 0 var(--sp-3);
+		height: 44px;
+		background: var(--bg-elevated);
+		border: 1px solid var(--border-strong);
+		border-radius: var(--r-md);
+	}
+	.fsb__bar:focus-within {
+		border-color: var(--accent);
+		box-shadow: 0 0 0 3px var(--accent-dim);
+	}
+	.fsb__icon {
+		display: flex;
+		color: var(--text-faint);
+	}
+	.fsb__input {
+		flex: 1;
+		border: 0;
+		background: transparent;
+		color: var(--text);
+		font-family: var(--font-mono);
+		font-size: var(--fs-md);
+		outline: none;
+		min-width: 0;
+	}
+	.fsb__input::placeholder {
+		color: var(--text-faint);
+	}
+	.fsb__clear {
+		display: flex;
+		border: 0;
+		background: transparent;
+		color: var(--text-faint);
+		cursor: pointer;
+		padding: var(--sp-1);
+		border-radius: var(--r-sm);
+	}
+	.fsb__clear:hover {
+		color: var(--text);
+		background: var(--bg-elevated-2);
+	}
+
+	.fsb__menu {
+		position: absolute;
+		top: calc(100% + 4px);
+		left: 0;
+		right: 0;
+		z-index: var(--z-drawer);
+		background: var(--bg-elevated);
+		border: 1px solid var(--border-strong);
+		border-radius: var(--r-md);
+		box-shadow: var(--shadow-lg);
+		padding: var(--sp-1);
+		max-height: 320px;
+		overflow-y: auto;
+	}
+	.fsb__menu-head {
+		font-size: var(--fs-xs);
+		text-transform: uppercase;
+		letter-spacing: 0.06em;
+		color: var(--text-faint);
+		padding: var(--sp-2) var(--sp-2) var(--sp-1);
+	}
+	.fsb__opt {
+		display: flex;
+		align-items: baseline;
+		gap: var(--sp-2);
+		width: 100%;
+		text-align: left;
+		border: 0;
+		background: transparent;
+		color: var(--text);
+		padding: var(--sp-2);
+		border-radius: var(--r-sm);
+		cursor: pointer;
+		font-size: var(--fs-sm);
+	}
+	.fsb__opt.is-active {
+		background: var(--accent-dim);
+	}
+	.fsb__opt-label {
+		font-weight: var(--fw-medium);
+	}
+	.fsb__opt-hint {
+		color: var(--text-faint);
+		font-size: var(--fs-xs);
+	}
+	.fsb__opt-code {
+		margin-left: auto;
+		font-family: var(--font-mono);
+		font-size: var(--fs-xs);
+		color: var(--text-muted);
+		background: var(--bg-elevated-2);
+		padding: 0 var(--sp-1);
+		border-radius: var(--r-sm);
+	}
+
+	.fsb__chips {
+		display: flex;
+		flex-wrap: wrap;
+		gap: var(--sp-2);
+		margin-top: var(--sp-3);
+	}
+	.fsb__chip-field {
+		font-weight: var(--fw-semibold);
+	}
+	.fsb__chip-op {
+		opacity: 0.7;
+		font-style: italic;
+		margin: 0 var(--sp-1);
+	}
+	.fsb__chip-val {
+		font-family: var(--font-mono);
+	}
+</style>

package/dist/components/organisms/FilterSearchBar.svelte.d.ts

@@ -0,0 +1,17 @@
+import { type Query } from '../../query/ast';
+import { type Schema } from '../../query/schema';
+type $$ComponentProps = {
+    schema: Schema;
+    /** The raw textual query (two-way bindable). */
+    value?: string;
+    placeholder?: string;
+    /** Render the parsed, removable filter chips under the bar. */
+    showChips?: boolean;
+    /** Fires the parsed AST on every change — feed this to your backend. */
+    onchange?: (query: Query, raw: string) => void;
+    /** Fires on Enter / clear / chip-remove with the raw query string. */
+    onsubmit?: (value: string) => void;
+};
+declare const FilterSearchBar: import("svelte").Component<$$ComponentProps, {}, "value">;
+type FilterSearchBar = ReturnType<typeof FilterSearchBar>;
+export default FilterSearchBar;

package/dist/index.d.ts

@@ -48,6 +48,8 @@ export { default as Toggle } from './components/molecules/Toggle.svelte';
 export { default as Tooltip } from './components/molecules/Tooltip.svelte';
 export { default as Truncate } from './components/molecules/Truncate.svelte';
 export { type Column, default as DataTable } from './components/organisms/DataTable.svelte';
+export { default as FilterSearchBar } from './components/organisms/FilterSearchBar.svelte';
+export { activeToken, compilePredicate, defaultOperator, type FieldDef, type FieldType, type FilterNode, filters, findField, freeText, OPERATORS, type Operator, type OperatorId, operatorByCode, operatorById, operatorsFor, parse, type Query, type QueryNode, resolveValues, type Schema, type Suggestion, type SuggestKind, type SuggestState, serialize, serializeFilter, suggest, type TextNode, toSql, type ValueOption, type ValueProvider, } from './query';
 export { fontScale, SCALE_LEVELS, type ScaleLevel } from './stores/fontscale.svelte';
 export { type Mode, THEMES, theme } from './stores/theme.svelte';
 export { type Toast, type ToastTone, toasts } from './stores/toast.svelte';

package/dist/index.js

@@ -59,6 +59,9 @@ export { default as Tooltip } from './components/molecules/Tooltip.svelte';
 export { default as Truncate } from './components/molecules/Truncate.svelte';
 // ---- organisms ----
 export { default as DataTable } from './components/organisms/DataTable.svelte';
+export { default as FilterSearchBar } from './components/organisms/FilterSearchBar.svelte';
+// ---- query core (headless: schema / parser / AST / suggest / compilers) ----
+export { activeToken, compilePredicate, defaultOperator, filters, findField, freeText, OPERATORS, operatorByCode, operatorById, operatorsFor, parse, resolveValues, serialize, serializeFilter, suggest, toSql, } from './query';
 export { fontScale, SCALE_LEVELS } from './stores/fontscale.svelte';
 // ---- stores / actions ----
 export { THEMES, theme } from './stores/theme.svelte';

package/dist/query/ast.d.ts

@@ -0,0 +1,24 @@
+import type { OperatorId } from './schema';
+/** A single `field op value(s)` clause. */
+export interface FilterNode {
+    kind: 'filter';
+    field: string;
+    op: OperatorId;
+    /** One value for most ops; two for range; many for `in`. */
+    values: string[];
+    /** Source span [start, end) in the raw string — used by the UI for editing. */
+    span: [number, number];
+}
+/** Leftover free-text term (full-text / fuzzy search on the backend). */
+export interface TextNode {
+    kind: 'text';
+    value: string;
+    span: [number, number];
+}
+export type QueryNode = FilterNode | TextNode;
+export interface Query {
+    /** Clauses are AND-combined (YouTrack semantics). */
+    nodes: QueryNode[];
+}
+export declare function filters(q: Query): FilterNode[];
+export declare function freeText(q: Query): string;

package/dist/query/ast.js

@@ -0,0 +1,16 @@
+// ─────────────────────────────────────────────────────────────────────────
+// The AST — the serialisable contract that the parser produces and that BOTH
+// the autocomplete UI and the backend compiler consume. The frontend never
+// asks the server to re-parse free text; it ships this tree (or the server
+// runs the same parser and gets the same tree).
+// ─────────────────────────────────────────────────────────────────────────
+export function filters(q) {
+    return q.nodes.filter((n) => n.kind === 'filter');
+}
+export function freeText(q) {
+    return q.nodes
+        .filter((n) => n.kind === 'text')
+        .map((n) => n.value)
+        .join(' ')
+        .trim();
+}

package/dist/query/index.d.ts

@@ -0,0 +1,8 @@
+export type { FilterNode, Query, QueryNode, TextNode } from './ast';
+export { filters, freeText } from './ast';
+export { parse } from './parser';
+export { compilePredicate, serialize, serializeFilter, toSql } from './query';
+export type { FieldDef, FieldType, Operator, OperatorId, Schema, ValueOption, ValueProvider, } from './schema';
+export { defaultOperator, findField, OPERATORS, operatorByCode, operatorById, operatorsFor, resolveValues, } from './schema';
+export type { Suggestion, SuggestKind, SuggestState } from './suggest';
+export { activeToken, suggest } from './suggest';

package/dist/query/index.js

@@ -0,0 +1,9 @@
+// Headless query core for FilterSearchBar — schema registry, tolerant parser,
+// serialisable AST, autocomplete engine and AST compilers. Framework-agnostic:
+// no Svelte, no DOM. A host app supplies a `Schema` (optionally with async
+// `ValueProvider`s) and consumes the `Query` AST against its own backend.
+export { filters, freeText } from './ast';
+export { parse } from './parser';
+export { compilePredicate, serialize, serializeFilter, toSql } from './query';
+export { defaultOperator, findField, OPERATORS, operatorByCode, operatorById, operatorsFor, resolveValues, } from './schema';
+export { activeToken, suggest } from './suggest';

package/dist/query/parser.d.ts

@@ -0,0 +1,3 @@
+import type { Query } from './ast';
+import { type Schema } from './schema';
+export declare function parse(input: string, schema: Schema): Query;

package/dist/query/parser.js

@@ -0,0 +1,181 @@
+// ─────────────────────────────────────────────────────────────────────────
+// Layer 2 — a tolerant, error-recovering parser.
+//
+// Hand-written scanner (not a strict grammar generator) precisely BECAUSE the
+// operators are "free for all": we must parse partial input (`artist:` with no
+// value, for autocomplete) and slightly-wrong input (a malformed clause must
+// degrade to free text, never throw). Output is the serialisable AST in ast.ts.
+//
+// Textual forms understood:
+//   artist:"Daft Punk"          → contains
+//   artist!:bootleg             → not_contains
+//   year>=2021  released<2020   → numeric/date comparisons
+//   status=released  by!=me     → is / is not
+//   genre in (house, techno)    → any of
+//   year..2021..2024            → range  (field..a..b)  also  field:a..b
+//   free floating words         → TextNode (full-text)
+//   AND / and                   → ignored separator (clauses are implicitly AND)
+// ─────────────────────────────────────────────────────────────────────────
+import { findField, operatorByCode, operatorsFor } from './schema';
+const IDENT = /[A-Za-z_][\w-]*/y;
+// Longest operator codes first so `>=` wins over `>`.
+const OP_CODES = ['!:', '!=', '>=', '<=', ':', '=', '>', '<'];
+function skipWs(sc) {
+    while (sc.i < sc.s.length && /\s/.test(sc.s[sc.i]))
+        sc.i++;
+}
+/** Read a value token: a "quoted string", or a bare run up to whitespace. */
+function readValue(sc) {
+    skipWsInline(sc);
+    if (sc.s[sc.i] === '"' || sc.s[sc.i] === "'") {
+        const quote = sc.s[sc.i];
+        const start = ++sc.i;
+        while (sc.i < sc.s.length && sc.s[sc.i] !== quote)
+            sc.i++;
+        const value = sc.s.slice(start, sc.i);
+        if (sc.s[sc.i] === quote)
+            sc.i++; // consume closing quote
+        return { value, end: sc.i };
+    }
+    const start = sc.i;
+    while (sc.i < sc.s.length &&
+        !/\s/.test(sc.s[sc.i]) &&
+        sc.s[sc.i] !== ',' &&
+        sc.s[sc.i] !== ')' &&
+        // stop at a `..` range separator so `a..b` splits into two values
+        !sc.s.startsWith('..', sc.i))
+        sc.i++;
+    return { value: sc.s.slice(start, sc.i), end: sc.i };
+}
+// Only skip spaces/tabs, never cross to a new token boundary semantics; used so
+// `artist: foo` (space after colon) still attaches `foo` as the value.
+function skipWsInline(sc) {
+    while (sc.i < sc.s.length && (sc.s[sc.i] === ' ' || sc.s[sc.i] === '\t'))
+        sc.i++;
+}
+function matchOp(s, i) {
+    for (const code of OP_CODES) {
+        if (s.startsWith(code, i))
+            return { code, len: code.length };
+    }
+    return null;
+}
+export function parse(input, schema) {
+    const sc = { s: input, i: 0 };
+    const nodes = [];
+    while (sc.i < sc.s.length) {
+        skipWs(sc);
+        if (sc.i >= sc.s.length)
+            break;
+        const clauseStart = sc.i;
+        // Try to read an identifier (potential field name).
+        IDENT.lastIndex = sc.i;
+        const m = IDENT.exec(sc.s);
+        if (m && m.index === sc.i) {
+            const ident = m[0];
+            const afterIdent = sc.i + ident.length;
+            // `AND` / `and` — implicit-AND separator, skip it.
+            if (ident.toUpperCase() === 'AND') {
+                sc.i = afterIdent;
+                continue;
+            }
+            const field = findField(schema, ident);
+            // Look for an operator right after the identifier (allow inline spaces).
+            let j = afterIdent;
+            while (sc.s[j] === ' ')
+                j++;
+            const inKeyword = sc.s.slice(j, j + 3).toLowerCase() === 'in ' || sc.s.slice(j) === 'in';
+            const opMatch = matchOp(sc.s, j);
+            if (field && (opMatch || inKeyword)) {
+                const node = readFilter(sc, field, clauseStart, j, opMatch, inKeyword);
+                if (node) {
+                    nodes.push(node);
+                    continue;
+                }
+            }
+        }
+        // Fallback: consume one whitespace-delimited word as free text.
+        const wStart = sc.i;
+        while (sc.i < sc.s.length && !/\s/.test(sc.s[sc.i]))
+            sc.i++;
+        const word = sc.s.slice(wStart, sc.i);
+        if (word) {
+            const last = nodes[nodes.length - 1];
+            if (last && last.kind === 'text') {
+                last.value += ` ${word}`;
+                last.span[1] = sc.i;
+            }
+            else {
+                nodes.push({ kind: 'text', value: word, span: [wStart, sc.i] });
+            }
+        }
+    }
+    return { nodes };
+}
+function readFilter(sc, field, clauseStart, opPos, opMatch, inKeyword) {
+    const legal = operatorsFor(field);
+    if (inKeyword) {
+        sc.i = opPos + 2; // past `in`
+        skipWsInline(sc);
+        if (sc.s[sc.i] === '(')
+            sc.i++;
+        const values = [];
+        while (sc.i < sc.s.length && sc.s[sc.i] !== ')') {
+            skipWsInline(sc);
+            if (sc.s[sc.i] === ',') {
+                sc.i++;
+                continue;
+            }
+            if (sc.s[sc.i] === ')')
+                break;
+            const { value } = readValue(sc);
+            if (value)
+                values.push(value);
+            else
+                break;
+        }
+        if (sc.s[sc.i] === ')')
+            sc.i++;
+        const op = legal.find((o) => o.id === 'in');
+        if (!op)
+            return null;
+        return { kind: 'filter', field: field.name, op: 'in', values, span: [clauseStart, sc.i] };
+    }
+    if (!opMatch)
+        return null;
+    const opCode = opMatch.code;
+    let op = operatorByCode(opCode);
+    // `:` means contains for strings but `is` (eq) for non-string fields.
+    if (op && !legal.some((o) => o.id === op?.id)) {
+        if (opCode === ':')
+            op = legal.find((o) => o.id === 'eq') ?? op;
+    }
+    if (!op || !legal.some((o) => o.id === op?.id)) {
+        // Operator not legal for this field → degrade: don't consume, treat as text.
+        return null;
+    }
+    sc.i = opPos + opMatch.len;
+    const first = readValue(sc);
+    // Range form: a..b
+    if (sc.s.startsWith('..', sc.i)) {
+        sc.i += 2;
+        const second = readValue(sc);
+        const rangeOp = operatorsFor(field).find((o) => o.id === 'range');
+        if (rangeOp) {
+            return {
+                kind: 'filter',
+                field: field.name,
+                op: 'range',
+                values: [first.value, second.value],
+                span: [clauseStart, sc.i],
+            };
+        }
+    }
+    return {
+        kind: 'filter',
+        field: field.name,
+        op: op.id,
+        values: [first.value],
+        span: [clauseStart, sc.i],
+    };
+}

package/dist/query/query.d.ts

@@ -0,0 +1,8 @@
+import { type FilterNode, type Query } from './ast';
+/** AST → canonical textual query (round-trips through the parser). */
+export declare function serialize(q: Query): string;
+export declare function serializeFilter(f: FilterNode): string;
+export declare function toSql(q: Query, table?: string): string;
+type Row = Record<string, unknown>;
+export declare function compilePredicate(q: Query): (row: Row) => boolean;
+export {};

package/dist/query/query.js

@@ -0,0 +1,128 @@
+// ─────────────────────────────────────────────────────────────────────────
+// AST consumers: serialise back to the textual query (for the code editor and
+// the URL), compile to a human-readable SQL-ish WHERE (to prove the filter
+// "properly propagates to backend & database"), and compile to a JS predicate
+// (our fake in-memory backend).
+// ─────────────────────────────────────────────────────────────────────────
+import { filters, freeText } from './ast';
+import { operatorById } from './schema';
+function quoteIfNeeded(v) {
+    return /[\s,()]/.test(v) || v === '' ? `"${v}"` : v;
+}
+/** AST → canonical textual query (round-trips through the parser). */
+export function serialize(q) {
+    const parts = [];
+    for (const f of filters(q))
+        parts.push(serializeFilter(f));
+    const text = freeText(q);
+    if (text)
+        parts.push(text);
+    return parts.join(' ');
+}
+export function serializeFilter(f) {
+    const op = operatorById(f.op);
+    if (!op)
+        return '';
+    if (f.op === 'in')
+        return `${f.field} in (${f.values.map(quoteIfNeeded).join(', ')})`;
+    if (f.op === 'range')
+        return `${f.field}:${quoteIfNeeded(f.values[0])}..${quoteIfNeeded(f.values[1])}`;
+    return `${f.field}${op.code}${quoteIfNeeded(f.values[0] ?? '')}`;
+}
+// ── SQL-ish compiler (illustrative — what the server would emit) ────────────
+const SQL_OP = {
+    eq: '=',
+    ne: '<>',
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+};
+export function toSql(q, table = 'tracks') {
+    const clauses = [];
+    for (const f of filters(q)) {
+        const col = f.field;
+        const v = (s) => `'${s.replace(/'/g, "''")}'`;
+        switch (f.op) {
+            case 'contains':
+                clauses.push(`${col} ILIKE '%${f.values[0]}%'`);
+                break;
+            case 'not_contains':
+                clauses.push(`${col} NOT ILIKE '%${f.values[0]}%'`);
+                break;
+            case 'in':
+                clauses.push(`${col} IN (${f.values.map(v).join(', ')})`);
+                break;
+            case 'range':
+                clauses.push(`${col} BETWEEN ${v(f.values[0])} AND ${v(f.values[1])}`);
+                break;
+            default:
+                clauses.push(`${col} ${SQL_OP[f.op]} ${v(f.values[0] ?? '')}`);
+        }
+    }
+    const text = freeText(q);
+    if (text)
+        clauses.push(`to_tsvector(title) @@ plainto_tsquery(${`'${text.replace(/'/g, "''")}'`})`);
+    const where = clauses.length ? clauses.join('\n  AND ') : 'TRUE';
+    return `SELECT * FROM ${table}\nWHERE ${where};`;
+}
+function asNumber(v) {
+    if (typeof v === 'number')
+        return v;
+    const s = String(v).trim();
+    // Plain integer/decimal (a year "2000", a play count) — take it literally.
+    // Guard against Date.parse swallowing "2000" as a year-timestamp.
+    if (/^-?\d+(\.\d+)?$/.test(s))
+        return Number(s);
+    const d = Date.parse(s); // real dates like "2021-02-01" compare by epoch ms
+    if (!Number.isNaN(d))
+        return d;
+    return Number(s);
+}
+function matchFilter(f, row) {
+    const cell = row[f.field];
+    const target = f.values[0] ?? '';
+    const cellStr = String(cell ?? '').toLowerCase();
+    switch (f.op) {
+        case 'contains':
+            return cellStr.includes(target.toLowerCase());
+        case 'not_contains':
+            return !cellStr.includes(target.toLowerCase());
+        case 'eq':
+            return cellStr === target.toLowerCase();
+        case 'ne':
+            return cellStr !== target.toLowerCase();
+        case 'in':
+            return f.values.map((x) => x.toLowerCase()).includes(cellStr);
+        case 'range':
+            return asNumber(cell) >= asNumber(f.values[0]) && asNumber(cell) <= asNumber(f.values[1]);
+        case 'gt':
+            return asNumber(cell) > asNumber(target);
+        case 'gte':
+            return asNumber(cell) >= asNumber(target);
+        case 'lt':
+            return asNumber(cell) < asNumber(target);
+        case 'lte':
+            return asNumber(cell) <= asNumber(target);
+        default:
+            return true;
+    }
+}
+export function compilePredicate(q) {
+    const fs = filters(q);
+    const text = freeText(q).toLowerCase();
+    return (row) => {
+        for (const f of fs) {
+            if (f.values.every((v) => v === ''))
+                continue; // ignore incomplete clauses
+            if (!matchFilter(f, row))
+                return false;
+        }
+        if (text) {
+            const hay = Object.values(row).join(' ').toLowerCase();
+            if (!hay.includes(text))
+                return false;
+        }
+        return true;
+    };
+}

package/dist/query/schema.d.ts

@@ -0,0 +1,60 @@
+export type FieldType = 'string' | 'enum' | 'id' | 'date' | 'number' | 'bool';
+/** A comparison operator. `code` is how it serialises in the textual query. */
+export type OperatorId = 'contains' | 'not_contains' | 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'range';
+export interface Operator {
+    id: OperatorId;
+    /** Human label shown in the operator dropdown (YouTrack "一致する" etc.). */
+    label: string;
+    /** Textual form used by the code parser/serialiser, e.g. `>=`, `:`, `!:`. */
+    code: string;
+    /** Types this operator can apply to. */
+    types: FieldType[];
+    /** range/in take two / many values. */
+    arity?: 'one' | 'two' | 'many';
+}
+export declare const OPERATORS: Operator[];
+export interface ValueOption {
+    value: string;
+    label: string;
+    /** Optional secondary line (e.g. an email under a username). */
+    hint?: string;
+}
+/** Resolves candidate values for a field given the user's partial input. */
+export type ValueProvider = (query: string) => ValueOption[] | Promise<ValueOption[]>;
+export interface FieldDef {
+    /** Canonical name, used in the serialised query (e.g. `artist`). */
+    name: string;
+    /** Display label (e.g. `Artist`). */
+    label: string;
+    type: FieldType;
+    /** Alternate spellings accepted by the parser (e.g. `by` → assignee). */
+    aliases?: string[];
+    /** Static options, or omit and supply `provider` for async lookups. */
+    options?: ValueOption[];
+    provider?: ValueProvider;
+    /**
+     * Restrict the operators offered for this field to exactly this set (in
+     * catalogue order). When omitted, all operators legal for the field's `type`
+     * are offered. Use this to mirror a backend registry's per-field whitelist so
+     * the dropdown — and the parser's legal-op check — match what the server
+     * actually accepts.
+     */
+    operators?: OperatorId[];
+    /** Placeholder shown in the value step of the dropdown. */
+    valuePlaceholder?: string;
+}
+export interface Schema {
+    fields: FieldDef[];
+}
+/** Operators legal for a given field, in catalogue order. When the field
+ *  declares an explicit `operators` whitelist that takes precedence over the
+ *  type-derived set (the whitelist is authoritative); otherwise every operator
+ *  legal for the field's `type` is returned. */
+export declare function operatorsFor(field: FieldDef): Operator[];
+/** The default operator picked when a user selects a field (YouTrack-like). */
+export declare function defaultOperator(field: FieldDef): Operator;
+export declare function findField(schema: Schema, token: string): FieldDef | undefined;
+export declare function operatorByCode(code: string): Operator | undefined;
+export declare function operatorById(id: OperatorId): Operator | undefined;
+/** Resolve a field's value options (sync wrapper that always returns a promise). */
+export declare function resolveValues(field: FieldDef, query: string): Promise<ValueOption[]>;

package/dist/query/schema.js

@@ -0,0 +1,54 @@
+// ─────────────────────────────────────────────────────────────────────────
+// Layer 1 — the schema / field registry.
+//
+// The single source of truth that drives BOTH the autocomplete UI and the
+// backend compiler. For each searchable field we declare its type, aliases,
+// the operators it allows and a value provider (static enum or async lookup).
+// Nothing here is UI: it's plain data a host app supplies.
+// ─────────────────────────────────────────────────────────────────────────
+// The full operator catalogue. The order here is the order shown in dropdowns.
+export const OPERATORS = [
+    { id: 'contains', label: 'includes', code: ':', types: ['string'] },
+    { id: 'not_contains', label: 'does not include', code: '!:', types: ['string'] },
+    { id: 'eq', label: 'is', code: '=', types: ['enum', 'id', 'number', 'bool', 'date'] },
+    { id: 'ne', label: 'is not', code: '!=', types: ['enum', 'id', 'number', 'bool', 'date'] },
+    { id: 'gt', label: 'greater than', code: '>', types: ['number', 'date'] },
+    { id: 'gte', label: 'greater or equal', code: '>=', types: ['number', 'date'] },
+    { id: 'lt', label: 'less than', code: '<', types: ['number', 'date'] },
+    { id: 'lte', label: 'less or equal', code: '<=', types: ['number', 'date'] },
+    { id: 'in', label: 'any of', code: 'in', types: ['enum', 'id'], arity: 'many' },
+    { id: 'range', label: 'in range', code: '..', types: ['date', 'number'], arity: 'two' },
+];
+/** Operators legal for a given field, in catalogue order. When the field
+ *  declares an explicit `operators` whitelist that takes precedence over the
+ *  type-derived set (the whitelist is authoritative); otherwise every operator
+ *  legal for the field's `type` is returned. */
+export function operatorsFor(field) {
+    if (field.operators) {
+        const allow = new Set(field.operators);
+        return OPERATORS.filter((op) => allow.has(op.id));
+    }
+    return OPERATORS.filter((op) => op.types.includes(field.type));
+}
+/** The default operator picked when a user selects a field (YouTrack-like). */
+export function defaultOperator(field) {
+    return operatorsFor(field)[0];
+}
+export function findField(schema, token) {
+    const t = token.toLowerCase();
+    return schema.fields.find((f) => f.name.toLowerCase() === t || f.aliases?.some((a) => a.toLowerCase() === t));
+}
+export function operatorByCode(code) {
+    return OPERATORS.find((op) => op.code === code);
+}
+export function operatorById(id) {
+    return OPERATORS.find((op) => op.id === id);
+}
+/** Resolve a field's value options (sync wrapper that always returns a promise). */
+export async function resolveValues(field, query) {
+    if (field.provider)
+        return field.provider(query);
+    const opts = field.options ?? [];
+    const q = query.toLowerCase();
+    return q ? opts.filter((o) => o.label.toLowerCase().includes(q)) : opts;
+}

package/dist/query/suggest.d.ts

@@ -0,0 +1,33 @@
+import { type Schema } from './schema';
+export type SuggestKind = 'field' | 'operator' | 'value';
+export interface Suggestion {
+    /** What to show on the row. */
+    label: string;
+    /** Secondary, dimmed line. */
+    hint?: string;
+    /** Right-aligned monospace token (operator code / field name). */
+    code?: string;
+    /** The string to splice into the query when accepted. */
+    insert: string;
+    /** Caret position after the insert (absolute index). */
+    caret: number;
+    /** When true, keep the dropdown open and advance to the next step. */
+    advance?: boolean;
+}
+export interface SuggestState {
+    kind: SuggestKind;
+    /** [start, end) of the token region these suggestions replace. */
+    span: [number, number];
+    items: Suggestion[];
+}
+/** The whitespace-delimited token under the caret (quotes count as non-ws). */
+export declare function activeToken(s: string, pos: number): {
+    start: number;
+    end: number;
+    raw: string;
+};
+/**
+ * Compute the suggestion state for the caret. Value lookups are async (they may
+ * hit the network), so this returns a promise. `null` means "no dropdown".
+ */
+export declare function suggest(schema: Schema, s: string, pos: number): Promise<SuggestState | null>;

package/dist/query/suggest.js

@@ -0,0 +1,125 @@
+// ─────────────────────────────────────────────────────────────────────────
+// Autocomplete engine — the SECOND consumer of the schema (the first is the
+// compiler). Given the raw string + caret position it figures out which of the
+// three YouTrack-style steps we're in (field → operator → value) and produces
+// the suggestion list + the text edit to apply when one is accepted.
+//
+// This is pure logic, deliberately UI-free so the Svelte organism stays dumb.
+// ─────────────────────────────────────────────────────────────────────────
+import { findField, operatorsFor, resolveValues, } from './schema';
+// Longest first so `>=`/`!:` win over `>`/`:`.
+const OP_CODES = ['!:', '!=', '>=', '<=', ':', '=', '>', '<'];
+/** The whitespace-delimited token under the caret (quotes count as non-ws). */
+export function activeToken(s, pos) {
+    let start = pos;
+    while (start > 0 && !/\s/.test(s[start - 1]))
+        start--;
+    let end = pos;
+    while (end < s.length && !/\s/.test(s[end]))
+        end++;
+    return { start, end, raw: s.slice(start, end) };
+}
+/** Split a token into field / operator-code / value parts (earliest op wins). */
+function splitToken(raw) {
+    let best = -1;
+    let bestCode = null;
+    for (const code of OP_CODES) {
+        const idx = raw.indexOf(code);
+        if (idx === -1)
+            continue;
+        // earliest position wins; on a tie the longer code wins (handled by order).
+        if (best === -1 || idx < best) {
+            best = idx;
+            bestCode = code;
+        }
+    }
+    if (bestCode === null)
+        return { field: raw, opCode: null, value: '' };
+    return {
+        field: raw.slice(0, best),
+        opCode: bestCode,
+        value: raw.slice(best + bestCode.length),
+    };
+}
+function unquote(v) {
+    return v.replace(/^["']|["']$/g, '');
+}
+function quoteIfNeeded(v) {
+    return /[\s,()]/.test(v) ? `"${v}"` : v;
+}
+function fieldSuggestions(schema, frag, span) {
+    const q = frag.toLowerCase();
+    const items = schema.fields
+        .filter((f) => !q ||
+        f.name.toLowerCase().includes(q) ||
+        f.label.toLowerCase().includes(q) ||
+        f.aliases?.some((a) => a.toLowerCase().includes(q)))
+        .map((f) => {
+        const op = operatorsFor(f)[0];
+        const insert = `${f.name}${op.code}`;
+        return {
+            label: f.label,
+            hint: f.aliases?.length ? `aka ${f.aliases.join(', ')}` : f.type,
+            code: f.name,
+            insert,
+            caret: span[0] + insert.length,
+            advance: true,
+        };
+    });
+    return { kind: 'field', span, items };
+}
+function operatorSuggestions(field, span) {
+    const items = operatorsFor(field).map((op) => {
+        const insert = `${field.name}${op.code}`;
+        return {
+            label: op.label,
+            code: op.code,
+            insert,
+            caret: span[0] + insert.length,
+            advance: true,
+        };
+    });
+    return { kind: 'operator', span, items };
+}
+function buildValueState(field, opCode, span, options) {
+    const items = options.map((o) => {
+        const insert = `${field.name}${opCode}${quoteIfNeeded(o.value)}`;
+        return {
+            label: o.label,
+            hint: o.hint,
+            insert,
+            caret: span[0] + insert.length,
+        };
+    });
+    return { kind: 'value', span, items };
+}
+/**
+ * Compute the suggestion state for the caret. Value lookups are async (they may
+ * hit the network), so this returns a promise. `null` means "no dropdown".
+ */
+export async function suggest(schema, s, pos) {
+    const { start, end, raw } = activeToken(s, pos);
+    const span = [start, end];
+    // Empty caret position (between tokens or empty input) → offer all fields.
+    if (raw === '')
+        return fieldSuggestions(schema, '', span);
+    const { field: fieldFrag, opCode, value } = splitToken(raw);
+    const field = findField(schema, fieldFrag);
+    // No operator typed yet.
+    if (opCode === null) {
+        // Exact field match → it's time to pick an operator.
+        if (field && fieldFrag.toLowerCase() === field.name.toLowerCase()) {
+            return operatorSuggestions(field, span);
+        }
+        // Otherwise we're still completing the field name.
+        return fieldSuggestions(schema, fieldFrag, span);
+    }
+    // Operator present but field unknown → nothing useful to suggest.
+    if (!field)
+        return null;
+    // Operator present → suggest values (async; filtered by what's typed).
+    const opts = await resolveValues(field, unquote(value));
+    if (opts.length === 0)
+        return null;
+    return buildValueState(field, opCode, span, opts);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorsk/tsumikit",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Minimal, dependency-free Svelte 5 + pure-CSS UI kit. Token-driven atoms, molecules & layouts with theming out of the box.",
   "type": "module",
   "license": "MIT",