app-tutor-ai-consumer 1.4.0 → 1.5.0

package/src/lib/hooks/use-intersection-observer-reverse-scroll/use-intersection-observer-reverse-scroll.tsx

@@ -0,0 +1,147 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { useThrottle } from '../use-throttle'
+
+export type UseIntersectionObserverReverseScrollProps = {
+  hasMore: boolean
+  asyncCallback: () => Promise<void>
+  onScroll?: () => void
+  isLoading?: boolean
+  threshold?: number
+  rootMargin?: string
+  enabled?: boolean
+}
+
+function useIntersectionObserverReverseScroll({
+  hasMore,
+  asyncCallback,
+  onScroll,
+  enabled = true,
+  isLoading = false,
+  rootMargin = '100px 0px',
+  threshold = 0.5
+}: UseIntersectionObserverReverseScrollProps) {
+  const [heightBeforeRender, setHeightBeforeRender] = useState(0)
+  const [shouldRestorePosition, setShouldRestorePosition] = useState(false)
+  const [hasUserScrolled, setHasUserScrolled] = useState(false)
+  const [isInitialLoad, setIsInitialLoad] = useState(true)
+
+  const scrollerRef = useRef<HTMLDivElement>(null)
+  const intersectionTargetRef = useRef<HTMLDivElement>(null)
+  const observerRef = useRef<IntersectionObserver | null>(null)
+
+  const { throttledCallback: throttledHandleScroll } = useThrottle({
+    callback: () => {
+      onScroll?.()
+    },
+    delay: 50
+  })
+
+  const handleScroll = useCallback(() => {
+    const { current: scroller } = scrollerRef
+
+    if (!scroller) return
+
+    if (!hasUserScrolled) setHasUserScrolled(true)
+
+    if (!isInitialLoad) setIsInitialLoad(true)
+
+    throttledHandleScroll()
+  }, [hasUserScrolled, isInitialLoad, throttledHandleScroll])
+
+  const handleIntersection = useCallback(
+    async (entries: IntersectionObserverEntry[]) => {
+      const [entry] = entries
+      const { current: scroller } = scrollerRef
+
+      if (!enabled || !scroller || !isInitialLoad || !hasUserScrolled || isLoading || !hasMore)
+        return
+
+      if (entry?.isIntersecting) {
+        setHeightBeforeRender(scroller.scrollHeight)
+        setShouldRestorePosition(true)
+        await asyncCallback()
+      }
+    },
+    [enabled, hasMore, hasUserScrolled, isInitialLoad, isLoading, asyncCallback]
+  )
+
+  const scrollToBottom = useCallback((smooth = false) => {
+    const { current: scroller } = scrollerRef
+
+    if (!scroller) return
+
+    scroller.scrollTo({
+      top: scroller.scrollHeight,
+      behavior: smooth ? 'smooth' : 'auto'
+    })
+  }, [])
+
+  const resetScrollState = useCallback(() => {
+    setHasUserScrolled(false)
+    setIsInitialLoad(true)
+    setShouldRestorePosition(false)
+    setHeightBeforeRender(0)
+  }, [])
+
+  useEffect(() => {
+    const { current: scroller } = scrollerRef
+    const { current: intersectionTarget } = intersectionTargetRef
+
+    if (!intersectionTarget || !scroller) return
+
+    observerRef.current = new IntersectionObserver((entries) => void handleIntersection(entries), {
+      root: scroller,
+      rootMargin,
+      threshold
+    })
+
+    observerRef.current.observe(intersectionTarget)
+
+    return () => {
+      observerRef.current?.disconnect()
+    }
+  }, [handleIntersection, rootMargin, threshold])
+
+  useEffect(() => {
+    const { current: scroller } = scrollerRef
+    const controller = new AbortController()
+
+    if (!scroller) return
+
+    scroller.addEventListener('scroll', handleScroll, { passive: true, signal: controller.signal })
+
+    return () => {
+      controller.abort()
+    }
+  }, [handleScroll])
+
+  useEffect(() => {
+    const { current: scroller } = scrollerRef
+
+    if (!shouldRestorePosition || isLoading || !scroller) return
+
+    const frameId = requestAnimationFrame(() => {
+      const newScrollTop = scroller.scrollHeight - heightBeforeRender
+
+      scroller.scrollTop = newScrollTop
+      setShouldRestorePosition(false)
+      setHeightBeforeRender(0)
+    })
+
+    return () => {
+      cancelAnimationFrame(frameId)
+    }
+  }, [heightBeforeRender, isLoading, shouldRestorePosition])
+
+  return {
+    scrollerRef,
+    intersectionTargetRef,
+    scrollToBottom,
+    resetScrollState,
+    hasUserScrolled,
+    isInitialLoad
+  }
+}
+
+export default useIntersectionObserverReverseScroll

package/src/lib/hooks/use-ref-client-height/index.ts

@@ -0,0 +1,2 @@
+export * from './use-ref-client-height'
+export { default as useRefClientHeight } from './use-ref-client-height'

package/src/lib/hooks/use-ref-client-height/use-ref-client-height.tsx

@@ -0,0 +1,38 @@
+import { type RefObject, useEffect, useState } from 'react'
+
+import { useThrottle } from '@/src/lib/hooks'
+
+function useRefClientHeight<T extends HTMLElement>(
+  refElement: RefObject<T | null>,
+  defaultHeight = '100vh'
+) {
+  const [clientHeight, setClientHeight] = useState(defaultHeight)
+
+  const { throttledCallback: resizeHandler } = useThrottle({
+    callback: () => {
+      if (!refElement?.current?.clientHeight) return
+
+      setClientHeight(`${refElement?.current.clientHeight}px`)
+    },
+    delay: 650
+  })
+
+  useEffect(resizeHandler, [resizeHandler])
+
+  useEffect(() => {
+    if (!refElement?.current?.clientHeight) return
+
+    const abortController = new AbortController()
+    const signal = abortController.signal
+
+    window.addEventListener('resize', resizeHandler, { signal })
+
+    return () => {
+      abortController.abort()
+    }
+  }, [refElement, resizeHandler])
+
+  return clientHeight
+}
+
+export default useRefClientHeight

package/src/lib/hooks/use-scroll-to-ref/index.ts

@@ -0,0 +1,2 @@
+export * from './use-scroll-to-ref'
+export { default as useScrollToRef } from './use-scroll-to-ref'

package/src/lib/hooks/use-scroll-to-ref/use-scroll-to-ref.tsx

@@ -0,0 +1,14 @@
+import { useCallback, useRef } from 'react'
+
+function useScrollToRef<R extends HTMLElement>() {
+  const ref = useRef<R>(null)
+
+  const scrollToRef = useCallback(() => {
+    const { current: element } = ref
+    element?.scrollIntoView({ behavior: 'smooth', block: 'end' })
+  }, [])
+
+  return { scrollTargetRef: ref, scrollToRef }
+}
+
+export default useScrollToRef

package/src/lib/hooks/use-throttle/index.ts

@@ -0,0 +1,3 @@
+export * from './types'
+export * from './use-throttle'
+export { default as useThrottle } from './use-throttle'

package/src/lib/hooks/use-throttle/types.ts

@@ -0,0 +1,13 @@
+export type UseThrottleProps<T extends (...args: unknown[]) => unknown> = {
+  callback: T
+  delay: number
+}
+
+export interface ThrottleControls {
+  cancel: () => void
+  pending: () => boolean
+}
+
+export type ThrottledFunction<T extends (...args: unknown[]) => unknown> = {
+  throttledCallback: T
+} & ThrottleControls

package/src/lib/hooks/use-throttle/use-throttle.spec.tsx

@@ -0,0 +1,296 @@
+import type { Mock } from 'vitest'
+
+import { act, renderHook } from '@/src/config/tests'
+
+import type { UseThrottleProps } from './types'
+import useThrottle from './use-throttle'
+
+describe('useThrottle', () => {
+  const mockCallback = vi.fn()
+  const mockDelay = 1000
+
+  const createHook = (
+    { callback, delay }: UseThrottleProps<ReturnType<typeof vi.fn>> = {
+      callback: mockCallback,
+      delay: mockDelay
+    }
+  ) =>
+    renderHook(() =>
+      useThrottle({
+        callback,
+        delay
+      })
+    )
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers()
+    vi.useRealTimers()
+    vi.clearAllMocks()
+  })
+
+  it('should execute callback immediately on first call', () => {
+    const { result } = createHook()
+
+    result.current.throttledCallback('test')
+
+    expect(mockCallback).toHaveBeenCalledTimes(1)
+    expect(mockCallback).toHaveBeenCalledWith('test')
+  })
+
+  it('should throttle subsequent calls within delay period', () => {
+    const { result } = createHook()
+
+    result.current.throttledCallback('call1')
+    result.current.throttledCallback('call2')
+    result.current.throttledCallback('call3')
+
+    expect(mockCallback).toHaveBeenCalledTimes(1)
+    expect(mockCallback).toHaveBeenCalledWith('call1')
+
+    act(() => {
+      vi.advanceTimersByTime(1000)
+    })
+
+    expect(mockCallback).toHaveBeenCalledTimes(2)
+    expect(mockCallback).toHaveBeenLastCalledWith('call3')
+  })
+
+  it('should allow execution after delay period has passed', () => {
+    const { result } = createHook()
+
+    result.current.throttledCallback('call1')
+
+    act(() => {
+      vi.advanceTimersByTime(1000)
+    })
+
+    result.current.throttledCallback('call2')
+
+    expect(mockCallback).toHaveBeenCalledTimes(2)
+    expect(mockCallback).toHaveBeenNthCalledWith(1, 'call1')
+    expect(mockCallback).toHaveBeenNthCalledWith(2, 'call2')
+  })
+
+  it('should handle multiple arguments correctly', () => {
+    const multiArgCallback: Mock<(a: string, b: number, c: boolean) => void> = vi.fn()
+
+    const { result } = createHook({ callback: multiArgCallback, delay: mockDelay })
+
+    result.current.throttledCallback('hello', 42, true)
+
+    expect(multiArgCallback).toHaveBeenCalledWith('hello', 42, true)
+  })
+
+  describe('cancel()', () => {
+    it('should cancel pending execution', () => {
+      const { result } = createHook()
+
+      act(() => {
+        result.current.throttledCallback('call1')
+      })
+
+      act(() => {
+        result.current.throttledCallback('call2')
+      })
+
+      expect(mockCallback).toHaveBeenCalledTimes(1)
+      expect(result.current.pending()).toBe(true)
+
+      act(() => {
+        result.current.cancel()
+      })
+
+      expect(result.current.pending()).toBe(false)
+
+      act(() => {
+        vi.advanceTimersByTime(1000)
+      })
+
+      expect(mockCallback).toHaveBeenCalledTimes(1)
+    })
+
+    it('should be safe to call cancel when no execution is pending', () => {
+      const { result } = createHook()
+
+      expect(() => {
+        act(() => {
+          result.current.cancel()
+        })
+      }).not.toThrow()
+
+      expect(result.current.pending()).toBe(false)
+    })
+  })
+
+  describe('pending()', () => {
+    it('should return false when no execution is pending', () => {
+      const { result } = createHook()
+
+      expect(result.current.pending()).toBe(false)
+    })
+
+    it('should return true when execution is pending', () => {
+      const { result } = createHook()
+
+      result.current.throttledCallback('call1')
+
+      expect(result.current.pending()).toBe(false)
+
+      result.current.throttledCallback('call2')
+
+      expect(result.current.pending()).toBe(true)
+
+      act(() => {
+        vi.advanceTimersByTime(1000)
+      })
+
+      expect(result.current.pending()).toBe(false)
+    })
+  })
+
+  it('should use the latest callback reference', () => {
+    let callbackVersion = 1
+    const initialCallback = vi.fn(() => `version-${callbackVersion}`)
+
+    const { result, rerender } = renderHook(
+      ({ callback }) => useThrottle({ callback, delay: 1000 }),
+      { initialProps: { callback: initialCallback } }
+    )
+
+    result.current.throttledCallback()
+
+    expect(initialCallback).toHaveBeenCalledTimes(1)
+
+    callbackVersion = 2
+    const updatedCallback = vi.fn(() => `version-${callbackVersion}`)
+
+    rerender({ callback: updatedCallback })
+
+    result.current.throttledCallback()
+
+    act(() => {
+      vi.advanceTimersByTime(1000)
+    })
+
+    expect(updatedCallback).toHaveBeenCalledTimes(1)
+    expect(initialCallback).toHaveBeenCalledTimes(1)
+  })
+
+  it('should handle callback changes during pending execution', () => {
+    const callback1 = vi.fn()
+    const callback2 = vi.fn()
+
+    const { result, rerender } = renderHook(
+      ({ callback }) => useThrottle({ callback, delay: 1000 }),
+      { initialProps: { callback: callback1 } }
+    )
+
+    result.current.throttledCallback('immediate')
+    result.current.throttledCallback('throttled')
+
+    expect(callback1).toHaveBeenCalledTimes(1)
+    expect(result.current.pending()).toBe(true)
+
+    rerender({ callback: callback2 })
+
+    act(() => {
+      vi.advanceTimersByTime(1000)
+    })
+
+    expect(callback1).toHaveBeenCalledTimes(1)
+    expect(callback2).toHaveBeenCalledTimes(1)
+    expect(callback2).toHaveBeenCalledWith('throttled')
+  })
+
+  it('should handle zero delay', () => {
+    const { result } = createHook({ callback: mockCallback, delay: 0 })
+
+    result.current.throttledCallback('call1')
+    result.current.throttledCallback('call2')
+    result.current.throttledCallback('call3')
+
+    expect(mockCallback).toHaveBeenCalledTimes(3)
+  })
+
+  it('should handle rapid successive calls correctly', () => {
+    const { result } = createHook()
+
+    for (let i = 0; i < 100; i++) {
+      result.current.throttledCallback(`call-${i}`)
+    }
+
+    expect(mockCallback).toHaveBeenCalledTimes(1)
+    expect(mockCallback).toHaveBeenCalledWith('call-0')
+
+    act(() => {
+      vi.advanceTimersByTime(1000)
+    })
+
+    expect(mockCallback).toHaveBeenCalledTimes(2)
+    expect(mockCallback).toHaveBeenLastCalledWith('call-99')
+  })
+
+  it('should cleanup timeout on unmount', () => {
+    const { result, unmount } = createHook()
+
+    result.current.throttledCallback('call1')
+    result.current.throttledCallback('call2')
+
+    expect(result.current.pending()).toBe(true)
+
+    unmount()
+
+    act(() => {
+      vi.advanceTimersByTime(1000)
+    })
+
+    expect(mockCallback).toHaveBeenCalledTimes(1)
+  })
+
+  it('should not cause memory leaks with multiple calls', () => {
+    const { result } = createHook({
+      callback: mockCallback,
+      delay: 100
+    })
+
+    for (let i = 0; i < 1000; i++) {
+      result.current.throttledCallback(`call-${i}`)
+
+      if (i % 10 === 0) {
+        result.current.cancel()
+      }
+    }
+
+    expect(() => {
+      act(() => {
+        vi.advanceTimersByTime(1000)
+      })
+    }).not.toThrow()
+  })
+
+  it('should maintain stable reference when dependencies do not change', () => {
+    const { result, rerender } = createHook()
+
+    const firstReference = result.current
+
+    rerender()
+
+    expect(result.current).toBe(firstReference)
+  })
+
+  it('should maintain stable control methods', () => {
+    const { result, rerender } = createHook()
+
+    const initialCancel = result.current.cancel
+    const initialPending = result.current.pending
+
+    rerender()
+
+    expect(result.current.cancel).toBe(initialCancel)
+    expect(result.current.pending).toBe(initialPending)
+  })
+})

package/src/lib/hooks/use-throttle/use-throttle.tsx

@@ -0,0 +1,91 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react'
+
+import type { ThrottledFunction, UseThrottleProps } from './types'
+
+/**
+ * Creates a throttled version of the provided function that only executes at most once per specified delay.
+ *
+ * @template T - The function type to throttle
+ * @param params - Configuration object
+ * @param params.callback - The function to throttle
+ * @param params.delay - Minimum time between executions in milliseconds
+ * @returns Throttled function with control methods (cancel, pending)
+ *
+ * @example
+ * ```typescript
+ * const throttledSearch = useThrottle({
+ *   callback: (query: string) => searchAPI(query),
+ *   delay: 300
+ * })
+ *
+ * // Use it
+ * throttledSearch('hello')
+ *
+ * // Check if pending
+ * if (throttledSearch.pending()) {
+ *   console.log('Search is pending...')
+ * }
+ *
+ * // Cancel if needed
+ * throttledSearch.cancel()
+ * ```
+ */
+function useThrottle<T extends (...args: any[]) => any>({
+  callback,
+  delay
+}: UseThrottleProps<T>): ThrottledFunction<T> {
+  const lastExecTime = useRef<number>(0)
+  const timeoutRef = useRef<NodeJS.Timeout | undefined>(undefined)
+  const callbackRef = useRef(callback)
+
+  const cancel = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = undefined
+    }
+  }, [])
+
+  const pending = useCallback(() => {
+    return timeoutRef.current !== undefined
+  }, [])
+
+  const throttledCallback = useCallback(
+    (...args: Parameters<T>) => {
+      const now = Date.now()
+      const timeSinceLastExec = now - lastExecTime.current
+
+      cancel()
+
+      if (timeSinceLastExec >= delay) {
+        lastExecTime.current = now
+        callbackRef.current(...args)
+        return
+      }
+
+      timeoutRef.current = setTimeout(() => {
+        lastExecTime.current = Date.now()
+        callbackRef.current(...args)
+        timeoutRef.current = undefined
+      }, delay - timeSinceLastExec)
+    },
+    [cancel, delay]
+  )
+
+  useEffect(() => {
+    callbackRef.current = callback
+  }, [callback])
+
+  useEffect(() => {
+    return () => cancel()
+  }, [cancel])
+
+  return useMemo(() => {
+    return {
+      throttledCallback,
+      cancel,
+      pending
+    } as ThrottledFunction<T>
+  }, [cancel, pending, throttledCallback])
+}
+
+export default useThrottle

package/src/main/main.spec.tsx

@@ -1,11 +1,18 @@
 import { chance, render, screen, waitFor } from '@/config/tests'
 import WidgetSettingPropsBuilder from '../modules/widget/__tests__/widget-settings-props.builder'
+import { useWidgetSettingsAtom } from '../modules/widget/store/widget-settings.atom'
 import { Main } from '.'
 
+vi.mock('../modules/widget/store/widget-settings.atom', () => ({ useWidgetSettingsAtom: vi.fn() }))
+
 describe('Main', () => {
   const defaultProps = new WidgetSettingPropsBuilder()
   const renderComponent = (props = { settings: defaultProps }) => render(<Main {...props} />)
 
+  beforeEach(() => {
+    vi.mocked(useWidgetSettingsAtom).mockReturnValue([null, vi.fn()])
+  })
+
   it('should render empty element when settings.tutorName is not defined', async () => {
     const { container } = renderComponent()
 
@@ -16,6 +23,8 @@ describe('Main', () => {
 
   it('should render without errors', async () => {
     const props = new WidgetSettingPropsBuilder().withTutorName(chance.name())
+    vi.mocked(useWidgetSettingsAtom).mockReturnValue([props, vi.fn()])
+
     renderComponent({ settings: props })
 
     await waitFor(() => {

package/src/modules/cursor/__tests__/icursor-update.builder.ts

@@ -0,0 +1,42 @@
+import { chance } from '@/src/config/tests'
+import type { ICursorUpdate } from '../types'
+
+class ICursorUpdateBuilder implements ICursorUpdate {
+  threadId: string
+  contactId: string
+  cursor: number
+  conversationId?: string
+
+  constructor() {
+    this.threadId = chance.guid()
+    this.contactId = chance.guid()
+    this.cursor = chance.integer()
+    this.conversationId = chance.guid()
+  }
+
+  withThreadId(threadId: typeof this.threadId) {
+    this.threadId = threadId
+
+    return this
+  }
+
+  withContactId(contactId: typeof this.contactId) {
+    this.contactId = contactId
+
+    return this
+  }
+
+  withCursor(cursor: typeof this.cursor) {
+    this.cursor = cursor
+
+    return this
+  }
+
+  withConversationId(conversationId: typeof this.conversationId) {
+    this.conversationId = conversationId
+
+    return this
+  }
+}
+
+export default ICursorUpdateBuilder

package/src/modules/cursor/hooks/index.ts

@@ -0,0 +1 @@
+export * from './use-update-cursor'

package/src/modules/cursor/hooks/use-update-cursor/index.ts

@@ -0,0 +1,2 @@
+export * from './use-update-cursor'
+export { default as useUpdateCursor } from './use-update-cursor'