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

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>
+  );
+};

package/hover-highlighter/hover-highlighter.spec.tsx

@@ -0,0 +1,115 @@
+import React, { ReactNode } from 'react';
+import { act } from 'react-dom/test-utils';
+import { render, fireEvent, waitForElementToBeRemoved } from '@testing-library/react';
+import { ComponentMeta, componentMetaField } from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+
+import { HoverHighlighter } from './hover-highlighter';
+
+const debounceTime = 2;
+
+function ButtonComponent({ children }: { children: ReactNode }) {
+  return <button>{children}</button>;
+}
+
+ButtonComponent[componentMetaField] = {
+  // could use a non-bit-id to render the "default" bubble
+  id: 'teambit.base-ui/input/button',
+} as ComponentMeta;
+
+it('should show bubble when hovering on element with bit id', async () => {
+  const { getByText, findByText } = render(
+    <HoverHighlighter debounceSelection={debounceTime}>
+      <ButtonComponent>hover here</ButtonComponent>
+    </HoverHighlighter>
+  );
+  const rendered = getByText('hover here');
+  expect(rendered).toBeTruthy();
+
+  act(() => {
+    fireEvent.mouseOver(rendered);
+  });
+
+  const highlightBubble = await findByText('input/button');
+  expect(highlightBubble).toBeInstanceOf(HTMLElement);
+});
+
+it('should hide the highlight when hovering out of the element', async () => {
+  const { getByText, findByText, queryByText } = render(
+    <HoverHighlighter debounceSelection={debounceTime}>
+      <ButtonComponent>hover here</ButtonComponent>
+    </HoverHighlighter>
+  );
+  const rendered = getByText('hover here');
+
+  act(() => {
+    fireEvent.mouseOver(rendered);
+  });
+
+  const highlightBubble = await findByText('input/button');
+  expect(highlightBubble).toBeInstanceOf(HTMLElement);
+
+  act(() => {
+    fireEvent.mouseOut(rendered);
+  });
+  await waitForElementToBeRemoved(() => queryByText('input/button'));
+});
+
+it('should keep the highlighter, when hovering on it (even when moving out of the component zone)', async () => {
+  const { getByText, findByText } = render(
+    <HoverHighlighter debounceSelection={debounceTime}>
+      <ButtonComponent>hover here</ButtonComponent>
+    </HoverHighlighter>
+  );
+  const rendered = getByText('hover here');
+
+  act(() => {
+    // hover on target element:
+    fireEvent.mouseOver(rendered);
+  });
+
+  const highlightBubble = await findByText('input/button');
+
+  await act(async () => {
+    // move mouse out of target element, "towards" the highlighter bubble
+    // this should trigger hiding
+    fireEvent.mouseOut(rendered);
+
+    // move mouse into the highlighter bubble
+    fireEvent.mouseEnter(highlightBubble);
+    // allow react to update state during the act()
+    // and before verifying highlighter remains
+    await new Promise((resolve) => setTimeout(resolve, debounceTime + 10));
+  });
+
+  // highlighter should still focus the target button
+  expect(await findByText('input/button')).toBeInstanceOf(HTMLElement);
+});
+
+it('should hide the highlighter when moving the mouse away of it', async () => {
+  const { getByText, queryByText, findByText } = render(
+    <HoverHighlighter debounceSelection={debounceTime}>
+      <ButtonComponent>hover here</ButtonComponent>
+    </HoverHighlighter>
+  );
+
+  const rendered = getByText('hover here');
+
+  // hover on target element:
+  await act(async () => {
+    fireEvent.mouseOver(rendered);
+  });
+
+  const highlightBubble = await findByText('input/button');
+
+  await act(async () => {
+    // hover on highlighter
+    fireEvent.mouseEnter(highlightBubble);
+    // leave the highlighter
+    fireEvent.mouseOut(highlightBubble);
+    await new Promise((resolve) => setTimeout(resolve, debounceTime + 10));
+  });
+
+  // highlighter sometimes disappears before this check,
+  // so not using waitForElementToBeRemoved, and using setTimeout instead
+  expect(queryByText('input/button')).toBeNull();
+});

package/hover-highlighter/hover-highlighter.tsx

@@ -0,0 +1,8 @@
+import React from 'react';
+import { HybridHighlighter, HybridHighlighterProps } from '../hybrid-highlighter';
+
+export type HoverHighlighterProps = Omit<HybridHighlighterProps, 'mode'>;
+
+export function HoverHighlighter({ ...props }: HoverHighlighterProps) {
+  return <HybridHighlighter {...props} mode={'hover'} />;
+}

package/hover-highlighter/index.ts

@@ -0,0 +1,5 @@
+export { useHoverHighlighter } from './use-hover-highlighter';
+export type { useHoverHighlighterOptions } from './use-hover-highlighter';
+
+export { HoverHighlighter } from './hover-highlighter';
+export type { HoverHighlighterProps } from './hover-highlighter';

package/hover-highlighter/use-hover-highlighter.tsx

@@ -0,0 +1,85 @@
+import React, { useEffect } from 'react';
+import { useDebouncedCallback } from 'use-debounce';
+import { useHoverSelection } from '@teambit/react.ui.hover-selector';
+import { ComponentMetaHolder } from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+
+import { excludeHighlighterSelector, skipHighlighterSelector } from '../ignore-highlighter';
+import { MatchRule, ComponentMatchRule } from '../rule-matcher';
+import { bubbleToComponent } from './bubble-to-component';
+
+type HighlightTarget = { element: HTMLElement; components: ComponentMetaHolder[] };
+export type useHoverHighlighterOptions = {
+  debounceDuration: number;
+  scopeClass: string;
+  disabled?: boolean;
+  /** filter highlighter targets by this query selector. (May be a more complex object in the future) */
+  rule?: MatchRule;
+  /** filter targets by this component match rule */
+  componentRule?: ComponentMatchRule;
+};
+
+/** fires onChange when targeting a new component */
+export function useHoverHighlighter<T extends HTMLElement = HTMLElement>(
+  onChange: (target?: HighlightTarget) => void,
+  props: React.HTMLAttributes<T> = {},
+  { debounceDuration, scopeClass, disabled, rule, componentRule }: useHoverHighlighterOptions
+) {
+  const { handleElement } = useHoverHandler({ onChange, scopeClass, debounceDuration, disabled, rule, componentRule });
+
+  const handlers = useHoverSelection(disabled ? undefined : handleElement, props);
+
+  return handlers;
+}
+
+type useHoverHighlighterProps = {
+  onChange: (target?: HighlightTarget) => void;
+  scopeClass?: string;
+  debounceDuration?: number;
+  disabled?: boolean;
+  rule?: MatchRule;
+  componentRule?: ComponentMatchRule;
+};
+
+function useHoverHandler({
+  onChange,
+  scopeClass = '',
+  debounceDuration,
+  disabled,
+  rule,
+  componentRule,
+}: useHoverHighlighterProps) {
+  // debounced method is ref'ed, so no need for useCallback
+  const _handleElement = (element: HTMLElement | null) => {
+    // clear highlighter at the edges:
+    if (!element || element.hasAttribute('data-nullify-component-highlight')) {
+      onChange(undefined);
+      return;
+    }
+
+    // clear when ancestor has 'data-ignore-component-highlight'
+    if (element.closest(`.${scopeClass} ${excludeHighlighterSelector}`)) {
+      onChange(undefined);
+      return;
+    }
+
+    // skip DOM trees having 'data-skip-component-highlight'
+    if (element.closest(`.${scopeClass} ${skipHighlighterSelector}`)) return;
+
+    const result = bubbleToComponent(element, { elementRule: rule, componentRule });
+    if (!result) return;
+
+    onChange({
+      element: result.element,
+      components: result.components,
+    });
+  };
+
+  const handleElement = useDebouncedCallback(_handleElement, debounceDuration);
+
+  // clear when disabling
+  useEffect(() => {
+    if (disabled) handleElement.cancel();
+  }, [disabled, handleElement]);
+
+  return { handleElement };
+}

package/hybrid-highlighter/hybrid-highlighter.tsx

@@ -0,0 +1,142 @@
+import React, { useState, useEffect, useMemo, useRef, createRef, CSSProperties } from 'react';
+import classnames from 'classnames';
+import { v4 } from 'uuid';
+
+import { ComponentMetaHolder } from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+
+import { useHoverHighlighter } from '../hover-highlighter';
+import { ElementHighlighter, Placement, HighlightClasses } from '../element-highlighter';
+import { useChildrenHighlighter } from '../children-highlighter';
+import type { MatchRule, ComponentMatchRule } from '../rule-matcher';
+
+type HighlightTarget = { element: HTMLElement; components: ComponentMetaHolder[] };
+
+export interface HybridHighlighterProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** stop all highlighting and drop listeners */
+  disabled?: boolean;
+  /** default pop location for the label */
+  placement?: Placement;
+  /** customize styles */
+  classes?: HighlightClasses;
+  /** customize highlighter */
+  highlightStyle?: CSSProperties;
+  /** debounces element hover selection.
+   * A higher value will reduce element lookups as well as "keep" the highlight on the current element for longer.
+   * Initial selection (when no element is currently selected) will always happen immediately to improve the user experience.
+   * @default 80ms
+   */
+  debounceSelection?: number;
+  /** continually update frame position to match moving elements */
+  watchMotion?: boolean;
+
+  /** filter highlighter targets by this query selector. (May be a more complex object in the future) */
+  rule?: MatchRule;
+  /** filter components to match this rule. Can be id, array of ids, or a function */
+  componentRule?: ComponentMatchRule;
+
+  /** set the behavior of the highlighter.
+   * `disabled` - stops highlighting.
+   * `allChildren` - highlights all components rendered under children
+   * `hover` - highlighters the component immediately under the mouse cursor
+   * */
+  mode?: 'allChildren' | 'hover';
+  bgColor?: string;
+  bgColorHover?: string;
+  bgColorActive?: string;
+}
+
+/** automatically highlight components on hover */
+export function HybridHighlighter({
+  disabled,
+  mode = 'hover',
+  debounceSelection = 80,
+  watchMotion = true,
+  placement,
+  rule,
+  componentRule,
+
+  classes,
+  highlightStyle,
+  className,
+  style,
+  bgColor,
+  bgColorHover,
+  bgColorActive,
+  children,
+  ...rest
+}: HybridHighlighterProps) {
+  const ref = createRef<HTMLDivElement>();
+  const [targets, setTarget] = useState<Record<string, HighlightTarget>>({});
+  // const scopeClass = useRef(`hl-scope-${v4()}`).current;
+  const [scopeClass, setScopeClass] = useState<string>('');
+
+  useEffect(() => {
+    setScopeClass(`hl-scope-${v4()}`);
+  }, []);
+
+  const hasTargets = Object.entries(targets).length > 0;
+
+  // clear targets when disabled
+  useEffect(() => {
+    if (disabled) setTarget({});
+  }, [disabled]);
+
+  const handlers = useHoverHighlighter(
+    (nextTarget) => setTarget(nextTarget ? { 'hover-target': nextTarget } : {}),
+    rest,
+    {
+      debounceDuration: hasTargets ? debounceSelection : 0,
+      scopeClass,
+      disabled: disabled || mode !== 'hover',
+      rule,
+      componentRule,
+    }
+  );
+
+  useChildrenHighlighter({
+    onChange: setTarget,
+    scopeRef: ref,
+    scopeClass,
+    disabled: disabled || mode !== 'allChildren',
+    rule,
+    componentRule,
+  });
+
+  const _styles = useMemo(
+    () => ({
+      '--bit-highlighter-color': bgColor,
+      '--bit-highlighter-color-hover': bgColorHover,
+      '--bit-highlighter-color-active': bgColorActive,
+      ...style,
+    }),
+    [bgColor, bgColorHover, bgColorActive, style]
+  );
+
+  return (
+    <div
+      ref={ref}
+      {...rest}
+      {...handlers}
+      style={_styles}
+      className={classnames(className, scopeClass)}
+      data-nullify-component-highlight
+    >
+      {children}
+      {/*
+       * keep the highlighter inside of the hover selector, or it could disappear when switching between elements
+       * the excludeHighlighterAtt will ensure it doesn't turn into a recursion.
+       */}
+      {Object.entries(targets).map(([key, target]) => (
+        <ElementHighlighter
+          key={key}
+          targetRef={{ current: target.element }}
+          components={target.components}
+          classes={classes}
+          style={highlightStyle}
+          placement={placement}
+          watchMotion={watchMotion}
+        />
+      ))}
+    </div>
+  );
+}

package/hybrid-highlighter/index.ts

@@ -0,0 +1,2 @@
+export { HybridHighlighter } from './hybrid-highlighter';
+export type { HybridHighlighterProps } from './hybrid-highlighter';

package/ignore-highlighter.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+
+/** name of ignore attribute */
+export const excludeHighlighterAttrName = 'data-ignore-component-highlight';
+
+/** selector for elements with the ignore attribute */
+export const excludeHighlighterSelector = `[${excludeHighlighterAttrName}]`;
+
+/** highlighter will exclude elements with this attribute */
+export const excludeHighlighterAtt = { [excludeHighlighterAttrName]: true };
+
+/** children of this element will be excluded by the automatic highlighter */
+export function ExcludeHighlighter(props: React.HTMLAttributes<HTMLDivElement>) {
+  return <div {...props} {...excludeHighlighterAtt} />;
+}
+
+/** name of skip attribute */
+export const skipHighlighterAttrName = 'data-skip-component-highlight';
+/** highlighter will skip (ignore) elements with these attributes */
+export const skipHighlighterAttr = { [skipHighlighterAttrName]: true };
+/** selector for elements with the skip attribute */
+export const skipHighlighterSelector = `[${skipHighlighterAttrName}]`;

package/index.ts

@@ -0,0 +1,21 @@
+export { HybridHighlighter as ComponentHighlighter } from './hybrid-highlighter';
+export type { HybridHighlighterProps as ComponentHighlightProps } from './hybrid-highlighter';
+
+export { HoverHighlighter } from './hover-highlighter';
+export type { HoverHighlighterProps } from './hover-highlighter';
+
+export { ChildrenHighlighter } from './children-highlighter';
+export type { ChildrenHighlighterProps } from './children-highlighter';
+
+export { ElementHighlighter } from './element-highlighter';
+export type { ElementHighlighterProps, Placement, HighlightClasses } from './element-highlighter';
+
+export {
+  ExcludeHighlighter,
+  excludeHighlighterAtt,
+  excludeHighlighterAttrName,
+  skipHighlighterAttr,
+  skipHighlighterAttrName,
+} from './ignore-highlighter';
+
+export type { MatchRule } from './rule-matcher';

package/label/component-strip.compositions.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { ComponentStrip } from './component-strip';
+import { MockButton, MockSnap } from '../mock-component';
+
+export const ComponentStripPreview = () => {
+  return (
+    <div style={{ fontFamily: 'sans-serif', padding: 8 }}>
+      <ComponentStrip component={MockSnap} />
+      <br />
+      <ComponentStrip component={MockButton} />
+    </div>
+  );
+};

package/label/component-strip.module.scss

@@ -0,0 +1,68 @@
+$borderRadius: 0.5em;
+$gap: 0.125em;
+
+.componentStrip {
+  display: flex;
+  width: fit-content; // for correct shadow size
+
+  border-radius: $borderRadius;
+  box-shadow: var(--bit-highlighter-shadow);
+  white-space: nowrap;
+
+  > * {
+    padding: 0 0.5em;
+    line-height: 1.5; //use line height to get rounder values than 0.25em padding
+
+    transition: filter 300ms, background-color 300ms;
+    transform: translateZ(0); //fix blurriness in Safari
+
+    background: var(--bit-highlighter-color, #eebcc9);
+
+    margin-right: $gap;
+
+    &:link,
+    &:visited {
+      text-decoration: inherit; // reset browser defaults
+      color: inherit; // reset browser defaults
+
+      &:hover {
+        background: var(--bit-highlighter-color-hover, #f6dae2);
+      }
+
+      &:active {
+        background: var(--bit-highlighter-color-active, #e79db1);
+        color: inherit;
+      }
+    }
+
+    &:first-child {
+      border-top-left-radius: $borderRadius;
+      border-bottom-left-radius: $borderRadius;
+    }
+
+    &:last-child {
+      border-top-right-radius: $borderRadius;
+      border-bottom-right-radius: $borderRadius;
+
+      margin-right: unset;
+    }
+  }
+}
+
+.nameBlock {
+  display: flex;
+
+  .version {
+    // leave room for 9 digits + 3 "."
+    max-width: 13ch;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    
+    transition: max-width 480ms;
+
+    &:hover {
+      max-width: 61ch;
+    }
+  }
+}