@usewayn/widget/src/wayn-floating.d.ts

Client side widget generator for Wayn PoW CAPTCHA.

/**
 * TypeScript declarations for wayn-floating.js
 * Floating widget functionality for Wayn
 */

declare namespace WaynFloating {
  /**
   * Configuration for floating widget positioning
   */
  interface FloatingConfig {
    /** Offset from the trigger element in pixels */
    offset?: number;
    /** Position relative to the trigger element */
    position?: 'top' | 'bottom';
    /** Selector for the Wayn widget to show */
    waynWidgetSelector: string;
  }

  /**
   * Event handler function type
   */
  type EventHandler = (event: Event) => void;

  /**
   * Internal state for managing floating widgets
   */
  interface FloatingState {
    waynWidget: WaynWidget;
    handlers: EventHandler[];
    element: HTMLElement;
  }
}

declare global {
  interface HTMLElement {
    /**
     * Data attribute for floating Wayn widget
     * Specifies the selector for the Wayn widget to display
     */
    'data-wayn-floating'?: string;
    
    /**
     * Data attribute for floating widget offset
     * Specifies the offset in pixels from the trigger element
     */
    'data-wayn-floating-offset'?: string;
    
    /**
     * Data attribute for floating widget position
     * Specifies whether to show above ('top') or below ('bottom') the trigger
     */
    'data-wayn-floating-position'?: 'top' | 'bottom';
    
    /**
     * Data attribute set when Wayn token is available
     * Contains the solved challenge token
     */
    'data-wayn-token'?: string;
    
    /**
     * Data attribute indicating Wayn progress state
     * Set to 'done' when challenge is solved
     */
    'data-wayn-progress'?: 'done' | string;
  }

  interface Window {
    /**
     * Browser API for getting event listeners (Chrome DevTools)
     * Used to preserve existing click handlers when available
     */
    getEventListeners?: (element: Element) => {
      [eventType: string]: Array<{
        listener: EventListener;
        useCapture: boolean;
      }>;
    };
  }
}

/**
 * Floating Wayn Widget Module
 * 
 * This module provides functionality to show Wayn widgets as floating overlays
 * when users interact with elements that have the `data-wayn-floating` attribute.
 * 
 * @example
 * ```html
 * <!-- Hidden Wayn widget -->
 * <wayn-widget id="floating-wayn" data-wayn-api-endpoint="/api/wayn/"></wayn-widget>
 * 
 * <!-- Button that triggers floating widget -->
 * <button 
 *   data-wayn-floating="#floating-wayn"
 *   data-wayn-floating-position="top"
 *   data-wayn-floating-offset="10"
 * >
 *   Submit Form
 * </button>
 * ```
 * 
 * Features:
 * - Automatically intercepts click events on elements with `data-wayn-floating`
 * - Shows the specified Wayn widget as a floating overlay
 * - Preserves and replays original click handlers after challenge is solved
 * - Supports positioning above or below the trigger element
 * - Automatically handles responsive positioning within viewport bounds
 * - Uses MutationObserver to handle dynamically added elements
 */
declare module WaynFloating {
  /**
   * Initialize floating widget functionality for an element or its descendants
   * @param root The root element to initialize (default: document.body)
   */
  function init(root: Element): void;

  /**
   * Set up floating widget functionality for a specific element
   * @param element The element to set up with floating widget
   */
  function setupElement(element: HTMLElement): void;

  /**
   * Handle click event for floating widget trigger
   * @param evt The click event
   * @param element The trigger element
   * @param waynWidget The Wayn widget to show
   * @param handlers Original click handlers to replay after solving
   */
  function handleClick(
    evt: Event,
    element: HTMLElement,
    waynWidget: WaynWidget,
    handlers: WaynFloating.EventHandler[]
  ): void;
}

export = WaynFloating;
export as namespace WaynFloating;