sveltacular 0.0.76 → 1.0.0

package/dist/helpers/positioning.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Positioning Utilities
+ *
+ * Pure JavaScript positioning calculations for tooltips, popovers, dropdowns, etc.
+ * Handles viewport collision detection, auto-flip positioning, and arrow placement.
+ *
+ * Built from scratch with zero dependencies as an alternative to Floating UI.
+ */
+export type Placement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+export type Alignment = 'start' | 'center' | 'end';
+export interface Position {
+    top: number;
+    left: number;
+    side: Side;
+    alignment: Alignment;
+}
+export interface ArrowPosition {
+    top?: number;
+    left?: number;
+    side: Side;
+}
+export interface PositionOptions {
+    /**
+     * Preferred placement for the floating element
+     */
+    placement: Placement;
+    /**
+     * Offset from the reference element in pixels
+     * @default 8
+     */
+    offset?: number;
+    /**
+     * Whether to flip to opposite side if doesn't fit
+     * @default true
+     */
+    autoFlip?: boolean;
+    /**
+     * Whether to adjust alignment if doesn't fit
+     * @default true
+     */
+    autoAlign?: boolean;
+    /**
+     * Padding from viewport edges in pixels
+     * @default 8
+     */
+    viewportPadding?: number;
+    /**
+     * Whether to include an arrow/pointer
+     * @default false
+     */
+    arrow?: boolean;
+    /**
+     * Size of the arrow in pixels
+     * @default 8
+     */
+    arrowSize?: number;
+}
+export interface Rect {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+/**
+ * Get the bounding rect of an element
+ */
+export declare function getRect(element: Element): Rect;
+/**
+ * Get the viewport dimensions
+ */
+export declare function getViewport(): Rect;
+/**
+ * Parse placement string into side and alignment
+ */
+export declare function parsePlacement(placement: Placement): {
+    side: Side;
+    alignment: Alignment;
+};
+/**
+ * Get the opposite side
+ */
+export declare function getOppositeSide(side: Side): Side;
+/**
+ * Calculate the best position for a floating element
+ */
+export declare function calculatePosition(referenceElement: Element, floatingElement: Element, options: PositionOptions): Position;
+/**
+ * Calculate arrow position relative to the floating element
+ */
+export declare function calculateArrowPosition(referenceElement: Element, floatingElement: Element, side: Side, arrowSize?: number): ArrowPosition;
+/**
+ * Create a positioning update function that can be called on scroll/resize
+ */
+export declare function createPositionUpdater(referenceElement: Element, floatingElement: Element, options: PositionOptions, onUpdate: (position: Position, arrow?: ArrowPosition) => void): () => void;

package/dist/helpers/positioning.js

@@ -0,0 +1,230 @@
+/**
+ * Positioning Utilities
+ *
+ * Pure JavaScript positioning calculations for tooltips, popovers, dropdowns, etc.
+ * Handles viewport collision detection, auto-flip positioning, and arrow placement.
+ *
+ * Built from scratch with zero dependencies as an alternative to Floating UI.
+ */
+/**
+ * Get the bounding rect of an element
+ */
+export function getRect(element) {
+    const rect = element.getBoundingClientRect();
+    return {
+        top: rect.top,
+        left: rect.left,
+        right: rect.right,
+        bottom: rect.bottom,
+        width: rect.width,
+        height: rect.height
+    };
+}
+/**
+ * Get the viewport dimensions
+ */
+export function getViewport() {
+    return {
+        top: 0,
+        left: 0,
+        right: window.innerWidth,
+        bottom: window.innerHeight,
+        width: window.innerWidth,
+        height: window.innerHeight
+    };
+}
+/**
+ * Parse placement string into side and alignment
+ */
+export function parsePlacement(placement) {
+    const [side, alignment = 'center'] = placement.split('-');
+    return { side, alignment: alignment || 'center' };
+}
+/**
+ * Get the opposite side
+ */
+export function getOppositeSide(side) {
+    const opposites = {
+        top: 'bottom',
+        bottom: 'top',
+        left: 'right',
+        right: 'left'
+    };
+    return opposites[side];
+}
+/**
+ * Calculate position for a given side and alignment
+ */
+function calculatePositionForSide(reference, floating, side, alignment, offset) {
+    let top = 0;
+    let left = 0;
+    // Calculate based on side
+    switch (side) {
+        case 'top':
+            top = reference.top - floating.height - offset;
+            left = reference.left;
+            break;
+        case 'bottom':
+            top = reference.bottom + offset;
+            left = reference.left;
+            break;
+        case 'left':
+            top = reference.top;
+            left = reference.left - floating.width - offset;
+            break;
+        case 'right':
+            top = reference.top;
+            left = reference.right + offset;
+            break;
+    }
+    // Adjust for alignment
+    if (side === 'top' || side === 'bottom') {
+        switch (alignment) {
+            case 'start':
+                // left already set
+                break;
+            case 'center':
+                left = reference.left + reference.width / 2 - floating.width / 2;
+                break;
+            case 'end':
+                left = reference.right - floating.width;
+                break;
+        }
+    }
+    else {
+        // left or right
+        switch (alignment) {
+            case 'start':
+                // top already set
+                break;
+            case 'center':
+                top = reference.top + reference.height / 2 - floating.height / 2;
+                break;
+            case 'end':
+                top = reference.bottom - floating.height;
+                break;
+        }
+    }
+    return { top, left };
+}
+/**
+ * Check if floating element fits in viewport at given position
+ */
+function fitsInViewport(position, floating, viewport, padding) {
+    const right = position.left + floating.width;
+    const bottom = position.top + floating.height;
+    return (position.top >= viewport.top + padding &&
+        position.left >= viewport.left + padding &&
+        right <= viewport.right - padding &&
+        bottom <= viewport.bottom - padding);
+}
+/**
+ * Calculate the best position for a floating element
+ */
+export function calculatePosition(referenceElement, floatingElement, options) {
+    const { placement, offset = 8, autoFlip = true, autoAlign = true, viewportPadding = 8 } = options;
+    const reference = getRect(referenceElement);
+    const floating = getRect(floatingElement);
+    const viewport = getViewport();
+    let { side, alignment } = parsePlacement(placement);
+    // Try preferred placement
+    let position = calculatePositionForSide(reference, floating, side, alignment, offset);
+    let fits = fitsInViewport(position, floating, viewport, viewportPadding);
+    // Try flipping to opposite side if doesn't fit
+    if (!fits && autoFlip) {
+        const oppositeSide = getOppositeSide(side);
+        const flippedPosition = calculatePositionForSide(reference, floating, oppositeSide, alignment, offset);
+        const flippedFits = fitsInViewport(flippedPosition, floating, viewport, viewportPadding);
+        if (flippedFits) {
+            side = oppositeSide;
+            position = flippedPosition;
+            fits = true;
+        }
+    }
+    // Try adjusting alignment if still doesn't fit
+    if (!fits && autoAlign) {
+        const alignments = ['start', 'center', 'end'];
+        for (const testAlignment of alignments) {
+            if (testAlignment === alignment)
+                continue;
+            const adjustedPosition = calculatePositionForSide(reference, floating, side, testAlignment, offset);
+            const adjustedFits = fitsInViewport(adjustedPosition, floating, viewport, viewportPadding);
+            if (adjustedFits) {
+                alignment = testAlignment;
+                position = adjustedPosition;
+                fits = true;
+                break;
+            }
+        }
+    }
+    // Clamp to viewport if still doesn't fit
+    if (!fits) {
+        position.left = Math.max(viewport.left + viewportPadding, Math.min(position.left, viewport.right - floating.width - viewportPadding));
+        position.top = Math.max(viewport.top + viewportPadding, Math.min(position.top, viewport.bottom - floating.height - viewportPadding));
+    }
+    return {
+        top: position.top,
+        left: position.left,
+        side,
+        alignment
+    };
+}
+/**
+ * Calculate arrow position relative to the floating element
+ */
+export function calculateArrowPosition(referenceElement, floatingElement, side, arrowSize = 8) {
+    const reference = getRect(referenceElement);
+    const floating = getRect(floatingElement);
+    // Arrow should be on the opposite side of where the tooltip is positioned
+    // If tooltip is on top, arrow is on bottom pointing down toward the element
+    const arrowPosition = { side: getOppositeSide(side) };
+    // Calculate arrow position to point at center of reference element
+    // Arrow CSS creates a triangle using borders, which is arrowSize*2 wide/tall
+    // The point of the arrow is at the center of that dimension
+    if (side === 'top' || side === 'bottom') {
+        // Arrow is horizontally positioned
+        const referenceCenterX = reference.left + reference.width / 2;
+        const floatingLeft = floating.left;
+        // Center the arrow (which is arrowSize*2 wide) on the reference center
+        arrowPosition.left = referenceCenterX - floatingLeft - arrowSize;
+        // Clamp arrow within floating element bounds, with padding to avoid rounded corners
+        // Typical border-radius is 4-6px, so keep arrow at least 8px from edges
+        const cornerPadding = arrowSize; // Keep arrow away from border-radius areas
+        arrowPosition.left = Math.max(cornerPadding, Math.min(arrowPosition.left, floating.width - cornerPadding - arrowSize * 2));
+    }
+    else {
+        // Arrow is vertically positioned
+        const referenceCenterY = reference.top + reference.height / 2;
+        const floatingTop = floating.top;
+        // Center the arrow (which is arrowSize*2 tall) on the reference center
+        arrowPosition.top = referenceCenterY - floatingTop - arrowSize;
+        // Clamp arrow within floating element bounds, with padding to avoid rounded corners
+        // Typical border-radius is 4-6px, so keep arrow at least 8px from edges
+        const cornerPadding = arrowSize; // Keep arrow away from border-radius areas
+        arrowPosition.top = Math.max(cornerPadding, Math.min(arrowPosition.top, floating.height - cornerPadding - arrowSize * 2));
+    }
+    return arrowPosition;
+}
+/**
+ * Create a positioning update function that can be called on scroll/resize
+ */
+export function createPositionUpdater(referenceElement, floatingElement, options, onUpdate) {
+    const update = () => {
+        const position = calculatePosition(referenceElement, floatingElement, options);
+        let arrow;
+        if (options.arrow) {
+            arrow = calculateArrowPosition(referenceElement, floatingElement, position.side, options.arrowSize);
+        }
+        onUpdate(position, arrow);
+    };
+    // Initial update
+    update();
+    // Listen for scroll and resize
+    window.addEventListener('scroll', update, { passive: true });
+    window.addEventListener('resize', update, { passive: true });
+    // Return cleanup function
+    return () => {
+        window.removeEventListener('scroll', update);
+        window.removeEventListener('resize', update);
+    };
+}

package/dist/helpers/round-to-decimals.d.ts

@@ -1,12 +1,14 @@
 /**
  * Round a number to a specific number of decimals
- *
- * @param value
- * @param decimals
- * @returns
+ * @param value - The number to round
+ * @param decimals - Number of decimal places
+ * @returns The rounded number
  */
 export declare const roundToDecimals: (value: number, decimals: number) => number;
 /**
- * Format a number to a string with a specific number of decimals
+ * Format a number to a string with a specific number of decimals using locale formatting
+ * @param value - The number to format
+ * @param decimals - Number of decimal places
+ * @returns The formatted number string
  */
 export declare const formatNumber: (value: number, decimals: number) => string;

package/dist/helpers/round-to-decimals.js

@@ -1,9 +1,8 @@
 /**
  * Round a number to a specific number of decimals
- *
- * @param value
- * @param decimals
- * @returns
+ * @param value - The number to round
+ * @param decimals - Number of decimal places
+ * @returns The rounded number
  */
 export const roundToDecimals = (value, decimals) => {
     if (!decimals)
@@ -11,7 +10,10 @@ export const roundToDecimals = (value, decimals) => {
     return Number(Math.round(Number(`${value}e${decimals}`)) + `e-${decimals}`);
 };
 /**
- * Format a number to a string with a specific number of decimals
+ * Format a number to a string with a specific number of decimals using locale formatting
+ * @param value - The number to format
+ * @param decimals - Number of decimal places
+ * @returns The formatted number string
  */
 export const formatNumber = (value, decimals) => {
     return roundToDecimals(value, decimals).toLocaleString();

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

@@ -0,0 +1,97 @@
+/**
+ * Spring animation composable using Svelte 5 runes
+ * Provides smooth, physics-based animations with $state reactivity
+ * @module spring
+ */
+import { springPresets, type SpringConfig } from './animations.js';
+/**
+ * Options for creating a spring animation
+ */
+export interface UseSpringOptions extends SpringConfig {
+    /** Initial value */
+    initialValue?: number;
+    /** Preset configuration name */
+    preset?: keyof typeof springPresets;
+}
+/**
+ * Spring animation composable with Svelte 5 $state
+ *
+ * @example
+ * ```typescript
+ * const scale = useSpring({ initialValue: 1, preset: 'wobbly' });
+ *
+ * // Set target value - spring will animate toward it
+ * scale.set(1.5);
+ *
+ * // Use the current value in your template
+ * console.log(scale.value); // Reactive value that updates during animation
+ * ```
+ */
+export declare function useSpring(options?: UseSpringOptions): {
+    /**
+     * Current animated value (reactive)
+     */
+    readonly value: number;
+    /**
+     * Current velocity (reactive)
+     */
+    readonly velocity: number;
+    /**
+     * Whether the spring is currently animating
+     */
+    readonly isAnimating: boolean;
+    /**
+     * Set target value to animate toward
+     */
+    set(newTarget: number, hard?: boolean): void;
+    /**
+     * Update spring configuration
+     */
+    updateConfig(newConfig: Partial<SpringConfig>): void;
+    /**
+     * Stop animation and reset to value
+     */
+    reset(value?: number): void;
+    /**
+     * Cleanup - stop animation
+     */
+    destroy(): void;
+};
+/**
+ * Spring animation for object with multiple properties
+ *
+ * @example
+ * ```typescript
+ * const transform = useSpringObject({ x: 0, y: 0, scale: 1 });
+ *
+ * transform.set({ x: 100, y: 50, scale: 1.5 });
+ *
+ * console.log(transform.values); // { x: 0-100, y: 0-50, scale: 1-1.5 } (animated)
+ * ```
+ */
+export declare function useSpringObject<T extends Record<string, number>>(initialValues: T, options?: UseSpringOptions): {
+    /**
+     * Current animated values (reactive)
+     */
+    readonly values: T;
+    /**
+     * Whether any spring is currently animating
+     */
+    readonly isAnimating: boolean;
+    /**
+     * Set target values to animate toward
+     */
+    set(newTargets: Partial<T>, hard?: boolean): void;
+    /**
+     * Update spring configuration for all springs
+     */
+    updateConfig(newConfig: Partial<SpringConfig>): void;
+    /**
+     * Reset all springs to values
+     */
+    reset(values?: Partial<T>): void;
+    /**
+     * Cleanup - stop all animations
+     */
+    destroy(): void;
+};

package/dist/helpers/spring.svelte.js

@@ -0,0 +1,216 @@
+/**
+ * Spring animation composable using Svelte 5 runes
+ * Provides smooth, physics-based animations with $state reactivity
+ * @module spring
+ */
+import { stepSpring, isSpringSettled, springPresets, prefersReducedMotion } from './animations.js';
+/**
+ * Spring animation composable with Svelte 5 $state
+ *
+ * @example
+ * ```typescript
+ * const scale = useSpring({ initialValue: 1, preset: 'wobbly' });
+ *
+ * // Set target value - spring will animate toward it
+ * scale.set(1.5);
+ *
+ * // Use the current value in your template
+ * console.log(scale.value); // Reactive value that updates during animation
+ * ```
+ */
+export function useSpring(options = {}) {
+    const preset = options.preset ? springPresets[options.preset] : springPresets.default;
+    const config = {
+        stiffness: options.stiffness ?? preset.stiffness,
+        damping: options.damping ?? preset.damping,
+        precision: options.precision ?? preset.precision
+    };
+    let state = $state({
+        value: options.initialValue ?? 0,
+        velocity: 0
+    });
+    let target = $state(options.initialValue ?? 0);
+    let animationFrameId = null;
+    let lastTime = null;
+    /**
+     * Animation loop using requestAnimationFrame
+     */
+    function tick(currentTime) {
+        // Initialize lastTime on first frame
+        if (lastTime === null) {
+            lastTime = currentTime;
+            animationFrameId = requestAnimationFrame(tick);
+            return;
+        }
+        // Calculate delta time in seconds
+        const deltaTime = Math.min((currentTime - lastTime) / 1000, 0.1); // Cap at 100ms
+        lastTime = currentTime;
+        // Skip animation if user prefers reduced motion - snap to target
+        if (prefersReducedMotion()) {
+            state.value = target;
+            state.velocity = 0;
+            stopAnimation();
+            return;
+        }
+        // Calculate next spring state
+        const newState = stepSpring(state, target, config, deltaTime);
+        state = newState;
+        // Check if spring has settled
+        if (isSpringSettled(state, target, config.precision)) {
+            // Snap to target and stop
+            state.value = target;
+            state.velocity = 0;
+            stopAnimation();
+        }
+        else {
+            // Continue animation
+            animationFrameId = requestAnimationFrame(tick);
+        }
+    }
+    /**
+     * Start the animation loop
+     */
+    function startAnimation() {
+        if (animationFrameId !== null)
+            return; // Already animating
+        lastTime = null;
+        animationFrameId = requestAnimationFrame(tick);
+    }
+    /**
+     * Stop the animation loop
+     */
+    function stopAnimation() {
+        if (animationFrameId !== null) {
+            cancelAnimationFrame(animationFrameId);
+            animationFrameId = null;
+        }
+        lastTime = null;
+    }
+    return {
+        /**
+         * Current animated value (reactive)
+         */
+        get value() {
+            return state.value;
+        },
+        /**
+         * Current velocity (reactive)
+         */
+        get velocity() {
+            return state.velocity;
+        },
+        /**
+         * Whether the spring is currently animating
+         */
+        get isAnimating() {
+            return animationFrameId !== null;
+        },
+        /**
+         * Set target value to animate toward
+         */
+        set(newTarget, hard = false) {
+            target = newTarget;
+            if (hard || prefersReducedMotion()) {
+                // Hard set - snap immediately without animation
+                state.value = newTarget;
+                state.velocity = 0;
+                stopAnimation();
+            }
+            else {
+                // Soft set - animate toward target
+                startAnimation();
+            }
+        },
+        /**
+         * Update spring configuration
+         */
+        updateConfig(newConfig) {
+            Object.assign(config, newConfig);
+        },
+        /**
+         * Stop animation and reset to value
+         */
+        reset(value = 0) {
+            target = value;
+            state.value = value;
+            state.velocity = 0;
+            stopAnimation();
+        },
+        /**
+         * Cleanup - stop animation
+         */
+        destroy() {
+            stopAnimation();
+        }
+    };
+}
+/**
+ * Spring animation for object with multiple properties
+ *
+ * @example
+ * ```typescript
+ * const transform = useSpringObject({ x: 0, y: 0, scale: 1 });
+ *
+ * transform.set({ x: 100, y: 50, scale: 1.5 });
+ *
+ * console.log(transform.values); // { x: 0-100, y: 0-50, scale: 1-1.5 } (animated)
+ * ```
+ */
+export function useSpringObject(initialValues, options = {}) {
+    // Create a spring for each property
+    const springs = Object.fromEntries(Object.entries(initialValues).map(([key, value]) => [
+        key,
+        useSpring({ ...options, initialValue: value })
+    ]));
+    return {
+        /**
+         * Current animated values (reactive)
+         */
+        get values() {
+            return Object.fromEntries(Object.entries(springs).map(([key, spring]) => [key, spring.value]));
+        },
+        /**
+         * Whether any spring is currently animating
+         */
+        get isAnimating() {
+            return Object.values(springs).some((spring) => spring.isAnimating);
+        },
+        /**
+         * Set target values to animate toward
+         */
+        set(newTargets, hard = false) {
+            for (const [key, value] of Object.entries(newTargets)) {
+                if (key in springs && typeof value === 'number') {
+                    springs[key].set(value, hard);
+                }
+            }
+        },
+        /**
+         * Update spring configuration for all springs
+         */
+        updateConfig(newConfig) {
+            Object.values(springs).forEach((spring) => spring.updateConfig(newConfig));
+        },
+        /**
+         * Reset all springs to values
+         */
+        reset(values) {
+            if (values) {
+                for (const [key, value] of Object.entries(values)) {
+                    if (key in springs && typeof value === 'number') {
+                        springs[key].reset(value);
+                    }
+                }
+            }
+            else {
+                Object.values(springs).forEach((spring) => spring.reset());
+            }
+        },
+        /**
+         * Cleanup - stop all animations
+         */
+        destroy() {
+            Object.values(springs).forEach((spring) => spring.destroy());
+        }
+    };
+}

package/dist/helpers/subscribable.d.ts

@@ -1,6 +1,5 @@
-/// <reference types="svelte" />
 import type { Writable } from 'svelte/store';
 export declare const subscribable: <T>(subject: Writable<T>) => {
-    subscribe: (this: void, run: import("svelte/store").Subscriber<T>, invalidate?: import("svelte/store").Invalidator<T> | undefined) => import("svelte/store").Unsubscriber;
+    subscribe: (this: void, run: import("svelte/store").Subscriber<T>, invalidate?: () => void) => import("svelte/store").Unsubscriber;
 };
 export type Subscribable<T> = ReturnType<typeof subscribable<T>>;