@ewjdev/anyclick-react 1.4.0 → 1.4.1

package/README.md

@@ -13,6 +13,10 @@
 
 ```bash
 npm install @ewjdev/anyclick-react
+# or
+yarn add @ewjdev/anyclick-react
+# or
+pnpm add @ewjdev/anyclick-react
 ```
 
 ## Requirements
@@ -25,8 +29,8 @@ npm install @ewjdev/anyclick-react
 ```tsx
 "use client";
 
-import { AnyclickProvider } from "@ewjdev/anyclick-react";
 import { createHttpAdapter } from "@ewjdev/anyclick-github";
+import { AnyclickProvider } from "@ewjdev/anyclick-react";
 
 const adapter = createHttpAdapter({
   endpoint: "/api/feedback",
@@ -42,27 +46,106 @@ That's it! Users can now right-click any element to submit feedback.
 ## Features
 
 - 🖱️ **Right-Click Context Menu** - Native feel with customizable items
+- 📱 **Touch Support** - Press-and-hold on mobile devices
 - 🎨 **Element Highlighting** - Visual feedback for target and container elements
-- 📸 **Screenshot Capture** - Automatic screenshots of target, container, and page
+- 📸 **Screenshot Capture** - Automatic screenshots of target, container, and viewport
 - 🔒 **Role-Based Menu Items** - Show different options based on user roles
-- 📱 **Submenus** - Organize menu items with nested submenus
+- 📁 **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
+- 🔍 **Element Inspector** - Chrome DevTools-style inspect dialog
+- ⚡ **Performance Optimized** - Memoized components and efficient re-renders
+
+## API Reference
+
+### AnyclickProvider Props
+
+| Prop                  | Type                       | Default     | Description                                    |
+| --------------------- | -------------------------- | ----------- | ---------------------------------------------- |
+| `adapter`             | `AnyclickAdapter`          | Required    | The adapter for submitting feedback            |
+| `menuItems`           | `ContextMenuItem[]`        | Default set | Custom menu items                              |
+| `metadata`            | `Record<string, unknown>`  | `undefined` | Additional data included with every submission |
+| `theme`               | `AnyclickTheme \| null`    | `undefined` | Theme configuration (inherits from parent)     |
+| `scoped`              | `boolean`                  | `false`     | Limit capture to this provider's children only |
+| `disabled`            | `boolean`                  | `false`     | Disable anyclick capture                       |
+| `highlightConfig`     | `HighlightConfig`          | Default     | Element highlighting configuration             |
+| `screenshotConfig`    | `ScreenshotConfig`         | Default     | Screenshot capture configuration               |
+| `onSubmitSuccess`     | `(payload) => void`        | `undefined` | Success callback                               |
+| `onSubmitError`       | `(error, payload) => void` | `undefined` | Error callback                                 |
+| `touchHoldDurationMs` | `number`                   | `500`       | Touch hold duration before triggering menu     |
+| `touchMoveThreshold`  | `number`                   | `10`        | Max movement in px before touch hold cancels   |
+
+### AnyclickTheme
+
+```tsx
+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;
+  /** Disable anyclick in this subtree */
+  disabled?: boolean;
+  /** Enable fun mode (go-kart cursor) */
+  funMode?: boolean | FunModeThemeConfig;
+}
+```
+
+### ContextMenuItem
+
+```tsx
+interface ContextMenuItem {
+  /** Unique type identifier */
+  type: string;
+  /** Display label */
+  label: string;
+  /** Optional icon */
+  icon?: ReactNode;
+  /** Show comment input after selection */
+  showComment?: boolean;
+  /** Status badge (e.g., "comingSoon") */
+  status?: "available" | "comingSoon";
+  /** Visual badge configuration */
+  badge?: { label: string; tone?: "neutral" | "info" | "warning" | "success" };
+  /** Required roles to see this item */
+  requiredRoles?: string[];
+  /** Nested submenu items */
+  children?: ContextMenuItem[];
+  /** Custom click handler */
+  onClick?: (context: {
+    targetElement: Element | null;
+    containerElement: Element | null;
+    closeMenu: () => void;
+  }) => void | boolean | Promise<void | boolean>;
+}
+```
 
-## Props
+### HighlightConfig
 
-| Prop              | Type                       | Description                                    |
-| ----------------- | -------------------------- | ---------------------------------------------- |
-| `adapter`         | `AnyclickAdapter`          | Required. The adapter for submitting anyclick  |
-| `menuItems`       | `ContextMenuItem[]`        | 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 anyclick capture                       |
-| `onSubmitSuccess` | `(payload) => void`        | Success callback                               |
-| `onSubmitError`   | `(error, payload) => void` | Error callback                                 |
+```tsx
+interface HighlightConfig {
+  /** Enable/disable highlighting */
+  enabled?: boolean;
+  /** Custom highlight colors */
+  colors?: {
+    targetColor?: string; // Default: "#3b82f6"
+    containerColor?: string; // Default: "#8b5cf6"
+    targetShadowOpacity?: number; // Default: 0.25
+    containerShadowOpacity?: number; // Default: 0.1
+  };
+  /** CSS selectors to identify container elements */
+  containerSelectors?: string[];
+  /** Minimum children count for auto-container detection */
+  minChildrenForContainer?: number;
+}
+```
 
-## Scoped Providers
+## Examples
+
+### Scoped Providers
 
 Limit feedback capture to specific sections of your app:
 
@@ -90,7 +173,7 @@ function App() {
 }
 ```
 
-## Nested Theming
+### Nested Theming
 
 Override themes for specific sections:
 
@@ -131,22 +214,10 @@ function App() {
 }
 ```
 
-## Theme Configuration
-
-```tsx
-interface AnyclickTheme {
-  menuStyle?: CSSProperties;
-  menuClassName?: string;
-  highlightConfig?: HighlightConfig;
-  screenshotConfig?: ScreenshotConfig;
-  disabled?: boolean; // Disable anyclick in this subtree
-}
-```
-
-## Custom Menu Items
+### Custom Menu Items
 
 ```tsx
-import { Bug, Lightbulb, Heart } from "lucide-react";
+import { Bug, Heart, Lightbulb } from "lucide-react";
 
 const menuItems = [
   {
@@ -174,7 +245,7 @@ const menuItems = [
 </AnyclickProvider>;
 ```
 
-## Role-Based Filtering
+### Role-Based Filtering
 
 ```tsx
 import { filterMenuItemsByRole } from "@ewjdev/anyclick-react";
@@ -188,15 +259,15 @@ const userContext = { roles: ["user", "developer"] };
 const menuItems = filterMenuItemsByRole(allMenuItems, userContext);
 ```
 
-## Role-Based Presets
+### Role-Based Presets
 
-Skip hand-authoring menus by pulling in a preset for common roles. Coming-soon actions stay visible with a badge but are disabled by default.
+Skip hand-authoring menus by pulling in a preset for common roles:
 
 ```tsx
 import { AnyclickProvider, createPresetMenu } from "@ewjdev/anyclick-react";
 
 const qaPreset = createPresetMenu("qa");
-// Or: listPresets() to show available roles, createPresetMenu("developer", { includeComingSoon: false })
+// Available presets: "qa", "pm", "designer", "developer", "chrome"
 
 <AnyclickProvider
   adapter={adapter}
@@ -209,26 +280,56 @@ const qaPreset = createPresetMenu("qa");
 </AnyclickProvider>;
 ```
 
-Preset defaults (examples):
+**Available Presets:**
+
+| Preset      | Description                                                       |
+| ----------- | ----------------------------------------------------------------- |
+| `qa`        | Bug/defect, UX papercut, repro steps, + performance trace (soon)  |
+| `pm`        | Feature idea, UX papercut, customer quote, + impact sizing (soon) |
+| `designer`  | Visual bug, accessibility, copy/tone, + motion glitch (soon)      |
+| `developer` | Bug, refactor request, + diagnostics submenu                      |
+| `chrome`    | Chrome-like menu with reload, print, search, share, inspect       |
 
-- QA: bug / repro / UX papercut + “Performance trace” (coming soon)
-- PM: feature idea / UX papercut + “Impact sizing” (coming soon)
-- Designer: visual bug / accessibility + “Motion glitch” (coming soon)
-- Developer: bug / refactor + diagnostics submenu (console/network traces marked coming soon)
+### useAnyclick Hook
 
-## Highlight Configuration
+Access anyclick context from child components:
+
+```tsx
+import { useAnyclick } from "@ewjdev/anyclick-react";
+
+function MyComponent() {
+  const {
+    isEnabled, // Whether anyclick is active
+    isSubmitting, // Whether a submission is in progress
+    openMenu, // Open menu programmatically
+    closeMenu, // Close menu
+    theme, // Current merged theme
+    scoped, // Whether provider is scoped
+    providerId, // Unique provider ID
+  } = useAnyclick();
+
+  const handleClick = (event) => {
+    openMenu(event.currentTarget, { x: event.clientX, y: event.clientY });
+  };
+
+  return <button onClick={handleClick}>Open Feedback</button>;
+}
+```
+
+### Custom Styling with CSS Variables
+
+Override menu styling using CSS custom properties:
 
 ```tsx
 <AnyclickProvider
   adapter={adapter}
   theme={{
-    highlightConfig: {
-      enabled: true,
-      colors: {
-        targetColor: "#3b82f6",
-        containerColor: "#8b5cf6",
-      },
-      containerSelectors: ["[data-component]", ".card"],
+    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",
     },
   }}
 >
@@ -236,25 +337,31 @@ Preset defaults (examples):
 </AnyclickProvider>
 ```
 
-## useAnyclick Hook
+**Available CSS Variables:**
 
-Access anyclick context from child components:
-
-```tsx
-import { useAnyclick } from "@ewjdev/anyclick-react";
+| Variable                       | Default   | Description              |
+| ------------------------------ | --------- | ------------------------ |
+| `--anyclick-menu-bg`           | `#ffffff` | Menu background color    |
+| `--anyclick-menu-hover`        | `#f5f5f5` | Item hover background    |
+| `--anyclick-menu-text`         | `#333333` | Primary text color       |
+| `--anyclick-menu-text-muted`   | `#666666` | Muted text color         |
+| `--anyclick-menu-border`       | `#e5e5e5` | Border color             |
+| `--anyclick-menu-accent`       | `#0066cc` | Accent/action color      |
+| `--anyclick-menu-accent-text`  | `#ffffff` | Accent text color        |
+| `--anyclick-menu-input-bg`     | `#ffffff` | Input background         |
+| `--anyclick-menu-input-border` | `#dddddd` | Input border color       |
+| `--anyclick-menu-cancel-bg`    | `#f0f0f0` | Cancel button background |
+| `--anyclick-menu-cancel-text`  | `#666666` | Cancel button text       |
 
-function MyComponent() {
-  const { isSubmitting, openMenu, closeMenu, theme, scoped, providerId } =
-    useAnyclick();
+## Performance Considerations
 
-  // Open menu programmatically
-  const handleClick = (event) => {
-    openMenu(event.currentTarget, { x: event.clientX, y: event.clientY });
-  };
+The package is optimized for performance:
 
-  return <button onClick={handleClick}>Open Feedback</button>;
-}
-```
+- Components use `React.memo` to prevent unnecessary re-renders
+- Expensive computations are wrapped in `useMemo`
+- Event handlers use `useCallback` for stable references
+- Screenshot capture is lazy-loaded and async
+- Touch event handling uses passive listeners where possible
 
 ## Migration from FeedbackProvider
 
@@ -263,11 +370,39 @@ The `FeedbackProvider` component has been renamed to `AnyclickProvider`. The old
 ```tsx
 // Old (deprecated)
 import { FeedbackProvider, useFeedback } from "@ewjdev/anyclick-react";
-
 // New (recommended)
 import { AnyclickProvider, useAnyclick } from "@ewjdev/anyclick-react";
 ```
 
+## Exported Utilities
+
+```tsx
+// Components
+export { AnyclickProvider, ContextMenu, ScreenshotPreview, InspectDialog };
+
+// Hooks
+export { useAnyclick, useProviderStore, useInspectStore };
+
+// Presets
+export { createPresetMenu, listPresets, presetDefaults };
+
+// Utilities
+export { filterMenuItemsByRole, getBadgeStyle };
+export {
+  findContainerParent,
+  highlightTarget,
+  highlightContainer,
+  clearHighlights,
+  applyHighlights,
+};
+
+// Styles
+export { menuStyles, darkMenuStyles, menuCSSVariables };
+
+// IDE Integration
+export { openInIDE, buildIDEUrl, detectPreferredIDE };
+```
+
 ## Documentation
 
 For full documentation, visit [anyclick.ewj.dev/docs/react](https://anyclick.ewj.dev/docs/react)
@@ -277,6 +412,7 @@ For full documentation, visit [anyclick.ewj.dev/docs/react](https://anyclick.ewj
 - [`@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
+- [`@ewjdev/anyclick-pointer`](https://www.npmjs.com/package/@ewjdev/anyclick-pointer) - Custom pointer effects
 
 ## License