@bettercms-ai/kit 0.1.0

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

@@ -0,0 +1,115 @@
+/** @jest-environment jsdom */
+
+import {render, screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import {useRef} from 'react'
+
+import {useClickOutsideEvent} from './useClickOutsideEvent'
+
+describe('useClickOutsideEvent', () => {
+  /**
+   * This suite demonstrates the new hook `useClickOutsideEvent` that replaces `useClickOutside`
+   */
+
+  it('calls the handler when clicking outside of the array of elements', async () => {
+    const user = userEvent.setup()
+    const handler = jest.fn()
+
+    const TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutsideEvent(handler, () => [buttonRef.current, popoverRef.current])
+
+      return (
+        <>
+          <button data-testid="button" ref={buttonRef} />
+          <div data-testid="popover" ref={popoverRef} />
+          <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 buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutsideEvent(handler, () => [
+        null,
+        [null, buttonRef.current],
+        [popoverRef.current, null],
+        null,
+      ])
+
+      return (
+        <>
+          <button data-testid="button" ref={buttonRef} />
+          <div data-testid="popover" ref={popoverRef} />
+          <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 buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+      const boundaryRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutsideEvent(
+        handler,
+        () => [buttonRef.current, popoverRef.current],
+        () => boundaryRef.current,
+      )
+
+      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" />
+        </>
+      )
+    }
+
+    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)
+  })
+})

package/src/core/hooks/useClickOutsideEvent.ts

@@ -0,0 +1,73 @@
+import {useDebugValue, useEffect} from 'react'
+import {useEffectEvent} from 'use-effect-event'
+
+import {EMPTY_ARRAY} from '../constants'
+
+/**
+ * @public
+ */
+export type ClickOutsideEventListener = (event: MouseEvent) => void
+
+/**
+ * @public
+ */
+export type ClickOutsideEventElements = (HTMLElement | null | (HTMLElement | null)[])[]
+
+/**
+ * @public
+ */
+export function useClickOutsideEvent(
+  listener: ClickOutsideEventListener | false | undefined,
+  elementsArg: () => ClickOutsideEventElements = () => EMPTY_ARRAY,
+  boundaryElement?: () => HTMLElement | null,
+): void {
+  /**
+   * The `useEffectEvent` hook allow us to always see the latest value of `listener`, `elementsArg` and `boundaryElement` without needing to
+   * juggle `useState`, `useRef` and `useState` to make sure the `mousedown` event listener isn't constantly being added and removed.
+   */
+  const onEvent = useEffectEvent((evt: MouseEvent) => {
+    if (!listener) {
+      return
+    }
+
+    const target = evt.target
+
+    if (!(target instanceof Node)) {
+      return
+    }
+
+    const resolvedBoundaryElement = boundaryElement?.()
+
+    if (resolvedBoundaryElement && !resolvedBoundaryElement.contains(target)) {
+      return
+    }
+
+    const elements = elementsArg().flat()
+
+    for (const el of elements) {
+      if (!el) continue
+
+      if (target === el || el.contains(target)) {
+        return
+      }
+    }
+
+    listener(evt)
+  })
+
+  const hasListener = Boolean(listener)
+
+  useEffect(() => {
+    if (!hasListener) return undefined
+
+    const handleEvent = (evt: MouseEvent) => onEvent(evt)
+
+    document.addEventListener('mousedown', handleEvent)
+
+    return () => {
+      document.removeEventListener('mousedown', handleEvent)
+    }
+  }, [hasListener])
+
+  useDebugValue(listener ? 'MouseDown On' : 'MouseDown Off')
+}

package/src/core/hooks/useCustomValidity.ts

@@ -0,0 +1,13 @@
+import {useEffect} from 'react'
+
+/**
+ * @beta
+ */
+export function useCustomValidity(
+  ref: {current: null | {setCustomValidity: (validity: string) => void}},
+  customValidity: string | undefined,
+): void {
+  useEffect(() => {
+    ref.current?.setCustomValidity(customValidity || '')
+  }, [customValidity, ref])
+}

package/src/core/hooks/useDelayed.test.ts

@@ -0,0 +1,88 @@
+/** @jest-environment jsdom */
+
+import {act, renderHook} from '@testing-library/react'
+
+import {useDelayedState} from './useDelayedState'
+
+describe('useDelayedState', () => {
+  it('should update state immediately if delay is not provided', () => {
+    const {result} = renderHook(() => useDelayedState(false))
+    const [, setState] = result.current
+
+    act(() => {
+      setState(true)
+    })
+    expect(result.current[0]).toBe(true)
+  })
+
+  it('should update state after delay if delay is provided', async () => {
+    jest.useFakeTimers()
+    const {result} = renderHook(() => useDelayedState(false))
+    const [, setState] = result.current
+
+    act(() => {
+      setState(true, 1000)
+    })
+    expect(result.current[0]).toBe(false)
+    act(() => {
+      jest.advanceTimersByTime(500)
+    })
+    expect(result.current[0]).toBe(false)
+
+    act(() => {
+      jest.advanceTimersByTime(500)
+    })
+
+    expect(result.current[0]).toBe(true)
+  })
+
+  it('should update state with callback function', () => {
+    const {result} = renderHook(() => useDelayedState(false))
+    const [, setState] = result.current
+
+    act(() => {
+      setState((prev: boolean) => !prev)
+    })
+
+    expect(result.current[0]).toBe(true)
+  })
+
+  it('should clear pending timeout on unmount', () => {
+    jest.useFakeTimers()
+    const clearTimeoutSpy = jest.spyOn(global, 'clearTimeout')
+    const {result, unmount} = renderHook(() => useDelayedState(false))
+    const [, setState] = result.current
+
+    act(() => {
+      setState(true, 1000)
+    })
+
+    clearTimeoutSpy.mockClear()
+
+    // Unmount while the delayed update is still pending
+    unmount()
+
+    // clearTimeout should have been called during cleanup
+    expect(clearTimeoutSpy).toHaveBeenCalledTimes(1)
+    clearTimeoutSpy.mockRestore()
+  })
+
+  it('should cancel update if the set state was called with a new state', () => {
+    const {result} = renderHook(() => useDelayedState(false))
+    const [, setState] = result.current
+
+    act(() => {
+      setState(true, 1000)
+    })
+    expect(result.current[0]).toBe(false)
+
+    jest.advanceTimersByTime(500)
+
+    act(() => {
+      setState(false)
+    })
+    jest.advanceTimersByTime(600)
+    // Even after 1.1 seconds, the state should continue being false, because it was cancelled by a next setState call
+    expect(result.current[0]).toBe(false)
+  })
+})

package/src/core/hooks/useDelayedState.ts

@@ -0,0 +1,36 @@
+import {SetStateAction, useCallback, useEffect, useRef, useState} from 'react'
+
+/**
+ * @beta
+ */
+export function useDelayedState<S>(
+  initialState: S | (() => S),
+): [S, (nextState: SetStateAction<S>, delay?: number) => void] {
+  const [state, setState] = useState(initialState)
+  const delayedAction = useRef<NodeJS.Timeout | undefined>(undefined)
+
+  const onStateChange = useCallback((nextState: SetStateAction<S>, delay?: number) => {
+    const action = () => {
+      setState(nextState)
+    }
+
+    // A new state change has been initiated, cancel the previous one.
+    if (delayedAction.current) {
+      clearTimeout(delayedAction.current)
+      delayedAction.current = undefined
+    }
+
+    if (!delay) return action()
+    delayedAction.current = setTimeout(action, delay)
+  }, [])
+
+  useEffect(() => {
+    return () => {
+      if (delayedAction.current) {
+        clearTimeout(delayedAction.current)
+      }
+    }
+  }, [])
+
+  return [state, onStateChange]
+}

package/src/core/hooks/useElementRect/__workshop__/example.tsx

@@ -0,0 +1,32 @@
+import {Box, Card, Code, Container, Stack, Text, useElementRect} from '@bettercms-ai/kit'
+import {useState} from 'react'
+
+import {Grid} from '../../../primitives'
+
+export default function ExampleStory() {
+  const [element, setElement] = useState<HTMLElement | null>(null)
+  const rect = useElementRect(element)
+  const size = {width: rect?.width || 0, height: rect?.height || 0}
+
+  return (
+    <Box padding={[3, 4, 5]}>
+      <Container width={1}>
+        <Stack space={4}>
+          <Grid columns={[1, 2, 3]}>
+            <Card ref={setElement} tone="transparent">
+              <Text>rect</Text>
+            </Card>
+          </Grid>
+
+          <div style={{height: 11}}>
+            <Card scheme="dark" style={{position: 'absolute', ...size}} />
+          </div>
+
+          <Code language="json" size={1}>
+            {JSON.stringify(size)}
+          </Code>
+        </Stack>
+      </Container>
+    </Box>
+  )
+}

package/src/core/hooks/useElementRect/__workshop__/index.ts

@@ -0,0 +1,14 @@
+import {defineScope} from '@bettercms-ai/kit-workshop'
+import {lazy} from 'react'
+
+export default defineScope({
+  name: 'hooks/useElementRect',
+  title: 'useElementRect',
+  stories: [
+    {
+      name: 'example',
+      title: 'Example',
+      component: lazy(() => import('./example')),
+    },
+  ],
+})

package/src/core/hooks/useElementRect/index.ts

@@ -0,0 +1 @@
+export * from './useElementRect'

package/src/core/hooks/useElementRect/useElementRect.ts

@@ -0,0 +1,13 @@
+import {useElementSize} from '../useElementSize'
+
+/**
+ * Subscribe to the rect of a DOM element.
+ * @beta
+ *
+ * @deprecated Use `useElementSize` instead
+ */
+export function useElementRect(element: HTMLElement | null): DOMRectReadOnly | null {
+  const elementSize = useElementSize(element)
+
+  return elementSize?._contentRect || null
+}

package/src/core/hooks/useElementSize.ts

@@ -0,0 +1,19 @@
+import {useEffect, useState} from 'react'
+
+import {_elementSizeObserver, ElementSize} from '../observers/elementSizeObserver'
+
+/**
+ * Subscribe to the size of a DOM element.
+ * @beta
+ */
+export function useElementSize(element: HTMLElement | null): ElementSize | null {
+  const [size, setSize] = useState<ElementSize | null>(null)
+
+  useEffect(() => {
+    if (!element) return undefined
+
+    return _elementSizeObserver.subscribe(element, setSize)
+  }, [element])
+
+  return size
+}

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/useGlobalKeyDown.ts

@@ -0,0 +1,24 @@
+import {useEffect} from 'react'
+import {useEffectEvent} from 'use-effect-event'
+
+/**
+ * Adds global keydown event listener to the window.
+ *
+ * @param onKeyDown - The function to call when a keydown event is triggered.
+ * @param options - The options to pass to the addEventListener function (example, capture: true)
+ * @beta
+ */
+export function useGlobalKeyDown(
+  onKeyDown: (event: KeyboardEvent) => void,
+  options?: AddEventListenerOptions,
+): void {
+  const handleKeyDown = useEffectEvent((event: KeyboardEvent) => onKeyDown(event))
+
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => handleKeyDown(event)
+
+    window.addEventListener('keydown', handler, options)
+
+    return () => window.removeEventListener('keydown', handler, options)
+  }, [options])
+}

package/src/core/hooks/useIsomorphicEffect.ts

@@ -0,0 +1,7 @@
+import {useEffect, useLayoutEffect} from 'react'
+
+/**
+ * @beta
+ * @deprecated use `useLayoutEffect` instead, or `useEffect` if possible
+ */
+export const useIsomorphicEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect

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/__workshop__/index.ts

@@ -0,0 +1,14 @@
+import {defineScope} from '@bettercms-ai/kit-workshop'
+import {lazy} from 'react'
+
+export default defineScope({
+  name: 'hooks/use-media-index',
+  title: 'useMediaIndex',
+  stories: [
+    {
+      name: 'test',
+      title: 'Test',
+      component: lazy(() => import('./test')),
+    },
+  ],
+})

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

@@ -0,0 +1,14 @@
+import {Card, Stack, Text, useMediaIndex} from '@bettercms-ai/kit'
+
+export default function TestStory() {
+  const mediaIndex = useMediaIndex()
+
+  return (
+    <Card padding={[3, 4, 5]}>
+      <Stack space={2}>
+        <Text weight="medium">The current media index is {mediaIndex}.</Text>
+        <Text muted>Try resizing the browser.</Text>
+      </Stack>
+    </Card>
+  )
+}

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

@@ -0,0 +1 @@
+export * from './useMediaIndex'

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

@@ -0,0 +1,36 @@
+/** @jest-environment node */
+
+import {buildTheme} from '@bettercms-ai/kit/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/useMounted.ts

@@ -0,0 +1,15 @@
+import {useSyncExternalStore} from 'react'
+
+/**
+ * Some components should only render after mounting to the DOM, and not be rendered at all during SSR renderToString or equivalent.
+ * @public
+ */
+export function useMounted(): boolean {
+  return useSyncExternalStore(
+    subscribe,
+    () => true,
+    () => false,
+  )
+}
+
+const subscribe = () => () => {}