perf: optimize DOM operations for better web vitals (INP, CLS, FID) (#657)

* perf: optimize DOM operations and reduce layout thrashing for better web vitals

- Batch reflow-causing reads in isFocusable() to minimize layout thrashing
- Use Set for O(1) tag lookups instead of Array.includes()
- Optimize getClippingRect() and getPositionedParent() with early exits
- Batch MutationObserver DOM operations (read phase, then write phase)
- Add sr-only inline styles to focus-trap sentinels to prevent CLS
- Cache isMacOS() result to avoid repeated userAgent parsing
- Add passive: true to mousemove listener in focus-zone
- Use :scope selector for faster direct-child sentinel lookup
- Replace for...of with indexed for loop in querySelectorAll iteration

* fix: remove useless passive option and fix trailing whitespace

* chore: add changeset

* fix: handle fixed/sticky positioning and correct attribute mutation logic

- Fixed isFocusable() to not exclude position:fixed/sticky elements (offsetParent is null for these)
- Fixed MutationObserver to check current attribute state instead of relying on oldValue
- Use Sets for deduplication in MutationObserver to avoid processing same element twice
- Added tests for fixed/sticky positioned elements

* fix: disconnect MutationObserver on abort to prevent memory leak

* test: add abort cleanup test and update mocks for sticky positioning

* fix: remove unused variable from test

* update optimizations for trap and zone

* add missing test

* docs

* focus-zone+indexed-set

* slight general perf

* release refs

* refactor: use setAttribute consistently for sentinel elements

* refactor: extract createSentinel helper to reduce duplication

* refactor: use options object for createSentinel

* avoid private field

* test: add comprehensive tests for IndexedSet

* refactor: remove redundant isMacOS cache (already cached in user-agent.ts)

Author: mattcosta7

.changeset/web-vitals-optimizations.md

@@ -0,0 +1,13 @@
+---
+'@primer/behaviors': patch
+---
+
+Optimize DOM operations for better web vitals (INP, CLS, FID)
+
+- Batch reflow-causing reads in `isFocusable()` to minimize layout thrashing
+- Use `Set` for O(1) tag lookups instead of `Array.includes()`
+- Optimize `getClippingRect()` and `getPositionedParent()` with early exits
+- Batch MutationObserver DOM operations (read phase, then write phase)
+- Add sr-only inline styles to focus-trap sentinels to prevent CLS
+- Use `:scope` selector for faster direct-child sentinel lookup
+- Add `IndexedSet` for O(1) membership checks in focus zone hot paths

src/__tests__/focus-trap.test.tsx

@@ -367,3 +367,27 @@ it('Should only have one set of sentinels', async () => {
   trapContainer.removeChild(newTrapContainer)
   expect(document.querySelectorAll('.sentinel').length).toEqual(2)
 })
+
+it('Should apply sr-only styles to sentinels to prevent layout shift', () => {
+  const {container} = render(
+    <div id="trapContainer">
+      <button tabIndex={0}>Apple</button>
+    </div>,
+  )
+
+  const trapContainer = container.querySelector<HTMLElement>('#trapContainer')!
+  const controller = focusTrap(trapContainer)
+
+  const sentinels = trapContainer.querySelectorAll<HTMLElement>('.sentinel')
+  expect(sentinels.length).toEqual(2)
+
+  // Verify both sentinels have sr-only styles to prevent CLS
+  for (const sentinel of sentinels) {
+    expect(sentinel.style.position).toEqual('absolute')
+    expect(sentinel.style.width).toEqual('1px')
+    expect(sentinel.style.height).toEqual('1px')
+    expect(sentinel.style.overflow).toEqual('hidden')
+  }
+
+  controller?.abort()
+})

src/__tests__/focus-zone.test.tsx

@@ -36,7 +36,8 @@ beforeAll(() => {
             }
           }
 
-          if (this.style?.position?.toLowerCase() === 'fixed') {
+          const position = this.style?.position?.toLowerCase()
+          if (position === 'fixed' || position === 'sticky') {
             return null
           }
 
@@ -914,3 +915,41 @@ it('Should not set initial focus via active descendant when focusInStrategy is "
 
   controller.abort()
 })
+
+it('Should not respond to DOM changes after abort is called', async () => {
+  const {container, rerender} = render(
+    <div id="focusZone">
+      <button tabIndex={0}>Apple</button>
+      <button tabIndex={0}>Banana</button>
+      <button tabIndex={0}>Cantaloupe</button>
+    </div>,
+  )
+
+  const focusZoneContainer = container.querySelector<HTMLElement>('#focusZone')!
+  const [firstButton] = focusZoneContainer.querySelectorAll('button')
+  const controller = focusZone(focusZoneContainer)
+
+  firstButton.focus()
+  expect(document.activeElement).toEqual(firstButton)
+
+  // Abort the focus zone
+  controller.abort()
+
+  // Add a new button - should not cause issues since observer is disconnected
+  rerender(
+    <div id="focusZone">
+      <button tabIndex={0}>Apple</button>
+      <button tabIndex={0}>Banana</button>
+      <button tabIndex={0}>Cantaloupe</button>
+      <button tabIndex={0}>Dragonfruit</button>
+    </div>,
+  )
+
+  await nextTick()
+
+  // Focus zone should no longer be managing focus, so all buttons should have their original tabindex
+  const buttons = focusZoneContainer.querySelectorAll('button')
+  for (const button of buttons) {
+    expect(button.getAttribute('tabindex')).toEqual('0')
+  }
+})

src/__tests__/indexed-set.test.ts

@@ -0,0 +1,224 @@
+import {IndexedSet} from '../utils/indexed-set'
+
+describe('IndexedSet', () => {
+  describe('insertAt', () => {
+    it('inserts elements at the specified index', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+
+      expect(set.get(0)).toBe('a')
+      expect(set.get(1)).toBe('b')
+      expect(set.get(2)).toBe('c')
+      expect(set.size).toBe(3)
+    })
+
+    it('inserts elements in the middle', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'c')
+      set.insertAt(1, 'b')
+
+      expect(set.get(0)).toBe('a')
+      expect(set.get(1)).toBe('b')
+      expect(set.get(2)).toBe('c')
+    })
+
+    it('deduplicates elements', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b')
+      set.insertAt(2, 'b', 'c') // 'b' should be ignored
+
+      expect(set.size).toBe(3)
+      expect(set.get(0)).toBe('a')
+      expect(set.get(1)).toBe('b')
+      expect(set.get(2)).toBe('c')
+    })
+
+    it('handles inserting all duplicates', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b')
+      set.insertAt(0, 'a', 'b') // all duplicates
+
+      expect(set.size).toBe(2)
+    })
+  })
+
+  describe('delete', () => {
+    it('removes an element and returns true', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+
+      expect(set.delete('b')).toBe(true)
+      expect(set.size).toBe(2)
+      expect(set.has('b')).toBe(false)
+      expect(set.get(0)).toBe('a')
+      expect(set.get(1)).toBe('c')
+    })
+
+    it('returns false for non-existent element', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a')
+
+      expect(set.delete('b')).toBe(false)
+      expect(set.size).toBe(1)
+    })
+  })
+
+  describe('has', () => {
+    it('returns true for existing elements', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b')
+
+      expect(set.has('a')).toBe(true)
+      expect(set.has('b')).toBe(true)
+    })
+
+    it('returns false for non-existent elements', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a')
+
+      expect(set.has('b')).toBe(false)
+    })
+
+    it('returns false after element is deleted', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a')
+      set.delete('a')
+
+      expect(set.has('a')).toBe(false)
+    })
+  })
+
+  describe('indexOf', () => {
+    it('returns the index of an existing element', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+
+      expect(set.indexOf('a')).toBe(0)
+      expect(set.indexOf('b')).toBe(1)
+      expect(set.indexOf('c')).toBe(2)
+    })
+
+    it('returns -1 for non-existent elements', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a')
+
+      expect(set.indexOf('b')).toBe(-1)
+    })
+  })
+
+  describe('get', () => {
+    it('returns the element at the specified index', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+
+      expect(set.get(0)).toBe('a')
+      expect(set.get(1)).toBe('b')
+      expect(set.get(2)).toBe('c')
+    })
+
+    it('returns undefined for out-of-bounds index', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a')
+
+      expect(set.get(1)).toBeUndefined()
+      expect(set.get(-1)).toBeUndefined()
+    })
+  })
+
+  describe('size', () => {
+    it('returns 0 for empty set', () => {
+      const set = new IndexedSet<string>()
+      expect(set.size).toBe(0)
+    })
+
+    it('returns correct size after insertions', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+      expect(set.size).toBe(3)
+    })
+
+    it('returns correct size after deletions', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+      set.delete('b')
+      expect(set.size).toBe(2)
+    })
+  })
+
+  describe('clear', () => {
+    it('removes all elements', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+      set.clear()
+
+      expect(set.size).toBe(0)
+      expect(set.has('a')).toBe(false)
+      expect(set.get(0)).toBeUndefined()
+    })
+  })
+
+  describe('find', () => {
+    it('returns the first matching element', () => {
+      const set = new IndexedSet<{id: number; name: string}>()
+      set.insertAt(0, {id: 1, name: 'a'}, {id: 2, name: 'b'}, {id: 3, name: 'c'})
+
+      const found = set.find(el => el.id === 2)
+      expect(found).toEqual({id: 2, name: 'b'})
+    })
+
+    it('returns undefined when no match', () => {
+      const set = new IndexedSet<{id: number}>()
+      set.insertAt(0, {id: 1}, {id: 2})
+
+      expect(set.find(el => el.id === 99)).toBeUndefined()
+    })
+  })
+
+  describe('[Symbol.iterator]', () => {
+    it('allows iteration with for...of', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+
+      const result: string[] = []
+      for (const item of set) {
+        result.push(item)
+      }
+
+      expect(result).toEqual(['a', 'b', 'c'])
+    })
+
+    it('allows spread operator', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+
+      expect([...set]).toEqual(['a', 'b', 'c'])
+    })
+
+    it('allows Array.from', () => {
+      const set = new IndexedSet<string>()
+      set.insertAt(0, 'a', 'b', 'c')
+
+      expect(Array.from(set)).toEqual(['a', 'b', 'c'])
+    })
+  })
+
+  describe('with HTMLElements', () => {
+    it('works with DOM elements', () => {
+      const set = new IndexedSet<HTMLElement>()
+      const div1 = document.createElement('div')
+      const div2 = document.createElement('div')
+      const div3 = document.createElement('div')
+
+      set.insertAt(0, div1, div2, div3)
+
+      expect(set.has(div1)).toBe(true)
+      expect(set.has(div2)).toBe(true)
+      expect(set.indexOf(div2)).toBe(1)
+      expect(set.get(0)).toBe(div1)
+
+      set.delete(div2)
+      expect(set.has(div2)).toBe(false)
+      expect(set.size).toBe(2)
+    })
+  })
+})

src/__tests__/iterate-focusable-elements.test.tsx

@@ -25,7 +25,8 @@ beforeAll(() => {
             }
           }
 
-          if (this.style?.position?.toLowerCase() === 'fixed') {
+          const position = this.style?.position?.toLowerCase()
+          if (position === 'fixed' || position === 'sticky') {
             return null
           }
 
@@ -213,6 +214,18 @@ describe('isFocusable', () => {
     const focusable = isFocusable(container.firstChild as HTMLElement, true)
     expect(focusable).toBeFalsy()
   })
+
+  it('position: fixed elements are focusable in strict mode', async () => {
+    const {container} = render(<button style={{position: 'fixed', top: 0, left: 0}}>Fixed Button</button>)
+    const focusable = isFocusable(container.firstChild as HTMLElement, true)
+    expect(focusable).toBeTruthy()
+  })
+
+  it('position: sticky elements are focusable in strict mode', async () => {
+    const {container} = render(<button style={{position: 'sticky', top: 0}}>Sticky Button</button>)
+    const focusable = isFocusable(container.firstChild as HTMLElement, true)
+    expect(focusable).toBeTruthy()
+  })
 })
 
 describe('isTabbable', () => {