\n *\n * Adapted from Fluid Functionalism's use-fluid-hover and fluid-hover-highlight by Micka Touillaud (MIT),\n * https://github.com/mickadesign/fluid-functionalism. Items are found by a selector instead of registering themselves,\n * so a component adopts it without changing its items.\n */\nimport { useEffect, useEffectEvent, useRef, useState } from \"react\";\nimport type { FocusEvent, MouseEvent, PointerEvent, RefObject } from \"react\";\nimport { AnimatePresence, motion, useReducedMotion } from \"motion/react\";\nimport { motionTokens } from \"./motion-tokens\";\n\n/** An item's box in the container's own layout space (unaffected by transforms or scrolling). */\nexport interface FluidRect { top: number; left: number; width: number; height: number }\n\nexport interface FluidHoverState {\n /** Where the highlight sits, or null when nothing is lit. */\n rect: FluidRect | null;\n /** The lit item. */\n item: HTMLElement | null;\n /** False when the highlight should jump (keyboard, a resize) rather than travel. */\n glide: boolean;\n /** Steps on each new pointer entry, so the highlight fades in where it lands. */\n session: number;\n}\n\nexport interface FluidHoverOptions {\n /** Selector for the items inside the container. */\n items: string;\n /** \"y\" for lists (default), \"x\" for a row of tabs, \"xy\" for grids. */\n axis?: \"x\" | \"y\" | \"xy\";\n /** Items the highlight skips (and a gap click never activates). Defaults to disabled or aria-disabled items. */\n isItemDisabled?: (item: HTMLElement) => boolean;\n /** \"skip\" (default) lights the nearest enabled item even over a disabled one; \"clear\" lights nothing over a disabled item (a calendar's unavailable days). */\n disabled?: \"skip\" | \"clear\";\n /** Route a click in a gap to the lit item. On by default; turn it off where empty space should stay inert. */\n gapClick?: boolean;\n /** Light the item that receives keyboard focus. On by default. */\n followFocus?: boolean;\n}\n\nconst defaultDisabled = (item: HTMLElement) =>\n item.matches(\":disabled, [aria-disabled='true'], [data-disabled]\");\n\n/** Controls that sit between items keep their own clicks. */\nconst CONTROL = \"input, textarea, select, button, a, summary, [contenteditable], [role='textbox'], [role='searchbox'], [role='button']\";\n\n/** The item's box relative to the container, summing offsets through positioned ancestors in between. */\nexport function rectOf(item: HTMLElement, container: HTMLElement): FluidRect {\n let top = item.offsetTop, left = item.offsetLeft;\n let parent = item.offsetParent as HTMLElement | null;\n while (parent && parent !== container && container.contains(parent)) {\n top += parent.offsetTop + parent.clientTop;\n left += parent.offsetLeft + parent.clientLeft;\n parent = parent.offsetParent as HTMLElement | null;\n }\n return { top, left, width: item.offsetWidth, height: item.offsetHeight };\n}\n\n/**\n * The item the pointer is inside, or else the one whose edge is nearest along the axis (both axes for a grid). Edges, not\n * centres, so a gap next to a wide item still lights the item the pointer is closer to.\n */\nexport function pickNearest(items: HTMLElement[], x: number, y: number, axis: \"x\" | \"y\" | \"xy\"): HTMLElement | null {\n let nearest: HTMLElement | null = null, best = Infinity;\n for (const item of items) {\n const r = item.getBoundingClientRect();\n if (!r.width && !r.height) continue;\n if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return item;\n const dx = Math.max(r.left - x, 0, x - r.right), dy = Math.max(r.top - y, 0, y - r.bottom);\n const distance = axis === \"x\" ? dx : axis === \"y\" ? dy : Math.hypot(dx, dy);\n if (distance < best) { best = distance; nearest = item; }\n }\n return nearest;\n}\n\n/** Hands a gap click to the item as a real mouse click (detail, modifiers and coordinates kept), so the item reads it as a pointer press, not a keyboard one. */\nfunction forwardClick(item: HTMLElement, event: MouseEvent) {\n const { detail, clientX, clientY, screenX, screenY, ctrlKey, shiftKey, altKey, metaKey, button, buttons } = event;\n item.dispatchEvent(new globalThis.MouseEvent(\"click\", { bubbles: true, cancelable: true, composed: true, view: window, detail, clientX, clientY, screenX, screenY, ctrlKey, shiftKey, altKey, metaKey, button, buttons }));\n}\n\n/** Whether an event happened inside the element whose handler hears it, not in a portalled child (a submenu, a tooltip). */\nconst isOwn = (event: { currentTarget: EventTarget; target: EventTarget }) =>\n !(event.currentTarget instanceof Node) || !(event.target instanceof Node) || event.currentTarget.contains(event.target);\n\nexport function useFluidHover(container: RefObject, options: FluidHoverOptions) {\n const { items: selector, axis = \"y\", isItemDisabled = defaultDisabled, disabled = \"skip\", gapClick = true, followFocus = true } = options;\n const [state, setState] = useState({ rect: null, item: null, glide: false, session: 0 });\n const current = useRef(state);\n const pointer = useRef(false);\n const entering = useRef(false);\n const frame = useRef(0);\n\n function commit(next: FluidHoverState) {\n const prev = current.current;\n if (prev.item === next.item && prev.session === next.session && sameRect(prev.rect, next.rect)) return;\n current.current = next;\n setState(next);\n }\n\n function light(item: HTMLElement | null, glide: boolean) {\n const root = container.current;\n if (!root || !item) return commit({ ...current.current, rect: null, item: null, glide });\n let session = current.current.session;\n if (entering.current) { entering.current = false; session += 1; }\n commit({ rect: rectOf(item, root), item, glide: glide && session === current.current.session, session });\n }\n\n const enabledItems = () => {\n const root = container.current;\n return root ? [...root.querySelectorAll(selector)].filter(item => !isItemDisabled(item)) : [];\n };\n\n // The lit item can move under a still highlight (a resize, content above it changing): follow it without travel.\n const follow = useEffectEvent(() => { const { item } = current.current; if (item?.isConnected) light(item, false); });\n useEffect(() => {\n const root = container.current;\n if (!root || typeof ResizeObserver === \"undefined\") return;\n const observer = new ResizeObserver(() => follow());\n observer.observe(root);\n return () => observer.disconnect();\n }, [container]);\n useEffect(() => () => cancelAnimationFrame(frame.current), []);\n\n const handlers = {\n onMouseEnter: () => { entering.current = true; },\n onMouseMove: (event: MouseEvent) => {\n if (!isOwn(event)) return;\n pointer.current = true;\n const { clientX, clientY } = event;\n cancelAnimationFrame(frame.current);\n frame.current = requestAnimationFrame(() => {\n const over = disabled === \"clear\" ? document.elementFromPoint(clientX, clientY)?.closest(selector) : null;\n light(over && isItemDisabled(over) ? null : pickNearest(enabledItems(), clientX, clientY, axis), true);\n });\n },\n onMouseLeave: () => { cancelAnimationFrame(frame.current); entering.current = false; light(null, false); },\n onKeyDownCapture: () => { pointer.current = false; },\n onFocus: (event: FocusEvent) => {\n if (!followFocus || pointer.current || !isOwn(event)) return;\n const item = event.target instanceof HTMLElement ? event.target.closest(selector) : null;\n if (item && container.current?.contains(item) && !isItemDisabled(item)) light(item, false);\n },\n onBlur: (event: FocusEvent) => {\n if (!pointer.current && !event.currentTarget.contains(event.relatedTarget as Node | null)) light(null, false);\n },\n onClick: (event: MouseEvent) => {\n if (!gapClick || !isOwn(event)) return;\n const target = event.target as Element;\n if (!target.isConnected || target.closest(selector) || target.closest(CONTROL)) return;\n const { item } = current.current;\n if (item?.isConnected && !isItemDisabled(item)) forwardClick(item, event);\n },\n };\n\n /** Clears the highlight at once, such as when a menu opens again. */\n const reset = () => { cancelAnimationFrame(frame.current); entering.current = true; light(null, false); };\n\n return { ...state, handlers, reset, light };\n}\n\nexport interface NearestItemOptions extends Omit {\n /** Called with the nearest enabled item as the mouse moves over the container. */\n onPick: (item: HTMLElement) => void;\n}\n\n/**\n * Fluid hover's picking without its highlight, for a list that already keeps its own active item and highlight (a listbox\n * with aria-activedescendant, a roving list): the mouse picks the nearest enabled item, gaps and padding included, and a\n * click in a gap goes to that item. Spread the result on the container.\n */\n// A hook only so callbacks that touch refs can be passed during render; it keeps no state.\nexport function useNearestItem({ items: selector, axis = \"y\", isItemDisabled = defaultDisabled, gapClick = true, onPick }: NearestItemOptions) {\n const nearest = (event: MouseEvent) => {\n if (!isOwn(event)) return null;\n const items = [...event.currentTarget.querySelectorAll(selector)].filter(item => !isItemDisabled(item));\n return pickNearest(items, event.clientX, event.clientY, axis);\n };\n return {\n onPointerMove: (event: PointerEvent) => { if (event.pointerType !== \"mouse\") return; const item = nearest(event); if (item) onPick(item); },\n onClick: (event: MouseEvent) => {\n if (!gapClick) return;\n const target = event.target as Element;\n if (!target.isConnected || target.closest(selector) || target.closest(CONTROL)) return;\n const item = nearest(event);\n if (item) forwardClick(item, event);\n },\n };\n}\n\nconst sameRect = (a: FluidRect | null, b: FluidRect | null) =>\n a === b || (!!a && !!b && a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height);\n\nexport interface FluidHoverHighlightProps {\n /** The state from useFluidHover (or any { rect, glide, session }). */\n hover: Pick;\n /** Radius, fill, z-index. The container must be position: relative; the highlight is placed at its top-left corner. */\n className?: string;\n /** Extra attributes for styling, such as data-tone. */\n tone?: string;\n}\n\n/** The one highlight a fluid hover set renders: it springs between items on transforms, and fades in and out. */\nexport function FluidHoverHighlight({ hover, className, tone }: FluidHoverHighlightProps) {\n const reduced = useReducedMotion() ?? false;\n const { rect, glide, session } = hover;\n const place = rect ? { x: rect.left, y: rect.top, width: rect.width, height: rect.height } : undefined;\n return (\n \n {place ? (\n \n ) : null}\n \n );\n}\n"}],"docs":"Docs and live preview: https://ui.teamofsilicons.com/multi-select","meta":{"tier":"free","kind":"component","docs":"https://ui.teamofsilicons.com/multi-select","markdown":"https://ui.teamofsilicons.com/multi-select.md","tags":["field","choice"],"status":"stable"}}