@poupe/vue/dist/composables.d.ts

Vue component library for Poupe UI framework with theme customization and accessibility support

import { App } from 'vue';
import { ComputedRef } from 'vue';
import { IconifyIcon } from '@iconify/vue';
import { InjectionKey } from 'vue';
import { MaybeRefOrGetter } from 'vue';
import { Ref } from 'vue';

/**
 * Creates a Poupe instance for the Vue app
 * Used by `@poupe/nuxt` to inject app-wide defaults
 */
export declare function createPoupe(options?: PoupeOptions): {
    install(app: App): void;
};

declare type IconValue = IconifyIcon | string;

/**
 * Extendable interface for component defaults
 * Components can augment this interface to add their own defaults
 *
 * @example
 * ```typescript
 * declare module '@poupe/vue' {
 *   interface PoupeComponentDefaults {
 *     button?: {
 *       variant?: string
 *       size?: string
 *       ripple?: boolean
 *     }
 *   }
 * }
 * ```
 */
export declare interface PoupeComponentDefaults {
}

export declare const poupeInjectionKey: InjectionKey<PoupeOptions>;

export declare interface PoupeOptions {
    defaults?: PoupeComponentDefaults;
    theme?: {
        dark?: boolean;
        colors?: Record<string, string>;
    };
    accessibility?: {
        reducedMotion?: boolean;
        highContrast?: boolean;
    };
    ripple?: {
        disabled?: boolean;
        color?: string;
        opacity?: number;
        duration?: number;
    };
}

/**
 * Provider for isolated Poupe instances (e.g., in stories)
 */
export declare function providePoupeOptions(options: PoupeOptions): void;

declare interface Ripple {
    x: number;
    y: number;
    size: number;
    id: number;
}

export declare interface RippleOptions {
    /**
     * Ripple color (CSS color value)
     * @defaultValue `'currentColor'`
     */
    color?: string;
    /**
     * Ripple opacity
     * @defaultValue `0.12`
     */
    opacity?: number;
    /**
     * Duration in milliseconds
     * @defaultValue `600`
     */
    duration?: number;
    /**
     * Whether the ripple is bounded by the container
     * @defaultValue `true`
     */
    bounded?: boolean;
    /**
     * Disable ripple effect
     * @defaultValue `false`
     */
    disabled?: MaybeRefOrGetter<boolean>;
}

export declare function usePasswordToggle(origType: MaybeRefOrGetter<string>): {
    showPassword: Ref<boolean, boolean>;
    passwordToggleIcon: ComputedRef<string | {
    readonly body: string;
    readonly left?: number | undefined;
    readonly top?: number | undefined;
    readonly width?: number | undefined;
    readonly height?: number | undefined;
    readonly rotate?: number | undefined;
    readonly hFlip?: boolean | undefined;
    readonly vFlip?: boolean | undefined;
    }>;
    typeAttr: ComputedRef<string>;
};

/**
 * Use Poupe options in components
 * Provides access to global defaults set via app.config.ts
 */
export declare function usePoupe(): PoupeOptions | undefined;

/**
 * Helper to get component defaults with fallback
 */
export declare function usePoupeDefaults<T extends keyof PoupeComponentDefaults>(component: T): PoupeComponentDefaults[T] | undefined;

export declare function usePoupeDefaults<T>(component: string): T | undefined;

export declare const usePoupeIcons: () => {
    readonly icons: {
        readonly [x: string]: {
            readonly [x: string]: string | {
                readonly body: string;
                readonly left?: number | undefined;
                readonly top?: number | undefined;
                readonly width?: number | undefined;
                readonly height?: number | undefined;
                readonly rotate?: number | undefined;
                readonly hFlip?: boolean | undefined;
                readonly vFlip?: boolean | undefined;
            };
        };
        readonly poupe: {
            readonly blankIcon: string | {
                readonly body: string;
                readonly left?: number | undefined;
                readonly top?: number | undefined;
                readonly width?: number | undefined;
                readonly height?: number | undefined;
                readonly rotate?: number | undefined;
                readonly hFlip?: boolean | undefined;
                readonly vFlip?: boolean | undefined;
            };
            readonly unknownIcon: string | {
                readonly body: string;
                readonly left?: number | undefined;
                readonly top?: number | undefined;
                readonly width?: number | undefined;
                readonly height?: number | undefined;
                readonly rotate?: number | undefined;
                readonly hFlip?: boolean | undefined;
                readonly vFlip?: boolean | undefined;
            };
            readonly spinner: string | {
                readonly body: string;
                readonly left?: number | undefined;
                readonly top?: number | undefined;
                readonly width?: number | undefined;
                readonly height?: number | undefined;
                readonly rotate?: number | undefined;
                readonly hFlip?: boolean | undefined;
                readonly vFlip?: boolean | undefined;
            };
            readonly showPassword: string | {
                readonly body: string;
                readonly left?: number | undefined;
                readonly top?: number | undefined;
                readonly width?: number | undefined;
                readonly height?: number | undefined;
                readonly rotate?: number | undefined;
                readonly hFlip?: boolean | undefined;
                readonly vFlip?: boolean | undefined;
            };
            readonly hidePassword: string | {
                readonly body: string;
                readonly left?: number | undefined;
                readonly top?: number | undefined;
                readonly width?: number | undefined;
                readonly height?: number | undefined;
                readonly rotate?: number | undefined;
                readonly hFlip?: boolean | undefined;
                readonly vFlip?: boolean | undefined;
            };
        };
    };
    readonly toIcon: (icon: MaybeRefOrGetter<IconifyIcon | string | undefined>) => IconifyIcon | string;
    readonly registerIcons: (namespace: string, icons: Record<string, IconValue>) => void;
};

/**
 * Helper to create merged props with proper type inference
 * Ensures component defaults are properly typed
 *
 * @example
 * ```typescript
 * const mergedProps = usePoupeMergedProps(props, 'surface', {
 *   variant: 'surface',
 *   color: 'base',
 *   shape: 'none',
 *   // ... other defaults
 * });
 * ```
 */
export declare function usePoupeMergedProps<TProps extends Record<string, unknown>, TDefaults extends Partial<TProps>>(props: TProps, componentName: keyof PoupeComponentDefaults, componentDefaults: TDefaults): TProps & Required<TDefaults>;

/**
 * Helper to merge component props with global defaults
 * Uses defu for deep merging with proper type inference
 *
 * @example
 * ```typescript
 * const finalProps = usePoupeMergeProps(props, 'button', {
 *   variant: 'filled',
 *   size: 'medium',
 * });
 * ```
 */
export declare function usePoupeMergeProps<T extends Record<string, unknown>>(props: T, componentName: keyof PoupeComponentDefaults, componentDefaults?: Partial<T>): T;

export declare function useRipple(elementReference: Ref<HTMLElement | undefined>, options?: RippleOptions): {
    ripples: Ref<{
        x: number;
        y: number;
        size: number;
        id: number;
    }[], Ripple[] | {
        x: number;
        y: number;
        size: number;
        id: number;
    }[]>;
    getRippleStyle: (ripple: Ripple) => {
        position: "absolute";
        left: string;
        top: string;
        width: string;
        height: string;
        transform: string;
        borderRadius: string;
        backgroundColor: string;
        opacity: number;
        pointerEvents: "none";
        animation: string;
    };
};

export { }