@quvel-kit/core 1.1.0

package/dist/composables/index.js

@@ -0,0 +1,16 @@
+/**
+ * Core Composables
+ *
+ * Vue composables for the Quvel UI framework
+ */
+export { useQuvel, ContainerKey, setClientContainer } from './useQuvel.js';
+export { useWindowEvent } from './useWindowEvent.js';
+export { useClient } from './useClient.js';
+export { useScript } from './useScript.js';
+export { useMetaConfig } from './useMetaConfig.js';
+export { useWebSockets } from './useWebSockets.js';
+export { useScopedService } from './useScopedService.js';
+export { useRecaptcha } from './useRecaptcha.js';
+export { useXsrf } from './useXsrf.js';
+export { useQueryMessageHandler, normalizeKey, mapStatusToType } from './useQueryMessageHandler.js';
+export { useUrlQueryHandler } from './useUrlQueryHandler.js';

package/dist/composables/useClient.d.ts

@@ -0,0 +1,16 @@
+/**
+ * useClient Composable
+ *
+ * Provides client-side detection for SSR-aware components
+ */
+/**
+ * Detects if code is running on the client-side
+ *
+ * Returns a reactive ref that is false during SSR and true after mount on client
+ *
+ * @returns Object containing isClient state
+ */
+export declare function useClient(): {
+    isClient: import("vue").Ref<boolean, boolean>;
+};
+//# sourceMappingURL=useClient.d.ts.map

package/dist/composables/useClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useClient.d.ts","sourceRoot":"","sources":["../../src/composables/useClient.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,wBAAgB,SAAS;;EAgBxB"}

package/dist/composables/useClient.js

@@ -0,0 +1,28 @@
+/**
+ * useClient Composable
+ *
+ * Provides client-side detection for SSR-aware components
+ */
+import { ref, onMounted } from 'vue';
+/**
+ * Detects if code is running on the client-side
+ *
+ * Returns a reactive ref that is false during SSR and true after mount on client
+ *
+ * @returns Object containing isClient state
+ */
+export function useClient() {
+    /**
+     * Flag indicating if the code is running on the client-side
+     */
+    const isClient = ref(false);
+    /**
+     * Sets isClient to true when component is mounted (client-side only)
+     */
+    onMounted(() => {
+        isClient.value = true;
+    });
+    return {
+        isClient,
+    };
+}

package/dist/composables/useMetaConfig.d.ts

@@ -0,0 +1,14 @@
+/**
+ * useMetaConfig Composable
+ *
+ * Configure meta-tags for a page with app-level configuration support
+ */
+/**
+ * Configure meta tags for a page, allowing full customization
+ * Uses app meta configuration when available, falls back to defaults
+ *
+ * @param pageTitle - The page title
+ * @param overrides - Optional overrides to modify metadata
+ */
+export declare function useMetaConfig(pageTitle?: string, overrides?: Partial<unknown>): void;
+//# sourceMappingURL=useMetaConfig.d.ts.map

package/dist/composables/useMetaConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMetaConfig.d.ts","sourceRoot":"","sources":["../../src/composables/useMetaConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAwEpF"}

package/dist/composables/useMetaConfig.js

@@ -0,0 +1,77 @@
+/**
+ * useMetaConfig Composable
+ *
+ * Configure meta-tags for a page with app-level configuration support
+ */
+import { useMeta } from 'quasar';
+import { useQuvel } from './useQuvel.js';
+/**
+ * Configure meta tags for a page, allowing full customization
+ * Uses app meta configuration when available, falls back to defaults
+ *
+ * @param pageTitle - The page title
+ * @param overrides - Optional overrides to modify metadata
+ */
+export function useMetaConfig(pageTitle, overrides) {
+    // Get app meta-configuration from the service container
+    const { config } = useQuvel();
+    const appMeta = config.meta || {};
+    // Use app configuration or fallback to defaults
+    const title = pageTitle ?? appMeta?.title ?? 'A Modern Hybrid App Framework';
+    // Create the title template function from app config or use default
+    const titleTemplate = appMeta?.titleTemplate
+        ? (title) => appMeta.titleTemplate.replace('%s', title)
+        : (title) => `${title} - QuVel Kit`;
+    const description = appMeta?.description ??
+        'QuVel Kit is a Laravel & Quasar hybrid framework optimized for SSR and seamless development.';
+    const keywords = appMeta?.keywords ?? 'Quasar, Laravel, SSR, Hybrid, Framework';
+    const ogTitle = appMeta?.ogTitle ?? pageTitle ?? 'QuVel Kit';
+    const ogDescription = appMeta?.ogDescription ?? 'A powerful Laravel & Quasar SSR framework for building modern apps.';
+    const twitterTitle = appMeta?.twitterTitle ?? pageTitle ?? 'QuVel Kit';
+    const twitterDescription = appMeta?.twitterDescription ?? 'A Laravel & Quasar hybrid framework optimized for SSR.';
+    useMeta({
+        title,
+        titleTemplate,
+        meta: {
+            description: {
+                name: 'description',
+                content: description,
+            },
+            keywords: { name: 'keywords', content: keywords },
+            ogTitle: { property: 'og:title', content: ogTitle },
+            ogDescription: {
+                property: 'og:description',
+                content: ogDescription,
+            },
+            ...(appMeta?.ogImage && {
+                ogImage: { property: 'og:image', content: appMeta.ogImage },
+            }),
+            ogType: { property: 'og:type', content: 'website' },
+            twitterCard: { name: 'twitter:card', content: 'summary_large_image' },
+            twitterTitle: { name: 'twitter:title', content: twitterTitle },
+            twitterDescription: {
+                name: 'twitter:description',
+                content: twitterDescription,
+            },
+            ...(appMeta?.twitterImage && {
+                twitterImage: { name: 'twitter:image', content: appMeta.twitterImage },
+            }),
+        },
+        script: {
+            structuredData: {
+                type: 'application/ld+json',
+                innerHTML: JSON.stringify({
+                    '@context': 'https://schema.org',
+                    '@type': 'WebSite',
+                    name: appMeta?.title ?? 'QuVel Kit',
+                    url: config.frontend?.url ?? 'https://quvelkit.com',
+                    description,
+                }),
+            },
+        },
+        htmlAttr: {
+            lang: 'en',
+        },
+        ...(overrides || {}),
+    });
+}

package/dist/composables/useQueryMessageHandler.d.ts

@@ -0,0 +1,44 @@
+export type MessageHandlerOptions<T> = {
+    /** Query parameter key to check (default: 'message') */
+    key?: string;
+    /** Function to normalize the message value */
+    normalize?: (value: string) => T;
+    /** Function to determine notification type from normalized value */
+    type?: (normalized: string) => 'positive' | 'negative' | 'warning' | 'info';
+    /** i18n translation key prefix */
+    i18nPrefix?: string;
+    /** Notification timeout in ms (default: 8000) */
+    timeout?: number;
+};
+/**
+ * Generic composable to handle query-based messages
+ *
+ * Useful for displaying messages from redirects (e.g., OAuth callbacks, email verification).
+ * Automatically shows a notification if a matching query parameter exists, then removes
+ * the parameter from the URL.
+ *
+ * @example
+ * ```ts
+ * // Handle OAuth callback messages
+ * useQueryMessageHandler({
+ *   key: 'message',
+ *   i18nPrefix: 'auth.messages.',
+ *   type: (msg) => msg.includes('success') ? 'positive' : 'negative'
+ * });
+ * ```
+ */
+export declare function useQueryMessageHandler<T = string>(options?: MessageHandlerOptions<T>): void;
+/**
+ * Normalizes Laravel-style language keys to frontend format
+ *
+ * Backend: `module::key` → Frontend: `module.key`
+ */
+export declare function normalizeKey(key: string, prefix?: string): string;
+/**
+ * Maps status keys to notification types
+ *
+ * Detects patterns like "status.success", "status.errors", etc.
+ * and returns the appropriate Quasar notification type.
+ */
+export declare function mapStatusToType(status: string): 'positive' | 'warning' | 'negative' | 'info';
+//# sourceMappingURL=useQueryMessageHandler.d.ts.map

package/dist/composables/useQueryMessageHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQueryMessageHandler.d.ts","sourceRoot":"","sources":["../../src/composables/useQueryMessageHandler.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;IACrC,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;IACjC,oEAAoE;IACpE,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC5E,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,MAAM,EAAE,OAAO,GAAE,qBAAqB,CAAC,CAAC,CAAM,GAAG,IAAI,CAmC/F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAa5F"}

package/dist/composables/useQueryMessageHandler.js

@@ -0,0 +1,74 @@
+import { onMounted } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { showNotification } from '../utils/notify.js';
+import { useQuvel } from './useQuvel.js';
+/**
+ * Generic composable to handle query-based messages
+ *
+ * Useful for displaying messages from redirects (e.g., OAuth callbacks, email verification).
+ * Automatically shows a notification if a matching query parameter exists, then removes
+ * the parameter from the URL.
+ *
+ * @example
+ * ```ts
+ * // Handle OAuth callback messages
+ * useQueryMessageHandler({
+ *   key: 'message',
+ *   i18nPrefix: 'auth.messages.',
+ *   type: (msg) => msg.includes('success') ? 'positive' : 'negative'
+ * });
+ * ```
+ */
+export function useQueryMessageHandler(options = {}) {
+    const { key = 'message', normalize = normalizeKey, type = mapStatusToType, i18nPrefix = '', timeout = 8000, } = options;
+    const route = useRoute();
+    const router = useRouter();
+    const { i18n } = useQuvel();
+    onMounted(() => {
+        const { [key]: rawMessage, ...rest } = route.query;
+        if (typeof rawMessage !== 'string' || rawMessage.length === 0)
+            return;
+        try {
+            const normalized = normalize(decodeURIComponent(rawMessage));
+            const translationKey = i18nPrefix + normalized;
+            // Only show notification if translation exists
+            if (!i18n.te(translationKey)) {
+                return;
+            }
+            showNotification(type(normalized), i18n.t(translationKey), { timeout });
+            // Remove the message from URL
+            router.replace({ query: rest }).catch(() => { });
+        }
+        catch {
+            // Silently fail on decode/routing errors
+        }
+    });
+}
+/**
+ * Normalizes Laravel-style language keys to frontend format
+ *
+ * Backend: `module::key` → Frontend: `module.key`
+ */
+export function normalizeKey(key, prefix = '') {
+    return key.replace(`${prefix}::`, `${prefix}.`);
+}
+/**
+ * Maps status keys to notification types
+ *
+ * Detects patterns like "status.success", "status.errors", etc.
+ * and returns the appropriate Quasar notification type.
+ */
+export function mapStatusToType(status) {
+    switch (true) {
+        case status.includes('status.success'):
+            return 'positive';
+        case status.includes('status.warnings'):
+            return 'warning';
+        case status.includes('status.errors'):
+            return 'negative';
+        case status.includes('status.info'):
+            return 'info';
+        default:
+            return 'info';
+    }
+}

package/dist/composables/useQuvel.d.ts

@@ -0,0 +1,15 @@
+import type { ServiceContainer } from '../container/ServiceContainer.js';
+/**
+ * Symbol for the Quvel service container key
+ */
+export declare const ContainerKey: unique symbol;
+/**
+ * Assigns a singleton container in the browser
+ */
+export declare function setClientContainer(container: ServiceContainer): void;
+/**
+ * Retrieves the Quvel service container
+ * Uses `ssrContext.$quvel` in SSR, singleton in the client
+ */
+export declare function useQuvel(): ServiceContainer;
+//# sourceMappingURL=useQuvel.d.ts.map

package/dist/composables/useQuvel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQuvel.d.ts","sourceRoot":"","sources":["../../src/composables/useQuvel.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,YAAY,eAAmB,CAAC;AAO7C;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAIpE;AAUD;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,gBAAgB,CAmB3C"}

package/dist/composables/useQuvel.js

@@ -0,0 +1,38 @@
+import { useSSRContext } from 'vue';
+/**
+ * Symbol for the Quvel service container key
+ */
+export const ContainerKey = Symbol('$quvel');
+/**
+ * Holds the singleton service container in the client
+ */
+let clientContainer = null;
+/**
+ * Assigns a singleton container in the browser
+ */
+export function setClientContainer(container) {
+    if (typeof window !== 'undefined') {
+        clientContainer = container;
+    }
+}
+/**
+ * Retrieves the Quvel service container
+ * Uses `ssrContext.$quvel` in SSR, singleton in the client
+ */
+export function useQuvel() {
+    if (typeof window === 'undefined') {
+        const context = useSSRContext();
+        if (context?.$quvel) {
+            return context.$quvel;
+        }
+        else {
+            throw new Error('SSR container not initialized. Ensure ssrContext is set in quvel boot file.');
+        }
+    }
+    else {
+        if (!clientContainer) {
+            throw new Error('Client container not initialized. Ensure quvel boot file ran.');
+        }
+        return clientContainer;
+    }
+}

package/dist/composables/useRecaptcha.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Composable for handling Google reCAPTCHA v3
+ *
+ * @example
+ * ```ts
+ * const { isLoaded, execute } = useRecaptcha();
+ *
+ * // Execute reCAPTCHA for a specific action
+ * const token = await execute('login');
+ * ```
+ */
+export declare function useRecaptcha(): {
+    isLoaded: import("vue").Ref<boolean, boolean>;
+    isLoading: import("vue").Ref<boolean, boolean>;
+    error: import("vue").Ref<Error | null, Error | null>;
+    load: () => Promise<void>;
+    unload: () => void;
+    execute: (action: string) => Promise<string>;
+    recaptchaKey: import("vue").ComputedRef<string>;
+};
+/**
+ * Global window augmentation for Google reCAPTCHA
+ */
+declare global {
+    interface Window {
+        grecaptcha: {
+            ready: (callback: () => void) => void;
+            execute: (siteKey: string, options: {
+                action: string;
+            }) => Promise<string>;
+            reset: () => void;
+        };
+    }
+}
+//# sourceMappingURL=useRecaptcha.d.ts.map

package/dist/composables/useRecaptcha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRecaptcha.d.ts","sourceRoot":"","sources":["../../src/composables/useRecaptcha.ts"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY;;;;;;sBA2CK,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;;EAkCxD;AAED;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,UAAU,EAAE;YACV,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;YACtC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAA;aAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;YAC3E,KAAK,EAAE,MAAM,IAAI,CAAC;SACnB,CAAC;KACH;CACF"}

package/dist/composables/useRecaptcha.js

@@ -0,0 +1,87 @@
+import { computed } from 'vue';
+import { useScript } from './useScript.js';
+import { useQuvel } from './useQuvel.js';
+/**
+ * Script constants
+ */
+const SCRIPT_ID = 'google_recaptcha';
+/**
+ * Composable for handling Google reCAPTCHA v3
+ *
+ * @example
+ * ```ts
+ * const { isLoaded, execute } = useRecaptcha();
+ *
+ * // Execute reCAPTCHA for a specific action
+ * const token = await execute('login');
+ * ```
+ */
+export function useRecaptcha() {
+    const { config } = useQuvel();
+    const recaptchaKey = computed(() => config.recaptchaGoogleSiteKey || '');
+    const recaptchaUrl = computed(() => `https://www.google.com/recaptcha/api.js?render=${recaptchaKey.value}`);
+    const { isLoaded, isLoading, error, load, unload } = useScript(SCRIPT_ID, recaptchaUrl.value, {
+        autoLoad: true,
+        autoUnload: true,
+        onUnload: () => {
+            // Cleanup global grecaptcha reference
+            if ('grecaptcha' in window) {
+                delete window.grecaptcha;
+            }
+            // Remove the badge injected by reCAPTCHA v3
+            const badge = document.querySelector('.grecaptcha-badge');
+            if (badge?.parentNode) {
+                badge.parentNode.removeChild(badge);
+            }
+            // Remove any iframes injected by Google
+            document.querySelectorAll('iframe[src*="recaptcha"]').forEach((iframe) => {
+                iframe.remove();
+            });
+            // Remove any scripts injected by Google
+            document.querySelectorAll('script[src*="recaptcha"]').forEach((script) => {
+                script.remove();
+            });
+            // Remove origin-trial meta tags
+            document.querySelectorAll('meta[http-equiv="origin-trial"]').forEach((meta) => {
+                meta.remove();
+            });
+        },
+    });
+    /**
+     * Executes a reCAPTCHA action and returns a token
+     *
+     * @param action - The action name for this reCAPTCHA execution
+     * @returns Promise that resolves to the reCAPTCHA token
+     */
+    async function execute(action) {
+        if (!isLoaded.value) {
+            await load();
+        }
+        if (!window.grecaptcha) {
+            throw new Error('reCAPTCHA not available on window');
+        }
+        const siteKey = recaptchaKey.value;
+        if (!siteKey) {
+            throw new Error('reCAPTCHA site key not configured');
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                window.grecaptcha.ready(() => {
+                    window.grecaptcha.execute(siteKey, { action }).then(resolve).catch(reject);
+                });
+            }
+            catch (err) {
+                reject(err instanceof Error ? err : new Error('Failed to execute reCAPTCHA'));
+            }
+        });
+    }
+    return {
+        isLoaded,
+        isLoading,
+        error,
+        load,
+        unload,
+        execute,
+        recaptchaKey,
+    };
+}

package/dist/composables/useScopedService.d.ts

@@ -0,0 +1,18 @@
+/**
+ * useScopedService Composable
+ *
+ * Provides a component-scoped service instance
+ * The service is created if missing and cleaned up on component unmounted
+ */
+import type { ServiceClass } from '../container/types.js';
+import type { Service } from '../services/Service.js';
+/**
+ * Provides a component-scoped service instance
+ *
+ * Creates a service instance and is automatically cleaned up when the component unmounts
+ *
+ * @param ServiceClass - Service class constructor
+ * @returns Service instance
+ */
+export declare function useScopedService<T extends Service>(ServiceClass: ServiceClass<T>): T;
+//# sourceMappingURL=useScopedService.d.ts.map

package/dist/composables/useScopedService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScopedService.d.ts","sourceRoot":"","sources":["../../src/composables/useScopedService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAGtD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,OAAO,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAWpF"}

package/dist/composables/useScopedService.js

@@ -0,0 +1,25 @@
+/**
+ * useScopedService Composable
+ *
+ * Provides a component-scoped service instance
+ * The service is created if missing and cleaned up on component unmounted
+ */
+import { onBeforeUnmount } from 'vue';
+import { useQuvel } from './useQuvel.js';
+/**
+ * Provides a component-scoped service instance
+ *
+ * Creates a service instance and is automatically cleaned up when the component unmounts
+ *
+ * @param ServiceClass - Service class constructor
+ * @returns Service instance
+ */
+export function useScopedService(ServiceClass) {
+    const container = useQuvel();
+    const service = container.get(ServiceClass);
+    const name = service.constructor.name;
+    onBeforeUnmount(() => {
+        container.removeService(name);
+    });
+    return service;
+}

package/dist/composables/useScript.d.ts

@@ -0,0 +1,25 @@
+/**
+ * useScript Composable
+ *
+ * Composable for dynamically loading external scripts.
+ * Provides a clean interface for loading, unloading, and managing external scripts
+ * in Vue components. Handles script lifecycle, loading states, and error handling.
+ */
+import type { ScriptOptions } from '../types/scripts.types.js';
+/**
+ * Dynamically loads and manages an external script
+ *
+ * @param scriptId - Unique identifier for the script element
+ * @param scriptUrl - URL of the script to load
+ * @param options - Configuration options for script loading behavior
+ * @returns Object containing script state and methods
+ */
+export declare function useScript(scriptId: string, scriptUrl: string, options?: ScriptOptions): {
+    isLoaded: import("vue").Ref<boolean, boolean>;
+    isLoading: import("vue").Ref<boolean, boolean>;
+    error: import("vue").Ref<Error | null, Error | null>;
+    load: () => Promise<void>;
+    unload: () => void;
+    reload: () => Promise<void>;
+};
+//# sourceMappingURL=useScript.d.ts.map

package/dist/composables/useScript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScript.d.ts","sourceRoot":"","sources":["../../src/composables/useScript.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB;;;;gBAUvE,OAAO,CAAC,IAAI,CAAC;kBAkDX,IAAI;kBAiBE,OAAO,CAAC,IAAI,CAAC;EAyBvC"}

package/dist/composables/useScript.js

@@ -0,0 +1,106 @@
+/**
+ * useScript Composable
+ *
+ * Composable for dynamically loading external scripts.
+ * Provides a clean interface for loading, unloading, and managing external scripts
+ * in Vue components. Handles script lifecycle, loading states, and error handling.
+ */
+import { ref, onBeforeUnmount } from 'vue';
+import { loadScript, unloadScript } from '../utils/scripts.js';
+/**
+ * Dynamically loads and manages an external script
+ *
+ * @param scriptId - Unique identifier for the script element
+ * @param scriptUrl - URL of the script to load
+ * @param options - Configuration options for script loading behavior
+ * @returns Object containing script state and methods
+ */
+export function useScript(scriptId, scriptUrl, options = {}) {
+    const isLoaded = ref(false);
+    const isLoading = ref(false);
+    const error = ref(null);
+    /**
+     * Loads the script if not already loaded
+     *
+     * @returns Promise resolving when script is loaded
+     */
+    function load() {
+        return new Promise((resolve, reject) => {
+            if (isLoaded.value) {
+                resolve();
+                return;
+            }
+            if (isLoading.value) {
+                const checkInterval = setInterval(() => {
+                    if (isLoaded.value) {
+                        clearInterval(checkInterval);
+                        resolve();
+                    }
+                    if (error.value) {
+                        clearInterval(checkInterval);
+                        reject(error.value);
+                    }
+                }, 100);
+                return;
+            }
+            isLoading.value = true;
+            try {
+                loadScript(scriptId, scriptUrl, () => {
+                    isLoaded.value = true;
+                    isLoading.value = false;
+                    if (options.onLoad) {
+                        options.onLoad();
+                    }
+                    resolve();
+                });
+            }
+            catch (err) {
+                isLoading.value = false;
+                error.value = err instanceof Error ? err : new Error(`Failed to load script: ${scriptId}`);
+                if (options.onError) {
+                    options.onError(error.value);
+                }
+                reject(error.value);
+            }
+        });
+    }
+    /**
+     * Unloads the script and resets the state
+     */
+    function unload() {
+        unloadScript(scriptId);
+        if (options.onUnload) {
+            options.onUnload();
+        }
+        isLoaded.value = false;
+        isLoading.value = false;
+        error.value = null;
+    }
+    /**
+     * Reloads the script by unloading and loading it again
+     *
+     * @returns Promise resolving when script is reloaded
+     */
+    async function reload() {
+        unload();
+        return load();
+    }
+    // Auto-load if requested
+    if (options.autoLoad) {
+        void load();
+    }
+    // Auto-unload on unmount unless disabled
+    if (options.autoUnload !== false) {
+        onBeforeUnmount(() => {
+            unload();
+        });
+    }
+    return {
+        isLoaded,
+        isLoading,
+        error,
+        load,
+        unload,
+        reload,
+    };
+}