@runwisp/ui 1.0.1 → 1.1.0

package/src/lib/components/FilterPill.svelte

@@ -0,0 +1,180 @@
+<!-- SPDX-FileCopyrightText: PoppyCake, s.r.o. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+<!--
+  One filter, one element. The pill is both the control and its own "chip":
+  inactive it reads `Label ▾` (muted); active it reads `Label: value ✕` (accent)
+  with an inline clear. Active vs inactive is a restyle of the SAME element — it
+  never spawns a second row, so the table below never jumps. Clicking the body
+  opens a type-specific editor popover (select menu / number / date range).
+-->
+
+<script lang="ts">
+    import { untrack } from "svelte";
+    import Popover from "./Popover.svelte";
+    import Input from "./Input.svelte";
+    import { Check, ChevronDown, X } from "@lucide/svelte";
+    import {
+        type FilterField,
+        type FilterValues,
+        fieldKeys,
+        fieldLabel,
+        isFieldActive,
+        isBlank,
+    } from "./filter-spec.js";
+
+    let {
+        field,
+        values = $bindable({}),
+        // Open the editor on mount — set when the pill was just added from the
+        // "+ Add filter" menu, so the user lands straight in the value picker.
+        autoOpen = false,
+        onClose,
+    }: {
+        field: FilterField;
+        values?: FilterValues;
+        autoOpen?: boolean;
+        onClose?: () => void;
+    } = $props();
+
+    // Capture the initial autoOpen once; later prop changes must not reopen it.
+    let open = $state(untrack(() => autoOpen));
+    const active = $derived(isFieldActive(field, values));
+    const label = $derived(fieldLabel(field));
+
+    // The active-state summary shown after the label (`Label: <this>`).
+    const summary = $derived.by(() => {
+        if (field.type === "select") {
+            const v = values[field.key];
+            return field.options.find((o) => String(o.value) === String(v))?.label ?? String(v);
+        }
+        if (field.type === "daterange") {
+            const from = values[`${field.key}From`];
+            const to = values[`${field.key}To`];
+            return `${from || "…"} → ${to || "…"}`;
+        }
+        return values[field.key] ?? "";
+    });
+
+    function clear() {
+        for (const k of fieldKeys(field)) values[k] = "";
+    }
+
+    // Tell the parent when the editor closes so an abandoned "just added" pill
+    // (opened but left blank) can be dropped from the visible set.
+    let wasOpen = false;
+    $effect(() => {
+        if (wasOpen && !open) onClose?.();
+        wasOpen = open;
+    });
+
+    // Date-range quick presets. Browser runtime, so reading the clock is fine.
+    const DAY_MS = 86_400_000;
+    const isoDay = (ms: number) => new Date(ms).toISOString().slice(0, 10);
+    function setRange(days: number) {
+        if (field.type !== "daterange") return;
+        const now = Date.now();
+        values[`${field.key}From`] = isoDay(now - days * DAY_MS);
+        values[`${field.key}To`] = isoDay(now);
+    }
+</script>
+
+<!--
+  Split pill: the body opens the editor (Popover trigger); the trailing ✕ is a
+  separate sibling button that clears the field. Keeping ✕ outside the Popover
+  trigger avoids nesting one interactive control inside another.
+-->
+<div
+    class="inline-flex items-center rounded-[3px] border text-sm {active
+        ? 'border-primary-soft-border bg-primary-soft text-primary-soft-text'
+        : 'border-outline bg-surface-raised text-on-surface-muted hover:border-outline-hover hover:text-on-surface'}"
+>
+    <Popover bind:open placement="bottom-start" mobileSheet>
+        {#snippet trigger()}
+            <span class="inline-flex cursor-pointer items-center gap-1.5 px-3 py-2">
+                <span class="truncate">
+                    {label}{#if active}<span class="font-medium">: {summary}</span>{/if}
+                </span>
+                {#if !active}<ChevronDown size={14} class="opacity-60" />{/if}
+            </span>
+        {/snippet}
+
+        {#if field.type === "select"}
+            <div class="flex w-52 flex-col gap-0.5">
+                {#each field.options as opt (String(opt.value))}
+                    {@const selected = String(values[field.key] ?? "") === String(opt.value)}
+                    <button
+                        type="button"
+                        class="flex items-center justify-between gap-2 rounded-[3px] px-2.5 py-1.5 text-left text-sm hover:bg-surface-sunken {selected
+                            ? 'text-on-surface'
+                            : 'text-on-surface-muted'}"
+                        onclick={() => {
+                            values[field.key] = String(opt.value);
+                            open = false;
+                        }}
+                    >
+                        <span class="truncate">{opt.label}</span>
+                        {#if selected}<Check size={15} class="shrink-0 text-primary" />{/if}
+                    </button>
+                {/each}
+            </div>
+        {:else if field.type === "number"}
+            <div class="w-44">
+                <Input
+                    type="number"
+                    value={values[field.key] ?? ""}
+                    placeholder={field.placeholder ?? field.label}
+                    autofocus
+                    onchange={(e) => (values[field.key] = e.currentTarget.value)}
+                    onkeydown={(e) => {
+                        if (e.key === "Enter") open = false;
+                    }}
+                />
+            </div>
+        {:else if field.type === "daterange"}
+            <div class="flex w-64 flex-col gap-3">
+                <div class="flex items-center gap-2">
+                    <label class="flex-1">
+                        <span class="mb-1 block text-xs text-on-surface-faint">From</span>
+                        <Input type="date" bind:value={values[`${field.key}From`]} size="sm" />
+                    </label>
+                    <label class="flex-1">
+                        <span class="mb-1 block text-xs text-on-surface-faint">To</span>
+                        <Input type="date" bind:value={values[`${field.key}To`]} size="sm" />
+                    </label>
+                </div>
+                <div class="flex flex-wrap gap-1.5">
+                    {#each [{ label: "Today", days: 0 }, { label: "7 days", days: 7 }, { label: "30 days", days: 30 }] as p (p.days)}
+                        <button
+                            type="button"
+                            class="rounded-[3px] border border-outline bg-surface-raised px-2 py-1 text-xs text-on-surface-muted hover:border-outline-hover hover:text-on-surface"
+                            onclick={() => setRange(p.days)}
+                        >
+                            {p.label}
+                        </button>
+                    {/each}
+                    {#if !isBlank(values[`${field.key}From`]) || !isBlank(values[`${field.key}To`])}
+                        <button
+                            type="button"
+                            class="ml-auto rounded-[3px] px-2 py-1 text-xs text-on-surface-muted hover:text-on-surface"
+                            onclick={() => clear()}
+                        >
+                            Clear
+                        </button>
+                    {/if}
+                </div>
+            </div>
+        {/if}
+    </Popover>
+
+    {#if active}
+        <button
+            type="button"
+            class="self-stretch rounded-r-[3px] border-l border-primary-soft-border px-2 hover:bg-primary/15"
+            onclick={clear}
+            aria-label="Clear {label} filter"
+        >
+            <X size={13} />
+        </button>
+    {/if}
+</div>

package/src/lib/components/NotificationBell.svelte

@@ -0,0 +1,70 @@
+<!-- SPDX-FileCopyrightText: PoppyCake, s.r.o. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+<!--
+  Header bell + unread badge + popover shell. The app owns the store and the
+  list items (they're domain-specific); it passes them in as `children`.
+-->
+
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    import { Bell } from "@lucide/svelte";
+    import Popover from "./Popover.svelte";
+
+    interface Props {
+        unread: number;
+        /** Badge colour: "danger" when an unread item is an error. */
+        tone?: "primary" | "danger";
+        open?: boolean;
+        /** Panel title; the right side of the header takes `actions`. */
+        title?: string;
+        actions?: Snippet;
+        children: Snippet;
+        class?: string;
+    }
+
+    let {
+        unread,
+        tone = "primary",
+        open = $bindable(false),
+        title = "Notifications",
+        actions,
+        children,
+        class: className = "",
+    }: Props = $props();
+
+    let badge = $derived(unread > 99 ? "99+" : String(unread));
+</script>
+
+<Popover bind:open placement="bottom-end" mobileSheet class="flex {className}">
+    {#snippet trigger()}
+        <span
+            class="relative flex h-9 w-9 items-center justify-center rounded-[3px] border border-transparent text-on-surface-muted hover:border-outline-hover hover:bg-surface-sunken hover:text-primary"
+            title="Notifications"
+        >
+            <Bell size={18} aria-hidden="true" />
+            <span class="sr-only">{title}</span>
+            {#if unread > 0}
+                <span
+                    class="absolute -top-0.5 -right-0.5 inline-flex min-w-[18px] items-center justify-center rounded-full px-1 font-mono text-2xs font-bold tabular-nums {tone ===
+                    'danger'
+                        ? 'bg-danger-surface text-on-danger'
+                        : 'bg-primary text-on-primary'}"
+                    aria-label={`${badge} unread`}
+                >
+                    {badge}
+                </span>
+            {/if}
+        </span>
+    {/snippet}
+
+    <div role="dialog" aria-label={title} class="w-96 max-w-[90vw]">
+        <div class="mb-2 flex items-center justify-between gap-2">
+            <h2 class="font-mono text-sm font-semibold text-on-surface">{title}</h2>
+            {#if actions}
+                <div class="flex items-center gap-3 text-xs">{@render actions()}</div>
+            {/if}
+        </div>
+        {@render children()}
+    </div>
+</Popover>

package/src/lib/components/SearchInput.svelte

@@ -0,0 +1,91 @@
+<!-- SPDX-FileCopyrightText: PoppyCake, s.r.o. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+<!--
+  Debounced search box for FilterBar. `value` is the committed term the parent
+  filters on; keystrokes are debounced so client re-filtering / server refetch
+  fires once the user pauses, not per character. `Esc` and the trailing ✕ clear
+  immediately. Exposes its raw <input> via `element` so FilterBar's `/` shortcut
+  can focus it.
+-->
+
+<script lang="ts">
+    import Input from "./Input.svelte";
+    import { Search, X } from "@lucide/svelte";
+    import { untrack, onDestroy } from "svelte";
+    import { debounce } from "../utils/debounce.js";
+
+    let {
+        value = $bindable(""),
+        placeholder = "Search...",
+        element = $bindable<HTMLInputElement | null>(null),
+    }: {
+        value?: string | undefined;
+        placeholder?: string;
+        element?: HTMLInputElement | null;
+    } = $props();
+
+    // `raw` is the live text; `value` is the debounced, committed term. Seeded
+    // once from `value` so a URL-restored search survives mount undebounced.
+    let raw = $state(value);
+    let wrapperEl = $state<HTMLDivElement | null>(null);
+
+    const commit = debounce((v: string) => (value = v), 250);
+    onDestroy(() => commit.cancel());
+
+    // Expose the real input for FilterBar's `/`-to-focus shortcut.
+    $effect(() => {
+        element = wrapperEl?.querySelector("input") ?? null;
+    });
+
+    // External writes to `value` (Reset / clear-all) win immediately: adopt them
+    // and drop any pending debounce. Depends only on `value` (raw is read
+    // untracked), so typing never re-enters here. Tiny race: a reset that leaves
+    // `value` unchanged ("" -> "") can't cancel a first-keystroke debounce —
+    // negligible at 250ms. ponytail: guarded two-way sync, fine for one field.
+    $effect(() => {
+        const v = value;
+        untrack(() => {
+            if (v !== raw) {
+                commit.cancel();
+                raw = v;
+            }
+        });
+    });
+
+    function clear() {
+        commit.cancel();
+        raw = "";
+        value = "";
+        wrapperEl?.querySelector("input")?.focus();
+    }
+
+    function onKeydown(e: KeyboardEvent) {
+        if (e.key === "Escape" && raw) {
+            e.preventDefault();
+            clear();
+        }
+    }
+</script>
+
+<div bind:this={wrapperEl} class="relative w-full sm:w-64">
+    <Input
+        bind:value={raw}
+        {placeholder}
+        oninput={() => commit(raw)}
+        onkeydown={onKeydown}
+        style={raw ? "padding-right:2.25rem" : undefined}
+    >
+        {#snippet leadingIcon()}<Search size={16} />{/snippet}
+    </Input>
+    {#if raw}
+        <button
+            type="button"
+            class="absolute top-1/2 right-2 -translate-y-1/2 rounded-[3px] p-1 text-on-surface-faint hover:bg-surface-sunken hover:text-on-surface"
+            onclick={clear}
+            aria-label="Clear search"
+        >
+            <X size={14} />
+        </button>
+    {/if}
+</div>

package/src/lib/components/StatusDot.svelte

@@ -0,0 +1,38 @@
+<!-- SPDX-FileCopyrightText: PoppyCake, s.r.o. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+<script lang="ts" module>
+    export type StatusDotTone = "primary" | "success" | "warning" | "danger" | "muted";
+</script>
+
+<script lang="ts">
+    interface Props {
+        tone?: StatusDotTone;
+        /** Radar ping around the dot — use for "live" states only. */
+        pulse?: boolean;
+        size?: "sm" | "md" | "lg";
+        class?: string;
+    }
+
+    let { tone = "primary", pulse = false, size = "sm", class: className = "" }: Props = $props();
+
+    const TONES: Record<StatusDotTone, string> = {
+        primary: "bg-primary",
+        success: "bg-success-surface",
+        warning: "bg-warning-surface",
+        danger: "bg-danger-surface",
+        muted: "bg-on-surface-faint",
+    };
+    const SIZES = { sm: "h-2 w-2", md: "h-2.5 w-2.5", lg: "h-3.5 w-3.5" };
+</script>
+
+<span class="relative flex shrink-0 {SIZES[size]} {className}" aria-hidden="true">
+    {#if pulse}
+        <span
+            class="absolute inline-flex h-full w-full animate-ping rounded-full opacity-75 motion-reduce:animate-none {TONES[
+                tone
+            ]}"
+        ></span>
+    {/if}
+    <span class="relative inline-flex h-full w-full rounded-full {TONES[tone]}"></span>
+</span>

package/src/lib/components/ThemeToggle.svelte

@@ -2,46 +2,41 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
 <script lang="ts">
-    import { Moon, Sun } from "@lucide/svelte";
+    import { ChevronDown, Monitor, Moon, Sun } from "@lucide/svelte";
+    import Dropdown from "./Dropdown.svelte";
+    import { themeStore, type ThemePreference } from "../utils/theme.svelte.js";
 
     interface Props {
-        storageKey?: string;
         class?: string;
     }
 
-    let { storageKey = "runwisp:theme", class: className = "" }: Props = $props();
+    let { class: className = "" }: Props = $props();
 
-    let isDark = $state(false);
-    let mounted = $state(false);
+    const options: { value: ThemePreference; label: string; icon: typeof Monitor }[] = [
+        { value: "auto", label: "Auto", icon: Monitor },
+        { value: "light", label: "Light", icon: Sun },
+        { value: "dark", label: "Dark", icon: Moon },
+    ];
 
-    $effect(() => {
-        isDark = document.documentElement.classList.contains("dark");
-        mounted = true;
-    });
+    let TriggerIcon = $derived(
+        themeStore.preference === "auto" ? Monitor : themeStore.resolved === "dark" ? Moon : Sun,
+    );
 
-    function toggle(): void {
-        const next = !isDark;
-        isDark = next;
-        document.documentElement.classList.toggle("dark", next);
-        try {
-            localStorage.setItem(storageKey, next ? "dark" : "light");
-        } catch {
-            // localStorage may be unavailable (private mode, embedded contexts) — fall through.
-        }
-    }
+    let items = $derived(
+        options.map((o) => ({
+            label: o.label,
+            icon: o.icon,
+            selected: themeStore.preference === o.value,
+            onClick: () => themeStore.set(o.value),
+        })),
+    );
 </script>
 
-<button
-    type="button"
-    onclick={toggle}
-    aria-pressed={isDark}
-    aria-label={isDark ? "Switch to light theme" : "Switch to dark theme"}
-    title={isDark ? "Switch to light theme" : "Switch to dark theme"}
-    class="inline-flex h-9 w-9 items-center justify-center rounded-[3px] border border-outline bg-surface-raised text-on-surface-muted hover:border-outline-hover hover:text-on-surface {className}"
->
-    {#if mounted && isDark}
-        <Sun size={16} />
-    {:else}
-        <Moon size={16} />
-    {/if}
-</button>
+<Dropdown {items} align="right" triggerLabel="Theme" class={className}>
+    {#snippet trigger()}
+        <span class="flex items-center gap-1">
+            <TriggerIcon size={18} />
+            <ChevronDown size={14} class="opacity-60" />
+        </span>
+    {/snippet}
+</Dropdown>

package/src/lib/components/filter-spec.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: PoppyCake, s.r.o.
+// SPDX-License-Identifier: Apache-2.0
+
+// Declarative filter spec. A `FilterField[]` + one bound `FilterValues` object
+// drives <FilterBar>, the client engine (`applyFilters`), and the URL sync
+// helper — the same way DataGrid's `Column[]` drives the table. Add a field
+// type here, and every table that adopts it renders identically.
+
+import type { SelectOption } from "./Select.svelte";
+
+// `path` (where present) is the dot-path read on the row for client-side
+// matching; it defaults to `key`. `key` is also the slot in `FilterValues` and
+// the URL query param. Search fields test `fields` (dot-paths) instead.
+export type FilterField =
+    | {
+          type: "search";
+          key: string;
+          fields: string[];
+          placeholder?: string;
+          primary?: boolean;
+      }
+    | {
+          type: "select";
+          key: string;
+          label: string;
+          options: SelectOption[];
+          path?: string;
+          primary?: boolean;
+      }
+    | {
+          type: "number";
+          key: string;
+          label: string;
+          placeholder?: string;
+          path?: string;
+          primary?: boolean;
+      }
+    | {
+          // Stored as two values: `${key}From` / `${key}To` (yyyy-mm-dd).
+          type: "daterange";
+          key: string;
+          label: string;
+          path?: string;
+          primary?: boolean;
+      };
+
+// All values are strings — DOM inputs are string-valued and URL params are
+// strings; the client engine coerces (e.g. Number()) where a field needs it.
+export type FilterValues = Record<string, string>;
+
+// The full state a list emits via onQueryChange: FilterBar values + sort +
+// pagination. The host mirrors this to the URL; server-mode lists also
+// map it to REST query params.
+export interface TableQuery {
+    values: FilterValues;
+    sortKey?: string;
+    sortDir?: "asc" | "desc";
+    page: number;
+    pageSize: number;
+}
+
+// A select value is "inactive" (matches everything) when blank, undefined, or
+// the conventional "all" sentinel some existing option lists use.
+export function isBlank(v: string | undefined): boolean {
+    return !v || v === "all";
+}
+
+// Which value keys a field owns — daterange owns two, everything else one.
+// Used by chips, active-state detection, clear, and URL (de)serialization so
+// none of them has to special-case the range type.
+export function fieldKeys(field: FilterField): string[] {
+    return field.type === "daterange" ? [`${field.key}From`, `${field.key}To`] : [field.key];
+}
+
+export function isFieldActive(field: FilterField, values: FilterValues): boolean {
+    return fieldKeys(field).some((k) => !isBlank(values[k]));
+}
+
+// Human label for a field. Every type but `search` carries one; search has no
+// label (its box speaks for itself), so fall back to the key for the narrower.
+export function fieldLabel(field: FilterField): string {
+    return "label" in field ? field.label : field.key;
+}
+
+// Seed a values object with every field's keys present (blank), overlaid with
+// any initial values (e.g. from the URL). Keeping all keys present up front
+// keeps the emitted query reactive to each field and the bindings simple.
+export function seedValues(fields: FilterField[], initial: FilterValues = {}): FilterValues {
+    const values: FilterValues = {};
+    for (const f of fields) {
+        for (const k of fieldKeys(f)) values[k] = initial[k] ?? "";
+    }
+    return values;
+}

package/src/lib/index.ts

@@ -33,7 +33,7 @@ export { default as FormField } from "./components/FormField.svelte";
 export { default as Input } from "./components/Input.svelte";
 export { default as Radio } from "./components/Radio.svelte";
 export { default as RadioGroup } from "./components/RadioGroup.svelte";
-export { default as Select } from "./components/Select.svelte";
+export { default as Select, type SelectOption } from "./components/Select.svelte";
 export { default as Textarea } from "./components/Textarea.svelte";
 export { default as TimezoneSelect } from "./components/TimezoneSelect.svelte";
 export { default as Toggle } from "./components/Toggle.svelte";
@@ -47,9 +47,25 @@ export { default as Avatar } from "./components/Avatar.svelte";
 export { default as Badge } from "./components/Badge.svelte";
 export { default as Card } from "./components/Card.svelte";
 export { default as DataGrid } from "./components/DataGrid.svelte";
+export type { Column, DataGridProps } from "./components/DataGrid.svelte";
+export { default as FilterBar } from "./components/FilterBar.svelte";
+export { default as FilterPill } from "./components/FilterPill.svelte";
+export { default as SearchInput } from "./components/SearchInput.svelte";
+export {
+    fieldKeys,
+    fieldLabel,
+    isBlank,
+    isFieldActive,
+    seedValues,
+    type FilterField,
+    type FilterValues,
+    type TableQuery,
+} from "./components/filter-spec.js";
+export { applyFilters, matchesQuery, resolvePath } from "./utils/filter.js";
 export { default as Progress } from "./components/Progress.svelte";
 export { default as Skeleton } from "./components/Skeleton.svelte";
 export { default as Sparkline } from "./components/Sparkline.svelte";
+export { default as StatusDot, type StatusDotTone } from "./components/StatusDot.svelte";
 export { default as StatusIndicator } from "./components/StatusIndicator.svelte";
 export { default as Table } from "./components/Table.svelte";
 export { default as TableBody } from "./components/TableBody.svelte";
@@ -64,9 +80,11 @@ export { default as Dropdown } from "./components/Dropdown.svelte";
 export { default as EmptyState } from "./components/EmptyState.svelte";
 export { default as ErrorState } from "./components/ErrorState.svelte";
 export { default as Modal } from "./components/Modal.svelte";
+export { default as NotificationBell } from "./components/NotificationBell.svelte";
 export { default as Popover } from "./components/Popover.svelte";
 export { default as ToastContainer } from "./components/ToastContainer.svelte";
 export { default as Tooltip } from "./components/Tooltip.svelte";
+export { default as ThemeToggle } from "./components/ThemeToggle.svelte";
 
 export { default as CodeBlock } from "./components/CodeBlock.svelte";
 export { default as TaskCard } from "./components/TaskCard.svelte";
@@ -118,6 +136,12 @@ export { humanizeCron, type HumanizedCron } from "./components/dashboard/cron-fo
 export type { DaemonState, DaemonStats } from "./components/dashboard/types.js";
 
 export { toast, type Toast, type ToastType } from "./utils/toast.svelte.js";
+export {
+    themeStore,
+    THEME_STORAGE_KEY,
+    type ThemePreference,
+    type ResolvedTheme,
+} from "./utils/theme.svelte.js";
 export { extractErrorMessage } from "./utils/error.js";
 export {
     formatBytes,
@@ -128,4 +152,5 @@ export {
     formatFullDateTime,
 } from "./utils/format.js";
 export { formatShortId } from "./utils/id.js";
+export { debounce } from "./utils/debounce.js";
 export { TickingNow } from "./utils/ticking-now.svelte.js";

package/src/lib/utils/debounce.test.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: PoppyCake, s.r.o.
+// SPDX-License-Identifier: Apache-2.0
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { debounce } from "./debounce.js";
+
+describe("debounce", () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    it("collapses rapid calls into one trailing call with the last args", () => {
+        const fn = vi.fn();
+        const d = debounce(fn, 20);
+        d(1);
+        d(2);
+        d(3);
+        expect(fn).not.toHaveBeenCalled();
+        vi.advanceTimersByTime(20);
+        expect(fn).toHaveBeenCalledTimes(1);
+        expect(fn).toHaveBeenCalledWith(3);
+    });
+
+    it("cancel drops the pending call", () => {
+        const fn = vi.fn();
+        const d = debounce(fn, 20);
+        d();
+        d.cancel();
+        vi.advanceTimersByTime(40);
+        expect(fn).not.toHaveBeenCalled();
+    });
+});

package/src/lib/utils/debounce.ts

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: PoppyCake, s.r.o.
+// SPDX-License-Identifier: Apache-2.0
+
+// Trailing-edge debounce. Returns a wrapper that defers `fn` until `ms` have
+// elapsed since the last call; `.cancel()` drops a pending call (used when an
+// external write must win immediately, e.g. Reset clearing a debounced field).
+export function debounce<A extends unknown[]>(
+    fn: (...args: A) => void,
+    ms: number,
+): ((...args: A) => void) & { cancel: () => void } {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const wrapped = (...args: A) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            fn(...args);
+        }, ms);
+    };
+    wrapped.cancel = () => {
+        clearTimeout(timer);
+    };
+    return wrapped;
+}