directix 1.4.0 → 1.4.1

package/dist/index.d.ts

@@ -78,6 +78,11 @@ export declare interface ComposableThrottledFunction<T extends (...args: any[])
     cancel: () => void;
 }
 
+/**
+ * Configure permission directive
+ */
+export declare function configurePermission(config: PermissionConfig): void;
+
 /**
  * Countdown complete callback
  */
@@ -485,6 +490,11 @@ export declare function generateId(prefix?: string): string;
  */
 export declare function get<T = any>(obj: Record<string, any>, path: string, defaultValue?: T): T;
 
+/**
+ * Get current configuration
+ */
+export declare function getPermissionConfig(): PermissionConfig | null;
+
 /**
  * Get current Vue version
  */
@@ -599,11 +609,21 @@ export declare function isVue3(): boolean;
  */
 export declare type ItemSizeFunction = (index: number) => number;
 
+/**
+ * Lazy loading state
+ */
+export declare type LazyState = 'pending' | 'loading' | 'loaded' | 'error';
+
 /**
  * Transform text to lowercase
  */
 export declare function lowercaseText(text: string, firstOnly?: boolean): string;
 
+/**
+ * Mutation change handler
+ */
+export declare type MutationHandler = (mutations: MutationRecord[], observer: MutationObserver) => void;
+
 /**
  * Parse formatted money string to number
  */
@@ -632,6 +652,18 @@ export declare function parseTargetTime(target: Date | number | string): number;
  */
 export declare function parseTime(arg?: string): number | null;
 
+/**
+ * Permission configuration
+ */
+declare interface PermissionConfig {
+    /** Get current user's permissions */
+    getPermissions: () => string[];
+    /** Get current user's roles */
+    getRoles?: () => string[];
+    /** Role to permission mapping */
+    roleMap?: Record<string, string[]>;
+}
+
 /**
  * Permission check mode
  */
@@ -800,6 +832,16 @@ export declare function throttleFn<T extends (...args: any[]) => any>(fn: T, wai
     trailing?: boolean;
 }): ComposableThrottledFunction<T>;
 
+/**
+ * Tooltip placement
+ */
+export declare type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+/**
+ * Tooltip trigger
+ */
+export declare type TooltipTrigger = 'hover' | 'click' | 'focus' | 'manual';
+
 /**
  * Touch gesture type
  */
@@ -832,6 +874,11 @@ export declare type TrimPosition = 'start' | 'end' | 'both';
  */
 export declare function trimText(text: string, position?: TrimPosition, chars?: string): string;
 
+/**
+ * Truncate position
+ */
+export declare type TruncatePosition = 'start' | 'middle' | 'end';
+
 /**
  * Utility function to truncate text to a specified length
  *
@@ -1805,6 +1852,91 @@ export declare interface UseImagePreviewReturn {
     bind: (element: HTMLImageElement) => () => void;
 }
 
+/**
+ * Composable for infinite scrolling
+ *
+ * @param options - Configuration options
+ * @returns Infinite scroll utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useInfiniteScroll } from 'directix'
+ *
+ * const items = ref([])
+ * const page = ref(1)
+ *
+ * const { bind, loading, finished } = useInfiniteScroll({
+ *   onLoad: async () => {
+ *     const newItems = await fetchItems(page.value++)
+ *     items.value.push(...newItems)
+ *     if (newItems.length === 0) finished.value = true
+ *   }
+ * })
+ *
+ * onMounted(() => bind(containerRef.value))
+ * </script>
+ *
+ * <template>
+ *   <div ref="containerRef" class="scroll-container">
+ *     <div v-for="item in items" :key="item.id">{{ item.name }}</div>
+ *     <div v-if="loading">Loading...</div>
+ *   </div>
+ * </template>
+ * ```
+ */
+export declare function useInfiniteScroll(options: UseInfiniteScrollOptions): UseInfiniteScrollReturn;
+
+/**
+ * Options for useInfiniteScroll composable
+ */
+export declare interface UseInfiniteScrollOptions {
+    /**
+     * Callback to load more items
+     */
+    onLoad: () => void | Promise<void>;
+    /**
+     * Whether loading is in progress
+     */
+    loading?: boolean | Ref<boolean>;
+    /**
+     * Whether all items are loaded
+     */
+    finished?: boolean | Ref<boolean>;
+    /**
+     * Distance from bottom to trigger load (in pixels)
+     * @default 0
+     */
+    distance?: number | Ref<number>;
+    /**
+     * Whether to check immediately on mount
+     * @default true
+     */
+    immediate?: boolean;
+    /**
+     * Whether to disable
+     * @default false
+     */
+    disabled?: boolean | Ref<boolean>;
+}
+
+/**
+ * Return type for useInfiniteScroll composable
+ */
+export declare interface UseInfiniteScrollReturn {
+    /** Whether loading is in progress */
+    loading: Readonly<Ref<boolean>>;
+    /** Whether all items are loaded */
+    finished: Readonly<Ref<boolean>>;
+    /** Manually trigger load */
+    load: () => Promise<void>;
+    /** Bind infinite scroll to an element */
+    bind: (element: HTMLElement) => () => void;
+    /** Stop observing */
+    stop: () => void;
+}
+
 /**
  * Composable for detecting element intersection with viewport
  *
@@ -1900,6 +2032,186 @@ export declare interface UseIntersectReturn {
     stop: () => void;
 }
 
+/**
+ * Composable for lazy loading images
+ *
+ * @param options - Configuration options
+ * @returns Lazy loading utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useLazy } from 'directix'
+ *
+ * const imageRef = ref(null)
+ * const { state, isLoading, bind } = useLazy({
+ *   src: 'https://example.com/image.jpg',
+ *   placeholder: '/placeholder.jpg'
+ * })
+ *
+ * onMounted(() => bind(imageRef.value))
+ * </script>
+ *
+ * <template>
+ *   <img ref="imageRef" />
+ * </template>
+ * ```
+ */
+export declare function useLazy(options?: UseLazyOptions): UseLazyReturn;
+
+/**
+ * Options for useLazy composable
+ */
+export declare interface UseLazyOptions {
+    /**
+     * Image source URL
+     */
+    src?: string | Ref<string>;
+    /**
+     * Placeholder image URL
+     */
+    placeholder?: string;
+    /**
+     * Error image URL (shown when loading fails)
+     */
+    error?: string;
+    /**
+     * Preload distance in pixels
+     * @default 0
+     */
+    preload?: number;
+    /**
+     * Callback when image loads successfully
+     */
+    onLoad?: (el: HTMLElement) => void;
+    /**
+     * Callback when image fails to load
+     */
+    onError?: (el: HTMLElement, error: Error) => void;
+    /**
+     * Number of retry attempts
+     * @default 1
+     */
+    attempt?: number;
+}
+
+/**
+ * Return type for useLazy composable
+ */
+export declare interface UseLazyReturn {
+    /** Current loading state */
+    state: Readonly<Ref<LazyState>>;
+    /** Whether the image is currently loading */
+    isLoading: Readonly<Ref<boolean>>;
+    /** Whether the image has loaded successfully */
+    isLoaded: Readonly<Ref<boolean>>;
+    /** Whether the image failed to load */
+    hasError: Readonly<Ref<boolean>>;
+    /** Bind lazy loading to an element */
+    bind: (element: HTMLElement) => () => void;
+    /** Manually trigger load */
+    load: () => void;
+    /** Reset state */
+    reset: () => void;
+}
+
+/**
+ * Composable for managing loading state
+ *
+ * @param options - Configuration options
+ * @returns Loading utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useLoading } from 'directix'
+ *
+ * const containerRef = ref(null)
+ * const { loading, start, stop, bind } = useLoading({
+ *   text: 'Loading...',
+ *   lock: true
+ * })
+ *
+ * onMounted(() => bind(containerRef.value))
+ *
+ * async function fetchData() {
+ *   start()
+ *   await api.getData()
+ *   stop()
+ * }
+ * </script>
+ *
+ * <template>
+ *   <div ref="containerRef">
+ *     <button @click="fetchData">Fetch Data</button>
+ *   </div>
+ * </template>
+ * ```
+ */
+export declare function useLoading(options?: UseLoadingOptions): UseLoadingReturn;
+
+/**
+ * Options for useLoading composable
+ */
+export declare interface UseLoadingOptions {
+    /**
+     * Initial loading state
+     * @default false
+     */
+    initial?: boolean | Ref<boolean>;
+    /**
+     * Loading text to display
+     */
+    text?: string | Ref<string>;
+    /**
+     * CSS class for loading overlay
+     * @default 'v-loading'
+     */
+    loadingClass?: string;
+    /**
+     * CSS class for loading spinner
+     * @default 'v-loading__spinner'
+     */
+    spinnerClass?: string;
+    /**
+     * CSS class for loading text
+     * @default 'v-loading__text'
+     */
+    textClass?: string;
+    /**
+     * Custom spinner HTML
+     */
+    spinner?: string;
+    /**
+     * Background color
+     * @default 'rgba(255, 255, 255, 0.9)'
+     */
+    background?: string;
+    /**
+     * Whether to lock scroll while loading
+     * @default false
+     */
+    lock?: boolean;
+}
+
+/**
+ * Return type for useLoading composable
+ */
+export declare interface UseLoadingReturn {
+    /** Current loading state */
+    loading: Ref<boolean>;
+    /** Start loading */
+    start: () => void;
+    /** Stop loading */
+    stop: () => void;
+    /** Toggle loading state */
+    toggle: () => void;
+    /** Bind loading to an element */
+    bind: (element: HTMLElement) => () => void;
+}
+
 /**
  * Composable for detecting long press gestures
  *
@@ -2051,6 +2363,91 @@ export declare interface UseLowercaseReturn {
     original: Ref<string>;
 }
 
+/**
+ * Composable for input masking
+ *
+ * @param options - Configuration options
+ * @returns Mask utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useMask } from 'directix'
+ *
+ * const inputRef = ref(null)
+ * const { bind, getRawValue } = useMask({
+ *   mask: '###-##-####',
+ *   placeholder: '_'
+ * })
+ *
+ * onMounted(() => bind(inputRef.value))
+ * </script>
+ *
+ * <template>
+ *   <input ref="inputRef" type="text" />
+ * </template>
+ * ```
+ */
+export declare function useMask(options: UseMaskOptions): UseMaskReturn;
+
+/**
+ * Options for useMask composable
+ */
+export declare interface UseMaskOptions {
+    /**
+     * Mask pattern: # digit, A letter, N alphanumeric, X any, others as literals
+     */
+    mask: string | Ref<string>;
+    /**
+     * Placeholder character
+     * @default '_'
+     */
+    placeholder?: string;
+    /**
+     * Show mask placeholder on focus
+     * @default true
+     */
+    showPlaceholder?: boolean;
+    /**
+     * Show mask on blur
+     * @default false
+     */
+    showMaskOnBlur?: boolean;
+    /**
+     * Clear incomplete on blur
+     * @default false
+     */
+    clearIncomplete?: boolean;
+    /**
+     * Disable
+     * @default false
+     */
+    disabled?: boolean | Ref<boolean>;
+    /**
+     * Callback when value changes
+     */
+    onChange?: (value: string, rawValue: string) => void;
+    /**
+     * Callback when mask is complete
+     */
+    onComplete?: (value: string) => void;
+}
+
+/**
+ * Return type for useMask composable
+ */
+export declare interface UseMaskReturn {
+    /** Get formatted value */
+    getFormattedValue: (value: string) => string;
+    /** Get raw value (without mask literals) */
+    getRawValue: (value: string) => string;
+    /** Check if mask is complete */
+    isComplete: (value: string) => boolean;
+    /** Bind mask to an input element */
+    bind: (element: HTMLInputElement | HTMLTextAreaElement) => () => void;
+}
+
 /**
  * Composable for formatting numbers as money
  *
@@ -2133,6 +2530,104 @@ export declare interface UseMoneyReturn {
     parse: (formatted: string) => number;
 }
 
+/**
+ * Composable for observing DOM mutations
+ *
+ * @param options - Configuration options
+ * @returns Mutation observer utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useMutation } from 'directix'
+ *
+ * const containerRef = ref(null)
+ * const { bind } = useMutation({
+ *   handler: (mutations) => {
+ *     mutations.forEach(mutation => {
+ *       console.log('Type:', mutation.type)
+ *       console.log('Target:', mutation.target)
+ *     })
+ *   },
+ *   childList: true,
+ *   subtree: true
+ * })
+ *
+ * onMounted(() => bind(containerRef.value))
+ * </script>
+ *
+ * <template>
+ *   <div ref="containerRef">
+ *     Content to observe
+ *   </div>
+ * </template>
+ * ```
+ */
+export declare function useMutation(options: UseMutationOptions): UseMutationReturn;
+
+/**
+ * Options for useMutation composable
+ */
+export declare interface UseMutationOptions {
+    /**
+     * Callback when mutations occur
+     * @required
+     */
+    handler: MutationHandler;
+    /**
+     * Whether to observe attribute changes
+     * @default false
+     */
+    attributes?: boolean;
+    /**
+     * Specific attributes to observe
+     */
+    attributeFilter?: string[];
+    /**
+     * Whether to observe child node additions/removals
+     * @default true
+     */
+    childList?: boolean;
+    /**
+     * Whether to observe all descendants, not just direct children
+     * @default false
+     */
+    subtree?: boolean;
+    /**
+     * Whether to observe character data changes
+     * @default false
+     */
+    characterData?: boolean;
+    /**
+     * Whether to record old attribute values
+     * @default false
+     */
+    attributeOldValue?: boolean;
+    /**
+     * Whether to record old character data
+     * @default false
+     */
+    characterDataOldValue?: boolean;
+    /**
+     * Whether to disable
+     * @default false
+     */
+    disabled?: boolean | Ref<boolean>;
+}
+
+/**
+ * Return type for useMutation composable
+ */
+export declare interface UseMutationReturn {
+    /** Bind mutation observer to an element */
+    bind: (element: HTMLElement) => () => void;
+    /** Stop observing */
+    stop: () => void;
+    /** Start observing */
+    start: () => void;
+}
+
 /**
  * Composable for formatting numbers
  *
@@ -2543,6 +3038,151 @@ export declare interface UseResizeReturn {
     stop: () => void;
 }
 
+/**
+ * Composable for creating ripple effects
+ *
+ * @param options - Configuration options
+ * @returns Ripple utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useRipple } from 'directix'
+ *
+ * const buttonRef = ref(null)
+ * const { bind, trigger } = useRipple({
+ *   color: 'rgba(255, 255, 255, 0.3)',
+ *   duration: 600
+ * })
+ *
+ * onMounted(() => bind(buttonRef.value))
+ * </script>
+ *
+ * <template>
+ *   <button ref="buttonRef">Click for ripple</button>
+ * </template>
+ * ```
+ */
+export declare function useRipple(options?: UseRippleOptions): UseRippleReturn;
+
+/**
+ * Options for useRipple composable
+ */
+export declare interface UseRippleOptions {
+    /**
+     * Ripple color
+     * @default 'currentColor'
+     */
+    color?: string | Ref<string>;
+    /**
+     * Ripple duration in milliseconds
+     * @default 600
+     */
+    duration?: number | Ref<number>;
+    /**
+     * Whether to disable ripple
+     * @default false
+     */
+    disabled?: boolean | Ref<boolean>;
+    /**
+     * Initial scale of ripple
+     * @default 0
+     */
+    initialScale?: number;
+    /**
+     * Final scale of ripple
+     * @default 2
+     */
+    finalScale?: number;
+}
+
+/**
+ * Return type for useRipple composable
+ */
+export declare interface UseRippleReturn {
+    /** Bind ripple effect to an element */
+    bind: (element: HTMLElement) => () => void;
+    /** Trigger ripple effect manually */
+    trigger: (event?: {
+        x?: number;
+        y?: number;
+    }) => void;
+}
+
+/**
+ * Composable for HTML sanitization
+ *
+ * @param options - Configuration options
+ * @returns Sanitization utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useSanitize } from 'directix'
+ *
+ * const { sanitize } = useSanitize({
+ *   allowedTags: ['b', 'i', 'p'],
+ *   allowedAttributes: []
+ * })
+ *
+ * const safeHtml = sanitize(userInput)
+ * </script>
+ * ```
+ */
+export declare function useSanitize(options?: UseSanitizeOptions): UseSanitizeReturn;
+
+/**
+ * Options for useSanitize composable
+ */
+export declare interface UseSanitizeOptions {
+    /**
+     * Tags to allow (whitelist)
+     * @default ['b', 'i', 'u', 'strong', 'em', 'br', 'p', 'span', 'div']
+     */
+    allowedTags?: string[];
+    /**
+     * Attributes to allow (whitelist)
+     * @default ['title', 'alt', 'href', 'src']
+     */
+    allowedAttributes?: string[];
+    /**
+     * Whether to allow data URLs
+     * @default false
+     */
+    allowDataUrls?: boolean;
+    /**
+     * Whether to allow inline styles
+     * @default false
+     */
+    allowStyles?: boolean;
+    /**
+     * Whether to allow class attribute
+     * @default false
+     */
+    allowClass?: boolean;
+    /**
+     * Whether to allow id attribute
+     * @default false
+     */
+    allowId?: boolean;
+    /**
+     * Custom sanitize function
+     */
+    handler?: (html: string) => string;
+}
+
+/**
+ * Return type for useSanitize composable
+ */
+export declare interface UseSanitizeReturn {
+    /** Sanitize HTML string */
+    sanitize: (html: string) => string;
+    /** Sanitize and set to element */
+    bind: (element: HTMLElement) => () => void;
+}
+
 /**
  * Composable for tracking scroll position
  *
@@ -2618,6 +3258,68 @@ export declare interface UseScrollReturn {
     }) => void;
 }
 
+/**
+ * Composable for sticky positioning
+ *
+ * @param options - Configuration options
+ * @returns Sticky utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useSticky } from 'directix'
+ *
+ * const headerRef = ref(null)
+ * const { isSticky, bind } = useSticky({
+ *   offsetTop: 60,
+ *   onStick: (sticky) => console.log('Sticky:', sticky)
+ * })
+ *
+ * onMounted(() => bind(headerRef.value))
+ * </script>
+ *
+ * <template>
+ *   <header ref="headerRef" :class="{ sticky: isSticky }">
+ *     Navigation
+ *   </header>
+ * </template>
+ * ```
+ */
+export declare function useSticky(options?: UseStickyOptions): UseStickyReturn;
+
+/**
+ * Options for useSticky composable
+ */
+export declare interface UseStickyOptions {
+    /**
+     * Offset from top in pixels
+     * @default 0
+     */
+    offsetTop?: number | Ref<number>;
+    /**
+     * Callback when stick state changes
+     */
+    onStick?: (isSticky: boolean) => void;
+    /**
+     * Whether to disable
+     * @default false
+     */
+    disabled?: boolean | Ref<boolean>;
+}
+
+/**
+ * Return type for useSticky composable
+ */
+export declare interface UseStickyReturn {
+    /** Whether the element is sticky */
+    isSticky: Readonly<Ref<boolean>>;
+    /** Bind sticky behavior to an element */
+    bind: (element: HTMLElement) => () => void;
+    /** Stop observing */
+    stop: () => void;
+}
+
 /**
  * Composable for detecting swipe gestures
  *
@@ -2780,6 +3482,102 @@ export declare interface UseThrottleReturn<T extends (...args: any[]) => any> {
     cancel: () => void;
 }
 
+/**
+ * Composable for tooltip functionality
+ *
+ * @param options - Configuration options
+ * @returns Tooltip utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useTooltip } from 'directix'
+ *
+ * const buttonRef = ref(null)
+ * const { isVisible, bind } = useTooltip({
+ *   content: 'Tooltip text',
+ *   placement: 'top'
+ * })
+ *
+ * onMounted(() => bind(buttonRef.value))
+ * </script>
+ *
+ * <template>
+ *   <button ref="buttonRef">Hover me</button>
+ * </template>
+ * ```
+ */
+export declare function useTooltip(options?: UseTooltipOptions): UseTooltipReturn;
+
+/**
+ * Options for useTooltip composable
+ */
+export declare interface UseTooltipOptions {
+    /**
+     * Tooltip content
+     */
+    content?: string | Ref<string>;
+    /**
+     * Tooltip placement
+     * @default 'top'
+     */
+    placement?: TooltipPlacement;
+    /**
+     * Trigger type
+     * @default 'hover'
+     */
+    trigger?: TooltipTrigger;
+    /**
+     * Show delay in milliseconds
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Hide delay in milliseconds
+     * @default 0
+     */
+    hideDelay?: number;
+    /**
+     * Whether to show arrow
+     * @default true
+     */
+    arrow?: boolean;
+    /**
+     * Custom class for tooltip
+     */
+    class?: string;
+    /**
+     * Callback when tooltip shows
+     */
+    onShow?: () => void;
+    /**
+     * Callback when tooltip hides
+     */
+    onHide?: () => void;
+    /**
+     * Whether to disable
+     * @default false
+     */
+    disabled?: boolean | Ref<boolean>;
+}
+
+/**
+ * Return type for useTooltip composable
+ */
+export declare interface UseTooltipReturn {
+    /** Whether the tooltip is visible */
+    isVisible: Readonly<Ref<boolean>>;
+    /** Show the tooltip */
+    show: () => void;
+    /** Hide the tooltip */
+    hide: () => void;
+    /** Toggle the tooltip */
+    toggle: () => void;
+    /** Bind tooltip to an element */
+    bind: (element: HTMLElement) => () => void;
+}
+
 /**
  * Composable for touch gesture detection
  *
@@ -2945,6 +3743,73 @@ export declare interface UseTrimReturn {
     wasTrimmed: Ref<boolean>;
 }
 
+/**
+ * Composable for text truncation
+ *
+ * @param options - Configuration options
+ * @returns Truncation utilities
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { ref } from 'vue'
+ * import { useTruncate } from 'directix'
+ *
+ * const longText = ref('This is a very long text that needs to be truncated')
+ * const { truncated, isTruncated } = useTruncate({
+ *   text: longText,
+ *   length: 20,
+ *   position: 'middle'
+ * })
+ * </script>
+ *
+ * <template>
+ *   <span>{{ truncated }}</span>
+ *   <span v-if="isTruncated" :title="longText">...</span>
+ * </template>
+ * ```
+ */
+export declare function useTruncate(options: UseTruncateOptions): UseTruncateReturn;
+
+/**
+ * Options for useTruncate composable
+ */
+export declare interface UseTruncateOptions {
+    /**
+     * Text to truncate
+     */
+    text: string | Ref<string>;
+    /**
+     * Maximum length
+     * @default 100
+     */
+    length?: number | Ref<number>;
+    /**
+     * Truncation position
+     * @default 'end'
+     */
+    position?: TruncatePosition | Ref<TruncatePosition>;
+    /**
+     * Omission string
+     * @default '...'
+     */
+    omission?: string;
+}
+
+/**
+ * Return type for useTruncate composable
+ */
+export declare interface UseTruncateReturn {
+    /** Truncated text */
+    truncated: Readonly<Ref<string>>;
+    /** Whether the text was truncated */
+    isTruncated: Readonly<Ref<boolean>>;
+    /** Original text length */
+    originalLength: Readonly<Ref<number>>;
+    /** Truncate a custom string */
+    truncate: (text: string, length?: number, position?: TruncatePosition) => string;
+}
+
 /**
  * Composable for transforming text to uppercase
  *