@tamagui/floating 2.0.0-rc.3 → 2.0.0-rc.30

package/src/interactions/types.ts

@@ -0,0 +1,165 @@
+import type { HTMLProps, RefObject } from 'react'
+import type { FloatingEvents } from './createFloatingEvents'
+import type { PopupTriggerMap } from './PopupTriggerMap'
+
+export type { FloatingEvents }
+
+export type ElementProps = {
+  reference?: HTMLProps<Element>
+  floating?: HTMLProps<HTMLElement>
+  item?:
+    | HTMLProps<HTMLElement>
+    | ((props: { active?: boolean; selected?: boolean }) => HTMLProps<HTMLElement>)
+}
+
+export type OpenChangeReason =
+  | 'hover'
+  | 'focus'
+  | 'click'
+  | 'dismiss'
+  | 'list-navigation'
+  | 'escape-key'
+  | 'reference-press'
+  | 'safe-polygon'
+
+export interface FloatingInteractionContext {
+  open: boolean
+  onOpenChange: (open: boolean, event?: Event, reason?: OpenChangeReason) => void
+  refs: {
+    reference: RefObject<Element | null>
+    floating: RefObject<HTMLElement | null>
+    domReference: RefObject<Element | null>
+  }
+  elements: {
+    reference: Element | null
+    floating: HTMLElement | null
+    domReference: Element | null
+  }
+  dataRef: RefObject<{
+    openEvent?: Event
+    // placement from the floating positioning — needed for safePolygon
+    placement?: string
+    // whether the user is currently typing (typeahead)
+    typing?: boolean
+  }>
+  events?: FloatingEvents
+  triggerElements?: PopupTriggerMap
+  // set by useHover when safePolygon's document mousemove handler is active.
+  // checked by onLeaveReference fallback timer to avoid racing safePolygon.
+  handleCloseActiveRef?: RefObject<boolean>
+}
+
+export type Delay =
+  | number
+  | Partial<{
+      open: number
+      close: number
+    }>
+
+export interface UseHoverProps {
+  enabled?: boolean
+  delay?: Delay
+  restMs?: number
+  move?: boolean
+  handleClose?: HandleCloseFn | null
+  mouseOnly?: boolean
+}
+
+// called once on mouseleave with the leave position, returns a handler
+// that runs on each subsequent document mousemove event. the returned
+// handler has the original leave x/y baked into its closure so the
+// polygon anchor stays fixed.
+export type HandleCloseFn = {
+  (context: {
+    x: number
+    y: number
+    placement: string
+    elements: {
+      reference: Element
+      floating: HTMLElement
+      domReference: Element
+    }
+    onClose: () => void
+    tree?: any
+    leave?: boolean
+  }): (event: MouseEvent) => void
+  __options?: SafePolygonOptions
+}
+
+export interface SafePolygonOptions {
+  requireIntent?: boolean
+  buffer?: number
+  blockPointerEvents?: boolean
+  /** render the safe polygon on screen for debugging */
+  __debug?: boolean
+}
+
+export interface UseFocusProps {
+  enabled?: boolean
+  visibleOnly?: boolean
+}
+
+export interface UseRoleProps {
+  enabled?: boolean
+  role?:
+    | 'dialog'
+    | 'tooltip'
+    | 'alertdialog'
+    | 'menu'
+    | 'listbox'
+    | 'grid'
+    | 'tree'
+    | 'select'
+    | 'combobox'
+    | 'label'
+}
+
+export interface UseClickProps {
+  enabled?: boolean
+  event?: 'click' | 'mousedown'
+  toggle?: boolean
+  ignoreMouse?: boolean
+  keyboardHandlers?: boolean
+  stickIfOpen?: boolean
+}
+
+export interface UseListNavigationProps {
+  listRef: RefObject<Array<HTMLElement | null>>
+  activeIndex: number | null
+  selectedIndex?: number | null
+  onNavigate?: (index: number | null) => void
+  enabled?: boolean
+  loop?: boolean
+  nested?: boolean
+  rtl?: boolean
+  virtual?: boolean
+  focusItemOnOpen?: boolean | 'auto'
+  focusItemOnHover?: boolean
+  openOnArrowKeyDown?: boolean
+  scrollItemIntoView?: boolean | ScrollIntoViewOptions
+  allowEscape?: boolean
+  orientation?: 'vertical' | 'horizontal' | 'both'
+  disabledIndices?: Array<number> | ((index: number) => boolean)
+  cols?: number
+}
+
+export interface UseTypeaheadProps {
+  listRef: RefObject<Array<string | null>>
+  activeIndex: number | null
+  selectedIndex?: number | null
+  onMatch?: (index: number) => void
+  onTypingChange?: (isTyping: boolean) => void
+  enabled?: boolean
+  findMatch?:
+    | null
+    | ((list: Array<string | null>, typedString: string) => string | null | undefined)
+  resetMs?: number
+  ignoreKeys?: string[]
+}
+
+export interface UseInnerOffsetProps {
+  enabled?: boolean
+  onChange: (offset: number | ((prev: number) => number)) => void
+  overflowRef: RefObject<any>
+  scrollRef?: RefObject<HTMLElement | null>
+}

package/src/interactions/useClick.ts

@@ -0,0 +1,148 @@
+import { useMemo, useRef } from 'react'
+import { isHTMLElement, isMouseLikePointerType, isTypeableElement } from './utils'
+import type { ElementProps, FloatingInteractionContext, UseClickProps } from './types'
+
+function isButtonTarget(event: React.KeyboardEvent<Element>) {
+  return isHTMLElement(event.target) && event.target.tagName === 'BUTTON'
+}
+
+function isAnchorTarget(event: React.KeyboardEvent<Element>) {
+  return isHTMLElement(event.target) && event.target.tagName === 'A'
+}
+
+function isSpaceIgnored(element: Element | null) {
+  return isTypeableElement(element)
+}
+
+// click interaction: toggles open state on click/mousedown
+export function useClick(
+  context: FloatingInteractionContext,
+  props: UseClickProps = {}
+): ElementProps {
+  const {
+    open,
+    onOpenChange,
+    dataRef,
+    elements: { domReference },
+  } = context
+  const {
+    enabled = true,
+    event: eventOption = 'click',
+    toggle = true,
+    ignoreMouse = false,
+    keyboardHandlers = true,
+    stickIfOpen = true,
+  } = props
+
+  const pointerTypeRef = useRef<'mouse' | 'pen' | 'touch' | undefined>(undefined)
+  const didKeyDownRef = useRef(false)
+
+  const reference: ElementProps['reference'] = useMemo(
+    () => ({
+      onPointerDown(event: any) {
+        pointerTypeRef.current = event.pointerType
+      },
+      onMouseDown(event: any) {
+        const pointerType = pointerTypeRef.current
+
+        // ignore all buttons except for the "main" button
+        if (event.button !== 0) return
+        if (eventOption === 'click') return
+        if (isMouseLikePointerType(pointerType, true) && ignoreMouse) return
+
+        if (
+          open &&
+          toggle &&
+          (dataRef.current.openEvent && stickIfOpen
+            ? dataRef.current.openEvent.type === 'mousedown'
+            : true)
+        ) {
+          onOpenChange(false, event.nativeEvent || event, 'click')
+        } else {
+          // prevent stealing focus from the floating element
+          event.preventDefault()
+          onOpenChange(true, event.nativeEvent || event, 'click')
+        }
+      },
+      onClick(event: any) {
+        const pointerType = pointerTypeRef.current
+
+        if (eventOption === 'mousedown' && pointerTypeRef.current) {
+          pointerTypeRef.current = undefined
+          return
+        }
+
+        if (isMouseLikePointerType(pointerType, true) && ignoreMouse) return
+
+        if (
+          open &&
+          toggle &&
+          (dataRef.current.openEvent && stickIfOpen
+            ? dataRef.current.openEvent.type === 'click'
+            : true)
+        ) {
+          onOpenChange(false, event.nativeEvent || event, 'click')
+        } else {
+          onOpenChange(true, event.nativeEvent || event, 'click')
+        }
+      },
+      onKeyDown(event: any) {
+        pointerTypeRef.current = undefined
+
+        if (event.defaultPrevented || !keyboardHandlers || isButtonTarget(event)) {
+          return
+        }
+
+        if (event.key === ' ' && !isSpaceIgnored(domReference)) {
+          // prevent scrolling
+          event.preventDefault()
+          didKeyDownRef.current = true
+        }
+
+        if (isAnchorTarget(event)) {
+          return
+        }
+
+        if (event.key === 'Enter') {
+          if (open && toggle) {
+            onOpenChange(false, event.nativeEvent || event, 'click')
+          } else {
+            onOpenChange(true, event.nativeEvent || event, 'click')
+          }
+        }
+      },
+      onKeyUp(event: any) {
+        if (
+          event.defaultPrevented ||
+          !keyboardHandlers ||
+          isButtonTarget(event) ||
+          isSpaceIgnored(domReference)
+        ) {
+          return
+        }
+
+        if (event.key === ' ' && didKeyDownRef.current) {
+          didKeyDownRef.current = false
+          if (open && toggle) {
+            onOpenChange(false, event.nativeEvent || event, 'click')
+          } else {
+            onOpenChange(true, event.nativeEvent || event, 'click')
+          }
+        }
+      },
+    }),
+    [
+      dataRef,
+      domReference,
+      eventOption,
+      ignoreMouse,
+      keyboardHandlers,
+      onOpenChange,
+      open,
+      stickIfOpen,
+      toggle,
+    ]
+  )
+
+  return useMemo(() => (enabled ? { reference } : {}), [enabled, reference])
+}

package/src/interactions/useDelayGroup.ts

@@ -0,0 +1,114 @@
+import * as React from 'react'
+import type { Delay, FloatingInteractionContext } from './types'
+
+type DelayGroupContextValue = {
+  currentId: string | null | undefined
+  setCurrentId: (id: string | null | undefined) => void
+  delay: Delay
+  timeoutMs: number
+  initialDelay: Delay
+}
+
+const DelayGroupContext = React.createContext<DelayGroupContextValue>({
+  currentId: null,
+  setCurrentId: () => {},
+  delay: 0,
+  timeoutMs: 0,
+  initialDelay: 0,
+})
+
+export function useDelayGroupContext() {
+  return React.useContext(DelayGroupContext)
+}
+
+// provider for coordinated tooltip delay.
+// when one tooltip is already open (currentId is set), subsequent tooltips
+// in the group open instantly instead of with the configured delay.
+export function FloatingDelayGroup({
+  children,
+  delay,
+  timeoutMs = 0,
+}: {
+  children: React.ReactNode
+  delay: Delay
+  timeoutMs?: number
+}) {
+  const [currentId, setCurrentIdRaw] = React.useState<string | null | undefined>(null)
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout>>(undefined)
+
+  const setCurrentId = React.useCallback(
+    (id: string | null | undefined) => {
+      clearTimeout(timeoutRef.current)
+      if (id == null && timeoutMs > 0) {
+        // delay clearing so moving between tooltips stays instant
+        timeoutRef.current = setTimeout(() => {
+          setCurrentIdRaw(null)
+        }, timeoutMs)
+      } else {
+        setCurrentIdRaw(id)
+      }
+    },
+    [timeoutMs]
+  )
+
+  React.useEffect(() => {
+    return () => clearTimeout(timeoutRef.current)
+  }, [])
+
+  const value = React.useMemo(
+    () => ({
+      currentId,
+      setCurrentId,
+      delay,
+      timeoutMs,
+      initialDelay: delay,
+    }),
+    [currentId, setCurrentId, delay, timeoutMs]
+  )
+
+  return React.createElement(DelayGroupContext.Provider, { value }, children)
+}
+
+// registers a tooltip with the delay group.
+// returns coordinated delay: instant open when another tooltip in the group is showing.
+export function useDelayGroup(
+  context: FloatingInteractionContext,
+  options: { id?: string } = {}
+): { delay: Delay; currentId: string | null | undefined } {
+  const { id } = options
+  const groupContext = React.useContext(DelayGroupContext)
+
+  // when this tooltip closes, start the timeout to clear the group
+  React.useEffect(() => {
+    if (!context.open && groupContext.currentId === id) {
+      groupContext.setCurrentId(null)
+    }
+  }, [context.open, id])
+
+  // when another tooltip in the group opens (currentId changed to someone else),
+  // close this one so only one tooltip is visible at a time
+  React.useEffect(() => {
+    if (groupContext.currentId != null && groupContext.currentId !== id && context.open) {
+      context.onOpenChange(false)
+    }
+  }, [groupContext.currentId, id, context.open])
+
+  // if another tooltip is currently open (currentId is set and not us),
+  // use instant delay for opening
+  if (groupContext.currentId != null) {
+    return {
+      delay: { open: 1, close: getClose(groupContext.initialDelay) },
+      currentId: groupContext.currentId,
+    }
+  }
+
+  return {
+    delay: groupContext.initialDelay,
+    currentId: groupContext.currentId,
+  }
+}
+
+function getClose(delay: Delay): number {
+  if (typeof delay === 'number') return delay
+  return delay?.close ?? 0
+}

package/src/interactions/useFocus.ts

@@ -0,0 +1,164 @@
+import { useEffect, useMemo, useRef } from 'react'
+
+import type {
+  ElementProps,
+  FloatingInteractionContext,
+  OpenChangeReason,
+  UseFocusProps,
+} from './types'
+import {
+  activeElement,
+  clearTimeoutIfSet,
+  contains,
+  getDocument,
+  getTarget,
+  isElement,
+  isHTMLElement,
+  isMac,
+  isSafari,
+  isTypeableElement,
+  matchesFocusVisible,
+} from './utils'
+
+function isMacSafari() {
+  return isMac() && isSafari()
+}
+
+// focus interaction: opens on focus, closes on blur.
+// ported from floating-ui/react useFocus hook with adaptations for our context.
+export function useFocus(
+  context: FloatingInteractionContext,
+  props: UseFocusProps = {}
+): ElementProps {
+  const { open, onOpenChange, events, dataRef, elements } = context
+  const { enabled = true, visibleOnly = true } = props
+
+  const blockFocusRef = useRef(false)
+  const timeoutRef = useRef(-1)
+  const keyboardModalityRef = useRef(true)
+
+  // if the reference was focused and the user left the tab/window, and the
+  // floating element was not open, block focus when they return.
+  // also tracks keyboard vs pointer modality on mac safari.
+  useEffect(() => {
+    if (!enabled) return
+
+    const win = getDocument(elements.domReference).defaultView || window
+
+    function onBlur() {
+      if (
+        !open &&
+        isHTMLElement(elements.domReference) &&
+        elements.domReference === activeElement(getDocument(elements.domReference))
+      ) {
+        blockFocusRef.current = true
+      }
+    }
+
+    function onKeyDown() {
+      keyboardModalityRef.current = true
+    }
+
+    function onPointerDown() {
+      keyboardModalityRef.current = false
+    }
+
+    win.addEventListener('blur', onBlur)
+
+    if (isMacSafari()) {
+      win.addEventListener('keydown', onKeyDown, true)
+      win.addEventListener('pointerdown', onPointerDown, true)
+    }
+
+    return () => {
+      win.removeEventListener('blur', onBlur)
+
+      if (isMacSafari()) {
+        win.removeEventListener('keydown', onKeyDown, true)
+        win.removeEventListener('pointerdown', onPointerDown, true)
+      }
+    }
+  }, [elements.domReference, open, enabled])
+
+  // block focus after reference-press or escape-key close,
+  // so that focus returning to the trigger doesn't reopen
+  useEffect(() => {
+    if (!enabled) return
+    if (!events) return
+
+    function handleOpenChange({ reason }: { reason: OpenChangeReason }) {
+      if (reason === 'reference-press' || reason === 'escape-key') {
+        blockFocusRef.current = true
+      }
+    }
+
+    events.on('openchange', handleOpenChange)
+    return () => {
+      events.off('openchange', handleOpenChange)
+    }
+  }, [events, enabled])
+
+  // cleanup timeout on unmount
+  useEffect(() => {
+    return () => {
+      clearTimeoutIfSet(timeoutRef)
+    }
+  }, [])
+
+  const reference: ElementProps['reference'] = useMemo(
+    () => ({
+      onMouseLeave() {
+        blockFocusRef.current = false
+      },
+      onFocus(event: any) {
+        if (blockFocusRef.current) return
+
+        const target = getTarget(event.nativeEvent)
+
+        if (visibleOnly && isElement(target)) {
+          // safari fails to match :focus-visible if focus was initially
+          // outside the document
+          if (isMacSafari() && !event.relatedTarget) {
+            if (!keyboardModalityRef.current && !isTypeableElement(target)) {
+              return
+            }
+          } else if (!matchesFocusVisible(target)) {
+            return
+          }
+        }
+
+        onOpenChange(true, event.nativeEvent, 'focus')
+      },
+      onBlur(event: any) {
+        blockFocusRef.current = false
+        const relatedTarget = event.relatedTarget as Element | null
+        const nativeEvent = event.nativeEvent
+
+        // wait for the window blur listener to fire
+        timeoutRef.current = window.setTimeout(() => {
+          const activeEl = activeElement(
+            elements.domReference ? elements.domReference.ownerDocument : document
+          )
+
+          // focus left the page, keep it open
+          if (!relatedTarget && activeEl === elements.domReference) return
+
+          // when focusing the reference element then clicking into the floating
+          // element, prevent it from hiding. we check activeElement rather than
+          // relatedTarget to handle shadow DOM correctly.
+          if (
+            contains(context.refs.floating.current, activeEl) ||
+            contains(elements.domReference, activeEl)
+          ) {
+            return
+          }
+
+          onOpenChange(false, nativeEvent, 'focus')
+        })
+      },
+    }),
+    [context.refs.floating, elements.domReference, onOpenChange, visibleOnly]
+  )
+
+  return useMemo(() => (enabled ? { reference } : {}), [enabled, reference])
+}