@furystack/shades-common-components 14.0.0 → 15.0.0

package/src/components/data-grid/data-grid.spec.tsx

@@ -284,15 +284,11 @@ describe('DataGrid', () => {
         expect(headers?.length).toBe(2)
       })
     })
-  })
 
-  describe('focus management', () => {
-    it('should set focus on click', async () => {
+    it('should render with auto-generated data-nav-section attribute', async () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
 
-        expect(service.hasFocus.getValue()).toBe(false)
-
         initializeShadeRoot({
           injector,
           rootElement,
@@ -302,70 +298,115 @@ describe('DataGrid', () => {
               collectionService={service}
               findOptions={findOptions}
               onFindOptionsChange={onFindOptionsChange}
-              styles={{}}
-              headerComponents={{}}
-              rowComponents={{}}
             />
           ),
         })
 
         await flushUpdates()
 
-        const grid = document.querySelector('shade-data-grid')
-        const wrapper = grid?.querySelector('.shade-grid-wrapper') as HTMLElement
+        const wrapper = document.querySelector('.shade-grid-wrapper')
+        const navSection = wrapper?.getAttribute('data-nav-section')
+        expect(navSection).toBeTruthy()
+        expect(navSection).toMatch(/^data-grid-/)
+      })
+    })
 
-        wrapper?.click()
+    it('should render with custom navSection', async () => {
+      await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
 
-        expect(service.hasFocus.getValue()).toBe(true)
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <DataGrid<TestEntry, 'id' | 'name'>
+              columns={['id', 'name']}
+              collectionService={service}
+              findOptions={findOptions}
+              onFindOptionsChange={onFindOptionsChange}
+              navSection="my-grid"
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const wrapper = document.querySelector('.shade-grid-wrapper')
+        expect(wrapper?.getAttribute('data-nav-section')).toBe('my-grid')
       })
     })
+  })
 
-    it('should lose focus on click outside', async () => {
+  describe('focus management', () => {
+    it('should clear hasFocus on focusout when focus leaves the grid', async () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
+        const outsideBtn = document.createElement('button')
+        document.body.appendChild(outsideBtn)
 
         initializeShadeRoot({
           injector,
           rootElement,
           jsxElement: (
-            <>
-              <div data-testid="outside">Outside</div>
-              <DataGrid<TestEntry, 'id' | 'name'>
-                columns={['id', 'name']}
-                collectionService={service}
-                findOptions={findOptions}
-                onFindOptionsChange={onFindOptionsChange}
-                styles={{}}
-                headerComponents={{}}
-                rowComponents={{}}
-              />
-            </>
+            <DataGrid<TestEntry, 'id' | 'name'>
+              columns={['id', 'name']}
+              collectionService={service}
+              findOptions={findOptions}
+              onFindOptionsChange={onFindOptionsChange}
+            />
           ),
         })
 
         await flushUpdates()
+        await new Promise((r) => setTimeout(r, 0))
 
-        const grid = document.querySelector('shade-data-grid')
-        const wrapper = grid?.querySelector('.shade-grid-wrapper') as HTMLElement
-        wrapper?.click()
-
-        expect(service.hasFocus.getValue()).toBe(true)
+        service.hasFocus.setValue(true)
 
-        const outside = document.querySelector('[data-testid="outside"]') as HTMLElement
-        outside?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+        const wrapper = document.querySelector('.shade-grid-wrapper') as HTMLElement
+        wrapper?.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget: outsideBtn }))
 
         expect(service.hasFocus.getValue()).toBe(false)
+        outsideBtn.remove()
       })
     })
-  })
 
-  describe('keyboard navigation', () => {
-    it('should handle ArrowDown to move focus to next entry', async () => {
+    it('should clear hasFocus on focusout when focus moves outside', async () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
+        const outsideEl = document.createElement('button')
+        outsideEl.textContent = 'Outside'
+        document.body.appendChild(outsideEl)
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <DataGrid<TestEntry, 'id' | 'name'>
+              columns={['id', 'name']}
+              collectionService={service}
+              findOptions={findOptions}
+              onFindOptionsChange={onFindOptionsChange}
+            />
+          ),
+        })
+
+        await flushUpdates()
+        await new Promise((r) => setTimeout(r, 0))
 
         service.hasFocus.setValue(true)
-        service.focusedEntry.setValue(service.data.getValue().entries[0])
+
+        const wrapper = document.querySelector('.shade-grid-wrapper') as HTMLElement
+        wrapper?.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget: outsideEl }))
+
+        expect(service.hasFocus.getValue()).toBe(false)
+
+        outsideEl.remove()
+      })
+    })
+
+    it('should clear hasFocus on focusout when relatedTarget is null', async () => {
+      await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
 
         initializeShadeRoot({
           injector,
@@ -376,28 +417,30 @@ describe('DataGrid', () => {
               collectionService={service}
               findOptions={findOptions}
               onFindOptionsChange={onFindOptionsChange}
-              styles={{}}
-              headerComponents={{}}
-              rowComponents={{}}
             />
           ),
         })
 
         await flushUpdates()
+        await new Promise((r) => setTimeout(r, 0))
 
-        const keydownEvent = new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true })
-        window.dispatchEvent(keydownEvent)
+        service.hasFocus.setValue(true)
 
-        expect(service.focusedEntry.getValue()).toEqual({ id: 2, name: 'Second' })
+        const wrapper = document.querySelector('.shade-grid-wrapper') as HTMLElement
+        wrapper?.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget: null }))
+
+        expect(service.hasFocus.getValue()).toBe(false)
       })
     })
+  })
 
-    it('should handle ArrowUp to move focus to previous entry', async () => {
+  describe('keyboard navigation', () => {
+    it('should move focus to next entry on ArrowDown', async () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
 
         service.hasFocus.setValue(true)
-        service.focusedEntry.setValue(service.data.getValue().entries[1])
+        service.focusedEntry.setValue(service.data.getValue().entries[0])
 
         initializeShadeRoot({
           injector,
@@ -417,19 +460,19 @@ describe('DataGrid', () => {
 
         await flushUpdates()
 
-        const keydownEvent = new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true })
+        const keydownEvent = new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true })
         window.dispatchEvent(keydownEvent)
 
-        expect(service.focusedEntry.getValue()).toEqual({ id: 1, name: 'First' })
+        expect(service.focusedEntry.getValue()).toEqual({ id: 2, name: 'Second' })
       })
     })
 
-    it('should handle Home to move focus to first entry', async () => {
+    it('should move focus to previous entry on ArrowUp', async () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
 
         service.hasFocus.setValue(true)
-        service.focusedEntry.setValue(service.data.getValue().entries[2])
+        service.focusedEntry.setValue(service.data.getValue().entries[1])
 
         initializeShadeRoot({
           injector,
@@ -449,19 +492,19 @@ describe('DataGrid', () => {
 
         await flushUpdates()
 
-        const keydownEvent = new KeyboardEvent('keydown', { key: 'Home', bubbles: true })
+        const keydownEvent = new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true })
         window.dispatchEvent(keydownEvent)
 
         expect(service.focusedEntry.getValue()).toEqual({ id: 1, name: 'First' })
       })
     })
 
-    it('should handle End to move focus to last entry', async () => {
+    it('should handle Home to move focus to first entry', async () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
 
         service.hasFocus.setValue(true)
-        service.focusedEntry.setValue(service.data.getValue().entries[0])
+        service.focusedEntry.setValue(service.data.getValue().entries[2])
 
         initializeShadeRoot({
           injector,
@@ -481,18 +524,19 @@ describe('DataGrid', () => {
 
         await flushUpdates()
 
-        const keydownEvent = new KeyboardEvent('keydown', { key: 'End', bubbles: true })
+        const keydownEvent = new KeyboardEvent('keydown', { key: 'Home', bubbles: true })
         window.dispatchEvent(keydownEvent)
 
-        expect(service.focusedEntry.getValue()).toEqual({ id: 3, name: 'Third' })
+        expect(service.focusedEntry.getValue()).toEqual({ id: 1, name: 'First' })
       })
     })
 
-    it('should handle Tab to toggle focus', async () => {
+    it('should handle End to move focus to last entry', async () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
 
         service.hasFocus.setValue(true)
+        service.focusedEntry.setValue(service.data.getValue().entries[0])
 
         initializeShadeRoot({
           injector,
@@ -512,10 +556,10 @@ describe('DataGrid', () => {
 
         await flushUpdates()
 
-        const keydownEvent = new KeyboardEvent('keydown', { key: 'Tab', bubbles: true })
+        const keydownEvent = new KeyboardEvent('keydown', { key: 'End', bubbles: true })
         window.dispatchEvent(keydownEvent)
 
-        expect(service.hasFocus.getValue()).toBe(false)
+        expect(service.focusedEntry.getValue()).toEqual({ id: 3, name: 'Third' })
       })
     })
 
@@ -694,7 +738,6 @@ describe('DataGrid', () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
 
-        service.hasFocus.setValue(false)
         service.focusedEntry.setValue(service.data.getValue().entries[0])
 
         initializeShadeRoot({
@@ -715,6 +758,8 @@ describe('DataGrid', () => {
 
         await flushUpdates()
 
+        service.hasFocus.setValue(false)
+
         const keydownEvent = new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true })
         window.dispatchEvent(keydownEvent)
 
@@ -934,6 +979,89 @@ describe('DataGrid', () => {
     })
   })
 
+  describe('row spatial navigation attributes', () => {
+    it('should set data-spatial-nav-target on rows', async () => {
+      await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <DataGrid<TestEntry, 'id' | 'name'>
+              columns={['id', 'name']}
+              collectionService={service}
+              findOptions={findOptions}
+              onFindOptionsChange={onFindOptionsChange}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const rows = document.querySelectorAll('shades-data-grid-row')
+        for (const row of rows) {
+          expect(row.hasAttribute('data-spatial-nav-target')).toBe(true)
+        }
+      })
+    })
+
+    it('should set tabIndex 0 on focused row and -1 on others', async () => {
+      await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        service.focusedEntry.setValue(service.data.getValue().entries[1])
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <DataGrid<TestEntry, 'id' | 'name'>
+              columns={['id', 'name']}
+              collectionService={service}
+              findOptions={findOptions}
+              onFindOptionsChange={onFindOptionsChange}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const rows = document.querySelectorAll<HTMLTableRowElement>('shades-data-grid-row')
+        expect(rows[0]?.tabIndex).toBe(-1)
+        expect(rows[1]?.tabIndex).toBe(0)
+        expect(rows[2]?.tabIndex).toBe(-1)
+      })
+    })
+
+    it('should sync focusedEntry on row onfocus', async () => {
+      await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <DataGrid<TestEntry, 'id' | 'name'>
+              columns={['id', 'name']}
+              collectionService={service}
+              findOptions={findOptions}
+              onFindOptionsChange={onFindOptionsChange}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const rows = document.querySelectorAll('shades-data-grid-row')
+        rows[2]?.dispatchEvent(new FocusEvent('focus'))
+
+        expect(service.focusedEntry.getValue()).toEqual({ id: 3, name: 'Third' })
+        expect(service.hasFocus.getValue()).toBe(true)
+      })
+    })
+  })
+
   describe('keyboard listener cleanup', () => {
     it('should remove keyboard listener when component is disconnected', async () => {
       await withTestGrid(async ({ injector, service, findOptions, onFindOptionsChange }) => {

package/src/components/data-grid/data-grid.tsx

@@ -1,7 +1,6 @@
 import type { FindOptions } from '@furystack/core'
 import type { ChildrenList } from '@furystack/shades'
 import { createComponent, Shade } from '@furystack/shades'
-import { ClickAwayService } from '../../services/click-away-service.js'
 import type { CollectionService } from '../../services/collection-service.js'
 import { cssVariableTheme } from '../../services/css-variable-theme.js'
 import type { GridProps } from '../grid.js'
@@ -9,6 +8,8 @@ import { DataGridBody } from './body.js'
 import { DataGridFooter } from './footer.js'
 import { DataGridHeader } from './header.js'
 
+let nextDataGridId = 0
+
 export type StringFilterConfig = { type: 'string' }
 export type NumberFilterConfig = { type: 'number' }
 export type BooleanFilterConfig = { type: 'boolean' }
@@ -119,6 +120,14 @@ export interface DataGridProps<T, Column extends string> {
    * @default dataGridItemsPerPage ([10, 20, 25, 50, 100, Infinity])
    */
   paginationOptions?: number[]
+
+  /**
+   * Section name for spatial navigation scoping.
+   * Sets `data-nav-section` on the grid wrapper so that SpatialNavigationService
+   * constrains arrow-key navigation within the grid.
+   * Auto-generated per instance when not provided.
+   */
+  navSection?: string
 }
 
 export const DataGrid: <T, Column extends string>(
@@ -157,25 +166,43 @@ export const DataGrid: <T, Column extends string>(
       borderRight: `1px solid ${cssVariableTheme.action.subtleBorder}`,
     },
   },
-  render: ({ props, useDisposable, useRef, useHostProps }) => {
+  render: ({ props, useDisposable, useRef, useHostProps, useState }) => {
     const wrapperRef = useRef<HTMLDivElement>('gridWrapper')
+    const [navSectionId] = useState('navSectionId', String(nextDataGridId++))
 
     const headerFindOptions = props.findOptions as FilterableFindOptions
     const handleHeaderChange = props.onFindOptionsChange as (options: FilterableFindOptions) => void
 
     useDisposable('keydown-handler', () => {
       const listener = (ev: KeyboardEvent) => props.collectionService.handleKeyDown(ev)
-      window.addEventListener('keydown', listener)
-      return { [Symbol.dispose]: () => window.removeEventListener('keydown', listener) }
+      window.addEventListener('keydown', listener, true)
+      return { [Symbol.dispose]: () => window.removeEventListener('keydown', listener, true) }
     })
 
-    useDisposable(
-      'clickAway',
-      () =>
-        new ClickAwayService(wrapperRef, () => {
+    useDisposable('focus-coordination', () => {
+      const handleFocusOut = (ev: FocusEvent) => {
+        const wrapper = wrapperRef.current
+        if (wrapper && (!ev.relatedTarget || !wrapper.contains(ev.relatedTarget as Node))) {
           props.collectionService.hasFocus.setValue(false)
-        }),
-    )
+        }
+      }
+
+      queueMicrotask(() => {
+        const wrapper = wrapperRef.current
+        if (wrapper) {
+          wrapper.addEventListener('focusout', handleFocusOut)
+        }
+      })
+
+      return {
+        [Symbol.dispose]: () => {
+          const wrapper = wrapperRef.current
+          if (wrapper) {
+            wrapper.removeEventListener('focusout', handleFocusOut)
+          }
+        },
+      }
+    })
 
     if (props.styles?.wrapper) {
       useHostProps({ style: props.styles.wrapper as Record<string, string> })
@@ -185,9 +212,7 @@ export const DataGrid: <T, Column extends string>(
       <div
         ref={wrapperRef}
         className="shade-grid-wrapper"
-        onclick={() => {
-          props.collectionService.hasFocus.setValue(true)
-        }}
+        data-nav-section={props.navSection ?? `data-grid-${navSectionId}`}
         ariaMultiSelectable="true"
       >
         <table>

package/src/components/data-grid/selection-cell.tsx

@@ -22,6 +22,7 @@ export const SelectionCell = Shade<{ entry: any; service: CollectionService<any>
 
     return (
       <input
+        tabIndex={-1}
         onchange={() => {
           props.service.toggleSelection(props.entry)
         }}

package/src/components/dialog.spec.tsx

@@ -1,9 +1,19 @@
-import { createComponent } from '@furystack/shades'
-import { describe, expect, it, vi } from 'vitest'
+import { Injector } from '@furystack/inject'
+import { createComponent, flushUpdates, initializeShadeRoot, SpatialNavigationService } from '@furystack/shades'
+import { usingAsync } from '@furystack/utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { DialogProps } from './dialog.js'
 import { ConfirmDialog, Dialog } from './dialog.js'
 
 describe('Dialog', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+  })
+
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
   it('should be defined', () => {
     expect(Dialog).toBeDefined()
     expect(typeof Dialog).toBe('function')
@@ -55,6 +65,71 @@ describe('Dialog', () => {
     const el = (<Dialog isVisible={false} />) as unknown as { props: DialogProps }
     expect(el.props.isVisible).toBe(false)
   })
+
+  it('should forward trapFocus to the underlying Modal', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const spatialNav = injector.getInstance(SpatialNavigationService)
+      const pushSpy = vi.spyOn(spatialNav, 'pushFocusTrap')
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <Dialog isVisible={true} trapFocus={true} navSection="dialog-trap">
+            <div>Content</div>
+          </Dialog>
+        ),
+      })
+
+      await flushUpdates()
+
+      expect(pushSpy).toHaveBeenCalledWith('dialog-trap')
+    })
+  })
+
+  it('should forward navSection to the underlying Modal', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <Dialog isVisible={true} navSection="my-dialog">
+            <div>Content</div>
+          </Dialog>
+        ),
+      })
+
+      await flushUpdates()
+
+      const backdrop = document.querySelector('.shade-backdrop')
+      expect(backdrop?.getAttribute('data-nav-section')).toBe('my-dialog')
+    })
+  })
+
+  it('should not push focus trap when trapFocus is false', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const spatialNav = injector.getInstance(SpatialNavigationService)
+      const pushSpy = vi.spyOn(spatialNav, 'pushFocusTrap')
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: (
+          <Dialog isVisible={true} trapFocus={false}>
+            <div>Content</div>
+          </Dialog>
+        ),
+      })
+
+      await flushUpdates()
+
+      expect(pushSpy).not.toHaveBeenCalled()
+    })
+  })
 })
 
 describe('ConfirmDialog', () => {

package/src/components/dialog.tsx

@@ -13,6 +13,17 @@ export type DialogProps = {
   actions?: JSX.Element
   maxWidth?: string
   fullWidth?: boolean
+  /**
+   * When true, traps spatial navigation within the dialog's bounds.
+   * Forwarded to the underlying Modal component.
+   */
+  trapFocus?: boolean
+  /**
+   * Section name for spatial navigation scoping.
+   * Forwarded to the underlying Modal component.
+   * @default 'modal'
+   */
+  navSection?: string
 }
 
 const showAnimation = async (el: Element | null) => {
@@ -127,7 +138,7 @@ export const Dialog = Shade<DialogProps>({
     },
   },
   render: ({ props, children }) => {
-    const { isVisible, title, onClose, actions, maxWidth = '560px', fullWidth } = props
+    const { isVisible, title, onClose, actions, maxWidth = '560px', fullWidth, trapFocus = true, navSection } = props
 
     const handleClose = () => {
       onClose?.()
@@ -139,6 +150,8 @@ export const Dialog = Shade<DialogProps>({
         onClose={handleClose}
         showAnimation={showAnimation}
         hideAnimation={hideAnimation}
+        trapFocus={trapFocus}
+        navSection={navSection}
         backdropStyle={{
           display: 'flex',
           alignItems: 'center',

package/src/components/dropdown.spec.tsx

@@ -416,6 +416,15 @@ describe('Dropdown', () => {
     })
   })
 
+  describe('spatial navigation', () => {
+    it('should have data-spatial-nav-passthrough on the backdrop', async () => {
+      await usingAsync(await renderDropdown({}), async ({ dropdown }) => {
+        const backdrop = dropdown.querySelector('.dropdown-backdrop') as HTMLElement
+        expect(backdrop.hasAttribute('data-spatial-nav-passthrough')).toBe(true)
+      })
+    })
+  })
+
   describe('placement', () => {
     it('should accept bottomRight placement', async () => {
       await usingAsync(await renderDropdown({ placement: 'bottomRight' }), async ({ dropdown }) => {

package/src/components/dropdown.tsx

@@ -309,6 +309,7 @@ export const Dropdown: (props: DropdownProps, children: ChildrenList) => JSX.Ele
         <div
           ref={backdropRef}
           className="dropdown-backdrop"
+          data-spatial-nav-passthrough=""
           style={{
             position: 'fixed',
             top: '0',