@sanity/ui 3.0.0-static.8 → 3.0.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/useForwardedRef.ts

@@ -0,0 +1,19 @@
+import {useImperativeHandle, useRef} from 'react'
+
+/**
+ * @beta
+ * @deprecated use `useImperativeHandle` instead
+ * @example
+ * ```diff
+ * -const ref = useForwardedRef(forwardedRef)
+ * +const ref = useRef(null)
+ * +useImperativeHandle(forwardedRef, () => ref.current)
+ * ```
+ */
+export function useForwardedRef<T>(ref: React.ForwardedRef<T>): React.MutableRefObject<T | null> {
+  const innerRef = useRef<T | null>(null)
+
+  useImperativeHandle(ref, () => innerRef.current!)
+
+  return innerRef
+}

package/src/core/hooks/useMatchMedia.ts

@@ -0,0 +1,28 @@
+import {useCallback, useDebugValue, useSyncExternalStore} from 'react'
+
+/**
+ * Efficiently subscribes to `window.matchMedia` queries
+ *
+ * @param getServerSnapshot - Only called during server-side rendering, and hydration if using hydrateRoot. Required if the hook is called during SSR (https://react.dev/reference/react/useSyncExternalStore#adding-support-for-server-rendering)
+ *
+ * @public
+ */
+export function useMatchMedia(
+  mediaQueryString: `(${string})`,
+  getServerSnapshot?: () => boolean,
+): boolean {
+  useDebugValue(mediaQueryString)
+
+  return useSyncExternalStore(
+    useCallback(
+      (onStoreChange) => {
+        const media = window.matchMedia(mediaQueryString)
+        media.addEventListener('change', onStoreChange)
+        return () => media.removeEventListener('change', onStoreChange)
+      },
+      [mediaQueryString],
+    ),
+    () => window.matchMedia(mediaQueryString).matches,
+    getServerSnapshot,
+  )
+}

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

@@ -0,0 +1,36 @@
+/** @jest-environment node */
+
+import {buildTheme} from '@sanity/ui/theme'
+import {renderToStaticMarkup, renderToString} from 'react-dom/server'
+
+import {ThemeProvider} from '../../theme'
+import {useMediaIndex} from './useMediaIndex'
+
+const theme = buildTheme()
+
+function Log() {
+  const mediaIndex = useMediaIndex()
+
+  return <>mediaIndex: {JSON.stringify(mediaIndex)}</>
+}
+
+describe('useMediaIndex', () => {
+  it(`SSR to static markup returns 0`, () => {
+    expect(
+      renderToStaticMarkup(
+        <ThemeProvider theme={theme}>
+          <Log />
+        </ThemeProvider>,
+      ),
+    ).toBe('mediaIndex: 0')
+  })
+  it(`SSR to markup for hydration doesn't throw`, () => {
+    expect(
+      renderToString(
+        <ThemeProvider theme={theme}>
+          <Log />
+        </ThemeProvider>,
+      ),
+    ).toMatchInlineSnapshot(`"mediaIndex: <!-- -->0"`)
+  })
+})

package/src/core/hooks/useMediaIndex/useMediaIndex.ts

@@ -0,0 +1,102 @@
+import {useMemo, useSyncExternalStore} from 'react'
+
+import {useTheme_v2} from '../../theme'
+
+/**
+ * @internal
+ */
+export interface _MediaStore {
+  subscribe: (onStoreChange: () => void) => () => void
+  getSnapshot: () => number
+}
+
+type MediaQueryMinWidth = `(min-width: ${number}px)`
+type MediaQueryMaxWidth = `(max-width: ${number}px)`
+type MediaQueryMinMaxWidth = `${MediaQueryMinWidth} and ${MediaQueryMaxWidth}`
+type MediaQuery = `screen and ${MediaQueryMinWidth | MediaQueryMaxWidth | MediaQueryMinMaxWidth}`
+
+function _getMediaQuery(media: number[], index: number): MediaQuery {
+  if (index === 0) {
+    return `screen and (max-width: ${media[index] - 1}px)`
+  }
+
+  if (index === media.length) {
+    return `screen and (min-width: ${media[index - 1]}px)`
+  }
+
+  return `screen and (min-width: ${media[index - 1]}px) and (max-width: ${media[index] - 1}px)`
+}
+
+function _createMediaStore(media: number[]): _MediaStore {
+  const mediaLen = media.length
+  let sizes: {mq: MediaQueryList; index: number}[]
+
+  // The _createMediaStore function is called in both server and client environments.
+  // However since subscribe and getSnapshot are only called on the client we lazy init what we need for them
+  // so that we don't need to run checks for wether it's safe to call `window.matchMedia`
+  const getSizes = () => {
+    if (!sizes) {
+      sizes = []
+
+      for (let index = mediaLen; index > -1; index -= 1) {
+        const mediaQuery = _getMediaQuery(media, index)
+
+        sizes.push({index, mq: window.matchMedia(mediaQuery)})
+      }
+    }
+
+    return sizes
+  }
+
+  const getSnapshot = () => {
+    for (const {index, mq} of getSizes()) {
+      if (mq.matches) return index
+    }
+
+    return 0
+  }
+
+  const subscribe = (onStoreChange: () => void) => {
+    const disposeFns: (() => void)[] = []
+
+    for (const {mq} of getSizes()) {
+      const handleChange = () => {
+        if (mq.matches) onStoreChange()
+      }
+
+      mq.addEventListener('change', handleChange)
+
+      disposeFns.push(() => mq.removeEventListener('change', handleChange))
+    }
+
+    return () => {
+      for (const disposeFn of disposeFns) {
+        disposeFn()
+      }
+    }
+  }
+
+  return {getSnapshot, subscribe}
+}
+
+/**
+ * Only called during server-side rendering, and hydration if using hydrateRoot
+ * Since the server environment doesn't have access to the DOM, we can't determine the current value of the media query
+ * and we assume `(prefers-color-scheme: light)` since it's the most common scheme
+ *
+ * @link https://beta.reactjs.org/apis/react/useSyncExternalStore#adding-support-for-server-rendering
+ */
+function getServerSnapshot() {
+  return 0
+}
+
+/**
+ * This API might change. DO NOT USE IN PRODUCTION.
+ * @beta
+ */
+export function useMediaIndex(): number {
+  const {media} = useTheme_v2()
+  const store = useMemo(() => _createMediaStore(media), [media])
+
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, getServerSnapshot)
+}

package/src/core/hooks/usePrefersDark.ts

@@ -0,0 +1,16 @@
+import {useMatchMedia} from './useMatchMedia'
+
+/**
+ * Returns true if a dark color scheme is preferred, false if a light color scheme is preferred or the preference is not known.
+ *
+ * @param getServerSnapshot - Only called during server-side rendering, and hydration if using hydrateRoot. Since the server environment doesn't have access to the DOM, we can't determine the current value of the media query and we assume `(prefers-color-scheme: light)` since it's the most common scheme (https://react.dev/reference/react/useSyncExternalStore#adding-support-for-server-rendering)
+ *
+ * If you persist the detected preference in a cookie or a header then you may implement your own server snapshot to read it.
+ * Chrome supports reading the `prefers-color-scheme` media query from a header if the server response: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-CH-Prefers-Color-Scheme
+ * @example https://gist.github.com/stipsan/13c0cccf8dfc34f4b44bb1b984baf7df
+ *
+ * @public
+ */
+export function usePrefersDark(getServerSnapshot = () => false): boolean {
+  return useMatchMedia('(prefers-color-scheme: dark)', getServerSnapshot)
+}