@ewjdev/anyclick-react 0.1.0 → 1.1.1

package/README.md

@@ -23,21 +23,17 @@ npm install @ewjdev/anyclick-react
 ## Quick Start
 
 ```tsx
-'use client';
+"use client";
 
-import { FeedbackProvider } 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 (
-    <FeedbackProvider adapter={adapter}>
-      {children}
-    </FeedbackProvider>
-  );
+  return <AnyclickProvider adapter={adapter}>{children}</AnyclickProvider>;
 }
 ```
 
@@ -50,102 +46,200 @@ That's it! Users can now right-click any element to submit feedback.
 - 📸 **Screenshot Capture** - Automatic screenshots of target, container, and page
 - 🔒 **Role-Based Menu Items** - Show different options based on user roles
 - 📱 **Submenus** - Organize menu items with nested submenus
+- 🎯 **Scoped Providers** - Limit feedback capture to specific components
+- 🎨 **Nested Theming** - Override themes for specific sections of your app
 
 ## 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 |
-| `highlightConfig` | `HighlightConfig` | Configure element highlighting |
-| `screenshotConfig` | `ScreenshotConfig` | Configure screenshot capture |
-| `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";
+
+function App() {
+  return (
+    <AnyclickProvider adapter={globalAdapter}>
+      {/* Global feedback works everywhere */}
+      <Header />
+
+      {/* Scoped provider - separate configuration */}
+      <AnyclickProvider
+        adapter={dashboardAdapter}
+        scoped
+        menuItems={dashboardMenuItems}
+      >
+        <Dashboard />
+      </AnyclickProvider>
+
+      <Footer />
+    </AnyclickProvider>
+  );
+}
+```
+
+## Nested Theming
+
+Override themes for specific sections:
+
+```tsx
+import { AnyclickProvider } from "@ewjdev/anyclick-react";
+
+function App() {
+  return (
+    <AnyclickProvider
+      adapter={adapter}
+      theme={{
+        highlightConfig: {
+          colors: { targetColor: "#3b82f6" },
+        },
+      }}
+    >
+      {/* Uses blue highlights */}
+      <MainContent />
+
+      {/* Uses red highlights (overrides parent) */}
+      <AnyclickProvider
+        scoped
+        theme={{
+          highlightConfig: {
+            colors: { targetColor: "#ef4444" },
+          },
+        }}
+      >
+        <WarningSection />
+      </AnyclickProvider>
+
+      {/* Disable anyclick for this section */}
+      <AnyclickProvider scoped theme={{ disabled: true }}>
+        <SensitiveArea />
+      </AnyclickProvider>
+    </AnyclickProvider>
+  );
+}
+```
+
+## Theme Configuration
+
+```tsx
+interface AnyclickTheme {
+  menuStyle?: CSSProperties;
+  menuClassName?: string;
+  highlightConfig?: HighlightConfig;
+  screenshotConfig?: ScreenshotConfig;
+  disabled?: boolean; // Disable anyclick in this subtree
+}
+```
 
 ## 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,
   },
 ];
 
-<FeedbackProvider adapter={adapter} menuItems={menuItems}>
+<AnyclickProvider adapter={adapter} menuItems={menuItems}>
   {children}
-</FeedbackProvider>
+</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);
 ```
 
 ## Highlight Configuration
 
 ```tsx
-<FeedbackProvider
+<AnyclickProvider
   adapter={adapter}
-  highlightConfig={{
-    enabled: true,
-    colors: {
-      targetColor: '#3b82f6',
-      containerColor: '#8b5cf6',
+  theme={{
+    highlightConfig: {
+      enabled: true,
+      colors: {
+        targetColor: "#3b82f6",
+        containerColor: "#8b5cf6",
+      },
+      containerSelectors: ["[data-component]", ".card"],
     },
-    containerSelectors: ['[data-component]', '.card'],
   }}
 >
   {children}
-</FeedbackProvider>
+</AnyclickProvider>
 ```
 
-## useFeedback Hook
+## useAnyclick Hook
 
-Access feedback context from child components:
+Access anyclick context from child components:
 
 ```tsx
-import { useFeedback } from '@ewjdev/anyclick-react';
+import { useAnyclick } from "@ewjdev/anyclick-react";
 
 function MyComponent() {
-  const { isSubmitting, openMenu, closeMenu } = useFeedback();
-  
+  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>;
 }
 ```
 
+## Migration from FeedbackProvider
+
+The `FeedbackProvider` component has been renamed to `AnyclickProvider`. The old name is still exported for backward compatibility but is deprecated:
+
+```tsx
+// Old (deprecated)
+import { FeedbackProvider, useFeedback } from "@ewjdev/anyclick-react";
+
+// New (recommended)
+import { AnyclickProvider, useAnyclick } from "@ewjdev/anyclick-react";
+```
+
 ## Documentation
 
 For full documentation, visit [anyclick.ewj.dev/docs/react](https://anyclick.ewj.dev/docs/react)

package/dist/index.d.mts

@@ -1,9 +1,33 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { FeedbackAdapter, FeedbackType, FeedbackPayload, ScreenshotConfig, ScreenshotData } from '@ewjdev/anyclick-core';
+import { FeedbackAdapter, FeedbackTriggerEvent, FeedbackType, FeedbackPayload, ScreenshotConfig, ScreenshotData, FeedbackMenuEvent } 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 * as react from 'react';
 import { ReactNode, CSSProperties } from 'react';
+import * as zustand from 'zustand';
 
+/**
+ * Theme configuration for AnyclickProvider
+ * Supports nested theming with inheritance
+ */
+interface AnyclickTheme {
+    /** Custom styles for the context menu */
+    menuStyle?: CSSProperties;
+    /** Custom class name for the context menu */
+    menuClassName?: string;
+    /** Configuration for element highlighting */
+    highlightConfig?: HighlightConfig;
+    /** Configuration for screenshot capture */
+    screenshotConfig?: ScreenshotConfig;
+    /** Whether anyclick functionality is disabled in this theme */
+    disabled?: boolean;
+}
+/**
+ * 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
  */
@@ -63,9 +87,9 @@ interface FeedbackUserContext {
  */
 declare function filterMenuItemsByRole(items: FeedbackMenuItem[], userContext?: FeedbackUserContext): FeedbackMenuItem[];
 /**
- * Props for the FeedbackProvider component
+ * Props for the AnyclickProvider component
  */
-interface FeedbackProviderProps {
+interface AnyclickProviderProps {
     /** The adapter to use for submitting feedback */
     adapter: FeedbackAdapter;
     /** Child components */
@@ -73,8 +97,9 @@ interface FeedbackProviderProps {
     /**
      * Filter function to determine if feedback should be captured for a target element
      * Return true to allow feedback, false to ignore
+     * Accepts both MouseEvent (right-click) and TouchEvent (press-and-hold)
      */
-    targetFilter?: (event: MouseEvent, target: Element) => boolean;
+    targetFilter?: (event: FeedbackTriggerEvent, target: Element) => boolean;
     /** Custom menu items (defaults to Issue, Feature, Like) */
     menuItems?: FeedbackMenuItem[];
     /** Maximum length for innerText capture */
@@ -103,11 +128,33 @@ interface FeedbackProviderProps {
     highlightConfig?: HighlightConfig;
     /** Configuration for screenshot capture */
     screenshotConfig?: ScreenshotConfig;
+    /**
+     * Whether to scope this provider to its children only.
+     * When true, events will only be captured for elements within this provider's subtree.
+     * When false (default), events are captured for the entire document.
+     */
+    scoped?: boolean;
+    /**
+     * Theme configuration for this provider.
+     * Themes are inherited from parent providers and merged (child overrides parent).
+     * 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;
 }
 /**
- * Context value exposed by FeedbackProvider
+ * @deprecated Use AnyclickProviderProps instead
+ */
+type FeedbackProviderProps = AnyclickProviderProps;
+/**
+ * Context value exposed by AnyclickProvider
  */
-interface FeedbackContextValue {
+interface AnyclickContextValue {
     /** Whether feedback is currently enabled */
     isEnabled: boolean;
     /** Whether a submission is in progress */
@@ -121,7 +168,17 @@ interface FeedbackContextValue {
     }) => void;
     /** Close the feedback menu */
     closeMenu: () => void;
+    /** The current merged theme (inherited from ancestors) */
+    theme: AnyclickTheme;
+    /** Whether this provider is scoped */
+    scoped: boolean;
+    /** The provider's unique ID */
+    providerId: string;
 }
+/**
+ * @deprecated Use AnyclickContextValue instead
+ */
+type FeedbackContextValue = AnyclickContextValue;
 /**
  * Props for the context menu component
  */
@@ -153,6 +210,8 @@ interface ContextMenuProps {
     highlightConfig?: HighlightConfig;
     /** Configuration for screenshot capture */
     screenshotConfig?: ScreenshotConfig;
+    /** Menu positioning mode (default: 'inView') */
+    positionMode?: MenuPositionMode;
 }
 /**
  * Props for the screenshot preview component
@@ -173,14 +232,19 @@ interface ScreenshotPreviewProps {
 }
 
 /**
- * FeedbackProvider component - wraps your app to enable feedback capture
+ * AnyclickProvider component - wraps your app to enable feedback capture
+ * Supports scoped providers and nested theming
  */
-declare function FeedbackProvider({ adapter, children, targetFilter, menuItems, maxInnerTextLength, maxOuterHTMLLength, maxAncestors, cooldownMs, stripAttributes, metadata, onSubmitSuccess, onSubmitError, menuStyle, menuClassName, disabled, highlightConfig, screenshotConfig, }: FeedbackProviderProps): react_jsx_runtime.JSX.Element;
+declare function AnyclickProvider({ adapter, children, targetFilter, menuItems, maxInnerTextLength, maxOuterHTMLLength, maxAncestors, cooldownMs, stripAttributes, metadata, onSubmitSuccess, onSubmitError, menuStyle, menuClassName, disabled, highlightConfig, screenshotConfig, scoped, theme, touchHoldDurationMs, touchMoveThreshold, }: AnyclickProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * @deprecated Use AnyclickProvider instead
+ */
+declare const FeedbackProvider: typeof AnyclickProvider;
 
 /**
  * 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, }: ContextMenuProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Screenshot preview component - shows captured screenshots before sending
@@ -188,15 +252,133 @@ declare function ContextMenu({ visible, position, targetElement, containerElemen
 declare function ScreenshotPreview({ screenshots, isLoading, onConfirm, onCancel, onRetake, isSubmitting, }: ScreenshotPreviewProps): react_jsx_runtime.JSX.Element;
 
 /**
- * React context for feedback functionality
+ * React context for anyclick functionality
+ */
+declare const AnyclickContext: react.Context<AnyclickContextValue | null>;
+/**
+ * @deprecated Use AnyclickContext instead
+ */
+declare const FeedbackContext: react.Context<AnyclickContextValue | null>;
+/**
+ * Hook to access anyclick context
+ * @throws Error if used outside of AnyclickProvider
+ */
+declare function useAnyclick(): AnyclickContextValue;
+/**
+ * @deprecated Use useAnyclick instead
+ */
+declare function useFeedback(): AnyclickContextValue;
+
+/**
+ * Registered provider instance
+ */
+interface ProviderInstance {
+    /** Unique identifier for this provider instance */
+    id: string;
+    /** Reference to the provider's container element (null if not scoped) */
+    containerRef: React.RefObject<Element | null>;
+    /** Whether this provider is scoped to its container */
+    scoped: boolean;
+    /** The provider's theme configuration */
+    theme: AnyclickTheme | null;
+    /** Whether this provider is disabled */
+    disabled: boolean;
+    /** Parent provider ID (if nested) */
+    parentId: string | null;
+    /** Depth in the provider hierarchy (0 = root) */
+    depth: number;
+    /** Handler to call when an event occurs in this provider's scope */
+    onContextMenu?: (event: FeedbackMenuEvent, element: Element) => boolean | void;
+}
+/**
+ * Provider registry store state
+ */
+interface ProviderStore {
+    /** Map of provider ID to provider instance */
+    providers: Map<string, ProviderInstance>;
+    /**
+     * Register a new provider
+     */
+    registerProvider: (provider: ProviderInstance) => void;
+    /**
+     * Unregister a provider
+     */
+    unregisterProvider: (id: string) => void;
+    /**
+     * Update a provider's configuration
+     */
+    updateProvider: (id: string, updates: Partial<ProviderInstance>) => void;
+    /**
+     * Find all providers that contain a given element, sorted by depth (nearest first)
+     */
+    findProvidersForElement: (element: Element) => ProviderInstance[];
+    /**
+     * Find the nearest parent provider for a given container
+     */
+    findParentProvider: (container: Element | null, excludeId?: string) => ProviderInstance | null;
+    /**
+     * Get merged theme for a provider (includes inherited parent themes)
+     */
+    getMergedTheme: (providerId: string) => AnyclickTheme;
+    /**
+     * Check if any ancestor provider has disabled anyclick
+     */
+    isDisabledByAncestor: (providerId: string) => boolean;
+    /**
+     * Check if an element is inside a disabled scoped provider's container
+     * This is used to prevent the global provider from handling events
+     * 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;
+/**
+ * Zustand store for managing provider instances
  */
-declare const FeedbackContext: react.Context<FeedbackContextValue | null>;
+declare const useProviderStore: zustand.UseBoundStore<zustand.StoreApi<ProviderStore>>;
 /**
- * Hook to access feedback context
- * @throws Error if used outside of FeedbackProvider
+ * Dispatch a context menu event to all matching providers (bubble up)
  */
-declare function useFeedback(): FeedbackContextValue;
+declare function dispatchContextMenuEvent(event: MouseEvent, element: Element): void;
 
+/**
+ * CSS custom properties for menu theming.
+ * These can be overridden via the `style` prop on AnyclickProvider.
+ *
+ * Example:
+ * ```tsx
+ * <AnyclickProvider
+ *   theme={{
+ *     menuStyle: {
+ *       '--anyclick-menu-bg': 'rgba(0, 0, 0, 0.9)',
+ *       '--anyclick-menu-text': '#ffffff',
+ *       '--anyclick-menu-border': 'rgba(255, 255, 255, 0.1)',
+ *       '--anyclick-menu-hover': 'rgba(255, 255, 255, 0.1)',
+ *       '--anyclick-menu-accent': '#f59e0b',
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+declare const menuCSSVariables: {
+    readonly "--anyclick-menu-bg": "#ffffff";
+    readonly "--anyclick-menu-hover": "#f5f5f5";
+    readonly "--anyclick-menu-text": "#333333";
+    readonly "--anyclick-menu-text-muted": "#666666";
+    readonly "--anyclick-menu-border": "#e5e5e5";
+    readonly "--anyclick-menu-accent": "#0066cc";
+    readonly "--anyclick-menu-accent-text": "#ffffff";
+    readonly "--anyclick-menu-input-bg": "#ffffff";
+    readonly "--anyclick-menu-input-border": "#dddddd";
+    readonly "--anyclick-menu-cancel-bg": "#f0f0f0";
+    readonly "--anyclick-menu-cancel-text": "#666666";
+};
 declare const menuStyles: Record<string, CSSProperties>;
 declare const darkMenuStyles: Record<string, CSSProperties>;
 
@@ -236,4 +418,4 @@ declare function applyHighlights(targetElement: Element, config?: HighlightConfi
     container: Element | null;
 };
 
-export { ContextMenu, type ContextMenuProps, FeedbackContext, type FeedbackContextValue, type FeedbackMenuItem, FeedbackProvider, type FeedbackProviderProps, type FeedbackUserContext, type HighlightColors, type HighlightConfig, ScreenshotPreview, type ScreenshotPreviewProps, applyHighlights, clearHighlights, darkMenuStyles, defaultContainerSelectors, defaultHighlightColors, filterMenuItemsByRole, findContainerParent, highlightContainer, highlightTarget, menuStyles, useFeedback };
+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 MenuPositionMode, type ProviderInstance, ScreenshotPreview, type ScreenshotPreviewProps, applyHighlights, clearHighlights, darkMenuStyles, defaultContainerSelectors, defaultHighlightColors, dispatchContextMenuEvent, filterMenuItemsByRole, findContainerParent, generateProviderId, highlightContainer, highlightTarget, menuCSSVariables, menuStyles, useAnyclick, useFeedback, useProviderStore };