@dorsk/tsumikit 0.8.1 → 0.9.0

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 {};