// Link // // The `` element's offset is based on the `

` // and not the body as the user sees it relative to the viewport. // So you have to traverse the offsets till you get to the root. function getOffset(element: HTMLElement) { let top = element.offsetTop let left = element.offsetLeft let offsetParent = element.offsetParent as HTMLElement | null while (offsetParent) { left += offsetParent.offsetLeft top += offsetParent.offsetTop offsetParent = offsetParent.offsetParent as HTMLElement | null } return [top, left] } function getBoundingOffset(element: HTMLElement) { const { top, left } = element.getBoundingClientRect() return [top, left] } function popoverShow(target: HTMLLinkElement, callback?: (popover: HTMLDivElement) => void) { if (popoverStartTimer) { window.clearTimeout(popoverStartTimer) } // The mouse has been moved over a link. If this is the "first time", // we want to delay showing the popover because it could be that the // *intention* of the user was not to hover over, but they might have // just moved the mouse over the link by "accident", or in a hurry // on their way to something else. // However, if they hover over the link because the popover is already // open, which happens when you hover over the popover and back again // to the link, then we don't want any delay. if (target === currentlyOpen) { popoverWrap(target, callback) } else { popoverStartTimer = window.setTimeout(() => { popoverWrap(target, callback) currentlyOpen = target }, DELAY_SHOW) } } function popoverHide() { // Important to use `window.setTimeout` instead of `setTimeout` so // that TypeScript knows which kind of timeout we're talking about. // If you use plain `setTimeout` TypeScript might think it's a // Node eventloop kinda timer. if (popoverStartTimer) { window.clearTimeout(popoverStartTimer) } popoverCloseTimer = window.setTimeout(() => { const popover = getOrCreatePopoverGlobal() popover.style.display = 'none' // Reset because we're closing the popover, so we have to start from afresh. currentlyOpen = null }, DELAY_HIDE) } let lastFocussedLink: HTMLLinkElement | null = null export function LinkPreviewPopover() { // This is to track if the user entirely tabs out of the window. // For example if they go to the address bar. useEffect(() => { function windowBlur() { popoverHide() } window.addEventListener('blur', windowBlur) return () => { window.removeEventListener('blur', windowBlur) } }, []) useEffect(() => { function showPopover(event: MouseEvent) { const target = event.currentTarget as HTMLLinkElement popoverShow(target) // Just in case you *had* used the keyboard shortcut, but now // hovered over something else, reset the last focussed link. lastFocussedLink = null } function hidePopover() { popoverHide() } function keyboardHandler(event: KeyboardEvent) { if (event.key === 'ArrowUp' && event.altKey) { event.preventDefault() const target = event.currentTarget as HTMLLinkElement popoverShow(target, (popover) => { const productHeadingLink = popover.querySelector('.product a') const first = document.getElementById(FIRST_LINK_ID) if (productHeadingLink && first) { first.focus() lastFocussedLink = target } }) } else if (event.key === 'ArrowDown' && event.altKey) { event.preventDefault() popoverHide() } } // Note, this is attached, as an event listener, to the `document` // meaning an Escape event here could be for anything. // But the `popoverHide` function is cheap to call. If the popover // was visible, it's hidden now. If it wasn't visible, nothing happens. // Because we do other things on Escape, we have to make sure that // this Escape was for closing a currently open popover. function escapeHandler(event: KeyboardEvent) { if (event.key === 'Escape') { const popover = getOrCreatePopoverGlobal() if (popover.style.display !== 'none') { popoverHide() // If this is true, the keyboard shortcut was used to open // the popover when the link (that can have a popover) // was used. So upon, Escape go back to focussing on that link. if (lastFocussedLink) { lastFocussedLink.focus() } } } } const links = Array.from( document.querySelectorAll( '#article-contents a[href], #article-intro a[href]', ), ).filter((link) => { // This filters out links that are not internal or in-page // and the ones that are in-page anchor links next to the headings. // Remember that `link.href` is always absolute because it comes // from the DOM. So to test the pathname, we have to parse it // and extract the pathname from the whole URL object. const { pathname } = new URL(link.href) return ( link.href.startsWith(window.location.origin) && !link.classList.contains('heading-link') && !pathname.startsWith('/public/') && !pathname.startsWith('/assets/') && // This skips those ToolPicker links with `data-tool="vscode"` // attribute, for example. !link.dataset.tool && !link.dataset.platform ) }) // Ideally, we'd have an event listener for the entire container and // the filter, at "runtime", within by filtering for the target // elements we're interested in. However, this is not possible // because then when you hover over the text in // a tag like Link the target // element is that of the `STRONG` tag. // The reason it would be better to have a single event listener and // filter is because it would work even if the DOM changes by // adding new `` elements. for (const link of links) { link.addEventListener('mouseover', showPopover) link.addEventListener('mouseout', hidePopover) link.addEventListener('keydown', keyboardHandler) } document.addEventListener('keydown', escapeHandler) return () => { for (const link of links) { link.removeEventListener('mouseover', showPopover) link.removeEventListener('mouseout', hidePopover) link.removeEventListener('keydown', keyboardHandler) } document.removeEventListener('keydown', escapeHandler) } }) // Note that this runs on every single mount return null }