diff --git a/docs/docs/accessibility.mdx b/docs/docs/accessibility.mdx index a00e3995..1fe278ee 100644 --- a/docs/docs/accessibility.mdx +++ b/docs/docs/accessibility.mdx @@ -43,7 +43,7 @@ The rest of this page shows how each of these maps to ReactTooltip props and mar :::info -ReactTooltip already opens the tooltip when the anchor receives keyboard focus (not just on hover), so most of the work is making sure your anchor is focusable and correctly associated with the tooltip. +ReactTooltip opens the tooltip when the anchor receives keyboard focus (`:focus-visible`), not only on hover. Focus moved by a script, or focus the browser restores when you return to the window, does not open it. Most of the remaining work is making sure your anchor is focusable and correctly associated with the tooltip. ::: @@ -72,7 +72,7 @@ Users must be able to close the tooltip without moving the pointer or focus. Ena ## Keyboard-accessible anchor (2.1.1) -ReactTooltip opens the tooltip when the anchor receives focus, but only focusable elements can receive keyboard focus. Interactive elements such as ``, ` + ), + }) + + const anchor = screen.getByRole('button', { name: 'Model' }) + + act(() => { + anchor.focus() + }) + await waitForTooltip('restore-focus') + act(() => { + jest.advanceTimersByTime(30) + }) + expect(describedBy(anchor)).toContain('restore-focus') + + act(() => { + fireEvent.mouseOut(anchor, { relatedTarget: document.body }) + }) + await waitForTooltipToStopShowing('restore-focus') + act(() => { + jest.runOnlyPendingTimers() + }) + expect(describedBy(anchor)).not.toContain('restore-focus') + expect(document.activeElement).toBe(anchor) + + act(() => { + window.dispatchEvent(new Event('blur')) + window.dispatchEvent(new Event('focus')) + fireEvent.focus(anchor) + jest.advanceTimersByTime(30) + }) + + expect(describedBy(anchor)).not.toContain('restore-focus') + }) + + test('does not reopen an open tooltip when the window regains focus', async () => { + renderTip({ + id: 'restore-open', + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + act(() => { + anchor.focus() + }) + await waitForTooltip('restore-open') + act(() => { + jest.advanceTimersByTime(30) + }) + expect(describedBy(anchor)).toContain('restore-open') + + act(() => { + window.dispatchEvent(new Event('blur')) + fireEvent.focusOut(anchor) + }) + act(() => { + jest.runOnlyPendingTimers() + }) + act(() => { + jest.runOnlyPendingTimers() + }) + expect(document.getElementById('restore-open')).not.toBeInTheDocument() + expect(describedBy(anchor)).not.toContain('restore-open') + + act(() => { + window.dispatchEvent(new Event('focus')) + fireEvent.focus(anchor) + jest.advanceTimersByTime(30) + }) + expect(describedBy(anchor)).not.toContain('restore-open') + }) + + test('opens when focus moves from a non-anchor onto an anchor within the show debounce', () => { + renderTip({ + id: 'tab-sequence', + children: ( + <> + + + + ), + }) + const other = screen.getByRole('button', { name: 'Other' }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + act(() => { + fireEvent.focus(other) + fireEvent.focus(anchor) + jest.advanceTimersByTime(30) + }) + + expect(describedBy(anchor)).toContain('tab-sequence') + }) + + test('does not keep blocking focus when the window never fires focus', async () => { + renderTip({ + id: 'restore-no-window-focus', + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + act(() => { + anchor.focus() + }) + await waitForTooltip('restore-no-window-focus') + act(() => { + fireEvent.mouseOut(anchor, { relatedTarget: document.body }) + jest.runOnlyPendingTimers() + }) + + act(() => { + window.dispatchEvent(new Event('blur')) + fireEvent.focus(anchor) + jest.advanceTimersByTime(30) + }) + expect(describedBy(anchor)).not.toContain('restore-no-window-focus') + + focusAndFlush(anchor) + expect(describedBy(anchor)).toContain('restore-no-window-focus') + }) + + test('stops ignoring the anchor after focus moves somewhere else', async () => { + renderTip({ + id: 'restore-moved', + children: ( + <> + + + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + const other = screen.getByRole('button', { name: 'Other' }) + + act(() => { + anchor.focus() + }) + await waitForTooltip('restore-moved') + act(() => { + fireEvent.mouseOut(anchor, { relatedTarget: document.body }) + jest.runOnlyPendingTimers() + }) + + act(() => { + window.dispatchEvent(new Event('blur')) + other.focus() + jest.runOnlyPendingTimers() + }) + + focusAndFlush(anchor) + expect(describedBy(anchor)).toContain('restore-moved') + }) + + test('opens on a later focus after an ignored window restore', async () => { + renderTip({ + id: 'restore-later', + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + act(() => { + anchor.focus() + }) + await waitForTooltip('restore-later') + act(() => { + fireEvent.mouseOut(anchor, { relatedTarget: document.body }) + jest.runOnlyPendingTimers() + }) + + act(() => { + window.dispatchEvent(new Event('blur')) + window.dispatchEvent(new Event('focus')) + fireEvent.focus(anchor) + jest.runOnlyPendingTimers() + }) + expect(describedBy(anchor)).not.toContain('restore-later') + + focusAndFlush(anchor) + expect(describedBy(anchor)).toContain('restore-later') + }) + + test('does not open when programmatic focus is not :focus-visible', () => { + installBrowserFocusVisible(() => false) + renderTip({ + id: 'programmatic-focus', + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + focusAndFlush(anchor) + + expect(describedBy(anchor)).not.toContain('programmatic-focus') + }) + + test('opens for keyboard focus that matches :focus-visible', () => { + installBrowserFocusVisible(() => true) + renderTip({ + id: 'keyboard-focus', + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + focusAndFlush(anchor) + + expect(describedBy(anchor)).toContain('keyboard-focus') + }) + + test('opens for :focus-visible on a control inside the anchor', () => { + installBrowserFocusVisible((element) => element.tagName === 'BUTTON') + renderTip({ + id: 'inner-focus', + children: ( +
+ Wrapper + +
+ ), + }) + const anchor = screen.getByText('Wrapper').closest('div') + const inner = screen.getByRole('button', { name: 'Inner' }) + + focusAndFlush(inner) + + expect(describedBy(anchor)).toContain('inner-focus') + }) + + test('openEvents focus true still opens when focus is not :focus-visible', () => { + installBrowserFocusVisible(() => false) + renderTip({ + id: 'any-focus', + openEvents: { focus: true }, + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + focusAndFlush(anchor) + + expect(describedBy(anchor)).toContain('any-focus') + }) + + test("openEvents focus 'visible' does not open on programmatic focus", () => { + installBrowserFocusVisible(() => false) + renderTip({ + id: 'visible-focus', + openEvents: { focus: 'visible', mouseenter: true }, + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + focusAndFlush(anchor) + + expect(describedBy(anchor)).not.toContain('visible-focus') + }) + + test('Mac Safari ignores pointer focus from outside the document', () => { + installMacSafari() + renderTip({ + id: 'safari-pointer', + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + act(() => { + fireEvent.pointerDown(anchor) + }) + focusAndFlush(anchor, { relatedTarget: null }) + + expect(describedBy(anchor)).not.toContain('safari-pointer') + }) + + test('Mac Safari opens keyboard focus from outside the document', () => { + installMacSafari() + renderTip({ + id: 'safari-key', + children: ( + + ), + }) + const anchor = screen.getByRole('button', { name: 'Model' }) + + act(() => { + fireEvent.keyDown(anchor, { key: 'Tab' }) + }) + focusAndFlush(anchor, { relatedTarget: null }) + + expect(describedBy(anchor)).toContain('safari-key') + }) + + test('Mac Safari still opens pointer focus on a text field', () => { + installMacSafari() + renderTip({ + id: 'safari-input', + children: , + }) + const anchor = screen.getByRole('textbox', { name: 'Name' }) + + act(() => { + fireEvent.pointerDown(anchor) + }) + focusAndFlush(anchor, { relatedTarget: null }) + + expect(describedBy(anchor)).toContain('safari-input') + }) +})