@ekairos/toolbar 1.22.4-beta.development.0

package/README.md

@@ -0,0 +1,43 @@
+# @ekairos/toolbar
+
+Lightweight visual feedback toolbar for selecting UI elements, collecting annotations, and exporting structured feedback.
+
+## Install
+
+```bash
+pnpm add @ekairos/toolbar
+```
+
+## Usage
+
+```tsx
+import { EkairosToolbar } from "@ekairos/toolbar";
+
+export function App() {
+  return (
+    <>
+      <YourApp />
+      <EkairosToolbar />
+    </>
+  );
+}
+```
+
+## Included
+
+- Single element selection
+- Multi-select by `Cmd/Ctrl + Shift + Click`
+- Drag multi-select and area selection
+- Feedback dialog (add/edit/delete)
+- Stable selector extraction (`stableSelector`) plus readable path (`elementPath`)
+- Markdown output generation and copy/send callbacks
+
+## Keyboard
+
+- `Cmd/Ctrl + Shift + F`: toggle feedback mode
+- `Esc`: cancel current interaction / close
+- `C`: copy output
+- `S`: send output callback
+- `X`: clear annotations
+- `H`: show/hide markers
+

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { EkairosToolbar } from "./toolbar";
+export { ToolbarPopup } from "./popup";
+export { getElementPath, getStableSelector, identifyElementName, getElementClasses, getNearbyText, deepElementFromPoint, closestCrossingShadow, isElementFixed, } from "./selectors";
+export { generateToolbarOutput } from "./output";
+export type { BoundingBox, EkairosToolbarProps, OutputDetailLevel, ToolbarAnnotation, ToolbarSelectionSnapshot, } from "./types";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { EkairosToolbar } from "./toolbar";
+export { ToolbarPopup } from "./popup";
+export { getElementPath, getStableSelector, identifyElementName, getElementClasses, getNearbyText, deepElementFromPoint, closestCrossingShadow, isElementFixed, } from "./selectors";
+export { generateToolbarOutput } from "./output";

package/dist/output.d.ts

@@ -0,0 +1,2 @@
+import type { OutputDetailLevel, ToolbarAnnotation } from "./types";
+export declare function generateToolbarOutput(annotations: ToolbarAnnotation[], pagePath: string, detail?: OutputDetailLevel): string;

package/dist/output.js

@@ -0,0 +1,37 @@
+export function generateToolbarOutput(annotations, pagePath, detail = "standard") {
+    if (annotations.length === 0)
+        return "";
+    const viewport = typeof window !== "undefined"
+        ? `${window.innerWidth}x${window.innerHeight}`
+        : "unknown";
+    let output = `## Toolbar Feedback: ${pagePath}\n`;
+    output += `**Viewport:** ${viewport}\n\n`;
+    annotations.forEach((annotation, index) => {
+        if (detail === "compact") {
+            output += `${index + 1}. ${annotation.element}: ${annotation.comment}\n`;
+            return;
+        }
+        output += `### ${index + 1}. ${annotation.element}\n`;
+        output += `- Feedback: ${annotation.comment}\n`;
+        output += `- Path: ${annotation.elementPath}\n`;
+        if (annotation.stableSelector) {
+            output += `- Selector: \`${annotation.stableSelector}\`\n`;
+        }
+        if (annotation.selectedText) {
+            output += `- Selected text: "${annotation.selectedText}"\n`;
+        }
+        if (detail === "detailed") {
+            if (annotation.cssClasses) {
+                output += `- Classes: ${annotation.cssClasses}\n`;
+            }
+            if (annotation.boundingBox) {
+                output += `- Box: x=${Math.round(annotation.boundingBox.x)}, y=${Math.round(annotation.boundingBox.y)}, w=${Math.round(annotation.boundingBox.width)}, h=${Math.round(annotation.boundingBox.height)}\n`;
+            }
+            if (annotation.nearbyText) {
+                output += `- Context: ${annotation.nearbyText.slice(0, 120)}\n`;
+            }
+        }
+        output += "\n";
+    });
+    return output.trim();
+}

package/dist/popup.d.ts

@@ -0,0 +1,17 @@
+import { type CSSProperties } from "react";
+export type ToolbarPopupProps = {
+    element: string;
+    selectedText?: string;
+    placeholder?: string;
+    initialValue?: string;
+    submitLabel?: string;
+    onSubmit: (text: string) => void;
+    onCancel: () => void;
+    onDelete?: () => void;
+    style?: CSSProperties;
+    accentColor?: string;
+};
+export type ToolbarPopupHandle = {
+    shake: () => void;
+};
+export declare const ToolbarPopup: import("react").ForwardRefExoticComponent<ToolbarPopupProps & import("react").RefAttributes<ToolbarPopupHandle>>;

package/dist/popup.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState, } from "react";
+export const ToolbarPopup = forwardRef(function ToolbarPopup({ element, selectedText, placeholder = "What should change?", initialValue = "", submitLabel = "Add", onSubmit, onCancel, onDelete, style, accentColor = "#2f7bf6", }, ref) {
+    const [text, setText] = useState(initialValue);
+    const [isFocused, setIsFocused] = useState(false);
+    const [isShaking, setIsShaking] = useState(false);
+    const textareaRef = useRef(null);
+    useEffect(() => {
+        setText(initialValue);
+    }, [initialValue]);
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            textareaRef.current?.focus();
+        }, 40);
+        return () => clearTimeout(timer);
+    }, []);
+    const shake = useCallback(() => {
+        setIsShaking(true);
+        const timer = setTimeout(() => setIsShaking(false), 250);
+        return () => clearTimeout(timer);
+    }, []);
+    useImperativeHandle(ref, () => ({ shake }), [shake]);
+    const submit = useCallback(() => {
+        const value = text.trim();
+        if (!value)
+            return;
+        onSubmit(value);
+    }, [text, onSubmit]);
+    const cancel = useCallback(() => {
+        onCancel();
+    }, [onCancel]);
+    return (_jsxs("div", { "data-ekairos-toolbar-popup": true, onClick: (event) => event.stopPropagation(), style: {
+            position: "fixed",
+            width: 300,
+            borderRadius: 12,
+            border: `1px solid ${isShaking ? "#f14668" : "rgba(255,255,255,0.08)"}`,
+            background: "#16161b",
+            color: "#f5f7fa",
+            padding: 12,
+            zIndex: 100003,
+            boxShadow: "0 10px 35px rgba(0,0,0,0.45)",
+            ...style,
+        }, children: [_jsx("div", { style: {
+                    fontSize: 12,
+                    color: "rgba(255,255,255,0.65)",
+                    marginBottom: 8,
+                    whiteSpace: "nowrap",
+                    overflow: "hidden",
+                    textOverflow: "ellipsis",
+                }, children: element }), selectedText ? (_jsxs("div", { style: {
+                    fontSize: 12,
+                    color: "rgba(255,255,255,0.65)",
+                    background: "rgba(255,255,255,0.05)",
+                    borderRadius: 8,
+                    padding: "6px 8px",
+                    marginBottom: 8,
+                }, children: ["\"", selectedText.slice(0, 100), selectedText.length > 100 ? "..." : "", "\""] })) : null, _jsx("textarea", { ref: textareaRef, value: text, rows: 3, placeholder: placeholder, onChange: (event) => setText(event.target.value), onFocus: () => setIsFocused(true), onBlur: () => setIsFocused(false), onKeyDown: (event) => {
+                    if (event.key === "Escape") {
+                        event.preventDefault();
+                        cancel();
+                        return;
+                    }
+                    if (event.key === "Enter" && !event.shiftKey && !event.nativeEvent.isComposing) {
+                        event.preventDefault();
+                        submit();
+                    }
+                }, style: {
+                    width: "100%",
+                    resize: "none",
+                    borderRadius: 8,
+                    border: `1px solid ${isFocused ? accentColor : "rgba(255,255,255,0.15)"}`,
+                    background: "rgba(255,255,255,0.04)",
+                    color: "#f5f7fa",
+                    fontSize: 13,
+                    lineHeight: 1.4,
+                    padding: "8px 10px",
+                    outline: "none",
+                    boxSizing: "border-box",
+                } }), _jsxs("div", { style: {
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    marginTop: 8,
+                }, children: [onDelete ? (_jsx("button", { type: "button", onClick: onDelete, style: {
+                            marginRight: "auto",
+                            border: "none",
+                            background: "transparent",
+                            color: "rgba(255,255,255,0.7)",
+                            cursor: "pointer",
+                            padding: "4px 6px",
+                        }, children: "Delete" })) : null, _jsx("button", { type: "button", onClick: cancel, style: {
+                            border: "none",
+                            background: "transparent",
+                            color: "rgba(255,255,255,0.72)",
+                            cursor: "pointer",
+                            padding: "4px 8px",
+                        }, children: "Cancel" }), _jsx("button", { type: "button", onClick: submit, disabled: !text.trim(), style: {
+                            border: "none",
+                            borderRadius: 999,
+                            background: accentColor,
+                            color: "#fff",
+                            cursor: text.trim() ? "pointer" : "not-allowed",
+                            opacity: text.trim() ? 1 : 0.45,
+                            padding: "5px 12px",
+                            fontSize: 12,
+                            fontWeight: 600,
+                        }, children: submitLabel })] })] }));
+});

package/dist/selectors.d.ts

@@ -0,0 +1,8 @@
+export declare function deepElementFromPoint(x: number, y: number): HTMLElement | null;
+export declare function closestCrossingShadow(element: Element, selector: string): Element | null;
+export declare function isElementFixed(element: HTMLElement): boolean;
+export declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+export declare function getStableSelector(target: HTMLElement): string;
+export declare function identifyElementName(target: HTMLElement): string;
+export declare function getElementClasses(target: HTMLElement): string;
+export declare function getNearbyText(target: HTMLElement): string;

package/dist/selectors.js

@@ -0,0 +1,216 @@
+const TEST_ID_ATTRS = [
+    "data-ekairos-id",
+    "data-testid",
+    "data-test",
+    "data-qa",
+    "data-cy",
+    "data-automation-id",
+];
+function getParentElementCrossShadow(element) {
+    if (element.parentElement)
+        return element.parentElement;
+    const root = element.getRootNode();
+    if (root instanceof ShadowRoot)
+        return root.host;
+    return null;
+}
+function escapeCssValue(value) {
+    if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+        return CSS.escape(value);
+    }
+    return value.replace(/["\\]/g, "\\$&");
+}
+function isUniqueSelector(selector) {
+    try {
+        return document.querySelectorAll(selector).length === 1;
+    }
+    catch {
+        return false;
+    }
+}
+function getMeaningfulClassList(element) {
+    return Array.from(element.classList)
+        .map((cls) => cls.trim())
+        .filter((cls) => cls.length > 2)
+        .filter((cls) => !/^[a-z]{1,2}$/.test(cls))
+        .filter((cls) => !/[A-Z0-9]{6,}/.test(cls));
+}
+function getNthOfTypeIndex(element) {
+    const parent = element.parentElement;
+    if (!parent)
+        return 1;
+    const sameTagSiblings = Array.from(parent.children).filter((child) => child.tagName === element.tagName);
+    return sameTagSiblings.indexOf(element) + 1;
+}
+export function deepElementFromPoint(x, y) {
+    let current = document.elementFromPoint(x, y);
+    if (!current)
+        return null;
+    while (current.shadowRoot) {
+        const deeper = current.shadowRoot.elementFromPoint(x, y);
+        if (!deeper || deeper === current)
+            break;
+        current = deeper;
+    }
+    return current;
+}
+export function closestCrossingShadow(element, selector) {
+    let current = element;
+    while (current) {
+        if (current.matches(selector))
+            return current;
+        current = getParentElementCrossShadow(current);
+    }
+    return null;
+}
+export function isElementFixed(element) {
+    let current = element;
+    while (current && current !== document.body) {
+        const position = window.getComputedStyle(current).position;
+        if (position === "fixed" || position === "sticky")
+            return true;
+        current = current.parentElement;
+    }
+    return false;
+}
+export function getElementPath(target, maxDepth = 5) {
+    const parts = [];
+    let current = target;
+    let depth = 0;
+    while (current && depth < maxDepth) {
+        const tag = current.tagName.toLowerCase();
+        if (tag === "html" || tag === "body")
+            break;
+        let segment = tag;
+        if (current.id) {
+            segment = `#${current.id}`;
+        }
+        else {
+            const classes = getMeaningfulClassList(current);
+            if (classes.length > 0) {
+                segment = `${tag}.${classes[0]}`;
+            }
+        }
+        parts.unshift(segment);
+        current = getParentElementCrossShadow(current);
+        depth += 1;
+    }
+    return parts.join(" > ");
+}
+export function getStableSelector(target) {
+    for (const attr of TEST_ID_ATTRS) {
+        const value = target.getAttribute(attr);
+        if (!value)
+            continue;
+        const raw = `[${attr}="${escapeCssValue(value)}"]`;
+        if (isUniqueSelector(raw))
+            return raw;
+        const tagged = `${target.tagName.toLowerCase()}${raw}`;
+        if (isUniqueSelector(tagged))
+            return tagged;
+    }
+    if (target.id) {
+        const idSelector = `#${escapeCssValue(target.id)}`;
+        if (isUniqueSelector(idSelector))
+            return idSelector;
+    }
+    const tag = target.tagName.toLowerCase();
+    const classes = getMeaningfulClassList(target);
+    for (let i = 0; i < Math.min(classes.length, 3); i += 1) {
+        const classSelector = `${tag}.${classes.slice(0, i + 1).join(".")}`;
+        if (isUniqueSelector(classSelector))
+            return classSelector;
+    }
+    const chain = [];
+    let current = target;
+    let guard = 0;
+    while (current && current.tagName.toLowerCase() !== "html" && guard < 8) {
+        const currentTag = current.tagName.toLowerCase();
+        const currentClasses = getMeaningfulClassList(current);
+        let segment = currentTag;
+        if (current.id) {
+            const idSelector = `#${escapeCssValue(current.id)}`;
+            chain.unshift(idSelector);
+            const joined = chain.join(" > ");
+            if (isUniqueSelector(joined))
+                return joined;
+            current = getParentElementCrossShadow(current);
+            guard += 1;
+            continue;
+        }
+        if (currentClasses.length > 0) {
+            segment = `${currentTag}.${currentClasses[0]}`;
+        }
+        const index = getNthOfTypeIndex(current);
+        segment = `${segment}:nth-of-type(${index})`;
+        chain.unshift(segment);
+        const candidate = chain.join(" > ");
+        if (isUniqueSelector(candidate))
+            return candidate;
+        current = getParentElementCrossShadow(current);
+        guard += 1;
+    }
+    return `${tag}:nth-of-type(${getNthOfTypeIndex(target)})`;
+}
+export function identifyElementName(target) {
+    if (target.dataset.ekairosLabel)
+        return target.dataset.ekairosLabel;
+    const tag = target.tagName.toLowerCase();
+    const text = target.textContent?.trim() ?? "";
+    const shortText = text.slice(0, 40);
+    if (tag === "button") {
+        const ariaLabel = target.getAttribute("aria-label");
+        if (ariaLabel)
+            return `button [${ariaLabel}]`;
+        if (shortText)
+            return `button "${shortText}"`;
+        return "button";
+    }
+    if (tag === "a") {
+        if (shortText)
+            return `link "${shortText}"`;
+        const href = target.getAttribute("href");
+        if (href)
+            return `link (${href.slice(0, 60)})`;
+        return "link";
+    }
+    if (tag === "input" || tag === "textarea" || tag === "select") {
+        const name = target.getAttribute("name");
+        const placeholder = target.getAttribute("placeholder");
+        if (placeholder)
+            return `${tag} "${placeholder.slice(0, 30)}"`;
+        if (name)
+            return `${tag} [${name}]`;
+        return tag;
+    }
+    if (/^h[1-6]$/.test(tag)) {
+        if (shortText)
+            return `${tag} "${shortText}"`;
+        return tag;
+    }
+    if (shortText && shortText.length <= 30)
+        return `"${shortText}"`;
+    return tag;
+}
+export function getElementClasses(target) {
+    const classes = Array.from(target.classList)
+        .map((value) => value.trim())
+        .filter(Boolean);
+    return classes.join(", ");
+}
+export function getNearbyText(target) {
+    const pieces = [];
+    const currentText = target.textContent?.trim();
+    if (currentText && currentText.length <= 120) {
+        pieces.push(currentText);
+    }
+    const prevText = target.previousElementSibling?.textContent?.trim();
+    if (prevText && prevText.length <= 60) {
+        pieces.unshift(`[before "${prevText.slice(0, 50)}"]`);
+    }
+    const nextText = target.nextElementSibling?.textContent?.trim();
+    if (nextText && nextText.length <= 60) {
+        pieces.push(`[after "${nextText.slice(0, 50)}"]`);
+    }
+    return pieces.join(" ");
+}

package/dist/toolbar.d.ts

@@ -0,0 +1,2 @@
+import type { EkairosToolbarProps } from "./types";
+export declare function EkairosToolbar({ onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, onSubmit, copyToClipboard, blockInteractions, initialActive, outputDetail, storageKey, }?: EkairosToolbarProps): import("react").ReactPortal | null;