feedtack 0.3.0 → 0.4.0

package/README.md

@@ -74,6 +74,96 @@ class MySupabaseAdapter implements FeedtackAdapter {
 }
 ```
 
+## Adapter recipes
+
+The `FeedtackAdapter` interface has five methods. Here are copy-paste implementations for common backends.
+
+### Disk / JSON files (Node.js)
+
+Git-trackable feedback — each submission becomes a JSON file in `.feedback/`.
+
+```ts
+import type { FeedtackAdapter, FeedbackItem, FeedtackPayload } from 'feedtack'
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const DIR = '.feedback'
+
+class DiskAdapter implements FeedtackAdapter {
+  async submit(payload: FeedtackPayload) {
+    await mkdir(DIR, { recursive: true })
+    const item: FeedbackItem = { payload, replies: [], resolutions: [], archives: [] }
+    await writeFile(join(DIR, `${payload.id}.json`), JSON.stringify(item, null, 2))
+  }
+
+  async reply(feedbackId: string, reply: Omit<FeedbackItem['replies'][0], 'id' | 'feedbackId'>) {
+    const item = await this.read(feedbackId)
+    item.replies.push({ ...reply, id: crypto.randomUUID(), feedbackId })
+    await this.write(feedbackId, item)
+  }
+
+  async resolve(feedbackId: string, resolution: Omit<FeedbackItem['resolutions'][0], 'feedbackId'>) {
+    const item = await this.read(feedbackId)
+    item.resolutions.push({ ...resolution, feedbackId })
+    await this.write(feedbackId, item)
+  }
+
+  async archive(feedbackId: string, userId: string) {
+    const item = await this.read(feedbackId)
+    item.archives.push({ feedbackId, archivedBy: { id: userId, name: '', role: '' }, timestamp: new Date().toISOString() })
+    await this.write(feedbackId, item)
+  }
+
+  async loadFeedback() {
+    await mkdir(DIR, { recursive: true })
+    const files = (await readdir(DIR)).filter((f) => f.endsWith('.json'))
+    return Promise.all(files.map(async (f) => JSON.parse(await readFile(join(DIR, f), 'utf-8')) as FeedbackItem))
+  }
+
+  private async read(id: string) { return JSON.parse(await readFile(join(DIR, `${id}.json`), 'utf-8')) as FeedbackItem }
+  private async write(id: string, item: FeedbackItem) { await writeFile(join(DIR, `${id}.json`), JSON.stringify(item, null, 2)) }
+}
+```
+
+### Supabase
+
+```ts
+import type { FeedtackAdapter, FeedbackItem, FeedtackFilter, FeedtackPayload } from 'feedtack'
+import type { SupabaseClient } from '@supabase/supabase-js'
+
+class SupabaseAdapter implements FeedtackAdapter {
+  constructor(private supabase: SupabaseClient) {}
+
+  async submit(payload: FeedtackPayload) {
+    await this.supabase.from('feedtack_submissions').insert({ id: payload.id, data: payload })
+  }
+
+  async reply(feedbackId: string, reply: Omit<FeedbackItem['replies'][0], 'id' | 'feedbackId'>) {
+    await this.supabase.from('feedtack_replies').insert({ feedback_id: feedbackId, ...reply })
+  }
+
+  async resolve(feedbackId: string, resolution: Omit<FeedbackItem['resolutions'][0], 'feedbackId'>) {
+    await this.supabase.from('feedtack_resolutions').insert({ feedback_id: feedbackId, ...resolution })
+  }
+
+  async archive(feedbackId: string, userId: string) {
+    await this.supabase.from('feedtack_archives').insert({ feedback_id: feedbackId, user_id: userId })
+  }
+
+  async loadFeedback(filter?: FeedtackFilter): Promise<FeedbackItem[]> {
+    let query = this.supabase.from('feedtack_submissions').select('*, feedtack_replies(*), feedtack_resolutions(*), feedtack_archives(*)')
+    if (filter?.pathname) query = query.eq('data->>page->>pathname', filter.pathname)
+    const { data } = await query
+    return (data ?? []).map((row) => ({
+      payload: row.data,
+      replies: row.feedtack_replies ?? [],
+      resolutions: row.feedtack_resolutions ?? [],
+      archives: row.feedtack_archives ?? [],
+    }))
+  }
+}
+```
+
 ## The payload
 
 Every pin emits a versioned JSON payload:

package/dist/index.d.ts

@@ -50,7 +50,10 @@ declare class WebhookAdapter implements FeedtackAdapter {
 declare function getViewportMeta(): FeedtackViewportMeta;
 declare function getPageMeta(): FeedtackPageMeta;
 declare function getDeviceMeta(): FeedtackDeviceMeta;
-declare function getPinCoords(event: MouseEvent): {
+declare function getPinCoords(event: {
+    clientX: number;
+    clientY: number;
+}): {
     x: number;
     y: number;
     xPct: number;

package/dist/react/index.d.ts

@@ -1,6 +1,11 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { F as FeedtackAdapter, o as FeedtackUser, n as FeedtackTheme, e as FeedbackItem } from '../theme-C-uctIoI.js';
+import { e as FeedbackItem, F as FeedtackAdapter, o as FeedtackUser, n as FeedtackTheme } from '../theme-C-uctIoI.js';
+
+interface FeedtackFlushEvent {
+    pathname: string;
+    items: FeedbackItem[];
+}
 
 interface FeedtackClasses {
     button?: string;
@@ -26,8 +31,14 @@ interface FeedtackProviderProps {
     disabled?: boolean;
     /** Render custom content inside a submitted pin marker. Receives the feedback item. */
     renderPinIcon?: (item: FeedbackItem) => React.ReactNode;
+    /** Called with batched feedback when user leaves a page or goes idle */
+    onFlush?: (event: FeedtackFlushEvent) => void;
+    /** Idle timeout in ms before flushing (default 5 min) */
+    flushIdleMs?: number;
+    /** User roles that trigger re-scope on reply (default: any non-'agent' role) */
+    rescopeRoles?: string[];
 }
-declare function FeedtackProvider({ children, adapter, currentUser, hotkey, adminOnly, theme, classes, sentimentLabels, onError, disabled, renderPinIcon, }: FeedtackProviderProps): react_jsx_runtime.JSX.Element;
+declare function FeedtackProvider({ children, adapter, currentUser, hotkey, adminOnly, theme, classes, sentimentLabels, onError, disabled, renderPinIcon, onFlush, flushIdleMs, rescopeRoles, }: FeedtackProviderProps): react_jsx_runtime.JSX.Element;
 
 interface FeedtackContextValue {
     activatePinMode: () => void;
@@ -38,4 +49,4 @@ interface FeedtackContextValue {
 /** Hook for host app to programmatically control feedtack */
 declare function useFeedtack(): FeedtackContextValue;
 
-export { type FeedtackClasses, FeedtackProvider, type FeedtackProviderProps, type FeedtackSentimentLabels, useFeedtack };
+export { type FeedtackClasses, type FeedtackFlushEvent, FeedtackProvider, type FeedtackProviderProps, type FeedtackSentimentLabels, useFeedtack };

package/dist/react/index.js

@@ -171,7 +171,7 @@ function ThreadPanel({
         item.replies.map((r) => /* @__PURE__ */ jsxs2(
           "div",
           {
-            style: { borderTop: "1px solid #f3f4f6", paddingTop: 8 },
+            style: { borderTop: "1px solid var(--ft-border)", paddingTop: 8 },
             children: [
               /* @__PURE__ */ jsx2("span", { style: { fontSize: 12, fontWeight: 600 }, children: r.author.name }),
               /* @__PURE__ */ jsx2("p", { style: { fontSize: 12 }, children: r.body })
@@ -190,7 +190,11 @@ function ThreadPanel({
               fontSize: 12,
               padding: 6,
               borderRadius: 6,
-              border: "1px solid #e5e7eb",
+              border: "1px solid var(--ft-border)",
+              background: "var(--ft-surface)",
+              color: "var(--ft-text)",
+              minHeight: 60,
+              resize: "vertical",
               marginTop: 4
             }
           }
@@ -243,14 +247,14 @@ function ThreadPanel({
 }
 
 // src/react/useFeedtackState.ts
-import { useCallback as useCallback2, useEffect as useEffect3, useState as useState2 } from "react";
+import { useCallback as useCallback3, useEffect as useEffect4, useState as useState2 } from "react";
 
 // src/react/useFeedtackDom.ts
 import { useEffect, useRef } from "react";
 
 // src/ui/styles.ts
 var FEEDTACK_DEFAULT_TOKENS = `
-  #feedtack-root {
+  #feedtack-root, .feedtack-form, .feedtack-thread {
     --ft-primary: #2563eb;
     --ft-primary-hover: #1d4ed8;
     --ft-bg: #ffffff;
@@ -532,21 +536,86 @@ function useFeedtackDom(theme, disabled) {
   return rootRef;
 }
 
+// src/react/useFeedtackFlush.ts
+import { useCallback, useEffect as useEffect2, useRef as useRef2 } from "react";
+var DEFAULT_IDLE_MS = 5 * 60 * 1e3;
+function useFeedtackFlush({
+  pathname,
+  feedbackItems,
+  onFlush,
+  flushIdleMs = DEFAULT_IDLE_MS,
+  disabled
+}) {
+  const flushedRef = useRef2(/* @__PURE__ */ new Set());
+  const prevPathnameRef = useRef2(pathname);
+  const idleTimerRef = useRef2(null);
+  const flush = useCallback(
+    (path, items) => {
+      if (!onFlush || flushedRef.current.has(path)) return;
+      const pageItems = items.filter((i) => i.payload.page.pathname === path);
+      if (pageItems.length === 0) return;
+      flushedRef.current.add(path);
+      onFlush({ pathname: path, items: pageItems });
+    },
+    [onFlush]
+  );
+  useEffect2(() => {
+    if (disabled || !onFlush) return;
+    const prev = prevPathnameRef.current;
+    prevPathnameRef.current = pathname;
+    if (prev !== pathname) {
+      flush(prev, feedbackItems);
+    }
+  }, [pathname, feedbackItems, flush, onFlush, disabled]);
+  useEffect2(() => {
+    if (disabled || !onFlush || flushIdleMs <= 0) return;
+    const resetTimer = () => {
+      if (idleTimerRef.current) clearTimeout(idleTimerRef.current);
+      idleTimerRef.current = setTimeout(() => {
+        flush(pathname, feedbackItems);
+      }, flushIdleMs);
+    };
+    const events = ["mousemove", "keydown", "scroll", "touchstart"];
+    for (const e of events)
+      window.addEventListener(e, resetTimer, { passive: true });
+    resetTimer();
+    return () => {
+      if (idleTimerRef.current) clearTimeout(idleTimerRef.current);
+      for (const e of events) window.removeEventListener(e, resetTimer);
+    };
+  }, [pathname, feedbackItems, flush, onFlush, flushIdleMs, disabled]);
+  useEffect2(() => {
+    if (disabled || !onFlush) return;
+    const handleUnload = () => flush(pathname, feedbackItems);
+    window.addEventListener("beforeunload", handleUnload);
+    return () => window.removeEventListener("beforeunload", handleUnload);
+  }, [pathname, feedbackItems, flush, onFlush, disabled]);
+  const clearFlushed = useCallback((path) => {
+    flushedRef.current.delete(path);
+  }, []);
+  return { clearFlushed };
+}
+
 // src/react/usePinMode.ts
-import { useCallback, useEffect as useEffect2, useState } from "react";
-function usePinMode({ hotkey, onDeactivate, disabled }) {
+import { useCallback as useCallback2, useEffect as useEffect3, useState } from "react";
+function usePinMode({
+  hotkey,
+  onDeactivate,
+  disabled,
+  isModalOpen
+}) {
   const [isActive, setIsActive] = useState(false);
   const [pendingPins, setPendingPins] = useState([]);
   const [selectedColor, setSelectedColor] = useState(PIN_PALETTE[0]);
   const [showForm, setShowForm] = useState(false);
-  const activate = useCallback(() => setIsActive(true), []);
-  const deactivate = useCallback(() => {
+  const activate = useCallback2(() => setIsActive(true), []);
+  const deactivate = useCallback2(() => {
     setIsActive(false);
     setPendingPins([]);
     setShowForm(false);
     onDeactivate?.();
   }, [onDeactivate]);
-  useEffect2(() => {
+  useEffect3(() => {
     if (isActive) {
       document.documentElement.classList.add("feedtack-crosshair");
     } else {
@@ -554,7 +623,7 @@ function usePinMode({ hotkey, onDeactivate, disabled }) {
     }
     return () => document.documentElement.classList.remove("feedtack-crosshair");
   }, [isActive]);
-  useEffect2(() => {
+  useEffect3(() => {
     if (disabled) return;
     const handler = (e) => {
       if (e.key === hotkey.toUpperCase() && e.shiftKey) {
@@ -563,7 +632,7 @@ function usePinMode({ hotkey, onDeactivate, disabled }) {
       if (e.key === "Escape") {
         deactivate();
       }
-      if (isActive && (e.key === "ArrowLeft" || e.key === "ArrowRight")) {
+      if (isActive && !isModalOpen && !showForm && (e.key === "ArrowLeft" || e.key === "ArrowRight")) {
         e.preventDefault();
         setSelectedColor((prev) => {
           const idx = PIN_PALETTE.indexOf(prev);
@@ -574,32 +643,53 @@ function usePinMode({ hotkey, onDeactivate, disabled }) {
     };
     window.addEventListener("keydown", handler);
     return () => window.removeEventListener("keydown", handler);
-  }, [hotkey, deactivate, isActive, disabled]);
-  const handlePageClick = useCallback(
-    (e) => {
-      if (!isActive) return;
-      const target = e.target;
+  }, [hotkey, deactivate, isActive, disabled, isModalOpen, showForm]);
+  const placePin = useCallback2(
+    (coords, target) => {
       if (target.closest("#feedtack-root, .feedtack-form, .feedtack-color-picker"))
         return;
-      e.preventDefault();
-      e.stopPropagation();
       setPendingPins((prev) => [
         ...prev,
         {
           color: selectedColor,
-          ...getPinCoords(e),
+          ...getPinCoords(coords),
           target: getTargetMeta(target)
         }
       ]);
       setShowForm(true);
     },
-    [isActive, selectedColor]
+    [selectedColor]
   );
-  useEffect2(() => {
+  const handlePageClick = useCallback2(
+    (e) => {
+      if (!isActive) return;
+      e.preventDefault();
+      e.stopPropagation();
+      placePin(e, e.target);
+    },
+    [isActive, placePin]
+  );
+  const handleTouchEnd = useCallback2(
+    (e) => {
+      if (!isActive) return;
+      const touch = e.changedTouches[0];
+      if (!touch) return;
+      const target = document.elementFromPoint(touch.clientX, touch.clientY);
+      if (!target) return;
+      e.preventDefault();
+      placePin(touch, target);
+    },
+    [isActive, placePin]
+  );
+  useEffect3(() => {
     if (disabled) return;
     document.addEventListener("click", handlePageClick, true);
-    return () => document.removeEventListener("click", handlePageClick, true);
-  }, [handlePageClick, disabled]);
+    document.addEventListener("touchend", handleTouchEnd, true);
+    return () => {
+      document.removeEventListener("click", handlePageClick, true);
+      document.removeEventListener("touchend", handleTouchEnd, true);
+    };
+  }, [handlePageClick, handleTouchEnd, disabled]);
   return {
     isActive,
     activate,
@@ -618,11 +708,16 @@ function useFeedtackState({
   hotkey,
   theme,
   onError,
-  disabled
+  disabled,
+  onFlush,
+  flushIdleMs,
+  rescopeRoles
 }) {
   useFeedtackDom(theme, disabled);
-  const [pathname, setPathname] = useState2(() => window.location.pathname);
-  useEffect3(() => {
+  const [pathname, setPathname] = useState2(
+    () => typeof window === "undefined" ? "/" : window.location.pathname
+  );
+  useEffect4(() => {
     const update = () => setPathname(window.location.pathname);
     const origPush = history.pushState.bind(history);
     const origReplace = history.replaceState.bind(history);
@@ -649,7 +744,7 @@ function useFeedtackState({
   const [loading, setLoading] = useState2(true);
   const [openThreadId, setOpenThreadId] = useState2(null);
   const [replyBody, setReplyBody] = useState2("");
-  const resetForm = useCallback2(() => {
+  const resetForm = useCallback3(() => {
     setComment("");
     setSentiment(null);
     setCommentError(false);
@@ -657,12 +752,20 @@ function useFeedtackState({
   const pinMode = usePinMode({
     hotkey,
     disabled,
+    isModalOpen: openThreadId !== null,
     onDeactivate: () => {
       resetForm();
       setOpenThreadId(null);
     }
   });
-  useEffect3(() => {
+  const { clearFlushed } = useFeedtackFlush({
+    pathname,
+    feedbackItems,
+    onFlush,
+    flushIdleMs,
+    disabled
+  });
+  useEffect4(() => {
     setLoading(true);
     adapter.loadFeedback({ pathname }).then(setFeedbackItems).catch((err) => onError?.(err)).finally(() => setLoading(false));
   }, [adapter, onError, pathname]);
@@ -710,19 +813,26 @@ function useFeedtackState({
         body,
         timestamp: ts
       });
-      updateItem(feedbackId, (item) => ({
-        ...item,
-        replies: [
-          ...item.replies,
-          {
-            id: generateId(),
-            feedbackId,
-            author: currentUser,
-            body,
-            timestamp: ts
-          }
-        ]
-      }));
+      updateItem(feedbackId, (item) => {
+        const updated = {
+          ...item,
+          replies: [
+            ...item.replies,
+            {
+              id: generateId(),
+              feedbackId,
+              author: currentUser,
+              body,
+              timestamp: ts
+            }
+          ]
+        };
+        const triggerRescope = rescopeRoles ? rescopeRoles.includes(currentUser.role) : currentUser.role !== "agent";
+        if (triggerRescope && updated.resolutions.length === 0 && onFlush) {
+          clearFlushed(pathname);
+        }
+        return updated;
+      });
       setReplyBody("");
     } catch (err) {
       onError?.(err);
@@ -762,6 +872,9 @@ function useFeedtackState({
       onError?.(err);
     }
   };
+  const isArchivedForUser = (item) => item.archives.some((a) => a.archivedBy.id === currentUser.id);
+  const hasUnread = (item) => item.replies.length > 0;
+  const hasValidPins = (item) => Array.isArray(item.payload?.pins) && item.payload.pins.length > 0;
   return {
     ...pinMode,
     isPinModeActive: pinMode.isActive,
@@ -785,9 +898,9 @@ function useFeedtackState({
     handleReply,
     handleResolve,
     handleArchive,
-    isArchivedForUser: (item) => item.archives.some((a) => a.archivedBy.id === currentUser.id),
-    hasUnread: (item) => item.replies.length > 0,
-    hasValidPins: (item) => Array.isArray(item.payload?.pins) && item.payload.pins.length > 0
+    isArchivedForUser,
+    hasUnread,
+    hasValidPins
   };
 }
 
@@ -804,7 +917,10 @@ function FeedtackProvider({
   sentimentLabels = {},
   onError,
   disabled = false,
-  renderPinIcon
+  renderPinIcon,
+  onFlush,
+  flushIdleMs,
+  rescopeRoles
 }) {
   const state = useFeedtackState({
     adapter,
@@ -812,7 +928,10 @@ function FeedtackProvider({
     hotkey,
     theme,
     onError,
-    disabled
+    disabled,
+    onFlush,
+    flushIdleMs,
+    rescopeRoles
   });
   const firstPin = state.pendingPins[0];
   const formPos = firstPin ? getAnchoredPosition(firstPin.x, firstPin.y) : {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feedtack",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Click anywhere. Drop a pin. Get a payload a developer can act on.",
   "type": "module",
   "license": "MIT",