angular-grab 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,215 @@
+# angular-grab
+
+> Grab any element in your Angular app and give it to AI coding agents
+
+Point at any element and press **Cmd+C** (Mac) or **Ctrl+C** (Windows/Linux) to copy the component name, file path, and HTML source code to your clipboard. Paste it into Claude, ChatGPT, Copilot, or any AI coding agent for instant context.
+
+## Install
+
+```bash
+npx angular-grab init
+```
+
+Or manually:
+
+```bash
+npm install angular-grab
+```
+
+Then add the provider to your app config:
+
+```typescript
+import { provideAngularGrab } from 'angular-grab/angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAngularGrab(),
+  ],
+};
+```
+
+And update `angular.json` to use the angular-grab builders:
+
+```json
+{
+  "architect": {
+    "build": {
+      "builder": "angular-grab:application"
+    },
+    "serve": {
+      "builder": "angular-grab:dev-server"
+    }
+  }
+}
+```
+
+## Usage
+
+Once installed, hover over any UI element in your browser and press:
+
+- **Cmd+C** on Mac
+- **Ctrl+C** on Windows/Linux
+
+This copies the element's context to your clipboard:
+
+```
+<button class="submit-btn">Save</button>
+in SubmitButtonComponent at src/app/submit-button/submit-button.component.ts:12
+in FormComponent at src/app/form/form.component.ts:8
+in AppComponent at src/app/app.component.ts:5
+```
+
+The output includes the cleaned HTML, the full Angular component stack trace, and source file locations.
+
+## Features
+
+- **Element selection** via keyboard shortcut or floating toolbar
+- **Component stack trace** -- full Angular component ancestor chain with file paths
+- **Open in VS Code** -- click file paths in the toast to open at the exact line
+- **Freeze mode** -- freeze the page to grab tooltips, dropdowns, and hover menus
+- **Floating toolbar** with selection, history, actions, freeze, theme, and enable controls
+- **History** of previously grabbed elements with one-click re-copy
+- **Dark / light / system theme** for all UI
+- **Plugin system** for custom actions, hooks, and theme overrides
+- **Crosshair guidelines** during selection mode
+- **Zero production impact** -- automatically disabled outside dev mode
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| Cmd+C / Ctrl+C (hold) | Activate selection mode |
+| Click | Select element and copy |
+| F (during selection) | Toggle freeze mode |
+| Escape | Cancel comment popover |
+
+## Configuration
+
+```typescript
+provideAngularGrab({
+  activationKey: 'Meta+C',       // Keyboard shortcut
+  activationMode: 'hold',        // 'hold' or 'toggle'
+  keyHoldDuration: 0,            // ms to hold before activating
+  maxContextLines: 20,           // Max HTML lines in clipboard
+  enabled: true,                 // Master switch
+  enableInInputs: false,         // Allow in input/textarea
+  devOnly: true,                 // Only active in dev mode
+  showToolbar: true,             // Show floating toolbar
+  themeMode: 'dark',             // 'dark' | 'light' | 'system'
+});
+```
+
+## Toolbar
+
+The floating toolbar provides quick access to all features without keyboard shortcuts:
+
+| Button | Action |
+|--------|--------|
+| Hand | Toggle selection mode |
+| Clock | Show grab history |
+| Ellipsis | Actions menu (Copy Element, Copy Styles, Copy HTML, Comment, Clear History) |
+| Snowflake | Toggle freeze mode |
+| Sun/Moon | Cycle theme (dark / light / system) |
+| Power | Enable/disable angular-grab |
+| X | Dismiss toolbar |
+
+Dismissing the toolbar doesn't disable angular-grab -- keyboard shortcuts still work, and activating selection mode brings the toolbar back.
+
+## Plugin System
+
+```typescript
+import { registerAngularGrabPlugin } from 'angular-grab/angular';
+
+registerAngularGrabPlugin({
+  name: 'my-plugin',
+  hooks: {
+    onElementSelect(context) {
+      console.log('Selected:', context.selector);
+    },
+    onCopySuccess(text, context) {
+      console.log('Copied:', context.componentName);
+    },
+    transformCopyContent(text, context) {
+      return `// From ${context.componentName}\n${text}`;
+    },
+  },
+});
+```
+
+### Plugin Hooks
+
+| Hook | Description |
+|------|-------------|
+| `onActivate` | Selection mode activated |
+| `onDeactivate` | Selection mode deactivated |
+| `onElementHover` | Mouse hovers over an element |
+| `onElementSelect` | Element is selected |
+| `onBeforeCopy` | About to copy to clipboard |
+| `onCopySuccess` | Successfully copied |
+| `onCopyError` | Copy failed |
+| `transformCopyContent` | Transform clipboard text before copying |
+
+### Plugin Theme Overrides
+
+```typescript
+registerAngularGrabPlugin({
+  name: 'custom-theme',
+  theme: {
+    overlayBorderColor: '#10b981',
+    overlayBgColor: 'rgba(16, 185, 129, 0.1)',
+    toolbarBgColor: '#1a1a2e',
+    toolbarAccentColor: '#10b981',
+  },
+});
+```
+
+## API
+
+Access the API programmatically via Angular's dependency injection:
+
+```typescript
+import { inject } from '@angular/core';
+import { ANGULAR_GRAB_API } from 'angular-grab/angular';
+
+const api = inject(ANGULAR_GRAB_API);
+api.activate();
+api.setThemeMode('light');
+```
+
+### `AngularGrabAPI`
+
+| Method | Description |
+|--------|-------------|
+| `activate()` | Enter selection mode |
+| `deactivate()` | Exit selection mode |
+| `toggle()` | Toggle selection mode |
+| `isActive()` | Check if selection mode is active |
+| `setOptions(opts)` | Update options |
+| `registerPlugin(plugin)` | Register a plugin |
+| `unregisterPlugin(name)` | Remove a plugin |
+| `setComponentResolver(fn)` | Custom component resolver |
+| `setSourceResolver(fn)` | Custom source file resolver |
+| `showToolbar()` | Show the floating toolbar |
+| `hideToolbar()` | Hide the floating toolbar |
+| `setThemeMode(mode)` | Set theme ('dark', 'light', 'system') |
+| `getHistory()` | Get grab history entries |
+| `clearHistory()` | Clear grab history |
+| `dispose()` | Clean up everything |
+
+## Subpath Exports
+
+The `angular-grab` package provides subpath exports for different build tool integrations:
+
+| Import | Description |
+|--------|-------------|
+| `angular-grab` | Core picker engine and types |
+| `angular-grab/angular` | Angular integration (providers, services, resolvers) |
+| `angular-grab/esbuild` | esbuild plugin for source location injection |
+| `angular-grab/vite` | Vite plugin for source location injection |
+| `angular-grab/webpack` | Webpack plugin for source location injection |
+| `angular-grab/builder` | Angular CLI custom builders |
+| `angular-grab/global` | IIFE browser bundle |
+
+## License
+
+MIT

package/examples/angular-19-app/.editorconfig

@@ -0,0 +1,17 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+ij_typescript_use_double_quotes = false
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/examples/angular-19-app/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=827846
+  "recommendations": ["angular.ng-template"]
+}

package/examples/angular-19-app/.vscode/launch.json

@@ -0,0 +1,20 @@
+{
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "ng serve",
+      "type": "chrome",
+      "request": "launch",
+      "preLaunchTask": "npm: start",
+      "url": "http://localhost:4200/"
+    },
+    {
+      "name": "ng test",
+      "type": "chrome",
+      "request": "launch",
+      "preLaunchTask": "npm: test",
+      "url": "http://localhost:9876/debug.html"
+    }
+  ]
+}

package/examples/angular-19-app/.vscode/mcp.json

@@ -0,0 +1,9 @@
+{
+  // For more information, visit: https://angular.dev/ai/mcp
+  "servers": {
+    "angular-cli": {
+      "command": "npx",
+      "args": ["-y", "@angular/cli", "mcp"]
+    }
+  }
+}

package/examples/angular-19-app/.vscode/tasks.json

@@ -0,0 +1,42 @@
+{
+  // For more information, visit: https://go.microsoft.com/fwlink/?LinkId=733558
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "start",
+      "isBackground": true,
+      "problemMatcher": {
+        "owner": "typescript",
+        "pattern": "$tsc",
+        "background": {
+          "activeOnStart": true,
+          "beginsPattern": {
+            "regexp": "Changes detected"
+          },
+          "endsPattern": {
+            "regexp": "bundle generation (complete|failed)"
+          }
+        }
+      }
+    },
+    {
+      "type": "npm",
+      "script": "test",
+      "isBackground": true,
+      "problemMatcher": {
+        "owner": "typescript",
+        "pattern": "$tsc",
+        "background": {
+          "activeOnStart": true,
+          "beginsPattern": {
+            "regexp": "Changes detected"
+          },
+          "endsPattern": {
+            "regexp": "bundle generation (complete|failed)"
+          }
+        }
+      }
+    }
+  ]
+}

package/examples/angular-19-app/README.md

@@ -0,0 +1,59 @@
+# Angular19App
+
+This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.1.1.
+
+## Development server
+
+To start a local development server, run:
+
+```bash
+ng serve
+```
+
+Once the server is running, open your browser and navigate to `http://localhost:4200/`. The application will automatically reload whenever you modify any of the source files.
+
+## Code scaffolding
+
+Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+
+```bash
+ng generate component component-name
+```
+
+For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+
+```bash
+ng generate --help
+```
+
+## Building
+
+To build the project run:
+
+```bash
+ng build
+```
+
+This will compile your project and store the build artifacts in the `dist/` directory. By default, the production build optimizes your application for performance and speed.
+
+## Running unit tests
+
+To execute unit tests with the [Vitest](https://vitest.dev/) test runner, use the following command:
+
+```bash
+ng test
+```
+
+## Running end-to-end tests
+
+For end-to-end (e2e) testing, run:
+
+```bash
+ng e2e
+```
+
+Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+
+## Additional Resources
+
+For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.

package/examples/angular-19-app/angular.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "cli": {
+    "packageManager": "pnpm",
+    "analytics": false
+  },
+  "newProjectRoot": "projects",
+  "projects": {
+    "angular-19-app": {
+      "projectType": "application",
+      "schematics": {},
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "angular-grab:application",
+          "options": {
+            "browser": "src/main.ts",
+            "tsConfig": "tsconfig.app.json",
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "public"
+              }
+            ],
+            "styles": [
+              "src/styles.css"
+            ]
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kB",
+                  "maximumError": "1MB"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "4kB",
+                  "maximumError": "8kB"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "angular-grab:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "angular-19-app:build:production"
+            },
+            "development": {
+              "buildTarget": "angular-19-app:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        },
+        "test": {
+          "builder": "@angular/build:unit-test"
+        }
+      }
+    }
+  }
+}

package/examples/angular-19-app/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "angular-19-app",
+  "version": "0.0.0",
+  "scripts": {
+    "ng": "ng",
+    "start": "ng serve",
+    "build": "ng build",
+    "watch": "ng build --watch --configuration development",
+    "test": "ng test"
+  },
+  "prettier": {
+    "printWidth": 100,
+    "singleQuote": true,
+    "overrides": [
+      {
+        "files": "*.html",
+        "options": {
+          "parser": "angular"
+        }
+      }
+    ]
+  },
+  "private": true,
+  "packageManager": "pnpm@9.15.0",
+  "dependencies": {
+    "@angular/common": "^21.1.0",
+    "@angular/compiler": "^21.1.0",
+    "@angular/core": "^21.1.0",
+    "@angular/forms": "^21.1.0",
+    "@angular/platform-browser": "^21.1.0",
+    "@angular/router": "^21.1.0",
+    "angular-grab": "workspace:*",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@angular/build": "^21.1.1",
+    "@angular/cli": "^21.1.1",
+    "@angular/compiler-cli": "^21.1.0",
+    "jsdom": "^27.1.0",
+    "typescript": "~5.9.2",
+    "vitest": "^4.0.8"
+  }
+}

package/examples/angular-19-app/src/app/app.config.ts

@@ -0,0 +1,13 @@
+import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { provideAngularGrab } from 'angular-grab/angular';
+
+import { routes } from './app.routes';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideBrowserGlobalErrorListeners(),
+    provideRouter(routes),
+    provideAngularGrab(),
+  ],
+};

package/examples/angular-19-app/src/app/app.css

@@ -0,0 +1,37 @@
+.main {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 32px 24px;
+}
+
+.hero {
+  text-align: center;
+  margin-bottom: 40px;
+}
+
+.hero h1 {
+  font-size: 2rem;
+  font-weight: 700;
+  margin: 0 0 12px;
+}
+
+.hero p {
+  color: #64748b;
+  font-size: 1.1rem;
+  line-height: 1.6;
+}
+
+.hero kbd {
+  background: #f1f5f9;
+  border: 1px solid #e2e8f0;
+  border-radius: 4px;
+  padding: 2px 6px;
+  font-family: monospace;
+  font-size: 0.9rem;
+}
+
+.cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 20px;
+}

package/examples/angular-19-app/src/app/app.html

@@ -0,0 +1,25 @@
+<app-header />
+
+<main class="main">
+  <section class="hero">
+    <h1>angular-grab Demo</h1>
+    <p>Hold <kbd>⌘C</kbd> (Mac) or <kbd>Ctrl+C</kbd> (Windows) and hover over any element to grab its context for AI coding agents.</p>
+  </section>
+
+  <section class="cards">
+    <app-card
+      title="Element Picker"
+      body="Hover over any UI element while holding the activation key. A blue overlay highlights the element under your cursor."
+    />
+    <app-card
+      title="Component Resolution"
+      body="angular-grab uses Angular's debug APIs to identify which component owns each element, including the component class name."
+    />
+    <app-card
+      title="Source Mapping"
+      body="The esbuild plugin injects data-ng-source attributes at build time, mapping each component to its source file and line number."
+    />
+  </section>
+
+  <app-popover />
+</main>

package/examples/angular-19-app/src/app/app.routes.ts

@@ -0,0 +1,3 @@
+import { Routes } from '@angular/router';
+
+export const routes: Routes = [];

package/examples/angular-19-app/src/app/app.spec.ts

@@ -0,0 +1,23 @@
+import { TestBed } from '@angular/core/testing';
+import { App } from './app';
+
+describe('App', () => {
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [App],
+    }).compileComponents();
+  });
+
+  it('should create the app', () => {
+    const fixture = TestBed.createComponent(App);
+    const app = fixture.componentInstance;
+    expect(app).toBeTruthy();
+  });
+
+  it('should render title', async () => {
+    const fixture = TestBed.createComponent(App);
+    await fixture.whenStable();
+    const compiled = fixture.nativeElement as HTMLElement;
+    expect(compiled.querySelector('h1')?.textContent).toContain('angular-grab Demo');
+  });
+});

package/examples/angular-19-app/src/app/app.ts

@@ -0,0 +1,12 @@
+import { Component } from '@angular/core';
+import { HeaderComponent } from './header/header.component';
+import { CardComponent } from './card/card.component';
+import { PopoverComponent } from './popover/popover.component';
+
+@Component({
+  selector: 'app-root',
+  imports: [HeaderComponent, CardComponent, PopoverComponent],
+  templateUrl: './app.html',
+  styleUrl: './app.css',
+})
+export class App {}

package/examples/angular-19-app/src/app/button/button.component.ts

@@ -0,0 +1,25 @@
+import { Component, Input } from '@angular/core';
+
+@Component({
+  selector: 'app-button',
+  standalone: true,
+  template: `
+    <button class="btn" type="button">{{ label }}</button>
+  `,
+  styles: [`
+    .btn {
+      padding: 8px 16px;
+      background: #3b82f6;
+      color: white;
+      border: none;
+      border-radius: 6px;
+      font-size: 0.875rem;
+      cursor: pointer;
+      transition: background 0.15s;
+    }
+    .btn:hover { background: #2563eb; }
+  `],
+})
+export class ButtonComponent {
+  @Input() label = 'Click me';
+}

package/examples/angular-19-app/src/app/card/card.component.ts

@@ -0,0 +1,33 @@
+import { Component, Input } from '@angular/core';
+import { ButtonComponent } from '../button/button.component';
+
+@Component({
+  selector: 'app-card',
+  standalone: true,
+  template: `
+    <div class="card">
+      <h2 class="card-title">{{ title }}</h2>
+      <p class="card-body">{{ body }}</p>
+      <div class="card-footer">
+        <app-button [label]="'Learn More'" />
+      </div>
+    </div>
+  `,
+  styles: [`
+    .card {
+      border: 1px solid #e2e8f0;
+      border-radius: 8px;
+      padding: 20px;
+      background: white;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+    .card-title { font-size: 1.1rem; font-weight: 600; margin: 0 0 8px; }
+    .card-body { color: #64748b; margin: 0 0 16px; line-height: 1.5; }
+    .card-footer { display: flex; justify-content: flex-end; }
+  `],
+  imports: [ButtonComponent],
+})
+export class CardComponent {
+  @Input() title = '';
+  @Input() body = '';
+}