@useclickly/react 0.2.0 → 1.0.0

package/README.md

@@ -1,15 +1,19 @@
 # @useclickly/react
 
+[![npm version](https://img.shields.io/npm/v/@useclickly/react.svg?color=0ea5e9)](https://www.npmjs.com/package/@useclickly/react)
+[![license](https://img.shields.io/npm/l/@useclickly/react.svg?color=10b981)](../../LICENSE)
+
 > Click-to-annotate dev toolbar for React. Generates prompts your AI coding agent can actually act on.
 
-Drop `<Clickly />` into your React app (dev only). A small floating action button appears in the bottom-right. Open it, click any element, write a comment — copy a perfectly-formatted markdown prompt into Claude Code / Cursor / Codex.
+Drop `<Clickly />` into your React app (dev only). A small floating action button appears in the bottom-right corner. Open it, click any element, write a comment — copy a perfectly-formatted markdown prompt into **Claude Code**, **Cursor**, **Codex**, or any MCP-aware tool.
 
 ## Install
 
 ```bash
 npm install -D @useclickly/react
-# or: pnpm add -D @useclickly/react
-# or: yarn add -D @useclickly/react
+# or:
+pnpm add -D @useclickly/react
+yarn add -D @useclickly/react
 ```
 
 ## Use
@@ -27,20 +31,30 @@ export default function App() {
 }
 ```
 
-That's it.
+That's it. The component returns `null` on the server (safe under SSR / Next App Router) and ships with `"use client"` already baked into the bundle.
+
+## What it does
+
+| Mode | How |
+|---|---|
+| **Single** | Click any element → popup with comment box |
+| **Multi-select** | Press `2` or shift-click to pin elements, hit **Annotate (N)** when done |
+| **Area drag** | Press `3`, drag a rectangle, every intersecting element gets pinned |
+| **Persistent pins** | Annotated elements stay numbered on the page across page interactions |
+| **Auto-copy** | Submitting an annotation copies markdown to clipboard (toggleable) |
+| **Settings** | Output detail tier, React component info, marker colour — all in the gear menu |
+
+## What gets captured
 
-## Features
+For every selected element, Clickly automatically collects:
 
-- **Click any element** → annotation popup with comment box
-- **Multi-select** — shift-click to pin elements, hit `Annotate (N)` when done
-- **Area drag** — press `3`, drag a rectangle, every intersecting element gets pinned
-- **Persistent numbered pins** on every annotated element
-- **CSS selectors + DOM paths + computed styles** captured automatically
-- **Auto-copy markdown** to clipboard on every Add
-- **AFS 1.1 schema** — wire-compatible with Agentation, parseable by any MCP-aware agent
-- **Crosshair cursor + text-select disabled** while inspecting
-- **Shadow DOM** for zero CSS leakage in either direction
-- **`"use client"` baked in** — Next.js App Router just works
+- Short + full CSS selector (`section.hero > button.cta`)
+- Computed styles (curated by detail tier)
+- Bounding box + position (handles `fixed` / `sticky`)
+- ARIA / `role` / `tabindex` / `title`
+- Visible nearby text (truncated)
+- **React component tree** (`App > Dashboard > Button`) via Fiber walk
+- **Source file + line** (`src/Button.tsx:42`) on Vite/Next — instant grep target
 
 ## Keyboard shortcuts
 
@@ -53,17 +67,51 @@ That's it.
 | `C` | Copy all annotations as markdown |
 | `X` | Clear all annotations |
 
+## Props
+
+All optional; `<Clickly />` works with zero config.
+
+```ts
+interface ClicklyProps {
+  className?: string;
+  endpoint?: string;          // MCP server URL — see @useclickly/mcp-server
+  sessionId?: string;
+  onAnnotationAdd?: (id: string) => void;
+  onAnnotationDelete?: (id: string) => void;
+  onAnnotationsClear?: () => void;
+  onCopy?: (markdown: string) => void;
+  onSessionCreated?: (sessionId: string) => void;
+}
+```
+
+## Output
+
+```md
+## Annotation #1
+**Element:** `button.cta.primary`
+**Path:** `body > main > section.hero > button.cta.primary`
+**Position:** 120px, 480px (200×48px)
+**Source:** `src/components/Hero.tsx:42`
+**React:** App > LandingPage > HeroSection > CTAButton
+**Feedback:** Button is cut off on mobile viewport
+```
+
+Configurable via the settings popover: `compact` (one-liner) → `standard` → `detailed` → `forensic` (full computed styles).
+
+The shape is **[AFS 1.1](https://agentation.dev/schema/annotation.v1.1.json)**-compatible — every MCP-aware agent can parse it.
+
 ## Requirements
 
 - React 18+ or 19+
 - Browser environment (no SSR; component returns `null` server-side)
 - Desktop only — touch / mobile is not optimised
+- **Not for React Native** — see the main [README](https://github.com/useclickly/clickly#react-native)
+
+## Advanced
 
-## Links
+For framework-agnostic engine access — building your own UI on top of Clickly's selection + metadata — see [`@useclickly/core`](https://www.npmjs.com/package/@useclickly/core).
 
-- Main repo and docs: [github.com/clickly/clickly](https://github.com/clickly/clickly)
-- AFS 1.1 schema: see `@useclickly/core`
-- MCP server (for agent integration): see `@useclickly/mcp-server`
+For agent integration over MCP — your agent reading/responding to annotations directly — see [`@useclickly/mcp-server`](https://www.npmjs.com/package/@useclickly/mcp-server).
 
 ## License
 

package/dist/index.cjs

@@ -148,11 +148,18 @@ function annotationsToMarkdown(annotations, detail = "standard") {
 function formatOne(a, index, detail) {
   const lines = [];
   lines.push(`## Annotation #${index}`);
-  lines.push(`**Element:** \`${a.element}${a.cssClasses ? "." + a.cssClasses.split(" ").join(".") : ""}\``);
+  lines.push(
+    `**Element:** \`${a.element}${a.cssClasses ? "." + a.cssClasses.split(" ").join(".") : ""}\``
+  );
   lines.push(`**Path:** \`${a.elementPath}\``);
   if (detail !== "compact" && a.boundingBox) {
     const b = a.boundingBox;
-    lines.push(`**Position:** ${Math.round(b.x)}px, ${Math.round(b.y)}px (${Math.round(b.width)}\xD7${Math.round(b.height)}px)`);
+    lines.push(
+      `**Position:** ${Math.round(b.x)}px, ${Math.round(b.y)}px (${Math.round(b.width)}\xD7${Math.round(b.height)}px)`
+    );
+  }
+  if (detail !== "compact" && a.sourceFile) {
+    lines.push(`**Source:** \`${a.sourceFile}:${a.sourceLine ?? "?"}\``);
   }
   if (detail === "detailed" || detail === "forensic") {
     if (a.reactComponents) lines.push(`**React:** ${a.reactComponents}`);
@@ -351,13 +358,25 @@ function Toolbar({ engine, onCollapse }) {
       style: { left: position.x, top: position.y, width: TOOLBAR_SIZE.width },
       "aria-label": "Clickly toolbar",
       children: [
-        /* @__PURE__ */ jsxRuntime.jsx("div", { className: "grip", ...handleProps, title: "Drag to move", children: /* @__PURE__ */ jsxRuntime.jsx(IconGrip, {}) }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            className: "grip",
+            ...handleProps,
+            title: "Drag to move",
+            role: "separator",
+            "aria-orientation": "vertical",
+            children: /* @__PURE__ */ jsxRuntime.jsx(IconGrip, {})
+          }
+        ),
         /* @__PURE__ */ jsxRuntime.jsx(
           "button",
           {
             className: `clickly-btn icon-only${currentMode === "single" ? " is-active" : ""}`,
             onClick: () => setMode("single"),
             title: "Single (1)",
+            "aria-label": "Single-element selection mode",
+            "aria-pressed": currentMode === "single",
             children: /* @__PURE__ */ jsxRuntime.jsx(IconCursor, {})
           }
         ),
@@ -367,6 +386,8 @@ function Toolbar({ engine, onCollapse }) {
             className: `clickly-btn icon-only${currentMode === "multi" ? " is-active" : ""}`,
             onClick: () => setMode("multi"),
             title: "Multi-select (2 / shift-click)",
+            "aria-label": "Multi-element selection mode",
+            "aria-pressed": currentMode === "multi",
             children: /* @__PURE__ */ jsxRuntime.jsx(IconLayers, {})
           }
         ),
@@ -376,6 +397,8 @@ function Toolbar({ engine, onCollapse }) {
             className: `clickly-btn icon-only${currentMode === "area" ? " is-active" : ""}`,
             onClick: () => setMode("area"),
             title: "Area drag (3)",
+            "aria-label": "Area drag-selection mode",
+            "aria-pressed": currentMode === "area",
             children: /* @__PURE__ */ jsxRuntime.jsx(IconSquare, {})
           }
         ),
@@ -424,6 +447,7 @@ function Toolbar({ engine, onCollapse }) {
             className: "clickly-btn icon-only",
             onClick: onCopy,
             title: "Copy markdown (C)",
+            "aria-label": "Copy all annotations as markdown",
             disabled: annotations.length === 0,
             children: /* @__PURE__ */ jsxRuntime.jsx(IconCopy, {})
           }
@@ -434,6 +458,7 @@ function Toolbar({ engine, onCollapse }) {
             className: "clickly-btn icon-only",
             onClick: onClear,
             title: "Clear (X)",
+            "aria-label": "Clear all annotations",
             disabled: annotations.length === 0,
             children: /* @__PURE__ */ jsxRuntime.jsx(IconTrash, {})
           }
@@ -445,6 +470,8 @@ function Toolbar({ engine, onCollapse }) {
             className: "clickly-btn icon-only",
             onClick: () => setShowSettings((v) => !v),
             title: "Settings",
+            "aria-label": "Open settings",
+            "aria-expanded": showSettings,
             children: /* @__PURE__ */ jsxRuntime.jsx(IconSettings, {})
           }
         ),
@@ -454,6 +481,7 @@ function Toolbar({ engine, onCollapse }) {
             className: "clickly-btn icon-only",
             onClick: onCollapse,
             title: "Collapse (Esc)",
+            "aria-label": "Collapse Clickly toolbar",
             children: /* @__PURE__ */ jsxRuntime.jsx(IconClose, {})
           }
         ),
@@ -527,8 +555,9 @@ function AnnotationPopup({ engine }) {
     if (elements.length === 0) return;
     const sharedComment = comment.trim() || "(no comment)";
     const isMulti = sel.kind !== "single";
+    const showReact = useSettings.getState().showReactComponents;
     for (const el of elements) {
-      const md = core.collectMetadata(el, { detail: outputDetail });
+      const md = core.collectMetadata(el, { detail: outputDetail, includeReact: showReact });
       const annotation = {
         id: "ann_" + nanoid.nanoid(8),
         comment: sharedComment,
@@ -546,6 +575,10 @@ function AnnotationPopup({ engine }) {
         nearbyText: md.nearbyText || void 0,
         selectedText: md.selectedText || void 0,
         isFixed: md.isFixed || void 0,
+        reactComponents: md.reactComponents || void 0,
+        sourceFile: md.sourceFile || void 0,
+        sourceLine: md.sourceLine || void 0,
+        sourceColumn: md.sourceColumn || void 0,
         isMultiSelect: isMulti,
         kind: "feedback",
         status: "pending"
@@ -586,6 +619,7 @@ function AnnotationPopup({ engine }) {
         ref: taRef,
         value: comment,
         placeholder: "Describe the issue or change\u2026  (\u2318/Ctrl + Enter to submit)",
+        "aria-label": "Annotation comment",
         onChange: (e) => setComment(e.target.value),
         onKeyDown: onKey
       }