@joewinke/jatui 0.20.0 → 0.22.0

package/CLAUDE.md

@@ -26,7 +26,7 @@ Then import:
 | `SelectInput` | Dropdown select | `label`, `value` (bindable), `options: SelectOption[]`, `placeholder` |
 | `PhoneInput` | Intl phone (country dropdown + tel input, outputs E.164; caps national digits per country). Fires `onChange(value)` on every change. | `value` (bindable), `name`, `defaultCountry`, `required`, `onChange` |
 | `ChipInput` | Tag/chip entry with suggestions | `chips` (bindable), `suggestions: SuggestionGroup[]`, `placeholder` |
-| `SearchDropdown` | Searchable dropdown with grouped results, keyboard nav, avatar/initials options. `appendToBody` escapes table/overflow stacking contexts; `variant='chip'` renders a compact pill; `size='sm'` a smaller trigger; `dropup` opens upward; `clearable` shows an × when a value is set. Exposes `openDropdown()`. | `groups: SearchDropdownGroup[]`, `value`, `onChange`, `placeholder`, `variant`, `size`, `dropup`, `appendToBody`, `clearable`, `colorFn` |
+| `SearchDropdown` | Searchable dropdown with grouped results, keyboard nav, avatar/initials options. `appendToBody` escapes table/overflow stacking contexts; `variant='chip'` renders a compact pill; `size='sm'` a smaller trigger; `dropup` opens upward; `clearable` shows an × when a value is set. `onSearch` turns the built-in search box into a debounced server-side search hook (fires on open/clear with `''`; internal filtering is bypassed — the consumer updates `groups`). Exposes `openDropdown()`. | `groups: SearchDropdownGroup[]`, `value`, `onChange`, `placeholder`, `variant`, `size`, `dropup`, `appendToBody`, `clearable`, `colorFn`, `onSearch`, `searchDebounceMs` |
 | `FilterDropdown` | Multi-select filter dropdown | `label`, `options: string[]`, `selected: Set<string>` (bindable) |
 | `SortDropdown` | Sort by column with direction | `options: SortOption[]`, `sortBy` (bindable), `sortDir` (bindable) |
 | `InlineEdit` | Click-to-edit text | `value` (bindable), `segments: DisplaySegment[]`, `onSave` |
@@ -252,6 +252,12 @@ import { snapResume, resumeLabel } from "jatui"                       // resume
 import { createQuietChain, amountFor } from "jatui"                   // loudness-compensated tone (WebAudio)
 import { qrMatrix, qrCanvas } from "jatui"                            // deep-link QR, ISO 18004 v1–10, no deps
 
+// Snapshot undo/redo history (wayflow-core, generic over any JSON-shaped state G).
+// Also importable as 'jatui/history'. Snapshots are JSON-deep-cloned (safe on $state proxies).
+// beginChange/endChange = push-on-first-move for drag gestures; untracked() = compound op, no pushes.
+import { createHistory, pushState, undo, redo, beginChange, endChange, untracked, clearHistory, MAX_UNDO_DEPTH } from "jatui"
+import type { History } from "jatui"
+
 // Date formatting
 import { formatRelativeTime, formatDate, formatShortDate, formatDateTime } from "jatui"
 

package/dist/components/SearchDropdown.svelte

@@ -36,6 +36,8 @@
 		triggerAttrs,
 		embedded = false,
 		onChange,
+		onSearch,
+		searchDebounceMs = 250,
 		onCreate,
 		createLabel = (q: string) => `Create "${q}"`,
 	}: {
@@ -65,6 +67,21 @@
 		/** Render inline without a trigger button — panel content is always visible, no dropdown behavior */
 		embedded?: boolean;
 		onChange: (value: string) => void;
+		/**
+		 * Server-side search hook (mos-ibafm). When set, the built-in search box
+		 * drives ASYNC results instead of the client-side substring filter: every
+		 * keystroke (debounced to `searchDebounceMs`) calls onSearch with the
+		 * current query, and the consumer updates `groups` with the server's
+		 * response. Also fires on panel open (typically with '') so the consumer
+		 * can load the initial result set, and again when the query is cleared —
+		 * so '' means "reset to the default list". Internal filtering is bypassed
+		 * entirely while this is set: the consumer owns exactly what the list
+		 * shows (a fuzzy server match must not be re-filtered by substring).
+		 * With it absent, behavior is unchanged (client-side filter).
+		 */
+		onSearch?: (query: string) => void;
+		/** Debounce applied to onSearch keystrokes before the callback fires. */
+		searchDebounceMs?: number;
 		/**
 		 * When set, an always-present "create" row is rendered as the last option
 		 * whenever the search box is non-empty — it survives a zero-match filter (so
@@ -108,6 +125,10 @@
 	const activeColor = $derived(colorFn ? colorFn(value) : undefined);
 
 	const filteredGroups = $derived.by(() => {
+		// Server-search mode: the consumer owns the result set (groups arrive
+		// from onSearch responses) — re-filtering them client-side would hide
+		// fuzzy server matches that don't substring-match the query.
+		if (onSearch) return groups;
 		if (!searchQuery.trim()) return groups;
 		const q = searchQuery.toLowerCase();
 		const result: SearchDropdownGroup[] = [];
@@ -166,6 +187,19 @@
 		});
 	}
 
+	// Debounced onSearch: one timer per open panel; each keystroke reruns the
+	// effect, which clears the pending timer and re-arms it — a burst of
+		// keystrokes collapses into a single callback firing `searchDebounceMs`
+		// after the last one. Firing on open too (query is '' after a reset) is
+		// what lets the consumer load the initial result set from the server.
+		$effect(() => {
+			if (!onSearch) return;
+			if (!open && !embedded) return;
+			const q = searchQuery;
+			const t = setTimeout(() => onSearch(q), searchDebounceMs);
+			return () => clearTimeout(t);
+		});
+
 	function handleSearchKeydown(e: KeyboardEvent) {
 		if (e.key === 'Escape') {
 			e.stopPropagation();

package/dist/components/SearchDropdown.svelte.d.ts

@@ -36,6 +36,21 @@ type $$ComponentProps = {
     /** Render inline without a trigger button — panel content is always visible, no dropdown behavior */
     embedded?: boolean;
     onChange: (value: string) => void;
+    /**
+     * Server-side search hook (mos-ibafm). When set, the built-in search box
+     * drives ASYNC results instead of the client-side substring filter: every
+     * keystroke (debounced to `searchDebounceMs`) calls onSearch with the
+     * current query, and the consumer updates `groups` with the server's
+     * response. Also fires on panel open (typically with '') so the consumer
+     * can load the initial result set, and again when the query is cleared —
+     * so '' means "reset to the default list". Internal filtering is bypassed
+     * entirely while this is set: the consumer owns exactly what the list
+     * shows (a fuzzy server match must not be re-filtered by substring).
+     * With it absent, behavior is unchanged (client-side filter).
+     */
+    onSearch?: (query: string) => void;
+    /** Debounce applied to onSearch keystrokes before the callback fires. */
+    searchDebounceMs?: number;
     /**
      * When set, an always-present "create" row is rendered as the last option
      * whenever the search box is non-empty — it survives a zero-match filter (so

package/dist/history.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Snapshot undo/redo history. Forked from @wayflow/core's history.ts (see
+ * README.md) and generalized to any graph type `G` — this module only
+ * deep-clones snapshots, it never inspects node/edge shape.
+ *
+ * Adds two things upstream keeps outside `core` (in its DOM editor package):
+ * push-on-first-move (`beginChange`/`endChange`) so a drag/resize gesture
+ * pushes exactly one pre-change snapshot no matter how many move events it
+ * fires, and `untracked()` to run a compound multi-step mutation (e.g.
+ * paste = add nodes + add edges) without each step pushing its own entry.
+ *
+ * CANONICAL HOME: this is the shared copy (jatui-00jfh, rebuilding the lost
+ * jat-gjw72 upstream half). The JAT IDE (ide/src/lib/utils/history.ts) and
+ * JST (src/lib/workflows/core/history.ts) carry vendored copies that
+ * repoint their imports at 'jatui' and are deleted at the swap.
+ */
+export declare const MAX_UNDO_DEPTH = 50;
+export interface History<G> {
+    undoStack: G[];
+    redoStack: G[];
+    /** True while a push-on-first-move gesture is in progress (see beginChange). */
+    changing: boolean;
+    /** Suppression depth for untracked(). Pushes no-op while > 0. */
+    suppressed: number;
+}
+export declare function createHistory<G>(): History<G>;
+/** Deep-clones `graph` onto the undo stack (capped at maxDepth) and clears redo. No-ops while suppressed. */
+export declare function pushState<G>(history: History<G>, graph: G, maxDepth?: number): void;
+/**
+ * Push-on-first-move: call on every move event of a drag/resize gesture.
+ * Pushes the pre-gesture snapshot only the first time it's called since the
+ * last endChange() — a click that never drags won't add a history entry.
+ */
+export declare function beginChange<G>(history: History<G>, graph: G, maxDepth?: number): void;
+/** Ends the current push-on-first-move gesture so the next beginChange() can push again. */
+export declare function endChange<G>(history: History<G>): void;
+/** Runs `fn` with history pushes suppressed — for compound ops that should land as zero or one entries (pair with a manual pushState before calling). */
+export declare function untracked<G>(history: History<G>, fn: () => void): void;
+/** Pops the most recent undo entry, pushing `currentGraph` onto redo. Returns null if nothing to undo. */
+export declare function undo<G>(history: History<G>, currentGraph: G): G | null;
+/** Pops the most recent redo entry, pushing `currentGraph` onto undo. Returns null if nothing to redo. */
+export declare function redo<G>(history: History<G>, currentGraph: G): G | null;
+/** Clears both stacks and any in-progress gesture/suppression state. */
+export declare function clearHistory<G>(history: History<G>): void;

package/dist/history.js

@@ -0,0 +1,87 @@
+/**
+ * Snapshot undo/redo history. Forked from @wayflow/core's history.ts (see
+ * README.md) and generalized to any graph type `G` — this module only
+ * deep-clones snapshots, it never inspects node/edge shape.
+ *
+ * Adds two things upstream keeps outside `core` (in its DOM editor package):
+ * push-on-first-move (`beginChange`/`endChange`) so a drag/resize gesture
+ * pushes exactly one pre-change snapshot no matter how many move events it
+ * fires, and `untracked()` to run a compound multi-step mutation (e.g.
+ * paste = add nodes + add edges) without each step pushing its own entry.
+ *
+ * CANONICAL HOME: this is the shared copy (jatui-00jfh, rebuilding the lost
+ * jat-gjw72 upstream half). The JAT IDE (ide/src/lib/utils/history.ts) and
+ * JST (src/lib/workflows/core/history.ts) carry vendored copies that
+ * repoint their imports at 'jatui' and are deleted at the swap.
+ */
+export const MAX_UNDO_DEPTH = 50;
+/**
+ * Deep-clones plain JSON-shaped state. Not `structuredClone` — callers pass
+ * Svelte 5 `$state` proxies (e.g. the canvas's reactive nodes/edges arrays),
+ * and `structuredClone` throws `DataCloneError` on those in real browsers
+ * (verified in-browser). A JSON round-trip reads through the proxy's
+ * property getters like any other consumer and is safe for graph data (no
+ * Date/Map/Set/functions).
+ */
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export function createHistory() {
+    return { undoStack: [], redoStack: [], changing: false, suppressed: 0 };
+}
+/** Deep-clones `graph` onto the undo stack (capped at maxDepth) and clears redo. No-ops while suppressed. */
+export function pushState(history, graph, maxDepth = MAX_UNDO_DEPTH) {
+    if (history.suppressed > 0)
+        return;
+    if (history.undoStack.length >= maxDepth) {
+        history.undoStack.shift();
+    }
+    history.undoStack.push(deepClone(graph));
+    history.redoStack = [];
+}
+/**
+ * Push-on-first-move: call on every move event of a drag/resize gesture.
+ * Pushes the pre-gesture snapshot only the first time it's called since the
+ * last endChange() — a click that never drags won't add a history entry.
+ */
+export function beginChange(history, graph, maxDepth = MAX_UNDO_DEPTH) {
+    if (history.changing)
+        return;
+    history.changing = true;
+    pushState(history, graph, maxDepth);
+}
+/** Ends the current push-on-first-move gesture so the next beginChange() can push again. */
+export function endChange(history) {
+    history.changing = false;
+}
+/** Runs `fn` with history pushes suppressed — for compound ops that should land as zero or one entries (pair with a manual pushState before calling). */
+export function untracked(history, fn) {
+    history.suppressed++;
+    try {
+        fn();
+    }
+    finally {
+        history.suppressed--;
+    }
+}
+/** Pops the most recent undo entry, pushing `currentGraph` onto redo. Returns null if nothing to undo. */
+export function undo(history, currentGraph) {
+    if (history.undoStack.length === 0)
+        return null;
+    history.redoStack.push(deepClone(currentGraph));
+    return history.undoStack.pop();
+}
+/** Pops the most recent redo entry, pushing `currentGraph` onto undo. Returns null if nothing to redo. */
+export function redo(history, currentGraph) {
+    if (history.redoStack.length === 0)
+        return null;
+    history.undoStack.push(deepClone(currentGraph));
+    return history.redoStack.pop();
+}
+/** Clears both stacks and any in-progress gesture/suppression state. */
+export function clearHistory(history) {
+    history.undoStack = [];
+    history.redoStack = [];
+    history.changing = false;
+    history.suppressed = 0;
+}

package/dist/index.d.ts

@@ -225,3 +225,5 @@ export { computeActiveSection, DEFAULT_ACTIVATION_RATIO } from './components/bas
 export type { SectionRect, SpyViewport, SpyScrollState } from './components/basic/sectionNavSpy';
 export { default as Slider } from './components/basic/Slider.svelte';
 export { default as Pagination } from './components/basic/Pagination.svelte';
+export { MAX_UNDO_DEPTH, createHistory, pushState, beginChange, endChange, untracked, undo, redo, clearHistory } from './history';
+export type { History } from './history';

package/dist/index.js

@@ -260,3 +260,5 @@ export { default as SectionNav } from './components/basic/SectionNav.svelte';
 export { computeActiveSection, DEFAULT_ACTIVATION_RATIO } from './components/basic/sectionNavSpy';
 export { default as Slider } from './components/basic/Slider.svelte';
 export { default as Pagination } from './components/basic/Pagination.svelte';
+// Snapshot undo/redo history (wayflow-core) — also importable as 'jatui/history' (jatui-00jfh).
+export { MAX_UNDO_DEPTH, createHistory, pushState, beginChange, endChange, untracked, undo, redo, clearHistory } from './history';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -17,6 +17,10 @@
       "svelte": "./dist/dnd/index.js",
       "default": "./dist/dnd/index.js"
     },
+    "./history": {
+      "types": "./dist/history.d.ts",
+      "default": "./dist/history.js"
+    },
     "./styles/rail.css": "./dist/styles/rail.css",
     "./showcase": {
       "types": "./dist/showcase/index.d.ts",