react-grab 0.1.48-dev.20fb4f1 → 0.1.48-dev.2140f70

package/README.md

@@ -114,72 +114,31 @@ if (process.env.NODE_ENV === "development") {
 }
 ```
 
-## Plugins
+## Build your own React Grab
 
-Use plugins to extend React Grab's built-in UI with context menu actions, toolbar menu items, lifecycle hooks, and theme overrides.
+Build a custom interface with the selection engine from `react-grab/primitives`. Use its APIs for hit testing, source context, page freezing, clipboard access, and editor navigation.
 
-Register a plugin using the `registerPlugin` export:
+### Customize hit testing
 
-```js
-import { registerPlugin } from "react-grab";
+Scope hit testing to a container or replace the default element filter with your own rules.
 
-registerPlugin({
-  name: "my-plugin",
-  hooks: {
-    onElementSelect: (element) => {
-      console.log("Selected:", element.tagName);
-    },
-  },
-});
-```
-
-If writing in React, register inside a `useEffect`:
+```typescript
+import { getElementAtPoint, isElementGrabbable } from "react-grab/primitives";
 
-```jsx
-import { registerPlugin, unregisterPlugin } from "react-grab";
-
-useEffect(() => {
-  registerPlugin({
-    name: "my-plugin",
-    actions: [
-      {
-        id: "my-action",
-        label: "My Action",
-        shortcut: "M",
-        onAction: (context) => {
-          console.log("Action on:", context.element);
-          context.hideContextMenu();
-        },
-      },
-    ],
+export const getPickerTarget = (
+  event: PointerEvent,
+  appElement: Element,
+  toolbarElement: Element,
+): Element | null =>
+  getElementAtPoint(event.clientX, event.clientY, {
+    container: appElement,
+    filter: (candidate) =>
+      isElementGrabbable(candidate) &&
+      !toolbarElement.contains(candidate),
   });
-
-  return () => unregisterPlugin("my-plugin");
-}, []);
-```
-
-Actions use a `target` field to control where they appear. Omit `target` (or set `"context-menu"`) for the right-click menu, or set `"toolbar"` for the toolbar dropdown:
-
-```js
-actions: [
-  {
-    id: "inspect",
-    label: "Inspect",
-    shortcut: "I",
-    onAction: (ctx) => console.dir(ctx.element),
-  },
-  {
-    id: "toggle-freeze",
-    label: "Freeze",
-    // Only show in the toolbar
-    target: "toolbar",
-    isActive: () => isFrozen,
-    onAction: () => toggleFreeze(),
-  },
-];
 ```
 
-See [`packages/react-grab/src/types.ts`](https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/src/types.ts) for the full `Plugin`, `PluginHooks`, and `PluginConfig` interfaces.
+Add `data-react-grab-ignore` to your picker interface so hit testing skips its subtree.
 
 ## Resources & Contributing Back
 

package/dist/{copy-content-Ca2txV90.d.cts → copy-content-CNRKFr6F.d.ts}

@@ -25,6 +25,17 @@ interface Position {
   x: number;
   y: number;
 }
+interface ElementAtPointOptions {
+  container?: Element;
+  filter?: (element: Element) => boolean;
+}
+interface ElementBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  borderRadius: string;
+}
 type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? T[P] extends ((...args: unknown[]) => unknown) ? T[P] : DeepPartial<T[P]> : T[P] };
 interface Theme {
   /**
@@ -140,11 +151,13 @@ interface AgentContext<T = unknown> {
   sessionId?: string;
 }
 type ActivationMode = "toggle" | "hold";
-interface ActionContextHooks {
-  transformHtmlContent: (html: string, elements: Element[]) => Promise<string>;
+interface OpenFileActionHooks {
   onOpenFile: (filePath: string, lineNumber?: number) => boolean | void;
   transformOpenFileUrl: (url: string, filePath: string, lineNumber?: number) => string;
 }
+interface ActionContextHooks extends OpenFileActionHooks {
+  transformHtmlContent: (html: string, elements: Element[]) => Promise<string>;
+}
 interface ActionContext {
   element: Element;
   elements: Element[];
@@ -260,24 +273,24 @@ interface HierarchyState {
   activeIndex: number;
 }
 interface PluginHooks {
-  onActivate?: () => void;
-  onDeactivate?: () => void;
-  onElementHover?: (element: Element) => void;
+  onActivate?: () => void | Promise<void>;
+  onDeactivate?: () => void | Promise<void>;
+  onElementHover?: (element: Element) => void | Promise<void>;
   onElementSelect?: (element: Element) => boolean | void | Promise<boolean>;
-  onDragStart?: (startX: number, startY: number) => void;
-  onDragEnd?: (elements: Element[], bounds: DragRect) => void;
+  onDragStart?: (startX: number, startY: number) => void | Promise<void>;
+  onDragEnd?: (elements: Element[], bounds: DragRect) => void | Promise<void>;
   onBeforeCopy?: (elements: Element[]) => void | Promise<void>;
   transformCopyContent?: (content: string, elements: Element[]) => string | Promise<string>;
-  onAfterCopy?: (elements: Element[], success: boolean) => void;
-  onCopySuccess?: (elements: Element[], content: string) => void;
-  onCopyError?: (error: Error) => void;
-  onStateChange?: (state: ReactGrabState) => void;
-  onPromptModeChange?: (isPromptMode: boolean, context: PromptModeContext) => void;
-  onSelectionBox?: (visible: boolean, bounds: OverlayBounds | null, element: Element | null) => void;
-  onDragBox?: (visible: boolean, bounds: OverlayBounds | null) => void;
-  onGrabbedBox?: (bounds: OverlayBounds, element: Element) => void;
-  onElementLabel?: (visible: boolean, variant: ElementLabelVariant, context: ElementLabelContext) => void;
-  onContextMenu?: (element: Element, position: Position) => void;
+  onAfterCopy?: (elements: Element[], success: boolean) => void | Promise<void>;
+  onCopySuccess?: (elements: Element[], content: string) => void | Promise<void>;
+  onCopyError?: (error: Error) => void | Promise<void>;
+  onStateChange?: (state: ReactGrabState) => void | Promise<void>;
+  onPromptModeChange?: (isPromptMode: boolean, context: PromptModeContext) => void | Promise<void>;
+  onSelectionBox?: (visible: boolean, bounds: OverlayBounds | null, element: Element | null) => void | Promise<void>;
+  onDragBox?: (visible: boolean, bounds: OverlayBounds | null) => void | Promise<void>;
+  onGrabbedBox?: (bounds: OverlayBounds, element: Element) => void | Promise<void>;
+  onElementLabel?: (visible: boolean, variant: ElementLabelVariant, context: ElementLabelContext) => void | Promise<void>;
+  onContextMenu?: (element: Element, position: Position) => void | Promise<void>;
   onOpenFile?: (filePath: string, lineNumber?: number) => boolean | void;
   transformHtmlContent?: (html: string, elements: Element[]) => string | Promise<string>;
   transformAgentContext?: (context: AgentContext, elements: Element[]) => AgentContext | Promise<AgentContext>;
@@ -289,7 +302,7 @@ interface PluginConfig {
   options?: SettableOptions;
   actions?: ContextMenuAction[];
   hooks?: PluginHooks;
-  cleanup?: () => void;
+  cleanup?: () => undefined;
 }
 interface Plugin {
   name: string;
@@ -432,13 +445,19 @@ interface FrozenLabelEntry {
   bounds: OverlayBounds;
   mouseX?: number;
 }
+interface FrozenLabelEntryAccessor {
+  read: () => FrozenLabelEntry | null;
+}
+interface SelectionLabelInstanceAccessor {
+  read: () => SelectionLabelInstance | null;
+}
 interface ReactGrabRendererProps {
   selectionVisible?: boolean;
   selectionBounds?: OverlayBounds;
   selectionBoundsMultiple?: OverlayBounds[];
   selectionShouldSnap?: boolean;
   selectionElementsCount?: number;
-  frozenLabelEntries?: FrozenLabelEntry[];
+  frozenLabelEntryAccessors?: FrozenLabelEntryAccessor[];
   pendingShiftPreviewEntry?: FrozenLabelEntry;
   selectionFilePath?: string;
   selectionLineNumber?: number;
@@ -449,6 +468,7 @@ interface ReactGrabRendererProps {
   hierarchyState?: HierarchyState;
   hierarchyMenuPosition?: DropdownAnchor | null;
   labelInstances?: SelectionLabelInstance[];
+  labelInstanceAccessors?: SelectionLabelInstanceAccessor[];
   dragVisible?: boolean;
   dragBounds?: OverlayBounds;
   grabbedBoxes?: Array<{
@@ -469,6 +489,7 @@ interface ReactGrabRendererProps {
   onToggleExpand?: () => void;
   selectionLabelShakeCount?: number;
   onConfirmDismiss?: () => void;
+  onOpenSelectionFile?: () => void;
   discardPrompt?: SelectionDiscardPrompt;
   toolbarVisible?: boolean;
   isActive?: boolean;
@@ -761,4 +782,4 @@ interface CopyContentOptions {
 }
 declare const copyContent: (content: string, options?: CopyContentOptions) => boolean;
 //#endregion
-export { SourceInfo as A, PromptModeContext as C, Rect as D, ReactGrabState as E, ToolbarState as M, SelectedElementPayload as O, Position as S, ReactGrabRendererProps as T, Options as _, ActionContext as a, PluginConfig as b, AgentContext as c, DeepPartial as d, DragRect as f, GrabbedBox as g, ElementSelectedEventDetail as h, Fiber as i, Theme as j, SettableOptions as k, ContextMenuAction as l, ElementLabelVariant as m, isInstrumentationActive as n, ActionContextHooks as o, ElementLabelContext as p, StackFrame as r, ActivationMode as s, copyContent as t, ContextMenuActionContext as u, OverlayBounds as v, ReactGrabAPI as w, PluginHooks as x, Plugin as y };
+export { Rect as A, PluginConfig as C, ReactGrabAPI as D, PromptModeContext as E, ToolbarState as F, SettableOptions as M, SourceInfo as N, ReactGrabRendererProps as O, Theme as P, Plugin as S, Position as T, ElementSelectedEventDetail as _, ActionContext as a, Options as b, AgentContext as c, DeepPartial as d, DragRect as f, ElementLabelVariant as g, ElementLabelContext as h, Fiber as i, SelectedElementPayload as j, ReactGrabState as k, ContextMenuAction as l, ElementBounds as m, isInstrumentationActive as n, ActionContextHooks as o, ElementAtPointOptions as p, StackFrame as r, ActivationMode as s, copyContent as t, ContextMenuActionContext as u, GrabbedBox as v, PluginHooks as w, OverlayBounds as x, OpenFileActionHooks as y };

package/dist/{copy-content-D6YIoJK4.d.ts → copy-content-CtYUWe5l.d.cts}

@@ -25,6 +25,17 @@ interface Position {
   x: number;
   y: number;
 }
+interface ElementAtPointOptions {
+  container?: Element;
+  filter?: (element: Element) => boolean;
+}
+interface ElementBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  borderRadius: string;
+}
 type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? T[P] extends ((...args: unknown[]) => unknown) ? T[P] : DeepPartial<T[P]> : T[P] };
 interface Theme {
   /**
@@ -140,11 +151,13 @@ interface AgentContext<T = unknown> {
   sessionId?: string;
 }
 type ActivationMode = "toggle" | "hold";
-interface ActionContextHooks {
-  transformHtmlContent: (html: string, elements: Element[]) => Promise<string>;
+interface OpenFileActionHooks {
   onOpenFile: (filePath: string, lineNumber?: number) => boolean | void;
   transformOpenFileUrl: (url: string, filePath: string, lineNumber?: number) => string;
 }
+interface ActionContextHooks extends OpenFileActionHooks {
+  transformHtmlContent: (html: string, elements: Element[]) => Promise<string>;
+}
 interface ActionContext {
   element: Element;
   elements: Element[];
@@ -260,24 +273,24 @@ interface HierarchyState {
   activeIndex: number;
 }
 interface PluginHooks {
-  onActivate?: () => void;
-  onDeactivate?: () => void;
-  onElementHover?: (element: Element) => void;
+  onActivate?: () => void | Promise<void>;
+  onDeactivate?: () => void | Promise<void>;
+  onElementHover?: (element: Element) => void | Promise<void>;
   onElementSelect?: (element: Element) => boolean | void | Promise<boolean>;
-  onDragStart?: (startX: number, startY: number) => void;
-  onDragEnd?: (elements: Element[], bounds: DragRect) => void;
+  onDragStart?: (startX: number, startY: number) => void | Promise<void>;
+  onDragEnd?: (elements: Element[], bounds: DragRect) => void | Promise<void>;
   onBeforeCopy?: (elements: Element[]) => void | Promise<void>;
   transformCopyContent?: (content: string, elements: Element[]) => string | Promise<string>;
-  onAfterCopy?: (elements: Element[], success: boolean) => void;
-  onCopySuccess?: (elements: Element[], content: string) => void;
-  onCopyError?: (error: Error) => void;
-  onStateChange?: (state: ReactGrabState) => void;
-  onPromptModeChange?: (isPromptMode: boolean, context: PromptModeContext) => void;
-  onSelectionBox?: (visible: boolean, bounds: OverlayBounds | null, element: Element | null) => void;
-  onDragBox?: (visible: boolean, bounds: OverlayBounds | null) => void;
-  onGrabbedBox?: (bounds: OverlayBounds, element: Element) => void;
-  onElementLabel?: (visible: boolean, variant: ElementLabelVariant, context: ElementLabelContext) => void;
-  onContextMenu?: (element: Element, position: Position) => void;
+  onAfterCopy?: (elements: Element[], success: boolean) => void | Promise<void>;
+  onCopySuccess?: (elements: Element[], content: string) => void | Promise<void>;
+  onCopyError?: (error: Error) => void | Promise<void>;
+  onStateChange?: (state: ReactGrabState) => void | Promise<void>;
+  onPromptModeChange?: (isPromptMode: boolean, context: PromptModeContext) => void | Promise<void>;
+  onSelectionBox?: (visible: boolean, bounds: OverlayBounds | null, element: Element | null) => void | Promise<void>;
+  onDragBox?: (visible: boolean, bounds: OverlayBounds | null) => void | Promise<void>;
+  onGrabbedBox?: (bounds: OverlayBounds, element: Element) => void | Promise<void>;
+  onElementLabel?: (visible: boolean, variant: ElementLabelVariant, context: ElementLabelContext) => void | Promise<void>;
+  onContextMenu?: (element: Element, position: Position) => void | Promise<void>;
   onOpenFile?: (filePath: string, lineNumber?: number) => boolean | void;
   transformHtmlContent?: (html: string, elements: Element[]) => string | Promise<string>;
   transformAgentContext?: (context: AgentContext, elements: Element[]) => AgentContext | Promise<AgentContext>;
@@ -289,7 +302,7 @@ interface PluginConfig {
   options?: SettableOptions;
   actions?: ContextMenuAction[];
   hooks?: PluginHooks;
-  cleanup?: () => void;
+  cleanup?: () => undefined;
 }
 interface Plugin {
   name: string;
@@ -432,13 +445,19 @@ interface FrozenLabelEntry {
   bounds: OverlayBounds;
   mouseX?: number;
 }
+interface FrozenLabelEntryAccessor {
+  read: () => FrozenLabelEntry | null;
+}
+interface SelectionLabelInstanceAccessor {
+  read: () => SelectionLabelInstance | null;
+}
 interface ReactGrabRendererProps {
   selectionVisible?: boolean;
   selectionBounds?: OverlayBounds;
   selectionBoundsMultiple?: OverlayBounds[];
   selectionShouldSnap?: boolean;
   selectionElementsCount?: number;
-  frozenLabelEntries?: FrozenLabelEntry[];
+  frozenLabelEntryAccessors?: FrozenLabelEntryAccessor[];
   pendingShiftPreviewEntry?: FrozenLabelEntry;
   selectionFilePath?: string;
   selectionLineNumber?: number;
@@ -449,6 +468,7 @@ interface ReactGrabRendererProps {
   hierarchyState?: HierarchyState;
   hierarchyMenuPosition?: DropdownAnchor | null;
   labelInstances?: SelectionLabelInstance[];
+  labelInstanceAccessors?: SelectionLabelInstanceAccessor[];
   dragVisible?: boolean;
   dragBounds?: OverlayBounds;
   grabbedBoxes?: Array<{
@@ -469,6 +489,7 @@ interface ReactGrabRendererProps {
   onToggleExpand?: () => void;
   selectionLabelShakeCount?: number;
   onConfirmDismiss?: () => void;
+  onOpenSelectionFile?: () => void;
   discardPrompt?: SelectionDiscardPrompt;
   toolbarVisible?: boolean;
   isActive?: boolean;
@@ -761,4 +782,4 @@ interface CopyContentOptions {
 }
 declare const copyContent: (content: string, options?: CopyContentOptions) => boolean;
 //#endregion
-export { SourceInfo as A, PromptModeContext as C, Rect as D, ReactGrabState as E, ToolbarState as M, SelectedElementPayload as O, Position as S, ReactGrabRendererProps as T, Options as _, ActionContext as a, PluginConfig as b, AgentContext as c, DeepPartial as d, DragRect as f, GrabbedBox as g, ElementSelectedEventDetail as h, Fiber as i, Theme as j, SettableOptions as k, ContextMenuAction as l, ElementLabelVariant as m, isInstrumentationActive as n, ActionContextHooks as o, ElementLabelContext as p, StackFrame as r, ActivationMode as s, copyContent as t, ContextMenuActionContext as u, OverlayBounds as v, ReactGrabAPI as w, PluginHooks as x, Plugin as y };
+export { Rect as A, PluginConfig as C, ReactGrabAPI as D, PromptModeContext as E, ToolbarState as F, SettableOptions as M, SourceInfo as N, ReactGrabRendererProps as O, Theme as P, Plugin as S, Position as T, ElementSelectedEventDetail as _, ActionContext as a, Options as b, AgentContext as c, DeepPartial as d, DragRect as f, ElementLabelVariant as g, ElementLabelContext as h, Fiber as i, SelectedElementPayload as j, ReactGrabState as k, ContextMenuAction as l, ElementBounds as m, isInstrumentationActive as n, ActionContextHooks as o, ElementAtPointOptions as p, StackFrame as r, ActivationMode as s, copyContent as t, ContextMenuActionContext as u, GrabbedBox as v, PluginHooks as w, OverlayBounds as x, OpenFileActionHooks as y };

package/dist/core/index.cjs

@@ -6,4 +6,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../core-CKtUC3h5.cjs`),t=require(`../freeze-updates-CZXNftlx.cjs`),n=require(`../copy-content-cjYKypHY.cjs`);exports.DEFAULT_THEME=e.a,exports.copyContent=n.t,exports.formatElementInfo=n.n,exports.generateSnippet=e.n,exports.getStack=n.o,exports.init=e.t,exports.isInstrumentationActive=t.P;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`../core-ZMvFTCzR.cjs`),t=require(`../freeze-updates-DjOZqpQg.cjs`),n=require(`../open-file-toF5t4tX.cjs`);exports.DEFAULT_THEME=e.a,exports.copyContent=n.n,exports.formatElementInfo=n.r,exports.generateSnippet=e.n,exports.getStack=n.s,exports.init=e.t,exports.isInstrumentationActive=t.U;

package/dist/core/index.d.cts

@@ -6,6 +6,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { A as SourceInfo, T as ReactGrabRendererProps, _ as Options, a as ActionContext, b as PluginConfig, c as AgentContext, k as SettableOptions, l as ContextMenuAction, n as isInstrumentationActive, t as copyContent, v as OverlayBounds, w as ReactGrabAPI, x as PluginHooks, y as Plugin } from "../copy-content-Ca2txV90.cjs";
-import { a as getStack, i as formatElementInfo, n as generateSnippet, r as DEFAULT_THEME, t as init } from "../index-CgWlIagV.cjs";
+import { C as PluginConfig, D as ReactGrabAPI, M as SettableOptions, N as SourceInfo, O as ReactGrabRendererProps, S as Plugin, a as ActionContext, b as Options, c as AgentContext, l as ContextMenuAction, n as isInstrumentationActive, t as copyContent, w as PluginHooks, x as OverlayBounds } from "../copy-content-CtYUWe5l.cjs";
+import { a as getStack, i as formatElementInfo, n as generateSnippet, r as DEFAULT_THEME, t as init } from "../index-BgTe-uWs.cjs";
 export { ActionContext, AgentContext, ContextMenuAction, DEFAULT_THEME, Options, OverlayBounds, Plugin, PluginConfig, PluginHooks, ReactGrabAPI, ReactGrabRendererProps, SettableOptions, SourceInfo, copyContent, formatElementInfo, generateSnippet, getStack, init, isInstrumentationActive };

package/dist/core/index.d.ts

@@ -6,6 +6,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { A as SourceInfo, T as ReactGrabRendererProps, _ as Options, a as ActionContext, b as PluginConfig, c as AgentContext, k as SettableOptions, l as ContextMenuAction, n as isInstrumentationActive, t as copyContent, v as OverlayBounds, w as ReactGrabAPI, x as PluginHooks, y as Plugin } from "../copy-content-D6YIoJK4.js";
-import { a as getStack, i as formatElementInfo, n as generateSnippet, r as DEFAULT_THEME, t as init } from "../index-C_tGQJlm.js";
+import { C as PluginConfig, D as ReactGrabAPI, M as SettableOptions, N as SourceInfo, O as ReactGrabRendererProps, S as Plugin, a as ActionContext, b as Options, c as AgentContext, l as ContextMenuAction, n as isInstrumentationActive, t as copyContent, w as PluginHooks, x as OverlayBounds } from "../copy-content-CNRKFr6F.js";
+import { a as getStack, i as formatElementInfo, n as generateSnippet, r as DEFAULT_THEME, t as init } from "../index-CdWMNcJF.js";
 export { ActionContext, AgentContext, ContextMenuAction, DEFAULT_THEME, Options, OverlayBounds, Plugin, PluginConfig, PluginHooks, ReactGrabAPI, ReactGrabRendererProps, SettableOptions, SourceInfo, copyContent, formatElementInfo, generateSnippet, getStack, init, isInstrumentationActive };

package/dist/core/index.js

@@ -6,4 +6,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import{a as e,n as t,t as n}from"../core-CBM7-BmH.js";import{P as r}from"../freeze-updates-BmKYPOzz.js";import{n as i,o as a,t as o}from"../copy-content-CPdjqgu5.js";export{e as DEFAULT_THEME,o as copyContent,i as formatElementInfo,t as generateSnippet,a as getStack,n as init,r as isInstrumentationActive};
+import{a as e,n as t,t as n}from"../core-D63FvPJ2.js";import{U as r}from"../freeze-updates-BfVmaGoQ.js";import{n as i,r as a,s as o}from"../open-file-gfHEw5hC.js";export{e as DEFAULT_THEME,i as copyContent,a as formatElementInfo,t as generateSnippet,o as getStack,n as init,r as isInstrumentationActive};