@teambit/react.ui.component-highlighter 0.0.0-4d64e75088ad738b699f1df7db0bcd7201d589d0

package/dist/preview-1751963029152.js

@@ -0,0 +1,10 @@
+import * as compositions_0 from '/tmp/capsules-root/sign-capsules/2025-6-8/gha9du/teambit.react_ui_component-highlighter@4d64e75088ad738b699f1df7db0bcd7201d589d0/dist/children-highlighter/children-highlighter.composition.js';
+import * as compositions_1 from '/tmp/capsules-root/sign-capsules/2025-6-8/gha9du/teambit.react_ui_component-highlighter@4d64e75088ad738b699f1df7db0bcd7201d589d0/dist/element-highlighter/element-highlighter.compositions.js';
+import * as compositions_2 from '/tmp/capsules-root/sign-capsules/2025-6-8/gha9du/teambit.react_ui_component-highlighter@4d64e75088ad738b699f1df7db0bcd7201d589d0/dist/hover-highlighter/hover-highlighter.compositions.js';
+import * as compositions_3 from '/tmp/capsules-root/sign-capsules/2025-6-8/gha9du/teambit.react_ui_component-highlighter@4d64e75088ad738b699f1df7db0bcd7201d589d0/dist/label/component-strip.compositions.js';
+import * as overview_0 from '/tmp/capsules-root/sign-capsules/2025-6-8/gha9du/teambit.react_ui_component-highlighter@4d64e75088ad738b699f1df7db0bcd7201d589d0/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,139 @@
+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';
+
+/** 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
+  useLayoutEffect(() => {
+    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]);
+});

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

@@ -0,0 +1,82 @@
+import { domToReacts, toRootElement } from '@teambit/react.modules.dom-to-react';
+import {
+  componentMetaField,
+  hasComponentMeta,
+  ReactComponentMetaHolder,
+} from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+import { ruleMatcher, MatchRule, ComponentMatchRule, componentRuleMatcher } from '../rule-matcher';
+
+type BubblingOptions = {
+  /** filter elements by this rule */
+  elementRule?: MatchRule;
+  /** filter components by this rule */
+  componentRule?: ComponentMatchRule;
+  /**
+   * continue bubbling when encountering a parent of the same component
+   * @default true
+   */
+  propagateSameParents?: boolean;
+};
+
+/** go up the dom tree until reaching a react bit component */
+export function bubbleToComponent(
+  element: HTMLElement | null,
+  { elementRule, componentRule, propagateSameParents = true }: BubblingOptions = {}
+) {
+  // check if the element is rendered in Vue
+  if ((element as any)?.__vnode) {
+    const vueComp = (element as any).__vnode?.ctx?.type;
+    const comp = vueComp?.__bit_component;
+    const compEl = (element as any).__vnode?.ctx?.ctx?.$el;
+    if (compEl && comp) {
+      return {
+        element: compEl,
+        components: [{ [componentMetaField]: comp }],
+      };
+    }
+  }
+
+  let current = bubbleToFirstComponent(element, elementRule, componentRule);
+  if (!propagateSameParents) return current;
+
+  while (current) {
+    const parentElement = current.element.parentElement;
+    const parent = bubbleToFirstComponent(parentElement, elementRule, componentRule);
+
+    const primeComponent = current?.components.slice(-1).pop();
+    const parentPrimeComponent = parent?.components.slice(-1).pop();
+
+    if (primeComponent?.[componentMetaField].id !== parentPrimeComponent?.[componentMetaField].id) return current;
+
+    current = parent;
+  }
+
+  return undefined;
+}
+
+/** go up the dom tree until reaching a react bit component */
+function bubbleToFirstComponent(
+  element: HTMLElement | null,
+  elementRule?: MatchRule,
+  componentRule?: ComponentMatchRule
+) {
+  for (let current = element; current; current = current.parentElement) {
+    current = toRootElement(current);
+    if (!current) return undefined;
+    if (ruleMatcher(current, elementRule)) {
+      const components = domToReacts(current);
+
+      const relevantComponents = components.filter(
+        (x) => hasComponentMeta(x) && componentRuleMatcher({ meta: x[componentMetaField] }, componentRule)
+      ) as ReactComponentMetaHolder[];
+
+      if (relevantComponents.length < 1) return undefined;
+      return {
+        element: current,
+        components: relevantComponents,
+      };
+    }
+  }
+
+  return undefined;
+}

package/hover-highlighter/hover-highlighter.compositions.tsx

@@ -0,0 +1,65 @@
+import React, { useEffect, useState } from 'react';
+import { HoverHighlighter } from './hover-highlighter';
+import { MockButton, MockTarget } from '../mock-component';
+import { excludeHighlighterAtt } from '../ignore-highlighter';
+
+export const ShowWhenHovering = () => {
+  const [disabled, setDisabled] = useState<boolean>(false);
+
+  return (
+    <div style={{ padding: '16px 50px 32px 16px', minWidth: 300, fontFamily: 'sans-serif' }}>
+      <HoverHighlighter style={{ padding: 16 }} disabled={disabled}>
+        <div>
+          <br />
+          <div>
+            <MockButton onClick={() => setDisabled((x) => !x)}>Hover here</MockButton>
+          </div>
+          <div>
+            {disabled ? 'X' : '✓'} highlighter is {disabled ? 'disabled' : 'enabled'}
+          </div>
+        </div>
+      </HoverHighlighter>
+    </div>
+  );
+};
+
+export const UnmountingElement = () => {
+  const [shown, setShown] = useState(true);
+  useEffect(() => {
+    const tid = setInterval(() => setShown((x) => !x), 1500);
+    return () => clearInterval(tid);
+  }, []);
+
+  return (
+    <div style={{ padding: '16px 50px 32px 16px', minWidth: 300, fontFamily: 'sans-serif' }}>
+      <HoverHighlighter>
+        <div>{!shown && '(hidden)'}</div>
+
+        <div>{shown && <MockButton>Hover here</MockButton>}</div>
+        <br />
+        <MockTarget>
+          <div>{shown && <MockButton>Hover here</MockButton>}</div>
+          <div>same with a container</div>
+        </MockTarget>
+      </HoverHighlighter>
+    </div>
+  );
+};
+
+export const HoverExclusionZones = () => {
+  return (
+    <div style={{ padding: '16px 50px 32px 16px', minWidth: 300, fontFamily: 'sans-serif' }}>
+      <HoverHighlighter>
+        <MockTarget>
+          container (target-able)
+          <div>{<MockButton>will be highlighted</MockButton>}</div>
+        </MockTarget>
+        <br />
+        <MockTarget>
+          container (target-able)
+          <div {...excludeHighlighterAtt}>{<MockButton>will be ignored</MockButton>}</div>
+        </MockTarget>
+      </HoverHighlighter>
+    </div>
+  );
+};