gotcha-feedback 1.1.6 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gotcha-feedback",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Developer-first contextual feedback SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",