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

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,136 @@
+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 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;
+    }
+  }
+}

package/label/component-strip.tsx

@@ -0,0 +1,57 @@
+import React, { useMemo, ReactNode, forwardRef, ForwardedRef } from 'react';
+import { NativeLink } from '@teambit/base-ui.routing.native-link';
+import { ComponentID } from '@teambit/component-id';
+import { ScopeUrl } from '@teambit/component.modules.component-url';
+import {
+  ComponentMeta,
+  componentMetaField,
+  ComponentMetaHolder,
+} from '@teambit/react.ui.highlighter.component-metadata.bit-component-meta';
+import styles from './component-strip.module.scss';
+import { calcComponentLink } from './links';
+
+interface ComponentStripProps extends React.HTMLAttributes<HTMLDivElement> {
+  component: ComponentMetaHolder | string;
+}
+export const ComponentStrip = forwardRef(function ComponentStrip(
+  { component, children }: ComponentStripProps,
+  ref: ForwardedRef<HTMLDivElement>
+) {
+  const { id, homepage, exported } = extractMetadata(component);
+
+  const parsedId = useMemo(() => ComponentID.tryFromString(id), [id]);
+  const componentLink = homepage || calcComponentLink(parsedId, exported);
+
+  return (
+    <div className={styles.componentStrip} ref={ref}>
+      {!parsedId && <LabelBlock link={homepage}>{id}</LabelBlock>}
+      {parsedId && <LabelBlock link={ScopeUrl.toUrl(parsedId.scope)}>{parsedId.scope}</LabelBlock>}
+      {parsedId && (
+        <LabelBlock link={componentLink} className={styles.nameBlock}>
+          <span>{parsedId.fullName}</span>
+          {parsedId.version && parsedId.version !== 'latest' && (
+            <span className={styles.version}>@{parsedId.version}</span>
+          )}
+        </LabelBlock>
+      )}
+      {children}
+    </div>
+  );
+});
+
+function LabelBlock({ link, children, className }: { link?: string; children: ReactNode; className?: string }) {
+  const Comp = link ? NativeLink : 'span';
+  return (
+    <Comp href={link} external={!!link} className={className}>
+      {children}
+    </Comp>
+  );
+}
+
+function extractMetadata(metadata: string | ComponentMetaHolder): ComponentMeta {
+  if (typeof metadata === 'string') {
+    return { id: metadata, exported: true };
+  }
+
+  return metadata[componentMetaField];
+}

package/label/index.ts

@@ -0,0 +1,5 @@
+export { Label } from './label';
+export type { LabelProps } from './label';
+
+export { LabelContainer } from './label-container';
+export type { LabelContainerProps, Placement } from './label-container';

package/label/label-container.tsx

@@ -0,0 +1,72 @@
+import React, { useLayoutEffect, useEffect, RefObject } from 'react';
+import classnames from 'classnames';
+import compact from 'lodash.compact';
+import {
+  useFloating,
+  offset as offsetMiddleware,
+  flip as flipMiddleware,
+  shift,
+  autoUpdate,
+  hide,
+} from '@floating-ui/react-dom';
+import type { Placement } from '@floating-ui/react-dom';
+import styles from './label.module.scss';
+
+const HAS_RESIZE_OBSERVER = typeof window !== 'undefined' && !!window.ResizeObserver;
+
+export interface LabelContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+  targetRef: RefObject<HTMLElement | null>;
+  offset?: [number, number];
+  placement?: Placement;
+  flip?: boolean;
+  /** continually update label position to match moving elements */
+  watchMotion?: boolean;
+}
+
+export type { Placement };
+
+export function LabelContainer({
+  targetRef,
+  offset,
+  placement,
+  flip = true,
+  watchMotion,
+  className,
+  style,
+  ...rest
+}: LabelContainerProps) {
+  const { x, y, strategy, floating, reference, refs, update, middlewareData } = useFloating({
+    placement,
+    middleware: compact([
+      offset && offsetMiddleware({ mainAxis: offset[0], crossAxis: offset[1] }),
+      flip && flipMiddleware(),
+      // enabling 'shift' for 'crossAxis' will make floating-ui push the label _inside_, when it has nowhere to go
+      shift({ rootBoundary: 'document', mainAxis: true, crossAxis: true }),
+      hide({ strategy: 'referenceHidden' }),
+    ]),
+  });
+
+  useLayoutEffect(() => {
+    reference(targetRef.current);
+  }, [targetRef.current, reference]);
+
+  // 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]);
+
+  const isReady = !middlewareData.hide?.referenceHidden;
+
+  return (
+    <div
+      {...rest}
+      ref={floating}
+      className={classnames(className, !isReady && styles.hidden)}
+      // starting at pos [0,0] will ensure the label doesn't increase the document size.
+      style={{ ...style, position: strategy, top: y ?? 0, left: x ?? 0 }}
+    />
+  );
+}

package/label/label.module.scss

@@ -0,0 +1,32 @@
+.othersContainer {
+  > * {
+    margin-bottom: 8px;
+
+    &:last-child {
+      margin-bottom: unset;
+    }
+  }
+}
+
+.othersTooltip {
+  user-select: none;
+  cursor: pointer;
+
+  &::before {
+    display: inline-block;
+    transition: transform 300ms;
+    content: '▾';
+  }
+
+  &.active::before {
+    transform: rotate(-180deg);
+  }
+}
+
+.hidden {
+  // label size is needed for position calculations,
+  // so it can't be removed by `display: none`
+  visibility: hidden;
+  pointer-events: none;
+  user-select: none;
+}