gotcha-feedback 1.1.5 → 1.1.7

package/README.md

@@ -46,10 +46,16 @@ function FeatureCard() {
 - **Bug Flagging** - Let users flag feedback as issues/bugs with a single toggle
 - **User Segmentation** - Analyze feedback by custom user attributes
 - **Edit Support** - Users can update their previous submissions
+- **Programmatic Trigger** - Open/close the widget from code with `useGotchaTrigger`
+- **Follow-up Questions** - Ask a follow-up after low ratings or negative votes
+- **Trigger Conditions** - Show widget after time delay, scroll depth, or visit count
+- **Screenshot Capture** - Users can attach screenshots when reporting bugs
+- **Offline Support** - Submissions queue in localStorage when offline, flush on reconnect
+- **Context Enrichment** - Viewport, timezone, language, and recent JS errors auto-attached
+- **Visibility Control** - Hide widget for N days after submission, reset onePerUser after N days
 - **Customizable** - Themes, sizes, positions
 - **Accessible** - Full keyboard navigation and screen reader support
 - **Animated** - Smooth enter/exit animations with CSS transitions
-- **Lightweight** - ~11KB gzipped
 
 ## Props
 
@@ -86,6 +92,18 @@ function FeatureCard() {
 | `npsHighLabel` | `string` | `'Very likely'` | Label for high end of NPS scale |
 | `enableBugFlag` | `boolean` | `false` | Show "Report an issue" toggle in feedback form |
 | `bugFlagLabel` | `string` | `'Report an issue'` | Custom label for the bug flag toggle |
+| `enableScreenshot` | `boolean` | `false` | Enable screenshot capture when bug flag is toggled (requires `enableBugFlag`) |
+| `onePerUser` | `boolean` | `false` | Show edit mode instead of new form when user has existing response |
+| `cooldownDays` | `number` | - | Allow new submission after N days (requires `onePerUser`) |
+| `hideAfterSubmitDays` | `number` | - | Hide widget for N days after submission (localStorage) |
+| `showAfterSeconds` | `number` | - | Delay showing widget by N seconds |
+| `showAfterScrollPercent` | `number` | - | Show widget after scrolling past N% (0-100) |
+| `showAfterVisits` | `number` | - | Show widget after N page visits (localStorage) |
+| `followUp` | `object` | - | Show follow-up question after low rating or negative vote |
+| `followUp.ratingThreshold` | `number` | - | Ratings at or below this trigger the follow-up |
+| `followUp.onNegativeVote` | `boolean` | - | Trigger follow-up on thumbs down |
+| `followUp.promptText` | `string` | Required | The follow-up question text |
+| `followUp.placeholder` | `string` | `'Tell us more...'` | Placeholder for follow-up textarea |
 | `user` | `object` | - | User metadata for segmentation |
 | `onSubmit` | `function` | - | Callback after submission |
 | `onOpen` | `function` | - | Callback when modal opens |
@@ -180,6 +198,82 @@ Add a "Report an issue" toggle to any feedback form. When toggled on, the submis
 />
 ```
 
+### Screenshot Capture
+
+When bug flagging is enabled, you can also let users capture and attach a screenshot. Tries `html2canvas` first (install as optional peer dep), falls back to the native Screen Capture API.
+
+```tsx
+<Gotcha
+  elementId="checkout"
+  mode="feedback"
+  enableBugFlag
+  enableScreenshot
+/>
+```
+
+### Follow-up Questions
+
+Ask a follow-up question when users give a low rating or negative vote. The follow-up updates the original response.
+
+```tsx
+<Gotcha
+  elementId="feature"
+  mode="feedback"
+  followUp={{
+    ratingThreshold: 2,          // Ratings 1-2 trigger follow-up
+    promptText: "What could we improve?",
+    placeholder: "Tell us more...",
+  }}
+/>
+```
+
+```tsx
+// Follow-up on negative vote
+<Gotcha
+  elementId="article"
+  mode="vote"
+  followUp={{
+    onNegativeVote: true,
+    promptText: "What went wrong?",
+  }}
+/>
+```
+
+### Trigger Conditions
+
+Control when the widget appears based on user engagement. All specified conditions must be met (AND logic).
+
+```tsx
+// Show after 5 seconds on page
+<Gotcha elementId="onboarding" showAfterSeconds={5} />
+
+// Show after scrolling 50%
+<Gotcha elementId="article-end" showAfterScrollPercent={50} />
+
+// Show after 3 visits
+<Gotcha elementId="feature" showAfterVisits={3} />
+
+// Combine: show after 10 seconds AND 3 visits
+<Gotcha elementId="power-user" showAfterSeconds={10} showAfterVisits={3} />
+```
+
+### Visibility Control
+
+Hide the widget for a period after submission, or allow re-submission after a cooldown.
+
+```tsx
+// Hide widget for 7 days after submission
+<Gotcha elementId="nps" hideAfterSubmitDays={7} />
+
+// One response per user, but allow new submission after 30 days
+<Gotcha
+  elementId="quarterly-survey"
+  onePerUser
+  cooldownDays={30}
+  user={{ id: currentUser.id }}
+/>
+```
+
 ### Feedback Field Options
 
 By default, feedback mode shows both a star rating and a text input. Use `showText` and `showRating` to control which fields appear.
@@ -279,6 +373,29 @@ Pass any attributes relevant to your use case. Supported value types: `string`,
 
 ## Hooks
 
+### useGotchaTrigger
+
+Open or close a specific widget programmatically. The corresponding `<Gotcha>` component must be mounted.
+
+```tsx
+import { useGotchaTrigger } from 'gotcha-feedback';
+
+function ErrorBoundary({ children }) {
+  const { open } = useGotchaTrigger('error-feedback');
+
+  const handleError = () => {
+    open(); // Opens the feedback modal for "error-feedback"
+  };
+
+  return <ErrorHandler onError={handleError}>{children}</ErrorHandler>;
+}
+
+// The widget must be rendered somewhere in the tree
+<Gotcha elementId="error-feedback" mode="feedback" promptText="What happened?" />
+```
+
+Returns `{ open, close, isOpen }`.
+
 ### useGotcha
 
 Access the Gotcha context for programmatic control:
@@ -287,7 +404,7 @@ Access the Gotcha context for programmatic control:
 import { useGotcha } from 'gotcha-feedback';
 
 function MyComponent() {
-  const { submitFeedback, disabled } = useGotcha();
+  const { submitFeedback, openModal, closeModal } = useGotcha();
 
   const handleCustomSubmit = async () => {
     await submitFeedback({
@@ -302,6 +419,8 @@ function MyComponent() {
 }
 ```
 
+Returns `{ client, disabled, defaultUser, debug, submitFeedback, openModal, closeModal, activeModalId }`.
+
 ## User Metadata & Segmentation
 
 When you pass custom attributes in the `user` prop, Gotcha automatically tracks them and enables segmentation in your dashboard.
@@ -383,12 +502,34 @@ import { GotchaScore } from 'gotcha-feedback';
 | `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Color theme |
 | `refreshInterval` | `number` | - | Auto-refresh interval in ms |
 
+## Offline Support
+
+Submissions are automatically queued in localStorage when the user is offline. When connectivity returns, queued items are flushed automatically. A subtle indicator appears on the widget button when items are queued. No configuration needed — this works out of the box.
+
+## Context Enrichment
+
+Every submission automatically includes enriched context beyond the page URL and user agent:
+
+- **Viewport size** (width x height)
+- **Language** and **timezone**
+- **Screen resolution**
+- **Recent JS errors** (last 10 uncaught errors and unhandled rejections)
+
+This context appears in your dashboard and is included in bug ticket descriptions. No configuration needed.
+
 ## TypeScript
 
 The package includes full TypeScript definitions:
 
 ```tsx
-import type { GotchaProps, GotchaProviderProps, ScoreData } from 'gotcha-feedback';
+import type {
+  GotchaProps,
+  GotchaProviderProps,
+  ScoreData,
+  SubmissionContext,
+  GotchaResponse,
+  GotchaError,
+} from 'gotcha-feedback';
 ```
 
 ## Requirements

package/dist/index.d.mts

@@ -34,6 +34,25 @@ interface GotchaStyles {
     backdrop?: React.CSSProperties;
     spinner?: React.CSSProperties;
 }
+interface SubmissionContext {
+    url?: string;
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    language?: string;
+    timezone?: string;
+    screenResolution?: {
+        width: number;
+        height: number;
+    };
+    recentErrors?: Array<{
+        message: string;
+        source?: string;
+        timestamp: number;
+    }>;
+}
 interface SubmitResponsePayload {
     elementId: string;
     mode: ResponseMode;
@@ -44,15 +63,13 @@ interface SubmitResponsePayload {
     pollOptions?: string[];
     pollSelected?: string[];
     isBug?: boolean;
+    screenshot?: string;
     user?: GotchaUser;
-    context?: {
-        url?: string;
-        userAgent?: string;
-    };
+    context?: SubmissionContext;
 }
 interface GotchaResponse {
     id: string;
-    status: 'created' | 'duplicate' | 'updated';
+    status: 'created' | 'duplicate' | 'updated' | 'queued';
     createdAt: string;
     results?: PollResults;
 }
@@ -89,6 +106,8 @@ interface ScoreData {
     npsScore: number | null;
 }
 
+declare function getQueueLength(): number;
+
 interface GotchaThemeColors {
     primary: string;
     primaryHover: string;
@@ -277,8 +296,32 @@ interface GotchaProps {
     enableBugFlag?: boolean;
     /** Custom label for the bug flag toggle (default: "Report an issue") */
     bugFlagLabel?: string;
+    /** Enable screenshot capture when bug flag is toggled (requires html2canvas peer dep, falls back to native API) */
+    enableScreenshot?: boolean;
     /** When true and user has already responded, show submitted state and allow review/edit instead of new submission */
     onePerUser?: boolean;
+    /** When onePerUser is true, allow a new submission after this many days. Has no effect without onePerUser. */
+    cooldownDays?: number;
+    /** After submission, hide the widget for this many days (client-side, localStorage).
+     *  Independent of cooldownDays — the widget stays hidden for the full duration even if cooldown expires sooner. */
+    hideAfterSubmitDays?: number;
+    /** Delay showing widget by N seconds after page load */
+    showAfterSeconds?: number;
+    /** Show widget after user scrolls past this percentage (0-100) */
+    showAfterScrollPercent?: number;
+    /** Show widget after user has visited N times (uses localStorage) */
+    showAfterVisits?: number;
+    /** Show a follow-up question after low rating or negative vote */
+    followUp?: {
+        /** Rating threshold (inclusive) — e.g., 2 means ratings 1-2 trigger follow-up */
+        ratingThreshold?: number;
+        /** Also trigger on negative vote */
+        onNegativeVote?: boolean;
+        /** The prompt text shown */
+        promptText: string;
+        /** Placeholder for the follow-up textarea */
+        placeholder?: string;
+    };
     /** Enable entrance animations on the button and modal (default: true) */
     animated?: boolean;
     /** Called after successful submission */
@@ -290,7 +333,7 @@ interface GotchaProps {
     /** Called on error */
     onError?: (error: GotchaError) => void;
 }
-declare function Gotcha({ elementId, user, mode, showText, showRating, voteLabels, options, allowMultiple, npsQuestion, npsFollowUp, npsFollowUpPlaceholder, npsLowLabel, npsHighLabel, enableBugFlag, bugFlagLabel, onePerUser, animated, position, size, theme, customStyles, visible, showOnHover, touchBehavior, promptText, placeholder, submitText, thankYouMessage, onSubmit, onOpen, onClose, onError, }: GotchaProps): react_jsx_runtime.JSX.Element | null;
+declare function Gotcha({ elementId, user, mode, showText, showRating, voteLabels, options, allowMultiple, npsQuestion, npsFollowUp, npsFollowUpPlaceholder, npsLowLabel, npsHighLabel, enableBugFlag, bugFlagLabel, enableScreenshot, onePerUser, cooldownDays, hideAfterSubmitDays, showAfterSeconds, showAfterScrollPercent, showAfterVisits, followUp, animated, position, size, theme, customStyles, visible, showOnHover, touchBehavior, promptText, placeholder, submitText, thankYouMessage, onSubmit, onOpen, onClose, onError, }: GotchaProps): react_jsx_runtime.JSX.Element | null;
 
 type ScoreVariant = 'stars' | 'number' | 'compact' | 'votes';
 interface GotchaScoreProps {
@@ -325,6 +368,8 @@ declare function useGotcha(): {
             ticketId: string;
             status: string;
         }>;
+        flushQueue(): Promise<void>;
+        getQueueLength: typeof getQueueLength;
         getBaseUrl(): string;
     };
     /** Whether Gotcha is globally disabled */
@@ -335,6 +380,22 @@ declare function useGotcha(): {
     debug: boolean;
     /** Submit feedback programmatically */
     submitFeedback: (payload: Omit<SubmitResponsePayload, "context">) => Promise<GotchaResponse>;
+    /** Open a specific Gotcha modal by elementId */
+    openModal: (elementId: string) => void;
+    /** Close the currently open modal */
+    closeModal: () => void;
+    /** The currently open modal's elementId, or null */
+    activeModalId: string | null;
+};
+
+/**
+ * Hook to programmatically open/close a specific Gotcha widget.
+ * The corresponding <Gotcha elementId="..."> must be mounted for the modal to render.
+ */
+declare function useGotchaTrigger(elementId: string): {
+    open: () => void;
+    close: () => void;
+    isOpen: boolean;
 };
 
-export { Gotcha, type GotchaError, type GotchaProps, GotchaProvider, type GotchaProviderProps, type GotchaResponse, GotchaScore, type GotchaScoreProps, type GotchaStyles, type GotchaThemeConfig, type GotchaUser, type Position, type ResponseMode, type ScoreData, type Size, type Theme, type TouchBehavior, type VoteType, createTheme, useGotcha };
+export { Gotcha, type GotchaError, type GotchaProps, GotchaProvider, type GotchaProviderProps, type GotchaResponse, GotchaScore, type GotchaScoreProps, type GotchaStyles, type GotchaThemeConfig, type GotchaUser, type Position, type ResponseMode, type ScoreData, type Size, type SubmissionContext, type Theme, type TouchBehavior, type VoteType, createTheme, useGotcha, useGotchaTrigger };

package/dist/index.d.ts

@@ -34,6 +34,25 @@ interface GotchaStyles {
     backdrop?: React.CSSProperties;
     spinner?: React.CSSProperties;
 }
+interface SubmissionContext {
+    url?: string;
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    language?: string;
+    timezone?: string;
+    screenResolution?: {
+        width: number;
+        height: number;
+    };
+    recentErrors?: Array<{
+        message: string;
+        source?: string;
+        timestamp: number;
+    }>;
+}
 interface SubmitResponsePayload {
     elementId: string;
     mode: ResponseMode;
@@ -44,15 +63,13 @@ interface SubmitResponsePayload {
     pollOptions?: string[];
     pollSelected?: string[];
     isBug?: boolean;
+    screenshot?: string;
     user?: GotchaUser;
-    context?: {
-        url?: string;
-        userAgent?: string;
-    };
+    context?: SubmissionContext;
 }
 interface GotchaResponse {
     id: string;
-    status: 'created' | 'duplicate' | 'updated';
+    status: 'created' | 'duplicate' | 'updated' | 'queued';
     createdAt: string;
     results?: PollResults;
 }
@@ -89,6 +106,8 @@ interface ScoreData {
     npsScore: number | null;
 }
 
+declare function getQueueLength(): number;
+
 interface GotchaThemeColors {
     primary: string;
     primaryHover: string;
@@ -277,8 +296,32 @@ interface GotchaProps {
     enableBugFlag?: boolean;
     /** Custom label for the bug flag toggle (default: "Report an issue") */
     bugFlagLabel?: string;
+    /** Enable screenshot capture when bug flag is toggled (requires html2canvas peer dep, falls back to native API) */
+    enableScreenshot?: boolean;
     /** When true and user has already responded, show submitted state and allow review/edit instead of new submission */
     onePerUser?: boolean;
+    /** When onePerUser is true, allow a new submission after this many days. Has no effect without onePerUser. */
+    cooldownDays?: number;
+    /** After submission, hide the widget for this many days (client-side, localStorage).
+     *  Independent of cooldownDays — the widget stays hidden for the full duration even if cooldown expires sooner. */
+    hideAfterSubmitDays?: number;
+    /** Delay showing widget by N seconds after page load */
+    showAfterSeconds?: number;
+    /** Show widget after user scrolls past this percentage (0-100) */
+    showAfterScrollPercent?: number;
+    /** Show widget after user has visited N times (uses localStorage) */
+    showAfterVisits?: number;
+    /** Show a follow-up question after low rating or negative vote */
+    followUp?: {
+        /** Rating threshold (inclusive) — e.g., 2 means ratings 1-2 trigger follow-up */
+        ratingThreshold?: number;
+        /** Also trigger on negative vote */
+        onNegativeVote?: boolean;
+        /** The prompt text shown */
+        promptText: string;
+        /** Placeholder for the follow-up textarea */
+        placeholder?: string;
+    };
     /** Enable entrance animations on the button and modal (default: true) */
     animated?: boolean;
     /** Called after successful submission */
@@ -290,7 +333,7 @@ interface GotchaProps {
     /** Called on error */
     onError?: (error: GotchaError) => void;
 }
-declare function Gotcha({ elementId, user, mode, showText, showRating, voteLabels, options, allowMultiple, npsQuestion, npsFollowUp, npsFollowUpPlaceholder, npsLowLabel, npsHighLabel, enableBugFlag, bugFlagLabel, onePerUser, animated, position, size, theme, customStyles, visible, showOnHover, touchBehavior, promptText, placeholder, submitText, thankYouMessage, onSubmit, onOpen, onClose, onError, }: GotchaProps): react_jsx_runtime.JSX.Element | null;
+declare function Gotcha({ elementId, user, mode, showText, showRating, voteLabels, options, allowMultiple, npsQuestion, npsFollowUp, npsFollowUpPlaceholder, npsLowLabel, npsHighLabel, enableBugFlag, bugFlagLabel, enableScreenshot, onePerUser, cooldownDays, hideAfterSubmitDays, showAfterSeconds, showAfterScrollPercent, showAfterVisits, followUp, animated, position, size, theme, customStyles, visible, showOnHover, touchBehavior, promptText, placeholder, submitText, thankYouMessage, onSubmit, onOpen, onClose, onError, }: GotchaProps): react_jsx_runtime.JSX.Element | null;
 
 type ScoreVariant = 'stars' | 'number' | 'compact' | 'votes';
 interface GotchaScoreProps {
@@ -325,6 +368,8 @@ declare function useGotcha(): {
             ticketId: string;
             status: string;
         }>;
+        flushQueue(): Promise<void>;
+        getQueueLength: typeof getQueueLength;
         getBaseUrl(): string;
     };
     /** Whether Gotcha is globally disabled */
@@ -335,6 +380,22 @@ declare function useGotcha(): {
     debug: boolean;
     /** Submit feedback programmatically */
     submitFeedback: (payload: Omit<SubmitResponsePayload, "context">) => Promise<GotchaResponse>;
+    /** Open a specific Gotcha modal by elementId */
+    openModal: (elementId: string) => void;
+    /** Close the currently open modal */
+    closeModal: () => void;
+    /** The currently open modal's elementId, or null */
+    activeModalId: string | null;
+};
+
+/**
+ * Hook to programmatically open/close a specific Gotcha widget.
+ * The corresponding <Gotcha elementId="..."> must be mounted for the modal to render.
+ */
+declare function useGotchaTrigger(elementId: string): {
+    open: () => void;
+    close: () => void;
+    isOpen: boolean;
 };
 
-export { Gotcha, type GotchaError, type GotchaProps, GotchaProvider, type GotchaProviderProps, type GotchaResponse, GotchaScore, type GotchaScoreProps, type GotchaStyles, type GotchaThemeConfig, type GotchaUser, type Position, type ResponseMode, type ScoreData, type Size, type Theme, type TouchBehavior, type VoteType, createTheme, useGotcha };
+export { Gotcha, type GotchaError, type GotchaProps, GotchaProvider, type GotchaProviderProps, type GotchaResponse, GotchaScore, type GotchaScoreProps, type GotchaStyles, type GotchaThemeConfig, type GotchaUser, type Position, type ResponseMode, type ScoreData, type Size, type SubmissionContext, type Theme, type TouchBehavior, type VoteType, createTheme, useGotcha, useGotchaTrigger };