@runwisp/ui 1.0.1 → 1.2.0

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,7 @@ 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";
+export { RunMotion } from "./utils/run-motion.js";
+export { arrival, leave, shift, prefersReducedMotion } from "./actions/row-motion.js";

package/src/lib/theme.css

@@ -298,3 +298,42 @@ h3 {
 .btn-scale:active {
     transform: scale(0.97);
 }
+
+/* Live arrival: the row drops in, then a primary ring glows and fades so the
+   eye finds the new run. Added by the `arrival` action; `translate` composes
+   with any inline `transform`. */
+.run-arrive {
+    border-radius: 3px;
+    animation: run-arrive 1.2s ease-out;
+}
+@keyframes run-arrive {
+    0% {
+        opacity: 0;
+        translate: 0 -6px;
+        box-shadow: 0 0 0 1px var(--color-primary);
+    }
+    18% {
+        opacity: 1;
+        translate: 0 0;
+        box-shadow:
+            0 0 0 1px var(--color-primary),
+            0 0 12px color-mix(in srgb, var(--color-primary) 35%, transparent);
+    }
+    100% {
+        box-shadow: 0 0 0 1px transparent;
+    }
+}
+@keyframes run-arrive-still {
+    0%,
+    18% {
+        box-shadow: 0 0 0 1px var(--color-primary);
+    }
+    100% {
+        box-shadow: 0 0 0 1px transparent;
+    }
+}
+@media (prefers-reduced-motion: reduce) {
+    .run-arrive {
+        animation-name: run-arrive-still;
+    }
+}

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

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

@@ -0,0 +1,172 @@
+// SPDX-FileCopyrightText: PoppyCake, s.r.o.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+import { applyFilters, matchesQuery, resolvePath } from "./filter.js";
+import {
+    type FilterField,
+    fieldKeys,
+    fieldLabel,
+    isBlank,
+    isFieldActive,
+    seedValues,
+} from "../components/filter-spec.js";
+
+interface Row {
+    id: string;
+    status: string;
+    exitCode: number;
+    roles: string[];
+    user: { name: string };
+    startedAt: Date;
+}
+
+const rows: Row[] = [
+    {
+        id: "a",
+        status: "ok",
+        exitCode: 0,
+        roles: ["owner"],
+        user: { name: "Ada" },
+        startedAt: new Date("2026-01-10"),
+    },
+    {
+        id: "b",
+        status: "err",
+        exitCode: 1,
+        roles: ["viewer"],
+        user: { name: "Bob" },
+        startedAt: new Date("2026-02-20"),
+    },
+    {
+        id: "c",
+        status: "ok",
+        exitCode: 2,
+        roles: ["owner", "viewer"],
+        user: { name: "Cy" },
+        startedAt: new Date("2026-03-30"),
+    },
+];
+
+const range: FilterField = { type: "daterange", key: "startedAt", label: "Date" };
+const search: FilterField = { type: "search", key: "q", fields: ["id", "user.name"] };
+const status: FilterField = { type: "select", key: "status", label: "Status", options: [] };
+
+const fields: FilterField[] = [
+    search,
+    status,
+    { type: "select", key: "role", label: "Role", path: "roles", options: [] },
+    { type: "number", key: "exitCode", label: "Exit" },
+    range,
+];
+
+const ids = (r: Row[]) => r.map((x) => x.id);
+
+describe("applyFilters", () => {
+    it("passes everything through when values are empty", () => {
+        expect(applyFilters(rows, fields, {})).toHaveLength(3);
+    });
+
+    it("searches dot-paths case-insensitively", () => {
+        expect(ids(applyFilters(rows, fields, { q: "ad" }))).toEqual(["a"]);
+    });
+
+    it("matches select by equality and treats 'all' as inactive", () => {
+        expect(ids(applyFilters(rows, fields, { status: "ok" }))).toEqual(["a", "c"]);
+        expect(applyFilters(rows, fields, { status: "all" })).toHaveLength(3);
+    });
+
+    it("matches select against an array cell by membership", () => {
+        expect(ids(applyFilters(rows, fields, { role: "viewer" }))).toEqual(["b", "c"]);
+    });
+
+    it("coerces number values", () => {
+        expect(ids(applyFilters(rows, fields, { exitCode: "1" }))).toEqual(["b"]);
+        expect(ids(applyFilters(rows, fields, { exitCode: "0" }))).toEqual(["a"]);
+    });
+
+    it("filters a date range inclusively on both ends", () => {
+        expect(
+            ids(
+                applyFilters(rows, fields, {
+                    startedAtFrom: "2026-02-01",
+                    startedAtTo: "2026-03-30",
+                }),
+            ),
+        ).toEqual(["b", "c"]);
+    });
+
+    it("ANDs combined filters", () => {
+        expect(ids(applyFilters(rows, fields, { status: "ok", role: "viewer" }))).toEqual(["c"]);
+    });
+
+    it("coerces non-string select cells (number, boolean, date) and skips the rest", () => {
+        interface Flagged {
+            id: string;
+            flags: unknown[];
+        }
+        const flaggedRows: Flagged[] = [
+            { id: "a", flags: [1, true, new Date("2026-01-01T00:00:00.000Z"), {}] },
+            { id: "b", flags: [0, false] },
+        ];
+        const flagField: FilterField = {
+            type: "select",
+            key: "flag",
+            label: "Flag",
+            path: "flags",
+            options: [],
+        };
+        const flagIds = (r: Flagged[]) => r.map((x) => x.id);
+        expect(flagIds(applyFilters(flaggedRows, [flagField], { flag: "1" }))).toEqual(["a"]);
+        expect(flagIds(applyFilters(flaggedRows, [flagField], { flag: "true" }))).toEqual(["a"]);
+        expect(
+            flagIds(
+                applyFilters(flaggedRows, [flagField], {
+                    flag: new Date("2026-01-01T00:00:00.000Z").toISOString(),
+                }),
+            ),
+        ).toEqual(["a"]);
+        expect(applyFilters(flaggedRows, [flagField], { flag: "no-such-value" })).toHaveLength(0);
+    });
+});
+
+describe("filter helpers", () => {
+    it("matchesQuery skips nullish fields and matches empty queries", () => {
+        expect(matchesQuery("", null)).toBe(true);
+        expect(matchesQuery("x", null, undefined)).toBe(false);
+        expect(matchesQuery("OB", "bob")).toBe(true);
+    });
+
+    it("resolvePath reads nested fields and misses gracefully", () => {
+        expect(resolvePath(rows[0], "user.name")).toBe("Ada");
+        expect(resolvePath(rows[0], "user.missing.deep")).toBeUndefined();
+    });
+
+    it("isBlank treats blank, undefined, and 'all' as inactive", () => {
+        expect(isBlank(undefined)).toBe(true);
+        expect(isBlank("")).toBe(true);
+        expect(isBlank("all")).toBe(true);
+        expect(isBlank("0")).toBe(false);
+    });
+
+    it("fieldLabel uses the label, falling back to the key for search fields", () => {
+        expect(fieldLabel(status)).toBe("Status");
+        expect(fieldLabel(search)).toBe("q");
+    });
+
+    it("daterange owns two value keys", () => {
+        expect(fieldKeys(range)).toEqual(["startedAtFrom", "startedAtTo"]);
+        expect(isFieldActive(range, { startedAtTo: "2026-01-01" })).toBe(true);
+    });
+
+    it("seedValues fills every key and overlays initial values", () => {
+        expect(seedValues(fields, { status: "ok", extra: "dropped" })).toEqual({
+            q: "",
+            status: "ok",
+            role: "",
+            exitCode: "",
+            startedAtFrom: "",
+            startedAtTo: "",
+        });
+    });
+});

package/src/lib/utils/filter.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: PoppyCake, s.r.o.
+// SPDX-License-Identifier: Apache-2.0
+
+import { type FilterField, type FilterValues, isBlank } from "../components/filter-spec.js";
+
+// Case-insensitive substring match against any of the given fields. Empty
+// query matches everything; nullish fields are skipped.
+export function matchesQuery(query: string, ...fields: (string | null | undefined)[]): boolean {
+    if (!query) return true;
+    const q = query.toLowerCase();
+    return fields.some((f) => f?.toLowerCase().includes(q) === true);
+}
+
+// Dot-path aware field read: resolves "user.name" against nested objects.
+// Shared by DataGrid's sort comparator and the filter engine below so both
+// read fields the same way.
+export function resolvePath(obj: unknown, path: string): unknown {
+    return path
+        .split(".")
+        .reduce<unknown>(
+            (acc, k): unknown =>
+                typeof acc === "object" && acc !== null ? Reflect.get(acc, k) : undefined,
+            obj,
+        );
+}
+
+// Scalar cell → the string a filter value is compared against. Objects and
+// nullish cells have no text form, so they never match a search or select.
+function toText(v: unknown): string | null {
+    if (typeof v === "string") return v;
+    if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+    if (v instanceof Date) return v.toISOString();
+    return null;
+}
+
+// Array cell (e.g. member roles) → membership; scalar → equality.
+function matchSelect(cell: unknown, v: string): boolean {
+    return Array.isArray(cell) ? cell.some((c) => toText(c) === v) : toText(cell) === v;
+}
+
+// Inclusive yyyy-mm-dd range. The ISO date portion sorts lexically, so a
+// string compare is enough.
+function matchDateRange(cell: unknown, from: string | undefined, to: string | undefined): boolean {
+    if (isBlank(from) && isBlank(to)) return true;
+    const d = cell instanceof Date ? cell : new Date(toText(cell) ?? "");
+    if (Number.isNaN(d.getTime())) return false;
+    const day = d.toISOString().slice(0, 10);
+    return (isBlank(from) || day >= (from ?? "")) && (isBlank(to) || day <= (to ?? ""));
+}
+
+function matchField(row: unknown, field: FilterField, values: FilterValues): boolean {
+    switch (field.type) {
+        case "search":
+            return matchesQuery(
+                values[field.key] ?? "",
+                ...field.fields.map((p) => toText(resolvePath(row, p))),
+            );
+        case "select": {
+            const v = values[field.key];
+            return isBlank(v) || matchSelect(resolvePath(row, field.path ?? field.key), v ?? "");
+        }
+        case "number": {
+            const v = values[field.key];
+            return isBlank(v) || Number(resolvePath(row, field.path ?? field.key)) === Number(v);
+        }
+        case "daterange":
+            return matchDateRange(
+                resolvePath(row, field.path ?? field.key),
+                values[`${field.key}From`],
+                values[`${field.key}To`],
+            );
+    }
+}
+
+// Client-side filter engine: a row survives when every field matches.
+// Server-mode tables map the same `values` to query params instead.
+export function applyFilters<T>(rows: T[], fields: FilterField[], values: FilterValues): T[] {
+    return rows.filter((row) => fields.every((f) => matchField(row, f, values)));
+}

package/src/lib/utils/run-motion.test.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: PoppyCake, s.r.o.
+// SPDX-License-Identifier: Apache-2.0
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { RunMotion } from "./run-motion.js";
+
+const WINDOW_MS = 2000;
+
+describe("RunMotion", () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    it("reports nothing for a run it was never told about", () => {
+        const motion = new RunMotion();
+        expect(motion.arrived("run-1")).toBe(false);
+        expect(motion.removed("run-1")).toBe(false);
+    });
+
+    it("keeps arrivals and removals apart", () => {
+        const motion = new RunMotion();
+        motion.markArrived("arrived-run");
+        motion.markRemoved("removed-run");
+        expect(motion.arrived("arrived-run")).toBe(true);
+        expect(motion.removed("arrived-run")).toBe(false);
+        expect(motion.removed("removed-run")).toBe(true);
+        expect(motion.arrived("removed-run")).toBe(false);
+    });
+
+    it("forgets a run once the window passes, so a later click doesn't animate it", () => {
+        const motion = new RunMotion();
+        motion.markArrived("run-1");
+        motion.markRemoved("run-2");
+        vi.advanceTimersByTime(WINDOW_MS - 1);
+        expect(motion.arrived("run-1")).toBe(true);
+        expect(motion.removed("run-2")).toBe(true);
+        vi.advanceTimersByTime(1);
+        expect(motion.arrived("run-1")).toBe(false);
+        expect(motion.removed("run-2")).toBe(false);
+    });
+
+    it("prunes expired runs when a later one is marked", () => {
+        const motion = new RunMotion();
+        motion.markArrived("old-run");
+        vi.advanceTimersByTime(WINDOW_MS);
+        motion.markArrived("new-run");
+        expect(motion.arrived("old-run")).toBe(false);
+        expect(motion.arrived("new-run")).toBe(true);
+    });
+
+    it("re-marking a run restarts its window", () => {
+        const motion = new RunMotion();
+        motion.markArrived("run-1");
+        vi.advanceTimersByTime(WINDOW_MS - 1);
+        motion.markArrived("run-1");
+        vi.advanceTimersByTime(WINDOW_MS - 1);
+        expect(motion.arrived("run-1")).toBe(true);
+    });
+
+    it("clear forgets everything", () => {
+        const motion = new RunMotion();
+        motion.markArrived("arrived-run");
+        motion.markRemoved("removed-run");
+        motion.clear();
+        expect(motion.arrived("arrived-run")).toBe(false);
+        expect(motion.removed("removed-run")).toBe(false);
+    });
+});

package/src/lib/utils/run-motion.ts

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: PoppyCake, s.r.o.
+// SPDX-License-Identifier: Apache-2.0
+
+// Long enough to span an SSE insert and the trigger's HTTP response that
+// selects the new run; short enough that a later click never re-animates it.
+const WINDOW_MS = 2000;
+
+class RecentIds {
+    readonly #at = new Map<string, number>();
+
+    mark(id: string): void {
+        const now = Date.now();
+        for (const [known, at] of this.#at) {
+            if (now - at >= WINDOW_MS) this.#at.delete(known);
+        }
+        this.#at.set(id, now);
+    }
+
+    has(id: string): boolean {
+        const at = this.#at.get(id);
+        return at !== undefined && Date.now() - at < WINDOW_MS;
+    }
+
+    clear(): void {
+        this.#at.clear();
+    }
+}
+
+/**
+ * Remembers which runs arrived or were removed live moments ago (a trigger, a
+ * scheduled firing, a run finishing, a delete), as opposed to rows that a page
+ * fetch, scroll or filter change loaded or dropped, so only genuine changes
+ * animate. Plain (non-reactive): it is only read at mount, unmount or
+ * selection time.
+ */
+export class RunMotion {
+    readonly #arrived = new RecentIds();
+    readonly #removed = new RecentIds();
+
+    markArrived(runId: string): void {
+        this.#arrived.mark(runId);
+    }
+
+    markRemoved(runId: string): void {
+        this.#removed.mark(runId);
+    }
+
+    // Arrows so they can be handed around unbound.
+    arrived = (runId: string): boolean => this.#arrived.has(runId);
+    removed = (runId: string): boolean => this.#removed.has(runId);
+
+    clear(): void {
+        this.#arrived.clear();
+        this.#removed.clear();
+    }
+}