@classic-homes/theme-svelte 0.1.0

package/dist/lib/composables/index.js

@@ -0,0 +1,10 @@
+/**
+ * Composables - Reusable Svelte 5 runes-based state management utilities
+ *
+ * These composables provide common patterns for form handling and async operations,
+ * built with Svelte 5 runes for optimal reactivity.
+ */
+// Form composable with Zod validation
+export { useForm, } from './useForm.svelte.js';
+// Async operation composable
+export { useAsync, runAsync, } from './useAsync.svelte.js';

package/dist/lib/composables/useAsync.svelte.d.ts

@@ -0,0 +1,102 @@
+/**
+ * useAsync - Svelte 5 runes-based async operation state management
+ *
+ * Features:
+ * - Loading state management
+ * - Error handling with toast integration
+ * - Success/error callbacks
+ * - Retry functionality
+ * - Abort/cancel support
+ * - Debounce support
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useAsync } from '@classic-homes/theme-svelte';
+ *
+ *   const fetchUser = useAsync({
+ *     fn: async (userId: string) => {
+ *       const response = await fetch(`/api/users/${userId}`);
+ *       return response.json();
+ *     },
+ *     onSuccess: (user) => console.log('User loaded:', user),
+ *     onError: (error) => console.error('Failed to load user:', error),
+ *   });
+ *
+ *   // Execute the async function
+ *   fetchUser.execute('user-123');
+ * </script>
+ *
+ * {#if fetchUser.isLoading}
+ *   <Spinner />
+ * {:else if fetchUser.error}
+ *   <Alert variant="error">{fetchUser.error.message}</Alert>
+ * {:else if fetchUser.data}
+ *   <UserCard user={fetchUser.data} />
+ * {/if}
+ * ```
+ */
+export interface UseAsyncOptions<TData, TArgs extends unknown[]> {
+    /** The async function to execute */
+    fn: (...args: TArgs) => Promise<TData>;
+    /** Initial data value */
+    initialData?: TData;
+    /** Called when the operation succeeds */
+    onSuccess?: (data: TData) => void;
+    /** Called when the operation fails */
+    onError?: (error: Error) => void;
+    /** Whether to show toast on error (default: true) */
+    showToastOnError?: boolean;
+    /** Custom error message for toast */
+    errorMessage?: string;
+    /** Whether to show toast on success (default: false) */
+    showToastOnSuccess?: boolean;
+    /** Custom success message for toast */
+    successMessage?: string;
+    /** Execute immediately on creation */
+    immediate?: boolean;
+    /** Arguments for immediate execution */
+    immediateArgs?: TArgs;
+    /** Debounce delay in milliseconds */
+    debounceMs?: number;
+}
+export interface UseAsyncReturn<TData, TArgs extends unknown[]> {
+    /** Current data (reactive) */
+    readonly data: TData | undefined;
+    /** Current error (reactive) */
+    readonly error: Error | undefined;
+    /** Whether the operation is in progress (reactive) */
+    readonly isLoading: boolean;
+    /** Whether the operation has been executed at least once (reactive) */
+    readonly isExecuted: boolean;
+    /** Whether the last execution was successful (reactive) */
+    readonly isSuccess: boolean;
+    /** Whether the last execution failed (reactive) */
+    readonly isError: boolean;
+    /** Execute the async function */
+    execute: (...args: TArgs) => Promise<TData | undefined>;
+    /** Reset state to initial values */
+    reset: () => void;
+    /** Retry the last execution with the same arguments */
+    retry: () => Promise<TData | undefined>;
+    /** Set data manually */
+    setData: (data: TData) => void;
+    /** Set error manually */
+    setError: (error: Error) => void;
+    /** Clear error */
+    clearError: () => void;
+}
+/**
+ * Create an async operation handler with Svelte 5 runes
+ */
+export declare function useAsync<TData, TArgs extends unknown[] = []>(options: UseAsyncOptions<TData, TArgs>): UseAsyncReturn<TData, TArgs>;
+/**
+ * Simple wrapper for one-off async operations
+ * Returns a promise that resolves with the result and handles errors via toast
+ */
+export declare function runAsync<T>(fn: () => Promise<T>, options?: {
+    errorMessage?: string;
+    successMessage?: string;
+    showToastOnError?: boolean;
+    showToastOnSuccess?: boolean;
+}): Promise<T | undefined>;

package/dist/lib/composables/useAsync.svelte.js

@@ -0,0 +1,210 @@
+/**
+ * useAsync - Svelte 5 runes-based async operation state management
+ *
+ * Features:
+ * - Loading state management
+ * - Error handling with toast integration
+ * - Success/error callbacks
+ * - Retry functionality
+ * - Abort/cancel support
+ * - Debounce support
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useAsync } from '@classic-homes/theme-svelte';
+ *
+ *   const fetchUser = useAsync({
+ *     fn: async (userId: string) => {
+ *       const response = await fetch(`/api/users/${userId}`);
+ *       return response.json();
+ *     },
+ *     onSuccess: (user) => console.log('User loaded:', user),
+ *     onError: (error) => console.error('Failed to load user:', error),
+ *   });
+ *
+ *   // Execute the async function
+ *   fetchUser.execute('user-123');
+ * </script>
+ *
+ * {#if fetchUser.isLoading}
+ *   <Spinner />
+ * {:else if fetchUser.error}
+ *   <Alert variant="error">{fetchUser.error.message}</Alert>
+ * {:else if fetchUser.data}
+ *   <UserCard user={fetchUser.data} />
+ * {/if}
+ * ```
+ */
+import { toastStore } from '../stores/toast.svelte.js';
+/**
+ * Create an async operation handler with Svelte 5 runes
+ */
+export function useAsync(options) {
+    const { fn, initialData, onSuccess, onError, showToastOnError = true, errorMessage, showToastOnSuccess = false, successMessage, immediate = false, immediateArgs, debounceMs, } = options;
+    // Reactive state using Svelte 5 runes
+    let data = $state(initialData);
+    let error = $state(undefined);
+    let isLoading = $state(false);
+    let isExecuted = $state(false);
+    let lastArgs = $state(undefined);
+    // Derived state
+    const isSuccess = $derived(isExecuted && !error && !isLoading);
+    const isError = $derived(isExecuted && !!error);
+    // Debounce timer
+    let debounceTimer;
+    /**
+     * Execute the async function
+     */
+    async function execute(...args) {
+        // Clear any pending debounce
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+            debounceTimer = undefined;
+        }
+        // If debounce is set, delay execution
+        if (debounceMs && debounceMs > 0) {
+            return new Promise((resolve) => {
+                debounceTimer = setTimeout(async () => {
+                    const result = await executeImmediate(...args);
+                    resolve(result);
+                }, debounceMs);
+            });
+        }
+        return executeImmediate(...args);
+    }
+    /**
+     * Execute immediately without debounce
+     */
+    async function executeImmediate(...args) {
+        lastArgs = args;
+        isLoading = true;
+        error = undefined;
+        isExecuted = true;
+        try {
+            const result = await fn(...args);
+            data = result;
+            if (onSuccess) {
+                onSuccess(result);
+            }
+            if (showToastOnSuccess && successMessage) {
+                toastStore.success(successMessage);
+            }
+            return result;
+        }
+        catch (err) {
+            const normalizedError = err instanceof Error ? err : new Error(String(err));
+            error = normalizedError;
+            if (onError) {
+                onError(normalizedError);
+            }
+            if (showToastOnError) {
+                toastStore.error(errorMessage || normalizedError.message || 'An error occurred');
+            }
+            return undefined;
+        }
+        finally {
+            isLoading = false;
+        }
+    }
+    /**
+     * Retry the last execution with the same arguments
+     */
+    async function retry() {
+        if (!lastArgs) {
+            console.warn('useAsync.retry: No previous execution to retry');
+            return undefined;
+        }
+        return execute(...lastArgs);
+    }
+    /**
+     * Reset state to initial values
+     */
+    function reset() {
+        // Clear any pending debounce
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+            debounceTimer = undefined;
+        }
+        data = initialData;
+        error = undefined;
+        isLoading = false;
+        isExecuted = false;
+        lastArgs = undefined;
+    }
+    /**
+     * Set data manually
+     */
+    function setData(newData) {
+        data = newData;
+        error = undefined;
+        isExecuted = true;
+    }
+    /**
+     * Set error manually
+     */
+    function setError(newError) {
+        error = newError;
+        isExecuted = true;
+    }
+    /**
+     * Clear error
+     */
+    function clearError() {
+        error = undefined;
+    }
+    // Execute immediately if requested
+    if (immediate && immediateArgs) {
+        // Use $effect-like behavior by queueing the execution
+        queueMicrotask(() => {
+            execute(...immediateArgs);
+        });
+    }
+    return {
+        get data() {
+            return data;
+        },
+        get error() {
+            return error;
+        },
+        get isLoading() {
+            return isLoading;
+        },
+        get isExecuted() {
+            return isExecuted;
+        },
+        get isSuccess() {
+            return isSuccess;
+        },
+        get isError() {
+            return isError;
+        },
+        execute,
+        reset,
+        retry,
+        setData,
+        setError,
+        clearError,
+    };
+}
+/**
+ * Simple wrapper for one-off async operations
+ * Returns a promise that resolves with the result and handles errors via toast
+ */
+export async function runAsync(fn, options) {
+    const { errorMessage, successMessage, showToastOnError = true, showToastOnSuccess = false, } = options || {};
+    try {
+        const result = await fn();
+        if (showToastOnSuccess && successMessage) {
+            toastStore.success(successMessage);
+        }
+        return result;
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (showToastOnError) {
+            toastStore.error(errorMessage || error.message || 'An error occurred');
+        }
+        return undefined;
+    }
+}

package/dist/lib/composables/useForm.svelte.d.ts

@@ -0,0 +1,123 @@
+/**
+ * useForm - Svelte 5 runes-based form state management with Zod validation
+ *
+ * Features:
+ * - Type-safe form data with Zod schema inference
+ * - Field-level and form-level validation
+ * - Automatic error handling with toast notifications
+ * - Loading state management
+ * - Support for nested objects and arrays
+ * - Dirty tracking per field
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useForm } from '@classic-homes/theme-svelte';
+ *   import { z } from 'zod';
+ *
+ *   const schema = z.object({
+ *     email: z.string().email(),
+ *     password: z.string().min(8),
+ *   });
+ *
+ *   const form = useForm({
+ *     schema,
+ *     initialValues: { email: '', password: '' },
+ *     onSubmit: async (data) => {
+ *       await loginUser(data);
+ *     },
+ *   });
+ * </script>
+ *
+ * <form onsubmit={form.handleSubmit}>
+ *   <input
+ *     bind:value={form.data.email}
+ *     onblur={() => form.validateField('email')}
+ *   />
+ *   {#if form.errors.email}
+ *     <span class="error">{form.errors.email}</span>
+ *   {/if}
+ * </form>
+ * ```
+ */
+import { z } from 'zod';
+export interface UseFormOptions<T extends z.ZodObject<z.ZodRawShape>> {
+    /** Zod schema for validation */
+    schema: T;
+    /** Initial form values */
+    initialValues: z.infer<T>;
+    /** Called on successful validation and submission */
+    onSubmit: (data: z.infer<T>) => Promise<void> | void;
+    /** Called when validation or submission fails */
+    onError?: (error: Error | z.ZodError) => void;
+    /** Whether to show toast on error (default: true) */
+    showToastOnError?: boolean;
+    /** Whether to reset form after successful submission (default: false) */
+    resetOnSuccess?: boolean;
+    /** Custom error message for toast */
+    errorMessage?: string;
+    /** Custom success message for toast (if set, shows toast on success) */
+    successMessage?: string;
+}
+export interface FieldError {
+    message: string;
+    path: string[];
+}
+export interface FormState<T> {
+    /** Current form data */
+    data: T;
+    /** Field errors keyed by field name (supports nested paths like "address.city") */
+    errors: Record<string, string>;
+    /** Whether the form is currently submitting */
+    isSubmitting: boolean;
+    /** Whether the form has been submitted at least once */
+    isSubmitted: boolean;
+    /** Whether any field has been modified */
+    isDirty: boolean;
+    /** Set of field names that have been modified */
+    dirtyFields: Set<string>;
+    /** Whether the form is currently valid */
+    isValid: boolean;
+}
+export interface UseFormReturn<T extends z.ZodObject<z.ZodRawShape>> {
+    /** Current form data (reactive) */
+    readonly data: z.infer<T>;
+    /** Field errors (reactive) */
+    readonly errors: Record<string, string>;
+    /** Whether form is submitting (reactive) */
+    readonly isSubmitting: boolean;
+    /** Whether form has been submitted (reactive) */
+    readonly isSubmitted: boolean;
+    /** Whether any field is dirty (reactive) */
+    readonly isDirty: boolean;
+    /** Whether form is currently valid (reactive) */
+    readonly isValid: boolean;
+    /** Set a field value */
+    setField: <K extends keyof z.infer<T>>(field: K, value: z.infer<T>[K]) => void;
+    /** Set multiple field values */
+    setFields: (values: Partial<z.infer<T>>) => void;
+    /** Set a nested field value using dot notation */
+    setNestedField: (path: string, value: unknown) => void;
+    /** Validate a single field */
+    validateField: (field: keyof z.infer<T>) => boolean;
+    /** Validate the entire form */
+    validate: () => boolean;
+    /** Handle form submission */
+    handleSubmit: (event?: Event) => Promise<void>;
+    /** Reset form to initial values */
+    reset: () => void;
+    /** Clear all errors */
+    clearErrors: () => void;
+    /** Set a specific error */
+    setError: (field: string, message: string) => void;
+    /** Mark a field as dirty */
+    markDirty: (field: string) => void;
+}
+/**
+ * Create a form handler with Zod validation and Svelte 5 runes
+ */
+export declare function useForm<T extends z.ZodObject<z.ZodRawShape>>(options: UseFormOptions<T>): UseFormReturn<T>;
+/**
+ * Type helper to extract form data type from schema
+ */
+export type InferFormData<T extends z.ZodObject<z.ZodRawShape>> = z.infer<T>;

package/dist/lib/composables/useForm.svelte.js

@@ -0,0 +1,245 @@
+/**
+ * useForm - Svelte 5 runes-based form state management with Zod validation
+ *
+ * Features:
+ * - Type-safe form data with Zod schema inference
+ * - Field-level and form-level validation
+ * - Automatic error handling with toast notifications
+ * - Loading state management
+ * - Support for nested objects and arrays
+ * - Dirty tracking per field
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useForm } from '@classic-homes/theme-svelte';
+ *   import { z } from 'zod';
+ *
+ *   const schema = z.object({
+ *     email: z.string().email(),
+ *     password: z.string().min(8),
+ *   });
+ *
+ *   const form = useForm({
+ *     schema,
+ *     initialValues: { email: '', password: '' },
+ *     onSubmit: async (data) => {
+ *       await loginUser(data);
+ *     },
+ *   });
+ * </script>
+ *
+ * <form onsubmit={form.handleSubmit}>
+ *   <input
+ *     bind:value={form.data.email}
+ *     onblur={() => form.validateField('email')}
+ *   />
+ *   {#if form.errors.email}
+ *     <span class="error">{form.errors.email}</span>
+ *   {/if}
+ * </form>
+ * ```
+ */
+import { toastStore } from '../stores/toast.svelte.js';
+/**
+ * Create a form handler with Zod validation and Svelte 5 runes
+ */
+export function useForm(options) {
+    const { schema, initialValues, onSubmit, onError, showToastOnError = true, resetOnSuccess = false, errorMessage, successMessage, } = options;
+    // Deep clone to avoid reference issues
+    const cloneInitialValues = () => JSON.parse(JSON.stringify(initialValues));
+    // Reactive state using Svelte 5 runes
+    let data = $state(cloneInitialValues());
+    let errors = $state({});
+    let isSubmitting = $state(false);
+    let isSubmitted = $state(false);
+    let dirtyFields = $state(new Set());
+    // Derived state
+    const isDirty = $derived(dirtyFields.size > 0);
+    const isValid = $derived(Object.keys(errors).length === 0);
+    /**
+     * Set nested value in object using dot notation path
+     */
+    function setNestedValue(obj, path, value) {
+        const keys = path.split('.');
+        let current = obj;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i];
+            if (current[key] === undefined || current[key] === null) {
+                current[key] = {};
+            }
+            current = current[key];
+        }
+        current[keys[keys.length - 1]] = value;
+    }
+    /**
+     * Parse Zod errors into field-keyed error map
+     */
+    function parseZodErrors(zodError) {
+        const fieldErrors = {};
+        for (const issue of zodError.issues) {
+            const path = issue.path.join('.');
+            // Only keep the first error for each field
+            if (!fieldErrors[path]) {
+                fieldErrors[path] = issue.message;
+            }
+        }
+        return fieldErrors;
+    }
+    /**
+     * Set a single field value
+     */
+    function setField(field, value) {
+        data[field] = value;
+        markDirty(field);
+    }
+    /**
+     * Set multiple field values
+     */
+    function setFields(values) {
+        for (const [key, value] of Object.entries(values)) {
+            data[key] = value;
+            markDirty(key);
+        }
+    }
+    /**
+     * Set a nested field value using dot notation
+     */
+    function setNestedField(path, value) {
+        setNestedValue(data, path, value);
+        markDirty(path);
+    }
+    /**
+     * Mark a field as dirty
+     */
+    function markDirty(field) {
+        dirtyFields = new Set([...dirtyFields, field]);
+    }
+    /**
+     * Validate a single field against the schema
+     */
+    function validateField(field) {
+        const fieldSchema = schema.shape[field];
+        if (!fieldSchema)
+            return true;
+        const fieldValue = data[field];
+        const result = fieldSchema.safeParse(fieldValue);
+        if (result.success) {
+            // Clear error for this field
+            const newErrors = { ...errors };
+            delete newErrors[field];
+            errors = newErrors;
+            return true;
+        }
+        else {
+            // Set error for this field
+            errors = {
+                ...errors,
+                [field]: result.error.issues[0]?.message || 'Invalid value',
+            };
+            return false;
+        }
+    }
+    /**
+     * Validate the entire form
+     */
+    function validate() {
+        const result = schema.safeParse(data);
+        if (result.success) {
+            errors = {};
+            return true;
+        }
+        else {
+            errors = parseZodErrors(result.error);
+            return false;
+        }
+    }
+    /**
+     * Handle form submission
+     */
+    async function handleSubmit(event) {
+        event?.preventDefault();
+        isSubmitted = true;
+        // Validate all fields
+        if (!validate()) {
+            const errorCount = Object.keys(errors).length;
+            if (showToastOnError) {
+                toastStore.error(errorMessage || `Please fix ${errorCount} validation error${errorCount > 1 ? 's' : ''}`);
+            }
+            return;
+        }
+        isSubmitting = true;
+        try {
+            await onSubmit(data);
+            if (successMessage) {
+                toastStore.success(successMessage);
+            }
+            if (resetOnSuccess) {
+                reset();
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (onError) {
+                onError(err);
+            }
+            if (showToastOnError) {
+                toastStore.error(errorMessage || err.message || 'An error occurred');
+            }
+        }
+        finally {
+            isSubmitting = false;
+        }
+    }
+    /**
+     * Reset form to initial values
+     */
+    function reset() {
+        data = cloneInitialValues();
+        errors = {};
+        isSubmitted = false;
+        dirtyFields = new Set();
+    }
+    /**
+     * Clear all errors
+     */
+    function clearErrors() {
+        errors = {};
+    }
+    /**
+     * Set a specific error manually
+     */
+    function setError(field, message) {
+        errors = { ...errors, [field]: message };
+    }
+    return {
+        get data() {
+            return data;
+        },
+        get errors() {
+            return errors;
+        },
+        get isSubmitting() {
+            return isSubmitting;
+        },
+        get isSubmitted() {
+            return isSubmitted;
+        },
+        get isDirty() {
+            return isDirty;
+        },
+        get isValid() {
+            return isValid;
+        },
+        setField,
+        setFields,
+        setNestedField,
+        validateField,
+        validate,
+        handleSubmit,
+        reset,
+        clearErrors,
+        setError,
+        markDirty,
+    };
+}