@furystack/shades-common-components 14.0.0 → 15.0.1

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',

package/src/components/image.spec.tsx

@@ -345,6 +345,88 @@ describe('Image component', () => {
     })
   })
 
+  it('should be focusable when preview is enabled', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <Image src="https://example.com/photo.jpg" preview />,
+      })
+
+      await flushUpdates()
+
+      const imageComponent = document.querySelector('shade-image') as HTMLElement
+      expect(imageComponent.getAttribute('tabindex')).toBe('0')
+    })
+  })
+
+  it('should not be focusable when preview is disabled', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <Image src="https://example.com/photo.jpg" />,
+      })
+
+      await flushUpdates()
+
+      const imageComponent = document.querySelector('shade-image') as HTMLElement
+      expect(imageComponent.hasAttribute('tabindex')).toBe(false)
+    })
+  })
+
+  it('should open lightbox when pressing Enter on a preview-enabled image', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <Image src="https://example.com/photo.jpg" alt="My photo" preview />,
+      })
+
+      await flushUpdates()
+
+      const imageComponent = document.querySelector('shade-image') as HTMLElement
+      imageComponent.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+
+      await flushUpdates()
+
+      const lightbox = document.querySelector('.lightbox-backdrop')
+      expect(lightbox).not.toBeNull()
+
+      lightbox?.remove()
+    })
+  })
+
+  it('should open lightbox when pressing Space on a preview-enabled image', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <Image src="https://example.com/photo.jpg" alt="My photo" preview />,
+      })
+
+      await flushUpdates()
+
+      const imageComponent = document.querySelector('shade-image') as HTMLElement
+      imageComponent.dispatchEvent(new KeyboardEvent('keydown', { key: ' ', bubbles: true }))
+
+      await flushUpdates()
+
+      const lightbox = document.querySelector('.lightbox-backdrop')
+      expect(lightbox).not.toBeNull()
+
+      lightbox?.remove()
+    })
+  })
+
   it('should store src and alt as data attributes', async () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement

package/src/components/image.tsx

@@ -438,13 +438,6 @@ export const Image = Shade<ImageProps>({
       style: styleOverrides,
     } = props
 
-    useHostProps({
-      'data-preview': preview ? '' : undefined,
-      'data-src': src,
-      'data-alt': alt,
-      ...(styleOverrides ? { style: styleOverrides as Record<string, string> } : {}),
-    })
-
     const [hasError, setHasError] = useState('hasError', false)
 
     const handleClick = () => {
@@ -466,6 +459,22 @@ export const Image = Shade<ImageProps>({
       createLightbox(src, alt)
     }
 
+    useHostProps({
+      'data-preview': preview ? '' : undefined,
+      'data-src': src,
+      'data-alt': alt,
+      tabIndex: preview ? 0 : undefined,
+      onkeydown: preview
+        ? (ev: KeyboardEvent) => {
+            if (ev.key === 'Enter' || ev.key === ' ') {
+              ev.preventDefault()
+              handleClick()
+            }
+          }
+        : undefined,
+      ...(styleOverrides ? { style: styleOverrides as Record<string, string> } : {}),
+    })
+
     return (
       <div ref={imageHostRef} style={{ display: 'contents' }}>
         <img

package/src/components/inputs/checkbox.tsx

@@ -95,6 +95,7 @@ export const Checkbox = Shade<CheckboxProps>({
     },
 
     '& input[type="checkbox"]:focus-visible': {
+      outline: 'none',
       boxShadow: cssVariableTheme.action.focusRing,
     },
 

package/src/components/inputs/radio.tsx

@@ -87,6 +87,7 @@ export const Radio = Shade<RadioProps>({
     },
 
     '& input[type="radio"]:focus-visible': {
+      outline: 'none',
       boxShadow: cssVariableTheme.action.focusRing,
     },
 

package/src/components/inputs/slider.tsx

@@ -293,6 +293,7 @@ export const Slider = Shade<SliderProps>({
     },
 
     '& .slider-thumb:focus-visible': {
+      outline: 'none',
       boxShadow: '0 0 0 4px color-mix(in srgb, var(--slider-color) 30%, transparent)',
     },
 

package/src/components/inputs/switch.tsx

@@ -154,6 +154,7 @@ export const Switch = Shade<SwitchProps>({
 
     // Focus state
     '& input[type="checkbox"]:focus-visible + .switch-track': {
+      outline: 'none',
       boxShadow: cssVariableTheme.action.focusRing,
     },
 

package/src/components/list/list-item.tsx

@@ -46,8 +46,21 @@ export const ListItem: <T>(props: ListItemProps<T>, children: ChildrenList) => J
     const isSelected = selection.includes(item)
 
     useHostProps({
+      tabIndex: isFocused ? 0 : -1,
+      'data-spatial-nav-target': '',
       role: 'option',
       'aria-selected': isSelected.toString(),
+      onpointerdown: () => {
+        listService.setFocusAnchor()
+      },
+      onfocus: () => {
+        if (listService.focusedItem.getValue() !== item) {
+          listService.focusedItem.setValue(item)
+        }
+        if (!listService.hasFocus.getValue()) {
+          listService.hasFocus.setValue(true)
+        }
+      },
       onclick: (ev: MouseEvent) => {
         listService.handleItemClick(item, ev)
       },
@@ -65,11 +78,16 @@ export const ListItem: <T>(props: ListItemProps<T>, children: ChildrenList) => J
       queueMicrotask(() => {
         const el = wrapperRef.current
         if (!el) return
+        const hostEl = el.closest('shade-list-item') as HTMLElement
+        if (!hostEl) return
+
+        if (document.activeElement !== hostEl) {
+          hostEl.focus({ preventScroll: true })
+        }
+
         const scrollContainer = el.closest('shade-list') as HTMLElement
         if (scrollContainer) {
           const containerRect = scrollContainer.getBoundingClientRect()
-          const hostEl = el.closest('shade-list-item') as HTMLElement
-          if (!hostEl) return
           const itemRect = hostEl.getBoundingClientRect()
           const itemTopInContainer = itemRect.top - containerRect.top
           const itemBottomInContainer = itemRect.bottom - containerRect.top
@@ -77,12 +95,12 @@ export const ListItem: <T>(props: ListItemProps<T>, children: ChildrenList) => J
           if (itemTopInContainer < 0) {
             scrollContainer.scrollTo({
               top: scrollContainer.scrollTop + itemTopInContainer,
-              behavior: 'smooth',
+              behavior: 'instant',
             })
           } else if (itemBottomInContainer > scrollContainer.clientHeight) {
             scrollContainer.scrollTo({
               top: scrollContainer.scrollTop + (itemBottomInContainer - scrollContainer.clientHeight),
-              behavior: 'smooth',
+              behavior: 'instant',
             })
           }
         }

package/src/components/list/list.spec.tsx

@@ -252,7 +252,7 @@ describe('List', () => {
       })
     })
 
-    it('should lose focus on click outside', async () => {
+    it('should lose focus on focusout to an outside element', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
         const service = createTestService()
@@ -262,7 +262,7 @@ describe('List', () => {
           rootElement,
           jsxElement: (
             <>
-              <div data-testid="outside">Outside</div>
+              <button data-testid="outside">Outside</button>
               <List<TestItem> items={testItems} listService={service} renderItem={(item) => <span>{item.name}</span>} />
             </>
           ),
@@ -277,7 +277,7 @@ describe('List', () => {
         expect(service.hasFocus.getValue()).toBe(true)
 
         const outside = document.querySelector('[data-testid="outside"]') as HTMLElement
-        outside?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+        wrapper?.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget: outside }))
 
         expect(service.hasFocus.getValue()).toBe(false)
 
@@ -336,6 +336,87 @@ describe('List', () => {
         service[Symbol.dispose]()
       })
     })
+
+    it('should not initialize focusedItem on wrapper focusin (items handle focus individually)', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const service = createTestService()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <List<TestItem> items={testItems} listService={service} renderItem={(item) => <span>{item.name}</span>} />
+          ),
+        })
+
+        await flushUpdates()
+        await new Promise((r) => setTimeout(r, 0))
+
+        expect(service.hasFocus.getValue()).toBe(false)
+        expect(service.focusedItem.getValue()).toBeUndefined()
+
+        service[Symbol.dispose]()
+      })
+    })
+
+    it('should clear hasFocus on focusout when focus moves outside', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const service = createTestService()
+        const outsideEl = document.createElement('button')
+        outsideEl.textContent = 'Outside'
+        document.body.appendChild(outsideEl)
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <List<TestItem> items={testItems} listService={service} renderItem={(item) => <span>{item.name}</span>} />
+          ),
+        })
+
+        await flushUpdates()
+        await new Promise((r) => setTimeout(r, 0))
+
+        service.hasFocus.setValue(true)
+
+        const wrapper = document.querySelector('.shade-list-wrapper') as HTMLElement
+        wrapper?.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget: outsideEl }))
+
+        expect(service.hasFocus.getValue()).toBe(false)
+
+        outsideEl.remove()
+        service[Symbol.dispose]()
+      })
+    })
+
+    it('should clear hasFocus on focusout when relatedTarget is null', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const service = createTestService()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <List<TestItem> items={testItems} listService={service} renderItem={(item) => <span>{item.name}</span>} />
+          ),
+        })
+
+        await flushUpdates()
+        await new Promise((r) => setTimeout(r, 0))
+
+        service.hasFocus.setValue(true)
+
+        const wrapper = document.querySelector('.shade-list-wrapper') as HTMLElement
+        wrapper?.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget: null }))
+
+        expect(service.hasFocus.getValue()).toBe(false)
+
+        service[Symbol.dispose]()
+      })
+    })
   })
 
   describe('selection', () => {
@@ -426,7 +507,7 @@ describe('List', () => {
   })
 
   describe('keyboard navigation', () => {
-    it('should handle ArrowDown to move focus to next item', async () => {
+    it('should not handle ArrowDown (delegated to spatial navigation)', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
         const service = createTestService()
@@ -446,13 +527,13 @@ describe('List', () => {
 
         window.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }))
 
-        expect(service.focusedItem.getValue()).toEqual(testItems[1])
+        expect(service.focusedItem.getValue()).toEqual(testItems[0])
 
         service[Symbol.dispose]()
       })
     })
 
-    it('should handle ArrowUp to move focus to previous item', async () => {
+    it('should not handle ArrowUp (delegated to spatial navigation)', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
         const service = createTestService()
@@ -472,7 +553,7 @@ describe('List', () => {
 
         window.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true }))
 
-        expect(service.focusedItem.getValue()).toEqual(testItems[0])
+        expect(service.focusedItem.getValue()).toEqual(testItems[1])
 
         service[Symbol.dispose]()
       })
@@ -666,31 +747,6 @@ describe('List', () => {
       })
     })
 
-    it('should handle Tab to toggle focus', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const rootElement = document.getElementById('root') as HTMLDivElement
-        const service = createTestService()
-
-        service.hasFocus.setValue(true)
-
-        initializeShadeRoot({
-          injector,
-          rootElement,
-          jsxElement: (
-            <List<TestItem> items={testItems} listService={service} renderItem={(item) => <span>{item.name}</span>} />
-          ),
-        })
-
-        await flushUpdates()
-
-        window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true }))
-
-        expect(service.hasFocus.getValue()).toBe(false)
-
-        service[Symbol.dispose]()
-      })
-    })
-
     it('should not handle keyboard when not focused', async () => {
       await usingAsync(new Injector(), async (injector) => {
         const rootElement = document.getElementById('root') as HTMLDivElement
@@ -956,6 +1012,83 @@ describe('List', () => {
     })
   })
 
+  describe('item spatial navigation attributes', () => {
+    it('should set data-spatial-nav-target on list items', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const service = createTestService()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <List<TestItem> items={testItems} listService={service} renderItem={(item) => <span>{item.name}</span>} />
+          ),
+        })
+
+        await flushUpdates()
+
+        const items = document.querySelectorAll('shade-list-item')
+        for (const item of items) {
+          expect(item.hasAttribute('data-spatial-nav-target')).toBe(true)
+        }
+
+        service[Symbol.dispose]()
+      })
+    })
+
+    it('should set tabIndex 0 on focused item and -1 on others', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const service = createTestService()
+
+        service.focusedItem.setValue(testItems[1])
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <List<TestItem> items={testItems} listService={service} renderItem={(item) => <span>{item.name}</span>} />
+          ),
+        })
+
+        await flushUpdates()
+
+        const items = document.querySelectorAll<HTMLDivElement>('shade-list-item')
+        expect(items[0]?.tabIndex).toBe(-1)
+        expect(items[1]?.tabIndex).toBe(0)
+        expect(items[2]?.tabIndex).toBe(-1)
+
+        service[Symbol.dispose]()
+      })
+    })
+
+    it('should sync focusedItem on item onfocus', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const service = createTestService()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <List<TestItem> items={testItems} listService={service} renderItem={(item) => <span>{item.name}</span>} />
+          ),
+        })
+
+        await flushUpdates()
+
+        const items = document.querySelectorAll('shade-list-item')
+        items[2]?.dispatchEvent(new FocusEvent('focus'))
+
+        expect(service.focusedItem.getValue()).toEqual(testItems[2])
+        expect(service.hasFocus.getValue()).toBe(true)
+
+        service[Symbol.dispose]()
+      })
+    })
+  })
+
   describe('keyboard listener cleanup', () => {
     it('should remove keyboard listener when component is disconnected', async () => {
       await usingAsync(new Injector(), async (injector) => {

package/src/components/list/list.tsx

@@ -1,11 +1,12 @@
 import type { ChildrenList, PartialElement } from '@furystack/shades'
 import { createComponent, Shade } from '@furystack/shades'
-import { ClickAwayService } from '../../services/click-away-service.js'
 import { cssVariableTheme } from '../../services/css-variable-theme.js'
 import type { ListService } from '../../services/list-service.js'
 import { Pagination } from '../pagination.js'
 import { ListItem } from './list-item.js'
 
+let nextListId = 0
+
 export type ListItemState = {
   isFocused: boolean
   isSelected: boolean
@@ -31,6 +32,13 @@ export type ListProps<T> = {
   onSelectionChange?: (selected: T[]) => void
   /** Optional pagination configuration. When provided, items are sliced and a Pagination control is rendered. */
   pagination?: ListPaginationProps
+  /**
+   * Section name for spatial navigation scoping.
+   * Sets `data-nav-section` on the list wrapper so that SpatialNavigationService
+   * constrains arrow-key navigation within the list.
+   * Auto-generated per instance when not provided.
+   */
+  navSection?: string
 } & PartialElement<HTMLDivElement>
 
 export const List: <T>(props: ListProps<T>, children: ChildrenList) => JSX.Element<any> = Shade({
@@ -46,8 +54,9 @@ export const List: <T>(props: ListProps<T>, children: ChildrenList) => JSX.Eleme
       padding: '8px 0',
     },
   },
-  render: ({ props, useDisposable, useHostProps, useRef }) => {
+  render: ({ props, useDisposable, useHostProps, useRef, useState }) => {
     const wrapperRef = useRef<HTMLDivElement>('listWrapper')
+    const [navSectionId] = useState('navSectionId', String(nextListId++))
 
     useDisposable('keydown-handler', () => {
       const listener = (ev: KeyboardEvent) => {
@@ -60,8 +69,8 @@ export const List: <T>(props: ListProps<T>, children: ChildrenList) => JSX.Eleme
           }
         }
       }
-      window.addEventListener('keydown', listener)
-      return { [Symbol.dispose]: () => window.removeEventListener('keydown', listener) }
+      window.addEventListener('keydown', listener, true)
+      return { [Symbol.dispose]: () => window.removeEventListener('keydown', listener, true) }
     })
 
     const { pagination } = props
@@ -79,13 +88,30 @@ export const List: <T>(props: ListProps<T>, children: ChildrenList) => JSX.Eleme
 
     props.listService.items.setValue(visibleItems)
 
-    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.listService.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.onSelectionChange) {
       const { onSelectionChange } = props
@@ -107,6 +133,7 @@ export const List: <T>(props: ListProps<T>, children: ChildrenList) => JSX.Eleme
           role="listbox"
           ariaMultiSelectable="true"
           className="shade-list-wrapper"
+          data-nav-section={props.navSection ?? `list-${navSectionId}`}
           onclick={() => props.listService.hasFocus.setValue(true)}
         >
           {visibleItems.map((item) => (