@qaiddev/thumbs-embed 1.0.9 → 1.0.11

package/dist/console-capture.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Console capture utilities
+ */
+import type { ConsoleError } from "./types";
+export interface ConsoleCapture {
+    errors: ConsoleError[];
+    restore: () => void;
+}
+/**
+ * Wrap console methods to capture messages
+ */
+export declare function captureConsoleErrors(onError?: (error: ConsoleError) => void): ConsoleCapture;
+/**
+ * Add an error to the captured errors array
+ */
+export declare function addError(errors: ConsoleError[], error: ConsoleError): void;
+/**
+ * Format console error for display
+ */
+export declare function formatError(error: ConsoleError): string;

package/dist/dom-utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DOM utility functions
+ */
+/**
+ * Create an element with attributes and optional children
+ */
+export declare function createElement<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string>, children?: (Node | string)[]): HTMLElementTagNameMap[K];
+/**
+ * Check if viewport width indicates mobile device
+ */
+export declare function isMobileViewport(breakpoint?: number): boolean;
+/**
+ * Get element at point, temporarily hiding shadow hosts so elementFromPoint
+ * sees through to the page elements underneath.
+ * Uses visibility:hidden which skips the element in elementFromPoint without
+ * triggering reflow.
+ */
+export declare function getElementAtPointUnderOverlay(x: number, y: number, hosts: HTMLElement[]): Element | null;
+/**
+ * Check if an element is part of the feedback embed
+ * With shadow DOM, embed elements are inside shadow hosts marked with
+ * data-qaid-embed or data-qaid-embed-overlay
+ */
+export declare function isEmbedElement(element: Element | null): boolean;
+/**
+ * Get element bounds with optional padding
+ */
+export declare function getElementBounds(element: Element, padding?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Remove all elements with a specific class
+ */
+export declare function removeAllByClass(className: string): void;

package/dist/element-selector.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Element selector generation utilities
+ */
+/** Data attributes to look for (in priority order) */
+export declare const DATA_ATTRS: string[];
+export interface ElementInfo {
+    selector: string;
+    text: string;
+    dataAttr: string | null;
+}
+/**
+ * Find the first matching data attribute on an element or its ancestors
+ */
+export declare function findDataAttribute(element: Element, stopAt?: Element): string | null;
+/**
+ * Get truncated text content from an element
+ */
+export declare function getTruncatedText(element: Element, maxLength?: number): string;
+/**
+ * Generate an nth-child path from body to the element
+ * This is always a valid CSS selector and uniquely identifies the element
+ * Exported for testing
+ */
+export declare function generateNthChildPath(element: Element): string;
+/**
+ * Generate a selector string for an element
+ * Priority: data attribute > ID > nth-child path
+ */
+export declare function generateSelector(element: Element): string;
+/**
+ * Generate complete element info for feedback
+ */
+export declare function generateElementInfo(element: Element): ElementInfo;

package/dist/embed.d.ts

@@ -0,0 +1,109 @@
+import type { FeedbackConfig } from "./types";
+/**
+ * QaidFeedback - Standalone feedback collection embed
+ */
+export declare class QaidFeedback {
+    private config;
+    private state;
+    private feedbackData;
+    private selectedBounds;
+    private feedbackId;
+    private mousePos;
+    private isMobile;
+    private visitorId;
+    private consoleCapture;
+    private videoRecorder;
+    private networkCapture;
+    private recordedBlob;
+    private recordingIndicator;
+    private videoPreview;
+    private isRecording;
+    private isSendingVideo;
+    private shadowHost;
+    private shadowRoot;
+    private overlayShadowHost;
+    private overlayShadowRoot;
+    private buttonsContainer;
+    private isUserProvidedContainer;
+    private overlayContainer;
+    private captureLayer;
+    private crosshairH;
+    private crosshairV;
+    private scope;
+    private highlightBox;
+    private marker;
+    private modalContainer;
+    private backdrop;
+    private dismissBtn;
+    private cssVars;
+    private boundKeyDown;
+    private boundMouseMove;
+    private boundClick;
+    private boundResize;
+    private destroyed;
+    private domObserver;
+    private boundBeforeSwap;
+    constructor(config: FeedbackConfig);
+    private applyVars;
+    private init;
+    /**
+     * Watch for the shadow hosts being removed from the DOM by framework
+     * client-side navigation (e.g. Astro View Transitions swapping <body>
+     * contents, or any SPA router that replaces DOM subtrees). If the host
+     * is disconnected and destroy() wasn't called, re-append it.
+     *
+     * Also hooks into Astro's `astro:before-swap` when available, which
+     * lets us carry elements into the new document before the swap happens
+     * (avoids a flash of the widget disappearing and reappearing).
+     */
+    private observeDom;
+    private checkMobile;
+    private handleResize;
+    private createEmbed;
+    /**
+     * Lazily create a separate overlay shadow host on document.body.
+     * This host contains all full-page elements (targeting overlay, marker,
+     * backdrop, modal, recording indicator, video preview) so they escape
+     * clip-path / transform containing blocks in user containers.
+     */
+    private ensureOverlayHost;
+    private tooltipElement;
+    private showTooltip;
+    private hideTooltip;
+    private handleDismiss;
+    private handleThumbClick;
+    private submitDirectFeedback;
+    private startTargeting;
+    private createTargetingOverlay;
+    private handleKeyDown;
+    private handleMouseMove;
+    private handleClick;
+    private cancelTargeting;
+    private removeTargetingOverlay;
+    private showSelectedMarker;
+    private hideSelectedMarker;
+    private submitFeedback;
+    private showModal;
+    private showBottomSheet;
+    private showPositionedModal;
+    private getModalContent;
+    private setupModalInteractions;
+    private submitMessage;
+    private closeModal;
+    private startRecording;
+    private stopRecording;
+    private showRecordingIndicator;
+    private updateRecordingTimer;
+    private formatTime;
+    private removeRecordingIndicator;
+    private showRecordingPreview;
+    private cancelRecordingPreview;
+    private removeVideoPreview;
+    private submitVideoFeedback;
+    private cleanupRecording;
+    private setButtonsDisabled;
+    /**
+     * Destroy the embed and clean up all resources
+     */
+    destroy(): void;
+}

package/dist/icons.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SVG icon strings for thumbs up/down buttons
+ */
+export declare const THUMBS_UP_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M14 10h4.764a2 2 0 011.789 2.894l-3.5 7A2 2 0 0115.263 21h-4.017c-.163 0-.326-.02-.485-.06L7 20m7-10V5a2 2 0 00-2-2h-.095c-.5 0-.905.405-.905.905 0 .714-.211 1.412-.608 2.006L7 11v9m7-10h-2M7 20H5a2 2 0 01-2-2v-6a2 2 0 012-2h2.5\"/>\n</svg>";
+export declare const THUMBS_DOWN_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M10 14H5.236a2 2 0 01-1.789-2.894l3.5-7A2 2 0 018.737 3h4.018a2 2 0 01.485.06l3.76.94m-7 10v5a2 2 0 002 2h.095c.5 0 .905-.405.905-.905 0-.714.211-1.412.608-2.006L17 13V4m-7 10h2m5-10h2a2 2 0 012 2v6a2 2 0 01-2 2h-2.5\"/>\n</svg>";
+export declare const RECORD_ICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"qaid-icon\" fill=\"none\" viewBox=\"0 0 24 24\" stroke=\"currentColor\" stroke-width=\"2\">\n  <path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M15.75 10.5l4.72-4.72a.75.75 0 011.28.53v11.38a.75.75 0 01-1.28.53l-4.72-4.72M4.5 18.75h9a2.25 2.25 0 002.25-2.25v-9a2.25 2.25 0 00-2.25-2.25h-9A2.25 2.25 0 002.25 7.5v9a2.25 2.25 0 002.25 2.25z\"/>\n</svg>";

package/dist/index.d.ts

@@ -1,411 +1,38 @@
-/**
- * Capture a screenshot of the current page using html2canvas
- * Returns a base64-encoded WebP data URL, or null on failure
- */
-export declare function captureDomScreenshot(options?: DomScreenshotOptions): Promise<string | null>;
-
-/**
- * Intercept fetch() and XMLHttpRequest to capture network errors (4xx/5xx)
- */
-export declare function captureNetworkErrors(): NetworkCapture;
-
-/**
- * Console message captured during the session
- */
-export declare interface ConsoleError {
-    message: string;
-    timestamp: number;
-    level: "error" | "warn" | "log";
-}
-
-/**
- * Create a video recorder that captures the screen
- */
-export declare function createVideoRecorder(options?: VideoRecorderOptions): VideoRecorder;
-
-/**
- * DOM-based screenshot capture using html2canvas
- * No browser permission dialog required - reconstructs the page from the DOM
- */
-export declare interface DomScreenshotOptions {
-    /** Quality of WebP compression (0-1). Default: 0.8 */
-    quality?: number;
-    /** Max width of the screenshot. Default: 1280 */
-    maxWidth?: number;
-    /** Max height of the screenshot. Default: 800 */
-    maxHeight?: number;
-}
-
-/**
- * Element bounds for server-side screenshot fallback
- */
-declare interface ElementBounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-
-/**
- * Configuration options for the QaidFeedback
- */
-export declare interface FeedbackConfig {
-    /** Required: API endpoint URL for submitting feedback */
-    endpoint: string;
-    /** API key for authenticating with the feedback service */
-    apiKey?: string;
-    /** CSS selector for user-provided container element. If not provided, creates fixed-position container */
-    container?: string;
-    /** Custom CSS class to apply to thumb buttons. When provided, default button styles are not applied */
-    buttonClass?: string;
-    /** Button layout direction. Default: 'horizontal' */
-    direction?: "horizontal" | "vertical";
-    /** Position of the feedback buttons. Default: 'bottom-right'. Ignored if container is provided */
-    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
-    /** Offset from edge in pixels. Default: { x: 16, y: 16 } */
-    offset?: {
-        x?: number;
-        y?: number;
-    };
-    /** z-index for the embed elements. Default: 50 */
-    zIndex?: number;
-    /** When true, skip element targeting and go directly to feedback modal. Default: false */
-    skipTargeting?: boolean;
-    /** Custom colors for feedback types */
-    colors?: {
-        /** Color for positive feedback. Default: rgb(0, 200, 83) */
-        positive?: string;
-        /** Color for negative feedback. Default: rgb(255, 0, 0) */
-        negative?: string;
-        /** Color for selected element marker. Default: #6366f1 */
-        marker?: string;
-    };
-    /** Button size. Default: 'medium' (48px). Small: 36px, Large: 64px */
-    buttonSize?: "small" | "medium" | "large";
-    /** Custom text labels */
-    text?: {
-        /** Tooltip text for buttons */
-        tooltip?: string;
-        /** Modal title */
-        modalTitle?: string;
-        /** Modal subtitle */
-        modalSubtitle?: string;
-        /** Textarea placeholder */
-        placeholder?: string;
-        /** Submit button text */
-        submitButton?: string;
-        /** Skip button text */
-        skipButton?: string;
-    };
-    /** Modal width in pixels. Default: 400 */
-    modalWidth?: number;
-    /** Backdrop opacity (0-1). Default: 0.3 */
-    backdropOpacity?: number;
-    /** Font family for text elements. Default: system-ui, -apple-system, sans-serif */
-    fontFamily?: string;
-    /** Base font size in pixels. Default: 16 */
-    fontSize?: number;
-    /** Enable screenshot capture with feedback. Default: false */
-    captureScreenshot?: boolean;
-    /** Enable video recording button. Default: false */
-    captureVideo?: boolean;
-    /** Video recording options */
-    videoOptions?: {
-        /** Max recording duration in seconds. Default: 15 */
-        maxDuration?: number;
-    };
-    /** Custom SVG string for record button icon */
-    recordIcon?: string;
-    /** When true, buttons are hidden until hovered. Default: false */
-    incognito?: boolean;
-    /** Custom SVG string for positive feedback button icon */
-    positiveIcon?: string;
-    /** Custom SVG string for negative feedback button icon */
-    negativeIcon?: string;
-    /** When true, hide thumbs up/down buttons (only show video button if enabled). Default: false */
-    hideThumbs?: boolean;
-    /** Custom CSS to inject into the embed's shadow root for theming */
-    css?: string;
-    /** Screenshot capture method. "dom" uses html2canvas (no permission), "permission" uses Screen Capture API. Default: "permission" */
-    screenshotMethod?: "dom" | "permission";
-    /** Screenshot options */
-    screenshotOptions?: {
-        /** Quality of WebP compression (0-1). Default: 1.0 */
-        quality?: number;
-        /** Max width of the screenshot. Default: 1280 */
-        maxWidth?: number;
-        /** Max height of the screenshot. Default: 800 */
-        maxHeight?: number;
-    };
-}
-
-/**
- * Current feedback data being collected
- */
-export declare interface FeedbackData {
-    feedbackType: "up" | "down" | null;
-    elementSelector: string | null;
-    elementText: string | null;
-    consoleErrors: ConsoleError[];
-}
-
-/**
- * Payload for updating feedback with a message
- */
-export declare interface FeedbackMessagePayload {
-    message: string | null;
-}
-
-/**
- * Payload sent to the feedback API
- */
-export declare interface FeedbackPayload {
-    feedbackType: "up" | "down";
-    pageUrl: string;
-    /** API key for authenticating with the feedback service */
-    apiKey?: string;
-    elementSelector: string | null;
-    elementText: string | null;
-    consoleErrors: ConsoleError[];
-    screenWidth: number;
-    screenHeight: number;
-    clickX: number;
-    clickY: number;
-    scrollX: number;
-    scrollY: number;
-    /** Base64-encoded screenshot image (WebP) */
-    screenshot: string | null;
-    /** Random UUID stored in visitor's localStorage (for anonymous feedback) */
-    visitorId: string;
-    /** Element bounds for server-side screenshot fallback when client screenshot fails */
-    elementBounds?: ElementBounds | null;
-    /** User agent string for server-side rendering consistency */
-    userAgent?: string;
-}
-
-/**
- * Response from the feedback API
- */
-export declare interface FeedbackResponse {
-    id: number;
-}
-
-/**
- * Detect the best supported MIME type for recording
- */
-export declare function getSupportedMimeType(): string;
-
-/**
- * Check if DOM screenshot capture is supported
- * Requires canvas and basic DOM APIs
- */
-export declare function isDomScreenshotSupported(): boolean;
-
-/**
- * Check if video recording is supported in this browser
- */
-export declare function isVideoRecordingSupported(): boolean;
-
-export declare interface NetworkCapture {
-    errors: NetworkError[];
-    restore: () => void;
-}
-
-/**
- * Network error captured during the session
- */
-export declare interface NetworkError {
-    url: string;
-    method: string;
-    status: number;
-    statusText: string;
-    requestBody?: string;
-    responseBody?: string;
-    timestamp: number;
-}
-
-/**
- * QaidFeedback - Standalone feedback collection embed
- */
-export declare class QaidFeedback {
-    private config;
-    private state;
-    private feedbackData;
-    private selectedBounds;
-    private feedbackId;
-    private mousePos;
-    private isMobile;
-    private visitorId;
-    private consoleCapture;
-    private videoRecorder;
-    private networkCapture;
-    private recordedBlob;
-    private recordingIndicator;
-    private videoPreview;
-    private isRecording;
-    private isSendingVideo;
-    private shadowHost;
-    private shadowRoot;
-    private overlayShadowHost;
-    private overlayShadowRoot;
-    private buttonsContainer;
-    private isUserProvidedContainer;
-    private overlayContainer;
-    private captureLayer;
-    private crosshairH;
-    private crosshairV;
-    private scope;
-    private highlightBox;
-    private marker;
-    private modalContainer;
-    private backdrop;
-    private cssVars;
-    private boundKeyDown;
-    private boundMouseMove;
-    private boundClick;
-    private boundResize;
-    constructor(config: FeedbackConfig);
-    private applyVars;
-    private init;
-    private checkMobile;
-    private handleResize;
-    private createEmbed;
-    /**
-     * Lazily create a separate overlay shadow host on document.body.
-     * This host contains all full-page elements (targeting overlay, marker,
-     * backdrop, modal, recording indicator, video preview) so they escape
-     * clip-path / transform containing blocks in user containers.
-     */
-    private ensureOverlayHost;
-    private tooltipElement;
-    private showTooltip;
-    private hideTooltip;
-    private handleThumbClick;
-    private submitDirectFeedback;
-    private startTargeting;
-    private createTargetingOverlay;
-    private handleKeyDown;
-    private handleMouseMove;
-    private handleClick;
-    private cancelTargeting;
-    private removeTargetingOverlay;
-    private showSelectedMarker;
-    private hideSelectedMarker;
-    private submitFeedback;
-    private showModal;
-    private showBottomSheet;
-    private showPositionedModal;
-    private getModalContent;
-    private setupModalInteractions;
-    private submitMessage;
-    private closeModal;
-    private startRecording;
-    private stopRecording;
-    private showRecordingIndicator;
-    private updateRecordingTimer;
-    private formatTime;
-    private removeRecordingIndicator;
-    private showRecordingPreview;
-    private cancelRecordingPreview;
-    private removeVideoPreview;
-    private submitVideoFeedback;
-    private cleanupRecording;
-    private setButtonsDisabled;
-    /**
-     * Destroy the embed and clean up all resources
-     */
-    destroy(): void;
-}
-
-/**
- * Fully resolved configuration with all defaults applied
- * Used internally by the embed after processing user config
- */
-export declare interface ResolvedFeedbackConfig {
-    endpoint: string;
-    apiKey: string;
-    container: string;
-    buttonClass: string;
-    direction: "horizontal" | "vertical";
-    position: "bottom-right" | "bottom-left" | "top-right" | "top-left";
-    offset: {
-        x: number;
-        y: number;
-    };
-    zIndex: number;
-    skipTargeting: boolean;
-    colors: {
-        positive: string;
-        negative: string;
-        marker: string;
-    };
-    buttonSize: "small" | "medium" | "large";
-    text: {
-        tooltip: string;
-        modalTitle: string;
-        modalSubtitle: string;
-        placeholder: string;
-        submitButton: string;
-        skipButton: string;
-    };
-    modalWidth: number;
-    backdropOpacity: number;
-    fontFamily: string;
-    fontSize: number;
-    captureScreenshot: boolean;
-    screenshotMethod: "dom" | "permission";
-    screenshotOptions: {
-        quality: number;
-        maxWidth: number;
-        maxHeight: number;
-    };
-    incognito: boolean;
-    positiveIcon: string;
-    negativeIcon: string;
-    hideThumbs: boolean;
-    css: string;
-    captureVideo: boolean;
-    videoOptions: {
-        maxDuration: number;
-    };
-    recordIcon: string;
-}
-
-/**
- * Bounds of the selected element
- */
-export declare interface SelectedBounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    clickX: number;
-    clickY: number;
-    visible: boolean;
-}
-
-export declare interface VideoRecorder {
-    /** Start recording. Requests getDisplayMedia if not already started. */
-    start(): Promise<void>;
-    /** Stop recording and return the video blob. */
-    stop(): Promise<Blob>;
-    /** Register a callback for each second tick (receives seconds elapsed). */
-    onTick(callback: (elapsed: number) => void): void;
-    /** Register a callback for when recording stops (e.g., browser stop button, max duration). */
-    onStop(callback: (blob: Blob | null) => void): void;
-    /** Clean up all resources. */
-    destroy(): void;
-}
-
-/**
- * Video capture utilities
- * Uses getDisplayMedia + MediaRecorder for screen recording
- */
-export declare interface VideoRecorderOptions {
-    /** Max recording duration in seconds. Default: 15 */
-    maxDuration?: number;
-    /** Video bitrate in bps. Default: 800000 (800kbps) */
-    videoBitsPerSecond?: number;
-}
-
-export { }
+/**
+ * @qaiddev/thumbs-embed - Standalone Feedback Embed
+ *
+ * A zero-dependency feedback embed with element targeting.
+ *
+ * Usage via ES module:
+ * ```typescript
+ * import { QaidFeedback } from '@qaiddev/thumbs-embed';
+ *
+ * const embed = new QaidFeedback({
+ *   endpoint: '/api/feedback'
+ * });
+ * ```
+ *
+ * Usage via script tag:
+ * ```html
+ * <script src="feedback.umd.cjs" data-endpoint="/api/feedback"></script>
+ * ```
+ *
+ * Or manually initialize:
+ * ```html
+ * <script src="feedback.umd.cjs"></script>
+ * <script>
+ *   const embed = new QaidFeedback.QaidFeedback({
+ *     endpoint: '/api/feedback'
+ *   });
+ * </script>
+ * ```
+ */
+import { QaidFeedback } from "./embed";
+export { QaidFeedback };
+export type { FeedbackConfig, ResolvedFeedbackConfig, ConsoleError, NetworkError, FeedbackData, SelectedBounds, FeedbackPayload, FeedbackResponse, FeedbackMessagePayload, } from "./types";
+export { captureNetworkErrors } from "./network-capture";
+export type { NetworkCapture } from "./network-capture";
+export { createVideoRecorder, isVideoRecordingSupported, getSupportedMimeType } from "./video-capture";
+export type { VideoRecorder, VideoRecorderOptions } from "./video-capture";
+export { captureDomScreenshot, isDomScreenshotSupported } from "./screenshot-dom";
+export type { DomScreenshotOptions } from "./screenshot-dom";