@marianmeres/stuic 2.17.0 → 2.19.0

package/dist/components/AnimatedElipsis/AnimatedEllipsis.svelte

@@ -2,53 +2,87 @@
 	export interface Props {
 		class?: string;
 		enabled?: boolean;
+		/** Animation cycle duration in ms (default: 1000) */
+		speed?: number;
 	}
 </script>
 
 <script lang="ts">
-	import { createTickerRAF } from "@marianmeres/ticker";
-	import { onMount } from "svelte";
-
-	let { class: _class, enabled = true }: Props = $props();
-
-	const speed = 250;
-	let visible = $state([false, false, false]);
-	let i = $state(0);
-
-	onMount(() => {
-		const ticker = createTickerRAF(speed, true);
-		const unsub = ticker.subscribe((t) => {
-			if (i > visible.length - 1) {
-				i = 0;
-				visible = visible.map((v) => false);
-			} else {
-				visible[i] = true;
-				i++;
-			}
-		});
-		return () => {
-			ticker.stop();
-			unsub();
-		};
-	});
+	let { class: _class, enabled = true, speed = 1000 }: Props = $props();
 </script>
 
 <!-- prettier-ignore -->
-<span class={_class}>
-	<span 
-		class={visible[0] || !enabled ? 'opacity-100' : 'opacity-0'} 
-		style="transition-duration: {speed}ms;"
-	>.</span><span 
-		class={visible[1] || !enabled ? 'opacity-100' : 'opacity-0'}
-		style="transition-duration: {speed}ms;"
-	>.</span><span 
-		class={visible[2] || !enabled ? 'opacity-100' : 'opacity-0'}
-		style="transition-duration: {speed}ms;"
-	>.</span>
-</span>
+<span class={_class} style:--duration="{speed}ms"
+	><span class="dot dot1" class:paused={!enabled}>.</span
+	><span class="dot dot2" class:paused={!enabled}>.</span
+	><span class="dot dot3" class:paused={!enabled}>.</span
+></span>
 
 <style>
-	span span {
-		transition-property: opacity;
+	.dot {
+		opacity: 0;
+	}
+
+	.dot1 {
+		animation: dot1 var(--duration, 1s) infinite linear;
+	}
+	.dot2 {
+		animation: dot2 var(--duration, 1s) infinite linear;
+	}
+	.dot3 {
+		animation: dot3 var(--duration, 1s) infinite linear;
+	}
+
+	.dot.paused {
+		animation: none;
+		opacity: 1;
+	}
+
+	@keyframes dot1 {
+		0%,
+		20% {
+			opacity: 0;
+		}
+		25% {
+			opacity: 1;
+		}
+		80% {
+			opacity: 1;
+		}
+		100% {
+			opacity: 0;
+		}
+	}
+
+	@keyframes dot2 {
+		0%,
+		45% {
+			opacity: 0;
+		}
+		50% {
+			opacity: 1;
+		}
+		80% {
+			opacity: 1;
+		}
+		100% {
+			opacity: 0;
+		}
+	}
+
+	@keyframes dot3 {
+		0%,
+		70% {
+			opacity: 0;
+		}
+		75% {
+			opacity: 1;
+		}
+		80% {
+			opacity: 1;
+		}
+		100% {
+			opacity: 0;
+		}
 	}
 </style>

package/dist/components/AnimatedElipsis/AnimatedEllipsis.svelte.d.ts

@@ -1,6 +1,8 @@
 export interface Props {
     class?: string;
     enabled?: boolean;
+    /** Animation cycle duration in ms (default: 1000) */
+    speed?: number;
 }
 declare const AnimatedEllipsis: import("svelte").Component<Props, {}, "">;
 type AnimatedEllipsis = ReturnType<typeof AnimatedEllipsis>;

package/dist/components/AvatarInitials/README.md

@@ -0,0 +1,169 @@
+# AvatarInitials
+
+A circular avatar component displaying initials extracted from names or emails, with optional auto-generated colors and size presets.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `input` | `string` | - | String to extract initials from (name, initials, or email) |
+| `hashSource` | `string` | - | Optional string for color hash calculation (falls back to `input`) |
+| `size` | `"sm" \| "md" \| "lg" \| "xl" \| string` | `"md"` | Size preset or custom Tailwind class |
+| `onclick` | `(event: MouseEvent) => void` | - | Click handler (renders as button when provided) |
+| `bg` | `string` | - | Background color Tailwind class (ignored if autoColor) |
+| `textColor` | `string` | - | Text color Tailwind class (ignored if autoColor) |
+| `autoColor` | `boolean` | `false` | Generate deterministic pastel colors from input |
+| `class` | `string` | - | Additional CSS classes |
+| `el` | `HTMLDivElement \| HTMLButtonElement` | - | Element reference (bindable) |
+
+## Size Presets
+
+| Size | Dimensions | Font Size |
+|------|------------|-----------|
+| `sm` | 32px (size-8) | text-xs |
+| `md` | 40px (size-10) | text-sm |
+| `lg` | 56px (size-14) | text-base |
+| `xl` | 64px (size-16) | text-lg |
+
+Custom sizes can be passed as Tailwind classes: `size="size-20 text-2xl"`
+
+## Initials Extraction Logic
+
+The component intelligently extracts up to 2 characters from the input:
+
+1. **Email addresses** (`john.doe@example.com`):
+   - Splits username by `.`, `_`, `+`, `-`
+   - Takes first letter of each part
+   - Result: `JD`
+
+2. **Full names** (`John Doe`):
+   - Splits by whitespace
+   - Takes first letter of each word
+   - Result: `JD`
+
+3. **Short strings** (`AB` or `Jo`):
+   - Takes first 2 characters
+   - Result: `AB` or `JO`
+
+4. **Empty input**:
+   - Returns `?`
+
+All initials are uppercase.
+
+## Auto Color Generation
+
+When `autoColor` is enabled, the component generates deterministic pastel colors:
+
+- Colors are derived from a hash of `hashSource` or `input`
+- Same input always produces the same color
+- Colors are designed as accessible pastel tones
+- Text color automatically contrasts with background
+
+## Usage
+
+### Basic Display
+
+```svelte
+<script lang="ts">
+  import { AvatarInitials } from 'stuic';
+</script>
+
+<AvatarInitials input="John Doe" />
+<AvatarInitials input="jane.smith@example.com" />
+<AvatarInitials input="AB" />
+```
+
+### Size Variants
+
+```svelte
+<AvatarInitials input="JD" size="sm" />
+<AvatarInitials input="JD" size="md" />
+<AvatarInitials input="JD" size="lg" />
+<AvatarInitials input="JD" size="xl" />
+
+<!-- Custom size -->
+<AvatarInitials input="JD" size="size-24 text-3xl" />
+```
+
+### Auto Color (Deterministic)
+
+```svelte
+<!-- Same email always produces same color -->
+<AvatarInitials input="john@example.com" autoColor />
+<AvatarInitials input="jane@example.com" autoColor />
+
+<!-- Use ID for consistent color regardless of display name -->
+<AvatarInitials input="John Doe" hashSource="user-123" autoColor />
+```
+
+### Custom Colors
+
+```svelte
+<AvatarInitials
+  input="JD"
+  bg="bg-blue-500"
+  textColor="text-white"
+/>
+
+<AvatarInitials
+  input="AB"
+  bg="bg-gradient-to-br from-purple-500 to-pink-500"
+  textColor="text-white"
+/>
+```
+
+### Clickable Avatar
+
+```svelte
+<script lang="ts">
+  function handleClick() {
+    console.log('Avatar clicked');
+  }
+</script>
+
+<AvatarInitials
+  input="john@example.com"
+  autoColor
+  onclick={handleClick}
+/>
+```
+
+### In Header Dropdown
+
+```svelte
+<script lang="ts">
+  import { AvatarInitials, DropdownMenu } from 'stuic';
+</script>
+
+<DropdownMenu
+  items={[
+    { type: "action", id: "profile", label: "View Profile" },
+    { type: "action", id: "logout", label: "Logout" },
+  ]}
+>
+  {#snippet trigger({ toggle })}
+    <AvatarInitials
+      input={userEmail}
+      onclick={toggle}
+      autoColor
+      class="cursor-pointer hover:ring-2 hover:ring-blue-500"
+    />
+  {/snippet}
+</DropdownMenu>
+```
+
+### Avatar List
+
+```svelte
+<div class="flex -space-x-2">
+  {#each users as user}
+    <AvatarInitials
+      input={user.email}
+      hashSource={user.id}
+      autoColor
+      size="sm"
+      class="ring-2 ring-white"
+    />
+  {/each}
+</div>
+```

package/dist/components/Backdrop/Backdrop.svelte

@@ -14,6 +14,9 @@
 		visible?: boolean;
 		noScrollLock?: boolean;
 	}
+
+	// Stack to track visible Backdrops - only topmost handles Escape
+	const escapeStack: Set<symbol> = new Set();
 </script>
 
 <script lang="ts">
@@ -104,17 +107,34 @@
 	// Note, that this will also reset if nested... (which is not desired, but ignoring)
 	onDestroy(BodyScroll.unlock);
 
+	// Unique ID for this Backdrop instance
+	const instanceId = Symbol();
+
 	$effect(() => {
+		if (!visible || typeof onEscape !== "function") return;
+
+		// Add to stack when visible
+		escapeStack.add(instanceId);
+
 		function onkeydown(e: KeyboardEvent) {
-			if (e.key === "Escape" && typeof onEscape === "function") {
-				e.stopPropagation();
-				e.stopImmediatePropagation();
+			// Skip if already handled by another component (ModalDialog, DropdownMenu, etc.)
+			if (e.defaultPrevented) return;
+
+			// Only handle if this is the topmost Backdrop
+			const stack = [...escapeStack];
+			if (stack[stack.length - 1] !== instanceId) return;
+
+			if (e.key === "Escape") {
 				e.preventDefault();
-				onEscape();
+				onEscape?.();
 			}
 		}
-		el?.addEventListener("keydown", onkeydown);
-		return () => el?.removeEventListener("keydown", onkeydown);
+
+		window.addEventListener("keydown", onkeydown);
+		return () => {
+			escapeStack.delete(instanceId);
+			window.removeEventListener("keydown", onkeydown);
+		};
 	});
 </script>
 

package/dist/components/DropdownMenu/README.md

@@ -0,0 +1,315 @@
+# DropdownMenu
+
+A feature-rich dropdown menu component with CSS Anchor Positioning (with fallback), full keyboard navigation, and support for multiple item types including expandable sections.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `DropdownMenuItem[]` | - | Menu items to display |
+| `isOpen` | `boolean` | `false` | Controlled open state (bindable) |
+| `position` | `DropdownMenuPosition` | `"bottom-span-left"` | Popover position relative to trigger |
+| `offset` | `string` | `"0.25rem"` | Offset from trigger element (CSS value) |
+| `maxHeight` | `string` | `"300px"` | Max height of dropdown |
+| `closeOnSelect` | `boolean` | `true` | Close menu when action item is selected |
+| `closeOnClickOutside` | `boolean` | `true` | Close on click outside |
+| `closeOnEscape` | `boolean` | `true` | Close on Escape key |
+| `forceFallback` | `boolean` | `false` | Force fallback positioning (for testing) |
+| `class` | `string` | - | Classes for wrapper element |
+| `classTrigger` | `string` | - | Classes for trigger button |
+| `classDropdown` | `string` | - | Classes for dropdown container |
+| `classItem` | `string` | - | Classes for action items |
+| `classItemActive` | `string` | - | Classes for active/focused item |
+| `classItemDisabled` | `string` | - | Classes for disabled items |
+| `classDivider` | `string` | - | Classes for dividers |
+| `classHeader` | `string` | - | Classes for header items |
+| `classExpandable` | `string` | - | Classes for expandable section header |
+| `classExpandableContent` | `string` | - | Classes for expandable section content |
+| `triggerEl` | `HTMLButtonElement` | - | Trigger element reference (bindable) |
+| `dropdownEl` | `HTMLDivElement` | - | Dropdown element reference (bindable) |
+
+## Snippets
+
+| Snippet | Parameters | Description |
+|---------|------------|-------------|
+| `trigger` | `{ isOpen, toggle, triggerProps }` | Custom trigger with full ARIA control |
+| `children` | - | Simple content for default trigger button |
+
+## Item Types
+
+### Action Item
+
+Clickable menu item with optional icon and shortcut.
+
+```typescript
+interface DropdownMenuActionItem {
+  type: "action";
+  id: string | number;
+  label: THC;           // Text, HTML, or component
+  icon?: THC;           // Optional leading icon
+  shortcut?: string;    // Keyboard shortcut hint
+  disabled?: boolean;
+  onSelect?: () => void | boolean;
+  class?: string;
+  data?: Record<string, any>;
+}
+```
+
+### Divider Item
+
+Visual separator between items.
+
+```typescript
+interface DropdownMenuDividerItem {
+  type: "divider";
+  id?: string | number;
+  class?: string;
+}
+```
+
+### Header Item
+
+Non-interactive section header.
+
+```typescript
+interface DropdownMenuHeaderItem {
+  type: "header";
+  id?: string | number;
+  label: THC;
+  class?: string;
+}
+```
+
+### Custom Item
+
+Render arbitrary content (non-interactive).
+
+```typescript
+interface DropdownMenuCustomItem {
+  type: "custom";
+  id?: string | number;
+  content: THC;
+  class?: string;
+}
+```
+
+### Expandable Item
+
+Collapsible section containing nested items.
+
+```typescript
+interface DropdownMenuExpandableItem {
+  type: "expandable";
+  id: string | number;
+  label: THC;
+  icon?: THC;
+  items: DropdownMenuFlatItem[];  // Nested items (no nested expandables)
+  defaultExpanded?: boolean;
+  disabled?: boolean;
+  class?: string;
+}
+```
+
+## Position Options
+
+| Position | Description |
+|----------|-------------|
+| `top`, `bottom` | Centered above/below trigger |
+| `top-left`, `top-right` | Above, aligned to left/right edge |
+| `bottom-left`, `bottom-right` | Below, aligned to left/right edge |
+| `top-span-left`, `top-span-right` | Above, spanning from left/right |
+| `bottom-span-left`, `bottom-span-right` | Below, spanning from left/right |
+| `left`, `right` | Side-by-side with trigger |
+
+## Callbacks
+
+| Callback | Parameters | Description |
+|----------|------------|-------------|
+| `onOpen` | - | Called when menu opens |
+| `onClose` | - | Called when menu closes |
+| `onSelect` | `(item: DropdownMenuActionItem)` | Called when action item selected (fallback) |
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Arrow Down` | Move to next item |
+| `Arrow Up` | Move to previous item |
+| `Home` | Move to first item |
+| `End` | Move to last item |
+| `Cmd/Ctrl + Arrow` | Jump to first/last |
+| `Enter` / `Space` | Select item or toggle expandable |
+| `Arrow Right` | Expand section (on expandable) |
+| `Arrow Left` | Collapse section (on expandable) |
+| `Escape` | Close menu |
+| `Tab` | Close menu |
+
+## Usage
+
+### Basic Menu
+
+```svelte
+<script lang="ts">
+  import { DropdownMenu } from 'stuic';
+
+  const items = [
+    { type: "action", id: "edit", label: "Edit" },
+    { type: "action", id: "duplicate", label: "Duplicate" },
+    { type: "divider" },
+    { type: "action", id: "delete", label: "Delete", class: "text-red-500" },
+  ];
+</script>
+
+<DropdownMenu
+  {items}
+  onSelect={(item) => console.log('Selected:', item.id)}
+>
+  Actions
+</DropdownMenu>
+```
+
+### With Icons and Shortcuts
+
+```svelte
+<script lang="ts">
+  import { DropdownMenu } from 'stuic';
+  import { iconLucideEdit } from '@marianmeres/icons-fns/lucide/iconLucideEdit.js';
+  import { iconLucideTrash } from '@marianmeres/icons-fns/lucide/iconLucideTrash.js';
+
+  const items = [
+    {
+      type: "action",
+      id: "edit",
+      label: "Edit",
+      icon: iconLucideEdit({ size: 16 }),
+      shortcut: "Cmd+E",
+      onSelect: () => handleEdit(),
+    },
+    { type: "divider" },
+    {
+      type: "action",
+      id: "delete",
+      label: "Delete",
+      icon: iconLucideTrash({ size: 16 }),
+      shortcut: "Cmd+D",
+      onSelect: () => handleDelete(),
+    },
+  ];
+</script>
+
+<DropdownMenu {items} position="bottom-right">
+  More Options
+</DropdownMenu>
+```
+
+### With Section Headers
+
+```svelte
+<DropdownMenu items={[
+  { type: "header", label: "Navigation" },
+  { type: "action", id: "dashboard", label: "Dashboard" },
+  { type: "action", id: "settings", label: "Settings" },
+  { type: "divider" },
+  { type: "header", label: "Account" },
+  { type: "action", id: "profile", label: "Profile" },
+  { type: "action", id: "logout", label: "Logout" },
+]} />
+```
+
+### Expandable Sections
+
+```svelte
+<DropdownMenu items={[
+  { type: "action", id: "new", label: "New File" },
+  {
+    type: "expandable",
+    id: "recent",
+    label: "Recent Files",
+    defaultExpanded: true,
+    items: [
+      { type: "action", id: "file1", label: "document.pdf" },
+      { type: "action", id: "file2", label: "report.xlsx" },
+      { type: "action", id: "file3", label: "notes.txt" },
+    ],
+  },
+  { type: "divider" },
+  { type: "action", id: "settings", label: "Settings" },
+]} />
+```
+
+### Custom Trigger
+
+```svelte
+<script lang="ts">
+  import { AvatarInitials, DropdownMenu } from 'stuic';
+</script>
+
+<DropdownMenu
+  items={[
+    { type: "action", id: "profile", label: "View Profile" },
+    { type: "action", id: "logout", label: "Logout" },
+  ]}
+>
+  {#snippet trigger({ isOpen, toggle, triggerProps })}
+    <button {...triggerProps} onclick={toggle}>
+      <AvatarInitials input="john.doe@example.com" autoColor />
+    </button>
+  {/snippet}
+</DropdownMenu>
+```
+
+### With Custom Content
+
+```svelte
+<script lang="ts">
+  import { DropdownMenu } from 'stuic';
+</script>
+
+<DropdownMenu items={[
+  {
+    type: "custom",
+    content: customHeader,
+  },
+  { type: "divider" },
+  { type: "action", id: "settings", label: "Settings" },
+  { type: "action", id: "logout", label: "Logout" },
+]} />
+
+{#snippet customHeader()}
+  <div class="px-3 py-2 text-center">
+    <img src="/avatar.jpg" class="w-12 h-12 rounded-full mx-auto" alt="User" />
+    <div class="mt-2 font-semibold">John Doe</div>
+    <div class="text-sm text-gray-500">john@example.com</div>
+  </div>
+{/snippet}
+```
+
+### Controlled State
+
+```svelte
+<script lang="ts">
+  import { DropdownMenu } from 'stuic';
+
+  let isOpen = $state(false);
+</script>
+
+<button onclick={() => isOpen = true}>Open Menu</button>
+
+<DropdownMenu
+  bind:isOpen
+  items={[
+    { type: "action", id: "option1", label: "Option 1" },
+    { type: "action", id: "option2", label: "Option 2" },
+  ]}
+/>
+```
+
+## Features
+
+- **CSS Anchor Positioning**: Uses modern CSS anchor positioning with automatic fallback for unsupported browsers
+- **Full Keyboard Navigation**: Complete arrow key navigation with Home/End support
+- **Expandable Sections**: Collapsible groups with independent toggle state
+- **ARIA Compliant**: Proper menu roles and keyboard interaction
+- **Reduced Motion**: Respects user's reduced motion preference
+- **Click Outside**: Automatically closes when clicking outside
+- **Focus Management**: Returns focus to trigger on close

package/dist/utils/index.d.ts

@@ -11,6 +11,7 @@ export * from "./file-from-bloburl.js";
 export * from "./force-download.js";
 export * from "./get-file-type-label.js";
 export * from "./get-id.js";
+export * from "./input-history.svelte.js";
 export * from "./is-browser.js";
 export * from "./is-image.js";
 export * from "./is-mac.js";

package/dist/utils/index.js

@@ -11,6 +11,7 @@ export * from "./file-from-bloburl.js";
 export * from "./force-download.js";
 export * from "./get-file-type-label.js";
 export * from "./get-id.js";
+export * from "./input-history.svelte.js";
 export * from "./is-browser.js";
 export * from "./is-image.js";
 export * from "./is-mac.js";

package/dist/utils/input-history.svelte.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Configuration options for InputHistory
+ */
+export interface InputHistoryOptions {
+    /** Composite key parts for namespacing (e.g., [projectId, domain, entity, type]) */
+    keyParts: string[];
+    /** Maximum number of entries to store (default: 10) */
+    maxEntries?: number;
+    /** App ID prefix for the storage key (default: "app") */
+    appId?: string;
+    /** Feature name for the key (default: "input-history") */
+    featureName?: string;
+}
+/**
+ * A reactive input history manager with localStorage persistence and arrow key navigation.
+ *
+ * @example
+ * ```ts
+ * const history = new InputHistory({
+ *   keyParts: [projectId, domain, entity, type],
+ *   appId: "joy",
+ *   featureName: "filter-history"
+ * });
+ *
+ * // Add entry on submit
+ * history.add(query);
+ *
+ * // Navigate with arrow keys
+ * history.navigateUp();    // Go to older entry
+ * history.navigateDown();  // Go to newer entry
+ *
+ * // Get current entry for display
+ * const current = history.getCurrent();
+ *
+ * // Reset navigation when user starts typing
+ * history.reset();
+ * ```
+ */
+export declare class InputHistory {
+    #private;
+    /** Storage key for this history instance */
+    readonly key: string;
+    /** Maximum entries to store */
+    readonly maxEntries: number;
+    constructor(options: InputHistoryOptions);
+    /** Get the stored history entries (newest first) */
+    get entries(): string[];
+    /** Get current navigation index (-1 when not navigating) */
+    get navigationIndex(): number;
+    /** Check if currently navigating through history */
+    get isNavigating(): boolean;
+    /**
+     * Add a new query to history (called on Enter/submit).
+     * Deduplicates and limits to maxEntries.
+     */
+    add(query: string): void;
+    /**
+     * Navigate up (to older entries).
+     * On first call, saves current input value.
+     * @param currentValue - The current input value (saved on first navigation)
+     */
+    navigateUp(currentValue?: string): string | null;
+    /**
+     * Navigate down (to newer entries).
+     * When reaching past newest, returns to temp value.
+     */
+    navigateDown(): string | null;
+    /**
+     * Get the current history entry based on navigation index.
+     * Returns null if not navigating.
+     */
+    getCurrent(): string | null;
+    /**
+     * Reset navigation state (call when user starts typing).
+     */
+    reset(): void;
+    /**
+     * Clear all history for this key.
+     */
+    clear(): void;
+    /**
+     * Clear all histories matching a pattern prefix.
+     * Call this on logout to clean up user data.
+     *
+     * @param pattern - Key prefix to match (e.g., "joy:input-history")
+     *
+     * @example
+     * ```ts
+     * // On logout, clear all input histories
+     * InputHistory.clearAllMatching("joy:input-history");
+     * ```
+     */
+    static clearAllMatching(pattern: string): void;
+    /**
+     * Clear all registered histories (nuclear option).
+     */
+    static clearAll(): void;
+    /**
+     * Get all registered history keys (for debugging).
+     */
+    static getRegisteredKeys(): string[];
+}

package/dist/utils/input-history.svelte.js

@@ -0,0 +1,197 @@
+import { localStorageState } from "./persistent-state.svelte.js";
+/**
+ * A reactive input history manager with localStorage persistence and arrow key navigation.
+ *
+ * @example
+ * ```ts
+ * const history = new InputHistory({
+ *   keyParts: [projectId, domain, entity, type],
+ *   appId: "joy",
+ *   featureName: "filter-history"
+ * });
+ *
+ * // Add entry on submit
+ * history.add(query);
+ *
+ * // Navigate with arrow keys
+ * history.navigateUp();    // Go to older entry
+ * history.navigateDown();  // Go to newer entry
+ *
+ * // Get current entry for display
+ * const current = history.getCurrent();
+ *
+ * // Reset navigation when user starts typing
+ * history.reset();
+ * ```
+ */
+export class InputHistory {
+    /** Storage key for this history instance */
+    key;
+    /** Maximum entries to store */
+    maxEntries;
+    /** Persistent state for stored history entries */
+    #storage;
+    /** Current navigation index (-1 means "not navigating", 0 is newest, length-1 is oldest) */
+    #navigationIndex = $state(-1);
+    /** Temporary value holder for current input before navigation started */
+    #tempValue = $state("");
+    constructor(options) {
+        const { keyParts, maxEntries = 10, appId = "app", featureName = "input-history", } = options;
+        this.maxEntries = maxEntries;
+        // Build composite key: "joy:input-history:projectId:domain:entity:type"
+        this.key = [appId, featureName, ...keyParts].filter(Boolean).join(":");
+        // Initialize persistent storage
+        this.#storage = localStorageState(this.key, []);
+        // Register this instance for cleanup
+        InputHistory.#register(this.key);
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Public API
+    // ─────────────────────────────────────────────────────────────
+    /** Get the stored history entries (newest first) */
+    get entries() {
+        return this.#storage.current;
+    }
+    /** Get current navigation index (-1 when not navigating) */
+    get navigationIndex() {
+        return this.#navigationIndex;
+    }
+    /** Check if currently navigating through history */
+    get isNavigating() {
+        return this.#navigationIndex >= 0;
+    }
+    /**
+     * Add a new query to history (called on Enter/submit).
+     * Deduplicates and limits to maxEntries.
+     */
+    add(query) {
+        query = query.trim();
+        if (!query)
+            return;
+        const current = [...this.#storage.current];
+        // Remove duplicates (case-sensitive)
+        const filtered = current.filter((item) => item !== query);
+        // Add to beginning (newest first)
+        filtered.unshift(query);
+        // Limit to maxEntries
+        this.#storage.current = filtered.slice(0, this.maxEntries);
+        // Reset navigation after adding
+        this.reset();
+    }
+    /**
+     * Navigate up (to older entries).
+     * On first call, saves current input value.
+     * @param currentValue - The current input value (saved on first navigation)
+     */
+    navigateUp(currentValue) {
+        const entries = this.entries;
+        if (entries.length === 0)
+            return null;
+        // If not navigating yet, save current value and start
+        if (this.#navigationIndex < 0) {
+            this.#tempValue = currentValue ?? "";
+            this.#navigationIndex = 0;
+        }
+        else if (this.#navigationIndex < entries.length - 1) {
+            // Move to older entry
+            this.#navigationIndex++;
+        }
+        // At oldest entry, stay there
+        return this.getCurrent();
+    }
+    /**
+     * Navigate down (to newer entries).
+     * When reaching past newest, returns to temp value.
+     */
+    navigateDown() {
+        if (this.#navigationIndex < 0)
+            return null;
+        if (this.#navigationIndex > 0) {
+            // Move to newer entry
+            this.#navigationIndex--;
+            return this.getCurrent();
+        }
+        else {
+            // At newest entry, go back to temp value
+            const temp = this.#tempValue;
+            this.reset();
+            return temp;
+        }
+    }
+    /**
+     * Get the current history entry based on navigation index.
+     * Returns null if not navigating.
+     */
+    getCurrent() {
+        if (this.#navigationIndex < 0)
+            return null;
+        return this.entries[this.#navigationIndex] ?? null;
+    }
+    /**
+     * Reset navigation state (call when user starts typing).
+     */
+    reset() {
+        this.#navigationIndex = -1;
+        this.#tempValue = "";
+    }
+    /**
+     * Clear all history for this key.
+     */
+    clear() {
+        this.#storage.current = [];
+        this.reset();
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Static cleanup registration
+    // ─────────────────────────────────────────────────────────────
+    /** Registry of all history keys (for cleanup on logout) */
+    static #registeredKeys = new Set();
+    /** Register a key for potential cleanup */
+    static #register(key) {
+        InputHistory.#registeredKeys.add(key);
+    }
+    /**
+     * Clear all histories matching a pattern prefix.
+     * Call this on logout to clean up user data.
+     *
+     * @param pattern - Key prefix to match (e.g., "joy:input-history")
+     *
+     * @example
+     * ```ts
+     * // On logout, clear all input histories
+     * InputHistory.clearAllMatching("joy:input-history");
+     * ```
+     */
+    static clearAllMatching(pattern) {
+        // Clear from our registry
+        for (const key of InputHistory.#registeredKeys) {
+            if (key.startsWith(pattern)) {
+                localStorage.removeItem(key);
+                InputHistory.#registeredKeys.delete(key);
+            }
+        }
+        // Also scan localStorage for any keys we might have missed
+        // (e.g., from previous sessions)
+        for (let i = localStorage.length - 1; i >= 0; i--) {
+            const key = localStorage.key(i);
+            if (key?.startsWith(pattern)) {
+                localStorage.removeItem(key);
+            }
+        }
+    }
+    /**
+     * Clear all registered histories (nuclear option).
+     */
+    static clearAll() {
+        for (const key of InputHistory.#registeredKeys) {
+            localStorage.removeItem(key);
+        }
+        InputHistory.#registeredKeys.clear();
+    }
+    /**
+     * Get all registered history keys (for debugging).
+     */
+    static getRegisteredKeys() {
+        return [...InputHistory.#registeredKeys];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",