├── .github
└── workflows
│ ├── ci.yml
│ └── npm-publish.yml
├── .gitignore
├── LICENSE.md
├── README.md
├── example
├── example.js
├── index.html
├── package-lock.json
└── package.json
├── package-lock.json
├── package.json
├── src
├── element-overlay.ts
├── element-picker.ts
├── index.ts
└── utils.ts
└── tsconfig.json
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
1 | # This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
2 | # For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
3 |
4 | name: Node.js CI
5 |
6 | on:
7 | push:
8 | branches: [ main ]
9 | pull_request:
10 | branches: [ main ]
11 |
12 | jobs:
13 | build:
14 | runs-on: ubuntu-latest
15 |
16 | steps:
17 | - uses: actions/checkout@v2
18 | - name: Use Node.js ${{ matrix.node-version }}
19 | uses: actions/setup-node@v1
20 | with:
21 | node-version: 14
22 | - run: npm ci
23 | - run: npm run build
24 |
--------------------------------------------------------------------------------
/.github/workflows/npm-publish.yml:
--------------------------------------------------------------------------------
1 | name: Node.js Package
2 |
3 | on:
4 | release:
5 | types: [created]
6 |
7 | jobs:
8 | build:
9 | runs-on: ubuntu-latest
10 | steps:
11 | - uses: actions/checkout@v2
12 | - uses: actions/setup-node@v1
13 | with:
14 | node-version: 14
15 | - run: npm ci
16 | - run: npm run build
17 |
18 | publish-npm:
19 | needs: build
20 | runs-on: ubuntu-latest
21 | steps:
22 | - uses: actions/checkout@v2
23 | - uses: actions/setup-node@v1
24 | with:
25 | node-version: 14
26 | registry-url: https://registry.npmjs.org/
27 | - run: npm ci
28 | - run: npm publish
29 | env:
30 | NODE_AUTH_TOKEN: ${{secrets.npm_token}}
31 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | dist/
2 | node_modules/
3 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2021 Harry Marr
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # pick-dom-element
2 |
3 | [](https://badge.fury.io/js/pick-dom-element)
4 |
5 | A JavaScript library (written in TypeScript) for interactively picking DOM elements.
6 |
7 |
8 |
10 |
11 | ## Usage
12 |
13 | Create an instance of the `ElementPicker` class, and call its `start()` method to start picking. Provide an `onHover` or `onClick` callback to get the picked element(s). Call `stop()` to stop picking and remove the overlay from the DOM.
14 |
15 | ```javascript
16 | import { ElementPicker } from "pick-dom-element";
17 |
18 | const style = { borderColor: "#0000ff" };
19 | const picker = new ElementPicker({ style });
20 | picker.start({
21 | onHover: (el) => console.log(`Hover: ${el}`),
22 | onClick: (el) => {
23 | picker.stop();
24 | console.log(`Picked: ${el}`);
25 | },
26 | });
27 | ```
28 |
29 | See the [example](example/) directory for a more complete example of how to use the library.
30 |
--------------------------------------------------------------------------------
/example/example.js:
--------------------------------------------------------------------------------
1 | import { ElementPicker } from "pick-dom-element";
2 |
3 | function main() {
4 | const status = document.getElementById("status");
5 | const startButton = document.getElementById("start");
6 | const onlyEmphasisCheckbox = document.getElementById("only-emphasis");
7 |
8 | const setElement = (el) => {
9 | const tags = [];
10 | while (el.parentNode) {
11 | tags.push(el.tagName);
12 | el = el.parentNode;
13 | }
14 | status.innerText = tags
15 | .reverse()
16 | .map((t) => t.toLowerCase())
17 | .join(" > ");
18 | };
19 |
20 | const picker = new ElementPicker({
21 | style: {
22 | background: "rgba(153, 235, 255, 0.5)",
23 | borderColor: "yellow"
24 | },
25 | });
26 | let onlyEmphasis = onlyEmphasisCheckbox.checked;
27 | onlyEmphasisCheckbox.onchange = (ev) => {
28 | onlyEmphasis = ev.target.checked;
29 | }
30 | const start = () => {
31 | startButton.disabled = true;
32 | picker.start({
33 | onHover: setElement,
34 | onClick: () => {
35 | picker.stop();
36 | startButton.disabled = false;
37 | },
38 | elementFilter: (el) => {
39 | if (!onlyEmphasis) {
40 | return true;
41 | }
42 | return ['I', 'B'].includes(el.tagName);
43 | }
44 | });
45 | };
46 |
47 | startButton.addEventListener("click", start);
48 | }
49 |
50 | document.addEventListener("DOMContentLoaded", main);
51 |
--------------------------------------------------------------------------------
/example/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
15 |
16 |
17 |
18 | Element Picker example
19 |
20 | This is an example page . Try hovering over some elements.
22 |
23 | Click "start" to activate the picker.
24 | Start
25 | = (el: HTMLElement) => T;
5 | type ElementPickerOptions = {
6 | parentElement?: Node;
7 | useShadowDOM?: boolean;
8 | onClick?: ElementCallback;
9 | onHover?: ElementCallback;
10 | elementFilter?: ElementCallback;
11 | };
12 |
13 | export default class ElementPicker {
14 | private overlay: ElementOverlay;
15 | private active: boolean;
16 | private options?: ElementPickerOptions;
17 | private target?: HTMLElement;
18 | private mouseX?: number;
19 | private mouseY?: number;
20 | private tickReq?: number;
21 |
22 | constructor(overlayOptions?: ElementOverlayOptions) {
23 | this.active = false;
24 | this.overlay = new ElementOverlay(overlayOptions ?? {});
25 | }
26 |
27 | start(options: ElementPickerOptions): boolean {
28 | if (this.active) {
29 | return false;
30 | }
31 |
32 | this.active = true;
33 | this.options = options;
34 | document.addEventListener("mousemove", this.handleMouseMove, true);
35 | document.addEventListener("click", this.handleClick, true);
36 |
37 | this.overlay.addToDOM(
38 | options.parentElement ?? document.body,
39 | options.useShadowDOM ?? true
40 | );
41 |
42 | this.tick();
43 |
44 | return true;
45 | }
46 |
47 | stop() {
48 | this.active = false;
49 | this.options = undefined;
50 | document.removeEventListener("mousemove", this.handleMouseMove, true);
51 | document.removeEventListener("click", this.handleClick, true);
52 |
53 | this.overlay.removeFromDOM();
54 | this.target = undefined;
55 | this.mouseX = undefined;
56 | this.mouseY = undefined;
57 |
58 | if (this.tickReq) {
59 | window.cancelAnimationFrame(this.tickReq);
60 | }
61 | }
62 |
63 | private handleMouseMove = (event: MouseEvent) => {
64 | this.mouseX = event.clientX;
65 | this.mouseY = event.clientY;
66 | };
67 |
68 | private handleClick = (event: MouseEvent) => {
69 | if (this.target && this.options?.onClick) {
70 | this.options.onClick(this.target);
71 | }
72 | event.preventDefault();
73 | };
74 |
75 | private tick = () => {
76 | this.updateTarget();
77 | this.tickReq = window.requestAnimationFrame(this.tick);
78 | };
79 |
80 | private updateTarget() {
81 | if (this.mouseX === undefined || this.mouseY === undefined) {
82 | return;
83 | }
84 |
85 | // Peek through the overlay to find the new target
86 | this.overlay.ignoreCursor();
87 | const elAtCursor = document.elementFromPoint(this.mouseX, this.mouseY);
88 | const newTarget = elAtCursor as HTMLElement;
89 | this.overlay.captureCursor();
90 |
91 | // If the target hasn't changed, there's nothing to do
92 | if (!newTarget || newTarget === this.target) {
93 | return;
94 | }
95 |
96 | // If we have an element filter and the new target doesn't match,
97 | // clear out the target
98 | if (this.options?.elementFilter) {
99 | if (!this.options.elementFilter(newTarget)) {
100 | this.target = undefined;
101 | this.overlay.setBounds({ x: 0, y: 0, width: 0, height: 0 });
102 | return;
103 | }
104 | }
105 |
106 | this.target = newTarget;
107 |
108 | const bounds = getElementBounds(newTarget);
109 | this.overlay.setBounds(bounds);
110 |
111 | if (this.options?.onHover) {
112 | this.options.onHover(newTarget);
113 | }
114 | }
115 | }
116 |
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
1 | import ElementPicker from "./element-picker";
2 |
3 | export { ElementPicker };
4 |
--------------------------------------------------------------------------------
/src/utils.ts:
--------------------------------------------------------------------------------
1 | export interface BoundingBox {
2 | x: number;
3 | y: number;
4 | width: number;
5 | height: number;
6 | }
7 |
8 | export interface ElementOverlayStyleOptions {
9 | background?: string;
10 | borderColor?: string;
11 | borderStyle?: string;
12 | borderRadius?: string;
13 | borderWidth?: string;
14 | boxSizing?: string;
15 | cursor?: string;
16 | position?: string;
17 | zIndex?: string;
18 | margin?: string;
19 | padding?: string;
20 | };
21 |
22 | export type ElementOverlayOptions = {
23 | className?: string;
24 | style?: ElementOverlayStyleOptions;
25 | };
26 |
27 | export const getElementBounds = (el: HTMLElement): BoundingBox => {
28 | const rect = el.getBoundingClientRect();
29 | return {
30 | x: window.pageXOffset + rect.left,
31 | y: window.pageYOffset + rect.top,
32 | width: el.offsetWidth,
33 | height: el.offsetHeight,
34 | };
35 | };
36 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "strict": true,
4 | "noImplicitAny": true,
5 | "target": "es2016",
6 | "sourceMap": false,
7 | "module": "ES6",
8 | "declaration": true,
9 | "outDir": "./dist"
10 | },
11 | "include": ["./src/"],
12 | "exclude": ["node_modules"]
13 | }
14 |
--------------------------------------------------------------------------------
9 |