@dorsk/tsumikit 0.54.0 → 0.56.0

package/README.md

@@ -222,6 +222,23 @@ renders, and the trigger belongs to `Popover`, so `.toolbar .my-trigger` compile
 to `.toolbar.svelte-x .my-trigger.svelte-x` and matches nothing. Use `style` and
 the properties above instead.
 
+### Anchoring to a component
+
+Components that render a single addressable element forward rest props onto it,
+so `data-journey`, `data-testid` and analytics attributes land where you expect.
+`Popover` puts them on its **trigger** (so `Menu`, `ThemePicker` and
+`FontScalePicker` forward through to it), `Tabs` on its root — with a per-tab
+`attrs` bag on each `TabItem` — `FilterInput` on its root, and `FilterSearchBar`
+forwards onto that. `Menu` items take an `attrs` bag. Components that forward
+into another component take `AnchorAttributes` (`data-*` only), which cannot
+collide with the child's own props; the rest take full `HTMLAttributes`. The
+component's own `role`, `aria-*`, `class` and keyboard wiring are applied after
+the spread and always win, so an anchor can never break behaviour; `class` in a
+rest/`attrs` bag is therefore dropped — use `class` / `triggerClass`.
+
+Never target the private `data-tsu="…"` markers: they are internal, unguarded by
+any test, and change without a major.
+
 ## Components
 
 **Atoms:** Text, Heading, Button, Input (`icon` inset leading glyph,
@@ -241,7 +258,8 @@ always/hover/none, `align`), Icon (open registry — pass a `children` snippet f
 any custom SVG).
 
 **Molecules:** Field (`grow`), IconButton, SelectButton, Toggle, OptionButton, Modal,
-Popover, Menu (items take a free-form trailing `tag` + `tagTone`, or a `tag` snippet),
+Popover, Menu (items take a free-form trailing `tag` + `tagTone`, or a `tag` snippet,
+and an `attrs` object for `data-*`/test ids on the row),
 Tabs, RadioGroup (`variant="rows"`: bordered rows, per-option `note`/`description`,
 `action(option)` trailing control that never toggles, `below(option)` inline panel),
 Tooltip, Accordion, CopyButton, FileButton,

package/dist/anchor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `data-*` attributes for addressing a component later — tour anchors, test ids.
+ *
+ * Components rendering their own element take a full `HTMLAttributes` rest
+ * instead; this narrower bag is for those that forward into another component,
+ * where a full attribute type collides with the child's narrower props.
+ */
+export type AnchorAttributes = {
+    [key: `data-${string}`]: string | number | boolean | null | undefined;
+};

package/dist/anchor.js

@@ -0,0 +1 @@
+export {};

package/dist/components/molecules/FilterInput.svelte

@@ -2,9 +2,10 @@
 	import type { FilterNode, Query } from '../../query/ast';
 
 	/**
-	 * The reactive parse context handed to the `inline` and `below` snippets so a
-	 * host can render arbitrary Svelte nodes (badges, custom components, chips)
-	 * either inline inside the bar or below it — all derived from the same value.
+	 * The reactive parse context handed to the `inline`, `display` and `below`
+	 * snippets so a host can render arbitrary Svelte nodes (badges, custom
+	 * components, chips) inside the bar, over the input or below it — all
+	 * derived from the same value.
 	 */
 	export interface FilterInputContext {
 		/** The parsed AST for the current value. */
@@ -38,6 +39,7 @@
 	// `ValueProvider`s). No `fetch` lives in here; the bar owns the QUERY string.
 	// ───────────────────────────────────────────────────────────────────────
 	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
 	import Icon, { type IconName } from '../atoms/Icon.svelte';
 	import { filters, freeText } from '../../query/ast';
 	import { autoQuoteEdit, backspaceEmptyQuotes, closingQuoteExit } from '../../query/edit';
@@ -67,10 +69,14 @@
 		onchange,
 		onsubmit,
 		inline,
+		display,
 		below,
 		class: klass = '',
 		style: styleProp = '',
-	}: {
+		...rest
+	}: Omit<HTMLAttributes<HTMLDivElement>, keyof Own> & Own = $props();
+
+	type Own = {
 		schema: Schema;
 		/**
 		 * Single-key mode: the name (or alias) of the ONE schema field being
@@ -120,6 +126,15 @@
 		 * inline (no below-bar chips). Receives the reactive parse context.
 		 */
 		inline?: Snippet<[FilterInputContext]>;
+		/**
+		 * Rendering of the value shown over the input while the field is blurred
+		 * and non-empty — a compact path, a formatted timestamp, a resolved id.
+		 * Focusing the input (click, Tab, `hotkey`, `context.focus()`) reveals the
+		 * raw text again. It is decoration, never a control: the overlay is
+		 * `aria-hidden`, takes no pointer events and adds no tab stop, so the
+		 * input stays the single focus target.
+		 */
+		display?: Snippet<[FilterInputContext]>;
 		/**
 		 * Content rendered below the bar (e.g. removable chips). FilterSearchBar
 		 * passes its chip row here; single-field hosts simply omit it.
@@ -127,7 +142,7 @@
 		below?: Snippet<[FilterInputContext]>;
 		class?: string;
 		style?: string;
-	} = $props();
+	};
 
 	const field = getFieldContext();
 	let el = $state<HTMLInputElement | null>(null);
@@ -177,6 +192,8 @@
 		focus: () => el?.focus()
 	});
 
+	const showDisplay = $derived(!!display && !focused && !!value);
+
 	// Emit the AST whenever the parse result changes.
 	$effect(() => {
 		onchange?.(ast, value);
@@ -335,6 +352,7 @@
 </script>
 
 <div
+	{...rest}
 	class="fi {klass}"
 	style={styleProp}
 	class:fi--sm={size === 'sm'}
@@ -347,31 +365,37 @@
 	<div class="fi__bar">
 		{#if icon}<span class="fi__icon"><Icon name={icon} label="Search" /></span>{/if}
 		{#if inline}{@render inline(ctx)}{/if}
-		<input
-			bind:this={el}
-			bind:value
-			class="fi__input"
-			id={id ?? field?.id}
-			aria-describedby={ariaDescribedby ?? field?.describedBy}
-			aria-invalid={ariaInvalid ?? (field?.invalid ? 'true' : undefined)}
-			spellcheck="false"
-			autocomplete="off"
-			placeholder={hint}
-			{oninput}
-			onclick={refresh}
-			onkeyup={(e) => {
-				if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') refresh();
-			}}
-			onfocus={() => {
-				focused = true;
-				refresh();
-			}}
-			onblur={() => {
-				focused = false;
-				setTimeout(() => (open = false), 120);
-			}}
-			{onkeydown}
-		/>
+		<span class="fi__field">
+			<input
+				bind:this={el}
+				bind:value
+				class="fi__input"
+				class:fi__input--masked={showDisplay}
+				id={id ?? field?.id}
+				aria-describedby={ariaDescribedby ?? field?.describedBy}
+				aria-invalid={ariaInvalid ?? (field?.invalid ? 'true' : undefined)}
+				spellcheck="false"
+				autocomplete="off"
+				placeholder={hint}
+				{oninput}
+				onclick={refresh}
+				onkeyup={(e) => {
+					if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') refresh();
+				}}
+				onfocus={() => {
+					focused = true;
+					refresh();
+				}}
+				onblur={() => {
+					focused = false;
+					setTimeout(() => (open = false), 120);
+				}}
+				{onkeydown}
+			/>
+			{#if display && showDisplay}
+				<span class="fi__display" aria-hidden="true">{@render display(ctx)}</span>
+			{/if}
+		</span>
 		{#if showHotkey && hotkey && !focused && !value}
 			<kbd class="fi__kbd" aria-hidden="true">{hotkey}</kbd>
 		{/if}
@@ -474,6 +498,22 @@
 		display: flex;
 		color: var(--text-faint);
 	}
+	.fi__field {
+		position: relative;
+		display: flex;
+		flex: 1;
+		min-width: 0;
+	}
+	.fi__display {
+		position: absolute;
+		inset: 0;
+		display: flex;
+		align-items: center;
+		gap: var(--sp-2);
+		min-width: 0;
+		overflow: hidden;
+		pointer-events: none;
+	}
 	.fi__input {
 		flex: 1;
 		border: 0;
@@ -487,6 +527,9 @@
 	.fi__input::placeholder {
 		color: var(--text-faint);
 	}
+	.fi__input--masked {
+		color: transparent;
+	}
 	.fi__clear {
 		display: flex;
 		border: 0;

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

@@ -1,8 +1,9 @@
 import type { FilterNode, Query } from '../../query/ast';
 /**
- * The reactive parse context handed to the `inline` and `below` snippets so a
- * host can render arbitrary Svelte nodes (badges, custom components, chips)
- * either inline inside the bar or below it — all derived from the same value.
+ * The reactive parse context handed to the `inline`, `display` and `below`
+ * snippets so a host can render arbitrary Svelte nodes (badges, custom
+ * components, chips) inside the bar, over the input or below it — all
+ * derived from the same value.
  */
 export interface FilterInputContext {
     /** The parsed AST for the current value. */
@@ -20,9 +21,10 @@ export interface FilterInputContext {
 }
 import type { ControlSize } from '../../size';
 import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
 import { type IconName } from '../atoms/Icon.svelte';
 import { type Schema } from '../../query/schema';
-type $$ComponentProps = {
+type Own = {
     schema: Schema;
     /**
      * Single-key mode: the name (or alias) of the ONE schema field being
@@ -72,6 +74,15 @@ type $$ComponentProps = {
      * inline (no below-bar chips). Receives the reactive parse context.
      */
     inline?: Snippet<[FilterInputContext]>;
+    /**
+     * Rendering of the value shown over the input while the field is blurred
+     * and non-empty — a compact path, a formatted timestamp, a resolved id.
+     * Focusing the input (click, Tab, `hotkey`, `context.focus()`) reveals the
+     * raw text again. It is decoration, never a control: the overlay is
+     * `aria-hidden`, takes no pointer events and adds no tab stop, so the
+     * input stays the single focus target.
+     */
+    display?: Snippet<[FilterInputContext]>;
     /**
      * Content rendered below the bar (e.g. removable chips). FilterSearchBar
      * passes its chip row here; single-field hosts simply omit it.
@@ -80,6 +91,7 @@ type $$ComponentProps = {
     class?: string;
     style?: string;
 };
+type $$ComponentProps = Omit<HTMLAttributes<HTMLDivElement>, keyof Own> & Own;
 declare const FilterInput: import("svelte").Component<$$ComponentProps, {}, "value">;
 type FilterInput = ReturnType<typeof FilterInput>;
 export default FilterInput;

package/dist/components/molecules/Menu.svelte

@@ -12,6 +12,12 @@
 		pressed?: boolean;
 		/** Custom row content (a rename Input, a slider…) replacing icon/label/tag. */
 		content?: import('svelte').Snippet<[MenuItem]>;
+		/**
+		 * Extra attributes for the rendered row — `data-*`, `title`, `aria-describedby`…
+		 * The row's own semantics (`role`, `aria-checked`, `disabled`, `class`, `onclick`)
+		 * are applied after and win.
+		 */
+		attrs?: import('svelte/elements').HTMLButtonAttributes;
 	}
 </script>
 
@@ -165,6 +171,7 @@
 		{#each items as item (item.label)}
 			<button
 				type="button"
+				{...item.attrs}
 				role={item.pressed === undefined ? 'menuitem' : 'menuitemcheckbox'}
 				aria-checked={item.pressed === undefined ? undefined : item.pressed}
 				class="menu-item"

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

@@ -11,6 +11,12 @@ export interface MenuItem {
     pressed?: boolean;
     /** Custom row content (a rename Input, a slider…) replacing icon/label/tag. */
     content?: import('svelte').Snippet<[MenuItem]>;
+    /**
+     * Extra attributes for the rendered row — `data-*`, `title`, `aria-describedby`…
+     * The row's own semantics (`role`, `aria-checked`, `disabled`, `class`, `onclick`)
+     * are applied after and win.
+     */
+    attrs?: import('svelte/elements').HTMLButtonAttributes;
 }
 import type { ComponentProps, Snippet } from 'svelte';
 import Popover from './Popover.svelte';

package/dist/components/molecules/Popover.svelte

@@ -10,6 +10,7 @@
 	// ships beyond Chromium; the popover semantics above are the hard part and
 	// are broadly supported today.)
 	import { tick, type Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
 	import { place } from '../../floating';
 	import { HOVER_CLOSE_GRACE, HOVER_OPEN_DELAY, createHoverIntent, opensOnHover } from './popover-hover.js';
 
@@ -20,36 +21,7 @@
 	type PanelRole = 'dialog' | 'menu' | 'listbox' | 'group';
 	type HasPopup = 'menu' | 'dialog' | 'listbox' | true;
 
-	let {
-		placement = 'bottom-start',
-		gap = 6,
-		label,
-		trigger,
-		children,
-		triggerClass = '',
-		bare = false,
-		variant,
-		tone = 'none',
-		size,
-		box,
-		pill = false,
-		control = false,
-		block = false,
-		hitArea = 'auto',
-		disabled = false,
-		openOn = 'click',
-		hoverDelay = HOVER_OPEN_DELAY,
-		as = 'button',
-		href,
-		role = 'dialog',
-		haspopup = 'dialog',
-		onopen,
-		onclose,
-		class: klass = '',
-		style: styleProp = '',
-		panelClass = '',
-		panelStyle = '',
-	}: {
+	type Own = {
 		placement?: Placement;
 		gap?: number;
 		/** Accessible name for the trigger. */
@@ -106,7 +78,39 @@
 		/** Class / inline style on the floating panel. */
 		panelClass?: string;
 		panelStyle?: string;
-	} = $props();
+	};
+
+	let {
+		placement = 'bottom-start',
+		gap = 6,
+		label,
+		trigger,
+		children,
+		triggerClass = '',
+		bare = false,
+		variant,
+		tone = 'none',
+		size,
+		box,
+		pill = false,
+		control = false,
+		block = false,
+		hitArea = 'auto',
+		disabled = false,
+		openOn = 'click',
+		hoverDelay = HOVER_OPEN_DELAY,
+		as = 'button',
+		href,
+		role = 'dialog',
+		haspopup = 'dialog',
+		onopen,
+		onclose,
+		class: klass = '',
+		style: styleProp = '',
+		panelClass = '',
+		panelStyle = '',
+		...rest
+	}: Omit<HTMLAttributes<HTMLElement>, keyof Own> & Own = $props();
 
 	const canonicalChrome = $derived(
 		variant !== undefined || tone !== 'none' || size !== undefined || control || block
@@ -219,6 +223,7 @@
 <svelte:element
 	this={as}
 	bind:this={triggerEl}
+	{...rest}
 	data-tsu="Popover"
 	class="pop-trigger {triggerClass} {klass}"
 	style={styleProp}

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

@@ -1,11 +1,12 @@
 import { type Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
 type Placement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
 type TriggerVariant = 'default' | 'primary' | 'ghost' | 'danger';
 type TriggerTone = 'none' | 'accent' | 'success' | 'info' | 'warn' | 'danger';
 type TriggerSize = 'sm' | 'md' | 'lg';
 type PanelRole = 'dialog' | 'menu' | 'listbox' | 'group';
 type HasPopup = 'menu' | 'dialog' | 'listbox' | true;
-type $$ComponentProps = {
+type Own = {
     placement?: Placement;
     gap?: number;
     /** Accessible name for the trigger. */
@@ -65,6 +66,7 @@ type $$ComponentProps = {
     panelClass?: string;
     panelStyle?: string;
 };
+type $$ComponentProps = Omit<HTMLAttributes<HTMLElement>, keyof Own> & Own;
 declare const Popover: import("svelte").Component<$$ComponentProps, {}, "">;
 type Popover = ReturnType<typeof Popover>;
 export default Popover;

package/dist/components/molecules/Tabs.svelte

@@ -7,6 +7,12 @@
 		disabled?: boolean;
 		/** Trailing count badge. */
 		count?: number | string;
+		/**
+		 * Extra attributes for this tab's button — `data-*`, `title`…
+		 * The tab's own semantics (`role`, `aria-*`, `id`, `class`, `disabled`,
+		 * `tabindex`, `onclick`) are applied after and win.
+		 */
+		attrs?: import('svelte/elements').HTMLButtonAttributes;
 	}
 </script>
 
@@ -18,6 +24,7 @@
 	// the Tab order. `value` is bindable; `panel` is a snippet that receives the
 	// active id so the caller renders the matching content.
 	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
 	import Icon from '../atoms/Icon.svelte';
 
 	let {
@@ -29,7 +36,10 @@
 		style: styleProp = '',
 		panelClass = '',
 		panelPadding = 'md',
-	}: {
+		...rest
+	}: Omit<HTMLAttributes<HTMLDivElement>, keyof Own> & Own = $props();
+
+	type Own = {
 		tabs: TabItem[];
 		value?: string;
 		label?: string;
@@ -38,7 +48,7 @@
 		style?: string;
 		panelClass?: string;
 		panelPadding?: 'none' | 'sm' | 'md';
-	} = $props();
+	};
 
 	// Default to the first selectable tab when no value is supplied.
 	$effect(() => {
@@ -84,11 +94,12 @@
 	}
 </script>
 
-<div class="tabs {klass}" style={styleProp} data-tsu="Tabs">
+<div {...rest} class="tabs {klass}" style={styleProp} data-tsu="Tabs">
 	<div bind:this={listEl} role="tablist" aria-label={label} tabindex="-1" class="tablist" {onkeydown}>
 		{#each tabs as t (t.id)}
 			<button
 				type="button"
+				{...t.attrs}
 				role="tab"
 				id="{baseId}-tab-{t.id}"
 				aria-selected={value === t.id}

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

@@ -6,9 +6,16 @@ export interface TabItem {
     disabled?: boolean;
     /** Trailing count badge. */
     count?: number | string;
+    /**
+     * Extra attributes for this tab's button — `data-*`, `title`…
+     * The tab's own semantics (`role`, `aria-*`, `id`, `class`, `disabled`,
+     * `tabindex`, `onclick`) are applied after and win.
+     */
+    attrs?: import('svelte/elements').HTMLButtonAttributes;
 }
 import type { Snippet } from 'svelte';
-type $$ComponentProps = {
+import type { HTMLAttributes } from 'svelte/elements';
+type Own = {
     tabs: TabItem[];
     value?: string;
     label?: string;
@@ -18,6 +25,7 @@ type $$ComponentProps = {
     panelClass?: string;
     panelPadding?: 'none' | 'sm' | 'md';
 };
+type $$ComponentProps = Omit<HTMLAttributes<HTMLDivElement>, keyof Own> & Own;
 declare const Tabs: import("svelte").Component<$$ComponentProps, {}, "value">;
 type Tabs = ReturnType<typeof Tabs>;
 export default Tabs;

package/dist/components/molecules/ThemePicker.svelte

@@ -6,6 +6,7 @@
 	// resolved once at :root and would not re-scope). The root default theme
 	// has no [data-theme] block, so its swatch carries the :root values.
 	import type { ComponentProps } from 'svelte';
+	import type { AnchorAttributes } from '../../anchor';
 	import Popover from './Popover.svelte';
 	import { type ThemeDef, theme } from '../../stores/theme.svelte';
 	import { AUTO_THEME } from '../../theme-mode';
@@ -34,7 +35,10 @@
 		darkLabel = 'Dark',
 		class: klass = '',
 		style: styleProp = '',
-	}: TriggerChrome & {
+		...rest
+	}: AnchorAttributes & TriggerChrome & Own = $props();
+
+	type Own = {
 		/** Offer an "auto" row that follows `prefers-color-scheme`, remembering
 		 *  one light and one dark theme. */
 		auto?: boolean;
@@ -44,7 +48,7 @@
 		darkLabel?: string;
 		class?: string;
 		style?: string;
-	} = $props();
+	};
 
 	let hovered = $state<ThemeDef | null>(null);
 	let hoveredAuto = $state(false);
@@ -74,6 +78,7 @@
 {/snippet}
 
 <Popover
+	{...rest}
 	label={title}
 	{placement}
 	{box}

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

@@ -1,7 +1,8 @@
 import type { ComponentProps } from 'svelte';
+import type { AnchorAttributes } from '../../anchor';
 import Popover from './Popover.svelte';
 type TriggerChrome = Pick<ComponentProps<typeof Popover>, 'variant' | 'tone' | 'size' | 'box' | 'pill' | 'control' | 'block' | 'bare' | 'hitArea' | 'placement' | 'disabled'>;
-type $$ComponentProps = TriggerChrome & {
+type Own = {
     /** Offer an "auto" row that follows `prefers-color-scheme`, remembering
      *  one light and one dark theme. */
     auto?: boolean;
@@ -12,6 +13,7 @@ type $$ComponentProps = TriggerChrome & {
     class?: string;
     style?: string;
 };
+type $$ComponentProps = AnchorAttributes & TriggerChrome & Own;
 declare const ThemePicker: import("svelte").Component<$$ComponentProps, {}, "">;
 type ThemePicker = ReturnType<typeof ThemePicker>;
 export default ThemePicker;

package/dist/components/organisms/FilterSearchBar.svelte

@@ -14,6 +14,7 @@
 	// and forwards onchange/onsubmit. Everything project-specific is INJECTED via
 	// `schema` (with per-field async `ValueProvider`s).
 	// ───────────────────────────────────────────────────────────────────────
+	import type { AnchorAttributes } from '../../anchor';
 	import Badge from '../atoms/Badge.svelte';
 	import FilterInput from '../molecules/FilterInput.svelte';
 	import type { Query } from '../../query/ast';
@@ -35,7 +36,10 @@
 		onsubmit,
 		class: klass = '',
 		style: styleProp = '',
-	}: {
+		...rest
+	}: AnchorAttributes & Own = $props();
+
+	type Own = {
 		schema: Schema;
 		/** The raw textual query (two-way bindable). */
 		value?: string;
@@ -61,7 +65,7 @@
 		onsubmit?: (value: string) => void;
 		class?: string;
 		style?: string;
-	} = $props();
+	};
 
 	function labelFor(fieldName: string): string {
 		return findField(schema, fieldName)?.label ?? fieldName;
@@ -69,6 +73,7 @@
 </script>
 
 <FilterInput
+	{...rest}
 	{schema}
 	bind:value
 	{placeholder}

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

@@ -1,7 +1,8 @@
 import type { ControlSize } from '../../size';
+import type { AnchorAttributes } from '../../anchor';
 import type { Query } from '../../query/ast';
 import { type Schema } from '../../query/schema';
-type $$ComponentProps = {
+type Own = {
     schema: Schema;
     /** The raw textual query (two-way bindable). */
     value?: string;
@@ -28,6 +29,7 @@ type $$ComponentProps = {
     class?: string;
     style?: string;
 };
+type $$ComponentProps = AnchorAttributes & Own;
 declare const FilterSearchBar: import("svelte").Component<$$ComponentProps, {}, "value">;
 type FilterSearchBar = ReturnType<typeof FilterSearchBar>;
 export default FilterSearchBar;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export type { AnchorAttributes } from './anchor';
 export { artworkGradient, artworkHue, initials } from './artwork';
 export { autoresize } from './autoresize';
 export { copyToClipboard } from './clipboard';

package/package.json

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