@teambit/react.ui.component-highlighter 0.0.0-2240a868c0f88bba4f62719e6d10d31987cae1f9

package/dist/label/links.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calcComponentLink = calcComponentLink;
+const url_join_1 = __importDefault(require("url-join"));
+const component_modules_component_url_1 = require("@teambit/component.modules.component-url");
+function calcComponentLink(id, exported) {
+    if (!id)
+        return undefined;
+    if (exported)
+        return component_modules_component_url_1.ComponentUrl.toUrl(id);
+    return (0, url_join_1.default)('/', id.fullName);
+}
+//# sourceMappingURL=links.js.map

package/dist/label/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../label/links.tsx"],"names":[],"mappings":";;;;;AAIA,8CAIC;AARD,wDAA+B;AAE/B,8FAAwE;AAExE,SAAgB,iBAAiB,CAAC,EAA2B,EAAE,QAA6B;IAC1F,IAAI,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IAC1B,IAAI,QAAQ;QAAE,OAAO,8CAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5C,OAAO,IAAA,kBAAO,EAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC"}

package/dist/label/other-components.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { TippyProps } from '@tippyjs/react/headless';
+import { ComponentMetaHolder } from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+export type OtherComponentsProps = {
+    components: (ComponentMetaHolder | string)[];
+    start?: number;
+    end?: number;
+} & TippyProps;
+export declare function OtherComponentsPopper({ components, children, start, end, placement, interactive, ...tippyProps }: OtherComponentsProps): React.JSX.Element;

package/dist/label/other-components.js

@@ -0,0 +1,34 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtherComponentsPopper = OtherComponentsPopper;
+const react_1 = __importDefault(require("react"));
+const headless_1 = __importDefault(require("@tippyjs/react/headless"));
+const component_strip_1 = require("./component-strip");
+const label_module_scss_1 = __importDefault(require("./label.module.scss"));
+// a popper ("tooltip") that shows the additional React Components related to this dom element
+function OtherComponentsPopper(_a) {
+    var { components, children, start, end = -1, placement = 'bottom', interactive = true } = _a, tippyProps = __rest(_a, ["components", "children", "start", "end", "placement", "interactive"]);
+    const content = (react_1.default.createElement(react_1.default.Fragment, null, components
+        .slice(start, end)
+        .reverse()
+        .map((comp, idx) => (react_1.default.createElement(component_strip_1.ComponentStrip, { key: idx, component: comp })))));
+    return (react_1.default.createElement(headless_1.default, Object.assign({ placement: placement, interactive: interactive }, tippyProps, { 
+        // second parameter "content" is always undefined, use content inline
+        // https://github.com/atomiks/tippyjs-react/issues/341
+        render: (attrs) => (react_1.default.createElement("div", Object.assign({}, attrs, { className: label_module_scss_1.default.othersContainer }), content)) }), children));
+}
+//# sourceMappingURL=other-components.js.map

package/dist/label/other-components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"other-components.js","sourceRoot":"","sources":["../../label/other-components.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAcA,sDAoCC;AAlDD,kDAA0B;AAC1B,uEAA4D;AAG5D,uDAAmD;AACnD,4EAAyC;AAQzC,8FAA8F;AAC9F,SAAgB,qBAAqB,CAAC,EAQf;QARe,EACpC,UAAU,EACV,QAAQ,EACR,KAAK,EACL,GAAG,GAAG,CAAC,CAAC,EACR,SAAS,GAAG,QAAQ,EACpB,WAAW,GAAG,IAAI,OAEG,EADlB,UAAU,cAPuB,sEAQrC,CADc;IAEb,MAAM,OAAO,GAAG,CACd,8DACG,UAAU;SACR,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC;SACjB,OAAO,EAAE;SACT,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAClB,8BAAC,gCAAc,IAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,GAAI,CAC9C,CAAC,CACH,CACJ,CAAC;IAEF,OAAO,CACL,8BAAC,kBAAK,kBACJ,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,WAAW,IACpB,UAAU;QACd,qEAAqE;QACrE,sDAAsD;QACtD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CACjB,uDAAS,KAAK,IAAE,SAAS,EAAE,2BAAM,CAAC,eAAe,KAC9C,OAAO,CACJ,CACP,KAEA,QAAQ,CACH,CACT,CAAC;AACJ,CAAC"}

package/dist/mock-component.d.ts

@@ -0,0 +1,14 @@
+import React, { ButtonHTMLAttributes, HTMLAttributes } from 'react';
+import { ComponentMeta } from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+export declare function MockTarget({ children, ...rest }: HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export declare namespace MockTarget {
+    var __bit_component: ComponentMeta;
+}
+export declare function MockButton({ children, ...rest }: ButtonHTMLAttributes<HTMLButtonElement>): React.JSX.Element;
+export declare namespace MockButton {
+    var __bit_component: ComponentMeta;
+}
+export declare function MockSnap({ children, ...rest }: ButtonHTMLAttributes<HTMLButtonElement>): React.JSX.Element;
+export declare namespace MockSnap {
+    var __bit_component: ComponentMeta;
+}

package/dist/mock-component.js

@@ -0,0 +1,43 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockTarget = MockTarget;
+exports.MockButton = MockButton;
+exports.MockSnap = MockSnap;
+const react_1 = __importDefault(require("react"));
+const react_ui_highlighter_component_metadata_bit_component_meta_1 = require("@teambit/react.ui.highlighter.component-metadata.bit-component-meta");
+function MockTarget(_a) {
+    var { children } = _a, rest = __rest(_a, ["children"]);
+    return react_1.default.createElement("div", Object.assign({}, rest), children);
+}
+MockTarget[react_ui_highlighter_component_metadata_bit_component_meta_1.componentMetaField] = {
+    id: 'teambit.design/ui/mock-target@1.6.2',
+};
+function MockButton(_a) {
+    var { children } = _a, rest = __rest(_a, ["children"]);
+    return react_1.default.createElement("button", Object.assign({}, rest), children);
+}
+MockButton[react_ui_highlighter_component_metadata_bit_component_meta_1.componentMetaField] = {
+    id: 'teambit.design/ui/icon-button@1.6.2',
+};
+function MockSnap(_a) {
+    var { children } = _a, rest = __rest(_a, ["children"]);
+    return react_1.default.createElement("button", Object.assign({}, rest), children);
+}
+MockSnap[react_ui_highlighter_component_metadata_bit_component_meta_1.componentMetaField] = {
+    id: 'teambit.design/ui/icon-button@a21594d5cc63fd24d2b4763fa7d817b131f0edbb',
+};
+//# sourceMappingURL=mock-component.js.map

package/dist/mock-component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-component.js","sourceRoot":"","sources":["../mock-component.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAGA,gCAEC;AAKD,gCAEC;AAKD,4BAEC;AAnBD,kDAAoE;AACpE,oJAAwH;AAExH,SAAgB,UAAU,CAAC,EAAqD;QAArD,EAAE,QAAQ,OAA2C,EAAtC,IAAI,cAAnB,YAAqB,CAAF;IAC5C,OAAO,uDAAS,IAAI,GAAG,QAAQ,CAAO,CAAC;AACzC,CAAC;AACD,UAAU,CAAC,+EAAkB,CAAC,GAAG;IAC/B,EAAE,EAAE,qCAAqC;CACzB,CAAC;AAEnB,SAAgB,UAAU,CAAC,EAA8D;QAA9D,EAAE,QAAQ,OAAoD,EAA/C,IAAI,cAAnB,YAAqB,CAAF;IAC5C,OAAO,0DAAY,IAAI,GAAG,QAAQ,CAAU,CAAC;AAC/C,CAAC;AACD,UAAU,CAAC,+EAAkB,CAAC,GAAG;IAC/B,EAAE,EAAE,qCAAqC;CACzB,CAAC;AAEnB,SAAgB,QAAQ,CAAC,EAA8D;QAA9D,EAAE,QAAQ,OAAoD,EAA/C,IAAI,cAAnB,YAAqB,CAAF;IAC1C,OAAO,0DAAY,IAAI,GAAG,QAAQ,CAAU,CAAC;AAC/C,CAAC;AACD,QAAQ,CAAC,+EAAkB,CAAC,GAAG;IAC7B,EAAE,EAAE,wEAAwE;CAC5D,CAAC"}

package/dist/preview-1768840768294.js

@@ -0,0 +1,10 @@
+import * as compositions_0 from '/tmp/capsules-root/sign-capsules/2026-0-19/z4rgtj/teambit.react_ui_component-highlighter@2240a868c0f88bba4f62719e6d10d31987cae1f9/dist/children-highlighter/children-highlighter.composition.js';
+import * as compositions_1 from '/tmp/capsules-root/sign-capsules/2026-0-19/z4rgtj/teambit.react_ui_component-highlighter@2240a868c0f88bba4f62719e6d10d31987cae1f9/dist/element-highlighter/element-highlighter.compositions.js';
+import * as compositions_2 from '/tmp/capsules-root/sign-capsules/2026-0-19/z4rgtj/teambit.react_ui_component-highlighter@2240a868c0f88bba4f62719e6d10d31987cae1f9/dist/hover-highlighter/hover-highlighter.compositions.js';
+import * as compositions_3 from '/tmp/capsules-root/sign-capsules/2026-0-19/z4rgtj/teambit.react_ui_component-highlighter@2240a868c0f88bba4f62719e6d10d31987cae1f9/dist/label/component-strip.compositions.js';
+import * as overview_0 from '/tmp/capsules-root/sign-capsules/2026-0-19/z4rgtj/teambit.react_ui_component-highlighter@2240a868c0f88bba4f62719e6d10d31987cae1f9/dist/component-highlighter.docs.md';
+
+export const compositions = [compositions_0, compositions_1, compositions_2, compositions_3];
+export const overview = [overview_0];
+
+export const compositions_metadata = {"compositions":[{"displayName":"Children highlighter preview","identifier":"ChildrenHighlighterPreview"},{"displayName":"Children highlighter with custom colors","identifier":"ChildrenHighlighterWithCustomColors"},{"displayName":"Children highlighter inside ignore","identifier":"ChildrenHighlighterInsideIgnore"},{"displayName":"Children highlighter with rule","identifier":"ChildrenHighlighterWithRule"},{"displayName":"Children highlighter with component rule","identifier":"ChildrenHighlighterWithComponentRule"},{"displayName":"Highlighted element","identifier":"HighlightedElement"},{"displayName":"Customized","identifier":"Customized"},{"displayName":"Sizes","identifier":"Sizes"},{"displayName":"Moving element","identifier":"MovingElement"},{"displayName":"Fullscreen element","identifier":"FullscreenElement"},{"displayName":"Offscreen elements","identifier":"OffscreenElements"},{"displayName":"Show when hovering","identifier":"ShowWhenHovering"},{"displayName":"Unmounting element","identifier":"UnmountingElement"},{"displayName":"Hover exclusion zones","identifier":"HoverExclusionZones"},{"displayName":"Component strip preview","identifier":"ComponentStripPreview"}]};

package/dist/rule-matcher.d.ts

@@ -0,0 +1,8 @@
+import { ComponentMeta } from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+export type MatchRule = undefined | string | ((element: HTMLElement) => boolean);
+export type ComponentMatchRule = undefined | string | string[] | ((target: ComponentMatchTarget) => boolean);
+export declare function ruleMatcher(element: HTMLElement, rule: MatchRule): boolean;
+export type ComponentMatchTarget = {
+    meta: ComponentMeta;
+};
+export declare function componentRuleMatcher(target: ComponentMatchTarget, rule: ComponentMatchRule): boolean;

package/dist/rule-matcher.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ruleMatcher = ruleMatcher;
+exports.componentRuleMatcher = componentRuleMatcher;
+// in the future, we will add more options here, like include / exclude objects.
+const component_id_1 = require("@teambit/component-id");
+function ruleMatcher(element, rule) {
+    if (typeof rule === 'string') {
+        return element.matches(rule);
+    }
+    if (typeof rule === 'function') {
+        return rule(element);
+    }
+    return true;
+}
+function componentRuleMatcher(target, rule) {
+    if (typeof rule === 'string') {
+        const targetCmpId = component_id_1.ComponentID.tryFromString(target.meta.id);
+        const ruleCmpId = component_id_1.ComponentID.tryFromString(rule);
+        return component_id_1.ComponentID.isEqual(ruleCmpId, targetCmpId, { ignoreVersion: true });
+    }
+    if (Array.isArray(rule)) {
+        const targetCmpId = component_id_1.ComponentID.tryFromString(target.meta.id);
+        const ruleCmpIds = rule.map((x) => component_id_1.ComponentID.tryFromString(x));
+        return ruleCmpIds.some((cmdId) => component_id_1.ComponentID.isEqual(targetCmpId, cmdId, { ignoreVersion: true }));
+    }
+    if (typeof rule === 'function') {
+        return rule(target);
+    }
+    return true;
+}
+//# sourceMappingURL=rule-matcher.js.map

package/dist/rule-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-matcher.js","sourceRoot":"","sources":["../rule-matcher.tsx"],"names":[],"mappings":";;AAOA,kCAUC;AAID,oDAoBC;AAzCD,gFAAgF;AAChF,wDAAoD;AAMpD,SAAgB,WAAW,CAAC,OAAoB,EAAE,IAAe;IAC/D,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAID,SAAgB,oBAAoB,CAAC,MAA4B,EAAE,IAAwB;IACzF,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAG,0BAAW,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9D,MAAM,SAAS,GAAG,0BAAW,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAElD,OAAO,0BAAW,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,WAAW,GAAG,0BAAW,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,0BAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QAEjE,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,0BAAW,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACtG,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/element-highlighter/element-highlighter.compositions.tsx

@@ -0,0 +1,130 @@
+import React, { useState, createRef, useEffect, CSSProperties } from 'react';
+import { ElementHighlighter } from './element-highlighter';
+import { MockTarget } from '../mock-component';
+
+type HighlightedElementProps = {
+  style?: CSSProperties;
+  targetStyle?: CSSProperties;
+  className?: string;
+  watchMotion?: boolean;
+};
+
+export const HighlightedElement = ({ style, targetStyle, watchMotion, className }: HighlightedElementProps) => {
+  const targetRef = createRef<HTMLDivElement>();
+
+  return (
+    <div className={className} style={{ padding: '16px 16px 40px 16px', width: 300, fontFamily: 'sans-serif' }}>
+      <div ref={targetRef} style={{ width: 100, ...targetStyle }}>
+        highlight target
+      </div>
+
+      <ElementHighlighter
+        targetRef={targetRef}
+        components={[MockTarget]}
+        style={style}
+        watchMotion={watchMotion}
+        placement="bottom"
+      />
+    </div>
+  );
+};
+
+export const Customized = () => {
+  return (
+    <HighlightedElement
+      style={
+        {
+          '--bit-highlighter-color': '#94deb4',
+          '--bit-highlighter-color-hover': '#d0f1de',
+          '--bit-highlighter-color-active': '#37b26c',
+        } as CSSProperties
+      }
+    />
+  );
+};
+
+export const Sizes = () => {
+  return (
+    <div>
+      <HighlightedElement style={{ fontSize: 10 }} />
+      <HighlightedElement style={{ fontSize: 14 }} />
+      <HighlightedElement style={{ fontSize: 18 }} />
+    </div>
+  );
+};
+
+const fps = 30;
+const frameInterval = 1000 / fps;
+
+export const MovingElement = () => {
+  const [margin, setMargin] = useState(0);
+
+  useEffect(() => {
+    const intervalId = setInterval(() => setMargin((x) => (x + 1) % 100), frameInterval);
+    return () => clearInterval(intervalId);
+  }, []);
+
+  return <HighlightedElement targetStyle={{ marginLeft: margin }} watchMotion />;
+};
+
+export const FullscreenElement = () => {
+  const targetRef = createRef<HTMLDivElement>();
+
+  return (
+    <div style={{ fontFamily: 'sans-serif' }}>
+      <div
+        ref={targetRef}
+        style={{
+          height: '100vh',
+          width: '100%',
+          background: '#bceed4',
+        }}
+      >
+        This element will cover the entire document,
+        <br />
+        pushing the highlighter to the edge of the window.
+        <br />
+        The highlighter should remain inside and expand no further than the document.
+      </div>
+      <ElementHighlighter targetRef={targetRef} components={[MockTarget]} watchMotion />
+    </div>
+  );
+};
+
+const edgeStyles = { position: 'absolute', background: 'cyan', padding: 30 } as const;
+const centerStyles = {
+  top: { top: -30, left: '50%', transform: 'translate(-50%,0)' },
+  right: { right: -30, top: '50%', transform: 'translate(0, -50%)' },
+  bottom: { bottom: -30, left: '50%', transform: 'translate(-50%,0)' },
+  left: { left: -30, top: '50%', transform: 'translate(0, -50%)' },
+};
+
+export function OffscreenElements() {
+  const target01 = createRef<HTMLDivElement>();
+  const target02 = createRef<HTMLDivElement>();
+  const target03 = createRef<HTMLDivElement>();
+  const target04 = createRef<HTMLDivElement>();
+
+  return (
+    <div style={{ fontFamily: 'sans-serif', height: '100%' }}>
+      <div style={{ position: 'relative', width: '100%', height: '100%', overflow: 'hidden' }}>
+        <div ref={target01} style={{ ...edgeStyles, ...centerStyles.top }}>
+          top
+        </div>
+        <div ref={target02} style={{ ...edgeStyles, ...centerStyles.right }}>
+          right
+        </div>
+        <div ref={target03} style={{ ...edgeStyles, ...centerStyles.bottom }}>
+          bottom
+        </div>
+        <div ref={target04} style={{ ...edgeStyles, ...centerStyles.left }}>
+          left
+        </div>
+        <ElementHighlighter targetRef={target01} components={[MockTarget]} watchMotion />
+        <ElementHighlighter targetRef={target02} components={[MockTarget]} watchMotion />
+        <ElementHighlighter targetRef={target03} components={[MockTarget]} watchMotion />
+        <ElementHighlighter targetRef={target04} components={[MockTarget]} watchMotion />
+      </div>
+    </div>
+  );
+}

package/element-highlighter/element-highlighter.module.scss

@@ -0,0 +1,10 @@
+.label {
+  // space between the label and the target
+  // keep this space so users can move their cursor in this space.
+  padding: 8px;
+}
+
+.frame,
+.label {
+  z-index: 15500 // $highlighter-z-index;
+}

package/element-highlighter/element-highlighter.tsx

@@ -0,0 +1,51 @@
+import React, { RefObject } from 'react';
+import classnames from 'classnames';
+import { ComponentMetaHolder } from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+import { Frame } from '../frame';
+import { Label, LabelContainer, Placement } from '../label';
+import { skipHighlighterAttr } from '../ignore-highlighter';
+import styles from './element-highlighter.module.scss';
+
+export interface ElementHighlighterProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** highlight this element */
+  targetRef: RefObject<HTMLElement | null>;
+  /** components with metadata to show in the label */
+  components?: (ComponentMetaHolder | string)[];
+
+  /** default location of the label */
+  placement?: Placement;
+  /** customize styles */
+  classes?: HighlightClasses;
+  /** continually update highlighter to match moving elements */
+  watchMotion?: boolean;
+}
+
+export { Placement };
+
+export type HighlightClasses = {
+  container?: string;
+  frame?: string;
+  label?: string;
+};
+
+export function ElementHighlighter({
+  targetRef,
+  components,
+  placement = 'top',
+  watchMotion,
+  className,
+  classes,
+  ...props
+}: ElementHighlighterProps) {
+  return (
+    <div {...props} {...skipHighlighterAttr} className={classnames(classes?.container, styles.container, className)}>
+      <Frame targetRef={targetRef} className={classnames(styles.frame, classes?.frame)} watchMotion={watchMotion} />
+
+      {components && (
+        <LabelContainer targetRef={targetRef} className={styles.label} placement={placement} watchMotion={watchMotion}>
+          <Label components={components} className={classes?.label} />
+        </LabelContainer>
+      )}
+    </div>
+  );
+}

package/element-highlighter/index.ts

@@ -0,0 +1,2 @@
+export { ElementHighlighter } from './element-highlighter';
+export type { ElementHighlighterProps, Placement, HighlightClasses } from './element-highlighter';

package/frame/frame.module.scss

@@ -0,0 +1,23 @@
+$border: 2;
+$padding: 4;
+
+.overlayBorder {
+  box-sizing: border-box;
+  border: $border * 1px solid var(--bit-highlighter-color, #eebcc9);
+
+  border-radius: 11px;
+  padding: $padding * 1px;
+
+  pointer-events: none;
+  user-select: none;
+}
+
+.hidden {
+  // the frame's size is ignored anyways,
+  // and so we can use 'display: none' and not 'visibility: hidden'
+  display: none;
+}
+
+:export {
+  offset: $border + $padding;
+}

package/frame/frame.tsx

@@ -0,0 +1,142 @@
+import React, { useEffect, useLayoutEffect, useRef, RefObject, CSSProperties } from 'react';
+import classnames from 'classnames';
+import { useFloating, autoUpdate, offset, size, detectOverflow, hide } from '@floating-ui/react-dom';
+import type { Coords } from '@floating-ui/react-dom';
+
+import styles from './frame.module.scss';
+
+export const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect
+
+/** frame padding around the target */
+const MARGIN_FROM_TARGET = +styles.offset || 6; // setting fallback 6, for tests
+/** min. distance from the edge of the screen. */
+const MARGIN_FROM_DOC_EDGE = 0;
+
+const overflowParameters = { rootBoundary: 'document', padding: MARGIN_FROM_DOC_EDGE } as const;
+const SHIFT_POSITIVE = 'shiftPositive';
+
+const HAS_RESIZE_OBSERVER = typeof window !== 'undefined' && !!window.ResizeObserver;
+
+export interface FrameProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** apply the frame to this element  */
+  targetRef: RefObject<HTMLElement | null>;
+  /**
+   * the specific flavor of the frame.
+   * @default "redBorderClass"
+   */
+  stylesClass?: string;
+  /** continually update frame position to match moving elements */
+  watchMotion?: boolean;
+}
+
+// position - bottom start (bottom left corner)
+// x - width - horizontal (cross axis)
+// y - height - vertical (main axis)
+
+type DimensionsStyle = Pick<CSSProperties, 'width' | 'height' | 'maxWidth' | 'maxHeight'>;
+
+export function Frame({ targetRef, watchMotion, className, stylesClass = styles.overlayBorder, style }: FrameProps) {
+  const dimensionRef = useRef<DimensionsStyle>({ width: 0, height: 0 });
+
+  const { x, y, strategy, reference, floating, update, refs, middlewareData } = useFloating({
+    placement: 'bottom-start',
+    middleware: [
+      // replace dimensions from previous iterations with the target's size
+      // this is only the measured size, not yet the applied size
+      {
+        name: 'align-to-target',
+        fn({ rects }) {
+          rects.floating = {
+            ...rects.floating,
+            width: rects.reference.width + 2 * MARGIN_FROM_TARGET,
+            height: rects.reference.height + 2 * MARGIN_FROM_TARGET,
+          };
+
+          return {};
+        },
+      },
+      // reposition x,y, to the top of the reference
+      offset(({ rects }) => -rects.reference.height),
+      // offset the frame by its extra padding
+      offset(() => ({ mainAxis: -MARGIN_FROM_TARGET, crossAxis: -MARGIN_FROM_TARGET })),
+      // pushes the frame into the document. Similar to shift(), but only pushes when coods are negative
+      {
+        name: 'shiftPositive',
+        fn: async (args) => {
+          const overflow = await detectOverflow(args, overflowParameters);
+
+          const nextCoords = {
+            x: overflow.left > 0 ? args.x + overflow.left : args.x,
+            y: overflow.top > 0 ? args.y + overflow.top : args.y,
+          };
+          const shiftAmount = {
+            x: nextCoords.x - args.x,
+            y: nextCoords.y - args.y,
+          };
+
+          return {
+            ...nextCoords,
+            data: shiftAmount,
+          };
+        },
+      },
+      // size also applies overflow detection via width and height
+      size({
+        // apply overflow detection in reference to the document
+        rootBoundary: 'document',
+        padding: MARGIN_FROM_DOC_EDGE,
+        apply({ elements, rects, availableHeight, availableWidth, middlewareData }) {
+          const shift: Coords = middlewareData[SHIFT_POSITIVE] || { x: 0, y: 0 };
+          const paddingX = 2 * MARGIN_FROM_TARGET - shift.x;
+          const paddingY = 2 * MARGIN_FROM_TARGET - shift.y;
+
+          const dimensions: DimensionsStyle = {
+            width: rects.reference.width + paddingX,
+            height: rects.reference.height + paddingY,
+            maxWidth: availableWidth,
+            maxHeight: availableHeight,
+          };
+
+          // per floating-ui docs, apply styles directly during apply()
+          Object.assign(elements.floating.style, dimensions);
+
+          // also store in reference, so react renders will have the same value
+          dimensionRef.current = dimensions;
+        },
+      }),
+      hide({ strategy: 'referenceHidden' }),
+    ],
+  });
+
+  // set target as floating reference
+  useIsomorphicLayoutEffect(() => {
+    reference(targetRef.current);
+  }, [targetRef.current]);
+
+  // automatically update on scroll, resize, etc.
+  // `watchMotion` will trigger continuous updates using animation frame
+  useEffect(() => {
+    if (!refs.reference.current || !refs.floating.current || !HAS_RESIZE_OBSERVER) return () => {};
+
+    return autoUpdate(refs.reference.current, refs.floating.current, update, { animationFrame: watchMotion });
+  }, [refs.reference.current, refs.floating.current, update, watchMotion]);
+
+  // could check if x !== null
+  const isReady = !middlewareData.hide?.referenceHidden;
+
+  return (
+    <div
+      ref={floating}
+      className={classnames(className, stylesClass, !isReady && styles.hidden)}
+      style={{
+        ...style,
+        ...dimensionRef.current,
+        position: strategy,
+        // starting at pos [0,0] will ensure the label doesn't increase the document size.
+        top: y ?? 0,
+        left: x ?? 0,
+      }}
+    />
+  );
+}

package/frame/index.ts

@@ -0,0 +1,2 @@
+export { Frame } from './frame';
+export type { FrameProps } from './frame';

package/hover-highlighter/bubble-to-component.spec.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import { MockTarget } from '../mock-component';
+import { bubbleToComponent } from './bubble-to-component';
+
+it('should find component when starting from a div', () => {
+  const { getByText, getByTestId } = render(
+    <MockTarget data-testid="expected-result">
+      <div>hello world</div>
+    </MockTarget>
+  );
+
+  const rendered = getByText('hello world');
+
+  const result = bubbleToComponent(rendered);
+
+  expect(result?.element).toBe(getByTestId('expected-result'));
+  expect(result?.components).toEqual([MockTarget]);
+});
+
+it('should bubble to root component when it renders itself recursively', () => {
+  const { getByText, getByTestId } = render(
+    <MockTarget data-testid="expected-result">
+      <MockTarget>
+        <MockTarget>
+          <div>hello world</div>
+        </MockTarget>
+      </MockTarget>
+    </MockTarget>
+  );
+
+  const rendered = getByText('hello world');
+
+  const result = bubbleToComponent(rendered);
+
+  expect(result?.element).toBe(getByTestId('expected-result'));
+  expect(result?.components).toEqual([MockTarget]);
+});
+
+it('should find first component, when parent propagation is disabled', () => {
+  const { getByText, getByTestId } = render(
+    <MockTarget>
+      <MockTarget>
+        <MockTarget data-testid="expected-result">
+          <div>hello world</div>
+        </MockTarget>
+      </MockTarget>
+    </MockTarget>
+  );
+
+  const rendered = getByText('hello world');
+
+  const result = bubbleToComponent(rendered, { propagateSameParents: false });
+
+  expect(result?.element).toBe(getByTestId('expected-result'));
+  expect(result?.components).toEqual([MockTarget]);
+});