angular-grab 0.1.0 → 0.1.2

package/packages/angular-grab/src/angular/__tests__/context-builder.test.ts

@@ -0,0 +1,216 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ComponentStackEntry } from '../../core';
+
+vi.mock('../resolvers/component-resolver', () => ({
+  resolveComponent: vi.fn(),
+}));
+
+vi.mock('../resolvers/source-resolver', () => ({
+  resolveSource: vi.fn(),
+  resolveSourceForComponent: vi.fn(),
+}));
+
+import { buildContext } from '../resolvers/context-builder';
+import { resolveComponent } from '../resolvers/component-resolver';
+import { resolveSource, resolveSourceForComponent } from '../resolvers/source-resolver';
+
+const mockedResolveComponent = vi.mocked(resolveComponent);
+const mockedResolveSource = vi.mocked(resolveSource);
+const mockedResolveSourceForComponent = vi.mocked(resolveSourceForComponent);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+
+  mockedResolveComponent.mockReturnValue({
+    name: null,
+    hostElement: null,
+    stack: [],
+  });
+
+  mockedResolveSource.mockReturnValue({
+    filePath: null,
+    line: null,
+    column: null,
+  });
+
+  mockedResolveSourceForComponent.mockReturnValue({
+    filePath: null,
+    line: null,
+    column: null,
+  });
+});
+
+describe('buildContext', () => {
+  it('produces correct ElementContext shape', () => {
+    const el = document.createElement('div');
+    el.innerHTML = 'hello';
+
+    const ctx = buildContext(el);
+
+    expect(ctx).toEqual(
+      expect.objectContaining({
+        element: el,
+        html: expect.any(String),
+        componentName: null,
+        filePath: null,
+        line: null,
+        column: null,
+        componentStack: [],
+        selector: expect.any(String),
+        cssClasses: expect.any(Array),
+      }),
+    );
+  });
+
+  it('includes component name from resolver', () => {
+    mockedResolveComponent.mockReturnValue({
+      name: 'MyComponent',
+      hostElement: null,
+      stack: [],
+    });
+
+    const el = document.createElement('div');
+    const ctx = buildContext(el);
+
+    expect(ctx.componentName).toBe('MyComponent');
+  });
+
+  it('includes file path from source resolver', () => {
+    mockedResolveSource.mockReturnValue({
+      filePath: 'src/app/app.component.ts',
+      line: 42,
+      column: 3,
+    });
+
+    const el = document.createElement('div');
+    const ctx = buildContext(el);
+
+    expect(ctx.filePath).toBe('src/app/app.component.ts');
+    expect(ctx.line).toBe(42);
+    expect(ctx.column).toBe(3);
+  });
+
+  it('builds component stack from resolver stack', () => {
+    mockedResolveComponent.mockReturnValue({
+      name: 'Child',
+      hostElement: null,
+      stack: [
+        { name: 'Child', hostElement: null },
+        { name: 'Parent', hostElement: null },
+      ],
+    });
+    mockedResolveSourceForComponent
+      .mockReturnValueOnce({ filePath: 'child.ts', line: 5, column: null })
+      .mockReturnValueOnce({ filePath: 'parent.ts', line: 20, column: null });
+
+    const el = document.createElement('div');
+    const ctx = buildContext(el);
+
+    expect(ctx.componentStack).toHaveLength(2);
+    expect(ctx.componentStack[0]).toEqual({
+      name: 'Child',
+      filePath: 'child.ts',
+      line: 5,
+      column: null,
+    });
+    expect(ctx.componentStack[1]).toEqual({
+      name: 'Parent',
+      filePath: 'parent.ts',
+      line: 20,
+      column: null,
+    });
+  });
+
+  it('truncates long HTML with truncation marker', () => {
+    const el = document.createElement('div');
+    // Create content longer than MAX_HTML_LENGTH (2000)
+    el.textContent = 'x'.repeat(2100);
+
+    const ctx = buildContext(el);
+
+    expect(ctx.html.length).toBeLessThanOrEqual(2000 + '<!-- truncated -->'.length);
+    expect(ctx.html).toContain('<!-- truncated -->');
+  });
+
+  it('does not truncate short HTML', () => {
+    const el = document.createElement('div');
+    el.textContent = 'short';
+
+    const ctx = buildContext(el);
+
+    expect(ctx.html).not.toContain('<!-- truncated -->');
+    expect(ctx.html).toContain('short');
+  });
+
+  it('generates CSS selector for element', () => {
+    const el = document.createElement('div');
+    el.id = 'myid';
+    document.body.appendChild(el);
+
+    const ctx = buildContext(el);
+    expect(ctx.selector).toContain('div#myid');
+
+    document.body.removeChild(el);
+  });
+
+  it('generates selector with classes', () => {
+    const el = document.createElement('span');
+    el.className = 'foo bar';
+    document.body.appendChild(el);
+
+    const ctx = buildContext(el);
+    expect(ctx.selector).toContain('span.foo.bar');
+
+    document.body.removeChild(el);
+  });
+
+  it('generates selector with nth-of-type for siblings', () => {
+    const parent = document.createElement('div');
+    const child1 = document.createElement('span');
+    const child2 = document.createElement('span');
+    parent.appendChild(child1);
+    parent.appendChild(child2);
+    document.body.appendChild(parent);
+
+    const ctx = buildContext(child2);
+    expect(ctx.selector).toContain('nth-of-type(2)');
+
+    document.body.removeChild(parent);
+  });
+
+  it('filters out Angular CSS classes', () => {
+    const el = document.createElement('div');
+    el.classList.add('my-class', 'ng-star-inserted', '_ngcontent-abc', 'real-class');
+
+    const ctx = buildContext(el);
+
+    expect(ctx.cssClasses).toContain('my-class');
+    expect(ctx.cssClasses).toContain('real-class');
+    expect(ctx.cssClasses).not.toContain('ng-star-inserted');
+    expect(ctx.cssClasses).not.toContain('_ngcontent-abc');
+  });
+
+  it('handles element with no classes', () => {
+    const el = document.createElement('div');
+    const ctx = buildContext(el);
+    expect(ctx.cssClasses).toEqual([]);
+  });
+
+  it('stops selector at element with id', () => {
+    const grandparent = document.createElement('section');
+    const parent = document.createElement('div');
+    parent.id = 'stop-here';
+    const child = document.createElement('span');
+    grandparent.appendChild(parent);
+    parent.appendChild(child);
+    document.body.appendChild(grandparent);
+
+    const ctx = buildContext(child);
+    // The selector should start from div#stop-here because id terminates the walk
+    expect(ctx.selector).toContain('div#stop-here');
+    expect(ctx.selector).toContain('span');
+
+    document.body.removeChild(grandparent);
+  });
+});

package/packages/angular-grab/src/angular/angular-grab.service.ts

@@ -0,0 +1,62 @@
+import { init } from '../core';
+import type { AngularGrabAPI, AngularGrabOptions, Plugin } from '../core';
+import { resolveComponent } from './resolvers/component-resolver';
+import { resolveSource } from './resolvers/source-resolver';
+
+declare const ngDevMode: boolean | undefined;
+
+let instance: AngularGrabAPI | null = null;
+
+/**
+ * Initialize angular-grab. Registers Angular-specific component and source
+ * resolvers, then returns the API handle. Idempotent — subsequent calls
+ * return the same instance.
+ */
+export function initAngularGrab(options?: Partial<AngularGrabOptions>): AngularGrabAPI {
+  if (instance) return instance;
+
+  // No-op in production
+  if (options?.devOnly !== false && typeof ngDevMode !== 'undefined' && !ngDevMode) {
+    instance = createNoOpApi();
+    return instance;
+  }
+
+  instance = init(options);
+  instance.setComponentResolver((el) => resolveComponent(el));
+  instance.setSourceResolver((el) => resolveSource(el));
+
+  return instance;
+}
+
+export function getAngularGrabApi(): AngularGrabAPI | null {
+  return instance;
+}
+
+export function registerAngularGrabPlugin(plugin: Plugin): void {
+  instance?.registerPlugin(plugin);
+}
+
+export function disposeAngularGrab(): void {
+  instance?.dispose();
+  instance = null;
+}
+
+function createNoOpApi(): AngularGrabAPI {
+  return {
+    activate() {},
+    deactivate() {},
+    toggle() {},
+    isActive() { return false; },
+    setOptions() {},
+    registerPlugin() {},
+    unregisterPlugin() {},
+    setComponentResolver() {},
+    setSourceResolver() {},
+    showToolbar() {},
+    hideToolbar() {},
+    setThemeMode() {},
+    getHistory() { return []; },
+    clearHistory() {},
+    dispose() {},
+  };
+}

package/packages/angular-grab/src/angular/index.ts

@@ -0,0 +1,13 @@
+// Resolvers
+export { resolveComponent } from './resolvers/component-resolver';
+export { resolveSource } from './resolvers/source-resolver';
+export { buildContext } from './resolvers/context-builder';
+
+// Angular integration
+export {
+  initAngularGrab,
+  getAngularGrabApi,
+  registerAngularGrabPlugin,
+  disposeAngularGrab,
+} from './angular-grab.service';
+export { provideAngularGrab, ANGULAR_GRAB_API } from './provide-angular-grab';

package/packages/angular-grab/src/angular/provide-angular-grab.ts

@@ -0,0 +1,22 @@
+import {
+  InjectionToken,
+  makeEnvironmentProviders,
+  provideEnvironmentInitializer,
+  type EnvironmentProviders,
+} from '@angular/core';
+import type { AngularGrabOptions, AngularGrabAPI } from '../core';
+import { initAngularGrab } from './angular-grab.service';
+
+export const ANGULAR_GRAB_API = new InjectionToken<AngularGrabAPI>('ANGULAR_GRAB_API');
+
+export function provideAngularGrab(
+  options?: Partial<AngularGrabOptions>,
+): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    {
+      provide: ANGULAR_GRAB_API,
+      useFactory: () => initAngularGrab(options),
+    },
+    provideEnvironmentInitializer(() => initAngularGrab(options)),
+  ]);
+}

package/packages/angular-grab/src/angular/resolvers/component-resolver.ts

@@ -0,0 +1,71 @@
+import { getNgApi, cleanComponentName } from './ng-utils';
+
+export function resolveComponent(element: Element): {
+  name: string | null;
+  hostElement: Element | null;
+  stack: Array<{ name: string; hostElement: Element | null }>;
+} {
+  const ng = getNgApi();
+  if (!ng) return { name: null, hostElement: null, stack: [] };
+
+  const stack: Array<{ name: string; hostElement: Element | null }> = [];
+  const seen = new Set<any>();
+
+  // Walk up the DOM collecting every Angular component
+  let current: Element | null = element;
+  while (current) {
+    const comp = ng.getComponent(current);
+    if (comp && !seen.has(comp)) {
+      seen.add(comp);
+      stack.push({
+        name: cleanComponentName(comp.constructor.name),
+        hostElement: current,
+      });
+    }
+    current = current.parentElement;
+  }
+
+  // If no direct component found, try getOwningComponent for the original element
+  if (stack.length === 0) {
+    let walk: Element | null = element;
+    while (walk) {
+      const owning = ng.getOwningComponent(walk);
+      if (owning && !seen.has(owning)) {
+        seen.add(owning);
+        // Find the host element
+        let host: Element | null = walk.parentElement;
+        while (host) {
+          if (ng.getComponent(host) === owning) break;
+          host = host.parentElement;
+        }
+        stack.push({
+          name: cleanComponentName(owning.constructor.name),
+          hostElement: host ?? walk.parentElement,
+        });
+        // Continue walking from the host to collect parents
+        current = host?.parentElement ?? walk.parentElement?.parentElement ?? null;
+        while (current) {
+          const comp = ng.getComponent(current);
+          if (comp && !seen.has(comp)) {
+            seen.add(comp);
+            stack.push({
+              name: cleanComponentName(comp.constructor.name),
+              hostElement: current,
+            });
+          }
+          current = current.parentElement;
+        }
+        break;
+      }
+      walk = walk.parentElement;
+    }
+  }
+
+  const closest = stack.length > 0 ? stack[0] : { name: null, hostElement: null };
+
+  return {
+    name: closest.name,
+    hostElement: closest.hostElement,
+    stack,
+  };
+}

package/packages/angular-grab/src/angular/resolvers/context-builder.ts

@@ -0,0 +1,86 @@
+import { filterAngularClasses, type ElementContext, type ComponentStackEntry } from '../../core';
+import { resolveComponent } from './component-resolver';
+import { resolveSource, resolveSourceForComponent } from './source-resolver';
+
+const MAX_HTML_LENGTH = 2000;
+
+export function buildContext(element: Element): ElementContext {
+  const compResult = resolveComponent(element);
+  const { filePath, line, column } = resolveSource(element);
+  const html = extractHtml(element);
+  const selector = generateSelector(element);
+
+  const cssClasses = filterAngularClasses(element.classList);
+
+  const componentStack: ComponentStackEntry[] = compResult.stack.map((entry) => {
+    const src = resolveSourceForComponent(entry.name);
+    return {
+      name: entry.name,
+      filePath: src.filePath,
+      line: src.line,
+      column: src.column,
+    };
+  });
+
+  return {
+    element,
+    html,
+    componentName: compResult.name,
+    filePath,
+    line,
+    column,
+    componentStack,
+    selector,
+    cssClasses,
+  };
+}
+
+function extractHtml(element: Element): string {
+  const html = element.outerHTML;
+  if (html.length <= MAX_HTML_LENGTH) return html;
+  return html.slice(0, MAX_HTML_LENGTH) + '<!-- truncated -->';
+}
+
+function generateSelector(element: Element): string {
+  const parts: string[] = [];
+  let current: Element | null = element;
+
+  while (current && current !== document.documentElement) {
+    let selector = current.tagName.toLowerCase();
+
+    if (current.id) {
+      selector += `#${current.id}`;
+      parts.unshift(selector);
+      break;
+    }
+
+    const className = current.getAttribute('class');
+    if (className) {
+      const classes = className
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 3);
+      if (classes.length > 0) {
+        selector += '.' + classes.join('.');
+      }
+    }
+
+    // Add nth-of-type if there are sibling elements with the same tag
+    const parent = current.parentElement;
+    if (parent) {
+      const siblings = Array.from(parent.children).filter(
+        (s) => s.tagName === current!.tagName
+      );
+      if (siblings.length > 1) {
+        const index = siblings.indexOf(current) + 1;
+        selector += `:nth-of-type(${index})`;
+      }
+    }
+
+    parts.unshift(selector);
+    current = current.parentElement;
+  }
+
+  return parts.join(' > ');
+}

package/packages/angular-grab/src/angular/resolvers/ng-utils.ts

@@ -0,0 +1,14 @@
+export interface NgDebugApi {
+  getComponent<T>(element: Element): T | null;
+  getOwningComponent<T>(element: Element): T | null;
+  getDirectives(element: Element): any[];
+}
+
+export function getNgApi(): NgDebugApi | null {
+  if (typeof window === 'undefined') return null;
+  return (window as any).ng || null;
+}
+
+export function cleanComponentName(name: string): string {
+  return name.startsWith('_') ? name.slice(1) : name;
+}

package/packages/angular-grab/src/angular/resolvers/source-resolver.ts

@@ -0,0 +1,61 @@
+import { type NgDebugApi, getNgApi, cleanComponentName } from './ng-utils';
+
+interface SourceMapEntry {
+  file: string;
+  line: number;
+}
+
+function getSourceMap(): Record<string, SourceMapEntry> | null {
+  return (globalThis as any).__ANGULAR_GRAB_SOURCE_MAP__ ?? null;
+}
+
+export function resolveSource(element: Element): {
+  filePath: string | null;
+  line: number | null;
+  column: number | null;
+} {
+  const sourceMap = getSourceMap();
+  if (!sourceMap) return { filePath: null, line: null, column: null };
+
+  const ng = getNgApi();
+  if (!ng) return { filePath: null, line: null, column: null };
+
+  // Find the component that owns this element
+  const componentName = findComponentName(element, ng);
+  if (!componentName) return { filePath: null, line: null, column: null };
+
+  const entry = sourceMap[componentName];
+  if (!entry) return { filePath: null, line: null, column: null };
+
+  return { filePath: entry.file, line: entry.line, column: null };
+}
+
+export function resolveSourceForComponent(componentName: string): {
+  filePath: string | null;
+  line: number | null;
+  column: number | null;
+} {
+  const sourceMap = getSourceMap();
+  if (!sourceMap) return { filePath: null, line: null, column: null };
+
+  const entry = sourceMap[componentName];
+  if (!entry) return { filePath: null, line: null, column: null };
+
+  return { filePath: entry.file, line: entry.line, column: null };
+}
+
+function findComponentName(element: Element, ng: NgDebugApi): string | null {
+  // Try direct component on this element
+  const direct = ng.getComponent(element);
+  if (direct) return cleanComponentName(direct.constructor.name);
+
+  // Walk up to find owning component
+  let current: Element | null = element;
+  while (current) {
+    const owning = ng.getOwningComponent(current);
+    if (owning) return cleanComponentName(owning.constructor.name);
+    current = current.parentElement;
+  }
+
+  return null;
+}

package/packages/angular-grab/src/builder/__tests__/builder.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+const PACKAGE_ROOT = join(__dirname, '..', '..', '..');
+
+describe('builders.json', () => {
+  const buildersJson = JSON.parse(
+    readFileSync(join(PACKAGE_ROOT, 'builders.json'), 'utf8'),
+  );
+
+  it('has a builders property', () => {
+    expect(buildersJson.builders).toBeDefined();
+    expect(typeof buildersJson.builders).toBe('object');
+  });
+
+  it('defines an application builder', () => {
+    const app = buildersJson.builders.application;
+    expect(app).toBeDefined();
+    expect(app.implementation).toBeDefined();
+    expect(app.schema).toBeDefined();
+    expect(app.description).toBeDefined();
+  });
+
+  it('defines a dev-server builder', () => {
+    const devServer = buildersJson.builders['dev-server'];
+    expect(devServer).toBeDefined();
+    expect(devServer.implementation).toBeDefined();
+    expect(devServer.schema).toBeDefined();
+    expect(devServer.description).toBeDefined();
+  });
+
+  it('application builder points to correct implementation path', () => {
+    const app = buildersJson.builders.application;
+    expect(app.implementation).toContain('builders/application');
+  });
+
+  it('dev-server builder points to correct implementation path', () => {
+    const devServer = buildersJson.builders['dev-server'];
+    expect(devServer.implementation).toContain('builders/dev-server');
+  });
+});
+
+describe('package.json', () => {
+  const packageJson = JSON.parse(
+    readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'),
+  );
+
+  it('declares builders field pointing to builders.json', () => {
+    expect(packageJson.builders).toBe('./builders.json');
+  });
+
+  it('exports builders.json', () => {
+    expect(packageJson.exports['./builders.json']).toBe('./builders.json');
+  });
+});
+
+describe('schema files', () => {
+  it('application schema is valid JSON', () => {
+    const schema = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, 'src', 'builder', 'builders', 'application', 'schema.json'), 'utf8'),
+    );
+    expect(schema.type).toBe('object');
+  });
+
+  it('dev-server schema is valid JSON', () => {
+    const schema = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, 'src', 'builder', 'builders', 'dev-server', 'schema.json'), 'utf8'),
+    );
+    expect(schema.type).toBe('object');
+  });
+});

package/packages/angular-grab/src/builder/builders/application/index.ts

@@ -0,0 +1,13 @@
+import { createBuilder } from '@angular-devkit/architect';
+import { buildApplication } from '@angular/build';
+import { angularGrabEsbuildPlugin } from '../../../esbuild-plugin';
+
+export default createBuilder(async function* (options: any, context) {
+  const isProduction = !!options.optimization;
+  yield* buildApplication(options, context, {
+    codePlugins: [angularGrabEsbuildPlugin({
+      rootDir: context.workspaceRoot,
+      enabled: !isProduction,
+    })],
+  });
+});

package/packages/angular-grab/src/builder/builders/dev-server/index.ts

@@ -0,0 +1,9 @@
+import { createBuilder } from '@angular-devkit/architect';
+import { executeDevServerBuilder } from '@angular/build';
+import { angularGrabEsbuildPlugin } from '../../../esbuild-plugin';
+
+export default createBuilder(async function* (options: any, context) {
+  yield* executeDevServerBuilder(options, context, {
+    buildPlugins: [angularGrabEsbuildPlugin({ rootDir: context.workspaceRoot })],
+  });
+});

package/packages/angular-grab/src/builder/index.ts

@@ -0,0 +1,3 @@
+// angular-grab/builder
+// This package provides Angular CLI builders that inject angular-grab source location mapping.
+// Builders are resolved via builders.json — this file is not directly imported by users.