@sanity/ui 3.1.13 → 4.0.0-beta.0

package/src/components/virtualList/__workshop__/ElementScroll.tsx

@@ -0,0 +1,43 @@
+import {Card, Container, Text, VirtualList} from '@sanity/ui'
+
+type Item = {
+  key: number
+}
+
+const data: Item[] = Array.from(new Array(1000)).map((_, key) => ({key}))
+
+export default function ElementScrollStory(): React.JSX.Element {
+  return (
+    <Card
+      __unstable_pattern="halftone"
+      height="fill"
+      padding={4}
+      sizing="border"
+      tone="transparent"
+    >
+      <Card
+        height="fill"
+        margin="auto"
+        maxWidth={1}
+        overflow="auto"
+        padding={4}
+        radius={5}
+        shadow={1}
+        sizing="border"
+        tone="default"
+      >
+        <Container width={1}>
+          <VirtualList
+            gap={2}
+            items={data}
+            renderItem={(item) => (
+              <Card padding={3} radius={4} shadow={1}>
+                <Text size={1}>Item #{item.key}</Text>
+              </Card>
+            )}
+          />
+        </Container>
+      </Card>
+    </Card>
+  )
+}

package/src/components/virtualList/__workshop__/InfiniteList.tsx

@@ -0,0 +1,40 @@
+import {Card, Container, Text, VirtualList} from '@sanity/ui'
+import {useRef, useState} from 'react'
+
+interface Item {
+  key: string
+}
+
+function getData(len: number, offsetIndex = 0): Item[] {
+  return Array.from(new Array(len)).map((_, index) => ({key: String(offsetIndex + index)}))
+}
+
+const ITEMS_PER_PAGE = 1000
+
+export default function InfiniteListStory(): React.JSX.Element {
+  const [data, setData] = useState(() => getData(ITEMS_PER_PAGE))
+  const offsetRef = useRef(0)
+
+  return (
+    <Container padding={4} width={1}>
+      <VirtualList
+        gap={2}
+        getItemKey={(item) => `item-${item.key}`}
+        items={data}
+        renderItem={(item) => (
+          <Card padding={3} radius={4} shadow={1}>
+            <Text size={1}>Item #{item.key}</Text>
+          </Card>
+        )}
+        onChange={({toIndex}) => {
+          const maxIndex = (offsetRef.current + 1) * ITEMS_PER_PAGE
+
+          if (toIndex >= maxIndex - 50) {
+            offsetRef.current += 1
+            setData((d) => d.concat(getData(ITEMS_PER_PAGE, offsetRef.current * ITEMS_PER_PAGE)))
+          }
+        }}
+      />
+    </Container>
+  )
+}

package/src/components/virtualList/__workshop__/WindowScrolll.tsx

@@ -0,0 +1,23 @@
+import {Card, Container, Text, VirtualList} from '@sanity/ui'
+
+type Item = {
+  key: number
+}
+
+const data: Item[] = Array.from(new Array(1000)).map((_, key) => ({key}))
+
+export default function WindowScrollStory(): React.JSX.Element {
+  return (
+    <Container paddingX={[4, 5, 6]} paddingY={[5, 6, 7]} width={1}>
+      <VirtualList
+        gap={2}
+        items={data}
+        renderItem={(item) => (
+          <Card padding={3} radius={4} shadow={1}>
+            <Text size={1}>Item #{item.key}</Text>
+          </Card>
+        )}
+      />
+    </Container>
+  )
+}

package/src/components/virtualList/__workshop__/index.ts

@@ -0,0 +1,31 @@
+import type {WorkshopScope} from '@sanity/ui-workshop'
+import {lazy} from 'react'
+
+const scope: WorkshopScope = {
+  name: 'components/virtual-list',
+  title: 'VirtualList',
+  stories: [
+    {
+      name: 'window-scroll',
+      title: 'Window scroll',
+      component: lazy(() => import('./WindowScrolll')),
+    },
+    {
+      name: 'element-scroll',
+      title: 'Element scroll',
+      component: lazy(() => import('./ElementScroll')),
+    },
+    {
+      name: 'infinite-list',
+      title: 'Infinite list',
+      component: lazy(() => import('./InfiniteList')),
+    },
+    {
+      name: 'changing-props',
+      title: 'Changing props',
+      component: lazy(() => import('./ChangingProps')),
+    },
+  ],
+}
+
+export default scope

package/src/core/_keys.ts

@@ -0,0 +1,26 @@
+type PropertyKey = string | number | symbol
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Any = any
+
+/** @internal */
+export function _splitKeys<
+  P extends Record<PropertyKey, Any>,
+  const K extends readonly (keyof P)[],
+>(props: P, keys: K) {
+  const style = {} as Pick<P, K[number]>
+  const rest = {} as Omit<P, K[number]>
+
+  // Faster membership than Array.includes for large key lists
+  const keySet = new Set<PropertyKey>(keys as readonly PropertyKey[])
+
+  for (const k in props) {
+    if (keySet.has(k)) {
+      ;(style as Any)[k] = (props as Any)[k]
+    } else {
+      ;(rest as Any)[k] = (props as Any)[k]
+    }
+  }
+
+  return [style, rest] as const
+}

package/src/core/constants.ts

@@ -1,20 +1,13 @@
 import type {Transition, Variant} from 'motion/react'
 
-/**
- * @internal
- */
 export const EMPTY_ARRAY: never[] = []
 
-/**
- * @internal
- */
 export const EMPTY_RECORD: Record<string, never> = {}
 
 const POPOVER_MOTION_DURATION = 0.2
 
 /**
  * Shared `framer-motion` variants used by `Popover` and `Tooltip` components.
- * @internal
  */
 export const POPOVER_MOTION_PROPS: {
   card: {
@@ -67,13 +60,8 @@ export const POPOVER_MOTION_PROPS: {
   },
 }
 
-/**
- * @internal
- * @deprecated No longer used.
- */
-export const FLOATING_STATIC_SIDES: Record<string, 'bottom' | 'left' | 'top' | 'right'> = {
-  top: 'bottom',
-  right: 'left',
-  bottom: 'top',
-  left: 'right',
+export const Z_OFFSETS = {
+  dialog: 600,
+  popover: 400,
+  tooltip: 200,
 }

package/src/core/getElementRef.ts

@@ -0,0 +1,29 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** @internal */
+// Based on https://github.com/radix-ui/primitives/blob/0bade6a704e5821b90a6da0f3d8cfa8a7711127d/packages/react/slot/src/Slot.tsx#L128-L150
+// Before React 19 accessing `element.props.ref` will throw a warning and suggest using `element.ref`
+// After React 19 accessing `element.ref` does the opposite.
+// https://github.com/facebook/react/pull/28348
+//
+// Access the ref using the method that doesn't yield a warning.
+export function getElementRef(element: React.ReactElement): React.Ref<unknown> | undefined {
+  // React <=18 in DEV
+  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get
+  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+
+  if (mayWarn) {
+    return (element as any).ref
+  }
+
+  // React 19 in DEV
+  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get
+  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+
+  if (mayWarn) {
+    return (element.props as {ref?: React.Ref<unknown>}).ref
+  }
+
+  // Not DEV
+  return (element.props as {ref?: React.Ref<unknown>}).ref || (element as any).ref
+}

package/src/core/helpers/animation.ts

@@ -13,15 +13,14 @@ export function _raf(fn: () => void): () => void {
  * @internal
  */
 export function _raf2(fn: () => void): () => void {
-  let innerDispose: (() => void) | null = null
+  let innerDispose: (() => void) | undefined = undefined
 
-  const outerDispose = _raf(() => {
+  const dispose = _raf(() => {
     innerDispose = _raf(fn)
   })
 
   return () => {
-    if (innerDispose) innerDispose()
-
-    outerDispose()
+    innerDispose?.()
+    dispose()
   }
 }

package/src/core/helpers/focus.ts

@@ -7,10 +7,6 @@ import {
   isHTMLTextAreaElement,
 } from './element'
 
-// export const globalFocusState = {
-//   IgnoreUtilFocusChanges: false,
-// }
-
 /**
  * @internal
  */
@@ -56,16 +52,12 @@ export function attemptFocus(element: HTMLElement): boolean {
     return false
   }
 
-  // globalFocusState.IgnoreUtilFocusChanges = true
-
   try {
     element.focus()
   } catch {
     // ignore
   }
 
-  // globalFocusState.IgnoreUtilFocusChanges = false
-
   return document.activeElement === element
 }
 

package/src/core/helpers/props.ts

@@ -0,0 +1,51 @@
+import {BREAKPOINT_KEYS, type ResponsiveProp, type ResponsivePropArray} from '@sanity/ui-css'
+
+import {EMPTY_ARRAY} from '../constants'
+import {isArray} from '../lib/isArray'
+import {isRecord} from '../lib/isRecord'
+
+// WeakMap for object/array values (automatic GC when objects are no longer referenced)
+const objectCache = new WeakMap<object, ResponsivePropArray<unknown>>()
+
+// Map for primitive values (bounded growth - only primitives like numbers/strings)
+const primitiveCache = new Map<unknown, ResponsivePropArray<unknown>>()
+
+/**
+ * @internal
+ */
+export function _getResponsiveProp<T>(
+  val: ResponsiveProp<T> | undefined,
+  defaultVal?: ResponsivePropArray<T>,
+): ResponsivePropArray<T> {
+  // Fast path: undefined
+  if (val === undefined) {
+    return defaultVal || (EMPTY_ARRAY as unknown as ResponsivePropArray<T>)
+  }
+
+  // Fast path: already an array or object - use WeakMap for identity-based caching
+  if (isArray(val)) {
+    let v = val
+
+    // convert to array
+    if (isRecord(val)) {
+      v = BREAKPOINT_KEYS.map((key) => val[key]) as ResponsivePropArray<T>
+    }
+
+    const cached = objectCache.get(v)
+    if (cached) return cached as ResponsivePropArray<T>
+
+    const ret = v as ResponsivePropArray<T>
+    objectCache.set(v, ret)
+    return ret
+  }
+
+  // Primitive value - wrap in array and cache by value
+  const cached = primitiveCache.get(val)
+  if (cached) return cached as ResponsivePropArray<T>
+
+  const ret = [val] as ResponsivePropArray<T>
+
+  primitiveCache.set(val, ret)
+
+  return ret
+}

package/src/core/lib/createGlobalScopedContext.ts

@@ -1,7 +1,7 @@
 /**
  * As `@sanity/ui` is declared as a dependency, and may be duplicated, sometimes across major versions
  * it's critical that vital react contexts are shared even when there is a duplicate.
- * If we used a model similar to `sanity` itself, or `styled-components`, this would be unnecessary as
+ * If we used a model similar to `sanity` itself this would be unnecessary as
  * those libraries enforce single instances.
  * Since we don't enforce it we have to support a sanity plugin being able to call hooks like `useToast`, and then
  * read the context setup by `sanity`, which calls `ToastProvider`, even if the provider and hook are different instances in memory.
@@ -16,7 +16,7 @@ export function createGlobalScopedContext<ContextType, const T extends ContextTy
   /**
    * Enforce that all Symbol.for keys used for globally scoped contexts have a predictable prefix
    */
-  key: `@sanity/ui/context/${string}`,
+  key: `@sanity/ui/v4/${string}`,
   defaultValue: T,
 ): Context<ContextType> {
   const symbol = Symbol.for(key)
@@ -30,7 +30,10 @@ export function createGlobalScopedContext<ContextType, const T extends ContextTy
     return context
   }
 
-  globalScope[symbol] = globalScope[symbol] || createContext<T>(defaultValue)
+  // Use the global scope as a map of symbols to contexts
+  const symbolMap = globalScope as Record<symbol, Context<ContextType>>
 
-  return globalScope[symbol]
+  symbolMap[symbol] = symbolMap[symbol] || createContext<T>(defaultValue)
+
+  return symbolMap[symbol]
 }

package/src/core/lib/globalScope.ts

@@ -16,4 +16,4 @@ function getGlobalScope() {
   throw new Error('@sanity/ui: could not locate global scope')
 }
 
-export const globalScope = getGlobalScope() as any
+export const globalScope: typeof globalThis = getGlobalScope()

package/src/core/lib/isArray.ts

@@ -0,0 +1,3 @@
+export function isArray(val: unknown): val is unknown[] {
+  return Array.isArray(val)
+}

package/src/core/types.ts

@@ -0,0 +1,57 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Assign properties from `U` to `T`, excluding properties that already exist in `T`.
+ *
+ * @public
+ */
+export type Assign<T extends {}, U extends {}> = Omit<T, keyof U> & U
+
+/** @public */
+export type EmptyProps = {}
+
+/** @public */
+export type TagType = keyof React.JSX.IntrinsicElements
+
+/** @public */
+export type ComponentType<P = any> =
+  | React.FunctionComponent<P>
+  | React.ComponentClass<P>
+  | React.ExoticComponent<P>
+
+/** @public */
+export type ElementType<P> = TagType | ComponentType<P>
+
+/** @public */
+export type Props<P extends EmptyProps, E extends ElementType<P>> = Assign<
+  E extends TagType ? React.JSX.IntrinsicElements[E] : React.ComponentProps<E>,
+  P & {as?: E}
+>
+
+/**
+ * Placement of floating UI elements.
+ *
+ * @public
+ */
+export type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+
+/** @public */
+export type Delay =
+  | number
+  | Partial<{
+      open: number
+      close: number
+    }>

package/src/hooks/useClickOutsideEvent.test.tsx

@@ -0,0 +1,114 @@
+import {render, screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import {useRef} from 'react'
+import {describe, expect, it, vi} from 'vitest'
+
+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 = vi.fn()
+
+    const TestComponent = () => {
+      const buttonRef = useRef<HTMLButtonElement | null>(null)
+      const popoverRef = useRef<HTMLDivElement | null>(null)
+
+      useClickOutsideEvent(handler, () => [buttonRef.current, popoverRef.current])
+
+      return (
+        <>
+          <button ref={buttonRef} data-testid="button" />
+          <div ref={popoverRef} data-testid="popover" />
+          <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 = vi.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 ref={buttonRef} data-testid="button" />
+          <div ref={popoverRef} data-testid="popover" />
+          <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 = vi.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 ref={buttonRef} data-testid="button" />
+            <div ref={popoverRef} data-testid="popover" />
+            <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/hooks/useClickOutsideEvent.ts

@@ -0,0 +1,66 @@
+import {useDebugValue, useEffect, useEffectEvent} from 'react'
+
+import {EMPTY_ARRAY} from '../core/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/hooks/useElementSize.ts

@@ -0,0 +1,19 @@
+import {useEffect, useState} from 'react'
+
+import {_elementSizeObserver, type ElementSize} from '../observers/elementSize'
+
+/**
+ * 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/hooks/useGlobalKeyDown.ts

@@ -0,0 +1,23 @@
+import {useEffect, useEffectEvent} from 'react'
+
+/**
+ * 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])
+}