sveltacular 0.0.77 → 1.0.0

package/dist/helpers/focus.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Focus Management Utilities
+ *
+ * Provides utilities for managing focus in accessible components including:
+ * - Roving tabindex for keyboard navigation
+ * - Focus trapping for modals/dialogs
+ * - Focus restoration
+ * - Focusable element detection
+ */
+/**
+ * Query selector for all focusable elements
+ */
+export declare const FOCUSABLE_SELECTOR: string;
+/**
+ * Get all focusable elements within a container
+ */
+export declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/**
+ * Get the first focusable element within a container
+ */
+export declare function getFirstFocusable(container: HTMLElement): HTMLElement | null;
+/**
+ * Get the last focusable element within a container
+ */
+export declare function getLastFocusable(container: HTMLElement): HTMLElement | null;
+/**
+ * Focus Trap - traps focus within a container (for modals, dialogs)
+ * Returns a cleanup function to remove the trap
+ */
+export declare function createFocusTrap(container: HTMLElement | null): () => void;
+/**
+ * Roving Tabindex Manager
+ * Manages keyboard navigation in a list of items (for menus, lists, tabs, etc.)
+ */
+export declare class RovingTabindexManager {
+    private items;
+    private currentIndex;
+    private orientation;
+    private loop;
+    constructor(items: HTMLElement[], options?: {
+        orientation?: 'horizontal' | 'vertical' | 'both';
+        loop?: boolean;
+        initialIndex?: number;
+    });
+    /**
+     * Update tabindex attributes based on current index
+     */
+    private updateTabindices;
+    /**
+     * Move focus to a specific index
+     */
+    focusItem(index: number): void;
+    /**
+     * Move focus to the next item
+     */
+    focusNext(): void;
+    /**
+     * Move focus to the previous item
+     */
+    focusPrevious(): void;
+    /**
+     * Move focus to the first item
+     */
+    focusFirst(): void;
+    /**
+     * Move focus to the last item
+     */
+    focusLast(): void;
+    /**
+     * Handle keyboard events for roving tabindex
+     */
+    handleKeyDown(event: KeyboardEvent): void;
+    /**
+     * Update the items list (when items change dynamically)
+     */
+    updateItems(items: HTMLElement[]): void;
+    /**
+     * Get the currently focused item index
+     */
+    getCurrentIndex(): number;
+    /**
+     * Get the currently focused item
+     */
+    getCurrentItem(): HTMLElement | null;
+}
+/**
+ * Svelte action for roving tabindex
+ * Usage: <div use:rovingTabindex={{ items, orientation: 'vertical' }}>
+ */
+export declare function rovingTabindex(node: HTMLElement, options: {
+    itemSelector: string;
+    orientation?: 'horizontal' | 'vertical' | 'both';
+    loop?: boolean;
+}): {
+    update(newOptions: typeof options): void;
+    destroy(): void;
+};
+/**
+ * Store the currently focused element
+ * Returns the element that had focus when this was called
+ */
+export declare function storeFocus(): HTMLElement | null;
+/**
+ * Restore focus to a previously stored element
+ */
+export declare function restoreFocus(element: HTMLElement | null): void;
+/**
+ * Trap focus within a container (simplified alias for createFocusTrap)
+ * Returns cleanup function
+ */
+export declare function trapFocus(container: HTMLElement | null): () => void;
+/**
+ * Focus-visible polyfill check
+ * Returns true if the browser supports :focus-visible
+ */
+export declare function supportsFocusVisible(): boolean;
+/**
+ * Add focus-visible class management for older browsers
+ * Usage: use:focusVisible on any focusable element
+ */
+export declare function focusVisible(node: HTMLElement): {
+    destroy(): void;
+};

package/dist/helpers/focus.js

@@ -0,0 +1,335 @@
+/**
+ * Focus Management Utilities
+ *
+ * Provides utilities for managing focus in accessible components including:
+ * - Roving tabindex for keyboard navigation
+ * - Focus trapping for modals/dialogs
+ * - Focus restoration
+ * - Focusable element detection
+ */
+/**
+ * Query selector for all focusable elements
+ */
+export const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'area[href]',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    'button:not([disabled])',
+    'iframe',
+    'object',
+    'embed',
+    '[tabindex]:not([tabindex="-1"])',
+    '[contenteditable]',
+    'audio[controls]',
+    'video[controls]'
+].join(',');
+/**
+ * Get all focusable elements within a container
+ */
+export function getFocusableElements(container) {
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => {
+        // Filter out elements that are not visible
+        return (el.offsetWidth > 0 &&
+            el.offsetHeight > 0 &&
+            window.getComputedStyle(el).visibility !== 'hidden');
+    });
+}
+/**
+ * Get the first focusable element within a container
+ */
+export function getFirstFocusable(container) {
+    const elements = getFocusableElements(container);
+    return elements[0] || null;
+}
+/**
+ * Get the last focusable element within a container
+ */
+export function getLastFocusable(container) {
+    const elements = getFocusableElements(container);
+    return elements[elements.length - 1] || null;
+}
+/**
+ * Focus Trap - traps focus within a container (for modals, dialogs)
+ * Returns a cleanup function to remove the trap
+ */
+export function createFocusTrap(container) {
+    // Guard against invalid container
+    if (!container || !(container instanceof HTMLElement) || !container.querySelectorAll) {
+        console.warn('createFocusTrap: Invalid container provided', container);
+        return () => { }; // Return no-op cleanup
+    }
+    const firstFocusable = getFirstFocusable(container);
+    const lastFocusable = getLastFocusable(container);
+    // Store the previously focused element to restore later
+    const previouslyFocused = document.activeElement;
+    // Focus the first focusable element
+    firstFocusable?.focus();
+    const handleKeyDown = (event) => {
+        if (event.key !== 'Tab')
+            return;
+        const focusableElements = getFocusableElements(container);
+        const firstElement = focusableElements[0];
+        const lastElement = focusableElements[focusableElements.length - 1];
+        // Shift + Tab: wrap to last element
+        if (event.shiftKey && document.activeElement === firstElement) {
+            event.preventDefault();
+            lastElement?.focus();
+        }
+        // Tab: wrap to first element
+        else if (!event.shiftKey && document.activeElement === lastElement) {
+            event.preventDefault();
+            firstElement?.focus();
+        }
+    };
+    container.addEventListener('keydown', handleKeyDown);
+    // Return cleanup function
+    return () => {
+        container.removeEventListener('keydown', handleKeyDown);
+        // Restore focus to previously focused element
+        previouslyFocused?.focus();
+    };
+}
+/**
+ * Roving Tabindex Manager
+ * Manages keyboard navigation in a list of items (for menus, lists, tabs, etc.)
+ */
+export class RovingTabindexManager {
+    items = [];
+    currentIndex = 0;
+    orientation = 'vertical';
+    loop = true;
+    constructor(items, options = {}) {
+        this.items = items;
+        this.orientation = options.orientation || 'vertical';
+        this.loop = options.loop !== undefined ? options.loop : true;
+        this.currentIndex = options.initialIndex || 0;
+        // Set initial tabindex values
+        this.updateTabindices();
+    }
+    /**
+     * Update tabindex attributes based on current index
+     */
+    updateTabindices() {
+        this.items.forEach((item, index) => {
+            if (index === this.currentIndex) {
+                item.setAttribute('tabindex', '0');
+            }
+            else {
+                item.setAttribute('tabindex', '-1');
+            }
+        });
+    }
+    /**
+     * Move focus to a specific index
+     */
+    focusItem(index) {
+        if (index < 0 || index >= this.items.length)
+            return;
+        this.currentIndex = index;
+        this.updateTabindices();
+        this.items[index]?.focus();
+    }
+    /**
+     * Move focus to the next item
+     */
+    focusNext() {
+        let nextIndex = this.currentIndex + 1;
+        if (nextIndex >= this.items.length) {
+            nextIndex = this.loop ? 0 : this.items.length - 1;
+        }
+        this.focusItem(nextIndex);
+    }
+    /**
+     * Move focus to the previous item
+     */
+    focusPrevious() {
+        let prevIndex = this.currentIndex - 1;
+        if (prevIndex < 0) {
+            prevIndex = this.loop ? this.items.length - 1 : 0;
+        }
+        this.focusItem(prevIndex);
+    }
+    /**
+     * Move focus to the first item
+     */
+    focusFirst() {
+        this.focusItem(0);
+    }
+    /**
+     * Move focus to the last item
+     */
+    focusLast() {
+        this.focusItem(this.items.length - 1);
+    }
+    /**
+     * Handle keyboard events for roving tabindex
+     */
+    handleKeyDown(event) {
+        const { key } = event;
+        // Vertical navigation
+        if (this.orientation === 'vertical' || this.orientation === 'both') {
+            if (key === 'ArrowDown') {
+                event.preventDefault();
+                this.focusNext();
+                return;
+            }
+            if (key === 'ArrowUp') {
+                event.preventDefault();
+                this.focusPrevious();
+                return;
+            }
+        }
+        // Horizontal navigation
+        if (this.orientation === 'horizontal' || this.orientation === 'both') {
+            if (key === 'ArrowRight') {
+                event.preventDefault();
+                this.focusNext();
+                return;
+            }
+            if (key === 'ArrowLeft') {
+                event.preventDefault();
+                this.focusPrevious();
+                return;
+            }
+        }
+        // Home/End
+        if (key === 'Home') {
+            event.preventDefault();
+            this.focusFirst();
+            return;
+        }
+        if (key === 'End') {
+            event.preventDefault();
+            this.focusLast();
+            return;
+        }
+    }
+    /**
+     * Update the items list (when items change dynamically)
+     */
+    updateItems(items) {
+        this.items = items;
+        this.currentIndex = Math.min(this.currentIndex, items.length - 1);
+        this.updateTabindices();
+    }
+    /**
+     * Get the currently focused item index
+     */
+    getCurrentIndex() {
+        return this.currentIndex;
+    }
+    /**
+     * Get the currently focused item
+     */
+    getCurrentItem() {
+        return this.items[this.currentIndex] || null;
+    }
+}
+/**
+ * Svelte action for roving tabindex
+ * Usage: <div use:rovingTabindex={{ items, orientation: 'vertical' }}>
+ */
+export function rovingTabindex(node, options) {
+    let manager;
+    function updateManager() {
+        const items = Array.from(node.querySelectorAll(options.itemSelector));
+        if (manager) {
+            manager.updateItems(items);
+        }
+        else {
+            manager = new RovingTabindexManager(items, {
+                orientation: options.orientation,
+                loop: options.loop
+            });
+        }
+    }
+    function handleKeyDown(event) {
+        manager?.handleKeyDown(event);
+    }
+    // Initialize
+    updateManager();
+    node.addEventListener('keydown', handleKeyDown);
+    // Set up MutationObserver to watch for DOM changes
+    const observer = new MutationObserver(updateManager);
+    observer.observe(node, { childList: true, subtree: true });
+    return {
+        update(newOptions) {
+            options = newOptions;
+            updateManager();
+        },
+        destroy() {
+            node.removeEventListener('keydown', handleKeyDown);
+            observer.disconnect();
+        }
+    };
+}
+/**
+ * Store the currently focused element
+ * Returns the element that had focus when this was called
+ */
+export function storeFocus() {
+    return document.activeElement;
+}
+/**
+ * Restore focus to a previously stored element
+ */
+export function restoreFocus(element) {
+    if (element && typeof element.focus === 'function') {
+        element.focus();
+    }
+}
+/**
+ * Trap focus within a container (simplified alias for createFocusTrap)
+ * Returns cleanup function
+ */
+export function trapFocus(container) {
+    return createFocusTrap(container);
+}
+/**
+ * Focus-visible polyfill check
+ * Returns true if the browser supports :focus-visible
+ */
+export function supportsFocusVisible() {
+    try {
+        document.querySelector(':focus-visible');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Add focus-visible class management for older browsers
+ * Usage: use:focusVisible on any focusable element
+ */
+export function focusVisible(node) {
+    let hadKeyboardEvent = false;
+    function onKeyDown() {
+        hadKeyboardEvent = true;
+    }
+    function onPointerDown() {
+        hadKeyboardEvent = false;
+    }
+    function onFocus() {
+        if (hadKeyboardEvent) {
+            node.classList.add('focus-visible');
+        }
+    }
+    function onBlur() {
+        node.classList.remove('focus-visible');
+    }
+    document.addEventListener('keydown', onKeyDown);
+    document.addEventListener('pointerdown', onPointerDown);
+    node.addEventListener('focus', onFocus);
+    node.addEventListener('blur', onBlur);
+    return {
+        destroy() {
+            document.removeEventListener('keydown', onKeyDown);
+            document.removeEventListener('pointerdown', onPointerDown);
+            node.removeEventListener('focus', onFocus);
+            node.removeEventListener('blur', onBlur);
+        }
+    };
+}

package/dist/helpers/fuzzy-search.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Fuzzy search utility for command palette and other search features
+ * Zero dependencies, custom implementation
+ */
+export interface FuzzyMatch {
+    /** The item that matched */
+    item: any;
+    /** The score of the match (higher is better) */
+    score: number;
+    /** The indices of matched characters in the string */
+    matches: number[];
+    /** The key that was matched (if searching object properties) */
+    matchedKey?: string;
+}
+export interface FuzzySearchOptions {
+    /** Keys to search in if items are objects */
+    keys?: string[];
+    /** Minimum score threshold (0-1) */
+    threshold?: number;
+    /** Maximum results to return */
+    limit?: number;
+    /** Case sensitive search */
+    caseSensitive?: boolean;
+}
+/**
+ * Calculate fuzzy match score for a query against a string
+ * Returns { score, matches } where matches are character indices
+ */
+export declare function fuzzyMatch(query: string, str: string, caseSensitive?: boolean): {
+    score: number;
+    matches: number[];
+} | null;
+/**
+ * Search an array of items with fuzzy matching
+ */
+export declare function fuzzySearch<T = any>(query: string, items: T[], options?: FuzzySearchOptions): FuzzyMatch[];
+/**
+ * Highlight matched characters in a string
+ * Returns HTML string with <mark> tags around matches
+ */
+export declare function highlightMatches(str: string, matches: number[]): string;

package/dist/helpers/fuzzy-search.js

@@ -0,0 +1,114 @@
+/**
+ * Fuzzy search utility for command palette and other search features
+ * Zero dependencies, custom implementation
+ */
+/**
+ * Calculate fuzzy match score for a query against a string
+ * Returns { score, matches } where matches are character indices
+ */
+export function fuzzyMatch(query, str, caseSensitive = false) {
+    if (!query)
+        return { score: 1, matches: [] };
+    if (!str)
+        return null;
+    const queryStr = caseSensitive ? query : query.toLowerCase();
+    const searchStr = caseSensitive ? str : str.toLowerCase();
+    let score = 0;
+    let queryIndex = 0;
+    const matches = [];
+    let previousMatchIndex = -1;
+    let consecutiveMatchCount = 0;
+    // Try to match each character in the query
+    for (let i = 0; i < searchStr.length && queryIndex < queryStr.length; i++) {
+        if (searchStr[i] === queryStr[queryIndex]) {
+            matches.push(i);
+            // Base score for match
+            score += 1;
+            // Bonus for consecutive matches
+            if (previousMatchIndex === i - 1) {
+                consecutiveMatchCount++;
+                score += consecutiveMatchCount * 5; // Exponential bonus
+            }
+            else {
+                consecutiveMatchCount = 0;
+            }
+            // Bonus for matching at word boundaries
+            if (i === 0 || searchStr[i - 1] === ' ' || searchStr[i - 1] === '-') {
+                score += 10;
+            }
+            // Bonus for matching uppercase in camelCase
+            if (str[i] === str[i].toUpperCase() && str[i] !== str[i].toLowerCase()) {
+                score += 5;
+            }
+            previousMatchIndex = i;
+            queryIndex++;
+        }
+    }
+    // Must match all characters in query
+    if (queryIndex !== queryStr.length) {
+        return null;
+    }
+    // Normalize score based on string length
+    score = score / str.length;
+    return { score, matches };
+}
+/**
+ * Search an array of items with fuzzy matching
+ */
+export function fuzzySearch(query, items, options = {}) {
+    const { keys = [], threshold = 0, limit = Infinity, caseSensitive = false } = options;
+    const results = [];
+    for (const item of items) {
+        let bestMatch = null;
+        // If item is a string, search directly
+        if (typeof item === 'string') {
+            const match = fuzzyMatch(query, item, caseSensitive);
+            if (match && match.score >= threshold) {
+                bestMatch = match;
+            }
+        }
+        // If item is an object, search specified keys
+        else if (typeof item === 'object' && item !== null) {
+            for (const key of keys) {
+                const value = item[key];
+                if (typeof value === 'string') {
+                    const match = fuzzyMatch(query, value, caseSensitive);
+                    if (match && match.score >= threshold) {
+                        if (!bestMatch || match.score > bestMatch.score) {
+                            bestMatch = { ...match, matchedKey: key };
+                        }
+                    }
+                }
+            }
+        }
+        if (bestMatch) {
+            results.push({
+                item,
+                score: bestMatch.score,
+                matches: bestMatch.matches,
+                matchedKey: bestMatch.matchedKey
+            });
+        }
+    }
+    // Sort by score (descending)
+    results.sort((a, b) => b.score - a.score);
+    // Apply limit
+    return results.slice(0, limit);
+}
+/**
+ * Highlight matched characters in a string
+ * Returns HTML string with <mark> tags around matches
+ */
+export function highlightMatches(str, matches) {
+    if (!matches.length)
+        return str;
+    let result = '';
+    let lastIndex = 0;
+    for (const index of matches) {
+        result += str.slice(lastIndex, index);
+        result += `<mark>${str[index]}</mark>`;
+        lastIndex = index + 1;
+    }
+    result += str.slice(lastIndex);
+    return result;
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,24 @@
+export * from './ago.js';
+export * from './anchor.js';
+export * from './animation-actions.js';
+export * from './animations.js';
+export * from './announcer.js';
+export * from './capitalize.js';
+export * from './copy-to-clipboard.svelte.js';
+export * from './date.js';
+export * from './debounce.js';
+export * from './focus.js';
+export * from './fuzzy-search.js';
+export * from './navigate-to.js';
+export * from './nobr.js';
+export * from './random.js';
+export * from './remove-properties.js';
+export * from './round-to-decimals.js';
+export * from './split-new-lines.js';
+export * from './spring.svelte.js';
+export * from './subscribable.js';
+export * from './theme.svelte.js';
+export * from './transform.js';
+export * from './ucfirst.js';
+export * from './unique-id.js';
+export * from './use-virtual-list.svelte.js';

package/dist/helpers/index.js

@@ -0,0 +1,24 @@
+export * from './ago.js';
+export * from './anchor.js';
+export * from './animation-actions.js';
+export * from './animations.js';
+export * from './announcer.js';
+export * from './capitalize.js';
+export * from './copy-to-clipboard.svelte.js';
+export * from './date.js';
+export * from './debounce.js';
+export * from './focus.js';
+export * from './fuzzy-search.js';
+export * from './navigate-to.js';
+export * from './nobr.js';
+export * from './random.js';
+export * from './remove-properties.js';
+export * from './round-to-decimals.js';
+export * from './split-new-lines.js';
+export * from './spring.svelte.js';
+export * from './subscribable.js';
+export * from './theme.svelte.js';
+export * from './transform.js';
+export * from './ucfirst.js';
+export * from './unique-id.js';
+export * from './use-virtual-list.svelte.js';

package/dist/helpers/navigate-to.d.ts

@@ -1 +1,5 @@
+/**
+ * Navigate to a URL using SvelteKit's navigation, with fallback to window.location
+ * @param url - The URL to navigate to
+ */
 export declare const navigateTo: (url: string) => void;

package/dist/helpers/navigate-to.js

@@ -1,6 +1,10 @@
 import { browser } from '$app/environment';
 import { goto } from '$app/navigation';
 import { redirect } from '@sveltejs/kit';
+/**
+ * Navigate to a URL using SvelteKit's navigation, with fallback to window.location
+ * @param url - The URL to navigate to
+ */
 export const navigateTo = (url) => {
     if (browser) {
         setTimeout(() => {