@ewjdev/anyclick-react 1.1.0 → 1.2.0

package/README.md

@@ -23,21 +23,17 @@ npm install @ewjdev/anyclick-react
 ## Quick Start
 
 ```tsx
-'use client';
+"use client";
 
-import { AnyclickProvider } from '@ewjdev/anyclick-react';
-import { createHttpAdapter } from '@ewjdev/anyclick-github';
+import { AnyclickProvider } from "@ewjdev/anyclick-react";
+import { createHttpAdapter } from "@ewjdev/anyclick-github";
 
 const adapter = createHttpAdapter({
-  endpoint: '/api/feedback',
+  endpoint: "/api/feedback",
 });
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <AnyclickProvider adapter={adapter}>
-      {children}
-    </AnyclickProvider>
-  );
+  return <AnyclickProvider adapter={adapter}>{children}</AnyclickProvider>;
 }
 ```
 
@@ -55,39 +51,39 @@ That's it! Users can now right-click any element to submit feedback.
 
 ## Props
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `adapter` | `FeedbackAdapter` | Required. The adapter for submitting feedback |
-| `menuItems` | `FeedbackMenuItem[]` | Custom menu items |
-| `metadata` | `Record<string, unknown>` | Additional data included with every submission |
-| `theme` | `AnyclickTheme \| null` | Theme configuration (inherits from parent) |
-| `scoped` | `boolean` | Limit capture to this provider's children only |
-| `disabled` | `boolean` | Disable feedback capture |
-| `onSubmitSuccess` | `(payload) => void` | Success callback |
-| `onSubmitError` | `(error, payload) => void` | Error callback |
+| Prop              | Type                       | Description                                    |
+| ----------------- | -------------------------- | ---------------------------------------------- |
+| `adapter`         | `FeedbackAdapter`          | Required. The adapter for submitting feedback  |
+| `menuItems`       | `FeedbackMenuItem[]`       | Custom menu items                              |
+| `metadata`        | `Record<string, unknown>`  | Additional data included with every submission |
+| `theme`           | `AnyclickTheme \| null`    | Theme configuration (inherits from parent)     |
+| `scoped`          | `boolean`                  | Limit capture to this provider's children only |
+| `disabled`        | `boolean`                  | Disable feedback capture                       |
+| `onSubmitSuccess` | `(payload) => void`        | Success callback                               |
+| `onSubmitError`   | `(error, payload) => void` | Error callback                                 |
 
 ## Scoped Providers
 
 Limit feedback capture to specific sections of your app:
 
 ```tsx
-import { AnyclickProvider } from '@ewjdev/anyclick-react';
+import { AnyclickProvider } from "@ewjdev/anyclick-react";
 
 function App() {
   return (
     <AnyclickProvider adapter={globalAdapter}>
       {/* Global feedback works everywhere */}
       <Header />
-      
+
       {/* Scoped provider - separate configuration */}
-      <AnyclickProvider 
+      <AnyclickProvider
         adapter={dashboardAdapter}
         scoped
         menuItems={dashboardMenuItems}
       >
         <Dashboard />
       </AnyclickProvider>
-      
+
       <Footer />
     </AnyclickProvider>
   );
@@ -99,33 +95,33 @@ function App() {
 Override themes for specific sections:
 
 ```tsx
-import { AnyclickProvider } from '@ewjdev/anyclick-react';
+import { AnyclickProvider } from "@ewjdev/anyclick-react";
 
 function App() {
   return (
-    <AnyclickProvider 
+    <AnyclickProvider
       adapter={adapter}
       theme={{
         highlightConfig: {
-          colors: { targetColor: '#3b82f6' }
-        }
+          colors: { targetColor: "#3b82f6" },
+        },
       }}
     >
       {/* Uses blue highlights */}
       <MainContent />
-      
+
       {/* Uses red highlights (overrides parent) */}
-      <AnyclickProvider 
+      <AnyclickProvider
         scoped
         theme={{
           highlightConfig: {
-            colors: { targetColor: '#ef4444' }
-          }
+            colors: { targetColor: "#ef4444" },
+          },
         }}
       >
         <WarningSection />
       </AnyclickProvider>
-      
+
       {/* Disable anyclick for this section */}
       <AnyclickProvider scoped theme={{ disabled: true }}>
         <SensitiveArea />
@@ -150,24 +146,24 @@ interface AnyclickTheme {
 ## Custom Menu Items
 
 ```tsx
-import { Bug, Lightbulb, Heart } from 'lucide-react';
+import { Bug, Lightbulb, Heart } from "lucide-react";
 
 const menuItems = [
-  { 
-    type: 'bug', 
-    label: 'Report Bug', 
+  {
+    type: "bug",
+    label: "Report Bug",
     icon: <Bug className="w-4 h-4" />,
     showComment: true,
   },
-  { 
-    type: 'feature', 
-    label: 'Suggest Feature', 
+  {
+    type: "feature",
+    label: "Suggest Feature",
     icon: <Lightbulb className="w-4 h-4" />,
     showComment: true,
   },
-  { 
-    type: 'love', 
-    label: 'Love It!', 
+  {
+    type: "love",
+    label: "Love It!",
     icon: <Heart className="w-4 h-4" />,
     showComment: false,
   },
@@ -175,20 +171,20 @@ const menuItems = [
 
 <AnyclickProvider adapter={adapter} menuItems={menuItems}>
   {children}
-</AnyclickProvider>
+</AnyclickProvider>;
 ```
 
 ## Role-Based Filtering
 
 ```tsx
-import { filterMenuItemsByRole } from '@ewjdev/anyclick-react';
+import { filterMenuItemsByRole } from "@ewjdev/anyclick-react";
 
 const allMenuItems = [
-  { type: 'bug', label: 'Report Bug' },
-  { type: 'debug', label: 'Debug Info', requiredRoles: ['developer'] },
+  { type: "bug", label: "Report Bug" },
+  { type: "debug", label: "Debug Info", requiredRoles: ["developer"] },
 ];
 
-const userContext = { roles: ['user', 'developer'] };
+const userContext = { roles: ["user", "developer"] };
 const menuItems = filterMenuItemsByRole(allMenuItems, userContext);
 ```
 
@@ -201,10 +197,10 @@ const menuItems = filterMenuItemsByRole(allMenuItems, userContext);
     highlightConfig: {
       enabled: true,
       colors: {
-        targetColor: '#3b82f6',
-        containerColor: '#8b5cf6',
+        targetColor: "#3b82f6",
+        containerColor: "#8b5cf6",
       },
-      containerSelectors: ['[data-component]', '.card'],
+      containerSelectors: ["[data-component]", ".card"],
     },
   }}
 >
@@ -217,23 +213,17 @@ const menuItems = filterMenuItemsByRole(allMenuItems, userContext);
 Access anyclick context from child components:
 
 ```tsx
-import { useAnyclick } from '@ewjdev/anyclick-react';
+import { useAnyclick } from "@ewjdev/anyclick-react";
 
 function MyComponent() {
-  const { 
-    isSubmitting, 
-    openMenu, 
-    closeMenu,
-    theme,
-    scoped,
-    providerId,
-  } = useAnyclick();
-  
+  const { isSubmitting, openMenu, closeMenu, theme, scoped, providerId } =
+    useAnyclick();
+
   // Open menu programmatically
   const handleClick = (event) => {
     openMenu(event.currentTarget, { x: event.clientX, y: event.clientY });
   };
-  
+
   return <button onClick={handleClick}>Open Feedback</button>;
 }
 ```
@@ -244,10 +234,10 @@ The `FeedbackProvider` component has been renamed to `AnyclickProvider`. The old
 
 ```tsx
 // Old (deprecated)
-import { FeedbackProvider, useFeedback } from '@ewjdev/anyclick-react';
+import { FeedbackProvider, useFeedback } from "@ewjdev/anyclick-react";
 
 // New (recommended)
-import { AnyclickProvider, useAnyclick } from '@ewjdev/anyclick-react';
+import { AnyclickProvider, useAnyclick } from "@ewjdev/anyclick-react";
 ```
 
 ## Documentation

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { FeedbackAdapter, FeedbackType, FeedbackPayload, ScreenshotConfig, ScreenshotData } from '@ewjdev/anyclick-core';
-export { DEFAULT_SCREENSHOT_CONFIG, DEFAULT_SENSITIVE_SELECTORS, ElementContext, FeedbackAdapter, FeedbackPayload, FeedbackType, PageContext, ScreenshotCapture, ScreenshotCaptureMode, ScreenshotConfig, ScreenshotData, captureAllScreenshots, captureScreenshot, estimateTotalSize, formatBytes, isScreenshotSupported } from '@ewjdev/anyclick-core';
+import { AnyclickAdapter, AnyclickTriggerEvent, AnyclickType, AnyclickPayload, ScreenshotConfig, ScreenshotData, AnyclickMenuEvent } from '@ewjdev/anyclick-core';
+export { AnyclickAdapter, AnyclickPayload, AnyclickType, DEFAULT_SCREENSHOT_CONFIG, DEFAULT_SENSITIVE_SELECTORS, ElementContext, PageContext, ScreenshotCapture, ScreenshotCaptureMode, ScreenshotConfig, ScreenshotData, captureAllScreenshots, captureScreenshot, estimateTotalSize, formatBytes, isScreenshotSupported } from '@ewjdev/anyclick-core';
 import * as react from 'react';
 import { ReactNode, CSSProperties } from 'react';
 import * as zustand from 'zustand';
@@ -20,7 +20,30 @@ interface AnyclickTheme {
     screenshotConfig?: ScreenshotConfig;
     /** Whether anyclick functionality is disabled in this theme */
     disabled?: boolean;
+    /**
+     * Enable fun mode (go-kart cursor) within this scoped provider.
+     * When true/configured, a FunModeBridge can hand off the track to the pointer.
+     */
+    funMode?: boolean | FunModeThemeConfig;
+}
+/**
+ * Optional fun mode configuration (forwarded to pointer fun mode)
+ */
+interface FunModeThemeConfig {
+    /** Whether fun mode is enabled (default: true) */
+    enabled?: boolean;
+    /** Optional max speed override for this provider */
+    maxSpeed?: number;
+    /** Optional acceleration override */
+    acceleration?: number;
 }
+/**
+ * Menu positioning modes
+ * - static: Menu stays at exact click position (may go off-screen)
+ * - inView: Menu adjusts position to stay fully visible in viewport
+ * - dynamic: User can drag the menu to reposition it
+ */
+type MenuPositionMode = "static" | "inView" | "dynamic";
 /**
  * Configuration for highlight colors
  */
@@ -48,11 +71,11 @@ interface HighlightConfig {
     minChildrenForContainer?: number;
 }
 /**
- * Menu item displayed in the feedback context menu
+ * Menu item displayed in the Anyclick context menu
  */
-interface FeedbackMenuItem {
+interface AnyclickMenuItem {
     /** Feedback type for this option (use unique identifier for parent items with children) */
-    type: FeedbackType;
+    type: AnyclickType;
     /** Display label */
     label: string;
     /** Optional icon */
@@ -62,12 +85,21 @@ interface FeedbackMenuItem {
     /** Optional role(s) required to see this menu item */
     requiredRoles?: string[];
     /** Child menu items (creates a submenu) */
-    children?: FeedbackMenuItem[];
+    children?: AnyclickMenuItem[];
+    /**
+     * Optional click handler for custom behavior.
+     * Return `false` (or a Promise resolving to false) to skip the default submission flow.
+     */
+    onClick?: (context: {
+        targetElement: Element | null;
+        containerElement: Element | null;
+        closeMenu: () => void;
+    }) => void | boolean | Promise<void | boolean>;
 }
 /**
  * User context for role-based menu filtering
  */
-interface FeedbackUserContext {
+interface AnyclickUserContext {
     /** User's role(s) */
     roles?: string[];
     /** User ID */
@@ -78,22 +110,25 @@ interface FeedbackUserContext {
 /**
  * Filter menu items based on user context
  */
-declare function filterMenuItemsByRole(items: FeedbackMenuItem[], userContext?: FeedbackUserContext): FeedbackMenuItem[];
+declare function filterMenuItemsByRole(items: AnyclickMenuItem[], userContext?: AnyclickUserContext): AnyclickMenuItem[];
 /**
  * Props for the AnyclickProvider component
  */
 interface AnyclickProviderProps {
-    /** The adapter to use for submitting feedback */
-    adapter: FeedbackAdapter;
+    /** Header content */
+    header?: ReactNode | null;
+    /** The adapter to use for submitting anyclick */
+    adapter: AnyclickAdapter;
     /** Child components */
     children: ReactNode;
     /**
-     * Filter function to determine if feedback should be captured for a target element
-     * Return true to allow feedback, false to ignore
+     * Filter function to determine if anyclick should be captured for a target element
+     * Return true to allow anyclick, false to ignore
+     * Accepts both MouseEvent (right-click) and TouchEvent (press-and-hold)
      */
-    targetFilter?: (event: MouseEvent, target: Element) => boolean;
+    targetFilter?: (event: AnyclickTriggerEvent, target: Element) => boolean;
     /** Custom menu items (defaults to Issue, Feature, Like) */
-    menuItems?: FeedbackMenuItem[];
+    menuItems?: AnyclickMenuItem[];
     /** Maximum length for innerText capture */
     maxInnerTextLength?: number;
     /** Maximum length for outerHTML capture */
@@ -107,9 +142,9 @@ interface AnyclickProviderProps {
     /** Additional metadata to include with every submission */
     metadata?: Record<string, unknown>;
     /** Callback after successful submission */
-    onSubmitSuccess?: (payload: FeedbackPayload) => void;
+    onSubmitSuccess?: (payload: AnyclickPayload) => void;
     /** Callback after failed submission */
-    onSubmitError?: (error: Error, payload: FeedbackPayload) => void;
+    onSubmitError?: (error: Error, payload: AnyclickPayload) => void;
     /** Custom styles for the context menu */
     menuStyle?: CSSProperties;
     /** Custom class name for the context menu */
@@ -132,27 +167,29 @@ interface AnyclickProviderProps {
      * Set to null or { disabled: true } to disable anyclick in this subtree.
      */
     theme?: AnyclickTheme | null;
+    /** Duration in ms to hold touch before triggering context menu (default: 500) */
+    touchHoldDurationMs?: number;
+    /** Maximum movement in px before touch hold is cancelled (default: 10) */
+    touchMoveThreshold?: number;
+    /** Menu positioning mode (default: 'inView') */
+    menuPositionMode?: MenuPositionMode;
 }
-/**
- * @deprecated Use AnyclickProviderProps instead
- */
-type FeedbackProviderProps = AnyclickProviderProps;
 /**
  * Context value exposed by AnyclickProvider
  */
 interface AnyclickContextValue {
-    /** Whether feedback is currently enabled */
+    /** Whether anyclick is currently enabled */
     isEnabled: boolean;
     /** Whether a submission is in progress */
     isSubmitting: boolean;
-    /** Submit feedback for a specific element */
-    submitFeedback: (element: Element, type: FeedbackType, comment?: string) => Promise<void>;
-    /** Open the feedback menu programmatically */
+    /** Submit anyclick for a specific element */
+    submitAnyclick: (element: Element, type: AnyclickType, comment?: string) => Promise<void>;
+    /** Open the anyclick menu programmatically */
     openMenu: (element: Element, position: {
         x: number;
         y: number;
     }) => void;
-    /** Close the feedback menu */
+    /** Close the anyclick menu */
     closeMenu: () => void;
     /** The current merged theme (inherited from ancestors) */
     theme: AnyclickTheme;
@@ -161,10 +198,6 @@ interface AnyclickContextValue {
     /** The provider's unique ID */
     providerId: string;
 }
-/**
- * @deprecated Use AnyclickContextValue instead
- */
-type FeedbackContextValue = AnyclickContextValue;
 /**
  * Props for the context menu component
  */
@@ -176,14 +209,14 @@ interface ContextMenuProps {
         x: number;
         y: number;
     };
-    /** Target element for feedback */
+    /** Target element for anyclick */
     targetElement: Element | null;
     /** Container element found by highlight logic */
     containerElement: Element | null;
     /** Menu items to display */
-    items: FeedbackMenuItem[];
+    items: AnyclickMenuItem[];
     /** Callback when an item is selected */
-    onSelect: (type: FeedbackType, comment?: string, screenshots?: ScreenshotData) => void;
+    onSelect: (type: AnyclickType, comment?: string, screenshots?: ScreenshotData) => void;
     /** Callback when menu is closed */
     onClose: () => void;
     /** Whether submission is in progress */
@@ -196,6 +229,12 @@ interface ContextMenuProps {
     highlightConfig?: HighlightConfig;
     /** Configuration for screenshot capture */
     screenshotConfig?: ScreenshotConfig;
+    /** Menu positioning mode (default: 'inView') */
+    positionMode?: MenuPositionMode;
+    /** Header content */
+    header?: ReactNode;
+    /** Footer content */
+    footer?: ReactNode;
 }
 /**
  * Props for the screenshot preview component
@@ -219,16 +258,23 @@ interface ScreenshotPreviewProps {
  * AnyclickProvider component - wraps your app to enable feedback capture
  * Supports scoped providers and nested theming
  */
-declare function AnyclickProvider({ adapter, children, targetFilter, menuItems, maxInnerTextLength, maxOuterHTMLLength, maxAncestors, cooldownMs, stripAttributes, metadata, onSubmitSuccess, onSubmitError, menuStyle, menuClassName, disabled, highlightConfig, screenshotConfig, scoped, theme, }: AnyclickProviderProps): react_jsx_runtime.JSX.Element;
+declare function AnyclickProvider({ adapter, children, targetFilter, menuItems, maxInnerTextLength, maxOuterHTMLLength, maxAncestors, cooldownMs, stripAttributes, metadata, onSubmitSuccess, onSubmitError, menuStyle, menuClassName, disabled, highlightConfig, header, screenshotConfig, scoped, theme, touchHoldDurationMs, touchMoveThreshold, }: AnyclickProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * @deprecated Use AnyclickProvider instead
  */
 declare const FeedbackProvider: typeof AnyclickProvider;
 
+/**
+ * FunModeBridge watches Anyclick scoped providers and toggles the pointer
+ * into fun mode (go-kart) when the cursor is within a provider with funMode enabled.
+ * Requires a PointerProvider higher in the tree.
+ */
+declare function FunModeBridge(): null;
+
 /**
  * Context menu component for selecting feedback type
  */
-declare function ContextMenu({ visible, position, targetElement, containerElement, items, onSelect, onClose, isSubmitting, style, className, highlightConfig, screenshotConfig, }: ContextMenuProps): react_jsx_runtime.JSX.Element | null;
+declare function ContextMenu({ visible, position, targetElement, containerElement, items, onSelect, onClose, isSubmitting, style, className, highlightConfig, screenshotConfig, positionMode, header, footer, }: ContextMenuProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Screenshot preview component - shows captured screenshots before sending
@@ -272,7 +318,7 @@ interface ProviderInstance {
     /** Depth in the provider hierarchy (0 = root) */
     depth: number;
     /** Handler to call when an event occurs in this provider's scope */
-    onContextMenu?: (event: MouseEvent, element: Element) => void;
+    onContextMenu?: (event: AnyclickMenuEvent, element: Element) => boolean | void;
 }
 /**
  * Provider registry store state
@@ -314,6 +360,12 @@ interface ProviderStore {
      * in areas where a disabled scoped provider should block them
      */
     isElementInDisabledScope: (element: Element) => boolean;
+    /**
+     * Check if an element is inside any scoped provider's container (enabled or not)
+     * This is used to prevent the global provider from handling touch events
+     * that should be handled by a scoped provider instead
+     */
+    isElementInAnyScopedProvider: (element: Element) => boolean;
 }
 declare function generateProviderId(): string;
 /**
@@ -396,4 +448,4 @@ declare function applyHighlights(targetElement: Element, config?: HighlightConfi
     container: Element | null;
 };
 
-export { AnyclickContext, type AnyclickContextValue, AnyclickProvider, type AnyclickProviderProps, type AnyclickTheme, ContextMenu, type ContextMenuProps, FeedbackContext, type FeedbackContextValue, type FeedbackMenuItem, FeedbackProvider, type FeedbackProviderProps, type FeedbackUserContext, type HighlightColors, type HighlightConfig, type ProviderInstance, ScreenshotPreview, type ScreenshotPreviewProps, applyHighlights, clearHighlights, darkMenuStyles, defaultContainerSelectors, defaultHighlightColors, dispatchContextMenuEvent, filterMenuItemsByRole, findContainerParent, generateProviderId, highlightContainer, highlightTarget, menuCSSVariables, menuStyles, useAnyclick, useFeedback, useProviderStore };
+export { AnyclickContext, type AnyclickContextValue, type AnyclickMenuItem, AnyclickProvider, type AnyclickProviderProps, type AnyclickTheme, type AnyclickUserContext, ContextMenu, type ContextMenuProps, FeedbackContext, FeedbackProvider, FunModeBridge, type FunModeThemeConfig, type HighlightColors, type HighlightConfig, type MenuPositionMode, type ProviderInstance, ScreenshotPreview, type ScreenshotPreviewProps, applyHighlights, clearHighlights, darkMenuStyles, defaultContainerSelectors, defaultHighlightColors, dispatchContextMenuEvent, filterMenuItemsByRole, findContainerParent, generateProviderId, highlightContainer, highlightTarget, menuCSSVariables, menuStyles, useAnyclick, useFeedback, useProviderStore };