@envive-ai/react-hooks 0.1.0

package/src/hooks/useElementObserver.ts

@@ -0,0 +1,245 @@
+import { ReactElement, useEffect, useRef, useState } from 'react';
+import { DOMObserver } from 'src/application/utils/domObserver';
+import { ElementObserver } from 'src/application/utils/elementObserver';
+import { MouseEventTypes } from 'src/application/utils/mouseEventTypes';
+import { NodeSelector } from 'src/application/utils/nodeSelector';
+
+export interface ElementObserverUtility {
+  onChange: (fn: (el: HTMLElement | null) => void) => void;
+  onAdd: (fn: (el: HTMLElement | null) => void) => void;
+  onRemove: (fn: (el: HTMLElement | null) => void) => void;
+  onClassChange: (fn: (classes?: DOMTokenList) => void) => void;
+  onClassAdded: (className: string, fn: () => void) => void;
+  onClassRemoved: (className: string, fn: () => void) => void;
+  onAddChild: (fn: (nodes?: DOMTokenList) => void) => void;
+  onRemoveChild: (fn: (nodes?: DOMTokenList) => void) => void;
+  onEvent: <K extends keyof HTMLElementEventMap>(
+    event: K,
+    fn: EventListenerOrEventListenerObject,
+  ) => void;
+  blockRendering: () => void;
+  unblockRendering: () => void;
+  exists: () => boolean;
+  isRendered: () => boolean;
+  render: (fn: () => ReactElement) => ReactElement | undefined;
+  fire: (event: MouseEventTypes) => void;
+  show: () => void;
+  hide: () => void;
+  applyStyle: (styles: React.CSSProperties) => void;
+  targetNode: HTMLElement | null;
+}
+
+/*
+ * This hook enables the connection between a `MutationObserver` and a React.js component.
+ * It abstracts all the necessary validations and implementations to modify HTML elements,
+ * monitor their changes, and interact with them. The only required input is the element's selector.
+ *
+ * How to use it:
+ *
+ * Let's assume we want to interact with the following element:
+ * `<div id="awesome-content"><content /></div>`
+ *
+ * To hook into that element, simply do the following:
+ * `const element = useElementObserver(SelectorFactory.id("awesome-content"))`
+ *
+ * With the `ElementObserver` instance in hand, we can interact with the HTML element without having
+ * to manage its presence in the DOM. The `onAdd` and `onRemove` functions can be used to determine
+ * whether the element is present in the DOM or not, and to ensure interaction occurs only when necessary.
+ *
+ * @param selector
+ * @returns
+ */
+export const useElementObserver = (selector: NodeSelector): ElementObserverUtility => {
+  const INITIAL_RENDER_STATE = true;
+  const eoRef = useRef<ElementObserver>(DOMObserver.add(selector));
+  const [renderBlocked, setRenderBlocked] = useState(INITIAL_RENDER_STATE);
+
+  /**
+   * Fired every time the HTML element changes.
+   *
+   * @param fn
+   */
+  const onChange = (fn: (el: HTMLElement | null) => void) => {
+    eoRef.current?.registerOnChange(fn);
+  };
+
+  /**
+   * Fired when the HTML element is added to the DOM.
+   *
+   * @param fn
+   */
+  const onAdd = (fn: (el: HTMLElement | null) => void) => {
+    eoRef.current?.registerOnAdd(fn);
+  };
+
+  /**
+   * Fired when the HTML element is removed from the DOM.
+   *
+   * @param fn
+   */
+  const onRemove = (fn: (el: HTMLElement | null) => void) => {
+    eoRef.current?.registerOnRemove(fn);
+  };
+
+  /**
+   * Fired when the class of the HTML element changes.
+   *
+   * @param fn
+   */
+  const onClassChange = (fn: (classes?: DOMTokenList) => void) => {
+    eoRef.current?.registerOnclassChange(fn);
+  };
+
+  /**
+   * Fired when a class is added to the HTML element.
+   *
+   * @param className
+   * @param fn
+   */
+  const onClassAdded = (className: string, fn: () => void) => {
+    eoRef.current?.registerOnClassAdded(className, fn);
+  };
+
+  /**
+   * Fired when a class is removed from the HTML element.
+   *
+   * @param className
+   * @param fn
+   */
+  const onClassRemoved = (className: string, fn: () => void) => {
+    eoRef.current?.registerOnClassRemoved(className, fn);
+  };
+
+  /**
+   * Fired when a child element is added to the HTML element.
+   *
+   * @param fn
+   */
+  const onAddChild = (fn: (nodes?: DOMTokenList) => void) => {
+    eoRef.current?.registerOnAddChild(fn);
+  };
+
+  /**
+   * Fired when a child element is removed from the HTML element.
+   *
+   * @param fn
+   */
+  const onRemoveChild = (fn: (nodes?: DOMTokenList) => void) => {
+    eoRef.current?.registerOnRemoveChild(fn);
+  };
+
+  /**
+   * Allows hooking event listeners to the HTML element, such as `focus`, `blur`, etc.
+   *
+   * @param event
+   * @param fn
+   */
+  const onEvent = <K extends keyof HTMLElementEventMap>(
+    event: K,
+    fn: EventListenerOrEventListenerObject,
+  ) => {
+    eoRef.current.registerEvent(event, fn);
+  };
+
+  /**
+   * Useful when rendering a React.js component inside the HTML element.
+   *
+   * @param fn
+   * @returns
+   */
+  const render = (fn: () => ReactElement) => {
+    if (!renderBlocked) {
+      return eoRef.current.render(fn);
+    }
+  };
+
+  /**
+   * Checks if the element exists in the DOM.
+   *
+   * @returns
+   */
+  const exists = () => !!eoRef.current.getNode();
+
+  /**
+   * Checks if rendering is unblocked.
+   *
+   * @returns
+   */
+  const isRendered = () => !renderBlocked;
+
+  /**
+   * Triggers an event for the HTML element.
+   *
+   * @param event
+   */
+  const fire = (event: MouseEventTypes) => {
+    eoRef.current.fire(event);
+  };
+
+  /**
+   * Shows the HTML element.
+   *
+   * @returns
+   */
+  const show = () => eoRef.current.show();
+
+  /**
+   * Hides the HTML element.
+   *
+   * @returns
+   */
+  const hide = () => eoRef.current.hide();
+
+  /**
+   * Blocks the rendering of elements.
+   *
+   * @returns
+   */
+  const blockRendering = () => setRenderBlocked(true);
+
+  /**
+   * Unblocks the rendering of elements.
+   *
+   * @returns
+   */
+  const unblockRendering = () => setRenderBlocked(false);
+
+  /**
+   * Applies CSS styles to the HTML element.
+   *
+   * @param styles
+   */
+  const applyStyle = (styles: React.CSSProperties) => {
+    const node = eoRef?.current?.getNode();
+    node && Object.assign(node.style, styles);
+  };
+
+  useEffect(() => {
+    eoRef.current.init();
+    eoRef.current.registerOnReset(() => setRenderBlocked(INITIAL_RENDER_STATE));
+    DOMObserver.observe();
+    return () => DOMObserver.remove(selector);
+  }, [selector.getPattern()]);
+
+  return {
+    targetNode: eoRef.current.getNode(),
+    onChange,
+    onAdd,
+    onRemove,
+    onClassChange,
+    onClassAdded,
+    onClassRemoved,
+    onAddChild,
+    onRemoveChild,
+    onEvent,
+    blockRendering,
+    unblockRendering,
+    exists,
+    isRendered,
+    render,
+    fire,
+    show,
+    hide,
+    applyStyle,
+  } satisfies ElementObserverUtility;
+};

package/src/hooks/useFileUpload.ts

@@ -0,0 +1,61 @@
+import { AttachmentRequest } from '@spiffy-ai/commerce-api-client';
+import { useAtom, useAtomValue } from 'jotai';
+import { useRef, useState } from 'react';
+import { customerServiceAttachment } from 'src/atoms';
+import { orgCustomerServiceService } from 'src/atoms/org/orgUIConfig';
+
+export const useFileUpload = () => {
+  const fileInputRef = useRef(null);
+  const [attachment, setAttachment] = useAtom(customerServiceAttachment);
+  const customerServiceImpl = useAtomValue(orgCustomerServiceService);
+  const [error, setError] = useState('');
+
+  const isValidFile = (file?: File) => {
+    const maxSize = customerServiceImpl.maxfileUploadSize;
+    if (maxSize && (file?.size || 0) > maxSize) {
+      const strFileSize = `${(maxSize / 1000000).toFixed(1)}MB`;
+      setError(`Exceeded file size of ${strFileSize}`);
+      return false;
+    }
+    return true;
+  };
+
+  const handleFileSelect = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event?.target?.files?.[0];
+
+    if (file && isValidFile(file)) {
+      const reader = new FileReader();
+      reader.readAsDataURL(file);
+      reader.onloadend = () => {
+        const base64 = reader?.result as string;
+        setAttachment({
+          base64_content: base64,
+          content_type: file.type,
+          file_name: file.name,
+        });
+      };
+    }
+  };
+
+  const prepareAttachment = (): AttachmentRequest | undefined => {
+    if (attachment) {
+      return {
+        ...attachment,
+        base64_content: attachment?.base64_content.split(',')[1],
+      } as AttachmentRequest;
+    }
+  };
+
+  const handleFileRemove = () => {
+    setAttachment(undefined);
+  };
+
+  return {
+    error,
+    fileInputRef,
+    attachment,
+    handleFileSelect,
+    handleFileRemove,
+    prepareAttachment,
+  };
+};

package/src/hooks/useGrabAndScroll.ts

@@ -0,0 +1,133 @@
+import { useRef, useState } from "react";
+
+type ArrowPosition = 'lt' | 'ct' | 'rt'
+
+interface AnimationProps {
+    element: HTMLElement
+    targetScroll: number 
+    duration: number 
+    direction?: 'lt' | 'rt' 
+    multiply?: number 
+    offset?: number
+    callback?: (position: ArrowPosition) => void
+}
+
+const animateHorizontalScroll = ({ element, duration, targetScroll, multiply = 1, direction, callback, offset = 0 }: AnimationProps) => {
+    const start = element.scrollLeft
+    const distance = (targetScroll - start) * multiply;
+    const startTime = performance.now();
+
+    function easeOutSine(x: number): number {
+      return Math.sin((x * Math.PI) / 2);
+    }
+
+    function scrollStep(currentTime: number): void {
+        const timeElapsed = currentTime - startTime;
+        const progress = Math.min(timeElapsed / duration, 1);
+        const easing = easeOutSine(progress);
+        const step = start + (distance * easing)
+        const canScroll = (direction === 'rt' ? (element.scrollLeft < step) : (element.scrollLeft > step)) || !direction
+        
+        if (step > 0 && canScroll) {
+          element.scrollTo(step, 0)
+        }
+
+        if (timeElapsed < duration) {
+            requestAnimationFrame(scrollStep);
+        } 
+
+        // End of scrolling container
+        else if ((element.scrollLeft + offset) === element.scrollWidth) {
+            callback?.('rt')
+        } 
+        // Begin of scrolling container
+        else if (element.scrollLeft <= 1) {
+            callback?.('lt')
+        }
+        // Somewhere in the middle
+        else {
+            callback?.('ct')
+        }
+
+    }
+
+    requestAnimationFrame(scrollStep);
+}
+
+
+export const useGrabAndScroll = (enabled: boolean, chunkWidth: number, speed: number = 400, offset: number = 0) => {
+    const containerRef = useRef<HTMLDivElement>(null)
+    const [ leftArrow, setLeftArrow ] = useState(false)
+    const [ rightArrow, setRightArrow ] = useState(true)
+
+    const handleArrows = (position: ArrowPosition) => {
+        switch (position) {
+            case 'lt':
+                setLeftArrow(false)
+                setRightArrow(true)
+                break
+
+            case 'rt':
+                setLeftArrow(true)
+                setRightArrow(false)
+                break
+
+            default:
+                setLeftArrow(true)
+                setRightArrow(true)
+        }
+    }
+
+    const animationTrigger = () => {
+        if (enabled && containerRef.current) {
+            const dist = (containerRef?.current?.scrollLeft || 0) / chunkWidth
+            const targetScroll = chunkWidth * (Math.floor(dist) + (dist % 1 > 0.5 ? 1 : 0))
+            animateHorizontalScroll({
+                element: containerRef.current, 
+                targetScroll, 
+                duration: speed,
+                offset,
+                callback: handleArrows
+            })
+        }
+    }
+
+    const onNext = (cardsToSlide: number) => {
+        if (containerRef.current) {
+            const targetScroll = containerRef.current.scrollLeft + chunkWidth
+            animateHorizontalScroll({
+                element: containerRef.current, 
+                targetScroll, 
+                duration: speed, 
+                direction: 'rt', 
+                multiply: cardsToSlide,
+                offset,
+                callback: handleArrows
+            })
+        }
+    }
+    
+    const onPrevious = (cardsToSlide: number) => {
+        if (containerRef.current) {
+            const targetScroll = containerRef.current.scrollLeft - chunkWidth
+            animateHorizontalScroll({
+                element: containerRef.current, 
+                targetScroll, 
+                duration: speed, 
+                direction: 'lt', 
+                multiply: cardsToSlide,
+                offset,
+                callback: handleArrows
+            })
+        }
+    }
+
+    return {
+        containerRef,
+        leftArrow,
+        rightArrow,
+        animationTrigger,
+        onNext,
+        onPrevious
+    }
+}

package/src/hooks/useHideElements.ts

@@ -0,0 +1,82 @@
+import Logger from 'src/application/logging/logger';
+import { SelectorFactory } from 'src/application/utils/nodeSelector';
+import { useEffect, useRef, useState } from 'react';
+import { useAtomValue } from 'jotai';
+import { SpiffyEventName } from 'src/application/models/events';
+import { ElementObserver } from 'src/application/utils/elementObserver';
+import { DOMObserver } from 'src/application/utils/domObserver';
+import { orgUIConfigAtom } from 'src/atoms/org/orgUIConfig';
+
+/**
+ * This hook hides/shows elements that could overlap with the chat when the chat is opened/closed.
+ */
+export const useHideElements = () => {
+  const orgUIConfig = useAtomValue(orgUIConfigAtom);
+  const [hasRegisteredEventListeners, setHasRegisteredEventListeners] = useState(false);
+  const elementObservers = useRef<ElementObserver[]>([]);
+
+  const hideElements = (elements: ElementObserver[]) => {
+    elements.forEach((element) => {
+      element.hide();
+    });
+  };
+
+  const showElements = (elements: ElementObserver[]) => {
+    elements.forEach((element) => {
+      element.show();
+    });
+  };
+
+  useEffect(() => {
+    elementObservers.current = [];
+    orgUIConfig.hiddenElementSelectors?.forEach((selector) => {
+      elementObservers.current.push(DOMObserver.add(SelectorFactory.query(selector)));
+    });
+    // since we're not using useElementObserver, we need to manually start the observer
+    elementObservers.current.forEach((element) => {
+      element.init();
+    });
+    DOMObserver.observe();
+
+    return () => {
+      elementObservers.current.forEach((element) => {
+        element.destroy();
+      });
+      elementObservers.current = [];
+    };
+  }, [orgUIConfig.hiddenElementSelectors]);
+
+  useEffect(() => {
+    if (elementObservers.current.length > 0 && !hasRegisteredEventListeners) {
+      Logger.logDebug(
+        `Registering ${SpiffyEventName.WidgetOpen} event for ${elementObservers.current.length} elements`,
+      );
+      window.addEventListener(SpiffyEventName.WidgetOpen, () =>
+        hideElements(elementObservers.current),
+      );
+
+      Logger.logDebug(
+        `Registering ${SpiffyEventName.WidgetClose} event for ${elementObservers.current.length} elements`,
+      );
+      window.addEventListener(SpiffyEventName.WidgetClose, () =>
+        showElements(elementObservers.current),
+      );
+
+      setHasRegisteredEventListeners(true);
+    }
+
+    return () => {
+      if (elementObservers.current.length > 0 && hasRegisteredEventListeners) {
+        window.removeEventListener(SpiffyEventName.WidgetOpen, () =>
+          hideElements(elementObservers.current),
+        );
+
+        window.removeEventListener(SpiffyEventName.WidgetClose, () =>
+          showElements(elementObservers.current),
+        );
+
+        setHasRegisteredEventListeners(false);
+      }
+    };
+  }, [hasRegisteredEventListeners]);
+};

package/src/hooks/useHorizontalScrollAnimation.ts

@@ -0,0 +1,115 @@
+import { useEffect, RefObject, useRef } from 'react';
+import { useReducedMotionWithOverride } from 'src/hooks/useReducedMotionWithOverride';
+
+// IMPORTANT: All refs passed to this hook must be mutable (not Readonly)
+interface UseHorizontalScrollAnimationOptions {
+  scrollContainerRef: RefObject<HTMLDivElement>;
+  animationSpeed?: 'standard' | 'slow' | 'none';
+}
+
+// When using this hook, ensure that scrouuContainerRef is not undefined. It is allowed to
+// prevent issued elsewhere in the codebase, but it should be dealt with whenever you use this hook.
+export function useHorizontalScrollAnimation({
+  scrollContainerRef,
+  animationSpeed = 'standard',
+}: UseHorizontalScrollAnimationOptions): void {
+  const reducedMotion = useReducedMotionWithOverride();
+  const resumeTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const scrollAnimationRef = useRef<number | null>(null);
+
+  const pauseOnHover = true; // This is unlikely to need to be configurable but I'm throwing it up here just in case.
+
+  // Animation constants: time-based
+  let PIXELS_PER_SECOND = 40;
+  switch (animationSpeed) {
+    case 'standard':
+      PIXELS_PER_SECOND = 40;
+      break;
+    case 'slow':
+      PIXELS_PER_SECOND = 25;
+      break;
+    case 'none':
+      PIXELS_PER_SECOND = 0;
+      break;
+    default:
+      PIXELS_PER_SECOND = 40;
+  }
+  const RESUME_DELAY_MS = 2000;
+  const isAnimated = animationSpeed !== 'none';
+
+  useEffect(() => {
+    if (!isAnimated || reducedMotion || !scrollContainerRef) return;
+
+    const container = scrollContainerRef.current;
+    if (!container) return;
+    if (container.scrollWidth <= container.clientWidth) return;
+
+    let isPaused = false;
+    let lastTimestamp: number | null = null;
+    let accumulatedScroll = 0; // Accumulate fractional pixels
+
+    const step = (timestamp: number) => {
+      if (lastTimestamp === null) lastTimestamp = timestamp;
+      if (!isPaused) {
+        const delta = timestamp - lastTimestamp;
+        lastTimestamp = timestamp;
+
+        // Accumulate the scroll amount (including fractional pixels)
+        accumulatedScroll += PIXELS_PER_SECOND * (delta / 1000);
+
+        // Only apply whole pixel movements
+        const pixelsToScroll = Math.floor(accumulatedScroll);
+        if (pixelsToScroll > 0) {
+          container.scrollLeft += pixelsToScroll;
+          accumulatedScroll -= pixelsToScroll; // Keep the fractional remainder
+
+          if (container.scrollLeft >= container.scrollWidth - container.clientWidth) {
+            container.scrollLeft = 0; // Reset scroll to create a looping effect
+            accumulatedScroll = 0; // Reset accumulated scroll when looping
+          }
+        }
+      }
+      scrollAnimationRef.current = requestAnimationFrame(step);
+    };
+
+    // Start animation
+    scrollAnimationRef.current = requestAnimationFrame(step);
+
+    // Pause/resume logic
+    const pauseAnimation = () => {
+      isPaused = true;
+      if (resumeTimeoutRef.current) {
+        clearTimeout(resumeTimeoutRef.current);
+        resumeTimeoutRef.current = null;
+      }
+    };
+    const scheduleResumeAnimation = () => {
+      resumeTimeoutRef.current = setTimeout(() => {
+        isPaused = false;
+        lastTimestamp = null; // Reset timestamp so delta is correct after pause
+      }, RESUME_DELAY_MS);
+    };
+
+    if (pauseOnHover) {
+      container.addEventListener('mouseenter', pauseAnimation);
+      container.addEventListener('mouseleave', scheduleResumeAnimation);
+      container.addEventListener('touchstart', pauseAnimation);
+      container.addEventListener('touchend', scheduleResumeAnimation);
+    }
+
+    return () => {
+      if (scrollAnimationRef.current) {
+        cancelAnimationFrame(scrollAnimationRef.current);
+      }
+      if (pauseOnHover) {
+        container.removeEventListener('mouseenter', pauseAnimation);
+        container.removeEventListener('mouseleave', scheduleResumeAnimation);
+        container.removeEventListener('touchstart', pauseAnimation);
+        container.removeEventListener('touchend', scheduleResumeAnimation);
+      }
+      if (resumeTimeoutRef.current) {
+        clearTimeout(resumeTimeoutRef.current);
+      }
+    };
+  }, [isAnimated, reducedMotion, PIXELS_PER_SECOND, pauseOnHover, scrollContainerRef]);
+}

package/src/hooks/useImageResolver.ts

@@ -0,0 +1,51 @@
+import { useAtomValue } from 'jotai';
+import { OrgShortName } from 'src/application/models';
+import { orgUIConfigAtom } from 'src/atoms/org/orgUIConfig';
+
+abstract class ImageResolver {
+  abstract resolve(url: string, size: number): string;
+}
+
+class MerchantImageResolver {
+  private static imageResolverMap = new Map<string, ImageResolver>();
+
+  private static loadMapping() {
+    if (this.imageResolverMap.size === 0) {
+      this.imageResolverMap.set(OrgShortName.Spanx, new ShopifyImageResolver());
+      this.imageResolverMap.set(OrgShortName.SpanxStaging, new ShopifyImageResolver());
+      this.imageResolverMap.set(OrgShortName.UniqueVintage, new ShopifyImageResolver());
+    }
+    return this.imageResolverMap;
+  }
+
+  static get(name: string) {
+    return this.loadMapping().get(name);
+  }
+}
+
+class ShopifyImageResolver extends ImageResolver {
+  resolve(url: string, size: number): string {
+    const pattern = /_\d+x\.jpg/;
+    const urlHasPrefix = pattern.test(url);
+    const newSizePrefix = `_${size}x.jpg`;
+    if (urlHasPrefix) {
+      return url.replace(pattern, newSizePrefix);
+    }
+    return url.replace('.jpg', newSizePrefix);
+  }
+}
+
+export const useImageResolver = () => {
+  const orgUIConfig = useAtomValue(orgUIConfigAtom);
+  const resolve = (image?: string, size?: number) => {
+    if (image && size) {
+      const newImagePath = MerchantImageResolver.get(orgUIConfig.shortName)?.resolve(image, size);
+      return newImagePath || image;
+    }
+    return image;
+  };
+
+  return {
+    resolve,
+  };
+};