@kelet-ai/feedback-ui 1.0.2 → 1.1.1

package/README.md

@@ -28,7 +28,7 @@ import { ShadcnVoteFeedback } from '@/components/ui/vote-feedback';
 function App() {
   return (
     <ShadcnVoteFeedback
-      tx_id="my-feature"
+      session_id="my-feature"
       onFeedback={feedback => console.log(feedback)}
       variant="outline"
     />
@@ -91,7 +91,7 @@ Users explicitly vote and provide comments:
 ```tsx
 import { VoteFeedback } from '@kelet-ai/feedback-ui';
 
-<VoteFeedback.Root onFeedback={handleFeedback} tx_id="ai-response">
+<VoteFeedback.Root onFeedback={handleFeedback} session_id="ai-response">
   <VoteFeedback.UpvoteButton>👍 Helpful</VoteFeedback.UpvoteButton>
   <VoteFeedback.DownvoteButton>👎 Not helpful</VoteFeedback.DownvoteButton>
   <VoteFeedback.Popover>
@@ -158,14 +158,14 @@ Understanding these fundamental concepts will help you implement feedback collec
 **Best Practice**: Use traceable IDs from your logging system (session ID, trace ID, request ID)
 
 ```tsx
-// ✅ Good: Traceable tx_id
-<VoteFeedback.Root tx_id="session-abc123-ai-response-456"/>
+// ✅ Good: Traceable session_id
+<VoteFeedback.Root session_id="session-abc123-ai-response-456"/>
 
-// ✅ Good: Content-based tx_id
-<VoteFeedback.Root tx_id={`article-${articleId}-section-${sectionId}`}/>
+// ✅ Good: Content-based session_id
+<VoteFeedback.Root session_id={`article-${articleId}-section-${sectionId}`}/>
 
-// ❌ Poor: Generic tx_id
-<VoteFeedback.Root tx_id="feedback"/>
+// ❌ Poor: Generic session_id
+<VoteFeedback.Root session_id="feedback"/>
 ```
 
 ### **📊 Feedback Sources**
@@ -296,8 +296,8 @@ const [data, setData] = useFeedbackState(initial, 'tracker', {
 #### **Identifiers**
 
 ✅ Use traceable session/request IDs  
-✅ Include context in tx_id structure  
-✅ Keep tx_ids consistent across related actions
+✅ Include context in session_id structure  
+✅ Keep session_ids consistent across related actions
 
 #### **Feedback Sources**
 
@@ -327,7 +327,7 @@ Main container component that manages feedback state.
 
 ```tsx
 <VoteFeedback.Root
-  tx_id="unique-id" // Required: Unique tracking ID
+  session_id="unique-id" // Required: Unique tracking ID
   onFeedback={handleFeedback} // Required: Callback function
   trigger_name="user_feedback" // Optional: Categorization
   extra_metadata={{ page: 'home' }} // Optional: Additional data
@@ -376,7 +376,7 @@ const [count, setCount] = useFeedbackState(0, 'counter-widget');
 ```tsx
 const [profile, setProfile] = useFeedbackState(
   { name: '', email: '' },
-  state => `profile-${state.email}`, // Dynamic tx_id
+  state => `profile-${state.email}`, // Dynamic session_id
   {
     debounceMs: 2000, // Wait time before sending feedback
     diffType: 'object', // Format: 'git' | 'object' | 'json'
@@ -466,7 +466,7 @@ dispatch({ type: 'custom' }, 'override'); // Custom trigger name
 
 ```tsx
 <VoteFeedback.Root
-  tx_id="ai-response-123"
+  session_id="ai-response-123"
   onFeedback={handleFeedback}
   trigger_name="ai_evaluation"
   extra_metadata={{
@@ -492,7 +492,7 @@ dispatch({ type: 'custom' }, 'override'); // Custom trigger name
 
 ```typescript
 interface FeedbackData {
-  tx_id: string; // Unique tracking ID
+  session_id: string; // Unique tracking ID
   vote: 'upvote' | 'downvote'; // User's vote
   explanation?: string; // Optional user comment
   extra_metadata?: Record<string, any>; // Additional context data
@@ -507,7 +507,7 @@ interface FeedbackData {
 
 | Prop             | Type                           | Required | Description                         |
 | ---------------- | ------------------------------ | -------- | ----------------------------------- |
-| `tx_id`          | `string`                       | ✅       | Unique transaction ID for tracking  |
+| `session_id`     | `string`                       | ✅       | Unique session ID for tracking      |
 | `onFeedback`     | `(data: FeedbackData) => void` | ✅       | Callback when feedback is submitted |
 | `trigger_name`   | `string`                       | ❌       | Optional categorization tag         |
 | `extra_metadata` | `object`                       | ❌       | Additional context data             |
@@ -593,9 +593,9 @@ bun run checks      # Run all quality checks (lint, format, typecheck, tests)
     <VoteFeedback.UpvoteButton>👍</VoteFeedback.UpvoteButton>
 </VoteFeedback.Root>
 
-// ✅ Include required tx_id and onFeedback
+// ✅ Include required session_id and onFeedback
 <VoteFeedback.Root
-    tx_id="my-feature"
+    session_id="my-feature"
     onFeedback={handleFeedback}
 >
     <VoteFeedback.UpvoteButton>👍</VoteFeedback.UpvoteButton>
@@ -631,14 +631,14 @@ const [value, setValue] = useFeedbackState('initial', 'test', {
 
 ### **Best Practices**
 
-✅ **Use unique tx_ids** for each feedback instance - the tx_id should be traceable back to the session's log
+✅ **Use unique session_ids** for each feedback instance - the session_id 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 tx_id** for multiple components. A tx_id should be traced back to the session's log -
+❌ **Don't use the same session_id** for multiple components. A session_id should be traced back to the session's log -
 allows us to understand the context of the feedback.
 
 ---

package/dist/components/vote-feedback.d.ts

@@ -1,6 +1,6 @@
 import { DownvoteButtonProps, PopoverProps, SubmitButtonProps, TextareaProps, UpvoteButtonProps, VoteFeedbackRootProps } from '../types';
 export declare const VoteFeedback: {
-    Root: ({ children, onFeedback, defaultText, tx_id: txIdProp, extra_metadata, trigger_name, }: VoteFeedbackRootProps) => import("react/jsx-runtime").JSX.Element;
+    Root: ({ children, onFeedback, defaultText, session_id: sessionIdProp, extra_metadata, trigger_name, }: VoteFeedbackRootProps) => import("react/jsx-runtime").JSX.Element;
     UpvoteButton: ({ asChild, children, onClick, ...props }: UpvoteButtonProps) => import("react/jsx-runtime").JSX.Element;
     DownvoteButton: ({ asChild, children, onClick, ...props }: DownvoteButtonProps) => string | number | bigint | true | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element;
     Popover: ({ asChild, children, ...props }: PopoverProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/feedback-ui.es.js

@@ -1,4 +1,4 @@
-import require$$0$1, { createContext, useContext, useCallback, isValidElement, cloneElement, useState, useRef, useId, useEffect } from "react";
+import require$$0$1, { createContext, useEffect, useContext, useCallback, isValidElement, cloneElement, useState, useRef, useId } from "react";
 function getDefaultExportFromCjs(x) {
   return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, "default") ? x["default"] : x;
 }
@@ -352,6 +352,88 @@ function requireJsxRuntime() {
   return jsxRuntime.exports;
 }
 var jsxRuntimeExports = requireJsxRuntime();
+let latestEvent = null;
+let isInitialized = false;
+function serializeTarget(target) {
+  if (!target || !(target instanceof Element)) return "unknown";
+  const el = target;
+  if (el.id) return `#${el.id}`;
+  const dataId = el.getAttribute("data-feedback-id");
+  if (dataId) return `[data-feedback-id="${dataId}"]`;
+  const path = [];
+  let current = el;
+  let depth = 0;
+  const MAX_DEPTH = 5;
+  while (current && current !== document.body && depth < MAX_DEPTH) {
+    let selector = current.tagName.toLowerCase();
+    if (current.classList.length > 0) {
+      const className = Array.from(current.classList)[0];
+      selector += `.${className}`;
+    }
+    const parent = current.parentElement;
+    if (parent) {
+      const siblings = Array.from(parent.children);
+      const index = siblings.indexOf(current) + 1;
+      if (siblings.length > 1) {
+        selector += `:nth-child(${index})`;
+      }
+    }
+    path.unshift(selector);
+    current = parent;
+    depth++;
+  }
+  return path.join(" > ");
+}
+function getTargetText(target) {
+  if (!target || !(target instanceof Element)) return "";
+  const el = target;
+  const ariaLabel = el.getAttribute("aria-label");
+  if (ariaLabel) return ariaLabel.substring(0, 50);
+  const text = el.textContent?.trim() || "";
+  return text.substring(0, 50);
+}
+function captureEvent(e) {
+  const captured = {
+    type: e.type,
+    targetSelector: serializeTarget(e.target),
+    targetText: getTargetText(e.target),
+    timestamp: Date.now()
+  };
+  if (e instanceof MouseEvent) {
+    captured.coordinates = { x: e.clientX, y: e.clientY };
+  } else if (e instanceof KeyboardEvent) {
+    captured.key = e.key;
+  }
+  return captured;
+}
+function initEventCapture() {
+  if (isInitialized || typeof window === "undefined") return;
+  const eventTypes = ["click", "keydown", "submit", "change"];
+  eventTypes.forEach((type) => {
+    window.addEventListener(
+      type,
+      (e) => {
+        latestEvent = captureEvent(e);
+      },
+      {
+        capture: true,
+        // Intercept before React handlers
+        passive: true
+        // Better scroll performance
+      }
+    );
+  });
+  isInitialized = true;
+}
+function getLatestEvent() {
+  if (!latestEvent) return null;
+  const age = Date.now() - latestEvent.timestamp;
+  if (age > 1e4) {
+    latestEvent = null;
+    return null;
+  }
+  return { ...latestEvent };
+}
 const KeletContext = createContext(null);
 const DefaultKeletBaseUrl = "https://api.kelet.ai/api";
 const useKelet = () => {
@@ -374,6 +456,9 @@ const useDefaultFeedbackHandler = () => {
   }
 };
 const KeletProvider = ({ apiKey, project, baseUrl, children }) => {
+  useEffect(() => {
+    initEventCapture();
+  }, []);
   const parentContext = useContext(KeletContext);
   const resolvedApiKey = apiKey || parentContext?.api_key;
   if (!resolvedApiKey) {
@@ -383,15 +468,21 @@ const KeletProvider = ({ apiKey, project, baseUrl, children }) => {
   }
   const feedback = async (data) => {
     const resolvedBaseUrl = baseUrl || DefaultKeletBaseUrl;
-    const url = `${resolvedBaseUrl}/projects/${project}/feedback`;
+    const url = `${resolvedBaseUrl}/projects/${project}/signal`;
+    const capturedEvent = getLatestEvent();
+    const metadata = {
+      ...data.extra_metadata ?? {},
+      ...capturedEvent && { $dom_event: capturedEvent }
+    };
     const req = {
-      tx_id: data.tx_id,
+      session_id: data.session_id,
       source: data.source || "EXPLICIT",
       vote: data.vote,
       explanation: data.explanation,
       correction: data.correction,
-      selection: data.selection
-      // Include trigger_name if needed in the future
+      selection: data.selection,
+      trigger_name: data.trigger_name,
+      metadata: Object.keys(metadata).length > 0 ? metadata : void 0
     };
     const response = await fetch(url, {
       method: "POST",
@@ -453,11 +544,11 @@ const VoteFeedbackRoot = ({
   children,
   onFeedback,
   defaultText = "",
-  tx_id: txIdProp,
+  session_id: sessionIdProp,
   extra_metadata,
   trigger_name
 }) => {
-  const tx_id = typeof txIdProp === "function" ? txIdProp() : txIdProp;
+  const session_id = typeof sessionIdProp === "function" ? sessionIdProp() : sessionIdProp;
   const [showPopover, setShowPopover] = useState(false);
   const [feedbackText, setFeedbackText] = useState(defaultText);
   const [isSubmitting, setIsSubmitting] = useState(false);
@@ -474,11 +565,11 @@ const VoteFeedbackRoot = ({
     setIsSubmitting(false);
     setVote(null);
     setTimeout(() => triggerRef.current?.focus(), 0);
-  }, [tx_id, defaultText]);
+  }, [session_id, defaultText]);
   const handleUpvote = useCallback(async () => {
     setVote("upvote");
     const data = {
-      tx_id,
+      session_id,
       vote: "upvote",
       ...extra_metadata && { extra_metadata },
       ...trigger_name && { trigger_name }
@@ -489,12 +580,12 @@ const VoteFeedbackRoot = ({
     } finally {
       setIsSubmitting(false);
     }
-  }, [handler, tx_id, extra_metadata, trigger_name]);
+  }, [handler, session_id, extra_metadata, trigger_name]);
   const handleDownvote = useCallback(async () => {
     setVote("downvote");
     if (handler) {
       const data = {
-        tx_id,
+        session_id,
         vote: "downvote",
         ...extra_metadata && { extra_metadata },
         ...trigger_name && { trigger_name }
@@ -517,7 +608,7 @@ const VoteFeedbackRoot = ({
       document.body.appendChild(announcement);
       setTimeout(() => document.body.removeChild(announcement), 1e3);
     }, 0);
-  }, [handler, tx_id, extra_metadata, trigger_name]);
+  }, [handler, session_id, extra_metadata, trigger_name]);
   const handleTextareaChange = useCallback(
     (e) => {
       setFeedbackText(e.target.value);
@@ -528,7 +619,7 @@ const VoteFeedbackRoot = ({
     const hasText = feedbackText.trim().length > 0;
     if (hasText) {
       const data = {
-        tx_id,
+        session_id,
         vote: "downvote",
         explanation: feedbackText,
         ...extra_metadata && { extra_metadata },
@@ -552,7 +643,14 @@ const VoteFeedbackRoot = ({
       document.body.appendChild(announcement);
       setTimeout(() => document.body.removeChild(announcement), 1e3);
     }
-  }, [handler, feedbackText, defaultText, tx_id, extra_metadata, trigger_name]);
+  }, [
+    handler,
+    feedbackText,
+    defaultText,
+    session_id,
+    extra_metadata,
+    trigger_name
+  ]);
   const handleKeyDown = useCallback(
     (e) => {
       if (e.key === "Escape") {
@@ -601,7 +699,7 @@ const VoteFeedbackRoot = ({
     triggerRef,
     popoverId,
     triggerId,
-    tx_id,
+    session_id,
     extra_metadata,
     trigger_name
   };
@@ -2016,7 +2114,7 @@ function stringify(value) {
     return String(value);
   }
 }
-function useStateChangeTracking(currentState, tx_id, options) {
+function useStateChangeTracking(currentState, session_id, options) {
   const defaultFeedbackHandler = useDefaultFeedbackHandler();
   const feedbackHandler = options?.onFeedback || defaultFeedbackHandler;
   const debounceMs = options?.debounceMs ?? 3e3;
@@ -2051,9 +2149,9 @@ function useStateChangeTracking(currentState, tx_id, options) {
       } else {
         vote = diffPercentage > 0.5 ? "downvote" : "upvote";
       }
-      const idString = typeof tx_id === "function" ? tx_id(endState) : tx_id;
+      const idString = typeof session_id === "function" ? session_id(endState) : session_id;
       feedbackHandler({
-        tx_id: idString,
+        session_id: idString,
         vote,
         explanation: `State change with diff percentage: ${(diffPercentage * 100).toFixed(1)}%`,
         correction: diffString,
@@ -2062,7 +2160,7 @@ function useStateChangeTracking(currentState, tx_id, options) {
         trigger_name: triggerName
       });
     },
-    [options, tx_id, diffType, feedbackHandler]
+    [options, session_id, diffType, feedbackHandler]
   );
   const notifyChange = useCallback(
     (trigger_name) => {
@@ -2131,7 +2229,7 @@ function useStateChangeTracking(currentState, tx_id, options) {
     };
   }, [
     currentState,
-    tx_id,
+    session_id,
     options,
     feedbackHandler,
     diffType,
@@ -2145,9 +2243,9 @@ function useStateChangeTracking(currentState, tx_id, options) {
     notifyChange
   };
 }
-function useFeedbackState(initialState, tx_id, options) {
+function useFeedbackState(initialState, session_id, options) {
   const [state, setStateInternal] = useState(initialState);
-  const { notifyChange } = useStateChangeTracking(state, tx_id, options);
+  const { notifyChange } = useStateChangeTracking(state, session_id, options);
   const setState = useCallback(
     (value, trigger_name) => {
       notifyChange(trigger_name);