@spaethtech/svelte-ui 0.1.10

package/dist/components/ElementManager/ElementManager.svelte

@@ -0,0 +1,397 @@
+<!--
+/**
+ * ElementManager - Utility component for automatic element discovery and management
+ * 
+ * Separates element discovery from component logic for better architecture.
+ * Used as a foundation for building manager components like TooltipHandler, ModalManager, etc.
+ * 
+ * @example Single Selector (backwards compatible)
+ * ```svelte
+ * <script>
+ *   let tooltipElements = $state(new Map());
+ * </script>
+ * 
+ * <ElementManager 
+ *   selector="[data-tooltip], [data-tooltip-text]" 
+ *   bind:elements={tooltipElements} 
+ * />
+ * 
+ * <TooltipHandler elements={tooltipElements} />
+ * <slot />
+ * ```
+ * 
+ * @example Multiple Selector Groups (new)
+ * ```svelte
+ * <script>
+ *   let elementGroups = $state({});
+ * </script>
+ * 
+ * <ElementManager 
+ *   selectors={{
+ *     viewportTooltips: "[data-tooltip]:not([data-contained])",
+ *     containerTooltips: "[data-tooltip][data-contained]",
+ *     modals: "[data-modal]"
+ *   }}
+ *   bind:elements={elementGroups}
+ * >
+ *   <TooltipHandler bind:elements={elementGroups.viewportTooltips} />
+ *   <TooltipHandler bind:elements={elementGroups.containerTooltips} container=".modal" />
+ *   <ModalManager bind:elements={elementGroups.modals} />
+ *   <slot />
+ * </ElementManager>
+ * ```
+ * 
+ * @example With Event Callbacks
+ * ```svelte
+ * <ElementManager 
+ *   selectors={{ modals: "[data-modal]" }}
+ *   bind:elements={elementGroups}
+ *   onElementAdded={(element, data, group) => {
+ *     console.log(`New ${group} trigger:`, element);
+ *   }}
+ *   onElementRemoved={(element, data, group) => {
+ *     // Cleanup any modal state
+ *     data.cleanup?.();
+ *   }}
+ * />
+ * ```
+ * 
+ * @example Custom Observer Options
+ * ```svelte
+ * <ElementManager 
+ *   selectors={{ editable: "[contenteditable]" }}
+ *   observerOptions={{
+ *     childList: true,
+ *     characterData: true,
+ *     subtree: true
+ *   }}
+ *   bind:elements={elementGroups}
+ * />
+ * ```
+ */
+-->
+<script lang="ts">
+  import { onMount, untrack } from 'svelte';
+  import type { Snippet } from 'svelte';
+  
+  /**
+   * Data structure for each discovered element
+   */
+  interface ElementData {
+    /** The HTML element that was discovered */
+    element: HTMLElement;
+    /** Optional cleanup function called when element is removed */
+    cleanup?: () => void;
+    /** Allow extension by consumer components with additional properties */
+    [key: string]: any;
+  }
+
+  /**
+   * ElementManager component props
+   * 
+   * @example Basic usage
+   * ```svelte
+   * <ElementManager 
+   *   selectors={{
+   *     tooltips: "[data-tooltip]",
+   *     modals: "[data-modal]"
+   *   }}
+   *   bind:elements={elementGroups}
+   * />
+   * ```
+   */
+  interface Props {
+    /** Multiple CSS selectors organized by group name */
+    selectors: Record<string, string>;
+    /** Bindable Record of Maps for discovered elements */
+    elements?: Record<string, Map<HTMLElement, ElementData>>;
+    /** Optional child content to wrap (uses class="contents" for transparent rendering) */
+    children?: Snippet;
+    /** Callback fired when a new element is discovered */
+    onElementAdded?: (element: HTMLElement, data: ElementData, group: string) => void;
+    /** Callback fired when an element is removed or no longer matches selector */
+    onElementRemoved?: (element: HTMLElement, data: ElementData, group: string) => void;
+    /** Custom MutationObserver configuration (defaults to childList, subtree, attributes) */
+    observerOptions?: MutationObserverInit;
+  }
+  
+  let { 
+    selectors, 
+    elements = $bindable(), 
+    children, 
+    onElementAdded, 
+    onElementRemoved, 
+    observerOptions 
+  }: Props = $props();
+  
+  // ===== DEVELOPMENT WARNINGS =====
+  
+  if (import.meta.env.DEV) {
+    // Validate prop usage
+    if (!selectors || Object.keys(selectors).length === 0) {
+      console.warn('ElementManager: No selectors provided or selectors object is empty. No elements will be discovered.');
+    }
+  }
+  
+  // ===== COMPONENT STATE =====
+  let containerElement: HTMLElement;
+  let observer: MutationObserver | null = null;
+  let debounceTimeout: ReturnType<typeof setTimeout> | null = null;
+  let initialized = false;
+  
+  // Initialize selectors as empty object if not provided (for development warnings)
+  let currentSelectors = $derived(() => selectors || {});
+  
+  // Initialize elements (runs before other effects)
+  $effect.pre(() => {
+    if (!elements && !initialized) {
+      initialized = true;
+      untrack(() => {
+        // Initialize with empty Maps for each group
+        const groups: Record<string, Map<HTMLElement, ElementData>> = {};
+        for (const group in currentSelectors()) {
+          groups[group] = new Map();
+        }
+        elements = groups;
+      });
+    }
+  });
+  
+  // ===== ELEMENT DISCOVERY =====
+  
+  /**
+   * Discovers elements matching the current selectors and updates the elements Map(s).
+   * Performs incremental updates to avoid full re-discovery on every change.
+   */
+  function discoverElements() {
+    if (!containerElement || !containerElement.isConnected) return;
+    
+    const selectorGroups = currentSelectors();
+    
+    // Track all found elements by group
+    const foundByGroup: Record<string, Set<HTMLElement>> = {};
+    
+    // Discover elements for each selector group
+    for (const [group, selectorString] of Object.entries(selectorGroups)) {
+      foundByGroup[group] = new Set();
+      
+      try {
+        const foundElements = containerElement.querySelectorAll(selectorString);
+        
+        // Warn in development if no elements found
+        if (import.meta.env.DEV && foundElements.length === 0) {
+          console.warn(`ElementManager: No elements matched selector "${selectorString}" for group "${group}"`);
+        }
+        
+        foundElements.forEach((el) => {
+          if (el instanceof HTMLElement) {
+            foundByGroup[group].add(el);
+          }
+        });
+      } catch (error) {
+        console.warn(`ElementManager: Invalid selector "${selectorString}" for group "${group}":`, 
+          error instanceof Error ? error.message : error);
+      }
+    }
+    
+    // Update elements for each group
+    const groupedElements = elements as Record<string, Map<HTMLElement, ElementData>>;
+    const newGroupedElements: Record<string, Map<HTMLElement, ElementData>> = {};
+      
+      for (const [group, foundSet] of Object.entries(foundByGroup)) {
+        const currentMap = groupedElements[group] || new Map();
+        const newMap = new Map(currentMap);
+        
+        // Remove elements that no longer match
+        for (const [element, data] of currentMap) {
+          if (!foundSet.has(element)) {
+            // Call cleanup function if provided
+            if (data.cleanup) {
+              try {
+                data.cleanup();
+              } catch (error) {
+                console.warn('ElementManager: Error in element cleanup:', error);
+              }
+            }
+            
+            // Call removal callback
+            if (onElementRemoved) {
+              try {
+                onElementRemoved(element, data, group);
+              } catch (error) {
+                console.warn('ElementManager: Error in onElementRemoved callback:', error);
+              }
+            }
+            
+            newMap.delete(element);
+          }
+        }
+        
+        // Add new elements
+        foundSet.forEach((element) => {
+          if (!currentMap.has(element)) {
+            const elementData: ElementData = { element };
+            newMap.set(element, elementData);
+            
+            // Call addition callback
+            if (onElementAdded) {
+              try {
+                onElementAdded(element, elementData, group);
+              } catch (error) {
+                console.warn('ElementManager: Error in onElementAdded callback:', error);
+              }
+            }
+          }
+        });
+        
+        newGroupedElements[group] = newMap;
+      }
+      
+      // Handle removed groups
+      for (const group in groupedElements) {
+        if (!(group in newGroupedElements)) {
+          // Clean up all elements in removed group
+          const currentMap = groupedElements[group];
+          for (const [element, data] of currentMap) {
+            if (data.cleanup) {
+              try {
+                data.cleanup();
+              } catch (error) {
+                console.warn('ElementManager: Error in element cleanup for removed group:', error);
+              }
+            }
+            if (onElementRemoved) {
+              try {
+                onElementRemoved(element, data, group);
+              } catch (error) {
+                console.warn('ElementManager: Error in onElementRemoved callback for removed group:', error);
+              }
+            }
+          }
+        }
+      }
+      
+      elements = newGroupedElements;
+  }
+  
+  /**
+   * Debounced version of discoverElements to prevent excessive updates during rapid DOM changes.
+   * Uses 16ms delay (~60fps) for smooth performance.
+   */
+  function debouncedDiscoverElements() {
+    if (debounceTimeout) {
+      clearTimeout(debounceTimeout);
+    }
+    
+    debounceTimeout = setTimeout(() => {
+      discoverElements();
+      debounceTimeout = null;
+    }, 16); // ~60fps for smooth updates
+  }
+
+  // ===== MUTATION OBSERVER MANAGEMENT =====
+  
+  /**
+   * Sets up MutationObserver to watch for DOM changes and trigger element re-discovery.
+   * Includes error handling and recovery mechanisms.
+   */
+  function setupObserver() {
+    if (observer || !containerElement || !containerElement.isConnected) return;
+    
+    observer = new MutationObserver(() => {
+      try {
+        debouncedDiscoverElements();
+      } catch (error) {
+        console.warn('ElementManager: Error in MutationObserver callback:', error);
+        // Attempt to recover by re-running discovery without debouncing
+        try {
+          discoverElements();
+        } catch (recoveryError) {
+          console.warn('ElementManager: Failed to recover from MutationObserver error:', recoveryError);
+        }
+      }
+    });
+    
+    try {
+      // Use custom options or simple defaults
+      const options: MutationObserverInit = observerOptions || {
+        childList: true,
+        subtree: true,
+        attributes: true
+        // No attributeFilter - watch all attribute changes for simplicity
+      };
+      
+      observer.observe(containerElement, options);
+    } catch (error) {
+      console.warn('ElementManager: Failed to set up MutationObserver:', error);
+      observer = null;
+    }
+  }
+  
+  /**
+   * Cleanup function called on component destruction.
+   * Disconnects observer, clears timeouts, and runs element cleanup callbacks.
+   */
+  function cleanup() {
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
+    
+    if (debounceTimeout) {
+      clearTimeout(debounceTimeout);
+      debounceTimeout = null;
+    }
+    
+    // Clean up all remaining elements
+    if (elements) {
+      const groupedElements = elements as Record<string, Map<HTMLElement, ElementData>>;
+      for (const group in groupedElements) {
+        const currentMap = groupedElements[group];
+        for (const [, data] of currentMap) {
+          if (data.cleanup) {
+            try {
+              data.cleanup();
+            } catch (error) {
+              console.warn('ElementManager: Error in element cleanup during component destruction:', error);
+            }
+          }
+        }
+        currentMap.clear();
+      }
+    }
+  }
+  
+  // React to selector changes and handle initial setup
+  $effect(() => {
+    // Ensure selectors are tracked as dependencies
+    currentSelectors();
+    
+    // Only proceed if we have a container and are initialized
+    if (containerElement && initialized) {
+      // Clean up existing observer
+      if (observer) {
+        observer.disconnect();
+        observer = null;
+      }
+      
+      // Re-discover with new selectors (untrack to prevent reactivity loop)
+      untrack(() => {
+        discoverElements();
+      });
+      
+      // Set up observer with new selectors
+      setupObserver();
+    }
+  });
+
+  onMount(() => {
+    return cleanup;
+  });
+</script>
+
+<div bind:this={containerElement} class="contents">
+  {#if children}
+    {@render children()}
+  {/if}
+</div>

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

@@ -0,0 +1,43 @@
+import type { Snippet } from 'svelte';
+/**
+ * Data structure for each discovered element
+ */
+interface ElementData {
+    /** The HTML element that was discovered */
+    element: HTMLElement;
+    /** Optional cleanup function called when element is removed */
+    cleanup?: () => void;
+    /** Allow extension by consumer components with additional properties */
+    [key: string]: any;
+}
+/**
+ * ElementManager component props
+ *
+ * @example Basic usage
+ * ```svelte
+ * <ElementManager
+ *   selectors={{
+ *     tooltips: "[data-tooltip]",
+ *     modals: "[data-modal]"
+ *   }}
+ *   bind:elements={elementGroups}
+ * />
+ * ```
+ */
+interface Props {
+    /** Multiple CSS selectors organized by group name */
+    selectors: Record<string, string>;
+    /** Bindable Record of Maps for discovered elements */
+    elements?: Record<string, Map<HTMLElement, ElementData>>;
+    /** Optional child content to wrap (uses class="contents" for transparent rendering) */
+    children?: Snippet;
+    /** Callback fired when a new element is discovered */
+    onElementAdded?: (element: HTMLElement, data: ElementData, group: string) => void;
+    /** Callback fired when an element is removed or no longer matches selector */
+    onElementRemoved?: (element: HTMLElement, data: ElementData, group: string) => void;
+    /** Custom MutationObserver configuration (defaults to childList, subtree, attributes) */
+    observerOptions?: MutationObserverInit;
+}
+declare const ElementManager: import("svelte").Component<Props, {}, "elements">;
+type ElementManager = ReturnType<typeof ElementManager>;
+export default ElementManager;

package/dist/components/ElementManager/index.d.ts

@@ -0,0 +1 @@
+export { default } from './ElementManager.svelte';

package/dist/components/ElementManager/index.js

@@ -0,0 +1 @@
+export { default } from './ElementManager.svelte';

package/dist/components/EmailInput/EmailInput.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import Input from '../Input/Input.svelte';
+  import { faEnvelope } from '@fortawesome/free-solid-svg-icons';
+  import type { HTMLInputAttributes } from 'svelte/elements';
+
+  interface Props extends Omit<HTMLInputAttributes, 'type'> {
+    value: string;
+    class?: string;
+    inputClass?: string;
+    validate?: (value: string) => boolean | string;
+    valid?: boolean;
+    touched?: boolean;
+    element?: HTMLInputElement;
+    required?: boolean;
+  }
+
+  let {
+    value = $bindable(),
+    valid = $bindable(true),
+    touched = $bindable(false),
+    element = $bindable(),
+    validate,
+    required = false,
+    ...restProps
+  }: Props = $props();
+
+  // Default email validation
+  const defaultEmailValidator = (value: string) => {
+    if (required && !value) return 'Email is required';
+    if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return 'Please enter a valid email address';
+    return true;
+  };
+
+  // Use custom validator if provided, otherwise use default
+  const emailValidator = validate || defaultEmailValidator;
+</script>
+
+<Input
+  bind:value
+  bind:valid
+  bind:touched
+  bind:element
+  type="email"
+  icon={faEnvelope}
+  validate={emailValidator}
+  {...restProps}
+/>

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

@@ -0,0 +1,14 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLInputAttributes, 'type'> {
+    value: string;
+    class?: string;
+    inputClass?: string;
+    validate?: (value: string) => boolean | string;
+    valid?: boolean;
+    touched?: boolean;
+    element?: HTMLInputElement;
+    required?: boolean;
+}
+declare const EmailInput: import("svelte").Component<Props, {}, "element" | "value" | "valid" | "touched">;
+type EmailInput = ReturnType<typeof EmailInput>;
+export default EmailInput;

package/dist/components/EmailInput/index.d.ts

@@ -0,0 +1 @@
+export { default } from './EmailInput.svelte';

package/dist/components/EmailInput/index.js

@@ -0,0 +1 @@
+export { default } from './EmailInput.svelte';

package/dist/components/Icon/Icon.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+  import type { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+  import type { HTMLAttributes } from 'svelte/elements';
+  import type { Variant } from '../../types/variants.js';
+
+  interface Props extends HTMLAttributes<SVGElement> {
+    icon: IconDefinition;
+    class?: string;
+    size?: string;
+    color?: string;
+    variant?: Omit<Variant, 'ghost'>;
+  }
+
+  let {
+    icon,
+    class: className = '',
+    size,
+    color,
+    variant,
+    ...restProps
+  }: Props = $props();
+
+  const getIconSize = (size?: string) => {
+    if (!size) return '1rem';
+    
+    // Support explicit sizes (px, rem, em, etc.)
+    if (size.match(/^\d+(\.\d+)?(px|rem|em|%)$/)) {
+      return size;
+    }
+    
+    // Fallback to 1rem for invalid sizes
+    return '1rem';
+  };
+  
+  const svgWidth = $derived(icon.icon[0]);
+  const svgHeight = $derived(icon.icon[1]);
+  const svgPath = $derived(icon.icon[4]);
+  const iconSize = $derived(getIconSize(size));
+  
+  // Color priority: explicit color > variant color > currentColor
+  const fillColor = $derived(() => {
+    if (color) return color;
+    if (variant) return `var(--color-${variant})`;
+    return 'currentColor';
+  });
+</script>
+
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="0 0 {svgWidth} {svgHeight}"
+  class="svg-inline--fa {className}"
+  aria-hidden="true"
+  focusable="false"
+  role="img"
+  style:fill={fillColor()}
+  style:height={iconSize}
+  {...restProps}
+>
+  {#if typeof svgPath === 'string'}
+    <path d={svgPath} />
+  {:else if Array.isArray(svgPath)}
+    {#each svgPath as path}
+      <path d={path} />
+    {/each}
+  {/if}
+</svg>
+
+<style>
+  .svg-inline--fa {
+    display: inline-block;
+    overflow: visible;
+    vertical-align: -0.125em;
+  }
+</style>

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

@@ -0,0 +1,13 @@
+import type { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { Variant } from '../../types/variants.js';
+interface Props extends HTMLAttributes<SVGElement> {
+    icon: IconDefinition;
+    class?: string;
+    size?: string;
+    color?: string;
+    variant?: Omit<Variant, 'ghost'>;
+}
+declare const Icon: import("svelte").Component<Props, {}, "">;
+type Icon = ReturnType<typeof Icon>;
+export default Icon;

package/dist/components/Icon/index.d.ts

@@ -0,0 +1 @@
+export { default } from './Icon.svelte';

package/dist/components/Icon/index.js

@@ -0,0 +1 @@
+export { default } from './Icon.svelte';