@dr.pogodin/react-utils 1.25.5 → 1.26.0

package/src/shared/components/WithTooltip/Tooltip.tsx

@@ -0,0 +1,353 @@
+/**
+ * The actual tooltip component. It is rendered outside the regular document
+ * hierarchy, and with sub-components managed without React to achieve the best
+ * performance during animation.
+ */
+/* global document, window */
+
+import {
+  type ReactNode,
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+
+import { createPortal } from 'react-dom';
+
+import PT from 'prop-types';
+
+/* Valid placements of the rendered tooltip. They will be overriden when
+ * necessary to fit the tooltip within the viewport. */
+export enum PLACEMENTS {
+  ABOVE_CURSOR = 'ABOVE_CURSOR',
+  ABOVE_ELEMENT = 'ABOVE_ELEMENT',
+  BELOW_CURSOR = 'BELOW_CURSOR',
+  BELOW_ELEMENT = 'BELOW_ELEMENT',
+}
+
+const ARROW_STYLE_DOWN = [
+  'border-bottom-color:transparent',
+  'border-left-color:transparent',
+  'border-right-color:transparent',
+].join(';');
+
+const ARROW_STYLE_UP = [
+  'border-top-color:transparent',
+  'border-left-color:transparent',
+  'border-right-color:transparent',
+].join(';');
+
+type ComponentsT = {
+  container: HTMLDivElement;
+  arrow: HTMLDivElement;
+  content: HTMLDivElement;
+};
+
+type HeapT = {
+  lastElement?: HTMLElement;
+  lastPageX: number;
+  lastPageY: number;
+  lastPlacement?: PLACEMENTS | undefined;
+};
+
+export interface TooltipThemeT {
+  appearance?: string;
+  arrow?: string;
+  content?: string;
+  container?: string;
+}
+
+/**
+ * Creates tooltip components.
+ * @ignore
+ * @param {object} theme Themes to use for tooltip container, arrow,
+ *  and content.
+ * @return {object} Object with DOM references to the container components:
+ *  container, arrow, content.
+ */
+function createTooltipComponents(theme: TooltipThemeT): ComponentsT {
+  const arrow = document.createElement('div');
+  if (theme.arrow) arrow.setAttribute('class', theme.arrow);
+
+  const content = document.createElement('div');
+  if (theme.content) content.setAttribute('class', theme.content);
+
+  const container = document.createElement('div');
+  if (theme.container) container.setAttribute('class', theme.container);
+
+  container.appendChild(arrow);
+  container.appendChild(content);
+  document.body.appendChild(container);
+
+  return { container, arrow, content };
+}
+
+type TooltipRectsT = {
+  arrow: DOMRect;
+  container: DOMRect;
+};
+
+/**
+ * Generates bounding client rectangles for tooltip components.
+ * @ignore
+ * @param tooltip DOM references to the tooltip components.
+ * @param tooltip.arrow
+ * @param tooltip.container
+ * @return Object holding tooltip rectangles in
+ *  two fields.
+ */
+function calcTooltipRects(tooltip: ComponentsT): TooltipRectsT {
+  return {
+    arrow: tooltip.arrow.getBoundingClientRect(),
+    container: tooltip.container.getBoundingClientRect(),
+  };
+}
+
+/**
+ * Calculates the document viewport size.
+ * @ignore
+ * @return {{x, y, width, height}}
+ */
+function calcViewportRect() {
+  const { scrollX, scrollY } = window;
+  const { documentElement: { clientHeight, clientWidth } } = document;
+  return {
+    left: scrollX,
+    right: scrollX + clientWidth,
+    top: scrollY,
+    bottom: scrollY + clientHeight,
+  };
+}
+
+/**
+ * Calculates tooltip and arrow positions for the placement just above
+ * the cursor.
+ * @ignore
+ * @param {number} x Cursor page-x position.
+ * @param {number} y Cursor page-y position.
+ * @param {object} tooltipRects Bounding client rectangles of tooltip parts.
+ * @param {object} tooltipRects.arrow
+ * @param {object} tooltipRects.container
+ * @return {object} Contains the following fields:
+ *  - {number} arrowX
+ *  - {number} arrowY
+ *  - {number} containerX
+ *  - {number} containerY
+ *  - {string} baseArrowStyle
+ */
+function calcPositionAboveXY(
+  x: number,
+  y: number,
+  tooltipRects: TooltipRectsT,
+) {
+  const { arrow, container } = tooltipRects;
+  return {
+    arrowX: 0.5 * (container.width - arrow.width),
+    arrowY: container.height,
+    containerX: x - container.width / 2,
+    containerY: y - container.height - arrow.height / 1.5,
+
+    // TODO: Instead of already setting the base style here, we should
+    // introduce a set of constants for arrow directions, which will help
+    // to do checks dependant on the arrow direction.
+    baseArrowStyle: ARROW_STYLE_DOWN,
+  };
+}
+
+/*
+const HIT = {
+  NONE: false,
+  LEFT: 'LEFT',
+  RIGHT: 'RIGHT',
+  TOP: 'TOP',
+  BOTTOM: 'BOTTOM',
+};
+*/
+
+/**
+ * Checks whether
+ * @param {object} pos
+ * @param {object} tooltipRects
+ * @param {object} viewportRect
+ * @return {HIT}
+ */
+/*
+function checkViewportFit(pos, tooltipRects, viewportRect) {
+  const { containerX, containerY } = pos;
+  if (containerX < viewportRect.left + 6) return HIT.LEFT;
+  if (containerX > viewportRect.right - 6) return HIT.RIGHT;
+  return HIT.NONE;
+}
+*/
+
+/**
+ * Shifts tooltip horizontally to fit into the viewport, while keeping
+ * the arrow pointed to the XY point.
+ * @param {number} x
+ * @param {number} y
+ * @param {object} pos
+ * @param {number} pageXOffset
+ * @param {number} pageXWidth
+ */
+/*
+function xPageFitCorrection(x, y, pos, pageXOffset, pageXWidth) {
+  if (pos.containerX < pageXOffset + 6) {
+    pos.containerX = pageXOffset + 6;
+    pos.arrowX = Math.max(6, pageX - containerX - arrowRect.width / 2);
+  } else {
+    const maxX = pageXOffset + docRect.width - containerRect.width - 6;
+    if (containerX > maxX) {
+      containerX = maxX;
+      arrowX = Math.min(
+        containerRect.width - 6,
+        pageX - containerX - arrowRect.width / 2,
+      );
+    }
+  }
+}
+*/
+
+/**
+ * Sets positions of tooltip components to point the tooltip to the specified
+ * page point.
+ * @ignore
+ * @param pageX
+ * @param pageY
+ * @param placement
+ * @param element DOM reference to the element wrapped by the tooltip.
+ * @param tooltip
+ * @param tooltip.arrow DOM reference to the tooltip arrow.
+ * @param tooltip.container DOM reference to the tooltip container.
+ */
+function setComponentPositions(
+  pageX: number,
+  pageY: number,
+  placement: PLACEMENTS | undefined,
+  element: HTMLElement | undefined,
+  tooltip: ComponentsT,
+) {
+  const tooltipRects = calcTooltipRects(tooltip);
+  const viewportRect = calcViewportRect();
+
+  /* Default container coords: tooltip at the top. */
+  const pos = calcPositionAboveXY(pageX, pageY, tooltipRects);
+
+  if (pos.containerX < viewportRect.left + 6) {
+    pos.containerX = viewportRect.left + 6;
+    pos.arrowX = Math.max(
+      6,
+      pageX - pos.containerX - tooltipRects.arrow.width / 2,
+    );
+  } else {
+    const maxX = viewportRect.right - 6 - tooltipRects.container.width;
+    if (pos.containerX > maxX) {
+      pos.containerX = maxX;
+      pos.arrowX = Math.min(
+        tooltipRects.container.width - 6,
+        pageX - pos.containerX - tooltipRects.arrow.width / 2,
+      );
+    }
+  }
+
+  /* If tooltip has not enough space on top - make it bottom tooltip. */
+  if (pos.containerY < viewportRect.top + 6) {
+    pos.containerY += tooltipRects.container.height
+      + 2 * tooltipRects.arrow.height;
+    pos.arrowY -= tooltipRects.container.height
+      + tooltipRects.arrow.height;
+    pos.baseArrowStyle = ARROW_STYLE_UP;
+  }
+
+  const containerStyle = `left:${pos.containerX}px;top:${pos.containerY}px`;
+  tooltip.container.setAttribute('style', containerStyle);
+
+  const arrowStyle = `${pos.baseArrowStyle};left:${pos.arrowX}px;top:${pos.arrowY}px`;
+  tooltip.arrow.setAttribute('style', arrowStyle);
+}
+
+/* The Tooltip component itself. */
+const Tooltip = forwardRef<unknown, {
+  children?: ReactNode;
+  theme: any;
+}>(({ children, theme }, ref) => {
+  // NOTE: The way it has to be implemented, for clean mounting and unmounting
+  // at the client side, the <Tooltip> is fully mounted into DOM in the next
+  // rendering cycles, and only then it can be correctly measured and positioned.
+  // Thus, when we create the <Tooltip> we have to record its target positioning
+  // details, and then apply them when it is created.
+
+  const { current: heap } = useRef<HeapT>({
+    lastElement: undefined,
+    lastPageX: 0,
+    lastPageY: 0,
+    lastPlacement: undefined,
+  });
+
+  const [components, setComponents] = useState<ComponentsT | null>(null);
+
+  const pointTo = (
+    pageX: number,
+    pageY: number,
+    placement: PLACEMENTS,
+    element: HTMLElement,
+  ) => {
+    heap.lastElement = element;
+    heap.lastPageX = pageX;
+    heap.lastPageY = pageY;
+    heap.lastPlacement = placement;
+
+    if (components) {
+      setComponentPositions(pageX, pageY, placement, element, components);
+    }
+  };
+  useImperativeHandle(ref, () => ({ pointTo }));
+
+  /* Inits and destroys tooltip components. */
+  useEffect(() => {
+    const x = createTooltipComponents(theme);
+    setComponents(x);
+    return () => {
+      document.body.removeChild(x.container);
+      setComponents(null);
+    };
+  }, [theme]);
+
+  useEffect(() => {
+    if (components) {
+      setComponentPositions(
+        heap.lastPageX,
+        heap.lastPageY,
+        heap.lastPlacement,
+        heap.lastElement,
+        components,
+      );
+    }
+  }, [
+    components,
+    // BEWARE: Careful about these dependencies - they are updated when mouse
+    // is moved over the tool-tipped element, thus potentially may cause
+    // unnecessary firing of this effect on each mouse event. It does not
+    // happen now just because the mouse movements themselves are not causing
+    // the component re-rendering, thus dependencies of this effect are not
+    // really re-evaluated.
+    heap.lastPageX,
+    heap.lastPageY,
+    heap.lastPlacement,
+    heap.lastElement,
+  ]);
+
+  return components ? createPortal(children, components.content) : null;
+});
+
+Tooltip.propTypes = {
+  children: PT.node,
+  theme: PT.shape({}).isRequired,
+};
+
+Tooltip.defaultProps = {
+  children: null,
+};
+
+export default Tooltip;

package/src/shared/components/WithTooltip/default-theme.scss

@@ -0,0 +1,36 @@
+@keyframes appearance {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+*,
+.ad.hoc,
+.context {
+  &.arrow {
+    border: 0.6em solid grey;
+    pointer-events: none;
+    position: absolute;
+    width: 0;
+    height: 0;
+  }
+
+  /*
+  &.content { }
+  */
+
+  &.container {
+    background: grey;
+    border-radius: 0.3em;
+    color: white;
+    display: inline-block;
+    padding: 0 0.3em;
+    position: absolute;
+    top: 0;
+    left: 0;
+    animation: appearance 0.6s;
+  }
+
+  &.wrapper {
+    display: inline-block;
+  }
+}

package/src/shared/components/WithTooltip/index.tsx

@@ -0,0 +1,204 @@
+/* global window */
+
+import PT from 'prop-types';
+import {
+  type ReactNode,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import Tooltip, { PLACEMENTS, type TooltipThemeT } from './Tooltip';
+
+import defaultTheme from './default-theme.scss';
+
+type PropsT = {
+  children?: ReactNode;
+  placement?: PLACEMENTS;
+  tip?: ReactNode;
+  theme: Theme & TooltipThemeT & {
+    wrapper?: string;
+  };
+};
+
+type TooltipRefT = {
+  pointTo: (
+    x: number,
+    y: number,
+    placement: PLACEMENTS,
+    wrapperRef: HTMLDivElement,
+  ) => void;
+};
+
+type HeapT = {
+  lastCursorX: number;
+  lastCursorY: number;
+  triggeredByTouch: boolean;
+  timerId?: NodeJS.Timeout;
+};
+
+/**
+ * Implements a simple to use and themeable tooltip component, _e.g._
+ * ```js
+ * <WithTooltip tip="This is example tooltip.">
+ *   <p>Hover to see the tooltip.</p>
+ * </WithTooltip>
+ * ```
+ * **Children:** Children are rendered in the place of `<WithTooltip>`,
+ * and when hovered the tooltip is shown. By default the wrapper itself is
+ * `<div>` block with `display: inline-block`.
+ * @param {object} props Component properties.
+ * @param {React.node} props.tip &ndash; Anything React is able to render,
+ * _e.g._ a tooltip text. This will be the tooltip content.
+ * @param {WithTooltipTheme} props.theme _Ad hoc_ theme.
+ */
+const Wrapper: React.FunctionComponent<PropsT> = ({
+  children,
+  placement,
+  tip,
+  theme,
+}) => {
+  const { current: heap } = useRef<HeapT>({
+    lastCursorX: 0,
+    lastCursorY: 0,
+    triggeredByTouch: false,
+    timerId: undefined,
+  });
+  const tooltipRef = useRef<TooltipRefT>();
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  const [showTooltip, setShowTooltip] = useState(false);
+
+  const updatePortalPosition = (cursorX: number, cursorY: number) => {
+    if (!showTooltip) {
+      heap.lastCursorX = cursorX;
+      heap.lastCursorY = cursorY;
+
+      // If tooltip was triggered by a touch, we delay its opening by a bit,
+      // to ensure it was not a touch-click - in the case of touch click we
+      // want to do the click, rather than show the tooltip, and the delay
+      // gives click handler a chance to abort the tooltip openning.
+      if (heap.triggeredByTouch) {
+        if (!heap.timerId) {
+          heap.timerId = setTimeout(() => {
+            heap.triggeredByTouch = false;
+            heap.timerId = undefined;
+            setShowTooltip(true);
+          }, 300);
+        }
+
+      // Otherwise we can just open the tooltip right away.
+      } else setShowTooltip(true);
+    } else {
+      const wrapperRect = wrapperRef.current!.getBoundingClientRect();
+      if (
+        cursorX < wrapperRect.left
+        || cursorX > wrapperRect.right
+        || cursorY < wrapperRect.top
+        || cursorY > wrapperRect.bottom
+      ) {
+        setShowTooltip(false);
+      } else if (tooltipRef.current) {
+        tooltipRef.current.pointTo(
+          cursorX + window.scrollX,
+          cursorY + window.scrollY,
+          placement!,
+          wrapperRef.current!,
+        );
+      }
+    }
+  };
+
+  useEffect(() => {
+    if (showTooltip && tip !== null) {
+      // This is necessary to ensure that even when a single mouse event
+      // arrives to a tool-tipped component, the tooltip is correctly positioned
+      // once opened (because similar call above does not have effect until
+      // the tooltip is fully mounted, and that is delayed to future rendering
+      // cycle due to the implementation).
+      if (tooltipRef.current) {
+        tooltipRef.current.pointTo(
+          heap.lastCursorX + window.scrollX,
+          heap.lastCursorY + window.scrollY,
+          placement!,
+          wrapperRef.current!,
+        );
+      }
+
+      const listener = () => setShowTooltip(false);
+      window.addEventListener('scroll', listener);
+      return () => window.removeEventListener('scroll', listener);
+    }
+    return undefined;
+  }, [
+    heap.lastCursorX,
+    heap.lastCursorY,
+    placement,
+    showTooltip,
+    tip,
+  ]);
+
+  return (
+    <div
+      className={theme.wrapper}
+      onMouseLeave={() => setShowTooltip(false)}
+      onMouseMove={(e) => updatePortalPosition(e.clientX, e.clientY)}
+      onClick={() => {
+        if (heap.timerId) {
+          clearTimeout(heap.timerId);
+          heap.timerId = undefined;
+          heap.triggeredByTouch = false;
+        }
+      }}
+      onTouchStart={() => {
+        heap.triggeredByTouch = true;
+      }}
+      ref={wrapperRef}
+      role="presentation"
+    >
+      {
+        showTooltip && tip !== null ? (
+          <Tooltip ref={tooltipRef} theme={theme}>{tip}</Tooltip>
+        ) : null
+      }
+      {children}
+    </div>
+  );
+};
+
+const ThemedWrapper = themed(
+  Wrapper,
+  'WithTooltip',
+  [
+    'appearance',
+    'arrow',
+    'container',
+    'content',
+    'wrapper',
+  ],
+  defaultTheme,
+);
+
+type ExportT = typeof ThemedWrapper & {
+  PLACEMENTS: typeof PLACEMENTS;
+};
+
+const e: ExportT = ThemedWrapper as ExportT;
+
+e.PLACEMENTS = PLACEMENTS;
+
+Wrapper.propTypes = {
+  children: PT.node,
+  placement: PT.oneOf(Object.values(PLACEMENTS)),
+  theme: ThemedWrapper.themeType.isRequired,
+  tip: PT.node,
+};
+
+Wrapper.defaultProps = {
+  children: null,
+  placement: PLACEMENTS.ABOVE_CURSOR,
+  tip: null,
+};
+
+export default e;

package/src/shared/components/YouTubeVideo/base.scss

@@ -0,0 +1,13 @@
+*,
+.context,
+.ad.hoc {
+  .container {
+    background: whitesmoke;
+  }
+
+  .video {
+    height: 100%;
+    position: relative;
+    width: 100%;
+  }
+}

package/src/shared/components/YouTubeVideo/index.tsx

@@ -0,0 +1,96 @@
+import PT from 'prop-types';
+import qs from 'qs';
+
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import ScalableRect from 'components/ScalableRect';
+import Throbber from 'components/Throbber';
+
+import baseTheme from './base.scss';
+import throbberTheme from './throbber.scss';
+
+type ComponentThemeT = Theme & {
+  container?: string;
+  video?: string;
+};
+
+type PropsT = {
+  autoplay?: boolean;
+  src: string;
+  theme: ComponentThemeT,
+  title?: string;
+};
+
+/**
+ * A component for embeding a YouTube video.
+ * @param [props] Component properties.
+ * @param [props.autoplay] If `true` the video will start to play
+ * automatically once loaded.
+ * @param [props.src] URL of the video to play. Can be in any of
+ * the following formats, and keeps any additional query parameters understood
+ * by the YouTube IFrame player:
+ * - `https://www.youtube.com/watch?v=NdF6Rmt6Ado`
+ * - `https://youtu.be/NdF6Rmt6Ado`
+ * - `https://www.youtube.com/embed/NdF6Rmt6Ado`
+ * @param [props.theme] _Ad hoc_ theme.
+ * @param [props.title] The `title` attribute to add to the player
+ * IFrame.
+ */
+const YouTubeVideo: React.FunctionComponent<PropsT> = ({
+  autoplay,
+  src,
+  theme,
+  title,
+}) => {
+  const srcParts = src.split('?');
+  let url = srcParts[0];
+  const queryString = srcParts[1];
+  const query = queryString ? qs.parse(queryString) : {};
+
+  const videoId = query.v || url.match(/\/([a-zA-Z0-9-_]*)$/)?.[1];
+  url = `https://www.youtube.com/embed/${videoId}`;
+
+  delete query.v;
+  query.autoplay = autoplay ? '1' : '0';
+  url += `?${qs.stringify(query)}`;
+
+  // TODO: https://developers.google.com/youtube/player_parameters
+  // More query parameters can be exposed via the component props.
+
+  return (
+    <ScalableRect className={theme.container} ratio="16:9">
+      <Throbber theme={throbberTheme} />
+      <iframe
+        allow="autoplay"
+        allowFullScreen
+        className={theme.video}
+        src={url}
+        title={title}
+      />
+    </ScalableRect>
+  );
+};
+
+const ThemedYouTubeVideo = themed(
+  YouTubeVideo,
+  'YouTubeVideo',
+  [
+    'container',
+    'video',
+  ],
+  baseTheme,
+);
+
+YouTubeVideo.propTypes = {
+  autoplay: PT.bool,
+  src: PT.string.isRequired,
+  theme: ThemedYouTubeVideo.themeType.isRequired,
+  title: PT.string,
+};
+
+YouTubeVideo.defaultProps = {
+  autoplay: false,
+  title: '',
+};
+
+export default ThemedYouTubeVideo;

package/src/shared/components/YouTubeVideo/throbber.scss

@@ -0,0 +1,11 @@
+*,
+.context,
+.ad.hoc {
+  .container {
+    position: absolute;
+    text-align: center;
+    top: 40%;
+    transform: translateY(50%);
+    width: 100%;
+  }
+}