@dorsk/tsumikit 0.9.6 → 0.11.0

package/dist/components/molecules/Tooltip.svelte

@@ -8,33 +8,50 @@
 	// only opens/closes under our control) and is positioned by the shared
 	// `place()` helper — so, like Popover, it escapes ancestor overflow/transform
 	// clipping and flips/clamps to stay in the viewport. Dependency-free.
+	//
+	// Rich mode: pass a `content` snippet instead of (or as well as — `content`
+	// wins) `text` and the panel renders arbitrary markup: key/value rows, code
+	// ids, CopyButton, small buttons. Closing is then hovercard-style: debounced
+	// by `closeDelay` and cancelled when the pointer (or focus) enters the panel,
+	// so users can move in to select/copy text or click a button. Note the
+	// role="tooltip" caveat: `aria-describedby` flattens the panel to its text.
 	import type { Snippet } from 'svelte';
 	import { place } from '../../floating';
 
 	let {
 		text,
+		content,
 		placement = 'top',
 		delay = 200,
+		closeDelay = 250,
 		trigger
 	}: {
-		text: string;
+		/** Plain-text bubble. Ignored when `content` is provided. */
+		text?: string;
+		/** Rich panel content — makes the panel hover-persistent and selectable. */
+		content?: Snippet;
 		placement?: 'top' | 'bottom' | 'left' | 'right';
+		/** Open delay (ms) on hover. */
 		delay?: number;
+		/** Grace period (ms) before closing — lets the pointer travel into the panel. */
+		closeDelay?: number;
 		trigger: Snippet;
 	} = $props();
 
 	const id = `tip-${Math.random().toString(36).slice(2, 8)}`;
 	let wrapEl = $state<HTMLElement | null>(null);
 	let tipEl = $state<HTMLElement | null>(null);
-	let timer: ReturnType<typeof setTimeout> | undefined;
+	let showTimer: ReturnType<typeof setTimeout> | undefined;
+	let hideTimer: ReturnType<typeof setTimeout> | undefined;
 
 	function reposition() {
 		if (wrapEl && tipEl) place(wrapEl, tipEl, `${placement}-center`, 6);
 	}
 
 	function show() {
-		clearTimeout(timer);
-		timer = setTimeout(() => {
+		clearTimeout(hideTimer); // pointer came back within the grace period
+		clearTimeout(showTimer);
+		showTimer = setTimeout(() => {
 			if (!tipEl || tipEl.matches(':popover-open')) return; // re-entry guard
 			tipEl.showPopover(); // top layer — displayed before we measure it
 			reposition();
@@ -42,12 +59,23 @@
 			addEventListener('resize', reposition);
 		}, delay);
 	}
-	function hide() {
-		clearTimeout(timer);
+	function hideNow() {
+		clearTimeout(showTimer);
+		clearTimeout(hideTimer);
 		if (tipEl?.matches(':popover-open')) tipEl.hidePopover();
 		removeEventListener('scroll', reposition, true);
 		removeEventListener('resize', reposition);
 	}
+	// Debounced close: cancelled if the pointer/focus enters the panel (rich
+	// mode) or returns to the trigger before `closeDelay` elapses.
+	function scheduleHide() {
+		clearTimeout(showTimer);
+		clearTimeout(hideTimer);
+		hideTimer = setTimeout(hideNow, closeDelay);
+	}
+	function cancelHide() {
+		clearTimeout(hideTimer);
+	}
 
 	const FOCUSABLE = 'a[href],button,input,select,textarea,[tabindex]';
 	// Action: wire aria-describedby onto the trigger's focusable element AND the
@@ -58,19 +86,39 @@
 			| HTMLElement
 			| null;
 		target?.setAttribute('aria-describedby', id);
-		const onkey = (e: KeyboardEvent) => e.key === 'Escape' && hide();
+		const onkey = (e: KeyboardEvent) => e.key === 'Escape' && hideNow();
 		node.addEventListener('mouseenter', show);
-		node.addEventListener('mouseleave', hide);
+		node.addEventListener('mouseleave', scheduleHide);
 		node.addEventListener('focusin', show);
-		node.addEventListener('focusout', hide);
+		node.addEventListener('focusout', scheduleHide);
 		node.addEventListener('keydown', onkey);
 		return {
 			destroy() {
 				target?.removeAttribute('aria-describedby');
 				node.removeEventListener('mouseenter', show);
-				node.removeEventListener('mouseleave', hide);
+				node.removeEventListener('mouseleave', scheduleHide);
 				node.removeEventListener('focusin', show);
-				node.removeEventListener('focusout', hide);
+				node.removeEventListener('focusout', scheduleHide);
+				node.removeEventListener('keydown', onkey);
+			}
+		};
+	}
+
+	// Action for the panel: in rich mode it accepts the pointer/focus, which
+	// cancels the pending close (hovercard persistence).
+	function panel(node: HTMLElement) {
+		const onkey = (e: KeyboardEvent) => e.key === 'Escape' && hideNow();
+		node.addEventListener('mouseenter', cancelHide);
+		node.addEventListener('mouseleave', scheduleHide);
+		node.addEventListener('focusin', cancelHide);
+		node.addEventListener('focusout', scheduleHide);
+		node.addEventListener('keydown', onkey);
+		return {
+			destroy() {
+				node.removeEventListener('mouseenter', cancelHide);
+				node.removeEventListener('mouseleave', scheduleHide);
+				node.removeEventListener('focusin', cancelHide);
+				node.removeEventListener('focusout', scheduleHide);
 				node.removeEventListener('keydown', onkey);
 			}
 		};
@@ -81,9 +129,17 @@
 	{@render trigger()}
 </span>
 
-<span bind:this={tipEl} {id} role="tooltip" popover="manual" class="tip">
-	{text}
-</span>
+<div
+	bind:this={tipEl}
+	{id}
+	role="tooltip"
+	popover="manual"
+	class="tip"
+	class:rich={!!content}
+	use:panel
+>
+	{#if content}{@render content()}{:else}{text}{/if}
+</div>
 
 <style>
 	.tip-wrap {
@@ -106,6 +162,15 @@
 		white-space: normal;
 		pointer-events: none; /* non-interactive: never steals hover/clicks */
 	}
+	/* Rich panel: interactive + selectable so the user can move the pointer in
+	   to copy an id or click a button (the close grace period allows the trip). */
+	.tip.rich {
+		pointer-events: auto;
+		user-select: text;
+		max-width: min(22rem, calc(100vw - 2 * var(--sp-3)));
+		padding: var(--sp-2);
+		border-radius: var(--r-md);
+	}
 	/* Fade/scale in when shown (skipped under reduced-motion via the global rule). */
 	.tip:popover-open {
 		animation: tip-in 0.12s var(--ease);

package/dist/components/molecules/Tooltip.svelte.d.ts

@@ -1,8 +1,14 @@
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
-    text: string;
+    /** Plain-text bubble. Ignored when `content` is provided. */
+    text?: string;
+    /** Rich panel content — makes the panel hover-persistent and selectable. */
+    content?: Snippet;
     placement?: 'top' | 'bottom' | 'left' | 'right';
+    /** Open delay (ms) on hover. */
     delay?: number;
+    /** Grace period (ms) before closing — lets the pointer travel into the panel. */
+    closeDelay?: number;
     trigger: Snippet;
 };
 declare const Tooltip: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/index.d.ts

@@ -50,7 +50,7 @@ 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 { type AndNode, activeToken, compilePredicate, defaultOperator, type ExprNode, type FieldDef, type FieldType, type FilterNode, filters, findField, freeText, type LeafNode, type NotNode, OPERATORS, type Operator, type OperatorId, type OrNode, 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, walk, } 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

@@ -62,7 +62,7 @@ export { default as Truncate } from './components/molecules/Truncate.svelte';
 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 { activeToken, compilePredicate, defaultOperator, filters, findField, freeText, OPERATORS, operatorByCode, operatorById, operatorsFor, parse, resolveValues, serialize, serializeFilter, suggest, toSql, walk, } 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

@@ -15,10 +15,38 @@ export interface TextNode {
     value: string;
     span: [number, number];
 }
-export type QueryNode = FilterNode | TextNode;
+/** Conjunction — every child must match. Implicit between adjacent clauses. */
+export interface AndNode {
+    kind: 'and';
+    children: ExprNode[];
+}
+/** Disjunction — at least one child must match. Written with `OR`. */
+export interface OrNode {
+    kind: 'or';
+    children: ExprNode[];
+}
+/** Boolean negation of a whole sub-expression. Written with `NOT`. */
+export interface NotNode {
+    kind: 'not';
+    child: ExprNode;
+}
+/** A leaf of the expression tree. */
+export type LeafNode = FilterNode | TextNode;
+/** Any node in the boolean expression tree. */
+export type ExprNode = AndNode | OrNode | NotNode | LeafNode;
+/**
+ * Backwards-compatible alias for a leaf node. Historically `QueryNode` was the
+ * only node type (the tree was a flat list of these); it now names the leaf
+ * union so existing type imports keep resolving.
+ */
+export type QueryNode = LeafNode;
 export interface Query {
-    /** Clauses are AND-combined (YouTrack semantics). */
-    nodes: QueryNode[];
+    /** Root of the boolean expression tree, or `null` for an empty query. */
+    root: ExprNode | null;
 }
+/** Depth-first walk of every node in the tree (leaves included). */
+export declare function walk(node: ExprNode | null, visit: (n: ExprNode) => void): void;
+/** Every filter leaf in the tree, in source order. */
 export declare function filters(q: Query): FilterNode[];
+/** All free-text leaves joined — the flat full-text fragment. */
 export declare function freeText(q: Query): string;

package/dist/query/ast.js

@@ -3,14 +3,44 @@
 // 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).
+//
+// The tree is a boolean expression: `And` / `Or` / `Not` nodes wrap the leaf
+// `FilterNode` / `TextNode`. The leaf shapes are unchanged from the flat-AND
+// era, so `schema.ts` and value providers are untouched. A query with no
+// explicit `OR` / `NOT` / parens parses to a single `And` of its leaves — the
+// same result set as the old implicit-AND clause list.
 // ─────────────────────────────────────────────────────────────────────────
+/** Depth-first walk of every node in the tree (leaves included). */
+export function walk(node, visit) {
+    if (!node)
+        return;
+    visit(node);
+    switch (node.kind) {
+        case 'and':
+        case 'or':
+            for (const c of node.children)
+                walk(c, visit);
+            break;
+        case 'not':
+            walk(node.child, visit);
+            break;
+    }
+}
+/** Every filter leaf in the tree, in source order. */
 export function filters(q) {
-    return q.nodes.filter((n) => n.kind === 'filter');
+    const out = [];
+    walk(q.root, (n) => {
+        if (n.kind === 'filter')
+            out.push(n);
+    });
+    return out;
 }
+/** All free-text leaves joined — the flat full-text fragment. */
 export function freeText(q) {
-    return q.nodes
-        .filter((n) => n.kind === 'text')
-        .map((n) => n.value)
-        .join(' ')
-        .trim();
+    const parts = [];
+    walk(q.root, (n) => {
+        if (n.kind === 'text')
+            parts.push(n.value);
+    });
+    return parts.join(' ').trim();
 }

package/dist/query/index.d.ts

@@ -1,5 +1,5 @@
-export type { FilterNode, Query, QueryNode, TextNode } from './ast';
-export { filters, freeText } from './ast';
+export type { AndNode, ExprNode, FilterNode, LeafNode, NotNode, OrNode, Query, QueryNode, TextNode, } from './ast';
+export { filters, freeText, walk } from './ast';
 export { parse } from './parser';
 export { compilePredicate, serialize, serializeFilter, toSql } from './query';
 export type { FieldDef, FieldType, Operator, OperatorId, Schema, ValueOption, ValueProvider, } from './schema';

package/dist/query/index.js

@@ -2,7 +2,7 @@
 // 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 { filters, freeText, walk } from './ast';
 export { parse } from './parser';
 export { compilePredicate, serialize, serializeFilter, toSql } from './query';
 export { defaultOperator, findField, OPERATORS, operatorByCode, operatorById, operatorsFor, resolveValues, } from './schema';

package/dist/query/parser.js

@@ -1,12 +1,19 @@
 // ─────────────────────────────────────────────────────────────────────────
-// Layer 2 — a tolerant, error-recovering parser.
+// Layer 2 — a tolerant, error-recovering recursive-descent 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.
+// Hand-written (not a grammar generator) precisely BECAUSE the input is "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 expression tree in
+// ast.ts.
 //
-// Textual forms understood:
+// Grammar (precedence NOT > AND > OR; AND is implicit between adjacent terms):
+//   orExpr   := andExpr ( OR andExpr )*
+//   andExpr  := notExpr ( (AND)? notExpr )*
+//   notExpr  := (NOT)? primary
+//   primary  := '(' orExpr ')' | filter | text-word
+//
+// Leaf textual forms understood:
 //   artist:"Daft Punk"          → contains
 //   artist!:bootleg             → not_contains
 //   year>=2021  released<2020   → numeric/date comparisons
@@ -14,16 +21,26 @@
 //   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)
+//
+// Error recovery: unmatched `)` is ignored, a missing `)` closes at end of
+// input, a dangling AND/OR/NOT with no operand collapses to its operand, and an
+// empty group yields nothing. The parser never throws.
 // ─────────────────────────────────────────────────────────────────────────
 import { findField, operatorByCode, operatorsFor } from './schema';
 const IDENT = /[A-Za-z_][\w-]*/y;
 // Longest operator codes first so `>=` wins over `>`.
 const OP_CODES = ['!:', '!=', '>=', '<=', ':', '=', '>', '<'];
+const KEYWORDS = new Set(['AND', 'OR', 'NOT']);
 function skipWs(sc) {
     while (sc.i < sc.s.length && /\s/.test(sc.s[sc.i]))
         sc.i++;
 }
+// Only skip spaces/tabs; used so `artist: foo` (space after colon) still
+// attaches `foo` as the value without crossing a real token boundary.
+function skipWsInline(sc) {
+    while (sc.i < sc.s.length && (sc.s[sc.i] === ' ' || sc.s[sc.i] === '\t'))
+        sc.i++;
+}
 /** Read a value token: a "quoted string", or a bare run up to whitespace. */
 function readValue(sc) {
     skipWsInline(sc);
@@ -42,17 +59,12 @@ function readValue(sc) {
         !/\s/.test(sc.s[sc.i]) &&
         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))
@@ -60,57 +72,160 @@ function matchOp(s, i) {
     }
     return null;
 }
+/**
+ * Peek at an upcoming connective keyword (AND / OR / NOT) without consuming it.
+ * A keyword only counts when it stands alone — i.e. it is NOT immediately
+ * followed by an operator, so `and:foo` or `or=x` stay field clauses. Returns
+ * the keyword and the index just past it, or null.
+ */
+function peekKeyword(sc) {
+    let j = sc.i;
+    while (j < sc.s.length && /\s/.test(sc.s[j]))
+        j++;
+    IDENT.lastIndex = j;
+    const m = IDENT.exec(sc.s);
+    if (!m || m.index !== j)
+        return null;
+    const word = m[0].toUpperCase();
+    if (!KEYWORDS.has(word))
+        return null;
+    // If an operator follows the ident it is a field name, not a connective.
+    let k = j + m[0].length;
+    while (sc.s[k] === ' ')
+        k++;
+    if (matchOp(sc.s, k))
+        return null;
+    return { word, next: j + m[0].length };
+}
 export function parse(input, schema) {
     const sc = { s: input, i: 0 };
-    const nodes = [];
-    while (sc.i < sc.s.length) {
+    const root = parseOr(sc, schema);
+    return { root };
+}
+// orExpr := andExpr ( OR andExpr )*
+function parseOr(sc, schema) {
+    const children = [];
+    const first = parseAnd(sc, schema);
+    if (first)
+        children.push(first);
+    for (;;) {
+        const kw = peekKeyword(sc);
+        if (!kw || kw.word !== 'OR')
+            break;
+        sc.i = kw.next;
+        const next = parseAnd(sc, schema);
+        if (next)
+            children.push(next);
+    }
+    if (children.length === 0)
+        return first ?? null;
+    if (children.length === 1)
+        return children[0];
+    return { kind: 'or', children };
+}
+// andExpr := notExpr ( (AND)? notExpr )*
+function parseAnd(sc, schema) {
+    const children = [];
+    for (;;) {
         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;
-                }
-            }
+        if (sc.s[sc.i] === ')')
+            break;
+        const kw = peekKeyword(sc);
+        if (kw?.word === 'OR')
+            break; // let the OR level handle it
+        let explicitAnd = false;
+        if (kw?.word === 'AND') {
+            sc.i = kw.next;
+            explicitAnd = true;
         }
-        // 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] });
-            }
+        const before = sc.i;
+        const node = parseNot(sc, schema);
+        if (!node) {
+            // No progress → avoid an infinite loop on stray tokens.
+            if (sc.i === before)
+                break;
+            continue;
+        }
+        // Merge adjacent implicit-AND free-text words into one TextNode so a bare
+        // `foo bar` still matches the contiguous phrase (old flat-AND behaviour).
+        const last = children[children.length - 1];
+        if (!explicitAnd && node.kind === 'text' && last && last.kind === 'text') {
+            last.value += ` ${node.value}`;
+            last.span[1] = node.span[1];
+            continue;
+        }
+        children.push(node);
+    }
+    if (children.length === 0)
+        return null;
+    if (children.length === 1)
+        return children[0];
+    return { kind: 'and', children };
+}
+// notExpr := (NOT)? primary
+function parseNot(sc, schema) {
+    const kw = peekKeyword(sc);
+    if (kw?.word === 'NOT') {
+        sc.i = kw.next;
+        const child = parseNot(sc, schema);
+        if (!child)
+            return null; // dangling NOT → nothing
+        return { kind: 'not', child };
+    }
+    return parsePrimary(sc, schema);
+}
+// primary := '(' orExpr ')' | filter | text-word
+function parsePrimary(sc, schema) {
+    skipWs(sc);
+    if (sc.i >= sc.s.length)
+        return null;
+    // Parenthesised group.
+    if (sc.s[sc.i] === '(') {
+        sc.i++;
+        const inner = parseOr(sc, schema);
+        skipWs(sc);
+        if (sc.s[sc.i] === ')')
+            sc.i++; // tolerate a missing close paren
+        return inner; // empty group → null
+    }
+    if (sc.s[sc.i] === ')')
+        return null;
+    // A connective keyword here isn't a leaf; let the caller handle it.
+    if (peekKeyword(sc))
+        return null;
+    const leaf = readLeaf(sc, schema);
+    return leaf;
+}
+/** Read a single leaf: a `field op value` filter, or one free-text word. */
+function readLeaf(sc, schema) {
+    const clauseStart = sc.i;
+    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;
+        const field = findField(schema, ident);
+        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)
+                return node;
         }
     }
-    return { nodes };
+    // Fallback: consume one word (up to whitespace or a paren) as free text.
+    const wStart = sc.i;
+    while (sc.i < sc.s.length && !/\s/.test(sc.s[sc.i]) && sc.s[sc.i] !== '(' && sc.s[sc.i] !== ')')
+        sc.i++;
+    const word = sc.s.slice(wStart, sc.i);
+    if (!word)
+        return null;
+    return { kind: 'text', value: word, span: [wStart, sc.i] };
 }
 function readFilter(sc, field, clauseStart, opPos, opMatch, inKeyword) {
     const legal = operatorsFor(field);

package/dist/query/query.d.ts

@@ -1,4 +1,4 @@
-import { type FilterNode, type Query } from './ast';
+import type { FilterNode, 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;

package/dist/query/query.js

@@ -2,22 +2,51 @@
 // 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).
+// (our fake in-memory backend). All three walk the boolean expression tree with
+// correct precedence / grouping / short-circuiting.
 // ─────────────────────────────────────────────────────────────────────────
-import { filters, freeText } from './ast';
 import { operatorById } from './schema';
 function quoteIfNeeded(v) {
     return /[\s,()]/.test(v) || v === '' ? `"${v}"` : v;
 }
+// ── Serialiser (AST → canonical textual query, round-trips through parse) ────
+/** Precedence rank: higher binds tighter. Leaves are atomic. */
+function rank(node) {
+    switch (node.kind) {
+        case 'or':
+            return 1;
+        case 'and':
+            return 2;
+        case 'not':
+            return 3;
+        default:
+            return 4; // leaf
+    }
+}
+/** Serialise `node`, wrapping in parens when its precedence is below `min`. */
+function serializeNode(node, min) {
+    const s = serializeBare(node);
+    return rank(node) < min ? `(${s})` : s;
+}
+function serializeBare(node) {
+    switch (node.kind) {
+        case 'filter':
+            return serializeFilter(node);
+        case 'text':
+            return node.value;
+        case 'not':
+            // Child must bind at least as tight as NOT, else parenthesise.
+            return `NOT ${serializeNode(node.child, 3)}`;
+        case 'and':
+            // Children need to sit above OR precedence; AND itself is implicit (space).
+            return node.children.map((c) => serializeNode(c, 2)).join(' ');
+        case 'or':
+            return node.children.map((c) => serializeNode(c, 1)).join(' OR ');
+    }
+}
 /** 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(' ');
+    return q.root ? serializeBare(q.root) : '';
 }
 export function serializeFilter(f) {
     const op = operatorById(f.op);
@@ -38,32 +67,41 @@ const SQL_OP = {
     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] ?? '')}`);
-        }
+function sqlLiteral(s) {
+    return `'${s.replace(/'/g, "''")}'`;
+}
+function filterToSql(f) {
+    const col = f.field;
+    switch (f.op) {
+        case 'contains':
+            return `${col} ILIKE '%${f.values[0]}%'`;
+        case 'not_contains':
+            return `${col} NOT ILIKE '%${f.values[0]}%'`;
+        case 'in':
+            return `${col} IN (${f.values.map(sqlLiteral).join(', ')})`;
+        case 'range':
+            return `${col} BETWEEN ${sqlLiteral(f.values[0])} AND ${sqlLiteral(f.values[1])}`;
+        default:
+            return `${col} ${SQL_OP[f.op]} ${sqlLiteral(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';
+}
+/** Serialise a node to a SQL boolean expression, parenthesising sub-groups. */
+function nodeToSql(node) {
+    switch (node.kind) {
+        case 'filter':
+            return filterToSql(node);
+        case 'text':
+            return `to_tsvector(title) @@ plainto_tsquery(${sqlLiteral(node.value)})`;
+        case 'not':
+            return `NOT (${nodeToSql(node.child)})`;
+        case 'and':
+            return node.children.map((c) => `(${nodeToSql(c)})`).join(' AND ');
+        case 'or':
+            return node.children.map((c) => `(${nodeToSql(c)})`).join(' OR ');
+    }
+}
+export function toSql(q, table = 'tracks') {
+    const where = q.root ? nodeToSql(q.root) : 'TRUE';
     return `SELECT * FROM ${table}\nWHERE ${where};`;
 }
 function asNumber(v) {
@@ -108,21 +146,65 @@ function matchFilter(f, row) {
             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) {
+/**
+ * Is this leaf still incomplete (mid-typing)? Such leaves are neutral — they
+ * neither match nor reject — so a half-written clause never changes the result
+ * set, matching the old flat-AND "ignore incomplete clauses" behaviour.
+ */
+function isIncomplete(node) {
+    if (node.kind === 'filter')
+        return node.values.every((v) => v === '');
+    if (node.kind === 'text')
+        return node.value.trim() === '';
+    return false;
+}
+/** Evaluate a node against a row. `null` = neutral (skip / don't constrain). */
+function evalNode(node, row) {
+    if (isIncomplete(node))
+        return null;
+    switch (node.kind) {
+        case 'filter':
+            return matchFilter(node, row);
+        case 'text': {
             const hay = Object.values(row).join(' ').toLowerCase();
-            if (!hay.includes(text))
-                return false;
+            return hay.includes(node.value.trim().toLowerCase());
+        }
+        case 'not': {
+            const inner = evalNode(node.child, row);
+            return inner === null ? null : !inner;
         }
-        return true;
+        case 'and': {
+            let sawReal = false;
+            for (const c of node.children) {
+                const r = evalNode(c, row);
+                if (r === null)
+                    continue; // neutral
+                sawReal = true;
+                if (!r)
+                    return false;
+            }
+            return sawReal ? true : null;
+        }
+        case 'or': {
+            let sawReal = false;
+            for (const c of node.children) {
+                const r = evalNode(c, row);
+                if (r === null)
+                    continue;
+                sawReal = true;
+                if (r)
+                    return true;
+            }
+            return sawReal ? false : null;
+        }
+    }
+}
+export function compilePredicate(q) {
+    const root = q.root;
+    return (row) => {
+        if (!root)
+            return true;
+        const r = evalNode(root, row);
+        return r === null ? true : r;
     };
 }

package/dist/query/suggest.d.ts

@@ -20,13 +20,6 @@ export interface SuggestState {
     span: [number, number];
     items: Suggestion[];
 }
-/**
- * The token under the caret. Whitespace ends a token EXCEPT inside an open
- * quote, so a quoted value containing spaces (`album:"ok computer`) stays one
- * token and keeps the caret in the value step rather than collapsing to an
- * empty token (which would wrongly re-offer fields). A closed quote followed by
- * whitespace starts a fresh token (so the next `field:` can be chained).
- */
 export declare function activeToken(s: string, pos: number): {
     start: number;
     end: number;

package/dist/query/suggest.js

@@ -10,15 +10,19 @@ import { findField, operatorsFor, resolveValues, } from './schema';
 // Longest first so `>=`/`!:` win over `>`/`:`.
 const OP_CODES = ['!:', '!=', '>=', '<=', ':', '=', '>', '<'];
 /**
- * The token under the caret. Whitespace ends a token EXCEPT inside an open
- * quote, so a quoted value containing spaces (`album:"ok computer`) stays one
- * token and keeps the caret in the value step rather than collapsing to an
- * empty token (which would wrongly re-offer fields). A closed quote followed by
- * whitespace starts a fresh token (so the next `field:` can be chained).
+ * The token under the caret. Whitespace — and boolean grouping parens `(` `)` —
+ * end a token EXCEPT inside an open quote, so a quoted value containing spaces
+ * (`album:"ok computer`) stays one token and keeps the caret in the value step
+ * rather than collapsing to an empty token (which would wrongly re-offer
+ * fields). Breaking on parens means `(artist:` offers operators for a clean
+ * `artist`, and autocomplete fires at the right spot inside a group.
  */
+function isBoundary(c) {
+    return /\s/.test(c) || c === '(' || c === ')';
+}
 export function activeToken(s, pos) {
     // Walk from the start so we can track quote state; the last unquoted
-    // whitespace before the caret is the token boundary.
+    // boundary before the caret is the token start.
     let start = 0;
     let inQuote = false;
     let q = '';
@@ -32,7 +36,7 @@ export function activeToken(s, pos) {
             inQuote = true;
             q = c;
         }
-        else if (/\s/.test(c)) {
+        else if (isBoundary(c)) {
             start = i + 1;
         }
     }
@@ -40,7 +44,7 @@ export function activeToken(s, pos) {
     let end = pos;
     for (let i = pos; i < s.length; i++) {
         const c = s[i];
-        if (!inQuote && /\s/.test(c))
+        if (!inQuote && isBoundary(c))
             break;
         if (inQuote) {
             if (c === q)
@@ -54,6 +58,9 @@ export function activeToken(s, pos) {
     }
     return { start, end, raw: s.slice(start, end) };
 }
+// The boolean connectives are not fields/operators/values; when the caret sits
+// on one there is nothing to autocomplete (the next token gets fresh fields).
+const CONNECTIVES = new Set(['AND', 'OR', 'NOT']);
 /** Split a token into field / operator-code / value parts (earliest op wins). */
 function splitToken(raw) {
     let best = -1;
@@ -139,6 +146,10 @@ export async function suggest(schema, s, pos) {
     if (raw === '')
         return fieldSuggestions(schema, '', span);
     const { field: fieldFrag, opCode, value } = splitToken(raw);
+    // The caret is parked on a bare boolean connective (`AND`/`OR`/`NOT`) — not a
+    // field, so suppress the dropdown until the next token begins.
+    if (opCode === null && CONNECTIVES.has(fieldFrag.toUpperCase()))
+        return null;
     const field = findField(schema, fieldFrag);
     // No operator typed yet.
     if (opCode === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorsk/tsumikit",
-  "version": "0.9.6",
+  "version": "0.11.0",
   "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",