@bettercms-ai/kit 0.1.0

package/src/core/hooks/useClickOutside.test.tsx

@@ -0,0 +1,482 @@
+/** @jest-environment jsdom */
+
+import {render, screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import {useEffect, useRef, useState} from 'react'
+
+import {useClickOutside} from './useClickOutside'
+
+describe('useClickOutside', () => {
+  /**
+   * Specifying the elements array directly:
+   * useClickOutside(handler, [buttonElement, popoverElement])
+   * instead of in a callback:
+   * useClickOutside(handler, () => [buttonElement, popoverElement])
+   * is still supported, but deprecated and discouraged. The same is true for the `setElement` callback pattern
+   */
+  it('calls the handler when clicking outside of the array of elements', async () => {
+    const user = userEvent.setup()
+    const handler = jest.fn()
+
+    const TestComponent = () => {
+      const [buttonElement, setButtonElement] = useState<HTMLButtonElement | null>(null)
+      const [popoverElement, setPopoverElement] = useState<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [buttonElement, popoverElement])
+
+      return (
+        <>
+          <button data-testid="button" ref={setButtonElement} />
+          <div data-testid="popover" ref={setPopoverElement} />
+          <div data-testid="outside" />
+        </>
+      )
+    }
+
+    render(<TestComponent />)
+
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    expect(handler).not.toHaveBeenCalled()
+
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('the elements array flattens nested arrays one level deep', async () => {
+    const user = userEvent.setup()
+    const handler = jest.fn()
+
+    const TestComponent = () => {
+      const [buttonElement, setButtonElement] = useState<HTMLButtonElement | null>(null)
+      const [popoverElement, setPopoverElement] = useState<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [null, [null, buttonElement], [popoverElement, null], null])
+
+      return (
+        <>
+          <button data-testid="button" ref={setButtonElement} />
+          <div data-testid="popover" ref={setPopoverElement} />
+          <div data-testid="outside" />
+        </>
+      )
+    }
+
+    render(<TestComponent />)
+
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    expect(handler).not.toHaveBeenCalled()
+
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('it can set a boundary to scope outside click events', async () => {
+    const user = userEvent.setup()
+    const handler = jest.fn()
+
+    const TestComponent = () => {
+      const [buttonElement, setButtonElement] = useState<HTMLButtonElement | null>(null)
+      const [popoverElement, setPopoverElement] = useState<HTMLDivElement | null>(null)
+      const [boundaryElement, setBoundaryElement] = useState<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [buttonElement, popoverElement], boundaryElement)
+
+      return (
+        <>
+          <div ref={setBoundaryElement}>
+            <button data-testid="button" ref={setButtonElement} />
+            <div data-testid="popover" ref={setPopoverElement} />
+            <div data-testid="inside" />
+          </div>
+          <div data-testid="outside" />
+        </>
+      )
+    }
+
+    render(<TestComponent />)
+
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    // Since it's outside the boundary it should be ignored
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).not.toHaveBeenCalled()
+
+    await user.click(screen.getByTestId('inside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('it returns a `setElement` callback', async () => {
+    /**
+     * We don't use this pattern in the studio codebase anymore, and we don't recommend using it moving forward.
+     * But since it's part of the public API we can't remove it without a major version bump.
+     * Thus it makes sense to unit test it to ensure it works as expected and we don't accidentally break backwards compatibility.
+     */
+    const user = userEvent.setup()
+    const handler = jest.fn()
+
+    const TestComponent = (props: {open?: true}) => {
+      const {open = false} = props
+      const [buttonElement, setButtonElement] = useState<HTMLButtonElement | null>(null)
+
+      const setElement = useClickOutside(handler, [buttonElement])
+
+      return (
+        <>
+          <button data-testid="button" ref={setButtonElement} />
+          {open && <div data-testid="popover" ref={setElement} />}
+          <div data-testid="outside" />
+        </>
+      )
+    }
+
+    const {rerender} = render(<TestComponent />)
+
+    await user.click(screen.getByTestId('button'))
+    expect(handler).not.toHaveBeenCalled()
+
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    // The popover isn't rendered yet
+    expect(screen.queryByTestId('popover')).toBeNull()
+
+    // Rerender the component with the popover open
+    rerender(<TestComponent open />)
+
+    // Clicking the popover should not trigger the handler
+    await user.click(screen.getByTestId('popover'))
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('instead of `setElement`, update the `elements` array', async () => {
+    /**
+     * Since we don't want people to use the `setElement` pattern, test that userland can handle dynamically changing elements arrays
+     */
+    const user = userEvent.setup()
+    const handler = jest.fn()
+
+    const TestComponent = (props: {open?: true}) => {
+      const {open = false} = props
+      const [buttonElement, setButtonElement] = useState<HTMLButtonElement | null>(null)
+      const [popoverElement, setPopoverElement] = useState<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [buttonElement, popoverElement])
+
+      return (
+        <>
+          <button data-testid="button" ref={setButtonElement} />
+          {open && <div data-testid="popover" ref={setPopoverElement} />}
+          <div data-testid="outside" />
+        </>
+      )
+    }
+
+    const {rerender} = render(<TestComponent />)
+
+    await user.click(screen.getByTestId('button'))
+    expect(handler).not.toHaveBeenCalled()
+
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    // The popover isn't rendered yet
+    expect(screen.queryByTestId('popover')).toBeNull()
+
+    // Rerender the component with the popover open
+    rerender(<TestComponent open />)
+
+    // Clicking the popover should not trigger the handler
+    await user.click(screen.getByTestId('popover'))
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('returning the current value of refs in the elements array is dangerous', async () => {
+    /**
+     * This test demonstrates why it's dangerous to return ref values in the elements array.
+     * When using refs, pass a function returning the elements array, instead of defining the array directly during render
+     */
+
+    const user = userEvent.setup()
+    let handler = jest.fn()
+
+    /**
+     * Using refs in the `useClickOutside` elements array is dangerous,
+     * the below example demonstrates how `useClickOutside` doesn't "see" the current values of refs,
+     * it can only "see" whatever the value of the ref was when the hook was rendered.
+     */
+    let TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [buttonRef.current, popoverRef.current])
+
+      return (
+        <>
+          <button data-testid="button" ref={buttonRef} />
+          <div data-testid="popover" ref={popoverRef} />
+        </>
+      )
+    }
+    const {rerender} = render(<TestComponent />)
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    // Because the ref values are stale, the handler is called
+    expect(handler).toHaveBeenCalledTimes(2)
+
+    /**
+     * If a mixture of refs and state is used it can appear like it's working correctly,
+     * but this is a side-effect, not an indication it's safe.
+     */
+    handler = jest.fn()
+    TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const [popoverElement, setPopoverElement] = useState<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [buttonRef.current, popoverElement])
+
+      return (
+        <>
+          <button data-testid="button" ref={buttonRef} />
+          <div data-testid="popover" ref={setPopoverElement} />
+          <div data-testid="outside" />
+        </>
+      )
+    }
+    rerender(<TestComponent />)
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    expect(handler).not.toHaveBeenCalled()
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    /**
+     * Unrelated state updates can create the same false impression of safety.
+     */
+    handler = jest.fn()
+    TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [buttonRef.current, popoverRef.current])
+
+      const [, tick] = useState(0)
+      useEffect(() => {
+        /**
+         * This effect schedules a re-render, which will lead to `useClickOutsideHandler` "seeing"
+         * the current value of the refs after they got assigned dom nodes when the React ref callbacks executed.
+         */
+        tick((prev) => ++prev)
+      }, [])
+
+      return (
+        <>
+          <button data-testid="button" ref={buttonRef} />
+          <div data-testid="popover" ref={popoverRef} />
+          <div data-testid="outside" />
+        </>
+      )
+    }
+    rerender(<TestComponent />)
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    expect(handler).not.toHaveBeenCalled()
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    /**
+     * When using the legacy version of the `useClickOutside` API it's necessary to synchronize mutable ref values
+     * with a effect and state loop to ensure they're not stale
+     */
+    const useElementsFromRefs = (refs: React.MutableRefObject<HTMLElement | null>[]) => {
+      const [elements, setElements] = useState(() => refs.map((ref) => ref.current))
+
+      useEffect(() => {
+        if (refs.length !== elements.length) {
+          setElements(refs.map((ref) => ref.current))
+        }
+        for (const ref of refs) {
+          if (!elements.includes(ref.current)) {
+            setElements(refs.map((ref) => ref.current))
+            return
+          }
+        }
+      }, [elements, refs])
+
+      return elements
+    }
+    handler = jest.fn()
+    TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+
+      const elements = useElementsFromRefs([buttonRef, popoverRef])
+      useClickOutside(handler, elements)
+
+      return (
+        <>
+          <button data-testid="button" ref={buttonRef} />
+          <div data-testid="popover" ref={popoverRef} />
+          <div data-testid="outside" />
+        </>
+      )
+    }
+    rerender(<TestComponent />)
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    expect(handler).not.toHaveBeenCalled()
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('using the current value of a react ref as the `boundaryElement` is dangerous', async () => {
+    /**
+     * This test demonstrates why it's dangerous to return a ref value as the boundaryElement,
+     * for the same reasons it's dangerous for the elements array.
+     */
+
+    const user = userEvent.setup()
+    let handler = jest.fn()
+
+    /**
+     * Using refs in the `useClickOutside` elements array is dangerous,
+     * the below example demonstrates how `useClickOutside` doesn't "see" the current values of refs,
+     * it can only "see" whatever the value of the ref was when the hook was rendered.
+     */
+    let TestComponent = () => {
+      const boundaryRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [], boundaryRef.current)
+
+      return (
+        <>
+          <div ref={boundaryRef}>
+            <div data-testid="inside" />
+          </div>
+          <div data-testid="outside" />
+        </>
+      )
+    }
+    const {rerender} = render(<TestComponent />)
+    await user.click(screen.getByTestId('inside'))
+    await user.click(screen.getByTestId('outside'))
+    // Because the ref values are stale, the handler is called
+    expect(handler).toHaveBeenCalledTimes(2)
+
+    /**
+     * If a mixture of refs and state is used it can appear like it's working correctly,
+     * but this is a side-effect, not an indication it's safe.
+     */
+    handler = jest.fn()
+    TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const [popoverElement, setPopoverElement] = useState<HTMLDivElement | null>(null)
+      const boundaryRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [buttonRef.current, popoverElement], boundaryRef.current)
+
+      return (
+        <>
+          <div ref={boundaryRef}>
+            <button data-testid="button" ref={buttonRef} />
+            <div data-testid="popover" ref={setPopoverElement} />
+            <div data-testid="inside" />
+          </div>
+          <div data-testid="outside" />
+        </>
+      )
+    }
+    rerender(<TestComponent />)
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).not.toHaveBeenCalled()
+    await user.click(screen.getByTestId('inside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    /**
+     * Unrelated state updates can create the same false impression of safety.
+     */
+    handler = jest.fn()
+    TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+      const boundaryRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutside(handler, [buttonRef.current, popoverRef.current], boundaryRef.current)
+
+      const [, tick] = useState(0)
+      useEffect(() => {
+        /**
+         * This effect schedules a re-render, which will lead to `useClickOutsideHandler` "seeing"
+         * the current value of the refs after they got assigned dom nodes when the React ref callbacks executed.
+         */
+        tick((prev) => ++prev)
+      }, [])
+
+      return (
+        <>
+          <div ref={boundaryRef}>
+            <button data-testid="button" ref={buttonRef} />
+            <div data-testid="popover" ref={popoverRef} />
+            <div data-testid="inside" />
+          </div>
+          <div data-testid="outside" />
+        </>
+      )
+    }
+    rerender(<TestComponent />)
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).not.toHaveBeenCalled()
+    await user.click(screen.getByTestId('inside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    /**
+     * When using the legacy version of the `useClickOutside` API it's necessary to synchronize mutable ref values
+     * with a effect and state loop to ensure they're not stale
+     */
+    const useBoundaryElementFromRef = (ref: React.MutableRefObject<HTMLElement | null>) => {
+      const [element, setElement] = useState(() => ref.current)
+
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      useEffect(() => {
+        // If the ref has mutated since the last render, update the state and schedule a re-render
+        if (ref.current !== element) {
+          setElement(ref.current)
+        }
+      })
+
+      return element
+    }
+    handler = jest.fn()
+    TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+      const boundaryRef = useRef<HTMLDivElement | null>(null)
+
+      const boundaryElement = useBoundaryElementFromRef(boundaryRef)
+      useClickOutside(handler, [buttonRef.current, popoverRef.current], boundaryElement)
+
+      return (
+        <>
+          <div ref={boundaryRef}>
+            <button data-testid="button" ref={buttonRef} />
+            <div data-testid="popover" ref={popoverRef} />
+            <div data-testid="inside" />
+          </div>
+          <div data-testid="outside" />
+        </>
+      )
+    }
+    rerender(<TestComponent />)
+    await user.click(screen.getByTestId('button'))
+    await user.click(screen.getByTestId('popover'))
+    await user.click(screen.getByTestId('outside'))
+    expect(handler).not.toHaveBeenCalled()
+    await user.click(screen.getByTestId('inside'))
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+})

package/src/core/hooks/useClickOutside.ts

@@ -0,0 +1,118 @@
+import {useEffect, useRef, useState} from 'react'
+
+import {EMPTY_ARRAY} from '../constants'
+
+/**
+ * @public
+ */
+export type ClickOutsideListener = (event: MouseEvent) => void
+
+/**
+ * @public
+ */
+export type ClickOutsideElements = (HTMLElement | null | (HTMLElement | null)[])[]
+
+function _getElements(
+  element: HTMLElement | null,
+  elementsArg: ClickOutsideElements,
+): HTMLElement[] {
+  const ret = [element]
+
+  for (const el of elementsArg) {
+    if (Array.isArray(el)) {
+      ret.push(...el)
+    } else {
+      ret.push(el)
+    }
+  }
+
+  return ret.filter(Boolean) as HTMLElement[]
+}
+
+/**
+ * @public
+ * @deprecated replaced by the new `useClickOutsideEvent` hook, instead of:
+ * ```tsx
+ * const [button, setButtonElement] = useState(null)
+ * useClickOutside((event) => {}, [button])
+ * return <button ref={setButtonElement} />
+ * ```
+ * do:
+ * ```tsx
+ * const buttonRef = useRef()
+ * useClickOutsideEvent((event) => {}, () => [buttonRef.current])
+ * return <button ref={buttonRef} />
+ * ```
+ */
+export function useClickOutside(
+  listener: ClickOutsideListener,
+  elementsArg: ClickOutsideElements = EMPTY_ARRAY,
+  boundaryElement?: HTMLElement | null,
+): (el: HTMLElement | null) => void {
+  const [element, setElement] = useState<HTMLElement | null>(null)
+  const [elements, setElements] = useState(() => _getElements(element, elementsArg))
+  const elementsRef = useRef(elements)
+
+  useEffect(() => {
+    const prevElements = elementsRef.current
+    const nextElements = _getElements(element, elementsArg)
+
+    if (prevElements.length !== nextElements.length) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setElements(nextElements)
+      elementsRef.current = nextElements
+
+      return
+    }
+
+    for (const el of prevElements) {
+      if (!nextElements.includes(el)) {
+        setElements(nextElements)
+        elementsRef.current = nextElements
+
+        return
+      }
+    }
+
+    for (const el of nextElements) {
+      if (!prevElements.includes(el)) {
+        setElements(nextElements)
+        elementsRef.current = nextElements
+
+        return
+      }
+    }
+  }, [element, elementsArg])
+
+  useEffect(() => {
+    if (!listener) return undefined
+
+    const handleWindowMouseDown = (evt: MouseEvent) => {
+      const target = evt.target
+
+      if (!(target instanceof Node)) {
+        return
+      }
+
+      if (boundaryElement && !boundaryElement.contains(target)) {
+        return
+      }
+
+      for (const el of elements) {
+        if (target === el || el.contains(target)) {
+          return
+        }
+      }
+
+      listener(evt)
+    }
+
+    window.addEventListener('mousedown', handleWindowMouseDown)
+
+    return () => {
+      window.removeEventListener('mousedown', handleWindowMouseDown)
+    }
+  }, [boundaryElement, listener, elements])
+
+  return setElement
+}