@kelet-ai/feedback-ui 1.1.4 → 1.3.0

package/README.md

@@ -126,6 +126,43 @@ function ContentEditor() {
 }
 ```
 
+### **Pattern 4: Manual Signal Sending**
+
+Send signals directly without tying them to component state — useful for custom events, page views, or any interaction not covered by the other patterns:
+
+```tsx
+import { KeletProvider, useKeletSignal } from "@kelet-ai/feedback-ui"
+
+function CopyButton({ sessionId }: { sessionId: string }) {
+  const sendSignal = useKeletSignal()
+
+  return (
+    <button
+      onClick={() => {
+        navigator.clipboard.writeText("...")
+        sendSignal({
+          session_id: sessionId,
+          kind: "feedback",
+          source: "human",
+          score: 1,
+          trigger_name: "copy_button_clicked",
+        })
+      }}
+    >
+      Copy
+    </button>
+  )
+}
+
+function App() {
+  return (
+    <KeletProvider apiKey="..." project="my-project">
+      <CopyButton sessionId="response-abc123" />
+    </KeletProvider>
+  )
+}
+```
+
 ### **Pattern 3: Complex State with Reducer**
 
 For advanced state management with automatic trigger tracking, by using a drop-in replacement for useReducer:
@@ -359,6 +396,39 @@ Context-aware feedback form that appears after voting.
 
 ---
 
+## ✉️ Manual Signal Sending
+
+### **useKeletSignal Hook**
+
+Returns the signal-sending function from the nearest `KeletProvider`. Use this to send signals manually for any event — custom interactions, page views, feature usage — without tying them to component state.
+
+Safe to call outside a provider: returns a no-op and logs a warning.
+
+```tsx
+import { useKeletSignal } from "@kelet-ai/feedback-ui"
+
+function MyComponent() {
+  const sendSignal = useKeletSignal()
+
+  const handleAction = () => {
+    sendSignal({
+      session_id: "my-session",
+      kind: "feedback",
+      source: "human",
+      score: 1,
+      trigger_name: "user_action",
+      metadata: { context: "sidebar" },
+    })
+  }
+
+  return <button onClick={handleAction}>Do something</button>
+}
+```
+
+Requires a `KeletProvider` ancestor to send signals to the API.
+
+---
+
 ## 📊 Automatic Feedback Hooks
 
 ### **useFeedbackState Hook**

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

@@ -1,8 +1,9 @@
+import { default as React } from 'react';
 import { DownvoteButtonProps, PopoverProps, SubmitButtonProps, TextareaProps, UpvoteButtonProps, VoteFeedbackRootProps } from '../types';
 export declare const VoteFeedback: {
     Root: ({ children, onFeedback, defaultText, session_id: sessionIdProp, metadata, trigger_name: triggerProp, trace_id, }: 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;
+    DownvoteButton: ({ asChild, children, onClick, ...props }: DownvoteButtonProps) => string | number | bigint | true | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element;
     Popover: ({ asChild, children, ...props }: PopoverProps) => import("react/jsx-runtime").JSX.Element | null;
     Textarea: ({ asChild, value, onChange, ...props }: TextareaProps) => import("react/jsx-runtime").JSX.Element;
     SubmitButton: ({ asChild, children, onClick, ...props }: SubmitButtonProps) => import("react/jsx-runtime").JSX.Element;

package/dist/contexts/kelet.d.ts

@@ -12,6 +12,26 @@ interface KeletProviderProps {
 }
 export declare const KeletContext: React.Context<KeletContextValue | null>;
 export declare const useKelet: () => KeletContextValue;
+/**
+ * Returns the signal-sending function from the nearest KeletProvider.
+ *
+ * Use this hook to send signals manually — e.g. tracking custom events,
+ * page views, or any interaction not covered by useFeedbackState.
+ *
+ * Safe to call outside a provider: returns a no-op and logs a warning.
+ *
+ * @example
+ * const sendSignal = useKeletSignal()
+ *
+ * sendSignal({
+ *   session_id: 'my-session',
+ *   kind: 'feedback',
+ *   source: 'human',
+ *   score: 1,
+ *   trigger_name: 'copy_button_clicked',
+ * })
+ */
+export declare const useKeletSignal: () => ((data: FeedbackData) => Promise<void>);
 export declare const useDefaultFeedbackHandler: () => ((data: FeedbackData) => Promise<void>);
 export declare const KeletProvider: React.FC<React.PropsWithChildren<KeletProviderProps>>;
 export {};

package/dist/feedback-ui.es.js

@@ -1,4 +1,4 @@
-import require$$0$1, { createContext, useEffect, useContext, useCallback, isValidElement, cloneElement, useState, useRef, useId } from "react";
+import require$$0$1, { createContext, useEffect, useContext, useCallback, isValidElement, cloneElement, useRef, useState, useId } from "react";
 function getDefaultExportFromCjs(x) {
   return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, "default") ? x["default"] : x;
 }
@@ -443,7 +443,7 @@ const useKelet = () => {
   }
   return context;
 };
-const useDefaultFeedbackHandler = () => {
+const useKeletSignal = () => {
   const context = useContext(KeletContext);
   if (!context) {
     console.warn(
@@ -455,6 +455,7 @@ const useDefaultFeedbackHandler = () => {
     return context.feedback;
   }
 };
+const useDefaultFeedbackHandler = useKeletSignal;
 const KeletProvider = ({ apiKey, project, baseUrl, children }) => {
   useEffect(() => {
     initEventCapture();
@@ -574,6 +575,11 @@ const VoteFeedbackRoot = ({
     setVote(null);
     setTimeout(() => triggerRef.current?.focus(), 0);
   }, [session_id, defaultText]);
+  const closePopover = useCallback(() => {
+    setShowPopover(false);
+    setFeedbackText(defaultText);
+    setTimeout(() => triggerRef.current?.focus(), 0);
+  }, [defaultText]);
   const handleUpvote = useCallback(async () => {
     setVote("upvote");
     const data = {
@@ -672,9 +678,7 @@ const VoteFeedbackRoot = ({
   const handleKeyDown = useCallback(
     (e) => {
       if (e.key === "Escape") {
-        setShowPopover(false);
-        setFeedbackText(defaultText);
-        triggerRef.current?.focus();
+        closePopover();
       } else if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
         e.preventDefault();
         handleSubmit().then((_) => {
@@ -697,7 +701,7 @@ const VoteFeedbackRoot = ({
         }
       }
     },
-    [handleSubmit, showPopover, popoverId, defaultText]
+    [handleSubmit, showPopover, popoverId, closePopover]
   );
   const contextValue = {
     onFeedback: handler,
@@ -713,6 +717,7 @@ const VoteFeedbackRoot = ({
     handleTextareaChange,
     handleSubmit,
     handleKeyDown,
+    closePopover,
     textareaRef,
     triggerRef,
     popoverId,
@@ -802,7 +807,25 @@ const DownvoteButton = ({
   return /* @__PURE__ */ jsxRuntimeExports.jsx("button", { ...slotProps, children: typeof children === "function" ? children({ isSelected }) : children });
 };
 const Popover = ({ asChild, children, ...props }) => {
-  const { showPopover, handleKeyDown, popoverId, triggerId } = useVoteFeedbackContext();
+  const {
+    showPopover,
+    closePopover,
+    handleKeyDown,
+    popoverId,
+    triggerId,
+    triggerRef
+  } = useVoteFeedbackContext();
+  const containerRef = useRef(null);
+  useEffect(() => {
+    if (!showPopover) return;
+    const handleMouseDown = (event) => {
+      if (containerRef.current && !containerRef.current.contains(event.target) && !triggerRef.current?.contains(event.target)) {
+        closePopover();
+      }
+    };
+    document.addEventListener("mousedown", handleMouseDown);
+    return () => document.removeEventListener("mousedown", handleMouseDown);
+  }, [showPopover, closePopover, triggerRef]);
   if (!showPopover) {
     return null;
   }
@@ -818,14 +841,14 @@ const Popover = ({ asChild, children, ...props }) => {
   };
   if (asChild && isValidElement(children)) {
     return /* @__PURE__ */ jsxRuntimeExports.jsxs(jsxRuntimeExports.Fragment, { children: [
-      cloneElement(
-        children,
-        mergeProps(slotProps, children.props)
-      ),
+      cloneElement(children, {
+        ...mergeProps(slotProps, children.props),
+        ref: containerRef
+      }),
       /* @__PURE__ */ jsxRuntimeExports.jsx("div", { id: `${popoverId}-description`, className: "sr-only", children: "Provide additional feedback for your downvote" })
     ] });
   }
-  return /* @__PURE__ */ jsxRuntimeExports.jsxs("div", { ...slotProps, children: [
+  return /* @__PURE__ */ jsxRuntimeExports.jsxs("div", { ref: containerRef, ...slotProps, children: [
     /* @__PURE__ */ jsxRuntimeExports.jsx("div", { id: `${popoverId}-description`, className: "sr-only", children: "Provide additional feedback for your downvote" }),
     children
   ] });
@@ -2275,6 +2298,7 @@ export {
   VoteFeedback,
   useDefaultFeedbackHandler,
   useFeedbackState,
-  useKelet
+  useKelet,
+  useKeletSignal
 };
 //# sourceMappingURL=feedback-ui.es.js.map