sveltacular 0.0.77 → 1.0.1

package/dist/helpers/theme.svelte.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Theme Management Composable
+ *
+ * Provides reactive theme state and utilities for switching between light and dark modes.
+ * The theme preference is persisted in localStorage and synced across tabs.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTheme } from './theme.svelte';
+ *
+ *   const theme = useTheme();
+ * </script>
+ *
+ * <button onclick={() => theme.toggle()}>
+ *   Current theme: {theme.current}
+ * </button>
+ * ```
+ */
+export type Theme = 'light' | 'dark' | 'system';
+export type ResolvedTheme = 'light' | 'dark';
+declare class ThemeManager {
+    current: Theme;
+    resolved: ResolvedTheme;
+    private mediaQuery;
+    private initialized;
+    constructor();
+    private initialize;
+    private updateResolvedTheme;
+    private applyTheme;
+    /**
+     * Set the theme to a specific value
+     */
+    set(theme: Theme): void;
+    /**
+     * Toggle between light and dark themes
+     * (skips 'system' mode for simple toggling)
+     */
+    toggle(): void;
+    /**
+     * Reset to system preference
+     */
+    resetToSystem(): void;
+    /**
+     * Check if dark mode is currently active
+     */
+    get isDark(): boolean;
+    /**
+     * Check if light mode is currently active
+     */
+    get isLight(): boolean;
+    /**
+     * Check if system preference is being used
+     */
+    get isSystem(): boolean;
+}
+/**
+ * Get the theme manager instance
+ *
+ * @returns ThemeManager instance with reactive theme state
+ */
+export declare function useTheme(): ThemeManager;
+export {};

package/dist/helpers/theme.svelte.js

@@ -0,0 +1,123 @@
+/**
+ * Theme Management Composable
+ *
+ * Provides reactive theme state and utilities for switching between light and dark modes.
+ * The theme preference is persisted in localStorage and synced across tabs.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useTheme } from './theme.svelte';
+ *
+ *   const theme = useTheme();
+ * </script>
+ *
+ * <button onclick={() => theme.toggle()}>
+ *   Current theme: {theme.current}
+ * </button>
+ * ```
+ */
+const STORAGE_KEY = 'sveltacular-theme';
+const MEDIA_QUERY = '(prefers-color-scheme: dark)';
+class ThemeManager {
+    current = $state('system');
+    resolved = $state('light');
+    mediaQuery = null;
+    initialized = false;
+    constructor() {
+        if (typeof window !== 'undefined') {
+            this.initialize();
+        }
+    }
+    initialize() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        // Load saved preference or default to 'system'
+        const saved = localStorage.getItem(STORAGE_KEY);
+        this.current = saved || 'system';
+        // Set up media query listener for system preference
+        this.mediaQuery = window.matchMedia(MEDIA_QUERY);
+        this.updateResolvedTheme();
+        // Listen for system theme changes
+        this.mediaQuery.addEventListener('change', () => {
+            this.updateResolvedTheme();
+        });
+        // Listen for storage changes (sync across tabs)
+        window.addEventListener('storage', (e) => {
+            if (e.key === STORAGE_KEY && e.newValue) {
+                this.current = e.newValue;
+                this.updateResolvedTheme();
+            }
+        });
+        // Apply theme immediately
+        this.applyTheme();
+    }
+    updateResolvedTheme() {
+        if (this.current === 'system') {
+            this.resolved = this.mediaQuery?.matches ? 'dark' : 'light';
+        }
+        else {
+            this.resolved = this.current;
+        }
+    }
+    applyTheme() {
+        if (typeof document === 'undefined')
+            return;
+        this.updateResolvedTheme();
+        document.documentElement.setAttribute('data-theme', this.resolved);
+    }
+    /**
+     * Set the theme to a specific value
+     */
+    set(theme) {
+        this.current = theme;
+        localStorage.setItem(STORAGE_KEY, theme);
+        this.applyTheme();
+    }
+    /**
+     * Toggle between light and dark themes
+     * (skips 'system' mode for simple toggling)
+     */
+    toggle() {
+        const newTheme = this.resolved === 'dark' ? 'light' : 'dark';
+        this.set(newTheme);
+    }
+    /**
+     * Reset to system preference
+     */
+    resetToSystem() {
+        this.set('system');
+    }
+    /**
+     * Check if dark mode is currently active
+     */
+    get isDark() {
+        return this.resolved === 'dark';
+    }
+    /**
+     * Check if light mode is currently active
+     */
+    get isLight() {
+        return this.resolved === 'light';
+    }
+    /**
+     * Check if system preference is being used
+     */
+    get isSystem() {
+        return this.current === 'system';
+    }
+}
+// Singleton instance
+let themeManager = null;
+/**
+ * Get the theme manager instance
+ *
+ * @returns ThemeManager instance with reactive theme state
+ */
+export function useTheme() {
+    if (!themeManager) {
+        themeManager = new ThemeManager();
+    }
+    return themeManager;
+}

package/dist/helpers/unique-id.d.ts

@@ -1 +1,5 @@
+/**
+ * Generates a unique ID string using timestamp and random number
+ * @returns A unique hexadecimal string identifier
+ */
 export declare const uniqueId: () => string;

package/dist/helpers/unique-id.js

@@ -1,3 +1,7 @@
+/**
+ * Generates a unique ID string using timestamp and random number
+ * @returns A unique hexadecimal string identifier
+ */
 export const uniqueId = () => {
     return Math.floor(Math.random() * Date.now()).toString(16);
 };

package/dist/helpers/use-position.svelte.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Position Composable
+ *
+ * Reactive positioning for floating elements (tooltips, popovers, dropdowns).
+ * Automatically updates position on scroll and resize events.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { usePosition } from './use-position.svelte';
+ *
+ *   let buttonRef: HTMLElement;
+ *   let tooltipRef: HTMLElement;
+ *
+ *   const position = usePosition(() => buttonRef, () => tooltipRef, {
+ *     placement: 'top',
+ *     arrow: true
+ *   });
+ * </script>
+ *
+ * <button bind:this={buttonRef}>Hover me</button>
+ *
+ * <div
+ *   bind:this={tooltipRef}
+ *   style="position: fixed; top: {position.top}px; left: {position.left}px;"
+ * >
+ *   Tooltip content
+ * </div>
+ * ```
+ */
+import { type PositionOptions } from './positioning.js';
+export interface UsePositionOptions extends PositionOptions {
+    /**
+     * Whether positioning is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Update position on scroll
+     * @default true
+     */
+    updateOnScroll?: boolean;
+    /**
+     * Update position on resize
+     * @default true
+     */
+    updateOnResize?: boolean;
+}
+export declare class PositionManager {
+    top: number;
+    left: number;
+    side: import("./positioning.js").Side;
+    alignment: import("./positioning.js").Alignment;
+    arrowTop: number | undefined;
+    arrowLeft: number | undefined;
+    arrowSide: import("./positioning.js").Side;
+    private getReferenceElement;
+    private getFloatingElement;
+    private options;
+    private cleanup;
+    private rafId;
+    constructor(getReferenceElement: () => Element | null, getFloatingElement: () => Element | null, options: UsePositionOptions);
+    /**
+     * Update the position
+     */
+    update(): void;
+    /**
+     * Start listening for scroll and resize events
+     */
+    start(): void;
+    /**
+     * Stop listening for events
+     */
+    stop(): void;
+    /**
+     * Update options
+     */
+    setOptions(options: Partial<UsePositionOptions>): void;
+    /**
+     * Get current position as style object
+     */
+    get style(): string;
+    /**
+     * Get arrow style object
+     */
+    get arrowStyle(): string;
+}
+/**
+ * Create a position manager instance
+ *
+ * @param getReferenceElement - Function that returns the reference element
+ * @param getFloatingElement - Function that returns the floating element
+ * @param options - Positioning options
+ * @returns PositionManager instance
+ */
+export declare function usePosition(getReferenceElement: () => Element | null, getFloatingElement: () => Element | null, options: UsePositionOptions): PositionManager;

package/dist/helpers/use-position.svelte.js

@@ -0,0 +1,189 @@
+/**
+ * Position Composable
+ *
+ * Reactive positioning for floating elements (tooltips, popovers, dropdowns).
+ * Automatically updates position on scroll and resize events.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { usePosition } from './use-position.svelte';
+ *
+ *   let buttonRef: HTMLElement;
+ *   let tooltipRef: HTMLElement;
+ *
+ *   const position = usePosition(() => buttonRef, () => tooltipRef, {
+ *     placement: 'top',
+ *     arrow: true
+ *   });
+ * </script>
+ *
+ * <button bind:this={buttonRef}>Hover me</button>
+ *
+ * <div
+ *   bind:this={tooltipRef}
+ *   style="position: fixed; top: {position.top}px; left: {position.left}px;"
+ * >
+ *   Tooltip content
+ * </div>
+ * ```
+ */
+import { calculatePosition, calculateArrowPosition } from './positioning.js';
+import { onMount } from 'svelte';
+export class PositionManager {
+    // Position state
+    top = $state(0);
+    left = $state(0);
+    side = $state('bottom');
+    alignment = $state('center');
+    // Arrow state
+    arrowTop = $state(undefined);
+    arrowLeft = $state(undefined);
+    arrowSide = $state('bottom');
+    // Element getters
+    getReferenceElement;
+    getFloatingElement;
+    // Options
+    options;
+    // Cleanup
+    cleanup = null;
+    rafId = null;
+    constructor(getReferenceElement, getFloatingElement, options) {
+        this.getReferenceElement = getReferenceElement;
+        this.getFloatingElement = getFloatingElement;
+        this.options = {
+            enabled: true,
+            updateOnScroll: true,
+            updateOnResize: true,
+            ...options
+        };
+    }
+    /**
+     * Update the position
+     */
+    update() {
+        // Cancel any pending update
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+        }
+        // Schedule update in next frame
+        this.rafId = requestAnimationFrame(() => {
+            this.rafId = null;
+            if (!this.options.enabled)
+                return;
+            const reference = this.getReferenceElement();
+            const floating = this.getFloatingElement();
+            if (!reference || !floating)
+                return;
+            // Calculate position
+            const position = calculatePosition(reference, floating, this.options);
+            this.top = position.top;
+            this.left = position.left;
+            this.side = position.side;
+            this.alignment = position.alignment;
+            // Calculate arrow position if enabled
+            if (this.options.arrow) {
+                const arrow = calculateArrowPosition(reference, floating, position.side, this.options.arrowSize);
+                this.arrowTop = arrow.top;
+                this.arrowLeft = arrow.left;
+                this.arrowSide = arrow.side;
+            }
+        });
+    }
+    /**
+     * Start listening for scroll and resize events
+     */
+    start() {
+        this.stop(); // Clean up any existing listeners
+        // Initial update
+        this.update();
+        // Set up event listeners
+        const listeners = [];
+        if (this.options.updateOnScroll) {
+            const scrollHandler = () => this.update();
+            window.addEventListener('scroll', scrollHandler, { passive: true });
+            listeners.push(() => window.removeEventListener('scroll', scrollHandler));
+        }
+        if (this.options.updateOnResize) {
+            const resizeHandler = () => this.update();
+            window.addEventListener('resize', resizeHandler, { passive: true });
+            listeners.push(() => window.removeEventListener('resize', resizeHandler));
+        }
+        // Store cleanup function
+        this.cleanup = () => {
+            listeners.forEach(cleanup => cleanup());
+            if (this.rafId !== null) {
+                cancelAnimationFrame(this.rafId);
+                this.rafId = null;
+            }
+        };
+    }
+    /**
+     * Stop listening for events
+     */
+    stop() {
+        if (this.cleanup) {
+            this.cleanup();
+            this.cleanup = null;
+        }
+    }
+    /**
+     * Update options
+     */
+    setOptions(options) {
+        this.options = { ...this.options, ...options };
+        this.update();
+    }
+    /**
+     * Get current position as style object
+     */
+    get style() {
+        return `position: fixed; top: ${this.top}px; left: ${this.left}px;`;
+    }
+    /**
+     * Get arrow style object
+     */
+    get arrowStyle() {
+        const styles = ['position: absolute;'];
+        if (this.arrowLeft !== undefined) {
+            styles.push(`left: ${this.arrowLeft}px;`);
+        }
+        if (this.arrowTop !== undefined) {
+            styles.push(`top: ${this.arrowTop}px;`);
+        }
+        // Position arrow on the correct side
+        // Overlap by 1px to bridge gap created by border-radius
+        switch (this.arrowSide) {
+            case 'top':
+                styles.push('bottom: calc(100% - 1px);');
+                break;
+            case 'bottom':
+                styles.push('top: calc(100% - 1px);');
+                break;
+            case 'left':
+                styles.push('right: calc(100% - 1px);');
+                break;
+            case 'right':
+                styles.push('left: calc(100% - 1px);');
+                break;
+        }
+        return styles.join(' ');
+    }
+}
+/**
+ * Create a position manager instance
+ *
+ * @param getReferenceElement - Function that returns the reference element
+ * @param getFloatingElement - Function that returns the floating element
+ * @param options - Positioning options
+ * @returns PositionManager instance
+ */
+export function usePosition(getReferenceElement, getFloatingElement, options) {
+    const manager = new PositionManager(getReferenceElement, getFloatingElement, options);
+    // Auto-start on mount
+    onMount(() => {
+        manager.start();
+        return () => manager.stop();
+    });
+    return manager;
+}

package/dist/helpers/use-virtual-list.svelte.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Virtual List Composable
+ *
+ * Provides efficient rendering of large lists by only rendering visible items.
+ * Maintains 60fps performance with 10,000+ items through viewport-based rendering.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useVirtualList } from './use-virtual-list.svelte';
+ *
+ *   const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, name: `Item ${i}` }));
+ *   const virtual = useVirtualList(items, { itemHeight: 40 });
+ * </script>
+ *
+ * <div bind:this={virtual.containerRef} style="height: 400px; overflow-y: auto;">
+ *   <div style="height: {virtual.totalHeight}px; position: relative;">
+ *     {#each virtual.visibleItems as item (item.index)}
+ *       <div style="position: absolute; top: {item.offsetTop}px; height: {virtual.itemHeight}px;">
+ *         {item.data.name}
+ *       </div>
+ *     {/each}
+ *   </div>
+ * </div>
+ * ```
+ */
+export interface VirtualListOptions {
+    /**
+     * Height of each item in pixels
+     */
+    itemHeight: number;
+    /**
+     * Number of items to render outside the visible viewport (buffer zone)
+     * Higher values provide smoother scrolling but render more items
+     * @default 3
+     */
+    overscan?: number;
+    /**
+     * Enable variable height items (experimental)
+     * When true, itemHeight is used as estimated height
+     * @default false
+     */
+    variableHeight?: boolean;
+}
+export interface VirtualItem<T> {
+    /**
+     * Original index in the source array
+     */
+    index: number;
+    /**
+     * The actual data item
+     */
+    data: T;
+    /**
+     * Offset from the top of the container
+     */
+    offsetTop: number;
+    /**
+     * Height of this specific item (for variable height)
+     */
+    height: number;
+}
+export declare class VirtualList<T> {
+    private itemHeight;
+    private overscan;
+    private variableHeight;
+    items: T[];
+    visibleItems: VirtualItem<T>[];
+    totalHeight: number;
+    scrollTop: number;
+    containerHeight: number;
+    containerRef: HTMLElement | null;
+    private heightCache;
+    private scrollHandler;
+    private resizeObserver;
+    constructor(items: T[], options: VirtualListOptions);
+    /**
+     * Update the items array
+     */
+    setItems(items: T[]): void;
+    /**
+     * Set the container element and attach scroll listener
+     */
+    setContainer(element: HTMLElement | null): void;
+    /**
+     * Calculate total height of all items
+     */
+    private calculateTotalHeight;
+    /**
+     * Get the height of a specific item
+     */
+    private getItemHeight;
+    /**
+     * Get the offset top position for a specific item
+     */
+    private getItemOffsetTop;
+    /**
+     * Find the start index based on scroll position
+     */
+    private findStartIndex;
+    /**
+     * Update which items should be visible
+     */
+    private updateVisibleItems;
+    /**
+     * Update the height of a specific item (for variable height mode)
+     */
+    setItemHeight(index: number, height: number): void;
+    /**
+     * Scroll to a specific item index
+     */
+    scrollToIndex(index: number, behavior?: ScrollBehavior): void;
+    /**
+     * Clean up event listeners
+     */
+    destroy(): void;
+}
+/**
+ * Create a virtual list instance
+ */
+export declare function useVirtualList<T>(items: T[], options: VirtualListOptions): VirtualList<T>;