@dorsk/tsumikit 0.50.0 → 0.52.0

package/README.md

@@ -154,6 +154,60 @@ for a light theme (`:root` defaults to dark, so dark themes may omit it).
 - Adding a built-in theme to the kit = one entry in `THEMES`
   (`stores/theme.svelte.ts`) + one block in `styles/themes.css`.
 
+### Styling a component from outside
+
+A Svelte consumer's **scoped** CSS cannot reach a child component's markup — the
+scoping attribute is only added to elements the consumer itself renders. `class`
+passthrough therefore only helps for layout hooks (margin, flex, grid placement).
+CSS custom properties *do* cross the component boundary, so they are the
+sanctioned escape hatch for everything else.
+
+- **Naming:** `--<prefix>-<axis>`, where `<prefix>` is the component's short
+  prefix (`btn`, `badge`, `txt`, `select`, `input`, `textarea`, `card`, `md`, …)
+  and `<axis>` is one of `bg`, `fg`, `border`, `size`, `radius`, plus a few
+  component-specific ones (`--btn-tone`, `--badge-max-width`, `--gauge-w`).
+  `Text` uses `txt` because `--text*` is already the theme's foreground token.
+- **Setting them:** per instance via `style`, or on any ancestor for a subtree.
+
+```svelte
+<Button style="--btn-bg: var(--c-violet); --btn-fg: #fff; --btn-radius: 0">Ship</Button>
+
+<div class="danger-zone">
+  <Button>Delete</Button>   <!-- inherits the block below -->
+</div>
+
+<style>
+  .danger-zone { --btn-border: var(--danger); --btn-fg: var(--danger); }
+</style>
+```
+
+- Every property is read as `var(--x, <default>)`, so leaving it unset renders
+  exactly as before.
+- **`:global()` into kit internals is unsupported.** Class names like `.btn`,
+  `.badge`, `.select-wrap` or `.textarea` are private and change without a major
+  bump. If an axis you need is missing, open an issue — do not reach in.
+
+| component | published properties |
+| --- | --- |
+| `Button` | `--btn-bg`, `--btn-fg`, `--btn-border`, `--btn-size`, `--btn-radius`, `--btn-tone`, `--btn-on`, `--btn-box` |
+| `Badge` | `--badge-bg`, `--badge-fg`, `--badge-border`, `--badge-radius`, `--badge-tone`, `--badge-max-width` |
+| `Text` | `--txt-fg`, `--txt-size` |
+| `Select` | `--select-bg`, `--select-fg`, `--select-border`, `--select-size`, `--select-radius` |
+| `Input` | `--input-bg`, `--input-fg`, `--input-border`, `--input-size`, `--input-radius` |
+| `Textarea` | `--textarea-bg`, `--textarea-fg`, `--textarea-border`, `--textarea-size`, `--textarea-radius` |
+| `Card` | `--card-pad`, `--card-gap`, `--card-border-style` |
+| `Divider` | `--divider-color`, `--divider-spacing` |
+| `Gauge` | `--gauge-w`, `--gauge-h`, `--gauge-fill` |
+| `MasterDetail` | `--md-list-w`, `--md-gap`, `--md-divider` |
+| `NavBar` | `--navbar-max` |
+| `Callout` | `--callout-tone` |
+| `Fieldset` | `--fieldset-pad`, `--fieldset-border` |
+| `GitRef` | `--git-ref-tone`, `--git-ref-max-width` |
+| `EmptyState` | `--empty-tone` |
+
+`tests/css-custom-property-contract.test.js` reads this table and fails if a
+listed property is not actually read by its component, so the docs cannot drift.
+
 ## Components
 
 **Atoms:** Text, Heading, Button, Input (`icon` inset leading glyph,
@@ -213,7 +267,10 @@ hooks on head/row/cell; `responsive="stack"` turns rows into cards below
 prefix, the `<table>` stays a table for assistive tech), FilterSearchBar /
 FilterInput (`size="sm"` compact bar on `--control-height-compact`,
 `shape="pill"`, `surface`, `hotkey="/"` focuses the input from anywhere
-outside an editable element, `showHotkey` renders the `<kbd>` hint, `grow`).
+outside an editable element, `showHotkey` renders the `<kbd>` hint, `grow`;
+`key="cwd"` puts FilterInput in single-key mode — `value` is the bare value
+instead of a `key:"value"` query, no key prefix in the box, the `placeholder`
+shows while empty, and completion still runs through that field's provider).
 
 **Layouts:** AppShell (responsive header/sidebar/main/footer — persistent
 sidebar on desktop, overlay drawer on mobile, optionally resizable;

package/dist/components/atoms/Badge.svelte

@@ -166,13 +166,13 @@
 		align-items: center;
 		gap: var(--sp-1);
 		padding: 0.15rem var(--sp-2);
-		border-radius: var(--r-pill);
+		border-radius: var(--badge-radius, var(--r-pill));
 		font-size: var(--fs-xs);
 		font-weight: var(--fw-medium);
 		line-height: 1.4;
-		background: var(--bg-elevated-2);
-		color: var(--text-muted);
-		border: 1px solid var(--border);
+		background: var(--badge-bg, var(--bg-elevated-2));
+		color: var(--badge-fg, var(--text-muted));
+		border: 1px solid var(--badge-border, var(--border));
 		white-space: nowrap;
 		max-width: var(--badge-max-width, 100%);
 	}
@@ -188,9 +188,9 @@
 		padding: 0.05rem var(--sp-2);
 	}
 	.toned {
-		color: var(--badge-tone);
-		border-color: color-mix(in srgb, var(--badge-tone) 40%, transparent);
-		background: color-mix(in srgb, var(--badge-tone) 12%, transparent);
+		color: var(--badge-fg, var(--badge-tone));
+		border-color: var(--badge-border, color-mix(in srgb, var(--badge-tone) 40%, transparent));
+		background: var(--badge-bg, color-mix(in srgb, var(--badge-tone) 12%, transparent));
 	}
 	.text {
 		padding: 0;

package/dist/components/atoms/Button.svelte

@@ -165,11 +165,11 @@
 		justify-content: center;
 		gap: var(--sp-2);
 		padding: var(--sp-2) var(--sp-4);
-		min-height: var(--control-height-default);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		background: var(--surface);
-		color: var(--text);
+		min-height: var(--btn-size, var(--control-height-default));
+		border: 1px solid var(--btn-border, var(--border-strong));
+		border-radius: var(--btn-radius, var(--r-md));
+		background: var(--btn-bg, var(--surface));
+		color: var(--btn-fg, var(--text));
 		font-weight: var(--fw-medium);
 		font-size: var(--fs-sm);
 		line-height: 1;
@@ -188,9 +188,9 @@
 		cursor: not-allowed;
 	}
 	.btn-primary {
-		background: var(--accent);
-		border-color: var(--accent);
-		color: var(--text-on-accent);
+		background: var(--btn-bg, var(--accent));
+		border-color: var(--btn-border, var(--accent));
+		color: var(--btn-fg, var(--text-on-accent));
 		font-weight: var(--fw-semibold);
 	}
 	.btn-primary:hover:not(:disabled) {
@@ -205,21 +205,21 @@
 		border-color: var(--danger);
 	}
 	.btn-ghost {
-		background: transparent;
-		border-color: transparent;
+		background: var(--btn-bg, transparent);
+		border-color: var(--btn-border, transparent);
 	}
 	.btn-ghost:hover:not(:disabled) {
 		background: var(--bg-elevated-2);
 		border-color: transparent;
 	}
 	.btn-sm {
-		height: var(--control-height-compact);
-		min-height: var(--control-height-compact);
+		height: var(--btn-size, var(--control-height-compact));
+		min-height: var(--btn-size, var(--control-height-compact));
 		padding: var(--sp-1) var(--sp-3);
 		font-size: var(--fs-xs);
 	}
 	.btn-lg {
-		min-height: var(--control-height-large);
+		min-height: var(--btn-size, var(--control-height-large));
 		padding: var(--sp-3) var(--sp-5);
 		font-size: var(--fs-base);
 	}
@@ -298,13 +298,13 @@
 		align-items: center;
 		justify-content: center;
 		gap: var(--sp-2);
-		height: var(--control-height);
-		min-height: var(--control-height);
+		height: var(--btn-size, var(--control-height));
+		min-height: var(--btn-size, var(--control-height));
 		padding: 0 var(--sp-3);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		background: var(--surface);
-		color: var(--text);
+		border: 1px solid var(--btn-border, var(--border-strong));
+		border-radius: var(--btn-radius, var(--r-md));
+		background: var(--btn-bg, var(--surface));
+		color: var(--btn-fg, var(--text));
 		font-weight: var(--fw-medium);
 		font-size: var(--fs-sm);
 		line-height: 1;
@@ -326,9 +326,9 @@
 	   the primary action with the neutral --surface; restore the accent fill when
 	   both are present. */
 	.btn-control.btn-primary {
-		background: var(--accent);
-		border-color: var(--accent);
-		color: var(--text-on-accent);
+		background: var(--btn-bg, var(--accent));
+		border-color: var(--btn-border, var(--accent));
+		color: var(--btn-fg, var(--text-on-accent));
 	}
 	.btn-control.btn-primary:hover:not(:disabled) {
 		border-color: var(--accent);
@@ -389,7 +389,7 @@
 		align-self: flex-start;
 	}
 	.btn-pill {
-		border-radius: var(--r-pill);
+		border-radius: var(--btn-radius, var(--r-pill));
 	}
 	/* Link variant: no box, inherits the surrounding text size. Placed after the
 	   size rules so their min-height doesn't reapply; a tone wins over --link. */
@@ -419,23 +419,23 @@
 	}
 	/* `square`: side = the height contract in force (size tier or control). */
 	.btn-square {
-		width: var(--control-height-default);
-		min-width: var(--control-height-default);
+		width: var(--btn-size, var(--control-height-default));
+		min-width: var(--btn-size, var(--control-height-default));
 		padding: 0;
 		flex: none;
 	}
 	.btn-square.btn-sm {
-		width: var(--control-height-compact);
-		min-width: var(--control-height-compact);
+		width: var(--btn-size, var(--control-height-compact));
+		min-width: var(--btn-size, var(--control-height-compact));
 	}
 	.btn-square.btn-lg {
-		width: var(--control-height-large);
-		min-width: var(--control-height-large);
-		height: var(--control-height-large);
+		width: var(--btn-size, var(--control-height-large));
+		min-width: var(--btn-size, var(--control-height-large));
+		height: var(--btn-size, var(--control-height-large));
 	}
 	.btn-square.btn-control {
-		width: var(--control-height);
-		min-width: var(--control-height);
+		width: var(--btn-size, var(--control-height));
+		min-width: var(--btn-size, var(--control-height));
 	}
 	/* `box`: explicit square scale, wins over icon/chip/square/size sizing. */
 	.btn-box {

package/dist/components/atoms/Input.svelte

@@ -130,13 +130,13 @@
 <style>
 	.input {
 		width: 100%;
-		min-height: var(--control-height-default);
+		min-height: var(--input-size, var(--control-height-default));
 		padding: var(--sp-2) var(--sp-3);
 		line-height: var(--lh-tight);
-		background: var(--bg);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		color: var(--text);
+		background: var(--input-bg, var(--bg));
+		border: 1px solid var(--input-border, var(--border-strong));
+		border-radius: var(--input-radius, var(--r-md));
+		color: var(--input-fg, var(--text));
 		transition: border-color 0.12s var(--ease);
 	}
 	.input:focus {
@@ -148,12 +148,12 @@
 		outline-offset: var(--focus-ring-offset);
 	}
 	.input-sm {
-		min-height: var(--control-height-compact);
+		min-height: var(--input-size, var(--control-height-compact));
 		padding: var(--sp-1) var(--sp-2);
 		font-size: var(--fs-sm);
 	}
 	.input-lg {
-		min-height: var(--control-height-large);
+		min-height: var(--input-size, var(--control-height-large));
 		padding: var(--sp-3) var(--sp-4);
 		font-size: var(--fs-base);
 	}
@@ -166,7 +166,7 @@
 		flex: none;
 	}
 	.input-pill {
-		border-radius: var(--r-pill);
+		border-radius: var(--input-radius, var(--r-pill));
 		padding-inline: var(--sp-4);
 	}
 	.input[aria-invalid='true'] {

package/dist/components/atoms/Select.svelte

@@ -205,13 +205,13 @@
 	}
 	.select {
 		width: 100%;
-		min-height: var(--control-height-default);
+		min-height: var(--select-size, var(--control-height-default));
 		padding: var(--sp-2) var(--sp-3);
 		line-height: var(--lh-tight);
-		background: var(--bg);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		color: var(--text);
+		background: var(--select-bg, var(--bg));
+		border: 1px solid var(--select-border, var(--border-strong));
+		border-radius: var(--select-radius, var(--r-md));
+		color: var(--select-fg, var(--text));
 		transition: border-color 0.12s var(--ease);
 	}
 	/* Default variant: drop the OS chevron, reserve room for our own. */
@@ -226,7 +226,7 @@
 	}
 	/* Compact inline form for dense headers/toolbars. */
 	.select.select-lg {
-		min-height: var(--control-height-large);
+		min-height: var(--select-size, var(--control-height-large));
 		padding: var(--sp-3) var(--sp-4);
 		font-size: var(--fs-base);
 	}
@@ -240,15 +240,15 @@
 	/* Toolbar contract: size="sm" shares the compact control height so it lines up
 	   with Button size="sm", Popover size="sm" and SegmentedControl size="sm". */
 	.select.select-sm {
-		height: var(--control-height-compact);
+		height: var(--select-size, var(--control-height-compact));
 	}
 	.select.w-auto {
 		width: auto;
 	}
 	.select.embedded {
-		background: var(--bg-elevated-2);
+		background: var(--select-bg, var(--bg-elevated-2));
 		border: none;
-		border-radius: var(--r-sm);
+		border-radius: var(--select-radius, var(--r-sm));
 	}
 	.select:focus {
 		outline: none;
@@ -281,7 +281,7 @@
 		gap: var(--sp-2);
 		padding: 0 var(--sp-3);
 		padding-right: calc(var(--sp-3) + 1.25rem);
-		color: var(--text);
+		color: var(--select-fg, var(--text));
 		pointer-events: none;
 		overflow: hidden;
 	}

package/dist/components/atoms/Text.svelte

@@ -95,29 +95,31 @@
 	/* Base: inherit everything — a bare <Text> renders like a plain span. */
 	.text {
 		margin: 0;
+		color: var(--txt-fg, inherit);
+		font-size: var(--txt-size, inherit);
 	}
 	/* Variants (presets) — listed before tone/weight/size so those override. */
 	.v-body {
-		font-size: var(--fs-base);
+		font-size: var(--txt-size, var(--fs-base));
 		line-height: var(--lh-normal);
-		color: var(--text);
+		color: var(--txt-fg, var(--text));
 	}
 	.v-label {
-		font-size: var(--fs-sm);
+		font-size: var(--txt-size, var(--fs-sm));
 		font-weight: var(--fw-medium);
-		color: var(--text-muted);
+		color: var(--txt-fg, var(--text-muted));
 	}
 	.v-caption {
-		font-size: var(--fs-xs);
-		color: var(--text-faint);
+		font-size: var(--txt-size, var(--fs-xs));
+		color: var(--txt-fg, var(--text-faint));
 	}
 	.v-code {
 		font-family: var(--font-mono);
-		font-size: 0.92em;
+		font-size: var(--txt-size, 0.92em);
 	}
 	.v-eyebrow {
-		font-size: var(--fs-xs);
-		color: var(--text-muted);
+		font-size: var(--txt-size, var(--fs-xs));
+		color: var(--txt-fg, var(--text-muted));
 		font-weight: var(--fw-medium);
 		text-transform: uppercase;
 		letter-spacing: 0.04em;
@@ -127,28 +129,28 @@
 		font-family: var(--font-mono);
 	}
 	.tone-default {
-		color: var(--text);
+		color: var(--txt-fg, var(--text));
 	}
 	.tone-muted {
-		color: var(--text-muted);
+		color: var(--txt-fg, var(--text-muted));
 	}
 	.tone-faint {
-		color: var(--text-faint);
+		color: var(--txt-fg, var(--text-faint));
 	}
 	.tone-success {
-		color: var(--ok);
+		color: var(--txt-fg, var(--ok));
 	}
 	.tone-warn {
-		color: var(--warn);
+		color: var(--txt-fg, var(--warn));
 	}
 	.tone-danger {
-		color: var(--danger);
+		color: var(--txt-fg, var(--danger));
 	}
 	.tone-info {
-		color: var(--info);
+		color: var(--txt-fg, var(--info));
 	}
 	.tone-accent {
-		color: var(--accent);
+		color: var(--txt-fg, var(--accent));
 	}
 	/* Weight — overrides variant weight. */
 	.fw-normal {
@@ -165,46 +167,46 @@
 	}
 	/* Size — overrides variant size (listed last so it wins). */
 	.fs-xs {
-		font-size: var(--fs-xs);
+		font-size: var(--txt-size, var(--fs-xs));
 	}
 	.fs-sm {
-		font-size: var(--fs-sm);
+		font-size: var(--txt-size, var(--fs-sm));
 	}
 	.fs-base {
-		font-size: var(--fs-base);
+		font-size: var(--txt-size, var(--fs-base));
 	}
 	.fs-md {
-		font-size: var(--fs-md);
+		font-size: var(--txt-size, var(--fs-md));
 	}
 	.fs-lg {
-		font-size: var(--fs-lg);
+		font-size: var(--txt-size, var(--fs-lg));
 	}
 	.fs-xl {
-		font-size: var(--fs-xl);
+		font-size: var(--txt-size, var(--fs-xl));
 	}
 	.fs-2xl {
-		font-size: var(--fs-2xl);
+		font-size: var(--txt-size, var(--fs-2xl));
 	}
 	.noscale.fs-xs {
-		font-size: 12px;
+		font-size: var(--txt-size, 12px);
 	}
 	.noscale.fs-sm {
-		font-size: 13px;
+		font-size: var(--txt-size, 13px);
 	}
 	.noscale.fs-base {
-		font-size: 15px;
+		font-size: var(--txt-size, 15px);
 	}
 	.noscale.fs-md {
-		font-size: 16px;
+		font-size: var(--txt-size, 16px);
 	}
 	.noscale.fs-lg {
-		font-size: 18px;
+		font-size: var(--txt-size, 18px);
 	}
 	.noscale.fs-xl {
-		font-size: 22px;
+		font-size: var(--txt-size, 22px);
 	}
 	.noscale.fs-2xl {
-		font-size: 28px;
+		font-size: var(--txt-size, 28px);
 	}
 	.italic {
 		font-style: italic;

package/dist/components/atoms/Textarea.svelte

@@ -223,16 +223,16 @@
 		   --sp-3 top+bottom would overshoot it and a `rows={1}` textarea would
 		   render taller than the buttons it sits beside. */
 		padding: var(--sp-2) var(--sp-3);
-		background: var(--bg);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		color: var(--text);
+		background: var(--textarea-bg, var(--bg));
+		border: 1px solid var(--textarea-border, var(--border-strong));
+		border-radius: var(--textarea-radius, var(--r-md));
+		color: var(--textarea-fg, var(--text));
 		transition: border-color 0.12s var(--ease);
 		/* Custom handle replaces the native grip; never show the native one. */
 		resize: none;
 		/* Match the single-row height of Button/Input so a `rows={1}` textarea
 		   lines up with them; the native `rows` attribute grows it from here. */
-		min-height: 2.5rem;
+		min-height: var(--textarea-size, 2.5rem);
 		line-height: var(--lh-tight);
 		font-family: inherit;
 	}
@@ -250,12 +250,12 @@
 	.textarea-sm {
 		padding: var(--sp-1) var(--sp-2);
 		font-size: var(--fs-sm);
-		min-height: 2rem;
+		min-height: var(--textarea-size, 2rem);
 	}
 	.textarea-lg {
 		padding: var(--sp-3) var(--sp-4);
 		font-size: var(--fs-base);
-		min-height: var(--control-height-large);
+		min-height: var(--textarea-size, var(--control-height-large));
 	}
 	.textarea[aria-invalid='true'],
 	.textarea[aria-invalid='true']:focus {

package/dist/components/layouts/NavBar.svelte

@@ -56,7 +56,7 @@
 	{...rest}
 >
 	<div class="navbar-inner">
-		{#each items as item (item.href)}
+		{#each items as item, i (`${i}:${item.href}`)}
 			<a
 				href={item.href}
 				class="navbar-link"

package/dist/components/molecules/FilterInput.svelte

@@ -43,13 +43,15 @@
 	import { autoQuoteEdit, backspaceEmptyQuotes, closingQuoteExit } from '../../query/edit';
 	import { parse } from '../../query/parser';
 	import { type Schema } from '../../query/schema';
+	import { singleQuery, suggestSingle } from '../../query/single';
 	import { suggest, type SuggestState } from '../../query/suggest';
 	import { getFieldContext, warnUnlabelled } from '../../field-context';
 
 	let {
 		schema,
+		key,
 		value = $bindable(''),
-		placeholder = 'artist:"Daft Punk" AND year>=2000',
+		placeholder,
 		autoQuote = true,
 		showClear = true,
 		icon = 'search',
@@ -70,13 +72,23 @@
 		style: styleProp = '',
 	}: {
 		schema: Schema;
-		/** The raw textual query (two-way bindable). */
+		/**
+		 * Single-key mode: the name (or alias) of the ONE schema field being
+		 * edited. `value` then holds the bare value instead of a `key:"value"`
+		 * query — no key prefix in the box, the placeholder shows while empty and
+		 * completion still runs through that field's provider. The equivalent query
+		 * is synthesised for `onchange` and the snippet context.
+		 */
+		key?: string;
+		/** The raw textual query, or the bare value in single-key mode (bindable). */
 		value?: string;
+		/** Defaults to a sample query, or to nothing in single-key mode. */
 		placeholder?: string;
 		/**
 		 * When a string field's value step opens (`title:`), auto-insert a `""`
 		 * pair with the caret inside so multi-word values stay together; Tab exits
 		 * the quotes. Set false for bare typing where spaces split the value.
+		 * Always off in single-key mode, which quotes nothing.
 		 */
 		autoQuote?: boolean;
 		/** Show the trailing clear (✕) button when the field is non-empty. */
@@ -147,8 +159,12 @@
 		return () => document.removeEventListener('keydown', onHotkey);
 	});
 
+	const single = $derived(!!key);
+	const quoting = $derived(autoQuote && !single);
+	const hint = $derived(placeholder ?? (single ? '' : 'artist:"Daft Punk" AND year>=2000'));
+
 	// Parsed view (drives the onchange AST + the snippet context).
-	const ast = $derived(parse(value, schema));
+	const ast = $derived(parse(key ? singleQuery(schema, key, value) : value, schema));
 	const chips = $derived(filters(ast));
 	const text = $derived(freeText(ast));
 
@@ -183,7 +199,7 @@
 	}
 
 	function oninput(e: Event) {
-		if (autoQuote && el && (e as InputEvent).inputType?.startsWith('insert')) {
+		if (quoting && el && (e as InputEvent).inputType?.startsWith('insert')) {
 			const pos = el.selectionStart ?? value.length;
 			const edit = autoQuoteEdit(schema, value, pos);
 			if (edit) {
@@ -200,7 +216,7 @@
 		if (!el) return;
 		const pos = el.selectionStart ?? value.length;
 		const id = ++reqId;
-		const next = await suggest(schema, value, pos);
+		const next = key ? await suggestSingle(schema, key, value) : await suggest(schema, value, pos);
 		if (id !== reqId) return; // a newer keystroke won
 		menu = next;
 		active = 0;
@@ -217,7 +233,7 @@
 		let caret = s.caret;
 		// A field/operator pick that opens a string field's value step gets the
 		// same auto-quotes as manual typing.
-		if (autoQuote && s.advance) {
+		if (quoting && s.advance) {
 			const edit = autoQuoteEdit(schema, value, caret);
 			if (edit) {
 				value = edit.value;
@@ -236,7 +252,7 @@
 	}
 
 	function onkeydown(e: KeyboardEvent) {
-		if (autoQuote && el) {
+		if (quoting && el) {
 			const pos = el.selectionStart ?? value.length;
 			if (e.key === 'Tab') {
 				// Inside auto-quotes Tab exits them (takes priority over accepting a
@@ -292,6 +308,14 @@
 	}
 
 	function removeChip(span: [number, number]) {
+		// Single-key spans index the synthesised query, not the box: the only
+		// clause there is the value itself, so removing it empties the field.
+		if (single) {
+			value = '';
+			onsubmit?.('');
+			queueMicrotask(() => el?.focus());
+			return;
+		}
 		// Splice the clause out, plus trailing spaces to avoid doubles.
 		const [a, b] = span;
 		let end = b;
@@ -332,7 +356,7 @@
 			aria-invalid={ariaInvalid ?? (field?.invalid ? 'true' : undefined)}
 			spellcheck="false"
 			autocomplete="off"
-			{placeholder}
+			placeholder={hint}
 			{oninput}
 			onclick={refresh}
 			onkeyup={(e) => {

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

@@ -24,13 +24,23 @@ import { type IconName } from '../atoms/Icon.svelte';
 import { type Schema } from '../../query/schema';
 type $$ComponentProps = {
     schema: Schema;
-    /** The raw textual query (two-way bindable). */
+    /**
+     * Single-key mode: the name (or alias) of the ONE schema field being
+     * edited. `value` then holds the bare value instead of a `key:"value"`
+     * query — no key prefix in the box, the placeholder shows while empty and
+     * completion still runs through that field's provider. The equivalent query
+     * is synthesised for `onchange` and the snippet context.
+     */
+    key?: string;
+    /** The raw textual query, or the bare value in single-key mode (bindable). */
     value?: string;
+    /** Defaults to a sample query, or to nothing in single-key mode. */
     placeholder?: string;
     /**
      * When a string field's value step opens (`title:`), auto-insert a `""`
      * pair with the caret inside so multi-word values stay together; Tab exits
      * the quotes. Set false for bare typing where spaces split the value.
+     * Always off in single-key mode, which quotes nothing.
      */
     autoQuote?: boolean;
     /** Show the trailing clear (✕) button when the field is non-empty. */

package/dist/index.d.ts

@@ -87,7 +87,7 @@ export { default as FilterSearchBar } from './components/organisms/FilterSearchB
 export { EMOJI_GROUPS, type EmojiEntry, type EmojiGroup, searchEmoji } from './emoji';
 export { FIELD_KEY, type FieldContext, getFieldContext, setFieldContext, warnUnlabelled, } from './field-context';
 export * as filterQuery 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 ValueContext, type ValueOption, type ValueProvider, walk, } 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, singleQuery, suggest, suggestSingle, type TextNode, toSql, type ValueContext, type ValueOption, type ValueProvider, walk, } from './query';
 export { type OptionSection, sectionOptions } from './select-options';
 export type { ControlSize } from './size';
 export { fontScale, SCALE_LEVELS, type ScaleLevel } from './stores/fontscale.svelte';

package/dist/index.js

@@ -98,7 +98,7 @@ export { EMOJI_GROUPS, searchEmoji } from './emoji';
 export { FIELD_KEY, getFieldContext, setFieldContext, warnUnlabelled, } from './field-context';
 // ---- query core (headless: schema / parser / AST / suggest / compilers) ----
 export * as filterQuery from './query';
-export { activeToken, compilePredicate, defaultOperator, filters, findField, freeText, OPERATORS, operatorByCode, operatorById, operatorsFor, parse, resolveValues, serialize, serializeFilter, suggest, toSql, walk, } from './query';
+export { activeToken, compilePredicate, defaultOperator, filters, findField, freeText, OPERATORS, operatorByCode, operatorById, operatorsFor, parse, resolveValues, serialize, serializeFilter, singleQuery, suggest, suggestSingle, toSql, walk, } from './query';
 export { sectionOptions } from './select-options';
 export { fontScale, SCALE_LEVELS } from './stores/fontscale.svelte';
 // ---- stores / actions ----

package/dist/query/index.d.ts

@@ -5,5 +5,6 @@ export { parse } from './parser';
 export { compilePredicate, serialize, serializeFilter, toSql } from './query';
 export type { FieldDef, FieldType, Operator, OperatorId, Schema, ValueContext, ValueOption, ValueProvider, } from './schema';
 export { defaultOperator, findField, OPERATORS, operatorByCode, operatorById, operatorsFor, resolveValues, } from './schema';
+export { singleQuery, suggestSingle } from './single';
 export type { Suggestion, SuggestKind, SuggestState } from './suggest';
 export { activeToken, suggest } from './suggest';

package/dist/query/index.js

@@ -7,4 +7,5 @@ export { autoQuoteEdit, backspaceEmptyQuotes, closingQuoteExit, insideQuoteAtCar
 export { parse } from './parser';
 export { compilePredicate, serialize, serializeFilter, toSql } from './query';
 export { defaultOperator, findField, OPERATORS, operatorByCode, operatorById, operatorsFor, resolveValues, } from './schema';
+export { singleQuery, suggestSingle } from './single';
 export { activeToken, suggest } from './suggest';

package/dist/query/single.d.ts

@@ -0,0 +1,15 @@
+import { type Schema } from './schema';
+import type { SuggestState } from './suggest';
+/**
+ * The textual query a bare `value` stands for, using `key`'s default operator —
+ * `"/srv/my app"` under key `cwd` becomes `cwd:"/srv/my app"`. Empty values (and
+ * unknown keys) yield an empty query so the AST stays empty rather than parsing
+ * a half-written clause.
+ */
+export declare function singleQuery(schema: Schema, key: string, value: string): string;
+/**
+ * Value suggestions for `key` given the whole box as the fragment. The span
+ * always covers the entire value, so accepting an item replaces it outright —
+ * there is no field or operator step to advance to.
+ */
+export declare function suggestSingle(schema: Schema, key: string, value: string): Promise<SuggestState | null>;

package/dist/query/single.js

@@ -0,0 +1,43 @@
+// ─────────────────────────────────────────────────────────────────────────
+// Single-key mode — the headless half of FilterInput's `key` prop: the box
+// holds the bare value (`/srv/app`, not `cwd:"/srv/app"`), completing through
+// the field's own provider, and the equivalent query is synthesised only for
+// the `inline` / `below` snippets and the `onchange` AST.
+// ─────────────────────────────────────────────────────────────────────────
+import { defaultOperator, findField, resolveValues } from './schema';
+function quoteIfNeeded(v) {
+    return /[\s,()]/.test(v) ? `"${v}"` : v;
+}
+/**
+ * The textual query a bare `value` stands for, using `key`'s default operator —
+ * `"/srv/my app"` under key `cwd` becomes `cwd:"/srv/my app"`. Empty values (and
+ * unknown keys) yield an empty query so the AST stays empty rather than parsing
+ * a half-written clause.
+ */
+export function singleQuery(schema, key, value) {
+    const field = findField(schema, key);
+    if (!field || !value)
+        return '';
+    return `${field.name}${defaultOperator(field).code}${quoteIfNeeded(value)}`;
+}
+/**
+ * Value suggestions for `key` given the whole box as the fragment. The span
+ * always covers the entire value, so accepting an item replaces it outright —
+ * there is no field or operator step to advance to.
+ */
+export async function suggestSingle(schema, key, value) {
+    const field = findField(schema, key);
+    if (!field)
+        return null;
+    const span = [0, value.length];
+    const options = await resolveValues(field, value, { rawQuery: value, span, caret: value.length });
+    if (options.length === 0)
+        return null;
+    const items = options.map((o) => ({
+        label: o.label,
+        hint: o.hint,
+        insert: o.value,
+        caret: o.value.length,
+    }));
+    return { kind: 'value', span, items };
+}

package/package.json

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