@lovett/ui 0.0.9 → 0.0.11

package/src/__tests__/layer-stack.test.tsx

@@ -0,0 +1,228 @@
+/**
+ * lib/layer-stack — the topmost-wins dismiss order shared by Modal,
+ * DropdownMenu and Popover.
+ *
+ * The load-bearing test is the Modal one: a layer registered AFTER a Modal
+ * opens takes Escape away from it. Revert Modal to a private `openPanels`
+ * array and both fire — that test goes red.
+ */
+import { useEffect } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { render } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import Modal from '../modal'
+import { useEscapeKey, useLayer, type LayerHandle, type LayerKind } from '../lib/layer-stack'
+
+function EscapeListener({
+  onEscape,
+  enabled = true,
+}: {
+  onEscape: () => void
+  enabled?: boolean
+}) {
+  useEscapeKey(onEscape, { enabled })
+  return null
+}
+
+function LayerProbe({
+  kind,
+  onHandle,
+}: {
+  kind: LayerKind
+  onHandle: (handle: LayerHandle) => void
+}) {
+  const handle = useLayer({ enabled: true, kind, onEscape: () => {} })
+  useEffect(() => {
+    onHandle(handle)
+  }, [handle, onHandle])
+  return null
+}
+
+describe('useEscapeKey / useLayer', () => {
+  it('dispatches Escape to the most recently registered layer only', async () => {
+    const first = vi.fn()
+    const second = vi.fn()
+    render(
+      <>
+        <EscapeListener onEscape={first} />
+        <EscapeListener onEscape={second} />
+      </>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(second).toHaveBeenCalledTimes(1)
+    expect(first).not.toHaveBeenCalled()
+  })
+
+  it('falls back to the layer below when the top one unregisters', async () => {
+    const first = vi.fn()
+    const second = vi.fn()
+    const { rerender } = render(
+      <>
+        <EscapeListener onEscape={first} />
+        <EscapeListener onEscape={second} />
+      </>,
+    )
+    rerender(
+      <>
+        <EscapeListener onEscape={first} />
+        <EscapeListener onEscape={second} enabled={false} />
+      </>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(first).toHaveBeenCalledTimes(1)
+    expect(second).not.toHaveBeenCalled()
+  })
+
+  it('does nothing once every layer has unregistered', async () => {
+    const handler = vi.fn()
+    const { unmount } = render(<EscapeListener onEscape={handler} />)
+    unmount()
+    await userEvent.keyboard('{Escape}')
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it('ignores keys other than Escape', async () => {
+    const handler = vi.fn()
+    render(<EscapeListener onEscape={handler} />)
+    await userEvent.keyboard('{Enter}a{Tab}')
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it('stops propagation so window-level listeners do not see a consumed Escape', async () => {
+    const windowSpy = vi.fn()
+    window.addEventListener('keydown', windowSpy)
+    try {
+      const handler = vi.fn()
+      const { unmount } = render(<EscapeListener onEscape={handler} />)
+      await userEvent.keyboard('{Escape}')
+      expect(handler).toHaveBeenCalledTimes(1)
+      expect(windowSpy).not.toHaveBeenCalled()
+
+      // With no layer open the key reaches window as before.
+      unmount()
+      await userEvent.keyboard('{Escape}')
+      expect(windowSpy).toHaveBeenCalledTimes(1)
+    } finally {
+      window.removeEventListener('keydown', windowSpy)
+    }
+  })
+
+  it('reads the latest handler without re-registering (order is preserved)', async () => {
+    const stale = vi.fn()
+    const fresh = vi.fn()
+    const above = vi.fn()
+    const { rerender } = render(
+      <>
+        <EscapeListener onEscape={stale} />
+        <EscapeListener onEscape={above} />
+      </>,
+    )
+    // Swapping the LOWER layer's handler must not move it to the top.
+    rerender(
+      <>
+        <EscapeListener onEscape={fresh} />
+        <EscapeListener onEscape={above} />
+      </>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(above).toHaveBeenCalledTimes(1)
+    expect(stale).not.toHaveBeenCalled()
+    expect(fresh).not.toHaveBeenCalled()
+
+    rerender(
+      <>
+        <EscapeListener onEscape={fresh} />
+        <EscapeListener onEscape={above} enabled={false} />
+      </>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(fresh).toHaveBeenCalledTimes(1)
+    expect(stale).not.toHaveBeenCalled()
+  })
+
+  it('isTop / isTopOfKind: a popover above a modal is top, but not top-of-kind for the modal', () => {
+    let modal: LayerHandle | undefined
+    let popover: LayerHandle | undefined
+    render(
+      <>
+        <LayerProbe kind="modal" onHandle={(h) => (modal = h)} />
+        <LayerProbe kind="popover" onHandle={(h) => (popover = h)} />
+      </>,
+    )
+    expect(popover?.isTop()).toBe(true)
+    expect(popover?.isTopOfKind()).toBe(true)
+    expect(modal?.isTop()).toBe(false)
+    expect(modal?.isTopOfKind()).toBe(true)
+  })
+
+  it('a second modal above the first takes both isTop and isTopOfKind', () => {
+    let lower: LayerHandle | undefined
+    let upper: LayerHandle | undefined
+    render(
+      <>
+        <LayerProbe kind="modal" onHandle={(h) => (lower = h)} />
+        <LayerProbe kind="modal" onHandle={(h) => (upper = h)} />
+      </>,
+    )
+    expect(upper?.isTop()).toBe(true)
+    expect(lower?.isTopOfKind()).toBe(false)
+  })
+
+  it('an unregistered handle answers false everywhere', () => {
+    let handle: LayerHandle | undefined
+    function Disabled() {
+      handle = useLayer({ enabled: false, kind: 'popover', onEscape: () => {} })
+      return null
+    }
+    render(<Disabled />)
+    expect(handle?.isTop()).toBe(false)
+    expect(handle?.isTopOfKind()).toBe(false)
+    expect(handle?.containsInLayerAbove(document.body)).toBe(false)
+  })
+})
+
+describe('shared with Modal', () => {
+  it('a layer opened above a Modal takes Escape; the Modal gets the next one', async () => {
+    const onClose = vi.fn()
+    const onEscape = vi.fn()
+    const { rerender } = render(
+      <>
+        <Modal isOpen onClose={onClose} title="Confirm">
+          body
+        </Modal>
+        <EscapeListener onEscape={onEscape} />
+      </>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(onEscape).toHaveBeenCalledTimes(1)
+    expect(onClose).not.toHaveBeenCalled()
+
+    rerender(
+      <>
+        <Modal isOpen onClose={onClose} title="Confirm">
+          body
+        </Modal>
+        <EscapeListener onEscape={onEscape} enabled={false} />
+      </>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(onClose).toHaveBeenCalledTimes(1)
+    expect(onEscape).toHaveBeenCalledTimes(1)
+  })
+
+  it('a Modal opened above an existing layer takes Escape from it', async () => {
+    const onClose = vi.fn()
+    const onEscape = vi.fn()
+    render(
+      <>
+        <EscapeListener onEscape={onEscape} />
+        <Modal isOpen onClose={onClose} title="Confirm">
+          body
+        </Modal>
+      </>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(onClose).toHaveBeenCalledTimes(1)
+    expect(onEscape).not.toHaveBeenCalled()
+  })
+})

package/src/__tests__/modal.test.tsx

@@ -1,13 +1,17 @@
 /**
  * Modal — 51 consuming files plus 113 sub-component call sites.
  *
- * Note what these tests deliberately do NOT claim: Modal has no
- * role="dialog", no aria-modal, no focus trap and no focus restore, so
- * there is no dialog role to query by. That is a real accessibility gap
- * (a keyboard user can Tab through the page behind the backdrop) and it
- * is tracked separately — these tests pin the behaviour that exists so
- * the a11y work can be verified as a change, not guessed at.
+ * The panel is a role="dialog" aria-modal="true" region: named by its own
+ * <h2> (or the `ariaLabel` prop when titleless), focused on open, focus
+ * RESTORED to the opener on close, and Tab/Shift+Tab wrapped inside it.
+ * The "a11y gap" block that used to stand here — no dialog role, no trap,
+ * no restore — is closed, and the describe() below is what closes it.
+ *
+ * Background inertness is by focus trap, NOT the `inert` attribute: Modal
+ * renders inline inside #root, so inerting the app root would inert the
+ * modal too. See the note in modal.tsx.
  */
+import { useState } from 'react'
 import { describe, expect, it, vi } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
@@ -142,6 +146,176 @@ describe('Modal', () => {
     })
   })
 
+  describe('accessibility', () => {
+    it('exposes the panel as a modal dialog named by its title', () => {
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          body
+        </Modal>,
+      )
+      const dialog = screen.getByRole('dialog', { name: 'Confirm' })
+      expect(dialog).toHaveAttribute('aria-modal', 'true')
+      expect(dialog).toHaveClass('ds-card-surface')
+    })
+
+    it('gives each open modal its own title id', () => {
+      render(
+        <>
+          <Modal isOpen onClose={noop} title="First">
+            a
+          </Modal>
+          <Modal isOpen onClose={noop} title="Second">
+            b
+          </Modal>
+        </>,
+      )
+      const [first, second] = screen.getAllByRole('dialog')
+      expect(first!.getAttribute('aria-labelledby')).not.toBe(
+        second!.getAttribute('aria-labelledby'),
+      )
+      expect(screen.getByRole('dialog', { name: 'First' })).toBeInTheDocument()
+      expect(screen.getByRole('dialog', { name: 'Second' })).toBeInTheDocument()
+    })
+
+    it('falls back to ariaLabel when there is no title', () => {
+      render(
+        <Modal isOpen onClose={noop} title="" ariaLabel="Asset details">
+          body
+        </Modal>,
+      )
+      const dialog = screen.getByRole('dialog', { name: 'Asset details' })
+      expect(dialog).not.toHaveAttribute('aria-labelledby')
+    })
+
+    it('moves focus to the panel on open', () => {
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <button type="button">Inside</button>
+        </Modal>,
+      )
+      expect(document.activeElement).toBe(screen.getByRole('dialog'))
+    })
+
+    it('honours a [data-autofocus] control', () => {
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <input data-autofocus aria-label="Name" />
+        </Modal>,
+      )
+      expect(document.activeElement).toBe(screen.getByRole('textbox'))
+    })
+
+    it('restores focus to the opener on close', async () => {
+      function Harness() {
+        const [open, setOpen] = useState(false)
+        return (
+          <>
+            <button type="button" onClick={() => setOpen(true)}>
+              Open
+            </button>
+            <Modal isOpen={open} onClose={() => setOpen(false)} title="Confirm">
+              body
+            </Modal>
+          </>
+        )
+      }
+      render(<Harness />)
+      const opener = screen.getByRole('button', { name: 'Open' })
+      await userEvent.click(opener)
+      expect(document.activeElement).toBe(screen.getByRole('dialog'))
+
+      await userEvent.click(screen.getByRole('button', { name: 'Close' }))
+      expect(screen.queryByRole('dialog')).toBeNull()
+      expect(document.activeElement).toBe(opener)
+    })
+
+    it('restores focus when the modal unmounts outright', async () => {
+      const opener = document.createElement('button')
+      document.body.appendChild(opener)
+      opener.focus()
+      const { unmount } = render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          body
+        </Modal>,
+      )
+      expect(document.activeElement).not.toBe(opener)
+      unmount()
+      expect(document.activeElement).toBe(opener)
+      opener.remove()
+    })
+
+    it('wraps Tab from the last control back to the first', async () => {
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <button type="button">Last</button>
+        </Modal>,
+      )
+      const close = screen.getByRole('button', { name: 'Close' })
+      const last = screen.getByRole('button', { name: 'Last' })
+      last.focus()
+      await userEvent.tab()
+      expect(document.activeElement).toBe(close)
+    })
+
+    it('wraps Shift+Tab from the first control round to the last', async () => {
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <button type="button">Last</button>
+        </Modal>,
+      )
+      const close = screen.getByRole('button', { name: 'Close' })
+      close.focus()
+      await userEvent.tab({ shift: true })
+      expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Last' }))
+    })
+
+    it('wraps Shift+Tab from the panel itself round to the last control', async () => {
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <button type="button">Last</button>
+        </Modal>,
+      )
+      expect(document.activeElement).toBe(screen.getByRole('dialog'))
+      await userEvent.tab({ shift: true })
+      expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Last' }))
+    })
+
+    it('does not let Tab leave the panel for the page behind it', async () => {
+      const outside = document.createElement('button')
+      outside.textContent = 'Behind'
+      document.body.appendChild(outside)
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <button type="button">Last</button>
+        </Modal>,
+      )
+      const dialog = screen.getByRole('dialog')
+      for (let i = 0; i < 6; i++) {
+        await userEvent.tab()
+        expect(dialog.contains(document.activeElement)).toBe(true)
+      }
+      outside.remove()
+    })
+
+    it('closes only the topmost modal on Escape', async () => {
+      const closeOuter = vi.fn()
+      const closeInner = vi.fn()
+      render(
+        <>
+          <Modal isOpen onClose={closeOuter} title="Outer">
+            outer
+          </Modal>
+          <Modal isOpen onClose={closeInner} title="Inner">
+            inner
+          </Modal>
+        </>,
+      )
+      await userEvent.keyboard('{Escape}')
+      expect(closeInner).toHaveBeenCalledTimes(1)
+      expect(closeOuter).not.toHaveBeenCalled()
+    })
+  })
+
   it('merges a caller className onto the panel', () => {
     render(
       <Modal isOpen onClose={noop} title="Confirm" className="max-w-sm">