@kelet-ai/feedback-ui 0.2.4 → 0.3.0

package/README.md

@@ -1,10 +1,22 @@
 # Feedback UI
 
-A headless React component to collect feedback for product and AI features.
+<!-- METADATA
+**Project Type**: React Component and Hooks Library
+**Primary Use Case**: User Feedback Collection. Especially great for learning from interactions with AI systems.
+**Framework**: React 19+, TypeScript, Headless UI
+**Installation**: `npm install @kelet-ai/feedback-ui` or with your preferred package manager. If using shadcn/ui, use `npx shadcn add https://feedback-ui.kelet.ai/r/vote-feedback.json` or with your preferred package manager.
+-->
 
-## Quick Start with shadcn/ui
+> **A headless React component to collect feedback for product and AI features.**
 
-The easiest way to start is by using the shadcn/ui theme for instant, beautiful results:
+Perfect for capturing user reactions to AI-generated content, new features, documentation, and UI components with both
+explicit voting interfaces and implicit behavior tracking.
+
+---
+
+## 🚀 Quick Start
+
+Get beautiful feedback components in 30 seconds with shadcn/ui integration:
 
 ```bash
 npx shadcn add https://feedback-ui.kelet.ai/r/vote-feedback.json
@@ -24,590 +36,388 @@ function App() {
 }
 ```
 
-## Why Feedback UI?
+**Result**: Fully styled thumbs up/down buttons with popover feedback form.
 
-Perfect for collecting user feedback on:
+---
 
-- **Product features** - Get user reactions to new functionality
-- **AI responses** - Improve AI models with user feedback
-- **Documentation** - Learn what content helps users
-- **UI components** - Validate design decisions
+## ✨ Why Feedback UI?
 
-### 3. Automatic Feedback with useFeedbackState
+### **Perfect For**
 
-Capture user behavior implicitly with our intelligent state hook:
+- **🤖 AI Response Feedback** - Improve models with user reactions
+- **🆕 Product Feature Validation** - Get user sentiment on new functionality
+- **📚 Documentation Effectiveness** - Learn what content helps users
+- **🎨 UI/UX Component Testing** - Validate design decisions
 
-```tsx
-import { useFeedbackState } from '@kelet-ai/feedback-ui';
+### **Key Benefits**
 
-function ContentEditor() {
-  // Drop-in useState replacement that tracks changes
-  const [content, setContent] = useFeedbackState(
-    'Start writing...',
-    'content-editor'
-  );
+- **🎯 Headless Architecture** - Complete design control
+- **♿ Accessibility First** - ARIA support, keyboard navigation, focus management
+- **📊 Implicit Tracking** - Capture user behavior without explicit feedback prompts
+- **🔒 TypeScript Native** - Full type safety included
+- **⚡ Zero Dependencies** - Just React, no other deps
+- **🎨 Flexible Styling** - Works with any CSS framework
 
-  return (
-    <textarea
-      value={content}
-      onChange={e => setContent(e.target.value)}
-      placeholder="Edit this content..."
-    />
-  );
-  // 🎯 Automatically sends feedback when user stops editing!
-}
-```
-
-## Three Ways to Use
+---
 
-### 1. Start Fast with shadcn/ui (Recommended)
+## 📋 Installation Methods
 
-Get beautiful, production-ready components instantly. Perfect for most use cases:
+### **Option 1: shadcn/ui (Recommended)**
 
-```tsx
-import { ShadcnVoteFeedback } from '@/components/ui/vote-feedback';
+First [install shadcn/ui](https://ui.shadcn.com/docs/installation) and then:
 
-<ShadcnVoteFeedback
-  identifier="my-feature"
-  onFeedback={handleFeedback}
-  variant="outline"
-/>;
+```bash
+npx shadcn add https://feedback-ui.kelet.ai/r/vote-feedback.json
 ```
 
-### 2. Go Headless for Full Control
-
-When you need complete design control, use the headless components.
+✅ **Best for**: Quick setup with beautiful pre-styled components
 
-First, install the package:
+### **Option 2: NPM Package**
 
-```console
+```bash
 npm install @kelet-ai/feedback-ui
 ```
 
-Then, import the headless components, and style them as you see fit:
+✅ **Best for**: Full control over styling and behavior
 
-```tsx
-import { VoteFeedback } from '@kelet-ai/feedback-ui';
-
-<VoteFeedback.Root onFeedback={handleFeedback}>
-  <VoteFeedback.UpvoteButton className="your-styles">
-    👍 Like
-  </VoteFeedback.UpvoteButton>
-  <VoteFeedback.DownvoteButton className="your-styles">
-    👎 Dislike
-  </VoteFeedback.DownvoteButton>
-  <VoteFeedback.Popover className="your-popover">
-    <VoteFeedback.Textarea placeholder="What could be better?" />
-    <VoteFeedback.SubmitButton>Send</VoteFeedback.SubmitButton>
-  </VoteFeedback.Popover>
-</VoteFeedback.Root>;
-```
-
-## Features
-
-- **Accessible**: Full keyboard navigation and ARIA support
-- **TypeScript**: Complete type safety included
-- **Flexible**: Works with any styling solution
-- **Zero Dependencies**: Just React - no other dependencies
-- **Automatic Feedback**: `useFeedbackState` hook captures implicit user behavior
-
-## API Reference
+---
 
-### VoteFeedback.Root
+## 🎯 Usage Patterns
 
-| Prop             | Type       | Required | Description                                     |
-| ---------------- | ---------- | -------- | ----------------------------------------------- |
-| `identifier`     | `string`   | ✓        | Unique identifier for tracking                  |
-| `onFeedback`     | `function` | ✓        | Callback when feedback is submitted             |
-| `extra_metadata` | `object`   |          | Additional metadata to include                  |
-| `trigger_name`   | `string`   |          | Optional trigger name for categorizing feedback |
+### **Pattern 1: Explicit Feedback (Most Common)**
 
-### Feedback Object
+Users explicitly vote and provide comments:
 
 ```tsx
-{
-    identifier: string;
-    vote: 'upvote' | 'downvote';
-    explanation ? : string;
-    extra_metadata ? : object;
-    source ? : 'IMPLICIT' | 'EXPLICIT';
-    correction ? : string;
-    selection ? : string;
-    trigger_name ? : string; // Optional trigger name for categorizing feedback
-}
-```
-
-## useFeedbackState Hook
-
-The `useFeedbackState` hook is a **drop-in replacement for React's useState** that automatically tracks state changes
-and sends implicit feedback through the Kelet system. Perfect for capturing user behavior without explicit feedback
-prompts.
+import { VoteFeedback } from '@kelet-ai/feedback-ui';
 
-### Key Features
+<VoteFeedback.Root onFeedback={handleFeedback} identifier="ai-response">
+  <VoteFeedback.UpvoteButton>👍 Helpful</VoteFeedback.UpvoteButton>
+  <VoteFeedback.DownvoteButton>👎 Not helpful</VoteFeedback.DownvoteButton>
+  <VoteFeedback.Popover>
+    <VoteFeedback.Textarea placeholder="How can we improve?" />
+    <VoteFeedback.SubmitButton>Send feedback</VoteFeedback.SubmitButton>
+  </VoteFeedback.Popover>
+</VoteFeedback.Root>;
+```
 
-- 🔄 **Drop-in useState replacement** - Same API signature and behavior
-- 🎯 **Automatic diff detection** - Only triggers on actual changes
-- ⏱️ **Smart debouncing** - Prevents feedback spam (default: 1500ms)
-- 📊 **Multiple diff formats** - Git, object, or JSON diff formats
-- 🎭 **Dynamic identifiers** - Can derive identifier from state
-- 🎚️ **Intelligent vote determination** - Automatic upvote/downvote based on change magnitude
-- 🔍 **Custom comparison** - Support for custom equality functions
+### **Pattern 2: Implicit State Tracking**
 
-### Basic Usage
+Capture user behavior automatically by using a drop-in replacement for useState:
 
 ```tsx
 import { useFeedbackState } from '@kelet-ai/feedback-ui';
 
-function MyComponent() {
-  // Drop-in replacement for useState
-  const [count, setCount] = useFeedbackState(0, 'counter-widget');
+function ContentEditor() {
+  // Drop-in useState replacement that tracks changes
+  const [content, setContent] = useFeedbackState(
+    'Start writing...',
+    'content-editor'
+  );
 
   return (
-    <div>
-      <p>Count: {count}</p>
-      <button onClick={() => setCount(count + 1)}>Increment</button>
-    </div>
+    <textarea
+      value={content}
+      onChange={e => setContent(e.target.value)}
+      placeholder="Edit this content..."
+    />
   );
+  // 🎯 Automatically sends feedback when user stops editing!
 }
 ```
 
-### Advanced Usage
+### **Pattern 3: Complex State with Reducer**
+
+For advanced state management with automatic trigger tracking, by using a drop-in replacement for useReducer:
 
 ```tsx
-import { useFeedbackState } from '@kelet-ai/feedback-ui';
+import { useFeedbackReducer } from '@kelet-ai/feedback-ui';
 
-function UserProfile() {
-  const [profile, setProfile] = useFeedbackState(
-    { name: '', email: '', preferences: {} },
-    state => `profile-${state.email}`, // Dynamic identifier
-    {
-      debounceMs: 2000, // Wait 2s before sending feedback
-      diffType: 'object', // Use object diff format
-      metadata: {
-        component: 'UserProfile',
-        version: '1.2.0',
-      },
-      compareWith: (a, b) => {
-        // Custom comparison function
-        return a.name === b.name && a.email === b.email;
-      },
-    }
-  );
+function TodoApp() {
+  const [todos, dispatch] = useFeedbackReducer(todoReducer, [], 'todo-app');
 
   return (
-    <form>
-      <input
-        value={profile.name}
-        onChange={e => setProfile({ ...profile, name: e.target.value })}
-        placeholder="Name"
-      />
-      <input
-        value={profile.email}
-        onChange={e => setProfile({ ...profile, email: e.target.value })}
-        placeholder="Email"
-      />
-    </form>
+    <button onClick={() => dispatch({ type: 'ADD_TODO', text: 'New task' })}>
+      Add Todo
+    </button>
+    // 🎯 Automatically sends feedback with trigger_name: 'ADD_TODO'
   );
 }
 ```
 
-### Trigger Names for State Changes
+---
+
+## 💡 Core Concepts
 
-The `useFeedbackState` hook supports **trigger names** to categorize and track different types of state changes. This
-powerful feature allows you to understand the context and cause of state changes in your feedback data.
+Understanding these fundamental concepts will help you implement feedback collection effectively:
 
-#### Basic Usage with Trigger Names
+### **🔑 Identifiers**
+
+**What**: Unique tracking ID that connects feedback to its context  
+**Purpose**: Links feedback to specific sessions, users, or content pieces  
+**Best Practice**: Use traceable IDs from your logging system (session ID, trace ID, request ID)
 
 ```tsx
-const [content, setContent] = useFeedbackState(
-  'Initial content',
-  'content-editor',
-  {
-    default_trigger_name: 'manual_edit', // Default for all changes
-  }
-);
+// ✅ Good: Traceable identifier
+<VoteFeedback.Root identifier="session-abc123-ai-response-456"/>
 
-// Uses default trigger name
-setContent('User typed this');
+// ✅ Good: Content-based identifier
+<VoteFeedback.Root identifier={`article-${articleId}-section-${sectionId}`}/>
 
-// Override with specific trigger name
-setContent('AI generated this', 'ai_assistance');
-setContent('Spell checker fixed this', 'spell_check');
+// ❌ Poor: Generic identifier
+<VoteFeedback.Root identifier="feedback"/>
 ```
 
-#### Trigger Switching - Advanced Behavior
+### **📊 Feedback Sources**
 
-When you change trigger names, the hook **immediately flushes** the previous sequence and starts a new one:
+Controls how feedback is collected and what data is captured:
 
-```tsx
-const [draft, setDraft] = useFeedbackState('', 'email-draft');
+#### **Explicit Feedback**
 
-setDraft('Hello', 'manual_typing'); // Starts debouncing for 'manual_typing'
-setDraft('Hello world', 'manual_typing'); // Extends debounce (same trigger)
-setDraft('Hello world!', 'ai_suggestion'); // IMMEDIATELY sends 'manual_typing' feedback
-// then starts new 'ai_suggestion' sequence
-```
+- **What**: Users actively vote and provide comments
+- **When to use**: Direct user opinions, satisfaction surveys, feature ratings
+- **Data captured**: Vote (upvote/downvote), comments, metadata
+- **User experience**: Interactive buttons and forms
 
-This creates two separate feedback entries:
+```tsx
+// Explicit feedback - user clicks buttons
+<VoteFeedback.Root onFeedback={handleExplicitFeedback}>
+  <VoteFeedback.UpvoteButton>👍 Helpful</VoteFeedback.UpvoteButton>
+  <VoteFeedback.DownvoteButton>👎 Not helpful</VoteFeedback.DownvoteButton>
+</VoteFeedback.Root>
+```
 
-1. **manual_typing**: `'' → 'Hello world'`
-2. **ai_suggestion**: `'Hello world' → 'Hello world!'`
+#### **Implicit Feedback**
 
-#### Real-world Examples
+- **What**: Automatic behavior tracking without user prompts
+- **When to use**: Content editing, user interactions, workflow analysis
+- **Data captured**: State diffs, interaction patterns, timing data
+- **User experience**: Seamless, no interruption
 
 ```tsx
-// Content creation with different interaction types
-const [article, setArticle] = useFeedbackState(
-  { title: '', content: '', tags: [] },
-  'article-editor',
-  {
-    default_trigger_name: 'user_input',
-    debounceMs: 2000,
-  }
+// Implicit feedback - tracks changes automatically
+const [content, setContent] = useFeedbackState(
+  'Initial content',
+  'content-editor'
 );
+// Sends feedback when user stops editing
+```
 
-// User typing
-setArticle({ ...article, title: 'My Article' }, 'user_input');
+### **🏷️ Trigger Names**
 
-// AI assistance
-setArticle(
-  {
-    ...article,
-    content: 'AI generated introduction...',
-  },
-  'ai_generation'
-);
+Categorization system for grouping and analyzing feedback:
 
-// Grammar correction
-setArticle(
-  {
-    ...article,
-    content: 'AI-generated introduction...',
-  },
-  'grammar_fix'
-);
+#### **Purpose**
 
-// User refinement
-setArticle(
-  {
-    ...article,
-    content: 'AI-generated introduction with my changes...',
-  },
-  'user_refinement'
-);
-```
+- **Group related feedback** for analysis
+- **Track interaction types** (manual vs AI-assisted)
+- **Measure feature adoption** and usage patterns
+- **Debug user experience** issues
 
-#### Common Trigger Name Patterns
+#### **Common Patterns**
 
 ```tsx
-// Content creation and editing
-{
-  default_trigger_name: 'manual_edit';
-}
-'user_typing' | 'copy_paste' | 'drag_drop';
-
-// AI interactions
-'ai_generation' | 'ai_completion' | 'ai_correction';
-'prompt_result' | 'ai_suggestion_accepted';
+// Content creation triggers
+'user_typing' | 'ai_generation' | 'spell_check' | 'auto_format';
 
-// Automated changes
-'spell_check' | 'auto_format' | 'auto_save';
-'validation_fix' | 'import_data';
+// User interaction triggers
+'manual_edit' | 'voice_input' | 'copy_paste' | 'drag_drop';
 
-// User interactions
-'voice_input' | 'gesture_input' | 'shortcut_key';
-'context_menu' | 'toolbar_action';
-
-// Workflow steps
+// Workflow triggers
 'draft' | 'review' | 'approval' | 'publication';
-'undo' | 'redo' | 'revert';
+
+// AI interaction triggers
+'ai_completion' | 'ai_correction' | 'prompt_result';
 ```
 
-#### Advanced Pattern: Context-Aware Triggers
+#### **Dynamic Trigger Names**
 
 ```tsx
-function SmartEditor() {
-  const [document, setDocument] = useFeedbackState(
-    { content: '', metadata: {} },
-    'smart-editor',
-    { default_trigger_name: 'user_edit' }
-  );
+const [document, setDocument] = useFeedbackState(
+  initialDoc,
+  'document-editor',
+  { default_trigger_name: 'user_edit' }
+);
 
-  const handleUserInput = text => {
-    setDocument({ ...document, content: text }, 'user_typing');
-  };
-
-  const handleAIComplete = completion => {
-    setDocument(
-      {
-        ...document,
-        content: document.content + completion,
-      },
-      'ai_completion'
-    );
-  };
-
-  const handleSpellCheck = correctedText => {
-    setDocument(
-      {
-        ...document,
-        content: correctedText,
-      },
-      'spell_check'
-    );
-  };
-
-  const handleImport = importedData => {
-    setDocument(importedData, 'data_import');
-  };
-}
+// Different triggers for different actions
+setDocument(aiGeneratedContent, 'ai_generation');
+setDocument(userEditedContent, 'manual_refinement');
+setDocument(spellCheckedContent, 'spell_check');
 ```
 
-#### Benefits of Trigger Names
+### **🔄 State Change Tracking**
+
+For implicit feedback, understanding how state changes are processed:
+
+#### **Debouncing Logic**
+
+```tsx
+// User types: "Hello" → "Hello World" → "Hello World!"
+// Only sends ONE feedback after user stops typing
+const [text, setText] = useFeedbackState('', 'editor', {
+  debounceMs: 1500, // Wait 1.5s after last change
+});
+```
 
-1. **Categorize Feedback** - Group feedback by interaction type
-2. **Track User Behavior** - Understand how users interact with features
-3. **Measure AI Impact** - See how often AI suggestions are used vs manual input
-4. **Debug Issues** - Identify problematic interaction patterns
-5. **Optimize UX** - Focus improvements on frequently used triggers
+#### **Diff Calculation**
 
-#### Analytics Insights
+Three formats available for different use cases:
 
-With trigger names, you can analyze:
+| Format   | Best For            | Output              |
+| -------- | ------------------- | ------------------- |
+| `git`    | Code/text changes   | Unified diff format |
+| `object` | Structured data     | Deep object diff    |
+| `json`   | Simple before/after | JSON comparison     |
 
-- **User vs AI ratio**: How much content comes from AI vs manual input?
-- **Correction patterns**: Are users frequently fixing AI suggestions?
-- **Workflow efficiency**: Which triggers lead to the most refinements?
-- **Feature adoption**: Are new features being used as intended?
+#### **Vote Determination**
 
-### API Reference
+Automatic classification of changes:
 
 ```tsx
-function useFeedbackState<T>(
-  initialState: T,
-  identifier: string | ((state: T) => string),
-  options?: DiffOptions<T>
-): [T, (value: SetStateAction<T>, trigger_name?: string) => void];
+// Smart vote logic based on change magnitude
+const [data, setData] = useFeedbackState(initial, 'tracker', {
+  vote: (before, after, diffPercentage) => {
+    // Small changes = refinement (positive)
+    if (diffPercentage <= 0.5) return 'upvote';
+    // Large changes = major revision (might indicate issues)
+    return 'downvote';
+  },
+});
 ```
 
-#### Parameters
+### **🎯 Best Practices Summary**
 
-| Parameter      | Type                             | Required | Description                    |
-| -------------- | -------------------------------- | -------- | ------------------------------ |
-| `initialState` | `T`                              | ✓        | Initial state value (any type) |
-| `identifier`   | `string \| (state: T) => string` | ✓        | Unique identifier for tracking |
-| `options`      | `DiffOptions<T>`                 |          | Configuration options          |
+#### **Identifiers**
 
-#### DiffOptions
+✅ Use traceable session/request IDs  
+✅ Include context in identifier structure  
+✅ Keep identifiers consistent across related actions
 
-| Option                 | Type                                    | Default               | Description                                       |
-| ---------------------- | --------------------------------------- | --------------------- | ------------------------------------------------- |
-| `debounceMs`           | `number`                                | `1500`                | Debounce time in milliseconds                     |
-| `diffType`             | `'git' \| 'object' \| 'json'`           | `'git'`               | Format for diff output                            |
-| `compareWith`          | `(a: T, b: T) => boolean`               |                       | Custom equality comparison function               |
-| `metadata`             | `Record<string, any>`                   |                       | Additional metadata to include                    |
-| `onFeedback`           | `(data: FeedbackData) => Promise<void>` |                       | Custom feedback handler (for testing)             |
-| `vote`                 | `'upvote' \| 'downvote' \| function`    |                       | Static vote or custom function for determination  |
-| `default_trigger_name` | `string`                                | `'auto_state_change'` | Default trigger name when no trigger is specified |
+#### **Feedback Sources**
 
-### How It Works
+✅ Use explicit feedback for user opinions  
+✅ Use implicit feedback for behavior analysis  
+✅ Combine both for comprehensive insights
 
-1. **State Changes**: When state updates, the hook captures the change
-2. **Debouncing**: Multiple rapid changes extend the timer (user is still editing)
-3. **Diff Calculation**: Once changes stop, calculates the difference from start to final state
-4. **Vote Determination**:
-   - **≤50% change** = `upvote` (minor refinement)
-   - **>50% change** = `downvote` (major revision)
-5. **Automatic Feedback**: Sends implicit feedback with diff data in the `correction` field
+#### **Trigger Names**
 
-### Diff Formats
+✅ Use consistent naming conventions  
+✅ Group related triggers with prefixes  
+✅ Document trigger meanings for your team
 
-#### Git Diff (default)
+#### **Integration**
+
+✅ Handle feedback data asynchronously  
+✅ Include relevant metadata for context  
+✅ Test both explicit and implicit flows
 
-```
 ---
-+++
-@@ -1,1 +1,1 @@
--{"name": "John"}
-+{"name": "John Doe"}
-```
 
-#### Object Diff
+## 🔧 Core Components
 
-```json
-[
-  {
-    "kind": "E",
-    "path": ["name"],
-    "lhs": "John",
-    "rhs": "John Doe"
-  }
-]
-```
+### **VoteFeedback.Root**
 
-#### JSON Diff
+Main container component that manages feedback state.
 
-```json
-{
-  "before": {
-    "name": "John"
-  },
-  "after": {
-    "name": "John Doe"
-  }
-}
+```tsx
+<VoteFeedback.Root
+  identifier="unique-id" // Required: Unique tracking ID
+  onFeedback={handleFeedback} // Required: Callback function
+  trigger_name="user_feedback" // Optional: Categorization
+  extra_metadata={{ page: 'home' }} // Optional: Additional data
+>
+  {/* Child components */}
+</VoteFeedback.Root>
 ```
 
-### Use Cases
+### **VoteFeedback.UpvoteButton / DownvoteButton**
 
-- **Form editing** - Track user input patterns and corrections
-- **Content creation** - Understand how users refine their writing
-- **Configuration changes** - Monitor settings adjustments
-- **Data visualization** - Capture how users explore and filter data
-- **AI interactions** - Learn from user modifications to AI-generated content
+Interactive voting buttons with built-in state management.
 
-### Vote Configuration
+```tsx
+<VoteFeedback.UpvoteButton className="your-styles">
+  👍 Like
+</VoteFeedback.UpvoteButton>
+```
 
-Control how changes are classified with the `vote` option:
+### **VoteFeedback.Popover**
 
-#### Static Vote
+Context-aware feedback form that appears after voting.
 
 ```tsx
-// Always upvote - useful for content creation tools
-const [content, setContent] = useFeedbackState('Draft...', 'content-editor', {
-  vote: 'upvote',
-});
-
-// Always downvote - useful for error tracking
-const [errors, setErrors] = useFeedbackState([], 'error-log', {
-  vote: 'downvote',
-});
+<VoteFeedback.Popover className="your-popover-styles">
+  <VoteFeedback.Textarea placeholder="Tell us more..." />
+  <VoteFeedback.SubmitButton>Send</VoteFeedback.SubmitButton>
+</VoteFeedback.Popover>
 ```
 
-#### Custom Vote Function
+---
+
+## 📊 Automatic Feedback Hooks
+
+### **useFeedbackState Hook**
+
+A **drop-in replacement for React's useState** that automatically tracks state changes.
+
+#### **Basic Usage**
 
 ```tsx
-// Business logic-based voting
-const [issue, setIssue] = useFeedbackState(
-  { priority: 1, severity: 'low' },
-  'issue-tracker',
-  {
-    vote: (before, after, diffPercentage) => {
-      // Priority increase = positive change
-      if (after.priority > before.priority) return 'upvote';
-      if (after.priority < before.priority) return 'downvote';
-
-      // Severity increase = negative change
-      const severityOrder = { low: 1, medium: 2, high: 3, critical: 4 };
-      const beforeSev = severityOrder[before.severity] || 1;
-      const afterSev = severityOrder[after.severity] || 1;
-
-      // Fall back to diff percentage for other cases
-      return afterSev > beforeSev
-        ? 'downvote'
-        : diffPercentage > 0.7
-          ? 'downvote'
-          : 'upvote';
-    },
-  }
-);
+const [count, setCount] = useFeedbackState(0, 'counter-widget');
 ```
 
-#### Advanced Vote Logic Examples
+#### **Advanced Configuration**
 
 ```tsx
-// Content quality assessment
-const [article, setArticle] = useFeedbackState(
-  { title: '', content: '', tags: [] },
-  'article-editor',
-  {
-    vote: (before, after, diffPercentage) => {
-      // More tags = improvement
-      if (after.tags.length > before.tags.length) return 'upvote';
-
-      // Significant content expansion = improvement
-      const contentGrowth =
-        after.content.length / Math.max(before.content.length, 1);
-      if (contentGrowth > 1.2) return 'upvote';
-
-      // Major changes might indicate problems
-      return diffPercentage > 0.6 ? 'downvote' : 'upvote';
-    },
-  }
-);
-
-// User experience tracking
-const [settings, setSettings] = useFeedbackState(
-  { theme: 'light', notifications: true, autoSave: false },
-  'user-preferences',
+const [profile, setProfile] = useFeedbackState(
+  { name: '', email: '' },
+  state => `profile-${state.email}`, // Dynamic identifier
   {
-    vote: (before, after, diffPercentage) => {
-      // Enabling helpful features = positive
-      if (after.autoSave && !before.autoSave) return 'upvote';
-      if (after.notifications && !before.notifications) return 'upvote';
-
-      // Disabling features might indicate UX issues
-      if (!after.autoSave && before.autoSave) return 'downvote';
-
-      // Small tweaks are usually positive
-      return diffPercentage < 0.3 ? 'upvote' : 'downvote';
-    },
+    debounceMs: 2000, // Wait time before sending feedback
+    diffType: 'object', // Format: 'git' | 'object' | 'json'
+    metadata: { component: 'UserProfile' },
+    vote: 'upvote', // Static vote or custom function
   }
 );
 ```
 
-### Best Practices
+#### **Trigger Names for Categorization**
 
 ```tsx
-// ✅ Good: Static identifier for consistent tracking
-const [settings, setSettings] = useFeedbackState(
-  defaultSettings,
-  'user-settings'
+const [content, setContent] = useFeedbackState(
+  'Initial content',
+  'content-editor',
+  { default_trigger_name: 'manual_edit' }
 );
 
-// ✅ Good: Dynamic identifier that makes sense
-const [items, setItems] = useFeedbackState(
-  [],
-  items => `shopping-cart-${items.length}-items`
-);
+// Uses default trigger
+setContent('User typed this');
 
-// ✅ Good: Appropriate debounce for use case
-const [searchQuery, setSearchQuery] = useFeedbackState(
-  '',
-  'search-input',
-  { debounceMs: 800 } // Shorter for search
-);
+// Override with specific trigger
+setContent('AI generated this', 'ai_assistance');
+setContent('Spell checker fixed this', 'spell_check');
+```
 
-// ✅ Good: Custom vote logic for domain-specific scenarios
-const [formData, setFormData] = useFeedbackState(initialForm, 'contact-form', {
-  vote: (before, after, diffPercentage) => {
-    // Form completion = positive signal
-    const beforeFields = Object.values(before).filter(Boolean).length;
-    const afterFields = Object.values(after).filter(Boolean).length;
-    return afterFields > beforeFields ? 'upvote' : 'downvote';
-  },
-});
+### **useFeedbackReducer Hook**
 
-// ❌ Avoid: Very short debounce times
-const [text, setText] = useFeedbackState(
-  '',
-  'editor',
-  { debounceMs: 50 } // Too aggressive
+A **drop-in replacement for React's useReducer** with automatic trigger name extraction from action types.
+
+```tsx
+const [state, dispatch] = useFeedbackReducer(
+  counterReducer,
+  { count: 0 },
+  'counter-widget'
 );
 
-// ❌ Avoid: Overly complex vote logic
-const [data, setData] = useFeedbackState({}, 'complex-data', {
-  vote: (before, after, diffPercentage) => {
-    // Don't make it too complicated - keep it readable!
-    // Complex business logic should be in separate functions
-    return determineVoteFromBusinessLogic(before, after, diffPercentage);
-  },
-});
+dispatch({ type: 'increment' }); // trigger_name: 'increment'
+dispatch({ type: 'reset' }); // trigger_name: 'reset'
+dispatch({ type: 'custom' }, 'override'); // Custom trigger name
 ```
 
-## Examples
+---
+
+## 🎨 Examples
 
-### Basic Usage
+### **Basic Voting Interface**
 
 ```tsx
 <VoteFeedback.Root onFeedback={feedback => console.log(feedback)}>
@@ -616,7 +426,7 @@ const [data, setData] = useFeedbackState({}, 'complex-data', {
 </VoteFeedback.Root>
 ```
 
-### With Custom Styling
+### **Styled with Custom CSS**
 
 ```tsx
 <VoteFeedback.Root onFeedback={handleFeedback}>
@@ -635,51 +445,210 @@ const [data, setData] = useFeedbackState({}, 'complex-data', {
 </VoteFeedback.Root>
 ```
 
-### With Trigger Name
+### **Polymorphic Components with asChild**
+
+```tsx
+<VoteFeedback.UpvoteButton asChild>
+  <button className="custom-button">
+    <Icon name="thumbs-up" />
+    Like
+  </button>
+</VoteFeedback.UpvoteButton>
+```
+
+### **AI Response Feedback**
 
 ```tsx
 <VoteFeedback.Root
+  identifier="ai-response-123"
   onFeedback={handleFeedback}
-  identifier="ai-response"
-  trigger_name="user_feedback"
+  trigger_name="ai_evaluation"
+  extra_metadata={{
+    model: 'gpt-4',
+    prompt_length: 150,
+    response_time: 1200,
+  }}
 >
   <VoteFeedback.UpvoteButton>👍 Helpful</VoteFeedback.UpvoteButton>
   <VoteFeedback.DownvoteButton>👎 Not helpful</VoteFeedback.DownvoteButton>
   <VoteFeedback.Popover>
-    <VoteFeedback.Textarea placeholder="How can we improve?" />
+    <VoteFeedback.Textarea placeholder="How can we improve this response?" />
     <VoteFeedback.SubmitButton>Send feedback</VoteFeedback.SubmitButton>
   </VoteFeedback.Popover>
 </VoteFeedback.Root>
 ```
 
-### Using asChild Pattern
+---
+
+## 📖 API Reference
+
+### **Feedback Data Object**
+
+```typescript
+interface FeedbackData {
+  identifier: string; // Unique tracking ID
+  vote: 'upvote' | 'downvote'; // User's vote
+  explanation?: string; // Optional user comment
+  extra_metadata?: Record<string, any>; // Additional context data
+  source?: 'IMPLICIT' | 'EXPLICIT'; // How feedback was collected
+  correction?: string; // For implicit feedback diffs
+  selection?: string; // Selected text context
+  trigger_name?: string; // Categorization tag
+}
+```
+
+### **VoteFeedback.Root Props**
+
+| Prop             | Type                           | Required | Description                         |
+| ---------------- | ------------------------------ | -------- | ----------------------------------- |
+| `identifier`     | `string`                       | ✅       | Unique identifier for tracking      |
+| `onFeedback`     | `(data: FeedbackData) => void` | ✅       | Callback when feedback is submitted |
+| `trigger_name`   | `string`                       | ❌       | Optional categorization tag         |
+| `extra_metadata` | `object`                       | ❌       | Additional context data             |
+
+### **Hook Options**
+
+#### **useFeedbackState Options**
+
+| Option                 | Type                                 | Default               | Description                   |
+| ---------------------- | ------------------------------------ | --------------------- | ----------------------------- |
+| `debounceMs`           | `number`                             | `1500`                | Debounce time in milliseconds |
+| `diffType`             | `'git' \| 'object' \| 'json'`        | `'git'`               | Diff output format            |
+| `compareWith`          | `(a: T, b: T) => boolean`            | `undefined`           | Custom equality function      |
+| `metadata`             | `Record<string, any>`                | `{}`                  | Additional metadata           |
+| `vote`                 | `'upvote' \| 'downvote' \| function` | `auto`                | Vote determination logic      |
+| `default_trigger_name` | `string`                             | `'auto_state_change'` | Default trigger name          |
+
+---
+
+## ♿ Accessibility
+
+✅ **Full keyboard navigation support**  
+✅ **ARIA labels and roles**  
+✅ **Focus management**  
+✅ **Screen reader compatible**  
+✅ **High contrast support**  
+✅ **Reduced motion respect**
+
+### **Keyboard Shortcuts**
+
+- `Tab` / `Shift+Tab` - Navigate between elements
+- `Enter` / `Space` - Activate buttons
+- `Escape` - Close popover
+- `Arrow Keys` - Navigate within popover
+
+---
+
+## 🛠 Development
+
+### **Setup**
+
+```bash
+bun install          # Install dependencies
+bun dev             # Start Storybook development server
+bun run checks       # Run all quality checks
+```
+
+### **Testing**
+
+```bash
+bun run test:unit           # Run unit tests
+bun run test:storybook      # Run Storybook interaction tests
+bun run test:storybook:coverage  # Run with coverage
+```
+
+### **Building**
+
+```bash
+bun build           # Build library for production
+bun run typecheck   # TypeScript type checking
+bun run lint        # ESLint code quality checks
+bun run prettier    # Code formatting
+```
+
+### **Quality Checks**
+
+```bash
+bun run checks      # Run all quality checks (lint, format, typecheck, tests)
+```
+
+---
+
+## ❓ Troubleshooting
+
+### **Common Issues**
+
+#### **Q: Feedback not triggering**
+
+```tsx
+// ❌ Missing required props
+<VoteFeedback.Root>
+    <VoteFeedback.UpvoteButton>👍</VoteFeedback.UpvoteButton>
+</VoteFeedback.Root>
+
+// ✅ Include required identifier and onFeedback
+<VoteFeedback.Root
+    identifier="my-feature"
+    onFeedback={handleFeedback}
+>
+    <VoteFeedback.UpvoteButton>👍</VoteFeedback.UpvoteButton>
+</VoteFeedback.Root>
+```
+
+#### **Q: TypeScript errors with custom components**
 
 ```tsx
+// ✅ Use asChild for custom components
 <VoteFeedback.UpvoteButton asChild>
-  <button className="custom-button">
-    <Icon name="thumbs-up" />
-    Like
-  </button>
+  <MyCustomButton>Like</MyCustomButton>
 </VoteFeedback.UpvoteButton>
 ```
 
-## Accessibility
+#### **Q: useFeedbackState not sending feedback**
 
-- Full keyboard navigation support
-- ARIA labels and roles
-- Focus management
-- Screen reader compatible
+```tsx
+// ✅ Ensure debounce time has passed(the time, not the configuration! :P) and state actually changed
+const [value, setValue] = useFeedbackState('initial', 'test', {
+  debounceMs: 1000, // Wait 1 second after last change
+});
+```
 
-## Development
+#### **Q: Styling not working**
 
-```bash
-bun install
-bun dev  # Start Storybook
-bun run test:unit # Run unit tests
-bun run test:storybook # Run Storybook tests
-bun build # Build library
+```tsx
+// ✅ Components are unstyled by default - add your own CSS or use the Shadcn UI library
+<VoteFeedback.UpvoteButton className="bg-green-500 text-white p-2">
+  👍 Like
+</VoteFeedback.UpvoteButton>
 ```
 
+### **Best Practices**
+
+✅ **Use unique identifiers** for each feedback instance - the identifier should be traceable back to the session's log
+and allow us to understand the context of the feedback.
+✅ **Handle feedback data asynchronously** in your callback  
+✅ **Test keyboard navigation** in your implementation  
+✅ **Provide meaningful trigger names** for categorization  
+✅ **Include relevant metadata** for context
+
+❌ **Don't use the same identifier** for multiple components. An identifier should be traced back to the session's log -
+allows us to understand the context of the feedback.
+
+---
+
+## 📚 Additional Resources
+
+**📖 Full Documentation**: [https://feedback-ui.kelet.ai/](https://feedback-ui.kelet.ai/)  
+**🎮 Interactive Examples**: [Storybook Documentation](https://feedback-ui.kelet.ai/storybook/)  
+**🐛 Report Issues**: [GitHub Issues](https://github.com/kelet-ai/feedback-ui/issues)  
+**💬 Discussions**: [GitHub Discussions](https://github.com/kelet-ai/feedback-ui/discussions)
+
+---
+
 ## License
 
-MIT
+**MIT License** - See [LICENSE](LICENSE) file for details.
+
+---
+
+_Built with ❤️ by the [Kelet AI](https://kelet.ai) team_