@ewjdev/anyclick-react 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# @ewjdev/anyclick-react
+
+> React provider and context menu UI for UI feedback capture
+
+[![npm version](https://img.shields.io/npm/v/@ewjdev/anyclick-react.svg)](https://www.npmjs.com/package/@ewjdev/anyclick-react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+`@ewjdev/anyclick-react` provides a drop-in React component that adds feedback capture to your application. Right-click any element to open a customizable context menu for submitting feedback.
+
+## Installation
+
+```bash
+npm install @ewjdev/anyclick-react
+```
+
+## Requirements
+
+- React 19+
+- @ewjdev/anyclick-core (included as dependency)
+
+## Quick Start
+
+```tsx
+'use client';
+
+import { FeedbackProvider } from '@ewjdev/anyclick-react';
+import { createHttpAdapter } from '@ewjdev/anyclick-github';
+
+const adapter = createHttpAdapter({
+  endpoint: '/api/feedback',
+});
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <FeedbackProvider adapter={adapter}>
+      {children}
+    </FeedbackProvider>
+  );
+}
+```
+
+That's it! Users can now right-click any element to submit feedback.
+
+## Features
+
+- 🖱️ **Right-Click Context Menu** - Native feel with customizable items
+- 🎨 **Element Highlighting** - Visual feedback for target and container elements
+- 📸 **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
+
+## 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 |
+
+## Custom Menu Items
+
+```tsx
+import { Bug, Lightbulb, Heart } from 'lucide-react';
+
+const menuItems = [
+  { 
+    type: 'bug', 
+    label: 'Report Bug', 
+    icon: <Bug className="w-4 h-4" />,
+    showComment: true,
+  },
+  { 
+    type: 'feature', 
+    label: 'Suggest Feature', 
+    icon: <Lightbulb className="w-4 h-4" />,
+    showComment: true,
+  },
+  { 
+    type: 'love', 
+    label: 'Love It!', 
+    icon: <Heart className="w-4 h-4" />,
+    showComment: false,
+  },
+];
+
+<FeedbackProvider adapter={adapter} menuItems={menuItems}>
+  {children}
+</FeedbackProvider>
+```
+
+## Role-Based Filtering
+
+```tsx
+import { filterMenuItemsByRole } from '@ewjdev/anyclick-react';
+
+const allMenuItems = [
+  { type: 'bug', label: 'Report Bug' },
+  { type: 'debug', label: 'Debug Info', requiredRoles: ['developer'] },
+];
+
+const userContext = { roles: ['user', 'developer'] };
+const menuItems = filterMenuItemsByRole(allMenuItems, userContext);
+```
+
+## Highlight Configuration
+
+```tsx
+<FeedbackProvider
+  adapter={adapter}
+  highlightConfig={{
+    enabled: true,
+    colors: {
+      targetColor: '#3b82f6',
+      containerColor: '#8b5cf6',
+    },
+    containerSelectors: ['[data-component]', '.card'],
+  }}
+>
+  {children}
+</FeedbackProvider>
+```
+
+## useFeedback Hook
+
+Access feedback context from child components:
+
+```tsx
+import { useFeedback } from '@ewjdev/anyclick-react';
+
+function MyComponent() {
+  const { isSubmitting, openMenu, closeMenu } = useFeedback();
+  
+  // Open menu programmatically
+  const handleClick = (event) => {
+    openMenu(event.currentTarget, { x: event.clientX, y: event.clientY });
+  };
+  
+  return <button onClick={handleClick}>Open Feedback</button>;
+}
+```
+
+## Documentation
+
+For full documentation, visit [anyclick.ewj.dev/docs/react](https://anyclick.ewj.dev/docs/react)
+
+## Related Packages
+
+- [`@ewjdev/anyclick-core`](https://www.npmjs.com/package/@ewjdev/anyclick-core) - Core library
+- [`@ewjdev/anyclick-github`](https://www.npmjs.com/package/@ewjdev/anyclick-github) - GitHub Issues integration
+- [`@ewjdev/anyclick-cursor`](https://www.npmjs.com/package/@ewjdev/anyclick-cursor) - Cursor AI integration
+
+## License
+
+MIT © [anyclick](https://anyclick.ewj.dev)

package/dist/index.d.mts

@@ -0,0 +1,239 @@
+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 * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+/**
+ * Configuration for highlight colors
+ */
+interface HighlightColors {
+    /** Color for the target element highlight (default: #3b82f6 - blue) */
+    targetColor?: string;
+    /** Color for the container element highlight (default: #8b5cf6 - purple) */
+    containerColor?: string;
+    /** Opacity for the target shadow (default: 0.25) */
+    targetShadowOpacity?: number;
+    /** Opacity for the container shadow (default: 0.1) */
+    containerShadowOpacity?: number;
+}
+/**
+ * Configuration for highlight behavior
+ */
+interface HighlightConfig {
+    /** Whether to show highlights (default: true) */
+    enabled?: boolean;
+    /** Custom colors for highlights */
+    colors?: HighlightColors;
+    /** CSS selectors to identify container elements */
+    containerSelectors?: string[];
+    /** Minimum number of children for an element to be considered a container (default: 2) */
+    minChildrenForContainer?: number;
+}
+/**
+ * Menu item displayed in the feedback context menu
+ */
+interface FeedbackMenuItem {
+    /** Feedback type for this option (use unique identifier for parent items with children) */
+    type: FeedbackType;
+    /** Display label */
+    label: string;
+    /** Optional icon */
+    icon?: ReactNode;
+    /** Whether to show a comment input for this type */
+    showComment?: boolean;
+    /** Optional role(s) required to see this menu item */
+    requiredRoles?: string[];
+    /** Child menu items (creates a submenu) */
+    children?: FeedbackMenuItem[];
+}
+/**
+ * User context for role-based menu filtering
+ */
+interface FeedbackUserContext {
+    /** User's role(s) */
+    roles?: string[];
+    /** User ID */
+    id?: string;
+    /** User email */
+    email?: string;
+}
+/**
+ * Filter menu items based on user context
+ */
+declare function filterMenuItemsByRole(items: FeedbackMenuItem[], userContext?: FeedbackUserContext): FeedbackMenuItem[];
+/**
+ * Props for the FeedbackProvider component
+ */
+interface FeedbackProviderProps {
+    /** The adapter to use for submitting feedback */
+    adapter: FeedbackAdapter;
+    /** 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
+     */
+    targetFilter?: (event: MouseEvent, target: Element) => boolean;
+    /** Custom menu items (defaults to Issue, Feature, Like) */
+    menuItems?: FeedbackMenuItem[];
+    /** Maximum length for innerText capture */
+    maxInnerTextLength?: number;
+    /** Maximum length for outerHTML capture */
+    maxOuterHTMLLength?: number;
+    /** Maximum number of ancestors to capture */
+    maxAncestors?: number;
+    /** Cooldown in milliseconds between submissions (rate limiting) */
+    cooldownMs?: number;
+    /** Attributes to strip from outerHTML for privacy */
+    stripAttributes?: string[];
+    /** Additional metadata to include with every submission */
+    metadata?: Record<string, unknown>;
+    /** Callback after successful submission */
+    onSubmitSuccess?: (payload: FeedbackPayload) => void;
+    /** Callback after failed submission */
+    onSubmitError?: (error: Error, payload: FeedbackPayload) => void;
+    /** Custom styles for the context menu */
+    menuStyle?: CSSProperties;
+    /** Custom class name for the context menu */
+    menuClassName?: string;
+    /** Whether the provider is disabled */
+    disabled?: boolean;
+    /** Configuration for element highlighting */
+    highlightConfig?: HighlightConfig;
+    /** Configuration for screenshot capture */
+    screenshotConfig?: ScreenshotConfig;
+}
+/**
+ * Context value exposed by FeedbackProvider
+ */
+interface FeedbackContextValue {
+    /** Whether feedback 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 */
+    openMenu: (element: Element, position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Close the feedback menu */
+    closeMenu: () => void;
+}
+/**
+ * Props for the context menu component
+ */
+interface ContextMenuProps {
+    /** Whether the menu is visible */
+    visible: boolean;
+    /** Position of the menu */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Target element for feedback */
+    targetElement: Element | null;
+    /** Container element found by highlight logic */
+    containerElement: Element | null;
+    /** Menu items to display */
+    items: FeedbackMenuItem[];
+    /** Callback when an item is selected */
+    onSelect: (type: FeedbackType, comment?: string, screenshots?: ScreenshotData) => void;
+    /** Callback when menu is closed */
+    onClose: () => void;
+    /** Whether submission is in progress */
+    isSubmitting: boolean;
+    /** Custom styles */
+    style?: CSSProperties;
+    /** Custom class name */
+    className?: string;
+    /** Configuration for element highlighting */
+    highlightConfig?: HighlightConfig;
+    /** Configuration for screenshot capture */
+    screenshotConfig?: ScreenshotConfig;
+}
+/**
+ * Props for the screenshot preview component
+ */
+interface ScreenshotPreviewProps {
+    /** Captured screenshot data */
+    screenshots: ScreenshotData | null;
+    /** Whether screenshots are loading */
+    isLoading: boolean;
+    /** Callback when user confirms screenshots */
+    onConfirm: (screenshots: ScreenshotData) => void;
+    /** Callback when user cancels */
+    onCancel: () => void;
+    /** Callback when user wants to retake screenshots */
+    onRetake: () => void;
+    /** Whether submission is in progress */
+    isSubmitting: boolean;
+}
+
+/**
+ * FeedbackProvider component - wraps your app to enable feedback capture
+ */
+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;
+
+/**
+ * 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;
+
+/**
+ * Screenshot preview component - shows captured screenshots before sending
+ */
+declare function ScreenshotPreview({ screenshots, isLoading, onConfirm, onCancel, onRetake, isSubmitting, }: ScreenshotPreviewProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * React context for feedback functionality
+ */
+declare const FeedbackContext: react.Context<FeedbackContextValue | null>;
+/**
+ * Hook to access feedback context
+ * @throws Error if used outside of FeedbackProvider
+ */
+declare function useFeedback(): FeedbackContextValue;
+
+declare const menuStyles: Record<string, CSSProperties>;
+declare const darkMenuStyles: Record<string, CSSProperties>;
+
+/**
+ * Highlight utilities for feedback target elements
+ */
+
+/**
+ * Default highlight colors
+ */
+declare const defaultHighlightColors: Required<HighlightColors>;
+/**
+ * Default container selectors
+ */
+declare const defaultContainerSelectors: string[];
+/**
+ * Find the closest container parent element
+ */
+declare function findContainerParent(element: Element, config?: HighlightConfig): Element | null;
+/**
+ * Apply highlight to target element
+ */
+declare function highlightTarget(element: Element, colors?: HighlightColors): void;
+/**
+ * Apply highlight to container element
+ */
+declare function highlightContainer(element: Element, colors?: HighlightColors): void;
+/**
+ * Remove all highlights from the document
+ */
+declare function clearHighlights(): void;
+/**
+ * Apply highlights to target element and its container parent
+ */
+declare function applyHighlights(targetElement: Element, config?: HighlightConfig): {
+    target: Element;
+    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 };

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+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 * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+/**
+ * Configuration for highlight colors
+ */
+interface HighlightColors {
+    /** Color for the target element highlight (default: #3b82f6 - blue) */
+    targetColor?: string;
+    /** Color for the container element highlight (default: #8b5cf6 - purple) */
+    containerColor?: string;
+    /** Opacity for the target shadow (default: 0.25) */
+    targetShadowOpacity?: number;
+    /** Opacity for the container shadow (default: 0.1) */
+    containerShadowOpacity?: number;
+}
+/**
+ * Configuration for highlight behavior
+ */
+interface HighlightConfig {
+    /** Whether to show highlights (default: true) */
+    enabled?: boolean;
+    /** Custom colors for highlights */
+    colors?: HighlightColors;
+    /** CSS selectors to identify container elements */
+    containerSelectors?: string[];
+    /** Minimum number of children for an element to be considered a container (default: 2) */
+    minChildrenForContainer?: number;
+}
+/**
+ * Menu item displayed in the feedback context menu
+ */
+interface FeedbackMenuItem {
+    /** Feedback type for this option (use unique identifier for parent items with children) */
+    type: FeedbackType;
+    /** Display label */
+    label: string;
+    /** Optional icon */
+    icon?: ReactNode;
+    /** Whether to show a comment input for this type */
+    showComment?: boolean;
+    /** Optional role(s) required to see this menu item */
+    requiredRoles?: string[];
+    /** Child menu items (creates a submenu) */
+    children?: FeedbackMenuItem[];
+}
+/**
+ * User context for role-based menu filtering
+ */
+interface FeedbackUserContext {
+    /** User's role(s) */
+    roles?: string[];
+    /** User ID */
+    id?: string;
+    /** User email */
+    email?: string;
+}
+/**
+ * Filter menu items based on user context
+ */
+declare function filterMenuItemsByRole(items: FeedbackMenuItem[], userContext?: FeedbackUserContext): FeedbackMenuItem[];
+/**
+ * Props for the FeedbackProvider component
+ */
+interface FeedbackProviderProps {
+    /** The adapter to use for submitting feedback */
+    adapter: FeedbackAdapter;
+    /** 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
+     */
+    targetFilter?: (event: MouseEvent, target: Element) => boolean;
+    /** Custom menu items (defaults to Issue, Feature, Like) */
+    menuItems?: FeedbackMenuItem[];
+    /** Maximum length for innerText capture */
+    maxInnerTextLength?: number;
+    /** Maximum length for outerHTML capture */
+    maxOuterHTMLLength?: number;
+    /** Maximum number of ancestors to capture */
+    maxAncestors?: number;
+    /** Cooldown in milliseconds between submissions (rate limiting) */
+    cooldownMs?: number;
+    /** Attributes to strip from outerHTML for privacy */
+    stripAttributes?: string[];
+    /** Additional metadata to include with every submission */
+    metadata?: Record<string, unknown>;
+    /** Callback after successful submission */
+    onSubmitSuccess?: (payload: FeedbackPayload) => void;
+    /** Callback after failed submission */
+    onSubmitError?: (error: Error, payload: FeedbackPayload) => void;
+    /** Custom styles for the context menu */
+    menuStyle?: CSSProperties;
+    /** Custom class name for the context menu */
+    menuClassName?: string;
+    /** Whether the provider is disabled */
+    disabled?: boolean;
+    /** Configuration for element highlighting */
+    highlightConfig?: HighlightConfig;
+    /** Configuration for screenshot capture */
+    screenshotConfig?: ScreenshotConfig;
+}
+/**
+ * Context value exposed by FeedbackProvider
+ */
+interface FeedbackContextValue {
+    /** Whether feedback 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 */
+    openMenu: (element: Element, position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Close the feedback menu */
+    closeMenu: () => void;
+}
+/**
+ * Props for the context menu component
+ */
+interface ContextMenuProps {
+    /** Whether the menu is visible */
+    visible: boolean;
+    /** Position of the menu */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Target element for feedback */
+    targetElement: Element | null;
+    /** Container element found by highlight logic */
+    containerElement: Element | null;
+    /** Menu items to display */
+    items: FeedbackMenuItem[];
+    /** Callback when an item is selected */
+    onSelect: (type: FeedbackType, comment?: string, screenshots?: ScreenshotData) => void;
+    /** Callback when menu is closed */
+    onClose: () => void;
+    /** Whether submission is in progress */
+    isSubmitting: boolean;
+    /** Custom styles */
+    style?: CSSProperties;
+    /** Custom class name */
+    className?: string;
+    /** Configuration for element highlighting */
+    highlightConfig?: HighlightConfig;
+    /** Configuration for screenshot capture */
+    screenshotConfig?: ScreenshotConfig;
+}
+/**
+ * Props for the screenshot preview component
+ */
+interface ScreenshotPreviewProps {
+    /** Captured screenshot data */
+    screenshots: ScreenshotData | null;
+    /** Whether screenshots are loading */
+    isLoading: boolean;
+    /** Callback when user confirms screenshots */
+    onConfirm: (screenshots: ScreenshotData) => void;
+    /** Callback when user cancels */
+    onCancel: () => void;
+    /** Callback when user wants to retake screenshots */
+    onRetake: () => void;
+    /** Whether submission is in progress */
+    isSubmitting: boolean;
+}
+
+/**
+ * FeedbackProvider component - wraps your app to enable feedback capture
+ */
+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;
+
+/**
+ * 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;
+
+/**
+ * Screenshot preview component - shows captured screenshots before sending
+ */
+declare function ScreenshotPreview({ screenshots, isLoading, onConfirm, onCancel, onRetake, isSubmitting, }: ScreenshotPreviewProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * React context for feedback functionality
+ */
+declare const FeedbackContext: react.Context<FeedbackContextValue | null>;
+/**
+ * Hook to access feedback context
+ * @throws Error if used outside of FeedbackProvider
+ */
+declare function useFeedback(): FeedbackContextValue;
+
+declare const menuStyles: Record<string, CSSProperties>;
+declare const darkMenuStyles: Record<string, CSSProperties>;
+
+/**
+ * Highlight utilities for feedback target elements
+ */
+
+/**
+ * Default highlight colors
+ */
+declare const defaultHighlightColors: Required<HighlightColors>;
+/**
+ * Default container selectors
+ */
+declare const defaultContainerSelectors: string[];
+/**
+ * Find the closest container parent element
+ */
+declare function findContainerParent(element: Element, config?: HighlightConfig): Element | null;
+/**
+ * Apply highlight to target element
+ */
+declare function highlightTarget(element: Element, colors?: HighlightColors): void;
+/**
+ * Apply highlight to container element
+ */
+declare function highlightContainer(element: Element, colors?: HighlightColors): void;
+/**
+ * Remove all highlights from the document
+ */
+declare function clearHighlights(): void;
+/**
+ * Apply highlights to target element and its container parent
+ */
+declare function applyHighlights(targetElement: Element, config?: HighlightConfig): {
+    target: Element;
+    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 };