{"_id":"@allystudio/element-inspector","_rev":"2-fef3a1ee8f1e820b79a946bd49fa198d","name":"@allystudio/element-inspector","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@allystudio/element-inspector","version":"0.0.1","keywords":["accessibility","a11y","dom","inspector","element","highlight","headless"],"author":{"name":"Allyship.dev"},"license":"MIT","_id":"@allystudio/element-inspector@0.0.1","maintainers":[{"name":"allystudio","email":"privat@aleksejdix.com"}],"homepage":"https://github.com/allyship-dev/allyship.dev#readme","bugs":{"url":"https://github.com/allyship-dev/allyship.dev/issues"},"dist":{"shasum":"ec11d5668fad3d7be87c41b81cd542d66c1f0bee","tarball":"https://registry.npmjs.org/@allystudio/element-inspector/-/element-inspector-0.0.1.tgz","fileCount":22,"integrity":"sha512-5lqIm+/GPpmFw04yEhwaFsNUtc2Row/AdEPWr0JWl+0nE5+YbsxkSydBpPweuq6uXg+YxflOiBW0bYNiTCS9aA==","signatures":[{"sig":"MEUCIFN09LlREcDO8IAORfvcSiAejgSIxbb4icocEoAxeysjAiEAj1sN2SPKYeCtQOAVboLljuhrbv62M9ieYZvBG1DIR40=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66150},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./types":{"types":"./dist/types.d.ts","import":"./dist/types.js"}},"gitHead":"51a0130ca44790bcfd274dc137c332afe9dde5c1","scripts":{"dev":"tsc --watch","lint":"eslint . --max-warnings 0","test":"vitest","build":"tsc","clean":"rm -rf dist"},"_npmUser":{"name":"allystudio","actor":{"name":"allystudio","type":"user","email":"privat@aleksejdix.com"},"email":"privat@aleksejdix.com"},"repository":{"url":"git+https://github.com/allyship-dev/allyship.dev.git","type":"git","directory":"packages/element-inspector"},"_npmVersion":"10.9.2","description":"Headless DOM element inspection and highlighting library","directories":{},"_nodeVersion":"23.11.0","dependencies":{"@allystudio/accessibility-utils":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.8","playwright":"^1.53.0","typescript":"^5.6.3","@vitest/browser":"^2.1.9","@vitest/coverage-v8":"2.1.9","@workspace/eslint-config":"*","@workspace/typescript-config":"*"},"peerDependencies":{"typescript":">=4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/element-inspector_0.0.1_1750390615688_0.4582471969308224","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@allystudio/element-inspector","version":"0.1.0","description":"Headless DOM element inspection and highlighting library","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./types":{"import":"./dist/types.js","types":"./dist/types.d.ts"}},"scripts":{"build":"tsc","dev":"tsc --watch","lint":"eslint . --max-warnings 0","test":"vitest","clean":"rm -rf dist"},"keywords":["accessibility","a11y","dom","inspector","element","highlight","headless"],"author":{"name":"Allyship.dev"},"license":"MIT","devDependencies":{"@vitest/browser":"^2.1.9","@vitest/coverage-v8":"2.1.9","@workspace/eslint-config":"*","@workspace/typescript-config":"*","playwright":"^1.53.0","typescript":"^5.6.3","vitest":"^2.1.8"},"peerDependencies":{"typescript":">=4.0.0"},"repository":{"type":"git","url":"git+https://github.com/allyship-dev/allyship.dev.git","directory":"packages/element-inspector"},"publishConfig":{"access":"public"},"dependencies":{"@allystudio/accessibility-utils":"^0.1.0"},"_id":"@allystudio/element-inspector@0.1.0","gitHead":"51a0130ca44790bcfd274dc137c332afe9dde5c1","bugs":{"url":"https://github.com/allyship-dev/allyship.dev/issues"},"homepage":"https://github.com/allyship-dev/allyship.dev#readme","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-BJHd5HKdcCDKOPmlNOL2n0PxB7Ki7PU/tEpV6XWexdRO+OEJZ57VIqh+UK1G1/cyjSPLtX1ue56U0rZm1i5I6g==","shasum":"ed9bccc973ea5c95e33eafd008b6d8c2f4c4daa6","tarball":"https://registry.npmjs.org/@allystudio/element-inspector/-/element-inspector-0.1.0.tgz","fileCount":22,"unpackedSize":66768,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFRuGBggixcDzDWXKTDuNJyjfUYCfIphWeMyT7bEHCMMAiAMgf4MfIqHmx0x89lkvVJPyya8AmYg3o9QIy/eMYZsfg=="}]},"_npmUser":{"name":"allystudio","email":"privat@aleksejdix.com","actor":{"name":"allystudio","email":"privat@aleksejdix.com","type":"user"}},"directories":{},"maintainers":[{"name":"allystudio","email":"privat@aleksejdix.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/element-inspector_0.1.0_1750398947796_0.7208788517863125"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-20T03:36:55.579Z","modified":"2025-06-20T05:55:48.141Z","0.0.1":"2025-06-20T03:36:55.850Z","0.1.0":"2025-06-20T05:55:47.967Z"},"bugs":{"url":"https://github.com/allyship-dev/allyship.dev/issues"},"author":{"name":"Allyship.dev"},"license":"MIT","homepage":"https://github.com/allyship-dev/allyship.dev#readme","keywords":["accessibility","a11y","dom","inspector","element","highlight","headless"],"repository":{"type":"git","url":"git+https://github.com/allyship-dev/allyship.dev.git","directory":"packages/element-inspector"},"description":"Headless DOM element inspection and highlighting library","maintainers":[{"name":"allystudio","email":"privat@aleksejdix.com"}],"readme":"# @allystudio/element-inspector\n\n**Bring Chrome DevTools' element inspection power directly into your web application.**\n\nA headless, programmable DOM element inspection library that lets you build element selection and analysis features directly into your web apps, browser extensions, or developer tools. Think of it as Chrome DevTools' element inspector, but as a library you can embed anywhere.\n\n## 🤔 What's the Essence?\n\nThis library captures the **core functionality** of Chrome DevTools' element inspector and packages it as a reusable, embeddable library. Instead of switching to DevTools to inspect elements, your users can inspect elements directly within your application interface.\n\n### Chrome DevTools vs @allystudio/element-inspector\n\n| Aspect             | Chrome DevTools                    | @allystudio/element-inspector           |\n|:-------------------|:-----------------------------------|:----------------------------------------|\n| **Environment**    | Separate dev tool window           | Embedded in your app                    |\n| **Audience**       | Developers only                    | Any user (developers, designers, QA)   |\n| **Customization**  | Fixed UI and behavior              | Fully customizable UI and behavior     |\n| **Integration**    | External tool                      | Native part of your app                |\n| **Production Use** | Development only                   | Can be used in production              |\n| **API Access**     | Limited extension API              | Full programmatic control              |\n| **Styling**        | Fixed DevTools theme               | Match your app's design                |\n| **Data Access**    | View only                          | Extract and process data               |\n\n## 🎯 Perfect For Building:\n\n- **Accessibility Auditing Tools** - Let users inspect accessibility properties\n- **Visual Website Builders** - Enable element selection for editing\n- **QA Testing Tools** - Help testers identify elements\n- **Design Systems Documentation** - Show component structure\n- **Browser Extensions** - Add inspection capabilities\n- **Learning Platforms** - Teach HTML/CSS interactively\n- **CMS Admin Interfaces** - Visual content editing\n- **A11y Training Tools** - Interactive accessibility learning\n\n## Features\n\n- 🔍 **Element Inspection** - Interactive element selection with mouse hover and click\n- 🎯 **Deep Inspection** - Find the most specific element at any point\n- ✨ **Element Highlighting** - Visual highlighting with customizable styles\n- 📊 **Rich Element Info** - Get comprehensive element information including accessibility data\n- ⚡ **High Performance** - Optimized with throttling and efficient DOM queries\n- 🎛️ **Configurable** - Extensive options for customization\n- 🚀 **Headless** - No UI dependencies, bring your own interface\n- 🧹 **Clean API** - Simple functional interface with closure-based state management\n- 📦 **ESM** - Modern ES modules with TypeScript support\n\n## Installation\n\n```bash\nnpm install @allystudio/element-inspector\n```\n\n## Quick Start\n\n```typescript\nimport { createElementInspector } from '@allystudio/element-inspector'\n\n// Create inspector instance\nconst inspector = createElementInspector({\n  deepInspection: true,\n  debug: true\n})\n\n// Listen for events\ninspector.on((event) => {\n  if (event.type === 'hover') {\n    console.log('Hovering over:', event.element?.tagName)\n    // Update your UI with element info\n    showElementDetails(event.element)\n  } else if (event.type === 'select') {\n    console.log('Selected element:', event.element?.selector)\n    // Process the selected element\n    onElementSelected(event.element)\n  }\n})\n\n// Start inspection (user can now hover/click elements)\ninspector.start()\n\n// Your users press Escape or you stop programmatically\n// inspector.stop()\n```\n\n## 🚀 Real-World Example: Accessibility Auditor\n\n```typescript\n// Build an accessibility inspector like in AllyStudio\nconst a11yInspector = createElementInspector({\n  deepInspection: true\n})\n\na11yInspector.on((event) => {\n  if (event.type === 'select') {\n    const element = event.element\n\n    // Get accessibility info\n    const a11yInfo = getAccessibilityInfo(element.element)\n\n    // Show in your UI\n    displayAccessibilityReport({\n      selector: element.selector,\n      role: a11yInfo.role,\n      ariaLabel: a11yInfo.ariaLabel,\n      focusable: a11yInfo.focusable,\n      // ... more a11y data\n    })\n  }\n})\n\n// Button in your app starts inspection\ndocument.getElementById('start-a11y-check').onclick = () => {\n  a11yInspector.start()\n}\n```\n\n## API Reference\n\n### `createElementInspector(options?): ElementInspector`\n\nCreates a new element inspector instance.\n\n#### Options\n\n```typescript\ninterface InspectorOptions {\n  /** Enable deep inspection mode (find smallest element at point) */\n  deepInspection?: boolean\n\n  /** Minimum element size to consider (pixels) */\n  minElementSize?: number\n\n  /** CSS selectors to exclude from inspection */\n  excludeSelectors?: string[]\n\n  /** Enable debug logging */\n  debug?: boolean\n\n  /** Throttle mouse events (ms, 0 to disable) */\n  throttle?: number\n}\n```\n\n### Inspector API\n\nThe inspector instance returned by `createElementInspector()` provides the following methods:\n\n#### Methods\n\n```typescript\n// Control inspection\ninspector.start()           // Start inspection mode\ninspector.stop()            // Stop inspection mode\ninspector.toggle()          // Toggle inspection state\ninspector.isInspecting()    // Check if currently inspecting\n\n// Event handling\nconst unsubscribe = inspector.on(handler)  // Add event listener\ninspector.off(handler)                     // Remove event listener\n\n// Element operations\nconst info = inspector.inspectAt(x, y)     // Get element at coordinates\nconst info = inspector.getElementInfo(el)  // Get element information\ninspector.highlight(element, options)      // Highlight element\ninspector.clearHighlights()                // Clear all highlights\n\n// Configuration\ninspector.setOptions(options)              // Update options\nconst state = inspector.getState()         // Get current state\ninspector.destroy()                        // Cleanup and destroy\n```\n\n#### Events\n\n```typescript\ninterface InspectorEvent {\n  type: 'hover' | 'select' | 'start' | 'stop'\n  element?: ElementInfo        // Element information (for hover/select)\n  timestamp: number           // Event timestamp\n  coordinates?: { x: number; y: number }  // Mouse coordinates\n}\n```\n\n### `ElementInfo`\n\nComprehensive element information:\n\n```typescript\ninterface ElementInfo {\n  element: HTMLElement           // The DOM element\n  selector: string              // CSS selector\n  xpath?: string               // XPath selector\n  tagName: string              // Element tag name\n  textContent: string          // Element text content\n  attributes: Record<string, string>  // All attributes\n  rect: DOMRect                // Bounding rectangle\n  computedStyles?: CSSStyleDeclaration  // Computed styles\n}\n```\n\n### Highlighting\n\n```typescript\n// Basic highlighting\ninspector.highlight(element)\n\n// Custom highlight style\ninspector.highlight(element, {\n  style: {\n    borderColor: '#ff0000',\n    borderWidth: 3,\n    backgroundColor: 'rgba(255, 0, 0, 0.1)',\n    borderStyle: 'dashed'\n  },\n  showTooltip: true,\n  tooltipContent: 'Selected Element'\n})\n```\n\n### Utility Functions\n\nThe package also exports useful utility functions:\n\n```typescript\nimport {\n  generateSelector,\n  generateXPath,\n  findElementByXPath,\n  findDeepestElementAtPoint,\n  isElementVisible,\n  getAccessibilityInfo\n} from '@allystudio/element-inspector'\n\n// Generate CSS selector for element\nconst selector = generateSelector(element)\n\n// Generate XPath for element\nconst xpath = generateXPath(element)\n\n// Find element by XPath\nconst element = findElementByXPath('//div[@id=\"content\"]')\n\n// Get accessibility information\nconst a11yInfo = getAccessibilityInfo(element)\n// Returns: { role, ariaLabel, tabIndex, focusable, ... }\n```\n\n## 🧠 Core Concept: Headless Inspection\n\n### What \"Headless\" Means\n\nUnlike Chrome DevTools which provides a **complete UI**, this library provides **only the inspection logic**. You bring your own UI:\n\n```typescript\nconst inspector = createElementInspector()\n\ninspector.on((event) => {\n  if (event.type === 'hover') {\n    // YOU decide how to show element info\n    // Could be a tooltip, sidebar, modal, anything...\n    yourCustomTooltip.show(event.element.selector)\n  }\n})\n```\n\n### The Power of Programmable Inspection\n\n**Chrome DevTools** gives you a fixed experience:\n- Fixed highlight style (blue border)\n- Fixed information panel\n- Fixed interaction patterns\n- Development-only environment\n\n**@allystudio/element-inspector** gives you building blocks:\n- Custom highlight styles and animations\n- Extract any element data you want\n- Integrate with your app's design system\n- Use in production for real users\n- Combine with other tools and workflows\n\n### Real Use Cases in Production\n\n1. **Figma-style Visual Editors**: Users click elements to edit them\n2. **Accessibility Auditing Apps**: Users inspect elements to see a11y issues\n3. **QA Testing Tools**: Testers can identify elements for bug reports\n4. **CMS Visual Editors**: Content creators select elements to modify\n5. **Learning Platforms**: Students explore HTML structure interactively\n\n## Advanced Usage\n\n### Custom Event Handling\n\n```typescript\nconst inspector = createElementInspector()\n\ninspector.on((event) => {\n  switch (event.type) {\n    case 'start':\n      console.log('Inspection started')\n      break\n\n    case 'hover':\n      // Update UI with element info\n      updateElementPanel(event.element)\n      break\n\n    case 'select':\n      // Handle element selection\n      onElementSelected(event.element)\n      inspector.stop() // Stop after selection\n      break\n\n    case 'stop':\n      console.log('Inspection stopped')\n      break\n  }\n})\n```\n\n### Deep Inspection Mode\n\nDeep inspection finds the most specific element at any point:\n\n```typescript\nconst inspector = createElementInspector({\n  deepInspection: true,\n  minElementSize: 1 // Allow very small elements\n})\n\n// Will find the innermost element, even if it's small\ninspector.start()\n```\n\n### Performance Optimization\n\n```typescript\nconst inspector = createElementInspector({\n  throttle: 32,  // 30fps throttling\n  excludeSelectors: [\n    '.tooltip',\n    '.popover',\n    '[data-testid=\"ignore\"]'\n  ]\n})\n```\n\n### Integration with Frameworks\n\n#### React Hook Example\n\n```typescript\nimport { useEffect, useRef } from 'react'\nimport { createElementInspector } from '@allystudio/element-inspector'\n\nfunction useElementInspector(options = {}) {\n  const inspectorRef = useRef()\n\n  useEffect(() => {\n    inspectorRef.current = createElementInspector(options)\n\n    return () => {\n      inspectorRef.current?.destroy()\n    }\n  }, [])\n\n  return inspectorRef.current\n}\n\n// Usage in component\nfunction MyComponent() {\n  const inspector = useElementInspector({ deepInspection: true })\n\n  const handleStartInspection = () => {\n    inspector?.start()\n  }\n\n  return <button onClick={handleStartInspection}>Start Inspection</button>\n}\n```\n\n#### Vue Composable Example\n\n```typescript\nimport { ref, onUnmounted } from 'vue'\nimport { createElementInspector } from '@allystudio/element-inspector'\n\nexport function useElementInspector(options = {}) {\n  const inspector = createElementInspector(options)\n  const isInspecting = ref(false)\n\n  inspector.on((event) => {\n    if (event.type === 'start') isInspecting.value = true\n    if (event.type === 'stop') isInspecting.value = false\n  })\n\n  onUnmounted(() => {\n    inspector.destroy()\n  })\n\n  return {\n    inspector,\n    isInspecting,\n    start: () => inspector.start(),\n    stop: () => inspector.stop(),\n    toggle: () => inspector.toggle()\n  }\n}\n```\n\n## 🔧 Technical Architecture\n\n### How Chrome DevTools Works\n1. **Separate process** from your web page\n2. **Communication via CDP** (Chrome DevTools Protocol)\n3. **Fixed UI** in DevTools window\n4. **Read-only inspection** for debugging\n\n### How @allystudio/element-inspector Works\n1. **Runs in your page's context** (same process)\n2. **Direct DOM access** and manipulation\n3. **Event-driven API** for your custom UI\n4. **Read-write capabilities** for building tools\n\n```typescript\n// Direct access to elements in your page\ninspector.on((event) => {\n  // You get the actual HTMLElement reference\n  const element = event.element.element\n\n  // You can modify, analyze, or extract data\n  element.style.backgroundColor = 'yellow'\n  const computedStyles = getComputedStyle(element)\n  const accessibility = getAccessibilityInfo(element)\n})\n```\n\n### Performance Comparison\n\n| Feature             | Chrome DevTools              | @allystudio/element-inspector    |\n|:-------------------|:-----------------------------|:---------------------------------|\n| **Startup**        | Heavy (separate process)     | Lightweight (in-page)           |\n| **Memory**         | High (full DevTools)        | Low (just inspection)            |\n| **Latency**        | IPC overhead                 | Direct DOM access                |\n| **Customization**  | None                         | Full control                     |\n\n## Browser Support\n\n- Chrome/Chromium 90+\n- Firefox 88+\n- Safari 14+\n- Edge 90+\n\nRequires modern browser with support for:\n- ES2022 features\n- Pointer Events API\n- CSS `elementsFromPoint()`\n\n## TypeScript\n\nFull TypeScript support included. All types are exported:\n\n```typescript\nimport type {\n  InspectorOptions,\n  InspectorEvent,\n  ElementInfo,\n  HighlightOptions\n} from '@allystudio/element-inspector'\n```\n\n## Contributing\n\nThis package is part of the [@allystudio](https://github.com/allyship-dev) monorepo. See the main repository for contribution guidelines.\n\n## License\n\nMIT © Allyship.dev\n","readmeFilename":"README.md"}